MdePkg: Apply uncrustify changes

[mirror_edk2.git] / MdePkg / Include / Pi / PiI2c.h

/** @file\r
  Include file matches things in PI.\r
\r
Copyright (c) 2013 - 2018, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
  @par Revision Reference:\r
  PI Version 1.3\r
\r
**/\r
\r
#ifndef __PI_I2C_H__\r
#define __PI_I2C_H__\r
\r
///\r
/// A 10-bit slave address is or'ed with the following value enabling the\r
/// I2C protocol stack to address the duplicated address space between 0\r
//  and 127 in 10-bit mode.\r
///\r
#define I2C_ADDRESSING_10_BIT  0x80000000\r
\r
///\r
/// I2C controller capabilities\r
///\r
/// The EFI_I2C_CONTROLLER_CAPABILITIES specifies the capabilities of the\r
/// I2C host controller.  The StructureSizeInBytes enables variations of\r
/// this structure to be identified if there is need to extend this\r
/// structure in the future.\r
///\r
typedef struct {\r
  ///\r
  /// Length of this data structure in bytes\r
  ///\r
  UINT32    StructureSizeInBytes;\r
\r
  ///\r
  /// The maximum number of bytes the I2C host controller is able to\r
  /// receive from the I2C bus.\r
  ///\r
  UINT32    MaximumReceiveBytes;\r
\r
  ///\r
  /// The maximum number of bytes the I2C host controller is able to send\r
  /// 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
} EFI_I2C_CONTROLLER_CAPABILITIES;\r
\r
///\r
/// I2C device description\r
///\r
/// The EFI_I2C_ENUMERATE_PROTOCOL uses the EFI_I2C_DEVICE to describe\r
/// the platform specific details associated with an I2C device.  This\r
/// description is passed to the I2C bus driver during enumeration where\r
/// it is made available to the third party I2C device driver via the\r
/// EFI_I2C_IO_PROTOCOL.\r
///\r
typedef struct {\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\r
  /// Configuration and Power Interface Specification, Revision 5.0\r
  /// for the field format and the Plug and play support for I2C\r
  /// web-page for restriction on values.\r
  ///\r
  /// http://www.acpi.info/spec.htm\r
  /// http://msdn.microsoft.com/en-us/library/windows/hardware/jj131711(v=vs.85).aspx\r
  ///\r
  UINT32          HardwareRevision;\r
\r
  ///\r
  /// I2C bus configuration for the I2C device\r
  ///\r
  UINT32          I2cBusConfiguration;\r
\r
  ///\r
  /// Number of slave addresses for the I2C device.\r
  ///\r
  UINT32          SlaveAddressCount;\r
\r
  ///\r
  /// Pointer to the array of slave addresses for the I2C device.\r
  ///\r
  CONST UINT32    *SlaveAddressArray;\r
} EFI_I2C_DEVICE;\r
\r
///\r
/// Define the I2C flags\r
///\r
/// I2C read operation when set\r
#define I2C_FLAG_READ  0x00000001\r
\r
///\r
/// Define the flags for SMBus operation\r
///\r
/// The following flags are also present in only the first I2C operation\r
/// and are ignored when present in other operations.  These flags\r
/// describe a particular SMB transaction as shown in the following table.\r
///\r
\r
/// SMBus operation\r
#define I2C_FLAG_SMBUS_OPERATION  0x00010000\r
\r
/// SMBus block operation\r
///   The flag I2C_FLAG_SMBUS_BLOCK causes the I2C master protocol to update\r
///   the LengthInBytes field of the operation in the request packet with\r
///   the actual number of bytes read or written.  These values are only\r
///   valid when the entire I2C transaction is successful.\r
///   This flag also changes the LengthInBytes meaning to be: A maximum\r
///   of LengthInBytes is to be read from the device.  The first byte\r
///   read contains the number of bytes remaining to be read, plus an\r
///   optional PEC value.\r
#define I2C_FLAG_SMBUS_BLOCK  0x00020000\r
\r
/// SMBus process call operation\r
#define I2C_FLAG_SMBUS_PROCESS_CALL  0x00040000\r
\r
/// SMBus use packet error code (PEC)\r
///   Note that the I2C master protocol may clear the I2C_FLAG_SMBUS_PEC bit\r
///   to indicate that the PEC value was checked by the hardware and is\r
///   not appended to the returned read data.\r
///\r
#define I2C_FLAG_SMBUS_PEC  0x00080000\r
\r
// ----------------------------------------------------------------------\r
///\r
/// QuickRead:          OperationCount=1,\r
///                     LengthInBytes=0,   Flags=I2C_FLAG_READ\r
/// QuickWrite:         OperationCount=1,\r
///                     LengthInBytes=0,   Flags=0\r
///\r
///\r
/// ReceiveByte:        OperationCount=1,\r
///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_READ\r
/// ReceiveByte+PEC:    OperationCount=1,\r
///                     LengthInBytes=2,   Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_READ\r
///                                            | I2C_FLAG_SMBUS_PEC\r
///\r
///\r
/// SendByte:           OperationCount=1,\r
///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION\r
/// SendByte+PEC:       OperationCount=1,\r
///                     LengthInBytes=2,   Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_SMBUS_PEC\r
///\r
///\r
/// ReadDataByte:       OperationCount=2,\r
///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION\r
///                     LengthInBytes=1,   Flags=I2C_FLAG_READ\r
/// ReadDataByte+PEC:   OperationCount=2,\r
///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_SMBUS_PEC\r
///                     LengthInBytes=2,   Flags=I2C_FLAG_READ\r
///\r
///\r
/// WriteDataByte:      OperationCount=1,\r
///                     LengthInBytes=2,   Flags=I2C_FLAG_SMBUS_OPERATION\r
/// WriteDataByte+PEC:  OperationCount=1,\r
///                     LengthInBytes=3,   Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_SMBUS_PEC\r
///\r
///\r
/// ReadDataWord:       OperationCount=2,\r
///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION\r
///                     LengthInBytes=2,   Flags=I2C_FLAG_READ\r
/// ReadDataWord+PEC:   OperationCount=2,\r
///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_SMBUS_PEC\r
///                     LengthInBytes=3,   Flags=I2C_FLAG_READ\r
///\r
///\r
/// WriteDataWord:      OperationCount=1,\r
///                     LengthInBytes=3,   Flags=I2C_FLAG_SMBUS_OPERATION\r
/// WriteDataWord+PEC:  OperationCount=1,\r
///                     LengthInBytes=4,   Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_SMBUS_PEC\r
///\r
///\r
/// ReadBlock:          OperationCount=2,\r
///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_SMBUS_BLOCK\r
///                     LengthInBytes=33,  Flags=I2C_FLAG_READ\r
/// ReadBlock+PEC:      OperationCount=2,\r
///                     LengthInBytes=1,   Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_SMBUS_BLOCK\r
///                                            | I2C_FLAG_SMBUS_PEC\r
///                     LengthInBytes=34,  Flags=I2C_FLAG_READ\r
///\r
///\r
/// WriteBlock:         OperationCount=1,\r
///                     LengthInBytes=N+2, Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_SMBUS_BLOCK\r
/// WriteBlock+PEC:     OperationCount=1,\r
///                     LengthInBytes=N+3, Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_SMBUS_BLOCK\r
///                                            | I2C_FLAG_SMBUS_PEC\r
///\r
///\r
/// ProcessCall:        OperationCount=2,\r
///                     LengthInBytes=3,   Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_SMBUS_PROCESS_CALL\r
///                     LengthInBytes=2,   Flags=I2C_FLAG_READ\r
/// ProcessCall+PEC:    OperationCount=2,\r
///                     LengthInBytes=3,   Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_SMBUS_PROCESS_CALL\r
///                                            | I2C_FLAG_SMBUS_PEC\r
///                     LengthInBytes=3,   Flags=I2C_FLAG_READ\r
///\r
///\r
/// BlkProcessCall:     OperationCount=2,\r
///                     LengthInBytes=N+2, Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_SMBUS_PROCESS_CALL\r
///                                            | I2C_FLAG_SMBUS_BLOCK\r
///                     LengthInBytes=33,  Flags=I2C_FLAG_READ\r
/// BlkProcessCall+PEC: OperationCount=2,\r
///                     LengthInBytes=N+2, Flags=I2C_FLAG_SMBUS_OPERATION\r
///                                            | I2C_FLAG_SMBUS_PROCESS_CALL\r
///                                            | I2C_FLAG_SMBUS_BLOCK\r
///                                            | I2C_FLAG_SMBUS_PEC\r
///                     LengthInBytes=34,  Flags=I2C_FLAG_READ\r
///\r
// ----------------------------------------------------------------------\r
\r
///\r
/// I2C device operation\r
///\r
/// The EFI_I2C_OPERATION describes a subset of an I2C transaction in which\r
/// the I2C controller is either sending or receiving bytes from the bus.\r
/// Some transactions will consist of a single operation while others will\r
/// be two or more.\r
///\r
/// Note: Some I2C controllers do not support read or write ping (address\r
/// only) operation and will return EFI_UNSUPPORTED status when these\r
/// operations are requested.\r
///\r
/// Note: I2C controllers which do not support complex transactions requiring\r
/// multiple repeated start bits return EFI_UNSUPPORTED without processing\r
/// any of the transaction.\r
///\r
typedef struct {\r
  ///\r
  /// Flags to qualify the I2C operation.\r
  ///\r
  UINT32    Flags;\r
\r
  ///\r
  /// Number of bytes to send to or receive from the I2C device.  A ping\r
  /// (address only byte/bytes)  is indicated by setting the LengthInBytes\r
  /// to zero.\r
  ///\r
  UINT32    LengthInBytes;\r
\r
  ///\r
  /// Pointer to a buffer containing the data to send or to receive from\r
  /// the I2C device.  The Buffer must be at least LengthInBytes in size.\r
  ///\r
  UINT8     *Buffer;\r
} EFI_I2C_OPERATION;\r
\r
///\r
/// I2C device request\r
///\r
/// The EFI_I2C_REQUEST_PACKET describes a single I2C transaction.  The\r
/// transaction starts with a start bit followed by the first operation\r
/// in the operation array.  Subsequent operations are separated with\r
/// repeated start bits and the last operation is followed by a stop bit\r
/// which concludes the transaction.  Each operation is described by one\r
/// of the elements in the Operation array.\r
///\r
typedef struct {\r
  ///\r
  /// Number of elements in the operation array\r
  ///\r
  UINTN                OperationCount;\r
\r
  ///\r
  /// Description of the I2C operation\r
  ///\r
  EFI_I2C_OPERATION    Operation[1];\r
} EFI_I2C_REQUEST_PACKET;\r
\r
#endif //  __PI_I2C_H__\r