asmjit::BaseBuilder Class Reference

Inheritance diagram for asmjit::BaseBuilder:

Builder interface.

BaseBuilder interface was designed to be used as a BaseAssembler replacement in case pre-processing or post-processing of the generated code is required. The code can be modified during or after code generation. Pre processing or post processing can be done manually or through a Pass object. BaseBuilder stores the emitted code as a double-linked list of nodes, which allows O(1) insertion and removal during processing.

Check out architecture specific builders for more details and examples:

• x86::Builder - X86/X64 builder implementation.
• a64::Builder - AArch64 builder implementation.

Public Members

Members

Zone _codeZone

Zone _dataZone

Zone _passZone

ZoneAllocator _allocator

ZoneVector<Pass*> _passes {}

ZoneVector<SectionNode*> _sectionNodes {}

ZoneVector<LabelNode*> _labelNodes {}

BaseNode* _cursor = nullptr

NodeList _nodeList

NodeFlags _nodeFlags = NodeFlags::kNone

bool _dirtySectionLinks = false

 Public Attributes inherited from asmjit::BaseEmitter

EmitterType _emitterType = EmitterType::kNone

EmitterFlags _emitterFlags = EmitterFlags::kNone

uint8_t _instructionAlignment = 0u

ValidationFlags _validationFlags = ValidationFlags::kNone

DiagnosticOptions _diagnosticOptions = DiagnosticOptions::kNone

uint64_t _archMask = 0

EncodingOptions _encodingOptions = EncodingOptions::kNone

InstOptions _forcedInstOptions = InstOptions::kReserved

uint32_t _privateData = 0

CodeHolder* _code = nullptr

Logger* _logger = nullptr

ErrorHandler* _errorHandler = nullptr

Environment _environment {}

OperandSignature _gpSignature {}

InstOptions _instOptions = InstOptions::kNone

RegOnly _extraReg {}

const char* _inlineComment = nullptr

Funcs _funcs {}

Public Types

typedef BaseEmitter Base

Member Functions

BaseBuilder(const BaseBuilder& other) = delete

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

Construction & Destruction

BaseBuilder() noexcept

~BaseBuilder() noexcept override

Node Management

NodeList nodeList() const noexcept

BaseNode* firstNode() const noexcept

BaseNode* lastNode() const noexcept

template<typename T, typename... Args>

Error _newNodeT(T** out, Args&&... args)

Error newInstNode(InstNode** out, InstId instId, InstOptions instOptions, uint32_t opCount)

Error newLabelNode(LabelNode** out)

Error newAlignNode(AlignNode** out, AlignMode alignMode, uint32_t alignment)

Error newEmbedDataNode(EmbedDataNode** out, TypeId typeId, const void* data, size_t itemCount, size_t repeatCount = 1)

Error newConstPoolNode(ConstPoolNode** out)

Error newCommentNode(CommentNode** out, const char* data, size_t size)

BaseNode* addNode(BaseNode* node) noexcept

BaseNode* addAfter(BaseNode* node, BaseNode* ref) noexcept

BaseNode* addBefore(BaseNode* node, BaseNode* ref) noexcept

BaseNode* removeNode(BaseNode* node) noexcept

void removeNodes(BaseNode* first, BaseNode* last) noexcept

BaseNode* cursor() const noexcept

BaseNode* setCursor(BaseNode* node) noexcept

void _setCursor(BaseNode* node) noexcept

Section Management

const ZoneVector<SectionNode*>& sectionNodes() const noexcept

bool hasRegisteredSectionNode(uint32_t sectionId) const noexcept

Error sectionNodeOf(SectionNode** out, uint32_t sectionId)

Error section(Section* section) override

bool hasDirtySectionLinks() const noexcept

void updateSectionLinks() noexcept

Label Management

const ZoneVector<LabelNode*>& labelNodes() const noexcept

bool hasRegisteredLabelNode(uint32_t labelId) const noexcept

bool hasRegisteredLabelNode(const Label& label) const noexcept

Error labelNodeOf(LabelNode** out, uint32_t labelId)

Error labelNodeOf(LabelNode** out, const Label& label)

Error registerLabelNode(LabelNode* node)

Label newLabel() override

Label newNamedLabel(const char* name, size_t nameSize = SIZE_MAX, LabelType type = LabelType::kGlobal, uint32_t parentId = Globals::kInvalidId) override

