## ASxxxx Utility Programs

### ... The ASxxxx Utilities

####

- Diagnostic Listing File Scanner
- Diagnostic Assembler File Creator
- S19OS9 Conversion Utility
- ASxxxx Diagnostic Assembler
- Go to the Documentation Index

####

    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.

##### => Section Index

####

    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: [-dqx234] file
              d    decimal listing
              q    octal   listing
              x    hex     listing (default)
              2    16-Bit  address (default)
              3    24-Bit  address
              4    32-Bit  address

       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.

       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

##### => Section Index

####

    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.

##### => Section Index

####

    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.

##### => Section Index

####

... Exit the ASxxxx Documentation

... Home Page

######

Last Updated: March 2021