libctru  v1.6.0
dsp.h
Go to the documentation of this file.
1 /**
2  * @file dsp.h
3  * @brief DSP Service to access the DSP processor commands (sound)
4  *
5  * The DSP has access to the Linear memory region, and to the DSP memory region if allowed in the exheader.
6  */
7 #pragma once
8 #include <3ds/types.h>
9 
10 /// DSP interrupt types.
11 typedef enum
12 {
13  DSP_INTERRUPT_PIPE = 2 ///< Pipe interrupt.
15 
16 /// DSP pipe directions.
17 typedef enum
18 {
19  DSP_PIPE_INPUT = 0, ///< DSP to ARM
20  DSP_PIPE_OUTPUT = 1 ///< ARM to DSP
22 
23 /**
24  * @brief Initializes the dsp service.
25  *
26  * Call this before calling any DSP_* function.
27  * @note This will also unload any previously loaded DSP binary.
28  * It is done this way since you have to provide your binary when the 3DS leaves sleep mode anyway.
29  */
30 Result dspInit(void);
31 
32 /**
33  * @brief Closes the dsp service.
34  * @note This will also unload the DSP binary.
35  */
36 void dspExit(void);
37 
38 /**
39  * @brief Checks if a headphone is inserted.
40  * @param is_inserted Pointer to output the insertion status to.
41  */
42 Result DSP_GetHeadphoneStatus(bool* is_inserted);
43 
44 /**
45  * @brief Flushes the cache
46  * @param address Beginning of the memory range to flush, inside the Linear or DSP memory regions
47  * @param size Size of the memory range to flush
48  *
49  * Flushes the cache for the specified memory range and invalidates the cache
50  */
51 Result DSP_FlushDataCache(const void* address, u32 size);
52 
53 /**
54  * @brief Invalidates the cache
55  * @param address Beginning of the memory range to invalidate, inside the Linear or DSP memory regions
56  * @param size Size of the memory range to flush
57  *
58  * Invalidates the cache for the specified memory range
59  */
60 Result DSP_InvalidateDataCache(const void* address, u32 size);
61 
62 /**
63  * @brief Retrieves the handle of the DSP semaphore.
64  * @param semaphore Pointer to output the semaphore to.
65  */
67 
68 /**
69  * @brief Sets the DSP hardware semaphore value.
70  * @param value Value to set.
71  */
73 
74 /**
75  * @brief Masks the DSP hardware semaphore value.
76  * @param mask Mask to apply.
77  */
79 
80 /**
81  * @brief Loads a DSP binary and starts the DSP
82  * @param component The program file address in memory
83  * @param size The size of the program
84  * @param prog_mask DSP memory block related ? Default is 0xff.
85  * @param data_mask DSP memory block related ? Default is 0xff.
86  * @param is_loaded Indicates if the DSP was succesfully loaded.
87  *
88  * @note The binary must be signed (http://3dbrew.org/wiki/DSP_Binary)
89  * @note Seems to be called when the 3ds leaves the Sleep mode
90  */
91 Result DSP_LoadComponent(const void* component, u32 size, u16 prog_mask, u16 data_mask, bool* is_loaded);
92 
93 ///Stops the DSP by unloading the binary.
95 
96 /**
97  * @brief Registers an event handle with the DSP through IPC
98  * @param handle Event handle to register.
99  * @param interrupt The type of interrupt that will trigger the event. Usual value is DSP_INTERRUPT_PIPE.
100  * @param channel The pipe channel. Usual value is 2
101  *
102  * @note It is possible that interrupt are inverted
103  */
104 Result DSP_RegisterInterruptEvents(Handle handle, u32 interrupt, u32 channel);
105 
106 /**
107  * @brief Reads a pipe if possible.
108  * @param channel unknown. Usually 2
109  * @param peer unknown. Usually 0
110  * @param buffer The buffer that will store the values read from the pipe
111  * @param length Length of the buffer
112  * @param length_read Number of bytes read by the command
113  */
114 Result DSP_ReadPipeIfPossible(u32 channel, u32 peer, void* buffer, u16 length, u16* length_read);
115 
116 /**
117  * @param Writes to a pipe.
118  * @param channel unknown. Usually 2
119  * @param buffer The message to send to the DSP process
120  * @param length Length of the message
121  */
122 Result DSP_WriteProcessPipe(u32 channel, const void* buffer, u32 length);
123 
124 /**
125  * @brief Converts a DSP memory address to a virtual address usable by the process.
126  * @param dsp_address Address to convert.
127  * @param arm_address Pointer to output the converted address to.
128  */
129 Result DSP_ConvertProcessAddressFromDspDram(u32 dsp_address, u32* arm_address);
130 
131 /**
132  * @brief Reads a DSP register
133  * @param regNo Offset of the hardware register, base address is 0x1EC40000
134  * @param value Pointer to read the register value to.
135  */
136 Result DSP_RecvData(u16 regNo, u16* value);
137 
138 /**
139  * @brief Checks if you can read a DSP register
140  * @param regNo Offset of the hardware register, base address is 0x1EC40000
141  * @param is_ready Pointer to write the ready status to.
142  *
143  * @warning This call might hang if the data is not ready. See @ref DSP_SendDataIsEmpty.
144  */
145 Result DSP_RecvDataIsReady(u16 regNo, bool* is_ready);
146 
147 /**
148  * @brief Writes to a DSP register
149  * @param regNo Offset of the hardware register, base address is 0x1EC40000
150  * @param value Value to write.
151  *
152  * @warning This call might hang if the SendData is not empty. See @ref DSP_SendDataIsEmpty.
153  */
154 Result DSP_SendData(u16 regNo, u16 value);
155 
156 /**
157  * @brief Checks if you can write to a DSP register ?
158  * @param regNo Offset of the hardware register, base address is 0x1EC40000
159  * @param is_empty Pointer to write the empty status to.
160  */
161 Result DSP_SendDataIsEmpty(u16 regNo, bool* is_empty);
Result DSP_SendDataIsEmpty(u16 regNo, bool *is_empty)
Checks if you can write to a DSP register ?
Various system types.
s32 Result
Function result.
Definition: types.h:42
uint16_t u16
16-bit unsigned integer
Definition: types.h:22
Result DSP_GetSemaphoreHandle(Handle *semaphore)
Retrieves the handle of the DSP semaphore.
Result dspInit(void)
Initializes the dsp service.
Result DSP_UnloadComponent(void)
Stops the DSP by unloading the binary.
Result DSP_InvalidateDataCache(const void *address, u32 size)
Invalidates the cache.
Result DSP_ConvertProcessAddressFromDspDram(u32 dsp_address, u32 *arm_address)
Converts a DSP memory address to a virtual address usable by the process.
u32 Handle
Resource handle.
Definition: types.h:41
Result DSP_SetSemaphoreMask(u16 mask)
Masks the DSP hardware semaphore value.
Result DSP_WriteProcessPipe(u32 channel, const void *buffer, u32 length)
uint32_t u32
32-bit unsigned integer
Definition: types.h:23
Result DSP_GetHeadphoneStatus(bool *is_inserted)
Checks if a headphone is inserted.
DSP_InterruptType
DSP interrupt types.
Definition: dsp.h:11
Result DSP_RecvDataIsReady(u16 regNo, bool *is_ready)
Checks if you can read a DSP register.
Result DSP_RecvData(u16 regNo, u16 *value)
Reads a DSP register.
Result DSP_FlushDataCache(const void *address, u32 size)
Flushes the cache.
DSP to ARM.
Definition: dsp.h:19
Result DSP_RegisterInterruptEvents(Handle handle, u32 interrupt, u32 channel)
Registers an event handle with the DSP through IPC.
Result DSP_LoadComponent(const void *component, u32 size, u16 prog_mask, u16 data_mask, bool *is_loaded)
Loads a DSP binary and starts the DSP.
ARM to DSP.
Definition: dsp.h:20
Result DSP_ReadPipeIfPossible(u32 channel, u32 peer, void *buffer, u16 length, u16 *length_read)
Reads a pipe if possible.
Result DSP_SendData(u16 regNo, u16 value)
Writes to a DSP register.
Pipe interrupt.
Definition: dsp.h:13
DSP_PipeDirection
DSP pipe directions.
Definition: dsp.h:17
Result DSP_SetSemaphore(u16 value)
Sets the DSP hardware semaphore value.
void dspExit(void)
Closes the dsp service.