home *** CD-ROM | disk | FTP | other *** search
/ Crawly Crypt Collection 1 / crawlyvol1.bin / program / compiler / nasm20b / doc / nlink65.txt < prev    next >
Text File  |  2007-09-14  |  7KB  |  183 lines
  1.    ----------------------------------------------------------------------
  2.                      Copyright (C) 1990 by Natürlich!
  3.                         This file is copyrighted!
  4.                   Refer to the documentation for details.
  5.    ----------------------------------------------------------------------
  6.  
  7.    NLINK65 --- an Atari 8-Bit Crosslinker for the Atari ST (et al.) v0.2
  8.  
  9.  
  10.                         Preliminary manual for NLINK65
  11.  
  12.          Copyright © 1990 by Natürlich!
  13.             on sources, binaries and manuals
  14.  
  15.  
  16.                   »» Bang that Bit that doesn't Bang ««
  17.  
  18.  
  19.    I n t r o d u c t i o n
  20.  
  21.    NLINK65 is a portable (?) single-pass cross-linker that produces 6502
  22.    code. NLINK65 currently runs on the 68000 Atari under TOS. The linker
  23.    produces two kinds of output, code that has to be run at a certain
  24.    origin, or relocatable code.
  25.  
  26.  
  27.    U s a g e
  28.  
  29.    nlink65 [-{tw}][-m[{1234}]][-s org][-b batch][-d libdir][-l lib]
  30.            [-o .com] <files>
  31.  
  32.    -t    TOS switch, wait for a keypress after running
  33.  
  34.    -w    The "what the ...." switch, even though errors occured an output
  35.          file is generated.
  36.  
  37.    -m    The relocatable switch. NLINK65 will create a relocatable Atari
  38.          8-Bit binary file for direct execution
  39.          mm xxxx   - Create a binary file that will be loaded to the
  40.                      default origin (or -s origin) and then moved to
  41.                      xxxx. (This is like assembling with an offset in
  42.                      MAC65). 
  43.          m[0]     -  create a binary with a mover that will be moved
  44.                      byte aligned to LOMEM.
  45.          m1       -  create a binary with a mover that will be moved
  46.                      page aligned to LOMEM (this produces a shorter
  47.                      binary) [see also -s]
  48.          m2 xxxx  -  create a binary with a mover that will be moved
  49.                      to the contents of xxxx (hex) at runtime
  50.          m3 xxxx   - as m1 but page aligned [see also -s]
  51.  
  52.  
  53.    -b    Use batchfile to read in the names of [more] <files>
  54.  
  55.    -d    Supply alternate library directory (Default is taken from the
  56.          Environment variable >LIBRARY<)
  57.  
  58.    -e    Limit the number of errors: 0 = show all
  59.  
  60.    -i    Append a RUNAD segment to the file, for DOS 2.X and
  61.          family
  62.          
  63.    -o    Specify alternate output file pathname (or filename)
  64.  
  65.    -s    Supply origin to load to. This is used with relocatable and
  66.          non relocatable code. Default = 2000 (hex). Page aligned code
  67.          will load at xx00 - 3.
  68.  
  69.    -l    Library to link with. STD.L65 is always tried to be linked.
  70.          Libraries must be linked in order. STD.L65 is always last.
  71.          f.e.  foo.l65->bar.l65->std.l65 -->   "-l foo -l bar"
  72.  
  73.    -x    Create a file suitable for use as a boot disk. Just write
  74.          the file sector per sector on a disc. 128 byte sectors only.
  75.          (use -xx for a bootheader-less file)
  76.          
  77.  
  78.    C r e a t i n g   f i x e d   o r i g i n   f i l e s
  79.  
  80.    Type from a shell:
  81.    nlink65 <object.o65>
  82.  
  83.    That will create a output file {object}.COM
  84.    Transfer this file (with NASTY for instance) to a 8-Bit Atari computer
  85.    and execute it there.
  86.  
  87.  
  88.    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
  89.  
  90.    Type from a shell
  91.    nlink65 -m <object.o65>
  92.    That will create a output file {object}.com for execution on an
  93.    8-Bit Atari. See -m for more details.
  94.  
  95.  
  96.    C r e a t i n g    b o o t s e c t o r   f i l e s 
  97.    
  98.    Type from a shell
  99.    nlink65 -x <object.o65>
  100.    That will create a output file {object}.boo ready for transplan-
  101.    tation on a 8-bit Atari SD diskette. If you have declared a label 
  102.    in your file with the name _boot_init, this will be entered into
  103.    the bootheader as the init address.
  104.       
  105.  
  106.  
  107.    H o w   t h e   l i n k e r   w o r k s
  108.  
  109.    The linker first reads in the source files (in order of appearance
  110.    in the command line (batch file)) and tries to resolve all open
  111.    references. If there are two files with the same defines label, NLINK65
  112.    will silently use the label of the last loaded file to fill the open
  113.    reference. [1] If there are still symbols that aren't linked, like
  114.    in this example:
  115.  
  116.    a.s:
  117.          foo jsr bar
  118.              brk
  119.  
  120.    b.s   bar jsr foobar
  121.              clc
  122.              rts
  123.  
  124.    FOOBAR, the linker will try to complete the link by using user 
  125.    supplied libraries (with the '-l' option). If there are then still 
  126.    open references the file STD.L65 will be read from the library 
  127.    directory.
  128.    The order in which files are linked is very important, since the
  129.    linker appends the modules. The program will always be run starting
  130.    with the first byte of the first module specified on the command
  131.    line. Libraries are always appended to the end of the program.
  132.    RUN and INIT addresses are only useful for non relocating programs
  133.    as those addresses will start the program, when it is not yet re-
  134.    located. 
  135.  
  136.  
  137.    B a t c h f i l e s
  138.  
  139.    There are solely used, because GEMDOS can only provide 128 bytes of
  140.    commandline space, and especially NLINK65 command lines tend to
  141.    need more room. The batchfile is not a real replacement for the
  142.    commandline, you can only specify a list of object files that are
  143.    to be linked. Lines that start of with a '#' are treated as comment.
  144.  
  145.    e.g.:
  146.    # Little batch file called "demo.lnk"
  147.    a.o65
  148.    b.o65
  149.    c.o65
  150.    foo.o65
  151.    # That's it
  152.    
  153.         So you can write instead of
  154.                 nlink65 a.o65 b.o65 c.o65 foo.o65
  155.         this    
  156.                 nlink65 -b demo.lnk
  157.  
  158.  
  159.  
  160.    M O V E R
  161.  
  162.    The mover is a startup object module that is appended at the end of the
  163.    program, which is called first, when a binary is loaded.
  164.    There are three different movers.
  165.  
  166.    PRELOC  -- page boundary relocator
  167.    BRELOC  -- byte boundary relocator
  168.    MOVER   -- byte boundary mover
  169.  
  170.    Using the mover is like assembling with an offset and having your code
  171.    moved into position.
  172.    BRELOC and PRELOC inspect at runtime a memory location (in most cases
  173.    MEMLO) calculate the place where the code has to be moved and then start
  174.    relocating. When the relocation is complete execution resumes at the
  175.    start of your program.
  176.    But your program is relocatable only once! See NASM65.TXT for more
  177.    details.
  178.    
  179.  
  180. [1] The reason for this behaviour is that I deciced once, to make macro
  181.     labels linkable. For good reason or not, is today unknown.
  182.  
  183.