Keil Logo

Technical Support

On-Line Manuals

Libraries and Floating Point Support Guide

Preface The ARM C and C++ Libraries Mandatory linkage with the C library C and C++ runtime libraries Summary of the C and C++ runtime libraries Compliance with the Application Binary Interface ( Increasing portability of object files to other CL ARM C and C++ library directory structure Selection of ARM C and C++ library variants based Thumb C libraries C and C++ library features C++ and C libraries and the std namespace Multithreaded support in ARM C libraries ARM C libraries and multithreading ARM C libraries and reentrant functions ARM C libraries and thread-safe functions Use of static data in the C libraries Use of the __user_libspace static data area by the C library functions to access subsections of the _ Re-implementation of legacy function __user_libspa Management of locks in multithreaded applications How to ensure re-implemented mutex functions are c Using the ARM C library in a multithreaded environ Thread safety in the ARM C library Thread safety in the ARM C++ library The floating-point status word in a multithreaded Support for building an application with the C lib Using the C library with an application Using the C and C++ libraries with an application Using $Sub$$ to mix semihosted and nonsemihosted I Using the libraries in a nonsemihosting environmen C++ exceptions in a non-semihosting environment Direct semihosting C library function dependencies Indirect semihosting C library function dependenci C library API definitions for targeting a differen Support for building an application without the C Building an application without the C library Creating an application as bare machine C without Integer and floating-point compiler functions and Bare machine integer C Bare machine C with floating-point processing Customized C library startup code and access to C Using low-level functions when exploiting the C li Using high-level functions when exploiting the C l Using malloc() when exploiting the C library Tailoring the C library to a new execution environ Initialization of the execution environment and ex C++ initialization, construction and destruction Exceptions system initialization Emergency buffer memory for exceptions Library functions called from main() Program exit and the assert macro Assembler macros that tailor locale functions in t Link time selection of the locale subsystem in the Runtime selection of the locale subsystem in the C Definition of locale data blocks in the C library LC_CTYPE data block LC_COLLATE data block LC_MONETARY data block LC_NUMERIC data block LC_TIME data block Modification of C library functions for error sign Stack and heap memory allocation and the ARM C and Library heap usage requirements of the ARM C and C Choosing a heap implementation for memory allocati Stack pointer initialization and heap bounds Legacy support for __user_initial_stackheap() Avoiding the heap and heap-using library functions Tailoring input/output functions in the C and C++ Target dependencies on low-level functions in the The C library printf family of functions The C library scanf family of functions Redefining low-level library functions to enable d The C library functions fread(), fgets() and gets( Re-implementing __backspace() in the C library Re-implementing __backspacewc() in the C library Redefining target-dependent system I/O functions i Tailoring non-input/output C library functions Real-time integer division in the ARM libraries ISO C library implementation definition How the ARM C library fulfills ISO C specification mathlib error handling ISO-compliant implementation of signals supported ISO-compliant C library input/output characteristi Standard C++ library implementation definition C library functions and extensions Compiler generated and library-resident helper fun C and C++ library naming conventions Using macro__ARM_WCHAR_NO_IO to disable FILE decla Using library functions with execute-only memory The ARM C Micro-library Floating-point Support The C and C++ Library Functions reference Floating-point Support Functions Reference

Stack pointer initialization and heap bounds

1.11.3 Stack pointer initialization and heap bounds

The C library requires you to specify where the stack pointer begins. If you intend to use ARM library functions that use the heap, for example, malloc(), calloc(), or if you define argc and argv command-line arguments for main(), the C library also requires you to specify which region of memory the heap is initially expected to use.

You must always specify where the stack pointer begins. The initial stack pointer must be aligned to a multiple of eight bytes.
You might have to configure the heap if, for example:
  • You intend to use ARM library functions that use the heap, for example, malloc(), calloc().
  • You define argc and argv command-line arguments for main()
If you are using the C library's initialization code, use any of the following methods to configure the stack and heap:
  • Use the symbols __initial_sp, __heap_base, and __heap_limit.
  • Use a scatter file to define ARM_LIB_STACKHEAP, ARM_LIB_STACK, or ARM_LIB_HEAP regions.
  • Implement __user_setup_stackheap() or __user_initial_stackheap().

Note

The first two methods are the only methods that microlib supports for defining where the stack pointer starts and for defining the heap bounds.
If you are not using the C library's initialization code (see 1.7.1 Building an application without the C library), use the following method to configure the stack and heap:
  • Set up the stack pointer manually at your application's entry point.
  • Call _init_alloc() to set up an initial heap region, and implement __rt_heap_extend() if you need to add memory to it later.

Configuring the stack and heap with symbols

Define the symbol __initial_sp to point to the top of the stack.
If using the heap, also define symbols __heap_base and __heap_limit.
You can define these symbols in an assembly language file, or by using the embedded assembler in C.
For example:
__asm void dummy_function(void)
{
    EXPORT __initial_sp
    EXPORT __heap_base
    EXPORT __heap_limit
__initial_sp EQU STACK_BASE
__heap_base EQU HEAP_BASE
__heap_limit EQU (HEAP_BASE + HEAP_SIZE)
}
The constants STACK_BASE, HEAP_BASE and HEAP_SIZE can be defined in a header file, for example stack.h, as follows:
/* stack.h */
#define HEAP_BASE 0x20100000  /* Example memory addresses */
#define STACK_BASE 0x20200000
#define HEAP_SIZE ((STACK_BASE-HEAP_BASE)/2)
#define STACK_SIZE ((STACK_BASE-HEAP_BASE)/2)

Note

This method of specifying the initial stack pointer and heap bounds is supported by both the standard C library (standardlib) and the micro C library (microlib).

Configuring the stack and heap with a scatter file

In a scatter file, either:
  • Define ARM_LIB_STACK and ARM_LIB_HEAP regions.
    If you do not intend to use the heap, only define an ARM_LIB_STACK region.
  • Define an ARM_LIB_STACKHEAP region.
    If you define an ARM_LIB_STACKHEAP region, the stack starts at the top of that region. The heap starts at the bottom.

Configuring the stack and heap with __user_setup_stackheap() or __user_initial_stackheap()

Implement __user_setup_stackheap() to set up the stack pointer and return the bounds of the initial heap region.
If you are using legacy code that uses __user_initial_stackheap(), and you do not want to replace __user_initial_stackheap() with __user_setup_stackheap(), continue to use __user_initial_stackheap().

Note

ARM recommends that you switch to using __user_setup_stackheap() if you are still using __user_initial_stackheap(), unless your implementation of __user_initial_stackheap() is:
  • Specialized in some way such that it is complex enough to require its own temporary stack to run on before it has created the proper stack.
  • Has some user-specific special requirement that means it has to be implemented in C rather than in assembly language.

Configuring the heap from bare machine C using _init_alloc and __rt_heap_extend

If you are using a heap implementation from bare machine C (that is an application that does not define main() and does not initialize the C library) you must define the base and top of the heap as well as providing a heap extension function.
  1. Call _init_alloc(base, top) to define the base and top of the memory you want to manage as a heap.

    Note

    The parameters of _init_alloc(base, top) must be eight-byte aligned.
  2. Define the function unsigned __rt_heap_extend(unsigned size, void **block) to handle calls to extend the heap when it becomes full.

Stack and heap collision detection

By default, if memory allocated for the heap is destined to overlap with memory that lies in close proximity with the stack, the potential collision of heap and stack is automatically detected and the requested heap allocation fails. If you do not require this automatic collision detection, you can save a small amount of code size by disabling it with #pragma import __use_two_region_memory.

Note

The memory allocation functions (malloc(), realloc(), calloc(), posix_memalign()) attempt to detect allocations that collide with the current stack pointer. Such detection cannot be guaranteed to always be successful.
Although it is possible to automatically detect expansion of the heap into the stack, it is not possible to automatically detect expansion of the stack into heap memory.
For legacy purposes, it is possible for you to bypass all of these methods and behavior. You can do this by defining the following functions to perform your own stack and heap memory management:
  • __rt_stackheap_init()
  • __rt_heap_extend()

Extending heap size at runtime

To enable the heap to extend into areas of memory other than the region of memory that is specified when the program starts, you can redefine the function __user_heap_extend().
__user_heap_extend() returns blocks of memory for heap usage in extending the size of the heap.
Non-ConfidentialPDF file icon PDF versionARM DUI0378H
Copyright © 2007, 2008, 2011, 2012, 2014-2016 ARM. All rights reserved. 
  Arm logo
Important information

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies.

Change Settings

Privacy Policy Update

Arm’s Privacy Policy has been updated. By continuing to use our site, you consent to Arm’s Privacy Policy. Please review our Privacy Policy to learn more about our collection, use and transfers
of your data.