Maple Bus driver interface. More...

#include <sys/cdefs.h>
#include <arch/types.h>
#include <sys/queue.h>

Data Structures
struct	maple_frame
	Maple frame to be queued for transport. More...

struct	maple_devinfo
	Maple device info structure. More...

struct	maple_response
	Maple response frame structure. More...

struct	maple_device
	One maple device. More...

struct	maple_port
	Internal representation of a Maple port. More...

struct	maple_driver
	A maple device driver. More...

struct	maple_state_str
	Maple state structure. More...

Macros
#define	MAPLE_DMA_DEBUG 0
	Enable Maple DMA debugging. More...

#define	MAPLE_IRQ_DEBUG 0
	Enable Maple IRQ debugging. More...

#define	MAPLE_BASE 0xa05f6c00
	Maple register base. More...

#define	MAPLE_DMAADDR (MAPLE_BASE+0x04)
	DMA address register. More...

#define	MAPLE_RESET2 (MAPLE_BASE+0x10)
	Reset register #2. More...

#define	MAPLE_ENABLE (MAPLE_BASE+0x14)
	Enable register. More...

#define	MAPLE_STATE (MAPLE_BASE+0x18)
	Status register. More...

#define	MAPLE_SPEED (MAPLE_BASE+0x80)
	Speed register. More...

#define	MAPLE_RESET1 (MAPLE_BASE+0x8c)
	Reset register #1. More...

#define	MAPLE_RESET2_MAGIC 0
	2nd reset value More...

#define	MAPLE_ENABLE_ENABLED 1
	Enable Maple. More...

#define	MAPLE_ENABLE_DISABLED 0
	Disable Maple. More...

#define	MAPLE_STATE_IDLE 0
	Idle state. More...

#define	MAPLE_STATE_DMA 1
	DMA in-progress. More...

#define	MAPLE_SPEED_2MBPS 0
	2Mbps bus speed More...

#define	MAPLE_SPEED_TIMEOUT(n) ((n) << 16)
	Bus timeout macro. More...

#define	MAPLE_RESET1_MAGIC 0x6155404f
	First reset value. More...

#define	MAPLE_RESPONSE_FILEERR -5
	File error. More...

#define	MAPLE_RESPONSE_AGAIN -4
	Try again later. More...

#define	MAPLE_RESPONSE_BADCMD -3
	Bad command sent. More...

#define	MAPLE_RESPONSE_BADFUNC -2
	Bad function code. More...

#define	MAPLE_RESPONSE_NONE -1
	No response. More...

#define	MAPLE_COMMAND_DEVINFO 1
	Device info request. More...

#define	MAPLE_COMMAND_ALLINFO 2
	All info request. More...

#define	MAPLE_COMMAND_RESET 3
	Reset device request. More...

#define	MAPLE_COMMAND_KILL 4
	Kill device request. More...

#define	MAPLE_RESPONSE_DEVINFO 5
	Device info response. More...

#define	MAPLE_RESPONSE_ALLINFO 6
	All info response. More...

#define	MAPLE_RESPONSE_OK 7
	Command completed ok. More...

#define	MAPLE_RESPONSE_DATATRF 8
	Data transfer. More...

#define	MAPLE_COMMAND_GETCOND 9
	Get condition request. More...

#define	MAPLE_COMMAND_GETMINFO 10
	Get memory information. More...

#define	MAPLE_COMMAND_BREAD 11
	Block read. More...

#define	MAPLE_COMMAND_BWRITE 12
	Block write. More...

#define	MAPLE_COMMAND_BSYNC 13
	Block sync. More...

#define	MAPLE_COMMAND_SETCOND 14
	Set condition request. More...

#define	MAPLE_COMMAND_MICCONTROL 15
	Microphone control. More...

#define	MAPLE_COMMAND_CAMCONTROL 17
	Camera control. More...

#define	MAPLE_FUNC_PURUPURU 0x00010000
	Jump pack. More...

#define	MAPLE_FUNC_MOUSE 0x00020000
	Mouse. More...

