gspgpu.h File Reference

GSPGPU service. More...

Go to the source code of this file.

Data Structures
struct	GSPGPU_FramebufferInfo
	Framebuffer information. More...
struct	GSPGPU_CaptureInfoEntry
	Capture info entry. More...
struct	GSPGPU_CaptureInfo
	Capture info. More...
struct	GSPGPU_PerfLogEntry
	GSPGPU performance log entry. More...
struct	GSPGPU_PerfLog
	GSPGPU performance log. More...

Macros
#define	GSP_SCREEN_TOP   0
	ID of the top screen.
#define	GSP_SCREEN_BOTTOM   1
	ID of the bottom screen.
#define	GSP_SCREEN_WIDTH   240
	Width of the top/bottom screens.
#define	GSP_SCREEN_HEIGHT_TOP   400
	Height of the top screen.
#define	GSP_SCREEN_HEIGHT_TOP_2X   800
	Height of the top screen (2x).
#define	GSP_SCREEN_HEIGHT_BOTTOM   320
	Height of the bottom screen.
#define	gspWaitForPSC0()   gspWaitForEvent(GSPGPU_EVENT_PSC0, false)
	Waits for PSC0.
#define	gspWaitForPSC1()   gspWaitForEvent(GSPGPU_EVENT_PSC1, false)
	Waits for PSC1.
#define	gspWaitForVBlank()   gspWaitForVBlank0()
	Waits for VBlank.
#define	gspWaitForVBlank0()   gspWaitForEvent(GSPGPU_EVENT_VBlank0, true)
	Waits for VBlank0.
#define	gspWaitForVBlank1()   gspWaitForEvent(GSPGPU_EVENT_VBlank1, true)
	Waits for VBlank1.
#define	gspWaitForPPF()   gspWaitForEvent(GSPGPU_EVENT_PPF, false)
	Waits for PPF.
#define	gspWaitForP3D()   gspWaitForEvent(GSPGPU_EVENT_P3D, false)
	Waits for P3D.
#define	gspWaitForDMA()   gspWaitForEvent(GSPGPU_EVENT_DMA, false)
	Waits for DMA.

Enumerations
enum	GSPGPU_FramebufferFormat {   GSP_RGBA8_OES =0 ,   GSP_BGR8_OES =1 ,   GSP_RGB565_OES =2 ,   GSP_RGB5_A1_OES =3 ,   GSP_RGBA4_OES =4 }
	Framebuffer format. More...
enum	GSPGPU_Event {   GSPGPU_EVENT_PSC0 = 0 ,   GSPGPU_EVENT_PSC1 ,   GSPGPU_EVENT_VBlank0 ,   GSPGPU_EVENT_VBlank1 ,   GSPGPU_EVENT_PPF ,   GSPGPU_EVENT_P3D ,   GSPGPU_EVENT_DMA ,   GSPGPU_EVENT_MAX }
	GSPGPU events. More...

Functions
static unsigned	gspGetBytesPerPixel (GSPGPU_FramebufferFormat format)
	Gets the number of bytes per pixel for the specified format.
Result	gspInit (void)
	Initializes GSPGPU.
void	gspExit (void)
	Exits GSPGPU.
Handle *	gspGetSessionHandle (void)
	Gets a pointer to the current gsp::Gpu session handle.
bool	gspHasGpuRight (void)
	Returns true if the application currently has GPU rights.
bool	gspPresentBuffer (unsigned screen, unsigned swap, const void *fb_a, const void *fb_b, u32 stride, u32 mode)
	Presents a buffer to the specified screen.
bool	gspIsPresentPending (unsigned screen)
	Returns true if a prior gspPresentBuffer command is still pending to be processed by GSP.
void	gspSetEventCallback (GSPGPU_Event id, ThreadFunc cb, void *data, bool oneShot)
	Configures a callback to run when a GSPGPU event occurs.
void	gspWaitForEvent (GSPGPU_Event id, bool nextEvent)
	Waits for a GSPGPU event to occur.
