asmjit::CodeHolder Class Reference

Holds assembled code and data (including sections, labels, and relocation information).

CodeHolder connects emitters with their targets. It provides them interface that can be used to query information about the target environment (architecture, etc...) and API to create labels, sections, relocations, and to write data to a CodeBuffer, which is always part of Section. More than one emitter can be attached to a single CodeHolder instance at a time, which is used in practice

CodeHolder provides interface for all emitter types. Assemblers use CodeHolder to write into CodeBuffer, and higher level emitters like Builder and Compiler use CodeHolder to manage labels and sections so higher level code can be serialized to Assembler by BaseEmitter::finalize() and BaseBuilder::serializeTo().

In order to use CodeHolder, it must be first initialized by init(). After the CodeHolder has been successfully initialized it can be used to hold assembled code, sections, labels, relocations, and to attach / detach code emitters. After the end of code generation it can be used to query physical locations of labels and to relocate the assembled code into the right address.

Note

CodeHolder has an ability to attach an ErrorHandler, however, the error handler is not triggered by CodeHolder itself, it's instead propagated to all emitters that attach to it.

Public Members

Members

Environment _environment

CpuFeatures _cpuFeatures

uint64_t _baseAddress

Logger* _logger

ErrorHandler* _errorHandler

Zone _zone

ZoneAllocator _allocator

ZoneVector<BaseEmitter*> _emitters

ZoneVector<Section*> _sections

ZoneVector<Section*> _sectionsByOrder

ZoneVector<LabelEntry*> _labelEntries

ZoneVector<RelocEntry*> _relocations

ZoneHash<LabelEntry> _namedLabels

size_t _unresolvedLinkCount

Section* _addressTableSection

ZoneTree<AddressTableEntry> _addressTableEntries

Member Functions

CodeHolder(const CodeHolder& other) = delete

CodeHolder& operator=(const CodeHolder& other) = delete

Construction & Destruction

CodeHolder(const Support::Temporary* temporary = nullptr) noexcept

CodeHolder(const Support::Temporary& temporary) noexcept

~CodeHolder() noexcept

bool isInitialized() const noexcept

Error init(const Environment& environment, uint64_t baseAddress = Globals::kNoBaseAddress) noexcept

Error init(const Environment& environment, const CpuFeatures& cpuFeatures, uint64_t baseAddress = Globals::kNoBaseAddress) noexcept

void reset(ResetPolicy resetPolicy = ResetPolicy::kSoft) noexcept

Attach & Detach

Error attach(BaseEmitter* emitter) noexcept

Error detach(BaseEmitter* emitter) noexcept

Allocators

ZoneAllocator* allocator() const noexcept

Code & Architecture

const Environment& environment() const noexcept

Arch arch() const noexcept

SubArch subArch() const noexcept

const CpuFeatures& cpuFeatures() const noexcept

bool hasBaseAddress() const noexcept

uint64_t baseAddress() const noexcept

Emitters

const ZoneVector<BaseEmitter*>& emitters() const noexcept

Logging

Logger* logger() const noexcept

void setLogger(Logger* logger) noexcept

void resetLogger() noexcept

Error Handling

bool hasErrorHandler() const noexcept

ErrorHandler* errorHandler() const noexcept

void setErrorHandler(ErrorHandler* errorHandler) noexcept

void resetErrorHandler() noexcept

Code Buffer

Error growBuffer(CodeBuffer* cb, size_t n) noexcept

Error reserveBuffer(CodeBuffer* cb, size_t n) noexcept

Sections

const ZoneVector<Section*>& sections() const noexcept

const ZoneVector<Section*>& sectionsByOrder() const noexcept

uint32_t sectionCount() const noexcept

bool isSectionValid(uint32_t sectionId) const noexcept

Error newSection(Section** sectionOut, const char* name, size_t nameSize = SIZE_MAX, SectionFlags flags = SectionFlags::kNone, uint32_t alignment = 1, int32_t order = 0) noexcept

Section* sectionById(uint32_t sectionId) const noexcept

Section* sectionByName(const char* name, size_t nameSize = SIZE_MAX) const noexcept

