liveBook · Manning

Sections block

As explained in Embedded Software with Rust

A SECTIONS block is a linker-script construct that maps output sections to declared memory regions and controls their placement.

A SECTIONS block in a linker script maps output sections to declared memory regions. It controls where code and data live, while a MEMORY block names the regions and specifies their addresses and sizes. section 4.1.3 section 5.4.4

Placement can differ at load time and run time. In a typical bare-metal layout, .text and .rodata stay in FLASH, .data is stored in FLASH but moved to RAM at startup, and .bss is reserved and zero-initialized in RAM. section 4.1.3

.data :
  {
    *(.data .data.*)
  } > RAM AT > FLASH

  .bss (NOLOAD) :
  {
    . = ALIGN(8);
    *(.bss .bss.*)
  } > RAM
}

The .data mapping uses RAM as its run-time region and FLASH as its load region. The .bss mapping reserves aligned space in RAM with NOLOAD. section 4.1.3

A vector table is commonly placed at the beginning of FLASH. On Cortex-M, its first entry supplies the initial stack pointer and its second identifies the reset handler. KEEP directives protect the reset vector and exception entries from linker garbage collection. section 4.1.3

SECTIONS
{
  .vector_table :
  {
    LONG(ORIGIN(RAM) + LENGTH(RAM));     /* Initial stack pointer (
        top of RAM) */
    KEEP(*(.vector_table.reset_vector))   /* Reset vector (
        entry point) */
    KEEP(*(.vector_table.exceptions))     /* Other exceptions and
    interrupts */
  } > FLASH

This vector-table mapping computes the top of RAM for the initial stack pointer and retains the named vector sections. section 4.1.3

Custom placement takes two steps: tag a Rust static or function with a section name, then map that section in the linker script. The attribute alone does not choose an address. Placement must respect safety requirements, such as keeping mutable data out of read-only FLASH and code in executable memory. section 5.4.4

// Safety: this buffer is only accessed from a single context.
// In practice, use a mutex or critical section for shared access.
#[unsafe(link_section = ".tcm_data")]
static mut CRITICAL_BUFFER: [u32; 128] = [0; 128];

This Rust static is tagged for the custom .tcm_data section. Shared access would require synchronization; in Rust 2024, access to the mutable static must use raw pointers rather than references. section 5.4.4

MEMORY {
  ITCM     : ORIGIN = 0x00000000, LENGTH = 64K
  DTCM     : ORIGIN = 0x20000000, LENGTH = 64K
  FLASH    : ORIGIN = 0x08000000, LENGTH = 1M
}

SECTIONS {
  .tcm_data (NOLOAD) : ALIGN(4) {
    KEEP(*(.tcm_data*))
  } > DTCM
}

The script declares memory regions and maps .tcm_data into DTCM, retaining matching input sections with KEEP. This TCM example applies to devices that provide DTCM, such as the cited Cortex-M7 devices, not the STM32F103. section 5.4.4

How Embedded Software with Rust covers it

How deep it goes
Works through standard and custom section mappings, load versus run locations, alignment, and linker retention.
Examples
Uses a FLASH vector table, RAM data sections, and a custom DTCM buffer to illustrate placement.
What you can do after
Operate/configure a linker script to place standard and custom sections in declared memory regions.
How it connects
Connects linker scripts to memory regions, reset handlers, vector tables, and Rust link_section attributes.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Embedded Software with Rust. The section links point to the parts of the book it draws on.