lit - link editor for transputers

       lit [options] [FILE ...]

       lit combines several LIT format object files and libraries
       into a single LIT format executable.

       --help show usage summary

       -o FILE, --output FILE
              output to FILE instead of a.out.

       -p N, --maxpasses N
              limit the number of offset optimization  passes  by
              N.   lit  runs offset optimizer repeatedly over the
              internal representation of the program  until  fur-
              ther  optimization  proves impossible or this limit
              is reached.  Default  limit  is  8,  increasing  it
              might make a bit tighter code.

       -a N, --segment-align N
              assume  segments will be aligned at the boundary of
              N bytes when the program is loaded.  lit needs this
              info  to  be  able to reduce most of expressions at
              link time, leaving only a  minimum  of  work  to  a
              loader.   Default  is 4, i.e.  segments are assumed
              to be  loaded  at  the  word  boundary.   For  best
              results,  this  parameter  should  be set not lower
              than the  biggest  alignment  requested  by  .align
              directives in the program being linked.

       -h NAME, --hook NAME
              request  that  the fragment associated with NAME be
              included in the executable being build.  All  frag-
              ments  which  this  fragment  needs  will  also  be
              included.  More than one hook may be given; if none
              are given, lit will use the default hook @@hook.

       -lAR, --library AR,
              add  libAR.a  to  the  list  of files that lit will
              search for needed fragments.

       -LDIR, --libdir DIR
              add DIR to the list of directories  to  search  for
              libraries specified with -l option.

       -T[SEG] nnn
              assume  that  the segment SEG will be loaded at the
              address nnn.   nnn  may  be  decimal  (ddd),  octal
              (0ooo),  or  hexadecimal  (0xhhh) number.  In fact,
              this option is equivalent to assignment of  nnn  to
              special  symbol segment@@start.  If SEG is omitted,
              text is assumed.

       -m[FILE], --map[=FILE]
              write primitive unsorted symbol map  to  FILE.   If
              FILE  is omitted, the map is output to stdout.  The
              map is meant for primitive debuggers, but may  also
              be  useful  when  you  want  to  find out where the
              linker has put what.

       -E, --expr-print-long
              affects verbosity of debugging dumps requested with
              --trace  or --dump.  Giving this option once causes
              elements and noname symbols referred  from  ELEMENT
              and NAME expressions to be prefixed with their mem-
              ory addresses.  Giving this option twice results in
              every  expression  being  prefixed  with its memory

       -t SPEC, --trace SPEC
              enable debugging  output  to  stdout.   SPEC  is  a
              string  of  the  form KEY[+|-KEY][+|-KEY]...  where
              +KEY turns on certain tracing facility, -KEY  turns
              the facility off.  KEY may be any of the following:
              all, opt, opt2, reduce, files, read, needs,  point,
              misc, expr.  all turns on all trace facilities; for
              the description of other facilities  refer  to  the
              ast source.

       -d SPEC, --dump SPEC
              enable  debugging  dumps of internal representation
              of the program being assembled at  certain  points.
              SPEC  is  parsed  in  the same way as for --trace ;
              valid  dump  keys  are  all,  parse,  opt,  reduce,
              freeze, unroll, merge.

       lit  makes two passes through the files being linked.  The
       purpose of the first pass is to determine which  fragments
       from  which  files are to be linked in.  The linker starts
       with some symbols (typically the only one - @@hook) marked
       as  needed,  and  reads  the  NAMETABLE and NEEDS areas of
       every file, building a dependency graph for names found in
       the  files  based  on the need list of every name.  In the
       end of the first pass, the linker  has  a  nametable  full
       with  names, some subset of which is marked as needed.  If
       there are needed names for which the linker has not seen a
       definition,  the  linker  flags these symbols as undefined
       and terminates; otherwise, all is well and the linker goes
       on to the second pass.

       The  second pass visits each file which claimes to contain
       a definition for at least one  needed  name  SEGMENTS  and
       DEFINITIONS  areas  from  them.   From the SEGMENTS areas,
       needed fragments are picked  up;  unneeded  fragments  are
       skipped.   From  the  DEFINITIONS area, the definitions of
       needed names are read.  Also are read the  definitions  of
       (not  necessarily  needed)  special  names,  such  as seg-
       ment@@blocksize.  Other definitions are  skipped  to  save

       At  the  end  of the second pass, the linker has the whole
       program read in, represented in an internal  form.   Frag-
       ments  in  every  segment  are placed back-to-back to each
       other, all fragment names become defined, the only  possi-
       bly  undefined  names  at this point are the special names

       The offset optimizer (see ast(1)) is run over the internal
       representation  of  the  program  to minimize the commands
       whose arguments depend on relative positions of fragments,
       and so were nonoptimizable in assembly time.

       The  optimization normally results in most fragments' size
       intervals being narrowed down to constants.  If  any  ele-
       ments  are  still  of variable size after the end of opti-
       mization, their size if fixed at the  higher  boundary  of
       the  size  interval.   If  the actual size of such element
       turns out smaller than the size it is fixed  at,  it  will
       have to be padded to that size when the code for that ele-
       ment is generated.

       The linker then performs some simplifying  transformations
       over  the  element chains: DATA and CMD elements with con-
       stant  arguments  are  transformed  into  BLOCK   elements
       (unrolling), and adjacent BLOCK elements are merged.

       Then  the resulting program is written to the output file,
       the linking process is finished.

       lit is capable of traversing archives in the basic  (with-
       out support for long character names and names with embed-
       ded spaces) "!<arch>\n" format.  If ar on your system uses
       a  different  format, get the GNU ar.  Currently, there is
       no ranlib in TTOOLS, and lit cannot use archive index yet;
       this is likely to change in a future release.

       Some  names have special meaning to the linker.  This sec-
       tion enumerates these names and explains their  effect  on
       linker operation.

              represents  the  start  address  of  the segment in
              transputer's memory.  It may be assigned a value in
              one  of  the  files  being linked, or it may be set
              using the -Tsegment address switch.  If it  is  not
              set  in  one way or the other, it remains undefined
              until loading.  The more info about segment  place-
              ment you give to the linker, the better results you
              can expect from offset optimization.  For  example,
              to  allow  offset  optimizer  to  minimize commands
              whose arguments depend  on  relative  placement  of
              segments, you can tell the linker that the segments
              are going to be loaded back-to-back:

                   .globl text@@size
                   .globl data@@size
                   .globl bss@@size

                   data@@start = text@@start + text@@size
                   bss@@start  = data@@start + data@@size

              represents the size of  segment  in  bytes.   These
              symbols  are  defined  by  the  linker,  and may be
              referred to in  programs.   Note  that  the  linker
              always  pads  the segment with zeroes to a multiple
              of segment-align, so the  above  back-to-back  seg-
              ments  example is safe in the sense of alignment of
              data and bss segments.

              may be defined in the program to  tell  the  linker
              not  hesitate  to  unroll DATA elements in the seg-
              ment, if the  BLOCK  elements  resulting  from  the
              unrolling  are  not bigger than segment@@blocksize.
              By default, DATA elements with constant  value  and
              count  are  unrolled only if the resulting BLOCK is
              smaller than 32 bytes, so as  to  keep  the  output
              file compact.

       @@hook is the default name from which the linker starts to
              build the fragment dependency graph, which is  used
              for selection of fragments to link in.  Typically a
              startup file contains a fragment  with  this  name.
              You  can  specify  an  alternative  starting symbol
              using --hook option.

       If you find any, please submit a description  of  the  bug
       and the data the bug exposes on to

       ast(1), dast(1), lit(5), litdump(1), ttools(1)

       lit is written by Yury Shevchuk (