Instruction Execution Tracing

To effectively debug a CPU simulator, capturing the flow of instruction execution is fundamental. This mechanism, often referred to as instruction tracing, records the program counter, the raw instruction bytes, and the disassembled mnemonic for every cycle.

The core logic resides within the main execution loop. When an instruction is fetched and decoded, a logging buffer is populated. If specific compilation flags are enabled, this buffer is formatted to include the hexadecimal address, the machine code, and the human-readable assembly instruction.

// src/cpu/execution_loop.c
static void process_instruction_cycle(Decode *decoder, vaddr_t current_pc) {
  decoder->pc = current_pc;
  decoder->snpc = current_pc;
  
  // Execute the specific ISA instruction
  isa_execute_single(decoder);
  
  // Update the global CPU program counter
  cpu.pc = decoder->dnpc;

#ifdef ENABLE_INSTRUCTION_TRACE
  char *buffer_ptr = decoder->debug_log;
  
  // Format the program counter address
  buffer_ptr += snprintf(buffer_ptr, sizeof(decoder->debug_log), 
                         FMT_WORD ":", decoder->pc);
  
  // Calculate instruction length
  int instr_len = decoder->snpc - decoder->pc;
  uint8_t *raw_bytes = (uint8_t *)&decoder->isa.inst.val;
  
  // Print raw instruction bytes in hex
  for (int i = instr_len - 1; i >= 0; i--) {
    buffer_ptr += snprintf(buffer_ptr, 4, " %02x", raw_bytes[i]);
  }
  
  // Pad space for alignment based on ISA architecture
  int max_len = defined(CONFIG_ISA_x86) ? 8 : 4;
  int padding = max_len - instr_len;
  if (padding < 0) padding = 0;
  padding = padding * 3 + 1;
  memset(buffer_ptr, ' ', padding);
  buffer_ptr += padding;
 
  // Perform disassembly and append to log
  resolve_instruction_assembly(buffer_ptr, 
      decoder->debug_log + sizeof(decoder->debug_log) - buffer_ptr,
      defined(CONFIG_ISA_x86) ? decoder->snpc : decoder->pc, 
      (uint8_t *)&decoder->isa.inst.val, instr_len);
#endif
}

The disassembly process leverages external libraries too translate machine code into assembly mnemonics. The resulting string is appended to the log buffer.

// src/utils/disassembler.cc
extern "C" void resolve_instruction_assembly(char *output_str, int max_size, 
                                             uint64_t addr, uint8_t *code, int len) {
  MCInst instruction;
  llvm::ArrayRef<uint8_t> byte_array(code, len);
  uint64_t temp_size = 0;
  
  // Decode instruction using LLVM backend
  gDisassembler->getInstruction(instruction, temp_size, byte_array, addr, llvm::nulls());
 
  std::string assembly_text;
  raw_string_ostream stream(assembly_text);
  gIP->printInst(&instruction, addr, "", *gSTI, stream);
 
  // Remove leading whitespace
  int offset = assembly_text.find_first_not_of('\t');
  const char *clean_text = assembly_text.c_str() + offset;
  
  assert((int)assembly_text.length() - offset < max_size);
  strcpy(output_str, clean_text);
}

To persist these logs, the system parses command-line arguments during initialization. A specific flag allows users to designate a file path for log output. During execution, if the trace condition is met, the content of the debug buffer is written to this file. Additionally, single-step debugging modes can trigger immediate output to the standard terminal.

Instruction Circular Buffer

While continuous logging is useful, it generates excessive data during long runs. A more efficient approach for crash debugging is maintaining a circular buffer of the most recent instructions. When a panic occurs (such as an out-of-bounds memory access), the simulator can dump this buffer to provide context on the events leading up to the failure.

The implementation involves storing decoded instruction structures in a fixed-size array. A pointer tracks the next write position, wrapping around to the beginning when the buffer is full.

// src/utils/history_trace.c
#include <common.h>
#include <cpu/decode.h>

#define HISTORY_BUFFER_SIZE 16

static Decode instruction_history[HISTORY_BUFFER_SIZE];
static int current_history_index = 0;

// Record the current instruction into the circular buffer
void record_instruction_history(Decode entry) {
  instruction_history[current_history_index++] = entry;
  if (current_history_index >= HISTORY_BUFFER_SIZE) {
    current_history_index = 0;
  }
}

// Helper to format a single history entry
static void format_history_entry(Decode *entry) {
  char *ptr = entry->debug_log;
  ptr += snprintf(ptr, sizeof(entry->debug_log), FMT_WORD ":", entry->pc);
  
  int len = entry->snpc - entry->pc;
  uint8_t *bytes = (uint8_t *)&entry->isa.inst.val;
  
  for (int i = len - 1; i >= 0; i--) {
    ptr += snprintf(ptr, 4, " %02x", bytes[i]);
  }
  
  // ... (padding and disassembly logic similar to itrace) ...
  // Disassembly call omitted for brevity
}

// Display the buffer content when an error occurs
void display_instruction_history() {
  // Calculate the index of the most recent instruction
  int latest_index = (current_history_index - 1) < 0 ? 
                     HISTORY_BUFFER_SIZE - 1 : current_history_index - 1;
  
  for (int i = 0; i < HISTORY_BUFFER_SIZE; i++) {
    // Mark the instruction that caused the crash (or the latest one)
    if (i == latest_index) {
      printf("%-4s", "-->");
    } else {
      printf("%-4s", "   ");
    }
    
    format_history_entry(&instruction_history[i]);
    printf("%s\n", instruction_history[i].debug_log);
  }
}

This display function is hooked into the assertion failure handler. When the system detects an invalid state, it invokes the history display before terminating, ensuring the developer sees the immediate execution context.

Memory Access Monitoring

Trcaking memory operations is crucial for diagnosing segmentation faults or data corruption. This feature, distinct from the instruction buffer, logs every read and write operation to physical memory. Due to the high frequency of memory access, this feature should be toggleable via configuration to avoid performance degradation and log flooding.

Implementation involves inserting logging calls within the physical memory read and write handlers. Conditional compilation ensures the code is only included when enabled.

// src/memory/physical_mem.c
void log_memory_access_read(paddr_t address, int length) {
  printf("READ  addr=" FMT_PADDR " pc=" FMT_WORD " size=%d\n",
      address, cpu.pc, length);
}
 
void log_memory_access_write(paddr_t address, int length, word_t data) {
  printf("WRITE addr=" FMT_PADDR " pc=" FMT_WORD " size=%d data=" FMT_WORD "\n",
      address, cpu.pc, length, data);
}

Integration with the build system allows users to enable or disable this feature through a menu configuration interface. Advanced implementations might filter logs based on specific address ranges to focus on relevant memory regions.

Function Call Tracing

Understanding the control flow at the function level requires parsing the executable file format. For this simulator, the ELF format is used. The goal is to identify function calls and returns dynamically during execution.

To achieve this, the simulator must load the ELF file provided as an argument. During initialization, the symbol table and string table sections are parsed to map addresses to function names. This avoids reliance on external tools like readelf during runtime, fostering a deeper understanding of the ELF structure.

For architectures like RISC-V, specific instructions such as jal (Jump and Link) and jalr (Jump and Link Register) indicate function calls and returns. The tracing logic must decode these instructions to update the call stack representation.

The implementation task involves:

• Extending the argument parser to accept the ELF file path.
• Writting an ELF parser to extract symbol information into memory.
• Hooking into the instruction execution stage to detect call/return patterns.
• Printing the function entry and exit events with appropriate indentation to visualize the call stack.