RealView® Compilation Tools Compiler and Libraries Guide 5.3.3. Building an application for a nonsemihosted environment

5.3.3. Building an application for a nonsemihosted environment

If you do not want to use any semihosting functionality, you must ensure that either no calls are made to any function that uses semihosting or that such functions are replaced by your own nonsemihosted functions.

To build an application that does not use semihosting functionality:

Create the source files to implement the target-dependent features (functions that use the semihosting SWI or that depend on the target memory map).
Add the __use_no_semihosting_swi guard to the source (see Avoiding the semihosting SWI).
Link the new objects with your application.
Use the new configuration when creating the target-dependent application.

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

If you are building an application for a different execution environment, you can re-implement the target-dependent functions, that is, those functions that use the semihosting SWI or that depend on the target memory map. There are no target-dependent functions in the C++ library, though some C++ functions use underlying C library functions that are target-dependent.

The functions that you might have to re-implement are described in:

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

See RealView Compilation Tools v2.2 Developer Guide for examples of creating embedded applications.

C++ exceptions in a nonsemihosted 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 nonsemihosted environment, you must provide an alternative implementation of abort().

Overview of semihosting dependencies

Table 5.3 shows those functions that depend directly on semihosting SWIs.

Table 5.3. Direct semihosting SWI dependencies

Function	Description
`__user_initial_stackheap()`	See Tailoring the runtime memory model. You must re-implement 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 5.4 shows those functions that depend indirectly on one or more of the functions listed in Table 5.3.

Table 5.4. Indirect semihosting SWI 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`	Re-implementing the printf family. See Tailoring the input/output functions.
`__backspace()` `fgetc()` `__stdin`	Re-implementing the scanf family. See Tailoring the input/output functions.
`fwrite()` `fputs()` `puts()` `fread()` `fgets()` `gets()` `ferror()`	Re-implementing the stream output family. See Tailoring the input/output functions.

Avoiding the semihosting SWI

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. The C library contains compiler helper functions and initialization code. Some C library functions use the semihosting SWI.

To avoid using the semihosting SWI, do either of the following:

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

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

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

You need to define this symbol once only in your application. The symbol has no effect except to cause a link-time error if a function that uses the semihosting SWI is included from the library. The linker error message is:

Error: L6200E: Symbol __semihosting_swi_guard multiply defined (by use_semi.o and use_no_semi.o).

Link with --verbose --errors out.txt, and then search the text file for the entry __semihosting_swi_guard. You must provide your own implementations of any functions you identify.

See the section on avoiding C library semihosting in RealView Compilation Tools v2.2 Developer Guide for more details.

API definitions

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

Table 5.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.
`locale` `CTYPE`	Defines the character properties for the local alphabet. See Tailoring locale and CTYPE.
`rt_sys.h`	A C header file describing all the functions whose default (semihosted) implementations use the semihosting SWI.
`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 re-implementing 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 Limited. You must not overwrite the supplied library files. Place your re-implemented functions in a separate library.

Copyright © 2002-2005 ARM Limited. All rights reserved.	ARM DUI 0205F
Non-Confidential
PDF version