MdePkg/Include/Protocol/SmbusHc.h - third_party/edk2 - Git at Google

 /** @file
   The file provides basic SMBus host controller management
   and basic data transactions over the SMBus.

   Copyright (c) 2006 - 2011, 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: PI
   Version 1.00.

 **/

 #ifndef __SMBUS_HC_H__
 #define __SMBUS_HC_H__

 #include <IndustryStandard/SmBus.h>

 #define EFI_SMBUS_HC_PROTOCOL_GUID \
   {0xe49d33ed, 0x513d, 0x4634, { 0xb6, 0x98, 0x6f, 0x55, 0xaa, 0x75, 0x1c, 0x1b} }

 typedef struct _EFI_SMBUS_HC_PROTOCOL EFI_SMBUS_HC_PROTOCOL;

 /**

   The Execute() function provides a standard way to execute an
   operation as defined in the System Management Bus (SMBus)
   Specification. The resulting transaction will be either that
   the SMBus slave devices accept this transaction or that this
   function returns with error.

   @param This     A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
                   SlaveAddress The SMBus slave address of the device
                   with which to communicate. Type
                   EFI_SMBUS_DEVICE_ADDRESS is defined in
                   EFI_PEI_SMBUS_PPI.Execute() in the Platform
                   Initialization SMBus PPI Specification.

   @param Command  This command is transmitted by the SMBus host
                   controller to the SMBus slave device and the
                   interpretation is SMBus slave device specific.
                   It can mean the offset to a list of functions
                   inside an SMBus slave device. Not all
                   operations or slave devices support this
                   command's registers. Type
                   EFI_SMBUS_DEVICE_COMMAND is defined in
                   EFI_PEI_SMBUS_PPI.Execute() in the Platform
                   Initialization SMBus PPI Specification.

  @param Operation Signifies the particular SMBus
                   hardware protocol instance it will use to
                   execute the SMBus transactions. This SMBus
                   hardware protocol is defined by the SMBus
                   Specification and is not related to PI
                   Architecture. Type EFI_SMBUS_OPERATION is
                   defined in EFI_PEI_SMBUS_PPI.Execute() in the
                   Platform Initialization SMBus PPI
                   Specification.

   @param PecCheck Defines if Packet Error Code (PEC) checking
                   is required for this operation. SMBus Host
                   Controller Code Definitions Version 1.0
                   August 21, 2006 13

  @param Length    Signifies the number of bytes that this operation will do.
                   The maximum number of bytes can be revision
                   specific and operation specific. This field
                   will contain the actual number of bytes that
                   are executed for this operation. Not all
                   operations require this argument.

   @param Buffer   Contains the value of data to execute to the
                   SMBus slave device. Not all operations require
                   this argument. The length of this buffer is
                   identified by Length.


   @retval EFI_SUCCESS           The last data that was returned from the
                                 access matched the poll exit criteria.

   @retval EFI_CRC_ERROR         Checksum is not correct (PEC is incorrect).

   @retval EFI_TIMEOUT           Timeout expired before the operation was
                                 completed. Timeout is determined by the
                                 SMBus host controller device.

   @retval EFI_OUT_OF_RESOURCES  The request could not be
                                 completed due to a lack of
                                 resources.

   @retval EFI_DEVICE_ERROR      The request was not completed
                                 because a failure that was reflected
                                 in the Host Status Register bit.
                                 Device errors are a result of a
                                 transaction collision, illegal
                                 command field, unclaimed cycle (host
                                 initiated), or bus errors
                                 (collisions).

   @retval EFI_INVALID_PARAMETER Operation is not defined in
                                 EFI_SMBUS_OPERATION.

   @retval EFI_INVALID_PARAMETER Length/Buffer is NULL for
                                 operations except for
                                 EfiSmbusQuickRead and
                                 EfiSmbusQuickWrite. Length is
                                 outside the range of valid
                                 values.

   @retval EFI_UNSUPPORTED       The SMBus operation or PEC is not
                                 supported.

   @retval EFI_BUFFER_TOO_SMALL  Buffer is not sufficient for
                                 this operation.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_SMBUS_HC_EXECUTE_OPERATION)(
   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
   IN        EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
   IN        EFI_SMBUS_DEVICE_COMMAND  Command,
   IN        EFI_SMBUS_OPERATION       Operation,
   IN        BOOLEAN                   PecCheck,
   IN OUT    UINTN                     *Length,
   IN OUT    VOID                      *Buffer
 );


 /**

   The ArpDevice() function provides a standard way for a device driver to
   enumerate the entire SMBus or specific devices on the bus.

   @param This           A pointer to the EFI_SMBUS_HC_PROTOCOL instance.

   @param ArpAll         A Boolean expression that indicates if the
                         host drivers need to enumerate all the devices
                         or enumerate only the device that is
                         identified by SmbusUdid. If ArpAll is TRUE,
                         SmbusUdid and SlaveAddress are optional. If
                         ArpAll is FALSE, ArpDevice will enumerate
                         SmbusUdid and the address will be at
                         SlaveAddress.

   @param SmbusUdid      The Unique Device Identifier (UDID) that is
                         associated with this device. Type
                         EFI_SMBUS_UDID is defined in
                         EFI_PEI_SMBUS_PPI.ArpDevice() in the
                         Platform Initialization SMBus PPI
                         Specification.

   @param SlaveAddress   The SMBus slave address that is
                         associated with an SMBus UDID.

   @retval EFI_SUCCESS           The last data that was returned from the
                                 access matched the poll exit criteria.

   @retval EFI_CRC_ERROR         Checksum is not correct (PEC is
                                 incorrect).

   @retval EFI_TIMEOUT           Timeout expired before the operation was
                                 completed. Timeout is determined by the
                                 SMBus host controller device.

   @retval EFI_OUT_OF_RESOURCES  The request could not be
                                 completed due to a lack of
                                 resources.

   @retval EFI_DEVICE_ERROR      The request was not completed
                                 because a failure was reflected in
                                 the Host Status Register bit. Device
                                 Errors are a result of a transaction
                                 collision, illegal command field,
                                 unclaimed cycle (host initiated), or
                                 bus errors (collisions).

   @retval EFI_UNSUPPORTED       ArpDevice, GetArpMap, and Notify are
                                 not implemented by this driver.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE)(
   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
   IN        BOOLEAN                   ArpAll,
   IN        EFI_SMBUS_UDID            *SmbusUdid,   OPTIONAL
   IN OUT    EFI_SMBUS_DEVICE_ADDRESS  *SlaveAddress OPTIONAL
 );


 /**
   The GetArpMap() function returns the mapping of all the SMBus devices
   that were enumerated by the SMBus host driver.

   @param This           A pointer to the EFI_SMBUS_HC_PROTOCOL instance.

   @param Length         Size of the buffer that contains the SMBus
                         device map.

   @param SmbusDeviceMap The pointer to the device map as
                         enumerated by the SMBus controller
                         driver.

   @retval EFI_SUCCESS       The SMBus returned the current device map.

   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
                             not implemented by this driver.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP)(
   IN CONST  EFI_SMBUS_HC_PROTOCOL   *This,
   IN OUT    UINTN                   *Length,
   IN OUT    EFI_SMBUS_DEVICE_MAP    **SmbusDeviceMap
 );

 /**
   The notify function does some actions.

   @param SlaveAddress
   The SMBUS hardware address to which the SMBUS device is preassigned or allocated.

   @param Data
   Data of the SMBus host notify command that the caller wants to be called.

   @return EFI_STATUS
 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_SMBUS_NOTIFY_FUNCTION)(
   IN        EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
   IN        UINTN                     Data
 );


 /**

   The Notify() function registers all the callback functions to
   allow the bus driver to call these functions when the
   SlaveAddress/Data pair happens.

   @param  This            A pointer to the EFI_SMBUS_HC_PROTOCOL instance.

   @param  SlaveAddress    Address that the host controller detects
                           as sending a message and calls all the registered function.

   @param  Data            Data that the host controller detects as sending
                           message and calls all the registered function.


   @param  NotifyFunction  The function to call when the bus
                           driver detects the SlaveAddress and
                           Data pair.

   @retval EFI_SUCCESS       NotifyFunction was registered.

   @retval EFI_UNSUPPORTED   ArpDevice, GetArpMap, and Notify are
                             not implemented by this driver.

 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_SMBUS_HC_PROTOCOL_NOTIFY)(
   IN CONST  EFI_SMBUS_HC_PROTOCOL     *This,
   IN        EFI_SMBUS_DEVICE_ADDRESS  SlaveAddress,
   IN        UINTN                     Data,
   IN        EFI_SMBUS_NOTIFY_FUNCTION NotifyFunction
 );


 ///
 /// The EFI_SMBUS_HC_PROTOCOL provides SMBus host controller management and basic data
 /// transactions over SMBus. There is one EFI_SMBUS_HC_PROTOCOL instance for each SMBus
 /// host controller.
 ///
 struct _EFI_SMBUS_HC_PROTOCOL {
   EFI_SMBUS_HC_EXECUTE_OPERATION    Execute;
   EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE  ArpDevice;
   EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP GetArpMap;
   EFI_SMBUS_HC_PROTOCOL_NOTIFY      Notify;
 };


 extern EFI_GUID gEfiSmbusHcProtocolGuid;

 #endif
	/** @file
	The file provides basic SMBus host controller management
	and basic data transactions over the SMBus.

	Copyright (c) 2006 - 2011, 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: PI
	Version 1.00.

	**/

	#ifndef __SMBUS_HC_H__
	#define __SMBUS_HC_H__

	#include <IndustryStandard/SmBus.h>

	#define EFI_SMBUS_HC_PROTOCOL_GUID \
	{0xe49d33ed, 0x513d, 0x4634, { 0xb6, 0x98, 0x6f, 0x55, 0xaa, 0x75, 0x1c, 0x1b} }

	typedef struct _EFI_SMBUS_HC_PROTOCOL EFI_SMBUS_HC_PROTOCOL;

	/**

	The Execute() function provides a standard way to execute an
	operation as defined in the System Management Bus (SMBus)
	Specification. The resulting transaction will be either that
	the SMBus slave devices accept this transaction or that this
	function returns with error.

	@param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.
	SlaveAddress The SMBus slave address of the device
	with which to communicate. Type
	EFI_SMBUS_DEVICE_ADDRESS is defined in
	EFI_PEI_SMBUS_PPI.Execute() in the Platform
	Initialization SMBus PPI Specification.

	@param Command This command is transmitted by the SMBus host
	controller to the SMBus slave device and the
	interpretation is SMBus slave device specific.
	It can mean the offset to a list of functions
	inside an SMBus slave device. Not all
	operations or slave devices support this
	command's registers. Type
	EFI_SMBUS_DEVICE_COMMAND is defined in
	EFI_PEI_SMBUS_PPI.Execute() in the Platform
	Initialization SMBus PPI Specification.

	@param Operation Signifies the particular SMBus
	hardware protocol instance it will use to
	execute the SMBus transactions. This SMBus
	hardware protocol is defined by the SMBus
	Specification and is not related to PI
	Architecture. Type EFI_SMBUS_OPERATION is
	defined in EFI_PEI_SMBUS_PPI.Execute() in the
	Platform Initialization SMBus PPI
	Specification.

	@param PecCheck Defines if Packet Error Code (PEC) checking
	is required for this operation. SMBus Host
	Controller Code Definitions Version 1.0
	August 21, 2006 13

	@param Length Signifies the number of bytes that this operation will do.
	The maximum number of bytes can be revision
	specific and operation specific. This field
	will contain the actual number of bytes that
	are executed for this operation. Not all
	operations require this argument.

	@param Buffer Contains the value of data to execute to the
	SMBus slave device. Not all operations require
	this argument. The length of this buffer is
	identified by Length.


	@retval EFI_SUCCESS The last data that was returned from the
	access matched the poll exit criteria.

	@retval EFI_CRC_ERROR Checksum is not correct (PEC is incorrect).

	@retval EFI_TIMEOUT Timeout expired before the operation was
	completed. Timeout is determined by the
	SMBus host controller device.

	@retval EFI_OUT_OF_RESOURCES The request could not be
	completed due to a lack of
	resources.

	@retval EFI_DEVICE_ERROR The request was not completed
	because a failure that was reflected
	in the Host Status Register bit.
	Device errors are a result of a
	transaction collision, illegal
	command field, unclaimed cycle (host
	initiated), or bus errors
	(collisions).

	@retval EFI_INVALID_PARAMETER Operation is not defined in
	EFI_SMBUS_OPERATION.

	@retval EFI_INVALID_PARAMETER Length/Buffer is NULL for
	operations except for
	EfiSmbusQuickRead and
	EfiSmbusQuickWrite. Length is
	outside the range of valid
	values.

	@retval EFI_UNSUPPORTED The SMBus operation or PEC is not
	supported.

	@retval EFI_BUFFER_TOO_SMALL Buffer is not sufficient for
	this operation.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_SMBUS_HC_EXECUTE_OPERATION)(
	IN CONST EFI_SMBUS_HC_PROTOCOL *This,
	IN EFI_SMBUS_DEVICE_ADDRESS SlaveAddress,
	IN EFI_SMBUS_DEVICE_COMMAND Command,
	IN EFI_SMBUS_OPERATION Operation,
	IN BOOLEAN PecCheck,
	IN OUT UINTN *Length,
	IN OUT VOID *Buffer
	);



	/**

	The ArpDevice() function provides a standard way for a device driver to
	enumerate the entire SMBus or specific devices on the bus.

	@param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.

	@param ArpAll A Boolean expression that indicates if the
	host drivers need to enumerate all the devices
	or enumerate only the device that is
	identified by SmbusUdid. If ArpAll is TRUE,
	SmbusUdid and SlaveAddress are optional. If
	ArpAll is FALSE, ArpDevice will enumerate
	SmbusUdid and the address will be at
	SlaveAddress.

	@param SmbusUdid The Unique Device Identifier (UDID) that is
	associated with this device. Type
	EFI_SMBUS_UDID is defined in
	EFI_PEI_SMBUS_PPI.ArpDevice() in the
	Platform Initialization SMBus PPI
	Specification.

	@param SlaveAddress The SMBus slave address that is
	associated with an SMBus UDID.

	@retval EFI_SUCCESS The last data that was returned from the
	access matched the poll exit criteria.

	@retval EFI_CRC_ERROR Checksum is not correct (PEC is
	incorrect).

	@retval EFI_TIMEOUT Timeout expired before the operation was
	completed. Timeout is determined by the
	SMBus host controller device.

	@retval EFI_OUT_OF_RESOURCES The request could not be
	completed due to a lack of
	resources.

	@retval EFI_DEVICE_ERROR The request was not completed
	because a failure was reflected in
	the Host Status Register bit. Device
	Errors are a result of a transaction
	collision, illegal command field,
	unclaimed cycle (host initiated), or
	bus errors (collisions).

	@retval EFI_UNSUPPORTED ArpDevice, GetArpMap, and Notify are
	not implemented by this driver.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE)(
	IN CONST EFI_SMBUS_HC_PROTOCOL *This,
	IN BOOLEAN ArpAll,
	IN EFI_SMBUS_UDID *SmbusUdid, OPTIONAL
	IN OUT EFI_SMBUS_DEVICE_ADDRESS *SlaveAddress OPTIONAL
	);


	/**
	The GetArpMap() function returns the mapping of all the SMBus devices
	that were enumerated by the SMBus host driver.

	@param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.

	@param Length Size of the buffer that contains the SMBus
	device map.

	@param SmbusDeviceMap The pointer to the device map as
	enumerated by the SMBus controller
	driver.

	@retval EFI_SUCCESS The SMBus returned the current device map.

	@retval EFI_UNSUPPORTED ArpDevice, GetArpMap, and Notify are
	not implemented by this driver.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP)(
	IN CONST EFI_SMBUS_HC_PROTOCOL *This,
	IN OUT UINTN *Length,
	IN OUT EFI_SMBUS_DEVICE_MAP **SmbusDeviceMap
	);

	/**
	The notify function does some actions.

	@param SlaveAddress
	The SMBUS hardware address to which the SMBUS device is preassigned or allocated.

	@param Data
	Data of the SMBus host notify command that the caller wants to be called.

	@return EFI_STATUS
	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_SMBUS_NOTIFY_FUNCTION)(
	IN EFI_SMBUS_DEVICE_ADDRESS SlaveAddress,
	IN UINTN Data
	);


	/**

	The Notify() function registers all the callback functions to
	allow the bus driver to call these functions when the
	SlaveAddress/Data pair happens.

	@param This A pointer to the EFI_SMBUS_HC_PROTOCOL instance.

	@param SlaveAddress Address that the host controller detects
	as sending a message and calls all the registered function.

	@param Data Data that the host controller detects as sending
	message and calls all the registered function.


	@param NotifyFunction The function to call when the bus
	driver detects the SlaveAddress and
	Data pair.

	@retval EFI_SUCCESS NotifyFunction was registered.

	@retval EFI_UNSUPPORTED ArpDevice, GetArpMap, and Notify are
	not implemented by this driver.

	**/
	typedef
	EFI_STATUS
	(EFIAPI *EFI_SMBUS_HC_PROTOCOL_NOTIFY)(
	IN CONST EFI_SMBUS_HC_PROTOCOL *This,
	IN EFI_SMBUS_DEVICE_ADDRESS SlaveAddress,
	IN UINTN Data,
	IN EFI_SMBUS_NOTIFY_FUNCTION NotifyFunction
	);


	///
	/// The EFI_SMBUS_HC_PROTOCOL provides SMBus host controller management and basic data
	/// transactions over SMBus. There is one EFI_SMBUS_HC_PROTOCOL instance for each SMBus
	/// host controller.
	///
	struct _EFI_SMBUS_HC_PROTOCOL {
	EFI_SMBUS_HC_EXECUTE_OPERATION Execute;
	EFI_SMBUS_HC_PROTOCOL_ARP_DEVICE ArpDevice;
	EFI_SMBUS_HC_PROTOCOL_GET_ARP_MAP GetArpMap;
	EFI_SMBUS_HC_PROTOCOL_NOTIFY Notify;
	};


	extern EFI_GUID gEfiSmbusHcProtocolGuid;

	#endif