Programmer's Manual for `libmicroemu`

Table of Contents

• Introduction
• Overview of the Library
  • Namespaces
  • Key Classes
• Error Management
• Logging
  • Overview
  • Logging Configuration
  • Built-In Loggers
• Typical Usage
  • Example Code
  • Step 1: Memory Setup
  • Step 2: Load ELF Files
  • Step 3: Start Emulation
• Extensibility

Introduction

Welcome to the Programmer's Manual for the libmicroemu Library!

It is a work in progress and will be updated regularly.

Overview of the Library

Namespaces

• Public Namespace:
  All user-accessible features are within libmicroemu.
• Private Namespace:
  Internals of the library reside in libmicroemu::internal. These are not accessible to library users.

Key Classes

• libmicroemu::Machine:
  The primary class for controlling the emulator. It allows configuration, ELF loading, and execution.
• libmicroemu::CpuStates:
  Encapsulates the emulator's state, including CPU registers and exception states.
• libmicroemu::ExecResult:
  Represents the result of an emulation run, detailing why execution stopped.

Error Management

• Consistent Error Handling:
  The error management system in libmicroemu ensures consistent and predictable handling of errors across all APIs. Focused on performance and simplicity, it avoids exceptions in favor of lightweight mechanisms.
• Key Components:
  • libmicroemu::StatusCode:
    Enum class defining operation outcomes, including success (libmicroemu::StatusCode::kSuccess) and various error categories such as memory issues (libmicroemu::StatusCode::kMemInaccesible), decoding failures (libmicroemu::StatusCode::kDecoderUnknownOpCode), and ELF-related errors (libmicroemu::StatusCode::kElfNotValid).
  • libmicroemu::StatusCodeToString:
    Converts a StatusCode into a human-readable string for debugging and logging purposes.
  • libmicroemu::internal::Result Class:
    Used internally to encapsulate either a result or a StatusCode in case of failure. Provides flexibility for handling complex results.
• Macros for Error Propagation:
  • TRY : Forwards results to the caller if a function returns an error.
  • TRY_ASSIGN : Combines result assignment and error propagation in a single step.

Logging

Overview

• Purpose:
  Logging in libmicroemu is used for tracking emulator activity, debugging, and performance monitoring.

Logging Configuration

1. Registering a Callback:
   
   • Use libmicroemu::Machine::RegisterLoggerCallback.
     
   • Callback is static for performance reasons.
     
   • Expected function signature is clearly defined.
2. Log Levels:
   
   • Log levels are build-dependent and defined in libmicroemu::LogLevel:
     
     • Debug: libmicroemu::LogLevel::kTrace and above.
       
     • Release: libmicroemu::LogLevel::kInfo and above.

Built-In Loggers

1. libmicroemu::StaticLogger:
   Outputs logs to static files or predefined locations.
2. libmicroemu::NullLogger:
   Disables logging entirely for performance-critical applications.

Typical Usage

Here’s an example demonstrating a typical use case for the emulator:

Example Code

#include "libmicroemu/machine.h"
#include <iostream>
#include <vector>
 
// Path to the ELF file
constexpr static const char *kElfPath = "coremark/prebuilt/bin/coremark.elf";
 
constexpr static libmicroemu::me_adr_t kFlashSegVadr = 0x0U;
constexpr static libmicroemu::me_adr_t kRam1SegVadr = 0x20000000U;
 
int main() {
  libmicroemu::Machine machine;
  std::cout << "Using libmicroemu version: " << machine.GetVersion() << std::endl;
 
  // Allocate memory for FLASH and RAM1 segments
  auto flash_seg = std::vector<uint8_t>(0x20000u); // 128KB for FLASH
  auto ram1_seg = std::vector<uint8_t>(0x40000u);  // 256KB for RAM1
 
  // Set up memory segments
  machine.SetFlashSegment(flash_seg.data(), flash_seg.size(), kFlashSegVadr);
  machine.SetRam1Segment(ram1_seg.data(), ram1_seg.size(), kRam1SegVadr);
 
  // Load the ELF file and set the entry point
  if (machine.Load(kElfPath, true) != libmicroemu::StatusCode::kSuccess) {
    std::cerr << "Failed to load ELF file." << std::endl;
    return EXIT_FAILURE;
  }
 
  // Execute the ELF file
  auto res_exec = machine.Exec();
  if (res_exec.IsErr()) {
    std::cerr << "Failed to execute ELF file." << std::endl;
    return EXIT_FAILURE;
  }
  return 0;
}

Step 1: Memory Setup

• Before the emulator can start operating, it must know the memory segments where the binary content will be stored.
• These segments are typically specified in the implementation documentation of the ARMv7-M architecture.
• Commonly used memory segment addresses:
  • Flash: Starts at 0x00000000
  • SRAM: Starts at 0x20000000
• Define FLASH memory using libmicroemu::Machine::SetFlashSegment.
• Set up RAM memory using libmicroemu::Machine::SetRam1Segment (optionally libmicroemu::Machine::SetRam2Segment for additional RAM).

Step 2: Load ELF Files

• Load an ELF file using libmicroemu::Machine::Load.
• Ensure the allocated FLASH memory can accommodate the ELF file contents.
• Set the entry point either automatically (from the ELF file) or manually.
• If the entry point is not set from the ELF file, the reset vector specifies the entry point.

Step 3: Start Emulation

• Start emulation with libmicroemu::Machine::Exec.
• Emulation stops under specific conditions:
  • Reaching a maximum instruction count (useful for coroutine-like workflows).
  • Program exit via:
    • SVC call.
    • Semihosting, e.g., exit() in the emulated program (handles termination automatically).

Extensibility

TBD