1. Home
2. Academy
3. Embedded C from Zero
4. Volume 09

9.1 Flash and RAM

A microcontroller has two memories, not one. Flash keeps what you put in it when the power goes. RAM forgets everything, every time.

Volume 00 put the numbers side by side: a small chip might have 64 KB of flash and 8 KB of RAM. Two budgets, not one. Running out of either one stops the build, and they run out for different reasons.

You can read the book while you cook. You cannot easily rewrite a page of it mid-recipe. That is flash: fast to read, awkward and slow to write, and only a limited number of writes before it wears out. So your program lives in flash and is read straight out of it, while everything that changes lives in RAM.

The two budgets, kept apart

RAM is usually the one you run out of first. It is the smaller number by a long way, and a single careless buffer can swallow it. Keeping an eye on it is most of what this volume is for.

9.2 .text, .data, .bss, stack and heap

The compiler does not produce one lump. It sorts your program into named piles called sections, and which pile a variable lands in decides what it costs.

There are four you meet constantly.

The odd one is .data. Those variables change, so they have to be in RAM. But something has to remember what they start at, and RAM remembers nothing. So the starting values are stored in flash as well, and copied across before your program runs. They cost you twice.

.bss is the bargain. Every one of those variables starts at zero, and zero does not need storing. Only the space is reserved, and code writes the zeros at start-up.

Watching it happen

Here is a file with one of each kind. Nothing in it runs; it exists to be weighed.

const uint8_t gamma_table[256] = { 1, 2, 3 };     /* .rodata: never changes  */

uint32_t calibration = 0x12345678u;               /* .data: starts non-zero  */
uint8_t  message[16] = "ready";                   /* .data                   */

uint32_t tick_count;                              /* .bss: starts at zero    */
uint8_t  rx_buffer[512];                          /* .bss                    */

static uint32_t private_counter;                  /* .bss, but private       */
static uint16_t private_limit = 1000u;            /* .data, but private      */

Compile it and ask the toolchain what it made. size counts each pile, and nm lists every symbol with its size.

section              size   addr
.text                  89      0
.data                  36      0
.bss                  520      0
.rodata               256      0

Check .bss against the source. rx_buffer is 512, tick_count is 4, private_counter is 4. That is 520, exactly. And .rodata is 256, the size of gamma_table.

The one that does not add up

.data says 36. But the variables in it are 4, 16 and 2 bytes, which is 22. Where did the other 14 go? nm answers it, because it prints the address each symbol landed at.

0000000000000000 0000000000000002 d private_limit
0000000000000010 0000000000000010 D message
0000000000000020 0000000000000004 D calibration

0000000000000000 0000000000000200 B rx_buffer
0000000000000200 0000000000000004 B tick_count
0000000000000204 0000000000000004 b private_counter

private_limit takes bytes 0 and 1. Then message starts at 0x10, which is 16. Fourteen bytes were skipped. This is padding again, the same thing Volume 08 found inside structs, and for the same reason: the compiler lines up a 16-byte array on a 16-byte boundary. The alignment rules do not stop at the edge of a struct.

.bss needed no padding at all, because its members happened to fall in a convenient order.

The 4096-byte question

This is the rule that catches people out, so it is worth proving. Two programs, each with a 4 KB buffer. The only difference is what the buffer starts at.

uint8_t buffer[4096];

int main(void)
{
    buffer[0] = 1u;
    return buffer[0];
}

uint8_t buffer[4096] = { 0xAA, 0xAA, /* ...4096 of them */ };

int main(void)
{
    buffer[0] = 1u;
    return buffer[0];
}

Build both and measure the files:

   text    data     bss     dec     hex  filename
   1233     544    4128    5905    1711  zeros
   1233    4656       8    5897    1709  ones

zeros: 15808 bytes
ones:  19920 bytes
difference: 4112 bytes

The buffer moved out of .bss and into .data, and the built file grew by 4112 bytes. On a chip that is 4 KB of flash gone, to store 4096 copies of the same byte. The RAM cost is identical either way.

Where the rest of RAM goes

Two more regions share RAM with your variables, and neither appears in the table above. The stack holds local variables and return addresses, and grows downwards from the top of RAM. The heap is what malloc hands out, and grows upwards from the end of .bss. They grow towards each other, into the same free space.

9.3 The linker script in plain words

The compiler makes the piles. The linker decides where each one goes, and it takes its orders from a linker script.

A linker script is a plain text file, usually ending .ld. Your toolchain already has one for your chip, and most projects never touch it. It is worth being able to read, because it explains every address you will meet in a map file.

It has two parts. The first says what memory the chip has.

