Linkstor80 1.1.0

Nestor80 linker library

Nestor80 is a Z80, R800 and Z280 assembler almost fully compatible with Microsoft's Macro80 at the source code level. It can produce absolute and relocatable files; relocatable files can be linked using the Linkstor80 package. Linkstor80 is the linker used to combine together multiple relocatable files into an absolute binary file.

Linkstor80 is published as a standalone command line application, LK80 (or LK80.exe). Additionally, you can use this NuGet package to link relocatable programmatically. The process is as follows:

1. Use Nestor80 (the N80 or N80.exe command line application, or the Nestor80 assembler NuGet package) to generate one or more relocatable files.

2. Create a an array of instances of ILinkingSequenceItem. The classes tha implement this interface are:

   • RelocatableFileReference - refers to a relocatable file to process.
   • SetCodeBeforeDataMode - instructs the linker to switch to "code before data" linking mode (places the code segment before the data segment for each program).
   • SetDataBeforeCodeMode - instructs the linker to place the "data before code" linking mode (places the data segment before the code segment for each program).
   • SetCodeSegmentAddress - instructs the linker to use the provided the supplied address as the next code segment address (in "separate code and data" linking mode) or as the next program address (in the other linking modes).
   • SetDataSegmentAddress - instructs the linker to switch to "separate code and data" linking mode (all code segments from all programs are linked together, and same for the data segments) and use the provided the supplied address as the next data segment address.
   • AlignCodeSegmentAddress - instructs the linker to align the code segment of the next program (or the entire program, depending on the linking mode) to an address that is a multiple of the supplied value.
   • AlignDataSegmentAddress - instructs the linker to align the data segment of the next program to an address that is a multiple of the supplied value (can be used in "separate code and data" linking mode only).

These classes mimic the command line arguments of the LK80 application, you can get a reference by running LK80 --help or by looking at the help text in the LK80 source code.

3. Create an instance of LinkingConfiguration and set its properties as appropriate. At the very least you should set LinkingSequenceItems (with the array created in the previous step) and OpenFile (a callback to open the involved relocatable files).

4. Run RelocatableFilesProcessor.Link, passing the instance of LinkingConfiguration and an open writable stream for the binary file to generate. The items in LinkingSequenceItems will be processed in the order in which they are found, and the output will be an instance of LinkingResult, where you can check if there was any error, and obtain information about the generated programs (as instances of ProgramData), for example the public symbols with their absolute addresses.

You can take a look at the source of the LK80 tool for a real life example. See also:

• Nestor80 repository
• Language reference
• Writing relocatable code
• Relocatable file format reference
• Z280 support
• SDCC relocatable file format support