MdePkg/Include/Library/SmbusLib.h

   1 /** @file
   2   Provides library functions to access SMBUS devices. Libraries of this class
   3   must be ported to a specific SMBUS controller.
   4
   5 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef __SMBUS_LIB__
  11 #define __SMBUS_LIB__
  12
  13 /**
  14   Macro that converts SMBUS slave address, SMBUS command, SMBUS data length,
  15   and PEC to a value that can be passed to the SMBUS Library functions.
  16
  17   Computes an address that is compatible with the SMBUS Library functions.
  18   The unused upper bits of SlaveAddress, Command, and Length are stripped
  19   prior to the generation of the address.
  20
  21   @param  SlaveAddress    SMBUS Slave Address.  Range 0..127.
  22   @param  Command         SMBUS Command.  Range 0..255.
  23   @param  Length          SMBUS Data Length.  Range 0..32.
  24   @param  Pec             TRUE if Packet Error Checking is enabled.  Otherwise FALSE.
  25
  26 **/
  27 #define SMBUS_LIB_ADDRESS(SlaveAddress, Command, Length, Pec)  \
  28   ( ((Pec) ? BIT22: 0)                  | \
  29     (((SlaveAddress) & 0x7f) << 1)      | \
  30     (((Command)      & 0xff) << 8)      | \
  31     (((Length)       & 0x3f) << 16)       \
  32   )
  33
  34 /**
  35   Macro that returns the SMBUS Slave Address value from an SmBusAddress Parameter value.
  36
  37   @param SmBusAddress   Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC
  38 **/
  39 #define SMBUS_LIB_SLAVE_ADDRESS(SmBusAddress)  (((SmBusAddress) >> 1)  & 0x7f)
  40
  41 /**
  42   Macro that returns the SMBUS Command value from an SmBusAddress Parameter value.
  43
  44   @param SmBusAddress   Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC
  45 **/
  46 #define SMBUS_LIB_COMMAND(SmBusAddress)  (((SmBusAddress) >> 8)  & 0xff)
  47
  48 /**
  49   Macro that returns the SMBUS Data Length value from an SmBusAddress Parameter value.
  50
  51   @param SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC
  52 **/
  53 #define SMBUS_LIB_LENGTH(SmBusAddress)  (((SmBusAddress) >> 16) & 0x3f)
  54
  55 /**
  56   Macro that returns the SMBUS PEC value from an SmBusAddress Parameter value.
  57
  58   @param SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC
  59 **/
  60 #define SMBUS_LIB_PEC(SmBusAddress)  ((BOOLEAN) (((SmBusAddress) & BIT22) != 0))
  61
  62 /**
  63   Macro that returns the set of reserved bits from an SmBusAddress Parameter value.
  64
  65   @param SmBusAddress Address that encodes the SMBUS Slave Address, SMBUS Command, SMBUS Data Length, and PEC
  66 **/
  67 #define SMBUS_LIB_RESERVED(SmBusAddress)  ((SmBusAddress) & ~(BIT23 - 2))
  68
  69 /**
  70   Executes an SMBUS quick read command.
  71
  72   Executes an SMBUS quick read command on the SMBUS device specified by SmBusAddress.
  73   Only the SMBUS slave address field of SmBusAddress is required.
  74   If Status is not NULL, then the status of the executed command is returned in Status.
  75   If PEC is set in SmBusAddress, then ASSERT().
  76   If Command in SmBusAddress is not zero, then ASSERT().
  77   If Length in SmBusAddress is not zero, then ASSERT().
  78   If any reserved bits of SmBusAddress are set, then ASSERT().
  79
  80   @param  SmBusAddress  Address that encodes the SMBUS Slave Address,
  81                         SMBUS Command, SMBUS Data Length, and PEC.
  82   @param  Status        Return status for the executed command.
  83                         This is an optional parameter and may be NULL.
  84                         RETURN_SUCCESS  The SMBUS command was executed.
  85                         RETURN_TIMEOUT  A timeout occurred while executing the SMBUS command.
  86                         RETURN_DEVICE_ERROR The request was not completed because a failure
  87                         reflected in the Host Status Register bit.  Device errors are a result
  88                         of a transaction collision, illegal command field, unclaimed cycle
  89                         (host initiated), or bus errors (collisions).
  90                         RETURN_UNSUPPORTED  The SMBus operation is not supported.
  91
  92 **/
  93 VOID
  94 EFIAPI
  95 SmBusQuickRead (
  96   IN  UINTN          SmBusAddress,
  97   OUT RETURN_STATUS  *Status       OPTIONAL
  98   );
  99
 100 /**
 101   Executes an SMBUS quick write command.
 102
 103   Executes an SMBUS quick write command on the SMBUS device specified by SmBusAddress.
 104   Only the SMBUS slave address field of SmBusAddress is required.
 105   If Status is not NULL, then the status of the executed command is returned in Status.
 106   If PEC is set in SmBusAddress, then ASSERT().
 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                         RETURN_SUCCESS The SMBUS command was executed.
 116                         RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 117                         RETURN_DEVICE_ERROR  The request was not completed because a failure
 118                         reflected in the Host Status Register bit.  Device errors are a result
 119                         of a transaction collision, illegal command field, unclaimed cycle
 120                         (host initiated), or bus errors (collisions).
 121                         RETURN_UNSUPPORTED  The SMBus operation is not supported.
 122
 123 **/
 124 VOID
 125 EFIAPI
 126 SmBusQuickWrite (
 127   IN  UINTN          SmBusAddress,
 128   OUT RETURN_STATUS  *Status       OPTIONAL
 129   );
 130
 131 /**
 132   Executes an SMBUS receive byte command.
 133
 134   Executes an SMBUS receive byte command on the SMBUS device specified by SmBusAddress.
 135   Only the SMBUS slave address field of SmBusAddress is required.
 136   The byte received from the SMBUS is returned.
 137   If Status is not NULL, then the status of the executed command is returned in Status.
 138   If Command in SmBusAddress is not zero, then ASSERT().
 139   If Length in SmBusAddress is not zero, then ASSERT().
 140   If any reserved bits of SmBusAddress are set, then ASSERT().
 141
 142   @param  SmBusAddress  Address that encodes the SMBUS Slave Address,
 143                         SMBUS Command, SMBUS Data Length, and PEC.
 144   @param  Status        Return status for the executed command.
 145                         This is an optional parameter and may be NULL.
 146                         RETURN_SUCCESS The SMBUS command was executed.
 147                         RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 148                         RETURN_DEVICE_ERROR  The request was not completed because a failure
 149                         reflected in the Host Status Register bit.  Device errors are a result
 150                         of a transaction collision, illegal command field, unclaimed cycle
 151                         (host initiated), or bus errors (collisions).
 152                         RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect)
 153                         RETURN_UNSUPPORTED  The SMBus operation is not supported.
 154
 155   @return The byte received from the SMBUS.
 156
 157 **/
 158 UINT8
 159 EFIAPI
 160 SmBusReceiveByte (
 161   IN  UINTN          SmBusAddress,
 162   OUT RETURN_STATUS  *Status        OPTIONAL
 163   );
 164
 165 /**
 166   Executes an SMBUS send byte command.
 167
 168   Executes an SMBUS send byte command on the SMBUS device specified by SmBusAddress.
 169   The byte specified by Value is sent.
 170   Only the SMBUS slave address field of SmBusAddress is required.  Value is returned.
 171   If Status is not NULL, then the status of the executed command is returned in Status.
 172   If Command in SmBusAddress is not zero, then ASSERT().
 173   If Length in SmBusAddress is not zero, then ASSERT().
 174   If any reserved bits of SmBusAddress are set, then ASSERT().
 175
 176   @param  SmBusAddress  Address that encodes the SMBUS Slave Address,
 177                         SMBUS Command, SMBUS Data Length, and PEC.
 178   @param  Value         The 8-bit value to send.
 179   @param  Status        Return status for the executed command.
 180                         This is an optional parameter and may be NULL.
 181                         RETURN_SUCCESS The SMBUS command was executed.
 182                         RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 183                         RETURN_DEVICE_ERROR  The request was not completed because a failure
 184                         reflected in the Host Status Register bit.  Device errors are a result
 185                         of a transaction collision, illegal command field, unclaimed cycle
 186                         (host initiated), or bus errors (collisions).
 187                         RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect)
 188                         RETURN_UNSUPPORTED  The SMBus operation is not supported.
 189
 190   @return The parameter of Value.
 191
 192 **/
 193 UINT8
 194 EFIAPI
 195 SmBusSendByte (
 196   IN  UINTN          SmBusAddress,
 197   IN  UINT8          Value,
 198   OUT RETURN_STATUS  *Status        OPTIONAL
 199   );
 200
 201 /**
 202   Executes an SMBUS read data byte command.
 203
 204   Executes an SMBUS read data byte command on the SMBUS device specified by SmBusAddress.
 205   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 206   The 8-bit value read from the SMBUS is returned.
 207   If Status is not NULL, then the status of the executed command is returned in Status.
 208   If Length in SmBusAddress is not zero, then ASSERT().
 209   If any reserved bits of SmBusAddress are set, then ASSERT().
 210
 211   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 212                           SMBUS Command, SMBUS Data Length, and PEC.
 213   @param  Status        Return status for the executed command.
 214                         This is an optional parameter and may be NULL.
 215                         RETURN_SUCCESS The SMBUS command was executed.
 216                         RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 217                         RETURN_DEVICE_ERROR  The request was not completed because a failure
 218                         reflected in the Host Status Register bit.  Device errors are a result
 219                         of a transaction collision, illegal command field, unclaimed cycle
 220                         (host initiated), or bus errors (collisions).
 221                         RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect)
 222                         RETURN_UNSUPPORTED  The SMBus operation is not supported.
 223
 224   @return The byte read from the SMBUS.
 225
 226 **/
 227 UINT8
 228 EFIAPI
 229 SmBusReadDataByte (
 230   IN  UINTN          SmBusAddress,
 231   OUT RETURN_STATUS  *Status        OPTIONAL
 232   );
 233
 234 /**
 235   Executes an SMBUS write data byte command.
 236
 237   Executes an SMBUS write data byte command on the SMBUS device specified by SmBusAddress.
 238   The 8-bit value specified by Value is written.
 239   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 240   Value is returned.
 241   If Status is not NULL, then the status of the executed command is returned in Status.
 242   If Length in SmBusAddress is not zero, then ASSERT().
 243   If any reserved bits of SmBusAddress are set, then ASSERT().
 244
 245   @param  SmBusAddress  Address that encodes the SMBUS Slave Address,
 246                         SMBUS Command, SMBUS Data Length, and PEC.
 247   @param  Value         The 8-bit value to write.
 248   @param  Status        Return status for the executed command.
 249                         This is an optional parameter and may be NULL.
 250                         RETURN_SUCCESS The SMBUS command was executed.
 251                         RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 252                         RETURN_DEVICE_ERROR  The request was not completed because a failure
 253                         reflected in the Host Status Register bit.  Device errors are a result
 254                         of a transaction collision, illegal command field, unclaimed cycle
 255                         (host initiated), or bus errors (collisions).
 256                         RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect)
 257                         RETURN_UNSUPPORTED  The SMBus operation is not supported.
 258
 259   @return The parameter of Value.
 260
 261 **/
 262 UINT8
 263 EFIAPI
 264 SmBusWriteDataByte (
 265   IN  UINTN          SmBusAddress,
 266   IN  UINT8          Value,
 267   OUT RETURN_STATUS  *Status        OPTIONAL
 268   );
 269
 270 /**
 271   Executes an SMBUS read data word command.
 272
 273   Executes an SMBUS read data word command on the SMBUS device specified by SmBusAddress.
 274   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 275   The 16-bit value read from the SMBUS is returned.
 276   If Status is not NULL, then the status of the executed command is returned in Status.
 277   If Length in SmBusAddress is not zero, then ASSERT().
 278   If any reserved bits of SmBusAddress are set, then ASSERT().
 279
 280   @param  SmBusAddress  Address that encodes the SMBUS Slave Address,
 281                         SMBUS Command, SMBUS Data Length, and PEC.
 282   @param  Status        Return status for the executed command.
 283                         This is an optional parameter and may be NULL.
 284                         RETURN_SUCCESS The SMBUS command was executed.
 285                         RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 286                         RETURN_DEVICE_ERROR  The request was not completed because a failure
 287                         reflected in the Host Status Register bit.  Device errors are a result
 288                         of a transaction collision, illegal command field, unclaimed cycle
 289                         (host initiated), or bus errors (collisions).
 290                         RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect)
 291                         RETURN_UNSUPPORTED  The SMBus operation is not supported.
 292
 293   @return The byte read from the SMBUS.
 294
 295 **/
 296 UINT16
 297 EFIAPI
 298 SmBusReadDataWord (
 299   IN  UINTN          SmBusAddress,
 300   OUT RETURN_STATUS  *Status        OPTIONAL
 301   );
 302
 303 /**
 304   Executes an SMBUS write data word command.
 305
 306   Executes an SMBUS write data word command on the SMBUS device specified by SmBusAddress.
 307   The 16-bit value specified by Value is written.
 308   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 309   Value is returned.
 310   If Status is not NULL, then the status of the executed command is returned in Status.
 311   If Length in SmBusAddress is not zero, then ASSERT().
 312   If any reserved bits of SmBusAddress are set, then ASSERT().
 313
 314   @param  SmBusAddress  Address that encodes the SMBUS Slave Address,
 315                         SMBUS Command, SMBUS Data Length, and PEC.
 316   @param  Value         The 16-bit value to write.
 317   @param  Status        Return status for the executed command.
 318                         This is an optional parameter and may be NULL.
 319                         RETURN_SUCCESS The SMBUS command was executed.
 320                         RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 321                         RETURN_DEVICE_ERROR  The request was not completed because a failure
 322                         reflected in the Host Status Register bit.  Device errors are a result
 323                         of a transaction collision, illegal command field, unclaimed cycle
 324                         (host initiated), or bus errors (collisions).
 325                         RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect)
 326                         RETURN_UNSUPPORTED  The SMBus operation is not supported.
 327
 328   @return The parameter of Value.
 329
 330 **/
 331 UINT16
 332 EFIAPI
 333 SmBusWriteDataWord (
 334   IN  UINTN          SmBusAddress,
 335   IN  UINT16         Value,
 336   OUT RETURN_STATUS  *Status        OPTIONAL
 337   );
 338
 339 /**
 340   Executes an SMBUS process call command.
 341
 342   Executes an SMBUS process call command on the SMBUS device specified by SmBusAddress.
 343   The 16-bit value specified by Value is written.
 344   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 345   The 16-bit value returned by the process call command is returned.
 346   If Status is not NULL, then the status of the executed command is returned in Status.
 347   If Length in SmBusAddress is not zero, then ASSERT().
 348   If any reserved bits of SmBusAddress are set, then ASSERT().
 349
 350   @param  SmBusAddress  Address that encodes the SMBUS Slave Address,
 351                         SMBUS Command, SMBUS Data Length, and PEC.
 352   @param  Value         The 16-bit value to write.
 353   @param  Status        Return status for the executed command.
 354                         This is an optional parameter and may be NULL.
 355                         RETURN_SUCCESS The SMBUS command was executed.
 356                         RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 357                         RETURN_DEVICE_ERROR  The request was not completed because a failure
 358                         reflected in the Host Status Register bit.  Device errors are a result
 359                         of a transaction collision, illegal command field, unclaimed cycle
 360                         (host initiated), or bus errors (collisions).
 361                         RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect)
 362                         RETURN_UNSUPPORTED  The SMBus operation is not supported.
 363
 364   @return The 16-bit value returned by the process call command.
 365
 366 **/
 367 UINT16
 368 EFIAPI
 369 SmBusProcessCall (
 370   IN  UINTN          SmBusAddress,
 371   IN  UINT16         Value,
 372   OUT RETURN_STATUS  *Status        OPTIONAL
 373   );
 374
 375 /**
 376   Executes an SMBUS read block command.
 377
 378   Executes an SMBUS read block command on the SMBUS device specified by SmBusAddress.
 379   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 380   Bytes are read from the SMBUS and stored in Buffer.
 381   The number of bytes read is returned, and will never return a value larger than 32-bytes.
 382   If Status is not NULL, then the status of the executed command is returned in Status.
 383   It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
 384   SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes.
 385   If Length in SmBusAddress is not zero, then ASSERT().
 386   If Buffer is NULL, then ASSERT().
 387   If any reserved bits of SmBusAddress are set, then ASSERT().
 388
 389   @param  SmBusAddress  Address that encodes the SMBUS Slave Address,
 390                         SMBUS Command, SMBUS Data Length, and PEC.
 391   @param  Buffer        Pointer to the buffer to store the bytes read from the SMBUS.
 392   @param  Status        Return status for the executed command.
 393                         This is an optional parameter and may be NULL.
 394                         RETURN_SUCCESS The SMBUS command was executed.
 395                         RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 396                         RETURN_DEVICE_ERROR  The request was not completed because a failure
 397                         reflected in the Host Status Register bit.  Device errors are a result
 398                         of a transaction collision, illegal command field, unclaimed cycle
 399                         (host initiated), or bus errors (collisions).
 400                         RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect)
 401                         RETURN_UNSUPPORTED  The SMBus operation is not supported.
 402
 403   @return The number of bytes read.
 404
 405 **/
 406 UINTN
 407 EFIAPI
 408 SmBusReadBlock (
 409   IN  UINTN          SmBusAddress,
 410   OUT VOID           *Buffer,
 411   OUT RETURN_STATUS  *Status        OPTIONAL
 412   );
 413
 414 /**
 415   Executes an SMBUS write block command.
 416
 417   Executes an SMBUS write block command on the SMBUS device specified by SmBusAddress.
 418   The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required.
 419   Bytes are written to the SMBUS from Buffer.
 420   The number of bytes written is returned, and will never return a value larger than 32-bytes.
 421   If Status is not NULL, then the status of the executed command is returned in Status.
 422   If Length in SmBusAddress is zero or greater than 32, then ASSERT().
 423   If Buffer is NULL, then ASSERT().
 424   If any reserved bits of SmBusAddress are set, then ASSERT().
 425
 426   @param  SmBusAddress  Address that encodes the SMBUS Slave Address,
 427                         SMBUS Command, SMBUS Data Length, and PEC.
 428   @param  Buffer        Pointer to the buffer to store the bytes read from the SMBUS.
 429   @param  Status        Return status for the executed command.
 430                         This is an optional parameter and may be NULL.
 431                         RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 432                         RETURN_DEVICE_ERROR  The request was not completed because a failure
 433                         reflected in the Host Status Register bit.  Device errors are a result
 434                         of a transaction collision, illegal command field, unclaimed cycle
 435                         (host initiated), or bus errors (collisions).
 436                         RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect)
 437                         RETURN_UNSUPPORTED  The SMBus operation is not supported.
 438
 439   @return The number of bytes written.
 440
 441 **/
 442 UINTN
 443 EFIAPI
 444 SmBusWriteBlock (
 445   IN  UINTN          SmBusAddress,
 446   OUT VOID           *Buffer,
 447   OUT RETURN_STATUS  *Status        OPTIONAL
 448   );
 449
 450 /**
 451   Executes an SMBUS block process call command.
 452
 453   Executes an SMBUS block process call command on the SMBUS device specified by SmBusAddress.
 454   The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required.
 455   Bytes are written to the SMBUS from WriteBuffer.  Bytes are then read from the SMBUS into ReadBuffer.
 456   If Status is not NULL, then the status of the executed command is returned in Status.
 457   It is the caller's responsibility to make sure ReadBuffer is large enough for the total number of bytes read.
 458   SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes.
 459   If Length in SmBusAddress is zero or greater than 32, then ASSERT().
 460   If WriteBuffer is NULL, then ASSERT().
 461   If ReadBuffer is NULL, then ASSERT().
 462   If any reserved bits of SmBusAddress are set, then ASSERT().
 463
 464   @param  SmBusAddress  Address that encodes the SMBUS Slave Address,
 465                         SMBUS Command, SMBUS Data Length, and PEC.
 466   @param  WriteBuffer   Pointer to the buffer of bytes to write to the SMBUS.
 467   @param  ReadBuffer    Pointer to the buffer of bytes to read from the SMBUS.
 468   @param  Status        Return status for the executed command.
 469                         This is an optional parameter and may be NULL.
 470                         RETURN_TIMEOUT A timeout occurred while executing the SMBUS command.
 471                         RETURN_DEVICE_ERROR  The request was not completed because a failure
 472                         reflected in the Host Status Register bit.  Device errors are a result
 473                         of a transaction collision, illegal command field, unclaimed cycle
 474                         (host initiated), or bus errors (collisions).
 475                         RETURN_CRC_ERROR  The checksum is not correct (PEC is incorrect)
 476                         RETURN_UNSUPPORTED  The SMBus operation is not supported.
 477
 478   @return The number of bytes written.
 479
 480 **/
 481 UINTN
 482 EFIAPI
 483 SmBusBlockProcessCall (
 484   IN  UINTN          SmBusAddress,
 485   IN  VOID           *WriteBuffer,
 486   OUT VOID           *ReadBuffer,
 487   OUT RETURN_STATUS  *Status        OPTIONAL
 488   );
 489
 490 #endif