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