RealView Compilation Tools Libraries and Floating Point Support Guide: 2.3.3. Building an application for a non semihosting environment

2.3.3. Building an application for a non semihosting environment

If you do not want to use any semihosting functionality, you must remove all calls to semihosting functions or reimplement them with non semihosting functions.

To build an application that does not use semihosting functionality:

Create the source files to implement the target-dependent features. For example, functions that use the semihosting calls or that depend on the target memory map.
Add the __use_no_semihosting symbol to the source. See Avoiding semihosting.
Link the new objects with your application.
Use the new configuration when creating the target-dependent application.

You must reimplement functions that the C library uses to insulate itself from target dependencies. For example, if you use printf() you must reimplement fputc(). If you do not use the higher-level input/output functions like printf(), you do not have to reimplement the lower-level functions like fputc().

If you are building an application for a different execution environment, you can reimplement the target-dependent functions. For example, those functions that use semihosting calls or depend on the target memory map. There are no target-dependent functions in the C++ library, although some C++ functions use underlying C library functions that are target-dependent.

Examples of embedded applications that do not use a hosted environment are included in the main examples directory, in ...\emb_sw_dev.

See the Developer Guide for examples of creating embedded applications.

C++ exceptions in a non semihosted environment

The default C++ std::terminate() handler is required by the C++ Standard to call abort(). The default C library implementation of abort() uses functions that require semihosting support. Therefore, if you use exceptions in a non semihosted environment, you must provide an alternative implementation of abort().

Overview of semihosting dependencies

Table 2.3 shows the functions that depend directly on semihosting.

Table 2.3. Direct semihosting dependencies

Function	Description
__user_initial_stackheap()	See Tailoring the runtime memory model. You might have to reimplement this function if you are using scatter-loading.
_sys_exit() _ttywrch()	See Tailoring error signaling, error handling, and program exit.
_sys_command_string(), _sys_close(), _sys_ensure(), _sys_iserror(), _sys_istty(), _sys_flen(), _sys_open(), _sys_read(), _sys_seek(), _sys_write(), _sys_tmpnam()	See Tailoring the input/output functions.
clock(), _clock_init(), remove(), rename(), system(), time()	See Tailoring other C library functions.

Table 2.4 shows those functions that depend indirectly on one or more of the functions listed in Table 2.3.

Table 2.4. Indirect semihosting dependencies

Function	Usage
__raise()	Catch, handle, or diagnose C library exceptions, without C signal support. See Tailoring error signaling, error handling, and program exit.
__default_signal_handler()	Catch, handle, or diagnose C library exceptions, with C signal support. See Tailoring error signaling, error handling, and program exit.
__Heap_Initialize()	Choosing or redefining memory allocation. See Tailoring storage management.
ferror(), fputc(), __stdout	Reimplementing the printf family. See Tailoring the input/output functions.
__backspace(), fgetc(), __stdin	Reimplementing the scanf family. See Tailoring the input/output functions.
fwrite(), fputs(), puts(),fread(), fgets(), gets(), ferror()	Reimplementing the stream output family. See Tailoring the input/output functions.

Avoiding semihosting

If you write an application in C, you must link it with the C library even if it makes no direct use of C library functions. This is because the compiler might implicitly call functions in the C library, and because the C library also contains initialization code. Some C library functions use semihosting.

To avoid using semihosting, do either of the following:

reimplement the functions in your own application
write the application so that it does not call any semihosted function.

To guarantee that no functions using semihosting are included in your application, use either:

IMPORT __use_no_semihosting from assembly language
#pragma import(__use_no_semihosting) from C.

Note

IMPORT __use_no_semihosting is only required to be added to a single assembly source file. Similarly, #pragma import(__use_no_semihosting) is only required to be added to a single C source file. It is not necessary to add these inserts to every single source file.

If you include a library function that uses semihosting and also reference __use_no_semihosting, the library detects the conflicting symbols and the linker reports an error. To find out which objects are using semihosting, link with --verbose --list=out.txt, search the output for the symbol, and find out what object referenced it. See --list=file and --verbose in the Linker Reference Guide for more information.

API definitions

In addition to the semihosted functions listed in Table 2.3 and Table 2.4, Table 2.5 shows functions and files that might be useful when building for a different environment.

Table 2.5. Published API definitions

File or function	Description
__main() __rt_entry()	Initializes the runtime environment and executes the user application.
__rt_lib_init(), __rt_exit(), __rt_lib_shutdown()	Initializes or finalizes the runtime library.
LC_CTYPE locale	Defines the character properties for the local alphabet. See Tailoring locale and CTYPE using assembler macros.
`rt_sys.h`	A C header file describing all the functions whose default (semihosted) implementations use semihosting calls.
`rt_heap.h`	A C header file describing the storage management abstract data type.
`rt_locale.h`	A C header file describing the five locale category filing systems, and defining some macros that are useful for describing the contents of locale categories.
`rt_misc.h`	A C header file describing miscellaneous unrelated public interfaces to the C library.
`rt_memory.s`	An empty, but commented, prototype implementation of the memory model. See Writing your own memory model for a description of this file.

If you are reimplementing a function that exists in the standard ARM library, the linker uses an object or library from your project rather than the standard ARM library. Any library you add to a project does not have to follow the ARM library naming convention.

Caution

Do not replace or delete libraries supplied by ARM. You must not overwrite the supplied library files. Place your reimplemented functions in separate object files or libraries instead.

Copyright © 2007-2010 ARM. All rights reserved.	ARM DUI 0349C
Non-Confidential	ID101213
PDF version