|
1 // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of the License "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // e32\include\drivers\i2s.h |
|
15 // |
|
16 // WARNING: This file contains some APIs which are internal and are subject |
|
17 // to change without notice. Such APIs should therefore not be used |
|
18 // outside the Kernel and Hardware Services package. |
|
19 // |
|
20 |
|
21 #ifndef __I2S_H__ |
|
22 #define __I2S_H__ |
|
23 |
|
24 #include <e32cmn.h> |
|
25 #include <e32def.h> |
|
26 |
|
27 |
|
28 /** |
|
29 @publishedPartner |
|
30 @prototype |
|
31 |
|
32 The I2S interface configuration |
|
33 */ |
|
34 class TI2sConfigV01 |
|
35 { |
|
36 public: |
|
37 TInt iRole; |
|
38 TInt iType; |
|
39 }; |
|
40 |
|
41 typedef TPckgBuf<TI2sConfigV01> TI2sConfigBufV01; |
|
42 |
|
43 /** |
|
44 @publishedPartner |
|
45 @prototype |
|
46 |
|
47 The I2S public API |
|
48 */ |
|
49 class I2s |
|
50 { |
|
51 public: |
|
52 /** |
|
53 The role an interface plays in a bus configuration: |
|
54 - Master, |
|
55 - Slave |
|
56 */ |
|
57 enum TI2sInterfaceRole |
|
58 { |
|
59 EMaster, |
|
60 ESlave |
|
61 }; |
|
62 |
|
63 |
|
64 /** |
|
65 The type of device this interface is with respect to data flow: |
|
66 - transmitter, |
|
67 - receiver, |
|
68 - bidirectional (by virtue of bidirectional data pin or separate pins for data input/output) |
|
69 - controller (only involved in synchronising data flow) |
|
70 */ |
|
71 enum TI2sInterfaceType |
|
72 { |
|
73 ETransmitter, |
|
74 EReceiver, |
|
75 EBidirectional, |
|
76 EController |
|
77 }; |
|
78 |
|
79 |
|
80 /** |
|
81 I2S transfer directions: |
|
82 - receive, |
|
83 - transmit |
|
84 |
|
85 These values are bitmasks which can be OR-ed to make up a composite bitmask. |
|
86 */ |
|
87 enum TI2sDirection |
|
88 { |
|
89 ERx = 0x01, |
|
90 ETx = 0x02 |
|
91 }; |
|
92 |
|
93 /** |
|
94 I2S frame phase: |
|
95 - left, |
|
96 - right |
|
97 */ |
|
98 enum TI2sFramePhase |
|
99 { |
|
100 ELeft, |
|
101 ERight |
|
102 }; |
|
103 |
|
104 /** |
|
105 I2S sampling rates: |
|
106 */ |
|
107 enum TI2sSamplingRate |
|
108 { |
|
109 // sparse enumeration |
|
110 E7_35KHz = 100, |
|
111 E8KHz = 200, |
|
112 E8_82KHz = 300, |
|
113 E9_6KHz = 400, |
|
114 E11_025KHz = 500, |
|
115 E12KHz = 600, |
|
116 E14_7KHz = 700, |
|
117 E16KHz = 800, |
|
118 E22_05KHz = 900, |
|
119 E24KHz = 1000, |
|
120 E29_4KHz = 1100, |
|
121 E32KHz = 1200, |
|
122 E44_1KHz = 1300, |
|
123 E48KHz = 1400, |
|
124 E96KHz = 1500 |
|
125 }; |
|
126 |
|
127 /** |
|
128 I2S frame length: |
|
129 */ |
|
130 enum TI2sFrameLength |
|
131 { |
|
132 // sparse enumeration |
|
133 EFrame16Bit = 16, |
|
134 EFrame24Bit = 24, |
|
135 EFrame32Bit = 32, |
|
136 EFrame48Bit = 48, |
|
137 EFrame64Bit = 64, |
|
138 EFrame96Bit = 96, |
|
139 EFrame128Bit = 128 |
|
140 }; |
|
141 |
|
142 /** |
|
143 I2S Audio word length: |
|
144 */ |
|
145 enum TI2sSampleLength |
|
146 { |
|
147 // sparse enumeration |
|
148 ESample8Bit = 8, |
|
149 ESample12Bit = 12, |
|
150 ESample16Bit = 16, |
|
151 ESample24Bit = 24, |
|
152 ESample32Bit = 32 |
|
153 }; |
|
154 |
|
155 /** |
|
156 I2S access mode flags: |
|
157 - Rx full (register or FIFO, depending on access mode, for left or right frame phase) |
|
158 - Tx empty (register or FIFO, depennding on access mode, for left or right frame phase) |
|
159 - Rx overrun (register or FIFO, depending on access mode, for left or right frame phase) |
|
160 - Tx underrun (register or FIFO, depending on access mode, for left or right frame phase) |
|
161 - Rx/Tx framing error |
|
162 |
|
163 These values are bitmasks which can be OR-ed to make up a composite bitmask. |
|
164 */ |
|
165 enum TI2sFlags |
|
166 { |
|
167 ERxFull = 0x01, |
|
168 ETxEmpty = 0x02, |
|
169 ERxOverrun = 0x04, |
|
170 ETxUnderrun = 0x08, |
|
171 EFramingError = 0x10 |
|
172 }; |
|
173 |
|
174 /** |
|
175 Configures the interface. |
|
176 |
|
177 @param aInterfaceId The interface Id. |
|
178 @param aConfig A pointer to the configuration as one of TI2sConfigBufV01 or greater. |
|
179 |
|
180 @return KErrNone, if successful; |
|
181 KErrArgument, if aInterfaceId is invalid or aConfig is NULL; |
|
182 KErrNotSupported, if the configuration is not supported by this interface; |
|
183 KErrInUse, if interface is not quiescient (a transfer is under way). |
|
184 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
185 */ |
|
186 IMPORT_C static TInt ConfigureInterface(TInt aInterfaceId, TDes8* aConfig); |
|
187 |
|
188 /** |
|
189 Reads the current configuration. |
|
190 |
|
191 @param aInterfaceId The interface Id. |
|
192 @param aConfig On return, the buffer passed is filled with the current configuration. |
|
193 |
|
194 @return KErrNone, if successful; |
|
195 KErrArgument, if aInterfaceId is invalid. |
|
196 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
197 */ |
|
198 IMPORT_C static TInt GetInterfaceConfiguration(TInt aInterfaceId, TDes8& aConfig); |
|
199 |
|
200 /** |
|
201 Sets the sampling rate. |
|
202 |
|
203 @param aInterfaceId The interface Id. |
|
204 @param aSamplingRate One of TI2sSamplingRate. |
|
205 |
|
206 @return KErrNone, if successful; |
|
207 KErrArgument, if aInterfaceId is invalid; |
|
208 KErrNotSupported, if the sampling rate is not supported by this interface; |
|
209 KErrInUse, if interface is not quiescient (a transfer is under way). |
|
210 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
211 */ |
|
212 IMPORT_C static TInt SetSamplingRate(TInt aInterfaceId, TI2sSamplingRate aSamplingRate); |
|
213 |
|
214 /** |
|
215 Reads the sampling rate. |
|
216 |
|
217 @param aInterfaceId The interface Id. |
|
218 @param aSamplingRate On return, contains one of TI2sSamplingRate. |
|
219 |
|
220 @return KErrNone, if successful; |
|
221 KErrArgument, if aInterfaceId is invalid. |
|
222 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
223 */ |
|
224 IMPORT_C static TInt GetSamplingRate(TInt aInterfaceId, TInt& aSamplingRate); |
|
225 |
|
226 |
|
227 /** |
|
228 Sets the frame length and format. |
|
229 |
|
230 @param aInterfaceId The interface Id. |
|
231 @param aFrameLength One of TI2sFrameLength. |
|
232 @param aLeftFramePhaseLength The length of the left frame phase (in number of data bits). |
|
233 |
|
234 @return KErrNone, if successful; |
|
235 KErrArgument, if aInterfaceId is invalid; |
|
236 KErrNotSupported, if the frame length or format are not supported by this interface; |
|
237 KErrInUse, if interface is not quiescient (a transfer is under way). |
|
238 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
239 |
|
240 The implementation calculates the Right frame phase length as (FrameLength - LeftFramePhaseLength) |
|
241 */ |
|
242 IMPORT_C static TInt SetFrameLengthAndFormat(TInt aInterfaceId, TI2sFrameLength aFrameLength, TInt aLeftFramePhaseLength); |
|
243 |
|
244 /** |
|
245 Reads the frame format. |
|
246 |
|
247 @param aInterfaceId The interface Id. |
|
248 @param aLeftFramePhaseLength On return, contains the length of the left frame phase. |
|
249 @param aRightFramePhaseLength On return, contains the length of the right frame phase. |
|
250 |
|
251 @return KErrNone, if successful; |
|
252 KErrArgument, if aInterfaceId is invalid. |
|
253 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
254 */ |
|
255 IMPORT_C static TInt GetFrameFormat(TInt aInterfaceId, TInt& aLeftFramePhaseLength, TInt& aRightFramePhaseLength); |
|
256 |
|
257 /** |
|
258 Sets the sample length for a frame phase (left or right). |
|
259 |
|
260 @param aInterfaceId The interface Id. |
|
261 @param aFramePhase One of TI2sFramePhase. |
|
262 @param aSampleLength One of TI2sSampleLength. |
|
263 |
|
264 @return KErrNone, if successful; |
|
265 KErrArgument, if aInterfaceId is invalid; |
|
266 KErrNotSupported, if the sample length for the frame phase selected is not supported by this interface; |
|
267 KErrInUse, if interface is not quiescient (a transfer is under way). |
|
268 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
269 */ |
|
270 IMPORT_C static TInt SetSampleLength(TInt aInterfaceId, TI2sFramePhase aFramePhase, TI2sSampleLength aSampleLength); |
|
271 |
|
272 /** |
|
273 Reads the sample length for a frame phase (left or right). |
|
274 |
|
275 @param aInterfaceId The interface Id. |
|
276 @param aFramePhase One of TI2sFramePhase. |
|
277 @param aSampleLength On return, contains the sample length for the frame phase indicated by aFramePhase. |
|
278 |
|
279 @return KErrNone, if successful; |
|
280 KErrArgument, if aInterfaceId is invalid. |
|
281 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
282 */ |
|
283 IMPORT_C static TInt GetSampleLength(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aSampleLength); |
|
284 |
|
285 /** |
|
286 Sets the number of delay cycles for a frame phase (left or right). |
|
287 |
|
288 @param aInterfaceId The interface Id. |
|
289 @param aFramePhase One of TI2sFramePhase. |
|
290 @param aDelayCycles The number of delay cycles to be introduced for the frame phase indicated by aFramePhase. |
|
291 |
|
292 @return KErrNone, if successful; |
|
293 KErrArgument, if aInterfaceId is invalid; |
|
294 KErrNotSupported, if the number of delay cycles for the frame phase selected is not supported by this interface; |
|
295 KErrInUse, if interface is not quiescient (a transfer is under way). |
|
296 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
297 |
|
298 Each delay cycle has a duration of a bit clock cycle. Delay cycles are inserted between the start of the frame and the start of data. |
|
299 */ |
|
300 IMPORT_C static TInt SetDelayCycles(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aDelayCycles); |
|
301 |
|
302 /** |
|
303 Reads the number of delay cycles for a frame phase (left or right). |
|
304 |
|
305 @param aInterfaceId The interface Id. |
|
306 @param aFramePhase One of TI2sFramePhase. |
|
307 @param aDelayCycles On return, contains the number of delay cycles for the frame phase indicated by aFramePhase. |
|
308 |
|
309 @return KErrNone, if successful; |
|
310 KErrArgument, if aInterfaceId is invalid. |
|
311 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
312 */ |
|
313 IMPORT_C static TInt GetDelayCycles(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aDelayCycles); |
|
314 |
|
315 /** |
|
316 Reads the receive data register for a frame phase. |
|
317 |
|
318 @param aInterfaceId The interface Id. |
|
319 @param aFramePhase One of TI2sFramePhase. |
|
320 @param aData On return, contains the receive data register contents. |
|
321 |
|
322 @return KErrNone, if successful; |
|
323 KErrArgument, if aInterfaceId is invalid; |
|
324 KErrNotSupported, if reading the receive data register is not supported (e.g. when if DMA is enabled); |
|
325 KErrNotReady, if the interface is not ready. |
|
326 @pre Can be called in any context. |
|
327 |
|
328 If the implementation has a combined receive/transmit register - half duplex operation only - this API is used to read from it. |
|
329 If the implementation only supports a single receive register for both frame phases, the aFramePhase argument shall be ignored and the |
|
330 API shall return the contents of the single register. The user of the API shall use the ReadRegisterModeStatus()/ReadFIFOModeStatus() |
|
331 API to determine which frame phase the data corresponds to. |
|
332 */ |
|
333 IMPORT_C static TInt ReadReceiveRegister(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aData); |
|
334 |
|
335 /** |
|
336 Writes to the transmit data register for a frame phase. |
|
337 |
|
338 @param aInterfaceId The interface Id. |
|
339 @param aFramePhase One of TI2sFramePhase. |
|
340 @param aData The data to be written. |
|
341 |
|
342 @return KErrNone, if successful; |
|
343 KErrArgument, if aInterfaceId is invalid; |
|
344 KErrNotSupported, if writing to the receive data register is not supported (e.g. when if DMA is enabled); |
|
345 KErrNotReady, if the interface is not ready. |
|
346 @pre Can be called in any context. |
|
347 |
|
348 If the implementation has a combined receive/transmit register - half duplex operation only - this API is used to write to it. |
|
349 If the implementation only supports a single transmit register for both frame phases, the aFramePhase argument shall be ignored and the |
|
350 API shall write to the single register. The user of the API shall use the ReadRegisterModeStatus()/ReadFIFOModeStatus() API to determine |
|
351 under which frame phase the data corresponds will be transmitted. |
|
352 */ |
|
353 IMPORT_C static TInt WriteTransmitRegister(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aData); |
|
354 |
|
355 /** |
|
356 Reads the transmit data register for a frame phase. |
|
357 |
|
358 @param aInterfaceId The interface Id. |
|
359 @param aFramePhase One of TI2sFramePhase. |
|
360 @param aData On return, contains the transmit data register contents. |
|
361 |
|
362 @return KErrNone, if successful; |
|
363 KErrArgument, if aInterfaceId is invalid; |
|
364 KErrNotSupported, if reading the transmit data register is not supported; |
|
365 KErrNotReady, if the interface is not ready. |
|
366 @pre Can be called in any context. |
|
367 |
|
368 If the implementation has a combined receive/transmit register this API is used to read from it (equivalent to ReadReceiveRegister()). |
|
369 If the implementation only supports a single transmit register for both frame phases, the aFramePhase argument shall be ignored and the |
|
370 API shall return the contents of the single register. The user of the API shall use the ReadRegisterModeStatus()/ReadFIFOModeStatus() |
|
371 API to determine which frame phase the data corresponds to. |
|
372 */ |
|
373 IMPORT_C static TInt ReadTransmitRegister(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aData); |
|
374 |
|
375 /** |
|
376 Reads the Register PIO access mode status flags for a frame phase. |
|
377 |
|
378 @param aInterfaceId The interface Id. |
|
379 @param aFramePhase One of TI2sFramePhase. |
|
380 @param aFlags On return, contains a bitmask with the status flags for the frame phase selected (see TI2SFlags). |
|
381 A bit set to "1" indicates the condition described by the corresponding flag is occurring. |
|
382 |
|
383 @return KErrNone, if successful; |
|
384 KErrArgument, if aInterfaceId is invalid; |
|
385 KErrNotSupported, if reading the status flags for Register PIO mode is not supported by this implementation. |
|
386 @pre Can be called in any context. |
|
387 |
|
388 The client driver may use one of IS_I2S_<CONDITION> macros to determine the status of individual conditions. |
|
389 */ |
|
390 IMPORT_C static TInt ReadRegisterModeStatus(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aFlags); |
|
391 |
|
392 /** |
|
393 Enables Register PIO access mode related interrupts for a frame phase. |
|
394 |
|
395 @param aInterfaceId The interface Id. |
|
396 @param aFramePhase One of TI2sFramePhase. |
|
397 @param aInterrupt A bitmask containing the relevant interrupt flags (see TI2sFlags). |
|
398 Bits set to "1" enable the corresponding interrupts. |
|
399 |
|
400 @return KErrNone, if successful; |
|
401 KErrArgument, if aInterfaceId is invalid; |
|
402 KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation. |
|
403 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
404 |
|
405 If the implementation only supports single transmit and receive registers for both frame phases, the aFramePhase argument is |
|
406 ignored. |
|
407 */ |
|
408 IMPORT_C static TInt EnableRegisterInterrupts(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aInterrupt); |
|
409 |
|
410 /** |
|
411 Disables Register PIO access mode related interrupts for a frame phase. |
|
412 |
|
413 @param aInterfaceId The interface Id. |
|
414 @param aFramePhase One of TI2sFramePhase. |
|
415 @param aInterrupt A bitmask containing the relevant interrupt flags (see TI2sFlags). |
|
416 Bits set to "1" disable the corresponding interrupts. |
|
417 |
|
418 @return KErrNone, if successful; |
|
419 KErrArgument, if aInterfaceId is invalid; |
|
420 KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation. |
|
421 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
422 |
|
423 If the implementation only supports single transmit and receive registers for both frame phases, the aFramePhase argument is |
|
424 ignored. |
|
425 */ |
|
426 IMPORT_C static TInt DisableRegisterInterrupts(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aInterrupt); |
|
427 |
|
428 /** |
|
429 Reads the Register PIO access mode interrupt mask for a frame phase. |
|
430 |
|
431 @param aInterfaceId The interface Id. |
|
432 @param aFramePhase One of TI2sFramePhase. |
|
433 @param aEnabled On return, contains a bitmask with the interrupts which are enabled for the frame phase selected (see TI2SFlags). |
|
434 A bit set to "1" indicates the corresponding interrupt is enabled. |
|
435 |
|
436 @return KErrNone, if successful; |
|
437 KErrArgument, if aInterfaceId is invalid; |
|
438 KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation. |
|
439 @pre Can be called in any context. |
|
440 |
|
441 If the implementation only supports single transmit and receive registers for both frame phases, the aFramePhase argument is |
|
442 ignored. |
|
443 */ |
|
444 IMPORT_C static TInt IsRegisterInterruptEnabled(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aEnabled); |
|
445 |
|
446 /** |
|
447 Enables receive and/or transmit FIFO on a per frame phase basis. |
|
448 |
|
449 @param aInterfaceId The interface Id. |
|
450 @param aFramePhase One of TI2sFramePhase. |
|
451 @param aFifoMask A bitmask specifying which FIFO direction(s) - receive and/or transmit - are to be enabled for the frame |
|
452 phase selected (see TI2sDirection). |
|
453 Bits set to "1" enable the corresponding FIFO. |
|
454 |
|
455 @return KErrNone, if successful; |
|
456 KErrArgument, if aInterfaceId is invalid; |
|
457 KErrNotSupported, if the implementation does no support FIFOs. |
|
458 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
459 |
|
460 If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFifoMask is ignored. |
|
461 If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored. |
|
462 */ |
|
463 IMPORT_C static TInt EnableFIFO(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aFifoMask); |
|
464 |
|
465 /** |
|
466 Disables receive and/or transmit FIFO on a per frame phase basis. |
|
467 |
|
468 @param aInterfaceId The interface Id. |
|
469 @param aFramePhase One of TI2sFramePhase. |
|
470 @param aFifoMask A bitmask specifying which FIFO direction(s) - receive and/or transmit - are to be disabled for the frame |
|
471 phase selected (see TI2sDirection). |
|
472 Bits set to "1" disable the corresponding FIFO. |
|
473 |
|
474 @return KErrNone, if successful; |
|
475 KErrArgument, if aInterfaceId is invalid; |
|
476 KErrNotSupported, if the implementation does no support FIFOs. |
|
477 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
478 |
|
479 If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFifoMask is ignored. |
|
480 If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored. |
|
481 */ |
|
482 IMPORT_C static TInt DisableFIFO(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aFifoMask); |
|
483 |
|
484 /** |
|
485 Reads the enabled state of a frame phase's FIFOs. |
|
486 |
|
487 @param aInterfaceId The interface Id. |
|
488 @param aFramePhase One of TI2sFramePhase. |
|
489 @param aEnabled On return, contains a bitmask indicating which FIFOs which are enabled for the frame phase selected (see TI2sDirection). |
|
490 A bit set to "1" indicates the corresponding FIFO is enabled. |
|
491 |
|
492 @return KErrNone, if successful; |
|
493 KErrArgument, if aInterfaceId is invalid; |
|
494 KErrNotSupported, if the implementation does no support FIFOs. |
|
495 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
496 |
|
497 If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aEnabled will have |
|
498 both Rx and Tx bits set when the FIFO is enabled. |
|
499 If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored. |
|
500 */ |
|
501 IMPORT_C static TInt IsFIFOEnabled(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aEnabled); |
|
502 |
|
503 /** |
|
504 Sets the receive or transmit FIFO threshold on a per frame phase basis. |
|
505 |
|
506 @param aInterfaceId The interface Id. |
|
507 @param aFramePhase One of TI2sFramePhase. |
|
508 @param aDirection One of TDirection. |
|
509 @param aThreshold A threshold level at which a receive FIFO is considered full or a transmit FIFO is considered empty. |
|
510 |
|
511 @return KErrNone, if successful; |
|
512 KErrArgument, if aInterfaceId is invalid; |
|
513 KErrNotSupported, if the implementation does no support FIFOs; |
|
514 KErrOverflow if the threshold level requested exceeds the FIFO length (or the admissible highest level allowed); |
|
515 KErrUnderflow if the threshold level requested is less than the minimum threshold allowed. |
|
516 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
517 |
|
518 If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aDirection is ignored. |
|
519 If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored. |
|
520 */ |
|
521 IMPORT_C static TInt SetFIFOThreshold(TInt aInterfaceId, TI2sFramePhase aFramePhase, TI2sDirection aDirection, TInt aThreshold); |
|
522 |
|
523 /** |
|
524 Reads the FIFO PIO access mode status flags for a frame phase. |
|
525 |
|
526 @param aInterfaceId The interface Id. |
|
527 @param aFramePhase One of TI2sFramePhase. |
|
528 @param aFlags On return, contains a bitmask with the status flags for the frame phase selected (see TI2sFlags). |
|
529 A bit set to "1" indicates the condition described by the corresponding flag is occurring. |
|
530 |
|
531 @return KErrNone, if successful; |
|
532 KErrArgument, if aInterfaceId is invalid; |
|
533 KErrNotSupported, if reading the status flags for FIFO PIO mode is not supported by this implementation. |
|
534 KErrInUse, if interface is not quiescient (a transfer is under way). |
|
535 @pre Can be called in any context. |
|
536 |
|
537 The client driver may use one of IS_I2S_<CONDITION> macros to determine the status of individual conditions. |
|
538 If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFlags will be set according |
|
539 to which operation (receive/transmit) is undergoing. |
|
540 If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored. |
|
541 */ |
|
542 IMPORT_C static TInt ReadFIFOModeStatus(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aFlags); |
|
543 |
|
544 /** |
|
545 Enables FIFO related interrupts for a frame phase. |
|
546 |
|
547 @param aInterfaceId The interface Id. |
|
548 @param aFramePhase One of TI2sFramePhase. |
|
549 @param aInterrupt A bitmask containing the relevant interrupt flags (see TI2sFlags). |
|
550 Bits set to "1" enable the corresponding interrupts. |
|
551 |
|
552 @return KErrNone, if successful; |
|
553 KErrArgument, if aInterfaceId is invalid; |
|
554 KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation. |
|
555 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
556 |
|
557 If the implementation only supports single transmit and receive FIFO for both frame phases, the aFramePhase argument is |
|
558 ignored. |
|
559 */ |
|
560 IMPORT_C static TInt EnableFIFOInterrupts(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aInterrupt); |
|
561 |
|
562 /** |
|
563 Disables FIFO related interrupts for a frame phase. |
|
564 |
|
565 @param aInterfaceId The interface Id. |
|
566 @param aFramePhase One of TI2sFramePhase. |
|
567 @param aInterrupt A bitmask containing the relevant interrupt flags (see TI2sFlags). |
|
568 Bits set to "1" disable the corresponding interrupts. |
|
569 |
|
570 @return KErrNone, if successful; |
|
571 KErrArgument, if aInterfaceId is invalid; |
|
572 KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation. |
|
573 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
574 |
|
575 If the implementation only supports single transmit and receive FIFO for both frame phases, the aFramePhase argument is |
|
576 ignored. |
|
577 */ |
|
578 IMPORT_C static TInt DisableFIFOInterrupts(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aInterrupt); |
|
579 |
|
580 /** |
|
581 Reads the FIFO interrupt masks for a frame phase. |
|
582 |
|
583 @param aInterfaceId The interface Id. |
|
584 @param aFramePhase One of TI2sFramePhase. |
|
585 @param aEnabled On return, contains a bitmask with the interrupts which are enabled for the frame phase selected (see TI2sFlags). |
|
586 A bit set to "1" indicates the corresponding interrupt is enabled. |
|
587 |
|
588 @return KErrNone, if successful; |
|
589 KErrArgument, if aInterfaceId is invalid; |
|
590 KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation. |
|
591 @pre Can be called in any context. |
|
592 */ |
|
593 IMPORT_C static TInt IsFIFOInterruptEnabled(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aEnabled); |
|
594 |
|
595 /** |
|
596 Reads the receive or transmit FIFO current level on a per frame phase basis. |
|
597 |
|
598 @param aInterfaceId The interface Id. |
|
599 @param aFramePhase One of TI2sFramePhase. |
|
600 @param aDirection One of TDirection. |
|
601 @param aLevel On return, contains the current level for the FIFO described by the (aFramePhase,aDirection) pair. |
|
602 |
|
603 @return KErrNone, if successful; |
|
604 KErrArgument, if aInterfaceId is invalid; |
|
605 KErrNotSupported, if the implementation does no support FIFOs. |
|
606 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
607 |
|
608 If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aDirection is ignored. |
|
609 If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored. |
|
610 */ |
|
611 IMPORT_C static TInt ReadFIFOLevel(TInt aInterfaceId, TI2sFramePhase aFramePhase, TI2sDirection aDirection, TInt& aLevel); |
|
612 |
|
613 /** |
|
614 Enables receive and/or transmit DMA. |
|
615 |
|
616 @param aInterfaceId The interface Id. |
|
617 @param aFifoMask A bitmask specifying which directions - receive and/or transmit - is DMA to be enabled (see TI2sDirection). |
|
618 Bits set to "1" enable DMA. |
|
619 |
|
620 @return KErrNone, if successful; |
|
621 KErrArgument, if aInterfaceId is invalid; |
|
622 KErrNotSupported, if the implementation does no support DMA. |
|
623 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
624 |
|
625 If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFifoMask is ignored. |
|
626 */ |
|
627 IMPORT_C static TInt EnableDMA(TInt aInterfaceId, TInt aFifoMask); |
|
628 |
|
629 /** |
|
630 Disables receive and/or transmit DMA. |
|
631 |
|
632 @param aInterfaceId The interface Id. |
|
633 @param aFifoMask A bitmask specifying which directions - receive and/or transmit - is DMA to be disabled (see TI2sDirection). |
|
634 Bits set to "1" disable DMA. |
|
635 |
|
636 @return KErrNone, if successful; |
|
637 KErrArgument, if aInterfaceId is invalid; |
|
638 KErrNotSupported, if the implementation does no support DMA. |
|
639 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
640 |
|
641 If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFifoMask is ignored. |
|
642 */ |
|
643 IMPORT_C static TInt DisableDMA(TInt aInterfaceId, TInt aFifoMask); |
|
644 |
|
645 /** |
|
646 Reads the enabled state of DMA. |
|
647 |
|
648 @param aInterfaceId The interface Id. |
|
649 @param aEnabled On return, contains a bitmask indicating if DMA enabled for the corresponding directions (see TI2sDirection). |
|
650 A bit set to "1" indicates DMA is enabled for the corresponding direction. |
|
651 |
|
652 @return KErrNone, if successful; |
|
653 KErrArgument, if aInterfaceId is invalid; |
|
654 KErrNotSupported, if the implementation does no support FIFOs. |
|
655 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
656 |
|
657 If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aEnabled will have |
|
658 both Rx and Tx bits set when the DMA is enabled. |
|
659 */ |
|
660 IMPORT_C static TInt IsDMAEnabled(TInt aInterfaceId, TInt& aEnabled); |
|
661 |
|
662 /** |
|
663 Starts data transmission and/or data reception unless interface is a Controller; |
|
664 if device is also a Master, starts generation of data synchronisation signals. |
|
665 |
|
666 @param aInterfaceId The interface Id. |
|
667 @param aDirection A bitmask made of TI2sDirection values. The value is ignored if interface is a Controller. |
|
668 |
|
669 @return KErrNone, if successful; |
|
670 KErrArgument, if aInterfaceId is invalid or if aDirection is invalid (i.e. negative, 0 or greater than 3); |
|
671 KErrNotSupported, if one of the transfer directions selected is not supported on this interface; |
|
672 KErrInUse, if interface has a bidirectional data port and an access in the opposite direction is underway; |
|
673 KErrNotReady, if interface is not ready (e.g. incomplete configuration). |
|
674 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
675 |
|
676 Start() is idempotent, attempting to start an already started interface has no effect (returns KErrNone). |
|
677 */ |
|
678 IMPORT_C static TInt Start(TInt aInterfaceId, TInt aDirection); |
|
679 |
|
680 /** |
|
681 Stops data transmission and/or data reception; |
|
682 if device is also a Master, stops generation of data synchronisation signals. |
|
683 |
|
684 @param aInterfaceId The interface Id. |
|
685 @param aDirection A bitmask made of TI2sDirection values. |
|
686 |
|
687 @return KErrNone, if successful; |
|
688 KErrArgument, if aInterfaceId is invalid or if aDirection is invalid (i.e. negative, 0 or greater than 3); |
|
689 KErrNotSupported, if one of the transfer directions selected is not supported on this interface. |
|
690 @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1). |
|
691 |
|
692 Stop() is idempotent, attempting to stop an already started interface has no effect (returns KErrNone). |
|
693 */ |
|
694 IMPORT_C static TInt Stop(TInt aInterfaceId, TInt aDirection); |
|
695 |
|
696 /** |
|
697 Checks if a transmission or a reception is underway. |
|
698 |
|
699 @param aInterfaceId The interface Id. |
|
700 @param aDirection One of TI2sDirection. |
|
701 @param aStarted On return, contains ETrue if the the access is underway, EFalse otherwise. |
|
702 |
|
703 @return KErrNone, if successful; |
|
704 KErrArgument, if aInterfaceId is invalid or if aDirection is invalid (i.e. negative, 0 or greater than 3); |
|
705 KErrNotSupported, if one of the transfer directions selected is not supported on this interface. |
|
706 @pre Can be called in any context. |
|
707 |
|
708 If the interface is a Controller and a bus operation is underway, ETrue is returned regardless of aDirection. |
|
709 */ |
|
710 IMPORT_C static TInt IsStarted(TInt aInterfaceId, TI2sDirection aDirection, TBool& aStarted); |
|
711 }; |
|
712 |
|
713 #define IS_I2S_RX_FULL(status) (status&I2s::ERxFull) |
|
714 #define IS_I2S_TX_EMPTY(status) (status&I2s::ETxEmpty) |
|
715 #define IS_I2S_RX_OVERRUN(status) (status&I2s::ERxOverrun) |
|
716 #define IS_I2S_TX_UNDERRUN(status) (status&I2s::ETxUnderrun) |
|
717 #define IS_I2S_FRAMING_ERROR(status) (status&I2s::EFramingError) |
|
718 |
|
719 #endif /* __I2S_H__ */ |
|
720 |