|
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_channel.h |
|
15 // Include file for channel implementation |
|
16 // |
|
17 // WARNING: This file contains some APIs which are internal and are subject |
|
18 // to change without notice. Such APIs should therefore not be used |
|
19 // outside the Kernel and Hardware Services package. |
|
20 |
|
21 /** |
|
22 @file |
|
23 @internalTechnology |
|
24 */ |
|
25 #ifndef __IIC_CHANNEL_H__ |
|
26 #define __IIC_CHANNEL_H__ |
|
27 |
|
28 #ifdef STANDALONE_CHANNEL |
|
29 #include <drivers/iic_transaction.h> |
|
30 #else |
|
31 #include <drivers/iic.h> |
|
32 #endif |
|
33 |
|
34 static const char KIicChannelPanic[]="Iic Channel PIL"; |
|
35 |
|
36 const static TInt KChannelTypeMask = 0x03; |
|
37 const static TInt KBusTypeShift = 2; |
|
38 const static TInt KBusTypeMask = 0x07<<KBusTypeShift; // number of buses may grow in future |
|
39 const static TInt KChannelDuplexShift= 5; |
|
40 const static TInt KChannelDuplexMask = 0x01<<KChannelDuplexShift; |
|
41 const static TInt16 KTransCountMsBit = (TInt16)((TUint16)0x8000); |
|
42 |
|
43 const static TInt8 KMaxWaitTime = 0x21; // Maximum allowable time in milliseconds for a Slave channel to wait for a response |
|
44 // (from Master or Client). This constant is used to limit run-time selected values |
|
45 // for timeouts. The value stated here is semi-arbitrary. |
|
46 |
|
47 #ifdef IIC_SIMULATED_PSL |
|
48 // In a real system, the following timeout values are likely to be excessive. However, they are available |
|
49 // for use in the test framework, to account for the processing overhead. |
|
50 const TInt KSlaveDefMWaitTime = 32; |
|
51 const TInt KSlaveDefCWaitTime = 16; |
|
52 #else |
|
53 const TInt KSlaveDefMWaitTime = 1; // Default wait time for Master timeout. PSL can use SetMasterWaitTime to override. |
|
54 const TInt KSlaveDefCWaitTime = 1; // Default wait time for Client timeout. PSL can use SetClientWaitTime to override. |
|
55 #endif |
|
56 |
|
57 |
|
58 /** |
|
59 @internalComponent |
|
60 @prototype 9.6 |
|
61 Base class for a Channel (not directly instantiable) |
|
62 */ |
|
63 class DIicBusChannel : public DBase |
|
64 { |
|
65 public: |
|
66 enum TChannelType |
|
67 { |
|
68 EMaster = 0, |
|
69 ESlave = 0x01, |
|
70 EMasterSlave = 0x02 |
|
71 }; |
|
72 enum TBusType |
|
73 { |
|
74 EI2c = 0, |
|
75 ESpi = 0x01, |
|
76 EMicrowire = 0x02, |
|
77 ECci = 0x03, |
|
78 ESccb = 0x04 |
|
79 }; |
|
80 enum TChannelDuplex |
|
81 { |
|
82 EHalfDuplex = 0, // supports only half duplex transactions (even if bus spec supports full duplex) |
|
83 EFullDuplex = 0x1 // supports full duplex transactions (queud transactions may still be half duplex) |
|
84 }; |
|
85 |
|
86 public: |
|
87 virtual TInt StaticExtension(TUint aFunction, TAny* /*aParam1*/, TAny* /*aParam2*/) |
|
88 { |
|
89 #ifdef _DEBUG |
|
90 if(aFunction == KCtrlIoDumpChan) |
|
91 { |
|
92 DumpChannel(); |
|
93 return KErrNone; |
|
94 } |
|
95 else |
|
96 #else |
|
97 (void)aFunction; |
|
98 #endif |
|
99 |
|
100 return KErrNotSupported; |
|
101 }; |
|
102 protected: |
|
103 // constructor |
|
104 inline DIicBusChannel(TChannelType aChanType, TBusType aBusType, TChannelDuplex aChanDuplex); |
|
105 // second phase construction - empty, to be implemented by derived types if required |
|
106 virtual TInt DoCreate()=0; |
|
107 |
|
108 // helper function to read an set flags |
|
109 inline TChannelType ChannelType(); |
|
110 inline void SetChannelType(TChannelType aChanType); |
|
111 inline TBusType BusType(); |
|
112 inline void SetBusType(TBusType aBusType); |
|
113 inline TChannelDuplex ChannelDuplex(); |
|
114 inline void SetChannelType(TChannelDuplex aChanDuplex); |
|
115 inline TInt8 ChannelNumber() const; |
|
116 |
|
117 virtual TInt CheckHdr(TDes8* aHdr) = 0; // PSL to check the header is valid for this channel |
|
118 protected: |
|
119 #ifdef _DEBUG |
|
120 inline void DumpChannel(); |
|
121 #endif |
|
122 protected: |
|
123 NTimer iTimeoutTimer; // timeout timer |
|
124 TInt8 iChannelNumber; // this is the Key for ordering channels in the array |
|
125 TUint8 iFlags; // combination of TChannelType, TChannelDuplex and TBusType |
|
126 TInt8 iSpare1; |
|
127 TInt8 iSpare2; |
|
128 private: |
|
129 TAny* iReserved; |
|
130 |
|
131 friend class DIicBusController; |
|
132 }; |
|
133 |
|
134 /** |
|
135 @publishedPartner |
|
136 @prototype 9.6 |
|
137 |
|
138 Base class for a Master Channel (not directly instantiable) |
|
139 |
|
140 */ |
|
141 class DIicBusChannelMaster : public DIicBusChannel |
|
142 { |
|
143 public: |
|
144 // interface to Bus Controller (implemented by PIL) |
|
145 // For stand-alone channel, there is no controller. So some parts of |
|
146 // the interface are exported for client direct use. |
|
147 /** |
|
148 @publishedPartner |
|
149 @prototype 9.6 |
|
150 Master channel interface to queue a transaction synchronously. |
|
151 |
|
152 @param aTransaction A pointer to a transaction object containing the details of the transaction. |
|
153 |
|
154 @return KErrNone, when successfully completed; |
|
155 KErrArgument, if aTransaction is NULL; |
|
156 KErrTimedOut, if the channel terminates the transaction because the addressed Slave exceeded the alloted time to respond; |
|
157 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). |
|
158 */ |
|
159 virtual TInt QueueTransaction(TIicBusTransaction* aTransaction); |
|
160 /** |
|
161 @publishedPartner |
|
162 @prototype 9.6 |
|
163 Master channel interface to queue a transaction asynchronously. |
|
164 |
|
165 @param aTransaction A pointer to a transaction object containing the details of the transaction. |
|
166 @param aCallback A pointer to a callback object. |
|
167 |
|
168 @return KErrNone, if successfully accepted; KErrArgument, if either aTransaction or aCallback are NULL; |
|
169 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). |
|
170 */ |
|
171 virtual TInt QueueTransaction(TIicBusTransaction* aTransaction, TIicBusCallback* aCallback); |
|
172 /** |
|
173 @publishedPartner |
|
174 @prototype 9.6 |
|
175 Master channel interface to cancel a previously queued transaction. |
|
176 |
|
177 @param aTransaction A pointer to a transaction object containing the details of the transaction. |
|
178 |
|
179 @return KErrCancel, if successfully cancelled; KErrArgument, if aTransaction is NULL; |
|
180 KErrNotFound if the transaction cannot be found on channel's queue of transactions; |
|
181 KErrInUse if this method is called on a transaction that has already been started; |
|
182 KErrNotSupported, if the channel does not support Master mode, or the method is called on a synchronous transaction.. |
|
183 */ |
|
184 virtual TInt CancelTransaction(TIicBusTransaction* aTransaction); |
|
185 /** |
|
186 @publishedPartner |
|
187 @prototype 9.6 |
|
188 Master channel interface interface to provide extended functionality |
|
189 |
|
190 @param aFunction A function identifier. If bit 31 is set and bit 30 cleared it is used to extend the Master-Slave channel; |
|
191 if bit 31 is cleared and bit 30 is set, it extends the Master channel; if both bits 31 and 30 are cleared it |
|
192 extends the Slave channel interface. |
|
193 @param aParam1 A generic argument to be passed to the function identified by aFunction. |
|
194 @param aParam2 A generic argument to be passed to the function identified by aFunction. |
|
195 |
|
196 @return KErrNone, if successful; |
|
197 KErrNotSupported, function is not supported; |
|
198 Any other system wide error code. |
|
199 */ |
|
200 virtual TInt StaticExtension(TUint aFunction, TAny* aParam1, TAny* aParam2); |
|
201 |
|
202 // |
|
203 virtual TInt Spare1(TInt aVal, TAny* aPtr1, TAny* aPtr2); |
|
204 |
|
205 /** |
|
206 @publishedPartner |
|
207 @prototype 9.6 |
|
208 Destructor for DIicBusChannelMaster |
|
209 */ |
|
210 ~DIicBusChannelMaster(); |
|
211 |
|
212 protected: |
|
213 // PSL implemented |
|
214 /** |
|
215 @publishedPartner |
|
216 @prototype 9.6 |
|
217 Gateway function for PSL implementation (to be called by the interface APIs) |
|
218 */ |
|
219 virtual TInt DoRequest(TIicBusTransaction* aTransaction) = 0; |
|
220 /** |
|
221 @publishedPartner |
|
222 @prototype 9.6 |
|
223 Function to be invoked in the event of a Slave timeout. May be overridden by the PSL. |
|
224 */ |
|
225 virtual TInt HandleSlaveTimeout() = 0; |
|
226 /** |
|
227 @publishedPartner |
|
228 @prototype 9.6 |
|
229 Second phase constructor to be implemented by the PSL |
|
230 */ |
|
231 virtual TInt DoCreate() = 0; |
|
232 |
|
233 // Called by PSL |
|
234 /** |
|
235 @publishedPartner |
|
236 @prototype 9.6 |
|
237 |
|
238 Constructor for DIicBusChannelMaster |
|
239 |
|
240 @param aBusType Argument to specify the type of Bus |
|
241 @param aChanDuplex Argument to specify the duplex support offered by this channel |
|
242 */ |
|
243 DIicBusChannelMaster(TBusType aBusType, TChannelDuplex aChanDuplex); |
|
244 /** |
|
245 @publishedPartner |
|
246 @prototype 9.6 |
|
247 Function to instigate DIicBusChannel initialisation |
|
248 |
|
249 @return KErrNone if no error |
|
250 KErrNoMemory if allocation of required objects |
|
251 */ |
|
252 TInt Init(); |
|
253 /** |
|
254 @publishedPartner |
|
255 @prototype 9.6 |
|
256 |
|
257 Function to start the timer to check the Slave responsiveness. |
|
258 |
|
259 @param aTime Timeout in milliseconds |
|
260 |
|
261 @return KErrNone if no error, |
|
262 KErrInUse if timer is already active. |
|
263 |
|
264 */ |
|
265 TInt StartSlaveTimeOutTimer(TInt aTime); |
|
266 /** |
|
267 @publishedPartner |
|
268 @prototype 9.6 |
|
269 |
|
270 Function to specify the DFC queue for the channel to use |
|
271 |
|
272 @param aDfcQue Pointer to the DFC queue to use |
|
273 |
|
274 */ |
|
275 void SetDfcQ(TDfcQue* aDfcQue); |
|
276 /** |
|
277 @publishedPartner |
|
278 @prototype 9.6 |
|
279 |
|
280 Function to Complete the transaction being processed by the channel |
|
281 |
|
282 @param aResult Error code to complete the transaction with |
|
283 |
|
284 */ |
|
285 void CompleteRequest(TInt aResult); |
|
286 /** |
|
287 @publishedPartner |
|
288 @prototype 9.6 |
|
289 |
|
290 Function to cancel the timer to check the Slave responsiveness. |
|
291 |
|
292 */ |
|
293 void CancelTimeOut(); |
|
294 |
|
295 // Methods to make private data of TIicBusTransaction object accessible to derivatives of this class |
|
296 /** |
|
297 @publishedPartner |
|
298 @prototype 9.6 |
|
299 |
|
300 Function to return the Transaction Header of a specified TIicBusTransaction object |
|
301 |
|
302 @return The Transaction Header of the specified TIicBusTransaction object |
|
303 |
|
304 @see TIicBusTransaction |
|
305 */ |
|
306 static inline TDes8* GetTransactionHeader(const TIicBusTransaction* aTransaction); |
|
307 /** |
|
308 @publishedPartner |
|
309 @prototype 9.6 |
|
310 |
|
311 Function to return the Half Duplex Transfer pointer of a specified TIicBusTransaction object |
|
312 |
|
313 @return The Half Duplex Transfer pointer of the specified TIicBusTransaction object |
|
314 |
|
315 @see TIicBusTransaction |
|
316 */ |
|
317 static inline TIicBusTransfer* GetTransHalfDuplexTferPtr(const TIicBusTransaction* aTransaction); |
|
318 /** |
|
319 @publishedPartner |
|
320 @prototype 9.6 |
|
321 |
|
322 Function to return the Full Duplex Transfer pointer of a specified TIicBusTransaction object |
|
323 |
|
324 @return The Full Duplex Transfer pointer of the specified TIicBusTransaction object |
|
325 |
|
326 @see TIicBusTransaction |
|
327 */ |
|
328 static inline TIicBusTransfer* GetTransFullDuplexTferPtr(const TIicBusTransaction* aTransaction); |
|
329 /** |
|
330 @publishedPartner |
|
331 @prototype 9.6 |
|
332 |
|
333 Function to return the address of the callback object of a specified TIicBusTransaction object |
|
334 |
|
335 @return The address of the callback object of the specified TIicBusTransaction object |
|
336 |
|
337 @see TIicBusTransaction |
|
338 */ |
|
339 static inline TIicBusCallback* GetTransCallback(const TIicBusTransaction* aTransaction); |
|
340 /** |
|
341 @publishedPartner |
|
342 @prototype 9.6 |
|
343 |
|
344 Function to return the value of the TransFlags member of a specified TIicBusTransaction object |
|
345 |
|
346 @return The value of the TransFlags member of the specified TIicBusTransaction object |
|
347 |
|
348 @see TIicBusTransaction |
|
349 */ |
|
350 static inline TUint8 GetTransFlags(const TIicBusTransaction* aTransaction); |
|
351 |
|
352 // Methods to make private data of TIicBusTransfer object accessible to derivatives of this class |
|
353 /** |
|
354 @publishedPartner |
|
355 @prototype 9.6 |
|
356 |
|
357 Function to return Transfer Type the of a specified TIicBusTransfer object |
|
358 |
|
359 @return The Transfer Type of the specified TIicBusTransfer object |
|
360 |
|
361 @see TIicBusTransfer |
|
362 */ |
|
363 static inline TInt8 GetTferType(const TIicBusTransfer* aTransfer); |
|
364 /** |
|
365 @publishedPartner |
|
366 @prototype 9.6 |
|
367 |
|
368 Function to return the Buffer Granularity of a specified TIicBusTransfer object |
|
369 |
|
370 @return The Buffer Granularity of the specified TIicBusTransfer object |
|
371 |
|
372 @see TIicBusTransfer |
|
373 */ |
|
374 static inline TInt8 GetTferBufGranularity(const TIicBusTransfer* aTransfer); |
|
375 /** |
|
376 @publishedPartner |
|
377 @prototype 9.6 |
|
378 |
|
379 Function to return the descriptor for the data for a specified TIicBusTransfer object |
|
380 |
|
381 @return The descriptor for the data for the specified TIicBusTransfer object |
|
382 |
|
383 @see TIicBusTransfer |
|
384 */ |
|
385 static inline const TDes8* GetTferBuffer(const TIicBusTransfer* aTransfer); |
|
386 /** |
|
387 @publishedPartner |
|
388 @prototype 9.6 |
|
389 |
|
390 Function to return the address of the next transfer for a specified TIicBusTransfer object |
|
391 |
|
392 @return The address of the next transfer for the specified TIicBusTransfer object |
|
393 |
|
394 @see TIicBusTransfer |
|
395 */ |
|
396 static inline TIicBusTransfer* GetTferNextTfer(const TIicBusTransfer* aTransfer); |
|
397 |
|
398 // Methods to make private data of TIicBusTransactionPreamble object accessible to derivatives of this class |
|
399 /** |
|
400 @publishedPartner |
|
401 @prototype 9.6 |
|
402 |
|
403 Function to return the function pointer for a specified TIicBusTransactionPreamble object |
|
404 |
|
405 @return The function pointer for the specified TIicBusTransactionPreamble object |
|
406 |
|
407 @see TIicBusTransactionPreamble |
|
408 */ |
|
409 static inline TIicBusPreamble GetPreambleFuncPtr(const TIicBusTransactionPreamble* aTransfer); |
|
410 /** |
|
411 @publishedPartner |
|
412 @prototype 9.6 |
|
413 |
|
414 Function to return the function argument for a specified TIicBusTransactionPreamble object |
|
415 |
|
416 @return The function argument for the specified TIicBusTransactionPreamble object |
|
417 |
|
418 @see TIicBusTransactionPreamble |
|
419 */ |
|
420 static inline TAny* GetPreambleFuncArg(const TIicBusTransactionPreamble* aTransfer); |
|
421 |
|
422 /** |
|
423 @publishedPartner |
|
424 @prototype 9.6 |
|
425 |
|
426 Function to return the function pointer of a specified TIicBusTransactionMultiTransc object |
|
427 |
|
428 @return The function pointer of the specified TIicBusTransactionMultiTransc object |
|
429 |
|
430 @see TIicBusTransactionMultiTransc |
|
431 */ |
|
432 static inline TIicBusMultiTranscCbFn GetMultiTranscFuncPtr(const TIicBusTransactionMultiTransc* aTransfer); |
|
433 /** |
|
434 @publishedPartner |
|
435 @prototype 9.6 |
|
436 |
|
437 Function to return the function argument of a specified TIicBusTransactionMultiTransc object |
|
438 |
|
439 @return The function argument of the specified TIicBusTransactionMultiTransc object |
|
440 |
|
441 @see TIicBusTransactionMultiTransc |
|
442 */ |
|
443 static inline TAny* GetMultiTranscFuncArg(const TIicBusTransactionMultiTransc* aTransfer); |
|
444 |
|
445 /** |
|
446 @publishedPartner |
|
447 @prototype 9.6 |
|
448 |
|
449 Function to return the function pointer of a specified TIicBusTransactionPreambleExt object |
|
450 |
|
451 @return The function pointer of the specified TIicBusTransactionPreambleExt object |
|
452 |
|
453 @see TIicBusTransaction |
|
454 */ |
|
455 static inline TIicBusMultiTranscCbFn GetExtTranscFuncPtr(const TIicBusTransactionPreambleExt* aTransfer); |
|
456 /** |
|
457 @publishedPartner |
|
458 @prototype 9.6 |
|
459 |
|
460 Function to return the function argument of a specified TIicBusTransactionPreambleExt object |
|
461 |
|
462 @return The function argument of the specified TIicBusTransactionPreambleExt object |
|
463 |
|
464 @see TIicBusTransaction |
|
465 */ |
|
466 static inline TAny* GetExtTranscFuncArg(const TIicBusTransactionPreambleExt* aTransfer); |
|
467 |
|
468 private: |
|
469 // Function to acquire the NFastMutex of the channel |
|
470 void Lock(); |
|
471 // Function to release the NFastMutex of the channel |
|
472 void Unlock(); |
|
473 |
|
474 // function to run on receiving a message |
|
475 static void MsgQFunc(TAny* aPtr); |
|
476 |
|
477 TIicBusTransaction* NextTrans(TIicBusTransaction* aTrans); |
|
478 void EndTransaction(TIicBusTransaction* aTrans, TInt aResult, TIicBusCallback* aCb); |
|
479 void Complete(TInt aResult, TIicBusTransaction* aTransaction); |
|
480 void UnlockAndKick(); |
|
481 |
|
482 static void SlaveTimeoutCallback(TAny*); |
|
483 |
|
484 // Used by DIidBusController (a friend of this class) |
|
485 TInt TransFlow(TIicBusTransaction* aTransaction); |
|
486 |
|
487 TInt8 IsMasterBusy(); |
|
488 |
|
489 protected: |
|
490 TDfcQue* iDfcQ; |
|
491 |
|
492 private: |
|
493 TDfc iTransQDfc; |
|
494 SOrdQue iTransactionQ; |
|
495 TIicBusTransaction* iTransaction; // Pointer to current transaction |
|
496 TIicBusTransaction* iCurrentTransaction; // Pointer to current fragment of a multiple transaction |
|
497 |
|
498 NFastMutex iTransactionQLock; |
|
499 |
|
500 TDfc* iSlaveTimeoutDfc; |
|
501 |
|
502 TInt16 iTransCount; // Count of pending transactions |
|
503 TInt8 iChannelReady; |
|
504 TInt8 iSpare1; |
|
505 |
|
506 private: |
|
507 TAny* iReserved1; |
|
508 TAny* iReserved2; |
|
509 |
|
510 friend class DIicBusChannelMasterSlave; |
|
511 friend class DIicBusController; // For static method DIicBusController::DeRegisterChannel |
|
512 }; |
|
513 |
|
514 |
|
515 /** |
|
516 @publishedPartner |
|
517 @prototype 9.6 |
|
518 |
|
519 Base class for a Slave Channel (not directly instantiable) |
|
520 |
|
521 */ |
|
522 class DIicBusChannelSlave : public DIicBusChannel |
|
523 { |
|
524 protected: |
|
525 /** |
|
526 @publishedPartner |
|
527 @prototype 9.6 |
|
528 The set of operation values for processing by the PSL |
|
529 */ |
|
530 enum TPslOperation |
|
531 { |
|
532 ESyncConfigPwrUp = 0x01, |
|
533 EAsyncConfigPwrUp = 0x02, |
|
534 EPowerDown = 0x04, |
|
535 ETransmit = 0x08, |
|
536 EReceive = 0x10, |
|
537 EAbort = 0x20 |
|
538 }; |
|
539 private: |
|
540 // Values used by the internal state machine |
|
541 enum TSlaveTimerStates |
|
542 { |
|
543 EInactive = 0x01, |
|
544 EWaitForMaster = 0x02, |
|
545 EWaitForClient = 0x04, |
|
546 EClientTimeout = 0x08 |
|
547 }; |
|
548 |
|
549 public: |
|
550 |
|
551 // Interface to Controller. |
|
552 // For stand-alone channel, the interface is exported. |
|
553 /** |
|
554 @publishedPartner |
|
555 @prototype 9.6 |
|
556 Capture this Slave channel. |
|
557 |
|
558 @param aConfigHdr A pointer to a descriptor containing the device specific configuration option applicable to all transactions. |
|
559 @param aCallback A pointer to a callback to be called upon specified triggers. |
|
560 @param aChannelId If this API is to complete synchronously, and the processing was successful, then on return aChannelId |
|
561 contains a platform-specific cookie that uniquely identifies the channel instance to be used by this client. |
|
562 If the processing was unsuccessful for the synchronous completion case, aChannelId will be unchanged. |
|
563 If the API was called to complete asynchronously, aChannelId will, in all cases, be set to zero; the valid |
|
564 value for the cookie will be set by the callback. |
|
565 @param aAsynch A boolean value that indicates if this API is to complete synchronously (EFalse) or asynchronously (ETrue). |
|
566 |
|
567 @return KErrNone, if successfully captured, or if API is asynchronous, if the request to capture the channel was accepted; |
|
568 KErrInUse if channel is already in use; KErrArgument, if aCallback is NULL; |
|
569 KErrNotSupported, if the channel does not support Slave mode. |
|
570 */ |
|
571 virtual TInt CaptureChannel(TDes8* aConfigHdr, TIicBusSlaveCallback* aCallback, TInt& aChannelId, TBool aAsynch); |
|
572 /** |
|
573 @publishedPartner |
|
574 @prototype 9.6 |
|
575 Release this previously captured Slave channel. |
|
576 |
|
577 @return KErrNone, if successfully released; |
|
578 KErrInUse if a transaction is currently underway on this channel; KErrArgument |
|
579 */ |
|
580 virtual TInt ReleaseChannel(); |
|
581 /** |
|
582 @publishedPartner |
|
583 @prototype 9.6 |
|
584 Register a receive buffer with this Slave channel. |
|
585 |
|
586 @param aRxBuffer A pointer to the receive buffer, in a client created descriptor. |
|
587 @param aBufGranularity The number of buffer bytes used to store a word. |
|
588 @param aNumWords The number of words expected to be received. |
|
589 @param aOffset The offset from the start of the buffer where to store the received data. |
|
590 |
|
591 @return KErrNone, if successfully registered; |
|
592 KErrAlreadyExists if a receive buffer is already pending; |
|
593 KErrArgument, if the pointer descriptor is NULL; |
|
594 */ |
|
595 virtual TInt RegisterRxBuffer(TPtr8 aRxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset); |
|
596 /** |
|
597 @publishedPartner |
|
598 @prototype 9.6 |
|
599 Register a transmit buffer with this Slave channel. |
|
600 This client may create a single buffer for the entire transaction and control where the received data |
|
601 is to be placed and the transmit data is to be found, by specifying the number of bytes to transmit (receive) |
|
602 and the offset into the buffer. |
|
603 |
|
604 @param aTxBuffer A pointer to the transmit buffer, in a client created descriptor. |
|
605 @param aBufGranularity The number of buffer bytes used to store a word. |
|
606 @param aNumWords The number of words to be transmitted. |
|
607 @param aOffset The offset from the start of the buffer where to fetch the data to be transmitted. |
|
608 |
|
609 @return KErrNone, if successfully registered; |
|
610 KErrAlreadyExists if a transmit buffer is already pending; |
|
611 KErrArgument, if the pointer descriptor is NULL; |
|
612 */ |
|
613 virtual TInt RegisterTxBuffer(TPtr8 aTxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset); |
|
614 /** |
|
615 @publishedPartner |
|
616 @prototype 9.6 |
|
617 Sets the notification triggers and readies the receive path and/or kick starts a transmit (if the node is being addressed). |
|
618 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). |
|
619 If a transmit buffer has been registered and this API has been called the channel will immediately transmit when addressed by the Master |
|
620 If the channel supports full duplex, both paths can be readied in one call to this API. |
|
621 |
|
622 @param aTrigger A bitmask specifying the notification trigger. Masks for individual triggers are specified by the TIicBusSlaveTrigger enumeration. |
|
623 |
|
624 @return KErrNone, if successful; |
|
625 KErrArgument, if the trigger is invalid for this channel; |
|
626 KErrInUse if a transaction is already underway on this channel; |
|
627 KErrTimedOut, if the client exceeded the alloted time to respond by invoking this API; |
|
628 */ |
|
629 virtual TInt SetNotificationTrigger(TInt aTrigger); |
|
630 /** |
|
631 @publishedPartner |
|
632 @prototype 9.6 |
|
633 Interface to provide extended functionality |
|
634 |
|
635 @param aFunction A function identifier. If bit 31 is set and bit 30 cleared it is used to extend the Master-Slave channel; |
|
636 if bit 31 is cleared and bit 30 is set, it extends the Master channel; if both bits 31 and 30 are cleared it |
|
637 extends the Slave channel interface. |
|
638 @param aParam1 A generic argument to be passed to the function identified by aFunction. |
|
639 @param aParam2 A generic argument to be passed to the function identified by aFunction. |
|
640 |
|
641 @return KErrNone, if successful; |
|
642 KErrNotSupported, function is not supported; |
|
643 Any other system wide error code. |
|
644 */ |
|
645 virtual TInt StaticExtension(TUint aFunction, TAny* aParam1, TAny* aParam2); |
|
646 // |
|
647 /** |
|
648 @internalTechnology |
|
649 @prototype 9.6 |
|
650 Function reserved for future use |
|
651 */ |
|
652 virtual TInt Spare1(TInt aVal, TAny* aPtr1, TAny* aPtr2); |
|
653 |
|
654 // Interface to TIicBusSlaveCallback |
|
655 // channel-specific function to process data received/transmitted (called from NotifyClient or DFC queued from it) |
|
656 // Must fill in the aCb object's iReturn, iRxWords and/or iTxWords using the appropriate funtions |
|
657 /** |
|
658 @publishedPartner |
|
659 @prototype 9.6 |
|
660 Function invoked when an asynchronous event occurs on the Slave channel. Implemented by the PSL. |
|
661 @param aTrigger Argument to indicate the type of event that occurred |
|
662 @param aCb Address of the Slave client callback object to process |
|
663 |
|
664 @return KErrNone, if successful; |
|
665 KErrNotSupported, function is not supported; |
|
666 Any other system wide error code. |
|
667 */ |
|
668 #ifdef STANDALONE_CHANNEL |
|
669 friend class TIicBusSlaveCallback; |
|
670 protected: |
|
671 virtual void ProcessData(TInt aTrigger, TIicBusSlaveCallback* aCb) = 0; |
|
672 private: |
|
673 TInt UpdateReqTrig(TInt8& aCbTrigVal, TInt& aCallbackRet); |
|
674 void StartTimerByState(); |
|
675 void StopTimer(); |
|
676 #else |
|
677 public: |
|
678 virtual void ProcessData(TInt aTrigger, TIicBusSlaveCallback* aCb) = 0; |
|
679 virtual TInt UpdateReqTrig(TInt8& aCbTrigVal, TInt& aCallbackRet); |
|
680 virtual void StartTimerByState(); |
|
681 virtual void StopTimer(); |
|
682 #endif |
|
683 |
|
684 public: |
|
685 // Values used by the Interface to TIicBusSlaveCallback |
|
686 enum TSlaveNotifProcSteps |
|
687 { |
|
688 EStopTimer = 0x01, |
|
689 EInvokeCb = 0x02, |
|
690 EStartTimer = 0x04 |
|
691 }; |
|
692 |
|
693 protected: |
|
694 // PSL implemented |
|
695 /** |
|
696 @publishedPartner |
|
697 @prototype 9.6 |
|
698 |
|
699 PSL specific second phase constructor |
|
700 |
|
701 @return KErrNone, if succesful; |
|
702 KErrNotSupported, function is not supported; |
|
703 Any other system wide error code. |
|
704 */ |
|
705 virtual TInt DoCreate() = 0; |
|
706 /** |
|
707 @publishedPartner |
|
708 @prototype 9.6 |
|
709 |
|
710 Gateway function for PSL implementation: aOperation is a bitmask made of TPslOperation (to be called by the interface APIs) |
|
711 |
|
712 @return KErrNone, if succesful; |
|
713 KErrNotSupported, function is not supported; |
|
714 Any other system wide error code. |
|
715 */ |
|
716 virtual TInt DoRequest(TInt aOperation) = 0; |
|
717 |
|
718 // Called by PSL |
|
719 /** |
|
720 @publishedPartner |
|
721 @prototype 9.6 |
|
722 |
|
723 Constructor for DIicBusChannelSlave |
|
724 |
|
725 @param aBusType Argument to specify the type of Bus |
|
726 @param aChanDuplex Argument to specify the duplex support offered by this channel |
|
727 @param aChannelId Argument to specify the identifier to use for this channel |
|
728 */ |
|
729 DIicBusChannelSlave(TBusType aBusType, TChannelDuplex aChanDuplex, TInt16 aChannelId); |
|
730 /** |
|
731 @publishedPartner |
|
732 @prototype 9.6 |
|
733 Function to instigate DIicBusChannelSlave initialisation |
|
734 |
|
735 @return KErrNone |
|
736 */ |
|
737 TInt Init(); |
|
738 |
|
739 /** |
|
740 @publishedPartner |
|
741 @prototype 9.6 |
|
742 Destructor for DIicBusChannelSlave |
|
743 */ |
|
744 ~DIicBusChannelSlave(); |
|
745 |
|
746 /** |
|
747 @publishedPartner |
|
748 @prototype 9.6 |
|
749 Function invoked when an asynchronous channel capture completes |
|
750 |
|
751 @param aResult Argument specifying the error code reurned by the capture operation |
|
752 |
|
753 @return KErrNone |
|
754 */ |
|
755 void ChanCaptureCallback(TInt aResult); |
|
756 /** |
|
757 @publishedPartner |
|
758 @prototype 9.6 |
|
759 Function invoked to instigate processing by the PSL, PIL and Client when an asynchronous event occurs |
|
760 |
|
761 @param aResult Argument specifying the trigger value associated with the asynchronous event |
|
762 |
|
763 @return KErrNone |
|
764 */ |
|
765 void NotifyClient(TInt aTrigger); |
|
766 |
|
767 /** |
|
768 @publishedPartner |
|
769 @prototype 9.6 |
|
770 Function invoked by the PSL to set the timeout period to wait for a response from the bus master |
|
771 |
|
772 @param aWaitTime Argument specifying the wait time, in milliseconds (limit=KMaxWaitTime) |
|
773 |
|
774 @return KErrNone, if succesful; |
|
775 KErrArgument, if aWaitTime > KMaxWaitTime |
|
776 */ |
|
777 TInt SetMasterWaitTime(TInt8 aWaitTime); |
|
778 /** |
|
779 @publishedPartner |
|
780 @prototype 9.6 |
|
781 Function invoked by the PSL to get the timeout period to wait for a response from the bus master |
|
782 |
|
783 @return The wait time, in milliseconds |
|
784 */ |
|
785 inline TInt8 GetMasterWaitTime(); |
|
786 /** |
|
787 @publishedPartner |
|
788 @prototype 9.6 |
|
789 Function invoked by the PSL to set the timeout period to wait for a response from the Client |
|
790 |
|
791 @param aWaitTime Argument specifying the wait time, in milliseconds (limit=KMaxWaitTime) |
|
792 @return KErrNone |
|
793 */ |
|
794 TInt SetClientWaitTime(TInt8 aWaitTime); |
|
795 /** |
|
796 @publishedPartner |
|
797 @prototype 9.6 |
|
798 Function invoked by the PSL to get the timeout period to wait for a response from the Client |
|
799 |
|
800 @return The wait time, in milliseconds |
|
801 */ |
|
802 inline TInt8 GetClientWaitTime(); |
|
803 private: |
|
804 //Method to instruct PSL to indicate a bus error to the bus Master, then return |
|
805 void SendBusErrorAndReturn(); |
|
806 void SetChannelId(TInt& aChannelId); |
|
807 |
|
808 void CompleteAsynchCapture(TInt aResult); |
|
809 void SlaveTimerCallBack(); |
|
810 static void SlaveStaticCB(TAny* aDumPtr); |
|
811 |
|
812 protected: |
|
813 TInt8 iRxGranularity; |
|
814 TInt8 iTxGranularity; |
|
815 TInt8 iNumRxWords; |
|
816 TInt8 iNumTxWords; |
|
817 TInt8 iRxOffset; |
|
818 TInt8 iTxOffset; |
|
819 private: |
|
820 TInt8 iChannelInUse; |
|
821 TInt8 iSpare1; |
|
822 protected: |
|
823 TInt16 iChannelId; // channel identifier to be returned to client (in aChannelId) |
|
824 private: |
|
825 TInt16 iInstanceCount; // instance count part of aChannelId |
|
826 protected: |
|
827 TDes8* iConfigHeader; |
|
828 TInt8* iTxBuf; |
|
829 TInt8* iRxBuf; |
|
830 private: |
|
831 TIicBusSlaveCallback* iNotif; |
|
832 TDfc* iClientTimeoutDfc; // To be queued on the dfc queue used by iNotif |
|
833 DThread* iClient; // stored when client captures channel |
|
834 #ifndef STANDALONE_CHANNEL |
|
835 DIicBusController* iController; |
|
836 #endif |
|
837 |
|
838 TInt8 iTimerState; |
|
839 TInt8 iMasterWaitTime; // 8 bits allows maximum wait time of 0.25 seconds |
|
840 TInt8 iClientWaitTime; // 8 bits allows maximum wait time of 0.25 seconds |
|
841 TInt8 iSpare2; |
|
842 |
|
843 TInt8 iReqTrig; // Represents the trigger required by the Client (bitmask from TIicBusSlaveTrigger). |
|
844 TInt8 iAccumTrig; // Represents the events accumulated during the current trigger period |
|
845 TInt16 iSpare3; |
|
846 |
|
847 TSpinLock iSpinLock; |
|
848 TAny* iReserved1; |
|
849 TAny* iReserved2; |
|
850 |
|
851 friend class DIicBusChannelMasterSlave; |
|
852 friend class DIicBusController; // For static method DIicBusController::DeRegisterChannel |
|
853 }; |
|
854 |
|
855 /** |
|
856 @internalComponent |
|
857 @prototype 9.6 |
|
858 The Master-Slave Channel class (not for derivation) |
|
859 */ |
|
860 class DIicBusChannelMasterSlave : public DIicBusChannel |
|
861 { |
|
862 public: |
|
863 // constructor |
|
864 #ifdef STANDALONE_CHANNEL |
|
865 IMPORT_C DIicBusChannelMasterSlave(TBusType aBusType, TChannelDuplex aChanDuplex, DIicBusChannelMaster* aMasterChan, DIicBusChannelSlave* aSlaveChan); |
|
866 #else |
|
867 inline DIicBusChannelMasterSlave(TBusType aBusType, TChannelDuplex aChanDuplex, DIicBusChannelMaster* aMasterChan, DIicBusChannelSlave* aSlaveChan); |
|
868 #endif |
|
869 ~DIicBusChannelMasterSlave(){delete iMasterChannel; delete iSlaveChannel; } |
|
870 inline TInt DoCreate(); |
|
871 // Master side interface to Bus Controller |
|
872 virtual TInt QueueTransaction(TIicBusTransaction* aTransaction); |
|
873 virtual TInt QueueTransaction(TIicBusTransaction* aTransaction, TIicBusCallback* aCallback); |
|
874 inline TInt CancelTransaction(TIicBusTransaction* aTransaction); |
|
875 |
|
876 // Slave side interface to Bus Controller |
|
877 virtual TInt CaptureChannel(TDes8* aConfigHdr, TIicBusSlaveCallback* aCallback, TInt& aChannelId, TBool aAsynch); |
|
878 virtual TInt ReleaseChannel(); |
|
879 inline TInt RegisterRxBuffer(TPtr8 aRxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset); |
|
880 inline TInt RegisterTxBuffer(TPtr8 aTxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset); |
|
881 inline TInt SetNotificationTrigger(TInt aTrigger); |
|
882 virtual TInt StaticExtension(TUint aFunction, TAny* aParam1, TAny* aParam2); |
|
883 |
|
884 private: |
|
885 // Base class support |
|
886 virtual TInt CheckHdr(TDes8* /*aHdr*/){ __ASSERT_DEBUG(0,Kern::Fault("DIicBusChannelMasterSlave::CheckHdr",__LINE__)); \ |
|
887 return KErrGeneral;}; // Not accessed. PSL implementation for Master or Slave used. |
|
888 protected: |
|
889 DIicBusChannelMaster* iMasterChannel; |
|
890 DIicBusChannelSlave* iSlaveChannel; |
|
891 private: |
|
892 |
|
893 friend class DIicBusChannelMaster; |
|
894 friend class DIicBusChannelSlave; |
|
895 friend class DIicBusController; // For static method DIicBusController::DeRegisterChannel |
|
896 }; |
|
897 |
|
898 #include <drivers/iic_channel.inl> |
|
899 |
|
900 #endif // #ifndef __IIC_CHANNEL_H__ |
|
901 |