home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / CPM / BDSC / BDSC-2 / L2.DOC < prev    next >
Text File  |  2000-06-30  |  15KB  |  529 lines
  1.  
  2.  
  3.  
  4. L2 (C Linker) v2.1               1                         7 Dec 81
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                    The Mark of the Unicorn Linker
  16.                              For BDS C
  17.  
  18.                            v2.1 7 Dec 81
  19.                          Linker and Docs by
  20.                 Scott W. Layson, Mark of the Unicorn
  21.  
  22.  
  23. L2 is an  alternative  to  CLINK  for  linking  BDS  C programs.  A
  24. program linked with CLINK will  have  a jump table at the beginning
  25. of  each function; calls to other  functions  are  made  indirectly
  26. through  the  table.  L2 eliminates these jump tables, and  adjusts
  27. indirect calls through them to go directly to the target function. 
  28. Besides  making the code imperceptibly faster, this  has  two  real
  29. advantages: one, it makes the code smaller by 4% to 10% (the latter
  30. has  been  observed  in  a  program containing many small functions
  31. which do  little besides call a few other functions), and it allows
  32. SID  to  display the  name  of  the  target  function  of  a  call,
  33. simplifying debugging. 
  34.  
  35. L2  seems  to  be complete enough to replace CLINK  entirely.   Its
  36. biggest  advantage is that it's written in C, so that if  you  need
  37. some feature  it  doesn't  have, you can just hack it in.  However,
  38. its  user  interface and certain aspects of its behavior are rather
  39. different. 
  40.  
  41. The most important difference  is  the distinction it makes between
  42. "program" and  "library"  CRL  files.   Program files are loaded in
  43. their  entirety;  each  function  in a program file is  linked  in,
  44. whether or not it has been referenced by the time it is encountered
  45. (unless another function  with  the  same  name  has  already  been
  46. loaded).  Library files  are  scanned  for  needed  functions; only
  47. those that have been referenced by another function are included in
  48. the  object code.  CLINK treats all CRL files as libraries in  this
  49. sense (except see the -f option for v1.4). 
  50.  
  51. A typical command line is
  52.  
  53.      l2 foo bar -l bletch grotz -wa
  54.  
  55. Given this command, L2 will load all the  functions  in FOO.CRL and
  56. BAR.CRL  (the  program files).  Then it  will  scan  the  libraries
  57. BLETCH.CRL, GROTZ.CRL, DEFF.CRL,  and DEFF2.CRL (in that order) for
  58. functions that have  been  referenced  but  not  linked.   If there
  59. remain unsatisfied references, L2 will display a list of the needed
  60. functions and  prompt  for  the name of a CRL file to scan; it will
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. L2 (C Linker) v2.1               2                         7 Dec 81
  71.  
  72.  
  73.  
  74.  
  75. repeat this process  until  all references are satisfied (just like
  76. CLINK). Then it will write the resulting code to  FOO.COM,  display
  77. the  link statistics, and write a symbol table (with the link stats
  78. appended) to FOO.SYM.
  79.  
  80. In more detail, then: here is a list of  the available command-line
  81. options.   Options  consist  of  a  dash  followed by  a  (possibly
  82. one-letter)  word,  preceded  and  followed  by  a  space.   Unlike
  83. CLINK's, L2's options  may  not  be combined; "-l -w", for example,
  84. may not be abbreviated "-lw"; and "-m fubar"  may  not  be  written
  85. "-mfubar".
  86.  
  87. -f <funcs>       Reserves enough table size for <funcs> functions. 
  88.                  (<funcs>  is  in decimal.)  The default is 200. If
  89.                  you  often  link  programs  with   more  than  200
  90.                  functions,  you  may wish to change the default --
  91.                  it's in setup() in L2.C.
  92.  
  93. -l                CRL file names  before  the  first  "-l"  on  the
  94.                  command line will be treated as program files; CRL
  95.                  files  after  the  first   "-l"   are  treated  as
  96.                  libraries.  Subsequent "-l"s have no effect. 
  97.  
  98. -m <name>        <name> becomes the  top-level  function.   This is
  99.                  the  function initially called when the .COM  file
  100.                  is run; by default,  of course, it is "main". Note
  101.                  that,  unlike  with  CLINK, the top-level function
  102.                  need not be the  first  function  in the first CRL
  103.                  file; it can be anywhere.  -m also works with -ovl
  104.                  (see below). 
  105.  
  106. -ovl <name> <addr>
  107.                  An overlay segment will be built instead of a root
  108.                  segment; the overlay will be linked to run at base
  109.                  address <addr> (entered in  hex).   <name>  is the
  110.                  name of  the root segment for which the overlay is
  111.                  being built; <name>.SYM, a symbol  table  produced
  112.                  with either L2 or CLINK,  will be read in *before*
  113.                  the CRL files,  to allow overlay functions to call
  114.                  root  functions.   The  name  of   the   top-level
  115.                  function in the overlay -- i.e., the one that gets
  116.                  invoked by a call to the overlay base  address  --
  117.                  is by  default  not "main", but rather <firstcrl>,
  118.                  the name of the first  CRL  file in the L2 command
  119.                  line.   The  overlay   segment   is   written   to
  120.                  <firstcrl>.OVL. (See example below.) 
  121.  
  122. -org <addr>      This option is used to produce a root segment with
  123.                  base address <addr>, e.g., for use  in  generating
  124.                  code for ROMming. <addr> is entered in hex, and is
  125.                  the starting address  of the code, not of RAM; the
  126.                  default is, of  course,  0x100. (To link a program
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. L2 (C Linker) v2.1               3                         7 Dec 81
  137.  
  138.  
  139.  
  140.  
  141.                  for   a   nonstandard  CP/M,  you  need  a  C.CCC,
  142.                  DEFF.CRL,  and DEFF2.CRL which have been assembled
  143.                  for that  address.   If  you  are  running L2 on a
  144.                  nonstandard  CP/M, you should change  the  default
  145.                  origin  in  setup()  to  0x4300.) If you are using
  146.                  this  option to generate code for ROM, be sure  to
  147.                  use the "-t" option also (see below). 
  148.  
  149. -t  <addr>         Works  just like the CLINK "-t" option: sets the
  150.                  stack pointer to the given address at the start of
  151.                  the run-time package.  This  option MUST ALWAYS BE
  152.                  USED when "-org" is used to generate code for ROM.
  153.                  IF   "-t"  is  NOT  used,  then  the   first   two
  154.                  instructions of the resulting COM file will be:
  155.  
  156.                       lhld origin-100h+6
  157.                       sphl
  158.  
  159.                  (where "origin" is normally 0x100 or 0x4300) while
  160.                  using  "-t" causes the first two  instructions  to
  161.                  be:
  162.  
  163.                       lxi sp,<addr>
  164.                       nop
  165.  
  166. -w                A  SID-compatible  symbol  table  is  written  to
  167.                  <firstcrl>.SYM,  where <firstcrl> is the  name  of
  168.                  the first CRL  file  listed  in the command line. 
  169.                  This table is normally produced in address  order,
  170.                  not alphabetical order like CLINK's; see below for
  171.                  how to change this. 
  172.  
  173. -wa              A variation on -w. The link statistics, which  are
  174.                  always  displayed on the console  at  the  end  of
  175.                  linking, are also appended to the .SYM  file.   If
  176.                  the resulting .SYM file is read into SID, SID will
  177.                  complain  by  issuing  its typical  verbose  error
  178.                  message "?", but then  will  work  correctly.  The
  179.                  big advantage of putting the stats at the  end  of
  180.                  the .SYM file is that one can subsequently look at
  181.                  that file to see exactly how long the code was and
  182.                  where the externals started. 
  183.  
  184. -ws              Another variation  on  -w.  This  one  writes  the
  185.                  symbol   table  to  <firstcrl>.SYM  and  the  link
  186.                  statistics to <firstcrl>.LNK.
  187.  
  188. Because L2 is so large, it cannot  always  link large programs in a
  189. single pass.  If it runs  out  of  memory  during  linking, it will
  190. switch automatically to (very slow) two-pass  mode.   (If  it  says
  191. "Module won't fit in memory at all", you probably have a very large
  192. program file.  Split it up  or  make it a library.  If this doesn't
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. L2 (C Linker) v2.1               4                         7 Dec 81
  203.  
  204.  
  205.  
  206.  
  207. work, you don't have enough memory to use L2.)
  208.  
  209. L2 is  built  from  the source files L2.C, SCOTT.C, and CHARIO.C. A
  210. typical compilation is
  211.  
  212.  
  213.  
  214.      cc l2.c -e4500
  215.      cc scott.c
  216.      cc chario.c
  217.         followed by either
  218.      clink l2 chario scott
  219.         or
  220.      l2 l2 chario -l scott
  221.         depending on whether an L2.COM is handy.
  222.  
  223. If you want  a  slightly  shorter version, comment out the "#define
  224. OVERLAYS"  statement near the  beginning  of  L2.C.  You  can  then
  225. compile with -e4100; the resulting L2 will  not  accept  the "-ovl"
  226. option. 
  227.  
  228. If  you  have  a pre-release of MARC and want a MARC  cross-linker,
  229. uncomment  the  "#define  MARC". Then, when  you  use  the  "-marc"
  230. option, L2 will look for CM.CCC,  DEFFM.CRL,  and DEFF2M.CRL, which
  231. should be the MARC versions of these files.  L2 will produce a .COM
  232. file  which must be MFTPed to MARC, then converted to load format. 
  233. L2 itself does  not yet run under MARC; if anyone has the energy to
  234. convert it, let me know! 
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. L2 (C Linker) v2.1               5                         7 Dec 81
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.                     Relocatable Overlay Manager
  280.  
  281.  
  282. MAKOVL is a  variation  on  L2.  It builds relocatable overlays and
  283. stores them  in fixed-size slots in a single overlay file.  Here is
  284. the (rather terse) documentation from the beginning of MAKOVL.C:
  285.  
  286.      Command format:
  287.  
  288.  
  289.           makovl <root name> <overlay name> {<CRL file>
  290.  
  291.      [-l {<CRL file>}] [-nd]}
  292.  
  293.      Overlay descriptor file, <root name>.DES, contains:
  294.  
  295.  
  296.           <overlay slot size> <relocation info size>
  297.           <CRL file> ... (default search list)
  298.           ... (more default search list)
  299.           <blank line>
  300.           <overlay name> <slot number>
  301.                <function name>  <comments or whatnot>
  302.                <function name>  <comments or whatnot>
  303.                ... (an entry for each top-level function in
  304.           the overlay)
  305.           <blank line>
  306.           <overlay name> <slot number>
  307.                <function name>  <comments or whatnot>
  308.                <function name>  <comments or whatnot>
  309.                ...
  310.           ... (an entry for each overlay in the file)
  311.  
  312.      Overlay segments are of length <overlay slot size> bytes,
  313.      of which the last  <relocation  info  size> bytes holds a
  314.      list  of  relocation offsets.  This is a  null-terminated
  315.      string  of  byte  values  giving  the  difference between
  316.      successive addresses to  be  relocated;  a  value  of 255
  317.      means  to  add  255  to the next byte value  to  get  the
  318.      offset.   The  first offset is relative to -1 (so that we
  319.      can  relocate  the  first word of the overlay).   At  the
  320.      beginning of the overlay  is  a  table  of  addresses  of
  321.      top-level functions, one address for each function listed
  322.      for that overlay in the descriptor file. 
  323.  
  324.      The -l option  works  as  for L2: CRL files listed before
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. L2 (C Linker) v2.1               6                         7 Dec 81
  335.  
  336.  
  337.  
  338.  
  339.      the  -l  are  loaded  in entirety; those after  are  just
  340.      scanned for needed functions.  Any functions specified in
  341.      the  default search list in the overlay  descriptor  file
  342.      are also scanned, unless the -nd (no default)  option  is
  343.      given. 
  344.  
  345.      The  overlay,  once  created,  is   written   into  <root
  346.      name>.OVL, at  address  <slot  number>  *  <overlay  slot
  347.      size>. 
  348.  
  349. Here is an example of a .DES file, with comments in brackets:
  350.  
  351.  
  352.      1024 128                 [1K overlay slots; 128 relocation
  353.      bytes]
  354.      lib1 lib2 lib3           [default CRL libraries]
  355.  
  356.      OvlOne    0              [overlay name, slot number]
  357.           Func11              [callable functions in the overlay]
  358.           Func12
  359.           Func13
  360.  
  361.      OvlTwo    1              [another overlay name & slot]
  362.           Func21
  363.           Func22
  364.           Func23
  365.  
  366. Here is some code to load and execute the generated overlays:
  367.  
  368.  
  369.      /* Overlay manager */
  370.  
  371.      int curovl, ovlfd;
  372.  
  373.      #define OVLSIZE     1024      /* overlay space size in bytes
  374.      */
  375.      #define RELOCSIZE   128       /* size of relocation info */
  376.      char overlay[OVLSIZE];
  377.  
  378.      OvlInit()                     /* start overlay manager */
  379.      {
  380.           curovl = -1;
  381.           if ((ovlfd = open ("FUBAR.OVL", INPUT)) < 0) {
  382.                puts ("Can't find the overlay file, FUBAR.OVL\n");
  383.                exit (1);
  384.                }
  385.           }
  386.  
  387.      OvlFini()                     /* clean up overlay manager */
  388.      {
  389.           close (ovlfd);
  390.           }
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. L2 (C Linker) v2.1               7                         7 Dec 81
  401.  
  402.  
  403.  
  404.  
  405.  
  406.      OvlCall (ovlno, fun, arg1, arg2) /* call function <fun> in
  407.      overlay <ovlno> */
  408.           int ovlno, fun, arg1, arg2; /* with args (<arg1>,
  409.      <arg2>) */
  410.      {
  411.           int *ovltab, (*ovlfunct)();   /* note C bug: "int
  412.      (**ovltab)()" doesn't work */
  413.      
  414.           OvlLoad (ovlno);
  415.           ovltab = overlay;
  416.           ovlfunct = ovltab[fun];
  417.           return (*ovlfunct) (arg1, arg2);
  418.           }
  419.  
  420.      OvlLoad (ovlno)               /* load overlay <ovlno> */
  421.           int ovlno;
  422.      {
  423.           char reloc[RELOCSIZE];
  424.      
  425.           if (ovlno == curovl) return;
  426.           if (seek (ovlfd, ovlno * ((OVLSIZE + RELOCSIZE) / 128),
  427.      ABSOLUTE) < 0
  428.               || read (ovlfd, overlay, (OVLSIZE / 128)) < 0
  429.               || read (ovlfd, reloc, (RELOCSIZE / 128)) < 0) {
  430.                puts ("Read error in the overlay file,
  431.      FUBAR.OVL\n");
  432.                exit (1);
  433.                }
  434.           OvlReloc (overlay, reloc);
  435.           curovl = ovlno;
  436.           }
  437.  
  438.      OvlReloc (code, rels)         /* relocate an overlay */
  439.           char *code, *rels;
  440.      {
  441.           int *itemp;
  442.           char *btemp;
  443.      
  444.           btemp = code - 1;
  445.           while (*rels) {
  446.                btemp += *rels;
  447.                if (*rels++ == 255) btemp += *rels++;
  448.                itemp = btemp;
  449.                *itemp += code;
  450.                }
  451.           }
  452.  
  453. To call these functions:
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. L2 (C Linker) v2.1               8                         7 Dec 81
  467.  
  468.  
  469.  
  470.  
  471.      #define FUNC11      0, 0
  472.      #define FUNC12      0, 1
  473.      #define FUNC13      0, 2
  474.  
  475.      ...
  476.  
  477.           OvlCall (FUNC11, arg1, arg2);
  478.  
  479.      ...
  480.  
  481. To make a MAKOVL.COM:
  482.  
  483.  
  484.  
  485.      cc makovl.c -e4100
  486.      cc chario.c         (if necessary)
  487.      cc scott.c          (if necessary)
  488.      l2 makovl chario -l scott
  489.  
  490.  
  491.  
  492.                                   Good luck
  493.  
  494.  
  495.                                   Scott W. Layson
  496.                                   Mark of the Unicorn
  497.                                   P.O. Box 423
  498.                                   Arlington, MA 02174
  499.  
  500.  
  501.  
  502.  
  503.  
  504.  
  505.  
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.