uefi/linaro-edk2/MdePkg/Include/Protocol/I2cHost.h - device/linaro/hikey960 - Gitiles

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

   This protocol provides callers with the ability to do I/O transactions
   to all of the devices on the I2C bus.

   Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>
   This program and the accompanying materials
   are licensed and made available under the terms and conditions of the BSD License
   which accompanies this distribution.  The full text of the license may be found at
   http://opensource.org/licenses/bsd-license.php

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

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

 **/

 #ifndef __I2C_HOST_H__
 #define __I2C_HOST_H__

 #include <Pi/PiI2c.h>

 #define EFI_I2C_HOST_PROTOCOL_GUID  { 0xa5aab9e3, 0xc727, 0x48cd, { 0x8b, 0xbf, 0x42, 0x72, 0x33, 0x85, 0x49, 0x48 }}

 ///
 /// I2C Host Protocol
 ///
 /// The I2C bus driver uses the services of the EFI_I2C_HOST_PROTOCOL
 /// to produce an instance of the EFI_I2C_IO_PROTOCOL for each I2C
 /// device on an I2C bus.
 ///
 /// The EFI_I2C_HOST_PROTOCOL exposes an asynchronous interface to
 /// callers to perform transactions to any device on the I2C bus.
 /// Internally, the I2C host protocol manages the flow of the I2C
 /// transactions to the host controller, keeping them in FIFO order.
 /// Prior to each transaction, the I2C host protocol ensures that the
 /// switches and multiplexers are properly configured.  The I2C host
 /// protocol then starts the transaction on the host controller using
 /// the EFI_I2C_MASTER_PROTOCOL.
 ///
 typedef struct _EFI_I2C_HOST_PROTOCOL EFI_I2C_HOST_PROTOCOL;


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

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

   The I2C host protocol uses the concept of I2C bus configurations
   to describe the I2C bus.  An I2C bus configuration is defined as
   a unique setting of the multiplexers and switches in the I2C bus
   which enable access to one or more I2C devices.  When using a
   switch to divide a bus, due to bus frequency differences, the
   I2C bus configuration management protocol defines an I2C bus
   configuration for the I2C devices on each side of the switch.
   When using a multiplexer, the I2C bus configuration management
   defines an I2C bus configuration for each of the selector values
   required to control the multiplexer.  See Figure 1 in the I2C -bus
   specification and user manual for a complex I2C bus configuration.

   The I2C host protocol processes all transactions in FIFO order.
   Prior to performing the transaction, the I2C host protocol calls
   EnableI2cBusConfiguration to reconfigure the switches and
   multiplexers in the I2C bus enabling access to the specified I2C
   device.  The EnableI2cBusConfiguration also selects the I2C bus
   frequency for the I2C device.  After the I2C bus is configured,
   the I2C host protocol calls the I2C master protocol to start the
   I2C transaction.

   If the I2C host protocol has pending I2C transactions queued when
   the driver binding Stop() routine is called then the I2C host
   protocol completes all of the pending I2C transactions by returning
   EFI_ABORTED status.  This notifies the upper layers allowing them
   to take corrective action or prepare to stop.

   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 asynchronously 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.

   @param[in] This             Pointer to an EFI_I2C_HOST_PROTOCOL structure.
   @param[in] I2cBusConfiguration  I2C bus configuration to access the I2C
                                   device
   @param[in] SlaveAddress     Address of the device on the I2C bus.  Set
                               the I2C_ADDRESSING_10_BIT when using 10-bit
                               addresses, clear this bit for 7-bit addressing.
                               Bits 0-6 are used for 7-bit I2C slave addresses
                               and bits 0-9 are used for 10-bit I2C slave
                               addresses.
   @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_ABORTED           The request did not complete because the
                                 driver binding Stop() routine was called.
   @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_NOT_FOUND         Reserved bit set in the SlaveAddress parameter
   @retval EFI_NO_MAPPING        Invalid I2cBusConfiguration value
   @retval EFI_NO_RESPONSE       The I2C device is not responding to the slave
                                 address.  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_HOST_PROTOCOL_QUEUE_REQUEST) (
   IN CONST EFI_I2C_HOST_PROTOCOL *This,
   IN UINTN                       I2cBusConfiguration,
   IN UINTN                       SlaveAddress,
   IN EFI_EVENT                   Event      OPTIONAL,
   IN EFI_I2C_REQUEST_PACKET      *RequestPacket,
   OUT EFI_STATUS                 *I2cStatus OPTIONAL
   );

 ///
 /// I2C Host Protocol
 ///
 struct _EFI_I2C_HOST_PROTOCOL {
   ///
   /// Queue an I2C transaction for execution on the I2C bus
   ///
   EFI_I2C_HOST_PROTOCOL_QUEUE_REQUEST     QueueRequest;

   ///
   /// 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 gEfiI2cHostProtocolGuid;

 #endif  //  __I2C_HOST_H__
	/** @file
	I2C Host Protocol as defined in the PI 1.3 specification.

	This protocol provides callers with the ability to do I/O transactions
	to all of the devices on the I2C bus.

	Copyright (c) 2013, Intel Corporation. All rights reserved.<BR>
	This program and the accompanying materials
	are licensed and made available under the terms and conditions of the BSD License
	which accompanies this distribution. The full text of the license may be found at
	http://opensource.org/licenses/bsd-license.php

	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

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

	**/

	#ifndef __I2C_HOST_H__
	#define __I2C_HOST_H__

	#include <Pi/PiI2c.h>

	#define EFI_I2C_HOST_PROTOCOL_GUID { 0xa5aab9e3, 0xc727, 0x48cd, { 0x8b, 0xbf, 0x42, 0x72, 0x33, 0x85, 0x49, 0x48 }}

	///
	/// I2C Host Protocol
	///
	/// The I2C bus driver uses the services of the EFI_I2C_HOST_PROTOCOL
	/// to produce an instance of the EFI_I2C_IO_PROTOCOL for each I2C
	/// device on an I2C bus.
	///
	/// The EFI_I2C_HOST_PROTOCOL exposes an asynchronous interface to
	/// callers to perform transactions to any device on the I2C bus.
	/// Internally, the I2C host protocol manages the flow of the I2C
	/// transactions to the host controller, keeping them in FIFO order.
	/// Prior to each transaction, the I2C host protocol ensures that the
	/// switches and multiplexers are properly configured. The I2C host
	/// protocol then starts the transaction on the host controller using
	/// the EFI_I2C_MASTER_PROTOCOL.
	///
	typedef struct _EFI_I2C_HOST_PROTOCOL EFI_I2C_HOST_PROTOCOL;


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

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

	The I2C host protocol uses the concept of I2C bus configurations
	to describe the I2C bus. An I2C bus configuration is defined as
	a unique setting of the multiplexers and switches in the I2C bus
	which enable access to one or more I2C devices. When using a
	switch to divide a bus, due to bus frequency differences, the
	I2C bus configuration management protocol defines an I2C bus
	configuration for the I2C devices on each side of the switch.
	When using a multiplexer, the I2C bus configuration management
	defines an I2C bus configuration for each of the selector values
	required to control the multiplexer. See Figure 1 in the I2C -bus
	specification and user manual for a complex I2C bus configuration.

	The I2C host protocol processes all transactions in FIFO order.
	Prior to performing the transaction, the I2C host protocol calls
	EnableI2cBusConfiguration to reconfigure the switches and
	multiplexers in the I2C bus enabling access to the specified I2C
	device. The EnableI2cBusConfiguration also selects the I2C bus
	frequency for the I2C device. After the I2C bus is configured,
	the I2C host protocol calls the I2C master protocol to start the
	I2C transaction.

	If the I2C host protocol has pending I2C transactions queued when
	the driver binding Stop() routine is called then the I2C host
	protocol completes all of the pending I2C transactions by returning
	EFI_ABORTED status. This notifies the upper layers allowing them
	to take corrective action or prepare to stop.

	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 asynchronously 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.

	@param[in] This Pointer to an EFI_I2C_HOST_PROTOCOL structure.
	@param[in] I2cBusConfiguration I2C bus configuration to access the I2C
	device
	@param[in] SlaveAddress Address of the device on the I2C bus. Set
	the I2C_ADDRESSING_10_BIT when using 10-bit
	addresses, clear this bit for 7-bit addressing.
	Bits 0-6 are used for 7-bit I2C slave addresses
	and bits 0-9 are used for 10-bit I2C slave
	addresses.
	@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_ABORTED The request did not complete because the
	driver binding Stop() routine was called.
	@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_NOT_FOUND Reserved bit set in the SlaveAddress parameter
	@retval EFI_NO_MAPPING Invalid I2cBusConfiguration value
	@retval EFI_NO_RESPONSE The I2C device is not responding to the slave
	address. 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_HOST_PROTOCOL_QUEUE_REQUEST) (
	IN CONST EFI_I2C_HOST_PROTOCOL *This,
	IN UINTN I2cBusConfiguration,
	IN UINTN SlaveAddress,
	IN EFI_EVENT Event OPTIONAL,
	IN EFI_I2C_REQUEST_PACKET *RequestPacket,
	OUT EFI_STATUS *I2cStatus OPTIONAL
	);

	///
	/// I2C Host Protocol
	///
	struct _EFI_I2C_HOST_PROTOCOL {
	///
	/// Queue an I2C transaction for execution on the I2C bus
	///
	EFI_I2C_HOST_PROTOCOL_QUEUE_REQUEST QueueRequest;

	///
	/// 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 gEfiI2cHostProtocolGuid;

	#endif // __I2C_HOST_H__