A C test for an SoC does not go straight from source code to something the DUT can run. The compiler first produces an object file: machine code and data, grouped into named sections, with every address still left blank. The linker then fills those blanks and produces the executable that the simulator loads into memory. Knowing what an object file holds tells you where each variable will end up, why a test can corrupt memory nobody wrote to, and what the linker still has to do. This article compiles one small C file for a 32-bit RISC-V core and reads every part of the result with the standard tools.
10 min read | Intermediate Level
What You'll Learn
- What an object file is and why it cannot run on its own
- Which section each kind of C variable and function lands in, including RISC-V's small-data section
- How the symbol table and relocation entries record what the linker still has to fill in
- How linking turns placeholders into final addresses, and what the loader then copies into the DUT's memory
The Example Program
The whole article follows one file. It has an initialized global, an uninitialized array, a constant string and two functions, which is enough to fill every common section:
#include <stdint.h>
uint32_t counter = 10; // initialized global
uint32_t buffer[256]; // uninitialized global
const char message[] = "Test Complete"; // constant
void increment_counter(void) {
counter++;
}
int main(void) {
increment_counter();
buffer[0] = counter;
return 0;
}
It is compiled for a 32-bit RISC-V core with the base integer instruction set (RV32I). The -c flag tells the compiler to stop after producing the object file instead of linking:
riscv64-unknown-elf-gcc -c -O1 -march=rv32i -mabi=ilp32 simple_test.c -o simple_test.o
The toolchain used here is GCC 13.2 built as riscv64-unknown-elf, which produces 32-bit code when given -march=rv32i -mabi=ilp32. A toolchain built as riscv32-unknown-elf, as used in other articles of this tutorial, gives the same result; only the command prefix differs. Every listing below is the real output of these tools on this file.
What Is an Object File?
An object file is the compiler's output for one source file. It holds the machine code for the functions in that file, the initial values of its variables, and two kinds of bookkeeping: a list of names (the symbol table) and a list of places where an address is still missing (the relocation entries). On RISC-V and most embedded targets the format is ELF, the Executable and Linkable Format, the same format as the final executable. Introduction to ELF covers the format as a whole; this article stays with the object file.
The ELF header says what kind of file this is:
riscv64-unknown-elf-readelf -h simple_test.o
ELF Header: Magic: 7f 45 4c 46 01 01 01 00 00 00 00 00 00 00 00 00 Class: ELF32 Data: 2's complement, little endian Version: 1 (current) OS/ABI: UNIX - System V ABI Version: 0 Type: REL (Relocatable file) Machine: RISC-V Version: 0x1 Entry point address: 0x0 Start of program headers: 0 (bytes into file) Start of section headers: 820 (bytes into file) Flags: 0x0 Size of this header: 52 (bytes) Size of program headers: 0 (bytes) Number of program headers: 0 Size of section headers: 40 (bytes) Number of section headers: 12 Section header string table index: 11
Three fields matter most. Type: REL means relocatable: the file is meant to be combined with others, not run. The entry point is 0x0 because no start address has been chosen yet. And there are no program headers, the tables a loader uses to copy a file into memory, because nothing ever loads an object file directly.
The Sections
Everything in the file is grouped into sections. The section header table lists them:
riscv64-unknown-elf-readelf -S -W simple_test.o
There are 12 section headers, starting at offset 0x334: Section Headers: [Nr] Name Type Addr Off Size ES Flg Lk Inf Al [ 0] NULL 00000000 000000 000000 00 0 0 0 [ 1] .text PROGBITS 00000000 000034 000044 00 AX 0 0 4 [ 2] .rela.text RELA 00000000 000218 0000c0 0c I 9 1 4 [ 3] .data PROGBITS 00000000 000078 000000 00 WA 0 0 1 [ 4] .bss NOBITS 00000000 000078 000400 00 WA 0 0 4 [ 5] .rodata PROGBITS 00000000 000078 00000e 00 A 0 0 4 [ 6] .sdata PROGBITS 00000000 000088 000004 00 WA 0 0 4 [ 7] .comment PROGBITS 00000000 00008c 000023 01 MS 0 0 1 [ 8] .riscv.attributes RISCV_ATTRIBUTES 00000000 0000af 00001c 00 0 0 1 [ 9] .symtab SYMTAB 00000000 0000cc 000100 10 10 11 4 [10] .strtab STRTAB 00000000 0001cc 00004a 00 0 0 1 [11] .shstrtab STRTAB 00000000 0002d8 00005b 00 0 0 1
Every Addr is 0: no section has a place in memory yet. The Flg column says how each section will be used: A means it takes memory at run time (allocated), W means writable, X means executable. The flags are what later lets a linker script put code in one region and variables in another.
.text: the Code
.text holds the machine instructions. Here it is 0x44 = 68 bytes: 20 for increment_counter and 48 for main. Disassembling it shows something odd at first sight:
riscv64-unknown-elf-objdump -d simple_test.o
00000000 <increment_counter>: 0: 00000737 lui a4,0x0 4: 00072783 lw a5,0(a4) # 0 <increment_counter> 8: 00178793 addi a5,a5,1 c: 00f72023 sw a5,0(a4) 10: 00008067 ret 00000014 <main>: 14: ff010113 addi sp,sp,-16 18: 00112623 sw ra,12(sp) 1c: 00000097 auipc ra,0x0 20: 000080e7 jalr ra # 1c <main+0x8> 24: 000007b7 lui a5,0x0 28: 0007a703 lw a4,0(a5) # 0 <increment_counter> 2c: 000007b7 lui a5,0x0 30: 00e7a023 sw a4,0(a5) # 0 <increment_counter> 34: 00000513 li a0,0 38: 00c12083 lw ra,12(sp) 3c: 01010113 addi sp,sp,16 40: 00008067 ret
increment_counter reads, adds 1 to and writes back counter, but the address it uses is 0, and the disassembler even labels that address as increment_counter. The call in main at offset 0x1c also jumps to an offset of 0. These zeros are placeholders. The compiler does not know where counter or buffer will live, so it writes 0 and leaves a note for the linker.
RISC-V needs two instructions to build a 32-bit address, because one instruction can carry at most 20 bits of it. lui loads the upper 20 bits and the following load or store adds the lower 12. The function call works the same way with auipc and jalr.
.data and .sdata: Initialized Variables
A global with a non-zero initial value has to carry that value in the file, so it goes in a data section. The expectation is .data, but the section table shows .data with size 0. The 4-byte counter went to .sdata instead:
riscv64-unknown-elf-objdump -s -j .sdata simple_test.o
Contents of section .sdata: 0000 0a000000 ....
The bytes 0a 00 00 00 are the value 10, stored least significant byte first (little endian). .sdata is the small data section. RISC-V GCC puts globals of 8 bytes or less there by default, so that a program can keep them close together and reach them with one instruction relative to a global pointer register. Treat .sdata as part of .data: it holds initialized, writable variables and needs the same handling. There is a matching .sbss for small zero-initialized variables.
.bss: Zero-Initialized Variables
buffer has no initializer, so C guarantees it starts as all zeros. There is no point storing 1,024 zero bytes in the file, so .bss has type NOBITS: the section header records a size of 0x400 = 1,024 bytes and nothing else. The whole object file is 1,300 bytes on disk, barely more than the array it describes. Someone has to write those zeros into memory before main() runs, which is the start-up code's job (or the testbench's, when it loads the program directly into simulation memory).
.rodata: Constants
riscv64-unknown-elf-objdump -s -j .rodata simple_test.o
Contents of section .rodata: 0000 54657374 20436f6d 706c6574 6500 Test Complete.
The const string is 13 characters plus the terminating zero byte, 14 bytes. Its flag is A alone, not W, so a linker script can place it in read-only memory such as a ROM.
The remaining sections are bookkeeping. .comment records the compiler version, .riscv.attributes records the instruction set (RV32I), .symtab and .strtab hold the symbols and their names, and .rela.text holds the relocations.
Quick Check
Q: A test adds uint32_t table[64] = {1, 2, 3}; and uint32_t flags;. Which sections hold them, and which one makes the object file larger?
Show Answer
table has initial values, so all 256 bytes go in .data and are stored in the file, including the 61 zeros. It is larger than 8 bytes, so it does not go to .sdata. flags is a 4-byte zero-initialized variable, so it goes to .sbss and only its size is recorded. Only table makes the file larger.
The Symbol Table
The symbol table names everything another file, the linker or a debugger might need to find:
riscv64-unknown-elf-readelf -s -W simple_test.o
Symbol table '.symtab' contains 16 entries:
Num: Value Size Type Bind Vis Ndx Name
0: 00000000 0 NOTYPE LOCAL DEFAULT UND
1: 00000000 0 FILE LOCAL DEFAULT ABS simple_test.c
2: 00000000 0 SECTION LOCAL DEFAULT 1 .text
3: 00000000 0 SECTION LOCAL DEFAULT 3 .data
4: 00000000 0 SECTION LOCAL DEFAULT 4 .bss
5: 00000000 0 NOTYPE LOCAL DEFAULT 1 $xrv32i2p1
6: 00000000 0 SECTION LOCAL DEFAULT 5 .rodata
7: 00000000 0 NOTYPE LOCAL DEFAULT 4 .LANCHOR0
8: 00000000 0 SECTION LOCAL DEFAULT 6 .sdata
9: 00000000 0 SECTION LOCAL DEFAULT 7 .comment
10: 00000000 0 SECTION LOCAL DEFAULT 8 .riscv.attributes
11: 00000000 20 FUNC GLOBAL DEFAULT 1 increment_counter
12: 00000000 4 OBJECT GLOBAL DEFAULT 6 counter
13: 00000014 48 FUNC GLOBAL DEFAULT 1 main
14: 00000000 14 OBJECT GLOBAL DEFAULT 5 message
15: 00000000 1024 OBJECT GLOBAL DEFAULT 4 buffer
Each Value is an offset inside the section given by Ndx, not an address: main starts 0x14 bytes into section 1 (.text), and counter sits at offset 0 of section 6 (.sdata). GLOBAL symbols can be used from other files; LOCAL ones cannot. .LANCHOR0 is a local label the compiler placed at the start of .bss and uses to reach buffer. $xrv32i2p1 is a marker recording that the code which follows uses the RV32I instruction set.
The shorter nm listing gives one letter per symbol: T for code, D for initialized data, B for zero-initialized data and R for read-only data. A function that this file calls but does not define would appear as U, undefined, which the linker must find in another file.
00000000 B buffer 00000000 D counter 00000000 T increment_counter 00000014 T main 00000000 R message
Relocations: the Linker's To-Do List
Every placeholder in .text has an entry in .rela.text that says where it is, which symbol it needs and how to insert that symbol's address:
riscv64-unknown-elf-readelf -r -W simple_test.o
Relocation section '.rela.text' at offset 0x218 contains 16 entries: Offset Info Type Sym. Value Symbol's Name + Addend 00000000 00000c1a R_RISCV_HI20 00000000 counter + 0 00000000 00000033 R_RISCV_RELAX 0 00000004 00000c1b R_RISCV_LO12_I 00000000 counter + 0 00000004 00000033 R_RISCV_RELAX 0 0000000c 00000c1c R_RISCV_LO12_S 00000000 counter + 0 0000000c 00000033 R_RISCV_RELAX 0 0000001c 00000b13 R_RISCV_CALL_PLT 00000000 increment_counter + 0 0000001c 00000033 R_RISCV_RELAX 0 00000024 00000c1a R_RISCV_HI20 00000000 counter + 0 00000024 00000033 R_RISCV_RELAX 0 00000028 00000c1b R_RISCV_LO12_I 00000000 counter + 0 00000028 00000033 R_RISCV_RELAX 0 0000002c 0000071a R_RISCV_HI20 00000000 .LANCHOR0 + 0 0000002c 00000033 R_RISCV_RELAX 0 00000030 0000071c R_RISCV_LO12_S 00000000 .LANCHOR0 + 0 00000030 00000033 R_RISCV_RELAX 0
The offsets match the instructions in the disassembly. R_RISCV_HI20 at offset 0x0 fills the upper 20 bits of counter's address into the lui, and R_RISCV_LO12_I at 0x4 fills the lower 12 bits into the lw. The store at 0xc needs its own type, LO12_S, because a store instruction splits its 12-bit offset across two fields. R_RISCV_CALL_PLT at 0x1c covers the whole auipc/jalr pair of the call.
Each relocation is paired with R_RISCV_RELAX. It gives the linker permission to replace the instruction sequence with a shorter one if the final address allows it. The next section shows that happening.
Quick Check
Q: main both reads counter and writes buffer[0]. Why do the relocations at 0x2c and 0x30 name .LANCHOR0 instead of buffer?
Show Answer
The compiler addresses buffer through .LANCHOR0, a local label at the start of .bss. buffer is the only variable in .bss and starts at offset 0, so the label and buffer have the same address, and the store to buffer[0] uses offset 0 from it.
Linking: From Offsets to Addresses
A linker script tells the linker what memory exists and where each section goes. This one describes a single 64 KB RAM at 0x80000000, the layout used in Linker Scripts and Memory Maps:
ENTRY(main)
MEMORY
{
RAM (rwx) : ORIGIN = 0x80000000, LENGTH = 64K
}
SECTIONS
{
.text : { *(.text*) } > RAM
.rodata : { *(.rodata*) } > RAM
.data : { *(.data*) *(.sdata*) } > RAM
.bss : {
_bss_start = .;
*(.sbss*) *(.bss*)
_bss_end = .;
} > RAM
}
riscv64-unknown-elf-gcc -O1 -march=rv32i -mabi=ilp32 -nostdlib -T soc_test.ld simple_test.o -o simple_test.elf
riscv64-unknown-elf-nm -n simple_test.elf
80000000 T increment_counter 80000014 T main 80000040 R message 80000050 D counter 80000054 B _bss_start 80000054 B buffer 80000454 B _bss_end
Every symbol now has a final address. The linker packed the sections in the order of the script: code from 0x80000000, the string at 0x80000040, counter at 0x80000050 after two bytes of padding to keep it 4-byte aligned, then buffer. _bss_start and _bss_end are not variables, only addresses defined by the script. Start-up code reads them to know which range to clear. The linker also warns that the single RAM region is readable, writable and executable at once, which is expected for this simple test layout.
The disassembly of the executable shows the placeholders filled in:
80000000 <increment_counter>: 80000000: 80000737 lui a4,0x80000 80000004: 05072783 lw a5,80(a4) # 80000050 <counter> 80000008: 00178793 addi a5,a5,1 8000000c: 04f72823 sw a5,80(a4) 80000010: 00008067 ret 80000014 <main>: 80000014: ff010113 addi sp,sp,-16 80000018: 00112623 sw ra,12(sp) 8000001c: fe5ff0ef jal 80000000 <increment_counter> 80000020: 800007b7 lui a5,0x80000 80000024: 0507a703 lw a4,80(a5) # 80000050 <counter> 80000028: 800007b7 lui a5,0x80000 8000002c: 04e7aa23 sw a4,84(a5) # 80000054 <buffer> 80000030: 00000513 li a0,0 80000034: 00c12083 lw ra,12(sp) 80000038: 01010113 addi sp,sp,16 8000003c: 00008067 ret
lui a4,0x80000 plus an offset of 80 (0x50) gives 0x80000050, the address of counter. The call shows relaxation at work: increment_counter is close enough for a single jal, so the linker replaced the two-instruction auipc/jalr pair with one instruction. main shrank from 48 to 44 bytes and .text from 68 to 64. Code addresses in a linked program can therefore differ from what the object file suggests, which is one more reason to take addresses from the linked file and not from the object file.
Finally, the program header is what a loader, including a testbench that loads the program into simulation memory, actually uses:
Type Offset VirtAddr PhysAddr FileSiz MemSiz Flg Align LOAD 0x001000 0x80000000 0x80000000 0x00054 0x00454 RWE 0x1000
One LOAD segment starts at 0x80000000. Its file size is 0x54 = 84 bytes (code, string and counter), and its memory size is 0x454 = 1,108 bytes. The 1,024-byte difference is .bss: a loader copies 84 bytes from the file and must fill the rest with zeros. How that program then gets into the DUT's memory is covered in Getting a C Test Running in the DUT.
Why This Matters for Verification
- Memory loading: the testbench or simulator loader must place each section at its linked address, and zero the gap between file size and memory size. If it only copies the file contents, every zero-initialized variable starts with whatever the memory model holds.
- Finding variables: a testbench that checks a result in memory should read the address of the variable from the linked file's symbol table (
nmoutput), not from an address typed into the testbench, which goes stale the next time the code changes. - Debugging: when a store lands at an unexpected address, the disassembly with relocations shows exactly which symbol the instruction was meant to reach.
- Memory map checks: the section flags and sizes show whether the code, constants and variables fit the regions the DUT really decodes.
Common Mistakes
Writing a linker script that names only .data and .bss.
On RISC-V, small variables go to .sdata and .sbss. If the script does not mention them, the linker still places them somewhere as orphan sections, outside the script's control and possibly outside the _bss_start/_bss_end range that start-up code clears. Linking with -Wl,--orphan-handling=warn makes this visible:
/usr/lib/gcc/riscv64-unknown-elf/13.2.0/../../../riscv64-unknown-elf/bin/ld: warning: orphan section `.sdata' from `simple_test.o' being placed in section `.sdata'
Taking addresses from the object file.
Every address in an object file is an offset inside its section, and the linker may still shorten code through relaxation. Use the symbol table of the linked file for any address a testbench depends on.
Assuming .bss is in the file.
The ELF file stores only the size of .bss. A loader or backdoor memory load that copies file contents and stops leaves those variables uninitialized, which can make a test pass or fail depending on what the memory model held before.
Summary
In this article, you learned:
- An object file (ELF type REL) holds code, data and bookkeeping for one source file, with every address still 0 and no entry point
- Code goes to
.text, initialized variables to.data(small ones to.sdataon RISC-V), zero-initialized variables to.bss(stored as a size only), and constants to.rodata - The symbol table records each name with its section and offset; relocation entries record each placeholder and how to fill it, such as
R_RISCV_HI20andR_RISCV_LO12_Ifor an address split across two instructions - The linker uses the linker script to give every section an address, fills the placeholders, and may shorten code through relaxation
- The loader copies the file size of each LOAD segment and must zero the rest; the testbench should take addresses from the linked file's symbols