Symbol control directives

In this section:

Syntax

EXTERN symbol [ ,symbol ] …

EXTWEAK symbol [ ,symbol ] …

IMPORT symbol [ ,symbol ] …

PUBLIC symbol [ ,symbol ] …

PUBWEAK symbol [ ,symbol ] …

REQUIRE symbol

Parameters

symbol

Symbol to be imported or exported.

Description

These directives control how symbols are shared between modules:

Directive	Description
`EXTERN`, `IMPORT`	Imports an external symbol.
`EXTWEAK`	Imports an external symbol. The symbol can be undefined.
`OVERLAY`	Recognized but ignored.
`PUBLIC`	Exports symbols to other modules.
`PUBWEAK`	Exports symbols to other modules, multiple definitions allowed.
`REQUIRE`	Forces a symbol to be referenced.

Table 124. Symbol control directives

Exporting symbols to other modules

Use PUBLIC to make one or more symbols available to other modules. Symbols defined PUBLIC can be relocatable or absolute, and can also be used in expressions (with the same rules as for other symbols).

The PUBLIC directive always exports full 32-bit values, which makes it feasible to use global 32-bit constants also in assemblers for 8-bit and 16-bit processors. With the LOW, HIGH, >>, and << operators, any part of such a constant can be loaded in an 8-bit or 16-bit register or word.

There can be any number of PUBLIC-defined symbols in a module.

Exporting symbols with multiple definitions to other modules

PUBWEAK is similar to PUBLIC except that it allows the same symbol to be defined in more than one module. Only one of those definitions is used by the linker. If a module containing a PUBLIC definition of a symbol is linked with one or more modules containing PUBWEAK definitions of the same symbol, the linker uses the PUBLIC definition.

Note

Library modules are only linked if a reference to a symbol in that module is made, and that symbol was not already linked. During the module selection phase, no distinction is made between PUBLIC and PUBWEAK definitions. This means that to ensure that the module containing the PUBLIC definition is selected, you should link it before the other modules, or make sure that a reference is made to some other PUBLIC symbol in that module.

Importing symbols

Use EXTERN or IMPORT to import an untyped external symbol.

The REQUIRE directive marks a symbol as referenced. This is useful if the section containing the symbol must be loaded even if the code is not referenced.

Example

The following example defines a subroutine to print an error message, and exports the entry address err so that it can be called from other modules. Because the message is enclosed in double quotes, the string will be followed by a zero byte.

It defines print as an external routine—the address is resolved at link time.

            name    errorMessage
            extern  print
            public  err
            rseg    CODE:CODE

err         jal     a0, print
            dc8     "** Error **"
            ret

            end

IAR Embedded Workbench for RISC-V 3.40