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