1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/bsptemplate/asspandvariant/template_assp/iic/iic_slave.cpp Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,803 @@
1.4 +/*
1.5 +* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of the License "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#include <drivers/iic.h>
1.23 +#include <drivers/iic_channel.h>
1.24 +// #include <gpio.h> // Include if using GPIO functionality
1.25 +#include "iic_psl.h"
1.26 +#include "iic_slave.h"
1.27 +
1.28 +// The timeout period to wait for a response from the client, expressed in milliseconds
1.29 +// This is converted to timer ticks by the PIL, so the maximum value is 2147483.
1.30 +// The value should be selected to allow for the longest, slowest transfer
1.31 +// const TInt KClientWaitTime = 2; // 2mS, when debugging might set up to KMaxWaitTime
1.32 +
1.33 +
1.34 +// In an SMP system, use a spin lock to guard access to member variables iTrigger and iInProgress
1.35 +#ifdef __SMP__
1.36 +static TSpinLock IicPslSpinLock = TSpinLock(TSpinLock::EOrderGenericIrqLow3);
1.37 +#endif
1.38 +
1.39 +// Callback function for the iHwGuardTimer timer.
1.40 +//
1.41 +// Called in ISR context if the iHwGuardTimer expires. Sets iTransactionStatus to KErrTimedOut
1.42 +//
1.43 +void DIicBusChannelSlavePsl::TimeoutCallback(TAny* aPtr)
1.44 + {
1.45 + __KTRACE_OPT(KIIC, Kern::Printf("DCsiChannelMaster::TimeoutCallback"));
1.46 + DIicBusChannelSlavePsl *a = (DIicBusChannelSlavePsl*) aPtr;
1.47 + a->iTransactionStatus = KErrTimedOut;
1.48 + }
1.49 +
1.50 +
1.51 +// Static method called by the ISR when the Master has ended a transfer
1.52 +//
1.53 +// The method checks and reports the Rx and Tx status to the PIL by calling NotifyClient with a bitmask described as follows:.
1.54 +// - If a Tx transfer has ended before all the data was transmitted, bitmask = (ETxAllBytes | ETxOverrun)
1.55 +// - If a Tx transfer has ended and all the data was transmitted, bitmask = ETxAllBytes
1.56 +// - If a Rx transfer has ended before the expected amount of data was received, bitmask = (ERxAllBytes | ERxUnderrun)
1.57 +// - If a Rx transfer has ended and the expected amount of data was received, bitmask = ERxAllBytes
1.58 +//
1.59 +void DIicBusChannelSlavePsl::NotifyClientEnd(DIicBusChannelSlavePsl* aPtr)
1.60 + {
1.61 + __KTRACE_OPT(KIIC, Kern::Printf("NotifyClientEnd, iTrigger %x", aPtr->iTrigger));
1.62 +
1.63 + // Since a transfer has ended, may wish to disable interrupts at this point
1.64 + // This will likely be supported with calls similar to the following:
1.65 + // AsspRegister::Write32(aPtr->iChannelBase + KBusInterruptEnableOffset, KIicPslBusDisableBitMask);
1.66 + // Interrupt::Disable(aPtr->iRxInterruptId);
1.67 + // Interrupt::Disable(aPtr->iTxInterruptId);
1.68 +
1.69 + // iTrigger will have bits ETransmit and EReceive set according to the operation requested in the call to DoRequest
1.70 + // Use variable flag for the bitmask to pass into the PIL method NotifyClient
1.71 + TInt flag = 0;
1.72 + if(aPtr->iTrigger & EReceive)
1.73 + {
1.74 + // Requested Rx operation has ended - check for RxUnderrun
1.75 + flag = ERxAllBytes;
1.76 + if(aPtr->iRxDataEnd != aPtr->iRxData)
1.77 + {
1.78 + flag |= ERxUnderrun;
1.79 + }
1.80 + }
1.81 + if(aPtr->iTrigger & ETransmit)
1.82 + {
1.83 + // Requested Tx operation has ended - check for RxOverrun
1.84 + flag |= ETxAllBytes;
1.85 + if(aPtr->iTxDataEnd != aPtr->iTxData)
1.86 + {
1.87 + flag |= ETxOverrun;
1.88 + }
1.89 + }
1.90 + aPtr->NotifyClient(flag);
1.91 + }
1.92 +
1.93 +
1.94 +// ISR Handler
1.95 +//
1.96 +// The ISR handler identifies the cause of the interrupt that lead to its invocation:
1.97 +// if the cause was transfer-related, it calls the PIL function NotifyClient to report a summary of the transfer status;
1.98 +// if the cause was completion of asynchronous channel capture, PIL function ChanCaptureCallback is called
1.99 +//
1.100 +// The ISR also clears the source of the interrupt, and (for transfer-related interrupts) transfers the next data
1.101 +// between buffers and the hardware and updates the member variable iInProgress to indicate if a transfer has started or
1.102 +// ended. If a transfer has ended before the expected amount of data has been transfered it calls function NotifyClientEnd.
1.103 +//
1.104 +void DIicBusChannelSlavePsl::IicPslIsr(TAny* /*aPtr*/)
1.105 + {
1.106 + // DIicBusChannelSlavePsl *a = (DIicBusChannelSlavePsl*) aPtr;
1.107 +
1.108 + // TInt intState = 0; // Variable to support use of spin lock
1.109 +
1.110 + // TInt trigger = 0; // Record the Rx and Tx transfers
1.111 +
1.112 + // TUint32 intStatus = 0; // Record of the interrupts that are being reported
1.113 +
1.114 + // Identify the cause of the interrupt. If this can be achieved by reading a single register,
1.115 + // code similar to the following could be used:
1.116 + // intStatus = AsspRegister::Read32(a->iChannelBase + KIntStatusOffset);
1.117 +
1.118 + // Optional (not required if asynchronous channel capture is not supported)
1.119 + // If the cause of the interrupt is completion of asynchronous channel capture, the ISR will check the appropriate
1.120 + // indicator for confirmation of success - for a real PSL, this may be by querying a bitmask in a register. For the template PSL,
1.121 + // however, a dummy member variable (iAsyncConfig) has been used to represent the asynchronous operation instead.
1.122 + //
1.123 + // if(iAsyncConfig == 1) // Replace with a check of the indicator that the interrupt was due to asynchrous channel capture
1.124 + // {
1.125 + // // The PIL function ChanCaptureCallback is now to be invoked. It takes as an argument either KErrNone or a
1.126 + // // system-wide error code to indicate the cause of failure. For a real PSL, the argument would likely be determined
1.127 + // // by reading a bitmask in a status register - but for the template port, just use KErrNone.
1.128 + // //
1.129 + // a->ChanCaptureCallback(KErrNone);
1.130 + // return;
1.131 + // }
1.132 +
1.133 + // If an interrupt indicates that a transfer has started, or that it has now ended, (such as a chip select
1.134 + // line transition for a SPI bus the member variable iInProgress should be modified accordingly. This should
1.135 + // be done under the guard of spin lock macros since iInProgress can be accessed in the context of the Client
1.136 + // thread (in DoRequest, ProcessData and InitTransfer). The following structure should be adopted:
1.137 + // intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);
1.138 + // <access a->iInProgress>
1.139 + // __SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);
1.140 + //
1.141 + // If a transfer has ended before the expected amount of data has been transfered, function NotifyClientEnd
1.142 + // should be called, as follows:
1.143 + // a->NotifyClientEnd(a);
1.144 + // return; // Return now - the interrupt indicated transfer end, not receipt or transmission of data.
1.145 +
1.146 + // The transfers that had been started are indicated by the bitmask held in member variable iTrigger.
1.147 + // This must be accessed under the guard of a spin lock since it can be accessed in the context of the
1.148 + // Client thread (in DoRequest, ProcessData and InitTransfer). The following structure should be adopted:
1.149 + // intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);
1.150 + // trigger = a->iTrigger;
1.151 + // __SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);
1.152 +
1.153 + // If the interrupt was raised for a Tx event, and a Tx transfer had been started (so the interrupt was not spurious)
1.154 + // then either prepare the next data to send, or, if all the data has been sent, call the PIL function NotifyClient
1.155 + // with bitmask (ETxAllBytes | ETxUnderrun) so that, if the Client specified a ETxUnderrun notification, it will be alerted
1.156 + // and can determine whether another buffer of data should be provide for transmission.
1.157 + // Code similar to the following could be used:
1.158 + // if(intStatus & KTxInterruptBitMask)
1.159 + // {
1.160 + // if(trigger & ETransmit)
1.161 + // {
1.162 + // // Interrupt was not spurious
1.163 + // if(a->iTxData == a->iTxDataEnd)
1.164 + // {
1.165 + // // All the data to be transmitted has been sent, so call the PIL method NotifyClient
1.166 + // a->NotifyClient(ETxAllBytes | ETxUnderrun);
1.167 + // }
1.168 + // else
1.169 + // {
1.170 + // // There is more data to be sent
1.171 + // // TUint8 nextTxValue = *iTxData; // For this example, assumes one byte of data is to be transmitted
1.172 + // // but if operating in 16-bit mode, bytes may need arranging for
1.173 + // // endianness
1.174 + //
1.175 + // // Write to the Tx register with something similar to the following:
1.176 + // // AsspRegister::Write32(iChannelBase + KTxFifoOffset, nextTxValue);
1.177 + //
1.178 + // iTxData += iWordSize; // Then increment the pointer to the data. In this example, 8-bit mode is assumed
1.179 + // // (iWordSize=1), but if operating in 16-bit mode iTxData would be incremented
1.180 + // // by the number of bytes specified in iWordSize
1.181 + // }
1.182 + // }
1.183 + // }
1.184 +
1.185 + // If the interrupt was raised for a Rx event, and a Rx transfer had been started (so the interrupt was not spurious)
1.186 + // read the received data from the hardware to the buffer. If a Rx FIFO is being used, use a loop to drain it - until
1.187 + // the FIFO is empty or the buffer is full. If data remains after the buffer is full, an RxOverrun condition has occurred
1.188 + // - so the PIL function NotifyClient should be called with bitmask (ERxAllBytes | ERxOverrun) so that, if the Client specified
1.189 + // a ERxOverrun notification, it will be alerted and can determine whether another buffer should be provided to continue reception.
1.190 + // Code similar to the following could be used:
1.191 + // if(intStatus & KRxInterruptBitMask)
1.192 + // {
1.193 + // if(trigger & EReceive)
1.194 + // {
1.195 + // // Interrupt was not spurious
1.196 + // while(AsspRegister::Read32(a->iChannelBase + KRxFifoLevelOffset))
1.197 + // {
1.198 + // if((a->iRxData - a->iRxDataEnd) >= a->iWordSize)
1.199 + // {
1.200 + // // Space remains in the buffer, so copy the received data to it
1.201 + // TUint8 nextRxValue = AsspRegister::Read32(a->iChannelBase + KRxFifoOffset);
1.202 + // *a->iRxData = nextRxValue; // For this example, assumes one byte of data is to be transmitted
1.203 + // // but if operating in 16-bit mode, bytes may need arranging for
1.204 + // // endianness
1.205 + //
1.206 + // a->iRxData += a->iWordSize; // Then increment the pointer to the data. In this example, 8-bit mode is assumed
1.207 + // // (iWordSize=1), but if operating in 16-bit mode iRxData would be incremented
1.208 + // // by the number of bytes specified in iWordSize
1.209 + // }
1.210 + // else
1.211 + // {
1.212 + // // The buffer is full but more data has been received - so there is an RxOverrun condition
1.213 + // // Disable the hardware from receiving any more data and call the PIL function NotifyClient
1.214 + // // with bitmask (ERxAllBytes | ERxOverrun).
1.215 + // AsspRegister::Write32(a->iChannelBase + KRxFifoControl, KRxFifoDisableBitMask);
1.216 + // a->NotifyClient(ERxAllBytes | ERxOverrun);
1.217 + // break;
1.218 + // }
1.219 + // }
1.220 + // }
1.221 + // else
1.222 + // {
1.223 + // // If the interrupt was spurious, ignore the data, and reset the FIFO
1.224 + // AsspRegister::Write32(a->iChannelBase + KRxFifoControl, KRxFifoClearBitMask);
1.225 + // }
1.226 +
1.227 + // Once the interrupts have been processed, clear the source. If this can be achieve by writing to
1.228 + // a single register, code similar to the following could be used:
1.229 + // AsspRegister::Write32(a->iChannelBase + KIntStatusOffset, KAIntBitMask);
1.230 +
1.231 + }
1.232 +
1.233 +
1.234 +// Constructor, first stage
1.235 +//
1.236 +// The PSL is responsible for setting the channel number - this is passed as the first parameter to
1.237 +// this overload of the base class constructor
1.238 +//
1.239 +DIicBusChannelSlavePsl::DIicBusChannelSlavePsl(TInt aChannelNumber, TBusType aBusType, TChannelDuplex aChanDuplex) :
1.240 + DIicBusChannelSlave(aBusType, aChanDuplex, 0), // Base class constructor. Initalise channel ID to zero.
1.241 + iHwGuardTimer(TimeoutCallback, this) // Timer to guard against hardware timeout
1.242 + {
1.243 + iChannelNumber = aChannelNumber;
1.244 + __KTRACE_OPT(KIIC, Kern::Printf("DIicBusChannelSlavePsl::DIicBusChannelSlavePsl, iChannelNumber = %d\n", iChannelNumber));
1.245 + }
1.246 +
1.247 +
1.248 +// Second stage construction
1.249 +//
1.250 +// Allocate and initialise objects required by the PSL channel implementation
1.251 +//
1.252 +TInt DIicBusChannelSlavePsl::DoCreate()
1.253 + {
1.254 + __KTRACE_OPT(KIIC, Kern::Printf("\nDIicBusChannelSlavePsl::DoCreate, ch: %d \n", iChannelNumber));
1.255 +
1.256 + TInt r = KErrNone;
1.257 +
1.258 + // PIL Base class initialization.
1.259 + r = Init();
1.260 + if(r == KErrNone)
1.261 + {
1.262 + // At a minimum, this function must set the channel's unique channel ID.
1.263 + // When the channel is captured, this value will be combined with an instance count
1.264 + // provided by the PIL to generate a value that will be used by a client as a unique
1.265 + // identifer in subsequent calls to the Slave API.
1.266 + //
1.267 + // There is no set format for the ID, it just needs to be unique.
1.268 + // Un-comment and complete the following line:
1.269 +// iChannelId =
1.270 +
1.271 + // This method may also be concerned with setting the base register address iChannelBase), and allocating
1.272 + // any objects that will be required to support operaton until the channel is deleted.
1.273 + //
1.274 + // Un-comment and complete the following line:
1.275 +// iChannelBase =
1.276 + }
1.277 + return r;
1.278 + }
1.279 +
1.280 +// static method used to construct the DIicBusChannelSlavePsl object.
1.281 +DIicBusChannelSlavePsl* DIicBusChannelSlavePsl::New(TInt aChannelNumber, const TBusType aBusType, const TChannelDuplex aChanDuplex)
1.282 + {
1.283 + __KTRACE_OPT(KIIC, Kern::Printf("DIicBusChannelSlavePsl::NewL(): aChannelNumber = %d, BusType =%d", aChannelNumber, aBusType));
1.284 + DIicBusChannelSlavePsl *pChan = new DIicBusChannelSlavePsl(aChannelNumber, aBusType, aChanDuplex);
1.285 +
1.286 + TInt r = KErrNoMemory;
1.287 + if (pChan)
1.288 + {
1.289 + r = pChan->DoCreate();
1.290 + }
1.291 + if (r != KErrNone)
1.292 + {
1.293 + delete pChan;
1.294 + pChan = NULL;
1.295 + }
1.296 +
1.297 + return pChan;
1.298 + }
1.299 +
1.300 +
1.301 +// Validates the configuration information specified by the client when capturing the channel
1.302 +//
1.303 +// Called by the PIL as part of the Slave CaptureChannel processing
1.304 +//
1.305 +// If the pointer to the header is NULL, return KErrArgument.
1.306 +// If the content of the header is not valid for this channel, return KErrNotSupported.
1.307 +//
1.308 +TInt DIicBusChannelSlavePsl::CheckHdr(TDes8* aHdrBuff)
1.309 + {
1.310 + TInt r = KErrNone;
1.311 +
1.312 + if(!aHdrBuff)
1.313 + {
1.314 + r = KErrArgument;
1.315 + }
1.316 + else
1.317 + {
1.318 + // Check that the contents of the header are valid
1.319 + //
1.320 + // The header will be specific to a particular bus type. Using a fictional
1.321 + // bus type Abc,code similar to the following could be used to validate each
1.322 + // member of the header:
1.323 + //
1.324 + // TConfigAbcBufV01* headerBuf = (TConfigAbcBufV01*) aHdrBuff;
1.325 + // TConfigAbcV01 &abcHeader = (*headerBuf)();
1.326 + // if( (abcHeader.iHeaderMember < ESomeMinValue) ||
1.327 + // (abcHeader.iHeaderMember > ESomeMaxValue))
1.328 + // {
1.329 + // __KTRACE_OPT(KIIC, Kern::Printf("iHeaderMember %d not supported",abcHeader.iHeaderMember));
1.330 + // r = KErrNotSupported;
1.331 + // }
1.332 +
1.333 + }
1.334 + __KTRACE_OPT(KIIC, Kern::Printf("DIicBusChannelSlavePsl::CheckHdr() r %d", r));
1.335 +
1.336 + return r;
1.337 + }
1.338 +
1.339 +
1.340 +// Method called in the context of the client thread, as a consequence of the PSL invocation of the
1.341 +// PIL method NotifyClient when a bus event occurs.
1.342 +//
1.343 +// This method updates the bitmask of requested operations (held in member variable iTrigger) and the
1.344 +// PIL counts of data received and transmitted. If the event was a bus error, the bitmask of requested operations
1.345 +// is cleared.
1.346 +//
1.347 +void DIicBusChannelSlavePsl::ProcessData(TInt aTrigger, TIicBusSlaveCallback* aCb)
1.348 + {
1.349 + __KTRACE_OPT(KIIC, Kern::Printf("DIicBusChannelSlavePsl::ProcessData(), trigger: %x\n", aTrigger));
1.350 +
1.351 + TInt intState;
1.352 +
1.353 + // If using the iInProgress member variable to indicate transitions on a chip-select line, and an interrupt
1.354 + // occurred as a transfer was to end, then must ensure the transmission of data has ceased.
1.355 + //
1.356 + // Must use spin lock to guard access since iInProgress is accessed by the ISR
1.357 + //
1.358 + TInt inProgress;
1.359 + intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);
1.360 + inProgress = iInProgress;
1.361 + __SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);
1.362 + //
1.363 + if(!inProgress && // Transfer has now ended
1.364 + (aTrigger & (ERxAllBytes | ETxAllBytes))) // Master has not yet finished transferring data
1.365 + {
1.366 + // Use the guard timer to make sure that transfer ends with an expected time - if this does not cease
1.367 + // before the timer expires, iTransactionStatus will be set to KErrTimedOut by the callback function TimeoutCallback
1.368 + //
1.369 + // Poll the relevant register to check for transfer activity, using code similar to the following:
1.370 + // TInt8 transferring = AsspRegister::Read32(iChannelBase + KStatusRegisterOffset) & KTransferringBitMask);
1.371 + // For the template port, use a dummy variable instead of the register access (transferring = 1)
1.372 + //
1.373 + TInt8 transferring = 1;
1.374 + iTransactionStatus = KErrNone;
1.375 + iHwGuardTimer.OneShot(NKern::TimerTicks(KTimeoutValue));
1.376 +
1.377 + while((iTransactionStatus == KErrNone) &&
1.378 + transferring); // Replace transferring with a register read, as described above
1.379 +
1.380 + // At this point, either the transfer has ceased, or the timer expired - in either case, may disable the interrupt
1.381 + // for the transfer now, using code similar to the following:
1.382 + // AsspRegister::Write32(iChannelBase + KIntEnableRegisterOffset, KIntDisableBitMask);
1.383 +
1.384 + // Check for guard timer expiry
1.385 + if(iTransactionStatus != KErrNone)
1.386 + {
1.387 + __KTRACE_OPT(KIIC, Kern::Printf("DIicBusChannelSlavePsl::ProcessData - Transaction timed-out"));
1.388 + return;
1.389 + }
1.390 + else
1.391 + {
1.392 + iHwGuardTimer.Cancel();
1.393 + }
1.394 +
1.395 + // If all transfer activity has now ceased, clear iTrigger
1.396 + // Must use spin lock to guard access since iInProgress is accessed by the ISR
1.397 + //
1.398 + intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);
1.399 + iTrigger = 0;
1.400 + __SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);
1.401 + }
1.402 +
1.403 + // If the PSL called the PIL function NotifyClient to indicate transfer activity (or error), the reason
1.404 + // will be specified as a bitmask in aTrigger
1.405 + // - if a Rx event occurred, the ERxAllBytes flag will be set
1.406 + // - if a Tx event occurred, the ETxAllBytes flag will be set
1.407 + // - if a bus error occurred, the EGeneralBusError flag will be set
1.408 + //
1.409 + if(aTrigger & ERxAllBytes)
1.410 + {
1.411 + __KTRACE_OPT(KIIC, Kern::Printf("ProcessData - Rx Buf: %x\n", iRxData));
1.412 + __KTRACE_OPT(KIIC, Kern::Printf("ProcessData - Rx Bufend: %x\n", iRxDataEnd));
1.413 +
1.414 + // Clear the internal EReceive flag
1.415 + // This must be done under guard of a spin lock since iTrigger is accessed by the ISR
1.416 + intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);
1.417 + iTrigger &= ~EReceive;
1.418 + __SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);
1.419 +
1.420 + // Update the PIL count of Rx data (in the Callback object)
1.421 + aCb->SetRxWords(iNumRxWords - ((iRxDataEnd - iRxData) / iWordSize));
1.422 + }
1.423 + //
1.424 + if(aTrigger & ETxAllBytes)
1.425 + {
1.426 + __KTRACE_OPT(KIIC, Kern::Printf("ProcessData - Tx Buf: %x\n", iTxData));
1.427 + __KTRACE_OPT(KIIC, Kern::Printf("ProcessData - Tx Bufend: %x\n", iTxDataEnd));
1.428 +
1.429 + // Clear the internal ETransmit flag..
1.430 + // This must be done under guard of a spin lock since iTrigger is accessed by the ISR
1.431 + intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);
1.432 + iTrigger &= ~ETransmit;
1.433 + __SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);
1.434 +
1.435 + // Update the PIL count of Tx data (in the Callback object)
1.436 + aCb->SetTxWords(iNumTxWords - ((iTxDataEnd - iTxData) / iWordSize));
1.437 + }
1.438 + //
1.439 + if(aTrigger & EGeneralBusError)
1.440 + {
1.441 + __KTRACE_OPT(KIIC, Kern::Printf("BusError.."));
1.442 +
1.443 + // Clear and disable relevant interrupts, possibly using code similar to the following:
1.444 + // AsspRegister::Write32(iChannelBase + KIntEnableRegisterOffset, KIntDisableBitMask);
1.445 +
1.446 + // Clear internal flags
1.447 + // This must be done under guard of a spin lock since iTrigger is accessed by the ISR
1.448 + intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);
1.449 + iTrigger = 0;
1.450 + __SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);
1.451 + }
1.452 +
1.453 + // Set the callback's trigger, for use by the PIL
1.454 + aCb->SetTrigger(aTrigger | aCb->GetTrigger());
1.455 + }
1.456 +
1.457 +
1.458 +
1.459 +// Method to initialise the hardware in accordance with the data provided by the Client
1.460 +// in the configuration header when capturing the channel
1.461 +//
1.462 +// This method is called from DoRequest and is expected to return a value to indicate success
1.463 +// or a system wide error code to inform of the failure
1.464 +//
1.465 +TInt DIicBusChannelSlavePsl::ConfigureInterface()
1.466 + {
1.467 + __KTRACE_OPT(KIIC, Kern::Printf("ConfigureInterface()"));
1.468 +
1.469 + TInt r = KErrNone;
1.470 +
1.471 + // The header is stored in member variable iConfigHeader, and will be specific to a particular bus type.
1.472 + // Using a fictional bus type Abc, code similar to the following could be used to access each
1.473 + // member of the header:
1.474 + //
1.475 + // TConfigAbcBufV01* headerBuf = (TConfigAbcBufV01*) iConfigHeader;
1.476 + // TConfigAbcV01 &abcHeader = (*headerBuf)();
1.477 + // TInt value = abcHeader.iTintMember;
1.478 +
1.479 + // Initialising the hardware may be achieved with calls similar to the following:
1.480 + // AsspRegister::Write32(a->iChannelBase + KBusModeControlOffset, KIicPslModeControlBitMask);
1.481 + // GPIO::SetPinMode(aPinId, GPIO::EEnabled);
1.482 +
1.483 + // Binding an ISR may be achieved with calls similar to the following:
1.484 + // r = Interrupt::Bind(iRxInterruptId, DIicBusChannelSlavePsl::IicPslIsr, this);
1.485 + // r = Interrupt::Bind(iTxInterruptId, DIicBusChannelSlavePsl::IicPslIsr, this);
1.486 + // Enabling interrupts may be achieved with calls similar to the following:
1.487 + // r = Interrupt::Enable(iRxInterruptId);
1.488 + // r = Interrupt::Enable(iTxInterruptId);
1.489 +
1.490 + // Modifying a hardware register may not be a zero-delay operation. The member variable iHwGuardTimer could be used to guard a
1.491 + // continuous poll of the hardware register that checks for the required change in the setting; TimeoutCallback is already
1.492 + // assigned as the callback function for iHwGaurdTimer, and it modifies member variable iTransactionStatus to indicate a timeout
1.493 + // - so the two could be used together as follows:
1.494 + // iTransactionStatus = KErrNone;
1.495 + // iHwGuardTimer.OneShot(NKern::TimerTicks(KTimeoutValue));
1.496 + // while((iTransactionStatus == KErrNone) &&
1.497 + // AsspRegister::Read32(iChannelBase + KRegisterOffset) & KRegisterFlagBitMask);
1.498 + // if(iTransactionStatus != KErrNone)
1.499 + // {
1.500 + // r = KErrGeneral;
1.501 + // }
1.502 + // else
1.503 + // {
1.504 + // iHwGuardTimer.Cancel();
1.505 + // }
1.506 +
1.507 + // DoRequest checks the return value so the variable r should be modified in the event of failure with a system-wide error code
1.508 + // for example, if a register could not be modified,
1.509 + // r = KErrGeneral;
1.510 + // __KTRACE_OPT(KIIC, Kern::Printf("ConfigureInterface failed with error %d\n",r));
1.511 + return r;
1.512 + }
1.513 +
1.514 +
1.515 +// Method to start asynchronous initialisation of the hardware, in accordance with the data provided by the Client
1.516 +// in the configuration header when capturing the channel. This differs from ConfigureInterface in that it
1.517 +// merely starts the initialisation, then returns immediately;
1.518 +//
1.519 +// The PSL is expected to be implemented as an asynchronous state machine, where events (for example hardware
1.520 +// interrupts, or timer expiry) invoke callback functions that advance the state machine to the next state. Once
1.521 +// all the required states have been transitioned, so that the PSL part of the CaptureChannel processing is
1.522 +// complete, the ISR should be invoked, which will then call PIL method ChanCaptureCallback
1.523 +//
1.524 +// This method is called from DoRequest and is expected to return a value to indicate success
1.525 +// or a system wide error code to inform of the failure
1.526 +//
1.527 +TInt DIicBusChannelSlavePsl::AsynchConfigureInterface()
1.528 + {
1.529 + __KTRACE_OPT(KIIC, Kern::Printf("ConfigureInterface()"));
1.530 +
1.531 +// TInt r = KErrNone; // A real implementation would use this as the return value to indicate success / failure
1.532 +
1.533 + // Precisely what processing is done to 'start' the asynchronous processing is entirely platform-specific;
1.534 + // it may be the set-up and activation of a long-running operation that completes asynchronously. Regardless of what
1.535 + // is done, its completion is expected to result in the ISR being run.
1.536 + //
1.537 + // Whatever the operation, there must be some means of the ISR recognising that an asynchronous initialisation has
1.538 + // been performed
1.539 + // In a real PSL, this may be be checking a bitmask in a status register. For the template PSL, however,
1.540 + // a dummy class member will be used (iAsyncConfig)
1.541 + // Since this member will be accessed by the ISR, it should, strictly speaking, be accessed under the guard of a spin lock
1.542 + TInt intState;
1.543 + intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);
1.544 + iAsyncConfig = 1;
1.545 + __SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);
1.546 +
1.547 + return KErrNone; // A real implementation would return an indication of success / failure
1.548 + }
1.549 +
1.550 +// Method called from DoRequest to start Tx and-or Rx transfer.
1.551 +//
1.552 +// The method will initialise the hardware and pointers used to manage transfers, before returning a value to report success
1.553 +// (KErrNone) or a system-wide error code that indicates the cause of failure.
1.554 +//
1.555 +TInt DIicBusChannelSlavePsl::InitTransfer()
1.556 + {
1.557 + __KTRACE_OPT(KIIC, Kern::Printf("DIicBusChannelSlavePsl::InitTransfer()"));
1.558 +
1.559 + TInt r = KErrNone;
1.560 +
1.561 + // Local copies of member variables that must be accessed in a synchronised manner
1.562 + TInt inProgress;
1.563 + TInt trigger;
1.564 +
1.565 + TInt intState;
1.566 +
1.567 + // Check if a transfer is already in progress.
1.568 + // If variable iInProgress is being used, this must be determined in a synchronised manner because the ISR modifies it.
1.569 + // Bus types that do not rely on chip-select transitions may use an alternative method to indicate if a transfer is in
1.570 + // progress
1.571 + intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);
1.572 + inProgress = iInProgress;
1.573 + __SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);
1.574 +
1.575 + if(!inProgress)
1.576 + {
1.577 + // If no transfers are in progress, it may be necessary to initialise the hardware to support those that
1.578 + // are being requested. This may include FIFO and interrupt initialisation,
1.579 + //
1.580 + // Initialising the hardware may be achieved with calls similar to the following:
1.581 + // AsspRegister::Write32(iChannelBase + KBusModeControlOffset, KIicPslModeControlBitMask);
1.582 + // GPIO::SetPinMode(aPinId, GPIO::EEnabled);
1.583 + }
1.584 +
1.585 + // Check the current operations. This must be determined in a synchronised manner because ProcessData
1.586 + // runs in the context of the Client thread and it modifies the value of iTrigger
1.587 + intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);
1.588 + trigger = iTrigger;
1.589 + __SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);
1.590 +
1.591 + if(trigger & ETransmit)
1.592 + {
1.593 + // If Tx transfers were not previously active, it may be necessary to initialise the Tx hardware here, e.g.
1.594 + // AsspRegister::Write32(iChannelBase + KBusModeControlOffset, KIicPslTxModeBitMask);
1.595 +
1.596 + // Initialise the Tx pointers
1.597 + iTxData = iTxBuf + (iWordSize * iTxOffset);
1.598 + iTxDataEnd = iTxData + (iWordSize * iNumTxWords);
1.599 +
1.600 + __KTRACE_OPT(KIIC, Kern::Printf("Tx Buf: %x", iTxData));
1.601 + __KTRACE_OPT(KIIC, Kern::Printf("Tx Bufend: %x", iTxDataEnd));
1.602 +
1.603 + // If using a FIFO, copy the data to it until either the FIFO is full or all the data has been copied
1.604 + // This could be achieved with something similar to the following lines:
1.605 + // while(AsspRegister::Read32(iChannelBase + KFifoLevelOffset) <= (KFifoMaxLevel - iWordSize) &&
1.606 + // iTxData != iTxDataEnd)
1.607 + // For the template port, will just use a dummy variable (dummyFifoLvlChk )in place of the register read
1.608 + TInt dummyFifoLvlChk = 0;
1.609 + while((dummyFifoLvlChk) && // Replace this dummy variable with a read of the hardware
1.610 + (iTxData != iTxDataEnd))
1.611 + {
1.612 + // TUint8 nextTxValue = *iTxData; // For this example, assumes one byte of data is to be transmitted
1.613 + // but if operating in 16-bit mode, bytes may need arranging for
1.614 + // endianness
1.615 +
1.616 + // Write to the Tx register with something similar to the following:
1.617 + // AsspRegister::Write32(iChannelBase + KTxFifoOffset, nextTxValue);
1.618 +
1.619 + iTxData += iWordSize; // Then increment the pointer to the data. In this example, 8-bit mode is assumed
1.620 + // (iWordSize=1), but if operating in 16-bit mode iTxData would be incremented
1.621 + // by the number of bytes specified in iWordSize
1.622 + }
1.623 + // If a Tx FIFO is not being used, a single Tx value would be written - in which case the above loop would be replaced
1.624 +
1.625 + __KTRACE_OPT(KIIC, Kern::Printf("After adding:\n\rTx Buf: %x", iTxData));
1.626 + __KTRACE_OPT(KIIC, Kern::Printf("Tx Bufend: %x", iTxDataEnd));
1.627 + }
1.628 +
1.629 + if(trigger & EReceive)
1.630 + {
1.631 + // Initialise the Rx pointers
1.632 + iRxData = iRxBuf + (iWordSize * iRxOffset);
1.633 + iRxDataEnd = iRxData + (iWordSize * iNumRxWords);
1.634 +
1.635 + __KTRACE_OPT(KIIC, Kern::Printf("Rx Buffer: %x", iRxData));
1.636 + __KTRACE_OPT(KIIC, Kern::Printf("Rx Bufend: %x", iRxDataEnd));
1.637 +
1.638 + // If Rx transfers were not previously active, it may be necessary to initialise the Rx hardware here, e.g.
1.639 + // AsspRegister::Write32(iChannelBase + KBusModeControlOffset, KIicPslRxModeBitMask);
1.640 + }
1.641 +
1.642 + // If there is some common configuration required to support Rx, Tx transfers, may do it here
1.643 +
1.644 + return r;
1.645 + }
1.646 +
1.647 +
1.648 +// The gateway function for PSL implementation
1.649 +//
1.650 +// This method is called by the PIL to perform one or more operations indicated in the bitmask aOperation,
1.651 +// which corresponds to members of the TPslOperation enumeration.
1.652 +//
1.653 +TInt DIicBusChannelSlavePsl::DoRequest(TInt aOperation)
1.654 + {
1.655 + __KTRACE_OPT(KIIC, Kern::Printf("\nDIicBusChannelSlavePsl::DoRequest, Operation 0x%x\n", aOperation));
1.656 +
1.657 + TInt r = KErrNone;
1.658 + TInt intState;
1.659 +
1.660 + if (aOperation & EAsyncConfigPwrUp)
1.661 + {
1.662 + // The PIL has requested asynchronous operation of CaptureChannel.
1.663 + // The PSL should start the processing required for a channel to be captured, and then return immediately with
1.664 + // error code KErrNone (if the processing was started without error), so that the client thread will be unblocked.
1.665 + // The PSL is expected to be implemented as an asynchronous state machine, where events (for example hardware
1.666 + // interrupts, or timer expiry) invoke callback functions that advance the state machine to the next state. Once
1.667 + // all the required states have been transitioned, so that the PSL part of the CaptureChannel processing is
1.668 + // complete, the PSL should call the PIL function ChanCaptureCallback - this will lead to the Client-provided
1.669 + // callback being executed in the context of the client thread
1.670 + //
1.671 + __KTRACE_OPT(KIIC, Kern::Printf("EAsyncConfigPwrUp"));
1.672 + r = AsynchConfigureInterface();
1.673 + if (r != KErrNone)
1.674 + {
1.675 + __KTRACE_OPT(KIIC, Kern::Printf("AsynchConfigureInterface returned %d\n", r));
1.676 + }
1.677 + return r;
1.678 + }
1.679 +
1.680 + if (aOperation & ESyncConfigPwrUp)
1.681 + {
1.682 + // The PIL has requested synchronous operation of CaptureChannel.
1.683 + // The PSL should perform the processing required for a channel to be captured, and return a system-wide error
1.684 + // code when this is complete to indicate the status of the capture.
1.685 + // Capturing a channel is expected to include initialisation of the hardware to enable operation in accordance
1.686 + // with the configuration specified in the PIL member variable iConfigHeader, which holds the configuration
1.687 + // specified by the Client.
1.688 + //
1.689 + __KTRACE_OPT(KIIC, Kern::Printf("ESyncConfigPwrUp"));
1.690 + r = ConfigureInterface();
1.691 + if (r != KErrNone)
1.692 + {
1.693 + __KTRACE_OPT(KIIC, Kern::Printf("ConfigureInterface returned %d\n", r));
1.694 + return r;
1.695 + }
1.696 + }
1.697 +
1.698 + if (aOperation & ETransmit)
1.699 + {
1.700 + // The PIL has requested that a Tx operation be started.
1.701 + // Since the SPL may support simultaneous Rx and Tx operations, just set the flag in the iTrigger bitmask to
1.702 + // indicate what has been requested. If both Rx and Tx operations are requested, and one completes ahead of the other,
1.703 + // requiring the Client to provide a new buffer and associated call to DoRequest (as is the case if the Master wishes
1.704 + // to transfer more data than the Slave buffer supported), it is possible that the other transfer could complete while
1.705 + // this function is running; consequently, it may attempt to access iTrigger, and so cause data corruption. To cater for
1.706 + // such situations, use a spin lock to guard access to iTrigger.
1.707 + // When the same check has been performed for Rx, call the InitTransfer function to start the required transfers.
1.708 + //
1.709 + __KTRACE_OPT(KIIC, Kern::Printf("ETransmit"));
1.710 + intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);
1.711 + iTrigger |= ETransmit;
1.712 + __SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);
1.713 + }
1.714 +
1.715 + if (aOperation & EReceive)
1.716 + {
1.717 + // The PIL has requested that a Rx operation be started.
1.718 + // Since the SPL may support simultaneous Rx and Tx operations, just set the flag in the iTrigger bitmask to
1.719 + // indicate what has been requested. If both Rx and Tx operations are requested, and one completes ahead of the other,
1.720 + // requiring the Client to provide a new buffer and associated call to DoRequest (as is the case if the Master wishes
1.721 + // to transfer more data than the Slave buffer supported), it is possible that the other transfer could complete while
1.722 + // this function is running; consequently, it may attempt to access iTrigger, and so cause data corruption. To cater for
1.723 + // such situations, use a spin lock to guard access to iTrigger.
1.724 + // When the same check has been performed for Tx, call the InitTransfer function to start the required transfers.
1.725 + //
1.726 + __KTRACE_OPT(KIIC, Kern::Printf("EReceive"));
1.727 + intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);
1.728 + iTrigger |= EReceive;
1.729 + __SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);
1.730 + }
1.731 +
1.732 + if (aOperation & (EReceive | ETransmit))
1.733 + {
1.734 + // This code should only be executed once it has been checked whether Rx and Tx operations are required.
1.735 + r = InitTransfer();
1.736 + }
1.737 +
1.738 + if (aOperation & EAbort)
1.739 + {
1.740 + // The PIL has requested that the current transaction be aborted.
1.741 + // This is the case if the Client has not responded within an expected time to specify the next steps in
1.742 + // the transaction processing. The time allowed is specified by calling PIL function SetClientWaitTime, otherwise
1.743 + // the time defaults to KSlaveDefCWaitTime.
1.744 + // If the PSL is able to satisfy this request it should, at a minimum, disable interrupts and update the member
1.745 + // variables that indicate a transaction is in progress. If the PSL is unable to satisfy the request then the same
1.746 + // behaviour will follow as if this request had not been made, so there is no point in modifying the state variables.
1.747 + // If both Rx and Tx operations had been requested, and one completes ahead of the other, it is possible that the other
1.748 + // transfer could complete while this function is running; consequently, it may attempt to access iTrigger and iInProgress,
1.749 + // and so cause data corruption. To cater for such situations, use a spin lock to guard access to iTrigger.
1.750 + // The PIL makes no assumptions of whether the PSL can support this request or not, and does not check the return
1.751 + // value - so there is no need to set one.
1.752 + //
1.753 + TUint8 dummyCanAbort = 1; // Dummy variable to represent a check of if it is possible to abort the current transaction
1.754 + __KTRACE_OPT(KIIC, Kern::Printf("EAbort"));
1.755 + intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);
1.756 + if(dummyCanAbort)
1.757 + {
1.758 + // The spin lock has been acquired, so it is safe to modify data and hardware registers that may be accessed as part of
1.759 + // interrupt processing performed by an ISR - this is assuming that the ISR has been written to acquire the same spin lock.
1.760 + // Limit the processing to only that which is necessary to be processed under spin lock control, so as to not delay other
1.761 + // threads of execution that are waiting for the spin lock to be freed.
1.762 + // Hardware may be configured using code similar to the following:
1.763 + // AsspRegister::Write32(iChannelBase + KBusInterruptEnableOffset, KIicPslBusDisableBitMask);
1.764 + iInProgress = EFalse;
1.765 + iTrigger = 0;
1.766 + }
1.767 + __SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);
1.768 + // Having released the spin lock, now perform any actions that are not affected by pre-emption by an ISR, this may include code
1.769 + // such as the following
1.770 + // Interrupt::Disable(iRxInterruptId);
1.771 + // Interrupt::Disable(iTxInterruptId);
1.772 + }
1.773 +
1.774 + if (aOperation & EPowerDown)
1.775 + {
1.776 + // The PIL has requested that the channel be released.
1.777 + // If this channel is not part of a MasterSlave channel, the next Client will operate in Slave mode. In this case, it may only
1.778 + // be necessary to disable interrupts, and reset the channel hardware.
1.779 + // If this channel represents the Slave of a MasterSlave channel, it is possible that some of the hardware is shared between the
1.780 + // Master and Slave sub-channels. Since it may not be known whether the next Client of the parent channel will require operation
1.781 + // in either Master or Slave mode, some additional processing may be required to allow for subsequent Master operation (for example.
1.782 + // unbinding an interrupt).
1.783 + //
1.784 + __KTRACE_OPT(KIIC, Kern::Printf("EPowerDown"));
1.785 +
1.786 + // Resetting the hardware may be achieved with calls similar to the following:
1.787 + // AsspRegister::Write32(iChannelBase + KBusInterruptEnableOffset, KIicPslBusDisableBitMask);
1.788 + // GPIO::SetPinMode(aPinId, GPIO::EDisabled);
1.789 +
1.790 + // Disable interrupts may be achieved with calls similar to the following:
1.791 + // Interrupt::Disable(iRxInterruptId);
1.792 + // Interrupt::Disable(iTxInterruptId);
1.793 +
1.794 + // Unbinding an ISR may be achieved with calls similar to the following:
1.795 + // Interrupt::Unbind(iRxInterruptId);
1.796 + // Interrupt::Unbind(iTxInterruptId);
1.797 +
1.798 + // The PIL checks the return value so the variable r should be modified in the event of failure with a system-wide error code
1.799 + // for example, if a register could not be modified,
1.800 + // r = KErrGeneral;
1.801 + // __KTRACE_OPT(KIIC, Kern::Printf("EPowerDown failed with error %d\n",r));
1.802 +
1.803 + }
1.804 + return r;
1.805 + }
1.806 +