Legacy function __user_initial_stackheap()

ARM Compiler toolchain v5.02 for µVision ARM C and C++ Libraries and Floating-Point Support Reference

Home > The C and C++ libraries > Legacy function __user_initial_stackheap()

Legacy function `__user_initial_stackheap()`

If you have legacy source code you might see __user_initial_stackheap(), from rt_misc.h. This is an old function that is only supported for backwards compatibility with legacy source code. The modern equivalent is __user_setup_stackheap().

Syntax

extern __value_in_regs struct __initial_stackheap __user_initial_stackheap(unsigned R0, unsigned SP, unsigned R2, unsigned SL);

Usage

__user_initial_stackheap() returns the:

heap base in r0
stack base in r1, that is, the highest address in the stack region
heap limit in r2.

If this function is reimplemented, it must:

use no more than 88 bytes of stack
not corrupt registers other than r12 (ip)
maintain eight-byte alignment of the heap.

The value of sp (r13) at the time __main() is called is passed as an argument in r1. The default implementation of __user_initial_stackheap(), using the semihosting SYS_HEAPINFO, is given by the library in module sys_stackheap.o.

To create a version of __user_initial_stackheap() that inherits sp from the execution environment and does not have a heap, set r0 and r2 to the value of r1 and return.

There is no limit to the size of the stack. However, if the heap region grows into the stack, malloc() attempts to detect the overlapping memory and fails the new memory allocation request.

The definition of __initial_stackheap in rt_misc.h is:

struct __initial_stackheap {
    unsigned heap_base; /* low-address end of initial heap */
    unsigned stack_base; /* high-address end of initial stack */
    unsigned heap_limit; /* high-address end of initial heap */
    unsigned stack_limit; /* unused */
};

Note

The value of stack_base is 0x1 greater than the highest address used by the stack because a full-descending stack is used.

Legacy function __user_initial_stackheap()