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 *	pvr_sq_load (void dest, const void src, size_t n, int type)
	Copy a block of memory to VRAM.

void *	pvr_sq_set16 (void *dest, uint32_t c, size_t n, int type)
	Set a block of PVR memory to a 16-bit value.

void *	pvr_sq_set32 (void *dest, uint32_t c, size_t n, int type)
	Set a block of PVR memory to a 32-bit value.

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

◆ pvr_sq_load()

void * pvr_sq_load	(	void *	dest,
		const void *	src,
		size_t	n,
		int	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,
		int	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,
		int	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()

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

Files

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ sq_flush

◆ SQ_MASK_DEST

◆ SQ_MASK_DEST_ADDR

Function Documentation

◆ pvr_sq_load()

◆ pvr_sq_set16()

◆ pvr_sq_set32()

◆ sq_clr()

◆ sq_cpy()

◆ sq_fast_cpy()

◆ sq_lock()

◆ sq_set()

◆ sq_set16()

◆ sq_set32()

◆ sq_unlock()

◆ sq_wait()