User manual

ST Assembler-Linker ST assembler
Doc ID 11392 Rev 4 21/89
4.3.4 Label scope
Often, in multi-module programs, a piece of code needs to refer to a label that is actually
defined in another module. To do this, the module that exports the label must declare it
PUBLIC, and the module which imports the label must declare it EXTERN. The two
directives EXTERN and PUBLIC go together as a pair.
Most labels in a program are of no interest for other pieces of the program, these are known
as 'internal' labels since they are only used in the module where they are defined. Labels
are 'internal' by default.
Here are two incomplete example modules that pass labels between them:
module 1
EXTERN _sig1.w ; import _sig1
EXTERN _sig2.w ; import _sig2
PUBLIC _handlers ; export _handlers
segment byte ‘P’
_handlers: ; define _handlers
jp _sig1 ; refer to _sig1
jp _sig2 ; refer to _sig2
end
module 2
EXTERN _handlers.w ; import _handlers (addr. is a word)
PUBLIC _sig2 ; export _sig2
segment byte ‘P’
_sig2: ; define _sig2
...
call _handlers ; refer to _handlers
...
ret
end
As you can see, module 1 refers to the '_sig2' subroutine which is defined in module 2. Note
that when module 1 refers to the '_sig2' label in an EXTERN directive it specifies a WORD
size with the '.w' suffix. Because the assembler cannot look up the definition of '_sig2' it has
to be told its address size explicitly. It doesn't need to be told relativity: all external labels
are assumed to be relative.
Absolute labels declared between modules should be defined in an INCLUDE file that is
called by all modules in the program; this idea of using INCLUDE files is very important
since it can reduce the number of PUBLIC symbols, and therefore the link time, significantly.
Lines in the source code listing which refer to external labels are marked with an X and
given 'empty' values for the linker to fill.
As a short cut, labels may be declared as PUBLIC by preceding them with a '.' at their
definition. If this is done the label name need not be given in a PUBLIC directive. For
example, the following code fragment declares the label 'lab4' as PUBLIC automatically:
lab3 ld A,#0
ret
.lab4 nop
ret