URL
https://opencores.org/ocsvn/w11/w11/trunk
Subversion Repositories w11
[/] [w11/] [tags/] [w11a_V0.6/] [doc/] [man/] [man1/] [asm-11_expect.1] - Rev 24
Compare with Previous | Blame | View Log
.\" -*- 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>