llf_linux.doc

LLF replaces the three Unix utilities Link, Locate and Format. It does all
three steps at once.

To run this utility on a Linux/Unix system, type:

	$ llf file ... [-options ...]
	
There can be any number of input files limited only by the shell. The input
files may be either the .ol or .ob object format (either such as produced
by compiliers and/or macxx assembler). The file format is identified by the
file type characters: .ol indicates the ol ASCII format (default) and .ob
indicates the binary object format. Library and Option files are provided
via the options -opt=file and -lib=file respectively.

Only the first 5 characters are significant on any of the optionss,
although any of them may be abbreviated to 1 or more characters.

The -options can appear anywhere on the command line. The items listed
in []'s are optional arguments to the particular option: 

Where option is one of ([] implies optional text):
-[no]output[=name] - select and name output file
-[no]map[=name]    - select and name map file
-[no]symbol[=name] - select and name symbol file
-[no]stb[=name] - select and name symbol table file
-option[=name]  - names an input option file
-library[=name] - names an input library file
-[no]binary     - select binary format output file
-[no]cross      - select cross reference map file format
-[no]octal      - select octal map file format
-[no]obj        - select default input file type of .ob
-[no]relative   - select relative output file format
-[no]error      - force display of undefined symbols in -relative mode
-[no]quiet      - suppress warnings about multiple defines from a .stb file.

Defaults are -out -nomap -nosym -nostb -bin -nocross
             -nooctal -noobj -norel -noerr -noquiet

The output filename defaults to the same name as the first input file with
output format and file types according to the following:
  .vlda if -bin -norel, .lb if -bin -rel,
  .hex if -nobin -norel, .ln if -nobin -rel

The -map, -symbol and -stb files default to the same name as the -output file
with file types of .map, .sym and .stb respectively.

The command options descriptions:

-cross - Cross references the global symbols used by filename and
	lists them in the map file. Forces the -map option. In the filename
	list, the first file listed is the one that defined the symbol
	unless the symbol was undefined (indicated by a message).

-binary - Forces the output file format to be written in a special binary
	format.

-obj - causes the default input file type to be .ob instead of .ol.
	That is, files are first attempted to be opened with a file type of
	.ob and if a file-not-found condition exists, then they are again
	attempted to be opened with a default file type of .ol.

-relative - Output file is in a relative format. That is, the segments are
	not located and global symbols may not be completely resolved. If
	this option is selected, then the default output file type is changed
	from .hex to .ln. The output can be run through LLF again to do the
	final locate and format. If -binary is present, then the default
	changes to .lb.

-error - Forces LLF to display undefined symbol and other messages that would
	normally be suppressed during a -relative link. Use this if you need
	a relative output but are not intending to re-link the output with
	additional object modules or just want to be informed of any unresolved
	global references.

-output[=name] - Allows you to specify an output file name that may be
    different than the input filename(s). This option is defaulted and
	the filename used is the same as the first non-library or non-option
	file input. Note that the file is created in the current default
	directory and not necessarily the directory that the input file(s)
	are located in.

-map[=name] - Specifies that LLF create a printable MAP file with the output
    image statistics (such as segment placement and global symbol values).
	The optional value allows for filename to be specified if different
	than that of the output filename. Note that segment and symbol names
	may be 32 characters in length but the rightmost characters may
	be truncated on the link map in order to make a reasonable display
	format. All the characters remain significant for linking purposes
	regardless of what is displayed on the link map.

-octal - Specifies that all the values displayed in error messages and on the
	link map be done using an octal radix. The segment and symbol name
	fields may be further truncated to accomodate the longer length of
	the 32 bit octal numbers.

-symbol[=name] - Specifies that global symbols and their values should be
    placed in the output file. If an optional value is placed on this
	option, then a seperate file will be created with only the global symbols
	in it. The symbol file will be created in tekhex format unless the
	-binary option is present, in which case, the output will be in .ob
	format. May not be used with the -relative option.

-stb=[name] - Creates a segment/symbol file that may be used in a later link
    step. This file would contain only the resolved globals and located
	segments. No code (user data) is placed in this file. (Functionally
	identical to a -symbol file except that the STB file is suitable to
	be used as input to LLF again where the -symbol files may be
	TekHex files suitable only for downloading). May not be used with
	the -relative option.

-library=name - Specifies the name of a library file. Libraries are
	processed in the order that they are encountered. If there are no
	undefined globals at the time the library file is processed, then no
	modules will be plucked from the library. If one or more modules are
	plucked from the library, then the library will be continually
	re-processed until no symbols are resolved by any module(s) in the
	library.

-option=name - Specifies the name of an option file. An option
	file is an ASCII file that you can use to define global symbols and
	locate segments and other specifics. The syntax of the OPTION file
	follows.

