KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
sound.h
Go to the documentation of this file.
1 /* KallistiOS ##version##
2 
3  dc/sound/sound.h
4  Copyright (C) 2002 Dan Potter
5 
6 */
7 
8 /** \file dc/sound/sound.h
9  \brief Low-level sound support and memory management.
10 
11  This file contains declarations for low-level sound operations and for SPU
12  RAM pool memory management. Most of the time you'll be better off using the
13  higher-level functionality in the sound effect support or streaming support,
14  but this stuff can be very useful for some things.
15 
16  \author Dan Potter
17 */
18 
19 #ifndef __DC_SOUND_SOUND_H
20 #define __DC_SOUND_SOUND_H
21 
22 #include <sys/cdefs.h>
23 __BEGIN_DECLS
24 
25 #include <arch/types.h>
26 
27 /** \brief Allocate memory in the SPU RAM pool
28 
29  This function acts as the memory allocator for the SPU RAM pool. It acts
30  much like one would expect a malloc() function to act, although it does not
31  return a pointer directly, but rather an offset in SPU RAM.
32 
33  \param size The amount of memory to allocate, in bytes.
34  \return The location of the start of the block on success,
35  or 0 on failure.
36 */
37 uint32 snd_mem_malloc(size_t size);
38 
39 /** \brief Free a block of allocated memory in the SPU RAM pool.
40 
41  This function frees memory previously allocated with snd_mem_malloc().
42 
43  \param addr The location of the start of the block to free.
44 */
45 void snd_mem_free(uint32 addr);
46 
47 /** \brief Get the size of the largest allocateable block in the SPU RAM pool.
48 
49  This function returns the largest size that can be currently passed to
50  snd_mem_malloc() and expected to not return failure. There may be more
51  memory available in the pool, especially if multiple blocks have been
52  allocated and freed, but calls to snd_mem_malloc() for larger blocks will
53  return failure, since the memory is not available contiguously.
54 
55  \return The size of the largest available block of memory in
56  the SPU RAM pool.
57 */
59 
60 /** \brief Reinitialize the SPU RAM pool.
61 
62  This function reinitializes the SPU RAM pool with the given base offset
63  within the memory space. There is generally not a good reason to do this in
64  your own code, but the functionality is there if needed.
65 
66  \param reserve The amount of memory to reserve as a base.
67  \retval 0 On success (no failure conditions defined).
68 */
69 int snd_mem_init(uint32 reserve);
70 
71 /** \brief Shutdown the SPU RAM allocator.
72 
73  There is generally no reason to be calling this function in your own code,
74  as doing so will cause problems if you try to allocate SPU memory without
75  calling snd_mem_init() afterwards.
76 */
77 void snd_mem_shutdown();
78 
79 /** \brief Initialize the sound system.
80 
81  This function reinitializes the whole sound system. It will not do anything
82  unless the sound system has been shut down previously or has not been
83  initialized yet. This will implicitly replace the program running on the
84  AICA's ARM processor when it actually initializes anything. The default
85  snd_stream_drv will be loaded if a new program is uploaded to the SPU.
86 */
87 int snd_init();
88 
89 /** \brief Shut down the sound system.
90 
91  This function shuts down the whole sound system, freeing memory and
92  disabling the SPU in the process. There's not generally many good reasons
93  for doing this in your own code.
94 */
95 void snd_shutdown();
96 
97 /** \brief Copy a request packet to the AICA queue.
98 
99  This function is to put in a low-level request using the built-in streaming
100  sound driver.
101 
102  \param packet The packet of data to copy.
103  \param size The size of the packet, in 32-bit increments.
104  \retval 0 On success (no error conditions defined).
105 */
106 int snd_sh4_to_aica(void *packet, uint32 size);
107 
108 /** \brief Begin processing AICA queue requests.
109 
110  This function begins processing of any queued requests in the AICA queue.
111 */
112 void snd_sh4_to_aica_start();
113 
114 /** \brief Stop processing AICA queue requests.
115 
116  This function stops the processing of any queued requests in the AICA queue.
117 */
118 void snd_sh4_to_aica_stop();
119 
120 /** \brief Transfer a packet of data from the AICA's SH4 queue.
121 
122  This function is used to retrieve a packet of data from the AICA back to the
123  SH4. The buffer passed in should at least contain 1024 bytes of space to
124  make sure any packet can fit.
125 
126  \param packetout The buffer to store the retrieved packet in.
127  \retval -1 On failure. Failure probably indicates the queue has
128  been corrupted, and thus should be reinitialized.
129  \retval 0 If no packets are available.
130  \retval 1 On successful copy of one packet.
131 */
132 int snd_aica_to_sh4(void *packetout);
133 
134 /** \brief Poll for a response from the AICA.
135 
136  This function waits for the AICA to respond to a previously sent request.
137  This function is not safe to call in an IRQ, as it does implicitly wait.
138 */
139 void snd_poll_resp();
140 
141 __END_DECLS
142 
143 #endif /* __DC_SOUND_SOUND_H */
144 
Common integer types.
int snd_mem_init(uint32 reserve)
Reinitialize the SPU RAM pool.
uint32 snd_mem_available()
Get the size of the largest allocateable block in the SPU RAM pool.
void snd_sh4_to_aica_stop()
Stop processing AICA queue requests.
void snd_mem_free(uint32 addr)
Free a block of allocated memory in the SPU RAM pool.
int snd_init()
Initialize the sound system.
void snd_mem_shutdown()
Shutdown the SPU RAM allocator.
uint32 snd_mem_malloc(size_t size)
Allocate memory in the SPU RAM pool.
void snd_poll_resp()
Poll for a response from the AICA.
unsigned long uint32
32-bit unsigned integer
Definition: types.h:28
void snd_sh4_to_aica_start()
Begin processing AICA queue requests.
int snd_aica_to_sh4(void *packetout)
Transfer a packet of data from the AICA's SH4 queue.
void snd_shutdown()
Shut down the sound system.
int snd_sh4_to_aica(void *packet, uint32 size)
Copy a request packet to the AICA queue.