EdkCompatibilityPkg/Foundation/Library/EdkIIGlueLib/Include/Library/EdkIIGlueSmbusLib.h

   1 /*++
   2
   3 Copyright (c) 2004 - 2006, Intel Corporation. All rights reserved.<BR>
   4 This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12
  13 Module Name:
  14
  15   EdkIIGlueSmbusLib.h
  16
  17 Abstract:
  18
  19   Public header file for Smbus Lib
  20
  21 --*/
  22
  23 #ifndef __EDKII_GLUE_SMBUS_LIB_H__
  24 #define __EDKII_GLUE_SMBUS_LIB_H__
  25
  26 //
  27 // PEC BIT is bit 22 in SMBUS address
  28 //
  29 #define SMBUS_LIB_PEC_BIT   (1 << 22)
  30
  31 /**
  32   Macro that converts SMBUS slave address, SMBUS command, SMBUS data length,
  33   and PEC to a value that can be passed to the SMBUS Library functions.
  34
  35   Computes an address that is compatible with the SMBUS Library functions.
  36   The unused upper bits of SlaveAddress, Command, and Length are stripped
  37   prior to the generation of the address.
  38
  39   @param  SlaveAddress    SMBUS Slave Address.  Range 0..127.
  40   @param  Command         SMBUS Command.  Range 0..255.
  41   @param  Length          SMBUS Data Length.  Range 0..32.
  42   @param  Pec             TRUE if Packet Error Checking is enabled.  Otherwise FALSE.
  43
  44 **/
  45 #define SMBUS_LIB_ADDRESS(SlaveAddress,Command,Length,Pec)  \
  46   ( ((Pec) ? SMBUS_LIB_PEC_BIT: 0)      | \
  47     (((SlaveAddress) & 0x7f) << 1)      | \
  48     (((Command)      & 0xff) << 8)      | \
  49     (((Length)       & 0x3f) << 16)       \
  50   )
  51
  52 /**
  53   Executes an SMBUS quick read command.
  54
  55   Executes an SMBUS quick read command on the SMBUS device specified by SmBusAddress.
  56   Only the SMBUS slave address field of SmBusAddress is required.
  57   If Status is not NULL, then the status of the executed command is returned in Status.
  58   If PEC is set in SmBusAddress, then ASSERT().
  59   If Command in SmBusAddress is not zero, then ASSERT().
  60   If Length in SmBusAddress is not zero, then ASSERT().
  61   If any reserved bits of SmBusAddress are set, then ASSERT().
  62
  63   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
  64                           SMBUS Command, SMBUS Data Length, and PEC.
  65   @param  Status          Return status for the executed command.
  66                           This is an optional parameter and may be NULL.
  67
  68 **/
  69 VOID
  70 EFIAPI
  71 SmBusQuickRead (
  72   IN  UINTN                     SmBusAddress,
  73   OUT RETURN_STATUS             *Status       OPTIONAL
  74   );
  75
  76 /**
  77   Executes an SMBUS quick write command.
  78
  79   Executes an SMBUS quick write command on the SMBUS device specified by SmBusAddress.
  80   Only the SMBUS slave address field of SmBusAddress is required.
  81   If Status is not NULL, then the status of the executed command is returned in Status.
  82   If PEC is set in SmBusAddress, then ASSERT().
  83   If Command in SmBusAddress is not zero, then ASSERT().
  84   If Length in SmBusAddress is not zero, then ASSERT().
  85   If any reserved bits of SmBusAddress are set, then ASSERT().
  86
  87   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
  88                           SMBUS Command, SMBUS Data Length, and PEC.
  89   @param  Status          Return status for the executed command.
  90                           This is an optional parameter and may be NULL.
  91
  92 **/
  93 VOID
  94 EFIAPI
  95 SmBusQuickWrite (
  96   IN  UINTN                     SmBusAddress,
  97   OUT RETURN_STATUS             *Status       OPTIONAL
  98   );
  99
 100 /**
 101   Executes an SMBUS receive byte command.
 102
 103   Executes an SMBUS receive byte command on the SMBUS device specified by SmBusAddress.
 104   Only the SMBUS slave address field of SmBusAddress is required.
 105   The byte received from the SMBUS is returned.
 106   If Status is not NULL, then the status of the executed command is returned in Status.
 107   If Command in SmBusAddress is not zero, then ASSERT().
 108   If Length in SmBusAddress is not zero, then ASSERT().
 109   If any reserved bits of SmBusAddress are set, then ASSERT().
 110
 111   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 112                           SMBUS Command, SMBUS Data Length, and PEC.
 113   @param  Status          Return status for the executed command.
 114                           This is an optional parameter and may be NULL.
 115
 116   @return The byte received from the SMBUS.
 117
 118 **/
 119 UINT8
 120 EFIAPI
 121 SmBusReceiveByte (
 122   IN  UINTN          SmBusAddress,
 123   OUT RETURN_STATUS  *Status        OPTIONAL
 124   );
 125
 126 /**
 127   Executes an SMBUS send byte command.
 128
 129   Executes an SMBUS send byte command on the SMBUS device specified by SmBusAddress.
 130   The byte specified by Value is sent.
 131   Only the SMBUS slave address field of SmBusAddress is required.  Value is returned.
 132   If Status is not NULL, then the status of the executed command is returned in Status.
 133   If Command in SmBusAddress is not zero, then ASSERT().
 134   If Length in SmBusAddress is not zero, then ASSERT().
 135   If any reserved bits of SmBusAddress are set, then ASSERT().
 136
 137   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 138                           SMBUS Command, SMBUS Data Length, and PEC.
 139   @param  Value           The 8-bit value to send.
 140   @param  Status          Return status for the executed command.
 141                           This is an optional parameter and may be NULL.
 142
 143   @return The parameter of Value.
 144
 145 **/
 146 UINT8
 147 EFIAPI
 148 SmBusSendByte (
 149   IN  UINTN          SmBusAddress,
 150   IN  UINT8          Value,
 151   OUT RETURN_STATUS  *Status        OPTIONAL
 152   );
 153
 154 /**
 155   Executes an SMBUS read data byte command.
 156
 157   Executes an SMBUS read data byte command on the SMBUS device specified by SmBusAddress.
 158   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 159   The 8-bit value read from the SMBUS is returned.
 160   If Status is not NULL, then the status of the executed command is returned in Status.
 161   If Length in SmBusAddress is not zero, then ASSERT().
 162   If any reserved bits of SmBusAddress are set, then ASSERT().
 163
 164   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 165                           SMBUS Command, SMBUS Data Length, and PEC.
 166   @param  Status          Return status for the executed command.
 167                           This is an optional parameter and may be NULL.
 168
 169   @return The byte read from the SMBUS.
 170
 171 **/
 172 UINT8
 173 EFIAPI
 174 SmBusReadDataByte (
 175   IN  UINTN          SmBusAddress,
 176   OUT RETURN_STATUS  *Status        OPTIONAL
 177   );
 178
 179 /**
 180   Executes an SMBUS write data byte command.
 181
 182   Executes an SMBUS write data byte command on the SMBUS device specified by SmBusAddress.
 183   The 8-bit value specified by Value is written.
 184   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 185   Value is returned.
 186   If Status is not NULL, then the status of the executed command is returned in Status.
 187   If Length in SmBusAddress is not zero, then ASSERT().
 188   If any reserved bits of SmBusAddress are set, then ASSERT().
 189
 190   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 191                           SMBUS Command, SMBUS Data Length, and PEC.
 192   @param  Value           The 8-bit value to write.
 193   @param  Status          Return status for the executed command.
 194                           This is an optional parameter and may be NULL.
 195
 196   @return The parameter of Value.
 197
 198 **/
 199 UINT8
 200 EFIAPI
 201 SmBusWriteDataByte (
 202   IN  UINTN          SmBusAddress,
 203   IN  UINT8          Value,
 204   OUT RETURN_STATUS  *Status        OPTIONAL
 205   );
 206
 207 /**
 208   Executes an SMBUS read data word command.
 209
 210   Executes an SMBUS read data word command on the SMBUS device specified by SmBusAddress.
 211   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 212   The 16-bit value read from the SMBUS is returned.
 213   If Status is not NULL, then the status of the executed command is returned in Status.
 214   If Length in SmBusAddress is not zero, then ASSERT().
 215   If any reserved bits of SmBusAddress are set, then ASSERT().
 216
 217   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 218                           SMBUS Command, SMBUS Data Length, and PEC.
 219   @param  Status          Return status for the executed command.
 220                           This is an optional parameter and may be NULL.
 221
 222   @return The byte read from the SMBUS.
 223
 224 **/
 225 UINT16
 226 EFIAPI
 227 SmBusReadDataWord (
 228   IN  UINTN          SmBusAddress,
 229   OUT RETURN_STATUS  *Status        OPTIONAL
 230   );
 231
 232 /**
 233   Executes an SMBUS write data word command.
 234
 235   Executes an SMBUS write data word command on the SMBUS device specified by SmBusAddress.
 236   The 16-bit value specified by Value is written.
 237   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 238   Value is returned.
 239   If Status is not NULL, then the status of the executed command is returned in Status.
 240   If Length in SmBusAddress is not zero, then ASSERT().
 241   If any reserved bits of SmBusAddress are set, then ASSERT().
 242
 243   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 244                           SMBUS Command, SMBUS Data Length, and PEC.
 245   @param  Value           The 16-bit value to write.
 246   @param  Status          Return status for the executed command.
 247                           This is an optional parameter and may be NULL.
 248
 249   @return The parameter of Value.
 250
 251 **/
 252 UINT16
 253 EFIAPI
 254 SmBusWriteDataWord (
 255   IN  UINTN          SmBusAddress,
 256   IN  UINT16         Value,
 257   OUT RETURN_STATUS  *Status        OPTIONAL
 258   );
 259
 260 /**
 261   Executes an SMBUS process call command.
 262
 263   Executes an SMBUS process call command on the SMBUS device specified by SmBusAddress.
 264   The 16-bit value specified by Value is written.
 265   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 266   The 16-bit value returned by the process call command is returned.
 267   If Status is not NULL, then the status of the executed command is returned in Status.
 268   If Length in SmBusAddress is not zero, then ASSERT().
 269   If any reserved bits of SmBusAddress are set, then ASSERT().
 270
 271   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 272                           SMBUS Command, SMBUS Data Length, and PEC.
 273   @param  Value           The 16-bit value to write.
 274   @param  Status          Return status for the executed command.
 275                           This is an optional parameter and may be NULL.
 276
 277   @return The 16-bit value returned by the process call command.
 278
 279 **/
 280 UINT16
 281 EFIAPI
 282 SmBusProcessCall (
 283   IN  UINTN          SmBusAddress,
 284   IN  UINT16         Value,
 285   OUT RETURN_STATUS  *Status        OPTIONAL
 286   );
 287
 288 /**
 289   Executes an SMBUS read block command.
 290
 291   Executes an SMBUS read block command on the SMBUS device specified by SmBusAddress.
 292   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 293   Bytes are read from the SMBUS and stored in Buffer.
 294   The number of bytes read is returned, and will never return a value larger than 32-bytes.
 295   If Status is not NULL, then the status of the executed command is returned in Status.
 296   It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
 297   SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes.
 298   If Length in SmBusAddress is not zero, then ASSERT().
 299   If Buffer is NULL, then ASSERT().
 300   If any reserved bits of SmBusAddress are set, then ASSERT().
 301
 302   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 303                           SMBUS Command, SMBUS Data Length, and PEC.
 304   @param  Buffer          Pointer to the buffer to store the bytes read from the SMBUS.
 305   @param  Status          Return status for the executed command.
 306                           This is an optional parameter and may be NULL.
 307
 308   @return The number of bytes read.
 309
 310 **/
 311 UINTN
 312 EFIAPI
 313 SmBusReadBlock (
 314   IN  UINTN          SmBusAddress,
 315   OUT VOID           *Buffer,
 316   OUT RETURN_STATUS  *Status        OPTIONAL
 317   );
 318
 319 /**
 320   Executes an SMBUS write block command.
 321
 322   Executes an SMBUS write block command on the SMBUS device specified by SmBusAddress.
 323   The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required.
 324   Bytes are written to the SMBUS from Buffer.
 325   The number of bytes written is returned, and will never return a value larger than 32-bytes.
 326   If Status is not NULL, then the status of the executed command is returned in Status.
 327   If Length in SmBusAddress is zero or greater than 32, then ASSERT().
 328   If Buffer is NULL, then ASSERT().
 329   If any reserved bits of SmBusAddress are set, then ASSERT().
 330
 331   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 332                           SMBUS Command, SMBUS Data Length, and PEC.
 333   @param  Buffer          Pointer to the buffer to store the bytes read from the SMBUS.
 334   @param  Status          Return status for the executed command.
 335                           This is an optional parameter and may be NULL.
 336
 337   @return The number of bytes written.
 338
 339 **/
 340 UINTN
 341 EFIAPI
 342 SmBusWriteBlock (
 343   IN  UINTN          SmBusAddress,
 344   OUT VOID           *Buffer,
 345   OUT RETURN_STATUS  *Status        OPTIONAL
 346   );
 347
 348 /**
 349   Executes an SMBUS block process call command.
 350
 351   Executes an SMBUS block process call command on the SMBUS device specified by SmBusAddress.
 352   The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required.
 353   Bytes are written to the SMBUS from WriteBuffer.  Bytes are then read from the SMBUS into ReadBuffer.
 354   If Status is not NULL, then the status of the executed command is returned in Status.
 355   It is the caller's responsibility to make sure ReadBuffer is large enough for the total number of bytes read.
 356   SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes.
 357   If Length in SmBusAddress is zero or greater than 32, then ASSERT().
 358   If WriteBuffer is NULL, then ASSERT().
 359   If ReadBuffer is NULL, then ASSERT().
 360   If any reserved bits of SmBusAddress are set, then ASSERT().
 361
 362   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 363                           SMBUS Command, SMBUS Data Length, and PEC.
 364   @param  WriteBuffer     Pointer to the buffer of bytes to write to the SMBUS.
 365   @param  ReadBuffer      Pointer to the buffer of bytes to read from the SMBUS.
 366   @param  Status          Return status for the executed command.
 367                           This is an optional parameter and may be NULL.
 368
 369   @return The number of bytes written.
 370
 371 **/
 372 UINTN
 373 EFIAPI
 374 SmBusBlockProcessCall (
 375   IN  UINTN          SmBusAddress,
 376   IN  VOID           *WriteBuffer,
 377   OUT VOID           *ReadBuffer,
 378   OUT RETURN_STATUS  *Status        OPTIONAL
 379   );
 380
 381
 382 #endif