Article 1260 of net.micro.amiga:
Relay-Version: version B 2.10.3 4.3bsd-beta 6/6/85; site unisoft.UUCP
Path: unisoft!lll-lcc!qantel!intelca!oliveb!glacier!decwrl!decvax!mcnc!ncsu!jcz
From: jcz@ncsu.UUCP (John A. Toebes, VIII)
Newsgroups: net.micro.amiga
Subject: AmigaDos Port-Handler (long)
Message-ID: <3074@ncsu.UUCP>
Date: 1 Apr 86 05:23:24 GMT
Date-Received: 2 Apr 86 11:15:29 GMT
Organization: SAS Institute Inc.
Lines: 578

As promised before, here is my version of the Port-Handler for AmigaDos.
It was derived in part from looking at the original Port-Handler in order
to obtain the calling conventions of BCPL and the routines that must be
called in order to do I/O through the BCPL environment, but otherwise
I started from scratch (and an empty file) to code it.

My original goal was to learn out exactly how AmigaDos device handlers are 
constructed and as such I have learned enough from writing this one that I
have also written a PIPE: handler to implement *REAL* UN*X pipes.  It
is not completely tested, so I expect it will be a week or so before I
would consider posting it.

Now on to how this one works:  I have tested it with the majority of the 
AmigaDos commands and have yet to get it to fail, but I have one instance
in a print program where it locks up.  Because of that, this program is NOT
to be taken as a direct replacement for the supplied Port-Handler until I
can track down that bug.  The true value of this code is that it shows what
the BCPL environment looks like from the handler point of view.

I will be posting a tutorial on the BCPL environment in about 2 weeks, but a
quick summary of the conventions:
    Upon entry to a BCPL routine (Including all command programs!) the
registers are set up as:
     A0 - Contains 0
     A1 - Points to the Bottom of the BCPL global stack
     A2 - Points to the internal AmigaDos library!
     A3 - ?unknown - I believe it to be unused
     A4 - Points to the Base of your code - I.E. Entry address
     A5 - Points to a service vector for calling other BCPL routines
     A6 - Points to the service vector to return from a routines
     A7 - Points to the program stack
     D0 - Generally unimportant - contains the size of the caller's global area
     D1-D4 - Contain first 4 (if that many) parameters
     D5-D7 - Unused
To call a BCPL routine you must:
  Load the parameters into D1-D4 respectively
  Load D0 with the size of your global stack
  Load A4 with the address of the routine to call
  JSR (A5)
To exit a BCPL routine you simply
  JSR (A6)
In general, A2 points to an internal AmigaDos library that WILL PROBABLY CHANGE
with the next release of Workbench/AmigaDos, but to what extent is unknown.
So as such, the calls described here must be used with NO SUPPORT even implied
by Commodore (They didn't document them so why should they stay?).  However
on the other side of the coin you would never get along without them.
I have figured out some of them as listed in the include file BCPL.I and will
document them later.  For now, the parameters should be fairly simple to
deduce from the code.

Once you have assembled and linked the code, it is invoked by simply replacing
the system PORT-HANDLER in the L: directory and then accessing any of PAR:
SER: or PRT:.  AmigaDos will automatically load and run the handler.  Note that
because this process is automatic, it is next to impossible to debug.  As such
you see the commented out debug statements in the code to store into the stack
frame and at $CA so that you can look at where the process is through WACK.
It is not an easy task, so expect to poke around a bit.

This code is being released for personal consumption only.  I am not supporting
this version (remember it has a known bug) but it should serve to show exactly
what an AmigaDos handler has to do.  I have not been able to get any
verification of correctness from Commodore or even a condonement/condeming
from them so this could be way off base (But I seriously doubt it).
Good Luck...

John A. Toebes, VIII
120 H Northington Place
Cary NC 27511
(919) 469-4210
 ...mcnc!ncsu!jcz   (as a guest there)

Disclaimer: I don't know what I am doing so how can you expect anyone else
to be responsible for what I say and do.