#define	MAPLE_FUNC_CAMERA 0x00080000
	Camera (Dreameye) More...

#define	MAPLE_FUNC_CONTROLLER 0x01000000
	Controller. More...

#define	MAPLE_FUNC_MEMCARD 0x02000000
	Memory card. More...

#define	MAPLE_FUNC_LCD 0x04000000
	LCD screen. More...

#define	MAPLE_FUNC_CLOCK 0x08000000
	Clock. More...

#define	MAPLE_FUNC_MICROPHONE 0x10000000
	Microphone. More...

#define	MAPLE_FUNC_ARGUN 0x20000000
	AR gun? More...

#define	MAPLE_FUNC_KEYBOARD 0x40000000
	Keyboard. More...

#define	MAPLE_FUNC_LIGHTGUN 0x80000000
	Lightgun. More...

#define	MAPLE_FRAME_VACANT 0
	Ready to be used. More...

#define	MAPLE_FRAME_UNSENT 1
	Ready to be sent. More...

#define	MAPLE_FRAME_SENT 2
	Frame has been sent, but no response yet. More...

#define	MAPLE_FRAME_RESPONDED 3
	Frame has a response. More...

#define	MAPLE_PORT_COUNT 4
	Number of ports on the bus. More...

#define	MAPLE_UNIT_COUNT 6
	Max number of units per port. More...

#define	MAPLE_DMA_SIZE 16384
	Maple DMA buffer size. More...

#define	maple_read(A) ( ((vuint32)(A)) )
	Maple memory read macro. More...

#define	maple_write(A, V) ( ((vuint32)(A)) = (V) )
	Maple memory write macro. More...

#define	MAPLE_EOK 0
	No error. More...

#define	MAPLE_EFAIL -1
	Command failed. More...

#define	MAPLE_EAGAIN -2
	Try again later. More...

#define	MAPLE_EINVALID -3
	Invalid command. More...

#define	MAPLE_ENOTSUPP -4
	Command not suppoted by device. More...

#define	MAPLE_ETIMEOUT -5
	Command timed out. More...

#define	MAPLE_FOREACH_BEGIN(TYPE, VARTYPE, VAR)
	Begin a foreach loop over Maple devices. More...

#define	MAPLE_FOREACH_END()
	End a foreach loop over Maple devices. More...

Typedefs
typedef struct maple_frame	maple_frame_t
	Maple frame to be queued for transport. More...

typedef struct maple_devinfo	maple_devinfo_t
	Maple device info structure. More...

typedef struct maple_response	maple_response_t
	Maple response frame structure. More...

typedef struct maple_device	maple_device_t
	One maple device. More...

typedef struct maple_port	maple_port_t
	Internal representation of a Maple port. More...

typedef struct maple_driver	maple_driver_t
	A maple device driver. More...

typedef struct maple_state_str	maple_state_t
	Maple state structure. More...

Functions
void	maple_bus_enable ()
	Enable the Maple bus. More...

void	maple_bus_disable ()
	Disable the Maple bus. More...

void	maple_dma_start ()
	Start a Maple DMA. More...

void	maple_dma_stop ()
	Stop a Maple DMA. More...

int	maple_dma_in_progress ()
	Is a Maple DMA in progress? More...

void	maple_dma_addr (void *ptr)
	Set the Maple DMA address. More...

uint8	maple_addr (int port, int unit)
	Return a "maple address" for a port, unit pair. More...

void	maple_raddr (uint8 addr, int port, int unit)
	Decompose a "maple address" into a port, unit pair. More...

const char *	maple_pcaps (uint32 functions)
	Return a string with the capabilities of a given function code. More...

const char *	maple_perror (int response)
	Return a string representing the maple response code. More...

int	maple_dev_valid (int p, int u)
	Determine if a given device is valid. More...

void	maple_queue_flush ()
	Send all queued frames. More...

int	maple_queue_frame (maple_frame_t *frame)
	Submit a frame for queueing. More...

