1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/include/drivers/i2s.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,720 @@
1.4 +// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// e32\include\drivers\i2s.h
1.18 +//
1.19 +// WARNING: This file contains some APIs which are internal and are subject
1.20 +// to change without notice. Such APIs should therefore not be used
1.21 +// outside the Kernel and Hardware Services package.
1.22 +//
1.23 +
1.24 +#ifndef __I2S_H__
1.25 +#define __I2S_H__
1.26 +
1.27 +#include <e32cmn.h>
1.28 +#include <e32def.h>
1.29 +
1.30 +
1.31 +/**
1.32 +@publishedPartner
1.33 +@prototype
1.34 +
1.35 +The I2S interface configuration
1.36 +*/
1.37 +class TI2sConfigV01
1.38 + {
1.39 +public:
1.40 + TInt iRole;
1.41 + TInt iType;
1.42 + };
1.43 +
1.44 +typedef TPckgBuf<TI2sConfigV01> TI2sConfigBufV01;
1.45 +
1.46 +/**
1.47 +@publishedPartner
1.48 +@prototype
1.49 +
1.50 +The I2S public API
1.51 +*/
1.52 +class I2s
1.53 + {
1.54 +public:
1.55 + /**
1.56 + The role an interface plays in a bus configuration:
1.57 + - Master,
1.58 + - Slave
1.59 + */
1.60 + enum TI2sInterfaceRole
1.61 + {
1.62 + EMaster,
1.63 + ESlave
1.64 + };
1.65 +
1.66 +
1.67 + /**
1.68 + The type of device this interface is with respect to data flow:
1.69 + - transmitter,
1.70 + - receiver,
1.71 + - bidirectional (by virtue of bidirectional data pin or separate pins for data input/output)
1.72 + - controller (only involved in synchronising data flow)
1.73 + */
1.74 + enum TI2sInterfaceType
1.75 + {
1.76 + ETransmitter,
1.77 + EReceiver,
1.78 + EBidirectional,
1.79 + EController
1.80 + };
1.81 +
1.82 +
1.83 + /**
1.84 + I2S transfer directions:
1.85 + - receive,
1.86 + - transmit
1.87 +
1.88 + These values are bitmasks which can be OR-ed to make up a composite bitmask.
1.89 + */
1.90 + enum TI2sDirection
1.91 + {
1.92 + ERx = 0x01,
1.93 + ETx = 0x02
1.94 + };
1.95 +
1.96 + /**
1.97 + I2S frame phase:
1.98 + - left,
1.99 + - right
1.100 + */
1.101 + enum TI2sFramePhase
1.102 + {
1.103 + ELeft,
1.104 + ERight
1.105 + };
1.106 +
1.107 + /**
1.108 + I2S sampling rates:
1.109 + */
1.110 + enum TI2sSamplingRate
1.111 + {
1.112 + // sparse enumeration
1.113 + E7_35KHz = 100,
1.114 + E8KHz = 200,
1.115 + E8_82KHz = 300,
1.116 + E9_6KHz = 400,
1.117 + E11_025KHz = 500,
1.118 + E12KHz = 600,
1.119 + E14_7KHz = 700,
1.120 + E16KHz = 800,
1.121 + E22_05KHz = 900,
1.122 + E24KHz = 1000,
1.123 + E29_4KHz = 1100,
1.124 + E32KHz = 1200,
1.125 + E44_1KHz = 1300,
1.126 + E48KHz = 1400,
1.127 + E96KHz = 1500
1.128 + };
1.129 +
1.130 + /**
1.131 + I2S frame length:
1.132 + */
1.133 + enum TI2sFrameLength
1.134 + {
1.135 + // sparse enumeration
1.136 + EFrame16Bit = 16,
1.137 + EFrame24Bit = 24,
1.138 + EFrame32Bit = 32,
1.139 + EFrame48Bit = 48,
1.140 + EFrame64Bit = 64,
1.141 + EFrame96Bit = 96,
1.142 + EFrame128Bit = 128
1.143 + };
1.144 +
1.145 + /**
1.146 + I2S Audio word length:
1.147 + */
1.148 + enum TI2sSampleLength
1.149 + {
1.150 + // sparse enumeration
1.151 + ESample8Bit = 8,
1.152 + ESample12Bit = 12,
1.153 + ESample16Bit = 16,
1.154 + ESample24Bit = 24,
1.155 + ESample32Bit = 32
1.156 + };
1.157 +
1.158 + /**
1.159 + I2S access mode flags:
1.160 + - Rx full (register or FIFO, depending on access mode, for left or right frame phase)
1.161 + - Tx empty (register or FIFO, depennding on access mode, for left or right frame phase)
1.162 + - Rx overrun (register or FIFO, depending on access mode, for left or right frame phase)
1.163 + - Tx underrun (register or FIFO, depending on access mode, for left or right frame phase)
1.164 + - Rx/Tx framing error
1.165 +
1.166 + These values are bitmasks which can be OR-ed to make up a composite bitmask.
1.167 + */
1.168 + enum TI2sFlags
1.169 + {
1.170 + ERxFull = 0x01,
1.171 + ETxEmpty = 0x02,
1.172 + ERxOverrun = 0x04,
1.173 + ETxUnderrun = 0x08,
1.174 + EFramingError = 0x10
1.175 + };
1.176 +
1.177 + /**
1.178 + Configures the interface.
1.179 +
1.180 + @param aInterfaceId The interface Id.
1.181 + @param aConfig A pointer to the configuration as one of TI2sConfigBufV01 or greater.
1.182 +
1.183 + @return KErrNone, if successful;
1.184 + KErrArgument, if aInterfaceId is invalid or aConfig is NULL;
1.185 + KErrNotSupported, if the configuration is not supported by this interface;
1.186 + KErrInUse, if interface is not quiescient (a transfer is under way).
1.187 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.188 + */
1.189 + IMPORT_C static TInt ConfigureInterface(TInt aInterfaceId, TDes8* aConfig);
1.190 +
1.191 + /**
1.192 + Reads the current configuration.
1.193 +
1.194 + @param aInterfaceId The interface Id.
1.195 + @param aConfig On return, the buffer passed is filled with the current configuration.
1.196 +
1.197 + @return KErrNone, if successful;
1.198 + KErrArgument, if aInterfaceId is invalid.
1.199 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.200 + */
1.201 + IMPORT_C static TInt GetInterfaceConfiguration(TInt aInterfaceId, TDes8& aConfig);
1.202 +
1.203 + /**
1.204 + Sets the sampling rate.
1.205 +
1.206 + @param aInterfaceId The interface Id.
1.207 + @param aSamplingRate One of TI2sSamplingRate.
1.208 +
1.209 + @return KErrNone, if successful;
1.210 + KErrArgument, if aInterfaceId is invalid;
1.211 + KErrNotSupported, if the sampling rate is not supported by this interface;
1.212 + KErrInUse, if interface is not quiescient (a transfer is under way).
1.213 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.214 + */
1.215 + IMPORT_C static TInt SetSamplingRate(TInt aInterfaceId, TI2sSamplingRate aSamplingRate);
1.216 +
1.217 + /**
1.218 + Reads the sampling rate.
1.219 +
1.220 + @param aInterfaceId The interface Id.
1.221 + @param aSamplingRate On return, contains one of TI2sSamplingRate.
1.222 +
1.223 + @return KErrNone, if successful;
1.224 + KErrArgument, if aInterfaceId is invalid.
1.225 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.226 + */
1.227 + IMPORT_C static TInt GetSamplingRate(TInt aInterfaceId, TInt& aSamplingRate);
1.228 +
1.229 +
1.230 + /**
1.231 + Sets the frame length and format.
1.232 +
1.233 + @param aInterfaceId The interface Id.
1.234 + @param aFrameLength One of TI2sFrameLength.
1.235 + @param aLeftFramePhaseLength The length of the left frame phase (in number of data bits).
1.236 +
1.237 + @return KErrNone, if successful;
1.238 + KErrArgument, if aInterfaceId is invalid;
1.239 + KErrNotSupported, if the frame length or format are not supported by this interface;
1.240 + KErrInUse, if interface is not quiescient (a transfer is under way).
1.241 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.242 +
1.243 + The implementation calculates the Right frame phase length as (FrameLength - LeftFramePhaseLength)
1.244 + */
1.245 + IMPORT_C static TInt SetFrameLengthAndFormat(TInt aInterfaceId, TI2sFrameLength aFrameLength, TInt aLeftFramePhaseLength);
1.246 +
1.247 + /**
1.248 + Reads the frame format.
1.249 +
1.250 + @param aInterfaceId The interface Id.
1.251 + @param aLeftFramePhaseLength On return, contains the length of the left frame phase.
1.252 + @param aRightFramePhaseLength On return, contains the length of the right frame phase.
1.253 +
1.254 + @return KErrNone, if successful;
1.255 + KErrArgument, if aInterfaceId is invalid.
1.256 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.257 + */
1.258 + IMPORT_C static TInt GetFrameFormat(TInt aInterfaceId, TInt& aLeftFramePhaseLength, TInt& aRightFramePhaseLength);
1.259 +
1.260 + /**
1.261 + Sets the sample length for a frame phase (left or right).
1.262 +
1.263 + @param aInterfaceId The interface Id.
1.264 + @param aFramePhase One of TI2sFramePhase.
1.265 + @param aSampleLength One of TI2sSampleLength.
1.266 +
1.267 + @return KErrNone, if successful;
1.268 + KErrArgument, if aInterfaceId is invalid;
1.269 + KErrNotSupported, if the sample length for the frame phase selected is not supported by this interface;
1.270 + KErrInUse, if interface is not quiescient (a transfer is under way).
1.271 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.272 + */
1.273 + IMPORT_C static TInt SetSampleLength(TInt aInterfaceId, TI2sFramePhase aFramePhase, TI2sSampleLength aSampleLength);
1.274 +
1.275 + /**
1.276 + Reads the sample length for a frame phase (left or right).
1.277 +
1.278 + @param aInterfaceId The interface Id.
1.279 + @param aFramePhase One of TI2sFramePhase.
1.280 + @param aSampleLength On return, contains the sample length for the frame phase indicated by aFramePhase.
1.281 +
1.282 + @return KErrNone, if successful;
1.283 + KErrArgument, if aInterfaceId is invalid.
1.284 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.285 + */
1.286 + IMPORT_C static TInt GetSampleLength(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aSampleLength);
1.287 +
1.288 + /**
1.289 + Sets the number of delay cycles for a frame phase (left or right).
1.290 +
1.291 + @param aInterfaceId The interface Id.
1.292 + @param aFramePhase One of TI2sFramePhase.
1.293 + @param aDelayCycles The number of delay cycles to be introduced for the frame phase indicated by aFramePhase.
1.294 +
1.295 + @return KErrNone, if successful;
1.296 + KErrArgument, if aInterfaceId is invalid;
1.297 + KErrNotSupported, if the number of delay cycles for the frame phase selected is not supported by this interface;
1.298 + KErrInUse, if interface is not quiescient (a transfer is under way).
1.299 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.300 +
1.301 + 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.
1.302 + */
1.303 + IMPORT_C static TInt SetDelayCycles(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aDelayCycles);
1.304 +
1.305 + /**
1.306 + Reads the number of delay cycles for a frame phase (left or right).
1.307 +
1.308 + @param aInterfaceId The interface Id.
1.309 + @param aFramePhase One of TI2sFramePhase.
1.310 + @param aDelayCycles On return, contains the number of delay cycles for the frame phase indicated by aFramePhase.
1.311 +
1.312 + @return KErrNone, if successful;
1.313 + KErrArgument, if aInterfaceId is invalid.
1.314 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.315 + */
1.316 + IMPORT_C static TInt GetDelayCycles(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aDelayCycles);
1.317 +
1.318 + /**
1.319 + Reads the receive data register for a frame phase.
1.320 +
1.321 + @param aInterfaceId The interface Id.
1.322 + @param aFramePhase One of TI2sFramePhase.
1.323 + @param aData On return, contains the receive data register contents.
1.324 +
1.325 + @return KErrNone, if successful;
1.326 + KErrArgument, if aInterfaceId is invalid;
1.327 + KErrNotSupported, if reading the receive data register is not supported (e.g. when if DMA is enabled);
1.328 + KErrNotReady, if the interface is not ready.
1.329 + @pre Can be called in any context.
1.330 +
1.331 + If the implementation has a combined receive/transmit register - half duplex operation only - this API is used to read from it.
1.332 + If the implementation only supports a single receive register for both frame phases, the aFramePhase argument shall be ignored and the
1.333 + API shall return the contents of the single register. The user of the API shall use the ReadRegisterModeStatus()/ReadFIFOModeStatus()
1.334 + API to determine which frame phase the data corresponds to.
1.335 + */
1.336 + IMPORT_C static TInt ReadReceiveRegister(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aData);
1.337 +
1.338 + /**
1.339 + Writes to the transmit data register for a frame phase.
1.340 +
1.341 + @param aInterfaceId The interface Id.
1.342 + @param aFramePhase One of TI2sFramePhase.
1.343 + @param aData The data to be written.
1.344 +
1.345 + @return KErrNone, if successful;
1.346 + KErrArgument, if aInterfaceId is invalid;
1.347 + KErrNotSupported, if writing to the receive data register is not supported (e.g. when if DMA is enabled);
1.348 + KErrNotReady, if the interface is not ready.
1.349 + @pre Can be called in any context.
1.350 +
1.351 + If the implementation has a combined receive/transmit register - half duplex operation only - this API is used to write to it.
1.352 + If the implementation only supports a single transmit register for both frame phases, the aFramePhase argument shall be ignored and the
1.353 + API shall write to the single register. The user of the API shall use the ReadRegisterModeStatus()/ReadFIFOModeStatus() API to determine
1.354 + under which frame phase the data corresponds will be transmitted.
1.355 + */
1.356 + IMPORT_C static TInt WriteTransmitRegister(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aData);
1.357 +
1.358 + /**
1.359 + Reads the transmit data register for a frame phase.
1.360 +
1.361 + @param aInterfaceId The interface Id.
1.362 + @param aFramePhase One of TI2sFramePhase.
1.363 + @param aData On return, contains the transmit data register contents.
1.364 +
1.365 + @return KErrNone, if successful;
1.366 + KErrArgument, if aInterfaceId is invalid;
1.367 + KErrNotSupported, if reading the transmit data register is not supported;
1.368 + KErrNotReady, if the interface is not ready.
1.369 + @pre Can be called in any context.
1.370 +
1.371 + If the implementation has a combined receive/transmit register this API is used to read from it (equivalent to ReadReceiveRegister()).
1.372 + If the implementation only supports a single transmit register for both frame phases, the aFramePhase argument shall be ignored and the
1.373 + API shall return the contents of the single register. The user of the API shall use the ReadRegisterModeStatus()/ReadFIFOModeStatus()
1.374 + API to determine which frame phase the data corresponds to.
1.375 + */
1.376 + IMPORT_C static TInt ReadTransmitRegister(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aData);
1.377 +
1.378 + /**
1.379 + Reads the Register PIO access mode status flags for a frame phase.
1.380 +
1.381 + @param aInterfaceId The interface Id.
1.382 + @param aFramePhase One of TI2sFramePhase.
1.383 + @param aFlags On return, contains a bitmask with the status flags for the frame phase selected (see TI2SFlags).
1.384 + A bit set to "1" indicates the condition described by the corresponding flag is occurring.
1.385 +
1.386 + @return KErrNone, if successful;
1.387 + KErrArgument, if aInterfaceId is invalid;
1.388 + KErrNotSupported, if reading the status flags for Register PIO mode is not supported by this implementation.
1.389 + @pre Can be called in any context.
1.390 +
1.391 + The client driver may use one of IS_I2S_<CONDITION> macros to determine the status of individual conditions.
1.392 + */
1.393 + IMPORT_C static TInt ReadRegisterModeStatus(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aFlags);
1.394 +
1.395 + /**
1.396 + Enables Register PIO access mode related interrupts for a frame phase.
1.397 +
1.398 + @param aInterfaceId The interface Id.
1.399 + @param aFramePhase One of TI2sFramePhase.
1.400 + @param aInterrupt A bitmask containing the relevant interrupt flags (see TI2sFlags).
1.401 + Bits set to "1" enable the corresponding interrupts.
1.402 +
1.403 + @return KErrNone, if successful;
1.404 + KErrArgument, if aInterfaceId is invalid;
1.405 + KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation.
1.406 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.407 +
1.408 + If the implementation only supports single transmit and receive registers for both frame phases, the aFramePhase argument is
1.409 + ignored.
1.410 + */
1.411 + IMPORT_C static TInt EnableRegisterInterrupts(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aInterrupt);
1.412 +
1.413 + /**
1.414 + Disables Register PIO access mode related interrupts for a frame phase.
1.415 +
1.416 + @param aInterfaceId The interface Id.
1.417 + @param aFramePhase One of TI2sFramePhase.
1.418 + @param aInterrupt A bitmask containing the relevant interrupt flags (see TI2sFlags).
1.419 + Bits set to "1" disable the corresponding interrupts.
1.420 +
1.421 + @return KErrNone, if successful;
1.422 + KErrArgument, if aInterfaceId is invalid;
1.423 + KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation.
1.424 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.425 +
1.426 + If the implementation only supports single transmit and receive registers for both frame phases, the aFramePhase argument is
1.427 + ignored.
1.428 + */
1.429 + IMPORT_C static TInt DisableRegisterInterrupts(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aInterrupt);
1.430 +
1.431 + /**
1.432 + Reads the Register PIO access mode interrupt mask for a frame phase.
1.433 +
1.434 + @param aInterfaceId The interface Id.
1.435 + @param aFramePhase One of TI2sFramePhase.
1.436 + @param aEnabled On return, contains a bitmask with the interrupts which are enabled for the frame phase selected (see TI2SFlags).
1.437 + A bit set to "1" indicates the corresponding interrupt is enabled.
1.438 +
1.439 + @return KErrNone, if successful;
1.440 + KErrArgument, if aInterfaceId is invalid;
1.441 + KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation.
1.442 + @pre Can be called in any context.
1.443 +
1.444 + If the implementation only supports single transmit and receive registers for both frame phases, the aFramePhase argument is
1.445 + ignored.
1.446 + */
1.447 + IMPORT_C static TInt IsRegisterInterruptEnabled(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aEnabled);
1.448 +
1.449 + /**
1.450 + Enables receive and/or transmit FIFO on a per frame phase basis.
1.451 +
1.452 + @param aInterfaceId The interface Id.
1.453 + @param aFramePhase One of TI2sFramePhase.
1.454 + @param aFifoMask A bitmask specifying which FIFO direction(s) - receive and/or transmit - are to be enabled for the frame
1.455 + phase selected (see TI2sDirection).
1.456 + Bits set to "1" enable the corresponding FIFO.
1.457 +
1.458 + @return KErrNone, if successful;
1.459 + KErrArgument, if aInterfaceId is invalid;
1.460 + KErrNotSupported, if the implementation does no support FIFOs.
1.461 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.462 +
1.463 + If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFifoMask is ignored.
1.464 + If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored.
1.465 + */
1.466 + IMPORT_C static TInt EnableFIFO(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aFifoMask);
1.467 +
1.468 + /**
1.469 + Disables receive and/or transmit FIFO on a per frame phase basis.
1.470 +
1.471 + @param aInterfaceId The interface Id.
1.472 + @param aFramePhase One of TI2sFramePhase.
1.473 + @param aFifoMask A bitmask specifying which FIFO direction(s) - receive and/or transmit - are to be disabled for the frame
1.474 + phase selected (see TI2sDirection).
1.475 + Bits set to "1" disable the corresponding FIFO.
1.476 +
1.477 + @return KErrNone, if successful;
1.478 + KErrArgument, if aInterfaceId is invalid;
1.479 + KErrNotSupported, if the implementation does no support FIFOs.
1.480 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.481 +
1.482 + If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFifoMask is ignored.
1.483 + If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored.
1.484 + */
1.485 + IMPORT_C static TInt DisableFIFO(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aFifoMask);
1.486 +
1.487 + /**
1.488 + Reads the enabled state of a frame phase's FIFOs.
1.489 +
1.490 + @param aInterfaceId The interface Id.
1.491 + @param aFramePhase One of TI2sFramePhase.
1.492 + @param aEnabled On return, contains a bitmask indicating which FIFOs which are enabled for the frame phase selected (see TI2sDirection).
1.493 + A bit set to "1" indicates the corresponding FIFO is enabled.
1.494 +
1.495 + @return KErrNone, if successful;
1.496 + KErrArgument, if aInterfaceId is invalid;
1.497 + KErrNotSupported, if the implementation does no support FIFOs.
1.498 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.499 +
1.500 + If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aEnabled will have
1.501 + both Rx and Tx bits set when the FIFO is enabled.
1.502 + If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored.
1.503 + */
1.504 + IMPORT_C static TInt IsFIFOEnabled(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aEnabled);
1.505 +
1.506 + /**
1.507 + Sets the receive or transmit FIFO threshold on a per frame phase basis.
1.508 +
1.509 + @param aInterfaceId The interface Id.
1.510 + @param aFramePhase One of TI2sFramePhase.
1.511 + @param aDirection One of TDirection.
1.512 + @param aThreshold A threshold level at which a receive FIFO is considered full or a transmit FIFO is considered empty.
1.513 +
1.514 + @return KErrNone, if successful;
1.515 + KErrArgument, if aInterfaceId is invalid;
1.516 + KErrNotSupported, if the implementation does no support FIFOs;
1.517 + KErrOverflow if the threshold level requested exceeds the FIFO length (or the admissible highest level allowed);
1.518 + KErrUnderflow if the threshold level requested is less than the minimum threshold allowed.
1.519 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.520 +
1.521 + If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aDirection is ignored.
1.522 + If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored.
1.523 + */
1.524 + IMPORT_C static TInt SetFIFOThreshold(TInt aInterfaceId, TI2sFramePhase aFramePhase, TI2sDirection aDirection, TInt aThreshold);
1.525 +
1.526 + /**
1.527 + Reads the FIFO PIO access mode status flags for a frame phase.
1.528 +
1.529 + @param aInterfaceId The interface Id.
1.530 + @param aFramePhase One of TI2sFramePhase.
1.531 + @param aFlags On return, contains a bitmask with the status flags for the frame phase selected (see TI2sFlags).
1.532 + A bit set to "1" indicates the condition described by the corresponding flag is occurring.
1.533 +
1.534 + @return KErrNone, if successful;
1.535 + KErrArgument, if aInterfaceId is invalid;
1.536 + KErrNotSupported, if reading the status flags for FIFO PIO mode is not supported by this implementation.
1.537 + KErrInUse, if interface is not quiescient (a transfer is under way).
1.538 + @pre Can be called in any context.
1.539 +
1.540 + The client driver may use one of IS_I2S_<CONDITION> macros to determine the status of individual conditions.
1.541 + If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFlags will be set according
1.542 + to which operation (receive/transmit) is undergoing.
1.543 + If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored.
1.544 + */
1.545 + IMPORT_C static TInt ReadFIFOModeStatus(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aFlags);
1.546 +
1.547 + /**
1.548 + Enables FIFO related interrupts for a frame phase.
1.549 +
1.550 + @param aInterfaceId The interface Id.
1.551 + @param aFramePhase One of TI2sFramePhase.
1.552 + @param aInterrupt A bitmask containing the relevant interrupt flags (see TI2sFlags).
1.553 + Bits set to "1" enable the corresponding interrupts.
1.554 +
1.555 + @return KErrNone, if successful;
1.556 + KErrArgument, if aInterfaceId is invalid;
1.557 + KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation.
1.558 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.559 +
1.560 + If the implementation only supports single transmit and receive FIFO for both frame phases, the aFramePhase argument is
1.561 + ignored.
1.562 + */
1.563 + IMPORT_C static TInt EnableFIFOInterrupts(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aInterrupt);
1.564 +
1.565 + /**
1.566 + Disables FIFO related interrupts for a frame phase.
1.567 +
1.568 + @param aInterfaceId The interface Id.
1.569 + @param aFramePhase One of TI2sFramePhase.
1.570 + @param aInterrupt A bitmask containing the relevant interrupt flags (see TI2sFlags).
1.571 + Bits set to "1" disable the corresponding interrupts.
1.572 +
1.573 + @return KErrNone, if successful;
1.574 + KErrArgument, if aInterfaceId is invalid;
1.575 + KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation.
1.576 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.577 +
1.578 + If the implementation only supports single transmit and receive FIFO for both frame phases, the aFramePhase argument is
1.579 + ignored.
1.580 + */
1.581 + IMPORT_C static TInt DisableFIFOInterrupts(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aInterrupt);
1.582 +
1.583 + /**
1.584 + Reads the FIFO interrupt masks for a frame phase.
1.585 +
1.586 + @param aInterfaceId The interface Id.
1.587 + @param aFramePhase One of TI2sFramePhase.
1.588 + @param aEnabled On return, contains a bitmask with the interrupts which are enabled for the frame phase selected (see TI2sFlags).
1.589 + A bit set to "1" indicates the corresponding interrupt is enabled.
1.590 +
1.591 + @return KErrNone, if successful;
1.592 + KErrArgument, if aInterfaceId is invalid;
1.593 + KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation.
1.594 + @pre Can be called in any context.
1.595 + */
1.596 + IMPORT_C static TInt IsFIFOInterruptEnabled(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aEnabled);
1.597 +
1.598 + /**
1.599 + Reads the receive or transmit FIFO current level on a per frame phase basis.
1.600 +
1.601 + @param aInterfaceId The interface Id.
1.602 + @param aFramePhase One of TI2sFramePhase.
1.603 + @param aDirection One of TDirection.
1.604 + @param aLevel On return, contains the current level for the FIFO described by the (aFramePhase,aDirection) pair.
1.605 +
1.606 + @return KErrNone, if successful;
1.607 + KErrArgument, if aInterfaceId is invalid;
1.608 + KErrNotSupported, if the implementation does no support FIFOs.
1.609 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.610 +
1.611 + If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aDirection is ignored.
1.612 + If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored.
1.613 + */
1.614 + IMPORT_C static TInt ReadFIFOLevel(TInt aInterfaceId, TI2sFramePhase aFramePhase, TI2sDirection aDirection, TInt& aLevel);
1.615 +
1.616 + /**
1.617 + Enables receive and/or transmit DMA.
1.618 +
1.619 + @param aInterfaceId The interface Id.
1.620 + @param aFifoMask A bitmask specifying which directions - receive and/or transmit - is DMA to be enabled (see TI2sDirection).
1.621 + Bits set to "1" enable DMA.
1.622 +
1.623 + @return KErrNone, if successful;
1.624 + KErrArgument, if aInterfaceId is invalid;
1.625 + KErrNotSupported, if the implementation does no support DMA.
1.626 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.627 +
1.628 + If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFifoMask is ignored.
1.629 + */
1.630 + IMPORT_C static TInt EnableDMA(TInt aInterfaceId, TInt aFifoMask);
1.631 +
1.632 + /**
1.633 + Disables receive and/or transmit DMA.
1.634 +
1.635 + @param aInterfaceId The interface Id.
1.636 + @param aFifoMask A bitmask specifying which directions - receive and/or transmit - is DMA to be disabled (see TI2sDirection).
1.637 + Bits set to "1" disable DMA.
1.638 +
1.639 + @return KErrNone, if successful;
1.640 + KErrArgument, if aInterfaceId is invalid;
1.641 + KErrNotSupported, if the implementation does no support DMA.
1.642 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.643 +
1.644 + If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFifoMask is ignored.
1.645 + */
1.646 + IMPORT_C static TInt DisableDMA(TInt aInterfaceId, TInt aFifoMask);
1.647 +
1.648 + /**
1.649 + Reads the enabled state of DMA.
1.650 +
1.651 + @param aInterfaceId The interface Id.
1.652 + @param aEnabled On return, contains a bitmask indicating if DMA enabled for the corresponding directions (see TI2sDirection).
1.653 + A bit set to "1" indicates DMA is enabled for the corresponding direction.
1.654 +
1.655 + @return KErrNone, if successful;
1.656 + KErrArgument, if aInterfaceId is invalid;
1.657 + KErrNotSupported, if the implementation does no support FIFOs.
1.658 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.659 +
1.660 + If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aEnabled will have
1.661 + both Rx and Tx bits set when the DMA is enabled.
1.662 + */
1.663 + IMPORT_C static TInt IsDMAEnabled(TInt aInterfaceId, TInt& aEnabled);
1.664 +
1.665 + /**
1.666 + Starts data transmission and/or data reception unless interface is a Controller;
1.667 + if device is also a Master, starts generation of data synchronisation signals.
1.668 +
1.669 + @param aInterfaceId The interface Id.
1.670 + @param aDirection A bitmask made of TI2sDirection values. The value is ignored if interface is a Controller.
1.671 +
1.672 + @return KErrNone, if successful;
1.673 + KErrArgument, if aInterfaceId is invalid or if aDirection is invalid (i.e. negative, 0 or greater than 3);
1.674 + KErrNotSupported, if one of the transfer directions selected is not supported on this interface;
1.675 + KErrInUse, if interface has a bidirectional data port and an access in the opposite direction is underway;
1.676 + KErrNotReady, if interface is not ready (e.g. incomplete configuration).
1.677 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.678 +
1.679 + Start() is idempotent, attempting to start an already started interface has no effect (returns KErrNone).
1.680 + */
1.681 + IMPORT_C static TInt Start(TInt aInterfaceId, TInt aDirection);
1.682 +
1.683 + /**
1.684 + Stops data transmission and/or data reception;
1.685 + if device is also a Master, stops generation of data synchronisation signals.
1.686 +
1.687 + @param aInterfaceId The interface Id.
1.688 + @param aDirection A bitmask made of TI2sDirection values.
1.689 +
1.690 + @return KErrNone, if successful;
1.691 + KErrArgument, if aInterfaceId is invalid or if aDirection is invalid (i.e. negative, 0 or greater than 3);
1.692 + KErrNotSupported, if one of the transfer directions selected is not supported on this interface.
1.693 + @pre Call from thread context (neither NULL thread nor DFC threads 0 or 1).
1.694 +
1.695 + Stop() is idempotent, attempting to stop an already started interface has no effect (returns KErrNone).
1.696 + */
1.697 + IMPORT_C static TInt Stop(TInt aInterfaceId, TInt aDirection);
1.698 +
1.699 + /**
1.700 + Checks if a transmission or a reception is underway.
1.701 +
1.702 + @param aInterfaceId The interface Id.
1.703 + @param aDirection One of TI2sDirection.
1.704 + @param aStarted On return, contains ETrue if the the access is underway, EFalse otherwise.
1.705 +
1.706 + @return KErrNone, if successful;
1.707 + KErrArgument, if aInterfaceId is invalid or if aDirection is invalid (i.e. negative, 0 or greater than 3);
1.708 + KErrNotSupported, if one of the transfer directions selected is not supported on this interface.
1.709 + @pre Can be called in any context.
1.710 +
1.711 + If the interface is a Controller and a bus operation is underway, ETrue is returned regardless of aDirection.
1.712 + */
1.713 + IMPORT_C static TInt IsStarted(TInt aInterfaceId, TI2sDirection aDirection, TBool& aStarted);
1.714 + };
1.715 +
1.716 +#define IS_I2S_RX_FULL(status) (status&I2s::ERxFull)
1.717 +#define IS_I2S_TX_EMPTY(status) (status&I2s::ETxEmpty)
1.718 +#define IS_I2S_RX_OVERRUN(status) (status&I2s::ERxOverrun)
1.719 +#define IS_I2S_TX_UNDERRUN(status) (status&I2s::ETxUnderrun)
1.720 +#define IS_I2S_FRAMING_ERROR(status) (status&I2s::EFramingError)
1.721 +
1.722 +#endif /* __I2S_H__ */
1.723 +