IIC SHAI Implementation Layer: Slave Channel

Implementing +a slave channel

To implement the SHAI implementation layer +of an IIC channel as slave you must write a class extending DIicBusChannelSlave. You must implement certain pure virtual +functions of the parent class in the subclass. Those functions and +any other functions which you write in the subclass are called the +SHAI implementation layer. The functions inherited from the parent +class are called the Platform Independent Layer (PIL).

The +four functions you must implement are:

DoCreate()
DoRequest()
ProcessData()
CheckHdr()

You must also provide the following functionality:

From the constructor, +call the constructor of the base class DIicBusChannelSlave with arguments for bus type and duplex settings,
assign the channel +number (if you are using the IIC Controller) and channel ID, and
report events +signalled by the hardware by calling the NotifyClient() callback function with the appropriate trigger.

Your implementation of the SHAI implementation layer will +need to call functions of the PIL. You are restricted to using a certain +subset of these.

Implementing the Platform Specific Layer

Implementing DoCreate()

DoCreate() is the second phase constructor of your class. Implement it with +functionality including:

If you are using +the IIC controller, set the channel number,
call the Init() method of the base class, and
set the iChannelId member to an ID to be returned to the SHAI implementation +layer, which will use it to create a channel ID which is unique with +respect to other opened slave channels.

Implementing DoRequest()

DoRequest() is the gateway function to the SHAI implementation layer. Implement +it with functionality including:

configure the +interface,
set triggers +and initiate transfers, and
disable interrupts +in the event of an abort.

DoRequest() shall be called with an +argument representing one of various possible operations.

The argument +is EAsyncConfigPwrUp when the client called the +client API with instructions to complete asynchronously. The SHAI +implementation layer should power up and configure the hardware and +then call ChanCaptureCallback() with the result +as argument.
The argument +is ESyncConfigPwrUp when the client called client +called the client API with instructions to complete synchronously. +The SHAI implementation layer should power up and configure the hardware +and return the result.
The argument +is EPowerDown when the client called client called +the client API. The SHAI implementation layer should disable the interrupts, +stop any ongoing or outstanding operations and stop or reset the hardware +to its initial state.
The argument +is ETransmit when the client called Iic::SetNotificationTrigger() with any of the transmit triggers as argument. The SHAI implementation +layer should initialize the hardware and set up transmission buffers. +In a typical implementation, if the transmission has not yet started +it should also fill up the transmit FIFO and enable interrupts to +prepare for transmission, but this is not necessary if the transmission +is ongoing and the argument ETransmit was passed +because of a transmit underrun.
The argument +is EReceive if the client called Iic::SetNotificationTrigger with any of the receive triggers as argument. The SHAI implementation +layer should initialize the hardware and set up receive buffers. In +a typical implementation, if the transmission has not yet started +it should also flush or fill the receive FIFO and enable interrupts, +but this is not necessary if the transmission is ongoing and the argument EReceive was passed because of a receive overrun.
The argument +is EAbort if the timer of the master activity has +expired. The SHAI implementation layer should stop the transfer by +disabling interrupts, stopping ongoing and outstanding operations +and resetting the hardware and return failure.

Implementing ProcessData()

The easiest way +to understand this, is to review the template port at \os\kernelhwsrv\bsptemplate\asspandvariant\template_assp\iic\iic_slave.

ProcessData() is the function called by +the platform independent layer in response to NotifyClient(). It has two arguments representing a trigger aTrigger and a callback aCb. You implement it to modify +the callback

aTrigger, a trigger of class TInt, and
aCb, a callback of class TIicBusSlaveCallback.

You implement the function to update the callback according +to the value of the trigger.

If the trigger +is a receive trigger, update the callback with the number of words +already received to the buffer by calling
aCb->SetRxWords(numWordsReceived);
If the trigger +is a transmit trigger, update the callback with the number of words +already transmitted (moved to the hardware transmit FIFO) by calling
aCb->SetTxWords(numWordsTransmitted);
Whether the +trigger is receive or transmit, update the trigger member of the callback +containing the accumulated event history by calling
aCb->SetTrigger(trigger | aCb->GetTrigger());
where trigger is one of the receive or transmit +triggers or EGeneralBusError.

Implementing CheckHdr()

Implement CheckHdr(). This is the function which is called if the +client tries to capture the channel. Implement it with the following +functionality:

check if the +specified configuration is valid.

Using the Platform Independent Layer

You can +only use certain functions of the PIL. They provide functionality +which is generic to IIC buses. They are:

DIicBusChannelSlave(). The constructor of the superclass DIicBusChannelSlave.
Init(). Initializes DIicBusChannelSlave.
ChanCaptureCallback(). Called with the error code when asynchronous channel capture has +completed in response to DoRequest(EAsyncConfigPwrUp).
NotifyClient(). Called to notify the PIL (which then notifies the client) that +a hardware event of the passed in type has occurred.
SetMasterWaitTime(). Sets the timeout for the master to respond after the transmission +has been started.
GetMasterWaitTime(). Gets the timeout for the master to respond after the transmission +has been started.
SetClientWaitTime(). Sets the client wait time within which it is expected to respond +with the next operation.
GetClientWaitTime(). Gets the client wait time within which it is expected to respond +with the next operation.

Implementing event notification

A slave channel +reports events on the hardware by calling the PIL function NotifyClient() to pass the following notifications under +the stated conditions.

Pass ERxAllBytes if the transmission has stopped with all bytes +received.
Pass ETxAllBytes if the transmission has stopped with all bytes +transmitted.
Pass ERxUnderrun if the transmission has been stopped but the +receive buffer provided by the client is not full, indicating that +the master has sent less data than expected.
Pass ERxOverrun if the transmission has not been stopped but +the receive buffer provided by the client is full. The client should +respond to a receive overrun by
- providing new +receive buffer, and
- resetting its +receive notification triggers for instance by calling SetNotificationTrigger(ERxAllBytes).
To make this possible the SHAI implementation layer should +try to keep the receive hardware FIFO at the lowest possible level.
Pass ETxUnderrun if the transmission has not been stopped but +all the data in the transmit buffer provided by the client has been +transferred. The client should respond to a transmit underrun by
- providing new +transmit buffer, and
- resetting its +transmit notification triggers for instance by calling SetNotificationTrigger(ETxAllBytes).
To make this possible the SHAI implementation layer should +try to keep the transmit hardware FIFO at the highest possible level.
Pass ETxOverrun if the transmission has been stopped but not +all the data in the transmit buffer provided by the client has been +transferred. This indicates that the client specified a bigger buffer +for the transmission than the master needed to read from the slave.
Pass EGeneralBusError if a bus error has occurred, that is if +an interrupt signals a bus overrun or underrun indicating data corruption.