Date : Wed, 11 Oct 2006 13:02:35 +0100
From : "David Harper" <dl.harper@...>
Subject: Re: Tube Documentation
Jonathan Graham Harston wrote:
> Errors and bugs in Tube documentation & code
> --------------------------------------------
>
> Acorn Application Note 004 "Tube Application Note" details the Acorn Tube
> interface and software protocols. ...
They are also in Chapter 12 of "The Advanced Reference Manual for the BBC
Master", published by Watford Electronics. This is already available on-line
via http://www.bbcdocs.com
> ... I have
> noticed several documentary errors and code bugs.
For reference, I can tell you that the 80186 copro (Master 512) has a number
of glitches and variations from the standard. (OSBYTE and OSWORD are
implemented in the 80186 ROM, accessed via Interrupts 4Bh and 4Ah. They can
be called from within DOS-Plus, provided appropriate Tube claims and
releases are made, using these interrupts or (better) using XIOS calls 89h
and 8Ah.
The 80186 ROM implements OSBYTE using a simple Tube protocol:
for A<&80, the A and X values are written to the host, and the X value
read back;
for A>=&80, the A, X and Y values are written and the C, X and Y
values read back.
There are four (and only four) exceptions to this:
if A=&9C, the protocol terminates after writing
if A=&82, &83 or &84, then no action is taken and the equivalent
of X=Y=0 is returned
> OSBYTE &8E, page 22
> ~~~~~~~~~~~~~~~~~~~
If you were to try and do this from within DOS-Plus it will simply crash the
system. If you do it from the 80186 monitor, then the results are
unreliable.
> OSBYTE &82 is 'Select language', and the only return is either an error
> ...
See above. The 80186 ROM ignores this one, and simply returns with the
equivalent of X=Y=0.
> OSWORD control block lengths, p23 (also p4,5)
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> OSWORD 5 is listed as sending a two-byte control block. OSWORD 5 is 'read
> byte in I/O memory', with XY%?0 to XY?3 containing the address to be read.
> Sending the bottom two bytes is sufficient for reading a location with 64K
> of memory, but really the whole 4-byte address should be sent. The 65C102
> CoProcessor v1.10 client sends four bytes, and the Master is able to use
> the
> top two bytes to distinguish between IO memory at &FFFFxxxx and screen
> memory at &FFFExxxx. There is no reason why OSWORD 5 in the host doesn't
> also allow access to sideways ROMs with &FFFrxxxx, so really a Tube client
> should send a full four bytes.
I suspect this is inherited from the Model B in which only two bytes were
relevant. It would make more sense for 4 bytes to be used, and this would
indeed be usable with a Master as host, but no-one thought to update the
co-pro ROMs to accommodate the new base machine.
The 80186 ROM behaves just like the others you describe, and only uses a
two-byte block.
> Mention is made of Tube clients sending and receiving 16 bytes for OSWORD
> 14
> and OSWORD 15. This causes problems if the host implements a Real Time
> Clock
> as OSWORD 14 returns a 25-character string.
>
> In fact, the both the 6502 TUBE v1.10 client and the 65C102 CoProcessor
> v1.10 client:
> sends 1 and receives 24 bytes for OSWORD 14 and
> sends 32 and receives 0 bytes for OSWORD 15
>
> This results in the full clock string being sent with OSWORD 14, but
> OSWORD 14 omits the terminating <cr>.
This appears to be a documentation error. The 80186 co-pro uses exactly the
same protocols at the 6502 ones you describe here (except that OSWORD 14
receives the full 25 bytes, not 24).
> When OSWORD calls with A>&7F are sent, the sent and received control block
> lengths are in the first two bytes of the control block. The application
> note omits to mention that lengths of &81 to &FF should send and receive
> *no* data, they should be treated the same as a length of zero. "Up to 128
> bytes" is mentioned on page 5 and page 10, but it should be specified in
> the protocol description on page 23.
Rather oddly, the 80186 sends and receives 16 bytes for OSWORD calls with
&14<A<&81 (so A=&80 is treated like one of the smaller numbers)
BTW, regarding the higher numbered OSWORDs, there has to be a limit for
anything that uses the standard Tube host code, because that uses part of
host Page 1 as a data block. If too large a data block is used then it will
corrupt the stack.
> All hosts treat &81 to &FF as being zero. The 6502 clients correctly send
> and wait for no data for &81 to &FF, but the Z80 v1.20 client does not. It
> sends up to 255 bytes and waits for up to 255 bytes, causing the Tube
> syncronisation to go off.
Not quite true. The 80186 ROM places extra code in the host to handle a
special OSWORD &FA. Also, when the Master 512 is running DOS-Plus then it
transfers some code into the host (from the file 6502.SYS on the boot disk)
which looks after OSWORDs &FB to &FF. In practice, &FD and &FE are not used.
> OSFILE object type, p24
> ~~~~~~~~~~~~~~~~~~~~~~~
> The protocol states that R2DATA AND &7F is the object type. But why AND
> &7F?
> This loses bit 7. The 6502 clients do not do this, returning the full
> 8-bit
> object type, but the Z80 client does. Object type &FF is defined in other
> Acorn documents as being a Run-Only file, but doing AND &7F means that
> object type &FF is returned as &7F.
OSFILE should be usable on the 80186 by calling Interrupt 45h. In practice,
it has a serious bug in it and will not work.
> Execute in Client Processor, p26
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> While page 9 states that Transfer Type 4 is "execute in client processor",
> it actually only passes an address to the client; the client picks up that
> address in the foreground when the foreground action has completed, eg
> OSCLI, OSBYTE &8E or STARTUP. It does not cause the client to call code
> from
> the interupt code. Econet documentation implies that a RemoteJSR can cause
> a
> jump to an address in the client processor, but there is nothing in the
> client code to let this happen. A jump to code can only happen when OSCLI,
> OSBYTE &8E or STARTUP waits for an acknowledgement byte.
Different versions of the 80186 ROM handle this in different ways. With some
versions a jump to the given address may be made, though exactly when it
will occur is something of a mystery. Other versions make no attempt to
allow the jump at all.
If DOS-Plus is running on the Master 512, then the protocol is ignored.
> Data transfer Sync Bytes, p26, 27
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> The documentation for Transfer Types 4, 6 and 7 shouldn't really say "Wait
> for data in R4DATA, discard it", it should say "Wait for and remove
> synchronising byte from R4DATA", as with transfers 1 to 3.
Obviously if a byte is intended to be discarded, then it should not be
called "data"
With the 80186, the sequence of byte transfers is slightly different
depending on whether the 80186 ROM or DOS-Plus is in charge.
> STARTUP procedure
> ~~~~~~~~~~~~~~~~~
> ...
>
> Transfer Acknowldgements
> ~~~~~~~~~~~~~~~~~~~~~~~~
> ...
>
> Bugs in Client Code
> ~~~~~~~~~~~~~~~~~~~
> The Z80 v1.20 client code is fairly untidy, has quite a bit of duplicated
> code, and has some bugs in it. There are only two that cause problems.
The 80186 ROM code is also rather untidy, but the DOS-Plus code is better,
and on the whole the ROM code is not used once DOS-Plus is started.
Most of the problems of DOS-Plus itself, and some of those in the 80186 ROM,
are explored in some detail in the later documents listed in
http://www.cowsarenotpurple.co.uk/bbccomputer/master512/info.html
> Suggestion for reading memory limits with OSBYTE
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> OSBYTE &83 and &84 read the bottom and the top of available memory. OSBYTE
> &82 reads the high order word of the memory map. On the 6502 client, for
> example, OSBYTE &82 returns &0000 and OSBYTE &83 returns &0800, showing
> that
> the bottom of free memory is at &00000800.
>
> ...
As noted above, on the 80186 these all return simply with the value 0.
David Harper