int	maple_queue_remove (maple_frame_t *frame)
	Remove a used frame from the queue. More...

void	maple_frame_init (maple_frame_t *frame)
	Initialize a new frame to prepare it to be placed on the queue. More...

int	maple_frame_lock (maple_frame_t *frame)
	Lock a frame so that someone else can't use it in the mean time. More...

void	maple_frame_unlock (maple_frame_t *frame)
	Unlock a frame. More...

int	maple_driver_reg (maple_driver_t *driver)
	Register a maple device driver. More...

int	maple_driver_unreg (maple_driver_t *driver)
	Unregister a maple device driver. More...

int	maple_driver_attach (maple_frame_t *det)
	Attach a maple device to a driver, if possible. More...

int	maple_driver_detach (int p, int u)
	Detach an attached maple device. More...

int	maple_driver_foreach (maple_driver_t drv, int(callback)(maple_device_t *))
	For each device which the given driver controls, call the callback. More...

void	maple_vbl_irq_hnd (uint32 code)
	Called on every VBL (~60fps). More...

void	maple_dma_irq_hnd (uint32 code)
	Called after a Maple DMA send / receive pair completes. More...

int	maple_enum_count ()
	Return the number of connected devices. More...

maple_device_t *	maple_enum_dev (int p, int u)
	Get a raw device info struct for the given device. More...

maple_device_t *	maple_enum_type (int n, uint32 func)
	Get the Nth device of the requested type (where N is zero-indexed). More...

maple_device_t *	maple_enum_type_ex (int n, uint32 func, uint32 cap)
	Return the Nth device that is of the requested type and supports the list of capabilities given. More...

void *	maple_dev_status (maple_device_t *dev)
	Get the status struct for the requested maple device. More...

int	maple_init ()
	Initialize Maple. More...

void	maple_shutdown ()
	Shutdown Maple. More...

void	maple_wait_scan ()
	Wait for the initial bus scan to complete. More...

Variables
maple_state_t	maple_state
	Global state info. More...

Detailed Description

Maple Bus driver interface.

This file provides support for accessing the Maple bus on the Dreamcast. Maple is the bus that all of your controllers and memory cards and the like connect to, so this is one of those types of things that are quite important to know how to use.

Each peripheral device registers their driver within this system, and can be accessed through the functions here. Most of the drivers have their own functionality that is implemented in their header files, as well.

Author: Dan Potter; Lawrence Sebald

See also: dc/maple/controller.h; dc/maple/dreameye.h; dc/maple/keyboard.h; dc/maple/mouse.h; dc/maple/purupuru.h; dc/maple/sip.h; dc/maple/vmu.h

Macro Definition Documentation

#define MAPLE_DMA_DEBUG 0

Enable Maple DMA debugging.

Changing this to a 1 will add massive amounts of processing time to the maple system in general, but it can help in verifying DMA errors. In general, for most purposes this should stay disabled.

#define MAPLE_DMA_SIZE 16384

Maple DMA buffer size.

Increase if you do a LOT of maple stuff on every periodic interrupt.

#define MAPLE_FOREACH_BEGIN	(	TYPE,
		VARTYPE,
		VAR
	)

Value:

do { \
        maple_device_t  * __dev; \
        VARTYPE * VAR; \
        int __i; \
        \
        __i = 0; \
        while ( (__dev = maple_enum_type(__i, TYPE)) ) { \
            VAR = (VARTYPE *)maple_dev_status(__dev); \
            do {

Begin a foreach loop over Maple devices.

This macro (along with the MAPLE_FOREACH_END() one) implements a simple foreach-style loop over the given type of devices. Essentially, it grabs the status of the device, and leaves it to you to figure out what to do with it.

The most common use of this would be to look for input on any controller.

Parameters

TYPE	The function code of devices to look at.
VARTYPE	The type to cast the return value of maple_dev_status() to.
VAR	The name of the result of maple_dev_status().

#define MAPLE_FOREACH_END ( )

Value:

} while(0); \
    __i++; \
    } \
    } while(0);

End a foreach loop over Maple devices.

