MdePkg/Include/Protocol/I2cIo.h - edk2 - Git at Google

 /** @file
   I2C I/O Protocol as defined in the PI 1.3 specification.

   The EFI I2C I/O protocol enables the user to manipulate a single
   I2C device independent of the host controller and I2C design.

   Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
   SPDX-License-Identifier: BSD-2-Clause-Patent

   @par Revision Reference:
   This protocol is from PI Version 1.3.

 **/

 #ifndef __I2C_IO_H__
 #define __I2C_IO_H__

 #include <Pi/PiI2c.h>

 #define EFI_I2C_IO_PROTOCOL_GUID  { 0xb60a3e6b, 0x18c4, 0x46e5, { 0xa2, 0x9a, 0xc9, 0xa1, 0x06, 0x65, 0xa2, 0x8e }}

 ///
 /// I2C I/O protocol
 ///
 /// The I2C IO protocol enables access to a specific device on the I2C
 /// bus.
 ///
 /// Each I2C device is identified uniquely in the system by the tuple
 /// DeviceGuid:DeviceIndex.  The DeviceGuid represents the manufacture
 /// and part number and is provided by the silicon vendor or the third
 /// party I2C device driver writer.  The DeviceIndex identifies the part
 /// within the system by using a unique number and is created by the
 /// board designer or the writer of the EFI_I2C_ENUMERATE_PROTOCOL.
 ///
 /// I2C slave addressing is abstracted to validate addresses and limit
 /// operation to the specified I2C device.  The third party providing
 /// the I2C device support provides an ordered list of slave addresses
 /// for the I2C device required to implement the EFI_I2C_ENUMERATE_PROTOCOL.
 /// The order of the list must be preserved.
 ///
 typedef struct _EFI_I2C_IO_PROTOCOL EFI_I2C_IO_PROTOCOL;

 /**
   Queue an I2C transaction for execution on the I2C device.

   This routine must be called at or below TPL_NOTIFY.  For synchronous
   requests this routine must be called at or below TPL_CALLBACK.

   This routine queues an I2C transaction to the I2C controller for
   execution on the I2C bus.

   When Event is NULL, QueueRequest() operates synchronously and returns
   the I2C completion status as its return value.

   When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS
   indicating that the asynchronous I2C transaction was queued.  The values
   above are returned in the buffer pointed to by I2cStatus upon the
   completion of the I2C transaction when I2cStatus is not NULL.

   The upper layer driver writer provides the following to the platform
   vendor:

   1.  Vendor specific GUID for the I2C part
   2.  Guidance on proper construction of the slave address array when the
       I2C device uses more than one slave address.  The I2C bus protocol
       uses the SlaveAddressIndex to perform relative to physical address
       translation to access the blocks of hardware within the I2C device.

   @param[in] This               Pointer to an EFI_I2C_IO_PROTOCOL structure.
   @param[in] SlaveAddressIndex  Index value into an array of slave addresses
                                 for the I2C device.  The values in the array
                                 are specified by the board designer, with the
                                 third party I2C device driver writer providing
                                 the slave address order.

                                 For devices that have a single slave address,
                                 this value must be zero.  If the I2C device
                                 uses more than one slave address then the
                                 third party (upper level) I2C driver writer
                                 needs to specify the order of entries in the
                                 slave address array.

                                 \ref ThirdPartyI2cDrivers "Third Party I2C
                                 Drivers" section in I2cMaster.h.
   @param[in] Event              Event to signal for asynchronous transactions,
                                 NULL for synchronous transactions
   @param[in] RequestPacket      Pointer to an EFI_I2C_REQUEST_PACKET structure
                                 describing the I2C transaction
   @param[out] I2cStatus         Optional buffer to receive the I2C transaction
                                 completion status

   @retval EFI_SUCCESS           The asynchronous transaction was successfully
                                 queued when Event is not NULL.
   @retval EFI_SUCCESS           The transaction completed successfully when
                                 Event is NULL.
   @retval EFI_BAD_BUFFER_SIZE   The RequestPacket->LengthInBytes value is too
                                 large.
   @retval EFI_DEVICE_ERROR      There was an I2C error (NACK) during the
                                 transaction.
   @retval EFI_INVALID_PARAMETER RequestPacket is NULL.
   @retval EFI_NO_MAPPING        The EFI_I2C_HOST_PROTOCOL could not set the
                                 bus configuration required to access this I2C
                                 device.
   @retval EFI_NO_RESPONSE       The I2C device is not responding to the slave
                                 address selected by SlaveAddressIndex.
                                 EFI_DEVICE_ERROR will be returned if the
                                 controller cannot distinguish when the NACK
                                 occurred.
   @retval EFI_OUT_OF_RESOURCES  Insufficient memory for I2C transaction
   @retval EFI_UNSUPPORTED       The controller does not support the requested
                                 transaction.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST)(
   IN CONST EFI_I2C_IO_PROTOCOL  *This,
   IN UINTN                      SlaveAddressIndex,
   IN EFI_EVENT                  Event      OPTIONAL,
   IN EFI_I2C_REQUEST_PACKET     *RequestPacket,
   OUT EFI_STATUS                *I2cStatus OPTIONAL
   );

 ///
 /// I2C I/O protocol
 ///
 struct _EFI_I2C_IO_PROTOCOL {
   ///
   /// Queue an I2C transaction for execution on the I2C device.
   ///
   EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST        QueueRequest;

   ///
   /// Unique value assigned by the silicon manufacture or the third
   /// party I2C driver writer for the I2C part.  This value logically
   /// combines both the manufacture name and the I2C part number into
   /// a single value specified as a GUID.
   ///
   CONST EFI_GUID                           *DeviceGuid;

   ///
   /// Unique ID of the I2C part within the system
   ///
   UINT32                                   DeviceIndex;

   ///
   /// Hardware revision - ACPI _HRV value.  See the Advanced Configuration
   /// and Power Interface Specification, Revision 5.0  for the field format
   /// and the Plug and play support for I2C web-page for restriction on values.
   ///
   UINT32                                   HardwareRevision;

   ///
   /// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing
   /// the capabilities of the I2C host controller.
   ///
   CONST EFI_I2C_CONTROLLER_CAPABILITIES    *I2cControllerCapabilities;
 };

 ///
 /// Reference to variable defined in the .DEC file
 ///
 extern EFI_GUID  gEfiI2cIoProtocolGuid;

 #endif //  __I2C_IO_H__
	/** @file
	I2C I/O Protocol as defined in the PI 1.3 specification.

	The EFI I2C I/O protocol enables the user to manipulate a single
	I2C device independent of the host controller and I2C design.

	Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>
	SPDX-License-Identifier: BSD-2-Clause-Patent

	@par Revision Reference:
	This protocol is from PI Version 1.3.

	**/

	#ifndef __I2C_IO_H__
	#define __I2C_IO_H__

	#include <Pi/PiI2c.h>

	#define EFI_I2C_IO_PROTOCOL_GUID { 0xb60a3e6b, 0x18c4, 0x46e5, { 0xa2, 0x9a, 0xc9, 0xa1, 0x06, 0x65, 0xa2, 0x8e }}

	///
	/// I2C I/O protocol
	///
	/// The I2C IO protocol enables access to a specific device on the I2C
	/// bus.
	///
	/// Each I2C device is identified uniquely in the system by the tuple
	/// DeviceGuid:DeviceIndex. The DeviceGuid represents the manufacture
	/// and part number and is provided by the silicon vendor or the third
	/// party I2C device driver writer. The DeviceIndex identifies the part
	/// within the system by using a unique number and is created by the
	/// board designer or the writer of the EFI_I2C_ENUMERATE_PROTOCOL.
	///
	/// I2C slave addressing is abstracted to validate addresses and limit
	/// operation to the specified I2C device. The third party providing
	/// the I2C device support provides an ordered list of slave addresses
	/// for the I2C device required to implement the EFI_I2C_ENUMERATE_PROTOCOL.
	/// The order of the list must be preserved.
	///
	typedef struct _EFI_I2C_IO_PROTOCOL EFI_I2C_IO_PROTOCOL;

	/**
	Queue an I2C transaction for execution on the I2C device.

	This routine must be called at or below TPL_NOTIFY. For synchronous
	requests this routine must be called at or below TPL_CALLBACK.

	This routine queues an I2C transaction to the I2C controller for
	execution on the I2C bus.

	When Event is NULL, QueueRequest() operates synchronously and returns
	the I2C completion status as its return value.

	When Event is not NULL, QueueRequest() synchronously returns EFI_SUCCESS
	indicating that the asynchronous I2C transaction was queued. The values
	above are returned in the buffer pointed to by I2cStatus upon the
	completion of the I2C transaction when I2cStatus is not NULL.

	The upper layer driver writer provides the following to the platform
	vendor:

	1. Vendor specific GUID for the I2C part
	2. Guidance on proper construction of the slave address array when the
	I2C device uses more than one slave address. The I2C bus protocol
	uses the SlaveAddressIndex to perform relative to physical address
	translation to access the blocks of hardware within the I2C device.

	@param[in] This Pointer to an EFI_I2C_IO_PROTOCOL structure.
	@param[in] SlaveAddressIndex Index value into an array of slave addresses
	for the I2C device. The values in the array
	are specified by the board designer, with the
	third party I2C device driver writer providing
	the slave address order.

	For devices that have a single slave address,
	this value must be zero. If the I2C device
	uses more than one slave address then the
	third party (upper level) I2C driver writer
	needs to specify the order of entries in the
	slave address array.

	\ref ThirdPartyI2cDrivers "Third Party I2C
	Drivers" section in I2cMaster.h.
	@param[in] Event Event to signal for asynchronous transactions,
	NULL for synchronous transactions
	@param[in] RequestPacket Pointer to an EFI_I2C_REQUEST_PACKET structure
	describing the I2C transaction
	@param[out] I2cStatus Optional buffer to receive the I2C transaction
	completion status

	@retval EFI_SUCCESS The asynchronous transaction was successfully
	queued when Event is not NULL.
	@retval EFI_SUCCESS The transaction completed successfully when
	Event is NULL.
	@retval EFI_BAD_BUFFER_SIZE The RequestPacket->LengthInBytes value is too
	large.
	@retval EFI_DEVICE_ERROR There was an I2C error (NACK) during the
	transaction.
	@retval EFI_INVALID_PARAMETER RequestPacket is NULL.
	@retval EFI_NO_MAPPING The EFI_I2C_HOST_PROTOCOL could not set the
	bus configuration required to access this I2C
	device.
	@retval EFI_NO_RESPONSE The I2C device is not responding to the slave
	address selected by SlaveAddressIndex.
	EFI_DEVICE_ERROR will be returned if the
	controller cannot distinguish when the NACK
	occurred.
	@retval EFI_OUT_OF_RESOURCES Insufficient memory for I2C transaction
	@retval EFI_UNSUPPORTED The controller does not support the requested
	transaction.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST)(
	IN CONST EFI_I2C_IO_PROTOCOL *This,
	IN UINTN SlaveAddressIndex,
	IN EFI_EVENT Event OPTIONAL,
	IN EFI_I2C_REQUEST_PACKET *RequestPacket,
	OUT EFI_STATUS *I2cStatus OPTIONAL
	);

	///
	/// I2C I/O protocol
	///
	struct _EFI_I2C_IO_PROTOCOL {
	///
	/// Queue an I2C transaction for execution on the I2C device.
	///
	EFI_I2C_IO_PROTOCOL_QUEUE_REQUEST QueueRequest;

	///
	/// Unique value assigned by the silicon manufacture or the third
	/// party I2C driver writer for the I2C part. This value logically
	/// combines both the manufacture name and the I2C part number into
	/// a single value specified as a GUID.
	///
	CONST EFI_GUID *DeviceGuid;

	///
	/// Unique ID of the I2C part within the system
	///
	UINT32 DeviceIndex;

	///
	/// Hardware revision - ACPI _HRV value. See the Advanced Configuration
	/// and Power Interface Specification, Revision 5.0 for the field format
	/// and the Plug and play support for I2C web-page for restriction on values.
	///
	UINT32 HardwareRevision;

	///
	/// Pointer to an EFI_I2C_CONTROLLER_CAPABILITIES data structure containing
	/// the capabilities of the I2C host controller.
	///
	CONST EFI_I2C_CONTROLLER_CAPABILITIES *I2cControllerCapabilities;
	};

	///
	/// Reference to variable defined in the .DEC file
	///
	extern EFI_GUID gEfiI2cIoProtocolGuid;

	#endif // __I2C_IO_H__