| 1 | /** @file
|
|---|
| 2 | I2C Master Protocol as defined in the PI 1.3 specification.
|
|---|
| 3 |
|
|---|
| 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.
|
|---|
| 6 |
|
|---|
| 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
|
|---|
| 12 |
|
|---|
| 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.
|
|---|
| 15 |
|
|---|
| 16 | @par Revision Reference:
|
|---|
| 17 | This protocol is from PI Version 1.3.
|
|---|
| 18 |
|
|---|
| 19 | **/
|
|---|
| 20 |
|
|---|
| 21 | #ifndef __I2C_MASTER_H__
|
|---|
| 22 | #define __I2C_MASTER_H__
|
|---|
| 23 |
|
|---|
| 24 | #include <Pi/PiI2c.h>
|
|---|
| 25 |
|
|---|
| 26 | #define EFI_I2C_MASTER_PROTOCOL_GUID { 0xcd72881f, 0x45b5, 0x4feb, { 0x98, 0xc8, 0x31, 0x3d, 0xa8, 0x11, 0x74, 0x62 }}
|
|---|
| 27 |
|
|---|
| 28 | typedef struct _EFI_I2C_MASTER_PROTOCOL EFI_I2C_MASTER_PROTOCOL;
|
|---|
| 29 |
|
|---|
| 30 | /**
|
|---|
| 31 | Set the frequency for the I2C clock line.
|
|---|
| 32 |
|
|---|
| 33 | This routine must be called at or below TPL_NOTIFY.
|
|---|
| 34 |
|
|---|
| 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
|
|---|
| 42 | EFI_UNSUPPORTED.
|
|---|
| 43 |
|
|---|
| 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.
|
|---|
| 48 |
|
|---|
| 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.
|
|---|
| 53 |
|
|---|
| 54 | **/
|
|---|
| 55 | typedef
|
|---|
| 56 | EFI_STATUS
|
|---|
| 57 | (EFIAPI *EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY) (
|
|---|
| 58 | IN CONST EFI_I2C_MASTER_PROTOCOL *This,
|
|---|
| 59 | IN OUT UINTN *BusClockHertz
|
|---|
| 60 | );
|
|---|
| 61 |
|
|---|
| 62 | /**
|
|---|
| 63 | Reset the I2C controller and configure it for use
|
|---|
| 64 |
|
|---|
| 65 | This routine must be called at or below TPL_NOTIFY.
|
|---|
| 66 |
|
|---|
| 67 | The I2C controller is reset. The caller must call SetBusFrequench() after
|
|---|
| 68 | calling Reset().
|
|---|
| 69 |
|
|---|
| 70 | @param[in] This Pointer to an EFI_I2C_MASTER_PROTOCOL structure.
|
|---|
| 71 |
|
|---|
| 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.
|
|---|
| 75 |
|
|---|
| 76 | **/
|
|---|
| 77 | typedef
|
|---|
| 78 | EFI_STATUS
|
|---|
| 79 | (EFIAPI *EFI_I2C_MASTER_PROTOCOL_RESET) (
|
|---|
| 80 | IN CONST EFI_I2C_MASTER_PROTOCOL *This
|
|---|
| 81 | );
|
|---|
| 82 |
|
|---|
| 83 | /**
|
|---|
| 84 | Start an I2C transaction on the host controller.
|
|---|
| 85 |
|
|---|
| 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.
|
|---|
| 88 |
|
|---|
| 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.
|
|---|
| 94 |
|
|---|
| 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.
|
|---|
| 100 |
|
|---|
| 101 | When Event is NULL, StartRequest operates synchronously and returns
|
|---|
| 102 | the I2C completion status as its return value.
|
|---|
| 103 |
|
|---|
| 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
|
|---|
| 109 | signaled.
|
|---|
| 110 |
|
|---|
| 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.
|
|---|
| 116 |
|
|---|
| 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
|
|---|
| 128 | completion status
|
|---|
| 129 |
|
|---|
| 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
|
|---|
| 133 | Event is NULL.
|
|---|
| 134 | @retval EFI_ALREADY_STARTED The controller is busy with another transaction.
|
|---|
| 135 | @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too
|
|---|
| 136 | large.
|
|---|
| 137 | @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the
|
|---|
| 138 | transaction.
|
|---|
| 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
|
|---|
| 144 | occurred.
|
|---|
| 145 | @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction
|
|---|
| 146 | @retval EFI_UNSUPPORTED The controller does not support the requested
|
|---|
| 147 | transaction.
|
|---|
| 148 |
|
|---|
| 149 | **/
|
|---|
| 150 | typedef
|
|---|
| 151 | EFI_STATUS
|
|---|
| 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
|
|---|
| 158 | );
|
|---|
| 159 |
|
|---|
| 160 | ///
|
|---|
| 161 | /// I2C master mode protocol
|
|---|
| 162 | ///
|
|---|
| 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
|
|---|
| 165 | /// in the I2C bus.
|
|---|
| 166 | ///
|
|---|
| 167 | struct _EFI_I2C_MASTER_PROTOCOL {
|
|---|
| 168 | ///
|
|---|
| 169 | /// Set the clock frequency for the I2C bus.
|
|---|
| 170 | ///
|
|---|
| 171 | EFI_I2C_MASTER_PROTOCOL_SET_BUS_FREQUENCY SetBusFrequency;
|
|---|
| 172 |
|
|---|
| 173 | ///
|
|---|
| 174 | /// Reset the I2C host controller.
|
|---|
| 175 | ///
|
|---|
| 176 | EFI_I2C_MASTER_PROTOCOL_RESET Reset;
|
|---|
| 177 |
|
|---|
| 178 | ///
|
|---|
| 179 | /// Start an I2C transaction in master mode on the host controller.
|
|---|
| 180 | ///
|
|---|
| 181 | EFI_I2C_MASTER_PROTOCOL_START_REQUEST StartRequest;
|
|---|
| 182 |
|
|---|
| 183 | ///
|
|---|
| 184 | /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing
|
|---|
| 185 | /// the capabilities of the I2C host controller.
|
|---|
| 186 | ///
|
|---|
| 187 | CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities;
|
|---|
| 188 | };
|
|---|
| 189 |
|
|---|
| 190 | extern EFI_GUID gEfiI2cMasterProtocolGuid;
|
|---|
| 191 |
|
|---|
| 192 | #endif // __I2C_MASTER_H__
|
|---|
