WonderWitch/FreyaBIOS/Communication

The Communication (comm) interrupt provides an abstraction layer and helpers for the WonderSwan's serial port.

Interrupts

INT $14/AH=$00 - comm_open

• AH = $00

Opens the serial port. Note that the baud rate must be set before calling comm_open.

INT $14/AH=$01 - comm_close

• AH = $01

Closes the serial port.

INT $14/AH=$02 - comm_send_char

• AH = $02
• BL = Character (byte) to send.

Return:

• AX = Return code.

Return codes:

• 0x0000 - Success
• 0x8101 - Transfer timeout
• 0x8102 - Transfer RX overrun
• 0x8103 - Transfer cancelled

INT $14/AH=$03 - comm_receive_char

• AH = $03

Return:

• AX = Character (byte) read (0x0000 - 0xFFFF) or error return code.

INT $14/AH=$04 - comm_receive_with_timeout

• AH = $03
• CX = Timeout, in frames (as in comm_set_timeout).

Return:

• AX = Character (byte) read (0x0000 - 0xFFFF) or error return code.

Unlike comm_receive_char, this function uses an user-provided timeout.

INT $14/AH=$05 - comm_send_string

• AH = $05
• DS:DX = Input string to send.

Return:

• AX = Return code.

INT $14/AH=$06 - comm_send_block

• AH = $06
• CX = Buffer size, in bytes.
• DS:DX = Input buffer to send.

Return:

• AX = Return code.

INT $14/AH=$07 - comm_receive_block

• AH = $07
• CX = Buffer size, in bytes.
• DS:DX = Buffer to receive bytes to.

Return:

• AX = Return code.
• DX = Number of bytes successfully received.

INT $14/AH=$08 - comm_set_timeout

• AH = $08
• BX = Receive timeout (in frames; 0xFFFF - wait forever)
• CX = Send timeout (in frames; 0xFFFF - wait forever)

INT $14/AH=$09 - comm_set_baudrate

• AH = $09
• BX = Baud rate (0 = 9600 bps, 1 = 38400 bps).

Only affects newly opened serial port connections.

INT $14/AH=$0A - comm_get_baudrate

• AH = $0A

Return:

• AX = Baud rate (0 = 9600 bps, 1 = 38400 bps).

INT $14/AH=$0B - comm_set_cancel_key

• AH = $0B
• BX = Cancel key combination.

INT $14/AH=$0C - comm_get_cancel_key

• AH = $0C

Return:

• AX = Cancel key combination.

INT $14/AH=$0D - comm_xmodem

• AH = $0D
• DS:BX = pointer to XMODEM state structure

Returns:

• AX = new state (equal to State in the structure)

Usage

To use comm_xmodem, allocate the state structure and set the following values:

• State = $0001 ("Start")
• Mode = your mode of choice
• Maximum number of blocks = the transfer size, in XMODEM blocks
• Bank, Offset = the transfer source/destination

Next, keep calling comm_xmodem until the "Done" state, or an error, is returned.

Data structures

XMODEM state structure

Offset	Size	Description
$00	2	State (or error code, if bit 15 set)
$02	1	Mode
$03	1	Number of total block transfer retries performed
$04	2	Number of blocks received/sent
$06	2	Maximum number of blocks to receive Number of blocks to send
$08	2	Size of block, typically 128 bytes
$0A	2	Bank to write to/read from
$0C	2	Offset to write to/read from
$0E	2	?

XMODEM state values

Value	Description
$0001	Start Set initial values: Number of retries = 0 Current block = 0 Block size = 128 bytes Goes to state "Negotiate".
$0002	Negotiate Also receives the first block. Goes to state "Block".
$0003	Block Sends or receives a block. Goes to state "Block" (if successful), "Retry Block" (if failed), or "Close" (if transfer complete).
$0004	Retry Block Same as Block.
$0005	Close Finishes the XMODEM transfer. Goes to state "Done".
$0006	Abort Treated as an "Invalid state value".
$0007	Done Treated as an "Invalid state value".
$0008	Erase bank Goes to state "Block".
$8100	Serial I/O: Busy
$8101	Serial I/O: Transfer timeout
$8102	Serial I/O: Transfer RX overrun
$8103	Serial I/O: Transfer cancelled
$8104	Invalid state value
$8105	XMODEM transfer cancelled
$8106	XMODEM block lost during transfer
$8107	XMODEM transfer too large

XMODEM mode:

7  bit  0
---- ----
.... .?od
       ||
       |+- Direction: 0 = Send, 1 = Receive
       +-- Enable obfuscation