rl_errarg. STMicroelectronics STxP70

Relocatable loader library

rl_errarg

Definition:

Arguments:

UM1237

Return the name of the symbol that could not be resolved

const char *rl_errarg(

rl_handle_t *handle);

Returns:

Description:

rl_errstr

Definition:

Arguments:

handle

The handle for the module.

The name of the symbol that could not be resolved.

If rl_errno() returns either RL_ERR_RELSYM or RL_ERR_SYM, the rl_errarg() function returns the name of the symbol that could not be resolved.

Return a string for an error code

const char *rl_errstr(

rl_handle_t *handle);

Returns:

Description:

handle

The handle for the module.

A string for the error code.

The rl_errstr() function returns a readable string for the error code reported by rl_errno()

. For example:

...

void *sym = rl_sym(handle, "symbol"); if (sym == NULL) fprintf(stderr, "failed: %s\n", rl_errstr(handle));

...

If symbol is not defined in the module referenced by handle then the following message is displayed: failed: symbol not found: symbol

156/166 8027948 Rev 15

UM1237 Relocatable loader library

9.5 Customization

The relocatable loader library defines a number of functions that it uses internally for providing services such as heap memory management and file access. To provide custom implementation of these functions, the application in the main module can override these functions.

Note:

These functions allocate free space for the load module image and for the handle objects: void *rl_malloc(int size); void *rl_memalign(int align, int size); void *rl_text_memalign(int align, int size); void *rl_data_memalign(int align, int size); void rl_free(void *ptr);

•

•

•

Where: rl_memalign

is valid only in RL_ONE_CHUNK_MODE rl_text_memalign

is valid only in RL_MULTIPLE_CHUNK_MODE for text segments rl_data_memalign

is valid only in RL_MULTIPLE_CHUNK_MODE for data segments

The default behavior for these functions is to call the standard C library functions malloc()

, memalign() and free() respectively.

If providing a custom implementation, override all three functions.

Note:

The rl_load_file() function uses these functions to open, read and close a file handle: void *rl_fopen(const char *f_name, const char *mode); int rl_fclose(void *file); int rl_fread(char *buffer, int eltsize, int nelts, void *file);

The default behavior for these functions is to call the standard C library functions fopen(), fread()

and fclose() respectively.

If providing a custom implementation, override all three functions and link them with the main program.

To build a relocatable library that can be loaded by the RL_LIB loader, additional compile time and link time options must be used.

The following is a simple example of building a hello world loadable module: stxp70cc -o rl_hello.o -fpic -Mgot=small -c rl_hello.c

stxp70cc -o rl_hello.rl --rlib rl_hello.o

Alternatively, the compile and link phases can be carried out with a single command: stxp70cc -o rl_hello.rl -fpic -Mgot=small --rlib rl_hello.c

To build a main module suitable for loading a relocatable library, specific link time options are required. No specific compile time option are required for the main module.

8027948 Rev 15 157/166

Relocatable loader library

9.6.1

Note:

UM1237

The following is an example of building a main module: stxp70cc -o prog.o prog.c

stxp70cc -o prog.exe --rmain prog.o

The compile and link phases can be carried out with a single command: stxp70cc -o prog.exe --rmain prog.c

Importing and exporting symbols

For the relocatable loader system to function, the main module (or a loaded module) must provide services to the other load modules. To avoid a load error when loading a module, it is usual for the referenced symbols to be linked into the main module.

When the services are present in a library, the main module imports the corresponding symbols at link time. However, to import symbols, the linker requires an import script.

•

•

stxp70-rltool generates a list of symbols in the form of an import or export script from the specified input files. Where, the input files are either load modules (relocatable libraries) or a text file containing a list of symbols:

An import script is generated from a list of symbols specified in the file symbol_list

(where, symbol_list must have only one symbol on each line), or from one or more load module files. In the latter case, the stxp70-rltool utility generates an import script from the set of symbols that the load modules require.

An export script can be generated to reduce the size of the dynamic symbol table in the main module or load modules. An export script is not mandatory as all global symbols are exported by default.

