orcus
|
Main header file for Orcus functions. More...
#include <stdint.h>
#include <stdbool.h>
Macros | |
#define | NAND_BLOCK_SIZE 512 |
Number of bytes in a NAND block. | |
#define | TIMER_NS_PER_TICK 135 |
Nanoseconds per timer tick. More... | |
#define | A (1<<0) |
Button. | |
#define | B (1<<1) |
Button. | |
#define | DOWN (1<<7) |
Button. | |
#define | DOWN_LEFT (1<<12) |
Button. | |
#define | DOWN_RIGHT (1<<13) |
Button. | |
#define | L (1<<17) |
Button. | |
#define | LEFT (1<<8) |
Button. | |
#define | R (1<<18) |
Button. | |
#define | RIGHT (1<<9) |
Button. | |
#define | SELECT (1<<5) |
Button. | |
#define | START (1<<4) |
Button. | |
#define | STICK (1<<16) |
Button. | |
#define | UP (1<<6) |
Button. | |
#define | UP_LEFT (1<<10) |
Button. | |
#define | UP_RIGHT (1<<11) |
Button. | |
#define | VOL_DOWN (1<<15) |
Button. | |
#define | VOL_UP (1<<14) |
Button. | |
#define | X (1<<2) |
Button. | |
#define | Y (1<<3) |
Button. | |
Enumerations | |
enum | BlendingMode { NO_BLENDING = 0, COLOUR_KEY = 1, ALPHA = 2 } |
Blending modes for combining regions on-screen. More... | |
enum | BurstMode { , WORDS_4 = 0x1 } |
DMA burst mode (RAM->RAM only). More... | |
enum | Parity { NONE, ODD, EVEN } |
UART parity settings. More... | |
enum | Peripheral |
MMSP2 peripherals available for DMA transfers. | |
enum | RgbFormat { P4BPP = 0, P8BPP = 1, RGB565 = 2, RGB888 = 3 } |
Bit formats in RGB region. More... | |
enum | RgbRegion { REGION1 = 1, REGION2 = 2, REGION3 = 3, REGION4 = 4, REGION5 = 5 } |
Regions available in RGB hardware. More... | |
Functions | |
uint16_t | ac97GetReg (uint8_t reg) |
Read register value from AC97 codec. More... | |
void | ac97SetReg (uint8_t reg, uint16_t value) |
Set register value in AC97 codec. More... | |
void | ac97Start () |
Start AC97 codec. More... | |
void | ac97Stop () |
Stop AC97 codec. More... | |
void | arm940ClockOff () |
Pause execution on the ARM940T. More... | |
void | arm940ClockOn () |
Resume execution on the ARM940T. More... | |
void | arm940Halt () |
Halt the ARM940T. More... | |
bool | arm940HasClock () |
Check if the ARM940T has a clock signal. More... | |
int | arm940Init (int memoryBank) |
Initialise ARM940T. More... | |
bool | arm940IsThis () |
Check if executing on the ARM940T. More... | |
void | arm940Run () |
Start execution on the ARM940T. More... | |
bool | arm940Running () |
Check if the ARM940T is running. More... | |
bool | audioHeadphonesConnected () |
Check if headphones are connected (F100 only). More... | |
void | audioInit (int dmaChannel) |
Initialise audio subsystem. More... | |
void | audioMuteHeadphones () |
Mute headphones. More... | |
void | audioMuteSpeakers () |
Mute speakers. More... | |
void | audioPlaySample (uint16_t bytes, void *data) |
Play a PCM sample. More... | |
bool | audioSamplePlaying () |
Check if a sample is currently playing. More... | |
void | audioSetSampleRate (uint16_t khz) |
Set sample rate for AC97 codec. More... | |
void | audioSetVolume (uint8_t left, uint8_t right) |
Set volume. More... | |
void | audioUnmuteHeadphones () |
Unmute headphones. More... | |
void | audioUnmuteSpeakers () |
Unmute speakers. More... | |
uint32_t | btnState () |
Get current button state. More... | |
uint32_t | btnStateDebounced () |
Get current button state (debounced). More... | |
void | dmaConfigureChannelIO (int channel, BurstMode burstMode, int8_t srcIncrement, int8_t destIncrement, Peripheral peripheral) |
Configure a DMA channel for memory-to-peripheral transfer. More... | |
void | dmaConfigureChannelMem (int channel, BurstMode burstMode, int8_t srcIncrement, int8_t destIncrement) |
Configure a DMA channel for memory-to-memory transfer. More... | |
bool | dmaHasFinished (int channel) |
Check if a DMA channel has finished transferring data. More... | |
bool | dmaIsTransferring (int channel) |
Check if a DMA channel is transferring data. More... | |
void | dmaStart (int channel, uint16_t length, uint32_t src, uint32_t dest) |
Initiate a DMA transfer. More... | |
void | dmaStop (int channel) |
Stop a DMA transfer. More... | |
void | enableICache () |
Enable icache on ARM920T. More... | |
uint32_t | exportPointer (void *ptr) |
Export a pointer to the other CPU. More... | |
void | gp2xInit () |
Initialise GP2X. More... | |
bool | gp2xIsF200 () |
Check if running on an F200. More... | |
void | gp2xSetDefaultRamTimings () |
Set default recommended RAM timings. More... | |
void | gp2xSetFastRamTimings () |
Set faster RAM timings. More... | |
void | gp2xSetRamTimings (int tRC, int tRAS, int tWR, int tMRD, int tRFC, int tRP, int tRCD) |
Set custom RAM timings. More... | |
void * | importPointer (uint32_t addr) |
Import a pointer from the other CPU. More... | |
bool | lcdHSync () |
Check if LCD is currently in hsync period. More... | |
bool | lcdVSync () |
Check if LCD is currently in vsync period. More... | |
void | lcdWaitNextHSync () |
Wait until LCD is in next hsync period. More... | |
void | lcdWaitNextVSync () |
Wait until LCD is in next vsync period. More... | |
void | nandErase (uint32_t startAdddr, int numberOfBlocks) |
Erase blocks on NAND. More... | |
void | nandRead (uint32_t startAddr, int numberOfBlocks, void *dest) |
Read blocks from NAND. More... | |
void | nandWrite (uint32_t startAddr, int numberOfBlocks, void *src) |
Write blocks to NAND. More... | |
void | rgbColourKey (uint8_t r, uint8_t g, uint8_t b) |
Set global colour key for blending. More... | |
void | rgbPrintf (uint16_t *fb, int x, int y, uint16_t colour, const char *format,...) |
printf directly to RGB565 framebuffer. More... | |
void | rgbPrintfBg (uint16_t *fb, int x, int y, uint16_t colour, uint16_t bgColour, const char *format,...) |
printf directly to RGB565 framebuffer with a background colour. More... | |
void | rgbPutc (uint16_t *fb, int x, int y, uint16_t colour, char c) |
Render a font character on the screen. More... | |
void | rgbPutcBg (uint16_t *fb, int x, int y, uint16_t colour, uint16_t bgColour, char c) |
Render a font character on the screen with a background colour. More... | |
void | rgbRegionBlendAlpha (RgbRegion region, uint4_t alpha) |
Enable alpha blending for this region. More... | |
void | rgbRegionBlendColourKey (RgbRegion region) |
Enable colour key blending for region. More... | |
void | rgbRegionNoBlend (RgbRegion region) |
Disable blending for a region. More... | |
void | rgbSetFbAddress (void *fb) |
Set RGB framebuffer address. More... | |
void | rgbSetFont (uint16_t *font, int charWidth, int charHeight) |
Set font data to use. More... | |
void | rgbSetPixelFormat (RgbFormat format) |
Configure RGB pixel format for all regions. More... | |
void | rgbSetRegionPosition (RgbRegion region, int x, int y, int width, int height) |
Set region coordinates and size. More... | |
void | rgbSetScale (int srcW, int srcH) |
Set source with for scaling region. More... | |
void | rgbToggleRegion (RgbRegion region, bool onOff) |
Enable or disable an RGB region. More... | |
int | sdInit () |
Initialise SD card. More... | |
bool | sdIsInserted () |
Check if SD card is inserted. More... | |
int | sdReadBlocks (int startBlock, int numberOfBlocks, uint8_t *dest) |
Read blocks from SD card. More... | |
uint32_t | timerGet () |
Get current timer tick. More... | |
unsigned int | timerNsSince (uint32_t lastTick, uint32_t *storeCurrent) |
Calculate nanoseconds elapsed since a given tick. More... | |
uint32_t | timerSet (uint32_t count) |
Reset timer to count from specific tick. More... | |
void | timerSleepNs (unsigned int ns) |
Wait for a given number of nanoseconds. More... | |
void | uartConfigure (int baudRate, int bitsPerFrame, Parity parity, int stopBits) |
Configure UART parameters. More... | |
int | uartGetc (bool isBlocking) |
Get a character from UART. More... | |
void | uartPrintf (const char *format,...) |
printf over UART. More... | |
char | uartPutc (char c, bool isBlocking) |
Output character over UART. More... | |
void | uartSetEcho (bool isEnabled) |
Set UART echoing. More... | |
Variables | |
volatile uint16_t * | arm920Data |
Pointer to start of 16x 16-bit shared data registers. More... | |
volatile uint16_t * | arm940Data |
Pointer to start of 16x 16-bit shared data registers. More... | |
#define TIMER_NS_PER_TICK 135 |
Nanoseconds per timer tick. Timer ticks once every 0.135uS.
enum BlendingMode |
enum BurstMode |
enum Parity |
enum RgbFormat |
enum RgbRegion |
uint16_t ac97GetReg | ( | uint8_t | reg | ) |
Read register value from AC97 codec
reg | Register to read |
void ac97SetReg | ( | uint8_t | reg, |
uint16_t | value | ||
) |
Set register value in AC97 codec.
reg | Register to set |
value | Value to set |
void ac97Start | ( | ) |
Start AC97 codec, will restart codec if it was previously started.
void ac97Stop | ( | ) |
Stop AC97 codec.
void arm940ClockOff | ( | ) |
Pause execution on the ARM940T by disabling its clock.
void arm940ClockOn | ( | ) |
Enable the clock on the ARM940T to resume execution at the same point it was at when the clock was disabled.
void arm940Halt | ( | ) |
Halt the ARM940T and hold it in RESET state.
bool arm940HasClock | ( | ) |
Check if the ARM940T has a clock signal, to see if execution is paused.
int arm940Init | ( | int | memoryBank | ) |
Initialise the ARM940T second CPU and configure the base address (in 16M increments) in physical memory which will appear as 0x0 from the perspective of the ARM940T.
This leaves the ARM940T in RESET state, and enables the clock.
Valid base addresses are 16M, 32M and 48M (banks 1, 2 and 3 respectively) to prevent overlapping with the ARM920T vector table (always stored at 0x0 in physical memory). It is possible to set both CPUs to start at 0x0 physical but in this case they will share a RESET vector and will execute the same code so it is highly discouraged unless you have an unusual use case in mind, and is not supported with this function.
Further documentation can be found on the Orcus wiki regarding using the ARM940T.
memoryBank | Memory bank to use as start of ARM940T address range (1 - 3) |
bool arm940IsThis | ( | ) |
Check if this call is being executed on the ARM940T.
void arm940Run | ( | ) |
Start execution on the ARM940T from its RESET vector entry (0x0) by releasing it from RESET state.
bool arm940Running | ( | ) |
Check if the ARM940T is running.
bool audioHeadphonesConnected | ( | ) |
Check if headphones are connected. This works on the F100 only, the F200 physically switches the DAC output between the speakers and headphones when you insert the jack.
void audioInit | ( | int | dmaChannel | ) |
Initialise auto subsystem.
dmaChannel | DMA channel to use for audio (0 - 15, recommend 0 - 3) |
void audioMuteHeadphones | ( | ) |
Mute headphones.
void audioMuteSpeakers | ( | ) |
Mute speakers.
void audioPlaySample | ( | uint16_t | bytes, |
void * | data | ||
) |
Play a PCM sample. Non-blocking, see if the sample has finished playing with audioSamplePlaying().
bytes | Number of bytes in sample (max 0xFFFF) |
data | Pointer to sample data |
bool audioSamplePlaying | ( | ) |
Check if a sample is currently playing.
void audioSetSampleRate | ( | uint16_t | khz | ) |
Set sample rate for AC97 codec.
khz | Sample rate to set |
void audioSetVolume | ( | uint8_t | left, |
uint8_t | right | ||
) |
Set volume.
@warn You may not wish to allow the volume to reach 31, with headphones connected this could do damage to somebody's hearing!
left | Volume level for left channel (0 [lowest] - 31 [highest]) |
right | Volume level for right channel (0 [lowest] - 31 [highest]) |
void audioUnmuteHeadphones | ( | ) |
Unmute headphones.
void audioUnmuteSpeakers | ( | ) |
Unmute speakers.
uint32_t btnState | ( | ) |
uint32_t btnStateDebounced | ( | ) |
Get current button state. This function debounces presses to give a reliable indicator.
One can check for a particular button state using &.
For example:
void dmaConfigureChannelIO | ( | int | channel, |
BurstMode | burstMode, | ||
int8_t | srcIncrement, | ||
int8_t | destIncrement, | ||
Peripheral | peripheral | ||
) |
Configure a DMA channel for memory-to-peripheral transfer.
channel | DMA channel to configure (0 - 15) |
burstMode | Number of words to copy at a time |
srcIncrement | Number of words to increment source address after each transfer (negative values and zero are permitted) |
destIncrement | Number of words to increment destination address after each transfer (negative values and zero are permitted) |
peripheral | MMSP2 peripheral to write to |
void dmaConfigureChannelMem | ( | int | channel, |
BurstMode | burstMode, | ||
int8_t | srcIncrement, | ||
int8_t | destIncrement | ||
) |
Configure a DMA channel for memory-to-memory transfer.
channel | DMA channel to configure (0 - 15) |
burstMode | Number of words to copy at a time |
srcIncrement | Number of words to increment source address after each transfer (negative values and zero are permitted) |
destIncrement | Number of words to increment destination address after each transfer (negative values and zero are permitted) |
bool dmaHasFinished | ( | int | channel | ) |
Check if a DMA channel has finished transferring data.
channel | DMA channel to check (0 - 15) |
bool dmaIsTransferring | ( | int | channel | ) |
Check if a DMA channel is transferring data.
channel | DMA channel to check (0 - 15) |
void dmaStart | ( | int | channel, |
uint16_t | length, | ||
uint32_t | src, | ||
uint32_t | dest | ||
) |
Initiate a DMA transfer on a previously configured channel.
channel | DMA channel to initiate transfer on (0 - 15) |
length | Number of bytes to transfer (maximum 64K) |
src | Source address (aligned to 4 byte word boundary) |
dst | Destination address (aligned to 4 byte word boundary) |
void dmaStop | ( | int | channel | ) |
Stop a DMA transfer.
channel | DMA channel to stop (0 - 15) |
void enableICache | ( | ) |
Enable icache on ARM920T. This is enabled by default in gp2xInit.
uint32_t exportPointer | ( | void * | ptr | ) |
Export a pointer to the address space of the other CPU.
ptr | Pointer to export |
void gp2xInit | ( | ) |
Initialise the GP2X hardware and set up system calls. This must be called before using any other functions from Orcus.
bool gp2xIsF200 | ( | ) |
Check if running on an F200. This tests to see if the NET2272 chip (only fitted to F100s) is present.
void gp2xSetDefaultRamTimings | ( | ) |
Equivalent to gp2xSetRamTimings(7, 15, 2, 7, 7, 7, 7)
void gp2xSetFastRamTimings | ( | ) |
Equivalent to gp2xSetRamTimings(5, 3, 0, 0, 0, 1, 1)
void gp2xSetRamTimings | ( | int | tRC, |
int | tRAS, | ||
int | tWR, | ||
int | tMRD, | ||
int | tRFC, | ||
int | tRP, | ||
int | tRCD | ||
) |
Sets RAM timing registers in MMSP2.
void* importPointer | ( | uint32_t | addr | ) |
Import a pointer from the other CPU into the address space of the CPU we are running on.
addr | Address to import from other CPU |
bool lcdHSync | ( | ) |
Check if LCD is currently in hsync period.
bool lcdVSync | ( | ) |
Check if LCD is currently in vsync period.
void lcdWaitNextHSync | ( | ) |
Wait until LCD is in next hsync period. If LCD is currently in hsync when this is called, it will wait until it has ended, and then again until the next one begins.
void lcdWaitNextVSync | ( | ) |
Wait until LCD is in next vsync period. If LCD is currently in vsync when this is called, it will wait until it has ended, and then again until the next one begins.
void nandErase | ( | uint32_t | startAdddr, |
int | numberOfBlocks | ||
) |
Erase (set to 0xFF) 512B blocks on NAND. You must do this before writing due to the nature of NAND storage where a write operating can only unset bits.
startAddr | Address to start erasing from (absolute, not in terms of blocks) |
numberOfBlocks | Number of 512B blocks to erase |
void nandRead | ( | uint32_t | startAddr, |
int | numberOfBlocks, | ||
void * | dest | ||
) |
Read 512B blocks from NAND.
startAddr | Address to start reading from (absolute, not in terms of blocks) |
numberOfBlocks | Number of 512B blocks to read |
dest | Pointer to memory location to store data |
void nandWrite | ( | uint32_t | startAddr, |
int | numberOfBlocks, | ||
void * | src | ||
) |
Write 512B blocks to NAND. You must first erase the blocks.
startAddr | Address to start start writing to (absolute, not in terms of blocks) |
numberOfBlocks | Number of 512B blocks to write |
src | Pointer to memory location holding data to write |
void rgbColourKey | ( | uint8_t | r, |
uint8_t | g, | ||
uint8_t | b | ||
) |
Set global colour key for blending RGB regions (all regions share the same key).
r | Red value to match |
g | Green value to match |
b | Blue value to match |
void rgbPrintf | ( | uint16_t * | fb, |
int | x, | ||
int | y, | ||
uint16_t | colour, | ||
const char * | format, | ||
... | |||
) |
printf directly to RGB565 framebuffer. Must have configured font first using rgbSetFont.
fb | Pointer to RGB565 framebuffer in which to render character |
x | X-coordinate at which to draw font |
y | Y-coordinate at which to draw font |
colour | RGB565 colour to draw character |
void rgbPrintfBg | ( | uint16_t * | fb, |
int | x, | ||
int | y, | ||
uint16_t | colour, | ||
uint16_t | bgColour, | ||
const char * | format, | ||
... | |||
) |
printf directly to RGB565 framebuffer with a background colour. Must have configured font first using rgbSetFont.
fb | Pointer to RGB565 framebuffer in which to render character |
x | X-coordinate at which to draw font |
y | Y-coordinate at which to draw font |
colour | RGB565 colour to draw character |
bgColour | RGB565 colour to use for background |
void rgbPutc | ( | uint16_t * | fb, |
int | x, | ||
int | y, | ||
uint16_t | colour, | ||
char | c | ||
) |
Render a font character on the screen. Must have configured font first using rgbSetFont.
fb | Pointer to RGB565 framebuffer in which to render character |
x | X-coordinate at which to draw font |
y | Y-coordinate at which to draw font |
colour | RGB565 colour to draw character |
c | Character to draw |
void rgbPutcBg | ( | uint16_t * | fb, |
int | x, | ||
int | y, | ||
uint16_t | colour, | ||
uint16_t | bgColour, | ||
char | c | ||
) |
Render a font character on the screen with a background colour. Must have configured font first using rgbSetFont.
fb | Pointer to RGB565 framebuffer in which to render character |
x | X-coordinate at which to draw font |
y | Y-coordinate at which to draw font |
colour | RGB565 colour to draw character |
bgColour | RGB565 colour to use for background |
c | Character to draw |
void rgbRegionBlendAlpha | ( | RgbRegion | region, |
uint4_t | alpha | ||
) |
Enable alpha blending for this region, and set alpha value.
region | Region to alter |
alpha | Alpha value (0 - 16) |
void rgbRegionBlendColourKey | ( | RgbRegion | region | ) |
Enable colour key blending for region.
region | Region to alter |
void rgbRegionNoBlend | ( | RgbRegion | region | ) |
Disable blending for a region.
region | Region to alter |
void rgbSetFbAddress | ( | void * | fb | ) |
Set RGB framebuffer address. The regions all share the same base pointer and are accessed sequentially from that location.
fb | Pointer to memory region which should be used as source of RGB data |
void rgbSetFont | ( | uint16_t * | font, |
int | charWidth, | ||
int | charHeight | ||
) |
Set font data to use for text drawing utility functions.
font | Pointer to font graphic data |
charWidth | Width of font character in pixels |
charHeight | Height of font character in pixels |
void rgbSetPixelFormat | ( | RgbFormat | format | ) |
Configure RGB pixel format for all regions.
format | Format to use when interpreting RGB data |
void rgbSetRegionPosition | ( | RgbRegion | region, |
int | x, | ||
int | y, | ||
int | width, | ||
int | height | ||
) |
Set region coordinates and size.
region | Region to alter |
x | X-coordinate of start of region |
y | Y-coordinate of start of region |
width | Width in pixels of region |
height | Height in pixels of region |
void rgbSetScale | ( | int | srcW, |
int | srcH | ||
) |
Sets source width for scaling region.
srcW | Source width in pixels, scaling in X dimension disabled if set to 0 |
srcH | Source height in pixels, scaling in Y dimension disabled if set to 0 |
void rgbToggleRegion | ( | RgbRegion | region, |
bool | onOff | ||
) |
Enable or disable an RGB region.
region | Region to alter |
onOff | true to enable a region, false to disable it |
int sdInit | ( | ) |
Initialise SD card.
bool sdIsInserted | ( | ) |
Check if an SD card is physically inserted into the slot (reads the state of the mechanical switch).
int sdReadBlocks | ( | int | startBlock, |
int | numberOfBlocks, | ||
uint8_t * | dest | ||
) |
Read blocks (512B) from SD card.
startBlock | Block to start reading from (i.e. address / 512) |
numberOfBlocks | Number of 512B blocks to read |
dest | Pointer to memory location to store data |
uint32_t timerGet | ( | ) |
Get current timer tick.
Timer ticks every 0.135uS and overflows at 0xFFFFFFFF then carries on counting.
unsigned int timerNsSince | ( | uint32_t | lastTick, |
uint32_t * | storeCurrent | ||
) |
Calculate nanoseconds elapsed since a given tick. Optionally store the current tick.
Useful for timeouts, or calculating time between frames.
uint32_t timerSet | ( | uint32_t | count | ) |
Reset timer to count from specific tick.
count | Tick to start counting from |
void timerSleepNs | ( | unsigned int | ns | ) |
Wait for a given number of nanoseconds.
ns | Nanoseconds to wait |
void uartConfigure | ( | int | baudRate, |
int | bitsPerFrame, | ||
Parity | parity, | ||
int | stopBits | ||
) |
int uartGetc | ( | bool | isBlocking | ) |
Gets a single character from UART.
isBlocking | If true, will wait for a character to become available, otherwise will return immediately if no character is in the input buffer. |
void uartPrintf | ( | const char * | format, |
... | |||
) |
As per the standard printf, with output directly to UART.
char uartPutc | ( | char | c, |
bool | isBlocking | ||
) |
Outputs a single character over UART.
c | Character to output |
isBlocking | If true will wait until the output buffer has space for this character, will fail fast if false |
void uartSetEcho | ( | bool | isEnabled | ) |
If enabled, uartGetc will echo any character received back out to the UART. This is handy when implementing a command line interface over UART.
isEnabled | If true, UART echoing will be enabled. |
arm920Data |
Pointer to start of 16x 16-bit shared data registers. These can be written to from either CPU, but can only trigger an interrupt on the ARM920T.
arm940Data |
Pointer to start of 16x 16-bit shared data registers. These can be written to from either CPU, but can only trigger an interrupt on the ARM940T.