ASM-11_EXPECT(1)

NAME
asm-11_expect - expect checker for asm-11 test bench

SYNOPSIS
asm-11_expect [OPTION]... FILE...
asm-11_expect --help

DESCRIPTION
Reads one of more asm-11(1) listing files and checks for unexpected assembly errors and tests for expected address and generated data values. What is expected is specified by comments, described in the section EXPECT COMMENTS, which are added to the asm-11 source code. asm-11 will copy these comments to the listing file and asm-11_expect extracts them and checks whether the actual assembly results match the expected ones.

asm-11_expect produces at least a one-line summary per file like

       asm-11_expect: test_0010_alloc.lst OK
       asm-11_expect: test_0020_expr.lst OK

where each file is marked either OK or FAILED. In case of detected errors, additional output follows which describes each error and the affected listing line, like

       asm-11_expect: test_0110_op_gg.lst FAILED
         FAIL: data 1 mismatch: found=177736, expect=177734
           in:  1 27 001042 067700 177736   add  @pa,r0  ;;!! 067700 177734

The main application for asm-11_expect is to build self-checking test benches for asm-11(1).

EXPECT COMMENTS
The special comments which describe what to expect for an assembly line have the format

       ;;!! [etags] [addr:] [data]...

with

etags
    list of expected assembly error flags, given as a sequence of uppercase letters without white space between letters.
addr
    expected location counter (value of '.'), given as 6 digit octal number. Note that all 6 digits must be specified, even leading zeros.
data
    expected generated assembly output data, given as a blank-separated list of either 3 (for byte output) or 6 (for word output) digit octal numbers. Again, all 3 or 6 digits must be specified, even leading zeros. This is checked against the data section of the assembly listing.
    In general, this is used to check data emitted into the binary output. However, some assembler statements, e.g. assignments or directives like .end, indicate some result value in the data section, and this can of course be checked as well.

All three components are optional. Error flags are always tested, if no etags are specified it is checked that no assembly error flag has been generated for the line. Address and data tests are only done in case addr or data components have been given.

If a line starts with an expect comment it will be applied to the asm-11 statement in the following line. Or it is simply appended to an asm-11 statement.

  Comment examples

;;!! DM
    expect a D and a M error flag

;;!! 001020:
    expect that the current location will be 001020, data not checked

;;!! 074167 177762
    expect that the listing data section shows two words, 074167 and 177762. The address is not checked.

;;!! 001004: 000207
    expect that the current location will be 001004 and that the listing data section shows one word with the value 000207.

  Some practical cases
       .word   65537.          ;;!! T
       sob     r4,s4           ;;!! A
       stkbot: .blkw   400     ;;!! 001000:
       .word   100+77          ;;!! 000177
       .byte   2+<4*10>        ;;!! 042
       spl     5               ;;!! 000235
       inc     @1234(r4)       ;;!! 005274 001234
       add     @p,@#a          ;;!! 067737 177614 001000
       jsr     pc,sub          ;;!! 001006: 004767 177772
       cmp = 1234              ;;!! 001234
       c2 = inc + 67           ;;!! 005267
       .end                    ;;!! 000001

OPTIONS

--tline
    Prints input lines from the listing file as they are processed. Helpful to debug expect comments, e.g. in conjunction with the --tcheck option.

--tcheck
    Prints for each detected expect comment in the listing file a line reflecting the content of the comment, like
           ...line generated by --tcheck ...    | original expect comment
           exp:  err=T                          | ;;!! T
           exp:  dot=001000                     | ;;!! 001000:
           exp:  dat=060037 001000              | ;;!! 060037 001000
           exp:  dot=001006 dat=004767          | ;;!! 001006: 004767

--help
    print full help text and exit.

EXIT STATUS
In case of an error, the exit codes are:
    1   run time errors, like a bad option, file not found, etc
    2   at least one expect FAILed, test bench has FAILed

EXAMPLES

asm-11_expect *.lst
    Will check all listing files in the current directory and produce a listing with at least one summary line per file as described in section DESCRIPTION.

SEE ALSO
asm-11(1)

AUTHOR
Walter F.J. Mueller <W.F.J.Mueller@gsi.de>