MEMORY
{
  FLASH (rx)  : ORIGIN = 0x08000000, LENGTH = 64K
  RAM   (rwx) : ORIGIN = 0x20000000, LENGTH = 8K
}

_estack = ORIGIN(RAM) + LENGTH(RAM);     /* the stack starts at the very top */

ENTRY(Reset_Handler)                     /* the first function to run        */

That is the whole memory map: two regions, each with a start address and a length. rx means readable and executable. rwx adds writable. These numbers come from the chip's datasheet, not from you.

The second part says where each section goes.

SECTIONS
{
  .isr_vector : { KEEP(*(.isr_vector)) } > FLASH   /* must be first in flash */

  .text   : { *(.text) *(.text*) }     > FLASH
  .rodata : { *(.rodata) *(.rodata*) } > FLASH

  _sidata = .;                         /* where the .data image sits in flash */

  .data : AT ( _sidata )
  {
    _sdata = .;
    *(.data) *(.data*)
    _edata = .;
  } > RAM

  .bss :
  {
    _sbss = .;
    *(.bss) *(.bss*) *(COMMON)
    _ebss = .;
  } > RAM
}

Read *(.text) as "every .text section, from every input file, one after another". The > FLASH at the end is the instruction that matters: put the result in the FLASH region.

The trick that makes .data work

Look at .data again. It ends with > RAM, but it also says AT ( _sidata ), which points into flash. It has two addresses, and both are real.

The run address is in RAM. That is the address your code uses whenever it touches the variable. The load address is in flash. That is where the starting value is actually stored in the built image.

objdump prints both, and here they are for a real link of that script:

Idx Name          Size      VMA               LMA               File off  Algn
  1 .text         00000054  0000000008000010  0000000008000010  00001010  2**0
                  CONTENTS, ALLOC, LOAD, READONLY, CODE
  3 .data         00000004  0000000020000000  0000000008000068  00002000  2**2
                  CONTENTS, ALLOC, LOAD, DATA
  4 .bss          00000204  0000000020000020  00000000080000a0  00002020  2**5
                  ALLOC

For .text the two addresses match: code runs from where it is stored. For .data they do not. Its VMA is 0x20000000 in RAM and its LMA is 0x08000068 in flash, which is the gap the copy loop has to close.

Now look at .bss. Its flags say ALLOC and nothing else. .text and .data both say CONTENTS and LOAD, meaning there are real bytes in the file to program. .bss has none. That single missing word is the whole reason a zero-filled array is free.

9.4 What happens before main

main is not the first thing that runs. By the time it starts, something has already put RAM in order, and that something is only a few lines long.

When power arrives, the core does not look for main. It reads the first two words of flash. The first is the address the stack should start at. The second is the address of the first instruction to run, which by convention is called the Reset_Handler. That pair, and the interrupt handlers after it, are the vector table.

The whole of start-up, in two loops

Strip away the chip-specific parts and start-up code is this:

extern uint32_t _sidata, _sdata, _edata, _sbss, _ebss, _estack;

void Reset_Handler(void)
{
    uint32_t *src = &_sidata;          /* the copy in flash  */
    uint32_t *dst = &_sdata;           /* where it belongs   */
    while (dst < &_edata) {
        *dst++ = *src++;               /* 1. copy .data      */
    }
    for (dst = &_sbss; dst < &_ebss; dst++) {
        *dst = 0u;                     /* 2. zero .bss       */
    }
    (void)main();
    for (;;) { }                       /* main should never return */
}

__attribute__((section(".isr_vector"), used))
void *const vector_table[2] = { (void *)&_estack, (void *)Reset_Handler };

Notice the variables are declared extern and never defined anywhere in C. They do not hold values. The linker plants them at the section boundaries, and the code only ever takes their addresses.

Watching RAM come good

Here is the same thing with "flash" and "RAM" as two arrays, so it can be printed at each step. RAM starts full of 0xA5, which is a pattern some debuggers really do leave behind.

                       word[0]  word[1]  word[2]  word[3]  word[4]  word[5]
at power-on:           A5A5A5A5 A5A5A5A5 A5A5A5A5 A5A5A5A5 A5A5A5A5 A5A5A5A5
after copying .data:   12345678 000003E8 A5A5A5A5 A5A5A5A5 A5A5A5A5 A5A5A5A5
after zeroing .bss:    12345678 000003E8 00000000 00000000 00000000 00000000

main() now starts with calibration = 0x12345678 and tick_count = 0

Two loops, and RAM is fit to use. Take out the second one and the difference is immediate:

with a correct start-up:    tick_count = 0
with the .bss loop missing: tick_count = 2779096485

