MdePkg/Include/Library/SmbusLib.h

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