Maple Bus

Driver for the Dreamcast's Maple Peripheral Bus More...

Topics
	Commands and Responses
	Maple command and response values
	Frame States
	States for a maple frame
	Function Codes
	Values of maple "function" codes
	Register Values
	Values for various maple registers
	Registers
	Addresses for various maple registers
	Return Values
	Return codes from maple access functions

Files
file	maple.h
	Maple Bus driver interface.

Data Structures
struct	maple_frame_t
	Maple frame to be queued for transport. More...
struct	maple_devinfo_t
	Maple device info structure. More...
struct	maple_response_t
	Maple response frame structure. More...
struct	maple_device_t
	One maple device. More...
struct	maple_port_t
	Internal representation of a Maple port. More...
struct	maple_driver_t
	A maple device driver. More...
struct	maple_state_t
	Maple state structure. More...

Macros
#define	MAPLE_DMA_DEBUG   0
	Enable Maple DMA debugging.
#define	MAPLE_IRQ_DEBUG   0
	Enable Maple IRQ debugging.
#define	MAPLE_DMA_SIZE   16384
	Maple DMA buffer size.
#define	maple_read(A)   ( *((vuint32*)(A)) )
	Maple memory read macro.
#define	maple_write(A, V)   ( *((vuint32*)(A)) = (V) )
	Maple memory write macro.
#define	MAPLE_FOREACH_BEGIN(TYPE, VARTYPE, VAR)
	Begin a foreach loop over Maple devices.
#define	MAPLE_FOREACH_END()
	End a foreach loop over Maple devices.

Typedefs
typedef void(*	maple_attach_callback_t) (maple_device_t *dev)
	Maple attach callback type.
typedef void(*	maple_detach_callback_t) (maple_device_t *dev)
	Maple detach callback type.

Functions
void	maple_bus_enable (void)
	Enable the Maple bus.
void	maple_bus_disable (void)
	Disable the Maple bus.
void	maple_dma_start (void)
	Start a Maple DMA.
void	maple_dma_stop (void)
	Stop a Maple DMA.
int	maple_dma_in_progress (void)
	Is a Maple DMA in progress?
void	maple_dma_addr (void *ptr)
	Set the Maple DMA address.
uint8	maple_addr (int port, int unit)
	Return a "maple address" for a port, unit pair.
void	maple_raddr (uint8 addr, int *port, int *unit)
	Decompose a "maple address" into a port, unit pair.
const char *	maple_pcaps (uint32 functions)
	Return a string with the capabilities of a given function code.
const char *	maple_perror (int response)
	Return a string representing the maple response code.
int	maple_dev_valid (int p, int u)
	Determine if a given device is valid.
int	maple_gun_enable (int port)
	Enable light gun mode for this frame.
void	maple_gun_disable (void)
	Disable light gun mode.
void	maple_gun_read_pos (int *x, int *y)
	Read the light gun position values.
void	maple_queue_flush (void)
	Send all queued frames.
int	maple_queue_frame (maple_frame_t *frame)
	Submit a frame for queueing.
int	maple_queue_remove (maple_frame_t *frame)
	Remove a used frame from the queue.
void	maple_frame_init (maple_frame_t *frame)
	Initialize a new frame to prepare it to be placed on the queue.
int	maple_frame_lock (maple_frame_t *frame)
	Lock a frame so that someone else can't use it in the mean time.
void	maple_frame_unlock (maple_frame_t *frame)
	Unlock a frame.
int	maple_driver_reg (maple_driver_t *driver)
	Register a maple device driver.
int	maple_driver_unreg (maple_driver_t *driver)
	Unregister a maple device driver.
int	maple_driver_attach (maple_frame_t *det)
	Attach a maple device to a driver, if possible.
int	maple_driver_detach (int p, int u)
	Detach an attached maple device.
int	maple_driver_foreach (maple_driver_t *drv, int(*callback)(maple_device_t *))
	For each device which the given driver controls, call the callback.
void	maple_attach_callback (uint32 functions, maple_attach_callback_t cb)
	Set an automatic maple attach callback.
void	maple_detach_callback (uint32 functions, maple_detach_callback_t cb)
	Set an automatic maple detach callback.
void	maple_vbl_irq_hnd (uint32 code, void *data)
	Called on every VBL (~60fps).
void	maple_dma_irq_hnd (uint32 code, void *data)
	Called after a Maple DMA send / receive pair completes.
int	maple_enum_count (void)
	Return the number of connected devices.
maple_device_t *	maple_enum_dev (int p, int u)
	Get a raw device info struct for the given device.
maple_device_t *	maple_enum_type (int n, uint32 func)
	Get the Nth device of the requested type (where N is zero-indexed).
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.
void *	maple_dev_status (maple_device_t *dev)
	Get the status struct for the requested maple device.
void	maple_init (void)
	Initialize Maple.
void	maple_shutdown (void)
	Shutdown Maple.
void	maple_wait_scan (void)
	Wait for the initial bus scan to complete.

Detailed Description

Driver for the Dreamcast's Maple Peripheral Bus

Macro Definition Documentation

MAPLE_DMA_DEBUG

#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.

MAPLE_DMA_SIZE

#define MAPLE_DMA_SIZE   16384