Section* textSection() const noexcept

bool hasAddressTable() const noexcept

Section* addressTableSection() const noexcept

Section* ensureAddressTableSection() noexcept

Error addAddressToAddressTable(uint64_t address) noexcept

Labels & Symbols

const ZoneVector<LabelEntry*>& labelEntries() const noexcept

uint32_t labelCount() const noexcept

bool isLabelValid(uint32_t labelId) const noexcept

bool isLabelValid(const Label& label) const noexcept

bool isLabelBound(uint32_t labelId) const noexcept

bool isLabelBound(const Label& label) const noexcept

LabelEntry* labelEntry(uint32_t labelId) const noexcept

LabelEntry* labelEntry(const Label& label) const noexcept

uint64_t labelOffset(uint32_t labelId) const noexcept

uint64_t labelOffset(const Label& label) const noexcept

uint64_t labelOffsetFromBase(uint32_t labelId) const noexcept

uint64_t labelOffsetFromBase(const Label& label) const noexcept

Error newLabelEntry(LabelEntry** entryOut) noexcept

Error newNamedLabelEntry(LabelEntry** entryOut, const char* name, size_t nameSize, LabelType type, uint32_t parentId = Globals::kInvalidId) noexcept

Label labelByName(const char* name, size_t nameSize = SIZE_MAX, uint32_t parentId = Globals::kInvalidId) noexcept

uint32_t labelIdByName(const char* name, size_t nameSize = SIZE_MAX, uint32_t parentId = Globals::kInvalidId) noexcept

bool hasUnresolvedLinks() const noexcept

size_t unresolvedLinkCount() const noexcept

LabelLink* newLabelLink(LabelEntry* le, uint32_t sectionId, size_t offset, intptr_t rel, const OffsetFormat& format) noexcept

Error resolveUnresolvedLinks() noexcept

Error bindLabel(const Label& label, uint32_t sectionId, uint64_t offset) noexcept

Relocations

bool hasRelocEntries() const noexcept

const ZoneVector<RelocEntry*>& relocEntries() const noexcept

RelocEntry* relocEntry(uint32_t id) const noexcept

Error newRelocEntry(RelocEntry** dst, RelocType relocType) noexcept

Utilities

Error flatten() noexcept

size_t codeSize() const noexcept

Error relocateToBase(uint64_t baseAddress) noexcept

Error copySectionData(void* dst, size_t dstSize, uint32_t sectionId, CopySectionFlags copyFlags = CopySectionFlags::kNone) noexcept

Error copyFlattenedData(void* dst, size_t dstSize, CopySectionFlags copyFlags = CopySectionFlags::kNone) noexcept

Constructor & Destructor Documentation

CodeHolder::CodeHolder(const Support::Temporary* temporary = nullptr)explicitnoexcept[1/2]

Creates an uninitialized CodeHolder (you must init() it before it can be used).

An optional temporary argument can be used to initialize the first block of Zone that the CodeHolder uses into a temporary memory provided by the user.

CodeHolder::CodeHolder(const Support::Temporary& temporary)explicitnoexcept[2/2]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CodeHolder::~CodeHolder()noexcept

Destroys the CodeHolder and frees all resources it has allocated.

Member Function Documentation

bool CodeHolder::isInitialized() constnoexcept

Tests whether the CodeHolder has been initialized.

Emitters can be only attached to initialized CodeHolder instances.

Error CodeHolder::init(const Environment& environment, uint64_t baseAddress = Globals::kNoBaseAddress)noexcept[1/2]

Initializes CodeHolder to hold code described by the given environment and baseAddress.

Error CodeHolder::init(const Environment& environment, const CpuFeatures& cpuFeatures, uint64_t baseAddress = Globals::kNoBaseAddress)noexcept[2/2]

Initializes CodeHolder to hold code described by the given environment, cpuFeatures, and baseAddress.

void CodeHolder::reset(ResetPolicy resetPolicy = ResetPolicy::kSoft)noexcept

Detaches all code-generators attached and resets the CodeHolder.

Error CodeHolder::attach(BaseEmitter* emitter)noexcept

Attaches an emitter to this CodeHolder.

