--- /dev/null
+/** @file\r
+ I2C bus interface\r
+\r
+ This layer provides I/O access to an I2C device.\r
+\r
+ Copyright (c) 2012, Intel Corporation\r
+ All rights reserved. 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_BUS_H__\r
+#define __I2C_BUS_H__\r
+\r
+#include <Protocol/I2cHostMcg.h>\r
+\r
+///\r
+/// I2C bus protocol\r
+///\r
+typedef struct _EFI_I2C_BUS_PROTOCOL EFI_I2C_BUS_PROTOCOL;\r
+\r
+\r
+/**\r
+ Perform an I2C operation on the 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
+ N.B. The typical consumers of this API are the third party I2C\r
+ drivers. Extreme care must be taken by other consumers of this\r
+ API to prevent confusing the third party I2C drivers due to a\r
+ state change at the I2C device which the third party I2C drivers\r
+ did not initiate. I2C platform drivers may use this API within\r
+ these guidelines.\r
+\r
+ This routine queues an operation to the I2C controller for execution\r
+ on the I2C bus.\r
+\r
+ As an upper layer driver writer, the following need to be provided\r
+ to the platform vendor:\r
+\r
+ 1. ACPI CID value or string - this is used to connect the upper layer\r
+ driver to the device.\r
+ 2. Slave address array guidance when the I2C device uses more than one\r
+ slave address. This is used to access the blocks of hardware within\r
+ the I2C device.\r
+\r
+ @param[in] This Address of an EFI_I2C_BUS_PROTOCOL\r
+ structure\r
+ @param[in] SlaveAddressIndex Index into an array of slave addresses for\r
+ the I2C device. The values in the array are\r
+ specified by the board designer, with the\r
+ I2C device driver writer providing the slave\r
+ 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 third\r
+ party (upper level) I2C driver writer needs to\r
+ specify the order of entries in the slave address\r
+ array.\r
+\r
+ \ref ThirdPartyI2cDrivers "Third Party I2C Drivers"\r
+ section in I2cMaster.h.\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_ACCESS_DENIED Invalid SlaveAddressIndex value\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_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
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_I2C_BUS_START_REQUEST) (\r
+ IN CONST EFI_I2C_BUS_PROTOCOL *This,\r
+ IN UINTN SlaveAddressIndex,\r
+ IN EFI_EVENT Event OPTIONAL,\r
+ IN CONST EFI_I2C_REQUEST_PACKET *RequestPacket,\r
+ OUT EFI_STATUS *I2cStatus OPTIONAL\r
+ );\r
+\r
+///\r
+/// The I2C bus protocol enables access to a specific device on the I2C bus.\r
+///\r
+/// Each I2C device is described as an ACPI node (HID, UID and CID) within the\r
+/// platform layer. The I2C bus protocol enumerates the I2C devices in the\r
+/// platform and creates a unique handle and device path for each I2C device.\r
+///\r
+/// I2C slave addressing is abstracted to validate addresses and limit operation\r
+/// to the specified I2C device. The third party providing the I2C device support\r
+/// provides an ordered list of slave addresses for the I2C device to the team\r
+/// building the platform layer. The platform team must preserve the order of the\r
+/// supplied list. SlaveAddressCount is the number of entries in this list or\r
+/// array within the platform layer. The third party device support references\r
+/// a slave address using an index into the list or array in the range of zero\r
+/// to SlaveAddressCount - 1.\r
+///\r
+struct _EFI_I2C_BUS_PROTOCOL {\r
+ ///\r
+ /// Start an I2C operation on the bus\r
+ ///\r
+ EFI_I2C_BUS_START_REQUEST StartRequest;\r
+\r
+ ///\r
+ /// The maximum number of slave addresses for the I2C device. The caller may\r
+ /// validate this value as a check on the platform layer's configuration. Slave\r
+ /// address selection uses an index value in the range of zero to SlaveAddressCount - 1.\r
+ ///\r
+ UINTN SlaveAddressCount;\r
+\r
+ ///\r
+ /// Hardware revision - Matches the ACPI _HRV value\r
+ ///\r
+ /// The HardwareRevision value allows a single driver to support multiple hardware\r
+ /// revisions and implement the necessary workarounds for limitations within the\r
+ /// hardware.\r
+ ///\r
+ UINT32 HardwareRevision;\r
+\r
+ ///\r
+ /// The maximum number of bytes the I2C host controller\r
+ /// is able to receive from the I2C bus.\r
+ ///\r
+ UINT32 MaximumReceiveBytes;\r
+\r
+ ///\r
+ /// The maximum number of bytes the I2C host controller\r
+ /// is able to send on the I2C bus.\r
+ ///\r
+ UINT32 MaximumTransmitBytes;\r
+\r
+ ///\r
+ /// The maximum number of bytes in the I2C bus transaction.\r
+ ///\r
+ UINT32 MaximumTotalBytes;\r
+};\r
+\r
+///\r
+/// GUID for the I2C bus protocol\r
+///\r
+extern EFI_GUID gEfiI2cBusProtocolGuid;\r
+\r
+#endif // __I2C_BUS_H__\r
projects / mirror_edk2.git / blobdiff