2779096485 is 0xA5A5A5A5 read as a number. The variable was never given a value, and nothing cleared it, so it starts as whatever the RAM held.

9.5 Reading a map file

A map file is the receipt. It lists every section and every symbol, with the address it landed at and the space it took.

You ask for one at link time. With gcc it is one flag, and the file costs nothing to produce:

gcc ... -Wl,-Map=firmware.map -o firmware.elf

A real map for a real project runs to thousands of lines. The structure is always the same, so learn it on a small one. This is the map from the tiny firmware in Module 4.

Part one: the chip

Memory Configuration

Name             Origin             Length             Attributes
FLASH            0x0000000008000000 0x0000000000010000 xr
RAM              0x0000000020000000 0x0000000000002000 xrw

That is the MEMORY block from the linker script, echoed back. Always check it first. If the lengths are wrong here, every other number in the file is measured against the wrong wall.

0x10000 is 65536, so 64 KB of flash. 0x2000 is 8192, so 8 KB of RAM.

Part two: where everything went

.data      0x0000000020000000   0x4 load address 0x0000000008000068
           0x0000000020000000       _sdata = .
 .data     0x0000000020000000   0x4 fw.o
           0x0000000020000000       calibration
           0x0000000020000004       _edata = .

.bss       0x0000000020000020 0x204 load address 0x00000000080000a0
           0x0000000020000020       _sbss = .
 .bss      0x0000000020000020 0x204 fw.o
           0x0000000020000020       rx_buffer
           0x0000000020000220       tick_count
           0x0000000020000224       _ebss = .

Each block reads the same way. First the output section, its address and its size. Then the input sections that fed it, each with the object file it came from. Then the symbols, at the addresses they ended up at.

The words load address on the .data line are the same two-address idea from Module 3, written out in full.

The gap worth noticing

_edata is at 0x20000004. But .bss starts at 0x20000020, which is 28 bytes later. Those 28 bytes belong to nobody.

It is alignment once more. rx_buffer is large, so the compiler asks for it to start on a 32-byte boundary, and 0x20000020 is the next one up. The linker obliges and leaves a hole.

Adding it up

Now the question the map exists to answer. Flash used is everything stored in it:

.isr_vector    16
.text          84
.rodata         4
.data           4     <- the starting values, stored in flash
             ----
               108

RAM used by variables runs from the start of RAM to _ebss, which is 0x224, or 548 bytes. That includes the 28-byte hole. It leaves 7644 bytes for the stack and heap to share.

How much stack are you really using?

Nothing reports it, so you measure it. Before main, fill the free RAM with a pattern. Later, count how many of those words are still untouched. Whatever is no longer the pattern, the stack reached. That deepest point is the high-water mark.

a dot is a word still holding the paint, a hash is a word the stack reached
                           bottom -> top
just after painting:       ................................  used  0 of 32 words (0 bytes)
after a shallow function:  ..........................######  used  6 of 32 words (24 bytes)
after a deeper one:        ...............#################  used 17 of 32 words (68 bytes)
after a shallow one again: ...............#################  used 17 of 32 words (68 bytes)

The mark never falls. Once 17 words have been touched, that is the worst case seen, whatever happens afterwards. That is what makes it useful: run the program through its hardest work, then read the number once.

total RAM               8192 bytes
.data and .bss           548 bytes
worst stack seen          68 bytes
left for heap and peaks 7576 bytes

What you learned

• Flash and RAM are two separate budgets, and RAM is the one that usually runs out first
• .text and .rodata stay in flash, .bss costs RAM only, and .data costs both
• A zero-filled array is free in flash; giving it any other starting value is not
• size weighs the piles, and nm names what is in them, with capitals for public symbols
• A linker script says what memory exists and where each section goes
• AT gives .data a run address in RAM and a load address in flash, and start-up closes the gap
• main runs fourth, after the core has read the vector table and start-up has fixed RAM
• A global stuck at a repeating pattern such as 0xA5A5A5A5 points at start-up, not at your logic
• A map file names every section and symbol with its address, and unexplained gaps are alignment
• The stack is in no section, so paint free RAM and count what survives

Practice

Interview corner

Next, Volume 10 stays at this level and goes one step closer to the hardware. Peripheral registers: what they really are, why volatile is not optional, and how to set one bit without disturbing the other thirty-one.

Key words from this volume

Every word below has a plain-English entry in the glossary.

• Flash memory
• SRAM
• Section
• .text
• .rodata
• .data
• .bss
• Symbol
• Padding
• Alignment
• Stack
• Heap
• Linker
• Linker script
• Memory map
• Run address (VMA)
• Load address (LMA)
• Reset handler
• Vector table
• Start-up code
• Map file
• Object file
• High-water mark