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