UL80(1)

NAME
ul80 - Microsoft LINK-80 compatible linker for 8080/Z80

SYNOPSIS
ul80 [-v] [-o output.com] [-x] [--prl] [-s] [-S file.sym] [-p origin] file.rel [file.rel]...

DESCRIPTION
ul80 is a Microsoft LINK-80 compatible linker that combines relocatable object files (.REL) produced by um80(1) into executable CP/M .COM files.

The linker resolves external references, allocates memory for code, data, and COMMON blocks, and produces a binary executable suitable for running under CP/M or a CP/M emulator.

OPTIONS

-v, --version
    Display version information and exit.

-o output.com
    Specify the output file name. Default is the first input file name with a .com extension.

-x  Output Intel HEX format instead of binary. Useful for EPROM programmers.

--prl
    Output MP/M .PRL (Page Relocatable) format instead of binary .COM. PRL files can be loaded at any page boundary in memory, useful for MP/M's multi-user environment. The output file contains a 256-byte header with code/BSS sizes, the code section, and a relocation bitmap that marks which bytes need page adjustment when loaded at a different address.

-s  Generate a symbol file (.SYM) with an auto-generated name based on the output file. The symbol file contains all PUBLIC symbols and their final relocated addresses.

-S file.sym
    Generate a symbol file with the specified name. Use this with the assembler's -g option to generate a complete symbol file including all labels:
    um80 -g program.mac
    ul80 -S program.sym program.rel

-p origin
    Set the program origin address. Default is 100 (hex), the standard CP/M transient program load address. Values are interpreted as hexadecimal by default (e.g., E000), or can use prefixes: 0x for hex, 0o for octal.

MEMORY LAYOUT
The linker arranges memory as follows:

1.  Code segment (CSEG) starting at the origin address

2.  Data segment (DSEG) immediately following code

3.  COMMON blocks following data

The first three bytes of a CP/M .COM file are typically a JMP instruction to the actual entry point, so code starts at origin + 3 (0x103 by default).

LINKING PROCESS

1.  Load all input .REL files

2.  Resolve external references between modules

3.  Allocate final addresses for all segments

4.  Perform address fixups for relocatable references

5.  Write output file

If an external symbol is not found in any loaded module, the linker reports an error. The linker searches library files (.LIB) for undefined symbols when specified on the command line.

EXAMPLES

Link a single module:
    ul80 program.rel

Link multiple modules:
    ul80 -o app.com main.rel io.rel util.rel

Generate symbol file:
    ul80 -s program.rel

Set custom origin (bare hex):
    ul80 -p E000 program.rel

Generate named symbol file:
    ul80 -S program.sym program.rel

Output Intel HEX:
    ul80 -x -o program.hex program.rel

Output MP/M PRL:
    ul80 --prl program.rel

Link with library:
    ul80 -o program.com main.rel mylib.lib

EXIT STATUS

0   Linking successful.

1   Linking failed due to errors (undefined symbols, etc.).

FILES

input.rel
    Relocatable object file (from um80).

input.lib
    Library file (from ulib80).

output.com
    CP/M executable binary.

output.hex
    Intel HEX format (with -x option).

output.prl
    MP/M Page Relocatable format (with --prl option).

output.sym
    Symbol file (with -s option).

SYMBOL FILE FORMAT
The symbol file contains one line per symbol:

    SYMBOL_NAME  XXXX

Where XXXX is the 16-bit hexadecimal address of the symbol.

SEE ALSO
um80(1), ulib80(1), ucref80(1), ud80(1)

The original Microsoft LINK-80 manual is available at docs/external/l80.pdf

COMPATIBILITY
ul80 is compatible with Microsoft LINK-80 (L80). The .REL file format is binary-compatible, allowing object files created by the original M80 to be linked with ul80, and vice versa.

NOTES

•   Libraries are searched in the order specified on the command line.

•   Only modules containing symbols that satisfy undefined references are included from libraries.

•   COMMON blocks with the same name in different modules share storage; the largest size requested is allocated.

AUTHOR
um80 project contributors.