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/iic.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: @file sl@0: @internalTechnology sl@0: */ sl@0: sl@0: #ifndef __IIC_H__ sl@0: #define __IIC_H__ sl@0: sl@0: #include // for DThread; sl@0: #include sl@0: sl@0: #include sl@0: sl@0: const TInt KIicBusImpExtMaxPriority = KExtensionMaximumPriority-9; // A kernel extension priority to use as an offset sl@0: // for all IIC bus implemenetations sl@0: const TInt KMaxNumCapturedChannels = 4; // Arbitrary limit on the maximum number of channels captured for Slave operation sl@0: sl@0: const TUint KControlIoMask = 0xF0000000; sl@0: const TUint KMasterControlIo = 0x40000000; sl@0: const TUint KSlaveControlIo = 0x00000000; sl@0: const TUint KMasterSlaveControlIo = 0x80000000; sl@0: sl@0: class TIicBusCallback; // Forward declaration sl@0: class DIicBusController; sl@0: sl@0: sl@0: // sl@0: // Generic interface for clients sl@0: // sl@0: sl@0: class IicBus sl@0: { sl@0: public: sl@0: // Master-side API sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype 9.6 sl@0: Queues a transaction synchronously. sl@0: sl@0: @param aBusId A token containing the bus realisation variability. sl@0: @param aTransaction A pointer to a transaction object containing the details of the transaction. sl@0: sl@0: @return KErrNone, when successfully completed; sl@0: KErrArgument, if aBusId is not a valid token or aTransaction is NULL; sl@0: KErrTimedOut, if the channel terminates the transaction because the addressed Slave exceeded the alloted time to respond; sl@0: KErrNotSupported, if either the channel does not support Master mode or the transaction is not valid on this channel (e.g. valid full duplex transaction queued on half duplex channel). sl@0: */ sl@0: IMPORT_C static TInt QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction); sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype 9.6 sl@0: Queues a transaction asynchronously. sl@0: sl@0: @param aBusId A token containing the bus realisation variability. sl@0: @param aTransaction A pointer to a transaction object containing the details of the transaction. sl@0: @param aCallback A pointer to a callback object. sl@0: sl@0: @return KErrNone, if successfully accepted; KErrArgument, if aBusId is not a valid token or either aTransaction or aCallback are NULL; sl@0: KErrNotSupported, if either the channel does not support Master mode or the transaction is not valid on this channel(e.g. valid full duplex transaction queued on half duplex channel). sl@0: */ sl@0: IMPORT_C static TInt QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction, TIicBusCallback* aCallback); sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype 9.6 sl@0: Cancels a previously queued transaction. sl@0: sl@0: @param aBusId A token containing the bus realisation variability. sl@0: @param aTransaction A pointer to a transaction object containing the details of the transaction. sl@0: sl@0: @return KErrCancel, if successfully cancelled; KErrArgument, if aBusId is not a valid token or aTransaction is NULL; sl@0: KErrNotFound if the transaction cannot be found on channel's queue of transactions; sl@0: KErrInUse if this method is called on a transaction that has already been started; sl@0: KErrNotSupported, if the channel does not support Master mode, or the method is called on a synchronous transaction.. sl@0: */ sl@0: IMPORT_C static TInt CancelTransaction(TInt aBusId, TIicBusTransaction* aTransaction); sl@0: sl@0: // Slave-side API sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype 9.6 sl@0: Capture a Slave channel. sl@0: sl@0: @param aBusId A token containing the bus realisation variability. sl@0: @param aConfigHdr A pointer to a descriptor containing the device specific configuration option applicable to all transactions. sl@0: @param aCallback A pointer to a callback to be called upon specified triggers. sl@0: @param aChannelId If this API is to complete synchronously, and the processing was successful, then on return aChannelId sl@0: contains a platform-specific cookie that uniquely identifies the channel instance to be used by this client. sl@0: If the processing was unsuccessful for the synchronous completion case, aChannelId will be unchanged. sl@0: If the API was called to complete asynchronously, aChannelId will, in all cases, be set to zero; the valid sl@0: value for the cookie will be set by the callback. sl@0: @param aAsynch A boolean value that indicates if this API is to complete synchronously (EFalse) or asynchronously (ETrue). sl@0: sl@0: @return KErrNone, if successfully captured, or if API is asynchronous, if the request to capture the channel was accepted; sl@0: KErrInUse if channel is already in use; KErrArgument, if aBusId is not a valid token or aCallback is NULL; sl@0: KErrNotSupported, if the channel does not support Slave mode. sl@0: */ sl@0: IMPORT_C static TInt CaptureChannel(TInt aBusId, TDes8* aConfigHdr, TIicBusSlaveCallback* aCallback, TInt& aChannelId, TBool aAsynch=EFalse); sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype 9.6 sl@0: Release a previously captured Slave channel. sl@0: sl@0: @param aChannelId The channel identifier cookie for this client. sl@0: sl@0: @return KErrNone, if successfully released; sl@0: KErrInUse if a transaction is currently underway on this channel; KErrArgument, if aChannelId is not a valid cookie; sl@0: */ sl@0: IMPORT_C static TInt ReleaseChannel(TInt aChannelId); sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype 9.6 sl@0: Register a receive buffer with this Slave channel. sl@0: sl@0: @param aChannelId The channel identifier cookie for this client. sl@0: @param aRxBuffer A pointer to the receive buffer, in a client created descriptor. sl@0: @param aBufGranularity The number of buffer bytes used to store a word. sl@0: @param aNumWords The number of words expected to be received. sl@0: @param aOffset The offset from the start of the buffer where to store the received data. sl@0: sl@0: @return KErrNone, if succesfully registered; sl@0: KErrAlreadyExists if a receive buffer is already pending; sl@0: KErrArgument, if aChannelId is not a valid cookie, or if the pointer descriptor is NULL; sl@0: */ sl@0: IMPORT_C static TInt RegisterRxBuffer(TInt aChannelId, TPtr8 aRxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset); sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype 9.6 sl@0: Register a transmit buffer with this Slave channel. sl@0: This client may create a single buffer for the entire transaction and control where the received data sl@0: is to be placed and the transmit data is to be found, by specifying the number of bytes to transmit (receive) sl@0: and the offset into the buffer. sl@0: sl@0: @param aChannelId The channel identifier cookie for this client. sl@0: @param aTxBuffer A pointer to the transmit buffer, in a client created descriptor. sl@0: @param aBufGranularity The number of buffer bytes used to store a word. sl@0: @param aNumWords The number of words to be transmitted. sl@0: @param aOffset The offset from the start of the buffer where to fetch the data to be transmitted. sl@0: sl@0: @return KErrNone, if successfully registered; sl@0: KErrAlreadyExists if a transmit buffer is already pending; sl@0: KErrArgument, if aChannelId is not a valid cookie, or if the pointer descriptor is NULL; sl@0: */ sl@0: IMPORT_C static TInt RegisterTxBuffer(TInt aChannelId, TPtr8 aTxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset); sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype 9.6 sl@0: Sets the notification triggers and readies the receive path and/or kick starts a transmit (if the node is being addressed). sl@0: It is only after a receive buffer has been registered and this API has been called that the channel is ready to receive data (when addressed). sl@0: If a transmit buffer has been registered and this API has been called the channel will immediately transmit when addressed by the Master sl@0: If the channel supports full duplex, both paths can be readied in one call to this API. sl@0: sl@0: @param aChannelId The channel identifier cookie for this client. sl@0: @param aTrigger A bitmask specifying the notification trigger. Masks for individual triggers are specified by the TIicBusSlaveTrigger enumeration. sl@0: sl@0: @return KErrNone, if successful; sl@0: KErrArgument, if aChannelId is not a valid cookie, or if the trigger is invalid for this channel; sl@0: KErrInUse if a transaction is already underway on this channel; sl@0: KErrTimedOut, if the client exceeded the alloted time to respond by invoking this API; sl@0: */ sl@0: IMPORT_C static TInt SetNotificationTrigger(TInt aChannelId, TInt aTrigger); sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype 9.6 sl@0: Interface to provide extended functionality sl@0: sl@0: @param aId A token containing the bus realisation variability or the channel identifier cookie for this client. sl@0: @param aFunction A function identifier. If bit 31 is set and bit 30 cleared it is used to extend the Master-Slave channel; sl@0: if bit 31 is cleared and bit 30 is set, it extends the Master channel; if both bits 31 and 30 are cleared it sl@0: extends the Slave channel interface. sl@0: @param aParam1 A generic argument to be passed to the function identified by aFunction. sl@0: @param aParam2 A generic argument to be passed to the function identified by aFunction. sl@0: sl@0: @return KErrNone, if successful; sl@0: KErrNotSupported, function is not supported; sl@0: Any other system wide error code. sl@0: */ sl@0: IMPORT_C static TInt StaticExtension(TUint aId, TUint aFunction, TAny* aParam1, TAny* aParam2); sl@0: }; sl@0: sl@0: // Forward declaration sl@0: class DIicBusChannel; sl@0: class DIicBusChannelSearcher; sl@0: sl@0: NONSHARABLE_CLASS(DIicBusController) : public DBase sl@0: { sl@0: public: sl@0: // constructor sl@0: inline DIicBusController() {}; sl@0: ~DIicBusController(); sl@0: sl@0: TInt Create(); sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype 9.6 sl@0: Interface to be used by Channel implementations to register a list of supported channels. This method sl@0: will check if the array of pointers to channels is already being modified and, if so, will return KErrInUse. sl@0: Otherwise, the iArrayBusy flag will be set and each entry in the list inserted into the array according sl@0: to a sorting algorithm; the iArrayBusy flag will then be cleared after inserting the last entry. sl@0: sl@0: @param aListChannels A pointer to a linked list of DIicBusChannel instances to be registered sl@0: @param aNumberChannels The number of channels to be registered. sl@0: sl@0: @return KErrNone, if successful; sl@0: KErrInUse, if the array of pointers to channels is already being modified; sl@0: Any other system wide error code. sl@0: */ sl@0: IMPORT_C static TInt RegisterChannels(DIicBusChannel** aListChannels, TInt aNumberChannels); sl@0: sl@0: /** sl@0: @publishedPartner sl@0: @prototype 9.6 sl@0: Interface to be used by Channel implementations to deregister a channel. This method sl@0: will check if the array of pointers to channels is already being modified and, if so, will return KErrInUse. sl@0: Otherwise, the channel will be removed from the array according to a sorting algorithm; the iArrayBusy sl@0: flag will be set before searching for the channel and cleared immediately after removing it. sl@0: sl@0: @param aListChannels A pointer to a linked list of DIicBusChannel instances to be registered sl@0: @param aNumberChannels The number of channels to be registered. sl@0: sl@0: @return KErrNone, if successful; sl@0: KErrInUse, if the array of pointers to channels is already being modified; sl@0: KErrArgument, if aChannel is a NULL pointer or represents and invalid channel type sl@0: KErrNotFound, if aChannel is not found in the array of pointers to channels sl@0: Any other system wide error code. sl@0: */ sl@0: IMPORT_C static TInt DeRegisterChannel(DIicBusChannel* aChannel); sl@0: sl@0: // implementation of public interface APIs sl@0: TInt QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction); sl@0: TInt QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction, TIicBusCallback* aCallback); sl@0: TInt CancelTransaction(TInt aBusId, TIicBusTransaction* aTransaction); sl@0: TInt CaptureChannel(TInt aBusId, TDes8* aConfigHdr, TIicBusSlaveCallback* aCallback, TInt& aChannelId, TBool aAsynch); sl@0: TInt ReleaseChannel(TInt aChannelId); sl@0: TInt RegisterRxBuffer(TInt aChannelId, TPtr8 aRxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset); sl@0: TInt RegisterTxBuffer(TInt aChannelId, TPtr8 aTxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset); sl@0: TInt SetNotificationTrigger(TInt aChannelId, TInt aTrigger); sl@0: TInt StaticExtension(TUint aId, TUint aFunction, TAny* aParam1, TAny* aParam2); sl@0: sl@0: static TInt OrderEntries(const DIicBusChannel& aMatch, const DIicBusChannel& aEntry); sl@0: sl@0: private: sl@0: TInt GetSlaveChanPtr(TInt aChannelId, DIicBusChannelSlave*& aSlaveChanPtr); sl@0: TInt GetChanPtr(const TInt aBusId, TInt &aIndex, DIicBusChannel*& aChan); sl@0: sl@0: inline RPointerArray* ChannelArray(); sl@0: sl@0: TInt GetChanWriteAccess(); sl@0: void FreeChanWriteAccess(); sl@0: TInt GetChanReadAccess(); sl@0: void FreeChanReadAccess(); sl@0: sl@0: TInt RequestTypeSupported(const TInt aBusId, DIicBusChannelMaster* const aChannel); sl@0: sl@0: public: sl@0: /** sl@0: @internalComponent sl@0: @prototype 9.6 sl@0: Class used by DIicBusController for locating channels captured by clients for Slave Mode operation sl@0: */ sl@0: class TCapturedChannel // Generated by DIicBusChannelSlave sl@0: { sl@0: public: sl@0: inline TCapturedChannel(); sl@0: inline TCapturedChannel(TInt aChannelId, DIicBusChannelSlave* aChanPtr); sl@0: sl@0: inline TCapturedChannel& operator=(TCapturedChannel& aChan); sl@0: inline TInt operator==(TCapturedChannel& aChan); sl@0: sl@0: public: sl@0: TInt iChannelId; // ID to be used by client sl@0: DIicBusChannelSlave* iChanPtr; // Index to iChannelArray sl@0: }; sl@0: public: sl@0: /** sl@0: @internalTechnology sl@0: @prototype 9.6 sl@0: Function to register a Slave channel with DIicBusController as captured sl@0: */ sl@0: virtual TInt InstallCapturedChannel(const TInt aChannelId, const DIicBusChannelSlave* aChanPtr); sl@0: private: sl@0: RPointerArray iChannelArray; sl@0: TCapturedChannel iCapturedChannels[KMaxNumCapturedChannels]; sl@0: TInt InsertCaptChanInArray(TCapturedChannel aCapturedChan); sl@0: TInt RemoveCaptChanFromArray(TCapturedChannel aCapturedChan); sl@0: TInt FindCapturedChan(TCapturedChannel aCapturedChan, TInt& aIndex); sl@0: TInt FindCapturedChanById(TCapturedChannel aCapturedChan, TInt& aIndex); sl@0: sl@0: TInt DeInstallCapturedChannel(const TInt aChannelId, const DIicBusChannelSlave* aChanPtr); sl@0: sl@0: #ifdef _DEBUG sl@0: void DumpCapturedChannels(); sl@0: void DumpChannelArray(); sl@0: #endif sl@0: sl@0: private: sl@0: enum TArrayActivity sl@0: { sl@0: EWriteInProgress=0x1, sl@0: EReadInProgress=0x2 sl@0: }; sl@0: sl@0: TSpinLock *iChanLock; sl@0: TUint32 iChanRdCount; // Maximum 32-bit count for concurrent reads sl@0: TSpinLock *iCaptLock; sl@0: sl@0: TInt8 iChanRwFlags; // Bit 0 for write, bit 1 for read sl@0: }; sl@0: sl@0: #ifdef IIC_SIMULATED_PSL sl@0: _LIT(KPddName,"iic.pdd"); sl@0: sl@0: NONSHARABLE_CLASS(DIicPdd) : public DPhysicalDevice sl@0: { sl@0: // Class to faciliate loading of the IIC classes sl@0: public: sl@0: class TCaps sl@0: { sl@0: public: sl@0: TVersion iVersion; sl@0: }; sl@0: public: sl@0: DIicPdd(); sl@0: ~DIicPdd(); sl@0: virtual TInt Install(); sl@0: virtual TInt Create(DBase*& aChannel, TInt aUnit, const TDesC8* anInfo, const TVersion& aVer); sl@0: virtual TInt Validate(TInt aUnit, const TDesC8* anInfo, const TVersion& aVer); sl@0: virtual void GetCaps(TDes8& aDes) const; sl@0: inline static TVersion VersionRequired(); sl@0: }; sl@0: #endif sl@0: sl@0: #include sl@0: sl@0: #endif // #ifndef __IIC_H__ sl@0: