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)    (MEM_AREA_SQ_BASE | ((uintptr_t)(dest) & 0x03ffffe0))
	Mask dest to Store Queue area as address.
#define	SQ_MASK_DEST(dest)    ((uint32_t *)(void *) SQ_MASK_DEST_ADDR(dest))
	Mask dest to Store Queue area as pointer.
#define	sq_flush(dest)   dcache_wback_sq(dest)
	Write-back one Store Queue.

Functions
void	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

)

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

)

((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

)

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

Mask dest to Store Queue area as address.

Function Documentation

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()

void 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.

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()