1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/include/drivers/iic_channel.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,901 @@
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_channel.h
1.18 +// Include file for channel implementation
1.19 +//
1.20 +// WARNING: This file contains some APIs which are internal and are subject
1.21 +// to change without notice. Such APIs should therefore not be used
1.22 +// outside the Kernel and Hardware Services package.
1.23 +
1.24 +/**
1.25 +@file
1.26 +@internalTechnology
1.27 +*/
1.28 +#ifndef __IIC_CHANNEL_H__
1.29 +#define __IIC_CHANNEL_H__
1.30 +
1.31 +#ifdef STANDALONE_CHANNEL
1.32 +#include <drivers/iic_transaction.h>
1.33 +#else
1.34 +#include <drivers/iic.h>
1.35 +#endif
1.36 +
1.37 +static const char KIicChannelPanic[]="Iic Channel PIL";
1.38 +
1.39 +const static TInt KChannelTypeMask = 0x03;
1.40 +const static TInt KBusTypeShift = 2;
1.41 +const static TInt KBusTypeMask = 0x07<<KBusTypeShift; // number of buses may grow in future
1.42 +const static TInt KChannelDuplexShift= 5;
1.43 +const static TInt KChannelDuplexMask = 0x01<<KChannelDuplexShift;
1.44 +const static TInt16 KTransCountMsBit = (TInt16)((TUint16)0x8000);
1.45 +
1.46 +const static TInt8 KMaxWaitTime = 0x21; // Maximum allowable time in milliseconds for a Slave channel to wait for a response
1.47 + // (from Master or Client). This constant is used to limit run-time selected values
1.48 + // for timeouts. The value stated here is semi-arbitrary.
1.49 +
1.50 +#ifdef IIC_SIMULATED_PSL
1.51 +// In a real system, the following timeout values are likely to be excessive. However, they are available
1.52 +// for use in the test framework, to account for the processing overhead.
1.53 +const TInt KSlaveDefMWaitTime = 32;
1.54 +const TInt KSlaveDefCWaitTime = 16;
1.55 +#else
1.56 +const TInt KSlaveDefMWaitTime = 1; // Default wait time for Master timeout. PSL can use SetMasterWaitTime to override.
1.57 +const TInt KSlaveDefCWaitTime = 1; // Default wait time for Client timeout. PSL can use SetClientWaitTime to override.
1.58 +#endif
1.59 +
1.60 +
1.61 +/**
1.62 +@internalComponent
1.63 +@prototype 9.6
1.64 +Base class for a Channel (not directly instantiable)
1.65 +*/
1.66 +class DIicBusChannel : public DBase
1.67 + {
1.68 +public:
1.69 + enum TChannelType
1.70 + {
1.71 + EMaster = 0,
1.72 + ESlave = 0x01,
1.73 + EMasterSlave = 0x02
1.74 + };
1.75 + enum TBusType
1.76 + {
1.77 + EI2c = 0,
1.78 + ESpi = 0x01,
1.79 + EMicrowire = 0x02,
1.80 + ECci = 0x03,
1.81 + ESccb = 0x04
1.82 + };
1.83 + enum TChannelDuplex
1.84 + {
1.85 + EHalfDuplex = 0, // supports only half duplex transactions (even if bus spec supports full duplex)
1.86 + EFullDuplex = 0x1 // supports full duplex transactions (queud transactions may still be half duplex)
1.87 + };
1.88 +
1.89 +public:
1.90 + virtual TInt StaticExtension(TUint aFunction, TAny* /*aParam1*/, TAny* /*aParam2*/)
1.91 + {
1.92 +#ifdef _DEBUG
1.93 + if(aFunction == KCtrlIoDumpChan)
1.94 + {
1.95 + DumpChannel();
1.96 + return KErrNone;
1.97 + }
1.98 + else
1.99 +#else
1.100 + (void)aFunction;
1.101 +#endif
1.102 +
1.103 + return KErrNotSupported;
1.104 + };
1.105 +protected:
1.106 + // constructor
1.107 + inline DIicBusChannel(TChannelType aChanType, TBusType aBusType, TChannelDuplex aChanDuplex);
1.108 + // second phase construction - empty, to be implemented by derived types if required
1.109 + virtual TInt DoCreate()=0;
1.110 +
1.111 + // helper function to read an set flags
1.112 + inline TChannelType ChannelType();
1.113 + inline void SetChannelType(TChannelType aChanType);
1.114 + inline TBusType BusType();
1.115 + inline void SetBusType(TBusType aBusType);
1.116 + inline TChannelDuplex ChannelDuplex();
1.117 + inline void SetChannelType(TChannelDuplex aChanDuplex);
1.118 + inline TInt8 ChannelNumber() const;
1.119 +
1.120 + virtual TInt CheckHdr(TDes8* aHdr) = 0; // PSL to check the header is valid for this channel
1.121 +protected:
1.122 +#ifdef _DEBUG
1.123 + inline void DumpChannel();
1.124 +#endif
1.125 +protected:
1.126 + NTimer iTimeoutTimer; // timeout timer
1.127 + TInt8 iChannelNumber; // this is the Key for ordering channels in the array
1.128 + TUint8 iFlags; // combination of TChannelType, TChannelDuplex and TBusType
1.129 + TInt8 iSpare1;
1.130 + TInt8 iSpare2;
1.131 +private:
1.132 + TAny* iReserved;
1.133 +
1.134 + friend class DIicBusController;
1.135 + };
1.136 +
1.137 +/**
1.138 +@publishedPartner
1.139 +@prototype 9.6
1.140 +
1.141 +Base class for a Master Channel (not directly instantiable)
1.142 +
1.143 +*/
1.144 +class DIicBusChannelMaster : public DIicBusChannel
1.145 + {
1.146 +public:
1.147 + // interface to Bus Controller (implemented by PIL)
1.148 + // For stand-alone channel, there is no controller. So some parts of
1.149 + // the interface are exported for client direct use.
1.150 + /**
1.151 + @publishedPartner
1.152 + @prototype 9.6
1.153 + Master channel interface to queue a transaction synchronously.
1.154 +
1.155 + @param aTransaction A pointer to a transaction object containing the details of the transaction.
1.156 +
1.157 + @return KErrNone, when successfully completed;
1.158 + KErrArgument, if aTransaction is NULL;
1.159 + KErrTimedOut, if the channel terminates the transaction because the addressed Slave exceeded the alloted time to respond;
1.160 + 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.161 + */
1.162 + virtual TInt QueueTransaction(TIicBusTransaction* aTransaction);
1.163 + /**
1.164 + @publishedPartner
1.165 + @prototype 9.6
1.166 + Master channel interface to queue a transaction asynchronously.
1.167 +
1.168 + @param aTransaction A pointer to a transaction object containing the details of the transaction.
1.169 + @param aCallback A pointer to a callback object.
1.170 +
1.171 + @return KErrNone, if successfully accepted; KErrArgument, if either aTransaction or aCallback are NULL;
1.172 + 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.173 + */
1.174 + virtual TInt QueueTransaction(TIicBusTransaction* aTransaction, TIicBusCallback* aCallback);
1.175 + /**
1.176 + @publishedPartner
1.177 + @prototype 9.6
1.178 + Master channel interface to cancel a previously queued transaction.
1.179 +
1.180 + @param aTransaction A pointer to a transaction object containing the details of the transaction.
1.181 +
1.182 + @return KErrCancel, if successfully cancelled; KErrArgument, if aTransaction is NULL;
1.183 + KErrNotFound if the transaction cannot be found on channel's queue of transactions;
1.184 + KErrInUse if this method is called on a transaction that has already been started;
1.185 + KErrNotSupported, if the channel does not support Master mode, or the method is called on a synchronous transaction..
1.186 + */
1.187 + virtual TInt CancelTransaction(TIicBusTransaction* aTransaction);
1.188 + /**
1.189 + @publishedPartner
1.190 + @prototype 9.6
1.191 + Master channel interface interface to provide extended functionality
1.192 +
1.193 + @param aFunction A function identifier. If bit 31 is set and bit 30 cleared it is used to extend the Master-Slave channel;
1.194 + 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.195 + extends the Slave channel interface.
1.196 + @param aParam1 A generic argument to be passed to the function identified by aFunction.
1.197 + @param aParam2 A generic argument to be passed to the function identified by aFunction.
1.198 +
1.199 + @return KErrNone, if successful;
1.200 + KErrNotSupported, function is not supported;
1.201 + Any other system wide error code.
1.202 + */
1.203 + virtual TInt StaticExtension(TUint aFunction, TAny* aParam1, TAny* aParam2);
1.204 +
1.205 +//
1.206 + virtual TInt Spare1(TInt aVal, TAny* aPtr1, TAny* aPtr2);
1.207 +
1.208 + /**
1.209 + @publishedPartner
1.210 + @prototype 9.6
1.211 + Destructor for DIicBusChannelMaster
1.212 + */
1.213 + ~DIicBusChannelMaster();
1.214 +
1.215 +protected:
1.216 + // PSL implemented
1.217 + /**
1.218 + @publishedPartner
1.219 + @prototype 9.6
1.220 + Gateway function for PSL implementation (to be called by the interface APIs)
1.221 + */
1.222 + virtual TInt DoRequest(TIicBusTransaction* aTransaction) = 0;
1.223 + /**
1.224 + @publishedPartner
1.225 + @prototype 9.6
1.226 + Function to be invoked in the event of a Slave timeout. May be overridden by the PSL.
1.227 + */
1.228 + virtual TInt HandleSlaveTimeout() = 0;
1.229 + /**
1.230 + @publishedPartner
1.231 + @prototype 9.6
1.232 + Second phase constructor to be implemented by the PSL
1.233 + */
1.234 + virtual TInt DoCreate() = 0;
1.235 +
1.236 + // Called by PSL
1.237 + /**
1.238 + @publishedPartner
1.239 + @prototype 9.6
1.240 +
1.241 + Constructor for DIicBusChannelMaster
1.242 +
1.243 + @param aBusType Argument to specify the type of Bus
1.244 + @param aChanDuplex Argument to specify the duplex support offered by this channel
1.245 + */
1.246 + DIicBusChannelMaster(TBusType aBusType, TChannelDuplex aChanDuplex);
1.247 + /**
1.248 + @publishedPartner
1.249 + @prototype 9.6
1.250 + Function to instigate DIicBusChannel initialisation
1.251 +
1.252 + @return KErrNone if no error
1.253 + KErrNoMemory if allocation of required objects
1.254 + */
1.255 + TInt Init();
1.256 + /**
1.257 + @publishedPartner
1.258 + @prototype 9.6
1.259 +
1.260 + Function to start the timer to check the Slave responsiveness.
1.261 +
1.262 + @param aTime Timeout in milliseconds
1.263 +
1.264 + @return KErrNone if no error,
1.265 + KErrInUse if timer is already active.
1.266 +
1.267 + */
1.268 + TInt StartSlaveTimeOutTimer(TInt aTime);
1.269 + /**
1.270 + @publishedPartner
1.271 + @prototype 9.6
1.272 +
1.273 + Function to specify the DFC queue for the channel to use
1.274 +
1.275 + @param aDfcQue Pointer to the DFC queue to use
1.276 +
1.277 + */
1.278 + void SetDfcQ(TDfcQue* aDfcQue);
1.279 + /**
1.280 + @publishedPartner
1.281 + @prototype 9.6
1.282 +
1.283 + Function to Complete the transaction being processed by the channel
1.284 +
1.285 + @param aResult Error code to complete the transaction with
1.286 +
1.287 + */
1.288 + void CompleteRequest(TInt aResult);
1.289 + /**
1.290 + @publishedPartner
1.291 + @prototype 9.6
1.292 +
1.293 + Function to cancel the timer to check the Slave responsiveness.
1.294 +
1.295 + */
1.296 + void CancelTimeOut();
1.297 +
1.298 + // Methods to make private data of TIicBusTransaction object accessible to derivatives of this class
1.299 + /**
1.300 + @publishedPartner
1.301 + @prototype 9.6
1.302 +
1.303 + Function to return the Transaction Header of a specified TIicBusTransaction object
1.304 +
1.305 + @return The Transaction Header of the specified TIicBusTransaction object
1.306 +
1.307 + @see TIicBusTransaction
1.308 + */
1.309 + static inline TDes8* GetTransactionHeader(const TIicBusTransaction* aTransaction);
1.310 + /**
1.311 + @publishedPartner
1.312 + @prototype 9.6
1.313 +
1.314 + Function to return the Half Duplex Transfer pointer of a specified TIicBusTransaction object
1.315 +
1.316 + @return The Half Duplex Transfer pointer of the specified TIicBusTransaction object
1.317 +
1.318 + @see TIicBusTransaction
1.319 + */
1.320 + static inline TIicBusTransfer* GetTransHalfDuplexTferPtr(const TIicBusTransaction* aTransaction);
1.321 + /**
1.322 + @publishedPartner
1.323 + @prototype 9.6
1.324 +
1.325 + Function to return the Full Duplex Transfer pointer of a specified TIicBusTransaction object
1.326 +
1.327 + @return The Full Duplex Transfer pointer of the specified TIicBusTransaction object
1.328 +
1.329 + @see TIicBusTransaction
1.330 + */
1.331 + static inline TIicBusTransfer* GetTransFullDuplexTferPtr(const TIicBusTransaction* aTransaction);
1.332 + /**
1.333 + @publishedPartner
1.334 + @prototype 9.6
1.335 +
1.336 + Function to return the address of the callback object of a specified TIicBusTransaction object
1.337 +
1.338 + @return The address of the callback object of the specified TIicBusTransaction object
1.339 +
1.340 + @see TIicBusTransaction
1.341 + */
1.342 + static inline TIicBusCallback* GetTransCallback(const TIicBusTransaction* aTransaction);
1.343 + /**
1.344 + @publishedPartner
1.345 + @prototype 9.6
1.346 +
1.347 + Function to return the value of the TransFlags member of a specified TIicBusTransaction object
1.348 +
1.349 + @return The value of the TransFlags member of the specified TIicBusTransaction object
1.350 +
1.351 + @see TIicBusTransaction
1.352 + */
1.353 + static inline TUint8 GetTransFlags(const TIicBusTransaction* aTransaction);
1.354 +
1.355 + // Methods to make private data of TIicBusTransfer object accessible to derivatives of this class
1.356 + /**
1.357 + @publishedPartner
1.358 + @prototype 9.6
1.359 +
1.360 + Function to return Transfer Type the of a specified TIicBusTransfer object
1.361 +
1.362 + @return The Transfer Type of the specified TIicBusTransfer object
1.363 +
1.364 + @see TIicBusTransfer
1.365 + */
1.366 + static inline TInt8 GetTferType(const TIicBusTransfer* aTransfer);
1.367 + /**
1.368 + @publishedPartner
1.369 + @prototype 9.6
1.370 +
1.371 + Function to return the Buffer Granularity of a specified TIicBusTransfer object
1.372 +
1.373 + @return The Buffer Granularity of the specified TIicBusTransfer object
1.374 +
1.375 + @see TIicBusTransfer
1.376 + */
1.377 + static inline TInt8 GetTferBufGranularity(const TIicBusTransfer* aTransfer);
1.378 + /**
1.379 + @publishedPartner
1.380 + @prototype 9.6
1.381 +
1.382 + Function to return the descriptor for the data for a specified TIicBusTransfer object
1.383 +
1.384 + @return The descriptor for the data for the specified TIicBusTransfer object
1.385 +
1.386 + @see TIicBusTransfer
1.387 + */
1.388 + static inline const TDes8* GetTferBuffer(const TIicBusTransfer* aTransfer);
1.389 + /**
1.390 + @publishedPartner
1.391 + @prototype 9.6
1.392 +
1.393 + Function to return the address of the next transfer for a specified TIicBusTransfer object
1.394 +
1.395 + @return The address of the next transfer for the specified TIicBusTransfer object
1.396 +
1.397 + @see TIicBusTransfer
1.398 + */
1.399 + static inline TIicBusTransfer* GetTferNextTfer(const TIicBusTransfer* aTransfer);
1.400 +
1.401 + // Methods to make private data of TIicBusTransactionPreamble object accessible to derivatives of this class
1.402 + /**
1.403 + @publishedPartner
1.404 + @prototype 9.6
1.405 +
1.406 + Function to return the function pointer for a specified TIicBusTransactionPreamble object
1.407 +
1.408 + @return The function pointer for the specified TIicBusTransactionPreamble object
1.409 +
1.410 + @see TIicBusTransactionPreamble
1.411 + */
1.412 + static inline TIicBusPreamble GetPreambleFuncPtr(const TIicBusTransactionPreamble* aTransfer);
1.413 + /**
1.414 + @publishedPartner
1.415 + @prototype 9.6
1.416 +
1.417 + Function to return the function argument for a specified TIicBusTransactionPreamble object
1.418 +
1.419 + @return The function argument for the specified TIicBusTransactionPreamble object
1.420 +
1.421 + @see TIicBusTransactionPreamble
1.422 + */
1.423 + static inline TAny* GetPreambleFuncArg(const TIicBusTransactionPreamble* aTransfer);
1.424 +
1.425 + /**
1.426 + @publishedPartner
1.427 + @prototype 9.6
1.428 +
1.429 + Function to return the function pointer of a specified TIicBusTransactionMultiTransc object
1.430 +
1.431 + @return The function pointer of the specified TIicBusTransactionMultiTransc object
1.432 +
1.433 + @see TIicBusTransactionMultiTransc
1.434 + */
1.435 + static inline TIicBusMultiTranscCbFn GetMultiTranscFuncPtr(const TIicBusTransactionMultiTransc* aTransfer);
1.436 + /**
1.437 + @publishedPartner
1.438 + @prototype 9.6
1.439 +
1.440 + Function to return the function argument of a specified TIicBusTransactionMultiTransc object
1.441 +
1.442 + @return The function argument of the specified TIicBusTransactionMultiTransc object
1.443 +
1.444 + @see TIicBusTransactionMultiTransc
1.445 + */
1.446 + static inline TAny* GetMultiTranscFuncArg(const TIicBusTransactionMultiTransc* aTransfer);
1.447 +
1.448 + /**
1.449 + @publishedPartner
1.450 + @prototype 9.6
1.451 +
1.452 + Function to return the function pointer of a specified TIicBusTransactionPreambleExt object
1.453 +
1.454 + @return The function pointer of the specified TIicBusTransactionPreambleExt object
1.455 +
1.456 + @see TIicBusTransaction
1.457 + */
1.458 + static inline TIicBusMultiTranscCbFn GetExtTranscFuncPtr(const TIicBusTransactionPreambleExt* aTransfer);
1.459 + /**
1.460 + @publishedPartner
1.461 + @prototype 9.6
1.462 +
1.463 + Function to return the function argument of a specified TIicBusTransactionPreambleExt object
1.464 +
1.465 + @return The function argument of the specified TIicBusTransactionPreambleExt object
1.466 +
1.467 + @see TIicBusTransaction
1.468 + */
1.469 + static inline TAny* GetExtTranscFuncArg(const TIicBusTransactionPreambleExt* aTransfer);
1.470 +
1.471 +private:
1.472 + // Function to acquire the NFastMutex of the channel
1.473 + void Lock();
1.474 + // Function to release the NFastMutex of the channel
1.475 + void Unlock();
1.476 +
1.477 + // function to run on receiving a message
1.478 + static void MsgQFunc(TAny* aPtr);
1.479 +
1.480 + TIicBusTransaction* NextTrans(TIicBusTransaction* aTrans);
1.481 + void EndTransaction(TIicBusTransaction* aTrans, TInt aResult, TIicBusCallback* aCb);
1.482 + void Complete(TInt aResult, TIicBusTransaction* aTransaction);
1.483 + void UnlockAndKick();
1.484 +
1.485 + static void SlaveTimeoutCallback(TAny*);
1.486 +
1.487 + // Used by DIidBusController (a friend of this class)
1.488 + TInt TransFlow(TIicBusTransaction* aTransaction);
1.489 +
1.490 + TInt8 IsMasterBusy();
1.491 +
1.492 +protected:
1.493 + TDfcQue* iDfcQ;
1.494 +
1.495 +private:
1.496 + TDfc iTransQDfc;
1.497 + SOrdQue iTransactionQ;
1.498 + TIicBusTransaction* iTransaction; // Pointer to current transaction
1.499 + TIicBusTransaction* iCurrentTransaction; // Pointer to current fragment of a multiple transaction
1.500 +
1.501 + NFastMutex iTransactionQLock;
1.502 +
1.503 + TDfc* iSlaveTimeoutDfc;
1.504 +
1.505 + TInt16 iTransCount; // Count of pending transactions
1.506 + TInt8 iChannelReady;
1.507 + TInt8 iSpare1;
1.508 +
1.509 +private:
1.510 + TAny* iReserved1;
1.511 + TAny* iReserved2;
1.512 +
1.513 + friend class DIicBusChannelMasterSlave;
1.514 + friend class DIicBusController; // For static method DIicBusController::DeRegisterChannel
1.515 + };
1.516 +
1.517 +
1.518 +/**
1.519 +@publishedPartner
1.520 +@prototype 9.6
1.521 +
1.522 +Base class for a Slave Channel (not directly instantiable)
1.523 +
1.524 +*/
1.525 +class DIicBusChannelSlave : public DIicBusChannel
1.526 + {
1.527 +protected:
1.528 + /**
1.529 + @publishedPartner
1.530 + @prototype 9.6
1.531 + The set of operation values for processing by the PSL
1.532 + */
1.533 + enum TPslOperation
1.534 + {
1.535 + ESyncConfigPwrUp = 0x01,
1.536 + EAsyncConfigPwrUp = 0x02,
1.537 + EPowerDown = 0x04,
1.538 + ETransmit = 0x08,
1.539 + EReceive = 0x10,
1.540 + EAbort = 0x20
1.541 + };
1.542 +private:
1.543 + // Values used by the internal state machine
1.544 + enum TSlaveTimerStates
1.545 + {
1.546 + EInactive = 0x01,
1.547 + EWaitForMaster = 0x02,
1.548 + EWaitForClient = 0x04,
1.549 + EClientTimeout = 0x08
1.550 + };
1.551 +
1.552 +public:
1.553 +
1.554 + // Interface to Controller.
1.555 + // For stand-alone channel, the interface is exported.
1.556 + /**
1.557 + @publishedPartner
1.558 + @prototype 9.6
1.559 + Capture this Slave channel.
1.560 +
1.561 + @param aConfigHdr A pointer to a descriptor containing the device specific configuration option applicable to all transactions.
1.562 + @param aCallback A pointer to a callback to be called upon specified triggers.
1.563 + @param aChannelId If this API is to complete synchronously, and the processing was successful, then on return aChannelId
1.564 + contains a platform-specific cookie that uniquely identifies the channel instance to be used by this client.
1.565 + If the processing was unsuccessful for the synchronous completion case, aChannelId will be unchanged.
1.566 + If the API was called to complete asynchronously, aChannelId will, in all cases, be set to zero; the valid
1.567 + value for the cookie will be set by the callback.
1.568 + @param aAsynch A boolean value that indicates if this API is to complete synchronously (EFalse) or asynchronously (ETrue).
1.569 +
1.570 + @return KErrNone, if successfully captured, or if API is asynchronous, if the request to capture the channel was accepted;
1.571 + KErrInUse if channel is already in use; KErrArgument, if aCallback is NULL;
1.572 + KErrNotSupported, if the channel does not support Slave mode.
1.573 + */
1.574 + virtual TInt CaptureChannel(TDes8* aConfigHdr, TIicBusSlaveCallback* aCallback, TInt& aChannelId, TBool aAsynch);
1.575 + /**
1.576 + @publishedPartner
1.577 + @prototype 9.6
1.578 + Release this previously captured Slave channel.
1.579 +
1.580 + @return KErrNone, if successfully released;
1.581 + KErrInUse if a transaction is currently underway on this channel; KErrArgument
1.582 + */
1.583 + virtual TInt ReleaseChannel();
1.584 + /**
1.585 + @publishedPartner
1.586 + @prototype 9.6
1.587 + Register a receive buffer with this Slave channel.
1.588 +
1.589 + @param aRxBuffer A pointer to the receive buffer, in a client created descriptor.
1.590 + @param aBufGranularity The number of buffer bytes used to store a word.
1.591 + @param aNumWords The number of words expected to be received.
1.592 + @param aOffset The offset from the start of the buffer where to store the received data.
1.593 +
1.594 + @return KErrNone, if successfully registered;
1.595 + KErrAlreadyExists if a receive buffer is already pending;
1.596 + KErrArgument, if the pointer descriptor is NULL;
1.597 + */
1.598 + virtual TInt RegisterRxBuffer(TPtr8 aRxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);
1.599 + /**
1.600 + @publishedPartner
1.601 + @prototype 9.6
1.602 + Register a transmit buffer with this Slave channel.
1.603 + This client may create a single buffer for the entire transaction and control where the received data
1.604 + is to be placed and the transmit data is to be found, by specifying the number of bytes to transmit (receive)
1.605 + and the offset into the buffer.
1.606 +
1.607 + @param aTxBuffer A pointer to the transmit buffer, in a client created descriptor.
1.608 + @param aBufGranularity The number of buffer bytes used to store a word.
1.609 + @param aNumWords The number of words to be transmitted.
1.610 + @param aOffset The offset from the start of the buffer where to fetch the data to be transmitted.
1.611 +
1.612 + @return KErrNone, if successfully registered;
1.613 + KErrAlreadyExists if a transmit buffer is already pending;
1.614 + KErrArgument, if the pointer descriptor is NULL;
1.615 + */
1.616 + virtual TInt RegisterTxBuffer(TPtr8 aTxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);
1.617 + /**
1.618 + @publishedPartner
1.619 + @prototype 9.6
1.620 + Sets the notification triggers and readies the receive path and/or kick starts a transmit (if the node is being addressed).
1.621 + 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.622 + If a transmit buffer has been registered and this API has been called the channel will immediately transmit when addressed by the Master
1.623 + If the channel supports full duplex, both paths can be readied in one call to this API.
1.624 +
1.625 + @param aTrigger A bitmask specifying the notification trigger. Masks for individual triggers are specified by the TIicBusSlaveTrigger enumeration.
1.626 +
1.627 + @return KErrNone, if successful;
1.628 + KErrArgument, if the trigger is invalid for this channel;
1.629 + KErrInUse if a transaction is already underway on this channel;
1.630 + KErrTimedOut, if the client exceeded the alloted time to respond by invoking this API;
1.631 + */
1.632 + virtual TInt SetNotificationTrigger(TInt aTrigger);
1.633 + /**
1.634 + @publishedPartner
1.635 + @prototype 9.6
1.636 + Interface to provide extended functionality
1.637 +
1.638 + @param aFunction A function identifier. If bit 31 is set and bit 30 cleared it is used to extend the Master-Slave channel;
1.639 + 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.640 + extends the Slave channel interface.
1.641 + @param aParam1 A generic argument to be passed to the function identified by aFunction.
1.642 + @param aParam2 A generic argument to be passed to the function identified by aFunction.
1.643 +
1.644 + @return KErrNone, if successful;
1.645 + KErrNotSupported, function is not supported;
1.646 + Any other system wide error code.
1.647 + */
1.648 + virtual TInt StaticExtension(TUint aFunction, TAny* aParam1, TAny* aParam2);
1.649 +//
1.650 + /**
1.651 + @internalTechnology
1.652 + @prototype 9.6
1.653 + Function reserved for future use
1.654 + */
1.655 + virtual TInt Spare1(TInt aVal, TAny* aPtr1, TAny* aPtr2);
1.656 +
1.657 + // Interface to TIicBusSlaveCallback
1.658 + // channel-specific function to process data received/transmitted (called from NotifyClient or DFC queued from it)
1.659 + // Must fill in the aCb object's iReturn, iRxWords and/or iTxWords using the appropriate funtions
1.660 + /**
1.661 + @publishedPartner
1.662 + @prototype 9.6
1.663 + Function invoked when an asynchronous event occurs on the Slave channel. Implemented by the PSL.
1.664 + @param aTrigger Argument to indicate the type of event that occurred
1.665 + @param aCb Address of the Slave client callback object to process
1.666 +
1.667 + @return KErrNone, if successful;
1.668 + KErrNotSupported, function is not supported;
1.669 + Any other system wide error code.
1.670 + */
1.671 +#ifdef STANDALONE_CHANNEL
1.672 + friend class TIicBusSlaveCallback;
1.673 +protected:
1.674 + virtual void ProcessData(TInt aTrigger, TIicBusSlaveCallback* aCb) = 0;
1.675 +private:
1.676 + TInt UpdateReqTrig(TInt8& aCbTrigVal, TInt& aCallbackRet);
1.677 + void StartTimerByState();
1.678 + void StopTimer();
1.679 +#else
1.680 +public:
1.681 + virtual void ProcessData(TInt aTrigger, TIicBusSlaveCallback* aCb) = 0;
1.682 + virtual TInt UpdateReqTrig(TInt8& aCbTrigVal, TInt& aCallbackRet);
1.683 + virtual void StartTimerByState();
1.684 + virtual void StopTimer();
1.685 +#endif
1.686 +
1.687 +public:
1.688 + // Values used by the Interface to TIicBusSlaveCallback
1.689 + enum TSlaveNotifProcSteps
1.690 + {
1.691 + EStopTimer = 0x01,
1.692 + EInvokeCb = 0x02,
1.693 + EStartTimer = 0x04
1.694 + };
1.695 +
1.696 +protected:
1.697 + // PSL implemented
1.698 + /**
1.699 + @publishedPartner
1.700 + @prototype 9.6
1.701 +
1.702 + PSL specific second phase constructor
1.703 +
1.704 + @return KErrNone, if succesful;
1.705 + KErrNotSupported, function is not supported;
1.706 + Any other system wide error code.
1.707 + */
1.708 + virtual TInt DoCreate() = 0;
1.709 + /**
1.710 + @publishedPartner
1.711 + @prototype 9.6
1.712 +
1.713 + Gateway function for PSL implementation: aOperation is a bitmask made of TPslOperation (to be called by the interface APIs)
1.714 +
1.715 + @return KErrNone, if succesful;
1.716 + KErrNotSupported, function is not supported;
1.717 + Any other system wide error code.
1.718 + */
1.719 + virtual TInt DoRequest(TInt aOperation) = 0;
1.720 +
1.721 + // Called by PSL
1.722 + /**
1.723 + @publishedPartner
1.724 + @prototype 9.6
1.725 +
1.726 + Constructor for DIicBusChannelSlave
1.727 +
1.728 + @param aBusType Argument to specify the type of Bus
1.729 + @param aChanDuplex Argument to specify the duplex support offered by this channel
1.730 + @param aChannelId Argument to specify the identifier to use for this channel
1.731 + */
1.732 + DIicBusChannelSlave(TBusType aBusType, TChannelDuplex aChanDuplex, TInt16 aChannelId);
1.733 + /**
1.734 + @publishedPartner
1.735 + @prototype 9.6
1.736 + Function to instigate DIicBusChannelSlave initialisation
1.737 +
1.738 + @return KErrNone
1.739 + */
1.740 + TInt Init();
1.741 +
1.742 + /**
1.743 + @publishedPartner
1.744 + @prototype 9.6
1.745 + Destructor for DIicBusChannelSlave
1.746 + */
1.747 + ~DIicBusChannelSlave();
1.748 +
1.749 + /**
1.750 + @publishedPartner
1.751 + @prototype 9.6
1.752 + Function invoked when an asynchronous channel capture completes
1.753 +
1.754 + @param aResult Argument specifying the error code reurned by the capture operation
1.755 +
1.756 + @return KErrNone
1.757 + */
1.758 + void ChanCaptureCallback(TInt aResult);
1.759 + /**
1.760 + @publishedPartner
1.761 + @prototype 9.6
1.762 + Function invoked to instigate processing by the PSL, PIL and Client when an asynchronous event occurs
1.763 +
1.764 + @param aResult Argument specifying the trigger value associated with the asynchronous event
1.765 +
1.766 + @return KErrNone
1.767 + */
1.768 + void NotifyClient(TInt aTrigger);
1.769 +
1.770 + /**
1.771 + @publishedPartner
1.772 + @prototype 9.6
1.773 + Function invoked by the PSL to set the timeout period to wait for a response from the bus master
1.774 +
1.775 + @param aWaitTime Argument specifying the wait time, in milliseconds (limit=KMaxWaitTime)
1.776 +
1.777 + @return KErrNone, if succesful;
1.778 + KErrArgument, if aWaitTime > KMaxWaitTime
1.779 + */
1.780 + TInt SetMasterWaitTime(TInt8 aWaitTime);
1.781 + /**
1.782 + @publishedPartner
1.783 + @prototype 9.6
1.784 + Function invoked by the PSL to get the timeout period to wait for a response from the bus master
1.785 +
1.786 + @return The wait time, in milliseconds
1.787 + */
1.788 + inline TInt8 GetMasterWaitTime();
1.789 + /**
1.790 + @publishedPartner
1.791 + @prototype 9.6
1.792 + Function invoked by the PSL to set the timeout period to wait for a response from the Client
1.793 +
1.794 + @param aWaitTime Argument specifying the wait time, in milliseconds (limit=KMaxWaitTime)
1.795 + @return KErrNone
1.796 + */
1.797 + TInt SetClientWaitTime(TInt8 aWaitTime);
1.798 + /**
1.799 + @publishedPartner
1.800 + @prototype 9.6
1.801 + Function invoked by the PSL to get the timeout period to wait for a response from the Client
1.802 +
1.803 + @return The wait time, in milliseconds
1.804 + */
1.805 + inline TInt8 GetClientWaitTime();
1.806 +private:
1.807 + //Method to instruct PSL to indicate a bus error to the bus Master, then return
1.808 + void SendBusErrorAndReturn();
1.809 + void SetChannelId(TInt& aChannelId);
1.810 +
1.811 + void CompleteAsynchCapture(TInt aResult);
1.812 + void SlaveTimerCallBack();
1.813 + static void SlaveStaticCB(TAny* aDumPtr);
1.814 +
1.815 +protected:
1.816 + TInt8 iRxGranularity;
1.817 + TInt8 iTxGranularity;
1.818 + TInt8 iNumRxWords;
1.819 + TInt8 iNumTxWords;
1.820 + TInt8 iRxOffset;
1.821 + TInt8 iTxOffset;
1.822 +private:
1.823 + TInt8 iChannelInUse;
1.824 + TInt8 iSpare1;
1.825 +protected:
1.826 + TInt16 iChannelId; // channel identifier to be returned to client (in aChannelId)
1.827 +private:
1.828 + TInt16 iInstanceCount; // instance count part of aChannelId
1.829 +protected:
1.830 + TDes8* iConfigHeader;
1.831 + TInt8* iTxBuf;
1.832 + TInt8* iRxBuf;
1.833 +private:
1.834 + TIicBusSlaveCallback* iNotif;
1.835 + TDfc* iClientTimeoutDfc; // To be queued on the dfc queue used by iNotif
1.836 + DThread* iClient; // stored when client captures channel
1.837 +#ifndef STANDALONE_CHANNEL
1.838 + DIicBusController* iController;
1.839 +#endif
1.840 +
1.841 + TInt8 iTimerState;
1.842 + TInt8 iMasterWaitTime; // 8 bits allows maximum wait time of 0.25 seconds
1.843 + TInt8 iClientWaitTime; // 8 bits allows maximum wait time of 0.25 seconds
1.844 + TInt8 iSpare2;
1.845 +
1.846 + TInt8 iReqTrig; // Represents the trigger required by the Client (bitmask from TIicBusSlaveTrigger).
1.847 + TInt8 iAccumTrig; // Represents the events accumulated during the current trigger period
1.848 + TInt16 iSpare3;
1.849 +
1.850 + TSpinLock iSpinLock;
1.851 + TAny* iReserved1;
1.852 + TAny* iReserved2;
1.853 +
1.854 + friend class DIicBusChannelMasterSlave;
1.855 + friend class DIicBusController; // For static method DIicBusController::DeRegisterChannel
1.856 + };
1.857 +
1.858 +/**
1.859 +@internalComponent
1.860 +@prototype 9.6
1.861 +The Master-Slave Channel class (not for derivation)
1.862 +*/
1.863 +class DIicBusChannelMasterSlave : public DIicBusChannel
1.864 + {
1.865 +public:
1.866 + // constructor
1.867 +#ifdef STANDALONE_CHANNEL
1.868 + IMPORT_C DIicBusChannelMasterSlave(TBusType aBusType, TChannelDuplex aChanDuplex, DIicBusChannelMaster* aMasterChan, DIicBusChannelSlave* aSlaveChan);
1.869 +#else
1.870 + inline DIicBusChannelMasterSlave(TBusType aBusType, TChannelDuplex aChanDuplex, DIicBusChannelMaster* aMasterChan, DIicBusChannelSlave* aSlaveChan);
1.871 +#endif
1.872 + ~DIicBusChannelMasterSlave(){delete iMasterChannel; delete iSlaveChannel; }
1.873 + inline TInt DoCreate();
1.874 + // Master side interface to Bus Controller
1.875 + virtual TInt QueueTransaction(TIicBusTransaction* aTransaction);
1.876 + virtual TInt QueueTransaction(TIicBusTransaction* aTransaction, TIicBusCallback* aCallback);
1.877 + inline TInt CancelTransaction(TIicBusTransaction* aTransaction);
1.878 +
1.879 + // Slave side interface to Bus Controller
1.880 + virtual TInt CaptureChannel(TDes8* aConfigHdr, TIicBusSlaveCallback* aCallback, TInt& aChannelId, TBool aAsynch);
1.881 + virtual TInt ReleaseChannel();
1.882 + inline TInt RegisterRxBuffer(TPtr8 aRxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);
1.883 + inline TInt RegisterTxBuffer(TPtr8 aTxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);
1.884 + inline TInt SetNotificationTrigger(TInt aTrigger);
1.885 + virtual TInt StaticExtension(TUint aFunction, TAny* aParam1, TAny* aParam2);
1.886 +
1.887 +private:
1.888 + // Base class support
1.889 + virtual TInt CheckHdr(TDes8* /*aHdr*/){ __ASSERT_DEBUG(0,Kern::Fault("DIicBusChannelMasterSlave::CheckHdr",__LINE__)); \
1.890 + return KErrGeneral;}; // Not accessed. PSL implementation for Master or Slave used.
1.891 +protected:
1.892 + DIicBusChannelMaster* iMasterChannel;
1.893 + DIicBusChannelSlave* iSlaveChannel;
1.894 +private:
1.895 +
1.896 + friend class DIicBusChannelMaster;
1.897 + friend class DIicBusChannelSlave;
1.898 + friend class DIicBusController; // For static method DIicBusController::DeRegisterChannel
1.899 + };
1.900 +
1.901 +#include <drivers/iic_channel.inl>
1.902 +
1.903 +#endif // #ifndef __IIC_CHANNEL_H__
1.904 +