Index ⭢ Logging

Logging [¶]

Logging and formatting.

Overview

The initial phase of a project that generates machine code is not always smooth. Failure cases are common not just at the beginning phase, but also during the development or refactoring. AsmJit provides logging functionality to address this issue. AsmJit does already a good job with function overloading to prevent from emitting unencodable instructions, but it can't prevent from emitting machine code that is correct at instruction level, but doesn't work when it's executed asa whole. Logging has always been an important part of AsmJit's infrastructure and looking at logs can sometimes reveal code generation issues quickly.

AsmJit provides API for logging and formatting:

Logger - A logger that you can pass to CodeHolder and all emitters that inherit from BaseEmitter.
FormatOptions - Formatting options that can change how instructions and operands are formatted.
Formatter - A namespace that provides functions that can format input data like Operand, Reg, Label, and BaseNode into String.

AsmJit's Logger serves the following purposes:

Provides a basic foundation for logging.
Abstract class leaving the implementation on users. The following built-in implementations are provided for simplicity:
- FileLogger implements logging into a standard FILE stream.
- StringLogger serializes all logs into a String instance.

AsmJit's FormatOptions provides the following to customize the formatting of instructions and operands through:

FormatFlags
FormatIndentationGroup

Logging [¶]

A Logger is typically attached to a CodeHolder, which propagates it to all attached emitters automatically. The example below illustrates how to use FileLogger that outputs to standard output:

#include <asmjit/core.h>
#include <stdio.h>
 
using namespace asmjit;
 
int main() {
  JitRuntime rt;               // Runtime specialized for JIT code execution.
  FileLogger logger(stdout);   // Logger should always survive CodeHolder.
 
  CodeHolder code;             // Holds code and relocation information.
  code.init(rt.environment(),  // Initialize code to match the JIT environment.
            rt.cpu_features());
  code.set_logger(&logger);    // Attach the `logger` to `code` holder.
 
  // ... code as usual, everything emitted will be logged to `stdout` ...
  return 0;
}

If output to FILE stream is not desired it's possible to use StringLogger, which concatenates everything into a multi-line string:

#include <asmjit/core.h>
#include <stdio.h>
#include <utility>
 
using namespace asmjit;
 
int main() {
  JitRuntime rt;               // Runtime specialized for JIT code execution.
  StringLogger logger;         // Logger should always survive CodeHolder.
 
  CodeHolder code;             // Holds code and relocation information.
  code.init(rt.environment(),  // Initialize code to match the JIT environment.
            rt.cpu_features());
  code.set_logger(&logger);    // Attach the `logger` to `code` holder.
 
  // ... code as usual, logging will be concatenated to logger string  ...
 
  // You can either use the string from StringLogger directly or you can
  // move it. Logger::data() returns its content as null terminated char[].
  printf("Logger content: %s\n", logger.data());
 
  // It can be moved into your own string like this:
  String content = std::move(logger.content());
  printf("The same content: %s\n", content.data());
 
  return 0;
}

Formatting [¶]

AsmJit uses Formatter to format inputs that are then passed to Logger. Formatting is public and can be used by AsmJit users as well. The most important thing to know regarding formatting is that Formatter always appends to the output string, so it can be used to build complex strings without having to concatenate intermediate strings.

The first example illustrates how to format operands:

    #include <asmjit/x86.h>
    #include <stdio.h>
   
    using namespace asmjit;
   
    void logOperand(Arch arch, const Operand_& op) {
      // The emitter is optional (named labels and virtual registers need it).
      BaseEmitter* emitter = nullptr;
   
      // No flags by default.
      FormatFlags format_flags = FormatFlags::kNone;
   
      StringTmp<128> sb;
      Formatter::format_operand(sb, format_flags, emitter, arch, op);
      printf("%s\n", sb.data());
    }
   
    void formattingExample() {
      using namespace x86;
   
      // Architecture is not part of operand, it must be passed explicitly.
      // Format flags. We pass it explicitly also to 'logOperand' to make
      // compatible with what AsmJit normally does.
      Arch arch = Arch::kX64;
   
      logOperand(arch, rax);                    // Prints 'rax'.
      logOperand(arch, ptr(rax, rbx, 2));       // Prints '[rax + rbx * 4]`.
      logOperand(arch, imm(42));                // Prints '42'.
    }

Next example illustrates how to format whole instructions:

#include <asmjit/x86.h>
#include <stdio.h>
#include <utility>
 
