Subversion Repositories w11

.\"  -*- nroff -*-
.\"  $Id: asm-11_expect.1 550 2014-02-03 08:16:57Z mueller $
.\"
.\" Copyright 2014- by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\" 
.\" ------------------------------------------------------------------
.
.TH ASM-11_EXPECT 1 2013-03-30 "Retro Project" "Retro Project Manual"
.\" ------------------------------------------------------------------
.SH NAME
asm-11_expect \- expect checker for asm-11 test bench
.\" ------------------------------------------------------------------
.SH SYNOPSIS
.
.SY asm-11_expect
.RI [ OPTION ]...
.I FILE...
.
.SY asm-11_expect
.B \-\-help
.YS
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
Reads one of more \fBasm-11\fP(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 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.
.PP
asm-11_expect produces at least a one line summary per file like
.PP
.EX
   asm-11_expect: test_0010_alloc.lst OK
   asm-11_expect: test_0020_expr.lst OK
.EE
.PP
where each file is marked either \fBOK\fR or \fBFAILED\fR. 
In case of detected errors additional output follows which gives a description
of each error and the affected listing line, like
.PP
.EX
   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
.EE
.PP
Main application for asm-11_expect is to build self-checking test benches
for \fBasm-11\fP(1).
.
.
.\" ------------------------------------------------------------------
.SH EXPECT COMMENTS
The special comments which describe what to expect for an assembly line
have the format
.PP
.EX
   ;;!! [\fIetags\fP] [\fIaddr\fP:] [\fIdata\fP]...
.EE
.PP
with
.PP
.PD 0
.IP "\fBetags\fP"
list of expected assembly error flags, given as sequence of uppercase letters
without white space between letters.
.IP "\fBaddr\fP"
expected location counter (value of '.'), given as 6 digit octal number. 
Note that all 6 digits must be specified, even leading zeros.
.IP "\fBdata\fP"
expected generated assembly output data, given as 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. 
.br
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 data section, and this can of course be 
checked as well. 
.PD
.PP
All three components are optional. Error flags are always tested, if no
\fIetags\fP 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
\fIaddr\fP or \fIdata\fP components have been given.
.PP
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 a asm-11
statement.
.SS Comment examples
.IP "\fB;;\-\- DM\fR" 4
expect a D and a M error flag
.IP "\fB;;\-\- 001020:\fR"
expect that current location will be 001020, data not checked
.IP "\fB;;\-\- 074167 177762\fR"
expect that the listing data section shows two words, 074167 and 177762.
Address is not checked.
.IP "\fB;;\-\- 001004: 000207\fR"
expect that current location will be 001004 and that the listing data section
shows one word with value 000207.

.SS Some practical cases
.EX
   .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

.EE

.\" ------------------------------------------------------------------
.SH OPTIONS
.
.\" ----------------------------------------------
.IP "\fB\-\-tline\fR"
Prints input lines from listing file as they are processed. Helpful to
debug expect comments, e.g. in conjunction with the \fB-\-tcheck\fR
option.
.
.\" ----------------------------------------------
.IP "\fB\-\-tcheck\fR"
Prints for each detected expect comment in the listing file a line reflecting
the content of the comment, like
.EX
   ...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 
.EE
.
.\" ----------------------------------------------
.IP "\fB\-help\fR"
print full help text and exit.
.
.\" ------------------------------------------------------------------
.SH EXAMPLES
.IP "\fBasm-11_expect *.lst\fR" 4
Will check all listing files in current directory and produce a listing with 
at least one summary line per file as described in section DESCRIPTION.

.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR asm-11 (1)

.\" ------------------------------------------------------------------
.SH AUTHOR
Walter F.J. Mueller <W.F.J.Mueller@gsi.de>