sl@0: // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // e32\include\drivers\i2s.h
sl@0: // 
sl@0: // WARNING: This file contains some APIs which are internal and are subject
sl@0: //          to change without notice. Such APIs should therefore not be used
sl@0: //          outside the Kernel and Hardware Services package.
sl@0: //
sl@0: 
sl@0: #ifndef __I2S_H__
sl@0: #define __I2S_H__
sl@0: 
sl@0: #include <e32cmn.h> 
sl@0: #include <e32def.h> 
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype
sl@0: 
sl@0: The I2S interface configuration
sl@0: */
sl@0: class TI2sConfigV01
sl@0: 	{
sl@0: public:
sl@0: 	TInt iRole;
sl@0: 	TInt iType;
sl@0: 	};
sl@0: 
sl@0: typedef  TPckgBuf<TI2sConfigV01> TI2sConfigBufV01;
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype
sl@0: 
sl@0: The I2S public API
sl@0: */
sl@0: class I2s
sl@0:    {
sl@0: public:
sl@0: 	/**
sl@0: 	The role an interface plays in a bus configuration:
sl@0: 	- Master,
sl@0: 	- Slave
sl@0: 	*/
sl@0: 	enum TI2sInterfaceRole
sl@0: 		{
sl@0: 		EMaster,
sl@0: 		ESlave
sl@0: 		};
sl@0: 
sl@0: 
sl@0: 	/**
sl@0: 	The type of device this interface is with respect to data flow:
sl@0: 	- transmitter,
sl@0: 	- receiver,
sl@0: 	- bidirectional (by virtue of bidirectional data pin or separate pins for data input/output)
sl@0: 	- controller (only involved in synchronising data flow)
sl@0: 	*/
sl@0: 	enum TI2sInterfaceType
sl@0: 		{
sl@0: 		ETransmitter,
sl@0: 		EReceiver,
sl@0: 		EBidirectional,
sl@0: 		EController
sl@0: 		};
sl@0: 
sl@0: 
sl@0: 	/**
sl@0: 	I2S transfer directions:
sl@0: 	- receive,
sl@0: 	- transmit
sl@0: 
sl@0: 	These values are bitmasks which can be OR-ed to make up a composite bitmask.
sl@0: 	*/
sl@0: 	enum TI2sDirection
sl@0: 		{
sl@0: 		ERx = 0x01,
sl@0: 		ETx = 0x02
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	I2S frame phase:
sl@0: 	- left,
sl@0: 	- right
sl@0: 	*/
sl@0: 	enum TI2sFramePhase
sl@0: 		{
sl@0: 		ELeft,
sl@0: 		ERight
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	I2S sampling rates:
sl@0: 	*/
sl@0: 	enum TI2sSamplingRate
sl@0: 		{
sl@0: 		// sparse enumeration
sl@0: 		E7_35KHz  = 100,
sl@0: 		E8KHz	  = 200,
sl@0: 		E8_82KHz  = 300,
sl@0: 		E9_6KHz	  = 400,
sl@0: 		E11_025KHz = 500,
sl@0: 		E12KHz	  = 600,
sl@0: 		E14_7KHz  = 700,
sl@0: 		E16KHz	  = 800,
sl@0: 		E22_05KHz = 900,
sl@0: 		E24KHz	  = 1000,
sl@0: 		E29_4KHz  = 1100,
sl@0: 		E32KHz	  = 1200,
sl@0: 		E44_1KHz  = 1300,
sl@0: 		E48KHz	  = 1400,
sl@0: 		E96KHz	  = 1500
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	I2S frame length:
sl@0: 	*/
sl@0: 	enum TI2sFrameLength
sl@0: 		{
sl@0: 		// sparse enumeration
sl@0: 		EFrame16Bit	= 16,
sl@0: 		EFrame24Bit	= 24,
sl@0: 		EFrame32Bit	= 32,
sl@0: 		EFrame48Bit	= 48,
sl@0: 		EFrame64Bit	= 64,
sl@0: 		EFrame96Bit	= 96,
sl@0: 		EFrame128Bit = 128
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	I2S Audio word length:
sl@0: 	*/
sl@0: 	enum TI2sSampleLength
sl@0: 		{
sl@0: 		// sparse enumeration
sl@0: 		ESample8Bit  = 8,
sl@0: 		ESample12Bit = 12,
sl@0: 		ESample16Bit = 16,
sl@0: 		ESample24Bit = 24,
sl@0: 		ESample32Bit = 32
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	I2S access mode flags:
sl@0: 	- Rx  full (register or FIFO, depending on access mode, for left or right frame phase)
sl@0: 	- Tx  empty (register or FIFO, depennding on access mode, for left or right frame phase)
sl@0: 	- Rx  overrun (register or FIFO, depending on access mode, for left or right frame phase)
sl@0: 	- Tx  underrun (register or FIFO, depending on access mode, for left or right frame phase)
sl@0: 	- Rx/Tx framing error
sl@0: 
sl@0: 	These values are bitmasks which can be OR-ed to make up a composite bitmask.
sl@0: 	*/
sl@0: 	enum TI2sFlags
sl@0: 		{
sl@0: 		ERxFull		  = 0x01,
sl@0: 		ETxEmpty	  = 0x02,
sl@0: 		ERxOverrun	  = 0x04,
sl@0: 		ETxUnderrun	  = 0x08,
sl@0: 		EFramingError = 0x10
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	Configures the interface.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aConfig		A pointer to the configuration as one of TI2sConfigBufV01 or greater.
sl@0: 
sl@0: 	@return				KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid or aConfig is NULL;
sl@0: 						KErrNotSupported, if the configuration is not supported by this interface;
sl@0: 						KErrInUse, if interface is not quiescient (a transfer is under way).
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 	*/
sl@0: 	IMPORT_C static TInt ConfigureInterface(TInt aInterfaceId, TDes8* aConfig);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the current configuration.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aConfig		On return, the buffer passed is filled with the current configuration.
sl@0: 
sl@0: 	@return				KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 	*/
sl@0: 	IMPORT_C static TInt GetInterfaceConfiguration(TInt aInterfaceId, TDes8& aConfig);
sl@0: 
sl@0: 	/**
sl@0: 	Sets the sampling rate.
sl@0: 
sl@0: 	@param aInterfaceId	 The interface Id.
sl@0: 	@param aSamplingRate One of TI2sSamplingRate.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if the sampling rate is not supported by this interface;
sl@0: 						KErrInUse, if interface is not quiescient (a transfer is under way).
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 	*/
sl@0: 	IMPORT_C static TInt SetSamplingRate(TInt aInterfaceId, TI2sSamplingRate aSamplingRate);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the sampling rate.
sl@0: 
sl@0: 	@param aInterfaceId	 The interface Id.
sl@0: 	@param aSamplingRate On return, contains one of TI2sSamplingRate.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 	*/
sl@0: 	IMPORT_C static TInt GetSamplingRate(TInt aInterfaceId, TInt& aSamplingRate);
sl@0: 
sl@0: 
sl@0: 	/**
sl@0: 	Sets the frame length and format.
sl@0: 
sl@0: 	@param aInterfaceId		  The interface Id.
sl@0: 	@param aFrameLength		  One of TI2sFrameLength.
sl@0: 	@param aLeftFramePhaseLength The length of the left frame phase (in number of data bits).
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if the frame length or format are not supported by this interface;
sl@0: 						KErrInUse, if interface is not quiescient (a transfer is under way).
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 				   
sl@0: 	The implementation calculates the Right frame phase length as (FrameLength - LeftFramePhaseLength)
sl@0: 	*/
sl@0: 	IMPORT_C static TInt SetFrameLengthAndFormat(TInt aInterfaceId, TI2sFrameLength aFrameLength, TInt aLeftFramePhaseLength);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the frame format.
sl@0: 
sl@0: 	@param aInterfaceId			 The interface Id.
sl@0: 	@param aLeftFramePhaseLength  On return, contains the length of the left frame phase.
sl@0: 	@param aRightFramePhaseLength On return, contains the length of the right frame phase.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 	*/
sl@0: 	IMPORT_C static TInt GetFrameFormat(TInt aInterfaceId, TInt& aLeftFramePhaseLength, TInt& aRightFramePhaseLength);
sl@0: 
sl@0: 	/**
sl@0: 	Sets the sample length for a frame phase (left or right).
sl@0: 
sl@0: 	@param aInterfaceId	 The interface Id.
sl@0: 	@param aFramePhase	 One of TI2sFramePhase.
sl@0: 	@param aSampleLength One of TI2sSampleLength.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if the sample length for the frame phase selected is not supported by this interface;
sl@0: 						KErrInUse, if interface is not quiescient (a transfer is under way).
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 	*/
sl@0: 	IMPORT_C static TInt SetSampleLength(TInt aInterfaceId, TI2sFramePhase aFramePhase, TI2sSampleLength aSampleLength);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the sample length for a frame phase (left or right).
sl@0: 
sl@0: 	@param aInterfaceId	 The interface Id.
sl@0: 	@param aFramePhase	 One of TI2sFramePhase.
sl@0: 	@param aSampleLength On return, contains the sample length for the frame phase indicated by aFramePhase.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 	*/
sl@0: 	IMPORT_C static TInt GetSampleLength(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aSampleLength);
sl@0: 
sl@0: 	/**
sl@0: 	Sets the number of delay cycles for a frame phase (left or right).
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aDelayCycles The number of delay cycles to be introduced for the frame phase indicated by aFramePhase.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if the number of delay cycles for the frame phase selected is not supported by this interface;
sl@0: 						KErrInUse, if interface is not quiescient (a transfer is under way).
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	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.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt SetDelayCycles(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aDelayCycles);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the number of delay cycles for a frame phase (left or right).
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aDelayCycles On return, contains the number of delay cycles for the frame phase indicated by aFramePhase.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 	*/
sl@0: 	IMPORT_C static TInt GetDelayCycles(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aDelayCycles);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the receive data register for a frame phase.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aData		On return, contains the receive data register contents.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if reading the receive data register is not supported (e.g. when if DMA is enabled);
sl@0: 						KErrNotReady, if the interface is not ready.
sl@0: 	@pre                Can be called in any context.
sl@0: 
sl@0: 	If the implementation has a combined receive/transmit register - half duplex operation only - this API is used to read from it.
sl@0: 	If the implementation only supports a single receive register for both frame phases, the aFramePhase argument shall be ignored and the 
sl@0: 	API shall return the contents of the single register. The user of the API shall use the ReadRegisterModeStatus()/ReadFIFOModeStatus()
sl@0: 	API to determine which frame phase the data corresponds to.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt ReadReceiveRegister(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aData);
sl@0: 
sl@0: 	/**
sl@0: 	Writes to the transmit data register for a frame phase.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aData		The data to be written.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if writing to the receive data register is not supported (e.g. when if DMA is enabled);
sl@0: 						KErrNotReady, if the interface is not ready.
sl@0: 	@pre                Can be called in any context.
sl@0: 
sl@0: 	If the implementation has a combined receive/transmit register - half duplex operation only - this API is used to write to it.
sl@0: 	If the implementation only supports a single transmit register for both frame phases, the aFramePhase argument shall be ignored and the 
sl@0: 	API shall write to the single register. The user of the API shall use the ReadRegisterModeStatus()/ReadFIFOModeStatus() API to determine
sl@0: 	under which frame phase the data corresponds will be transmitted.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt WriteTransmitRegister(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aData);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the transmit data register for a frame phase.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aData		On return, contains the transmit data register contents.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if reading the transmit data register is not supported;
sl@0: 						KErrNotReady, if the interface is not ready.
sl@0: 	@pre                Can be called in any context.
sl@0: 
sl@0: 	If the implementation has a combined receive/transmit register this API is used to read from it (equivalent to ReadReceiveRegister()).
sl@0: 	If the implementation only supports a single transmit register for both frame phases, the aFramePhase argument shall be ignored and the 
sl@0: 	API shall return the contents of the single register. The user of the API shall use the ReadRegisterModeStatus()/ReadFIFOModeStatus()
sl@0: 	API to determine which frame phase the data corresponds to.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt ReadTransmitRegister(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aData);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the Register PIO access mode status flags for a frame phase.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aFlags		On return, contains a bitmask with the status flags for the frame phase selected (see TI2SFlags).
sl@0: 						A bit set to "1" indicates the condition described by the corresponding flag is occurring.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if reading the status flags for Register PIO mode is not supported by this implementation.
sl@0: 	@pre                Can be called in any context.
sl@0: 
sl@0: 	The client driver may use one of IS_I2S_<CONDITION> macros to determine the status of individual conditions.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt ReadRegisterModeStatus(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aFlags);
sl@0: 
sl@0: 	/**
sl@0: 	Enables Register PIO access mode related interrupts for a frame phase.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aInterrupt	A bitmask containing the relevant interrupt flags (see TI2sFlags).
sl@0: 						Bits set to "1" enable the corresponding interrupts.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	If the implementation only supports single transmit and receive registers for both frame phases, the aFramePhase argument is 
sl@0: 	ignored.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt EnableRegisterInterrupts(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aInterrupt);
sl@0: 
sl@0: 	/**
sl@0: 	Disables Register PIO access mode related interrupts for a frame phase.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aInterrupt	A bitmask containing the relevant interrupt flags (see TI2sFlags).
sl@0: 						Bits set to "1" disable the corresponding interrupts.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	If the implementation only supports single transmit and receive registers for both frame phases, the aFramePhase argument is 
sl@0: 	ignored.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt DisableRegisterInterrupts(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aInterrupt);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the Register PIO access mode interrupt mask for a frame phase.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aEnabled		On return, contains a bitmask with the interrupts which are enabled for the frame phase selected (see TI2SFlags).
sl@0: 						A bit set to "1" indicates the corresponding interrupt is enabled.
sl@0: 
sl@0: 	@return				KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation.
sl@0: 	@pre                Can be called in any context.
sl@0: 
sl@0: 	If the implementation only supports single transmit and receive registers for both frame phases, the aFramePhase argument is 
sl@0: 	ignored.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt IsRegisterInterruptEnabled(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aEnabled);
sl@0: 
sl@0: 	/**
sl@0: 	Enables receive and/or transmit FIFO on a per frame phase basis.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aFifoMask	A bitmask specifying which FIFO direction(s) - receive and/or transmit - are to be enabled for the frame 
sl@0: 						phase selected (see TI2sDirection).
sl@0: 						Bits set to "1" enable the corresponding FIFO.
sl@0: 
sl@0: 	@return				KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if the implementation does no support FIFOs.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFifoMask is ignored.
sl@0: 	If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt EnableFIFO(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aFifoMask);
sl@0: 
sl@0: 	/**
sl@0: 	Disables receive and/or transmit FIFO on a per frame phase basis.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aFifoMask	A bitmask specifying which FIFO direction(s) - receive and/or transmit - are to be disabled for the frame 
sl@0: 						phase selected (see TI2sDirection).
sl@0: 						Bits set to "1" disable the corresponding FIFO.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if the implementation does no support FIFOs.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFifoMask is ignored.
sl@0: 	If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt DisableFIFO(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aFifoMask);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the enabled state of a frame phase's FIFOs.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aEnabled		On return, contains a bitmask indicating which FIFOs which are enabled for the frame phase selected (see TI2sDirection).
sl@0: 						A bit set to "1" indicates the corresponding FIFO is enabled.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if the implementation does no support FIFOs.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aEnabled will have 
sl@0: 	both Rx and Tx bits set when the FIFO is enabled.
sl@0: 	If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt IsFIFOEnabled(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aEnabled);
sl@0: 
sl@0: 	/**
sl@0: 	Sets the receive or transmit FIFO threshold on a per frame phase basis.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aDirection	One of TDirection.
sl@0: 	@param aThreshold	A threshold level at which a receive FIFO is considered full or a transmit FIFO is considered empty.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if the implementation does no support FIFOs;
sl@0: 						KErrOverflow if the threshold level requested exceeds the FIFO length (or the admissible highest level allowed);
sl@0: 						KErrUnderflow if the threshold level requested is less than the minimum threshold allowed.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aDirection is ignored.
sl@0: 	If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt SetFIFOThreshold(TInt aInterfaceId, TI2sFramePhase aFramePhase, TI2sDirection aDirection, TInt aThreshold);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the FIFO PIO access mode status flags for a frame phase.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aFlags		On return, contains a bitmask with the status flags for the frame phase selected (see TI2sFlags).
sl@0: 						A bit set to "1" indicates the condition described by the corresponding flag is occurring.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if reading the status flags for FIFO PIO mode is not supported by this implementation.
sl@0: 						KErrInUse, if interface is not quiescient (a transfer is under way).
sl@0: 	@pre                Can be called in any context.
sl@0: 
sl@0: 	The client driver may use one of IS_I2S_<CONDITION> macros to determine the status of individual conditions.
sl@0: 	If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFlags will be set according
sl@0: 	to which operation (receive/transmit) is undergoing.
sl@0: 	If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt ReadFIFOModeStatus(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aFlags);
sl@0: 
sl@0: 	/**
sl@0: 	Enables FIFO related interrupts for a frame phase.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aInterrupt	A bitmask containing the relevant interrupt flags (see TI2sFlags).
sl@0: 						Bits set to "1" enable the corresponding interrupts.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	If the implementation only supports single transmit and receive FIFO for both frame phases, the aFramePhase argument is 
sl@0: 	ignored.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt EnableFIFOInterrupts(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aInterrupt);
sl@0: 
sl@0: 	/**
sl@0: 	Disables FIFO related interrupts for a frame phase.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aInterrupt	A bitmask containing the relevant interrupt flags (see TI2sFlags).
sl@0: 						Bits set to "1" disable the corresponding interrupts.
sl@0: 
sl@0: 	@return				KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	If the implementation only supports single transmit and receive FIFO for both frame phases, the aFramePhase argument is 
sl@0: 	ignored.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt DisableFIFOInterrupts(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt aInterrupt);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the FIFO interrupt masks for a frame phase.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aEnabled		On return, contains a bitmask with the interrupts which are enabled for the frame phase selected (see TI2sFlags).
sl@0: 						A bit set to "1" indicates the corresponding interrupt is enabled.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if one of the selected interrupt conditions cannot be generated by this implementation.
sl@0: 	@pre                Can be called in any context.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt IsFIFOInterruptEnabled(TInt aInterfaceId, TI2sFramePhase aFramePhase, TInt& aEnabled);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the receive or transmit FIFO current level on a per frame phase basis.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFramePhase	One of TI2sFramePhase.
sl@0: 	@param aDirection	One of TDirection.
sl@0: 	@param aLevel		On return, contains the current level for the FIFO described by the (aFramePhase,aDirection) pair.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if the implementation does no support FIFOs.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aDirection is ignored.
sl@0: 	If the implementation only supports a single FIFO for both frame phases then aFramePhase is ignored.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt ReadFIFOLevel(TInt aInterfaceId, TI2sFramePhase aFramePhase, TI2sDirection aDirection, TInt& aLevel);
sl@0: 
sl@0: 	/**
sl@0: 	Enables receive and/or transmit DMA.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFifoMask	A bitmask specifying which directions - receive and/or transmit - is DMA to be enabled (see TI2sDirection).
sl@0: 						Bits set to "1" enable DMA.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if the implementation does no support DMA.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFifoMask is ignored.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt EnableDMA(TInt aInterfaceId, TInt aFifoMask);
sl@0: 
sl@0: 	/**
sl@0: 	Disables receive and/or transmit DMA.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aFifoMask	A bitmask specifying which directions - receive and/or transmit - is DMA to be disabled (see TI2sDirection).
sl@0: 						Bits set to "1" disable DMA.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if the implementation does no support DMA.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aFifoMask is ignored.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt DisableDMA(TInt aInterfaceId, TInt aFifoMask);
sl@0: 
sl@0: 	/**
sl@0: 	Reads the enabled state of DMA.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aEnabled		On return, contains a bitmask indicating if DMA enabled for the corresponding directions (see TI2sDirection).
sl@0: 						A bit set to "1" indicates DMA is enabled for the corresponding direction.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid;
sl@0: 						KErrNotSupported, if the implementation does no support FIFOs.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	If the implementation has a combined receive/transmit FIFO - half duplex operation only - then aEnabled will have 
sl@0: 	both Rx and Tx bits set when the DMA is enabled.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt IsDMAEnabled(TInt aInterfaceId, TInt& aEnabled);
sl@0: 
sl@0: 	/**
sl@0: 	Starts data transmission and/or data reception unless interface is a Controller;
sl@0: 	if device is also a Master, starts generation of data synchronisation signals.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aDirection	A bitmask made of TI2sDirection values. The value is ignored if interface is a Controller.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid or if aDirection  is invalid (i.e. negative, 0 or greater than 3);
sl@0: 						KErrNotSupported, if one of the transfer directions selected is not supported on this interface;
sl@0: 						KErrInUse, if interface has a bidirectional data port and an access in the opposite direction is underway;
sl@0: 						KErrNotReady, if interface is not ready (e.g. incomplete configuration).
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	Start() is idempotent, attempting to start an already started interface has no effect (returns KErrNone).
sl@0: 	*/
sl@0: 	IMPORT_C static TInt Start(TInt aInterfaceId, TInt aDirection);
sl@0: 
sl@0: 	/**
sl@0: 	Stops data transmission and/or data reception;
sl@0: 	if device is also a Master, stops generation of data synchronisation signals.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aDirection	A bitmask made of TI2sDirection values.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid or if aDirection  is invalid (i.e. negative, 0 or greater than 3);
sl@0: 						KErrNotSupported, if one of the transfer directions selected is not supported on this interface.
sl@0: 	@pre                Call from thread context (neither NULL thread nor DFC threads 0 or 1).
sl@0: 
sl@0: 	Stop() is idempotent, attempting to stop an already started interface has no effect (returns KErrNone).
sl@0: 	*/
sl@0: 	IMPORT_C static TInt Stop(TInt aInterfaceId, TInt aDirection);
sl@0: 
sl@0: 	/**
sl@0: 	Checks if a transmission or a reception is underway.
sl@0: 
sl@0: 	@param aInterfaceId	The interface Id.
sl@0: 	@param aDirection	One of TI2sDirection.
sl@0: 	@param aStarted 	On return, contains ETrue if the the access is underway, EFalse otherwise.
sl@0: 
sl@0: 	@return 			KErrNone, if successful; 
sl@0: 						KErrArgument, if aInterfaceId is invalid or if aDirection  is invalid (i.e. negative, 0 or greater than 3);
sl@0: 						KErrNotSupported, if one of the transfer directions selected is not supported on this interface.
sl@0: 	@pre                Can be called in any context.
sl@0: 
sl@0: 	If the interface is a Controller and a bus operation is underway, ETrue is returned regardless of aDirection.
sl@0: 	*/
sl@0: 	IMPORT_C static TInt IsStarted(TInt aInterfaceId, TI2sDirection aDirection, TBool& aStarted);
sl@0: 	};
sl@0: 
sl@0: #define IS_I2S_RX_FULL(status)	(status&I2s::ERxFull)
sl@0: #define IS_I2S_TX_EMPTY(status)	(status&I2s::ETxEmpty)
sl@0: #define IS_I2S_RX_OVERRUN(status)	(status&I2s::ERxOverrun)
sl@0: #define IS_I2S_TX_UNDERRUN(status)	(status&I2s::ETxUnderrun)
sl@0: #define IS_I2S_FRAMING_ERROR(status)	(status&I2s::EFramingError)
sl@0: 
sl@0: #endif /* __I2S_H__ */
sl@0: