A datatype for describing the memory layout of binaries.

See the module-level documentation for an overview.

Region indices (RegionIndex) may not correspond precisely with segments or section indices (SectionIndex, SegmentIndex) within the binary, and so we also maintain mappings so that one can map both sections and segments in the binary to the address it is loaded at (memSectionIndexMap, memSegmentIndexMap).

Address width of the memory

Return the number of bytes in an address.

Return the set of memory segments in memory.

This walks through all the memory regions and looks at each address size block of memory that is aligned at a multiple of the address size.

It returns a list of all offset and value pairs that can be interpreted as a valid offset within a memory segment.

A memory with no segments.

Insert segment into memory or fail if this overlaps with another segment in memory.

Describes why we could not insert segment into memory.

Print description of insertion error.

This denotes the base region for loads.

Set the region index used or the load addresses.

Add a new section index to address entry.

Map from registered section indices to the segment offset it is loaded at.

Map from registered segment indices to associated segment.

Record binding from the segment index to the segment.

Information about a contiguous sequence of bytes in memory.

See the module-level documentation for an overview.

Our memory model supports relocatable code, and so segments may have either fixed (absolute) or floating addresses. Floating addresses are represented as an offset from an abstract base address (segmentBase). When segmentBase is 0, segmentOffset is the absolute address of the segment. Binaries may have floating segments that are fixed relative to each other, and this can be modeled by creating different segments with the same non-zero segmentBase identifier.

This creates a memory segment from a buffer after applying relocations and options for

Base for this segment

N.B. 0 indicates a fixed base address of zero.

An identifier used to support relocatable (i.e., position-independent) code.

See the module-level documentation for an overview.

Non-zero region indices represent addresses that would be chosen at runtime by the loader (e.g., the virtual address of an ELF segment containing position-independent code).

The region index 0 indicates an absolute address:

• A MemAddr with an addrBase of 0 is an absolute address.
• A MemSegment with a segmentBase of 0 has an absolute address in its segmentOffset.

Offset of segment relative to segmentBase

Permission flags

Return the size of the segment data.

Pretty print a memory segment.

A memory chunk describes a contiguous sequence of bytes within a segment.

The parameter denotes the width of a memory address.

Note that the term "region" in this type is not related to the notion of "region" described in the module-level documentation (i.e., the Region in RegionIndex).

Information about a relocation. This essentially is a region of memory in a binary whose contents are unknown when the binary is generated.

For object files, relocations are created for symbol names, as the address they are stored at is assigned by the linker. The relocation generated by the compiler provides the linker with the information it needs to perform relocations.

For dynamic executables and shared libraries, relocation values are generated to allow the loader to load the file at a specific address. These may be assigned during loading, or in the case of functions, when first being invoked.

This structure contains the information needed to compute the value stored in memory, and whether there are constraints on that value.

The value to be stored in a relocation r, is the integer computed by base + off - rel where

• base is the address of the symbol identified by relocationSym r;
• off is the offset relocationOffset r; and
• rel is the address the relocation is stored at if relocationIsRel r is true, and 0 otherwise.

The integer value stored is encoded in a bitvector with relocationSize r bytes. This is interpreted as a signed number using two's complement encoding when relocationIsSigned r is true, and an unsigned number otherwise. The byte order is determined by relocationEndiness r.

Because the integer value are stored in fixed width bitvectors that cannot represent all legal integer values, the code doing the relocation is not allowed to place symbols at arbitrary addresses. The integer value computed must fit within the given number of bytes, and so relocations effectively are implicit constraints on where code may be stored in memory.

forcedTakeMemChunks ranges cnt attempts to read cnt bytes from ranges.

It is a total function, and will return ranges if it contains less than cnt bytes. It may also return more than cnt bytes as if a relocation region spans across the break, it will return the region.

Given a contiguous sequence of memory chunks and a number of bytes c, this partitions the data in two data regions. The first contains the first c bytes in the data; the second contains the rest of the data.

This will return an error if the size of the data is too small or the partition would split a relocation entry.

Describes why we could not split the memory chunks.

Typeclass for widths supported by memory addresses.

