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