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/iic.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 @file

    22 @internalTechnology

    23 */

    24 

    25 #ifndef __IIC_H__

    26 #define __IIC_H__

    27 

    28 #include <kernel/kern_priv.h> // for DThread;

    29 #include <e32ver.h>

    30 

    31 #include <drivers/iic_transaction.h>

    32 

    33 const TInt KIicBusImpExtMaxPriority = KExtensionMaximumPriority-9;	// A kernel extension priority to use as an offset

    34 																	// for all IIC bus implemenetations

    35 const TInt KMaxNumCapturedChannels = 4;	// Arbitrary limit on the maximum number of channels captured for Slave operation

    36 

    37 const TUint KControlIoMask =			0xF0000000;

    38 const TUint KMasterControlIo =		0x40000000;

    39 const TUint KSlaveControlIo =		0x00000000;

    40 const TUint KMasterSlaveControlIo =	0x80000000;

    41 

    42 class TIicBusCallback; // Forward declaration

    43 class DIicBusController;

    44 

    45 

    46 //

    47 // Generic interface for clients

    48 //

    49 

    50 class IicBus

    51 	{

    52 public:

    53 	// Master-side API

    54 

    55     /**

    56 	@publishedPartner

    57 	@prototype 9.6

    58     Queues a transaction synchronously.

    59 

    60     @param aBusId			A token containing the bus realisation variability.

    61     @param aTransaction		A pointer to a transaction object containing the details of the transaction.

    62 

    63     @return KErrNone, when successfully completed;

    64 			KErrArgument, if aBusId is not a valid token or aTransaction is NULL;

    65 			KErrTimedOut, if the channel terminates the transaction because  the addressed Slave exceeded the alloted time to respond;

    66             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).

    67     */

    68 	IMPORT_C static TInt QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction);

    69 

    70     /**

    71 	@publishedPartner

    72 	@prototype 9.6

    73     Queues a transaction asynchronously.

    74 

    75     @param aBusId			A token containing the bus realisation variability.

    76     @param aTransaction		A pointer to a transaction object containing the details of the transaction.

    77     @param aCallback		A pointer to a callback object.

    78 

    79     @return KErrNone, if successfully accepted; KErrArgument, if aBusId is not a valid token or either aTransaction or aCallback are NULL;

    80             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).

    81     */

    82 	IMPORT_C static TInt QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction, TIicBusCallback* aCallback);

    83 

    84     /**

    85 	@publishedPartner

    86 	@prototype 9.6

    87     Cancels a previously queued transaction.

    88 

    89     @param aBusId			A token containing the bus realisation variability.

    90     @param aTransaction		A pointer to a transaction object containing the details of the transaction.

    91 

    92     @return KErrCancel, if successfully cancelled; KErrArgument, if aBusId is not a valid token or aTransaction is NULL;

    93 			KErrNotFound if the transaction cannot be found on channel's queue of transactions;

    94 			KErrInUse if this method is called on a transaction that has already been started;

    95             KErrNotSupported, if the channel does not support Master mode, or the method is called on a synchronous transaction..

    96     */

    97 	IMPORT_C static TInt CancelTransaction(TInt aBusId, TIicBusTransaction* aTransaction);

    98 

    99 	// Slave-side API

   100 

   101 	/**

   102 	@publishedPartner

   103 	@prototype 9.6

   104     Capture a Slave channel.

   105 

   106     @param aBusId		A token containing the bus realisation variability.

   107     @param aConfigHdr	A pointer to a descriptor containing the device specific configuration option applicable to all transactions.

   108     @param aCallback	A pointer to a callback to be called upon specified triggers.

   109     @param aChannelId	If this API is to complete synchronously, and the processing was successful, then on return aChannelId

   110                       contains a platform-specific cookie that uniquely identifies the channel instance to be used by this client.

   111                       If the processing was unsuccessful for the synchronous completion case, aChannelId will be unchanged.

   112                       If the API was called to complete asynchronously, aChannelId will, in all cases, be set to zero; the valid

   113                       value for the cookie will be set by the callback.

   114 	@param aAsynch		A boolean value that indicates if this API is to complete synchronously (EFalse) or asynchronously (ETrue).

   115 

   116     @return KErrNone, if successfully captured, or if API is asynchronous, if the request to capture the channel was accepted;

   117 			KErrInUse if channel is already in use; KErrArgument, if aBusId is not a valid token or aCallback is NULL;

   118             KErrNotSupported, if the channel does not support Slave mode.

   119     */

   120 	IMPORT_C static TInt CaptureChannel(TInt aBusId, TDes8* aConfigHdr, TIicBusSlaveCallback* aCallback, TInt& aChannelId, TBool aAsynch=EFalse);

   121 

   122 	/**

   123 	@publishedPartner

   124 	@prototype 9.6

   125     Release a previously captured Slave channel.

   126 

   127     @param aChannelId	The channel identifier cookie for this client.

   128 

   129     @return KErrNone, if successfully released;

   130 			KErrInUse if a transaction is currently underway on this channel; KErrArgument, if aChannelId is not a valid cookie;

   131     */

   132 	IMPORT_C static TInt ReleaseChannel(TInt aChannelId);

   133 

   134 	/**

   135 	@publishedPartner

   136 	@prototype 9.6

   137 	Register a receive buffer with this Slave channel.

   138 

   139     @param aChannelId	The channel identifier cookie for this client.

   140     @param aRxBuffer	A pointer to the receive buffer, in a client created descriptor.

   141 	@param aBufGranularity The number of buffer bytes used to store a word.

   142     @param aNumWords	The number of words expected to be received.

   143     @param aOffset		The offset from the start of the buffer where to store the received data.

   144 

   145     @return KErrNone, if succesfully registered;

   146 			KErrAlreadyExists if a receive buffer is already pending;

   147 			KErrArgument, if aChannelId is not a valid cookie, or if the pointer descriptor is NULL;

   148     */

   149 	IMPORT_C static TInt RegisterRxBuffer(TInt aChannelId, TPtr8 aRxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);

   150 

   151 	/**

   152 	@publishedPartner

   153 	@prototype 9.6

   154 	Register a transmit buffer with this Slave channel.

   155 	This client may create a single buffer for the entire transaction and control where the received data

   156 	is to be placed and the transmit data is to be found, by specifying the number of bytes to transmit (receive)

   157 	and the offset into the buffer.

   158 

   159     @param aChannelId	The channel identifier cookie for this client.

   160     @param aTxBuffer	A pointer to the transmit buffer, in a client created descriptor.

   161 	@param aBufGranularity The number of buffer bytes used to store a word.

   162     @param aNumWords	The number of words to be transmitted.

   163     @param aOffset		The offset from the start of the buffer where to fetch the data to be transmitted.

   164 

   165     @return KErrNone, if successfully registered;

   166 			KErrAlreadyExists if a transmit buffer is already pending;

   167 			KErrArgument, if aChannelId is not a valid cookie, or if the pointer descriptor is NULL;

   168     */

   169 	IMPORT_C static TInt RegisterTxBuffer(TInt aChannelId, TPtr8 aTxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);

   170 

   171 	/**

   172 	@publishedPartner

   173 	@prototype 9.6

   174 	Sets the notification triggers and readies the receive path and/or kick starts a transmit (if the node is being addressed).

   175 	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).

   176 	If a transmit buffer has been registered and this API has been called the channel will immediately transmit when addressed by the Master

   177 	If the channel supports full duplex, both paths can be readied in one call to this API.

   178 

   179     @param aChannelId	The channel identifier cookie for this client.

   180     @param aTrigger		A bitmask specifying the notification trigger. Masks for individual triggers are specified by the TIicBusSlaveTrigger enumeration.

   181 

   182     @return KErrNone, if successful;

   183 			KErrArgument, if aChannelId is not a valid cookie, or if the trigger is invalid for this channel;

   184 			KErrInUse if a transaction is already underway on this channel;

   185 			KErrTimedOut, if the client exceeded the alloted time to respond by invoking this API;

   186     */

   187 	IMPORT_C static TInt SetNotificationTrigger(TInt aChannelId, TInt aTrigger);

   188 

   189 	/**

   190 	@publishedPartner

   191 	@prototype 9.6

   192 	Interface to provide extended functionality

   193 

   194     @param aId			A token containing the bus realisation variability or the channel identifier cookie for this client.

   195     @param aFunction	A function identifier. If bit 31 is set and bit 30 cleared it is used to extend the Master-Slave channel;

   196 						if bit 31 is cleared and bit 30 is set, it extends the Master channel; if both bits 31 and 30 are cleared it

   197 						extends the Slave channel interface.

   198     @param aParam1		A generic argument to be passed to the function identified by aFunction.

   199     @param aParam2		A generic argument to be passed to the function identified by aFunction.

   200 

   201     @return KErrNone, if successful;

   202 			KErrNotSupported, function is not supported;

   203 			Any other system wide error code.

   204 	*/

   205     IMPORT_C static TInt StaticExtension(TUint aId, TUint aFunction, TAny* aParam1, TAny* aParam2);

   206 	};

   207 

   208 // Forward declaration

   209 class DIicBusChannel;

   210 class DIicBusChannelSearcher;

   211 

   212 NONSHARABLE_CLASS(DIicBusController) : public DBase

   213 	{

   214 public:

   215 	// constructor

   216 	inline DIicBusController() {};

   217 	~DIicBusController();

   218 

   219 	TInt Create();

   220 

   221 	/**

   222 	@publishedPartner

   223 	@prototype 9.6

   224 	Interface to be used by Channel implementations to register a list of supported channels. This method

   225 	will check if the array of pointers to channels is already being modified and, if so, will return KErrInUse.

   226 	Otherwise, the iArrayBusy flag will be set and each entry in the list inserted into the array according

   227 	to a sorting algorithm; the iArrayBusy flag will then be cleared after inserting the last entry.

   228 

   229     @param aListChannels	A pointer to a linked list of DIicBusChannel instances to be registered

   230     @param aNumberChannels	The number of channels to be registered.

   231 

   232     @return KErrNone, if successful;

   233 			KErrInUse, if the array of pointers to channels is already being modified;

   234 			Any other system wide error code.

   235 	*/

   236 	IMPORT_C static TInt RegisterChannels(DIicBusChannel** aListChannels, TInt aNumberChannels);

   237 

   238 	/**

   239 	@publishedPartner

   240 	@prototype 9.6

   241 	Interface to be used by Channel implementations to deregister a channel. This method

   242 	will check if the array of pointers to channels is already being modified and, if so, will return KErrInUse.

   243 	Otherwise, the channel will be removed from the array according to a sorting algorithm; the iArrayBusy

   244 	flag will be set before searching for the channel and cleared immediately after removing it.

   245 

   246     @param aListChannels	A pointer to a linked list of DIicBusChannel instances to be registered

   247     @param aNumberChannels	The number of channels to be registered.

   248 

   249     @return KErrNone, if successful;

   250 			KErrInUse, if the array of pointers to channels is already being modified;

   251 			KErrArgument, if aChannel is a NULL pointer or represents and invalid channel type

   252 			KErrNotFound, if aChannel is not found in the array of pointers to channels

   253 			Any other system wide error code.

   254 	*/

   255 	IMPORT_C static TInt DeRegisterChannel(DIicBusChannel* aChannel);

   256 

   257 	// implementation of public interface APIs

   258 	TInt QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction);

   259 	TInt QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction, TIicBusCallback* aCallback);

   260 	TInt CancelTransaction(TInt aBusId, TIicBusTransaction* aTransaction);

   261 	TInt CaptureChannel(TInt aBusId, TDes8* aConfigHdr, TIicBusSlaveCallback* aCallback, TInt& aChannelId, TBool aAsynch);

   262 	TInt ReleaseChannel(TInt aChannelId);

   263 	TInt RegisterRxBuffer(TInt aChannelId, TPtr8 aRxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);

   264 	TInt RegisterTxBuffer(TInt aChannelId, TPtr8 aTxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);

   265 	TInt SetNotificationTrigger(TInt aChannelId, TInt aTrigger);

   266 	TInt StaticExtension(TUint aId, TUint aFunction, TAny* aParam1, TAny* aParam2);

   267 

   268 	static TInt OrderEntries(const DIicBusChannel& aMatch, const DIicBusChannel& aEntry);

   269 

   270 private:

   271 	TInt GetSlaveChanPtr(TInt aChannelId, DIicBusChannelSlave*& aSlaveChanPtr);

   272 	TInt GetChanPtr(const TInt aBusId, TInt &aIndex, DIicBusChannel*& aChan);

   273 

   274 	inline RPointerArray<DIicBusChannel>* ChannelArray();

   275 

   276 	TInt GetChanWriteAccess();

   277 	void FreeChanWriteAccess();

   278 	TInt GetChanReadAccess();

   279 	void FreeChanReadAccess();

   280 

   281 	TInt RequestTypeSupported(const TInt aBusId, DIicBusChannelMaster* const aChannel);

   282 

   283 public:

   284 	/**

   285 	@internalComponent

   286 	@prototype 9.6

   287 	Class used by DIicBusController for locating channels captured by clients for Slave Mode operation

   288 	*/

   289 	class TCapturedChannel	// Generated by DIicBusChannelSlave

   290 		{

   291 		public:

   292 			inline TCapturedChannel();

   293 			inline TCapturedChannel(TInt aChannelId, DIicBusChannelSlave* aChanPtr);

   294 

   295 			inline TCapturedChannel& operator=(TCapturedChannel& aChan);

   296 			inline TInt operator==(TCapturedChannel& aChan);

   297 

   298 		public:

   299 			TInt iChannelId;	// ID to be used by client

   300 			DIicBusChannelSlave* iChanPtr;	// Index to iChannelArray

   301 		};

   302 public:

   303 	/**

   304 	@internalTechnology

   305 	@prototype 9.6

   306 	Function to register a Slave channel with DIicBusController as captured

   307 	*/

   308 	virtual TInt InstallCapturedChannel(const TInt aChannelId, const DIicBusChannelSlave* aChanPtr);

   309 private:

   310 	RPointerArray<DIicBusChannel> iChannelArray;

   311 	TCapturedChannel iCapturedChannels[KMaxNumCapturedChannels];

   312 	TInt InsertCaptChanInArray(TCapturedChannel aCapturedChan);

   313 	TInt RemoveCaptChanFromArray(TCapturedChannel aCapturedChan);

   314 	TInt FindCapturedChan(TCapturedChannel aCapturedChan, TInt& aIndex);

   315 	TInt FindCapturedChanById(TCapturedChannel aCapturedChan, TInt& aIndex);

   316 

   317 	TInt DeInstallCapturedChannel(const TInt aChannelId, const DIicBusChannelSlave* aChanPtr);

   318 

   319 #ifdef _DEBUG

   320 	void DumpCapturedChannels();

   321 	void DumpChannelArray();

   322 #endif

   323 

   324 private:

   325 	enum TArrayActivity

   326 		{

   327 		EWriteInProgress=0x1,

   328 		EReadInProgress=0x2

   329 		};

   330 

   331 	TSpinLock *iChanLock;

   332 	TUint32 iChanRdCount;	// Maximum 32-bit count for concurrent reads

   333 	TSpinLock *iCaptLock;

   334 

   335 	TInt8 iChanRwFlags;		// Bit 0 for write, bit 1 for read

   336 	};

   337 

   338 #ifdef IIC_SIMULATED_PSL

   339 _LIT(KPddName,"iic.pdd");

   340 

   341 NONSHARABLE_CLASS(DIicPdd) : public DPhysicalDevice

   342 	{

   343 // Class to faciliate loading of the IIC classes

   344 public:

   345 	class TCaps

   346 		{

   347 	public:

   348 		TVersion iVersion;

   349 		};

   350 public:

   351 	DIicPdd();

   352 	~DIicPdd();

   353 	virtual TInt Install();

   354 	virtual TInt Create(DBase*& aChannel, TInt aUnit, const TDesC8* anInfo, const TVersion& aVer);

   355 	virtual TInt Validate(TInt aUnit, const TDesC8* anInfo, const TVersion& aVer);

   356 	virtual void GetCaps(TDes8& aDes) const;

   357 	inline static TVersion VersionRequired();

   358 	};

   359 #endif

   360 

   361 #include <drivers/iic.inl>

   362 

   363 #endif  // #ifndef __IIC_H__

   364