Project Logs

Collapse

• How Mk handles dynamic loading

  EmbSoft3 • 07/08/2026 at 15:18 • 0 comments

  To allow external programs to be loaded dynamically at runtime without being statically linked against the kernel, the Mk ELF loader needs to resolve symbols on the fly. Instead of duplicating or hardcoding the entire kernel API inside every external application, the system relies on Sym2srec.

  Sym2srec extracts the .symtab and .strtab sections from an ELF32 executable, generates an optimized GNU hash table, and embeds everything as loadable segments into a new S-Record file ready to flash.

  Here is the complete layout and the lookup protocol used inside the Mk ecosystem.

  Concepts

  Symbol — a unique identifier representing a function, variable, or object in a program.

  Symbol resolution — the process of finding the exact memory address of a symbol:

  • Static resolution: performed at compile time, for symbols known within a single compilation unit.
  • Dynamic resolution: performed at runtime, for symbols shared across compilation units or loaded dynamically.

  Relocation — adjusting a symbol's address so it can be correctly referenced after being loaded at a different address than originally linked.

  Dynamic loading — copying a program from storage into RAM and resolving all symbol references so it can execute correctly.

  Output format — S-Record layout

  Sym2srec parses the input ELF file and performs the following steps:

  1. Builds a GNU hash table (.gnuhash) from the .symtab and .strtab sections.
  2. Builds a SymbolsAreaHeader_t header pointing to all three tables.
  3. Copies all existing loadable segments from the ELF file to the S-Record.
  4. Appends .symtab, .strtab, and .gnuhash as new loadable segments.

  The resulting S-Record layout is:

  S-Record file
  │
  ├── Existing loadable segments (from input ELF)
  │
  └── Symbol area  (at <base_address>)    
      ├── SymbolsAreaHeader_t        ← loaded at <base_address>   
      ├── .symtab                    ← at symtabBaseAddr    
      ├── .strtab                    ← at strtabBaseAddr    
      └── .gnuhash                   ← at gnuHashBaseAddr
  

  Symbol resolution protocol

  This section describes the complete protocol a dynamic loader must implement to resolve a symbol by name using the data produced by sym2srec.

  SymbolsAreaHeader_t

  The symbol area always begins with this header at <base_address>:

  typedef struct
  {    
      uint32_t  magicNumber;       /* Magic number: 0x53594D42 ('SYMB') */    
      uint32_t  headerSize;        /* Size of this header in bytes (40) */    
      uint32_t  padding;           /* Reserved: 0xFFFFFFFF */    
      uint32_t  version;           /* Header version: 0x00000001 */    
      uint32_t* symtabBaseAddr;    /* Pointer to the symbol table */    
      uint32_t  symtabSize;        /* Size of the symbol table in bytes */    
      uint32_t* strtabBaseAddr;    /* Pointer to the string table */    
      uint32_t  strtabSize;        /* Size of the string table in bytes */    
      uint32_t* gnuhashBaseAddr;   /* Pointer to the GNU hash table */    
      uint32_t  gnuhashSize;       /* Size of the GNU hash table in bytes */
  } SymbolsAreaHeader_t;
  

  To access the header in your loader:

  SymbolsAreaHeader_t* l_header = (SymbolsAreaHeader_t*) 0x002C0000;

  GNU hash table

  The GNU hash table is stored contiguously in memory. Initialize the following structure from the header to navigate it:

  typedef struct
  {    
      uint32_t  nbuckets;          /* Number of buckets */    
      uint32_t  symbolsOffset;     /* Index of first non-local symbol */    
      uint32_t  bloomFilterSize;   /* Bloom filter size in 32-bit words */    
      uint32_t  bloomFilterShift;  /* Bloom filter shift value */    
      uint32_t* bloomAddr;         /* Pointer to the bloom filter array */    
      uint32_t* bucketsAddr;       /* Pointer to the bucket array */    
      uint32_t* hashValuesAddr;    /* Pointer to the hash value array */
  } ELF32GNUHashTable_t;
  

  Initialize it from the header:

  ELF32GNUHashTable_t l_hashTable;
  
  l_hashTable.nbuckets        =  l_header->gnuhashBaseAddr[0];
  l_hashTable.symbolsOffset   =  l_header->gnuhashBaseAddr[1];
  l_hashTable.bloomFilterSize =  l_header->gnuhashBaseAddr[2];
  l_hashTable.bloomFilterShift=  l_header->gnuhashBaseAddr[3];
  l_hashTable.bloomAddr       = &l_header->gnuhashBaseAddr[4];
  l_hashTable.bucketsAddr = &l_header->gnuhashBaseAddr[4...

  Read more »

• Initial release

  EmbSoft3 • 06/26/2026 at 18:58 • 0 comments

  Mk is available on GitHub after 6 years of solo development. Future logs will dive into specific parts of the implementation: the kernel, the dynamic ELF loader, the USB stack, and more.

View all 2 project logs