Low-level driver for SPU and audio management More...

Topics
	AICA
	API defining the SH4/AICA shared interface

Files
file	sound.h
	Low-level sound support and memory management.

file	spu.h
	Functions related to sound.

Macros
#define	SPU_RAM_BASE 0x00800000
	Sound ram address from the SH4 side.

#define	SPU_RAM_UNCACHED_BASE (MEM_AREA_P2_BASE \| SPU_RAM_BASE)

Typedefs
typedef g2_dma_callback_t	spu_dma_callback_t
	SPU DMA callback type.

Functions
uint32	snd_mem_malloc (size_t size)
	Allocate memory in the SPU RAM pool.

void	snd_mem_free (uint32 addr)
	Free a block of allocated memory in the SPU RAM pool.

uint32	snd_mem_available (void)
	Get the size of the largest allocateable block in the SPU RAM pool.

int	snd_mem_init (uint32 reserve)
	Reinitialize the SPU RAM pool.

void	snd_mem_shutdown (void)
	Shutdown the SPU RAM allocator.

int	snd_init (void)
	Initialize the sound system.

void	snd_shutdown (void)
	Shut down the sound system.

int	snd_sh4_to_aica (void *packet, uint32 size)
	Copy a request packet to the AICA queue.

void	snd_sh4_to_aica_start (void)
	Begin processing AICA queue requests.

void	snd_sh4_to_aica_stop (void)
	Stop processing AICA queue requests.

int	snd_aica_to_sh4 (void *packetout)
	Transfer a packet of data from the AICA's SH4 queue.

void	snd_poll_resp (void)
	Poll for a response from the AICA.

void	snd_pcm16_split (uint32_t data, uint32_t left, uint32_t *right, size_t size)
	Separates stereo PCM samples into 2 mono channels.

void	snd_pcm16_split_sq (uint32_t *data, uintptr_t left, uintptr_t right, size_t size)
	Separates stereo PCM samples into 2 mono channels with SQ transfer.

void	snd_pcm8_split (uint32_t data, uint32_t left, uint32_t *right, size_t size)
	Separates stereo PCM samples into 2 mono channels.

void	snd_adpcm_split (uint32_t data, uint32_t left, uint32_t *right, size_t size)
	Separates stereo ADPCM samples into 2 mono channels.

void	spu_memload (uintptr_t to, void *from, size_t length)
	Copy a block of data to sound RAM.

void	spu_memload_sq (uintptr_t to, void *from, size_t length)
	Copy a block of data to sound RAM by using the Store Queues.

void	spu_memload_dma (uintptr_t to, void *from, size_t length)
	Copy a block of data to sound RAM by using DMA (or SQ on fails).

void	spu_memread (void *to, uintptr_t from, size_t length)
	Copy a block of data from sound RAM.

void	spu_memset (uintptr_t to, uint32_t what, size_t length)
	Set a block of sound RAM to the specified value.

void	spu_memset_sq (uintptr_t to, uint32_t what, size_t length)
	Set a block of sound RAM to the specified value.

int	spu_dma_transfer (void from, uintptr_t dest, size_t length, int block, spu_dma_callback_t callback, void cbdata)
	Copy a block of data from SH4 RAM to sound RAM via DMA.

void	spu_enable (void)
	Enable the SPU.

void	spu_disable (void)
	Disable the SPU.

void	spu_cdda_volume (int left_volume, int right_volume)
	Set CDDA volume.

void	spu_cdda_pan (int left_pan, int right_pan)
	Set CDDA panning.

void	spu_master_mixer (int volume, int stereo)
	Set master mixer settings.

int	spu_init (void)
	Initialize the SPU.

int	spu_shutdown (void)
	Shutdown the SPU.

void	spu_reset_chans (void)
	Reset SPU channels.

Detailed Description

Low-level driver for SPU and audio management

Macro Definition Documentation

◆ SPU_RAM_BASE

#define SPU_RAM_BASE 0x00800000

Sound ram address from the SH4 side.

◆ SPU_RAM_UNCACHED_BASE

#define SPU_RAM_UNCACHED_BASE (MEM_AREA_P2_BASE | SPU_RAM_BASE)

Typedef Documentation

◆ spu_dma_callback_t

typedef g2_dma_callback_t spu_dma_callback_t

SPU DMA callback type.