GSPGPU_Event	gspWaitForAnyEvent (void)
	Waits for any GSPGPU event to occur.
Result	gspSubmitGxCommand (const u32 gxCommand[0x8])
	Submits a GX command.
Result	GSPGPU_AcquireRight (u8 flags)
	Acquires GPU rights.
Result	GSPGPU_ReleaseRight (void)
	Releases GPU rights.
Result	GSPGPU_ImportDisplayCaptureInfo (GSPGPU_CaptureInfo *captureinfo)
	Retrieves display capture info.
Result	GSPGPU_SaveVramSysArea (void)
	Saves the VRAM sys area.
Result	GSPGPU_ResetGpuCore (void)
	Resets the GPU.
Result	GSPGPU_RestoreVramSysArea (void)
	Restores the VRAM sys area.
Result	GSPGPU_SetLcdForceBlack (u8 flags)
	Sets whether to force the LCD to black.
Result	GSPGPU_SetBufferSwap (u32 screenid, const GSPGPU_FramebufferInfo *framebufinfo)
	Updates a screen's framebuffer state.
Result	GSPGPU_FlushDataCache (const void *adr, u32 size)
	Flushes memory from the data cache.
Result	GSPGPU_InvalidateDataCache (const void *adr, u32 size)
	Invalidates memory in the data cache.
Result	GSPGPU_WriteHWRegs (u32 regAddr, const u32 *data, u8 size)
	Writes to GPU hardware registers.
Result	GSPGPU_WriteHWRegsWithMask (u32 regAddr, const u32 *data, u8 datasize, const u32 *maskdata, u8 masksize)
	Writes to GPU hardware registers with a mask.
Result	GSPGPU_ReadHWRegs (u32 regAddr, u32 *data, u8 size)
	Reads from GPU hardware registers.
Result	GSPGPU_RegisterInterruptRelayQueue (Handle eventHandle, u32 flags, Handle *outMemHandle, u8 *threadID)
	Registers the interrupt relay queue.
Result	GSPGPU_UnregisterInterruptRelayQueue (void)
	Unregisters the interrupt relay queue.
Result	GSPGPU_TriggerCmdReqQueue (void)
	Triggers a handling of commands written to shared memory.
Result	GSPGPU_SetLedForceOff (bool disable)
	Sets 3D_LEDSTATE to the input state value.
Result	GSPGPU_SetPerfLogMode (bool enabled)
	Enables or disables the performance log and clear its state to zero.
Result	GSPGPU_GetPerfLog (GSPGPU_PerfLog *outPerfLog)
	Retrieves the performance log.

Detailed Description

GSPGPU service.

Enumeration Type Documentation

GSPGPU_Event

enum GSPGPU_Event

GSPGPU events.

Enumerator
GSPGPU_EVENT_PSC0	Memory fill completed.
GSPGPU_EVENT_PSC1	TODO.
GSPGPU_EVENT_VBlank0	TODO.
GSPGPU_EVENT_VBlank1	TODO.
GSPGPU_EVENT_PPF	Display transfer finished.
GSPGPU_EVENT_P3D	Command list processing finished.
GSPGPU_EVENT_DMA	TODO.
GSPGPU_EVENT_MAX	Used to know how many events there are.

GSPGPU_FramebufferFormat

enum GSPGPU_FramebufferFormat

Framebuffer format.

Enumerator
GSP_RGBA8_OES	RGBA8. (4 bytes)
GSP_BGR8_OES	BGR8. (3 bytes)
GSP_RGB565_OES	RGB565. (2 bytes)
GSP_RGB5_A1_OES	RGB5A1. (2 bytes)
GSP_RGBA4_OES	RGBA4. (2 bytes)

Function Documentation

gspGetBytesPerPixel()

static unsigned gspGetBytesPerPixel ( GSPGPU_FramebufferFormat  format )

inlinestatic

Gets the number of bytes per pixel for the specified format.

Parameters

format

