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.

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


Member Functions

Construction & Destruction
Attach & Detach
Code & Architecture
Error Handling
Code Buffer
Labels & Symbols

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.


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.

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.

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.

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).

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'.

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 particular 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.

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.

entryOutWhere to store the created LabelEntry.
nameThe name of the label.
nameSizeThe 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.
typeThe type of the label to create, see LabelType.
parentIdParent id of a local label, otherwise it must be Globals::kInvalidId.
Return values
Alwaysreturns 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.

This should never be called more than once.

size_t CodeHolder::codeSize() constnoexcept◆ 

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

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.

baseAddressAbsolute 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 relocation code to resolve all stored relocations.
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.


Attached emitters.


Section entries.


Section entries sorted by section order and then section id.


Label entries.


Relocation entries.


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).


Address table entries.