Store Queues

SH4 CPU Peripheral for burst memory transactions. More...

Files
file	sq.h
	Functions to access the SH4 Store Queues.

Macros
#define	SQ_MASK_DEST_ADDR(dest)
	Mask dest to Store Queue area as address.
#define	SQ_MASK_DEST(dest)
	Mask dest to Store Queue area as pointer.
#define	sq_flush(dest)
	Write-back one Store Queue.

Functions
void *	pvr_sq_load (void *dest, const void *src, size_t n, pvr_dma_type_t type)
	Copy a block of memory to VRAM.
void *	pvr_sq_set16 (void *dest, uint32_t c, size_t n, pvr_dma_type_t type)
	Set a block of PVR memory to a 16-bit value.
void *	pvr_sq_set32 (void *dest, uint32_t c, size_t n, pvr_dma_type_t type)
	Set a block of PVR memory to a 32-bit value.
uint32_t *	sq_lock (void *dest)
	Lock Store Queues.
void	sq_unlock (void)
	Unlock Store Queues.
void	sq_wait (void)
	Wait for both Store Queues to complete.
void *	sq_cpy (void *dest, const void *src, size_t n)
	Copy a block of memory.
void *	sq_fast_cpy (void *dest, const void *src, size_t n)
	Copy a block of memory.
void *	sq_set (void *dest, uint32_t c, size_t n)
	Set a block of memory to an 8-bit value.
void *	sq_set16 (void *dest, uint32_t c, size_t n)
	Set a block of memory to a 16-bit value.
void *	sq_set32 (void *dest, uint32_t c, size_t n)
	Set a block of memory to a 32-bit value.
void	sq_clr (void *dest, size_t n)
	Clear a block of memory.

Detailed Description

SH4 CPU Peripheral for burst memory transactions.

The store queues are a way to do efficient burst transfers from the CPU to external memory. They can be used in a variety of ways, such as to transfer a texture to PVR memory. The transfers are in units of 32-bytes, and the destinations must be 32-byte aligned.

Note

Mastery over knowing when and how to utilize the store queues is important when trying to push the limits of the Dreamcast, specifically when transferring chunks of data between regions of memory. It is often the case that the DMA is faster for transactions which are consistently large; however, the store queues tend to have better performance and have less configuration overhead when bursting smaller chunks of data.

Macro Definition Documentation

sq_flush

#define sq_flush

(

dest

)

Value:

dcache_wback_sq(dest)

Write-back one Store Queue.

Initiates write-back from SQ buffer to external memory.

Parameters

dest	The address to copy to (32-byte aligned).

See also

sq_wait()

SQ_MASK_DEST

#define SQ_MASK_DEST

(

dest

)

Value:

    ((uint32_t *)(void *) SQ_MASK_DEST_ADDR(dest))

Mask dest to Store Queue area as pointer.

SQ_MASK_DEST_ADDR

#define SQ_MASK_DEST_ADDR

(

dest

)

Value:

    (MEM_AREA_SQ_BASE | ((uintptr_t)(dest) & 0x03ffffe0))

Mask dest to Store Queue area as address.

Function Documentation

pvr_sq_load()

void * pvr_sq_load	(	void *	dest,
		const void *	src,
		size_t	n,
		pvr_dma_type_t	type )

Copy a block of memory to VRAM.

This function is similar to sq_cpy(), but it has been optimized for writing to a destination residing within VRAM.

Warning

This function cannot be used at the same time as a PVR DMA transfer.

The dest pointer must be at least 32-byte aligned and reside in video memory, the src pointer must be at least 8-byte aligned, and n must be a multiple of 32.

Parameters

dest	The address to copy to (32-byte aligned).
src	The address to copy from (32-bit (8-byte) aligned).
n	The number of bytes to copy (multiple of 32).
type	The type of SQ/DMA transfer to do (see list of modes).

Returns

The original value of dest.

See also

pvr_sq_set32()

pvr_sq_set16()

void * pvr_sq_set16	(	void *	dest,
		uint32_t	c,
		size_t	n,
		pvr_dma_type_t	type )

Set a block of PVR memory to a 16-bit value.

This function is similar to sq_set16(), but it has been optimized for writing to a destination residing within VRAM.

Warning

This function cannot be used at the same time as a PVR DMA transfer.

The dest pointer must be at least 32-byte aligned and reside in video memory, n must be a multiple of 32 and only the low 16-bits are used from c.

Parameters

dest	The address to begin setting at (32-byte aligned).
c	The value to set (in the low 16-bits).
n	The number of bytes to set (multiple of 32).
type	The type of SQ/DMA transfer to do (see list of modes).

Returns

The original value of dest.

See also

pvr_sq_set32()

pvr_sq_set32()

void * pvr_sq_set32	(	void *	dest,
		uint32_t	c,
		size_t	n,
		pvr_dma_type_t	type )

