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 /**
  70   Executes an SMBUS quick write command.
  71
  72   Executes an SMBUS quick write 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
  85 **/
  86 VOID
  87 EFIAPI
  88 SmBusQuickWrite (
  89   IN  UINTN                     SmBusAddress,
  90   OUT RETURN_STATUS             *Status       OPTIONAL
  91   )
  92 ;
  93
  94 /**
  95   Executes an SMBUS receive byte command.
  96
  97   Executes an SMBUS receive byte command on the SMBUS device specified by SmBusAddress.
  98   Only the SMBUS slave address field of SmBusAddress is required.
  99   The byte received from the SMBUS is returned.
 100   If Status is not NULL, then the status of the executed command is returned in Status.
 101   If Command in SmBusAddress is not zero, then ASSERT().
 102   If Length in SmBusAddress is not zero, then ASSERT().
 103   If any reserved bits of SmBusAddress are set, then ASSERT().
 104
 105   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 106                           SMBUS Command, SMBUS Data Length, and PEC.
 107   @param  Status          Return status for the executed command.
 108                           This is an optional parameter and may be NULL.
 109
 110   @return The byte received from the SMBUS.
 111
 112 **/
 113 UINT8
 114 EFIAPI
 115 SmBusReceiveByte (
 116   IN  UINTN          SmBusAddress,
 117   OUT RETURN_STATUS  *Status        OPTIONAL
 118   )
 119 ;
 120
 121 /**
 122   Executes an SMBUS send byte command.
 123
 124   Executes an SMBUS send byte command on the SMBUS device specified by SmBusAddress.
 125   The byte specified by Value is sent.
 126   Only the SMBUS slave address field of SmBusAddress is required.  Value is returned.
 127   If Status is not NULL, then the status of the executed command is returned in Status.
 128   If Command in SmBusAddress is not zero, then ASSERT().
 129   If Length in SmBusAddress is not zero, then ASSERT().
 130   If any reserved bits of SmBusAddress are set, then ASSERT().
 131
 132   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 133                           SMBUS Command, SMBUS Data Length, and PEC.
 134   @param  Value           The 8-bit value to send.
 135   @param  Status          Return status for the executed command.
 136                           This is an optional parameter and may be NULL.
 137
 138   @return The parameter of Value.
 139
 140 **/
 141 UINT8
 142 EFIAPI
 143 SmBusSendByte (
 144   IN  UINTN          SmBusAddress,
 145   IN  UINT8          Value,
 146   OUT RETURN_STATUS  *Status        OPTIONAL
 147   )
 148 ;
 149
 150 /**
 151   Executes an SMBUS read data byte command.
 152
 153   Executes an SMBUS read data byte command on the SMBUS device specified by SmBusAddress.
 154   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 155   The 8-bit value read from the SMBUS is returned.
 156   If Status is not NULL, then the status of the executed command is returned in Status.
 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  Status          Return status for the executed command.
 163                           This is an optional parameter and may be NULL.
 164
 165   @return The byte read from the SMBUS.
 166
 167 **/
 168 UINT8
 169 EFIAPI
 170 SmBusReadDataByte (
 171   IN  UINTN          SmBusAddress,
 172   OUT RETURN_STATUS  *Status        OPTIONAL
 173   )
 174 ;
 175
 176 /**
 177   Executes an SMBUS write data byte command.
 178
 179   Executes an SMBUS write data byte command on the SMBUS device specified by SmBusAddress.
 180   The 8-bit value specified by Value is written.
 181   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 182   Value 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  Value           The 8-bit value to write.
 190   @param  Status          Return status for the executed command.
 191                           This is an optional parameter and may be NULL.
 192
 193   @return The parameter of Value.
 194
 195 **/
 196 UINT8
 197 EFIAPI
 198 SmBusWriteDataByte (
 199   IN  UINTN          SmBusAddress,
 200   IN  UINT8          Value,
 201   OUT RETURN_STATUS  *Status        OPTIONAL
 202   )
 203 ;
 204
 205 /**
 206   Executes an SMBUS read data word command.
 207
 208   Executes an SMBUS read data word command on the SMBUS device specified by SmBusAddress.
 209   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 210   The 16-bit value read from the SMBUS is returned.
 211   If Status is not NULL, then the status of the executed command is returned in Status.
 212   If Length in SmBusAddress is not zero, then ASSERT().
 213   If any reserved bits of SmBusAddress are set, then ASSERT().
 214
 215   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 216                           SMBUS Command, SMBUS Data Length, and PEC.
 217   @param  Status          Return status for the executed command.
 218                           This is an optional parameter and may be NULL.
 219
 220   @return The byte read from the SMBUS.
 221
 222 **/
 223 UINT16
 224 EFIAPI
 225 SmBusReadDataWord (
 226   IN  UINTN          SmBusAddress,
 227   OUT RETURN_STATUS  *Status        OPTIONAL
 228   )
 229 ;
 230
 231 /**
 232   Executes an SMBUS write data word command.
 233
 234   Executes an SMBUS write data word command on the SMBUS device specified by SmBusAddress.
 235   The 16-bit value specified by Value is written.
 236   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 237   Value is returned.
 238   If Status is not NULL, then the status of the executed command is returned in Status.
 239   If Length in SmBusAddress is not zero, then ASSERT().
 240   If any reserved bits of SmBusAddress are set, then ASSERT().
 241
 242   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 243                           SMBUS Command, SMBUS Data Length, and PEC.
 244   @param  Value           The 16-bit value to write.
 245   @param  Status          Return status for the executed command.
 246                           This is an optional parameter and may be NULL.
 247
 248   @return The parameter of Value.
 249
 250 **/
 251 UINT16
 252 EFIAPI
 253 SmBusWriteDataWord (
 254   IN  UINTN          SmBusAddress,
 255   IN  UINT16         Value,
 256   OUT RETURN_STATUS  *Status        OPTIONAL
 257   )
 258 ;
 259
 260 /**
 261   Executes an SMBUS process call command.
 262
 263   Executes an SMBUS process call command on the SMBUS device specified by SmBusAddress.
 264   The 16-bit value specified by Value is written.
 265   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 266   The 16-bit value returned by the process call command is returned.
 267   If Status is not NULL, then the status of the executed command is returned in Status.
 268   If Length in SmBusAddress is not zero, then ASSERT().
 269   If any reserved bits of SmBusAddress are set, then ASSERT().
 270
 271   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 272                           SMBUS Command, SMBUS Data Length, and PEC.
 273   @param  Value           The 16-bit value to write.
 274   @param  Status          Return status for the executed command.
 275                           This is an optional parameter and may be NULL.
 276
 277   @return The 16-bit value returned by the process call command.
 278
 279 **/
 280 UINT16
 281 EFIAPI
 282 SmBusProcessCall (
 283   IN  UINTN          SmBusAddress,
 284   IN  UINT16         Value,
 285   OUT RETURN_STATUS  *Status        OPTIONAL
 286   )
 287 ;
 288
 289 /**
 290   Executes an SMBUS read block command.
 291
 292   Executes an SMBUS read block command on the SMBUS device specified by SmBusAddress.
 293   Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required.
 294   Bytes are read from the SMBUS and stored in Buffer.
 295   The number of bytes read is returned, and will never return a value larger than 32-bytes.
 296   If Status is not NULL, then the status of the executed command is returned in Status.
 297   It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
 298   SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes.
 299   If Length in SmBusAddress is not zero, then ASSERT().
 300   If Buffer is NULL, then ASSERT().
 301   If any reserved bits of SmBusAddress are set, then ASSERT().
 302
 303   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 304                           SMBUS Command, SMBUS Data Length, and PEC.
 305   @param  Buffer          Pointer to the buffer to store the bytes read from the SMBUS.
 306   @param  Status          Return status for the executed command.
 307                           This is an optional parameter and may be NULL.
 308
 309   @return The number of bytes read.
 310
 311 **/
 312 UINTN
 313 EFIAPI
 314 SmBusReadBlock (
 315   IN  UINTN          SmBusAddress,
 316   OUT VOID           *Buffer,
 317   OUT RETURN_STATUS  *Status        OPTIONAL
 318   )
 319 ;
 320
 321 /**
 322   Executes an SMBUS write block command.
 323
 324   Executes an SMBUS write block command on the SMBUS device specified by SmBusAddress.
 325   The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required.
 326   Bytes are written to the SMBUS from Buffer.
 327   The number of bytes written is returned, and will never return a value larger than 32-bytes.
 328   If Status is not NULL, then the status of the executed command is returned in Status.
 329   If Length in SmBusAddress is zero or greater than 32, then ASSERT().
 330   If Buffer is NULL, then ASSERT().
 331   If any reserved bits of SmBusAddress are set, then ASSERT().
 332
 333   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 334                           SMBUS Command, SMBUS Data Length, and PEC.
 335   @param  Buffer          Pointer to the buffer to store the bytes read from the SMBUS.
 336   @param  Status          Return status for the executed command.
 337                           This is an optional parameter and may be NULL.
 338
 339   @return The number of bytes written.
 340
 341 **/
 342 UINTN
 343 EFIAPI
 344 SmBusWriteBlock (
 345   IN  UINTN          SmBusAddress,
 346   OUT VOID           *Buffer,
 347   OUT RETURN_STATUS  *Status        OPTIONAL
 348   )
 349 ;
 350
 351 /**
 352   Executes an SMBUS block process call command.
 353
 354   Executes an SMBUS block process call command on the SMBUS device specified by SmBusAddress.
 355   The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required.
 356   Bytes are written to the SMBUS from WriteBuffer.  Bytes are then read from the SMBUS into ReadBuffer.
 357   If Status is not NULL, then the status of the executed command is returned in Status.
 358   It is the caller's responsibility to make sure ReadBuffer is large enough for the total number of bytes read.
 359   SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes.
 360   If Length in SmBusAddress is zero or greater than 32, then ASSERT().
 361   If WriteBuffer is NULL, then ASSERT().
 362   If ReadBuffer is NULL, then ASSERT().
 363   If any reserved bits of SmBusAddress are set, then ASSERT().
 364
 365   @param  SmBusAddress    Address that encodes the SMBUS Slave Address,
 366                           SMBUS Command, SMBUS Data Length, and PEC.
 367   @param  WriteBuffer     Pointer to the buffer of bytes to write to the SMBUS.
 368   @param  ReadBuffer      Pointer to the buffer of bytes to read from the SMBUS.
 369   @param  Status          Return status for the executed command.
 370                           This is an optional parameter and may be NULL.
 371
 372   @return The number of bytes written.
 373
 374 **/
 375 UINTN
 376 EFIAPI
 377 SmBusBlockProcessCall (
 378   IN  UINTN          SmBusAddress,
 379   IN  VOID           *WriteBuffer,
 380   OUT VOID           *ReadBuffer,
 381   OUT RETURN_STATUS  *Status        OPTIONAL
 382   )
 383 ;
 384
 385
 386 #endif