See GSPGPU_FramebufferFormat.

Returns

Bytes per pixel.

gspGetSessionHandle()

Handle * gspGetSessionHandle

(

void

)

Gets a pointer to the current gsp::Gpu session handle.

Returns

A pointer to the current gsp::Gpu session handle.

GSPGPU_AcquireRight()

Result GSPGPU_AcquireRight

(

u8

flags

)

Acquires GPU rights.

Parameters

flags

Flags to acquire with.

GSPGPU_FlushDataCache()

Result GSPGPU_FlushDataCache	(	const void *	adr,
		u32	size
	)

Flushes memory from the data cache.

Parameters

adr	Address to flush.
size	Size of the memory to flush.

Examples

audio/mic/source/main.c, and mvd/source/main.c.

GSPGPU_GetPerfLog()

Result GSPGPU_GetPerfLog

(

GSPGPU_PerfLog *

outPerfLog

)

Retrieves the performance log.

Parameters

[out]

outPerfLog

Pointer to output the performance log to.

Note

Use the difference between two totalDurationUs when using a GPU library (e.g. citro3d), as there can be multiple GPU operations (e.g. P3D, PPF) per render pass, or per frame, and so on. Don't use totalDurationUs as-is (rather, take the difference as just described), because it can overflow.

For a MemoryFill operation that uses both PSC0 and PSC1, take the maximum of the two "last duration" entries.

For PDC0/PDC1 (VBlank0/1), the "last duration" entry corresponds to the time between the current PDC (VBlank) IRQ and the previous one. The official GSP sysmodule assumes both PDC0 and PDC1 IRQ happens at the same rate (this is almost always the case, but not always if user changes PDC timings), and sets both entries in the PDC0 handler.

Bug:

The official sysmodule doesn't handle the PDC0/1 entries correctly after init. On the first frame GSPGPU_SetPerfLogMode is enabled, "last duration" will have a nonsensical value; and "total duration" stays nonsensical. This isn't much of a problem, except for the first frame, because "total duration" is not supposed to be used as-is (you are supposed to take the difference of this field between two time points of your choosing, instead).

Since it is running at approx. 3.25 GiB/s per bank, some small PSC operations might complete before the official GSP has time to record the start time.

The official sysmodule doesn't properly handle data synchronization for the perflog, in practice this should be fine, however.

GSPGPU_ImportDisplayCaptureInfo()

Result GSPGPU_ImportDisplayCaptureInfo

(

GSPGPU_CaptureInfo *

captureinfo

)

Retrieves display capture info.

Parameters

captureinfo

Pointer to output capture info to.

GSPGPU_InvalidateDataCache()

Result GSPGPU_InvalidateDataCache	(	const void *	adr,
		u32	size
	)

Invalidates memory in the data cache.

Parameters

adr	Address to invalidate.
size	Size of the memory to invalidate.

GSPGPU_ReadHWRegs()

Result GSPGPU_ReadHWRegs	(	u32	regAddr,
		u32 *	data,
		u8	size
	)

Reads from GPU hardware registers.

Parameters

regAddr	Register address to read from.
data	Buffer to read data to.
size	Size of the buffer.

GSPGPU_RegisterInterruptRelayQueue()

Result GSPGPU_RegisterInterruptRelayQueue	(	Handle	eventHandle,
		u32	flags,
		Handle *	outMemHandle,
		u8 *	threadID
	)

Registers the interrupt relay queue.

Parameters

eventHandle	Handle of the GX command event.
flags	Flags to register with.
outMemHandle	Pointer to output the shared memory handle to.
threadID	Pointer to output the GSP thread ID to.

GSPGPU_SetBufferSwap()

Result GSPGPU_SetBufferSwap	(	u32	screenid,
		const GSPGPU_FramebufferInfo *	framebufinfo
	)

Updates a screen's framebuffer state.

Parameters

screenid	ID of the screen to update.
framebufinfo	Framebuffer information to update with.

GSPGPU_SetLcdForceBlack()