Set a block of PVR memory to a 32-bit value.

This function is similar to sq_set32(), but it has been optimized for writing to a destination residing within VRAM.

Warning

This function cannot be used at the same time as a PVR DMA transfer.

The dest pointer must be at least 32-byte aligned and reside in video memory, n must be a multiple of 32.

Parameters

dest	The address to begin setting at (32-byte aligned).
c	The value to set.
n	The number of bytes to set (multiple of 32).
type	The type of SQ/DMA transfer to do (see list of modes).

Returns

The original value of dest.

See also

pvr_sq_set16

sq_clr()

void sq_clr	(	void *	dest,
		size_t	n )

Clear a block of memory.

This function is similar to calling memset() with a value to set of 0, but uses the store queues to do its work.

Warning

The dest pointer must be a 32-byte aligned with n being a multiple of 32!

Parameters

dest	The address to begin clearing at (32-byte aligned).
n	The number of bytes to clear (multiple of 32).

sq_cpy()

void * sq_cpy	(	void *	dest,
		const void *	src,
		size_t	n )

Copy a block of memory.

This function is similar to memcpy4(), but uses the store queues to do its work.

Warning

The dest pointer must be at least 32-byte aligned, the src pointer must be at least 4-byte aligned (8-byte aligned uses fast path), and n must be a multiple of 32!

Parameters

dest	The address to copy to (32-byte aligned).
src	The address to copy from (32-bit (4/8-byte) aligned).
n	The number of bytes to copy (multiple of 32).

Returns

The original value of dest.

See also

sq_fast_cpy()

sq_fast_cpy()

void * sq_fast_cpy	(	void *	dest,
		const void *	src,
		size_t	n )

Copy a block of memory.

This function is similar to sq_cpy() but expects the user to lock/unlock the store queues before and after as well as having different requirements for the params.

Warning

The dest pointer must be at least 32-byte aligned that already has been masked by SQ_MASK_DEST(), the src pointer must be at least 8-byte aligned, and n must be the number of 32-byte blocks you want to copy.

Parameters

dest	The store queue address to copy to (32-byte aligned).
src	The address to copy from (8-byte aligned).
n	The number of 32-byte blocks to copy.

Returns

The original value of dest.

See also

sq_cpy()

sq_lock()

uint32_t * sq_lock

(

void *

dest

)

Lock Store Queues.

Locks the store queues so that they cannot be used from another thread until unlocked.

Warning

This function is called automatically by the store queue API provided by KOS; however, it must be called manually when driving the SQs directly from outside of this API.

Parameters

dest	The destination address.

Returns

The translated address that can be directly written to.

See also

sq_unlock()

sq_set()

void * sq_set	(	void *	dest,
		uint32_t	c,
		size_t	n )

Set a block of memory to an 8-bit value.

This function is similar to calling memset(), but uses the store queues to do its work.

Warning

The dest pointer must be a 32-byte aligned with n being a multiple of 32, and only the low 8-bits are used from c.

Parameters

dest	The address to begin setting at (32-byte aligned).
c	The value to set (in the low 8-bits).
n	The number of bytes to set (multiple of 32).

Returns

The original value of dest.

See also

sq_set16(), sq_set32()

sq_set16()

void * sq_set16	(	void *	dest,
		uint32_t	c,
		size_t	n )

Set a block of memory to a 16-bit value.

This function is similar to calling memset2(), but uses the store queues to do its work.

Warning

The dest pointer must be a 32-byte aligned with n being a multiple of 32, and only the low 16-bits are used from c.

Parameters

dest	The address to begin setting at (32-byte aligned).
c	The value to set (in the low 16-bits).
n	The number of bytes to set (multiple of 32).

Returns

The original value of dest.

See also

sq_set(), sq_set32()

sq_set32()

void * sq_set32	(	void *	dest,
		uint32_t	c,
		size_t	n )

Set a block of memory to a 32-bit value.

This function is similar to calling memset4(), but uses the store queues to do its work.

Warning

The dest pointer must be a 32-byte aligned with n being a multiple of 32!

Parameters

dest	The address to begin setting at (32-byte aligned).
c	The value to set (all 32-bits).
n	The number of bytes to set (multiple of 32).

Returns

The original value of dest.

See also

sq_set(), sq_set16()

sq_unlock()

void sq_unlock

(

void

)

Unlock Store Queues.

Unlocks the store queues so that they can be used from any thread.

Note

sq_lock() should've already been called previously.

Warning

sq_lock() and sq_unlock() are called automatically by the store queue API provided by KOS; however, they must be called manually when driving the SQs directly from outside this API.

See also

sq_lock()

sq_wait()

void sq_wait

(

void

)

Wait for both Store Queues to complete.

Wait for both store queues to complete by writing to SQ area.

See also

sq_lock()