1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/include/drivers/iic.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,364 @@
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/iic.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 +@file
1.25 +@internalTechnology
1.26 +*/
1.27 +
1.28 +#ifndef __IIC_H__
1.29 +#define __IIC_H__
1.30 +
1.31 +#include <kernel/kern_priv.h> // for DThread;
1.32 +#include <e32ver.h>
1.33 +
1.34 +#include <drivers/iic_transaction.h>
1.35 +
1.36 +const TInt KIicBusImpExtMaxPriority = KExtensionMaximumPriority-9; // A kernel extension priority to use as an offset
1.37 + // for all IIC bus implemenetations
1.38 +const TInt KMaxNumCapturedChannels = 4; // Arbitrary limit on the maximum number of channels captured for Slave operation
1.39 +
1.40 +const TUint KControlIoMask = 0xF0000000;
1.41 +const TUint KMasterControlIo = 0x40000000;
1.42 +const TUint KSlaveControlIo = 0x00000000;
1.43 +const TUint KMasterSlaveControlIo = 0x80000000;
1.44 +
1.45 +class TIicBusCallback; // Forward declaration
1.46 +class DIicBusController;
1.47 +
1.48 +
1.49 +//
1.50 +// Generic interface for clients
1.51 +//
1.52 +
1.53 +class IicBus
1.54 + {
1.55 +public:
1.56 + // Master-side API
1.57 +
1.58 + /**
1.59 + @publishedPartner
1.60 + @prototype 9.6
1.61 + Queues a transaction synchronously.
1.62 +
1.63 + @param aBusId A token containing the bus realisation variability.
1.64 + @param aTransaction A pointer to a transaction object containing the details of the transaction.
1.65 +
1.66 + @return KErrNone, when successfully completed;
1.67 + KErrArgument, if aBusId is not a valid token or aTransaction is NULL;
1.68 + KErrTimedOut, if the channel terminates the transaction because the addressed Slave exceeded the alloted time to respond;
1.69 + 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).
1.70 + */
1.71 + IMPORT_C static TInt QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction);
1.72 +
1.73 + /**
1.74 + @publishedPartner
1.75 + @prototype 9.6
1.76 + Queues a transaction asynchronously.
1.77 +
1.78 + @param aBusId A token containing the bus realisation variability.
1.79 + @param aTransaction A pointer to a transaction object containing the details of the transaction.
1.80 + @param aCallback A pointer to a callback object.
1.81 +
1.82 + @return KErrNone, if successfully accepted; KErrArgument, if aBusId is not a valid token or either aTransaction or aCallback are NULL;
1.83 + 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).
1.84 + */
1.85 + IMPORT_C static TInt QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction, TIicBusCallback* aCallback);
1.86 +
1.87 + /**
1.88 + @publishedPartner
1.89 + @prototype 9.6
1.90 + Cancels a previously queued transaction.
1.91 +
1.92 + @param aBusId A token containing the bus realisation variability.
1.93 + @param aTransaction A pointer to a transaction object containing the details of the transaction.
1.94 +
1.95 + @return KErrCancel, if successfully cancelled; KErrArgument, if aBusId is not a valid token or aTransaction is NULL;
1.96 + KErrNotFound if the transaction cannot be found on channel's queue of transactions;
1.97 + KErrInUse if this method is called on a transaction that has already been started;
1.98 + KErrNotSupported, if the channel does not support Master mode, or the method is called on a synchronous transaction..
1.99 + */
1.100 + IMPORT_C static TInt CancelTransaction(TInt aBusId, TIicBusTransaction* aTransaction);
1.101 +
1.102 + // Slave-side API
1.103 +
1.104 + /**
1.105 + @publishedPartner
1.106 + @prototype 9.6
1.107 + Capture a Slave channel.
1.108 +
1.109 + @param aBusId A token containing the bus realisation variability.
1.110 + @param aConfigHdr A pointer to a descriptor containing the device specific configuration option applicable to all transactions.
1.111 + @param aCallback A pointer to a callback to be called upon specified triggers.
1.112 + @param aChannelId If this API is to complete synchronously, and the processing was successful, then on return aChannelId
1.113 + contains a platform-specific cookie that uniquely identifies the channel instance to be used by this client.
1.114 + If the processing was unsuccessful for the synchronous completion case, aChannelId will be unchanged.
1.115 + If the API was called to complete asynchronously, aChannelId will, in all cases, be set to zero; the valid
1.116 + value for the cookie will be set by the callback.
1.117 + @param aAsynch A boolean value that indicates if this API is to complete synchronously (EFalse) or asynchronously (ETrue).
1.118 +
1.119 + @return KErrNone, if successfully captured, or if API is asynchronous, if the request to capture the channel was accepted;
1.120 + KErrInUse if channel is already in use; KErrArgument, if aBusId is not a valid token or aCallback is NULL;
1.121 + KErrNotSupported, if the channel does not support Slave mode.
1.122 + */
1.123 + IMPORT_C static TInt CaptureChannel(TInt aBusId, TDes8* aConfigHdr, TIicBusSlaveCallback* aCallback, TInt& aChannelId, TBool aAsynch=EFalse);
1.124 +
1.125 + /**
1.126 + @publishedPartner
1.127 + @prototype 9.6
1.128 + Release a previously captured Slave channel.
1.129 +
1.130 + @param aChannelId The channel identifier cookie for this client.
1.131 +
1.132 + @return KErrNone, if successfully released;
1.133 + KErrInUse if a transaction is currently underway on this channel; KErrArgument, if aChannelId is not a valid cookie;
1.134 + */
1.135 + IMPORT_C static TInt ReleaseChannel(TInt aChannelId);
1.136 +
1.137 + /**
1.138 + @publishedPartner
1.139 + @prototype 9.6
1.140 + Register a receive buffer with this Slave channel.
1.141 +
1.142 + @param aChannelId The channel identifier cookie for this client.
1.143 + @param aRxBuffer A pointer to the receive buffer, in a client created descriptor.
1.144 + @param aBufGranularity The number of buffer bytes used to store a word.
1.145 + @param aNumWords The number of words expected to be received.
1.146 + @param aOffset The offset from the start of the buffer where to store the received data.
1.147 +
1.148 + @return KErrNone, if succesfully registered;
1.149 + KErrAlreadyExists if a receive buffer is already pending;
1.150 + KErrArgument, if aChannelId is not a valid cookie, or if the pointer descriptor is NULL;
1.151 + */
1.152 + IMPORT_C static TInt RegisterRxBuffer(TInt aChannelId, TPtr8 aRxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);
1.153 +
1.154 + /**
1.155 + @publishedPartner
1.156 + @prototype 9.6
1.157 + Register a transmit buffer with this Slave channel.
1.158 + This client may create a single buffer for the entire transaction and control where the received data
1.159 + is to be placed and the transmit data is to be found, by specifying the number of bytes to transmit (receive)
1.160 + and the offset into the buffer.
1.161 +
1.162 + @param aChannelId The channel identifier cookie for this client.
1.163 + @param aTxBuffer A pointer to the transmit buffer, in a client created descriptor.
1.164 + @param aBufGranularity The number of buffer bytes used to store a word.
1.165 + @param aNumWords The number of words to be transmitted.
1.166 + @param aOffset The offset from the start of the buffer where to fetch the data to be transmitted.
1.167 +
1.168 + @return KErrNone, if successfully registered;
1.169 + KErrAlreadyExists if a transmit buffer is already pending;
1.170 + KErrArgument, if aChannelId is not a valid cookie, or if the pointer descriptor is NULL;
1.171 + */
1.172 + IMPORT_C static TInt RegisterTxBuffer(TInt aChannelId, TPtr8 aTxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);
1.173 +
1.174 + /**
1.175 + @publishedPartner
1.176 + @prototype 9.6
1.177 + Sets the notification triggers and readies the receive path and/or kick starts a transmit (if the node is being addressed).
1.178 + 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).
1.179 + If a transmit buffer has been registered and this API has been called the channel will immediately transmit when addressed by the Master
1.180 + If the channel supports full duplex, both paths can be readied in one call to this API.
1.181 +
1.182 + @param aChannelId The channel identifier cookie for this client.
1.183 + @param aTrigger A bitmask specifying the notification trigger. Masks for individual triggers are specified by the TIicBusSlaveTrigger enumeration.
1.184 +
1.185 + @return KErrNone, if successful;
1.186 + KErrArgument, if aChannelId is not a valid cookie, or if the trigger is invalid for this channel;
1.187 + KErrInUse if a transaction is already underway on this channel;
1.188 + KErrTimedOut, if the client exceeded the alloted time to respond by invoking this API;
1.189 + */
1.190 + IMPORT_C static TInt SetNotificationTrigger(TInt aChannelId, TInt aTrigger);
1.191 +
1.192 + /**
1.193 + @publishedPartner
1.194 + @prototype 9.6
1.195 + Interface to provide extended functionality
1.196 +
1.197 + @param aId A token containing the bus realisation variability or the channel identifier cookie for this client.
1.198 + @param aFunction A function identifier. If bit 31 is set and bit 30 cleared it is used to extend the Master-Slave channel;
1.199 + if bit 31 is cleared and bit 30 is set, it extends the Master channel; if both bits 31 and 30 are cleared it
1.200 + extends the Slave channel interface.
1.201 + @param aParam1 A generic argument to be passed to the function identified by aFunction.
1.202 + @param aParam2 A generic argument to be passed to the function identified by aFunction.
1.203 +
1.204 + @return KErrNone, if successful;
1.205 + KErrNotSupported, function is not supported;
1.206 + Any other system wide error code.
1.207 + */
1.208 + IMPORT_C static TInt StaticExtension(TUint aId, TUint aFunction, TAny* aParam1, TAny* aParam2);
1.209 + };
1.210 +
1.211 +// Forward declaration
1.212 +class DIicBusChannel;
1.213 +class DIicBusChannelSearcher;
1.214 +
1.215 +NONSHARABLE_CLASS(DIicBusController) : public DBase
1.216 + {
1.217 +public:
1.218 + // constructor
1.219 + inline DIicBusController() {};
1.220 + ~DIicBusController();
1.221 +
1.222 + TInt Create();
1.223 +
1.224 + /**
1.225 + @publishedPartner
1.226 + @prototype 9.6
1.227 + Interface to be used by Channel implementations to register a list of supported channels. This method
1.228 + will check if the array of pointers to channels is already being modified and, if so, will return KErrInUse.
1.229 + Otherwise, the iArrayBusy flag will be set and each entry in the list inserted into the array according
1.230 + to a sorting algorithm; the iArrayBusy flag will then be cleared after inserting the last entry.
1.231 +
1.232 + @param aListChannels A pointer to a linked list of DIicBusChannel instances to be registered
1.233 + @param aNumberChannels The number of channels to be registered.
1.234 +
1.235 + @return KErrNone, if successful;
1.236 + KErrInUse, if the array of pointers to channels is already being modified;
1.237 + Any other system wide error code.
1.238 + */
1.239 + IMPORT_C static TInt RegisterChannels(DIicBusChannel** aListChannels, TInt aNumberChannels);
1.240 +
1.241 + /**
1.242 + @publishedPartner
1.243 + @prototype 9.6
1.244 + Interface to be used by Channel implementations to deregister a channel. This method
1.245 + will check if the array of pointers to channels is already being modified and, if so, will return KErrInUse.
1.246 + Otherwise, the channel will be removed from the array according to a sorting algorithm; the iArrayBusy
1.247 + flag will be set before searching for the channel and cleared immediately after removing it.
1.248 +
1.249 + @param aListChannels A pointer to a linked list of DIicBusChannel instances to be registered
1.250 + @param aNumberChannels The number of channels to be registered.
1.251 +
1.252 + @return KErrNone, if successful;
1.253 + KErrInUse, if the array of pointers to channels is already being modified;
1.254 + KErrArgument, if aChannel is a NULL pointer or represents and invalid channel type
1.255 + KErrNotFound, if aChannel is not found in the array of pointers to channels
1.256 + Any other system wide error code.
1.257 + */
1.258 + IMPORT_C static TInt DeRegisterChannel(DIicBusChannel* aChannel);
1.259 +
1.260 + // implementation of public interface APIs
1.261 + TInt QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction);
1.262 + TInt QueueTransaction(TInt aBusId, TIicBusTransaction* aTransaction, TIicBusCallback* aCallback);
1.263 + TInt CancelTransaction(TInt aBusId, TIicBusTransaction* aTransaction);
1.264 + TInt CaptureChannel(TInt aBusId, TDes8* aConfigHdr, TIicBusSlaveCallback* aCallback, TInt& aChannelId, TBool aAsynch);
1.265 + TInt ReleaseChannel(TInt aChannelId);
1.266 + TInt RegisterRxBuffer(TInt aChannelId, TPtr8 aRxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);
1.267 + TInt RegisterTxBuffer(TInt aChannelId, TPtr8 aTxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);
1.268 + TInt SetNotificationTrigger(TInt aChannelId, TInt aTrigger);
1.269 + TInt StaticExtension(TUint aId, TUint aFunction, TAny* aParam1, TAny* aParam2);
1.270 +
1.271 + static TInt OrderEntries(const DIicBusChannel& aMatch, const DIicBusChannel& aEntry);
1.272 +
1.273 +private:
1.274 + TInt GetSlaveChanPtr(TInt aChannelId, DIicBusChannelSlave*& aSlaveChanPtr);
1.275 + TInt GetChanPtr(const TInt aBusId, TInt &aIndex, DIicBusChannel*& aChan);
1.276 +
1.277 + inline RPointerArray<DIicBusChannel>* ChannelArray();
1.278 +
1.279 + TInt GetChanWriteAccess();
1.280 + void FreeChanWriteAccess();
1.281 + TInt GetChanReadAccess();
1.282 + void FreeChanReadAccess();
1.283 +
1.284 + TInt RequestTypeSupported(const TInt aBusId, DIicBusChannelMaster* const aChannel);
1.285 +
1.286 +public:
1.287 + /**
1.288 + @internalComponent
1.289 + @prototype 9.6
1.290 + Class used by DIicBusController for locating channels captured by clients for Slave Mode operation
1.291 + */
1.292 + class TCapturedChannel // Generated by DIicBusChannelSlave
1.293 + {
1.294 + public:
1.295 + inline TCapturedChannel();
1.296 + inline TCapturedChannel(TInt aChannelId, DIicBusChannelSlave* aChanPtr);
1.297 +
1.298 + inline TCapturedChannel& operator=(TCapturedChannel& aChan);
1.299 + inline TInt operator==(TCapturedChannel& aChan);
1.300 +
1.301 + public:
1.302 + TInt iChannelId; // ID to be used by client
1.303 + DIicBusChannelSlave* iChanPtr; // Index to iChannelArray
1.304 + };
1.305 +public:
1.306 + /**
1.307 + @internalTechnology
1.308 + @prototype 9.6
1.309 + Function to register a Slave channel with DIicBusController as captured
1.310 + */
1.311 + virtual TInt InstallCapturedChannel(const TInt aChannelId, const DIicBusChannelSlave* aChanPtr);
1.312 +private:
1.313 + RPointerArray<DIicBusChannel> iChannelArray;
1.314 + TCapturedChannel iCapturedChannels[KMaxNumCapturedChannels];
1.315 + TInt InsertCaptChanInArray(TCapturedChannel aCapturedChan);
1.316 + TInt RemoveCaptChanFromArray(TCapturedChannel aCapturedChan);
1.317 + TInt FindCapturedChan(TCapturedChannel aCapturedChan, TInt& aIndex);
1.318 + TInt FindCapturedChanById(TCapturedChannel aCapturedChan, TInt& aIndex);
1.319 +
1.320 + TInt DeInstallCapturedChannel(const TInt aChannelId, const DIicBusChannelSlave* aChanPtr);
1.321 +
1.322 +#ifdef _DEBUG
1.323 + void DumpCapturedChannels();
1.324 + void DumpChannelArray();
1.325 +#endif
1.326 +
1.327 +private:
1.328 + enum TArrayActivity
1.329 + {
1.330 + EWriteInProgress=0x1,
1.331 + EReadInProgress=0x2
1.332 + };
1.333 +
1.334 + TSpinLock *iChanLock;
1.335 + TUint32 iChanRdCount; // Maximum 32-bit count for concurrent reads
1.336 + TSpinLock *iCaptLock;
1.337 +
1.338 + TInt8 iChanRwFlags; // Bit 0 for write, bit 1 for read
1.339 + };
1.340 +
1.341 +#ifdef IIC_SIMULATED_PSL
1.342 +_LIT(KPddName,"iic.pdd");
1.343 +
1.344 +NONSHARABLE_CLASS(DIicPdd) : public DPhysicalDevice
1.345 + {
1.346 +// Class to faciliate loading of the IIC classes
1.347 +public:
1.348 + class TCaps
1.349 + {
1.350 + public:
1.351 + TVersion iVersion;
1.352 + };
1.353 +public:
1.354 + DIicPdd();
1.355 + ~DIicPdd();
1.356 + virtual TInt Install();
1.357 + virtual TInt Create(DBase*& aChannel, TInt aUnit, const TDesC8* anInfo, const TVersion& aVer);
1.358 + virtual TInt Validate(TInt aUnit, const TDesC8* anInfo, const TVersion& aVer);
1.359 + virtual void GetCaps(TDes8& aDes) const;
1.360 + inline static TVersion VersionRequired();
1.361 + };
1.362 +#endif
1.363 +
1.364 +#include <drivers/iic.inl>
1.365 +
1.366 +#endif // #ifndef __IIC_H__
1.367 +