Function Documentation

◆ snd_adpcm_split()

void snd_adpcm_split	(	uint32_t *	data,
		uint32_t *	left,
		uint32_t *	right,
		size_t	size )

Separates stereo ADPCM samples into 2 mono channels.

Splits a buffer containing 2 interleaved channels of 4-bit ADPCM samples into 2 separate buffers of 4-bit ADPCM samples.

Parameters

data	Source buffer of interleaved stereo samples
left	Destination buffer for left mono samples
right	Destination buffer for right mono samples
size	Size of the source buffer in bytes

See also: snd_pcm16_split()

◆ snd_aica_to_sh4()

int snd_aica_to_sh4 ( void * packetout )

Transfer a packet of data from the AICA's SH4 queue.

This function is used to retrieve a packet of data from the AICA back to the SH4. The buffer passed in should at least contain 1024 bytes of space to make sure any packet can fit.

Parameters

packetout The buffer to store the retrieved packet in.

Return values

-1	On failure. Failure probably indicates the queue has been corrupted, and thus should be reinitialized.
0	If no packets are available.
1	On successful copy of one packet.

◆ snd_init()

int snd_init ( void )

Initialize the sound system.

This function reinitializes the whole sound system. It will not do anything unless the sound system has been shut down previously or has not been initialized yet. This will implicitly replace the program running on the AICA's ARM processor when it actually initializes anything. The default snd_stream_drv will be loaded if a new program is uploaded to the SPU.

◆ snd_mem_available()

uint32 snd_mem_available ( void )

Get the size of the largest allocateable block in the SPU RAM pool.

This function returns the largest size that can be currently passed to snd_mem_malloc() and expected to not return failure. There may be more memory available in the pool, especially if multiple blocks have been allocated and freed, but calls to snd_mem_malloc() for larger blocks will return failure, since the memory is not available contiguously.

Returns: The size of the largest available block of memory in the SPU RAM pool.

◆ snd_mem_free()

void snd_mem_free ( uint32 addr )

Free a block of allocated memory in the SPU RAM pool.

This function frees memory previously allocated with snd_mem_malloc().

Parameters

addr	The location of the start of the block to free.

◆ snd_mem_init()

int snd_mem_init ( uint32 reserve )

Reinitialize the SPU RAM pool.

This function reinitializes the SPU RAM pool with the given base offset within the memory space. There is generally not a good reason to do this in your own code, but the functionality is there if needed.

Parameters

reserve The amount of memory to reserve as a base.

Return values

0	On success (no failure conditions defined).

◆ snd_mem_malloc()

uint32 snd_mem_malloc ( size_t size )

Allocate memory in the SPU RAM pool.

This function acts as the memory allocator for the SPU RAM pool. It acts much like one would expect a malloc() function to act, although it does not return a pointer directly, but rather an offset in SPU RAM.

Parameters

size	The amount of memory to allocate, in bytes.

Returns: The location of the start of the block on success, or 0 on failure.

◆ snd_mem_shutdown()

void snd_mem_shutdown ( void )

Shutdown the SPU RAM allocator.

There is generally no reason to be calling this function in your own code, as doing so will cause problems if you try to allocate SPU memory without calling snd_mem_init() afterwards.

◆ snd_pcm16_split()

void snd_pcm16_split	(	uint32_t *	data,
		uint32_t *	left,
		uint32_t *	right,
		size_t	size )

Separates stereo PCM samples into 2 mono channels.

Splits a buffer containing 2 interleaved channels of 16-bit PCM samples into 2 separate buffers of 16-bit PCM samples.

Warning: All arguments must be 32-byte aligned.

Parameters

data	Source buffer of interleaved stereo samples
left	Destination buffer for left mono samples
right	Destination buffer for right mono samples
size	Size of the source buffer in bytes (must be divisible by 32)

See also: snd_pcm16_split_sq()

◆ snd_pcm16_split_sq()

void snd_pcm16_split_sq	(	uint32_t *	data,
		uintptr_t	left,
		uintptr_t	right,
		size_t	size )

Separates stereo PCM samples into 2 mono channels with SQ transfer.

Splits a buffer containing 2 interleaved channels of 16-bit PCM samples into 2 separate buffers of 16-bit PCM samples by using the store queues for data transfer.

Warning: All arguments must be 32-byte aligned.