Result GSPGPU_SetLcdForceBlack

(

u8

flags

)

Sets whether to force the LCD to black.

Parameters

flags

Whether to force the LCD to black. (0 = no, non-zero = yes)

GSPGPU_SetLedForceOff()

Result GSPGPU_SetLedForceOff

(

bool

disable

)

Sets 3D_LEDSTATE to the input state value.

Parameters

disable

False = 3D LED enable, true = 3D LED disable.

GSPGPU_SetPerfLogMode()

Result GSPGPU_SetPerfLogMode

(

bool

enabled

)

Enables or disables the performance log and clear its state to zero.

Parameters

enabled

Whether to enable the performance log.

Note

It is assumed that no GPU operation is in progress when calling this function.

Bug:

The official sysmodule forgets to clear the "start tick" states to 0, though this should not be much of an issue (as per the note above).

GSPGPU_WriteHWRegs()

Result GSPGPU_WriteHWRegs	(	u32	regAddr,
		const u32 *	data,
		u8	size
	)

Writes to GPU hardware registers.

Parameters

regAddr	Register address to write to.
data	Data to write.
size	Size of the data to write.

GSPGPU_WriteHWRegsWithMask()

Result GSPGPU_WriteHWRegsWithMask	(	u32	regAddr,
		const u32 *	data,
		u8	datasize,
		const u32 *	maskdata,
		u8	masksize
	)

Writes to GPU hardware registers with a mask.

Parameters

regAddr	Register address to write to.
data	Data to write.
datasize	Size of the data to write.
maskdata	Data of the mask.
masksize	Size of the mask.

gspIsPresentPending()

bool gspIsPresentPending

(

unsigned

screen

)

Returns true if a prior gspPresentBuffer command is still pending to be processed by GSP.

Parameters

screen

Screen ID (see GSP_SCREEN_TOP and GSP_SCREEN_BOTTOM)

gspPresentBuffer()

bool gspPresentBuffer	(	unsigned	screen,
		unsigned	swap,
		const void *	fb_a,
		const void *	fb_b,
		u32	stride,
		u32	mode
	)

Presents a buffer to the specified screen.

Parameters

screen	Screen ID (see GSP_SCREEN_TOP and GSP_SCREEN_BOTTOM)
swap	Specifies which set of framebuffer registers to configure and activate (0 or 1)
fb_a	Pointer to the framebuffer (in stereo mode: left eye)
fb_b	Pointer to the secondary framebuffer (only used in stereo mode for the right eye, otherwise pass the same as fb_a)
stride	Stride in bytes between scanlines
mode	Mode configuration to be written to LCD register

Returns

true if a buffer had already been presented to the screen but not processed yet by GSP, false otherwise.

Note

The most recently presented buffer is processed and configured during the specified screen's next VBlank event.

gspSetEventCallback()

void gspSetEventCallback	(	GSPGPU_Event	id,
		ThreadFunc	cb,
		void *	data,
		bool	oneShot
	)

Configures a callback to run when a GSPGPU event occurs.

Parameters

id	ID of the event.
cb	Callback to run.
data	Data to be passed to the callback.
oneShot	When true, the callback is only executed once. When false, the callback is executed every time the event occurs.

gspSubmitGxCommand()

Result gspSubmitGxCommand

(

const u32

gxCommand[0x8]

)

Submits a GX command.

Parameters

gxCommand

GX command to execute.

gspWaitForAnyEvent()

GSPGPU_Event gspWaitForAnyEvent

(

void

)

Waits for any GSPGPU event to occur.

Returns

The ID of the event that occurred.

The function returns immediately if there are unprocessed events at the time of call.

gspWaitForEvent()

void gspWaitForEvent	(	GSPGPU_Event	id,
		bool	nextEvent
	)

Waits for a GSPGPU event to occur.

Parameters

id	ID of the event.
nextEvent	Whether to discard the current event and wait for the next event.

Examples

sdmc/source/main.c.