<util/ram-usage.h>: Determine dynamic RAM usage

Functions
uint16_t	_get_ram_unused (void)

Symbols
	__heap_start
	__ram_color_end
	__ram_color_value

Detailed Description

#include <util/ram-usage.h>

This header provides a single function, _get_ram_unused(), that can be used during development to get a rough estimate of how much RAM might be used by an application. This works as follows:

1. The startup code paints the RAM location with a specific value. This happens in .init3, and only when _get_ram_unused() is actually used. The coloring extends from __heap_start (which is the RAM location right after static storage) up to and including RAMEND as defined in <avr/io.h>.
2. The application calls _get_ram_unused() and determines how much of the colored bytes are still intact. This can be used to calculate a lower bound of how much RAM is used by the application.

Since

AVR-LibC v2.3

Function Documentation

_get_ram_unused()

uint16_t _get_ram_unused ( void  )

inline

Determines how much of the initial RAM coloring is still intact. It can be used to get a lower bound of how much RAM might be used by an application.

The function is written in such a way that it has a small register foot print, so that it is not a big issue to call it in an ISR. Though that's not required for the intended purpose: _get_ram_unused() can simply be called after some time has elapsed and enough ISRs and other functions have been invoked.

Returns

The value returned by _get_ram_unused() is an upper bound for how much bytes of RAM are still unused at the time of invocation.
The return value will never increase with time (except for very rare occasions where __ram_color_value is written to the top of the stack).

Limitations

• The start of the coloring is hard coded as __heap_start, which is the beginning of the RAM area after static storage.
• The algorithm assumes that the stack is located after static storage and grows downwards towards __heap_start.
• The current implementation is not compatible with malloc et al. (alloca() is no problem though, since it allocates on the stack.)

Variable Documentation

__heap_start

__heap_start

extern

A symbol defined in the default linker script. It points one byte past static storage (.data, .bss, .noinit).

__ram_color_end

__ram_color_end

A weak symbol that defaults to RAMEND + 1. It points one byte past the last location that is colored by the startup code. It can be adjusted by say

avr-gcc ... -Wl,-defsym,__ram_color_end=<value>

in the link command, or by means of a global inline assembly statement like:

__asm (".global __ram_color_end\n"
       "__ram_color_end = <value>");

__ram_color_value

__ram_color_value

A weak symbol that defaults to 0xaa. It represents the "color" that's being used by the startup code to paint the RAM, and the value that _get_ram_unused() will check against. It can be adjusted by say

avr-gcc ... -Wl,-defsym,__ram_color_value=<value>

in the link command.