1\ingroup GroupModules Modules 2\defgroup GroupI2C I2C HAL 3 4Module I2C Architecture 5======================= 6 7# Overview {#module_i2c_architecture_overview} 8 9This module implements a Hardware Abstraction Layer (HAL) API for I2C 10transactions. 11 12# Architecture {#module_i2c_architecture_architecture} 13 14The I2C module provides an interface for modules to request transmission of data 15through an I2C bus, reception from an I2C bus and to request a transmission 16followed by a reception on an I2C bus. 17 18The I2C module defines a driver interface on which it relies to transfer/receive 19data to/from the bus. 20 21A response event notifies the caller of the transaction completion. 22 23The I2C module provides support for concurrent accesses to an I2C bus. If a 24I2C transaction is requested on an I2C bus while the bus is busy processing 25another transaction, the transaction request is queued. The queuing and 26processing of I2C transaction requests follow a FIFO logic. When a transaction 27is completed, the processing of the transaction request at the head of the 28queue, if any, is initiated. 29 30# Restriction {#module_i2c_architecture_restriction} 31 32The following features are unsupported. Support may be added in the future. 33 34- Acting like a target. 35- 10-bit target addressing. 36 37# Flow {#module_i2c_architecture_flow} 38 39The following schematic describes the transaction flow for an I2C controller 40transmission. It is assumed that all the sequence occurs without any 41concurrent access and that the driver handles the transmission asynchonously. 42The flow for a reception is similar. 43 44 Client I2C I2C Driver I2C ISR (Driver) 45 | | | | 46 | transmit_ | | | 47 +-+ as_controller | | | 48 | +-------------->+-+ | | 49 | | | +- - + | | 50 | +<--------------+-+ |process_ | | 51 +-+ | |event E1 | | 52 | | | | | 53 | +-+<- -+ | | 54 | | | transmit_ | | 55 | | | as_controller| | 56 | | +------------>+-+ | 57 | | +<------------+-+ | 58 | +-+ | | 59 | | | transaction +-+ 60 | | | _completed | | 61 | +-+<-------------+--------------+ | 62 | +- -+ | | | | 63 | process_ | +-+--------------+------------->+ | 64 | event E2 | | | | | 65 | +- >+-+ | +-+ 66 | | | | | 67 +-+<- - - - - - - +-+ | | 68 +-+ process_ | | | 69 | event R1 | | | 70 71 E1 : Request event 72 E2 : Request completed event 73 R1 : Response to the request event E1 74 ---> : Function call/return 75 - -> : Asynchronous call via the event/notification interface 76 77The client calls *transmit_as_controller* API of the I2C module. 78This function creates and sends the targeted I2C device request event which 79defines the selected target on the bus and the data to be transmitted. When 80processing the request event, the I2C module initiates the transfer by 81programming the I2C controller through the *transmit_as_controller* API of the 82I2C driver. 83 84An interrupt is asserted when the I2C transaction either completes or encounters 85an error. The I2C ISR calls the *transaction_completed* API of the I2C HAL 86module which sends a response event to indicate that transaction completed to 87the client. 88 89In the case of *transmit_then_receive_as_controller*, the I2C HAL does not send 90a event at the end of the transmission. Instead it starts the reception by 91calling *receive_as_controller* driver function. The event is then sent when 92the reception has completed. 93 94# Concurrent accesses {#module_i2c_architecture_concurrent_accesses} 95 96In case of concurrent access, transaction requests are queued using the 97framework delayed response facility. When the transaction request event is 98processed, the transaction is not initiated and its response delayed. This is 99illustrated by the following schematic: 100 101 Client I2C 102 | | 103 | transmit_ | 104 +-+ as_controller | 105 | +-------------->+-+ 106 | | | +- - + 107 | +<--------------+-+ |process_ 108 +-+ | |event E1 109 | | | 110 | +-+<- -+ 111 | | | 112 | | | Request response delayed 113 | | | 114 | +-+ 115 | | 116 | | 117 118 E1 : Request event 119 120When a transaction is completed on an I2C bus, the delayed response queue of 121the associated I2C module element is checked. If it is not empty, the processing 122of the request associated to the head of the queue is then initiated. This is 123illustrated in the following schematic where the pending request which is 124initiated is a reception request. 125 126 Client I2C I2C Driver I2C ISR (Driver) 127 ... 128 | | | | 129 | | | transaction +-+ 130 | | | _completed | | 131 | +-+<-------------+--------------+ | 132 | +- -+ | | | | 133 | process_ | +-+--------------+------------->+ | 134 | event E1 | | | | | 135 | +- >+-+ | +-+ 136 | | | | | 137 | | | receive_ | | 138 | | | as_controller| | 139 | | +------------>+-+ | 140 | | +<------------+-+ | 141 +-+<- - - - - - - + | | | 142 | | process_ | | | | 143 | | event R1 | | | | 144 +-+ +-+ | | 145 | | | | 146 ... 147 148 E1 : Request completed event 149 R1 : Response to the completed request 150 ---> : Function call/return 151 - -> : Asynchronous call via the event/notification interface 152 153Finally, in the case where the processing of the pending request completes 154immediately (synchronous handling by the driver) and another transaction request 155is pending, the processing of this last transaction request is not initiated 156immediately to avoid multiple transactions being processed within the same event 157processing. A reload event is then sent and the processing of the next pending 158request is initiated as part of the processing of the reload event. 159