Error bind(const Label& label) override

Passes

const ZoneVector<Pass*>& passes() const noexcept

template<typename T>

T* newPassT() noexcept

template<typename T, typename... Args>

T* newPassT(Args&&... args) noexcept

template<typename T>

Error addPassT()

template<typename T, typename... Args>

Error addPassT(Args&&... args)

Pass* passByName(const char* name) const noexcept

Error addPass(Pass* pass) noexcept

Error deletePass(Pass* pass) noexcept

Error runPasses()

Emit

Error _emit(InstId instId, const Operand_& o0, const Operand_& o1, const Operand_& o2, const Operand_* opExt) override

Align

Error align(AlignMode alignMode, uint32_t alignment) override

Embed

Error embed(const void* data, size_t dataSize) override

Error embedDataArray(TypeId typeId, const void* data, size_t count, size_t repeat = 1) override

Error embedConstPool(const Label& label, const ConstPool& pool) override

Error embedLabel(const Label& label, size_t dataSize = 0) override

Error embedLabelDelta(const Label& label, const Label& base, size_t dataSize = 0) override

Comment

Error comment(const char* data, size_t size = SIZE_MAX) override

Serialization

Error serializeTo(BaseEmitter* dst)

Events

Error onAttach(CodeHolder* code) noexcept override

Error onDetach(CodeHolder* code) noexcept override

 Public Member Functions inherited from asmjit::BaseEmitter

BaseEmitter(const BaseEmitter& other) = delete

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

BaseEmitter(EmitterType emitterType) noexcept

~BaseEmitter() noexcept

template<typename T>

T* as() noexcept

template<typename T>

const T* as() const noexcept

EmitterType emitterType() const noexcept

EmitterFlags emitterFlags() const noexcept

bool isAssembler() const noexcept

bool isBuilder() const noexcept

bool isCompiler() const noexcept

bool hasEmitterFlag(EmitterFlags flag) const noexcept

bool isFinalized() const noexcept

bool isDestroyed() const noexcept

CodeHolder* code() const noexcept

const Environment& environment() const noexcept

bool is32Bit() const noexcept

bool is64Bit() const noexcept

Arch arch() const noexcept

SubArch subArch() const noexcept

uint32_t registerSize() const noexcept

OperandSignature gpSignature() const noexcept

uint32_t instructionAlignment() const noexcept

bool isInitialized() const noexcept

Error finalize()

bool hasLogger() const noexcept

bool hasOwnLogger() const noexcept

Logger* logger() const noexcept

void setLogger(Logger* logger) noexcept

void resetLogger() noexcept

bool hasErrorHandler() const noexcept

bool hasOwnErrorHandler() const noexcept

ErrorHandler* errorHandler() const noexcept

void setErrorHandler(ErrorHandler* errorHandler) noexcept

void resetErrorHandler() noexcept

Error reportError(Error err, const char* message = nullptr)

EncodingOptions encodingOptions() const noexcept

bool hasEncodingOption(EncodingOptions option) const noexcept

void addEncodingOptions(EncodingOptions options) noexcept

void clearEncodingOptions(EncodingOptions options) noexcept

DiagnosticOptions diagnosticOptions() const noexcept

bool hasDiagnosticOption(DiagnosticOptions option) const noexcept

void addDiagnosticOptions(DiagnosticOptions options) noexcept

void clearDiagnosticOptions(DiagnosticOptions options) noexcept

InstOptions forcedInstOptions() const noexcept

InstOptions instOptions() const noexcept

void setInstOptions(InstOptions options) noexcept

void addInstOptions(InstOptions options) noexcept

void resetInstOptions() noexcept

bool hasExtraReg() const noexcept

const RegOnly& extraReg() const noexcept

void setExtraReg(const BaseReg& reg) noexcept

void setExtraReg(const RegOnly& reg) noexcept

void resetExtraReg() noexcept

const char* inlineComment() const noexcept

void setInlineComment(const char* s) noexcept

void resetInlineComment() noexcept

void resetState() noexcept

Label newAnonymousLabel(const char* name, size_t nameSize = SIZE_MAX)

Label newExternalLabel(const char* name, size_t nameSize = SIZE_MAX)

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

bool isLabelValid(uint32_t labelId) const noexcept

bool isLabelValid(const Label& label) const noexcept

Error _emitI(InstId instId)

