IIC SHAI Implementation Layer: Generic Considerations

Generic +architecture

Different IIC buses have a large amount of +functionality in common, but some functionality is specific to individual +implementations. For this reason, the IIC software has an architecture +consisting of two layers, the Platform Independent Layer (PIL) and +the SHAI implementation layer. The Platform Independent Layer is a +set of classes which encapsulate generic functionality and have been +implemented for you. The SHAI implementation layer is an interface +which you must implement yourself to encapsulate the functionality +specific to the platform you are working on.

You implement +the SHAI implementation layer by subclassing the classes of the Platform +Independent Layer and writing functions that provide an abstraction +of your hardware. To access the hardware you are strongly recommended +to use existing Symbian APIs such as e.g. AsspRegister to access hardware registers, or GPIO to access +GPIO pins).

An IIC channel operates in one of two modes, master +and slave, and there are separate master and slave APIs to be implemented. +In master mode, a channel and a client communicating with that channel +execute in two separate threads. In slave mode there is only one thread +for both channel and client.

The SHAI implementation and platform +independent APIs assume an interrupt-driven approach to implementation. +An event on hardware triggers an interrupt, which then signals this +event to the channel thread (where client is master) or client thread +(where client is slave). This means that implementation involves writing +interrupt service routines (ISRs) and a DFC queue to hold the callbacks +which respond to them. For both master and slave operation, the callbacks +are queued for execution on the client thread - so the client thread +must not be blocked, otherwise the callbacks will never run.

Clients of a master channel request transactions for execution in +either a synchronous or asynchronous manner. This results in the transaction +being entered in the channel’s request queue.

If synchronous +execution is requested, the client thread is blocked until the transaction +completes (either an ISR or polling mechanism in the SHAI implementation +layer recognizes the transaction has completed, and it calls the PIL +method CompleteRequest(), which will unblock the +client thread.

If asynchronous execution is requested, the +client thread is not blocked, and may continue to perform other tasks. +In the meanwhile, the channel thread will retrieve the next transaction +from the request queue and pass it to the SHAI implementation layer +for processing. When the transaction completes, the SHAI implementation +layer calls the PIL method CompleteRequest() and +this adds the client’s callback to the client’s DFC queue.

A client of a slave channel provides receive and transmit buffers +to be used and specifies the types of event (trigger) that it wishes +to be notified of. When ANY event occurs, the SHAI implementation +layer should call the PIL method NotifyClient(); +this determines whether the reported triggers qualify for notifying +the client – if so, the client callback is added to the client’s DFC +queue for execution. Note that the same mechanism is used to notify +the client of completion of asynchronous capture of the channel, and +of bus errors.

You should refer to the template port at \os\kernelhwsrv\bsptemplate\asspandvariant\template_assp\iic for more information.