using namespace asmjit;
 
template<typename... Args>
void logInstruction(Arch arch, const BaseInst& inst, Args&&... args) {
  // The emitter is optional (named labels and virtual registers need it).
  BaseEmitter* emitter = nullptr;
 
  // No flags by default.
  FormatFlags format_flags = FormatFlags::kNone;
 
  // The formatter expects operands in an array.
  Operand_ operands[] { std::forward<Args>(args)... };
 
  StringTmp<128> sb;
  Formatter::format_instruction(
    sb, format_flags, emitter, arch, inst, operands, sizeof...(args));
  printf("%s\n", sb.data());
}
 
void formattingExample() {
  using namespace x86;
 
  // Architecture is not part of operand, it must be passed explicitly.
  // Format flags. We pass it explicitly also to 'logOperand' to make
  // compatible with what AsmJit normally does.
  Arch arch = Arch::kX64;
 
  // Prints 'mov rax, rcx'.
  logInstruction(arch, BaseInst(Inst::kIdMov), rax, rcx);
 
  // Prints 'vaddpd zmm0, zmm1, [rax] {1to8}'.
  logInstruction(arch,
                 BaseInst(Inst::kIdVaddpd),
                 zmm0, zmm1, ptr(rax)._1to8());
 
  // BaseInst abstracts instruction id, instruction options, and extra_reg.
  // Prints 'lock add [rax], rcx'.
  logInstruction(arch,
                 BaseInst(Inst::kIdAdd, InstOptions::kX86_Lock),
                 ptr(rax), rcx);
 
  // Similarly an extra register (like AVX-512 selector) can be used.
  // Prints 'vaddpd zmm0 {k2} {z}, zmm1, [rax]'.
  logInstruction(arch,
                 BaseInst(Inst::kIdAdd, InstOptions::kX86_ZMask, k2),
                 zmm0, zmm1, ptr(rax));
}

And finally, the example below illustrates how to use a built-in function to format the content of BaseBuilder, which consists of nodes:

#include <asmjit/core.h>
#include <stdio.h>
 
using namespace asmjit;
 
void formattingExample(BaseBuilder* builder) {
  FormatOptions format_options {};
 
  // This also shows how temporary strings can be used.
  StringTmp<512> sb;
 
  // FormatNodeList requires the String for output, formatting flags, which
  // were zero (no extra flags), and the builder instance, which we have
  // provided. An overloaded version also exists, which accepts begin and
  // and end nodes, which can be used to only format a range of nodes.
  Formatter::format_node_list(sb, format_options, builder);
 
  // You can do whatever else with the string, it's always null terminated,
  // so it can be passed to C functions like printf().
  printf("%s\n", sb.data());
}

Namespaces

namespace Formatter

Classes

class FormatOptions

class Logger

class FileLogger

class StringLogger

Enumerations

enum class FormatFlags : uint32_t

enum class FormatIndentationGroup : uint32_t

enum class FormatPaddingGroup : uint32_t

FormatFlags : uint32_tenum class[¶]

Format flags used by Logger and FormatOptions.

Constant	Description
kNone	No formatting flags.
kMachineCode	Show also a binary representation of each logged instruction (Assembler).
kShowAliases	Show aliases of some instructions that have them. This option is now mostly for x86/x64 to show aliases of instructions such as `cmov<cc>`, `j<cc>`, `set<cc>`, etc...
kExplainImms	Show a text explanation of some immediate values.
kHexImms	Use hexadecimal notation of immediate values.
kHexOffsets	Use hexadecimal notation of addresses and offsets in addresses.
kRegCasts	Show casts between virtual register types (Compiler).
kPositions	Show positions associated with nodes (Compiler).
kRegType	Always format a register type (Compiler).

FormatIndentationGroup : uint32_tenum class[¶]

Format indentation group, used by FormatOptions.

Constant	Description
kCode	Indentation used for instructions and directives.
kLabel	Indentation used for labels and function nodes.
kComment	Indentation used for comments (not inline comments).
kMaxValue	Maximum value of `FormatIndentationGroup`.

FormatPaddingGroup : uint32_tenum class[¶]

Format padding group, used by FormatOptions.

Constant	Description
kRegularLine	Describes padding of a regular line, which can represent instruction, data, or assembler directives.
kMachineCode	Describes padding of machine code dump that is visible next to the instruction, if enabled.
kMaxValue	Maximum value of `FormatPaddingGroup`.