Joybus

Joybus library core functionality. More...

Data Structures
struct	joybus_api
struct	joybus_host_op
struct	joybus
	A Joybus instance. More...
struct	joybus_sync_ctx

Macros
#define	JOYBUS_USE_RAM_FUNCS   1
	Whether to place latency-critical functions in RAM.
#define	JOYBUS_RAM_FUNC
	Attribute for a latency-critical function, such as a target command handler.
#define	JOYBUS_FREQ_NOMINAL   250000
	Nominal Joybus frequency, matching an OEM N64/GameCube controller.
#define	JOYBUS_FREQ_N64_CONSOLE   244141
	Joybus frequency of an N64 console (NUS-001).
#define	JOYBUS_FREQ_N64_EXTJOY   JOYBUS_FREQ_N64_CONSOLE
	Joybus frequency of an external joybus device (EEPROM/RTC on an N64 cartridge).
#define	JOYBUS_FREQ_N64_CONTROLLER   250000
	Joybus frequency of an N64 controller (NUS-005).
#define	JOYBUS_FREQ_N64_VRU   250000
	Joybus frequency of an N64 VRU (NUS-020).
#define	JOYBUS_FREQ_GCN_CONSOLE   202500
	Joybus frequency of a GameCube console (DOL-001 / DOL-101).
#define	JOYBUS_FREQ_GCN_CONTROLLER   250000
	Joybus frequency of a GameCube controller (DOL-003).
#define	JOYBUS_FREQ_WAVEBIRD_RECEIVER   225000
	Joybus frequency of WaveBird receiver (DOL-005)
#define	JOYBUS_FREQ_WII_CONSOLE   202500
	Joybus frequency of a Wii console (RVL-001 / RVL-101 / RVL-201).
#define	JOYBUS_FREQ_GCN_GBA_CABLE   262144
	Joybus frequency of a GameCube Game Boy Advance cable (DOL-011).
#define	JOYBUS_INTER_TRANSFER_DELAY_US   80
	Minimum delay between Joybus transfers, in microseconds.
#define	JOYBUS_REPLY_TIMEOUT_US   64
	Timeout for waiting for a reply from a target, in microseconds.
#define	JOYBUS_BUS_IDLE_US   100
	Minimum line-high time to consider the bus idle, in microseconds.
#define	JOYBUS_BLOCK_SIZE   64
	Maximum size of a Joybus transfer, in bytes.
#define	JOYBUS_PAK_BLOCK_SIZE   32
	Size of a Joybus N64 pak read/write block.
#define	JOYBUS(bus)
	Macro to cast a backend-specific Joybus instance to a generic Joybus instance.

Typedefs
typedef void(*	joybus_transfer_cb) (struct joybus *bus, int status, void *user_data)
	Function type for transfer completion callbacks.

Enumerations
enum	joybus_mode {   JOYBUS_MODE_HOST ,   JOYBUS_MODE_TARGET }
	The role a Joybus instance plays on the bus. More...
enum	joybus_error {   JOYBUS_ERR_DISABLED = 1 ,   JOYBUS_ERR_BUSY ,   JOYBUS_ERR_TIMEOUT ,   JOYBUS_ERR_NOT_SUPPORTED ,   JOYBUS_ERR_CHECKSUM ,   JOYBUS_ERR_NO_DEVICE }
	Joybus error codes. More...

Functions
static int	joybus_enable (struct joybus *bus, enum joybus_mode mode)
	Enable the Joybus instance in the given mode.
static int	joybus_disable (struct joybus *bus)
	Disable the Joybus instance.
static int	joybus_transfer (struct joybus *bus, const uint8_t *write_buf, uint8_t write_len, uint8_t *read_buf, uint8_t read_len, joybus_transfer_cb callback, void *user_data)
	Perform a Joybus "write then read" transfer.
int	joybus_transfer_sync (struct joybus *bus, const uint8_t *write_buf, uint8_t write_len, uint8_t *read_buf, uint8_t read_len)
	Perform a synchronous "write then read" Joybus transfer.
static int	joybus_attach_target (struct joybus *bus, struct joybus_target *target)
	Attach a target to handle commands received in target mode.
static int	joybus_detach_target (struct joybus *bus, struct joybus_target *target)
	Detach a target from the bus.
void	joybus_sync_cb (struct joybus *bus, int status, void *user_data)
int	joybus_sync (int start_status, struct joybus_sync_ctx *ctx)
uint8_t	joybus_data_checksum_update (uint8_t crc, uint8_t byte)
	Fold one byte into a running Joybus data checksum.
uint8_t	joybus_data_checksum (const uint8_t *data, size_t size)
	Compute the CRC-8 checksum of a Joybus data buffer.
uint8_t	joybus_address_checksum (uint16_t addr)
	Compute the CRC-5 address checksum for data transfer commands.

Detailed Description

Joybus library core functionality.

Checksum routines used by various Joybus data transfer commands.

Macro Definition Documentation

JOYBUS

#define JOYBUS

(

bus

)

Value:

((struct joybus *)(bus))

Macro to cast a backend-specific Joybus instance to a generic Joybus instance.

JOYBUS_RAM_FUNC

#define JOYBUS_RAM_FUNC

Attribute for a latency-critical function, such as a target command handler.

Places it in RAM instead of executing it in place from flash, so a flash fetch or cache miss cannot add latency to the response. A no-op when JOYBUS_USE_RAM_FUNCS is 0, or on platforms that are not yet wired up.

