mirror of
https://github.com/antoinevignau/source.git
synced 2025-01-01 15:30:02 +00:00
1 line
13 KiB
Plaintext
1 line
13 KiB
Plaintext
|
|
|
|
S-C Software Corporation
|
|
2331 Gus Thomasson, Suite 125
|
|
P.O. Box 280300
|
|
Dallas, Texas 75228
|
|
(214) 324-2050
|
|
|
|
|
|
|
|
|
|
S-C Cross Reference Utility
|
|
|
|
|
|
The S-C Cross Reference Utility (s-C XREF) generates an alphabetized
|
|
listing of all labels used in a source file, showing with each label
|
|
the line number where it is defined along with all line numbers which
|
|
contain references to the label.
|
|
|
|
|
|
Features:
|
|
|
|
* Written in assembly language for Apple ][, Apple ][ Plus or Apple
|
|
//e computers. Fantastic convenience, speed, and efficiency!
|
|
|
|
* Works with the S-C Macro Assembler, properly handling all
|
|
directives and operand modes.
|
|
|
|
* Compatible with older versions of the S-C Assembler series,
|
|
including S-C Assembler II Versions 3.2 and 4.0.
|
|
|
|
* Optional cross reference of all directives and opcddes used in your
|
|
program.
|
|
|
|
* Optional paginated listing of your source program, for complete
|
|
documentation packages.
|
|
|
|
* Cross reference of all macro calls listed after all labels.
|
|
|
|
* Easy-to-change page length and width parameters.
|
|
|
|
* Full range of line numbers (from 0 through 65535).
|
|
|
|
* Easily-generated EXEC files allow programs consisting of many
|
|
separate files to be processed in sequence.
|
|
|
|
* Appropriate changes to two small opc ode tables permit processing
|
|
of source programs for other CPU chips, in conjunction with most of
|
|
the S-C Macro Cross Assemblers.
|
|
|
|
* Complete commented source code is available to owners of S-C XREF
|
|
for only $32.50 additional (or total price of $50.00 if source and
|
|
object code are purchased together.)
|
|
[ Requires S-C Macro Assembler ]
|
|
|
|
- 1 -
|
|
|
|
---------------------------------------------------------------------
|
|
|
|
Using S-C XREF
|
|
|
|
|
|
S-C XREF is designed to be used from within the normal S-C Assembler
|
|
environment. S-C XREF assumes that the source syntax is consistent
|
|
with the S-C Assembler syntax. We recommend that you assemble the
|
|
source file before running the S-C XREF, to insure that the source is
|
|
error-free. Invalid assembler source lines may cause S-C XREF to
|
|
find strange undefined labels.
|
|
|
|
The S-C XREF program BLOADs into the memory area $800-$FFF. The S-C
|
|
Assemblers normally load at $1000 with the symbol table area
|
|
following the assembler, or at $DOOO with the symbol table area
|
|
starting at $1000. S-C XREF uses the symbol table area for
|
|
developing the cross reference table.
|
|
|
|
1. S-C XREF operates on the assembly language source file currently
|
|
in memory. Therefore the first step is to LOAD your source program:
|
|
|
|
:LOAD filename
|
|
|
|
2. The next step is to load S-C XREF, if it is not already in memory:
|
|
|
|
:BLOAD S-C XREF
|
|
|
|
3. If you wish to change any parameters, now is the time to do it.
|
|
The default values select 55 lines per page, 80 columns per line, no
|
|
source code listing, and no opoode listing. The parameters are in
|
|
the five bytes from $806 through $80A:
|
|
|
|
$806: Lines per page.
|
|
|
|
$807: Printer width in columns.
|
|
|
|
$808: Set non zero to produce an opcode cross reference listing.
|
|
|
|
$809: Set non-zero to produce a paginated listing of your source
|
|
program.
|
|
|
|
$80A: Set to 0 to prevent a Cross Reference listing from being
|
|
generated.
|
|
|
|
For example, to include the opcodes and directives in the listing, type:
|
|
|
|
:$808:1
|
|
|
|
4. If you wish for the cross reference listing to be sent to your
|
|
printer, turn on your printer and type:
|
|
|
|
:PR#slot
|
|
|
|
5. Now execute S-C XREF by typing:
|
|
|
|
:$800G
|
|
|
|
S-C XREF will scan through your source program for a few seconds and
|
|
then begin displaying a paginated cross reference listing of all the
|
|
symbols used in the program. If you selected your printer, the
|
|
listing will be printed. When the listing is finished, control will
|
|
return to the S-C Assembler.
|
|
|
|
6. The listing can be aborted at any time by pressing the RETURN
|
|
key, or paused/restarted with any other key, just as in the S-C Macro
|
|
Assembler. You can single step the listing by tapping two keys at
|
|
once.
|
|
|
|
- 2 -
|
|
|
|
---------------------------------------------------------------------
|
|
|
|
What You Will Get
|
|
|
|
|
|
There are four parts to the cross reference listing:
|
|
|
|
1. Source listing (if enabled).
|
|
2. Opcode mnemonic cross reference (if enabled).
|
|
3. Label cross reference.
|
|
4. Macro call cross reference.
|
|
|
|
1. The source listing (enabled by parameter $809) consists of a
|
|
normal listing, such as produced by the LIST command in the S-C
|
|
Assemblers. The listing will be paginated with page numbers at the
|
|
top-right of each page.
|
|
|
|
2. The opcode mnemonic listing (enabled by parameter $808) is
|
|
separated from the normal label cross reference listing by a line of
|
|
dashes. The opcodes will be listed in alphabetical order, with
|
|
directives first.
|
|
|
|
3. The cross reference listing (enabled by parameter $80A) includes
|
|
all symbols used in your source program, in alphabetical order. Here
|
|
is the format:
|
|
|
|
Columns 1-5 : The line number where a symbol is defined. If a symbol
|
|
appears in the label field of a line, that line number
|
|
will be shown here. If the symbol is not defined in
|
|
the current module then "-----" appears in this field.
|
|
|
|
Columns 8-n : The symbol name (up to 32 characters).
|
|
|
|
Columns n-end: The line numbers in the current source module which
|
|
refer to the symbol. If a symbol has no references
|
|
in the current module then no line numbers will be
|
|
printed.
|
|
|
|
Here is an excerpt from a listing:
|
|
|
|
---- CHRGOT 3340 3830 5570
|
|
3210 COLORTBL 3170
|
|
1110 SHAPE 1800 1910 2170 2830 2960 3090 3530 4770
|
|
7460 11920 12180 12390
|
|
----- SYMBOL.TABLE 2870 12340
|
|
12500 ZZ.SIZE
|
|
|
|
|
|
If there are too many references to fit on one line, the rest are
|
|
listed on following lines beginning in column 11.
|
|
|
|
The symbol cross reference listing will include all uses of the
|
|
indexed addressing modes as references to the symbols "X" and "Y".
|
|
Any labels "X" or "Y" will also appear in the same reference list
|
|
with the indexed addressing references.
|
|
|
|
4. The macro call cross reference listing (also enabled with
|
|
parameter $80A) follows the symbol cross references. The macro calls
|
|
are distinguished by a ">" character in front of the name, and are
|
|
listed in alphabetical order.
|
|
|
|
|
|
|
|
|
|
- 3 -
|
|
|
|
---------------------------------------------------------------------
|
|
|
|
How S-C XREF Works
|
|
|
|
|
|
S-C XREF scans through the source program currently in memory in just
|
|
one pass. If you have selected a paginated source listing it will be
|
|
printqd during this pass. S-C XREF parses each source line into a
|
|
label field, an opcode field, and an operand field. Definitions and
|
|
references are entered into a symbol table in the same memory area
|
|
used by the S-C Assemblers for the Assembly Symbol Table.
|
|
|
|
If there is not enough memory for the symbol table below the source
|
|
program, then a warning message "MEMORY FULL!" is displayed and S-C
|
|
XREF stops execution.
|
|
|
|
1. When a label is found in the label field it is added to the
|
|
symbol table. The current line number is stored in the symbol table
|
|
entry in the definition position. Local labels (.00 - .99) and
|
|
private labels (:00 - :99) are ignored. If the label already has been
|
|
defined then the current line number is entered as a reference to the
|
|
label (because the listing only has room for one definition line
|
|
entry). A label can legally have more than one definition only if it
|
|
is used with a .SE directive, but the Cross Reference program does
|
|
not enforce this rule.
|
|
|
|
2. The opcode field is separated from the label field by at least
|
|
one blank, and ends with a blank or end-of-line. There are five
|
|
classes of opcodes, and each is handled in a distinct way:
|
|
|
|
* Directives
|
|
* Macro Calls
|
|
* Opcodes with no operand field
|
|
* Opcodes with an optional operand field
|
|
* Opoodes with a mandatory operand field.
|
|
|
|
Directives are handled by special directive processors, according to
|
|
the type of data fields which may follow the directive opcode. Some
|
|
have no possible data fields, some have only one, and others have a
|
|
list of data items. The .EN directive will terminate the cross
|
|
reference scan, even if it is not the last line in the source
|
|
program. The .MA directive DEFINES the label in the data field. Any
|
|
directives not in the built-in table will be assumed to have no data
|
|
fields.
|
|
|
|
If the opcode is a macro call it is entered into the symbol table as
|
|
a reference to the macro. If you have selected the optional opcode
|
|
cross reference, the opcode reference will be logged.
|
|
|
|
Two tables of opcode names at the end of S-C XREF list the opcodes in
|
|
categories 3 and 4. Those with no operand field (such as TAX, INY,
|
|
etc.) are listed first. S-C XREF does nothing further with lines
|
|
having any of these opcodes.
|
|
|
|
Opcodes which have an optional operand are the four shifts: ASL, ROL,
|
|
LSR, and ROR. For these ambiguous cases, S-C XREF assumes no operand
|
|
is present if two or more blanks follow the opcode.
|
|
|
|
3. Operand fields are scanned to find any references to normal
|
|
labels. The operand is separated from the opcode by at least one
|
|
blank, and ends with a blank or end-of-line. The operand scanner
|
|
skips over constants, parentheses, operators, and other syntax
|
|
characters to pick out only the normal labels. Local labels (.00 -
|
|
.99), private labels (:00 - :99), and macro parameters (]O - ]9 and
|
|
]#) are ignored. All references to normal labels are duly logged in
|
|
the symbol table.
|
|
|
|
|
|
- 4 -
|
|
|
|
---------------------------------------------------------------------
|
|
|
|
Using S-C XREF with Multiple-File Programs
|
|
|
|
|
|
S-C XHEF can also be used from an EXEC file to generate a Cross
|
|
Reference for a program too large to be all in memory at once. Each
|
|
source file can be LOADed in turn and processed. If you elect to
|
|
generated a source listing at the same time, you can document an
|
|
entire multiple-file program automatically.
|
|
|
|
For example, the following text file can be EXEC1ed to cross
|
|
reference a large system program on two diskettes.
|
|
|
|
BLOAD S-C XREF,A$800
|
|
PR#1
|
|
LOAD EQUATES,D1
|
|
$800G
|
|
LOAD MAIN PROGRAM,D1
|
|
$803G
|
|
LOAD COMMAND HANDLER,D1
|
|
$803G
|
|
LOAD SCAN TEXT,D2
|
|
$803G
|
|
LOAD TABLES,D2
|
|
$803G
|
|
|
|
Note that the first call to the S-C XREF is $800G, and each
|
|
succeeding call is $803G. This causes the page numbers to appear in
|
|
continuous ascending order, rather than restarting at 0001 with each
|
|
new source file.
|
|
|
|
If you want a listing and an opcode cross reference of each module,
|
|
then insert a line like this after the BLOAD S-C XREF command:
|
|
|
|
$808:01 01
|
|
|
|
This enables the option flags at $808 and $809.
|
|
|
|
|
|
Special Entry Points and Parameters
|
|
|
|
|
|
There are two entry addresses, to allOw continuous page numbering
|
|
with successive source files:
|
|
|
|
:$800G -- Main entry point. Page numbers begin at 0001.
|
|
|
|
:$803G -- Successive modules entry point. Page numbers begin at last+1.
|
|
|
|
You can adjust the page length and width with two parameters:
|
|
|
|
$806: Contains the number of lines to be printed on each page. This
|
|
is normally 55 (hex $37). If you set your printer to 8 lines
|
|
per inch, you may want to select 76 lines per page (hex $4C).
|
|
If you are watching it on the screen only, you may wish to
|
|
select 20 lines per page. S-C XREF prints a formfeed character
|
|
($0C) before each page.
|
|
|
|
$807: Maximum number of characters to print on each line (normally
|
|
80). You should not set this value below 40.
|
|
|
|
|
|
- 5 -
|
|
|
|
---------------------------------------------------------------------
|
|
|
|
You can select any combination of three optional listings with these
|
|
three parameters:
|
|
|
|
|
|
$808: Opoode cross reference option flag. Default 0. Set non-zero
|
|
to produce an opcode cross reference.
|
|
|
|
$809: Source code listing option flag. Default 0. Set non-zero to
|
|
produce a paginated source listing.
|
|
|
|
$80A: Symbol and macro call option flag. Default 1. Set to 0 to
|
|
omit a Cross Reference listing of symbols and macro calls.
|
|
|
|
|
|
|
|
About the Source Code Files
|
|
|
|
|
|
If you have also ordered the Source Code for the S-C XREF, the disk
|
|
contains the following additional files:
|
|
|
|
S.ACF Assembly Control File
|
|
S.XREF.1 Main Code - 1
|
|
S.XREF.2 Main Code - 2
|
|
S.XREF.6502 6502 Opcode Tables
|
|
and
|
|
XREF CONTROL FILE EXEC File to Cross-Reference S-C XREF
|
|
|
|
To assemble S-C XREF just LOAD S.ACF into the S-C Macro Assembler,
|
|
change the .TI directive in line 1000 as necessary, and assemble it.
|
|
The .IN directives will load in the other files as they are needed.
|
|
|
|
S.XREF.1 and S.XREF.2 are the body of the code for the program.
|
|
|
|
S.XREF.6502 contains the lists of 6502 opcodes which have no
|
|
operands, or optional operands. This is the file to change if you
|
|
want to use S-C XREF with one of the Cross Assemblers.
|
|
|
|
XREF CONTROL FILE is an example of an EXEC file to control the cross
|
|
reference of a multiple-file source program. It contains the
|
|
commands to produce a cross reference of the S-C XREF Source Code.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- 6 -
|
|
|
|
---------------------------------------------------------------------
|