IIC SHAI Implementation Layer: Master Channel

Implementing +a master channel

You should read and understand the template +port at \os\kernelhwsrv\bsptemplate\asspandvariant\template_assp\iic\iic_master as this will provide most of the information you need to implement +the master channel.

To implement the SHAI implementation layer +of an IIC channel as master you must write a class extending DIicBusChannelMaster. 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()
HandleSlaveTimeout()
CheckHdr()

You must also provide the following functionality:

validation of +input,
interrupt service +routines, and
reporting on +transmission status using the callback function CompleteRequest() with the relevant error code.

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 DoCreate()

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

call the PIL +function Init(),
create the DFC +queue for the driver and assign it to the driver by calling SetDfcQueue(),
initialize the +hardware, setting up interrupts, and
initialize the +other data structures representing the channel.

Implementing DoRequest()

DoRequest() is the gateway function to the SHAI implementation layer. It configures +the interface using the supplied configuration and processes transactions. +It takes one argument aTransaction, a pointer to +a TIicBusTransaction object created by the client: +you use the protected data functions of the PIL (listed below) to +extract the data needed to perform the associated transfers. Implement DoRequest() with functionality including the following:

Extract the +transaction parameters, that is the transaction header and transfers +(TIicBusTransfer),
configure the +interface with the configuration supplied in the transaction header,
set up the hardware +to start the first transfer, that is
- extract the +first transfer for one direction by calling GetTransHalfDuplexTransfer(),
- and if the transfer +is full duplex extract the first transfer for the second direction +by calling GetTransFullDuplexTransferPtr(),
in each case filling hardware FIFO buffers, enabling interrupts +and so on,
call the PIL +function StartSlaveTimeoutTimer(),
instruct the +hardware to start transmission, and
return either +an error code or KErrNone.

The effect of calling DoRequest() should +be to start the sequence of transfers comprising the transaction. +Typically, at the end of each transfer a hardware interrupt and associated +DFC callback occurs. If the PIL function StartSlaveTimeout() was called to monitor the duration of an individual transfer, the +PIL function CancelTimeout() should be called to +cancel the timer. If the transfer was successful and a call to get +the next transfers succeeds, the next transfer is set up. This continues +until either all the transfers have been processed, or there is an +error; after that, the PIL method DIicBusChannelMaster::CompleteRequest() is called to indicate the result.

Implementing HandleSlaveTimeout()

If the timer started by the PIL method StartSlaveTimeoutTimer() expires then the slave peripheral has not responded within the expected +time, and in such case some SHAI implementation layer-specific recovery +will be required; this is to be provided by the implementation of + HandleSlaveTimeout(). Implement it with functionality +including:

stop the transmission,
disable the +hardware, and
call the PIL +function CompleteRequest() with the KErrTimedOut error code.

Implementing CheckHdr()

Implement CheckHdr(). This is the function which is called in the +context of the client thread when the client calls QueueTransaction(). 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. Most are used to access private +data of the parent class. Others provide functionality which is generic +to IIC buses. These are:

DIicBusChannelMaster(), the constructor of the superclass DIicBusChannelMaster with arguments representing the bus type and the duplex settings.
Init(). Initializes DIicBusChannelMaster.
•SetDfcQ(). Sets the driver's DFC queue to +be used by DFCs in the PIL.
StartSlaveTimeOutTimer(). Starts a timer which causes the HandleSlaveTimeout() callback to run if the transaction (or transfer, SHAI implementation +layer decides) is not completed in the specified time.
CancelTimeOut();. Cancels the timeout timer which monitors the transaction time.
CompleteRequest(). Called to signal the PIL about completed transactions, transmission +errors and timeouts.

The functions accessing private members of TIicBusTransaction are:

+ + + +Function +Returns + + + + +

GetTransactionHeader()

A pointer to the configuration header.

+ + +

GetTransHalfDuplexTfrPtr()

A pointer to the head of the list of half duplex transfers.

+ + +

GetTransFullDuplexTfrPtr()

A pointer to the head of the list of full duplex transfers.

+ + +

GetTransCallback()

A pointer to the callback function

+ + +

GetTransFlags()

a pointer to the transaction flags

+ + + +

The functions accessing private members of TIicBusTransfer are:

+ + + +Function +Returns + + + + +

GetTferType()

The transfer type, EMasterRead or EMasterWrite, defined in the enumeration TReqType.

+ + +

GetTferBufGranularity()

The size of the buffer item in bits, typically 8 or 16.

+ + +

GetTferBuffer()

A pointer to the buffer where the data is stored.

+ + +

GetTferNextTfer()

A pointer to the next transfer in the transaction.

+ + + +

In addition to the above functions, there are additional +functions for accessing transactions with preambles, extending transactions +(multitransactions) and extended transactions with preamble. Refer +to the header file for details on these functions.