EdkCompatibilityPkg/Foundation/Library/EdkIIGlueLib/Include/Library/EdkIIGlueSmbusLib.h

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