1 /*---------------------------------------------------------------------------*
2   Project:  TwlSDK - SPI - include
3   File:     api.h
4 
5   Copyright 2003-2008 Nintendo. All rights reserved.
6 
7   These coded instructions, statements, and computer programs contain
8   proprietary information of Nintendo of America Inc. and/or Nintendo
9   Company Ltd., and are protected by Federal copyright law. They may
10   not be disclosed to third parties or copied or duplicated in any form,
11   in whole or in part, without the prior written consent of Nintendo.
12 
13   $Date:: 2008-09-18#$
14   $Rev: 8573 $
15   $Author: okubata_ryoma $
16  *---------------------------------------------------------------------------*/
17 
18 #ifndef NITRO_SPI_ARM9_MIC_H_
19 #define NITRO_SPI_ARM9_MIC_H_
20 
21 #ifdef  __cplusplus
22 extern "C" {
23 #endif
24 
25 /*===========================================================================*/
26 
27 #include    <nitro/spi/common/type.h>
28 #include    <nitro/pxi.h>
29 
30 
31 /*---------------------------------------------------------------------------*
32     Constant Definitions
33  *---------------------------------------------------------------------------*/
34 // Processing result definition
35 typedef enum MICResult
36 {
37     MIC_RESULT_SUCCESS = 0,            // Success
38     MIC_RESULT_BUSY,                   // Exclusion control in effect
39     MIC_RESULT_ILLEGAL_PARAMETER,      // Illegal parameter
40     MIC_RESULT_SEND_ERROR,             // Failed transmission by PXI
41     MIC_RESULT_INVALID_COMMAND,        // Unknown command
42     MIC_RESULT_ILLEGAL_STATUS,         // Status does not permit execution
43     MIC_RESULT_FATAL_ERROR,            // Errors other than those above
44     MIC_RESULT_MAX
45 }
46 MICResult;
47 
48 // Sampling type definitions
49 typedef enum MICSamplingType
50 {
51     MIC_SAMPLING_TYPE_8BIT = 0,        //  8-bit sampling
52     MIC_SAMPLING_TYPE_12BIT,           // 12-bit sampling
53     MIC_SAMPLING_TYPE_SIGNED_8BIT,     // Signed 8-bit sampling
54     MIC_SAMPLING_TYPE_SIGNED_12BIT,    // Signed 12-bit sampling
55     MIC_SAMPLING_TYPE_12BIT_FILTER_OFF,
56     MIC_SAMPLING_TYPE_SIGNED_12BIT_FILTER_OFF,
57     MIC_SAMPLING_TYPE_MAX
58 }
59 MICSamplingType;
60 
61 // Typical sampling periods are defined in ARM7 clock ticks.
62 typedef enum MICSamplingRate
63 {
64     MIC_SAMPLING_RATE_8K = (HW_CPU_CLOCK_ARM7 / 8000),  // Approx. 8.0 kHz
65     MIC_SAMPLING_RATE_11K = (HW_CPU_CLOCK_ARM7 / 11025),        // Approx. 11.025 kHz
66     MIC_SAMPLING_RATE_16K = (HW_CPU_CLOCK_ARM7 / 16000),        // Approx. 16.0 kHz
67     MIC_SAMPLING_RATE_22K = (HW_CPU_CLOCK_ARM7 / 22050),        // Approx. 22.05 kHz
68     MIC_SAMPLING_RATE_32K = (HW_CPU_CLOCK_ARM7 / 32000),        // Approx. 32.0 kHz
69     MIC_SAMPLING_RATE_LIMIT = 1024
70 }
71 MICSamplingRate;
72 
73 /*---------------------------------------------------------------------------*
74     Structure Definitions
75  *---------------------------------------------------------------------------*/
76 // Callback function type definitions
77 typedef void (*MICCallback) (MICResult result, void *arg);
78 
79 // Auto-sampling setting definitions
80 typedef struct MICAutoParam
81 {
82     MICSamplingType type;              // Sampling type
83     void   *buffer;                    // Pointer to result storage buffer
84     u32     size;                      // Buffer size
85     u32     rate;                      // Sampling period (ARM7 clock count)
86     BOOL    loop_enable;               // Enable/disable the loop when buffer is full
87     MICCallback full_callback;         // Callback when buffer is full
88     void   *full_arg;                  // Argument to specify for the above callbacks
89 
90 }
91 MICAutoParam;
92 
93 
94 /*---------------------------------------------------------------------------*
95     Function Definitions
96  *---------------------------------------------------------------------------*/
97 
98 /*---------------------------------------------------------------------------*
99   Name:         MIC_Init
100 
101   Description:  Initializes microphone library
102 
103   Arguments:    None.
104 
105   Returns:      None.
106  *---------------------------------------------------------------------------*/
107 void    MIC_Init(void);
108 
109 /*---------------------------------------------------------------------------*
110   Name:         MIC_DoSamplingAsync
111 
112   Description:  Performs a single asynchronous sample of the microphone.
113 
114   Arguments:    type:      - Specifies the sampling type.
115                 buf:       - Specifies the buffer that stores the sampling data.
116                 callback     - Specifies the function to be called when the asynchronous process is completed.
117                 arg       - Specifies the argument used when calling the callback function.
118 
119   Returns:      MICResult:    - Returns the result of starting the asynchronous device operation
120  *---------------------------------------------------------------------------*/
121 MICResult MIC_DoSamplingAsync(MICSamplingType type, void *buf, MICCallback callback, void *arg);
122 
123 /*---------------------------------------------------------------------------*
124   Name:         MIC_StartAutoSamplingAsync
125 
126   Description:  Asynchronously starts microphone auto-sampling
127 
128   Arguments:    param:     - Pointer to a structure that specifies auto-sampling settings
129                 callback     - Specifies the function to be called when the asynchronous process is completed.
130                 arg       - Specifies the argument used when calling the callback function.
131 
132   Returns:      MICResult:    - Returns the result of starting the asynchronous device operation.
133  *---------------------------------------------------------------------------*/
134 MICResult MIC_StartAutoSamplingAsync(const MICAutoParam *param, MICCallback callback, void *arg);
135 
136 /*---------------------------------------------------------------------------*
137   Name:         MIC_StopAutoSamplingAsync
138 
139   Description:  Asynchronously stops microphone auto-sampling
140 
141   Arguments:    callback     - Specifies the function to be called when the asynchronous process is completed.
142                 arg       - Specifies the argument used when calling the callback function.
143 
144   Returns:      MICResult:    - Returns the result of starting the asynchronous device operation.
145  *---------------------------------------------------------------------------*/
146 MICResult MIC_StopAutoSamplingAsync(MICCallback callback, void *arg);
147 
148 /*---------------------------------------------------------------------------*
149   Name:         MIC_AdjustAutoSamplingAsync
150 
151   Description:  Asynchronously adjusts the sampling rate used in microphone auto-sampling
152 
153 
154   Arguments:    rate:       - Specifies the sampling rate.
155                 callback     - Specifies the function to be called when the asynchronous process is completed.
156                 arg       - Specifies the argument used when calling the callback function.
157 
158   Returns:      MICResult:    - Returns the result of starting the asynchronous device operation.
159  *---------------------------------------------------------------------------*/
160 MICResult MIC_AdjustAutoSamplingAsync(u32 rate, MICCallback callback, void *arg);
161 
162 /*---------------------------------------------------------------------------*
163   Name:         MIC_GetLastSamplingAddress
164 
165   Description:  Gets the address where the most recent mic sampling result is stored
166 
167   Arguments:    None.
168 
169   Returns:      void*:   Returns the storage address of the sampling result.
170                         Returns NULL if nothing has been sampled yet.
171  *---------------------------------------------------------------------------*/
172 void   *MIC_GetLastSamplingAddress(void);
173 
174 /*---------------------------------------------------------------------------*
175   Name:         MIC_DoSampling
176 
177   Description:  Samples the microphone once.
178 
179   Arguments:    type:      - Specifies the sampling type.
180                 buf:       - Specifies the buffer that stores the sampling data.
181 
182   Returns:      MICResult:    - Returns the result of the device operation process.
183  *---------------------------------------------------------------------------*/
184 MICResult MIC_DoSampling(MICSamplingType type, void *buf);
185 
186 /*---------------------------------------------------------------------------*
187   Name:         MIC_StartAutoSampling
188 
189   Description:  Starts auto-sampling with the microphone.
190 
191   Arguments:    param:     - Pointer to a structure that specifies auto-sampling settings
192 
193   Returns:      MICResult:    - Returns the result of the device operation process.
194  *---------------------------------------------------------------------------*/
195 MICResult MIC_StartAutoSampling(const MICAutoParam *param);
196 
197 /*---------------------------------------------------------------------------*
198   Name:         MIC_StopAutoSampling
199 
200   Description:  Stops auto-sampling with the microphone.
201                 If a loop was not specified at the start of auto-sampling, sampling will stop automatically when the buffer is full.
202 
203 
204   Arguments:    None.
205 
206   Returns:      MICResult:    - Returns the result of the device operation process.
207  *---------------------------------------------------------------------------*/
208 MICResult MIC_StopAutoSampling(void);
209 
210 /*---------------------------------------------------------------------------*
211   Name:         MIC_AdjustAutoSampling
212 
213   Description:  Adjusts the microphone auto-sampling rate.
214 
215   Arguments:    rate:       - Specifies the sampling rate.
216 
217   Returns:      MICResult:    - Returns the result of the device operation process.
218  *---------------------------------------------------------------------------*/
219 MICResult MIC_AdjustAutoSampling(u32 rate);
220 
221 #ifdef  SDK_TWL
222 /*---------------------------------------------------------------------------*
223   Name:         MIC_StartLimitedSamplingAsync
224 
225   Description:  Asynchronously starts rate-limited microphone auto-sampling.
226                 Although sampling at accurate frequencies with a low CPU load is possible because it is done in hardware, this is limited to sampling rates supported by the hardware.
227                 This is an asynchronous function, so the actual processing result will be passed when the callback is invoked.
228                 When called on a NITRO system, this will be replaced by an existing function that uses the CPU to start auto-sampling.
229 
230 
231 
232 
233   Arguments:    param:     - Pointer to a structure that specifies auto-sampling settings.
234                 callback     - Specifies the function to be called when the asynchronous process is completed.
235                 arg       - Specifies the argument used when calling the callback function.
236 
237   Returns:      MICResult:    - Returns the result of starting the asynchronous device operation.
238  *---------------------------------------------------------------------------*/
239 MICResult   MIC_StartLimitedSamplingAsync(const MICAutoParam* param, MICCallback callback, void* arg);
240 
241 /*---------------------------------------------------------------------------*
242   Name:         MIC_StopLimitedSamplingAsync
243 
244   Description:  Asynchronously stops rate-limited microphone auto-sampling.
245                 This is an asynchronous function, so the actual processing result will be passed when the callback is invoked.
246                 When called on a NITRO system, this will be replaced by an existing function that uses the CPU to stop auto-sampling.
247 
248 
249 
250   Arguments:    callback     - Specifies the function to be called when the asynchronous process is completed.
251                 arg       - Specifies the argument used when calling the callback function.
252 
253   Returns:      MICResult:    - Returns the result of starting the asynchronous device operation.
254  *---------------------------------------------------------------------------*/
255 MICResult   MIC_StopLimitedSamplingAsync(MICCallback callback, void* arg);
256 
257 /*---------------------------------------------------------------------------*
258   Name:         MIC_AdjustLimitedSamplingAsync
259 
260   Description:  Asynchronously adjusts the rate for rate-limited microphone auto-sampling.
261                 This is an asynchronous function, so the actual processing result will be passed when the callback is invoked.
262                 When called on a NITRO system, this will be replaced by an existing function that uses the CPU to adjust the auto-sampling rate.
263 
264 
265 
266   Arguments:    rate     - Specifies the sampling interval in ARM7 CPU clock cycles
267                 callback     - Specifies the function to be called when the asynchronous process is completed.
268                 arg       - Specifies the argument used when calling the callback function.
269 
270   Returns:      MICResult:    - Returns the result of starting the asynchronous device operation.
271  *---------------------------------------------------------------------------*/
272 MICResult   MIC_AdjustLimitedSamplingAsync(u32 rate, MICCallback callback, void* arg);
273 
274 /*---------------------------------------------------------------------------*
275   Name:         MIC_StartLimitedSampling
276 
277   Description:  Starts rate-limited microphone auto-sampling.
278                 Although sampling at accurate frequencies with a low CPU load is possible because it is done in hardware, this is limited to sampling rates supported by the hardware.
279                 This is a synchronous function, so calls to it from interrupt handlers are prohibited.
280                 When called on a NITRO system, this will be replaced by an existing function that uses the CPU to start auto-sampling.
281 
282 
283 
284 
285   Arguments:    param:     - Pointer to a structure that specifies auto-sampling settings.
286 
287   Returns:      MICResult:    - Returns the result of the device operation process.
288  *---------------------------------------------------------------------------*/
289 MICResult   MIC_StartLimitedSampling(const MICAutoParam* param);
290 
291 /*---------------------------------------------------------------------------*
292   Name:         MIC_StopLimitedSampling
293 
294   Description:  Stops rate-limited microphone auto-sampling.
295                 This is a synchronous function, so calls to it from interrupt handlers are prohibited.
296                 When called on a NITRO system, this will be replaced by an existing function that uses the CPU to stop auto-sampling.
297 
298 
299   Arguments:    None.
300 
301   Returns:      MICResult:    - Returns the result of the device operation process.
302  *---------------------------------------------------------------------------*/
303 MICResult   MIC_StopLimitedSampling(void);
304 
305 /*---------------------------------------------------------------------------*
306   Name:         MIC_AdjustLimitedSampling
307 
308   Description:  Adjusts the rate for rate-limited microphone auto-sampling.
309                 This is a synchronous function, so calls to it from interrupt handlers are prohibited.
310                 When called on a NITRO system, this will be replaced by an existing function that uses the CPU to adjust the auto-sampling rate.
311 
312 
313 
314   Arguments:    rate     - Specifies the sampling interval in ARM7 CPU clock cycles
315 
316   Returns:      MICResult:    - Returns the result of the device operation process.
317  *---------------------------------------------------------------------------*/
318 MICResult   MIC_AdjustLimitedSampling(u32 rate);
319 
320 #endif
321 
322 /*===========================================================================*/
323 
324 #ifdef  __cplusplus
325 }       /* extern "C" */
326 #endif
327 
328 #endif /* NITRO_RTC_ARM9_API_H_ */
329 
330 /*---------------------------------------------------------------------------*
331   End of file
332  *---------------------------------------------------------------------------*/
333