---------------------------------------------------------------------- Copyright (C) 1990 by Natrlich! This file is copyrighted! Refer to the documentation for details. ---------------------------------------------------------------------- NLINK65 --- an Atari 8-Bit Crosslinker for the Atari ST (et al.) v0.2 Preliminary manual for NLINK65 Copyright ½ 1990 by Natrlich! on sources, binaries and manuals ¯¯ Bang that Bit that doesn't Bang ®® I n t r o d u c t i o n NLINK65 is a portable (?) single-pass cross-linker that produces 6502 code. NLINK65 currently runs on the 68000 Atari under TOS. The linker produces two kinds of output, code that has to be run at a certain origin, or relocatable code. U s a g e nlink65 [-{tw}][-m[{1234}]][-s org][-b batch][-d libdir][-l lib] [-o .com] -t TOS switch, wait for a keypress after running -w The "what the ...." switch, even though errors occured an output file is generated. -m The relocatable switch. NLINK65 will create a relocatable Atari 8-Bit binary file for direct execution mm xxxx - Create a binary file that will be loaded to the default origin (or -s origin) and then moved to xxxx. (This is like assembling with an offset in MAC65). m[0] - create a binary with a mover that will be moved byte aligned to LOMEM. m1 - create a binary with a mover that will be moved page aligned to LOMEM (this produces a shorter binary) [see also -s] m2 xxxx - create a binary with a mover that will be moved to the contents of xxxx (hex) at runtime m3 xxxx - as m1 but page aligned [see also -s] -b Use batchfile to read in the names of [more] -d Supply alternate library directory (Default is taken from the Environment variable >LIBRARY<) -e Limit the number of errors: 0 = show all -i Append a RUNAD segment to the file, for DOS 2.X and family -o Specify alternate output file pathname (or filename) -s Supply origin to load to. This is used with relocatable and non relocatable code. Default = 2000 (hex). Page aligned code will load at xx00 - 3. -l Library to link with. STD.L65 is always tried to be linked. Libraries must be linked in order. STD.L65 is always last. f.e. foo.l65->bar.l65->std.l65 --> "-l foo -l bar" -x Create a file suitable for use as a boot disk. Just write the file sector per sector on a disc. 128 byte sectors only. (use -xx for a bootheader-less file) C r e a t i n g f i x e d o r i g i n f i l e s Type from a shell: nlink65 That will create a output file {object}.COM Transfer this file (with NASTY for instance) to a 8-Bit Atari computer and execute it there. C r e a t i n g r e l o c a t a b l e b i n a r i e s Type from a shell nlink65 -m That will create a output file {object}.com for execution on an 8-Bit Atari. See -m for more details. C r e a t i n g b o o t s e c t o r f i l e s Type from a shell nlink65 -x That will create a output file {object}.boo ready for transplan- tation on a 8-bit Atari SD diskette. If you have declared a label in your file with the name _boot_init, this will be entered into the bootheader as the init address. H o w t h e l i n k e r w o r k s The linker first reads in the source files (in order of appearance in the command line (batch file)) and tries to resolve all open references. If there are two files with the same defines label, NLINK65 will silently use the label of the last loaded file to fill the open reference. [1] If there are still symbols that aren't linked, like in this example: a.s: foo jsr bar brk b.s bar jsr foobar clc rts FOOBAR, the linker will try to complete the link by using user supplied libraries (with the '-l' option). If there are then still open references the file STD.L65 will be read from the library directory. The order in which files are linked is very important, since the linker appends the modules. The program will always be run starting with the first byte of the first module specified on the command line. Libraries are always appended to the end of the program. RUN and INIT addresses are only useful for non relocating programs as those addresses will start the program, when it is not yet re- located. B a t c h f i l e s There are solely used, because GEMDOS can only provide 128 bytes of commandline space, and especially NLINK65 command lines tend to need more room. The batchfile is not a real replacement for the commandline, you can only specify a list of object files that are to be linked. Lines that start of with a '#' are treated as comment. e.g.: # Little batch file called "demo.lnk" a.o65 b.o65 c.o65 foo.o65 # That's it So you can write instead of nlink65 a.o65 b.o65 c.o65 foo.o65 this nlink65 -b demo.lnk M O V E R The mover is a startup object module that is appended at the end of the program, which is called first, when a binary is loaded. There are three different movers. PRELOC -- page boundary relocator BRELOC -- byte boundary relocator MOVER -- byte boundary mover Using the mover is like assembling with an offset and having your code moved into position. BRELOC and PRELOC inspect at runtime a memory location (in most cases MEMLO) calculate the place where the code has to be moved and then start relocating. When the relocation is complete execution resumes at the start of your program. But your program is relocatable only once! See NASM65.TXT for more details. [1] The reason for this behaviour is that I deciced once, to make macro labels linkable. For good reason or not, is today unknown.