irutil

README

irutil

LLVM IR utility functions.

The irutil repository provides utility functions for LLVM IR and is intended to supplement llir/llvm.

Experimental

Note: the API of irutil is to be considered experimental. We intend to iterate on the design of the API, so make sure to pin versions to ensure stability.

License

The llir/irutil project is dual-licensed to the public domain and under a zero-clause BSD license. You may choose either license to govern your use of llir/irutil.

Documentation

Overview

Package irutil implements LLVM IR utility functions.

Index

• func NewCString(s string) *constant.CharArray
• func NewPascalString(s string) *constant.CharArray
• func NewZero(typ types.Type) value.Value
• func ResetNames(f *ir.Func)
• func ResetTypes(f *ir.Func)
• func Simplify(c constant.Constant) constant.Constant
• func Walk(root interface{}, visit func(n interface{}) bool)
• type AggregateAlignment
  • func NewAggregateAlignment(abiAl, prefAl uint64) *AggregateAlignment
• type Comment
  • func NewComment(text string) *Comment
  • func (c *Comment) LLString() string
• type DataLayout
  • func NewDataLayout(os string, arch string) *DataLayout
  • func NewDataLayoutFromString(layoutString, os, arch string) (*DataLayout, error)
  • func (dl *DataLayout) LLString() string
• type DefaultLayout
  • func (l DefaultLayout) SizeOf(typ types.Type) int
• type FloatingPointSizeAlignment
  • func NewFloatingPointSizeAlignment(size, abiAl, prefAl uint64) *FloatingPointSizeAlignment
• type FunctionPointerAlignment
  • func NewFunctionPointerAlignment(isInd bool, abiAl uint64) *FunctionPointerAlignment
• type Ident
• type IntegerSizeAlignment
  • func NewIntegerSizeAlignment(size, abiAl, prefAl uint64) *IntegerSizeAlignment
• type Layout
• type ManglingStyle
• type PointerSizeAlignment
  • func NewPointerSizeAlignment(addSp, size, abiAl, prefAl, addCalInd uint64) *PointerSizeAlignment
• type VectorSizeAlignment
  • func NewVectorSizeAlignment(size, abiAl, prefAl uint64) *VectorSizeAlignment

Functions

func NewCString

func NewCString(s string) *constant.CharArray

NewCString returns a new NULL-terminated character array constant based on the given UTF-8 string contents.

func NewPascalString

func NewPascalString(s string) *constant.CharArray

NewPascalString returns a length-prefixed string, also known as a Pascal string. The length prefix is stored as a 32-bit integer with big-endian encoding.

func NewZero

func NewZero(typ types.Type) value.Value

NewZero returns a new zero value of the given type.

func ResetNames

func ResetNames(f *ir.Func)

ResetNames resets the IDs of unnamed local variables in the given function.

func ResetTypes

func ResetTypes(f *ir.Func)

ResetTypes resets the (cached) types of instructions in the given function.

func Simplify

func Simplify(c constant.Constant) constant.Constant

Simplify returns an equivalent (and potentially simplified) constant to the constant expression.

func Walk

func Walk(root interface{}, visit func(n interface{}) bool)

Walk walks the LLVM IR AST in depth-first order; invoking visit recursively for each non-nil child of root. If visit returns false, the walk is terminated.

Types

type AggregateAlignment

type AggregateAlignment struct {
	ABIAlignment       uint64
	PreferredAlignment uint64 // optional and defaults to abi
}

func NewAggregateAlignment

func NewAggregateAlignment(abiAl, prefAl uint64) *AggregateAlignment

type Comment

type Comment struct {
	// Comment text; may contain multiple lines.
	Text string

	// embed ir.Instruction to satisfy the ir.Instruction interface.
	ir.Instruction
}

Comment is an LLVM IR comment represented as a pseudo-instruction. Comment implements ir.Instruction.

func NewComment

func NewComment(text string) *Comment

NewComment returns a new LLVM IR comment represented as a pseudo-instruction. Text may contain multiple lines.

func (*Comment) LLString

func (c *Comment) LLString() string

LLString returns the LLVM syntax representation of the value.

type DataLayout

