w11 - /man/cat1/asm-11_expect.0

ASM-11_EXPECT(1)             Retro Project Manual             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 as-
       sembly errors and tests for expected address and generated data values.
       What is expected is specified by comments, described in the section EX-
       PECT 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 er-
       rors,  additional output follows which describes each error and the af-
       fected 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-sepa-
              rated list of either 3 (for byte output) or 6 (for word  output)
              digit  octal  numbers.   Again, all 3 or 6 digits must be speci-
              fied, even leading zeros.  This is checked against the data sec-
              tion 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  list-
           ing 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>


Retro Project                     2018-11-03                  ASM-11_EXPECT(1)