2 I2C Master Protocol as defined in the PI 1.3 specification.
4 This protocol manipulates the I2C host controller to perform transactions as a master
5 on the I2C bus using the current state of any switches or multiplexers in the I2C bus.
7 Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>
8 This program and the accompanying materials
9 are licensed and made available under the terms and conditions of the BSD License
10 which accompanies this distribution. The full text of the license may be found at
11 http://opensource.org/licenses/bsd-license.php
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 @par Revision Reference:
17 This protocol is from PI Version 1.3.
21 #ifndef __I2C_MASTER_H__
22 #define __I2C_MASTER_H__
26 #define EFI_I2C_MASTER_PROTOCOL_GUID { 0xcd72881f, 0x45b5, 0x4feb, { 0x98, 0xc8, 0x31, 0x3d, 0xa8, 0x11, 0x74, 0x62 }}
28 typedef struct _EFI_I2C_MASTER_PROTOCOL EFI_I2C_MASTER_PROTOCOL
;
31 Set the frequency for the I2C clock line.
33 This routine must be called at or below TPL_NOTIFY.
35 The software and controller do a best case effort of using the specified
36 frequency for the I2C bus. If the frequency does not match exactly then
37 the I2C master protocol selects the next lower frequency to avoid
38 exceeding the operating conditions for any of the I2C devices on the bus.
39 For example if 400 KHz was specified and the controller's divide network
40 only supports 402 KHz or 398 KHz then the I2C master protocol selects 398
41 KHz. If there are not lower frequencies available, then return
44 @param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure
45 @param[in] BusClockHertz Pointer to the requested I2C bus clock frequency
46 in Hertz. Upon return this value contains the
47 actual frequency in use by the I2C controller.
49 @retval EFI_SUCCESS The bus frequency was set successfully.
50 @retval EFI_ALREADY_STARTED The controller is busy with another transaction.
51 @retval EFI_INVALID_PARAMETER BusClockHertz is NULL
52 @retval EFI_UNSUPPORTED The controller does not support this frequency.
57 (EFIAPI
*EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY
) (
58 IN CONST EFI_I2C_MASTER_PROTOCOL
*This
,
59 IN OUT UINTN
*BusClockHertz
63 Reset the I2C controller and configure it for use
65 This routine must be called at or below TPL_NOTIFY.
67 The I2C controller is reset. The caller must call SetBusFrequench() after
70 @param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure.
72 @retval EFI_SUCCESS The reset completed successfully.
73 @retval EFI_ALREADY_STARTED The controller is busy with another transaction.
74 @retval EFI_DEVICE_ERROR The reset operation failed.
79 (EFIAPI
*EFI_I2C_MASTER_PROTOCOL_RESET
) (
80 IN CONST EFI_I2C_MASTER_PROTOCOL
*This
84 Start an I2C transaction on the host controller.
86 This routine must be called at or below TPL_NOTIFY. For synchronous
87 requests this routine must be called at or below TPL_CALLBACK.
89 This function initiates an I2C transaction on the controller. To
90 enable proper error handling by the I2C protocol stack, the I2C
91 master protocol does not support queuing but instead only manages
92 one I2C transaction at a time. This API requires that the I2C bus
93 is in the correct configuration for the I2C transaction.
95 The transaction is performed by sending a start-bit and selecting the
96 I2C device with the specified I2C slave address and then performing
97 the specified I2C operations. When multiple operations are requested
98 they are separated with a repeated start bit and the slave address.
99 The transaction is terminated with a stop bit.
101 When Event is NULL, StartRequest operates synchronously and returns
102 the I2C completion status as its return value.
104 When Event is not NULL, StartRequest synchronously returns EFI_SUCCESS
105 indicating that the I2C transaction was started asynchronously. The
106 transaction status value is returned in the buffer pointed to by
107 I2cStatus upon the completion of the I2C transaction when I2cStatus
108 is not NULL. After the transaction status is returned the Event is
111 Note: The typical consumer of this API is the I2C host protocol.
112 Extreme care must be taken by other consumers of this API to prevent
113 confusing the third party I2C drivers due to a state change at the
114 I2C device which the third party I2C drivers did not initiate. I2C
115 platform specific code may use this API within these guidelines.
117 @param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure.
118 @param[in] SlaveAddress Address of the device on the I2C bus. Set the
119 I2C_ADDRESSING_10_BIT when using 10-bit addresses,
120 clear this bit for 7-bit addressing. Bits 0-6
121 are used for 7-bit I2C slave addresses and bits
122 0-9 are used for 10-bit I2C slave addresses.
123 @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET
124 structure describing the I2C transaction.
125 @param[in] Event Event to signal for asynchronous transactions,
126 NULL for asynchronous transactions
127 @param[out] I2cStatus Optional buffer to receive the I2C transaction
130 @retval EFI_SUCCESS The asynchronous transaction was successfully
131 started when Event is not NULL.
132 @retval EFI_SUCCESS The transaction completed successfully when
134 @retval EFI_ALREADY_STARTED The controller is busy with another transaction.
135 @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too
137 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the
139 @retval EFI_INVALID_PARAMETER RequestPacket is NULL
140 @retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter
141 @retval EFI_NO_RESPONSE The I2C device is not responding to the slave
142 address. EFI_DEVICE_ERROR will be returned if
143 the controller cannot distinguish when the NACK
145 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction
146 @retval EFI_UNSUPPORTED The controller does not support the requested
152 (EFIAPI
*EFI_I2C_MASTER_PROTOCOL_START_REQUEST
) (
153 IN CONST EFI_I2C_MASTER_PROTOCOL
*This
,
154 IN UINTN SlaveAddress
,
155 IN EFI_I2C_REQUEST_PACKET
*RequestPacket
,
156 IN EFI_EVENT Event OPTIONAL
,
157 OUT EFI_STATUS
*I2cStatus OPTIONAL
161 /// I2C master mode protocol
163 /// This protocol manipulates the I2C host controller to perform transactions as a
164 /// master on the I2C bus using the current state of any switches or multiplexers
167 struct _EFI_I2C_MASTER_PROTOCOL
{
169 /// Set the clock frequency for the I2C bus.
171 EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY SetBusFrequency
;
174 /// Reset the I2C host controller.
176 EFI_I2C_MASTER_PROTOCOL_RESET Reset
;
179 /// Start an I2C transaction in master mode on the host controller.
181 EFI_I2C_MASTER_PROTOCOL_START_REQUEST StartRequest
;
184 /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing
185 /// the capabilities of the I2C host controller.
187 CONST EFI_I2C_CONTROLLER_CAPABILITIES
*I2cControllerCapabilities
;
190 extern EFI_GUID gEfiI2cMasterProtocolGuid
;
192 #endif // __I2C_MASTER_H__