Error _emitI(InstId instId, const Operand_& o0)

Error _emitI(InstId instId, const Operand_& o0, const Operand_& o1)

Error _emitI(InstId instId, const Operand_& o0, const Operand_& o1, const Operand_& o2)

Error _emitI(InstId instId, const Operand_& o0, const Operand_& o1, const Operand_& o2, const Operand_& o3)

Error _emitI(InstId instId, const Operand_& o0, const Operand_& o1, const Operand_& o2, const Operand_& o3, const Operand_& o4)

Error _emitI(InstId instId, const Operand_& o0, const Operand_& o1, const Operand_& o2, const Operand_& o3, const Operand_& o4, const Operand_& o5)

template<typename... Args>

Error emit(InstId instId, Args&&... operands)

Error emitOpArray(InstId instId, const Operand_* operands, size_t opCount)

Error emitInst(const BaseInst& inst, const Operand_* operands, size_t opCount)

Error emitProlog(const FuncFrame& frame)

Error emitEpilog(const FuncFrame& frame)

Error emitArgsAssignment(const FuncFrame& frame, const FuncArgsAssignment& args)

Error embedInt8(int8_t value, size_t repeatCount = 1)

Error embedUInt8(uint8_t value, size_t repeatCount = 1)

Error embedInt16(int16_t value, size_t repeatCount = 1)

Error embedUInt16(uint16_t value, size_t repeatCount = 1)

Error embedInt32(int32_t value, size_t repeatCount = 1)

Error embedUInt32(uint32_t value, size_t repeatCount = 1)

Error embedInt64(int64_t value, size_t repeatCount = 1)

Error embedUInt64(uint64_t value, size_t repeatCount = 1)

Error embedFloat(float value, size_t repeatCount = 1)

Error embedDouble(double value, size_t repeatCount = 1)

Error commentf(const char* fmt, ...)

Error commentv(const char* fmt, va_list ap)

void onSettingsUpdated() noexcept

Constructor & Destructor Documentation

BaseBuilder::BaseBuilder()noexcept

Creates a new BaseBuilder instance.

BaseBuilder::~BaseBuilder()overridenoexcept

Destroys the BaseBuilder instance.

Member Function Documentation

BaseNode* BaseBuilder::firstNode() constnoexcept

Returns the first node.

BaseNode* BaseBuilder::lastNode() constnoexcept

Returns the last node.

template<typename T, typename... Args>

Error BaseBuilder::_newNodeT(T** out, Args&&... args)

Allocates and instantiates a new node of type T and returns its instance.

If the allocation fails nullptr is returned.

The template argument T must be a type that is extends BaseNode.

Remarks

The pointer returned (if non-null) is owned by the Builder or Compiler. When the Builder/Compiler is destroyed it destroys all nodes it created so no manual memory management is required.

Error BaseBuilder::newInstNode(InstNode** out, InstId instId, InstOptions instOptions, uint32_t opCount)

Creates a new InstNode.

Error BaseBuilder::newLabelNode(LabelNode** out)

Creates a new LabelNode.

Error BaseBuilder::newAlignNode(AlignNode** out, AlignMode alignMode, uint32_t alignment)

Creates a new AlignNode.

Error BaseBuilder::newEmbedDataNode(EmbedDataNode** out, TypeId typeId, const void* data, size_t itemCount, size_t repeatCount = 1)

Creates a new EmbedDataNode.

Error BaseBuilder::newConstPoolNode(ConstPoolNode** out)

Creates a new ConstPoolNode.

Error BaseBuilder::newCommentNode(CommentNode** out, const char* data, size_t size)

Creates a new CommentNode.

BaseNode* BaseBuilder::addNode(BaseNode* node)noexcept

Adds node after the current and sets the current node to the given node.

BaseNode* BaseBuilder::addAfter(BaseNode* node, BaseNode* ref)noexcept

Inserts the given node after ref.

BaseNode* BaseBuilder::addBefore(BaseNode* node, BaseNode* ref)noexcept

Inserts the given node before ref.

BaseNode* BaseBuilder::removeNode(BaseNode* node)noexcept

Removes the given node.

void BaseBuilder::removeNodes(BaseNode* first, BaseNode* last)noexcept

Removes multiple nodes.

BaseNode* BaseBuilder::cursor() constnoexcept

Returns the cursor.

