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