Subversion Repositories w11

.\"  -*- nroff -*-

.\"  $Id: asm-11_expect.1 550 2014-02-03 08:16:57Z mueller $

.\"

.\" Copyright 2014- by Walter F.J. Mueller 

.\"

.\" ------------------------------------------------------------------

.

.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