No Fragments Archive 10: Diskmags/nf_archive_10.iso/MAGS/ST_NEWS/STN_02_4.MSA/DATA_DOC13

Text File | 1987-06-11 | 17KB | 441 lines

üTRAP IN AND TRAP OUT Çby Ronald van der Kamp

How to fiddle with some low-level stuff


1. Introduction

 You readers, will all have heard by now about TRAPs that are  in
use on our ST machines. Some of us, Modula programmers, will have
wondered what these are used for,  because we do not have to know
in  detail  about our traps,  the library modules  take  care  of
difficult stuff like that.  So in this artikel I will explain the
use  of  the traps by our operating system and how you  can  make
your own traps,  why you should do it and for what kind of things
to use them.







2.Traps and the operating system.

  Let us take for example the action of writing a string  to  the
midi  port.  After  some  searching you will  find   a  procedure
'MIDIWS' in the extended BIOS module (with the name 'XBIOS').  In
the  definition module the description is  "PROCEDURE  MIDIWS(VAR
string: ARRAY OF BYTE; length: CARDINAL);" so that this action is
very simple for us.
  On another (lower) level we can see what kind of things  should
be done in the implementation of this call.  The manuals tell  us
that   we  can write a string to the midi port by  doing  a  trap
number 14,  function number 12, with the parameters on the stack.
But what does this mean?
 To explain this,  I have first to tell you about our CPU  ,  the
68000 and some of its workings.







3. The 68000 and Exception Processing.

  When  you walk undisturbed for 50.000 miles and  then  suddenly
falls into a trap, that is something very exceptional to you.
  While the CPU is executing instructions,  there can  come  from
outside  (the I/O chips for instance) an interrupt;  an  external
exception.  When  a division  by  zero  is attempted (and this is
impossible)  then an internal generated exception is  done.  When
the instruction the CPU executes is a TRAP instruction,  also  an
internal  exception is generated.  What the CPU then does is  the
following (as far as is needed to know at this point):

a.  the contents of the CPU status register ( 16 bits) is put  on
the supervisor stack;
b.  the  value of the CPU program counter register (32  bits)  is
placed on the supervisor stack;
c.  a memory location is calculated as  follows:  128+(trapnumber
times 4); so for trap number 11 the address is 172(decimal);
d.  the CPU goes into supervisor mode (if he was not already) and
fetches  the  address (of 4 bytes length),  that  stands  in  the
calculated   memory position,  into the program counter  register
and start executing the code from this point.
  By  using  traps it is possible to  write  software  that  will
function o.k.  with different versions of the TOS.  (I know of  4
versions  now,  but maybe there are more) Although  the  routines
that  cater  for the traps may be in different places  in  memory
(depending  on your TOS version),  the address of the start of  a
traphandler  code is always to be found in the same (low)  memory
location. ( see point c. above)

4. Inheritance of Traps.

 When the TOS system is booted,  the following traps are set  and