The Option file description:

        The contents of the option file is used to define global symbols
        and set the locations of sections and other memory operations. It
        uses basically the same rules as the "C" language in that white
        space consists of spaces, tabs and newlines. White space must
	seperate names from other names but otherwise is ignored. Comments
	can appear on any line and are de-limited with double dashes (--)
	or exclamation mark (!) and a newline. The C comment construct of "/*"
	and "*/" can also be used. The "case" of any of the keywords is NOT
	significant, but the "case" of the segment and global names IS
	significant. Numbers are assumed to be decimal unless prefixed with a
	pound sign (#) or '0x' which indicates hexidecimal. The C constant
	declaration may also be used. That is constants are assumed to be decimal
	unless preceeded with a leading 0, in which case, they are octal or
	preceeded with a 0x to indicate hexidecimal. The main keyword (FILE,
	LOCATE, etc.) is expected to be the first token on a newline and
	everything after the closing parantheses to end of line is discarded.
	Some examples:

FILE ( filename1 filename2 ... )   /* includes file(s) for input */
LIBRARY ( library1 library2 ... )  /* includes library(s) for input */

	As with the command input, the default input file types are assumed to
	be .ol or .ob and the default library file type is .LIB. Filenames
	may be delimited with either commas (,) or white space and the files
	and libraries are processed in the order in which they are specified
	and in the same order as the option file is input in the command
	string. For example: 

		$ LLF one,two/opt,three

	where TWO.OPT contains:

		FILE (four five)
		LIBRARY (six)
		FILE (seven)

	will cause the files to be processed as "one,two,four,five,six/lib,
	seven,three". 

LOCATE ( group_name : address_option ; ... )	!position a group or segment
LOCATE ( segment_name ... : address_option ; ... ) !at a specific address 
						!or range of addresses

	Where "group_name" refers to the name of a group and "segment_name"
	refers to the name of a segment or section (there's no difference
	between a section and a segment). The "address_option" can be one of
	the following:

		constant [additional_argument(s)]

	Where "constant" is assumed to be a number and "additional_arguments"
	can be one or more of the following:

		TO constant
		OUTPUT constant
		NAME group_name

	The "TO constant" construct instructs LLF to notify you if the
	segment(s) you locate won't fit in the area specified. The
	"OUTPUT constant" construct allows you to locate the segment(s)
	at one address but place the data in a different area in the
	output address space. The "NAME" option allows you to name a
	group with other than the automatic "noname_xxx" name generator.
	Examples: 

		LOCATE ( DEFAULT_GROUP : #1000 );
		LOCATE ( $$one $$two $$three : #0100;
			 $$four $$five $$six : #0200 TO #02FF;
			 $code : #8000 TO #DFFF OUTPUT #10000;
			 $tables1 $tables2 : #0C000 OUTPUT #1C000);

DECLARE ( symbol_name value, ...) !to define a global symbol

	Where "symbol_name" is the global symbol you're defining and value
	is the value to assign to the symbol. You cannot re-define an already
	defined symbol nor can you create a symbol that isn't referenced in
	any of the input files. Examples:

		DECLARE ( checksum #0123, FIVE 5, TEN 10 )

RESERVE ( address_option ... )  !to reserve an area of memory such that
				!no segments will be placed there by the
				!automatic placement mechanism.

	Where "address_option" is any of the following:

	constant		/* a specific single location */
	BEFORE constant		/* all addresses below constant */
	AFTER constant		/* all addresses above constant */
	constant TO constant	/* all locations between the 2 constants */

	Examples:
	
		RESERVE ( 0 TO #0FFF )		/* 0 to FFF inclusive */
		RESERVE ( 0x0630 )		/* location 630 only */
		RESERVE ( AFTER 0100000 )	/* 8000-FFFFFFFF inclusive */
		RESERVE ( BEFORE #0FFF )	/* 0-FFF inclusive */
Miscellaneous information:

RT-11/RSX object files allow for global symbols and PSECTs to have the same name
and yet treat them differently. The OL format does not distinguish between
global symbol names and segment names. In order to allow both formats to
co-exist, LLF suffixes an underscore on all PSECT names defined in the RT/RSX
object files. In addition, the RT/RSX object files may have unnamed psects (the
default blank program section). LLF renames the "blank" psect as "unnamed_"
(notice that it's lowercase). If you choose to locate specific psects to
specific areas, you'll need to reference them using LLF's naming convention.
Notice also that the use of .ASECT, .PSECT xx,ABS and/or .PSECT xx,BSE may
result in warnings about segments being overlayed. This is because the BSE
section(s) may be overlaying the .ASECT or .PSECT xx,ABS sections. 

Output file formats:

Extended TEKhex format is an ASCII record containing one of the following:

	%nnTcs...

where:	% is the ASCII percent character (record sentinel).
	nn- is a 2 hex digit count of the number of bytes in the
	     record excluding the percent character.
	T  - is the record type: 3 for symbol, 6 for data and
	     8 for end of file (termination record will not have
	     any data).
	cs - is a 2 digit hex number representing the sum, mod 256,
	     of all the characters in the record, except the leading
	     %, the checksum digits, and the end of line.

In Extended TEKhex, certains fields may vary in length from 2 to 17
characters. This enables data compression by eliminating leading zeroes
from numbers and trailing spaces from symbols. The first character of a
variable length field is the length of the rest of the field. The digit
0 indicates a length of 16 characters. There will be a variable number
of these variable length fields following the checksum and their content
varies according to the record type: 

	%nn6cslldd... - Data block
		ll    = 2-9 chars of load address
		dd... = n pairs of chars of hex data

	%nn8csll   - termination record
		ll = 2-9 chars of transfer address

	%nn3ccvvss... - symbol record
		vv = 2-17 chars of section name (LLF always writes 2S_)
		ss = n x 5-27 chars of symbol definition:
			1 char of symbol type (LLF always outputs an 
				ASCII 2 = global scalar)
			2-17 chars of symbol name
			2-9 chars of symbol value (LLF resolves to 32 bits)

VLDA file format is a binary variable length record with no RMS record
attributes. It may or may not contain relocatable code. For preliminary
release (relocatable elements are subject to change), the format of the
absolute output record is:

	byte 0 - record type code, =0 for absolute data
	     1-4 - 4 byte load address (byte 1=lsb, byte 4=msb)
	     5-n - binary load data

Compute the number of data bytes by subtracting 5 from the record length
returned by RMS. LLF will place TEKhex symbol records including a trailing crlf
into a VLDA record type 13 (decimal) if the /SYM and/or /SEG command qualifiers
are used in conjunction with the /VLDA qualifier.