| 1 | /** @file
|
|---|
| 2 | I2C I/O Protocol as defined in the PI 1.3 specification.
|
|---|
| 3 |
|
|---|
| 4 | The EFI I2C I/O protocol enables the user to manipulate a single
|
|---|
| 5 | I2C device independent of the host controller and I2C design.
|
|---|
| 6 |
|
|---|
| 7 | Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
|
|---|
| 8 | SPDX-License-Identifier: BSD-2-Clause-Patent
|
|---|
| 9 |
|
|---|
| 10 | @par Revision Reference:
|
|---|
| 11 | This protocol is from PI Version 1.3.
|
|---|
| 12 |
|
|---|
| 13 | **/
|
|---|
| 14 |
|
|---|
| 15 | #ifndef __I2C_IO_H__
|
|---|
| 16 | #define __I2C_IO_H__
|
|---|
| 17 |
|
|---|
| 18 | #include <Pi/PiI2c.h>
|
|---|
| 19 |
|
|---|
| 20 | #define EFI_I2C_IO_PROTOCOL_GUID { 0xb60a3e6b, 0x18c4, 0x46e5, { 0xa2, 0x9a, 0xc9, 0xa1, 0x06, 0x65, 0xa2, 0x8e }}
|
|---|
| 21 |
|
|---|
| 22 | ///
|
|---|
| 23 | /// I2C I/O protocol
|
|---|
| 24 | ///
|
|---|
| 25 | /// The I2C IO protocol enables access to a specific device on the I2C
|
|---|
| 26 | /// bus.
|
|---|
| 27 | ///
|
|---|
| 28 | /// Each I2C device is identified uniquely in the system by the tuple
|
|---|
| 29 | /// DeviceGuid:DeviceIndex. The DeviceGuid represents the manufacture
|
|---|
| 30 | /// and part number and is provided by the silicon vendor or the third
|
|---|
| 31 | /// party I2C device driver writer. The DeviceIndex identifies the part
|
|---|
| 32 | /// within the system by using a unique number and is created by the
|
|---|
| 33 | /// board designer or the writer of the EFI_I2C_ENUMERATE_PROTOCOL.
|
|---|
| 34 | ///
|
|---|
| 35 | /// I2C slave addressing is abstracted to validate addresses and limit
|
|---|
| 36 | /// operation to the specified I2C device. The third party providing
|
|---|
| 37 | /// the I2C device support provides an ordered list of slave addresses
|
|---|
| 38 | /// for the I2C device required to implement the EFI_I2C_ENUMERATE_PROTOCOL.
|
|---|
| 39 | /// The order of the list must be preserved.
|
|---|
| 40 | ///
|
|---|
| 41 | typedef struct _EFI_I2C_IO_PROTOCOL EFI_I2C_IO_PROTOCOL;
|
|---|
| 42 |
|
|---|
| 43 | /**
|
|---|
| 44 | Queue an I2C transaction for execution on the I2C device.
|
|---|
| 45 |
|
|---|
| 46 | This routine must be called at or below TPL_NOTIFY. For synchronous
|
|---|
| 47 | requests this routine must be called at or below TPL_CALLBACK.
|
|---|
| 48 |
|
|---|
| 49 | This routine queues an I2C transaction to the I2C controller for
|
|---|
| 50 | execution on the I2C bus.
|
|---|
| 51 |
|
|---|
| 52 | When Event is NULL, QueueRequest() operates synchronously and returns
|
|---|
| 53 | the I2C completion status as its return value.
|
|---|
| 54 |
|
|---|
| 55 | When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS
|
|---|
| 56 | indicating that the asynchronous I2C transaction was queued. The values
|
|---|
| 57 | above are returned in the buffer pointed to by I2cStatus upon the
|
|---|
| 58 | completion of the I2C transaction when I2cStatus is not NULL.
|
|---|
| 59 |
|
|---|
| 60 | The upper layer driver writer provides the following to the platform
|
|---|
| 61 | vendor:
|
|---|
| 62 |
|
|---|
| 63 | 1. Vendor specific GUID for the I2C part
|
|---|
| 64 | 2. Guidance on proper construction of the slave address array when the
|
|---|
| 65 | I2C device uses more than one slave address. The I2C bus protocol
|
|---|
| 66 | uses the SlaveAddressIndex to perform relative to physical address
|
|---|
| 67 | translation to access the blocks of hardware within the I2C device.
|
|---|
| 68 |
|
|---|
| 69 | @param[in] This Pointer to an EFI_I2C_IO_PROTOCOL structure.
|
|---|
| 70 | @param[in] SlaveAddressIndex Index value into an array of slave addresses
|
|---|
| 71 | for the I2C device. The values in the array
|
|---|
| 72 | are specified by the board designer, with the
|
|---|
| 73 | third party I2C device driver writer providing
|
|---|
| 74 | the slave address order.
|
|---|
| 75 |
|
|---|
| 76 | For devices that have a single slave address,
|
|---|
| 77 | this value must be zero. If the I2C device
|
|---|
| 78 | uses more than one slave address then the
|
|---|
| 79 | third party (upper level) I2C driver writer
|
|---|
| 80 | needs to specify the order of entries in the
|
|---|
| 81 | slave address array.
|
|---|
| 82 |
|
|---|
| 83 | \ref ThirdPartyI2cDrivers "Third Party I2C
|
|---|
| 84 | Drivers" section in I2cMaster.h.
|
|---|
| 85 | @param[in] Event Event to signal for asynchronous transactions,
|
|---|
| 86 | NULL for synchronous transactions
|
|---|
| 87 | @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure
|
|---|
| 88 | describing the I2C transaction
|
|---|
| 89 | @param[out] I2cStatus Optional buffer to receive the I2C transaction
|
|---|
| 90 | completion status
|
|---|
| 91 |
|
|---|
| 92 | @retval EFI_SUCCESS The asynchronous transaction was successfully
|
|---|
| 93 | queued when Event is not NULL.
|
|---|
| 94 | @retval EFI_SUCCESS The transaction completed successfully when
|
|---|
| 95 | Event is NULL.
|
|---|
| 96 | @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too
|
|---|
| 97 | large.
|
|---|
| 98 | @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the
|
|---|
| 99 | transaction.
|
|---|
| 100 | @retval EFI_INVALID_PARAMETER RequestPacket is NULL.
|
|---|
| 101 | @retval EFI_NO_MAPPING The EFI_I2C_HOST_PROTOCOL could not set the
|
|---|
| 102 | bus configuration required to access this I2C
|
|---|
| 103 | device.
|
|---|
| 104 | @retval EFI_NO_RESPONSE The I2C device is not responding to the slave
|
|---|
| 105 | address selected by SlaveAddressIndex.
|
|---|
| 106 | EFI_DEVICE_ERROR will be returned if the
|
|---|
| 107 | controller cannot distinguish when the NACK
|
|---|
| 108 | occurred.
|
|---|
| 109 | @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction
|
|---|
| 110 | @retval EFI_UNSUPPORTED The controller does not support the requested
|
|---|
| 111 | transaction.
|
|---|
| 112 |
|
|---|
| 113 | **/
|
|---|
| 114 | typedef
|
|---|
| 115 | EFI_STATUS
|
|---|
| 116 | (EFIAPI *EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST)(
|
|---|
| 117 | IN CONST EFI_I2C_IO_PROTOCOL *This,
|
|---|
| 118 | IN UINTN SlaveAddressIndex,
|
|---|
| 119 | IN EFI_EVENT Event OPTIONAL,
|
|---|
| 120 | IN EFI_I2C_REQUEST_PACKET *RequestPacket,
|
|---|
| 121 | OUT EFI_STATUS *I2cStatus OPTIONAL
|
|---|
| 122 | );
|
|---|
| 123 |
|
|---|
| 124 | ///
|
|---|
| 125 | /// I2C I/O protocol
|
|---|
| 126 | ///
|
|---|
| 127 | struct _EFI_I2C_IO_PROTOCOL {
|
|---|
| 128 | ///
|
|---|
| 129 | /// Queue an I2C transaction for execution on the I2C device.
|
|---|
| 130 | ///
|
|---|
| 131 | EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST QueueRequest;
|
|---|
| 132 |
|
|---|
| 133 | ///
|
|---|
| 134 | /// Unique value assigned by the silicon manufacture or the third
|
|---|
| 135 | /// party I2C driver writer for the I2C part. This value logically
|
|---|
| 136 | /// combines both the manufacture name and the I2C part number into
|
|---|
| 137 | /// a single value specified as a GUID.
|
|---|
| 138 | ///
|
|---|
| 139 | CONST EFI_GUID *DeviceGuid;
|
|---|
| 140 |
|
|---|
| 141 | ///
|
|---|
| 142 | /// Unique ID of the I2C part within the system
|
|---|
| 143 | ///
|
|---|
| 144 | UINT32 DeviceIndex;
|
|---|
| 145 |
|
|---|
| 146 | ///
|
|---|
| 147 | /// Hardware revision - ACPI _HRV value. See the Advanced Configuration
|
|---|
| 148 | /// and Power Interface Specification, Revision 5.0 for the field format
|
|---|
| 149 | /// and the Plug and play support for I2C web-page for restriction on values.
|
|---|
| 150 | ///
|
|---|
| 151 | UINT32 HardwareRevision;
|
|---|
| 152 |
|
|---|
| 153 | ///
|
|---|
| 154 | /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing
|
|---|
| 155 | /// the capabilities of the I2C host controller.
|
|---|
| 156 | ///
|
|---|
| 157 | CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities;
|
|---|
| 158 | };
|
|---|
| 159 |
|
|---|
| 160 | ///
|
|---|
| 161 | /// Reference to variable defined in the .DEC file
|
|---|
| 162 | ///
|
|---|
| 163 | extern EFI_GUID gEfiI2cIoProtocolGuid;
|
|---|
| 164 |
|
|---|
| 165 | #endif // __I2C_IO_H__
|
|---|