Each MAPLE_FOREACH_BEGIN() must be paired with one of these after the loop body.

#define MAPLE_IRQ_DEBUG 0

Enable Maple IRQ debugging.

Changing this to a 1 will turn on intra-interrupt debugging messages, which may cause issues if you're using dcload rather than a raw serial debug terminal. You probably will never have a good reason to enable this, so keep it disabled for normal use.

#define MAPLE_PORT_COUNT 4

Number of ports on the bus.

#define maple_read ( A ) ( *((vuint32*)(A)) )

Maple memory read macro.

#define MAPLE_UNIT_COUNT 6

Max number of units per port.

#define maple_write	(	A,
		V
	)	( ((vuint32)(A)) = (V) )

Maple memory write macro.

Typedef Documentation

typedef struct maple_device maple_device_t

One maple device.

Note that we duplicate the port/unit info which is normally somewhat implicit so that we can pass around a pointer to a particular device struct.

typedef struct maple_devinfo maple_devinfo_t

Maple device info structure.

This structure is used by the hardware to deliver the response to the device info request.

typedef struct maple_driver maple_driver_t

A maple device driver.

Anything which is added to this list is capable of handling one or more maple device types. When a device of the given type is connected (includes startup "connection"), the driver is invoked. This same process happens for disconnection, response receipt, and on a periodic interval (for normal updates).

typedef struct maple_frame maple_frame_t

Maple frame to be queued for transport.

Internal representation of a frame to be queued up for sending.

typedef struct maple_port maple_port_t

Internal representation of a Maple port.

each maple port can contain up to 6 devices, the first one of which is always the port itself.

typedef struct maple_response maple_response_t

Maple response frame structure.

This structure is used to deliver the actual response to a request placed. The data field is where all the interesting stuff will be.

typedef struct maple_state_str maple_state_t

Maple state structure.

We put everything in here to keep from polluting the global namespace too much.

Function Documentation

uint8 maple_addr	(	int	port,
		int	unit
	)

Return a "maple address" for a port, unit pair.

Parameters

port	The port to build the address for.
unit	The unit to build the address for.

Returns: The Maple address of the pair.

void maple_bus_disable ( )

Disable the Maple bus.

There's really not many good reasons to be mucking with this at runtime.

void maple_bus_enable ( )

Enable the Maple bus.

This will be done for you autmatically at init time, and there's probably not many reasons to be doing this during runtime.

void* maple_dev_status ( maple_device_t * dev )

Get the status struct for the requested maple device.

This function will wait until the status is valid before returning. You should cast to the appropriate type you're expecting.

Parameters

dev	The device to look up.

Returns: The device's status.

int maple_dev_valid	(	int	p,
		int	u
	)

Determine if a given device is valid.

Parameters

p	The port to check.
u	The unit to check.

Returns: Non-zero if the device is valid.

void maple_dma_addr ( void * ptr )

Set the Maple DMA address.

Once again, you should not muck around with this in your programs.

int maple_dma_in_progress ( )

Is a Maple DMA in progress?

Returns: Non-zero if a DMA is in progress.

void maple_dma_irq_hnd ( uint32 code )

Called after a Maple DMA send / receive pair completes.

Parameters

code	The ASIC event code.

void maple_dma_start ( )

Start a Maple DMA.

This stuff will all be handled internally, so there's probably no reason to be doing this yourself.

void maple_dma_stop ( )

Stop a Maple DMA.

This stuff will all be handled internally, so there's probably no reason to be doing this yourself.

int maple_driver_attach ( maple_frame_t * det )

Attach a maple device to a driver, if possible.

Parameters

det	The detection frame.

Return values

0	On success.
-1	If no driver is available.

int maple_driver_detach	(	int	p,
		int	u
	)

Detach an attached maple device.

Parameters

p	The port of the device to detach.
u	The unit of the device to detach.

Return values

0	On success.
-1	If the device wasn't valid.

int maple_driver_foreach	(	maple_driver_t *	drv,
		int()(maple_device_t )	callback
	)

