--- /dev/null
+/** @file\r
+ Private data structures for the I2C DXE driver.\r
+\r
+ This file defines common data structures, macro definitions and some module\r
+ internal function header files.\r
+\r
+ Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>\r
+ This program and the accompanying materials\r
+ are licensed and made available under the terms and conditions of the BSD License\r
+ which accompanies this distribution. The full text of the license may be found at\r
+ http://opensource.org/licenses/bsd-license.php\r
+\r
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+**/\r
+\r
+#ifndef __I2C_DXE_H__\r
+#define __I2C_DXE_H__\r
+\r
+#include <Uefi.h>\r
+#include <Library/BaseMemoryLib.h>\r
+#include <Library/DebugLib.h>\r
+#include <Library/DevicePathLib.h>\r
+#include <Library/MemoryAllocationLib.h>\r
+#include <Library/TimerLib.h>\r
+#include <Library/UefiBootServicesTableLib.h>\r
+#include <Library/UefiDriverEntryPoint.h>\r
+#include <Library/UefiLib.h>\r
+\r
+#include <Protocol/DriverBinding.h>\r
+#include <Protocol/I2cEnumerate.h>\r
+#include <Protocol/I2cHost.h>\r
+#include <Protocol/I2cIo.h>\r
+#include <Protocol/I2cMaster.h>\r
+#include <Protocol/I2cBusConfigurationManagement.h>\r
+#include <Protocol/LoadedImage.h>\r
+\r
+#define I2C_DEVICE_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'D')\r
+#define I2C_HOST_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'H')\r
+#define I2C_REQUEST_SIGNATURE SIGNATURE_32 ('I', '2', 'C', 'R')\r
+\r
+//\r
+// Synchronize access to the list of requests\r
+//\r
+#define TPL_I2C_SYNC TPL_NOTIFY\r
+\r
+//\r
+// I2C bus context\r
+//\r
+typedef struct {\r
+ EFI_I2C_ENUMERATE_PROTOCOL *I2cEnumerate;\r
+ EFI_I2C_HOST_PROTOCOL *I2cHost;\r
+ EFI_HANDLE Controller;\r
+ EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath;\r
+ EFI_HANDLE DriverBindingHandle; \r
+} I2C_BUS_CONTEXT;\r
+\r
+//\r
+// I2C device context\r
+//\r
+typedef struct {\r
+ //\r
+ // Structure identification\r
+ //\r
+ UINT32 Signature;\r
+\r
+ //\r
+ // I2c device handle\r
+ //\r
+ EFI_HANDLE Handle;\r
+\r
+ //\r
+ // Upper level API to support the I2C device I/O\r
+ //\r
+ EFI_I2C_IO_PROTOCOL I2cIo;\r
+\r
+ //\r
+ // Device path for this device\r
+ //\r
+ EFI_DEVICE_PATH_PROTOCOL *DevicePath;\r
+\r
+ //\r
+ // Platform specific data for this device\r
+ //\r
+ CONST EFI_I2C_DEVICE *I2cDevice;\r
+\r
+ //\r
+ // Context for the common I/O support including the\r
+ // lower level API to the host controller.\r
+ //\r
+ I2C_BUS_CONTEXT *I2cBusContext;\r
+} I2C_DEVICE_CONTEXT;\r
+\r
+#define I2C_DEVICE_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_DEVICE_CONTEXT, I2cIo, I2C_DEVICE_SIGNATURE)\r
+\r
+//\r
+// I2C Request\r
+//\r
+typedef struct {\r
+ //\r
+ // Signature\r
+ //\r
+ UINT32 Signature;\r
+ \r
+ //\r
+ // Next request in the pending request list\r
+ //\r
+ LIST_ENTRY Link;\r
+\r
+ //\r
+ // I2C bus configuration for the operation\r
+ //\r
+ UINTN I2cBusConfiguration;\r
+\r
+ //\r
+ // I2C slave address for the operation\r
+ //\r
+ UINTN SlaveAddress;\r
+\r
+ //\r
+ // Event to set for asynchronous operations, NULL for\r
+ // synchronous operations\r
+ //\r
+ EFI_EVENT Event;\r
+\r
+ //\r
+ // I2C operation description\r
+ //\r
+ EFI_I2C_REQUEST_PACKET *RequestPacket;\r
+\r
+ //\r
+ // Optional buffer to receive the I2C operation completion status\r
+ //\r
+ EFI_STATUS *Status;\r
+} I2C_REQUEST;\r
+\r
+#define I2C_REQUEST_FROM_ENTRY(a) CR (a, I2C_REQUEST, Link, I2C_REQUEST_SIGNATURE);\r
+\r
+//\r
+// I2C host context\r
+//\r
+typedef struct {\r
+ //\r
+ // Structure identification\r
+ //\r
+ UINTN Signature;\r
+\r
+ //\r
+ // Current I2C bus configuration\r
+ //\r
+ UINTN I2cBusConfiguration;\r
+\r
+ //\r
+ // I2C bus configuration management event\r
+ //\r
+ EFI_EVENT I2cBusConfigurationEvent;\r
+\r
+ //\r
+ // I2C operation completion event\r
+ //\r
+ EFI_EVENT I2cEvent;\r
+\r
+ //\r
+ // I2C operation and I2C bus configuration management status\r
+ //\r
+ EFI_STATUS Status;\r
+\r
+ //\r
+ // I2C bus configuration management operation pending\r
+ //\r
+ BOOLEAN I2cBusConfigurationManagementPending;\r
+\r
+ //\r
+ // I2C request list maintained by I2C Host\r
+ //\r
+ LIST_ENTRY RequestList;\r
+\r
+ //\r
+ // Upper level API\r
+ //\r
+ EFI_I2C_HOST_PROTOCOL I2cHost;\r
+\r
+ //\r
+ // I2C bus configuration management protocol\r
+ //\r
+ EFI_I2C_BUS_CONFIGURATION_MANAGEMENT_PROTOCOL *I2cBusConfigurationManagement;\r
+\r
+ //\r
+ // Lower level API for I2C master (controller)\r
+ //\r
+ EFI_I2C_MASTER_PROTOCOL *I2cMaster;\r
+} I2C_HOST_CONTEXT;\r
+\r
+#define I2C_HOST_CONTEXT_FROM_PROTOCOL(a) CR (a, I2C_HOST_CONTEXT, I2cHost, I2C_HOST_SIGNATURE)\r
+\r
+//\r
+// Global Variables\r
+//\r
+extern EFI_COMPONENT_NAME_PROTOCOL gI2cBusComponentName;\r
+extern EFI_COMPONENT_NAME2_PROTOCOL gI2cBusComponentName2;\r
+extern EFI_DRIVER_BINDING_PROTOCOL gI2cBusDriverBinding;\r
+\r
+extern EFI_COMPONENT_NAME_PROTOCOL gI2cHostComponentName;\r
+extern EFI_COMPONENT_NAME2_PROTOCOL gI2cHostComponentName2;\r
+extern EFI_DRIVER_BINDING_PROTOCOL gI2cHostDriverBinding;\r
+\r
+/**\r
+ Start the I2C driver\r
+\r
+ This routine allocates the necessary resources for the driver.\r
+\r
+ This routine is called by I2cBusDriverStart to complete the driver\r
+ initialization.\r
+\r
+ @param[in] I2cBus Address of an I2C_BUS_CONTEXT structure\r
+ @param[in] Controller Handle to the controller\r
+ @param[in] RemainingDevicePath A pointer to the remaining portion of a device path.\r
+\r
+ @retval EFI_SUCCESS Driver API properly initialized\r
+ \r
+**/\r
+EFI_STATUS\r
+RegisterI2cDevice (\r
+ IN I2C_BUS_CONTEXT *I2cBus,\r
+ IN EFI_HANDLE Controller,\r
+ IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
+ );\r
+\r
+/**\r
+ Unregister an I2C device.\r
+\r
+ This function removes the protocols installed on the controller handle and\r
+ frees the resources allocated for the I2C device.\r
+\r
+ @param This The pointer to EFI_DRIVER_BINDING_PROTOCOL instance.\r
+ @param Controller The controller handle of the I2C device.\r
+ @param Handle The child handle.\r
+\r
+ @retval EFI_SUCCESS The I2C device is successfully unregistered.\r
+ @return Others Some error occurs when unregistering the I2C device.\r
+\r
+**/\r
+EFI_STATUS\r
+UnRegisterI2cDevice (\r
+ IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
+ IN EFI_HANDLE Controller,\r
+ IN EFI_HANDLE Handle\r
+ );\r
+\r
+/**\r
+ Create a path for the I2C device\r
+\r
+ Append the I2C slave path to the I2C master controller path.\r
+\r
+ @param[in] I2cDeviceContext Address of an I2C_DEVICE_CONTEXT structure.\r
+ @param[in] BuildControllerNode Flag to build controller node in device path.\r
+\r
+ @retval EFI_SUCCESS The I2C device path is built successfully.\r
+ @return Others It is failed to built device path.\r
+\r
+**/\r
+EFI_STATUS\r
+I2cBusDevicePathAppend (\r
+ IN I2C_DEVICE_CONTEXT *I2cDeviceContext,\r
+ IN BOOLEAN BuildControllerNode\r
+ );\r
+\r
+/**\r
+ Queue an I2C transaction for execution on the I2C device.\r
+\r
+ This routine must be called at or below TPL_NOTIFY. For synchronous\r
+ requests this routine must be called at or below TPL_CALLBACK.\r
+\r
+ This routine queues an I2C transaction to the I2C controller for\r
+ execution on the I2C bus.\r
+\r
+ When Event is NULL, QueueRequest() operates synchronously and returns\r
+ the I2C completion status as its return value.\r
+\r
+ When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS\r
+ indicating that the asynchronous I2C transaction was queued. The values\r
+ above are returned in the buffer pointed to by I2cStatus upon the\r
+ completion of the I2C transaction when I2cStatus is not NULL.\r
+\r
+ The upper layer driver writer provides the following to the platform\r
+ vendor:\r
+ \r
+ 1. Vendor specific GUID for the I2C part\r
+ 2. Guidance on proper construction of the slave address array when the\r
+ I2C device uses more than one slave address. The I2C bus protocol\r
+ uses the SlaveAddressIndex to perform relative to physical address\r
+ translation to access the blocks of hardware within the I2C device.\r
+\r
+ @param[in] This Pointer to an EFI_I2C_IO_PROTOCOL structure.\r
+ @param[in] SlaveAddressIndex Index value into an array of slave addresses\r
+ for the I2C device. The values in the array\r
+ are specified by the board designer, with the\r
+ third party I2C device driver writer providing\r
+ the slave address order.\r
+\r
+ For devices that have a single slave address,\r
+ this value must be zero. If the I2C device\r
+ uses more than one slave address then the\r
+ third party (upper level) I2C driver writer\r
+ needs to specify the order of entries in the\r
+ slave address array.\r
+\r
+ \ref ThirdPartyI2cDrivers "Third Party I2C\r
+ Drivers" section in I2cMaster.h.\r
+ @param[in] Event Event to signal for asynchronous transactions,\r
+ NULL for synchronous transactions\r
+ @param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure\r
+ describing the I2C transaction\r
+ @param[out] I2cStatus Optional buffer to receive the I2C transaction\r
+ completion status\r
+\r
+ @retval EFI_SUCCESS The asynchronous transaction was successfully\r
+ queued when Event is not NULL.\r
+ @retval EFI_SUCCESS The transaction completed successfully when\r
+ Event is NULL.\r
+ @retval EFI_ABORTED The request did not complete because the driver\r
+ binding Stop() routine was called.\r
+ @retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too\r
+ large.\r
+ @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the\r
+ transaction.\r
+ @retval EFI_INVALID_PARAMETER RequestPacket is NULL\r
+ @retval EFI_NOT_FOUND Reserved bit set in the SlaveAddress parameter\r
+ @retval EFI_NO_MAPPING The EFI_I2C_HOST_PROTOCOL could not set the\r
+ bus configuration required to access this I2C\r
+ device.\r
+ @retval EFI_NO_RESPONSE The I2C device is not responding to the slave\r
+ address selected by SlaveAddressIndex.\r
+ EFI_DEVICE_ERROR will be returned if the\r
+ controller cannot distinguish when the NACK\r
+ occurred.\r
+ @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction\r
+ @retval EFI_UNSUPPORTED The controller does not support the requested\r
+ transaction.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cBusQueueRequest (\r
+ IN CONST EFI_I2C_IO_PROTOCOL *This,\r
+ IN UINTN SlaveAddressIndex,\r
+ IN EFI_EVENT Event OPTIONAL,\r
+ IN EFI_I2C_REQUEST_PACKET *RequestPacket,\r
+ OUT EFI_STATUS *I2cStatus OPTIONAL\r
+ );\r
+\r
+/**\r
+ Tests to see if this driver supports a given controller. If a child device is provided,\r
+ it further tests to see if this driver supports creating a handle for the specified child device.\r
+\r
+ This function checks to see if the driver specified by This supports the device specified by\r
+ ControllerHandle. Drivers will typically use the device path attached to\r
+ ControllerHandle and/or the services from the bus I/O abstraction attached to\r
+ ControllerHandle to determine if the driver supports ControllerHandle. This function\r
+ may be called many times during platform initialization. In order to reduce boot times, the tests\r
+ performed by this function must be very small, and take as little time as possible to execute. This\r
+ function must not change the state of any hardware devices, and this function must be aware that the\r
+ device specified by ControllerHandle may already be managed by the same driver or a\r
+ different driver. This function must match its calls to AllocatePages() with FreePages(),\r
+ AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().\r
+ Since ControllerHandle may have been previously started by the same driver, if a protocol is\r
+ already in the opened state, then it must not be closed with CloseProtocol(). This is required\r
+ to guarantee the state of ControllerHandle is not modified by this function.\r
+\r
+ @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
+ @param[in] ControllerHandle The handle of the controller to test. This handle\r
+ must support a protocol interface that supplies\r
+ an I/O abstraction to the driver.\r
+ @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This\r
+ parameter is ignored by device drivers, and is optional for bus\r
+ drivers. For bus drivers, if this parameter is not NULL, then\r
+ the bus driver must determine if the bus controller specified\r
+ by ControllerHandle and the child controller specified\r
+ by RemainingDevicePath are both supported by this\r
+ bus driver.\r
+\r
+ @retval EFI_SUCCESS The device specified by ControllerHandle and\r
+ RemainingDevicePath is supported by the driver specified by This.\r
+ @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and\r
+ RemainingDevicePath is already being managed by the driver\r
+ specified by This.\r
+ @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and\r
+ RemainingDevicePath is already being managed by a different\r
+ driver or an application that requires exclusive access.\r
+ Currently not implemented.\r
+ @retval EFI_UNSUPPORTED The device specified by ControllerHandle and\r
+ RemainingDevicePath is not supported by the driver specified by This.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cBusDriverSupported (\r
+ IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
+ IN EFI_HANDLE Controller,\r
+ IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
+ );\r
+\r
+/**\r
+ Starts a device controller or a bus controller.\r
+\r
+ The Start() function is designed to be invoked from the EFI boot service ConnectController().\r
+ As a result, much of the error checking on the parameters to Start() has been moved into this\r
+ common boot service. It is legal to call Start() from other locations,\r
+ but the following calling restrictions must be followed or the system behavior will not be deterministic.\r
+ 1. ControllerHandle must be a valid EFI_HANDLE.\r
+ 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned\r
+ EFI_DEVICE_PATH_PROTOCOL.\r
+ 3. Prior to calling Start(), the Supported() function for the driver specified by This must\r
+ have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.\r
+\r
+ @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
+ @param[in] ControllerHandle The handle of the controller to start. This handle\r
+ must support a protocol interface that supplies\r
+ an I/O abstraction to the driver.\r
+ @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This\r
+ parameter is ignored by device drivers, and is optional for bus\r
+ drivers. For a bus driver, if this parameter is NULL, then handles\r
+ for all the children of Controller are created by this driver.\r
+ If this parameter is not NULL and the first Device Path Node is\r
+ not the End of Device Path Node, then only the handle for the\r
+ child device specified by the first Device Path Node of\r
+ RemainingDevicePath is created by this driver.\r
+ If the first Device Path Node of RemainingDevicePath is\r
+ the End of Device Path Node, no child handle is created by this\r
+ driver.\r
+\r
+ @retval EFI_SUCCESS The device was started.\r
+ @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.\r
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.\r
+ @retval Others The driver failded to start the device.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cBusDriverStart (\r
+ IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
+ IN EFI_HANDLE Controller,\r
+ IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
+ );\r
+\r
+/**\r
+ Stops a device controller or a bus controller.\r
+\r
+ The Stop() function is designed to be invoked from the EFI boot service DisconnectController().\r
+ As a result, much of the error checking on the parameters to Stop() has been moved\r
+ into this common boot service. It is legal to call Stop() from other locations,\r
+ but the following calling restrictions must be followed or the system behavior will not be deterministic.\r
+ 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this\r
+ same driver's Start() function.\r
+ 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid\r
+ EFI_HANDLE. In addition, all of these handles must have been created in this driver's\r
+ Start() function, and the Start() function must have called OpenProtocol() on\r
+ ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.\r
+\r
+ @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
+ @param[in] ControllerHandle A handle to the device being stopped. The handle must\r
+ support a bus specific I/O protocol for the driver\r
+ to use to stop the device.\r
+ @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.\r
+ @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL\r
+ if NumberOfChildren is 0.\r
+\r
+ @retval EFI_SUCCESS The device was stopped.\r
+ @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cBusDriverStop (\r
+ IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
+ IN EFI_HANDLE Controller,\r
+ IN UINTN NumberOfChildren,\r
+ IN EFI_HANDLE *ChildHandleBuffer\r
+ );\r
+\r
+/**\r
+ Retrieves a Unicode string that is the user readable name of the driver.\r
+\r
+ This function retrieves the user readable name of a driver in the form of a\r
+ Unicode string. If the driver specified by This has a user readable name in\r
+ the language specified by Language, then a pointer to the driver name is\r
+ returned in DriverName, and EFI_SUCCESS is returned. If the driver specified\r
+ by This does not support the language specified by Language,\r
+ then EFI_UNSUPPORTED is returned.\r
+\r
+ @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or\r
+ EFI_COMPONENT_NAME_PROTOCOL instance.\r
+\r
+ @param Language[in] A pointer to a Null-terminated ASCII string\r
+ array indicating the language. This is the\r
+ language of the driver name that the caller is\r
+ requesting, and it must match one of the\r
+ languages specified in SupportedLanguages. The\r
+ number of languages supported by a driver is up\r
+ to the driver writer. Language is specified\r
+ in RFC 4646 or ISO 639-2 language code format.\r
+\r
+ @param DriverName[out] A pointer to the Unicode string to return.\r
+ This Unicode string is the name of the\r
+ driver specified by This in the language\r
+ specified by Language.\r
+\r
+ @retval EFI_SUCCESS The Unicode string for the Driver specified by\r
+ This and the language specified by Language was\r
+ returned in DriverName.\r
+\r
+ @retval EFI_INVALID_PARAMETER Language is NULL.\r
+\r
+ @retval EFI_INVALID_PARAMETER DriverName is NULL.\r
+\r
+ @retval EFI_UNSUPPORTED The driver specified by This does not support\r
+ the language specified by Language.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cBusComponentNameGetDriverName (\r
+ IN EFI_COMPONENT_NAME2_PROTOCOL *This,\r
+ IN CHAR8 *Language,\r
+ OUT CHAR16 **DriverName\r
+ );\r
+ \r
+/**\r
+ Retrieves a Unicode string that is the user readable name of the controller\r
+ that is being managed by a driver.\r
+\r
+ This function retrieves the user readable name of the controller specified by\r
+ ControllerHandle and ChildHandle in the form of a Unicode string. If the\r
+ driver specified by This has a user readable name in the language specified by\r
+ Language, then a pointer to the controller name is returned in ControllerName,\r
+ and EFI_SUCCESS is returned. If the driver specified by This is not currently\r
+ managing the controller specified by ControllerHandle and ChildHandle,\r
+ then EFI_UNSUPPORTED is returned. If the driver specified by This does not\r
+ support the language specified by Language, then EFI_UNSUPPORTED is returned.\r
+\r
+ @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or\r
+ EFI_COMPONENT_NAME_PROTOCOL instance.\r
+\r
+ @param ControllerHandle[in] The handle of a controller that the driver\r
+ specified by This is managing. This handle\r
+ specifies the controller whose name is to be\r
+ returned.\r
+\r
+ @param ChildHandle[in] The handle of the child controller to retrieve\r
+ the name of. This is an optional parameter that\r
+ may be NULL. It will be NULL for device\r
+ drivers. It will also be NULL for a bus drivers\r
+ that wish to retrieve the name of the bus\r
+ controller. It will not be NULL for a bus\r
+ driver that wishes to retrieve the name of a\r
+ child controller.\r
+\r
+ @param Language[in] A pointer to a Null-terminated ASCII string\r
+ array indicating the language. This is the\r
+ language of the driver name that the caller is\r
+ requesting, and it must match one of the\r
+ languages specified in SupportedLanguages. The\r
+ number of languages supported by a driver is up\r
+ to the driver writer. Language is specified in\r
+ RFC 4646 or ISO 639-2 language code format.\r
+\r
+ @param ControllerName[out] A pointer to the Unicode string to return.\r
+ This Unicode string is the name of the\r
+ controller specified by ControllerHandle and\r
+ ChildHandle in the language specified by\r
+ Language from the point of view of the driver\r
+ specified by This.\r
+\r
+ @retval EFI_SUCCESS The Unicode string for the user readable name in\r
+ the language specified by Language for the\r
+ driver specified by This was returned in\r
+ DriverName.\r
+\r
+ @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.\r
+\r
+ @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid\r
+ EFI_HANDLE.\r
+\r
+ @retval EFI_INVALID_PARAMETER Language is NULL.\r
+\r
+ @retval EFI_INVALID_PARAMETER ControllerName is NULL.\r
+\r
+ @retval EFI_UNSUPPORTED The driver specified by This is not currently\r
+ managing the controller specified by\r
+ ControllerHandle and ChildHandle.\r
+\r
+ @retval EFI_UNSUPPORTED The driver specified by This does not support\r
+ the language specified by Language.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cBusComponentNameGetControllerName (\r
+ IN EFI_COMPONENT_NAME2_PROTOCOL *This,\r
+ IN EFI_HANDLE ControllerHandle,\r
+ IN EFI_HANDLE ChildHandle OPTIONAL,\r
+ IN CHAR8 *Language,\r
+ OUT CHAR16 **ControllerName\r
+ );\r
+\r
+/**\r
+ The user entry point for the I2C bus module. The user code starts with\r
+ this function.\r
+\r
+ @param[in] ImageHandle The firmware allocated handle for the EFI image.\r
+ @param[in] SystemTable A pointer to the EFI System Table.\r
+\r
+ @retval EFI_SUCCESS The entry point is executed successfully.\r
+ @retval other Some error occurs when executing this entry point.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+InitializeI2cBus(\r
+ IN EFI_HANDLE ImageHandle,\r
+ IN EFI_SYSTEM_TABLE *SystemTable\r
+ );\r
+\r
+/**\r
+ This is the unload handle for I2C bus module.\r
+\r
+ Disconnect the driver specified by ImageHandle from all the devices in the handle database.\r
+ Uninstall all the protocols installed in the driver entry point.\r
+\r
+ @param[in] ImageHandle The drivers' driver image.\r
+\r
+ @retval EFI_SUCCESS The image is unloaded.\r
+ @retval Others Failed to unload the image.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cBusUnload (\r
+ IN EFI_HANDLE ImageHandle\r
+ );\r
+\r
+/**\r
+ Release all the resources allocated for the I2C device.\r
+\r
+ This function releases all the resources allocated for the I2C device.\r
+\r
+ @param I2cDeviceContext The I2C child device involved for the operation.\r
+\r
+**/\r
+VOID\r
+ReleaseI2cDeviceContext (\r
+ IN I2C_DEVICE_CONTEXT *I2cDeviceContext\r
+ );\r
+\r
+/**\r
+ Complete the current request\r
+\r
+ @param[in] I2cHost Address of an I2C_HOST_CONTEXT structure.\r
+ @param[in] Status Status of the I<sub>2</sub>C operation.\r
+\r
+ @return This routine returns the input status value.\r
+\r
+**/\r
+EFI_STATUS\r
+I2cHostRequestComplete (\r
+ I2C_HOST_CONTEXT *I2cHost,\r
+ EFI_STATUS Status\r
+ );\r
+\r
+/**\r
+ Enable access to the I2C bus configuration\r
+\r
+ @param[in] I2cHostContext Address of an I2C_HOST_CONTEXT structure\r
+\r
+ @retval EFI_SUCCESS The operation completed successfully.\r
+ @retval EFI_ABORTED The request did not complete because the driver\r
+ was shutdown.\r
+ @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.\r
+ @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.\r
+ This could indicate the slave device is not present.\r
+ @retval EFI_INVALID_PARAMETER RequestPacket is NULL\r
+ @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value\r
+ @retval EFI_NO_RESPONSE The I2C device is not responding to the\r
+ slave address. EFI_DEVICE_ERROR may also be\r
+ returned if the controller can not distinguish\r
+ when the NACK occurred.\r
+ @retval EFI_NOT_FOUND I2C slave address exceeds maximum address\r
+ @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for\r
+ the event and then read status.\r
+ @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation\r
+ @retval EFI_TIMEOUT The transaction did not complete within an internally\r
+ specified timeout period.\r
+\r
+**/\r
+EFI_STATUS\r
+I2cHostRequestEnable (\r
+ I2C_HOST_CONTEXT *I2cHost\r
+ );\r
+\r
+/**\r
+ Tests to see if this driver supports a given controller. If a child device is provided,\r
+ it further tests to see if this driver supports creating a handle for the specified child device.\r
+\r
+ This function checks to see if the driver specified by This supports the device specified by\r
+ ControllerHandle. Drivers will typically use the device path attached to\r
+ ControllerHandle and/or the services from the bus I/O abstraction attached to\r
+ ControllerHandle to determine if the driver supports ControllerHandle. This function\r
+ may be called many times during platform initialization. In order to reduce boot times, the tests\r
+ performed by this function must be very small, and take as little time as possible to execute. This\r
+ function must not change the state of any hardware devices, and this function must be aware that the\r
+ device specified by ControllerHandle may already be managed by the same driver or a\r
+ different driver. This function must match its calls to AllocatePages() with FreePages(),\r
+ AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().\r
+ Since ControllerHandle may have been previously started by the same driver, if a protocol is\r
+ already in the opened state, then it must not be closed with CloseProtocol(). This is required\r
+ to guarantee the state of ControllerHandle is not modified by this function.\r
+\r
+ @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
+ @param[in] ControllerHandle The handle of the controller to test. This handle\r
+ must support a protocol interface that supplies\r
+ an I/O abstraction to the driver.\r
+ @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This\r
+ parameter is ignored by device drivers, and is optional for bus\r
+ drivers. For bus drivers, if this parameter is not NULL, then\r
+ the bus driver must determine if the bus controller specified\r
+ by ControllerHandle and the child controller specified\r
+ by RemainingDevicePath are both supported by this\r
+ bus driver.\r
+\r
+ @retval EFI_SUCCESS The device specified by ControllerHandle and\r
+ RemainingDevicePath is supported by the driver specified by This.\r
+ @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and\r
+ RemainingDevicePath is already being managed by the driver\r
+ specified by This.\r
+ @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and\r
+ RemainingDevicePath is already being managed by a different\r
+ driver or an application that requires exclusive access.\r
+ Currently not implemented.\r
+ @retval EFI_UNSUPPORTED The device specified by ControllerHandle and\r
+ RemainingDevicePath is not supported by the driver specified by This.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cHostDriverSupported (\r
+ IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
+ IN EFI_HANDLE Controller,\r
+ IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
+ );\r
+\r
+/**\r
+ Starts a device controller or a bus controller.\r
+\r
+ The Start() function is designed to be invoked from the EFI boot service ConnectController().\r
+ As a result, much of the error checking on the parameters to Start() has been moved into this\r
+ common boot service. It is legal to call Start() from other locations,\r
+ but the following calling restrictions must be followed, or the system behavior will not be deterministic.\r
+ 1. ControllerHandle must be a valid EFI_HANDLE.\r
+ 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned\r
+ EFI_DEVICE_PATH_PROTOCOL.\r
+ 3. Prior to calling Start(), the Supported() function for the driver specified by This must\r
+ have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.\r
+\r
+ @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
+ @param[in] ControllerHandle The handle of the controller to start. This handle\r
+ must support a protocol interface that supplies\r
+ an I/O abstraction to the driver.\r
+ @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This\r
+ parameter is ignored by device drivers, and is optional for bus\r
+ drivers. For a bus driver, if this parameter is NULL, then handles\r
+ for all the children of Controller are created by this driver.\r
+ If this parameter is not NULL and the first Device Path Node is\r
+ not the End of Device Path Node, then only the handle for the\r
+ child device specified by the first Device Path Node of\r
+ RemainingDevicePath is created by this driver.\r
+ If the first Device Path Node of RemainingDevicePath is\r
+ the End of Device Path Node, no child handle is created by this\r
+ driver.\r
+\r
+ @retval EFI_SUCCESS The device was started.\r
+ @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.\r
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.\r
+ @retval Others The driver failded to start the device.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cHostDriverStart (\r
+ IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
+ IN EFI_HANDLE Controller,\r
+ IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
+ );\r
+ \r
+/**\r
+ Stops a device controller or a bus controller.\r
+\r
+ The Stop() function is designed to be invoked from the EFI boot service DisconnectController().\r
+ As a result, much of the error checking on the parameters to Stop() has been moved\r
+ into this common boot service. It is legal to call Stop() from other locations,\r
+ but the following calling restrictions must be followed, or the system behavior will not be deterministic.\r
+ 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this\r
+ same driver's Start() function.\r
+ 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid\r
+ EFI_HANDLE. In addition, all of these handles must have been created in this driver's\r
+ Start() function, and the Start() function must have called OpenProtocol() on\r
+ ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.\r
+\r
+ @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.\r
+ @param[in] ControllerHandle A handle to the device being stopped. The handle must\r
+ support a bus specific I/O protocol for the driver\r
+ to use to stop the device.\r
+ @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.\r
+ @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL\r
+ if NumberOfChildren is 0.\r
+\r
+ @retval EFI_SUCCESS The device was stopped.\r
+ @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cHostDriverStop (\r
+ IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
+ IN EFI_HANDLE Controller,\r
+ IN UINTN NumberOfChildren,\r
+ IN EFI_HANDLE *ChildHandleBuffer\r
+ );\r
+\r
+/**\r
+ Retrieves a Unicode string that is the user readable name of the driver.\r
+\r
+ This function retrieves the user readable name of a driver in the form of a\r
+ Unicode string. If the driver specified by This has a user readable name in\r
+ the language specified by Language, then a pointer to the driver name is\r
+ returned in DriverName, and EFI_SUCCESS is returned. If the driver specified\r
+ by This does not support the language specified by Language,\r
+ then EFI_UNSUPPORTED is returned.\r
+\r
+ @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or\r
+ EFI_COMPONENT_NAME_PROTOCOL instance.\r
+\r
+ @param Language[in] A pointer to a Null-terminated ASCII string\r
+ array indicating the language. This is the\r
+ language of the driver name that the caller is\r
+ requesting, and it must match one of the\r
+ languages specified in SupportedLanguages. The\r
+ number of languages supported by a driver is up\r
+ to the driver writer. Language is specified\r
+ in RFC 4646 or ISO 639-2 language code format.\r
+\r
+ @param DriverName[out] A pointer to the Unicode string to return.\r
+ This Unicode string is the name of the\r
+ driver specified by This in the language\r
+ specified by Language.\r
+\r
+ @retval EFI_SUCCESS The Unicode string for the Driver specified by\r
+ This and the language specified by Language was\r
+ returned in DriverName.\r
+\r
+ @retval EFI_INVALID_PARAMETER Language is NULL.\r
+\r
+ @retval EFI_INVALID_PARAMETER DriverName is NULL.\r
+\r
+ @retval EFI_UNSUPPORTED The driver specified by This does not support\r
+ the language specified by Language.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cHostComponentNameGetDriverName (\r
+ IN EFI_COMPONENT_NAME2_PROTOCOL *This,\r
+ IN CHAR8 *Language,\r
+ OUT CHAR16 **DriverName\r
+ );\r
+ \r
+/**\r
+ Retrieves a Unicode string that is the user readable name of the controller\r
+ that is being managed by a driver.\r
+\r
+ This function retrieves the user readable name of the controller specified by\r
+ ControllerHandle and ChildHandle in the form of a Unicode string. If the\r
+ driver specified by This has a user readable name in the language specified by\r
+ Language, then a pointer to the controller name is returned in ControllerName,\r
+ and EFI_SUCCESS is returned. If the driver specified by This is not currently\r
+ managing the controller specified by ControllerHandle and ChildHandle,\r
+ then EFI_UNSUPPORTED is returned. If the driver specified by This does not\r
+ support the language specified by Language, then EFI_UNSUPPORTED is returned.\r
+\r
+ @param This[in] A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or\r
+ EFI_COMPONENT_NAME_PROTOCOL instance.\r
+\r
+ @param ControllerHandle[in] The handle of a controller that the driver\r
+ specified by This is managing. This handle\r
+ specifies the controller whose name is to be\r
+ returned.\r
+\r
+ @param ChildHandle[in] The handle of the child controller to retrieve\r
+ the name of. This is an optional parameter that\r
+ may be NULL. It will be NULL for device\r
+ drivers. It will also be NULL for a bus drivers\r
+ that wish to retrieve the name of the bus\r
+ controller. It will not be NULL for a bus\r
+ driver that wishes to retrieve the name of a\r
+ child controller.\r
+\r
+ @param Language[in] A pointer to a Null-terminated ASCII string\r
+ array indicating the language. This is the\r
+ language of the driver name that the caller is\r
+ requesting, and it must match one of the\r
+ languages specified in SupportedLanguages. The\r
+ number of languages supported by a driver is up\r
+ to the driver writer. Language is specified in\r
+ RFC 4646 or ISO 639-2 language code format.\r
+\r
+ @param ControllerName[out] A pointer to the Unicode string to return.\r
+ This Unicode string is the name of the\r
+ controller specified by ControllerHandle and\r
+ ChildHandle in the language specified by\r
+ Language from the point of view of the driver\r
+ specified by This.\r
+\r
+ @retval EFI_SUCCESS The Unicode string for the user readable name in\r
+ the language specified by Language for the\r
+ driver specified by This was returned in\r
+ DriverName.\r
+\r
+ @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.\r
+\r
+ @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid\r
+ EFI_HANDLE.\r
+\r
+ @retval EFI_INVALID_PARAMETER Language is NULL.\r
+\r
+ @retval EFI_INVALID_PARAMETER ControllerName is NULL.\r
+\r
+ @retval EFI_UNSUPPORTED The driver specified by This is not currently\r
+ managing the controller specified by\r
+ ControllerHandle and ChildHandle.\r
+\r
+ @retval EFI_UNSUPPORTED The driver specified by This does not support\r
+ the language specified by Language.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cHostComponentNameGetControllerName (\r
+ IN EFI_COMPONENT_NAME2_PROTOCOL *This,\r
+ IN EFI_HANDLE ControllerHandle,\r
+ IN EFI_HANDLE ChildHandle OPTIONAL,\r
+ IN CHAR8 *Language,\r
+ OUT CHAR16 **ControllerName\r
+ );\r
+\r
+/**\r
+ Handle the bus available event\r
+\r
+ This routine is called at TPL_I2C_SYNC.\r
+\r
+ @param[in] Event Address of an EFI_EVENT handle\r
+ @param[in] Context Address of an I2C_HOST_CONTEXT structure\r
+\r
+**/\r
+VOID\r
+EFIAPI\r
+I2cHostRequestCompleteEvent (\r
+ IN EFI_EVENT Event,\r
+ IN VOID *Context\r
+ );\r
+\r
+/**\r
+ Handle the I2C bus configuration available event\r
+\r
+ This routine is called at TPL_I2C_SYNC.\r
+\r
+ @param[in] Event Address of an EFI_EVENT handle\r
+ @param[in] Context Address of an I2C_HOST_CONTEXT structure\r
+\r
+**/\r
+VOID\r
+EFIAPI\r
+I2cHostI2cBusConfigurationAvailable (\r
+ IN EFI_EVENT Event,\r
+ IN VOID *Context\r
+ );\r
+\r
+/**\r
+ Queue an I2C operation for execution on the I2C controller.\r
+\r
+ This routine must be called at or below TPL_NOTIFY. For synchronous\r
+ requests this routine must be called at or below TPL_CALLBACK.\r
+\r
+ N.B. The typical consumers of this API are the I2C bus driver and\r
+ on rare occasions the I2C test application. Extreme care must be\r
+ taken by other consumers of this API to prevent confusing the\r
+ third party I2C drivers due to a state change at the I2C device\r
+ which the third party I2C drivers did not initiate. I2C platform\r
+ drivers may use this API within these guidelines.\r
+\r
+ This layer uses the concept of I2C bus configurations to describe\r
+ the I2C bus. An I2C bus configuration is defined as a unique\r
+ setting of the multiplexers and switches in the I2C bus which\r
+ enable access to one or more I2C devices. When using a switch\r
+ to divide a bus, due to speed differences, the I2C platform layer\r
+ would define an I2C bus configuration for the I2C devices on each\r
+ side of the switch. When using a multiplexer, the I2C platform\r
+ layer defines an I2C bus configuration for each of the selector\r
+ values required to control the multiplexer. See Figure 1 in the\r
+ <a href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I<sup>2</sup>C\r
+ Specification</a> for a complex I2C bus configuration.\r
+\r
+ The I2C host driver processes all operations in FIFO order. Prior to\r
+ performing the operation, the I2C host driver calls the I2C platform\r
+ driver to reconfigure the switches and multiplexers in the I2C bus\r
+ enabling access to the specified I2C device. The I2C platform driver\r
+ also selects the maximum bus speed for the device. After the I2C bus\r
+ is configured, the I2C host driver calls the I2C port driver to\r
+ initialize the I2C controller and start the I2C operation.\r
+\r
+ @param[in] This Address of an EFI_I2C_HOST_PROTOCOL instance.\r
+ @param[in] I2cBusConfiguration I2C bus configuration to access the I2C\r
+ device.\r
+ @param[in] SlaveAddress Address of the device on the I2C bus.\r
+ @param[in] Event Event to set for asynchronous operations,\r
+ NULL for synchronous operations\r
+ @param[in] RequestPacket Address of an EFI_I2C_REQUEST_PACKET\r
+ structure describing the I2C operation\r
+ @param[out] I2cStatus Optional buffer to receive the I2C operation\r
+ completion status\r
+\r
+ @retval EFI_SUCCESS The operation completed successfully.\r
+ @retval EFI_ABORTED The request did not complete because the driver\r
+ was shutdown.\r
+ @retval EFI_BAD_BUFFER_SIZE The WriteBytes or ReadBytes buffer size is too large.\r
+ @retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the operation.\r
+ This could indicate the slave device is not present.\r
+ @retval EFI_INVALID_PARAMETER RequestPacket is NULL\r
+ @retval EFI_INVALID_PARAMETER TPL is too high\r
+ @retval EFI_NO_MAPPING Invalid I2cBusConfiguration value\r
+ @retval EFI_NO_RESPONSE The I2C device is not responding to the\r
+ slave address. EFI_DEVICE_ERROR may also be\r
+ returned if the controller can not distinguish\r
+ when the NACK occurred.\r
+ @retval EFI_NOT_FOUND I2C slave address exceeds maximum address\r
+ @retval EFI_NOT_READY I2C bus is busy or operation pending, wait for\r
+ the event and then read status pointed to by\r
+ the request packet.\r
+ @retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C operation\r
+ @retval EFI_TIMEOUT The transaction did not complete within an internally\r
+ specified timeout period.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cHostQueueRequest (\r
+ IN CONST EFI_I2C_HOST_PROTOCOL *This,\r
+ IN UINTN I2cBusConfiguration,\r
+ IN UINTN SlaveAddress,\r
+ IN EFI_EVENT Event OPTIONAL,\r
+ IN EFI_I2C_REQUEST_PACKET *RequestPacket,\r
+ OUT EFI_STATUS *I2cStatus OPTIONAL\r
+ );\r
+\r
+/**\r
+ The user Entry Point for I2C host module. The user code starts with this function.\r
+\r
+ @param[in] ImageHandle The firmware allocated handle for the EFI image.\r
+ @param[in] SystemTable A pointer to the EFI System Table.\r
+\r
+ @retval EFI_SUCCESS The entry point is executed successfully.\r
+ @retval other Some error occurs when executing this entry point.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+InitializeI2cHost(\r
+ IN EFI_HANDLE ImageHandle,\r
+ IN EFI_SYSTEM_TABLE *SystemTable\r
+ );\r
+\r
+/**\r
+ This is the unload handle for I2C host module.\r
+\r
+ Disconnect the driver specified by ImageHandle from all the devices in the handle database.\r
+ Uninstall all the protocols installed in the driver entry point.\r
+\r
+ @param[in] ImageHandle The drivers' driver image.\r
+\r
+ @retval EFI_SUCCESS The image is unloaded.\r
+ @retval Others Failed to unload the image.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+I2cHostUnload (\r
+ IN EFI_HANDLE ImageHandle\r
+ );\r
+\r
+#endif // __I2C_DXE_H__\r
projects / mirror_edk2.git / blobdiff