3 Copyright (c) 2004 - 2014, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials are licensed and made available under
6 the terms and conditions of the BSD License that accompanies this distribution.
7 The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php.
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
15 \section I2cDriverStack I2C Driver Stack
17 The following is a representation of the I<sup>2</sup>C (I2C)
18 driver stack and an I2C bus layout.
28 +--------+ +-----------------+
29 | Slave | | Third Party |
30 | Driver | | I2C Device |
32 +--------+ +-----------------+
38 | | I2C Bus Driver |------------------.
39 | +-----------------+ |
43 SLAVE | V MANAGEMENT | ACPI
44 | +-----------------+ |
45 | | I2C Host Driver |----------. |
46 | +-----------------+ | |
49 | | +-------=-------------+
50 | V | I2C Platform Driver |
51 | +-----------------+ +---------------------+
52 `------>| I2C Port Driver | | |
53 +-----------------+ | |
56 --------------------------------------------------
60 +-----------------+ | |
61 | I2C Controller | | |
62 +-----------------+ | |
64 ----------------------- | |
67 +----| High speed | | |
73 | Switch |<------------------` |
83 | Multiplexer |<-----------------------`
89 | +----| Third Party |
96 +------------| Third Party |
103 The platform hardware designer chooses the bus layout based upon
104 the platform, I2C chip and software requirements. The design uses
105 switches to truncate the bus to enable higher speed operation for a
106 subset of devices which are placed closer to the controller. When the
107 switch is on, the extended bus must operate at a lower speed. The
108 design uses multiplexer to create separate address spaces enabling
109 the use of multiple devices which would otherwise have conflicting
111 <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C
112 Specification</a> for more details.
114 N.B. Some operating systems may prohibit the changing of switches
115 and multiplexers in the I2C bus. In this case the platform hardware
116 and software designers must select a single I2C bus configuration
117 consisting of constant input values for the switches and multiplexers.
118 The platform software designer must then ensure that this I2C bus
119 configuration is enabled prior to passing control to the operating
122 The platform hardware designer needs to provide the platform software
123 designer the following data for each I2C bus:
125 1. Which controller controls this bus
127 2. A list of logic blocks contained in one or more I2C devices:
129 a. I2C device which contains this logic block
131 b. Logic block slave address
135 3. For each configuration of the switches and multiplexer
137 a. What is the maximum speed of operation
139 b. What devices are accessible
141 4. The settings for the switches and multiplexers when control is
142 given to the operating system.
144 \section ThirdPartyI2cDrivers Third Party I2C Drivers
146 This layer is I2C chip specific but platform and host controller
149 Third party I2C driver writers, typically silicon vendors, need
152 1. The device path node data that is used to select their
155 2. The order for the blocks of logic that get referenced
156 by the entries in the slave address array.
158 3. The hardware version of the I2C device, this value is passed
159 to the third party I2C driver to enable it to perform work
160 arounds for the specific hardware version. This value should
161 match the value in the ACPI _HRV tag.
163 The third party I2C driver uses relative addressing to abstract
164 the platform specific details of the I2C device. Using an
165 example I2C device containing an accelerometer and a magnetometer
166 which consumes two slave addresses, one for each logic block. The
167 third party I2C driver writer may choose to write two drivers, one
168 for each block of logic, in which case each driver refers to the
169 single I2C slave address using the relative value of zero (0).
170 However if the third party I2C driver writer chooses to write a
171 single driver which consumes multiple slave addresses then the
172 third party I2C driver writer needs to convey the order of the
173 I2C slave address entries in the slave address array to the
174 platform software designer. For the example:
180 The platform hardware designer picks the actual slave addresses
181 from the I2C device's data sheet and provides this information
182 to the platform software designer. The platform software designer
183 then places the slave addresses into the slave address array in the
184 order specified by the third party I2C driver writer. The third
185 party driver I2C writer then indirectly references this array by
186 specifying the index value as the relative slave address. The
187 relative value always starts at zero (0) and its maximum value is
188 the number of entries in slave address array minus one.
190 The slave address is specified as a 32-bit integer to allow room
191 for future slave address expansion. Only the port driver knows
192 the maximum slave address value. All other drivers and
193 applications must look for the EFI_NOT_FOUND status for the
194 indication that the maximum slave address was exceeded.
196 \section I2cBusDriver I2C Bus Driver
198 This layer is platform, host controller, and I2C chip independent.
200 The I2C bus driver creates a handle for each of the I2C devices
201 described within the platform driver. The I2C controller's device
202 path is extended with the device path node provided by the platform
203 driver and attached to the handle. The third party I2C device driver
204 uses the device path to determine if it may connect. For ACPI nodes,
205 the third party I2C driver should use the CID or CidString value.
207 The I2C bus driver validates the relative address for the I2C device
208 and then converts the relative value to an actual I2C slave address.
209 The request is then passed to the I2C host driver.
211 \section I2cHostDriver I2C Host Driver
213 This layer is platform, host controller, and I2C chip independent.
215 N.B. For proper operation of the I2C bus, only the I2C bus driver
216 and the I2C test application should connect to the I2C host driver
217 via the EFI_I2C_HOST_DRIVER_PROTOCOL.
219 The I2C host driver may access any device on the I2C bus. The I2C
220 host driver has the following responsibilities:
222 1. Limits the number of requests to the I2C port driver to one.
223 The I2C host driver holds on to additional requests until the
224 I2C port driver is available to process the request. The I2C
225 requests are issued in FIFO order to the I2C port driver.
227 2. Enable the proper I2C bus configuration before starting the
228 I2C request on the I2C port driver
230 I2C devices are addressed as the tuple: BusConfiguration:SlaveAddress.
231 I2C bus configuration zero (0) is the portion of the I2C bus that
232 connects to the host controller. The bus configuration specifies
233 the control values for the switches and multiplexers in the I2C bus.
234 After the switches and multiplexers are properly configured, the I2C
235 controller uses the slave address to access the requested I2C device.
237 Since the I2C driver stack supports asynchronous operations this
238 layer maintains a queue of I2C requests until the I2C controller
239 is available them. When a request reaches the head of the queue
240 the necessary bus configuration is enabled and then the request
241 is sent to the I2C port driver.
243 \section I2cPortDriver I2C Port Driver
245 This layer is I2C controller specific but platform independent.
247 This layer manipulates the I2C controller to perform an operation
248 on the I2C bus. This layer does not configure the I2C bus so it
249 is up to the caller to ensure that the I2C bus is in the proper
250 configuration before issuing the I2C request.
252 This layer typically needs the following information:
254 1. Host controller address
255 2. Controller's input clock frequency
257 Depending upon the I2C controller, more data may be necessary.
258 This layer may use any method to get these values: hard coded
259 values, PCD values, or may choose to communicate with the platform
260 layer using an undefined mechanism to get these values.
262 If the I2C port driver requires data from the platform driver then
263 the I2C port driver writer needs to provide the platform interface
264 details to the platform software designer.
266 \section I2cPlatformDriver I2C Platform Driver
268 When enabling access to I2C devices within UEFI, this driver
269 installs the EFI_I2C_ACPI_PROTOCOL to provide the I2C device
270 descriptions to the I2C bus driver using the EFI_I2C_DEVICE
271 structure. These descriptions include the bus configuration
272 number required for the I2C device, the slave address array
275 The EFI_I2C_BUS_CONFIGURATION_MANAGEMENT protocol is optional.
276 This protocol needs to be specified under the following conditions:
278 1. The I2C bus must operate at a frequency greater than 100 KHz
279 2. The I2C bus contains switches or multiplexers.
281 The EFI_I2C_BUS_CONFIGURATION_MANAGEMENT protocol enables the
282 I2C host driver to call into the I2C platform driver to enable
283 a specific I2C bus configuration and set its maximum clock speed.
285 The platform software designer collects the data requirements
286 from third party I2C driver writers, the I2C controller
287 driver writer, the EFI_I2C_ACPI_PROTOCOL and
288 EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL. The platform
289 software designer gets the necessary data from the platform
290 hardware designer. The platform software designer then builds
291 the data structures and implements the necessary routines to
292 construct the I2C platform driver.
294 \section I2cSwitches Switches and Multiplexers
296 There are some I2C switches and I2C multiplexers where the control
297 is done via I2C commands. When the control inputs come via the
298 same I2C bus that is being configured then the platform driver must
299 use the EFI_I2C_MASTER_PROTOCOL that is passed to the platform
300 driver. While the I2C host driver makes the call to the I2C
301 platform driver to configure the bus, the host driver keeps the
302 I2C port driver idle, to allow the I2C platform driver preform
303 the necessary configuration operations.
305 If however the configuration control is done via and I2C device
306 connected to a different I2C bus (host controller), then it is
307 possible for the platform software designer may choose between
310 1. Call into a third party I2C driver to manipulate the I2C
312 2. Call into the EFI_I2C_BUS_PROTOCOL if no third party I2C
313 driver exists for the I2C bus control device
314 3. Call into the EFI_I2C_HOST_PROTOCOL if the platform does
315 not expose the I2C bus control device.
319 #ifndef __I2C_MASTER_H__
320 #define __I2C_MASTER_H__
323 Declare the forward references
326 typedef struct _EFI_I2C_MASTER_PROTOCOL EFI_I2C_MASTER_PROTOCOL
; ///< I2C master protocol
329 /// I2C device operation
331 /// This structure provides the information necessary for an operation
336 /// Number of bytes to send to the I2C device
341 /// Number of bytes to read, set to zero for write only operations
346 /// Address of the buffer containing the data to send to the I2C device.
347 /// The WriteBuffer must be at least WriteBytes in length.
352 /// Address of the buffer to receive data from the I2C device. Use NULL
353 /// for write only operations. The ReadBuffer must be at least ReadBytes
359 /// Timeout for the I2C operation in 100 ns units
362 } EFI_I2C_REQUEST_PACKET
;
366 Set the I2C controller bus clock frequency.
368 This routine must be called at or below TPL_NOTIFY.
370 The software and controller do a best case effort of using the specified
371 frequency for the I2C bus. If the frequency does not match exactly then
372 the controller will use a slightly lower frequency to avoid
373 exceeding the operating conditions for any of the I2C devices on the bus.
374 For example if 400 KHz was specified and the controller's divide network
375 only supports 402 KHz or 398 KHz then the controller would be set to 398
376 KHz. However if the desired frequency is 400 KHz and the controller only
377 supports 1 MHz and 100 KHz then this routine would return EFI_UNSUPPORTED.
379 @param[in] This Address of an EFI_I2C_MASTER_PROTOCOL
381 @param[in] BusClockHertz New I2C bus clock frequency in Hertz
383 @retval EFI_SUCCESS The bus frequency was set successfully.
384 @retval EFI_UNSUPPORTED The controller does not support this frequency.
389 (EFIAPI
*EFI_I2C_MASTER_BUS_FREQUENCY_SET
) (
390 IN CONST EFI_I2C_MASTER_PROTOCOL
*This
,
391 IN UINTN BusClockHertz
395 Reset the I2C controller and configure it for use
397 This routine must be called at or below TPL_NOTIFY.
399 The I2C controller is reset and the I2C bus frequency is set to 100 KHz.
401 @param[in] This Address of an EFI_I2C_MASTER_PROTOCOL
407 (EFIAPI
*EFI_I2C_MASTER_RESET
) (
408 IN CONST EFI_I2C_MASTER_PROTOCOL
*This
412 Start an I2C operation on the host controller
414 This routine must be called at or below TPL_NOTIFY. For synchronous
415 requests this routine must be called at or below TPL_CALLBACK.
417 This function initiates an I2C operation on the controller.
419 The operation is performed by selecting the I2C device with its slave
420 address and then sending all write data to the I2C device. If read data
421 is requested, a restart is sent followed by the slave address and then
422 the read data is clocked into the I2C controller and placed in the read
423 buffer. When the operation completes, the status value is returned and
424 then the event is set.
426 N.B. The typical consumer of this API is the I2C host driver.
427 Extreme care must be taken by other consumers of this API to
428 prevent confusing the third party I2C drivers due to a state
429 change at the I2C device which the third party I2C drivers did
430 not initiate. I2C platform drivers may use this API within
433 N.B. This API supports only one operation, no queuing support
434 exists at this layer. This API assumes that the I2C bus is in
435 the correct configuration for the I2C request.
437 @param[in] This Address of an EFI_I2C_MASTER_PROTOCOL
439 @param[in] SlaveAddress Address of the device on the I2C bus.
440 @param[in] Event Event to set for asynchronous operations,
441 NULL for synchronous operations
442 @param[in] RequestPacket Address of an EFI_I2C_REQUEST_PACKET
443 structure describing the I2C operation
444 @param[out] I2cStatus Optional buffer to receive the I2C operation
447 @retval EFI_SUCCESS The operation completed successfully.
448 @retval EFI_ABORTED The request did not complete because the driver
450 @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.
451 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.
452 This could indicate the slave device is not present.
453 @retval EFI_INVALID_PARAMETER RequestPacket is NULL
454 @retval EFI_INVALID_PARAMETER TPL is too high
455 @retval EFI_NOT_FOUND SlaveAddress exceeds maximum address
456 @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for
457 the event and then read status pointed to by
459 @retval EFI_NO_RESPONSE The I2C device is not responding to the
460 slave address. EFI_DEVICE_ERROR may also be
461 returned if the controller cannot distinguish
462 when the NACK occurred.
463 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation
464 @retval EFI_TIMEOUT The transaction did not complete within an internally
465 specified timeout period.
470 (EFIAPI
*EFI_I2C_MASTER_START_REQUEST
) (
471 IN CONST EFI_I2C_MASTER_PROTOCOL
*This
,
472 IN UINTN SlaveAddress
,
473 IN EFI_EVENT Event OPTIONAL
,
474 IN CONST EFI_I2C_REQUEST_PACKET
*RequestPacket
,
475 OUT EFI_STATUS
*I2cStatus OPTIONAL
479 /// I2C master mode protocol
481 /// This protocol manipulates the I2C host controller to perform transactions as a
482 /// master on the I2C bus using the current state of any switches or multiplexers
485 struct _EFI_I2C_MASTER_PROTOCOL
{
487 /// Set the clock frequency for the I2C bus
489 EFI_I2C_MASTER_BUS_FREQUENCY_SET BusFrequencySet
;
492 /// Reset the I2C host controller
494 EFI_I2C_MASTER_RESET Reset
;
497 /// Start an I2C transaction in master mode on the host controller
499 EFI_I2C_MASTER_START_REQUEST StartRequest
;
502 /// The maximum number of bytes the I2C host controller
503 /// is able to receive from the I2C bus.
505 UINT32 MaximumReceiveBytes
;
508 /// The maximum number of bytes the I2C host controller
509 /// is able to send on the I2C bus.
511 UINT32 MaximumTransmitBytes
;
514 /// The maximum number of bytes in the I2C bus transaction.
516 UINT32 MaximumTotalBytes
;
520 /// GUID for the EFI_I2C_MASTER_PROTOCOL
522 extern EFI_GUID gEfiI2cMasterProtocolGuid
;
524 #endif // __I2C_MASTER_H__