2 Private data structures for the I2C DXE driver.
4 This file defines common data structures, macro definitions and some module
5 internal function header files.
7 Copyright (c) 2013 - 2018, 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
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.
22 #include <Library/BaseMemoryLib.h>
23 #include <Library/DebugLib.h>
24 #include <Library/DevicePathLib.h>
25 #include <Library/MemoryAllocationLib.h>
26 #include <Library/TimerLib.h>
27 #include <Library/UefiBootServicesTableLib.h>
28 #include <Library/UefiDriverEntryPoint.h>
29 #include <Library/UefiLib.h>
31 #include <Protocol/DriverBinding.h>
32 #include <Protocol/I2cEnumerate.h>
33 #include <Protocol/I2cHost.h>
34 #include <Protocol/I2cIo.h>
35 #include <Protocol/I2cMaster.h>
36 #include <Protocol/I2cBusConfigurationManagement.h>
37 #include <Protocol/LoadedImage.h>
39 #define I2C_DEVICE_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'D')
40 #define I2C_HOST_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'H')
41 #define I2C_REQUEST_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'R')
44 // Synchronize access to the list of requests
46 #define TPL_I2C_SYNC TPL_NOTIFY
52 EFI_I2C_ENUMERATE_PROTOCOL
*I2cEnumerate
;
53 EFI_I2C_HOST_PROTOCOL
*I2cHost
;
54 EFI_HANDLE Controller
;
55 EFI_DEVICE_PATH_PROTOCOL
*ParentDevicePath
;
56 EFI_HANDLE DriverBindingHandle
;
64 // Structure identification
74 // Upper level API to support the I2C device I/O
76 EFI_I2C_IO_PROTOCOL I2cIo
;
79 // Device path for this device
81 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
84 // Platform specific data for this device
86 CONST EFI_I2C_DEVICE
*I2cDevice
;
89 // Context for the common I/O support including the
90 // lower level API to the host controller.
92 I2C_BUS_CONTEXT
*I2cBusContext
;
95 #define I2C_DEVICE_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_DEVICE_CONTEXT, I2cIo, I2C_DEVICE_SIGNATURE)
107 // Next request in the pending request list
112 // I2C bus configuration for the operation
114 UINTN I2cBusConfiguration
;
117 // I2C slave address for the operation
122 // Event to set for asynchronous operations, NULL for
123 // synchronous operations
128 // I2C operation description
130 EFI_I2C_REQUEST_PACKET
*RequestPacket
;
133 // Optional buffer to receive the I2C operation completion status
138 #define I2C_REQUEST_FROM_ENTRY(a) CR (a, I2C_REQUEST, Link, I2C_REQUEST_SIGNATURE);
145 // Structure identification
150 // Current I2C bus configuration
152 UINTN I2cBusConfiguration
;
155 // I2C bus configuration management event
157 EFI_EVENT I2cBusConfigurationEvent
;
160 // I2C operation completion event
165 // I2C operation and I2C bus configuration management status
170 // I2C bus configuration management operation pending
172 BOOLEAN I2cBusConfigurationManagementPending
;
175 // I2C request list maintained by I2C Host
177 LIST_ENTRY RequestList
;
182 EFI_I2C_HOST_PROTOCOL I2cHost
;
185 // I2C bus configuration management protocol
187 EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL
*I2cBusConfigurationManagement
;
190 // Lower level API for I2C master (controller)
192 EFI_I2C_MASTER_PROTOCOL
*I2cMaster
;
195 #define I2C_HOST_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_HOST_CONTEXT, I2cHost, I2C_HOST_SIGNATURE)
200 extern EFI_COMPONENT_NAME_PROTOCOL gI2cBusComponentName
;
201 extern EFI_COMPONENT_NAME2_PROTOCOL gI2cBusComponentName2
;
202 extern EFI_DRIVER_BINDING_PROTOCOL gI2cBusDriverBinding
;
204 extern EFI_COMPONENT_NAME_PROTOCOL gI2cHostComponentName
;
205 extern EFI_COMPONENT_NAME2_PROTOCOL gI2cHostComponentName2
;
206 extern EFI_DRIVER_BINDING_PROTOCOL gI2cHostDriverBinding
;
211 This routine allocates the necessary resources for the driver.
213 This routine is called by I2cBusDriverStart to complete the driver
216 @param[in] I2cBus Address of an I2C_BUS_CONTEXT structure
217 @param[in] Controller Handle to the controller
218 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path.
220 @retval EFI_SUCCESS Driver API properly initialized
225 IN I2C_BUS_CONTEXT
*I2cBus
,
226 IN EFI_HANDLE Controller
,
227 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
231 Unregister an I2C device.
233 This function removes the protocols installed on the controller handle and
234 frees the resources allocated for the I2C device.
236 @param This The pointer to EFI_DRIVER_BINDING_PROTOCOL instance.
237 @param Controller The controller handle of the I2C device.
238 @param Handle The child handle.
240 @retval EFI_SUCCESS The I2C device is successfully unregistered.
241 @return Others Some error occurs when unregistering the I2C device.
245 UnRegisterI2cDevice (
246 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
247 IN EFI_HANDLE Controller
,
252 Create a path for the I2C device
254 Append the I2C slave path to the I2C master controller path.
256 @param[in] I2cDeviceContext Address of an I2C_DEVICE_CONTEXT structure.
257 @param[in] BuildControllerNode Flag to build controller node in device path.
259 @retval EFI_SUCCESS The I2C device path is built successfully.
260 @return Others It is failed to built device path.
264 I2cBusDevicePathAppend (
265 IN I2C_DEVICE_CONTEXT
*I2cDeviceContext
,
266 IN BOOLEAN BuildControllerNode
270 Queue an I2C transaction for execution on the I2C device.
272 This routine must be called at or below TPL_NOTIFY. For synchronous
273 requests this routine must be called at or below TPL_CALLBACK.
275 This routine queues an I2C transaction to the I2C controller for
276 execution on the I2C bus.
278 When Event is NULL, QueueRequest() operates synchronously and returns
279 the I2C completion status as its return value.
281 When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS
282 indicating that the asynchronous I2C transaction was queued. The values
283 above are returned in the buffer pointed to by I2cStatus upon the
284 completion of the I2C transaction when I2cStatus is not NULL.
286 The upper layer driver writer provides the following to the platform
289 1. Vendor specific GUID for the I2C part
290 2. Guidance on proper construction of the slave address array when the
291 I2C device uses more than one slave address. The I2C bus protocol
292 uses the SlaveAddressIndex to perform relative to physical address
293 translation to access the blocks of hardware within the I2C device.
295 @param[in] This Pointer to an EFI_I2C_IO_PROTOCOL structure.
296 @param[in] SlaveAddressIndex Index value into an array of slave addresses
297 for the I2C device. The values in the array
298 are specified by the board designer, with the
299 third party I2C device driver writer providing
300 the slave address order.
302 For devices that have a single slave address,
303 this value must be zero. If the I2C device
304 uses more than one slave address then the
305 third party (upper level) I2C driver writer
306 needs to specify the order of entries in the
309 \ref ThirdPartyI2cDrivers "Third Party I2C
310 Drivers" section in I2cMaster.h.
311 @param[in] Event Event to signal for asynchronous transactions,
312 NULL for synchronous transactions
313 @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure
314 describing the I2C transaction
315 @param[out] I2cStatus Optional buffer to receive the I2C transaction
318 @retval EFI_SUCCESS The asynchronous transaction was successfully
319 queued when Event is not NULL.
320 @retval EFI_SUCCESS The transaction completed successfully when
322 @retval EFI_ABORTED The request did not complete because the driver
323 binding Stop() routine was called.
324 @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too
326 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the
328 @retval EFI_INVALID_PARAMETER RequestPacket is NULL
329 @retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter
330 @retval EFI_NO_MAPPING The EFI_I2C_HOST_PROTOCOL could not set the
331 bus configuration required to access this I2C
333 @retval EFI_NO_RESPONSE The I2C device is not responding to the slave
334 address selected by SlaveAddressIndex.
335 EFI_DEVICE_ERROR will be returned if the
336 controller cannot distinguish when the NACK
338 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction
339 @retval EFI_UNSUPPORTED The controller does not support the requested
346 IN CONST EFI_I2C_IO_PROTOCOL
*This
,
347 IN UINTN SlaveAddressIndex
,
348 IN EFI_EVENT Event OPTIONAL
,
349 IN EFI_I2C_REQUEST_PACKET
*RequestPacket
,
350 OUT EFI_STATUS
*I2cStatus OPTIONAL
354 Tests to see if this driver supports a given controller. If a child device is provided,
355 it further tests to see if this driver supports creating a handle for the specified child device.
357 This function checks to see if the driver specified by This supports the device specified by
358 ControllerHandle. Drivers will typically use the device path attached to
359 ControllerHandle and/or the services from the bus I/O abstraction attached to
360 ControllerHandle to determine if the driver supports ControllerHandle. This function
361 may be called many times during platform initialization. In order to reduce boot times, the tests
362 performed by this function must be very small, and take as little time as possible to execute. This
363 function must not change the state of any hardware devices, and this function must be aware that the
364 device specified by ControllerHandle may already be managed by the same driver or a
365 different driver. This function must match its calls to AllocatePages() with FreePages(),
366 AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
367 Since ControllerHandle may have been previously started by the same driver, if a protocol is
368 already in the opened state, then it must not be closed with CloseProtocol(). This is required
369 to guarantee the state of ControllerHandle is not modified by this function.
371 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
372 @param[in] ControllerHandle The handle of the controller to test. This handle
373 must support a protocol interface that supplies
374 an I/O abstraction to the driver.
375 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
376 parameter is ignored by device drivers, and is optional for bus
377 drivers. For bus drivers, if this parameter is not NULL, then
378 the bus driver must determine if the bus controller specified
379 by ControllerHandle and the child controller specified
380 by RemainingDevicePath are both supported by this
383 @retval EFI_SUCCESS The device specified by ControllerHandle and
384 RemainingDevicePath is supported by the driver specified by This.
385 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
386 RemainingDevicePath is already being managed by the driver
388 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
389 RemainingDevicePath is already being managed by a different
390 driver or an application that requires exclusive access.
391 Currently not implemented.
392 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
393 RemainingDevicePath is not supported by the driver specified by This.
397 I2cBusDriverSupported (
398 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
399 IN EFI_HANDLE Controller
,
400 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
404 Starts a device controller or a bus controller.
406 The Start() function is designed to be invoked from the EFI boot service ConnectController().
407 As a result, much of the error checking on the parameters to Start() has been moved into this
408 common boot service. It is legal to call Start() from other locations,
409 but the following calling restrictions must be followed or the system behavior will not be deterministic.
410 1. ControllerHandle must be a valid EFI_HANDLE.
411 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
412 EFI_DEVICE_PATH_PROTOCOL.
413 3. Prior to calling Start(), the Supported() function for the driver specified by This must
414 have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
416 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
417 @param[in] ControllerHandle The handle of the controller to start. This handle
418 must support a protocol interface that supplies
419 an I/O abstraction to the driver.
420 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
421 parameter is ignored by device drivers, and is optional for bus
422 drivers. For a bus driver, if this parameter is NULL, then handles
423 for all the children of Controller are created by this driver.
424 If this parameter is not NULL and the first Device Path Node is
425 not the End of Device Path Node, then only the handle for the
426 child device specified by the first Device Path Node of
427 RemainingDevicePath is created by this driver.
428 If the first Device Path Node of RemainingDevicePath is
429 the End of Device Path Node, no child handle is created by this
432 @retval EFI_SUCCESS The device was started.
433 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
434 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
435 @retval Others The driver failded to start the device.
441 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
442 IN EFI_HANDLE Controller
,
443 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
447 Stops a device controller or a bus controller.
449 The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
450 As a result, much of the error checking on the parameters to Stop() has been moved
451 into this common boot service. It is legal to call Stop() from other locations,
452 but the following calling restrictions must be followed or the system behavior will not be deterministic.
453 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
454 same driver's Start() function.
455 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
456 EFI_HANDLE. In addition, all of these handles must have been created in this driver's
457 Start() function, and the Start() function must have called OpenProtocol() on
458 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
460 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
461 @param[in] ControllerHandle A handle to the device being stopped. The handle must
462 support a bus specific I/O protocol for the driver
463 to use to stop the device.
464 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
465 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
466 if NumberOfChildren is 0.
468 @retval EFI_SUCCESS The device was stopped.
469 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
475 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
476 IN EFI_HANDLE Controller
,
477 IN UINTN NumberOfChildren
,
478 IN EFI_HANDLE
*ChildHandleBuffer
482 Retrieves a Unicode string that is the user readable name of the driver.
484 This function retrieves the user readable name of a driver in the form of a
485 Unicode string. If the driver specified by This has a user readable name in
486 the language specified by Language, then a pointer to the driver name is
487 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
488 by This does not support the language specified by Language,
489 then EFI_UNSUPPORTED is returned.
491 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
492 EFI_COMPONENT_NAME_PROTOCOL instance.
494 @param Language[in] A pointer to a Null-terminated ASCII string
495 array indicating the language. This is the
496 language of the driver name that the caller is
497 requesting, and it must match one of the
498 languages specified in SupportedLanguages. The
499 number of languages supported by a driver is up
500 to the driver writer. Language is specified
501 in RFC 4646 or ISO 639-2 language code format.
503 @param DriverName[out] A pointer to the Unicode string to return.
504 This Unicode string is the name of the
505 driver specified by This in the language
506 specified by Language.
508 @retval EFI_SUCCESS The Unicode string for the Driver specified by
509 This and the language specified by Language was
510 returned in DriverName.
512 @retval EFI_INVALID_PARAMETER Language is NULL.
514 @retval EFI_INVALID_PARAMETER DriverName is NULL.
516 @retval EFI_UNSUPPORTED The driver specified by This does not support
517 the language specified by Language.
522 I2cBusComponentNameGetDriverName (
523 IN EFI_COMPONENT_NAME2_PROTOCOL
*This
,
525 OUT CHAR16
**DriverName
529 Retrieves a Unicode string that is the user readable name of the controller
530 that is being managed by a driver.
532 This function retrieves the user readable name of the controller specified by
533 ControllerHandle and ChildHandle in the form of a Unicode string. If the
534 driver specified by This has a user readable name in the language specified by
535 Language, then a pointer to the controller name is returned in ControllerName,
536 and EFI_SUCCESS is returned. If the driver specified by This is not currently
537 managing the controller specified by ControllerHandle and ChildHandle,
538 then EFI_UNSUPPORTED is returned. If the driver specified by This does not
539 support the language specified by Language, then EFI_UNSUPPORTED is returned.
541 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
542 EFI_COMPONENT_NAME_PROTOCOL instance.
544 @param ControllerHandle[in] The handle of a controller that the driver
545 specified by This is managing. This handle
546 specifies the controller whose name is to be
549 @param ChildHandle[in] The handle of the child controller to retrieve
550 the name of. This is an optional parameter that
551 may be NULL. It will be NULL for device
552 drivers. It will also be NULL for a bus drivers
553 that wish to retrieve the name of the bus
554 controller. It will not be NULL for a bus
555 driver that wishes to retrieve the name of a
558 @param Language[in] A pointer to a Null-terminated ASCII string
559 array indicating the language. This is the
560 language of the driver name that the caller is
561 requesting, and it must match one of the
562 languages specified in SupportedLanguages. The
563 number of languages supported by a driver is up
564 to the driver writer. Language is specified in
565 RFC 4646 or ISO 639-2 language code format.
567 @param ControllerName[out] A pointer to the Unicode string to return.
568 This Unicode string is the name of the
569 controller specified by ControllerHandle and
570 ChildHandle in the language specified by
571 Language from the point of view of the driver
574 @retval EFI_SUCCESS The Unicode string for the user readable name in
575 the language specified by Language for the
576 driver specified by This was returned in
579 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
581 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
584 @retval EFI_INVALID_PARAMETER Language is NULL.
586 @retval EFI_INVALID_PARAMETER ControllerName is NULL.
588 @retval EFI_UNSUPPORTED The driver specified by This is not currently
589 managing the controller specified by
590 ControllerHandle and ChildHandle.
592 @retval EFI_UNSUPPORTED The driver specified by This does not support
593 the language specified by Language.
598 I2cBusComponentNameGetControllerName (
599 IN EFI_COMPONENT_NAME2_PROTOCOL
*This
,
600 IN EFI_HANDLE ControllerHandle
,
601 IN EFI_HANDLE ChildHandle OPTIONAL
,
603 OUT CHAR16
**ControllerName
607 The user entry point for the I2C bus module. The user code starts with
610 @param[in] ImageHandle The firmware allocated handle for the EFI image.
611 @param[in] SystemTable A pointer to the EFI System Table.
613 @retval EFI_SUCCESS The entry point is executed successfully.
614 @retval other Some error occurs when executing this entry point.
620 IN EFI_HANDLE ImageHandle
,
621 IN EFI_SYSTEM_TABLE
*SystemTable
625 This is the unload handle for I2C bus module.
627 Disconnect the driver specified by ImageHandle from all the devices in the handle database.
628 Uninstall all the protocols installed in the driver entry point.
630 @param[in] ImageHandle The drivers' driver image.
632 @retval EFI_SUCCESS The image is unloaded.
633 @retval Others Failed to unload the image.
639 IN EFI_HANDLE ImageHandle
643 Release all the resources allocated for the I2C device.
645 This function releases all the resources allocated for the I2C device.
647 @param I2cDeviceContext The I2C child device involved for the operation.
651 ReleaseI2cDeviceContext (
652 IN I2C_DEVICE_CONTEXT
*I2cDeviceContext
656 Complete the current request
658 @param[in] I2cHost Address of an I2C_HOST_CONTEXT structure.
659 @param[in] Status Status of the I<sub>2</sub>C operation.
661 @return This routine returns the input status value.
665 I2cHostRequestComplete (
666 I2C_HOST_CONTEXT
*I2cHost
,
671 Enable access to the I2C bus configuration
673 @param[in] I2cHostContext Address of an I2C_HOST_CONTEXT structure
675 @retval EFI_SUCCESS The operation completed successfully.
676 @retval EFI_ABORTED The request did not complete because the driver
678 @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.
679 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.
680 This could indicate the slave device is not present.
681 @retval EFI_INVALID_PARAMETER RequestPacket is NULL
682 @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value
683 @retval EFI_NO_RESPONSE The I2C device is not responding to the
684 slave address. EFI_DEVICE_ERROR may also be
685 returned if the controller can not distinguish
686 when the NACK occurred.
687 @retval EFI_NOT_FOUND I2C slave address exceeds maximum address
688 @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for
689 the event and then read status.
690 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation
691 @retval EFI_TIMEOUT The transaction did not complete within an internally
692 specified timeout period.
696 I2cHostRequestEnable (
697 I2C_HOST_CONTEXT
*I2cHost
701 Tests to see if this driver supports a given controller. If a child device is provided,
702 it further tests to see if this driver supports creating a handle for the specified child device.
704 This function checks to see if the driver specified by This supports the device specified by
705 ControllerHandle. Drivers will typically use the device path attached to
706 ControllerHandle and/or the services from the bus I/O abstraction attached to
707 ControllerHandle to determine if the driver supports ControllerHandle. This function
708 may be called many times during platform initialization. In order to reduce boot times, the tests
709 performed by this function must be very small, and take as little time as possible to execute. This
710 function must not change the state of any hardware devices, and this function must be aware that the
711 device specified by ControllerHandle may already be managed by the same driver or a
712 different driver. This function must match its calls to AllocatePages() with FreePages(),
713 AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
714 Since ControllerHandle may have been previously started by the same driver, if a protocol is
715 already in the opened state, then it must not be closed with CloseProtocol(). This is required
716 to guarantee the state of ControllerHandle is not modified by this function.
718 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
719 @param[in] ControllerHandle The handle of the controller to test. This handle
720 must support a protocol interface that supplies
721 an I/O abstraction to the driver.
722 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
723 parameter is ignored by device drivers, and is optional for bus
724 drivers. For bus drivers, if this parameter is not NULL, then
725 the bus driver must determine if the bus controller specified
726 by ControllerHandle and the child controller specified
727 by RemainingDevicePath are both supported by this
730 @retval EFI_SUCCESS The device specified by ControllerHandle and
731 RemainingDevicePath is supported by the driver specified by This.
732 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
733 RemainingDevicePath is already being managed by the driver
735 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
736 RemainingDevicePath is already being managed by a different
737 driver or an application that requires exclusive access.
738 Currently not implemented.
739 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
740 RemainingDevicePath is not supported by the driver specified by This.
744 I2cHostDriverSupported (
745 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
746 IN EFI_HANDLE Controller
,
747 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
751 Starts a device controller or a bus controller.
753 The Start() function is designed to be invoked from the EFI boot service ConnectController().
754 As a result, much of the error checking on the parameters to Start() has been moved into this
755 common boot service. It is legal to call Start() from other locations,
756 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
757 1. ControllerHandle must be a valid EFI_HANDLE.
758 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
759 EFI_DEVICE_PATH_PROTOCOL.
760 3. Prior to calling Start(), the Supported() function for the driver specified by This must
761 have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
763 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
764 @param[in] ControllerHandle The handle of the controller to start. This handle
765 must support a protocol interface that supplies
766 an I/O abstraction to the driver.
767 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
768 parameter is ignored by device drivers, and is optional for bus
769 drivers. For a bus driver, if this parameter is NULL, then handles
770 for all the children of Controller are created by this driver.
771 If this parameter is not NULL and the first Device Path Node is
772 not the End of Device Path Node, then only the handle for the
773 child device specified by the first Device Path Node of
774 RemainingDevicePath is created by this driver.
775 If the first Device Path Node of RemainingDevicePath is
776 the End of Device Path Node, no child handle is created by this
779 @retval EFI_SUCCESS The device was started.
780 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
781 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
782 @retval Others The driver failded to start the device.
788 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
789 IN EFI_HANDLE Controller
,
790 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath
794 Stops a device controller or a bus controller.
796 The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
797 As a result, much of the error checking on the parameters to Stop() has been moved
798 into this common boot service. It is legal to call Stop() from other locations,
799 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
800 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
801 same driver's Start() function.
802 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
803 EFI_HANDLE. In addition, all of these handles must have been created in this driver's
804 Start() function, and the Start() function must have called OpenProtocol() on
805 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
807 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
808 @param[in] ControllerHandle A handle to the device being stopped. The handle must
809 support a bus specific I/O protocol for the driver
810 to use to stop the device.
811 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
812 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
813 if NumberOfChildren is 0.
815 @retval EFI_SUCCESS The device was stopped.
816 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
822 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
823 IN EFI_HANDLE Controller
,
824 IN UINTN NumberOfChildren
,
825 IN EFI_HANDLE
*ChildHandleBuffer
829 Retrieves a Unicode string that is the user readable name of the driver.
831 This function retrieves the user readable name of a driver in the form of a
832 Unicode string. If the driver specified by This has a user readable name in
833 the language specified by Language, then a pointer to the driver name is
834 returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
835 by This does not support the language specified by Language,
836 then EFI_UNSUPPORTED is returned.
838 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
839 EFI_COMPONENT_NAME_PROTOCOL instance.
841 @param Language[in] A pointer to a Null-terminated ASCII string
842 array indicating the language. This is the
843 language of the driver name that the caller is
844 requesting, and it must match one of the
845 languages specified in SupportedLanguages. The
846 number of languages supported by a driver is up
847 to the driver writer. Language is specified
848 in RFC 4646 or ISO 639-2 language code format.
850 @param DriverName[out] A pointer to the Unicode string to return.
851 This Unicode string is the name of the
852 driver specified by This in the language
853 specified by Language.
855 @retval EFI_SUCCESS The Unicode string for the Driver specified by
856 This and the language specified by Language was
857 returned in DriverName.
859 @retval EFI_INVALID_PARAMETER Language is NULL.
861 @retval EFI_INVALID_PARAMETER DriverName is NULL.
863 @retval EFI_UNSUPPORTED The driver specified by This does not support
864 the language specified by Language.
869 I2cHostComponentNameGetDriverName (
870 IN EFI_COMPONENT_NAME2_PROTOCOL
*This
,
872 OUT CHAR16
**DriverName
876 Retrieves a Unicode string that is the user readable name of the controller
877 that is being managed by a driver.
879 This function retrieves the user readable name of the controller specified by
880 ControllerHandle and ChildHandle in the form of a Unicode string. If the
881 driver specified by This has a user readable name in the language specified by
882 Language, then a pointer to the controller name is returned in ControllerName,
883 and EFI_SUCCESS is returned. If the driver specified by This is not currently
884 managing the controller specified by ControllerHandle and ChildHandle,
885 then EFI_UNSUPPORTED is returned. If the driver specified by This does not
886 support the language specified by Language, then EFI_UNSUPPORTED is returned.
888 @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
889 EFI_COMPONENT_NAME_PROTOCOL instance.
891 @param ControllerHandle[in] The handle of a controller that the driver
892 specified by This is managing. This handle
893 specifies the controller whose name is to be
896 @param ChildHandle[in] The handle of the child controller to retrieve
897 the name of. This is an optional parameter that
898 may be NULL. It will be NULL for device
899 drivers. It will also be NULL for a bus drivers
900 that wish to retrieve the name of the bus
901 controller. It will not be NULL for a bus
902 driver that wishes to retrieve the name of a
905 @param Language[in] A pointer to a Null-terminated ASCII string
906 array indicating the language. This is the
907 language of the driver name that the caller is
908 requesting, and it must match one of the
909 languages specified in SupportedLanguages. The
910 number of languages supported by a driver is up
911 to the driver writer. Language is specified in
912 RFC 4646 or ISO 639-2 language code format.
914 @param ControllerName[out] A pointer to the Unicode string to return.
915 This Unicode string is the name of the
916 controller specified by ControllerHandle and
917 ChildHandle in the language specified by
918 Language from the point of view of the driver
921 @retval EFI_SUCCESS The Unicode string for the user readable name in
922 the language specified by Language for the
923 driver specified by This was returned in
926 @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.
928 @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
931 @retval EFI_INVALID_PARAMETER Language is NULL.
933 @retval EFI_INVALID_PARAMETER ControllerName is NULL.
935 @retval EFI_UNSUPPORTED The driver specified by This is not currently
936 managing the controller specified by
937 ControllerHandle and ChildHandle.
939 @retval EFI_UNSUPPORTED The driver specified by This does not support
940 the language specified by Language.
945 I2cHostComponentNameGetControllerName (
946 IN EFI_COMPONENT_NAME2_PROTOCOL
*This
,
947 IN EFI_HANDLE ControllerHandle
,
948 IN EFI_HANDLE ChildHandle OPTIONAL
,
950 OUT CHAR16
**ControllerName
954 Handle the bus available event
956 This routine is called at TPL_I2C_SYNC.
958 @param[in] Event Address of an EFI_EVENT handle
959 @param[in] Context Address of an I2C_HOST_CONTEXT structure
964 I2cHostRequestCompleteEvent (
970 Handle the I2C bus configuration available event
972 This routine is called at TPL_I2C_SYNC.
974 @param[in] Event Address of an EFI_EVENT handle
975 @param[in] Context Address of an I2C_HOST_CONTEXT structure
980 I2cHostI2cBusConfigurationAvailable (
986 Queue an I2C operation for execution on the I2C controller.
988 This routine must be called at or below TPL_NOTIFY. For synchronous
989 requests this routine must be called at or below TPL_CALLBACK.
991 N.B. The typical consumers of this API are the I2C bus driver and
992 on rare occasions the I2C test application. Extreme care must be
993 taken by other consumers of this API to prevent confusing the
994 third party I2C drivers due to a state change at the I2C device
995 which the third party I2C drivers did not initiate. I2C platform
996 drivers may use this API within these guidelines.
998 This layer uses the concept of I2C bus configurations to describe
999 the I2C bus. An I2C bus configuration is defined as a unique
1000 setting of the multiplexers and switches in the I2C bus which
1001 enable access to one or more I2C devices. When using a switch
1002 to divide a bus, due to speed differences, the I2C platform layer
1003 would define an I2C bus configuration for the I2C devices on each
1004 side of the switch. When using a multiplexer, the I2C platform
1005 layer defines an I2C bus configuration for each of the selector
1006 values required to control the multiplexer. See Figure 1 in the
1007 <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C
1008 Specification</a> for a complex I2C bus configuration.
1010 The I2C host driver processes all operations in FIFO order. Prior to
1011 performing the operation, the I2C host driver calls the I2C platform
1012 driver to reconfigure the switches and multiplexers in the I2C bus
1013 enabling access to the specified I2C device. The I2C platform driver
1014 also selects the maximum bus speed for the device. After the I2C bus
1015 is configured, the I2C host driver calls the I2C port driver to
1016 initialize the I2C controller and start the I2C operation.
1018 @param[in] This Address of an EFI_I2C_HOST_PROTOCOL instance.
1019 @param[in] I2cBusConfiguration I2C bus configuration to access the I2C
1021 @param[in] SlaveAddress Address of the device on the I2C bus.
1022 @param[in] Event Event to set for asynchronous operations,
1023 NULL for synchronous operations
1024 @param[in] RequestPacket Address of an EFI_I2C_REQUEST_PACKET
1025 structure describing the I2C operation
1026 @param[out] I2cStatus Optional buffer to receive the I2C operation
1029 @retval EFI_SUCCESS The operation completed successfully.
1030 @retval EFI_ABORTED The request did not complete because the driver
1032 @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.
1033 @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.
1034 This could indicate the slave device is not present.
1035 @retval EFI_INVALID_PARAMETER RequestPacket is NULL
1036 @retval EFI_INVALID_PARAMETER TPL is too high
1037 @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value
1038 @retval EFI_NO_RESPONSE The I2C device is not responding to the
1039 slave address. EFI_DEVICE_ERROR may also be
1040 returned if the controller can not distinguish
1041 when the NACK occurred.
1042 @retval EFI_NOT_FOUND I2C slave address exceeds maximum address
1043 @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for
1044 the event and then read status pointed to by
1046 @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation
1047 @retval EFI_TIMEOUT The transaction did not complete within an internally
1048 specified timeout period.
1053 I2cHostQueueRequest (
1054 IN CONST EFI_I2C_HOST_PROTOCOL
*This
,
1055 IN UINTN I2cBusConfiguration
,
1056 IN UINTN SlaveAddress
,
1057 IN EFI_EVENT Event OPTIONAL
,
1058 IN EFI_I2C_REQUEST_PACKET
*RequestPacket
,
1059 OUT EFI_STATUS
*I2cStatus OPTIONAL
1063 The user Entry Point for I2C host module. The user code starts with this function.
1065 @param[in] ImageHandle The firmware allocated handle for the EFI image.
1066 @param[in] SystemTable A pointer to the EFI System Table.
1068 @retval EFI_SUCCESS The entry point is executed successfully.
1069 @retval other Some error occurs when executing this entry point.
1075 IN EFI_HANDLE ImageHandle
,
1076 IN EFI_SYSTEM_TABLE
*SystemTable
1080 This is the unload handle for I2C host module.
1082 Disconnect the driver specified by ImageHandle from all the devices in the handle database.
1083 Uninstall all the protocols installed in the driver entry point.
1085 @param[in] ImageHandle The drivers' driver image.
1087 @retval EFI_SUCCESS The image is unloaded.
1088 @retval Others Failed to unload the image.
1094 IN EFI_HANDLE ImageHandle
1097 #endif // __I2C_DXE_H__