Troubleshooting help file

Got any troubles? Well, tell me, but read this first!

Index:
1) Problems with assembler and linker (i think this is the most likely trouble)
2) Runtime quirks and bugs
3) Bugs from Hell

1) PROBLEMS WITH ASSEMBLER AND LINKER

* The short, the small and the large
  There are THREE different sizes of offsets,displacements and immediate values

  short <expr>       casts <expr> to be byte sized (8bit)
                        0..255  for immediate values and offsets
                     -128..+127 for dispalcements and signed bytes

  small <expr>       casts <expr> to be word  sized (16bit)
  large <expr>       casts <expr> to be dword sized (32bit)

  "As is" the 386power source code assembles correctly with my assembler
  but there are assembler that expect stricter syntax.
  So, if you want to store a 32bit offset (with the upper word cleared)
  into a word register, remember to use the "small" override.
  i.e:
        code32 segment para public use32
               ...
        bigfatbyte db 0
               ...
        code32 ends

        code16 segment para public use16
               assume ds:code32
               ....
               mov bx,small offset bigfatbyte
               mov [bx],al
               ...
        code16 ends

  and so on ....

  Alex Yu reported some casting problems with tasm 3.2
  and helped me resolve 'em, but the current 386P 2.00 is a lot different
  from 386P 1.01 so similar problems may happen, simply put the correct
  type override to tell the assembler "Ok! I know what i'm doing".


* Dumb assembler bugs

  a) Once upon a time assemblers were quite permissive, now they are not.
     They insist on syntactic things to improve your productivity
     but there is no standard for this and sometimes this can cause troubles
     together with hidden bugs, look at this:

        mov [ebx + offset _MouseX],123

     sometimes the usage of the OFFSET operator where a label offset is expected
     causes strange quirks (double offset referencing?!?)
     use instead [ebx +_MouseX].
     This little thing nearly made me crazy until i looked at what
     was the actual offset in the program code (urgh!).

  b) Other times there are casting problems, look at the size of what you use
     and then put a TYPE OVERRIDE i.e:

        smurf dd 0

        mov ax, WORD PTR smurf ; (copies the low word of smurf into ax)

* "hidden" identifiers

  Be careful when you use identifiers
  A problem i had while devenloping the 386keyb module
  was caused by the referencing of an identifier called 'nothing'.
  Well, the assembler had a 'nothing' too, but i did not remember all those
  predefined identifiers, so every reference to 'nothing'
  turned into a pointer to an empty string, while my 'nothing' was
  pointing to non-empty string (AARGH!).
  Changing 'nothing' to 'nada' solved this ... until somebody will
  try this thing on an assembler made in Spain ;)

2) RUNTIME QUIRKS AND BUGS

  One of the biggest sources of problems are the "mode switches"
  needed to execute real-mode code.

  The 386keyb "keyboard driver", when installed, takes over the keyboard
  "hardware irq" (IRQ 1 or INT 09h) to perform "raw" input
  (i.e. to read multiple key press/release).
  But when you call the _ReadAscii function
  (the one also used by _GetString,_GetInt,_GetUnsigned functions)
  the MS-DOS function 07 (consolle input) is called.
  I choosed to do this because this way it is possible to "read" keys
  using the keyboard layout set by MS-DOS and BIOS.
  This way it is possible to read correctly the alphabetic keys
  even on localized keyboards (don't forget i'm european).

  Anyway, if you press too many keys while the _ReadAscii function is running
  sometimes you get a "scrambled keys" situation, some keys acts like
  the SHIFT key is always pressed, to resolve this,
  simply press together CTRL-SHIFT-ALT one or more times.
  I don't think it is a problem caused by my code ... this strange quirk
  plagued even Scorched Earth (a 1990 "real mode" artillery game)
  and similar problems happened to Doom and OMF when i tried 'em
  on my computer.

3) BUGS FROM HELL

  Well, THIS will scare you!
  While devenloping 386P 2.00 i encountered quite weird problems
  they are listed with a "key" title to help you remember
  what they are related to:

  a) No wanna short bits, man!

        Sometimes moving a declaration from a place to another
        and then recompiling caused a previously working program to crash.

        I discovered it was a bug related with the "auto grouping of segments"
        my assembler performed, coupled with the particular
        protected mode stack addressing conventions of Intel processors
        (read: wrong address size overrides in the wrong place
               and 16bit offsets that could not reach a location
               that needed a 32bit offset).
        To be sure to have totally eliminated that pest i "rewrote in a week"
        ALL 386power.asm (if you look inside, it is quite different from
        old release 1.01) (this is also one of the reasons i've been
        so late in releasing 386P 2.00).
        If you have problems of VCPI protected mode environment initialization
        look if you have instructions with EXPLICT addressing of stack segment
        maybe they are the cause
        (push,pop,call don't care, they are stack-implicit instructions ).

  b) Typemaniac rate

        It all started when after installing a new antivirus
        the 386P "program termination" code
        produced strange "pauses" while terminating under DPMI
        and self-resetted when terminating under VCPI.
        I discovered the problem was related to the "set typematic rate" code.
        When you set the typematic rate you need to talk to the
        keyboard controller and to set the CMOS
        typematic values, two typical "it smell like a virus" activities.
        What's more, if you changed the irq9 handler, well, the keyb controller
        may get lost.

  c) Die keyboard controller pig!

        This was a recurrent problem with VCPI, when switching modes looks like
        the VCPI server toggles the A20 line (SOMETIMES!!), when it happens
        it needs the default irq 9 handler in place (the keyboard
        controller irq), so if you redirected it, well you can guess
        what can happen. I've got "old" keyboard controller roms
        (AMI release K8), maybe this is the cause.