Maple DMA buffer size.

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

MAPLE_FOREACH_BEGIN

#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().

MAPLE_FOREACH_END

#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.

MAPLE_IRQ_DEBUG

#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.

maple_read

#define maple_read

(

A

)

( *((vuint32*)(A)) )

Maple memory read macro.

maple_write

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

Maple memory write macro.

Typedef Documentation

maple_attach_callback_t

typedef void(* maple_attach_callback_t) (maple_device_t *dev)

Maple attach callback type.

Functions of this type can be set with maple_attach_callback() to respond automatically to the attachment of a maple device that supports specified functions.

maple_detach_callback_t

typedef void(* maple_detach_callback_t) (maple_device_t *dev)

Maple detach callback type.

Functions of this type can be set with maple_detach_callback() to respond automatically to the detachment of a maple device that supports specified functions.

Function Documentation

maple_addr()

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.

maple_attach_callback()

void maple_attach_callback	(	uint32	functions,
		maple_attach_callback_t	cb )

Set an automatic maple attach callback.

This function sets a callback function to be called when the specified maple device that supports functions has been attached.

Parameters

functions	The functions maple device must support. Set to 0 to support all maple devices.
cb	The callback to call when the maple is attached.

maple_bus_disable()

void maple_bus_disable

(

void

)

Disable the Maple bus.

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

maple_bus_enable()

void maple_bus_enable

(

void

)

Enable the Maple bus.

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

maple_detach_callback()

void maple_detach_callback	(	uint32	functions,
		maple_detach_callback_t	cb )

Set an automatic maple detach callback.

This function sets a callback function to be called when the specified maple device that supports functions has been detached.

Parameters

functions	The functions maple device must support. Set to 0 to support all maple devices.
cb	The callback to call when the maple is detached.

maple_dev_status()

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.

maple_dev_valid()

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.

maple_dma_addr()

void maple_dma_addr

(

void *

ptr

)

Set the Maple DMA address.

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

maple_dma_in_progress()

int maple_dma_in_progress

(

void

)

Is a Maple DMA in progress?

Returns

Non-zero if a DMA is in progress.

maple_dma_irq_hnd()

void maple_dma_irq_hnd	(	uint32	code,
		void *	data )

Called after a Maple DMA send / receive pair completes.

Parameters

code	The ASIC event code.
data	The user pointer associated with this callback.

maple_dma_start()

void maple_dma_start

(

void

)

Start a Maple DMA.

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

maple_dma_stop()

void maple_dma_stop

(

void

)

Stop a Maple DMA.

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

maple_driver_attach()

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.

maple_driver_detach()

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.

maple_driver_foreach()

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

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.

maple_driver_reg()

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).

maple_driver_unreg()

int maple_driver_unreg

(

maple_driver_t *

driver

)

Unregister a maple device driver.

Return values

0	On success (no error conditions defined).

maple_enum_count()

int maple_enum_count

(

void

)

Return the number of connected devices.

Returns

The number of devices connected.

maple_enum_dev()

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_enum_type()

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_enum_type_ex()

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.

maple_frame_init()

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.

maple_frame_lock()

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.

maple_frame_unlock()

void maple_frame_unlock

(

maple_frame_t *

frame

)

Unlock a frame.

maple_gun_disable()

void maple_gun_disable

(

void

)

Disable light gun mode.

There is probably very little reason to call this function. Light gun mode is ordinarily disabled and is automatically disabled after the data has been read from the device. The only reason to call this function is if you call the maple_gun_enable() function, and then change your mind during the same frame.

maple_gun_enable()

int maple_gun_enable

(

int

port

)

Enable light gun mode for this frame.

This function enables light gun processing for the current frame of data. Light gun mode will automatically be disabled when the data comes back for this frame.

Parameters

port	The port to enable light gun mode on.

Returns

MAPLE_EOK on success, MAPLE_EFAIL on error.

maple_gun_read_pos()

void maple_gun_read_pos	(	int *	x,
		int *	y )

Read the light gun position values.

This function fetches the gun position values from the video hardware and returns them via the parameters. These values are not normalized before returning.

Parameters

x	Storage for the horizontal position of the gun.
y	Storage for the vertical position of the gun.

Note

The values returned from this function are the raw H and V counter values from the video hardware where the gun registered its position. The values, however, need a bit of massaging before they correspond nicely to screen values. The y value is particularly odd in interlaced modes due to the fact that you really have half as many physical lines on the screen as you might expect.

maple_init()

void maple_init

(

void

)

Initialize Maple.

maple_pcaps()

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 containing the capabilities.

maple_perror()

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 representation of the response code.

maple_queue_flush()

void maple_queue_flush

(

void

)

Send all queued frames.

maple_queue_frame()

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.

maple_queue_remove()

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.

maple_raddr()

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.

maple_shutdown()

void maple_shutdown

(

void

)

Shutdown Maple.

maple_vbl_irq_hnd()

void maple_vbl_irq_hnd	(	uint32	code,
		void *	data )

Called on every VBL (~60fps).

Parameters

code	The ASIC event code.
data	The user pointer associated with this callback.

maple_wait_scan()

void maple_wait_scan

(

void

)

Wait for the initial bus scan to complete.