NAME
lit - link editor for transputers
SYNOPSIS
lit [options] [FILE ...]
DESCRIPTION
lit combines several LIT format object files and libraries
into a single LIT format executable.
OPTIONS
--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
address.
-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.
LINKER OPERATION OVERVIEW
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
memory.
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
segment@@start.
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.
HANDLING LIBRARIES
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.
SPECIAL NAMES
Some names have special meaning to the linker. This sec-
tion enumerates these names and explains their effect on
linker operation.
segment@@start
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
segment@@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.
segment@@blocksize
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.
BUGS
If you find any, please submit a description of the bug
and the data the bug exposes on to bug-ttools@botik.ru.
SEE ALSO
ast(1), dast(1), lit(5), litdump(1), ttools(1)
AUTHOR
lit is written by Yury Shevchuk (sizif@botik.ru)