IIC Kernel-side +Implementation Guide: Slave Channel

Implementing a slave channel

To implement 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 Platform Specific Layer (PSL). 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:

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

Your implementation of the PSL 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:

call the constructor +of DIicBusChannelSlave,
call the constructor +of your platform specific subclass of DIicBusChannelSlave,
set the timer,
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 PSL, 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 PSL. 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 IicBus::CaptureChannel() with instructions +to complete asynchronously. The platform specific 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 IicBus::CaptureChannel() with instructions +to complete synchronously. The platform specific layer should power up and +configure the hardware and return the result.
The argument is EPowerDown when +the client called Iic::ReleaseChannel(). The platform specific +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 platform specific layer should initialise +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 platform specific layer should initialise +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 platform specific layer +should stop the transfer by disabling interrupts, stopping ongoing and outstanding +operations and resetting the hardware and return failure.

Implementing ProcessData()

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 header +of the transaction 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(). +Initialises 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 NotifyClient() callback +function 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 PSL 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 PSL 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.