Parameters

data	Source buffer of interleaved stereo samples
left	Destination buffer address for left mono samples
right	Destination buffer address for right mono samples
size	Size of the source buffer in bytes (must be divisible by 32)

See also: snd_pcm16_split() Store queues must be prepared before.

◆ snd_pcm8_split()

void snd_pcm8_split	(	uint32_t *	data,
		uint32_t *	left,
		uint32_t *	right,
		size_t	size )

Separates stereo PCM samples into 2 mono channels.

Splits a buffer containing 2 interleaved channels of 8-bit PCM samples into 2 separate buffers of 8-bit PCM samples.

Parameters

data	Source buffer of interleaved stereo samples
left	Destination buffer for left mono samples
right	Destination buffer for right mono samples
size	Size of the source buffer in bytes

See also: snd_adpcm_split()

◆ snd_poll_resp()

void snd_poll_resp ( void )

Poll for a response from the AICA.

This function waits for the AICA to respond to a previously sent request. This function is not safe to call in an IRQ, as it does implicitly wait.

◆ snd_sh4_to_aica()

int snd_sh4_to_aica	(	void *	packet,
		uint32	size )

Copy a request packet to the AICA queue.

This function is to put in a low-level request using the built-in streaming sound driver.

Parameters

packet	The packet of data to copy.
size	The size of the packet, in 32-bit increments.

Return values

0	On success (no error conditions defined).

◆ snd_sh4_to_aica_start()

void snd_sh4_to_aica_start ( void )

Begin processing AICA queue requests.

This function begins processing of any queued requests in the AICA queue.

◆ snd_sh4_to_aica_stop()

void snd_sh4_to_aica_stop ( void )

Stop processing AICA queue requests.

This function stops the processing of any queued requests in the AICA queue.

◆ snd_shutdown()

void snd_shutdown ( void )

Shut down the sound system.

This function shuts down the whole sound system, freeing memory and disabling the SPU in the process. There's not generally many good reasons for doing this in your own code.

◆ spu_cdda_pan()

void spu_cdda_pan	(	int	left_pan,
		int	right_pan )

Set CDDA panning.

Valid values are from 0-31. 16 is centered.

Parameters

left_pan	Pan of the left channel.
right_pan	Pan of the right channel.

◆ spu_cdda_volume()

void spu_cdda_volume	(	int	left_volume,
		int	right_volume )

Set CDDA volume.

Valid volume values are 0-15.

Parameters

left_volume	Volume of the left channel.
right_volume	Volume of the right channel.

◆ spu_disable()

void spu_disable ( void )

Disable the SPU.

This function resets all sound channels and puts the ARM in a reset state.

◆ spu_dma_transfer()

int spu_dma_transfer	(	void *	from,
		uintptr_t	dest,
		size_t	length,
		int	block,
		spu_dma_callback_t	callback,
		void *	cbdata )

Copy a block of data from SH4 RAM to sound RAM via DMA.

This function sets up a DMA transfer from main RAM to the sound RAM with G2 DMA.

Parameters

from	A pointer in main RAM to transfer from. Must be 32-byte aligned.
dest	Offset in sound RAM to transfer to. Do not include the 0xA0800000 part, its implied. Must be 32-byte aligned.
length	Number of bytes to copy. Must be a multiple of 32.
block	1 if you want to wait for the transfer to complete, 0 otherwise (use the callback for this case).
callback	Function to call when the DMA completes. Can be NULL if you don't want to have a callback. This will be called in an interrupt context, so keep that in mind when writing the function.
cbdata	Data to pass to the callback function.

Return values

-1	On failure. Sets errno as appropriate.
0	On success.

Error Conditions:: EINVAL - Invalid channel
EFAULT - from or dest is not aligned
EIO - I/O error

◆ spu_enable()

void spu_enable ( void )

Enable the SPU.

This function resets all sound channels and lets the ARM out of reset.

◆ spu_init()

int spu_init ( void )

Initialize the SPU.

This function will reset the SPU, clear the sound RAM, reinit the CDDA support and run an infinite loop on the ARM.

Return values

0	On success (no error conditions defined).

◆ spu_master_mixer()

void spu_master_mixer	(	int	volume,
		int	stereo )

Set master mixer settings.

This function sets the master mixer volume and mono/stereo setting.

Parameters