usable:  Trap #1 for GEMDOS calls,  Trap #2 for GEM/GSX, trap #13
for  the BIOS and trap #14 for the XBIOS.  These correspond  with
our  TDI  library  modules with the names  GEMDOS,(  nothing  for
#2),BIOS and XBIOS.  As soon as a modula program starts,  he will
find these traps available (he inherits them).
  As you know,  any modula program needs at least one other  link
file  with  the  name GEMX.  (and accessories  need  a  different
version of this LNK file). This GEMX  module contains the Modula-
run-time-system that has some initial actions to perform,  before
your own code is executed.  One of its actions is installing  the
traps  numbers 5 (for IOTRANSFER),  number 7 (for  TRANSFER)  and
number  8 for the runtime-errors.  (For version 2 of  TDI  Modula
there is an error in the manual;  not trap #6 but #5 is used  for
IOTRANSFER.)
So,   as   long   as   there  are   no   accessories   or   other
'concurrent' programs in the machine (as for instance programs in
the vertical blank list) that meddle with traps, all goes well.

5.Trap installation and use.

Doing a Trap is very simple in principle.  Say, want want our own
Trap  #11  handling.  Activating the trap can be  done  with  the
statement:

 "CODE(4E40h + 11);"

What we need is also a procedure as:

PROCEDURE NewTrap11;
BEGIN (* do your trap actions here*)
....
CODE(4E73h); (* RTE=ReTurn from Exception*)
END NewTrap11;
to perform our actions when the trap is activated.
Now things become less simple.  First we shall want to pass  some
values  to a traphandling procedure,  just as you pass values  to
every  normal  procedure with a  parameter  list.  The  parameter
passing  as  done  in the Modula code is not  compatible  to  the
mechanism of the exception processing of the CPU.
The  accepted  method  for passing values  to  procedures  is  by
putting  them 'on the stack' before the procedure call  and  have
the procedure 'read them from the stack'.
The activation of our trap with one parameter of WORD size (  the
value 15 in this case) would be done with:

SETREG(D7,15)(* with CONST D7=7; according to TDI convention*)
CODE(3F07h);(* MOVE.W d7,-(A7) =put word on stack*)
CODE(4E4Bh);(* TRAP #11 =do the trap now*)
CODE(548Fh);(* ADDQ.L #2,A7 = clean the stack (2bytes=1word)*)






  This  way of passing parameters makes things for  the  reciever
(the traphandling procedure) rather complicated.
 First of all the traphandler should not have any entry code with
him.  So use the compiler option (*$P- *)  to stop the generating
of entry and exit code by the compiler.
The procedure header should not have a parameter list,  and there
should also be no variables declared local within the handler (No
VAR  statement).  Remember  that by using the (*$P-  *)  compiler
option,  no exit code is generated for the procedure, so the last
executed  statement should be ( in our case ) a RTE.(and  not  an
RTS (ReTurn from Subroutine) as would be normal.)
  As told before,  the CPU puts itself into supervisor mode  when
the  exception  processing  is  initiated.   So  from  the  first
statement of the traphandler to the last ( the RTS) the CPU is by
default  in  supervisor  mode.  In our case  this  means  trouble
because the stackpointer register A7 is a little bit 'dual'.
  When  we  talk  about address register A7 and  the  CPU  is  in
supervisor  mode,  the register A7 denotes the  Supervisor  Stack
Pointer, and when in user mode this register A7 contains the User
Stack  Pointer.  When  the CPU is in supervisor  mode  there  are
privileged  instructions like 'MOVE USP,A0' that let you get  the
value of the User Stack Pointer, while A7 contains the Supervisor
Stack pointer.  It stands to reason that in user mode you  cannot
get at the supervisor stack.
  We have said that it is a nice thing to be able to pass  values
to the traphandler; values that are 'put on the stack'. Now it is
considered   a  good  programming  technique  not  to  make   any
restrictions  on the status of the CPU when a trap is  initiated.
The  program that activates the traphandler will normally  be  in
user mode,  but it is not right to suppose that it is always  the
case.  So how can the traphandler know in what state the  program
was that activated him?
 As told before,  when the CPU does an  exception processing, the
contents  of the status register is put on de  supervisor  stack.
And this stack is pointed to by register A7 when the  traphandler
becomes active.
  Before  we illustrate this article with some  lines  of  Modula
statements, a small remark first.

  In  the traphandling procedure there will always be a   use  of
some  CPU  registers.  When  we exit the  traphandler  we  should
restore  the  registers  to the values they  contained  when  the
traphandler was activated.  (and also the stackpointers should be
set o.k.)
6.How we make a traphandler.

  First  we  take care of the saving of used  register  from  the
traphandler. We define:

TYPE regStack = RECORD
                 heap: ARRAY [0..127] OF ADDRESS; (*stackspace*)
                 SP : ADDRESS (* our own StackPointer*) END;
and declare:

VAR regSaved : regStack;

then there is some initialisation needed:

WITH regSaved DO SP := ADR(SP) END;

and so our own stack is now ready to be used.
The traphandler now starts with:




(*$P- *)
PROCEDURE NewTrap11;
BEGIN (* in super mode*)
  SETREG(A0,regSaved.SP); (* set our own stackpointer*)
  CODE(48E0h,047Eh);(* MOVEM.L D5/A1-A6 -(A0) *)
  (* these registers will  be used in this handler *)
  regSaved := REGISTER(A0); (* set our own stackptr *)

Where  A0 equals 8 according to the TDI convention  of  numbering
the registers for the REGISTER and SETREG functions.  In this way
the register contents we are going to destroy,  are kept safe  by
copying them to our own stack, so we are able to reconstruct them
later on.

We know that there is an exception frame on the supervisor stack.
If we define

TYPE exceptionFrame = RECORD
                        Stat  :   statusRegister;
                        PC : ADDRESS END;


with

TYPE statusRegister = SET OF status;

whereby

TYPE status = (carry,overflow,zero,negative,extend,
               r1,r2,r3,i1,i2,i3,r4,r5,supervisor,trace);

Further on we declare:

VAR toExceptionFrame : POINTER TO exceptionFrame;

and now we can get the pointer to the exception frame with:

toExceptionFrame := REGISTER (A7); (* A7=15 according to TDI *)

If we now ask:

IF supervisor IN toExceptionFrame^.stat THEN


we know if the function frame,  containing the parameters we pass
to the traphandler, is on the supervisor stack, or in other words
:  if the activator was in super mode or user mode and so  placed
its info on de super- or userstack.
If the last  statement is true then we perform the actions:

  CODE(204Fh);(* MOVE.L A7,A0 *)
  CODE(0D0FCh,TSIZE(exceptionFrame));(* ADDA.W size,A0 *)

because the stack grows downward, we add (6 bytes) to the copy of
the super stack pointer in CPU register A0.  In the other case we
can get the function frame more simple:

ELSE
  CODE(4E68h);(* MOVE USP,A0 a priveleged instruction *)
END; (*if*)

Now we have to save the pointer to the function frame:

toFunctionFrame := REGISTER(A0);


In our example the function frame is:

TYPE functionFrame = RECORD fNr : CARDINAL END;

and a declaration of

VAR toFunctionFrame : POINTER TO functionFrame;

to keep the address of the frame.
  Now that we have the pointer to the functionFrame we  can  read
our parameters from the function frame with statements like:

yyy := toFunctionFrame^.fNr;

By having the values of the given parameters to our disposal, all
needed actions of the traphandler can be done,  but take care not
to  change A7 (SSP) or USP.  Do not suppose there is  much  space
left  on either of these two stacks.  Every call to  a  procedure
will  use  up  at  least 4 bytes on the  stack  (for  the  return
addres), so do not nest too many calls!


  You  are strongly adviced to take some actions to set  all  the
stacks  o.k.   before  exiting  the  traphandler  (with  an   RTE
instruction). The following path should be taken:

in case the function frame is on the supervisor stack,  it should
be  removed  and the exception frame should be  shifted  'upward'
with the needed amount (= the length of the function frame). With
a copy of the exception frame available, the actions are simple:
declare:

VAR savedExcFrame : exceptionFrame;

and the stack is cleaned with the statements:

If supervisor IN toExceptionFrame^.stat THEN
  savedExcFrame := toExceptionFrame^;
  CODE(0DEFCh,TSIZE(functionFrame));(* ADDA.W size,A7 *)
  toExceptionFrame := REGISTER(A7);
  toExceptionFrame^ := savedExcFrame;



ELSE
  CODE(4E68h);(* MOVE USP,A0 *)
  CODE(0D0FCh,TSIZE(functionFrame));(* ADDA.W size,A0 *)
  CODE(4E60h);(* MOVE.L A0,USP *)
END;(*if*)

All kind of other actions can be done now,  but do not end simply
with and RTE;  restore first all the registers we had in  use.  (
see the start of the traphandler) with:

SETREG(A0,regSaved.SP);
CODE(4CD8h,7E20h);(* MOVEM.L (A0)+,D5/A1-A6 *)
savedD5 := REGISTER(D5);(* sorry, next action destroys him*)
regSaved.SP := REGISTER(A0);
SETREG(D5,savedD5);
CODE(4E73h); (* RTE *)
END NewTrap11;





Do not let your understanding of this piece of code be clouded by
the D5 stuff;  a habit of the generation of code by the  compiler
is   to  use  D5  as  intermediate  for  even  the  most   simple
assignments.  The  central  point  of the code  is  to  fill  all
registers of the CPU with values they contained when the handling
of our trap was started. A copy of these values was stored in our
own stack. The stackpointers A7 (SSP) and USP are already earlier
cleaned up, so an RTE is possible.

7.The installation of a Trap

In  the module 'BIOS' we find a procedure to install a  trap.  Of
course, strictly spoken, we can put the adress of our traphandler
in the right memory position (172 for Trap #11), but this is very
much bad programming practice. Always use a system function call,
because you never are sure whether your idea of  trapinstallation
is what the system itself does. The statement becomes:

BIOS.SetException(trap11VectorNr,NewTrap11);

whereby

 CONST trap11VectorNr=43; (* = 172 DIV 4 *)

  Mostly  you  will want a construction in  which  a  program  is
activated  at  boot-time ( what can be done by putting  the  .PRG
file  in  the AUTO folder of the boot-disk),  then  installs  the
traphandler,  and  deactivates itself,  keeping the code  of  the
traphandler in memory.  In this case you must take care of ending
the  installation program not in the normal way ( that is with  a
call to the GEMDOS.Term ) but with a call of:

GEMDOS.TermRes(numBytes,exitCode)

whereby  numBytes  gives the number of bytes of memory  that  are
kept  (should  be  as  much as  the  program  needs  for  itself)
counting from the start of the program code. ExitCode is 0 (zero)
for no-error.(otherwise >0)
  This termination call will deactivate the program and keep  the
memory  block  intact by not giving it back to  the  free  memory
space.  So  later  programs and data will  never  overwrite  this
program code. The reason for using this call is that you must not


end  up  in a situation where the traphandler is  noted  down  as
being available, while the code of the traphandler is gone to the
dogs.

8. Redefinition of available (system) traps.

 When you wish to redirect all the output of the printer port  to
say the Midi port,  you will need an own traphandler,  that takes
the place of the system function GEMDOS.PrnOut.  This function is
implemented as Trap #1 with  function number 5 and the  character
to print is on the stack ( in a WORD,  because the stack serviced
by CPU register A7 works in units of WORDs).
  The  program  that installs the traphandler  has  to  save  the
address  of the trap number 1 that is already in existence (  the
normal system trap). This is done with:

oldTrap1 := BIOS.GetException(trap1VectorNr);(* vector=33*)

and  in  the  traphandler we do a test after we  have  found  the
functionframe:


IF toFunctionFrame^.fNr <> 5 THEN (*  nothing for me to do *)
  SETREG(A0,regSaved.SP);(* restore the registers *)
  CODE(4CD8h,7E20h);(* MOVEM.L (A0)+,D5/A1-A6 *)
  savedD5 := REGISTER(D5); (* next statement uses D5 *)
  regSaved.SP := REGISTER(A0);(* set stackpointer back*)
  SETREG(D5,savedD5); (* D5 got smashed *)
  SETREG(A0,oldTrap1);(* the normal system trap *)
  CODE(4ED0h);(* JUMP(A0) *)
ELSE
  ......my trap handling actions

Make  sure that,  when you  trap through to the old  system  trap
handler,  the  whole  situation should be restored  that  was  in
existence when the traphandler was activated.








9. Conclusion

  When you want to have some extra built-in functions in your  ST
so  that it looks like an extended TOS is invented,  or when  you
need one or more operating system functions to behave  different,
you  should construct your own traphandler and make a program  to
install  that  traphandler in the operating system.  There  is  a
listing  of  a  trap test program written  in  Modula  with  this
article and a ready to run version (=compiled and linked) of  the
test program will be somewhere on this disk.
 When you make the traphandler and starts with the rather minimal
source code of the test program,  it will not be unduly difficult
to  make a usefull traphandler.  The TDI post-mortem debugger  is
not  a  useable tool for debugging traphandlers.  So  build  your
traphandlers 'bit by bit',  otherwise it becomes very  frustating
to develop this kind of software.

(c) Stichting Modula Nederland (april 1987)
Bakkersteeg 9 A
2311 RH LEIDEN
The Netherlands