
GoSDC OS_Word &B0 API
---------------------

Quick and dirty description of the GoSDC OS_Word &B0 API :

A = &B0 in all cases, and, of course, call &FFF1. May be called from a second
processor as well as the host (but note the memory address on call 3 and 4).

Y = &FF : do NOT use. do not EVER use. It serves controller emulation only and
will not be documented/will change whenever I feel like it.

Otherwise :

X = low byte of info block address
Y = high byte of info block address

Info block :

+0 = total size of info block (input), derive from descriptions below
+1 = total size of info block (output), derive from descriptions below
+2 = reason code (1,2,3,4 or 5 currently)
+3 = reason subcode (depends on reason code)
+4 = usually 1 (see below why)
+5 = reserved, must be 0
+6 onwards depends on reason code and subcode

All reason codes :

+4 on exit is 0 if call was recognized, or 1 if not

Note that if GoSDC is not present, the OS_Word will return unnoticed by ROMs
and +4 will remain 1, indicating failure by default.

Reason code 1 ('return value') :

- Subcode 1 (read GoSDC ROM number) :

  +6 on exit contains GoSDC ROM number (1 byte)

- Subcode 2 (read flash card size) :

  +6 on exit contains card size in bytes (4 bytes)

- Subcode 3 (read address of last selected medium) :

  +6 on exit contains absolute card address (4 bytes)

- Subcode 4 (read size of last selected medium) :

  +6 on exit contains medium size in bytes (4 bytes)

- Subcode 5 (read addresses of selected DFS drives 0,2,1,3) :

  +6 on exit contains absolute card addresses (4 * 4 bytes, 0 if drive absent)

- Subcode 6 (read sizes of selected DFS drives 0,2,1,3) :

  +6 on exit contains drive sizes in bytes (4 * 4 bytes, 0 if drive absent)

- Subcode 7 (read addresses of selected ADFS drives 0,1,4,5) :

  +6 on exit contains absolute card addresses (4 * 4 bytes, 0 if drive absent)

- Subcode 8 (read sizes of selected ADFS drives 0,1,4,5) :

  +6 on exit contains drive sizes in bytes (4 * 4 bytes, 0 if drive absent)

- Subcode 9 (read flash card type) :

  +6 on exit contains flash card type code (1 byte, 0/1/2/&FF for MMC/SD/SDHC/none)

Reason code 2 ('execute command') :

- Subcode 9/10 (issue flash card CMD9/10, see flash card (SPI mode) low level
  documentation) :

  +5 on exit contains internal error code, or 0 if all ok
  +6 on exit contains info (19 bytes) :

    +0  - command response byte
    +1  - 16 bytes info
    +17 - 2 bytes CRC

Reason code 3/4/5 ('raw access') :

Provides raw bulk access to the last selected medium. Note : you should only
use code 3, with subcode bit 6 clear (don't set bit 6 unless you know exactly
what you're doing and accept the risk of corrupting all flash card contents).
Codes 4 and 5 are DFS and ADFS specific calls, for internal use only. Do not
use in your own code.

- Subcode contains flags :

  bit 0  - read (0) or write (1)
  bit 6  - card address is medium relative (0) or absolute (1)
  others - for internal use (any input values are ignored)

  +6  on entry contains 4-byte memory address
  +10 on entry contains 4-byte card address
  +14 on entry contains 3-byte size in bytes

  +5 on exit contains internal error code, or 0 if all ok

Tube transfers are fine. Specify &FFFFxxxx to explicitly address the host.


