17. Section reference

Compiler-generated code and data objects are organized into sections within the object file. Understanding these sections is crucial for writing linker placement files and interpreting compiler and linker list files.

17.1. Section overview

Code and data objects occupy space in target memory, either as program-bits (actual data written to memory) or no-bits (sections represented only by their size in the ELF object file).

The Calypsi C compiler tool chain has adapted names that trace back to the origins to the early days of computing. These may not always be the best possible names, but they are widely known and familiar to many.

Sections are broadly categorized into three groups: text, data, and bss. Text sections are read-only program-bits. Data sections are read-write program-bits. BSS sections are read-write no-bits.

Note

If you ever wondered about what bss section stands for, it originally is block started by symbol, a pseudo operation in an assembler for IBM 704 from the mid fifties. Some people suggest it is easier to remember as better save space, as it is a way to save space in the output file by just storing the size of the section without any explicit data bits.

Section names

Each section has a name, and multiple section fragments can share the same name. Section names serve two purposes:

• To provide a descriptive identifier for the section.

• To control memory placement through rules that reference these names.

Section types

Each section has a type: text, data, or bss. For embedded systems, rodata (read-only data) and no-init sections are also available. Read-only data sections are similar to text sections but identify data rather than executable code. No-init sections resemble bss but lack the memory-clearing mechanism.

Data sections

From the compiler’s perspective, data sections are read-write program-bits sections, meaning they have initializer values that reside in memory. In a hosted environment, such sections are loaded into memory before program execution. This approach is unsuitable for programs stored in flash memory where execution is expected to begin immediately upon power-on.

To address this, the linker clones data sections. The initializers for the original data section are moved and placed in the clone. The clone has a section name with an “i” prepended (e.g., idata for data) and is intended for flash (read-only) memory.

To initialize data sections on power-on, a copy routine is inserted before the main() function. This routine copies initializers from flash to RAM, initializing data memory and clearing bss sections.

The linker generates a data-init_table describing data to be copied and cleared.

Note

For some targets, the Calypsi C compiler tool chain can cross-compile executables for OS loading. The --hosted option prevents data section cloning, avoiding duplication. However, the table-driven initializer is still needed for BSS sections in such environments.

17.2. Sections used by the compiler

The following sections are sections used by the Calypsi C compiler tool chain.

Table 17.1 Sections

Section name	Type	Memory kind	Description
code	text	ROM	Executable code
nearcode	text	ROM	Executable near code
znear	bss	RAM	bss (zero initialized) near data
near	data	RAM	Initialized near data
zfar	bss	RAM	bss (zero initialized) far data
far	data	RAM	Initialized far data
cfar	rodata	ROM	Constant far data
switch	rodata	ROM	Switch tables
inear	rodata	ROM	Near data initializers
ifar	rodata	ROM	Far data initializers
data_init_table	rodata	ROM	Data initializer table
reset	text	ROM	Reset vector, when used
heap	noinit	RAM	Heap memory, for malloc()
stack	noinit	RAM	User stack
sstack	noinit	RAM	Supervisor stack

The sections inear, ifar and data_init_table in the table above are linker generated.

Note

It is assumed that there are no ROM or flash in either the Near area. Constants placed in either of those are placed in a normal writable section and the const attribute only affects the type of the object.

Note

The table assigns sections to ROM and RAM for ROM-based applications that start on power-up. For hosted systems loading from storage to RAM, this distinction is not applicable. Always consider ROM-marked sections as read-only.

The vector section

An interrupt function will have an associated vector. This is a specially named section for the purpose of holding a single vector. The name looks something like $$interruptVector_0x00000000. The intended address of the vector is encoded in the section name and the linker recognizes these and will place the vector at the address specified. This is handled without the help of any section placement rules.

Section reference

The following goes through the available sections in detail.

code

Holds program code, address range 0x00000000-0xffffffff. This section is intended to be placed in a flash or ROM memory.

nearcode

Holds program code, address range 0x00000000-0xffffffff but limited to about 32K. Code in this section treats function calls as being reachable with the BSR instruction that takes a signed 16 bit offset, which means all calls are assumed to be reachable.

znear

Holds zero initialized (bss) data reachable using base relative from register A4, up to 64K in total.

near

Holds initialized data reachable using base relative from register A4, up to 64K in total.

zfar

Holds zero initialized (bss) data in the main memory, address range 0x00000000-0xffffffff.

far

Holds non-zero initialized data in the main memory, address range 0x00000000-0xffffffff.

cfar

Holds initialized constant data in the main memory, address range 0x00000000-0xffffffff. This section is intended to be placed in a flash or ROM memory.

switch

Holds switch tables in the main memory, address range 0x00000000-0xffffffff. This section is intended to be placed in a flash or ROM memory.

inear

Holds initializers for the near section. This section is created by the linker by cloning the near section provided by the compiler. This section is placed in the main memory, address range 0x00000000-0xffffffff and needs to be placed in a flash or ROM. This section is not used when linking for a hosted system.

ifar

Holds initializers for the far section. This section is created by the linker by cloning the far section provided by the compiler. This section is placed in the main memory, address range 0x00000000-0xffffffff and needs to be placed in a flash or ROM. This section is not used when linking for a hosted system.

data_init_table

This section is created by the linker and filled in with information to the C startup code on how to copy and clear memory regions to properly initialize the data object before giving control to main(). This section is placed in the main memory, address range 0x00000000-0xffffffff and needs to be placed in read-only memory, such as flash or ROM.