volume	The volume to set (0-15).
stereo	1 for stereo output, 0 for mono.

◆ spu_memload()

void spu_memload	(	uintptr_t	to,
		void *	from,
		size_t	length )

Copy a block of data to sound RAM.

This function acts much like memcpy() but copies to the sound RAM area.

Parameters

to	The offset in sound RAM to copy to. Do not include the 0xA0800000 part, it is implied.
from	A pointer to copy from.
length	The number of bytes to copy. Automatically rounded up to be a multiple of 4.

◆ spu_memload_dma()

void spu_memload_dma	(	uintptr_t	to,
		void *	from,
		size_t	length )

Copy a block of data to sound RAM by using DMA (or SQ on fails).

This function acts much like memcpy() but copies to the sound RAM area by using the DMA. If DMA fails, then will be used the Store Queues.

Parameters

to	The offset in sound RAM to copy to. Do not include the 0xA0800000 part, it is implied.
from	A pointer to copy from.
length	The number of bytes to copy. Must be a multiple of 32.

◆ spu_memload_sq()

void spu_memload_sq	(	uintptr_t	to,
		void *	from,
		size_t	length )

Copy a block of data to sound RAM by using the Store Queues.

This function acts much like memcpy() but copies to the sound RAM area by using the Store Queues.

Parameters

to	The offset in sound RAM to copy to. Do not include the 0xA0800000 part, it is implied.
from	A pointer to copy from.
length	The number of bytes to copy. Automatically rounded up to be a multiple of 4.

◆ spu_memread()

void spu_memread	(	void *	to,
		uintptr_t	from,
		size_t	length )

Copy a block of data from sound RAM.

This function acts much like memcpy() but copies from the sound RAM area.

Parameters

to	A pointer to copy to.
from	The offset in sound RAM to copy from. Do not include the 0xA0800000 part, it is implied.
length	The number of bytes to copy. Automatically rounded up to be a multiple of 4.

◆ spu_memset()

void spu_memset	(	uintptr_t	to,
		uint32_t	what,
		size_t	length )

Set a block of sound RAM to the specified value.

This function acts like memset4(), setting the specified block of sound RAM to the given 32-bit value.

Parameters

to	The offset in sound RAM to set at. Do not include the 0xA0800000 part, it is implied.
what	The value to set.
length	The number of bytes to copy. Automatically rounded up to be a multiple of 4.

◆ spu_memset_sq()

void spu_memset_sq	(	uintptr_t	to,
		uint32_t	what,
		size_t	length )

Set a block of sound RAM to the specified value.

This function acts like memset4(), setting the specified block of sound RAM to the given 32-bit value by using the Store Queues.

Parameters

to	The offset in sound RAM to set at. Do not include the 0xA0800000 part, it is implied.
what	The value to set.
length	The number of bytes to copy. Automatically rounded up to be a multiple of 4.

◆ spu_reset_chans()

void spu_reset_chans ( void )

Reset SPU channels.

◆ spu_shutdown()

int spu_shutdown ( void )

Shutdown the SPU.

This function disables the SPU and clears sound RAM.

Return values

0	On success (no error conditions defined).

Topics

Files

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SPU_RAM_BASE

◆ SPU_RAM_UNCACHED_BASE

Typedef Documentation

◆ spu_dma_callback_t

Function Documentation

◆ snd_adpcm_split()

◆ snd_aica_to_sh4()

◆ snd_init()

◆ snd_mem_available()

◆ snd_mem_free()

◆ snd_mem_init()

◆ snd_mem_malloc()

◆ snd_mem_shutdown()

◆ snd_pcm16_split()

◆ snd_pcm16_split_sq()

◆ snd_pcm8_split()

◆ snd_poll_resp()

◆ snd_sh4_to_aica()

◆ snd_sh4_to_aica_start()

◆ snd_sh4_to_aica_stop()

◆ snd_shutdown()

◆ spu_cdda_pan()

◆ spu_cdda_volume()

◆ spu_disable()

◆ spu_dma_transfer()

◆ spu_enable()

◆ spu_init()

◆ spu_master_mixer()

◆ spu_memload()

◆ spu_memload_dma()

◆ spu_memload_sq()

◆ spu_memread()

◆ spu_memset()

◆ spu_memset_sq()

◆ spu_reset_chans()

◆ spu_shutdown()