When the Builder/Compiler is created it automatically creates a '.text' SectionNode, which will be the initial one. When instructions are added they are always added after the cursor and the cursor is changed to be that newly added node. Use setCursor() to change where new nodes are inserted.

BaseNode* BaseBuilder::setCursor(BaseNode* node)noexcept

Sets the current node to node and return the previous one.

void BaseBuilder::_setCursor(BaseNode* node)noexcept

Sets the current node without returning the previous node.

Only use this function if you are concerned about performance and want this inlined (for example if you set the cursor in a loop, etc...).

const ZoneVector<SectionNode*>& BaseBuilder::sectionNodes() constnoexcept

Returns a vector of SectionNode objects.

Note

If a section of some id is not associated with the Builder/Compiler it would be null, so always check for nulls if you iterate over the vector.

bool BaseBuilder::hasRegisteredSectionNode(uint32_t sectionId) constnoexcept

Tests whether the SectionNode of the given sectionId was registered.

Error BaseBuilder::sectionNodeOf(SectionNode** out, uint32_t sectionId)

Returns or creates a SectionNode that matches the given sectionId.

Remarks

This function will either get the existing SectionNode or create it in case it wasn't created before. You can check whether a section has a registered SectionNode by using BaseBuilder::hasRegisteredSectionNode().

Error BaseBuilder::section(Section* section)override

Switches the given section.

Once switched, everything is added to the given section.

Reimplemented from asmjit::BaseEmitter.

bool BaseBuilder::hasDirtySectionLinks() constnoexcept

Returns whether the section links of active section nodes are dirty.

You can update these links by calling updateSectionLinks() in such case.

void BaseBuilder::updateSectionLinks()noexcept

Updates links of all active section nodes.

const ZoneVector<LabelNode*>& BaseBuilder::labelNodes() constnoexcept

Returns a vector of LabelNode nodes.

Note

If a label of some id is not associated with the Builder/Compiler it would be null, so always check for nulls if you iterate over the vector.

bool BaseBuilder::hasRegisteredLabelNode(uint32_t labelId) constnoexcept[1/2]

Tests whether the LabelNode of the given labelId was registered.

