4.2.2. 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 non-semihosted functions.

To build an application that does not use semihosting functionality:

  1. Create the source files to implement the target-dependent features.

  2. Add the __use_no_semihosting_swi guard to the source. See Avoiding the semihosting SWI.

  3. Link the new objects with your application.

  4. 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 (functions that use the semihosting SWI or that depend on the target memory map). There are no target-dependent functions in the C++ library.

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 install_directory\Examples\embedded\embed.

See the ADS Developer Guide for examples of creating applications for embedding into ROM.

Overview of semihosting dependencies

The functions shown in Table 4.2 depend directly on semihosting SWIs.

Table 4.2. Direct dependencies

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

The functions listed in Table 4.3 depend indirectly on one or more of the functions listed in Table 4.2.

Table 4.3. Indirect dependencies

FunctionWhere used
__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(), __stdoutRetargeting the printf family. See Tailoring the input/output functions.
__backspace(), fgetc(), __stdinRetargeting the scanf family. See Tailoring the input/output functions.
fwrite(), fputs(), puts(), fread(), fgets(), gets(), ferror()Retargeting 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.

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).

Use the linker symbol table and cross reference listings to identify functions you have called that directly, or indirectly, use semihosting. You can view this information by using the linker options -map, -xref, and -verbose. Remove, or re-implement semihosted functions, and rebuild the application.

API definitions

In addition to the semihosted functions listed in Table 4.2 and Table 4.3, the functions and files listed in Table 4.4 might be useful when building for a different environment.

Table 4.4. Published API definitions

File or functionDescription
__main() and __rt_entry()Initializes the runtime environment and executes the user application.
__rt_lib_init(), __rt_exit(), and __rt_lib_shutdown()Initializes or finalizes the runtime library.
locale() and CTYPEDefines the character properties for the local alphabet. See Tailoring locale and CTYPE.
rt_sys.hA C header file describing all the functions whose default (semihosted) implementations use the semihosting SWI.
rt_heap.hA C header file describing the storage management abstract data type.
rt_locale.hA 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.hA C header file describing miscellaneous unrelated public interfaces to the C library.
rt_memory.sAn 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. A library you add to a project does not have to follow the ARM naming convention for libraries.

Caution

Do not replace or delete libraries supplied by ARM. You must not overwrite the supplied library files. Place your re-implemented functions in a separate library.

Copyright © 1999-2001 ARM Limited. All rights reserved.ARM DUI 0067D
Non-Confidential