libdragon
Data Structures | Files | Defines | Typedefs | Functions | Variables
Hardware Coprocessor Interface
libdragon

Interface to the hardware coprocessor (RSP). More...

Data Structures

struct  ijob
 Internal Job structure. More...
struct  job_queue_t
 Internal Job Queue structure. More...

Files

file  rsp.c
 

Hardware Coprocessor Interface.


file  rsp.h
 

Hardware Coprocessor Interface.


Defines

#define JOB_STATE_IDLE   0
 Job states.
#define JOB_STATE_QUEUED   1
#define JOB_STATE_RUNNING   2
#define JOB_STATE_FINISHED   3

Typedefs

typedef struct ijob job_t
 Internal Job structure.

Functions

static void ADD_TAIL (job_queue_t *q, job_t *j)
 Add job to end of queue.
static job_tREMOVE_HEAD (job_queue_t *q)
 Remove job from head of queue and return it.
static void REMOVE_NODE (job_queue_t *q, job_t *j)
 Remove job from queue.
static uint32_t __rsp_lock (uint32_t wait)
 Lock access to RSP DMA.
static void __rsp_unlock ()
 Unlock access to RSP DMA.
static void __rsp_wait_dma (uint32_t busy)
 Wait for RSP DMA.
static void __rsp_dma_read (uint32_t offs, void *src, uint32_t len)
 Set RSP DMA for read to D/IMEM from DRAM.
static void __rsp_dma_write (uint32_t offs, void *dst, uint32_t len)
 Set RSP DMA for write to DRAM from D/IMEM.
static uint32_t __rsp_get_status ()
 Return the status bits in the RSP.
static void __rsp_set_status (uint32_t flags)
 Set or clear the status bits in the RSP.
static void __rsp_set_pc (uint32_t pc)
 Set RSP PC.
static void __rsp_interrupt ()
 RSP interrupt handler.
void rsp_init (void)
 Initialize the RSP system.
void rsp_close (void)
 Close the RSP system.
void rsp_load_lib (uint8_t *lib)
 Load RSP library to D/IMEM.
uint32_t rsp_lib_fn (char *mod, uint32_t fn)
 Return the vector of the function entry point in a module.
void rsp_queue_job (job_t *job)
 Queue a job for the RSP.
void rsp_do_job (job_t *job)
 Queue a job for the RSP and wait until it's done.
void rsp_wait_job (job_t *job)
 Wait on a queued job for the RSP.
void rsp_abort_job (job_t *job)
 Abort a queued job for the RSP.
job_trsp_new_job (uint32_t fn, void(*cb)(job_t *), uint32_t count,...)
 Return a new job structure with fields filled in.
void rsp_dispose_job (job_t *job)
 Dispose of an existing job structure.

Variables

job_queue_t jobQueue

Detailed Description

Interface to the hardware coprocessor (RSP).

The hardware coprocessor interface sets up and talks with the RSP in order to perform parallel processing of data. The code executed by the RSP is loaded as a library of modules that fit within the 4KB of IMEM. Module functions are queued for execution as the RSP finishes previously queued functions (FIFO queue).

Before attempting to queue any functions on the RSP, the hardware coprocessor interface should be initialized with rsp_init. After the RSP is no longer needed, be sure to free all resources using rsp_close.

After the interface is initialized, the library should be loaded with rsp_load_lib. The entry vectors for functions of a particular module can then be fetched using rsp_lib_fn. The functions can then be used to create a job to perform on the RSP using rsp_new_job. The job can be queued for execution with rsp_queue_job, or rsp_do_job, which also waits until the queued job is finished before returning.


Function Documentation

static void __rsp_dma_read ( uint32_t  offs,
void *  src,
uint32_t  len 
) [inline, static]

Set RSP DMA for read to D/IMEM from DRAM.

Parameters:
[in]offsOffset into D/IMEM (0x0000 to 0x1FFF - must be 8-byte aligned!)
[in]srcAddress in DRAM of data (must be 8-byte aligned!)
[in]lenLength in bytes (max of 4KB)
static void __rsp_dma_write ( uint32_t  offs,
void *  dst,
uint32_t  len 
) [inline, static]

Set RSP DMA for write to DRAM from D/IMEM.

Parameters:
[in]offsOffset into D/IMEM (0x0000 to 0x1FFF - must be 8-byte aligned!)
[in]dstAddress in DRAM for data (must be 8-byte aligned!)
[in]lenLength in bytes (max of 4KB)
static uint32_t __rsp_get_status ( ) [inline, static]

Return the status bits in the RSP.

Returns:
RSP status bits.
static void __rsp_interrupt ( ) [static]

RSP interrupt handler.

This interrupt is called when a the RSP executes a break instruction. This signifies the job being executed is finished or errored out.

static uint32_t __rsp_lock ( uint32_t  wait) [inline, static]

Lock access to RSP DMA.

Parameters:
[in]waitWait until lock successful if set
Returns:
RSP already locked.
static void __rsp_set_pc ( uint32_t  pc) [inline, static]

Set RSP PC.

Parameters:
[in]pcFunction entry point in IMEM
static void __rsp_set_status ( uint32_t  flags) [inline, static]

Set or clear the status bits in the RSP.

Parameters:
[in]flagsA set of SET and CLR status bits
static void __rsp_wait_dma ( uint32_t  busy) [inline, static]

Wait for RSP DMA.

Parameters:
[in]busyWait on DMA not busy (1), or not full (0)
static job_t* REMOVE_HEAD ( job_queue_t q) [inline, static]

Remove job from head of queue and return it.

Returns:
Job from the head of queue.
void rsp_abort_job ( job_t job)

Abort a queued job for the RSP.

Parameters:
[in]jobJob to remove from queue

The job may be running. If so, the RSP is forced to stop, the callback is ignored, and the next job is started.

void rsp_dispose_job ( job_t job)

Dispose of an existing job structure.

Parameters:
[in]jobJob created by rsp_new_job

Job must not be currently queued or running.

void rsp_do_job ( job_t job)

Queue a job for the RSP and wait until it's done.

Parameters:
[in]jobJob for execution on the RSP
uint32_t rsp_lib_fn ( char *  mod,
uint32_t  fn 
)

Return the vector of the function entry point in a module.

Parameters:
[in]modModule name string
[in]fnIndex of function in module
Returns:
Vector for function in module inside IMEM.
void rsp_load_lib ( uint8_t *  lib)

Load RSP library to D/IMEM.

There's no need to lock the RSP DMA here since we've halted the RSP. The library must be 8KB long and in DRAM on an 8 byte alignment.

Parameters:
[in]libPointer to library
job_t* rsp_new_job ( uint32_t  fn,
void(*)(job_t *)  cb,
uint32_t  count,
  ... 
)

Return a new job structure with fields filled in.

Parameters:
[in]fnIndex of function in module
[in]cbcallback for the job
[in]countnumber of args passed (max of 16)
[in]...arguments for the job (max of 16)
Returns:
New job with fields filled in, or NULL.
void rsp_queue_job ( job_t job)

Queue a job for the RSP.

Parameters:
[in]jobJob for execution on the RSP
void rsp_wait_job ( job_t job)

Wait on a queued job for the RSP.

Parameters:
[in]jobJob to wait on
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines