S1Debug API
From S1MP3 Wiki
Contents |
S1MP3 DEBUG API
This is the mp3 players software part of the Debug interface which is needed to enable debugging ability, available through the s1debug console from host.
The s1mp3 debug API is a small piece of code which stays resident at a fixed memory area. It provides several debugging functions:
- puts - output zero-terminated string to host
- putch - output character to host
- puti - output integer to host
- putui - output unsigned integer to host
- getch - read character from host
- brkpnt - stop execution and notify host of breakpoint (standalone)
The API occupies at least two restart locations:
- 0x30 - execute API function (opcode 0xF7)
- 0x38 - breakpoint (opcode 0xFF)
The interrupt entry point for mode 1 maskable interrupts at 0x0036 is still left free for a relative jump instruction (2 bytes). Only bytes 0x30..0x32 and 0x38..0x3A will be occupied.
The code implementation of the API could be located anywhere in ZRAM. A good choice will be to place it at 0x100..0x2FF for example.
COMMUNICATION PROTOCOL
The debug interface provides us with 4 single-directional bits for each direction:
- client -> host: DATA_OUT (bit 5..7, bit 5=MSB), CLK (bit 4)
- host -> client: DATA_OUT (bit 0..2, bit 0=MSB), READY (bit 3)
Basic data exchange protocol:
---client--- ---host--- set DATA_OUT . toggle CLK -> wait until CLK toggles . get DATA . set DATA_OUT (return answer) wait until READY toggles <- toggle READY (resync on timeout) get DATA .
Data gets transfered bytewise with a 1bit odd parity prefix (9th bit) in front of each byte sent (8 bits).
The data bytes get transfered with MSB first.
To syncronize the transfer, host and client use a special syncronization protocol:
---client--- ---host---
send 0x000 (9 zero bits) -> if parity error then resync
wait until 9 zero bits got received
send 3 bit sync-code -> receive sync-code (service number)
while receiving 3 bits <- if service gets accepted
then echo sync-code
repeat whole sequence
until host returned an
echo
API Functions
All API functions get executed by calling the address 0x0030, possibly by using the restart instruction (RST 0x30). The accu register (A) should contain one of the following function id's:
- 0x00: bool puts(char *) - output zero-terminated string to host
- 0x01: bool putch(char) - output character to host
- 0x02: bool puti(int16) - output integer to host
- 0x03: bool putui(uint16) - output unsigned integer to host
- 0x04: char getch(void) - read character from host
The HL register contains the parameter for the function. The API call only takes effect on the accu register, all other registers stay unchanged. If the returned value is zero, the called function has failed.
Related pages
- Debug interface - the piece of hardware needed to connect client and host for debugging
- s1debug - the software on the host side
