+++ /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. All rights reserved.\r
- SPDX-License-Identifier: BSD-2-Clause-Patent\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