;----------------------------------------------------------------------------
;File name:	PASM_BUG.TXT			Revision date:	1998.08.15
;Created by:	Ulf Ronald Andersson		Creation date:	1998.08.15
;----------------------------------------------------------------------------
;File purpose:	Illustrate a bug in the PASM assembler
;----------------------------------------------------------------------------

I chose a simple bootsector source for these examples due to the small size
of the code.  There is a macro in the source which limits the TEXT section
to 512 bytes, padding it to reach that size if necessary.  With the program
headers added by the linker this means that the resulting size should always
be exactly 544 bytes after assembly.  Before actual use I run this through
a program that cuts away the 28 byte front header as well as the four byte
tail header (relocation start ptr) from the file, which then results in a
length of exactly 512 bytes, as needed for a boot sector.  Yet another of
my utility programs is then used to place it on floppy with the correctly
adjusted media id and checksum.

This particular boot sector is useful to switch a TT to ST_Low and then
boot a game diskette which is dependent on this resolution (as many are).
It does no other patching though, so for that my B030 package is a better
alternative (on my home page at "http://www.oden.se/~dlanor/").

Ordinarily I call this source BLOW.S, but for this illustration I have made
two slightly different (8 bytes) versions of it, each with PC and PRJ files
etc.  These two variants are called 'BUGGED.S' and 'NOBUGS.S' since one of
them suffers the effects of a PASM bug while the other does not.

You should have the following files in the same folder as this text:

TRACER.SH       Small code tracer, which I use to debug boot sector code
BUGGED.PC       PC_Shell project file           \
BUGGED.PRJ      PureC project file               \
BUGGED.S        Source code in PASM dialect       > The bugged variant
BUGGED.O        Object module                    /
BUGGED.BS       Assembled program               /
NOBUGS.PC       PC_Shell project file           \
NOBUGS.PRJ      PureC project file               \
NOBUGS.S        Source code in PASM dialect       > The bugfree variant
NOBUGS.O        Object module                    /
NOBUGS.BS       Assembled program               /
ERROR.DAT       Latest assembly errors.

Note that since neither variant gives any error messages during assembly,
the ERROR.DAT remains at zero size for both versions.

The only difference between NOBUGS.S and BUGGED.S, is that some branches
which could use short offset have not been specified with '.s' data type
extension.  (Eg: NOBUGS uses 'bne.s label', but BUGGED uses 'bne   label')
This difference exists for four branches, which is why the difference in
length of the sources is exactly 8 bytes.

This results in PASM miscalculating some of the label values with during
the calculation of much assembly-time arithmetic, which causes the macro
that adjusts the code length (by padding zeroes) to use an insufficient
pad size, resulting in a file which is much shorter than it should be.

There are some things worthy of note here...

1:  This is NOT the only sort of thing which cause this kind of assembly-time
    arithmetic error.  Many other things can have the same effect, since it
    is a result of PASM making a choice between code variants that differs in
    the code size produced.  Sometimes the FINAL decision made only after the
    entire source has been passed will differ from the preliminary choice in
    effect when arithmetic was calculated. PASM takes no note of such cases,
    except in some cases where it concerns a simple data constant, but in a
    few cases even such (eg: "dc.w (arithmetic expression)" ) have also been
    affected.

2:  In this particular case it was easy to fix the problem, but that is not
    at all often the case. In some cases I have found it impossible (so far).

;----------------------------------------------------------------------------
;End of file:	PASM_BUG.TXT
;----------------------------------------------------------------------------
