KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Data Structures | Macros | Typedefs | Functions | Variables
maple.h File Reference

Maple Bus driver interface. More...

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

Go to the source code of this file.

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_tmaple_enum_dev (int p, int u)
 Get a raw device info struct for the given device. More...
 
maple_device_tmaple_enum_type (int n, uint32 func)
 Get the Nth device of the requested type (where N is zero-indexed). More...
 
maple_device_tmaple_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 {
struct maple_device maple_device_t
One maple device.
void * maple_dev_status(maple_device_t *dev)
Get the status struct for the requested maple device.
maple_device_t * maple_enum_type(int n, uint32 func)
Get the Nth device of the requested type (where N is zero-indexed).

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
TYPEThe function code of devices to look at.
VARTYPEThe type to cast the return value of maple_dev_status() to.
VARThe 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,
 
)    ( *((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.

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.

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.

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
portThe port to build the address for.
unitThe 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
devThe 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
pThe port to check.
uThe 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
codeThe 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
detThe detection frame.
Return values
0On success.
-1If no driver is available.
int maple_driver_detach ( int  p,
int  u 
)

Detach an attached maple device.

Parameters
pThe port of the device to detach.
uThe unit of the device to detach.
Return values
0On success.
-1If 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
drvThe driver to loop through devices of.
callbackThe 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
0On success.
-1If 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
0On success (no error conditions defined).
int maple_driver_unreg ( maple_driver_t driver)

Unregister a maple device driver.

Return values
0On 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
pThe port to look up.
uThe 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
nThe index to look up.
funcThe 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
nThe index to look up.
funcThe function code to look for.
capCapabilities 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
frameThe 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
0On success.
-1If 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
functionsThe 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
responseThe 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
frameThe frame to queue up.
Return values
0On success.
-1If 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
frameThe frame to remove from the queue.
Return values
0On success.
-1If 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
addrThe input address.
portOutput space for the port of the address.
unitOutput 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
codeThe 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.