type DataLayout struct {
	IsBigEndian                bool                                   // default - True
	NaturalStackAlignment      uint64                                 // bits in multiple of 8, default: 0
	ProgramMemoryAddressSpace  uint64                                 // default - 0
	GlobalVarAddressSpace      uint64                                 // default - 0
	AllocaAddressSpace         uint64                                 // default - 0
	PointerSizeAlignment       map[uint64]*PointerSizeAlignment       // Key is addressspace
	IntegerSizeAlignment       map[uint64]*IntegerSizeAlignment       // Key is size
	VectorSizeAlignment        map[uint64]*VectorSizeAlignment        // Key is size
	FloatingPointSizeAlignment map[uint64]*FloatingPointSizeAlignment // Key is size
	AggregateAlignment         *AggregateAlignment                    // default - 0:64
	FunctionPointerAlignment   *FunctionPointerAlignment              // default - Not specified in LLVM Ref doc
	Mangling                   ManglingStyle                          // depends on os - "e" for linux, "o" for mac
	NativeIntBitWidths         []uint64                               // default - depends on arch "8:16:32:64" for x86-64
	NonIntegralPointerTypes    []string                               // Unsure of the datatype, so leaving it as string to accommodate anything.
}

DataLayout is a structural representation of the datalayout string from https://llvm.org/docs/LangRef.html#data-layout

func NewDataLayout

func NewDataLayout(os string, arch string) *DataLayout

NewDataLayout returns an instance of DataLayout with default values taken from https://llvm.org/docs/LangRef.html#data-layout

func NewDataLayoutFromString

func NewDataLayoutFromString(layoutString, os, arch string) (*DataLayout, error)

NewDataLayoutFromString parses a datalayout string and constructs a DataLayout object. Default values whereever applicable will be added if options are ommitted.

This API expects the string to be valid as per LLVM spec, so there aren't many validations.

func (*DataLayout) LLString

func (dl *DataLayout) LLString() string

type DefaultLayout

type DefaultLayout struct{}

DefaultLayout provides a default implementation of data layout, which specifies the size of types and how data is to be laid out in memory.

Users may embed this struct and implement the Sizeof method to provide custom handling of specific types and their size in number of bits.

func (DefaultLayout) SizeOf

func (l DefaultLayout) SizeOf(typ types.Type) int

SizeOf returns the size of the given type in number of bits.

type FloatingPointSizeAlignment

type FloatingPointSizeAlignment struct {
	Size               uint64
	ABIAlignment       uint64
	PreferredAlignment uint64 // optional and defaults to abi
}

func NewFloatingPointSizeAlignment

func NewFloatingPointSizeAlignment(size, abiAl, prefAl uint64) *FloatingPointSizeAlignment

type FunctionPointerAlignment

type FunctionPointerAlignment struct {
	IsIndependant bool
	ABIAlignment  uint64
}

func NewFunctionPointerAlignment

func NewFunctionPointerAlignment(isInd bool, abiAl uint64) *FunctionPointerAlignment

type Ident

type Ident interface {
	value.Named
	// ID returns the ID of the identifier.
	ID() int64
	// SetID sets the ID of the identifier.
	SetID(id int64)
	// IsUnnamed reports whether the identifier is unnamed.
	IsUnnamed() bool
}

Ident is the global or local identifier of a named value.

type IntegerSizeAlignment

type IntegerSizeAlignment struct {
	Size               uint64
	ABIAlignment       uint64
	PreferredAlignment uint64 // optional and defaults to abi
}

func NewIntegerSizeAlignment

func NewIntegerSizeAlignment(size, abiAl, prefAl uint64) *IntegerSizeAlignment

type Layout

type Layout interface {
	// SizeOf returns the size of the given type in number of bits.
	SizeOf(typ types.Type) int
}

Layout specifies how data is to be laid out in memory.

type ManglingStyle

type ManglingStyle string

const (
	ELF        ManglingStyle = "e"
	Mips       ManglingStyle = "m"
	MachO      ManglingStyle = "o"
	WinX86COFF ManglingStyle = "x"
	WinCOFF    ManglingStyle = "w"
	XCOFF      ManglingStyle = "a"
)

type PointerSizeAlignment

type PointerSizeAlignment struct {
	AddressSpace            uint64
	Size                    uint64
	ABIAlignment            uint64
	PreferredAlignment      uint64 // optional and defaults to abi
	AddressCalculationIndex uint64 // default 0
}

func NewPointerSizeAlignment

func NewPointerSizeAlignment(addSp, size, abiAl, prefAl, addCalInd uint64) *PointerSizeAlignment

type VectorSizeAlignment

type VectorSizeAlignment struct {
	Size               uint64
	ABIAlignment       uint64
	PreferredAlignment uint64 // optional and defaults to abi
}

func NewVectorSizeAlignment

func NewVectorSizeAlignment(size, abiAl, prefAl uint64) *VectorSizeAlignment