This only will work for 32 and 64bit values due to requirement to implement addrWidthRepr.

This represents a bitvector value with w bits.

Operations on it require the MemWidth constraint to be satisfied, so in practice this only works for 32 and 64-bit values.

Equal to 0

Convert word64 x into mem word x mod 2^w-1.

Return the value represented by the MemWord as an unsigned integer.

Treat the word as a signed integer.

Read an address with the given endianess.

This returns nothing if the bytestring is too short.

A signed integer with the given width.

Convert Int64 x into mem word x mod 2^w-1.

An address in memory, represented by a base (RegionIndex) and an offset.

See the module-level documentation for an overview.

This representation does not require that the address is mapped to actual memory (see MemSegmentOff for an address representation that ensures the reference points to allocated memory).

Treat a machine word as an absolute address (with a addrBase of 0).

Construct an address from an offset from a memory segment.

Return an absolute address if the region of the MemAddr is 0.

Returns the number of bytes between two addresses if they point to the same region and Nothing if they are different segments.

Increment an address by a fixed amount.

Return True if least-significant bit in addr is set.

Clear the least significant bit of an address.

Return a segment offset from the address if defined.

A pair containing a segment and offset.

Functions that return a segment-offset pair enforce that the offset is strictly less than the size of the memory segment in bytes.

The segment this is an offset of

The offset within the segment.

Return the address of a segment offset.

Return the absolute address associated with the segment offset pair (if any)

Return the number of bytes in the segment after this address.

Return the memory contents from a given offset, that is, the MemChunk at the given offset, then the following MemChunks until the end of the segment. Returns a MemoryError if the requested offset falls within a relocation, which we cannot partition.

Return the segment offset associated with the given region offset if any.

Return the segment associated with the given address if well-defined.

Make a segment offset pair after ensuring the offset is valid

Increment a segment offset by a given amount.

Returns Nothing if the result would be out of range.

Return the difference between two segment offsets pairs or Nothing if undefined.

Clear the least-significant bit of an segment offset.

Type of errors that may occur when reading memory.

Return contents starting from location or throw a memory error if there is an unaligned relocation.

Attempt to read a bytestring of the given length

Read an address from the value in the segment or report a memory error.

Read the given address as a reference to a memory segment offset, or report a memory read error.

Read a single byte.

Read a big endian word16

Read a little endian word16

Read a big endian word32

Read a little endian word32

Read a big endian word64

Read a little endian word64

Attempt to read a null terminated bytesting.

An address width

Number of bytes in addr width repr.

The nat representation of this address.

Number of bytes in an address

Indicates whether bytes are stored in big or little endian representation.

In a big endian representation, the most significant byte is stored first; In a little endian representation, the most significant byte is stored last.

Convert a byte string to an integer using the provided endianness.

Convert a bytestring to an unsigned with the given endianness.

Naive string matching algorithm identifies matches to given pattern within the list of memory segments and their corresponding offset within memory. Relocations are treated as wildcards.

Return list of segment content memory segment ranges with its content's address offset relative to segment offsets

Information about a relocation sufficient to know how many bytes are affected, and how to replaces the existing bytes.

Function for resolving the new contents of a relocation entry given an optional index for the current segment and the existing contents.

The segment index is used for dynamic relocations and set to Nothing for static relocations.

Given a segment data and a number of bytes c, this partitions the data in two data regions. The first contains the first c bytes in the data; the second contains the rest of the data.

This will return an exception if the size of the data is too small or the partition would split a relocation entry.

Given a contiguous list of segment ranges and a number of bytes to drop, this returns the remaining segment ranges or throws an error.

Convert SplitError to equivalent MemoryError.

Note. External code does not use this, so unless we get feedback otherwise, it will be dropped in a future Macaw release.

Return segments with executable permissions.

Return segments with read-only permissions.

Treat the word as an integer.

Treat the word as a signed integer.

Return the segment offset associated with the given region offset if any.

Convert the segment offset to an address.

Return the absolute address associated with the segment offset pair (if any)

Return segment this is offset of.

Return offset of segment

Return the number of bytes in the segment after this address.

Construct an address relative to an existing memory segment.