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