Multics Technical Bulletin MTB-718
Linkage Editor.
To: Distribution
From: Dean Elhard
Date: 6 June 1986
Subject: Multics Linkage Editor Specification
1. Abstract
This MTB will supply the specifications for the new Multics Link
Editor mentioned in MTB 688 and MTB 691.
Revision 1:
Revised ocu_ subroutine interface, and linkage editor
command interface.
Revision 2: |
|
Revides to change terminology regarding object multisegment |
files. |
Changes are marked with change bars.
Comments should be sent to the author:
via Multics mail to:
Elhard -at System-M
via posted mail to:
Dean Elhard
Advanced Computing Technology Centre
Foothills Professional Building
1620 29th St., N.W.
Calgary Alberta Canada T2N-4L7
via telephone to:
(403)-284-6400
(403)-284-6427 (Elhard)
via forum on System-M to:
>udd>m>DGHowe>mtgs_dir>c>c_imp (c)
_________________________________________________________________
Multics project internal documentation; not to be reproduced or
distributed outside the Multics project.
MTB-718 Multics Technical Bulletin
Linkage Editor.
TABLE OF CONTENTS
Section Page Subject
======= ==== =======
1 i Abstract
2 1 Preface
3 1 Introduction
3.1 1 . . Goal
3.2 1 . . References For This Document
4 2 Background
5 2 Functional Specifications.
5.1 5 . . Input Paths.
5.2 6 . . Libraries.
5.3 7 . . Output.
5.4 7 . . Map/List Output.
6 7 Link Editor Implementation
6.1 8 . . General Implementation
6.1.1 8 . . . . Command Processing.
6.1.2 8 . . . . Link and Library Resolution.
6.1.3 8 . . . . External Initialization Resolution.
6.1.4 8 . . . . MSF Partitioning.
6.1.5 8 . . . . Component Processing.
6.1.6 9 . . . . Output Backpatching.
6.1.7 9 . . . . MSF Transfer Vector Creation.
6.2 10 . . Library Link Resolution.
6.3 10 . . Object Creation Utilities.
6.3.1 11 . . . . ocu_$open
6.3.2 13 . . . . ocu_$close
6.3.3 14 . . . . ocu_$release
6.3.4 15 . . . . ocu_$emit_text
6.3.5 16 . . . . ocu_$emit_definition
6.3.6 18 . . . . ocu_$emit_segname
6.3.7 19 . . . . ocu_$emit_msf_map
6.3.8 20 . . . . ocu_$emit_static
6.3.9 21 . . . . ocu_$emit_link
6.3.10 23 . . . . ocu_$emit_partial_link
6.3.11 25 . . . . ocu_$emit_firstref_trap
6.3.12 26 . . . . ocu_$emit_symbol
6.3.13 27 . . . . ocu_$backpatch
6.3.14 29 . . . . ocu_$create_msf
6.4 31 . . Object Multi-Segment Files.
Multics Technical Bulletin MTB-718
Linkage Editor.
2. Preface
In the development of the C language on Multics it has been found
that a new method of binding object segments together is
required. This new method will have a user interface similar to
what C users expect.
3. Introduction
3.1. Goal
The objective is to allow the porting of existing software to
Multics, in particular, the porting of large C packages. The
linkage_editor is seen as the beginning of a series of tools
implemented to aid in the porting of third party software. The
linkage_editor will allow packages that were developed in a more
conventional (ie. statically linked) environment to be ported
more conveniently without having to worry about problems such as
name conflicts, object segment size constraints, etc.
3.2. References For This Document
1) Multics Programmers Reference Manual (10.2 AG91-03A)
(hereafter referred to as MPRM)
MTB-718 Multics Technical Bulletin
Linkage Editor.
4. Background
The development of the C language on Multics has introduced the
need for tools to aid users to port software to Multics. One
such tool required specifically for C is a linkage_editor. This
linkage_editor will function in a manner similar to linkers
available on other systems. At its base level, the function of
the linkage_editor will be similar to the current Multics binder.
5. Functional Specifications.
The following is a functional description of what services the
linkage editor will provide and how they are used.
Syntax: le {paths} {-control arguments}
Function: Joins a series of object segment together into a
single execution unit resolving external references to the
explicitly named segments or segments within the named libraries.
Arguments:
paths
specifications of the input binaries which are to be included
in the output binary. Valid formats for a path specification
are:
Archive
Library archives are unbound archives containing object
segments which may be used to resolve external references. To
specify a library archive, the ".archive" suffix must be
included in the name.
Directory
Library directories may be specified which contain loose
object segments or archives of object segments. |
Pathname
Pathnames to specific segments or archive components may be
specified.
Starname
Starnames specifying groups of loose segments or archives |
within a directory may be specified, or an archive component |
starname specifying a set of components within a particular
archive.
Multics Technical Bulletin MTB-718
Linkage Editor.
Control Arguments:
-abort_severity N, -asv N |
Abort the translation if an error of severity N or greater |
occurs. Abort severity can be set to values from 0 to 3. The |
default abort severity is 3. If the abort severity is set to |
0. No output file will be generated if the abort severity is |
set to 0. Execution will continue as long as possible after |
any error up to the point where the final object is created in |
order to provide as much information as possible. Possible |
error severities are: |
1 - WARNING Possible error but not serious. |
2 - ERROR Recoverable error. |
3 - FATAL ERROR Unrecoverable error. |
4 - IMPLEMENTATION ERROR Error in the linkage editor. |
Causes immediate abort. |
-auto_segnames, -asn |
generates a segname definition on the containing component for |
each entrypoint definition in the component. This allows |
references which only refer to the entrypoint name to be |
located properly regardless of the name of the object module |
which contain them. (Default) |
-component_size pages, -compsz pages
specifies the maximum number of pages which a single component
of the output object should contain. This value is used to
determine at what point the transition is made from single
segment to multisegment file and the size of an individual MSF |
component. If this control argument is not specified, a value
of 255 pages is used.
-delete {starname}, -dl {starname} |
deletes the matching entrypoints from the output binary. If |
no starname is given, all entrypoints will be deleted, with |
the exception of the definition for "main_" and its associated |
segnames, if present. This definition can be removed with an |
explicit -delete main_ control argument. For a further |
explanation of definition starnames see the "Notes" section |
below. |
-display_severity N, -dsv N |
Only display errors of severity N or greater. Display |
severity can be set to a value from 1 to 5. The display |
severity defaults to 1. Error severities are: |
1 - WARNING Possible error but not serious. |
2 - ERROR Recoverable error. |
MTB-718 Multics Technical Bulletin
Linkage Editor.
3 - FATAL ERROR Unrecoverable error. |
4 - IMPLEMENTATION ERROR Error in the linkage editor. |
Causes immediate abort. |
A display severity of 5 indicates that no error messages will |
be printed other than the final message if the translation |
failed. |
-force, -fc
suppresses the query before overwriting a non-object segment
or an object segment created by a translator.
-library library_specification, -lib library_specification
specifies one or more object library routines which the
linkage editor will use to resolve external references. The
library specification can be in one of four formats:
Archive
Library archives are unbound archives containing object
segments which may be used to resolve external references. To
specify a library archive, the ".archive" suffix must be
included in the name.
Directory
Library directories may be specified which contain loose
object segments or archives of object segments to which |
external references may be resolved.
Pathname
Pathnames to specific segments or archive components may be
specified.
Starname
Starnames specifying groups of loose segments or archives |
within a directory may be specified, or an archive component |
starname specifying a set of components within a particular
archive.
-list, -ls
create a listing specifying what segments were involved in the
creation of the linked segment, the disposition of each input
component and link, and a list of the retained links and
definitions. The name of the listing segment will be the same
as the output binary with a .list suffix appended.
-map
Create a map of the input components and where they were
placed. The name of the listing segment will be the same as
the output binary with a .list suffix appended.
Multics Technical Bulletin MTB-718
Linkage Editor.
-no_auto_segnames, -nasn |
do not automatically add segnames to the input components to |
correspond to the entrypoints contained in the component. In |
this case the only segname that will be used to locate a link |
target will be the name of the input component. |
-no_force, -nfc
query before overwriting a non-object segment, or an object
created by a translator. (Default)
-no_list, -nls
do not produce a listing segment. (Default)
-no_version, -nvers
do not print out the version of the linkage editor.
-output_file pathname, -of pathname
specifies the pathname of the ouput binary to be created. If
no -output_file argument is given, the output binary will be
created in the working directory with the name a.out. Before
generating the output, the linkage editor will check to insure
that the target either does not exist, or was a binary
produced by the linkage editor prior to overwriting. If the
target is not an object, or is not bound, the user will be |
queried before it is overwritten.
-retain {starname}, -rt {starname} |
specifies entrypoints that should be retained. The entrypoint |
is given in the form segname$entryname. Either the segname or |
entrypoint name portions (or both) may be given as starnames. |
If no -retain or -delete argument is given, all segnames and
entrypoints will be retained. If any -retain arguments are
given, all other entrypoint and segname definitons will be
deleted, with the exception of a "main_" definition which will
always be retained, along with its associated segnames, unless
deleted with an explicit -delete main_ control argument.
-version, -vers
prints out the version of the linkage editor before linking.
(Default)
5.1. Input Paths.
The input paths as given to the linkage_editor specify the names
and order of the input binaries to be used to produce the final
output. They can consist of segments, starnames, archive
components, archive component starnames, entire archives, or
directories.
Given the following set file system entities:
MTB-718 Multics Technical Bulletin
Linkage Editor.
dir
a directory containing the files x, y, and the archive |
z.archive containing components i and j. |
file1
a single segment object segment.
archive.archive
an archive containing the components a, b, c.1, and d.1
The following examples show which binaries are selected for each
input path given:
le file1
selects only the single segment object file1.
le dir
selects the single segment binaries x, y, and the components |
i and j from the archive z.archive in the directory dir. |
le archive.archive
selects the components a, b, c.1, and c.2.
le dir>*
selects the files x and y from the directory dir.
le archive::*.1
selects the components c.1 and d.1 from the archive called
archive.archive.
After each of the input files has been selected, they are checked
to insure that they actually are executable binaries. If any of
the specified input files are not valid binaries, an error
message is printed and the run continues. |
5.2. Libraries.
The specification of libraries uses the same conventions and
methods as the input path evaluation to determine which
segments/archive components are available for use as library
targets. This makes construction of a library simple as there is
no standard format. A library can be a directory full of loose
executable binaries, an archive, or even a single segment. The
primary difference between an input binary specified via
input_paths and one specified as a library component, is that
library components are included only if they are referenced by
either an input_path component or an already referenced library
component.
Multics Technical Bulletin MTB-718
Linkage Editor.
5.3. Output.
The output from the linkage editor will be either an executable
single segment binary, similar to what is currently produced by
the binder, or, if the size of the output exceeds the maximum
size specified by the -component_size control argument, an MSF |
with components of the specified size. |
5.4. Map/List Output.
The -map and -list control arguments will create a segment
containing a description of what was done in the linkage_editor.
They differ primarily in the level of detail provided.
-map
Produces a map of the input binaries, where they came from
(explicit path, extracted from a library, which library,
etc), where they were placed (in the case of an object MSF) |
as well as the other information contained in the bind map.
-list
Produces a more detailed description of the transformations
done to the input. All of the information provided by -map
is included as well as a list of the retained external
definitions and links, and a description of the resolution
of each external link on a component-by-component basis.
Two list will be produced:
- the links for each component that were resolved and
where they were resolved to.
- the links for each component that were left external.
6. Link Editor Implementation
The following section discusses how the Link Editor will be
implemented on Multics. This discussion will be broken down into
a general implementation description and more detailed sections
on certain aspects of the linkage_editor which are different from
existing applications.
6.1. General Implementation
The generation of the linked segment/MSF from the given input |
will be done in discrete stages as follows:
MTB-718 Multics Technical Bulletin
Linkage Editor.
6.1.1. Command Processing.
- Parse the command line extracting the input paths, library
paths, and options.
- derive pointers to each input component and library
component as described above.
6.1.2. Link and Library Resolution.
- Extract the definition information from each of the input
components.
- Extraction of all type-4 links from the named objects to
determine what inter-component linkages are present. Each
link target is determined at this time.
- Any links which remain external are then applied to the
libraries to determine whether they can be satisfied there.
- If they can the target of the link is added to the component
list. The last 4 steps are repeated for the new input
components until no more links can be resolved within the
libraries.
6.1.3. External Initialization Resolution.
- Extract all *system and *heap links from the input
components and resolve their initialization infos into a
single init_info.
- Determine which of the input components will contain this
info, and therefor which output component, if the output is
an MSF. |
6.1.4. MSF Partitioning. |
- Determine the size of the resulting object. If it is larger |
than the maximum size limit specified for a single segment, |
partition the input objects into MSF components. |
6.1.5. Component Processing.
- For each output component:
- Copy the text section, performing relocation as required.
This process will also generate most of the linkage section
and parts of the definition section in the form of tables.
- Extract all the *system and *heap links found in the input
for this component and insure that they are regenerated
regardless of whether they are referenced.
- Emit the definition list. If the output is to be an MSF |
Multics Technical Bulletin MTB-718
Linkage Editor.
component, emit the msf_map indicating the number of |
components and the component being emitted.
- Copy and relocate the symbol section, truncating to remove
the old relocation information.
- Close the object, generating the definition section, linkage
section, and object map from previously emitted information.
6.1.6. Output Backpatching.
- When all of the components have been generated, various
back-patches will be applied to fill in values which could
not be calculated at the time the output components were
created (such as an offset into another component which had
not yet been created.)
6.1.7. MSF Transfer Vector Creation. |
- If the output consists of more than 1 component, we now
create component 0. Component 0 contains indirect
definitions for each retained entrypoint, constituting a
transfer vector through a partially-snapped link to the
actual entrypoint.
MTB-718 Multics Technical Bulletin
Linkage Editor.
6.2. Library Link Resolution.
If library specifications are supplied, external links which
cannot be resolved within the input binaries may be resolved in
the libraries. The process of library resolution is performed
recursively after all the links which can be resolved within the
existing set of binaries is completed. After all links which can
be resolved internally have been found, the remaining external
links are scanned looking for links which can be resolved to
binaries within the libraries. Those library routines which
satisfy some outstanding external link are added to the set of
input binaries. Note that only those library routines which
satisfy some link are included. This process of resolving links
internally, and then scanning the libraries is continued
recursively until a pass over the libraries cannot resolve any
more links.
6.3. Object Creation Utilities.
In order to facilitate the creation of the output object
segments/MSF components, a set of object utilities will be |
created to perform many of the standard functions necessary in
the creation of an object segment. This represents a base level
implementation which can be extended to meet the needs of
compilers.
Multics Technical Bulletin MTB-718
Linkage Editor.
6.3.1. ocu_$open
dcl ocu_$open entry (char (*), char (*), bit (*), ptr,
fixed bin (35));
call ocu_$open (dir_name, entry_name, flags, ocu_datap, code);
Function:
Allocates and initializes the data structures used to create
the object segment and returns a pointer used to locate the
structures.
Arguments:
dir_name
is the name of the directory in which the final object will
be created. (Input)
entry_name
is the entry name of the output object segment. (Input)
flags
is a bit string indicating various options to be used in the
creation of the object segment. (Input)
The following values may be used to derive the desired flag
value. (found in ocu_dcls.incl.pl1)
OPEN_FLAGS_BOUND = "10000"b
The object being created will have the format of a
bound object (ie. one containing multiple
translator produced objects) and is formatted
according to the standards for bound objects.
This format is not enforced by ocu_ and it is the
responsibility of the caller to set up the object
properly.
OPEN_FLAGS_RELOCATABLE = "01000"b
The object being created has relocation
information and can be used as input to the binder
or linkage editor. This flag is used by ocu_ to
determine whether or not to add the relocation
information to the linkage section of the object
segment when the object is closed.
OPEN_FLAGS_PROCEDURE = "00100"b
The object contains executable code.
OPEN_FLAGS_SEPARATE_STATIC = "00010"b
The object segment is to contain a static section
rather than have the static section included in
the linkage section. This flag is examined by
ocu_ when closing the object segment to determine
MTB-718 Multics Technical Bulletin
Linkage Editor.
relocation of static and linkage section
references and to generate the sections properly.
OPEN_FLAGS_PERPROCESS_STATIC = "00001"b
The static section of this object segment is not
to be duplicated when called from within a run
unit.
ocu_datap
is a pointer to the ocu data structures used by the other
calls. (Output)
code
is a standard status code. (Output)
Multics Technical Bulletin MTB-718
Linkage Editor.
6.3.2. ocu_$close
dcl ocu_$close entry (ptr, fixed bin (35));
call ocu_$close (ocu_datap, code);
Function:
takes the information provided by previous calls to ocu_ and
assembles the final object segment. The relocation
information, object_map, linkage header, definition string
map, hash table, and header are synthesized at this point.
Arguments:
ocu_datap
is a pointer returned by ocu_$open. This identifies all the
data structues needed to create the object segment. (Input)
code
is a standard status code. (Output)
MTB-718 Multics Technical Bulletin
Linkage Editor.
6.3.3. ocu_$release |
|
dcl ocu_$release entry (ptr); |
call ocu_$release (ocu_datap); |
|
Function: |
releases the temporary storage used by ocu_. This entrypoint is |
designed to be called by a cleanup handler to release storage in |
the event of an unexpected release. |
Arguments: |
|
ocu_datap |
is a pointer returned by ocu_$open. This identifies all the |
data structues needed to create the object segment. (Input) |
Multics Technical Bulletin MTB-718
Linkage Editor.
6.3.4. ocu_$emit_text
dcl ocu_$emit_text entry (ptr, ptr, ptr,
fixed bin (18) unsigned)
returns (fixed bin (18) unsigned);
text_relp = ocu_$emit_text (ocu_datap, textp, relocationp,
word_count);
Function:
emits a block of text words, appending them to the end of
the text section and returning the offset within the text
section. Errors encountered are reported using the sub_err_
subroutine.
Arguments:
ocu_datap
is a pointer returned by ocu_$open. This identifies all the
data structues needed to create the object segment. (Input)
textp
is a pointer to an array of text words of dimension
(word_count) to be appended to the text section. (Input)
relocationp
is a pointer to a character string of length (2*word_count)
representing the relocation information associated with the
text array. (Input)
The characters used are the standard character relocation
codes used by the translators. (see the Multics Programmers
Reference Manual). This string is required regardless of
whether the output object is to be relocatable since it is
used to relocate linkage and static references if the static
section is not separate.
word_count
is the number of words of text to be emitted. (Input)
text_relp
is an offset to this block of words relative to the base of
the section. (Output)
MTB-718 Multics Technical Bulletin
Linkage Editor.
6.3.5. ocu_$emit_definition
dcl ocu_$emit_definition entry (ptr, char (*) varying,
fixed bin (3), fixed bin (18) unsigned,
bit (*)) returns (fixed bin (18) unsigned);
def_relp = ocu_$emit_definition (ocu_datap, name, section,
offset, flags);
Function:
Emits a single non-class-3 definition, and threads it into
the definition list. Definitions are threaded in the order
of the calls to ocu_$emit_definition and ocu_$emit_segname.
Successive calls to emit_segname generate multiple segnames
in a single block. Calls to emit_segname with intervening
calls to emit_definition create a new block.
Arguments:
ocu_datap
is a pointer returned by ocu_$open. This identifies all the
data structues needed to create the object segment. (Input)
name
is the name of the definition. (Input)
section
is the section that the definition refers to. (Input)
Constants for the sections can be found in
definition_dcls.incl.pl1. Valid sections for this
subroutine are:
SECTION_TEXT = 0
SECTION_LINK = 1
SECTION_SYMBOL = 2
SECTION_STATIC = 4
offset
is the offset of the target of the definition within the
given section. (Input)
flags
is a bit string representing the flags to be set in the
definition. (Input)
Constants definition the values can be found in
ocu_dcls.incl.pl1.
DEFINITION_FLAGS_IGNORE = "1000"b
DEFINITION_FLAGS_ENTRY = "0100"b
DEFINITION_FLAGS_RETAIN = "0010"b
DEFINITION_FLAGS_INDIRECT = "0001"b
Multics Technical Bulletin MTB-718
Linkage Editor.
def_relp
is an offset to the generated definition relative to the
base of the definition section. (Output)
MTB-718 Multics Technical Bulletin
Linkage Editor.
6.3.6. ocu_$emit_segname
dcl ocu_$emit_segname entry (ptr, char (*) varying, bit (*))
returns (fixed bin (18) unsigned);
def_relp = ocu_$emit_segname (ocu_datap, name, flags);
Function:
Emits a single class-3 (segname) definition, and threads it
into the definition list. The definitions are chained in
the order of calls to ocu_$emit_definition and
ocu_$emit_segname. Sequential calls to emit_segname
generate multiple segnames in a single block. A call to
emit_segname after calls to emit_definition starts a new
block. It is invalid to call emit_definition without
calling emit_segname at least once.
Arguments:
ocu_datap
is a pointer returned by ocu_$open. This identifies all the
data structues needed to create the object segment. (Input)
name
is the name of this segname definition. (Input)
flags
is a bit string representing the flags to be set in the
definition. (Input)
Constants definition the values can be found in
ocu_dcls.incl.pl1.
DEFINITION_FLAGS_IGNORE = "1000"b
DEFINITION_FLAGS_ENTRY = "0100"b
DEFINITION_FLAGS_RETAIN = "0010"b
DEFINITION_FLAGS_INDIRECT = "0001"b
def_relp
is an offset to the generated definition relative to the
base of the definition section. (Output)
Multics Technical Bulletin MTB-718
Linkage Editor.
6.3.7. ocu_$emit_msf_map |
dcl ocu_$emit_msf_map (ptr, fixed bin (15) unsigned, |
fixed bin (15) unsigned); |
call ocu_$emit_msf_map (ocu_datap, component_count, |
my_component); |
Function:
Emits the msf_map in the definition section of the new |
object. This entrypoint should ONLY be called if the object |
segment being generated is an MSF component. Errors |
encountered are reported using calls to the sub_err_
subroutine.
Arguments:
ocu_datap
is a pointer returned by ocu_$open. This identifies all the
data structues needed to create the object segment. (Input)
component_count
is the number of components in the MSF, including component |
0. (Input)
my_component
is the number of the component being generated in the range
0 to component_count - 1. (Input)
MTB-718 Multics Technical Bulletin
Linkage Editor.
6.3.8. ocu_$emit_static
dcl ocu_$emit_static entry (ptr, ptr, fixed bin (18) unsigned,
returns (fixed bin (18) unsigned);
static_relp = ocu_$emit_static (ocu_datap, staticp, word_count);
Function:
Emits a block of words which are appended to the static
section. Since there is no relocation info for the static
section (and it is forced to be absolute if it is contained
in the linkage section), no relocation information is
required. Note that even if the static section is to be
contained in the linkage section, references to the static
section should be made with static relocation info and not
attempt to adjust the offsets for the presence of the
linkage header. when the new object is closed, all static
references will be mapped into the appropriate linkage
references.
Error encountered are reported using the sub_err_
subroutine.
Arguments:
ocu_datap
is a pointer returned by ocu_$open. This identifies all the
data structues needed to create the object segment. (Input)
staticp
is a pointer to an array or words of dimension (word_count)
to be appended to the static section. (Input)
word_count
is the number of words to be appended to the static section.
(Input)
static_relp
is the offset of the block or words relative to the base of
the static section
Multics Technical Bulletin MTB-718
Linkage Editor.
6.3.9. ocu_$emit_link
dcl ocu_$emit_link entry (ptr, fixed bin (3), fixed bin (3),
char (*) var, char (*) var, fixed bin, bit (6), ptr)
returns (fixed bin (18) unsigned);
link_relp = ocu_$emit_link (ocu_datap, type, class, segname,
offsetname, expression, modifier, init_infop);
Function:
Creates a single external link. The expression word,
type_pair, segname and offsetname strings, and any
trap_words or external initialization information in the
definition section are also generated as required. Errors
encountered are reported using the sub_err_ subroutine.
Arguments:
ocu_datap
is a pointer returned by ocu_$open. This identifies all the
data structues needed to create the object segment. (Input)
type
is the type of the link. Constants for the valid link types
can be found in definition_dcls.incl.pl1. Valid valued are:
LINK_SELF_BASE = 1
LINK_REFNAME_BASE = 3
LINK_REFNAME_OFFSETNAME = 4
LINK_SELF_OFFSETNAME = 5
class
is the class of the link for type 1 (link self base) and
type 5 (link self offsetname). This indicates what section
of the object segment the expression value is relative to.
It is used only if the type is 1 or 5. Constants usable for
this value are declared in definition_dcls.incl.pl1. Valid
values are:
CLASS_TEXT = 0
CLASS_LINKAGE = 1
CLASS_SYMBOL = 2
CLASS_STATIC = 4
CLASS_SYSTEM = 5
CLASS_HEAP = 6
MTB-718 Multics Technical Bulletin
Linkage Editor.
segname
is the segname of the link target. This field is only used
if the type of the link is type 3 (link-refname-base) or
type 4 (link-refname-offsetname). This is the refname that
will be used to search for the segment when the link is
snapped. (Input)
offsetname
is the name of the definition to be searched for when the
link is snapped. This field is only used if the link type
is type 4 (link-refname-offsetname) or type 5
(link-self-offsetname). (Input)
expression
is a word offset to be added to the offset derived from the
section and offsetname values. (Input)
modifier
is the modifier of the link. This is the modifier that will
be present in the pointer representing the snapped link.
Generally a null modifier (""b) is used. (Input)
init_infop
is a pointer to the initialization info, or to a trap_pair.
(Input)
If the link is a type 5, class 5 link (a *system or external
link). This points to an initialization info block which
will be placed into the definition section. This can point
to any type of standard initialization info (INIT_NO_INIT,
INIT_COPY_INFO, INIT_DEFINE_AREA, INIT_LIST_TEMPLATE, or
INIT_DEFERRED if the object segment being created is an MSF |
component.) If the link is not a *system link, a non-null |
value will be assumed to point to a trap-pair representing a
trap-before-link. Since trap-before-links are generally
obsolete, this should only be non-null when supplying
initialization_info for *system links.
link_relp
is the offset of this link relative to the base of the
linkage section. Note that the link offset returned is the
location of the link assuming there is no linkage-resident
static section. When the object is closed (via a call to
ocu_$close) all link references will be relocated to account
for the presence of a static section. If you plan to use
this returned link offset for purposes other than to store
in one of the other object sections, you will have to adjust
for the static section manually.
Multics Technical Bulletin MTB-718
Linkage Editor.
6.3.10. ocu_$emit_partial_link
dcl ocu_$emit_partial_link entry (ptr, fixed bin (15) unsigned,
fixed bin (3), fixed bin (18) unsigned, bit (6))
returns (fixed bin (18) unsigned);
link_relp = ocu_$emit_link (ocu_datap, component, section,
offset, modifier);
Function:
Emits a partially snapped link. A partially snapped link
uses no information in the definition section, and is
snapped before entry by a first reference trap. This
entrypoint should ONLY be called when generating an MSF |
component. Errors are reported using the sub_err_ |
subroutine.
Arguments:
ocu_datap
is a pointer returned by ocu_$open. This identifies all the
data structues needed to create the object segment. (Input)
component
is the component number of the target component within the
MSF. Generally this will be in the range 1 to the maximum |
component number. (Input)
section
is the target section of the link within the target MSF |
component. (Input) Constants for these values can be found |
in definition_dcls.incl.pl1. Valid values are:
SECTION_TEXT = 0
SECTION_LINKAGE = 1
SECTION_SYMBOL = 2
SECTION_STATIC = 4
offset
is the offset of the pointer. This value is relative to the
base of the section specified by the section parameter.
(Input)
modifier
is the modifier of the link. This will also be the modifier
of the pointer generated by snapping the link. The null
modifier (""b) is generally used. (Input)
MTB-718 Multics Technical Bulletin
Linkage Editor.
link_relp
is the offset of the generated link relative to the base of
the linkage section. Note that this value is calculated as
if there were no static section resident in the linkage
section. When the object is closed (via a call to
ocu_$close) all linkage references are relocated to adjust
for the presence of a static section. If the caller wishes
to use this value for other purposes that to include in
another call to ocu_, it will have to be adjusted for the
presence of the static section manually. (Output)
Multics Technical Bulletin MTB-718
Linkage Editor.
6.3.11. ocu_$emit_firstref_trap
dcl ocu_$emit_firstref_trap entry (ptr, fixed bin (18) unsigned,
fixed bin (18) unsigned);
call ocu_$emit_firstref_trap (ocu_datap, call_relp, info_relp);
Function:
Adds a firstref trap to the first reference trap block in
the linkage section. The links reference by the call_relp
and info_relp must have already been emitted. Errors
encountered are reported using the sub_err_ subroutine.
Arguments:
ocu_datap
is a pointer returned by ocu_$open. This identifies all the
data structues needed to create the object segment. (Input)
call_relp
is the offset relative to the base of the linkage section of
a link to be used to call the trap procedure. (Input)
info_relp
is the offset relative to the base of the linkage section of
a link to be passed to the trap procedure. If this value is
0, no parameter will be passed to the trap procedure.
(Input)
MTB-718 Multics Technical Bulletin
Linkage Editor.
6.3.12. ocu_$emit_symbol
dcl ocu_$emit_symbol entry (ptr, ptr, ptr,
fixed bin (18) unsigned)
returns (fixed bin (18) unsigned);
symbol_relp = ocu_$emit_symbol (ocu_datap, symbolp,
relocationp, word_count);
Function:
Emits a block of symbol words and appends them to the symbol
section. Errors encountered are reported using the sub_err_
subroutine.
Arguments:
ocu_datap
is a pointer returned by ocu_$open. This identifies all the
data structues needed to create the object segment. (Input)
symbolp
is a pointer to an array symbol section words of dimension
(word_count) to be appended to the symbol section. (Input)
relocationp
is a pointer to a character string of length (2*word_count)
representing the relocation information for the accompanying
block of words. (Input)
The relocation characters are taken from the set of standard
characters used by language translators (see the Multics
Programmers Reference Manual). The relocation string is
required even if the object to be generated is not
relocatables since the relocation information is used to
locate static and linkage references which will have to be
relocated if the static section is linkage resident.
word_count
is the number of symbol words to be emitted. (Input)
symbol_relp
is the offset of this block of words relative to the base of
the symbol section. (Output)
Multics Technical Bulletin MTB-718
Linkage Editor.
6.3.13. ocu_$backpatch
dcl ocu_$backpatch entry (ptr, char (*),
fixed bin (18) unsigned, char (*), fixed bin (35);
call ocu_$backpatch (ocu_datap, section, offset, side,
new_value);
Function:
It is often necessary in the creation of an object segment
to generate a reference to something which has not been
emitted yet. This entrypoint allows changes to be made in a
word which has already been emitted. Since many sections of
the object segment are being synthesized by ocu_ from other
information, it is not practical to patch them. (eg. the
definition section contains type_pairs, expression_words,
init_info, and ACC_strings generated as byproducts of link
generation. The offsets of these items are not known until
the object is closed.) This entry is primarily for patching
sections which were emitted as blocks of words. (ie. text,
static, and symbol sections.)
Arguments:
ocu_datap
is a pointer returned by ocu_$open. This identifies all the
data structues needed to create the object segment. (Input)
section
is a character identifying the section to be patched.
(Input)
Valid values for this argument are:
"text" - to patch the text section.
"static" - to patch the static section.
"symbol" - to patch the symbol section.
offset
is the word offset within the given section of the halfword
to be patched. (Input)
side
is a string indicating what portion of the specified word is
to be patched. (Input)
Valid values depend on the section being patched and
correspond to the valid types of relocation allowed for that
section.
- Text section
"left 15 unsigned"
"left 15 signed"
"left 18 unsigned"
"left 18 signed"
MTB-718 Multics Technical Bulletin
Linkage Editor.
"right 18 unsigned"
"right 18 unsigned"
- Static section
"left 18 unsigned"
"left 18 signed"
"right 18 unsigned"
"right 18 signed"
- Symbol section
"left 18 unsigned"
"left 18 signed"
"right 18 unsigned"
"right 18 signed"
new_value
is the new value to be patched into the specified portion of
the word. (Input)
Multics Technical Bulletin MTB-718
Linkage Editor.
6.3.14. ocu_$create_msf |
dcl ocu_$create_msf entry (ptr, fixed bin (15) unsigned, |
ptr, fixed bin (35)); |
call ocu_$create_msf (component_listp, component_count, |
gen_infop, code); |
Function:
Creates component 0 of the MSF. Given an array of pointers |
to all of the components of the MSF (excepting component 0), |
generates component 0, copying the external definitions, and |
building the first reference trap.
Arguments:
component_listp
is a pointer to an array of pointers of dimension
(1:component_count-1). (Input)
Each pointer points to one component of the MSF. Each of |
the pointers points to a completed object segment. It is |
assumed that each of the components already has it's linkage |
section built as an MSF component (ie. containing |
appropriate partially-snapped links) and that the msf_map is |
present in the definition section. |
component_count
is the number of components in the final MSF not counting |
component 0. (Input)
gen_infop
is a pointer to the gen_info structure used to set the
generator_info in the symbol header of component 0. (Input)
The gen_info structure is declared in the include file
ocu_dcls.incl.pl1.
dcl 01 gen_info aligned based,
02 gen_created fixed bin (71),
02 generator char (8),
02 gen_number fixed bin,
02 gen_version char (512) varying;
gen_created
is the clock time that the generator was created.
generator
is the name of the generator (eg. PL/I, binder, etc.).
gen_number
is the version number of the generator. This value
must the version number if the gen_version string.
MTB-718 Multics Technical Bulletin
Linkage Editor.
gen_version
is a version string giving the name, version, and date
of the generator (eg. Multics PL/I Compiler, Release
28e, of February 14, 1985)
code
is a standard status code. (Output)
Multics Technical Bulletin MTB-718
Linkage Editor.
6.4. Object Multi-Segment Files. |
The linkage editor will handle object MSFs as output. In this |
case, special handling is required in order to compensate for the |
multi-segment format. When it is determined that there is |
sufficient input to require that an MSF be produced, the linkage |
editor will partition the input binaries into output components.
No form of optimization will be done at this stage to determine
which input binaries are placed together. This must be done by
the user specifying the order. An optimization stage could be
placed here at a later time if it it found to be sufficiently
desirable. These components are then each processes in the same
way that a single-segment output would be except that when an
inter-component reference is encountered, a partially snapped
link is generated, and if necessary, a backpatch record so that
the proper link offset can be inserted when the target component
is processed. The only other difference in processing is the
inclusion of the msf_map, and the final call to ocu_$create_msf |
to build component 0.