For each device which the given driver controls, call the callback.

Parameters

drv	The driver to loop through devices of.
callback	The function to call. The parameter is the device that it is being called on. It should return 0 on success, and <0 on failure.

Return values

0	On success.
-1	If any callbacks return <0.

int maple_driver_reg ( maple_driver_t * driver )

Register a maple device driver.

This should be done before calling maple_init().

Return values

0	On success (no error conditions defined).

int maple_driver_unreg ( maple_driver_t * driver )

Unregister a maple device driver.

Return values

0	On success (no error conditions defined).

int maple_enum_count ( )

Return the number of connected devices.

Returns: The number of devices connected.

maple_device_t* maple_enum_dev	(	int	p,
		int	u
	)

Get a raw device info struct for the given device.

Parameters

p	The port to look up.
u	The unit to look up.

Returns: The device at that address, or NULL if no device is there.

maple_device_t* maple_enum_type	(	int	n,
		uint32	func
	)

Get the Nth device of the requested type (where N is zero-indexed).

Parameters

n	The index to look up.
func	The function code to look for.

Returns: The device found, if any. NULL otherwise.

maple_device_t* maple_enum_type_ex	(	int	n,
		uint32	func,
		uint32	cap
	)

Return the Nth device that is of the requested type and supports the list of capabilities given.

Note, this only currently makes sense for controllers, since some devices don't necessarily use the function data in the same manner that controllers do (and controllers are the only devices where we have a list of what all the bits mean at the moment).

Parameters

n	The index to look up.
func	The function code to look for.
cap	Capabilities bits to look for.

Returns: The device found, if any. NULL otherwise.

void maple_frame_init ( maple_frame_t * frame )

Initialize a new frame to prepare it to be placed on the queue.

You should call this before you fill in the frame data.

Parameters

frame The frame to initialize.

int maple_frame_lock ( maple_frame_t * frame )

Lock a frame so that someone else can't use it in the mean time.

Return values

0	On success.
-1	If the frame is already locked.

void maple_frame_unlock ( maple_frame_t * frame )

Unlock a frame.

int maple_init ( )

Initialize Maple.

Returns: 0 on success, <0 on failure.

const char* maple_pcaps ( uint32 functions )

Return a string with the capabilities of a given function code.

This function is not re-entrant, and thus NOT THREAD SAFE.

Parameters

functions The list of function codes.

Returns: A string containting the capabilities.

const char* maple_perror ( int response )

Return a string representing the maple response code.

Parameters

response The response code returned from the function.

Returns: A string containing a textual respresentation of the response code.

void maple_queue_flush ( )

Send all queued frames.

int maple_queue_frame ( maple_frame_t * frame )

Submit a frame for queueing.

This will generally be called inside the periodic interrupt; however, if you need to do something asynchronously (e.g., VMU access) then it might cause some problems. In this case, the function will automatically do locking by disabling interrupts temporarily. In any case, the callback will be done inside an IRQ context.

Parameters

frame The frame to queue up.

Return values

0	On success.
-1	If the frame is already queued.

int maple_queue_remove ( maple_frame_t * frame )

Remove a used frame from the queue.

This will be done automatically when the frame is consumed.

Parameters

frame The frame to remove from the queue.

Return values

0	On success.
-1	If the frame is not queued.

void maple_raddr	(	uint8	addr,
		int *	port,
		int *	unit
	)

Decompose a "maple address" into a port, unit pair.

WARNING: This function will not work with multi-cast addresses!

Parameters

addr	The input address.
port	Output space for the port of the address.
unit	Output space for the unit of the address.

void maple_shutdown ( )

Shutdown Maple.

void maple_vbl_irq_hnd ( uint32 code )

Called on every VBL (~60fps).

Parameters

code	The ASIC event code.

void maple_wait_scan ( )

Wait for the initial bus scan to complete.

Variable Documentation

maple_state_t maple_state

Global state info.

Do not manipulate this state yourself, as it will likely break things if you do so.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation

Variable Documentation