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