... The ASxxxx Utilities
The ASXSCN Listing File Scanner
The program ASXSCN is a debugging utility program used to
verify ASxxxx assembler code generation. The program may be in-
voked with any of the following options:
Usage: [-dqx234i] file
d decimal listing
q octal listing
x hex listing (default)
2 16-Bit address (default)
3 24-Bit address
4 32-Bit address
i ignore relocation flags
c comment starts at last ';'
Select one of the -d, -q, or -x options to match the listing
file format and select only one of the -2, -3, or -4 options to
match the addressing range of the listing file. The -i option
inhibits the verification of the assembler relocation flags
generated by the ASxxxx assemblers -f or -ff options.
Each source assembly line selected for verification must in-
clude the expected output code in the comment field of the line.
The default expects verification code to follow the first ';'
encountered in the line. Use the -c option to specify that the
verification code follows the last ';' on the line. The follow-
ing has been extracted from the ASF2MC8 test file tf2mc8.asm:
reti ; 30
call ext ; 31s12r34
subc a ; 32
subcw a ; 33
subc a,#v22 ; 34r22
subc a,*dir ; 35*33
subc a,@ix+off ; 36r44
subc a,@ep ; 37
The r, s, and * are specific address relocation flags created
when the -ff option is specified with any ASxxxx assembler.
Invoking the assembler:
asf2mc8 -gloaxff tf2mc8
produces a listing file:
033B 30 677 reti ; 30
033C 31s12r34 678 call ext ; 31s12r34
033F 32 679 subc a ; 32
0340 33 680 subcw a ; 33
0341 34r22 681 subc a,#v22 ; 34r22
0343 35*33 682 subc a,*dir ; 35*33
0345 36r44 683 subc a,@ix+off ; 36r44
0347 37 684 subc a,@ep ; 37
The expected code can be compared with the generated code by
invoking the scanning program:
asxscn tf2mc8.lst
0 code difference(s) found in file tf2mc8.lst
The assembled code can also be linked:
aslink -u ...options... t2fc8
to create an updated listing file:
033B 30 677 reti ; 30
033C 31 12 34 678 call ext ; 31s12r34
033F 32 679 subc a ; 32
0340 33 680 subcw a ; 33
0341 34 22 681 subc a,#v22 ; 34r22
0343 35 33 682 subc a,*dir ; 35*33
0345 36 44 683 subc a,@ix+off ; 36r44
which resolves all relocations and removes the relocation flags.
This file can also be verified:
asxscn -i tf2mc8.rst
0 code difference(s) found in file tf2mc8.rst
The verification of both the .lst and .rst files from the
same assembler test file requires careful definition of external
variables so that the assembler listing file and the linker
listing file have the same code values.
The ASXCNV Diagnostic Assembler File Creator
The program ASXCNV is a debugging utility program used to
create an assembler file with verification data. The program
may be invoked with any of the following options:
Usage: [-dqx234n#] file
d decimal listing
q octal listing
x hex listing (default)
2 16-Bit address (default)
3 24-Bit address
4 32-Bit address
n# cycle digits (2-4) (default = 2)
Select one of the -d, -q, or -x options to match the listing
file format, select only one of the -2, -3, or -4 options to
match the addressing range of the listing file, and use -n#,
where # is 2,3, or 4, to specify the number of cycle digits.
The defaults are hex listing, 16-Bit addressing, and 2 cycle di-
gits.
Each source assembly line which creates output data will have
the data appended to the source line as a comment. The appended
comment will contain the relocation codes if they are present in
the listing file. Any existing comment on the line will be
overwritten.
Given an existing listing file, a.lst, containing:
033B 30 677 reti
033C 31s12r34 678 call ext
033F 32 679 subc a
0340 33 680 subcw a
0341 34r22 681 subc a,#v22
0343 35*33 682 subc a,*dir
0345 36r44 683 subc a,@ix+off
0347 37 684 subc a,@ep
A converted listing file can be created using the following
command:
asxcnv -d2 a.lst
The created output file, a.out, is a new assembly file now con-
tain the verification data in the comments:
reti ; 30
call ext ; 31s12r34
subc a ; 32
subcw a ; 33
subc a,#v22 ; 34r22
subc a,*dir ; 35*33
subc a,@ix+off ; 36r44
subc a,@ep ; 37
S19OS9 CONVERSION UTILITY
BACKGROUND
OS9 is an Operating System for the TRS-80/Tandy Color Com-
puters based on the 6809/6309 processors. The open source ver-
sion of the OS9 operating system is NitrOS-9 and is available
at:
The NitrOS-9 Project
http://www.nitros9.org
The s19os9 utility package contains the following:
1) OS9 definition files and an OS9 assembler module
which creates the OS9 header, code and data areas,
and the module CRC block:
os9_mod.def OS9 Module Definitions
os9_sys.def OS9 Sytem Definitions
os9_mod.asm OS9 Module Begin / End Code
2) a program, s19os9, to post-process assembled OS9
modules from S19 format into binary OS9 modules
with the appropriate header checksum and module
CRC values calculated.
The file os9_mod.def contains module definitions used in the
header of OS9 binary files and was derived from the NitrOS-9
file os9_mod.def.
The file os9_sys.def contains system definitions pertaining
to system service request codes, system reserved calls, I/O ser-
vice request calls, file access modes, signal codes, get/put
status codes, module offsets, and error codes. This file was
derived from the NitrOS-9 file os9defs.a.
CREATING AN OS9 MODULE
This section describes how to create an OS9 module using the
files os9_mod.def, os9_sys.def, and os9_mod.asm.
When creating an OS9 module certain parameters are required
by the os9_mod.asm file to create the appropriate headers. The
list of supported parameters is listed here:
Basic Header:
.define OS9_ModNam, "Module_Name"
.define OS9_Typ, "Type_Value"
.define OS9_Lng, "Language_Value"
.define OS9_Att, "Attributes_Value"
.define OS9_Rev, "Revision_Value"
General Parameters:
.define OS9_ModExe, "Module Entry Point Offset"
.define OS9_ModMem, "Module Permanent Storage"
Device Driver Parameters:
.define OS9_Mod, "Module Mode"
Descriptor Parameters:
.define OS9_FMN, "Device Driver Name Label"
.define OS9_DDR, "Device Driver Name Label"
.define OS9_AbsAdr02, "Device Absolute Address <23:16>"
.define OS9_AbsAdr01, "Device Absolute Address <15:08>"
.define OS9_AbsAdr00, "Device Absolute Address <07:00>"
.define OS9_Opt, "Descriptor Option"
.define OS9_DType, "Descriptor Data Type"
The OS9 Module file os9_mod.asm supports the creation of the
following simple module types:
SYSTM - System Module
PRGRM - Program Module
SBTRN - Subroutine Module
DRIVR - Device Driver Module
FLMGR - File Manager Module
DEVIC - Device Descriptor Module
The following code shows the steps required when creating an
OS9 program using the os9_mod.asm file. os9_mod.asm loads the
os9_mod.def and os9_sys.def files, defines the software inter-
rupt macro os9, and creates the os9 program header and crc
blocks.
Step 1: Define Header Values
;****
; Step 1:
; Use the .define assembler directive
; to insert the parameters into the
; os9_mod.asm's header structure.
;
; Note: See the file os9_mod.asm for
; parameter names and definitions.
;
.title List Program
.sbttl Header Definitions
.define OS9_ModNam, "LSTNAM"
.define OS9_Typ, "PRGRM"
.define OS9_Lng, "OBJCT"
.define OS9_Att, "REENT"
.define OS9_Rev, "1"
.define OS9_ModExe, "LSTENT"
.define OS9_ModMem, "LSTMEM"
Step 2: Create The Module Header
; Step 2:
; Set the symbol OS9_Module equal to 1
; and .include the file os9_mod.asm.
OS9_Module = 1 ; OS9 Module Begin (==1)
; .include "os9_mod.asm"
.nlist
.include "os9_mod.asm"
.list
With OS9_Module = 1 the following code is inserted into the
code stream:
.define os9, "swi2 .byte" ; os9 macro
; Include OS9 Definition Files
; os9_sys.def Listing Disabled
.nlist
.include "os9_sys.def"
.list
; os9_mod.def Listing Disabled
.nlist
.include "os9_mod.def"
.list
; Define The OS9 Module Bank and Areas.
;
; Place the module program code in area OS9_Module
; and the module data in area OS9_Data.
;
.bank OS9_Module (BASE=0,FSFX=_OS9)
.area OS9_Module (REL,CON,BANK=OS9_Module)
.bank OS9_Data (BASE=0,FSFX=_DAT)
.area OS9_Data (REL,CON,BANK=OS9_Data)
.area OS9_Module
OS9_ModBgn = .
.byte OS9_ID0, OS9_ID1
; OS9 Module Sync Bytes
.word OS9_ModEnd - OS9_ModBgn
; Length (Includes 3 CRC Bytes)
.word OS9_ModNam - OS9_ModBgn
; Offset to Module Name String
.byte OS9_Typ | OS9_Lng
; Type / Language
.byte OS9_Att | OS9_Rev
; Attributes / Revision
.byte 0xFF
; Header Parity
.word OS9_ModExe - OS9_ModBgn
; Execution Entry Offset
.word OS9_ModMem
; Storage Requirement
; OS9_ModData
; Module Data
Step 3: Allocate Storage
The next step is to add the program data storage space for
the program. Note that the space is only allocated here and no
initialization is done.
;*****-----*****-----*****-----*****-----*****-----*****
; LIST UTILITY COMMAND
; Syntax: list <pathname>
; COPIES INPUT FROM SPECIFIED FILE TO STANDARD OUTPUT
; Step 3:
; Allocate the storage in .area OS9_Data
.area OS9_Data
; STATIC STORAGE OFFSETS
BUFSIZ .equ 200 ; size of input buffer
Base = .
IPATH = . - Base
.rmb 1 ; input path number
PRMPTR = . - Base
.rmb 2 ; parameter pointer
BUFFER = . - Base
.rmb BUFSIZ ; allocate line buffer
.rmb 200 ; allocate stack
.rmb 200 ; room for parameter list
LSTMEM = . - Base
Step 4: Insert The Program Code
Once the data storage space has been allocated then the pro-
gram code is added to .area OS9_Module:
; Step 4:
; Insert the Module Code into .area OS9_Module
.area OS9_Module
LSTNAM: .strs "List" ; String with last byte
; or'd with 0x80
LSTENT: stx *PRMPTR ; save parameter ptr
lda #READ. ; select read access mode
os9 I$OPEN ; open input file
bcs LIST50 ; exit if error
sta *IPATH ; save input path number
stx *PRMPTR ; save updated param ptr
LIST20: lda *IPATH ; load input path number
leax *BUFFER,U ; load buffer pointer
ldy #BUFSIZ ; maximum bytes to read
os9 I$READLN ; read line of input
bcs LIST30 ; exit if error
lda #1 ; load std. out. path #
os9 I$WRITLN ; output line
bcc LIST20 ; Repeat if no error
bra LIST50 ; exit if error
LIST30: cmpb #E$EOF ; at end of file?
bne LIST50 ; branch if not
lda *IPATH ; load input path number
os9 I$CLOSE ; close input path
bcs LIST50 ; ..exit if error
ldx *PRMPTR ; restore parameter ptr
lda ,X
cmpa #0x0D ; End of parameter line?
bne LSTENT ; ..no, list next file
clrb
LIST50: os9 F$EXIT ; ... terminate
Step 5: End Assembly By Inserting CRC
; Step 5:
; Set the symbol OS9_Module equal to 0
; and .include the file os9_mod.asm.
OS9_Module = 0 ; OS9 Module End (==0)
; .include "os9_mod.asm"
.nlist
.include "os9_mod.asm"
.list
.end
With OS9_Module = 0 the following code is the last code in-
serted into the code stream:
.area OS9_Module
; The 3-Byte Module CRC
.byte OS9_CRC0, OS9_CRC1, OS9_CRC2
OS9_ModEnd = . ; End of OS9 Module
THE CONVERSION UTILITY: S19OS9
Once you have assembled your module into an .S19 file use the
program s19os9 to create the binary OS9 module file.
The program s19os9 is invoked from the command line:
s19os9 mod.s19 -o mod.bin
where mod.s19 is the input S19 file and mod.bin is the OS9
binary output file.
The conversion utility s19os9 reads the .S19 file into an in-
ternal buffer (48K bytes maximum). As each line is read from
the .S19 file the record length, address, data, and checksum
values are processed checking for invalid characters and a valid
checksum.
After the .S19 file has been loaded into the internal buffer
the OS9 module is checked for correct length, and the OS9 Module
ID, OS9 Initial Header Checksum, and OS9 Initial Module CRC are
verified. After these parameters have been checked then the ac-
tual header checksum and module CRC values are calculated and
replace the Initial Module Checksum and CRC values. The final-
ized module is then written to the file mod.bin.
ASxxxx Diagnostic Assembler
The ASxxxx assembler ASCHECK is used to test the machine in-
dependent features of the ASxxxx assemblers. The source files
for the ASCHECK assembler are also useful as a template for the
development of a new ASxxxx assembler.
The ASCHECK assembler has all the ASxxxx directives enabled
for testing all features of the assemblers.
.opcode DIRECTIVE
Format:
.opcode n
The .opcode directive creates a single byte of code having the
value n and having cycle counts defined in the following table:
/*--*--* 0 1 2 3 4 5 6 7 8 9 A B C D E F */
/*--*--* - - - - - - - - - - - - - - - - */
/*00*/ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9,10,11,12,13,14,15,
/*10*/ UN, 1,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,
/*20*/ UN,UN, 2,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,
/*30*/ UN,UN,UN, 3,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,
/*40*/ UN,UN,UN,UN, 4,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,
/*50*/ UN,UN,UN,UN,UN, 5,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,
/*60*/ UN,UN,UN,UN,UN,UN, 6,UN,UN,UN,UN,UN,UN,UN,UN,UN,
/*70*/ UN,UN,UN,UN,UN,UN,UN, 7,UN,UN,UN,UN,UN,UN,UN,UN,
/*80*/ UN,UN,UN,UN,UN,UN,UN,UN, 8,UN,UN,UN,UN,UN,UN,UN,
/*90*/ UN,UN,UN,UN,UN,UN,UN,UN,UN, 9,UN,UN,UN,UN,UN,UN,
/*A0*/ UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,10,UN,UN,UN,UN,UN,
/*B0*/ UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,11,UN,UN,UN,UN,
/*C0*/ UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,12,UN,UN,UN,
/*D0*/ UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,13,UN,UN,
/*E0*/ UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,14,UN,
/*F0*/ UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,UN,15
The UN symbols indicate 'undefined cycles' where no cycle count
will be output.
... Exit the ASxxxx Documentation
... Home Page
Last Updated: September 2023