IIC Kernel-side +Implementation Guide: Master Channel

Implementing a master channel

To implement 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 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()
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 PSL 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(),
initialise the hardware, +setting up interrupts, and
initialise the other +data structures representing the channel.

Implementing DoRequest()

DoRequest() is +the gateway function to the PSL. It configures the interface using the supplied +configuration and processes transfers. It takes one argument aTransaction, +a pointer to a TIicBusTransaction object created by the +client: you use the private 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. At the end of +each transfer a hardware interrupt and associated DFC callback occurs. If +the transfer was successful and a call to get the next transfers succeeds, +the next transfer is set up.

Implementing HandleSlaveTimeout()

Implement HandleSlaveTimeout(). +This is the callback function which is triggered when a slave node times out. +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(). +Initialises DIicBusChannelMaster.
StartSlaveTimeOutTimer(). +Starts a timer which causes the HandleSlaveTimeout() callback +to run if the transaction is not completed in the specified time.
SetDfcQ(). +Sets the driver's DFC queue to be used by DFCs in the PIL.
CompleteRequest(). +Called to signal the PIL about completed transactions, transmission errors +and timeouts.
CancelTimeOut();. +Cancels the timeout timer which monitors the transaction time.

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 tothe head of the list of full duplex transfers.

+ + + +

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.

+ + + +