bool BaseBuilder::hasRegisteredLabelNode(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 BaseBuilder::labelNodeOf(LabelNode** out, uint32_t labelId)[1/2]

Gets or creates a LabelNode that matches the given labelId.

Remarks

This function will either get the existing LabelNode or create it in case it wasn't created before. You can check whether a label has a registered LabelNode by calling BaseBuilder::hasRegisteredLabelNode().

Error BaseBuilder::labelNodeOf(LabelNode** out, const Label& label)[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 BaseBuilder::registerLabelNode(LabelNode* node)

Registers this LabelNode (internal).

This function is used internally to register a newly created LabelNode with this instance of Builder/Compiler. Use labelNodeOf() functions to get back LabelNode from a label or its identifier.

Label BaseBuilder::newLabel()override

Creates a new label.

Reimplemented from asmjit::BaseEmitter.

Label BaseBuilder::newNamedLabel(const char* name, size_t nameSize = SIZE_MAX, LabelType type = LabelType::kGlobal, uint32_t parentId = Globals::kInvalidId)override

Creates a new named label.

Reimplemented from asmjit::BaseEmitter.

Error BaseBuilder::bind(const Label& label)override

Binds the label to the current position of the current section.

Note

Attempt to bind the same label multiple times will return an error.

Reimplemented from asmjit::BaseEmitter.

const ZoneVector<Pass*>& BaseBuilder::passes() constnoexcept

Returns a vector of Pass instances that will be executed by runPasses().

template<typename T>

T* BaseBuilder::newPassT()noexcept[1/2]

Allocates and instantiates a new pass of type T and returns its instance.

If the allocation fails nullptr is returned.

The template argument T must be a type that is extends Pass.

Remarks

The pointer returned (if non-null) is owned by the Builder or Compiler. When the Builder/Compiler is destroyed it destroys all passes it created so no manual memory management is required.

template<typename T, typename... Args>

T* BaseBuilder::newPassT(Args&&... args)noexcept[2/2]

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

Pass* BaseBuilder::passByName(const char* name) constnoexcept

Returns Pass by name.

If the pass having the given name doesn't exist nullptr is returned.

Error BaseBuilder::addPass(Pass* pass)noexcept

Adds pass to the list of passes.

Error BaseBuilder::deletePass(Pass* pass)noexcept

Removes pass from the list of passes and delete it.

Error BaseBuilder::runPasses()

Runs all passes in order.

Error BaseBuilder::align(AlignMode alignMode, uint32_t alignment)override

Aligns the current CodeBuffer position to the alignment specified.

The sequence that is used to fill the gap between the aligned location and the current location depends on the align mode, see AlignMode. The alignment argument specifies alignment in bytes, so for example when it's 32 it means that the code buffer will be aligned to 32 bytes.

Reimplemented from asmjit::BaseEmitter.

Error BaseBuilder::embed(const void* data, size_t dataSize)override

Embeds raw data into the CodeBuffer.

Reimplemented from asmjit::BaseEmitter.

Error BaseBuilder::embedDataArray(TypeId typeId, const void* data, size_t itemCount, size_t repeatCount = 1)override

Embeds a typed data array.

This is the most flexible function for embedding data as it allows to:

• Assign a typeId to the data, so the emitter knows the type of items stored in data. Binary data should use TypeId::kUInt8.
• Repeat the given data repeatCount times, so the data can be used as a fill pattern for example, or as a pattern used by SIMD instructions.

Reimplemented from asmjit::BaseEmitter.

Error BaseBuilder::embedConstPool(const Label& label, const ConstPool& pool)override

Embeds a constant pool at the current offset by performing the following:

1. Aligns by using AlignMode::kData to the minimum pool alignment.
2. Binds the ConstPool label so it's bound to an aligned location.
3. Emits ConstPool content.

Reimplemented from asmjit::BaseEmitter.

Error BaseBuilder::embedLabel(const Label& label, size_t dataSize = 0)override

Embeds an absolute label address as data.

The dataSize is an optional argument that can be used to specify the size of the address data. If it's zero (default) the address size is deduced from the target architecture (either 4 or 8 bytes).

Reimplemented from asmjit::BaseEmitter.

Error BaseBuilder::embedLabelDelta(const Label& label, const Label& base, size_t dataSize = 0)override

Embeds a delta (distance) between the label and base calculating it as label - base.

This function was designed to make it easier to embed lookup tables where each index is a relative distance of two labels.

Reimplemented from asmjit::BaseEmitter.

Error BaseBuilder::comment(const char* data, size_t size = SIZE_MAX)override

Emits a comment stored in data with an optional size parameter.

Reimplemented from asmjit::BaseEmitter.

Error BaseBuilder::serializeTo(BaseEmitter* dst)

Serializes everything the given emitter dst.

Although not explicitly required the emitter will most probably be of Assembler type. The reason is that there is no known use of serializing nodes held by Builder/Compiler into another Builder-like emitter.

Error BaseBuilder::onAttach(CodeHolder* code)overridenoexcept

Called after the emitter was attached to CodeHolder.

Reimplemented from asmjit::BaseEmitter.

Reimplemented in asmjit::BaseCompiler, asmjit::x86::Builder, and asmjit::x86::Compiler.

Error BaseBuilder::onDetach(CodeHolder* code)overridenoexcept

Called after the emitter was detached from CodeHolder.

Reimplemented from asmjit::BaseEmitter.

Reimplemented in asmjit::BaseCompiler, asmjit::x86::Builder, and asmjit::x86::Compiler.

Member Data Documentation

Zone BaseBuilder::_codeZone

Base zone used to allocate nodes and passes.

Zone BaseBuilder::_dataZone

Data zone used to allocate data and names.

Zone BaseBuilder::_passZone

Pass zone, passed to Pass::run().

ZoneAllocator BaseBuilder::_allocator

Allocator that uses _codeZone.

ZoneVector<Pass*>BaseBuilder::_passes {}

Array of Pass objects.

ZoneVector<SectionNode*>BaseBuilder::_sectionNodes {}

Maps section indexes to LabelNode nodes.

ZoneVector<LabelNode*>BaseBuilder::_labelNodes {}

Maps label indexes to LabelNode nodes.

BaseNode* BaseBuilder::_cursor = nullptr

Current node (cursor).

NodeList BaseBuilder::_nodeList

First and last nodes.

NodeFlags BaseBuilder::_nodeFlags = NodeFlags::kNone

Flags assigned to each new node.

bool BaseBuilder::_dirtySectionLinks = false

The sections links are dirty (used internally).