--- /dev/null
+/** @file\r
+ I2C I/O Protocol as defined in the PI 1.3 specification.\r
+\r
+ The EFI I2C I/O protocol enables the user to manipulate a single \r
+ I2C device independent of the host controller and I2C design.\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
+ @par Revision Reference:\r
+ This protocol is from PI Version 1.3.\r
+\r
+**/\r
+\r
+#ifndef __I2C_IO_H__\r
+#define __I2C_IO_H__\r
+\r
+#include <Pi/PiI2c.h>\r
+\r
+#define EFI_I2C_IO_PROTOCOL_GUID { 0xb60a3e6b, 0x18c4, 0x46e5, { 0xa2, 0x9a, 0xc9, 0xa1, 0x06, 0x65, 0xa2, 0x8e }}\r
+\r
+///\r
+/// I2C I/O protocol\r
+///\r
+/// The I2C IO protocol enables access to a specific device on the I2C\r
+/// bus.\r
+///\r
+/// Each I2C device is identified uniquely in the system by the tuple\r
+/// DeviceGuid:DeviceIndex. The DeviceGuid represents the manufacture\r
+/// and part number and is provided by the silicon vendor or the third\r
+/// party I2C device driver writer. The DeviceIndex identifies the part\r
+/// within the system by using a unique number and is created by the\r
+/// board designer or the writer of the EFI_I2C_ENUMERATE_PROTOCOL.\r
+///\r
+/// I2C slave addressing is abstracted to validate addresses and limit\r
+/// operation to the specified I2C device. The third party providing\r
+/// the I2C device support provides an ordered list of slave addresses\r
+/// for the I2C device required to implement the EFI_I2C_ENUMERATE_PROTOCOL.\r
+/// The order of the list must be preserved.\r
+///\r
+typedef struct _EFI_I2C_IO_PROTOCOL EFI_I2C_IO_PROTOCOL;\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
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST) (\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
+/// I2C I/O protocol\r
+///\r
+struct _EFI_I2C_IO_PROTOCOL {\r
+ ///\r
+ /// Queue an I2C transaction for execution on the I2C device.\r
+ ///\r
+ EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST QueueRequest;\r
+\r
+ ///\r
+ /// Unique value assigned by the silicon manufacture or the third\r
+ /// party I2C driver writer for the I2C part. This value logically\r
+ /// combines both the manufacture name and the I2C part number into\r
+ /// a single value specified as a GUID.\r
+ ///\r
+ CONST EFI_GUID *DeviceGuid;\r
+\r
+ ///\r
+ /// Unique ID of the I2C part within the system\r
+ ///\r
+ UINT32 DeviceIndex;\r
+\r
+ ///\r
+ /// Hardware revision - ACPI _HRV value. See the Advanced Configuration\r
+ /// and Power Interface Specification, Revision 5.0 for the field format\r
+ /// and the Plug and play support for I2C web-page for restriction on values.\r
+ ///\r
+ UINT32 HardwareRevision;\r
+\r
+ ///\r
+ /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing\r
+ /// the capabilities of the I2C host controller.\r
+ ///\r
+ CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities;\r
+};\r
+\r
+///\r
+/// Reference to variable defined in the .DEC file\r
+///\r
+extern EFI_GUID gEfiI2cIoProtocolGuid;\r
+\r
+#endif // __I2C_IO_H__\r
projects / mirror_edk2.git / blobdiff