You copied the Doc URL to your clipboard.

Placing the stack and heap with a scatter file

The Arm® C library provides multiple implementations of the function __user_setup_stackheap(), and can select the correct one for you automatically from information that is given in a scatter file.


  • If you re-implement __user_setup_stackheap(), your version does not get invoked when stack and heap are defined in a scatter file.
  • You might have to update your startup code to use the correct initial stack pointer. Some processors, such as the Cortex®-M3 processor, require that you place the initial stack pointer in the vector table. See Stack and heap configuration in AN179 - Cortex®-M3 Embedded Software Development for more details.
  • You must ensure correct alignment of the stack and heap:
    • In AArch32 state, the stack and heap must be 8-byte aligned.
    • In AArch64 state, the stack and heap must be 16-byte aligned.


  1. Define two special execution regions in your scatter file that are named ARM_LIB_HEAP and ARM_LIB_STACK.
  2. Assign the EMPTY attribute to both regions.
    Because the stack and heap are in separate regions, the library selects the non-default implementation of __user_setup_stackheap() that uses the value of the symbols:
    • Image$$ARM_LIB_STACK$$ZI$$Base.
    • Image$$ARM_LIB_STACK$$ZI$$Limit.
    • Image$$ARM_LIB_HEAP$$ZI$$Base.
    • Image$$ARM_LIB_HEAP$$ZI$$Limit.

    You can specify only one ARM_LIB_STACK or ARM_LIB_HEAP region, and you must allocate a size.

        ARM_LIB_STACK 0x40000 EMPTY -0x20000  ; Stack region growing down
        { }
        ARM_LIB_HEAP 0x28000000 EMPTY 0x80000 ; Heap region growing up
        { }
  3. Alternatively, define a single execution region that is named ARM_LIB_STACKHEAP to use a combined stack and heap region. Assign the EMPTY attribute to the region.
    Because the stack and heap are in the same region, __user_setup_stackheap() uses the value of the symbols Image$$ARM_LIB_STACKHEAP$$ZI$$Base and Image$$ARM_LIB_STACKHEAP$$ZI$$Limit.