Syntax

               .global symbol₁[, ... ,symbol_n]

              .def symbol₁[, ... ,symbol_n]

              .ref symbol₁[, ... ,symbol_n]

Description

Three directives identify global symbols that are defined externally or can be referenced externally:

The .def directive identifies a symbol that is defined in the current module and can be accessed by other files. The assembler places this symbol in the symbol table.

The .ref directive identifies a symbol that is used in the current module but is defined in another module. The linker resolves this symbol's definition at link time.

The .global directive acts as a .ref or a .def, as needed.

A global symbol is defined in the same manner as any other symbol; that is, it appears as a label or is defined by the .set, .equ, .bss or .usect directive. If a global symbol is defined more than once, the linker issues a multiple-definition error. (The assembler can provide a similar multiple-definition error for local symbols.) The .ref directive always creates a symbol table entry for a symbol, whether the module uses the symbol or not; .global, however, creates an entry only if the module actually uses the symbol.

A symbol can be declared global for either of two reasons:

• If the symbol is not defined in the current module (which includes macro, copy, and include files), the .global or .ref directive tells the assembler that the symbol is defined in an external module. This prevents the assembler from issuing an unresolved reference error. At link time, the linker looks for the symbol's definition in other modules.
• If the symbol is defined in the current module, the .global or .def directive declares that the symbol and its definition can be used externally by other modules. These types of references are resolved at link time.

Example

This example shows four files. The file1.lst and file2.lst refer to each other for all symbols used; file3.lst and file4.lst are similarly related.

The file1.lst and file3.lst files are equivalent. Both files define the symbol INIT and make it available to other modules; both files use the external symbols X, Y, and Z. Also, file1.lst uses the .global directive to identify these global symbols; file3.lst uses .ref and .def to identify the symbols.

The file2.lst and file4.lst files are equivalent. Both files define the symbols X, Y, and Z and make them available to other modules; both files use the external symbol INIT. Also, file2.lst uses the .global directive to identify these global symbols; file4.lst uses .ref and .def to identify the symbols.

file1.lst

       1              ; Global symbol defined in this file
       2                     .global INIT
       3              ; Global symbols defined in file2.lst
       4                     .global X, Y, Z
       5 000000       INIT:
       6 000000 0956         ADD    ACC, #56h
       7                   
       8 000001 0000!        .word   X
       9              ;      .
      10              ;      .
      11              ;      .
      12                     .end

file2.lst

       1              ; Global symbols defined in this file
       2                       .global X, Y, Z
       3              ; Global symbol defined in file1.lst
       4                       .global INIT
       5        0001  X:       .set    1
       6        0002  Y:       .set    2
       7        0003  Z:       .set    3
       8 000000 0000!          .word   INIT
       9              ;        .
      10              ;        .
      11              ;        .
      12                       .end

file3.lst

       1              ; Global symbol defined in this file
       2                    .def    INIT
       3              ; Global symbols defined in file4.lst
       4                    .ref    X, Y, Z
       5 000000       INIT:
       6 000000 0956        ADD     ACC, #56h
       7                
       8 000001 0000!       .word   X
       9              ;     .
      10              ;     .
      11              ;     .
      12                    .end

file4.lst

       1              ; Global symbols defined in this file
       2                       .def    X, Y, Z
       3              ; Global symbol defined in file3.lst
       4                       .ref    INIT
       5        0001  X:       .set    1
       6        0002  Y:       .set    2
       7        0003  Z:       .set    3
       8 000000 0000!          .word   INIT
       9              ;        .
      10              ;        .
      11              ;        .
      12                       .end