JOYBUS_USE_RAM_FUNCS

#define JOYBUS_USE_RAM_FUNCS   1

Whether to place latency-critical functions in RAM.

Enabled by default, for a deterministic command-to-response turnaround. Define as 0 to keep them in flash, saving RAM at the cost of a variable turnaround (a flash fetch or cache miss can slow a reply).

Typedef Documentation

joybus_transfer_cb

typedef void(* joybus_transfer_cb) (struct joybus *bus, int status, void *user_data)

Function type for transfer completion callbacks.

Invoked once, after the async call has returned, when a started transfer completes. Runs in transfer-completion context, which is an interrupt on most backends, so it must not block.

Parameters

bus	the Joybus associated with the transfer
status	0 on success, a negative joybus_error on failure
user_data	the user_data passed to the async function

Enumeration Type Documentation

joybus_error

enum joybus_error

Joybus error codes.

Errors are reported as negatives of these codes. Functions return 0 on success or a negative joybus_error on failure, and the status passed to a transfer callback uses the same convention. If an async function returns an error, the transfer did not start, so its callback is not invoked.

Enumerator
JOYBUS_ERR_DISABLED	Bus not enabled.
JOYBUS_ERR_BUSY	Bus is busy with another operation.
JOYBUS_ERR_TIMEOUT	Transfer timed out.
JOYBUS_ERR_NOT_SUPPORTED	Command not supported by Joybus target.
JOYBUS_ERR_CHECKSUM	Checksum error.
JOYBUS_ERR_NO_DEVICE	Expected device not detected.

joybus_mode

enum joybus_mode

The role a Joybus instance plays on the bus.

Enumerator
JOYBUS_MODE_HOST	Host mode, sends commands and reads responses from a target device.
JOYBUS_MODE_TARGET	Target mode, listens for commands from a host device and responds accordingly.

Function Documentation

joybus_address_checksum()

uint8_t joybus_address_checksum

(

uint16_t

addr

)

Compute the CRC-5 address checksum for data transfer commands.

Parameters

addr	an 11 bit address to checksum

Returns

CRC-5 checksum of the address

joybus_attach_target()

int joybus_attach_target ( struct joybus * bus, struct joybus_target * target )

inlinestatic

Attach a target to handle commands received in target mode.

Parameters

bus	the Joybus instance to use
target	the target to attach

Returns

0 on success, a negative joybus_error on failure

joybus_data_checksum()

uint8_t joybus_data_checksum	(	const uint8_t *	data,
		size_t	size )

Compute the CRC-8 checksum of a Joybus data buffer.

Parameters

data	buffer to checksum
size	number of bytes in data

Returns

the CRC-8 checksum of the buffer

joybus_data_checksum_update()

uint8_t joybus_data_checksum_update	(	uint8_t	crc,
		uint8_t	byte )

Fold one byte into a running Joybus data checksum.

Seed crc with 0 on the first call and pass the result back in on subsequent calls to compute the checksum over a stream of bytes.

Parameters

crc	running checksum value, or 0 to start a fresh checksum
byte	next byte to fold in

Returns

updated running checksum after folding in byte

joybus_detach_target()

int joybus_detach_target ( struct joybus * bus, struct joybus_target * target )

inlinestatic

Detach a target from the bus.

Parameters

bus	the Joybus instance to use
target	the target to detach

Returns

0 on success, a negative joybus_error on failure

joybus_disable()

int joybus_disable ( struct joybus * bus )

inlinestatic

Disable the Joybus instance.

Parameters

bus	the Joybus instance to disable

joybus_enable()

int joybus_enable ( struct joybus * bus, enum joybus_mode mode )

inlinestatic

Enable the Joybus instance in the given mode.

Spins up the backend peripherals and starts operating as a host or a target. The mode applies until the instance is disabled; to switch modes, disable the instance and enable it again with the other mode.

Parameters

bus	the Joybus instance to enable
mode	whether to operate as a host or a target

joybus_transfer()

int joybus_transfer ( struct joybus * bus, const uint8_t * write_buf, uint8_t write_len, uint8_t * read_buf, uint8_t read_len, joybus_transfer_cb callback, void * user_data )

inlinestatic

Perform a Joybus "write then read" transfer.

Sends a command to a device and reads the response. Returns once the transfer has started, and callback is invoked with the status when it completes. The provided buffers must stay valid until the callback runs.

Parameters

bus	the Joybus instance to use
write_buf	the buffer containing the command to send
write_len	the number of bytes to write
read_buf	the buffer to store the response in
read_len	the number of bytes to read
callback	invoked once when the transfer completes
user_data	user data to pass to the callback

Returns

0 if the transfer was started, a negative joybus_error otherwise

joybus_transfer_sync()

int joybus_transfer_sync	(	struct joybus *	bus,
		const uint8_t *	write_buf,
		uint8_t	write_len,
		uint8_t *	read_buf,
		uint8_t	read_len )

Perform a synchronous "write then read" Joybus transfer.

Sends a command to a device and blocks until the response arrives.

Parameters

bus	the Joybus instance to use
write_buf	the buffer containing the command to send
write_len	the number of bytes to write
read_buf	the buffer to store the response in
read_len	the number of bytes to read

Returns

0 on success, a negative joybus_error on failure

Warning

Blocks by busy-waiting, so it must not be called from an interrupt or timer callback. Use joybus_transfer() there.