]>
Commit | Line | Data |
---|---|---|
43e543bc EL |
1 | /** @file\r |
2 | Private data structures for the I2C DXE driver.\r | |
3 | \r | |
4 | This file defines common data structures, macro definitions and some module\r | |
5 | internal function header files.\r | |
6 | \r | |
d1102dba | 7 | Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>\r |
9d510e61 | 8 | SPDX-License-Identifier: BSD-2-Clause-Patent\r |
43e543bc EL |
9 | \r |
10 | **/\r | |
11 | \r | |
12 | #ifndef __I2C_DXE_H__\r | |
13 | #define __I2C_DXE_H__\r | |
14 | \r | |
15 | #include <Uefi.h>\r | |
16 | #include <Library/BaseMemoryLib.h>\r | |
17 | #include <Library/DebugLib.h>\r | |
18 | #include <Library/DevicePathLib.h>\r | |
19 | #include <Library/MemoryAllocationLib.h>\r | |
20 | #include <Library/TimerLib.h>\r | |
21 | #include <Library/UefiBootServicesTableLib.h>\r | |
22 | #include <Library/UefiDriverEntryPoint.h>\r | |
23 | #include <Library/UefiLib.h>\r | |
24 | \r | |
25 | #include <Protocol/DriverBinding.h>\r | |
26 | #include <Protocol/I2cEnumerate.h>\r | |
27 | #include <Protocol/I2cHost.h>\r | |
28 | #include <Protocol/I2cIo.h>\r | |
29 | #include <Protocol/I2cMaster.h>\r | |
30 | #include <Protocol/I2cBusConfigurationManagement.h>\r | |
31 | #include <Protocol/LoadedImage.h>\r | |
32 | \r | |
1436aea4 MK |
33 | #define I2C_DEVICE_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'D')\r |
34 | #define I2C_HOST_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'H')\r | |
35 | #define I2C_REQUEST_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'R')\r | |
43e543bc EL |
36 | \r |
37 | //\r | |
38 | // Synchronize access to the list of requests\r | |
39 | //\r | |
1436aea4 | 40 | #define TPL_I2C_SYNC TPL_NOTIFY\r |
43e543bc EL |
41 | \r |
42 | //\r | |
43 | // I2C bus context\r | |
44 | //\r | |
45 | typedef struct {\r | |
1436aea4 MK |
46 | EFI_I2C_ENUMERATE_PROTOCOL *I2cEnumerate;\r |
47 | EFI_I2C_HOST_PROTOCOL *I2cHost;\r | |
48 | EFI_HANDLE Controller;\r | |
49 | EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath;\r | |
50 | EFI_HANDLE DriverBindingHandle;\r | |
43e543bc EL |
51 | } I2C_BUS_CONTEXT;\r |
52 | \r | |
53 | //\r | |
54 | // I2C device context\r | |
55 | //\r | |
56 | typedef struct {\r | |
57 | //\r | |
58 | // Structure identification\r | |
59 | //\r | |
1436aea4 | 60 | UINT32 Signature;\r |
43e543bc EL |
61 | \r |
62 | //\r | |
63 | // I2c device handle\r | |
64 | //\r | |
1436aea4 | 65 | EFI_HANDLE Handle;\r |
43e543bc EL |
66 | \r |
67 | //\r | |
68 | // Upper level API to support the I2C device I/O\r | |
69 | //\r | |
1436aea4 | 70 | EFI_I2C_IO_PROTOCOL I2cIo;\r |
43e543bc EL |
71 | \r |
72 | //\r | |
73 | // Device path for this device\r | |
74 | //\r | |
1436aea4 | 75 | EFI_DEVICE_PATH_PROTOCOL *DevicePath;\r |
43e543bc EL |
76 | \r |
77 | //\r | |
78 | // Platform specific data for this device\r | |
79 | //\r | |
1436aea4 | 80 | CONST EFI_I2C_DEVICE *I2cDevice;\r |
43e543bc EL |
81 | \r |
82 | //\r | |
83 | // Context for the common I/O support including the\r | |
84 | // lower level API to the host controller.\r | |
85 | //\r | |
1436aea4 | 86 | I2C_BUS_CONTEXT *I2cBusContext;\r |
43e543bc EL |
87 | } I2C_DEVICE_CONTEXT;\r |
88 | \r | |
1436aea4 | 89 | #define I2C_DEVICE_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_DEVICE_CONTEXT, I2cIo, I2C_DEVICE_SIGNATURE)\r |
43e543bc EL |
90 | \r |
91 | //\r | |
92 | // I2C Request\r | |
93 | //\r | |
94 | typedef struct {\r | |
95 | //\r | |
96 | // Signature\r | |
97 | //\r | |
1436aea4 | 98 | UINT32 Signature;\r |
d1102dba | 99 | \r |
43e543bc EL |
100 | //\r |
101 | // Next request in the pending request list\r | |
102 | //\r | |
1436aea4 | 103 | LIST_ENTRY Link;\r |
43e543bc EL |
104 | \r |
105 | //\r | |
106 | // I2C bus configuration for the operation\r | |
107 | //\r | |
1436aea4 | 108 | UINTN I2cBusConfiguration;\r |
43e543bc EL |
109 | \r |
110 | //\r | |
111 | // I2C slave address for the operation\r | |
112 | //\r | |
1436aea4 | 113 | UINTN SlaveAddress;\r |
43e543bc EL |
114 | \r |
115 | //\r | |
116 | // Event to set for asynchronous operations, NULL for\r | |
117 | // synchronous operations\r | |
118 | //\r | |
1436aea4 | 119 | EFI_EVENT Event;\r |
43e543bc EL |
120 | \r |
121 | //\r | |
122 | // I2C operation description\r | |
123 | //\r | |
1436aea4 | 124 | EFI_I2C_REQUEST_PACKET *RequestPacket;\r |
43e543bc EL |
125 | \r |
126 | //\r | |
127 | // Optional buffer to receive the I2C operation completion status\r | |
128 | //\r | |
1436aea4 | 129 | EFI_STATUS *Status;\r |
43e543bc EL |
130 | } I2C_REQUEST;\r |
131 | \r | |
1436aea4 | 132 | #define I2C_REQUEST_FROM_ENTRY(a) CR (a, I2C_REQUEST, Link, I2C_REQUEST_SIGNATURE);\r |
43e543bc EL |
133 | \r |
134 | //\r | |
135 | // I2C host context\r | |
136 | //\r | |
137 | typedef struct {\r | |
138 | //\r | |
139 | // Structure identification\r | |
140 | //\r | |
1436aea4 | 141 | UINTN Signature;\r |
43e543bc EL |
142 | \r |
143 | //\r | |
144 | // Current I2C bus configuration\r | |
145 | //\r | |
1436aea4 | 146 | UINTN I2cBusConfiguration;\r |
43e543bc EL |
147 | \r |
148 | //\r | |
149 | // I2C bus configuration management event\r | |
150 | //\r | |
1436aea4 | 151 | EFI_EVENT I2cBusConfigurationEvent;\r |
43e543bc EL |
152 | \r |
153 | //\r | |
154 | // I2C operation completion event\r | |
155 | //\r | |
1436aea4 | 156 | EFI_EVENT I2cEvent;\r |
43e543bc EL |
157 | \r |
158 | //\r | |
159 | // I2C operation and I2C bus configuration management status\r | |
160 | //\r | |
1436aea4 | 161 | EFI_STATUS Status;\r |
43e543bc EL |
162 | \r |
163 | //\r | |
164 | // I2C bus configuration management operation pending\r | |
165 | //\r | |
1436aea4 | 166 | BOOLEAN I2cBusConfigurationManagementPending;\r |
43e543bc EL |
167 | \r |
168 | //\r | |
169 | // I2C request list maintained by I2C Host\r | |
170 | //\r | |
1436aea4 | 171 | LIST_ENTRY RequestList;\r |
43e543bc EL |
172 | \r |
173 | //\r | |
174 | // Upper level API\r | |
175 | //\r | |
1436aea4 | 176 | EFI_I2C_HOST_PROTOCOL I2cHost;\r |
43e543bc EL |
177 | \r |
178 | //\r | |
179 | // I2C bus configuration management protocol\r | |
180 | //\r | |
1436aea4 | 181 | EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL *I2cBusConfigurationManagement;\r |
43e543bc EL |
182 | \r |
183 | //\r | |
184 | // Lower level API for I2C master (controller)\r | |
185 | //\r | |
1436aea4 | 186 | EFI_I2C_MASTER_PROTOCOL *I2cMaster;\r |
43e543bc EL |
187 | } I2C_HOST_CONTEXT;\r |
188 | \r | |
1436aea4 | 189 | #define I2C_HOST_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_HOST_CONTEXT, I2cHost, I2C_HOST_SIGNATURE)\r |
43e543bc EL |
190 | \r |
191 | //\r | |
192 | // Global Variables\r | |
193 | //\r | |
1436aea4 MK |
194 | extern EFI_COMPONENT_NAME_PROTOCOL gI2cBusComponentName;\r |
195 | extern EFI_COMPONENT_NAME2_PROTOCOL gI2cBusComponentName2;\r | |
196 | extern EFI_DRIVER_BINDING_PROTOCOL gI2cBusDriverBinding;\r | |
43e543bc | 197 | \r |
1436aea4 MK |
198 | extern EFI_COMPONENT_NAME_PROTOCOL gI2cHostComponentName;\r |
199 | extern EFI_COMPONENT_NAME2_PROTOCOL gI2cHostComponentName2;\r | |
200 | extern EFI_DRIVER_BINDING_PROTOCOL gI2cHostDriverBinding;\r | |
43e543bc EL |
201 | \r |
202 | /**\r | |
203 | Start the I2C driver\r | |
204 | \r | |
205 | This routine allocates the necessary resources for the driver.\r | |
206 | \r | |
207 | This routine is called by I2cBusDriverStart to complete the driver\r | |
208 | initialization.\r | |
209 | \r | |
210 | @param[in] I2cBus Address of an I2C_BUS_CONTEXT structure\r | |
211 | @param[in] Controller Handle to the controller\r | |
212 | @param[in] RemainingDevicePath A pointer to the remaining portion of a device path.\r | |
213 | \r | |
214 | @retval EFI_SUCCESS Driver API properly initialized\r | |
d1102dba | 215 | \r |
43e543bc EL |
216 | **/\r |
217 | EFI_STATUS\r | |
218 | RegisterI2cDevice (\r | |
219 | IN I2C_BUS_CONTEXT *I2cBus,\r | |
1436aea4 | 220 | IN EFI_HANDLE Controller,\r |
43e543bc EL |
221 | IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r |
222 | );\r | |
223 | \r | |
224 | /**\r | |
225 | Unregister an I2C device.\r | |
226 | \r | |
227 | This function removes the protocols installed on the controller handle and\r | |
228 | frees the resources allocated for the I2C device.\r | |
229 | \r | |
230 | @param This The pointer to EFI_DRIVER_BINDING_PROTOCOL instance.\r | |
231 | @param Controller The controller handle of the I2C device.\r | |
232 | @param Handle The child handle.\r | |
233 | \r | |
234 | @retval EFI_SUCCESS The I2C device is successfully unregistered.\r | |
235 | @return Others Some error occurs when unregistering the I2C device.\r | |
236 | \r | |
237 | **/\r | |
238 | EFI_STATUS\r | |
239 | UnRegisterI2cDevice (\r | |
1436aea4 MK |
240 | IN EFI_DRIVER_BINDING_PROTOCOL *This,\r |
241 | IN EFI_HANDLE Controller,\r | |
242 | IN EFI_HANDLE Handle\r | |
43e543bc EL |
243 | );\r |
244 | \r | |
245 | /**\r | |
246 | Create a path for the I2C device\r | |
247 | \r | |
248 | Append the I2C slave path to the I2C master controller path.\r | |
249 | \r | |
250 | @param[in] I2cDeviceContext Address of an I2C_DEVICE_CONTEXT structure.\r | |
251 | @param[in] BuildControllerNode Flag to build controller node in device path.\r | |
252 | \r | |
253 | @retval EFI_SUCCESS The I2C device path is built successfully.\r | |
254 | @return Others It is failed to built device path.\r | |
255 | \r | |
256 | **/\r | |
257 | EFI_STATUS\r | |
258 | I2cBusDevicePathAppend (\r | |
1436aea4 MK |
259 | IN I2C_DEVICE_CONTEXT *I2cDeviceContext,\r |
260 | IN BOOLEAN BuildControllerNode\r | |
43e543bc EL |
261 | );\r |
262 | \r | |
263 | /**\r | |
264 | Queue an I2C transaction for execution on the I2C device.\r | |
265 | \r | |
266 | This routine must be called at or below TPL_NOTIFY. For synchronous\r | |
267 | requests this routine must be called at or below TPL_CALLBACK.\r | |
268 | \r | |
269 | This routine queues an I2C transaction to the I2C controller for\r | |
270 | execution on the I2C bus.\r | |
271 | \r | |
272 | When Event is NULL, QueueRequest() operates synchronously and returns\r | |
273 | the I2C completion status as its return value.\r | |
274 | \r | |
275 | When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS\r | |
276 | indicating that the asynchronous I2C transaction was queued. The values\r | |
277 | above are returned in the buffer pointed to by I2cStatus upon the\r | |
278 | completion of the I2C transaction when I2cStatus is not NULL.\r | |
279 | \r | |
280 | The upper layer driver writer provides the following to the platform\r | |
281 | vendor:\r | |
d1102dba | 282 | \r |
43e543bc EL |
283 | 1. Vendor specific GUID for the I2C part\r |
284 | 2. Guidance on proper construction of the slave address array when the\r | |
285 | I2C device uses more than one slave address. The I2C bus protocol\r | |
286 | uses the SlaveAddressIndex to perform relative to physical address\r | |
287 | translation to access the blocks of hardware within the I2C device.\r | |
288 | \r | |
289 | @param[in] This Pointer to an EFI_I2C_IO_PROTOCOL structure.\r | |
290 | @param[in] SlaveAddressIndex Index value into an array of slave addresses\r | |
291 | for the I2C device. The values in the array\r | |
292 | are specified by the board designer, with the\r | |
293 | third party I2C device driver writer providing\r | |
294 | the slave address order.\r | |
295 | \r | |
296 | For devices that have a single slave address,\r | |
297 | this value must be zero. If the I2C device\r | |
298 | uses more than one slave address then the\r | |
299 | third party (upper level) I2C driver writer\r | |
300 | needs to specify the order of entries in the\r | |
301 | slave address array.\r | |
302 | \r | |
303 | \ref ThirdPartyI2cDrivers "Third Party I2C\r | |
304 | Drivers" section in I2cMaster.h.\r | |
305 | @param[in] Event Event to signal for asynchronous transactions,\r | |
306 | NULL for synchronous transactions\r | |
307 | @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure\r | |
308 | describing the I2C transaction\r | |
309 | @param[out] I2cStatus Optional buffer to receive the I2C transaction\r | |
310 | completion status\r | |
311 | \r | |
312 | @retval EFI_SUCCESS The asynchronous transaction was successfully\r | |
313 | queued when Event is not NULL.\r | |
314 | @retval EFI_SUCCESS The transaction completed successfully when\r | |
315 | Event is NULL.\r | |
316 | @retval EFI_ABORTED The request did not complete because the driver\r | |
317 | binding Stop() routine was called.\r | |
318 | @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too\r | |
319 | large.\r | |
320 | @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the\r | |
321 | transaction.\r | |
322 | @retval EFI_INVALID_PARAMETER RequestPacket is NULL\r | |
323 | @retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter\r | |
324 | @retval EFI_NO_MAPPING The EFI_I2C_HOST_PROTOCOL could not set the\r | |
325 | bus configuration required to access this I2C\r | |
326 | device.\r | |
327 | @retval EFI_NO_RESPONSE The I2C device is not responding to the slave\r | |
328 | address selected by SlaveAddressIndex.\r | |
329 | EFI_DEVICE_ERROR will be returned if the\r | |
330 | controller cannot distinguish when the NACK\r | |
331 | occurred.\r | |
332 | @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction\r | |
333 | @retval EFI_UNSUPPORTED The controller does not support the requested\r | |
334 | transaction.\r | |
335 | \r | |
336 | **/\r | |
337 | EFI_STATUS\r | |
338 | EFIAPI\r | |
339 | I2cBusQueueRequest (\r | |
340 | IN CONST EFI_I2C_IO_PROTOCOL *This,\r | |
341 | IN UINTN SlaveAddressIndex,\r | |
342 | IN EFI_EVENT Event OPTIONAL,\r | |
343 | IN EFI_I2C_REQUEST_PACKET *RequestPacket,\r | |
344 | OUT EFI_STATUS *I2cStatus OPTIONAL\r | |
345 | );\r | |
346 | \r | |
347 | /**\r | |
348 | Tests to see if this driver supports a given controller. If a child device is provided,\r | |
349 | it further tests to see if this driver supports creating a handle for the specified child device.\r | |
350 | \r | |
351 | This function checks to see if the driver specified by This supports the device specified by\r | |
352 | ControllerHandle. Drivers will typically use the device path attached to\r | |
353 | ControllerHandle and/or the services from the bus I/O abstraction attached to\r | |
354 | ControllerHandle to determine if the driver supports ControllerHandle. This function\r | |
355 | may be called many times during platform initialization. In order to reduce boot times, the tests\r | |
356 | performed by this function must be very small, and take as little time as possible to execute. This\r | |
357 | function must not change the state of any hardware devices, and this function must be aware that the\r | |
358 | device specified by ControllerHandle may already be managed by the same driver or a\r | |
359 | different driver. This function must match its calls to AllocatePages() with FreePages(),\r | |
360 | AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().\r | |
361 | Since ControllerHandle may have been previously started by the same driver, if a protocol is\r | |
362 | already in the opened state, then it must not be closed with CloseProtocol(). This is required\r | |
363 | to guarantee the state of ControllerHandle is not modified by this function.\r | |
364 | \r | |
365 | @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r | |
366 | @param[in] ControllerHandle The handle of the controller to test. This handle\r | |
367 | must support a protocol interface that supplies\r | |
368 | an I/O abstraction to the driver.\r | |
369 | @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This\r | |
370 | parameter is ignored by device drivers, and is optional for bus\r | |
371 | drivers. For bus drivers, if this parameter is not NULL, then\r | |
372 | the bus driver must determine if the bus controller specified\r | |
373 | by ControllerHandle and the child controller specified\r | |
374 | by RemainingDevicePath are both supported by this\r | |
375 | bus driver.\r | |
376 | \r | |
377 | @retval EFI_SUCCESS The device specified by ControllerHandle and\r | |
378 | RemainingDevicePath is supported by the driver specified by This.\r | |
379 | @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and\r | |
380 | RemainingDevicePath is already being managed by the driver\r | |
381 | specified by This.\r | |
382 | @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and\r | |
383 | RemainingDevicePath is already being managed by a different\r | |
384 | driver or an application that requires exclusive access.\r | |
385 | Currently not implemented.\r | |
386 | @retval EFI_UNSUPPORTED The device specified by ControllerHandle and\r | |
387 | RemainingDevicePath is not supported by the driver specified by This.\r | |
388 | **/\r | |
389 | EFI_STATUS\r | |
390 | EFIAPI\r | |
391 | I2cBusDriverSupported (\r | |
392 | IN EFI_DRIVER_BINDING_PROTOCOL *This,\r | |
393 | IN EFI_HANDLE Controller,\r | |
394 | IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r | |
395 | );\r | |
396 | \r | |
397 | /**\r | |
398 | Starts a device controller or a bus controller.\r | |
399 | \r | |
400 | The Start() function is designed to be invoked from the EFI boot service ConnectController().\r | |
401 | As a result, much of the error checking on the parameters to Start() has been moved into this\r | |
402 | common boot service. It is legal to call Start() from other locations,\r | |
403 | but the following calling restrictions must be followed or the system behavior will not be deterministic.\r | |
404 | 1. ControllerHandle must be a valid EFI_HANDLE.\r | |
405 | 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned\r | |
406 | EFI_DEVICE_PATH_PROTOCOL.\r | |
407 | 3. Prior to calling Start(), the Supported() function for the driver specified by This must\r | |
408 | have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.\r | |
409 | \r | |
410 | @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r | |
411 | @param[in] ControllerHandle The handle of the controller to start. This handle\r | |
412 | must support a protocol interface that supplies\r | |
413 | an I/O abstraction to the driver.\r | |
414 | @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This\r | |
415 | parameter is ignored by device drivers, and is optional for bus\r | |
416 | drivers. For a bus driver, if this parameter is NULL, then handles\r | |
417 | for all the children of Controller are created by this driver.\r | |
418 | If this parameter is not NULL and the first Device Path Node is\r | |
419 | not the End of Device Path Node, then only the handle for the\r | |
420 | child device specified by the first Device Path Node of\r | |
421 | RemainingDevicePath is created by this driver.\r | |
422 | If the first Device Path Node of RemainingDevicePath is\r | |
423 | the End of Device Path Node, no child handle is created by this\r | |
424 | driver.\r | |
425 | \r | |
426 | @retval EFI_SUCCESS The device was started.\r | |
427 | @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.\r | |
428 | @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.\r | |
29f7ad8b | 429 | @retval Others The driver failed to start the device.\r |
43e543bc EL |
430 | \r |
431 | **/\r | |
432 | EFI_STATUS\r | |
433 | EFIAPI\r | |
434 | I2cBusDriverStart (\r | |
435 | IN EFI_DRIVER_BINDING_PROTOCOL *This,\r | |
436 | IN EFI_HANDLE Controller,\r | |
437 | IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r | |
438 | );\r | |
439 | \r | |
440 | /**\r | |
441 | Stops a device controller or a bus controller.\r | |
442 | \r | |
443 | The Stop() function is designed to be invoked from the EFI boot service DisconnectController().\r | |
444 | As a result, much of the error checking on the parameters to Stop() has been moved\r | |
445 | into this common boot service. It is legal to call Stop() from other locations,\r | |
446 | but the following calling restrictions must be followed or the system behavior will not be deterministic.\r | |
447 | 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this\r | |
448 | same driver's Start() function.\r | |
449 | 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid\r | |
450 | EFI_HANDLE. In addition, all of these handles must have been created in this driver's\r | |
451 | Start() function, and the Start() function must have called OpenProtocol() on\r | |
452 | ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.\r | |
453 | \r | |
454 | @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r | |
455 | @param[in] ControllerHandle A handle to the device being stopped. The handle must\r | |
456 | support a bus specific I/O protocol for the driver\r | |
457 | to use to stop the device.\r | |
458 | @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.\r | |
459 | @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL\r | |
460 | if NumberOfChildren is 0.\r | |
461 | \r | |
462 | @retval EFI_SUCCESS The device was stopped.\r | |
463 | @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.\r | |
464 | \r | |
465 | **/\r | |
466 | EFI_STATUS\r | |
467 | EFIAPI\r | |
468 | I2cBusDriverStop (\r | |
469 | IN EFI_DRIVER_BINDING_PROTOCOL *This,\r | |
470 | IN EFI_HANDLE Controller,\r | |
471 | IN UINTN NumberOfChildren,\r | |
472 | IN EFI_HANDLE *ChildHandleBuffer\r | |
473 | );\r | |
474 | \r | |
475 | /**\r | |
476 | Retrieves a Unicode string that is the user readable name of the driver.\r | |
477 | \r | |
478 | This function retrieves the user readable name of a driver in the form of a\r | |
479 | Unicode string. If the driver specified by This has a user readable name in\r | |
480 | the language specified by Language, then a pointer to the driver name is\r | |
481 | returned in DriverName, and EFI_SUCCESS is returned. If the driver specified\r | |
482 | by This does not support the language specified by Language,\r | |
483 | then EFI_UNSUPPORTED is returned.\r | |
484 | \r | |
485 | @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or\r | |
486 | EFI_COMPONENT_NAME_PROTOCOL instance.\r | |
487 | \r | |
488 | @param Language[in] A pointer to a Null-terminated ASCII string\r | |
489 | array indicating the language. This is the\r | |
490 | language of the driver name that the caller is\r | |
491 | requesting, and it must match one of the\r | |
492 | languages specified in SupportedLanguages. The\r | |
493 | number of languages supported by a driver is up\r | |
494 | to the driver writer. Language is specified\r | |
495 | in RFC 4646 or ISO 639-2 language code format.\r | |
496 | \r | |
497 | @param DriverName[out] A pointer to the Unicode string to return.\r | |
498 | This Unicode string is the name of the\r | |
499 | driver specified by This in the language\r | |
500 | specified by Language.\r | |
501 | \r | |
502 | @retval EFI_SUCCESS The Unicode string for the Driver specified by\r | |
503 | This and the language specified by Language was\r | |
504 | returned in DriverName.\r | |
505 | \r | |
506 | @retval EFI_INVALID_PARAMETER Language is NULL.\r | |
507 | \r | |
508 | @retval EFI_INVALID_PARAMETER DriverName is NULL.\r | |
509 | \r | |
510 | @retval EFI_UNSUPPORTED The driver specified by This does not support\r | |
511 | the language specified by Language.\r | |
512 | \r | |
513 | **/\r | |
514 | EFI_STATUS\r | |
515 | EFIAPI\r | |
516 | I2cBusComponentNameGetDriverName (\r | |
1436aea4 MK |
517 | IN EFI_COMPONENT_NAME2_PROTOCOL *This,\r |
518 | IN CHAR8 *Language,\r | |
519 | OUT CHAR16 **DriverName\r | |
43e543bc | 520 | );\r |
d1102dba | 521 | \r |
43e543bc EL |
522 | /**\r |
523 | Retrieves a Unicode string that is the user readable name of the controller\r | |
524 | that is being managed by a driver.\r | |
525 | \r | |
526 | This function retrieves the user readable name of the controller specified by\r | |
527 | ControllerHandle and ChildHandle in the form of a Unicode string. If the\r | |
528 | driver specified by This has a user readable name in the language specified by\r | |
529 | Language, then a pointer to the controller name is returned in ControllerName,\r | |
530 | and EFI_SUCCESS is returned. If the driver specified by This is not currently\r | |
531 | managing the controller specified by ControllerHandle and ChildHandle,\r | |
532 | then EFI_UNSUPPORTED is returned. If the driver specified by This does not\r | |
533 | support the language specified by Language, then EFI_UNSUPPORTED is returned.\r | |
534 | \r | |
535 | @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or\r | |
536 | EFI_COMPONENT_NAME_PROTOCOL instance.\r | |
537 | \r | |
538 | @param ControllerHandle[in] The handle of a controller that the driver\r | |
539 | specified by This is managing. This handle\r | |
540 | specifies the controller whose name is to be\r | |
541 | returned.\r | |
542 | \r | |
543 | @param ChildHandle[in] The handle of the child controller to retrieve\r | |
544 | the name of. This is an optional parameter that\r | |
545 | may be NULL. It will be NULL for device\r | |
546 | drivers. It will also be NULL for a bus drivers\r | |
547 | that wish to retrieve the name of the bus\r | |
548 | controller. It will not be NULL for a bus\r | |
549 | driver that wishes to retrieve the name of a\r | |
550 | child controller.\r | |
551 | \r | |
552 | @param Language[in] A pointer to a Null-terminated ASCII string\r | |
553 | array indicating the language. This is the\r | |
554 | language of the driver name that the caller is\r | |
555 | requesting, and it must match one of the\r | |
556 | languages specified in SupportedLanguages. The\r | |
557 | number of languages supported by a driver is up\r | |
558 | to the driver writer. Language is specified in\r | |
559 | RFC 4646 or ISO 639-2 language code format.\r | |
560 | \r | |
561 | @param ControllerName[out] A pointer to the Unicode string to return.\r | |
562 | This Unicode string is the name of the\r | |
563 | controller specified by ControllerHandle and\r | |
564 | ChildHandle in the language specified by\r | |
565 | Language from the point of view of the driver\r | |
566 | specified by This.\r | |
567 | \r | |
568 | @retval EFI_SUCCESS The Unicode string for the user readable name in\r | |
569 | the language specified by Language for the\r | |
570 | driver specified by This was returned in\r | |
571 | DriverName.\r | |
572 | \r | |
573 | @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.\r | |
574 | \r | |
575 | @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid\r | |
576 | EFI_HANDLE.\r | |
577 | \r | |
578 | @retval EFI_INVALID_PARAMETER Language is NULL.\r | |
579 | \r | |
580 | @retval EFI_INVALID_PARAMETER ControllerName is NULL.\r | |
581 | \r | |
582 | @retval EFI_UNSUPPORTED The driver specified by This is not currently\r | |
583 | managing the controller specified by\r | |
584 | ControllerHandle and ChildHandle.\r | |
585 | \r | |
586 | @retval EFI_UNSUPPORTED The driver specified by This does not support\r | |
587 | the language specified by Language.\r | |
588 | \r | |
589 | **/\r | |
590 | EFI_STATUS\r | |
591 | EFIAPI\r | |
592 | I2cBusComponentNameGetControllerName (\r | |
1436aea4 MK |
593 | IN EFI_COMPONENT_NAME2_PROTOCOL *This,\r |
594 | IN EFI_HANDLE ControllerHandle,\r | |
595 | IN EFI_HANDLE ChildHandle OPTIONAL,\r | |
596 | IN CHAR8 *Language,\r | |
597 | OUT CHAR16 **ControllerName\r | |
43e543bc EL |
598 | );\r |
599 | \r | |
600 | /**\r | |
601 | The user entry point for the I2C bus module. The user code starts with\r | |
602 | this function.\r | |
603 | \r | |
604 | @param[in] ImageHandle The firmware allocated handle for the EFI image.\r | |
605 | @param[in] SystemTable A pointer to the EFI System Table.\r | |
606 | \r | |
607 | @retval EFI_SUCCESS The entry point is executed successfully.\r | |
608 | @retval other Some error occurs when executing this entry point.\r | |
609 | \r | |
610 | **/\r | |
611 | EFI_STATUS\r | |
612 | EFIAPI\r | |
1436aea4 MK |
613 | InitializeI2cBus (\r |
614 | IN EFI_HANDLE ImageHandle,\r | |
615 | IN EFI_SYSTEM_TABLE *SystemTable\r | |
43e543bc EL |
616 | );\r |
617 | \r | |
618 | /**\r | |
619 | This is the unload handle for I2C bus module.\r | |
620 | \r | |
621 | Disconnect the driver specified by ImageHandle from all the devices in the handle database.\r | |
622 | Uninstall all the protocols installed in the driver entry point.\r | |
623 | \r | |
624 | @param[in] ImageHandle The drivers' driver image.\r | |
625 | \r | |
626 | @retval EFI_SUCCESS The image is unloaded.\r | |
627 | @retval Others Failed to unload the image.\r | |
628 | \r | |
629 | **/\r | |
630 | EFI_STATUS\r | |
631 | EFIAPI\r | |
632 | I2cBusUnload (\r | |
1436aea4 | 633 | IN EFI_HANDLE ImageHandle\r |
43e543bc EL |
634 | );\r |
635 | \r | |
636 | /**\r | |
637 | Release all the resources allocated for the I2C device.\r | |
638 | \r | |
639 | This function releases all the resources allocated for the I2C device.\r | |
640 | \r | |
641 | @param I2cDeviceContext The I2C child device involved for the operation.\r | |
642 | \r | |
643 | **/\r | |
644 | VOID\r | |
645 | ReleaseI2cDeviceContext (\r | |
1436aea4 | 646 | IN I2C_DEVICE_CONTEXT *I2cDeviceContext\r |
43e543bc EL |
647 | );\r |
648 | \r | |
649 | /**\r | |
650 | Complete the current request\r | |
651 | \r | |
652 | @param[in] I2cHost Address of an I2C_HOST_CONTEXT structure.\r | |
653 | @param[in] Status Status of the I<sub>2</sub>C operation.\r | |
654 | \r | |
655 | @return This routine returns the input status value.\r | |
656 | \r | |
657 | **/\r | |
658 | EFI_STATUS\r | |
659 | I2cHostRequestComplete (\r | |
1436aea4 MK |
660 | I2C_HOST_CONTEXT *I2cHost,\r |
661 | EFI_STATUS Status\r | |
43e543bc EL |
662 | );\r |
663 | \r | |
664 | /**\r | |
665 | Enable access to the I2C bus configuration\r | |
666 | \r | |
667 | @param[in] I2cHostContext Address of an I2C_HOST_CONTEXT structure\r | |
668 | \r | |
669 | @retval EFI_SUCCESS The operation completed successfully.\r | |
670 | @retval EFI_ABORTED The request did not complete because the driver\r | |
671 | was shutdown.\r | |
672 | @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.\r | |
673 | @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.\r | |
674 | This could indicate the slave device is not present.\r | |
675 | @retval EFI_INVALID_PARAMETER RequestPacket is NULL\r | |
676 | @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value\r | |
677 | @retval EFI_NO_RESPONSE The I2C device is not responding to the\r | |
678 | slave address. EFI_DEVICE_ERROR may also be\r | |
679 | returned if the controller can not distinguish\r | |
680 | when the NACK occurred.\r | |
681 | @retval EFI_NOT_FOUND I2C slave address exceeds maximum address\r | |
682 | @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for\r | |
683 | the event and then read status.\r | |
684 | @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation\r | |
685 | @retval EFI_TIMEOUT The transaction did not complete within an internally\r | |
686 | specified timeout period.\r | |
687 | \r | |
688 | **/\r | |
689 | EFI_STATUS\r | |
690 | I2cHostRequestEnable (\r | |
1436aea4 | 691 | I2C_HOST_CONTEXT *I2cHost\r |
43e543bc EL |
692 | );\r |
693 | \r | |
694 | /**\r | |
695 | Tests to see if this driver supports a given controller. If a child device is provided,\r | |
696 | it further tests to see if this driver supports creating a handle for the specified child device.\r | |
697 | \r | |
698 | This function checks to see if the driver specified by This supports the device specified by\r | |
699 | ControllerHandle. Drivers will typically use the device path attached to\r | |
700 | ControllerHandle and/or the services from the bus I/O abstraction attached to\r | |
701 | ControllerHandle to determine if the driver supports ControllerHandle. This function\r | |
702 | may be called many times during platform initialization. In order to reduce boot times, the tests\r | |
703 | performed by this function must be very small, and take as little time as possible to execute. This\r | |
704 | function must not change the state of any hardware devices, and this function must be aware that the\r | |
705 | device specified by ControllerHandle may already be managed by the same driver or a\r | |
706 | different driver. This function must match its calls to AllocatePages() with FreePages(),\r | |
707 | AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().\r | |
708 | Since ControllerHandle may have been previously started by the same driver, if a protocol is\r | |
709 | already in the opened state, then it must not be closed with CloseProtocol(). This is required\r | |
710 | to guarantee the state of ControllerHandle is not modified by this function.\r | |
711 | \r | |
712 | @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r | |
713 | @param[in] ControllerHandle The handle of the controller to test. This handle\r | |
714 | must support a protocol interface that supplies\r | |
715 | an I/O abstraction to the driver.\r | |
716 | @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This\r | |
717 | parameter is ignored by device drivers, and is optional for bus\r | |
718 | drivers. For bus drivers, if this parameter is not NULL, then\r | |
719 | the bus driver must determine if the bus controller specified\r | |
720 | by ControllerHandle and the child controller specified\r | |
721 | by RemainingDevicePath are both supported by this\r | |
722 | bus driver.\r | |
723 | \r | |
724 | @retval EFI_SUCCESS The device specified by ControllerHandle and\r | |
725 | RemainingDevicePath is supported by the driver specified by This.\r | |
726 | @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and\r | |
727 | RemainingDevicePath is already being managed by the driver\r | |
728 | specified by This.\r | |
729 | @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and\r | |
730 | RemainingDevicePath is already being managed by a different\r | |
731 | driver or an application that requires exclusive access.\r | |
732 | Currently not implemented.\r | |
733 | @retval EFI_UNSUPPORTED The device specified by ControllerHandle and\r | |
734 | RemainingDevicePath is not supported by the driver specified by This.\r | |
735 | **/\r | |
736 | EFI_STATUS\r | |
737 | EFIAPI\r | |
738 | I2cHostDriverSupported (\r | |
739 | IN EFI_DRIVER_BINDING_PROTOCOL *This,\r | |
740 | IN EFI_HANDLE Controller,\r | |
741 | IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r | |
742 | );\r | |
743 | \r | |
744 | /**\r | |
745 | Starts a device controller or a bus controller.\r | |
746 | \r | |
747 | The Start() function is designed to be invoked from the EFI boot service ConnectController().\r | |
748 | As a result, much of the error checking on the parameters to Start() has been moved into this\r | |
749 | common boot service. It is legal to call Start() from other locations,\r | |
750 | but the following calling restrictions must be followed, or the system behavior will not be deterministic.\r | |
751 | 1. ControllerHandle must be a valid EFI_HANDLE.\r | |
752 | 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned\r | |
753 | EFI_DEVICE_PATH_PROTOCOL.\r | |
754 | 3. Prior to calling Start(), the Supported() function for the driver specified by This must\r | |
755 | have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.\r | |
756 | \r | |
757 | @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r | |
758 | @param[in] ControllerHandle The handle of the controller to start. This handle\r | |
759 | must support a protocol interface that supplies\r | |
760 | an I/O abstraction to the driver.\r | |
761 | @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This\r | |
762 | parameter is ignored by device drivers, and is optional for bus\r | |
763 | drivers. For a bus driver, if this parameter is NULL, then handles\r | |
764 | for all the children of Controller are created by this driver.\r | |
765 | If this parameter is not NULL and the first Device Path Node is\r | |
766 | not the End of Device Path Node, then only the handle for the\r | |
767 | child device specified by the first Device Path Node of\r | |
768 | RemainingDevicePath is created by this driver.\r | |
769 | If the first Device Path Node of RemainingDevicePath is\r | |
770 | the End of Device Path Node, no child handle is created by this\r | |
771 | driver.\r | |
772 | \r | |
773 | @retval EFI_SUCCESS The device was started.\r | |
774 | @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.\r | |
775 | @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.\r | |
29f7ad8b | 776 | @retval Others The driver failed to start the device.\r |
43e543bc EL |
777 | \r |
778 | **/\r | |
779 | EFI_STATUS\r | |
780 | EFIAPI\r | |
781 | I2cHostDriverStart (\r | |
1436aea4 MK |
782 | IN EFI_DRIVER_BINDING_PROTOCOL *This,\r |
783 | IN EFI_HANDLE Controller,\r | |
784 | IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r | |
43e543bc | 785 | );\r |
d1102dba | 786 | \r |
43e543bc EL |
787 | /**\r |
788 | Stops a device controller or a bus controller.\r | |
789 | \r | |
790 | The Stop() function is designed to be invoked from the EFI boot service DisconnectController().\r | |
791 | As a result, much of the error checking on the parameters to Stop() has been moved\r | |
792 | into this common boot service. It is legal to call Stop() from other locations,\r | |
793 | but the following calling restrictions must be followed, or the system behavior will not be deterministic.\r | |
794 | 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this\r | |
795 | same driver's Start() function.\r | |
796 | 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid\r | |
797 | EFI_HANDLE. In addition, all of these handles must have been created in this driver's\r | |
798 | Start() function, and the Start() function must have called OpenProtocol() on\r | |
799 | ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.\r | |
800 | \r | |
801 | @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r | |
802 | @param[in] ControllerHandle A handle to the device being stopped. The handle must\r | |
803 | support a bus specific I/O protocol for the driver\r | |
804 | to use to stop the device.\r | |
805 | @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.\r | |
806 | @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL\r | |
807 | if NumberOfChildren is 0.\r | |
808 | \r | |
809 | @retval EFI_SUCCESS The device was stopped.\r | |
810 | @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.\r | |
811 | \r | |
812 | **/\r | |
813 | EFI_STATUS\r | |
814 | EFIAPI\r | |
815 | I2cHostDriverStop (\r | |
1436aea4 MK |
816 | IN EFI_DRIVER_BINDING_PROTOCOL *This,\r |
817 | IN EFI_HANDLE Controller,\r | |
818 | IN UINTN NumberOfChildren,\r | |
819 | IN EFI_HANDLE *ChildHandleBuffer\r | |
43e543bc EL |
820 | );\r |
821 | \r | |
822 | /**\r | |
823 | Retrieves a Unicode string that is the user readable name of the driver.\r | |
824 | \r | |
825 | This function retrieves the user readable name of a driver in the form of a\r | |
826 | Unicode string. If the driver specified by This has a user readable name in\r | |
827 | the language specified by Language, then a pointer to the driver name is\r | |
828 | returned in DriverName, and EFI_SUCCESS is returned. If the driver specified\r | |
829 | by This does not support the language specified by Language,\r | |
830 | then EFI_UNSUPPORTED is returned.\r | |
831 | \r | |
832 | @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or\r | |
833 | EFI_COMPONENT_NAME_PROTOCOL instance.\r | |
834 | \r | |
835 | @param Language[in] A pointer to a Null-terminated ASCII string\r | |
836 | array indicating the language. This is the\r | |
837 | language of the driver name that the caller is\r | |
838 | requesting, and it must match one of the\r | |
839 | languages specified in SupportedLanguages. The\r | |
840 | number of languages supported by a driver is up\r | |
841 | to the driver writer. Language is specified\r | |
842 | in RFC 4646 or ISO 639-2 language code format.\r | |
843 | \r | |
844 | @param DriverName[out] A pointer to the Unicode string to return.\r | |
845 | This Unicode string is the name of the\r | |
846 | driver specified by This in the language\r | |
847 | specified by Language.\r | |
848 | \r | |
849 | @retval EFI_SUCCESS The Unicode string for the Driver specified by\r | |
850 | This and the language specified by Language was\r | |
851 | returned in DriverName.\r | |
852 | \r | |
853 | @retval EFI_INVALID_PARAMETER Language is NULL.\r | |
854 | \r | |
855 | @retval EFI_INVALID_PARAMETER DriverName is NULL.\r | |
856 | \r | |
857 | @retval EFI_UNSUPPORTED The driver specified by This does not support\r | |
858 | the language specified by Language.\r | |
859 | \r | |
860 | **/\r | |
861 | EFI_STATUS\r | |
862 | EFIAPI\r | |
863 | I2cHostComponentNameGetDriverName (\r | |
1436aea4 MK |
864 | IN EFI_COMPONENT_NAME2_PROTOCOL *This,\r |
865 | IN CHAR8 *Language,\r | |
866 | OUT CHAR16 **DriverName\r | |
43e543bc | 867 | );\r |
d1102dba | 868 | \r |
43e543bc EL |
869 | /**\r |
870 | Retrieves a Unicode string that is the user readable name of the controller\r | |
871 | that is being managed by a driver.\r | |
872 | \r | |
873 | This function retrieves the user readable name of the controller specified by\r | |
874 | ControllerHandle and ChildHandle in the form of a Unicode string. If the\r | |
875 | driver specified by This has a user readable name in the language specified by\r | |
876 | Language, then a pointer to the controller name is returned in ControllerName,\r | |
877 | and EFI_SUCCESS is returned. If the driver specified by This is not currently\r | |
878 | managing the controller specified by ControllerHandle and ChildHandle,\r | |
879 | then EFI_UNSUPPORTED is returned. If the driver specified by This does not\r | |
880 | support the language specified by Language, then EFI_UNSUPPORTED is returned.\r | |
881 | \r | |
882 | @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or\r | |
883 | EFI_COMPONENT_NAME_PROTOCOL instance.\r | |
884 | \r | |
885 | @param ControllerHandle[in] The handle of a controller that the driver\r | |
886 | specified by This is managing. This handle\r | |
887 | specifies the controller whose name is to be\r | |
888 | returned.\r | |
889 | \r | |
890 | @param ChildHandle[in] The handle of the child controller to retrieve\r | |
891 | the name of. This is an optional parameter that\r | |
892 | may be NULL. It will be NULL for device\r | |
893 | drivers. It will also be NULL for a bus drivers\r | |
894 | that wish to retrieve the name of the bus\r | |
895 | controller. It will not be NULL for a bus\r | |
896 | driver that wishes to retrieve the name of a\r | |
897 | child controller.\r | |
898 | \r | |
899 | @param Language[in] A pointer to a Null-terminated ASCII string\r | |
900 | array indicating the language. This is the\r | |
901 | language of the driver name that the caller is\r | |
902 | requesting, and it must match one of the\r | |
903 | languages specified in SupportedLanguages. The\r | |
904 | number of languages supported by a driver is up\r | |
905 | to the driver writer. Language is specified in\r | |
906 | RFC 4646 or ISO 639-2 language code format.\r | |
907 | \r | |
908 | @param ControllerName[out] A pointer to the Unicode string to return.\r | |
909 | This Unicode string is the name of the\r | |
910 | controller specified by ControllerHandle and\r | |
911 | ChildHandle in the language specified by\r | |
912 | Language from the point of view of the driver\r | |
913 | specified by This.\r | |
914 | \r | |
915 | @retval EFI_SUCCESS The Unicode string for the user readable name in\r | |
916 | the language specified by Language for the\r | |
917 | driver specified by This was returned in\r | |
918 | DriverName.\r | |
919 | \r | |
920 | @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.\r | |
921 | \r | |
922 | @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid\r | |
923 | EFI_HANDLE.\r | |
924 | \r | |
925 | @retval EFI_INVALID_PARAMETER Language is NULL.\r | |
926 | \r | |
927 | @retval EFI_INVALID_PARAMETER ControllerName is NULL.\r | |
928 | \r | |
929 | @retval EFI_UNSUPPORTED The driver specified by This is not currently\r | |
930 | managing the controller specified by\r | |
931 | ControllerHandle and ChildHandle.\r | |
932 | \r | |
933 | @retval EFI_UNSUPPORTED The driver specified by This does not support\r | |
934 | the language specified by Language.\r | |
935 | \r | |
936 | **/\r | |
937 | EFI_STATUS\r | |
938 | EFIAPI\r | |
939 | I2cHostComponentNameGetControllerName (\r | |
1436aea4 MK |
940 | IN EFI_COMPONENT_NAME2_PROTOCOL *This,\r |
941 | IN EFI_HANDLE ControllerHandle,\r | |
942 | IN EFI_HANDLE ChildHandle OPTIONAL,\r | |
943 | IN CHAR8 *Language,\r | |
944 | OUT CHAR16 **ControllerName\r | |
43e543bc EL |
945 | );\r |
946 | \r | |
947 | /**\r | |
948 | Handle the bus available event\r | |
949 | \r | |
950 | This routine is called at TPL_I2C_SYNC.\r | |
951 | \r | |
952 | @param[in] Event Address of an EFI_EVENT handle\r | |
953 | @param[in] Context Address of an I2C_HOST_CONTEXT structure\r | |
954 | \r | |
955 | **/\r | |
956 | VOID\r | |
957 | EFIAPI\r | |
958 | I2cHostRequestCompleteEvent (\r | |
1436aea4 MK |
959 | IN EFI_EVENT Event,\r |
960 | IN VOID *Context\r | |
43e543bc EL |
961 | );\r |
962 | \r | |
963 | /**\r | |
964 | Handle the I2C bus configuration available event\r | |
965 | \r | |
966 | This routine is called at TPL_I2C_SYNC.\r | |
967 | \r | |
968 | @param[in] Event Address of an EFI_EVENT handle\r | |
969 | @param[in] Context Address of an I2C_HOST_CONTEXT structure\r | |
970 | \r | |
971 | **/\r | |
972 | VOID\r | |
973 | EFIAPI\r | |
974 | I2cHostI2cBusConfigurationAvailable (\r | |
1436aea4 MK |
975 | IN EFI_EVENT Event,\r |
976 | IN VOID *Context\r | |
43e543bc EL |
977 | );\r |
978 | \r | |
979 | /**\r | |
980 | Queue an I2C operation for execution on the I2C controller.\r | |
981 | \r | |
982 | This routine must be called at or below TPL_NOTIFY. For synchronous\r | |
983 | requests this routine must be called at or below TPL_CALLBACK.\r | |
984 | \r | |
985 | N.B. The typical consumers of this API are the I2C bus driver and\r | |
986 | on rare occasions the I2C test application. Extreme care must be\r | |
987 | taken by other consumers of this API to prevent confusing the\r | |
988 | third party I2C drivers due to a state change at the I2C device\r | |
989 | which the third party I2C drivers did not initiate. I2C platform\r | |
990 | drivers may use this API within these guidelines.\r | |
991 | \r | |
992 | This layer uses the concept of I2C bus configurations to describe\r | |
993 | the I2C bus. An I2C bus configuration is defined as a unique\r | |
994 | setting of the multiplexers and switches in the I2C bus which\r | |
995 | enable access to one or more I2C devices. When using a switch\r | |
996 | to divide a bus, due to speed differences, the I2C platform layer\r | |
997 | would define an I2C bus configuration for the I2C devices on each\r | |
998 | side of the switch. When using a multiplexer, the I2C platform\r | |
999 | layer defines an I2C bus configuration for each of the selector\r | |
1000 | values required to control the multiplexer. See Figure 1 in the\r | |
1001 | <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C\r | |
1002 | Specification</a> for a complex I2C bus configuration.\r | |
1003 | \r | |
1004 | The I2C host driver processes all operations in FIFO order. Prior to\r | |
1005 | performing the operation, the I2C host driver calls the I2C platform\r | |
1006 | driver to reconfigure the switches and multiplexers in the I2C bus\r | |
1007 | enabling access to the specified I2C device. The I2C platform driver\r | |
1008 | also selects the maximum bus speed for the device. After the I2C bus\r | |
1009 | is configured, the I2C host driver calls the I2C port driver to\r | |
1010 | initialize the I2C controller and start the I2C operation.\r | |
1011 | \r | |
1012 | @param[in] This Address of an EFI_I2C_HOST_PROTOCOL instance.\r | |
1013 | @param[in] I2cBusConfiguration I2C bus configuration to access the I2C\r | |
1014 | device.\r | |
1015 | @param[in] SlaveAddress Address of the device on the I2C bus.\r | |
1016 | @param[in] Event Event to set for asynchronous operations,\r | |
1017 | NULL for synchronous operations\r | |
1018 | @param[in] RequestPacket Address of an EFI_I2C_REQUEST_PACKET\r | |
1019 | structure describing the I2C operation\r | |
1020 | @param[out] I2cStatus Optional buffer to receive the I2C operation\r | |
1021 | completion status\r | |
1022 | \r | |
1023 | @retval EFI_SUCCESS The operation completed successfully.\r | |
1024 | @retval EFI_ABORTED The request did not complete because the driver\r | |
1025 | was shutdown.\r | |
1026 | @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.\r | |
1027 | @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.\r | |
1028 | This could indicate the slave device is not present.\r | |
1029 | @retval EFI_INVALID_PARAMETER RequestPacket is NULL\r | |
1030 | @retval EFI_INVALID_PARAMETER TPL is too high\r | |
1031 | @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value\r | |
1032 | @retval EFI_NO_RESPONSE The I2C device is not responding to the\r | |
1033 | slave address. EFI_DEVICE_ERROR may also be\r | |
1034 | returned if the controller can not distinguish\r | |
1035 | when the NACK occurred.\r | |
1036 | @retval EFI_NOT_FOUND I2C slave address exceeds maximum address\r | |
1037 | @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for\r | |
1038 | the event and then read status pointed to by\r | |
1039 | the request packet.\r | |
1040 | @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation\r | |
1041 | @retval EFI_TIMEOUT The transaction did not complete within an internally\r | |
1042 | specified timeout period.\r | |
1043 | \r | |
1044 | **/\r | |
1045 | EFI_STATUS\r | |
1046 | EFIAPI\r | |
1047 | I2cHostQueueRequest (\r | |
1048 | IN CONST EFI_I2C_HOST_PROTOCOL *This,\r | |
1049 | IN UINTN I2cBusConfiguration,\r | |
1050 | IN UINTN SlaveAddress,\r | |
1051 | IN EFI_EVENT Event OPTIONAL,\r | |
1052 | IN EFI_I2C_REQUEST_PACKET *RequestPacket,\r | |
1053 | OUT EFI_STATUS *I2cStatus OPTIONAL\r | |
1054 | );\r | |
1055 | \r | |
1056 | /**\r | |
1057 | The user Entry Point for I2C host module. The user code starts with this function.\r | |
1058 | \r | |
1059 | @param[in] ImageHandle The firmware allocated handle for the EFI image.\r | |
1060 | @param[in] SystemTable A pointer to the EFI System Table.\r | |
1061 | \r | |
1062 | @retval EFI_SUCCESS The entry point is executed successfully.\r | |
1063 | @retval other Some error occurs when executing this entry point.\r | |
1064 | \r | |
1065 | **/\r | |
1066 | EFI_STATUS\r | |
1067 | EFIAPI\r | |
1436aea4 MK |
1068 | InitializeI2cHost (\r |
1069 | IN EFI_HANDLE ImageHandle,\r | |
1070 | IN EFI_SYSTEM_TABLE *SystemTable\r | |
43e543bc EL |
1071 | );\r |
1072 | \r | |
1073 | /**\r | |
1074 | This is the unload handle for I2C host module.\r | |
1075 | \r | |
1076 | Disconnect the driver specified by ImageHandle from all the devices in the handle database.\r | |
1077 | Uninstall all the protocols installed in the driver entry point.\r | |
1078 | \r | |
1079 | @param[in] ImageHandle The drivers' driver image.\r | |
1080 | \r | |
1081 | @retval EFI_SUCCESS The image is unloaded.\r | |
1082 | @retval Others Failed to unload the image.\r | |
1083 | \r | |
1084 | **/\r | |
1085 | EFI_STATUS\r | |
1086 | EFIAPI\r | |
1087 | I2cHostUnload (\r | |
1436aea4 | 1088 | IN EFI_HANDLE ImageHandle\r |
43e543bc EL |
1089 | );\r |
1090 | \r | |
1436aea4 | 1091 | #endif // __I2C_DXE_H__\r |