6502/wdc-utils
1
0
Fork 0
mirror of https://github.com/ksherlock/wdc-utils.git synced 2025-01-19 08:30:01 +00:00
Code Issues Projects Releases Wiki Activity

man page updates.

Browse Source
This commit is contained in:
Kelvin Sherlock 2016-12-29 15:32:47 -05:00
parent 7a2168afc7
commit 1f1577d0d4
4 changed files with 404 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
wdclib.1
View File

@ -3,7 +3,7 @@
.Os
.Sh NAME
.Nm wdclib
.Nd WDC Librarian
.Nd WDC librarian
.Sh SYNOPSIS
.Nm
.Op Fl F Ar argfile
@ -114,6 +114,7 @@ name. After extraction, the modules in the library are deleted.
The following example extracts two files from a library.
.Pp
.Dl WDCLIB -X MYLIB.LIB LIBSRC3.OBJ LIBSRC1.OBJ
.El
.Sh SEE ALSO
.Xr wdc02as 1 ,
.Xr wdc02cc 1 ,

397
wdcln.1 Normal file
View File

@ -0,0 +1,397 @@
.Dd December 28, 2016
.Dt WDCLN 1
.Os
.Sh NAME
.Nm wdclib
.Nd WDC linker
.Sh SYNOPSIS
.Nm
.Op Fl BEGNQTVWX
.Op Fl Hxx
.Op Fl Mxx
.Op Fl Sxx
.Op Fl O Ar output
.Op Fl Zsec=XX,XX
.Op Fl Asec=XX,XX
.Op Fl C=XX,XX
.Op Fl D=XX,XX
.Op Fl K=XX,XX
.Op Fl U=XX,XX
.Op Fl F Ar argfile
.Op Fl L Ar library
.Op Ar objfile ...
.Sh DESCRIPTION
The WDC linker,
.Nm ,
reads one or more object files and/or libraries and merges them into a
singleoutput file. References from one module to another are resolved
during the link. The linker operates in two passes. In the first pass,
each object module is scanned to determine what symbols are defined and
what symbols are referenced. Symbols that are defined are entered into a
symbol table. When other object modules want the address of a symbol they
will look in the symbol table. If the symbol is not in the symbol table
it is added to a list of undefined symbols. If a later module defines the
symbol it is removed from the undefined list. If a library is encountered,
it's dictionary is repeatedly scanned for any symbols that match any of
the symbols in the undefined list. If such a symbol is found, the module
that defines it is loaded from the library and its symbols are handled
just like a normal object module. Through this process, only object modules
that are needed are loaded from the library. Libraries are usually placed
at the end of the list of object files. At the end of the first pass, all
undefined symbol references should be resolved. During the second pass,
the linker reads each object module a second time. As it reads each
module, it generates the final output file based on the information in
the object module.
.Sh OPTIONS
.Bl -tag -width indent
.It Fl A
This option is used to specify the relocation and ROM address of the named
section. The option is followed by information in the following format:
.Pp
.Dl Fl A Ns Ar section Ns = Ns Op Ad XXXX Ns Op , Ns Ad XXXX
.Pp
where section is the name of the section to be located. The section name
is followed by an
.Ql =
sign which in turn is followed by the relocation
address and ROM address separated by a comma. All addresses are assumed
to be hexadecimal numbers. If the comma and ROM address are not present,
it is assumed that the relocation address will be used for the ROM address
as well. If the comma is present and either the relocation address or
the ROM address is missing, then the specified address is assumed to be
the end of the previously specified section.
.It Fl B
This option is used to create a file with the same root name as the output
file and with the extension
.Pa .BNK .
This file is similar to the map file and contains bank information.
.It Fl C
This option is used to specify the relocation address and the ROM address
of the predefined CODE section. The format is:
.Pp
.Dl Fl C Ns Op Ad XXXX Ns Op , Ns Ad XXXX
.Pp
which is similar to the
.Fl A
option without the section name.
.It Fl D
This option is used to specify the relocation address and the ROM address
of the predefined DATA section. The format is:
.Pp
.Dl Fl D Ns Op Ad XXXX Ns Op , Ns Ad XXXX
.Pp
which is similar to the
.Fl A
option without the section name.
.It Fl E
This option is used to create a file with the same root name as the output
file and with the extension
.Pa .ERR .
This file contains any warnings or error messages generated during the link.
.It Fl F
This option causes the linker to continue reading options and file names
from a file. When done, it then continues reading arguments from the command
line. The name of the file follows the option
.Fl F .
Lines beginning with a
.Ql #
character are ignored. For example, the following
command links
.Pa PROG.OBJ
with
.Pa SUB1.OBJ , ... , SUB4.OBJ ,
and
.Pa TC.LIB .
It reads some arguments from the file
.Pa PROG.LNK :
.Pp
.Dl Nm Pa PROG.OBJ Fl F Ar PROG.LNK Pa TC.LIB
.Pp
where
.Pa PROG.LNK
contains:
.Bd -literal -offset indent
-O PROG.OUT
SUB1.OBJ
SUB2.OBJ
SUB3.OBJ
SUB4.OBJ
.Ed
.Pp
.Em WARNING:
There is a limit of 5000 files for the source level information
contained in reading file names from a file (Include files are counted
in this total).
.It Fl G
This option tell the linker to generate source level information. When
specified by itself with no additional symbol style option, the WDC symbol
file format is generated. Otherwise, if the
.Fl SN
Extended MicroTek symbol format option is specified, the source information
is added as special records.
.It Fl H
This option is used to select the format of the hex output file. Four formats
are currently supported. The following table shows the name of the format,
the option used to generate it, address field size.
.Pp
.Bl -column "Option" "File" "Size" "Format"
.It Sy "Option" Ta Sy "File" Ta Sy "Size" Ta Sy "Format"
.It Fl HB Ta Pa .BIN Ta -- Ta Straight Binary
.It Fl HI Ta Pa .HEX Ta 16 Ta Intel Hex
.It Fl HIE Ta Pa .HEX Ta 32 Ta Extended Intel Hex
.It Fl HM19 Ta Pa .S19 Ta 16 Ta Motorola S19
.It Fl HM28 Ta Pa .S28 Ta 24 Ta Motorola S28
.It Fl HM37 Ta Pa .S37 Ta 32 Ta Motorola S37
.It Fl HN Ta Pa .ISX Ta 24 Ta Nintendo Binary
.It Fl HT Ta Pa .TEK Ta 16 Ta Tektronix Hex
.It Fl HZ Ta Pa .BIN Ta 24 Ta WDC Binary
.El
.Pp
The following binary format is generated if
.Fl HZ
is specified to the linker:
.Pp
.Bl -inset -compact -offset indent
.It Initial byte 'Z' as signature.
.El
Then for each block:
.Bl -inset -compact -offset indent
.It 3 byte address
.It 3 byte length length bytes of data
.It The final block has an address and length of 0.
.It The default is Motorola S19.
.El
.It Fl J
This option causes the module info to be placed in alphabetical order.
By default, module info is sorted by section.
.It Fl K
This option is used to specify the relocation address and the ROM address
of the predefined KDATA section. The format is:
.Pp
.Dl Fl K Ns Op Ad XXXX Ns Op , Ns Ad XXXX
.Pp
which is similar to the
.Fl A
option without the section name.
.It Fl L
This option takes the following characters and adds
.Pa .LIB
to form the name of the library. The default library directories specified
in the
.Ev WDC_LIB
environment variable are then searched for the fully defined file name.
.Pp
For example, the command:
.Pp
.Dl Nm Fl J Fl L Ns Ar CL
.Pp
will look for the file
.Pa CL.LIB .
.Pp
.Em Note:
The order of the libraries is important! The linker will pull in the
functions it needs from the
.Em first
library it sees. For example,
the following command:
.Pp
.Dl Nm Pa Sample.obj Fl L Ns Ar MS Fl L Ns Ar CS
.Pp
will pull in the
.Fn scanf
and
.Fn printf
functions from the floating point library as it is specified first. This
will result in larger code size! Therefore, If you are using floating
point math, put
.Fl L Ns Ar MS
before
.Fl L Ns Ar CS
so the proper functions are included.
.Pp
If you are NOT using floating point math, do not include
.Fl L Ns Ar MS
on the command line, or put it after
.Fl L Ns Ar CS
.Pp
.Em Note:
For the W65C02, use
.Pa c.lib
and/or
.Pa m.lib .
For the W65C816, use
.Pa coc.lib , col.lib , com.lib , ms.lib , mm.lib , mc.lib , ml.lib ,
.Pa cs.lib , cm.lib , cc.lib ,
and/or
.Pa cl.lib.
.It Fl M
This option is used to select a special machine mode. Currently, the only
available machine modes are
.Fl MN , MN80 ,
and
.Fl MN21
which stand for Nintendo, slow and fast, and Nintendo Mode 21 respectively.
.It Fl N
If this option is specified, the linker will not place any symbols defined
in a
.Pa .QCK
file into the symbol file. This is useful if the
.Pa .QCK
file is created from a large amount of data whose symbols are not required
after linking. The symbol file can be significantly smaller if the data
symbols are discarded.
.It Fl O
Option
.Fl O
can be used to specify the name of the file to which the linker is to
write the executable program. The name of this file is in the parameter
that follows
.Fl O .
For example, the following command writes the executable program to the
file
.Pa PROG.OUT :
.Pp
.Dl Nm Fl O Ar PROG.OUT Pa PROG.OBJ Pa TC.LIB
.Pp
If this option is not used, the linker derives the name of the executable
file from that of the first input file with the extension changed to
reflect the type of hex file being generated.
.It Fl P
This option sets the fill characters in the hex output file. The default,
(no
.Fl P Ns No ),
does not add any fill characters to the hex output file. If this option is
specified as
.Fl PFF ,
it will fill in the blank areas of the hex output file with
.Li $FF Ns \(aqs
(all 1\(aqs). If this option is specified as
.Fl P00 ,
it will fill in the blank areas of the hex output file with zeros (0\(aqs).
.It Fl Q
As the linker reads files and modules, it displays the name of each module.
Each subsequent module name overwrites the preceding name. This option
tells the linker not to display module names.
.\"
.\" -S
.\"
.It Fl S
This option controls the generation of symbol file information. By default,
no symbol file is generated. When this option is specified, a symbol file
is generated which can be used to aid in debugging the application.
.Pp
The following table shows the options and the formats generated.
.Pp
.Bl -column "Option" "Format"
.It Sy "Option" Ta Sy "Format"
.It Fl S2 Ta 2500AD symbol format
.It Fl SM Ta MicroTek symbol format
.It Fl SN Ta Extended MicroTek symbol format
.It Fl SQ Ta Quick link object file
.It Fl SZ Ta WDC symbol format
.El
.Pp
The linker supports an extension to the Extended MicroTek symbol file format.
.Pp
The linker generates the following additional symbol records if the
.Fl G
(source level info) option and
.Fl SN
options have been selected.
.Pp
.Bl -tag -width indent -compact
.It 0-9
Standard MicroTek symbol type - global symbols
.It 50-59
Standard MicroTek symbol type - local symbols
.It 101
Single character name that is the status Register as specified by
LONGA/LONGI
directives. In other words, if
LONGA ON
is specified a 101 record will be generated with a
$20 as the ps value.
.It 102
A two character name (low,high) that is the line number associated
with this address.
.It 103
The name is the source file name associated with the object module.
.It 120+N
A zero length name with the address being the starting address for
section N. Section 1 is CODE, section 2 is DATA, section 3 is UDATA.
Other sections can probably be ignored unless you want to handle them.
.It 150+N
A zero length name with the address being the ending address for section N.
.El
.\"
.\" -T
.\"
.It Fl T
This option instructs the linker to generate a text map file with the
extension
.Pa .MAP .
The final address of each symbol is listed.
.It Fl U
This option is used to specify the relocation address and the ROM address
of the predefined UDATA section. The format is:
.Pp
.Dl Fl U Ns Op Ad XXXX Ns Op , Ns Ad XXXX
.Pp
which is similar to the
.Fl A
option without the section name. The UDATA section is a little different
since it never needs to be in the ROM at all since it contains
uninitialized data.
.Fl V
This option displays additional information to the screen giving the names
of variables and their locations.
.It Fl W
This option disables warnings from the linker. The linker will warn if a
symbol defined in a program module overrides a symbol defined in a library
module. This warning is useful for preventing hard to track down errors
such as when the user defines a routine called write that overrides the
library write routine.
.Pp
.Em Note:
This option not used after V3.10
.It Fl X
This option directs the linker to use EMM memory mapping to provide
additional space for linking programs with large numbers of symbols. It
must be the first option specified.
.\" -Z
.It Fl Z
This option is used to specify the top and bottom address to use when
spreading the indicated section of various modules across multiple
banks of memory. The format is:
.Pp
.Dl Fl Z Ns Ar section Ns = Ns Op Cm bottom Ns Op , Ns Cm top
.Pp
The section specified by
.Ar section
will be marked for spreading. The default bottom is
.Ad 0000
and the default top is
.Ad $1:0000 .
If no bottom or top is specified, the default is used. The first byte of
the section is specified using the ROM and relative org directives.
.Pp
The sub-options for
.Fl Z
are:
.Fl Z Ns Ar section Ns = ,
.Fl Z Ns Ar code Ns = ,
and
.Fl Z Ns Ar data Ns = .
.El
.Sh SEE ALSO
.Xr wdc02as 1 ,
.Xr wdc02cc 1 ,
.Xr wdc02op 1 ,
.Xr wdc816as 1 ,
.Xr wdc816cc 1 ,
.Xr wdc816op 1 ,
.Xr wdcdb 1 ,
.\" .Xr wdcln 1 ,
.Xr wdclib 1 ,
.Xr wdcobj 1 ,
.Xr wdcsym 1

9
wdcobj.1
View File

@ -3,13 +3,10 @@
.Os
.Sh NAME
.Nm wdcobj
.Nd Examine object modules
.Nd Examine WDC object modules
.Sh SYNOPSIS
.Nm
.Op Fl D
.Op Fl L
.Op Fl R
.Op Fl S
.Op Fl DLRS
.Ar objfile
.Sh DESCRIPTION
The
@ -65,7 +62,7 @@ modules in the file
.Ar PROG.OBJ :
.Pp
.Dl WDCOBJ -S PROG.OBJ
.Pp
.El
.Sh SEE ALSO
.Xr wdc02as 1 ,
.Xr wdc02cc 1 ,

7
wdcsym.1
View File

@ -3,12 +3,10 @@
.Os
.Sh NAME
.Nm wdcsym
.Nd Examine symbol tables
.Nd Examine WDC symbol tables
.Sh SYNOPSIS
.Nm
.Op Fl A
.Op Fl L
.Op Fl S
.Op Fl ALS
.Ar symfile
.Sh DESCRIPTION
The
@ -46,7 +44,6 @@ The following command displays the section information, and symbols for all
sections and the global symbols as well.
.Pp
.Dl WDCSYM -S PROG.SYM
.Pp
.El
The basic structure of the file is outlined as follows:
.Bl -inset -compact -offset indent