Date   : Wed, 11 Oct 2006 22:42:10
From   : Sprow <info@...>
Subject: Re: Tube Documentation

In article <061011015502@...>,
   Jonathan Graham Harston <jgh@...> wrote:
> [...in...] Acorn Application Note 004 I have
> noticed several documentary errors and code bugs.

It is a terrible document, presumably because the number of people
requesting it at the time was limited and they either worked at Acorn so
could just ask other staff or figured it out for themselves.

I think you've only scratched the surface here, as you soon find out all the
ambiguities when actually implementing a coprocessor!

> OSBYTE &8E, page 22
> ~~~~~~~~~~~~~~~~~~~
> When the client calls OSBYTE, after sending the parameters it should check
> for OSBYTE &8E and jump to check for a single acknowledge byte indicating
> if code is to be entered.
>
> OSBYTE &82
         ^^^
         &8E

> 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.
>
> 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

In 6502 Tube OS 1.20 this is s8/r25 for OSWORD 14
                         and s8/r8 for OSWORD 19
though of course because the ROM is downloaded into RAM the table is easily
fixed in other versions with a bonus poke. Alternatively, always do
buffer?24 after reading the clock? Yuk.

> 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.

It is a pain, I opted to just say &FFFF as that was the biggest number I
could return and referred the reader to a more suitable API.

I'm trying to imagine when this would be an issue:

 Compiled code
   You'd know at compile time which CPU it was running on, so can switch
   in the (relevant) more appropriate API call.
 Assembled code
   Likewise, it's 2nd processor specific so can be taylored appropriately
 Interpreted (BASIC) code
   The BASIC interpreter must fall into the compiled/assembled catagory, so
   will know how to find the true top and bottom of memory. This then finds
   its way into PAGE and HIMEM, which the user can read in a CPU agnostic
   way

or did I miss something?
Sprow.