Error CodeHolder::detach(BaseEmitter* emitter)noexcept

Detaches an emitter from this CodeHolder.

ZoneAllocator* CodeHolder::allocator() constnoexcept

Returns the allocator that the CodeHolder uses.

Note

This should be only used for AsmJit's purposes. Code holder uses arena allocator to allocate everything, so anything allocated through this allocator will be invalidated by CodeHolder::reset() or by CodeHolder's destructor.

const Environment& CodeHolder::environment() constnoexcept

Returns the target environment information.

Arch CodeHolder::arch() constnoexcept

Returns the target architecture.

SubArch CodeHolder::subArch() constnoexcept

Returns the target sub-architecture.

const CpuFeatures& CodeHolder::cpuFeatures() constnoexcept

Returns the minimum CPU features of the target architecture.

bool CodeHolder::hasBaseAddress() constnoexcept

Tests whether a static base-address is set.

uint64_t CodeHolder::baseAddress() constnoexcept

Returns a static base-address or Globals::kNoBaseAddress, if not set.

const ZoneVector<BaseEmitter*>& CodeHolder::emitters() constnoexcept

Returns a vector of attached emitters.

Logger* CodeHolder::logger() constnoexcept

Returns the attached logger.

void CodeHolder::setLogger(Logger* logger)noexcept

Attaches a logger to CodeHolder and propagates it to all attached emitters.

void CodeHolder::resetLogger()noexcept

Resets the logger to none.

bool CodeHolder::hasErrorHandler() constnoexcept

Tests whether the CodeHolder has an attached error handler, see ErrorHandler.

ErrorHandler* CodeHolder::errorHandler() constnoexcept

Returns the attached error handler.

void CodeHolder::setErrorHandler(ErrorHandler* errorHandler)noexcept

Attach an error handler to this CodeHolder.

void CodeHolder::resetErrorHandler()noexcept

Resets the error handler to none.

Error CodeHolder::growBuffer(CodeBuffer* cb, size_t n)noexcept

Makes sure that at least n bytes can be added to CodeHolder's buffer cb.

Note

The buffer cb must be managed by CodeHolder - otherwise the behavior of the function is undefined.

Error CodeHolder::reserveBuffer(CodeBuffer* cb, size_t n)noexcept

Reserves the size of cb to at least n bytes.

Note

The buffer cb must be managed by CodeHolder - otherwise the behavior of the function is undefined.

const ZoneVector<Section*>& CodeHolder::sections() constnoexcept

Returns an array of Section* records.

const ZoneVector<Section*>& CodeHolder::sectionsByOrder() constnoexcept

Returns an array of Section* records sorted according to section order first, then section id.

uint32_t CodeHolder::sectionCount() constnoexcept

Returns the number of sections.

bool CodeHolder::isSectionValid(uint32_t sectionId) constnoexcept

Tests whether the given sectionId is valid.

Error CodeHolder::newSection(Section** sectionOut, const char* name, size_t nameSize = SIZE_MAX, SectionFlags flags = SectionFlags::kNone, uint32_t alignment = 1, int32_t order = 0)noexcept

Creates a new section and return its pointer in sectionOut.

Returns Error, does not report a possible error to ErrorHandler.

Section* CodeHolder::sectionById(uint32_t sectionId) constnoexcept

Returns a section entry of the given index.

Section* CodeHolder::sectionByName(const char* name, size_t nameSize = SIZE_MAX) constnoexcept

Returns section-id that matches the given name.

If there is no such section Section::kInvalidId is returned.

Section* CodeHolder::textSection() constnoexcept

Returns '.text' section (section that commonly represents code).

Note

Text section is always the first section in CodeHolder::sections() array.

bool CodeHolder::hasAddressTable() constnoexcept

Tests whether '.addrtab' section exists.

Section* CodeHolder::addressTableSection() constnoexcept

Returns '.addrtab' section.

This section is used exclusively by AsmJit to store absolute 64-bit addresses that cannot be encoded in instructions like 'jmp' or 'call'.

Note

This section is created on demand, the returned pointer can be null.

Section* CodeHolder::ensureAddressTableSection()noexcept

