loader — Binary File Loading

Architecture Overview

The loader subsystem handles the critical task of loading binary workloads into simulated memory. It supports multiple binary formats through a plugin architecture and provides a uniform interface for memory image construction and symbol resolution.

graph TB
    Binary["Binary File\n(.elf, .out, .bin)"]
    IFD["ImageFileData\n(raw file bytes)"]
    IF["ImageFile\n(format parser)"]
    ELF["ElfObject"]
    AOUT["AoutObject"]
    RAW["RawImage"]
    MI["MemoryImage\n(segment list)"]
    ST["SymbolTable\n(name ↔ address)"]
    PM["PhysicalMemory"]

    Binary --> IFD
    IFD --> IF
    IF --> ELF
    IF --> AOUT
    IF --> RAW
    ELF --> MI
    ELF --> ST
    AOUT --> MI
    AOUT --> ST
    RAW --> MI
    MI --> PM
    

ImageFileData

ImageFileData is the lowest-level abstraction — it memory-maps a file from disk and provides raw byte access. All format-specific parsers operate on ImageFileData rather than doing their own file I/O.

class ImageFileData
{
  public:
    ImageFileData(const std::string &filename);
    ~ImageFileData();

    const std::string &filename() const { return _filename; }
    const uint8_t *data() const { return _data; }
    size_t len() const { return _len; }

  private:
    std::string _filename;
    uint8_t *_data;    // Memory-mapped file contents
    size_t _len;       // File size in bytes
};

ImageFile Interface

ImageFile is the abstract base class for all binary format parsers. It receives an ImageFileData and provides methods to extract memory images and symbol tables.

class ImageFile
{
  protected:
    ImageFileData *imageData;

  public:
    ImageFile(ImageFileData *data);
    virtual ~ImageFile();

    // Build the memory image from this file
    virtual MemoryImage buildImage() const = 0;

    // Extract symbol table
    virtual SymbolTable *symtab() const { return nullptr; }

    // Architecture detection
    virtual Arch getArch() const = 0;
    virtual OpSys getOpSys() const = 0;

    // Entry point
    virtual Addr entryPoint() const = 0;
};

ELF Object

The most commonly used format parser. ElfObject reads ELF headers, program headers (segments), section headers, and symbol/string tables. It handles both 32-bit and 64-bit ELF files across multiple architectures.

class ElfObject : public ImageFile
{
  public:
    ElfObject(ImageFileData *data, Arch arch, OpSys os,
              Addr entry, Addr globalPtr);

    MemoryImage buildImage() const override;
    SymbolTable *symtab() const override;

    // ELF-specific accessors
    Addr globalPointer() const { return _globalPtr; }
    bool isDynamic() const;

    // Section info
    uint16_t getEMachine() const;
    uint8_t getEClass() const;    // ELFCLASS32 or ELFCLASS64
    uint8_t getEData() const;     // Endianness

    // Try to load — returns nullptr if not ELF
    static ImageFile *tryFile(ImageFileData *data);

  private:
    Arch _arch;
    OpSys _opSys;
    Addr _entry;
    Addr _globalPtr;
    std::vector<Segment> segments;
};

MemoryImage

MemoryImage represents the in-memory layout of a loaded binary. It consists of named segments, each with a virtual address, physical address, and data. The image is written into simulated physical memory during workload initialization.

class MemoryImage
{
  public:
    struct Segment {
        std::string name;    // e.g., ".text", ".data"
        Addr vaddr;          // Virtual address
        Addr paddr;          // Physical address
        const uint8_t *data; // Segment data
        size_t size;         // Segment size
    };

    MemoryImage();

    // Add a segment
    MemoryImage &addSegment(const Segment &seg);

    // Move all segments by an offset
    MemoryImage &offset(Addr by);
    // Mask addresses (for physical address extraction)
    MemoryImage &mask(Addr m);

    // Write image into physical memory
    bool write(PortProxy &proxy) const;

    // Access segments
    const std::vector<Segment> &segments() const;

    // Min/max addresses
    Addr minAddr() const;
    Addr maxAddr() const;
};

Symbol Table

SymbolTable provides bidirectional mapping between symbol names and addresses. It supports multiple symbol bindings (local, global, weak) and is used for debug output, function tracing, and workload analysis.

class SymbolTable
{
  public:
    struct Symbol {
        enum Binding { Local, Global, Weak };
        Binding binding;
        std::string name;
        Addr address;
    };

    SymbolTable();

    // Insert symbols
    bool insert(const Symbol &sym);
    bool insert(Addr address, const std::string &name);

    // Lookup by name → address
    const Symbol *find(const std::string &name) const;

    // Lookup by address → name (nearest symbol)
    const Symbol *find(Addr addr) const;

    // Reverse lookup (address → name string)
    bool findNearestSymbol(Addr addr, std::string &name,
                           Addr &offset) const;

    // Filter symbols
    SymbolTable filtered(std::function<bool(const Symbol &)> pred) const;
    SymbolTable globals() const;
    SymbolTable locals() const;

    // Iterate
    typedef std::vector<Symbol>::const_iterator const_iterator;
    const_iterator begin() const;
    const_iterator end() const;
    size_t size() const;

    // Serialize/unserialize
    void serialize(const std::string &base, CheckpointOut &cp) const;
    void unserialize(const std::string &base, CheckpointIn &cp);

  private:
    std::vector<Symbol> symbols;
    std::unordered_map<std::string, size_t> nameMap;
    std::map<Addr, size_t> addrMap;
};

Format Detection

When loading a binary, gem5 tries each format handler in sequence until one recognizes the file. This plugin architecture makes it easy to add new formats.

// Auto-detect binary format and load
ImageFile *createImageFile(const std::string &filename)
{
    ImageFileData *data = new ImageFileData(filename);

    // Try each format in priority order
    ImageFile *file = nullptr;
    file = ElfObject::tryFile(data);
    if (file) return file;

    file = AoutObject::tryFile(data);
    if (file) return file;

    // Fall back to raw image
    return new RawImage(data);
}

Supported Architectures

Key Components Reference

Glossary