The export script defines the set of symbols (and only these) that must be exported to the other modules through the dynamic symbol table. These symbols are then accessible by the load time symbol binding process and by the calls to rl_sym() and rl_sym_rec()

.

This utility has both a generic driver stxp70-rltool as well as version specific commands to invoke it: stxp70v3-rltool and stxp70v4-rltool. All versions of the utility are documented in the STxP70 utilities reference manual (8210925).

stxp70v3-rltool and stxp70v4-rltool are identical in terms of options and arguments.

Using the relocatable loader import/export utility

This section provides some examples of using the relocatable loader import/export utility.

•

•

Two common scenarios where an import script might be generated are:

When the required services are well defined and a list of symbols can be passed to the

stxp70-rltool utility.

When the list of services is not defined but the load modules are available and can be passed to the stxp70-rltool utility. The stxp70-rltool utility generates an import script from the set of symbols that the load modules require.

The following command generates an import script from a list of symbols specified in the file prog_import.lst

(one symbol per line): stxp70-rltool -mcore=[stxp70v3|stxp70v4] -i -s -o prog_import.ld prog_import.lst

158/166 8027948 Rev 15

UM1237 Relocatable loader library

The following command generates an import script that the main module can load from a list of load modules, liba.rl and libb.rl: stxp70-rltool -mcore=[stxp70v3|stxp70v4] -i -o prog_import.ld liba.rl libb.rl

Use the import script to link the main module, for example: stxp70cc -o prog.exe --rmain object_files.o prog_import.ld

•

•

Two common scenarios where an export script might be generated are:

When an import script is required for the module, the export script can be generated at the same time. This is because the symbols to export are generally those that are imported.

For a load module that has a well known external interface, the export script can be generated from a list of symbols to export.

The following example shows how to generate an export script and import script for a list of modules that is then used when linking the main module. Only the symbols from liba.rl and libb.rl are imported into the main module and exported by it.

stxp70-rltool -mcore=[stxp70v3|stxp70v4] -i -e -o prog_import_export.ld liba.rl libb.rl

stxp70cc -o prog.exe --rmain object_files.o prog_import_export.ld

To generate an export script for a load module with a well defined interface specified in the file liba_export.lst (one symbol per line): stxp70-rltool -mcore=[stxp70v3|stxp70v4] -e -s -o liba_export.ld liba_export.lst

stxp70cc -o liba.rl --rlib *.o liba_export.ld

When compiling a load module with the -fpic -Mgot=small option, some overhead occurs in the generated code to access functions and data objects. Compiler options and

C language extensions can be used to reduce this overhead.

Relocatable libraries are not subject to symbol preemption, therefore, when generating position independent code, the -fvisibility=protected option can be used in addition to -fpic -Mgot. The -fvisibility=protected option enables the inlining of global functions and can be used as a default option for compiling relocatable libraries. For example: stxp70cc -o a.o -fpic -Mgot=small -fvisibility=protected a.c

In addition to this option, fine grain visibility can be specified with the