Ensures that '.addrtab' section exists (creates it if it doesn't) and returns it.

Can return nullptr on out of memory condition.

Error CodeHolder::addAddressToAddressTable(uint64_t address)noexcept

Used to add an address to an address table.

This implicitly calls ensureAddressTableSection() and then creates AddressTableEntry that is inserted to _addressTableEntries. If the address already exists this operation does nothing as the same addresses use the same slot.

This function should be considered internal as it's used by assemblers to insert an absolute address into the address table. Inserting address into address table without creating a particula relocation entry makes no sense.

const ZoneVector<LabelEntry*>& CodeHolder::labelEntries() constnoexcept

Returns array of LabelEntry* records.

uint32_t CodeHolder::labelCount() constnoexcept

Returns number of labels created.

bool CodeHolder::isLabelValid(uint32_t labelId) constnoexcept[1/2]

Tests whether the label having id is valid (i.e. created by newLabelEntry()).

bool CodeHolder::isLabelValid(const Label& label) constnoexcept[2/2]

Tests whether the label is valid (i.e. created by newLabelEntry()).

bool CodeHolder::isLabelBound(uint32_t labelId) constnoexcept[1/2]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool CodeHolder::isLabelBound(const Label& label) constnoexcept[2/2]

Tests whether the label is already bound.

Returns false if the label is not valid.

LabelEntry* CodeHolder::labelEntry(uint32_t labelId) constnoexcept[1/2]

Returns LabelEntry of the given label id.

LabelEntry* CodeHolder::labelEntry(const Label& label) constnoexcept[2/2]

Returns LabelEntry of the given label.

uint64_t CodeHolder::labelOffset(uint32_t labelId) constnoexcept[1/2]

Returns offset of a Label by its labelId.

The offset returned is relative to the start of the section. Zero offset is returned for unbound labels, which is their initial offset value.

uint64_t CodeHolder::labelOffset(const Label& label) constnoexcept[2/2]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

uint64_t CodeHolder::labelOffsetFromBase(uint32_t labelId) constnoexcept[1/2]

Returns offset of a label by it's labelId relative to the base offset.

Remarks

The offset of the section where the label is bound must be valid in order to use this function, otherwise the value returned will not be reliable.

uint64_t CodeHolder::labelOffsetFromBase(const Label& label) constnoexcept[2/2]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Error CodeHolder::newLabelEntry(LabelEntry** entryOut)noexcept

Creates a new anonymous label and return its id in idOut.

Returns Error, does not report error to ErrorHandler.

Error CodeHolder::newNamedLabelEntry(LabelEntry** entryOut, const char* name, size_t nameSize, LabelType type, uint32_t parentId = Globals::kInvalidId)noexcept

Creates a new named LabelEntry of the given label type.

Parameters

entryOut	Where to store the created LabelEntry.
name	The name of the label.
nameSize	The length of name argument, or SIZE_MAX if name is a null terminated string, which means that the CodeHolder will use strlen() to determine the length.
type	The type of the label to create, see LabelType.
parentId	Parent id of a local label, otherwise it must be Globals::kInvalidId.

Return values

Always

returns Error, does not report a possible error to the attached ErrorHandler.

AsmJit has a support for local labels (LabelType::kLocal) which require a parent label id (parentId). The names of local labels can conflict with names of other local labels that have a different parent. In addition, AsmJit supports named anonymous labels, which are useful only for debugging purposes as the anonymous name will have a name, which will be formatted, but the label itself cannot be queried by such name.

Label CodeHolder::labelByName(const char* name, size_t nameSize = SIZE_MAX, uint32_t parentId = Globals::kInvalidId)noexcept

Returns a label by name.

If the named label doesn't a default constructed Label is returned, which has its id set to Globals::kInvalidId.

uint32_t CodeHolder::labelIdByName(const char* name, size_t nameSize = SIZE_MAX, uint32_t parentId = Globals::kInvalidId)noexcept

Returns a label id by name.

If the named label doesn't exist Globals::kInvalidId is returned.

bool CodeHolder::hasUnresolvedLinks() constnoexcept

Tests whether there are any unresolved label links.

size_t CodeHolder::unresolvedLinkCount() constnoexcept

Returns the number of label links, which are unresolved.

LabelLink* CodeHolder::newLabelLink(LabelEntry* le, uint32_t sectionId, size_t offset, intptr_t rel, const OffsetFormat& format)noexcept

Creates a new label-link used to store information about yet unbound labels.

Returns null if the allocation failed.

Error CodeHolder::resolveUnresolvedLinks()noexcept

Resolves cross-section links (LabelLink) associated with each label that was used as a destination in code of a different section.

It's only useful to people that use multiple sections as it will do nothing if the code only contains a single section in which cross-section links are not possible.

Error CodeHolder::bindLabel(const Label& label, uint32_t sectionId, uint64_t offset)noexcept

Binds a label to a given sectionId and offset (relative to start of the section).

This function is generally used by BaseAssembler::bind() to do the heavy lifting.

bool CodeHolder::hasRelocEntries() constnoexcept

Tests whether the code contains relocation entries.

const ZoneVector<RelocEntry*>& CodeHolder::relocEntries() constnoexcept

Returns array of RelocEntry* records.

RelocEntry* CodeHolder::relocEntry(uint32_t id) constnoexcept

Returns a RelocEntry of the given id.

Error CodeHolder::newRelocEntry(RelocEntry** dst, RelocType relocType)noexcept

Creates a new relocation entry of type relocType.

Additional fields can be set after the relocation entry was created.

Error CodeHolder::flatten()noexcept

Flattens all sections by recalculating their offsets, starting at 0.

Note

This should never be called more than once.

size_t CodeHolder::codeSize() constnoexcept

Returns computed the size of code & data of all sections.

Note

All sections will be iterated over and the code size returned would represent the minimum code size of all combined sections after applying minimum alignment. Code size may decrease after calling flatten() and relocateToBase().

Error CodeHolder::relocateToBase(uint64_t baseAddress)noexcept

Relocates the code to the given baseAddress.

Parameters

baseAddress

Absolute base address where the code will be relocated to. Please note that nothing is copied to such base address, it's just an absolute value used by the relocator to resolve all stored relocations.

Note

This should never be called more than once.

Error CodeHolder::copySectionData(void* dst, size_t dstSize, uint32_t sectionId, CopySectionFlags copyFlags = CopySectionFlags::kNone)noexcept

Copies a single section into dst.

Error CodeHolder::copyFlattenedData(void* dst, size_t dstSize, CopySectionFlags copyFlags = CopySectionFlags::kNone)noexcept

Copies all sections into dst.

This should only be used if the data was flattened and there are no gaps between the sections. The dstSize is always checked and the copy will never write anything outside the provided buffer.

Member Data Documentation

Environment CodeHolder::_environment

Environment information.

CpuFeatures CodeHolder::_cpuFeatures

CPU features of the target architecture.

uint64_t CodeHolder::_baseAddress

Base address or Globals::kNoBaseAddress.

Logger* CodeHolder::_logger

Attached Logger, used by all consumers.

ErrorHandler* CodeHolder::_errorHandler

Attached ErrorHandler.

Zone CodeHolder::_zone

Code zone (used to allocate core structures).

ZoneAllocator CodeHolder::_allocator

Zone allocator, used to manage internal containers.

ZoneVector<BaseEmitter*>CodeHolder::_emitters

Attached emitters.

ZoneVector<Section*>CodeHolder::_sections

Section entries.

ZoneVector<Section*>CodeHolder::_sectionsByOrder

Section entries sorted by section order and then section id.

ZoneVector<LabelEntry*>CodeHolder::_labelEntries

Label entries.

ZoneVector<RelocEntry*>CodeHolder::_relocations

Relocation entries.

ZoneHash<LabelEntry>CodeHolder::_namedLabels

Label name -> LabelEntry (only named labels).

size_t CodeHolder::_unresolvedLinkCount

Count of label links, which are not resolved.

Section* CodeHolder::_addressTableSection

Pointer to an address table section (or null if this section doesn't exist).

ZoneTree<AddressTableEntry>CodeHolder::_addressTableEntries

Address table entries.