You copied the Doc URL to your clipboard.

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.

Note

Arm recommends not using __user_initial_stackheap() in new code. Instead, use its modern equivalent, __user_setup_stackheap().

Syntax

For AArch32 targets:

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

For AArch64 targets:

extern __attribute__((value_in_regs)) struct __initial_stackheap __user_initial_stackheap(unsigned long R0, unsigned long SP, unsigned long R2, unsigned long 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) when targeting AArch32.
Not corrupt registers other than r16 (ip0) and r17 (ip1) when targeting AArch64.
Maintain 8-byte alignment of the heap when targeting AArch32.
Maintain 16-byte alignment of the heap when targeting AArch64.

When __user_initial_stackheap() is called, the argument in r1 is the value that sp had when __main() was called. 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, setr0 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.

For AArch32 targets, 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 */
};

For AArch64 targets, the definition of __initial_stackheap in rt_misc.h is:

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