__attribute__((visibility(...))

GNU C extension at the source code level.

For example, if the external interface of a load module is well defined in a header file, the

__attribute__((visibility("protected"))

can be attached to each function of the external interface. To specify that all other defined functions are internal to the load module, on the command line, use the -fvisibility=hidden option. This combination of options optimize references from the same file to global objects that are not part of the interface.

To specify the visibility of each symbol externally with the given <file>, use the mvisibility-decl=<file>

option. In the case where the external services required by a module (default visibility) and the external services provided by the module (protected visibility) are known, all other functions or data objects can be declared as internal (hidden visibility). This option can be used to specify these visibility declarations. In this case, only

8027948 Rev 15 159/166

Relocatable loader library UM1237

the functions that are external have an associated overhead. The other internal functions have a very reduced overhead.

For a full inter-procedural optimization of the relocatable library, use the -ipa option. In this case, when combined with the declaration of external functions, the library is generated with a minimal overhead for the dynamic linking support.

For detailed information on the visibility specification, refer to the compiler options documentation and to the ELF System V Dynamic Linking ABI.

The debugging of dynamically loaded modules is possible in the same way as for System V dynamic shared objects. The main module debugging information loads at load time of the application. The load modules debugging information loads at load time of the load modules.

To update debugging information, the loader maintains a list of loaded modules together with their filenames (the file contains the debugging information) and the load address of the module. Each time a new module loads, the loader calls a specific function. The debugger has to set a breakpoint on this specific function and, when the breakpoint is hit, traverse the list to find new loaded modules and load the debugging information.

For the STxP70 toolset, the debugger implements the required mechanism for the automatic debugging of loaded modules.

To find the file that contains the debug information, the loader must know the path to the load module. This is automatic in the case of rl_load_file() as the filename is specified in the interface. For the rl_load_buffer() and rl_load_stream() functions, the user must set the filename with a call to the rl_set_file_name() function.

For example, the following code enables automatic debugging of a load module loaded with rl_load_buffer()

:

{

int status;

rl_handle_t *handle = rl_handle_new(rl_this(), 0);

if (handle == NULL) { /* error */ }

#ifdef DEBUG_ENABLED

rl_set_filename(handle, "path_to_the_file_for_the_module");

#endif

status = rl_load_buffer(handle, module_image);

}

if (status == -1) { /* error */ }

...

160/166 8027948 Rev 15

UM1237 Relocatable loader library

The action callbacks may be used with a profiling support library, or alternatively, a user defined package can be informed that a segment has just been loaded or is on the point of being unloaded by using the user action callback interface.

Below is an example that iterates over the segment list and declares the executable segments to a profiling support library on the loading/unloading of a module.

static int segment_profile(rl_handle_t *handle, rl_segment_info_t

*info,

{

rl_action_t action = *((rl_action_t *)cookie);

const char *file_name = handle_file_name(handle);

if (file_name != NULL && (info->seg_flags & RL_SEG_EXEC) {

if (action == RL_ACTION_LOAD) {

/* Call profiling interface for adding a code region. */

profiler_add_region(file_name, info->seg_addr, info-

>seg_size);

}

if (action == RL_ACTION_UNLOAD) {

/* Call profiling interface for removing a code region. */ info->seg_size);

}

}

}

return 0; static int module_profile(rl_handle_t *handle, rl_action_t action,

{

rl_foreach_segment(handle, segment_profile, (void *)&action);

}

return 0; int main()

{

...

if (rl_add_action_callback(RL_ACTION_ALL, module_profile,

NULL)==-1){

fprintf(stderr, "rl_add_Action_callback failed\n"); exit(1);

}

...

status = rl_load_file(handle, file_name);

...

}

return 0;

8027948 Rev 15 161/166

Relocatable loader library

9.9 Memory protection support

UM1237

When a new library segment has loaded into memory or is on the point of being unloaded from memory, a system library (or the user) can use the user-action callback interface to install a memory protection scheme.

To set user protection support, use the user-action callback, see

Section 9.8: Profiling support

.

A basic MUTEX implementation is provided in the STxP70 targeting of the pre-compiled

RL_LIB, delivered with the toolset. In addition, because there is no cache activated on the

STxP70, specific functions such as bsp_cache_purge_data and bsp_cache_invalidate_instruction (which respectively purge the data cache and handle instruction cache invalidation) are not implemented.

It is the programmer’s responsibility to implement those functions depending on the platform and STxP70 architecture used.

Table 32

provides details of the files’ location in the toolset

distribution.

Table 32.

RL_LIB source file location

Functionality Source file

STxP70 v3 MUTEX implementation

STxP70 v3 Cache management

STxP70 v4 MUTEX implementation

STxP70 v4 Cache management

<RL_LIB_root>/librl/config/stxp70v3/sys_mutex.[c|h]

<RL_LIB_root>/librl/config/stxp70v3/targ_elf.[c|h]

<RL_LIB_root>/librl/config/stxp70v4/sys_mutex.[c|h]

<RL_LIB_root>/librl/config/stxp70v4/targ_elf.[c|h]

162/166 8027948 Rev 15

UM1237 Compiler bugs

This chapter describes the different categories of compiler bugs and how they should be reported to STMicroelectronics.

10.1 Identifying a compiler bug

•

•

•

•

•

•

The following cases are compiler or toolset bugs: the compilation phase ends with an assertion message the compilation phase ends with a system error message (core dump, bus error) the compilation phase produces an output that cannot be assembled the compilation phase never ends, or at least does not end in a reasonable amount of time the compiler produces an error message for code that is valid input the compiler produces code that does not compute the expected results (but see

Section 10.1.2

)

•

The following case is possibly not a compiler or toolset bug.

The code is functional under a specific optimization level, but not under another. This may be due to an existing code bug that is only exposed by aggressive optimization.

10.2 Checks performed by user

•

•

•

•

•

The following checks should be performed on your code before reporting a bug: check that the code works correctly on at least one other compiler, on another host check that the code does not access out-of-bound memory check that the source code does not raise any warning when compiled with the -Wall option check that the source code does not make assumptions that may be false: specifically check restrict annotations, and optimization pragmas check that the code does not exercise language edges or does not violate language standards: an example of undefined behavior is to assume a specific behavior of shift operators when the shift amount is negative or bigger than the size of the type shifted

8027948 Rev 15 163/166

Compiler bugs UM1237

10.3 Workaround

The following can be carried out to temporarily work-around a compiler bug.

1.

Demote the optimization level to -O1 or -O0 when compiling the specific file creating the problem, either in category 1 or 2. (See

Section 10.1.1

and

Section 10.1.2

.)

2. Remove the optimization pragmas or restrict annotations.

3. Finally, check that you have an up-to-date compiler release.

10.4 Reporting a compiler bug

Carry out the following if a compiler bug is encountered.

1.

Obtain your compiler version by running the command stxp70cc -version.

2. If the compiler bug is in category 1 (see

Section 10.1.1

), prepare a pre-processed input

file that can reproduce the problem.

3. If the compiler bug is in category 2 (see

Section 10.1.2

), prepare a source set and

Makefile that can reproduce the problem.

4. Supply the full command line that generates the problem.

5. Report the result of the following command in the shell that you use: uname -a.

6. Prepare a description of the expected result and the actual result.

7. Report all the above information through your local ST Field Applications Engineer

(FAE).

Finally, when in doubt, it is preferable that a possible bug is reported than ignored.

10.5 Known bugs and limitations

Please refer to the Release note supplied with the toolset for an up-to-date list of bugs and limitations.

164/166 8027948 Rev 15

UM1237 Revision history

Table 33.

Document revision history

Date Revision Changes

Earlier revision history entries deleted as they are no longer pertinent.

05-Mar-2012

17-May-2012

11

12

Update for STxP70 toolset 2012.1.

Updated

Documentation suite on page 9

to remove references to STxP70 assembler documents. The assembler as is documented in the GNU documents, supplied with the toolset.

Updated

Inlining criteria on page 56

to change -INLINE:none to -INLINE:off.

Added the option -INLINE:size_static and updated the description of -

INLINE:all

in

Table 21 on page 56

.

Added

Inlining static functions on page 57

.

Update for STxP70 toolset 2012.1 patch 001.

Table 15: Code generation options on page 31

updated -mlib-short-double

and added -mlib-nofloat.

Table 19: C99 support in stxp70cc on page 42

updated throughout.

19-Sep-2012

28-Jan-2013

13

14

Update for STxP70 toolset 2012.2.

Updated

Table 6

and

Table 7

to add config options bypass and bhb.

Updated

Table 13

to add -o4 optimization option.

Updated

Table 14

, --deadcode and -f[no]unroll-loops options.

Updated

Table 15

to add -maggressive_unroll option.

Updated

Table 20

optimization levels.

Updated

Table 21

, -INLINE:size_static to add -o4 optimization level.

Added

Section 4.2: Loop unrolling on page 63

.

Updated

Table 27

, -IPA:mem_placement to include -o4 optimization level.

Updated

Section 6.4: Restrictions on page 112

.

Updated

Section 8.2.1: Compiler options on page 122

.

Update for STxP70 toolset 2012.2. Update 01.

Updated

rl_handle_new on page 145

to add mode argument.

Updated

rl_errno on page 154

to expand description of RL_ERR_MEM error code.

Updated

Section 9.5.1: Memory allocation on page 157

.

08-May-2013 15

Update for STxP70 toolset 2013.1.

Corrected syntax for FPx registers in

Chapter 6: GNU ASM on page 109

.

Added options to control warnings generated for -fpack-struct in

Table 12 on page 27

and updated description of -fpack-struct in

Table 15 on page 31

.

Updated the description of -f[no-]math-errno in

Table 15 on page 31

to

reflect its changed behavior in this toolset release.

Added GNU assembly parsing options at the end of

Table 15 on page 31

.

Added

Section 6.8: Parsing and optimization of GNU assembly statement on page 114

.

8027948 Rev 14 165/166

UM1237

Please Read Carefully:

Information in this document is provided solely in connection with ST products. STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, modifications or improvements, to this document, and the products and services described herein at any time, without notice.

All ST products are sold pursuant to ST’s terms and conditions of sale.

Purchasers are solely responsible for the choice, selection and use of the ST products and services described herein, and ST assumes no liability whatsoever relating to the choice, selection or use of the ST products and services described herein.

No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted under this document. If any part of this document refers to any third party products or services it shall not be deemed a license grant by ST for the use of such third party products or services, or any intellectual property contained therein or considered as a warranty covering the use in any manner whatsoever of such third party products or services or any intellectual property contained therein.

UNLESS OTHERWISE SET FORTH IN ST’S TERMS AND CONDITIONS OF SALE ST DISCLAIMS ANY EXPRESS OR IMPLIED

WARRANTY WITH RESPECT TO THE USE AND/OR SALE OF ST PRODUCTS INCLUDING WITHOUT LIMITATION IMPLIED

WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE (AND THEIR EQUIVALENTS UNDER THE LAWS

OF ANY JURISDICTION), OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.

ST PRODUCTS ARE NOT AUTHORIZED FOR USE IN WEAPONS. NOR ARE ST PRODUCTS DESIGNED OR AUTHORIZED FOR USE

IN: (A) SAFETY CRITICAL APPLICATIONS SUCH AS LIFE SUPPORTING, ACTIVE IMPLANTED DEVICES OR SYSTEMS WITH

PRODUCT FUNCTIONAL SAFETY REQUIREMENTS; (B) AERONAUTIC APPLICATIONS; (C) AUTOMOTIVE APPLICATIONS OR

ENVIRONMENTS, AND/OR (D) AEROSPACE APPLICATIONS OR ENVIRONMENTS. WHERE ST PRODUCTS ARE NOT DESIGNED

FOR SUCH USE, THE PURCHASER SHALL USE PRODUCTS AT PURCHASER’S SOLE RISK, EVEN IF ST HAS BEEN INFORMED IN

WRITING OF SUCH USAGE, UNLESS A PRODUCT IS EXPRESSLY DESIGNATED BY ST AS BEING INTENDED FOR “AUTOMOTIVE,

AUTOMOTIVE SAFETY OR MEDICAL” INDUSTRY DOMAINS ACCORDING TO ST PRODUCT DESIGN SPECIFICATIONS.

PRODUCTS FORMALLY ESCC, QML OR JAN QUALIFIED ARE DEEMED SUITABLE FOR USE IN AEROSPACE BY THE

CORRESPONDING GOVERNMENTAL AGENCY.

Resale of ST products with provisions different from the statements and/or technical features set forth in this document shall immediately void any warranty granted by ST for the ST product or service described herein and shall not create or extend in any manner whatsoever, any liability of ST.

ST and the ST logo are trademarks or registered trademarks of ST in various countries.

Information in this document supersedes and replaces all information previously supplied.

The ST logo is a registered trademark of STMicroelectronics. All other names are the property of their respective owners.

© 2013 STMicroelectronics - All rights reserved

STMicroelectronics group of companies

Australia - Belgium - Brazil - Canada - China - Czech Republic - Finland - France - Germany - Hong Kong - India - Israel - Italy - Japan -

Malaysia - Malta - Morocco - Philippines - Singapore - Spain - Sweden - Switzerland - United Kingdom - United States of America

www.st.com

166/166 8027948 Rev 15