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. All rights reserved.<BR> 6 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) & ~(BIT23 - 2)) 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 RETURN_SUCCESS The SMBUS command was executed. 91 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 92 RETURN_DEVICE_ERROR The request was not completed because a failure 93 reflected in the Host Status Register bit. Device errors are a result 94 of a transaction collision, illegal command field, unclaimed cycle 95 (host initiated), or bus errors (collisions). 96 RETURN_UNSUPPORTED The SMBus operation is not supported. 97 98 **/ 99 VOID 100 EFIAPI 101 SmBusQuickRead ( 102 IN UINTN SmBusAddress, 103 OUT RETURN_STATUS *Status OPTIONAL 104 ); 105 106 /** 107 Executes an SMBUS quick write command. 108 109 Executes an SMBUS quick write command on the SMBUS device specified by SmBusAddress. 110 Only the SMBUS slave address field of SmBusAddress is required. 111 If Status is not NULL, then the status of the executed command is returned in Status. 112 If PEC is set in SmBusAddress, then ASSERT(). 113 If Command in SmBusAddress is not zero, then ASSERT(). 114 If Length in SmBusAddress is not zero, then ASSERT(). 115 If any reserved bits of SmBusAddress are set, then ASSERT(). 116 117 @param SmBusAddress Address that encodes the SMBUS Slave Address, 118 SMBUS Command, SMBUS Data Length, and PEC. 119 @param Status Return status for the executed command. 120 This is an optional parameter and may be NULL. 121 RETURN_SUCCESS The SMBUS command was executed. 122 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 123 RETURN_DEVICE_ERROR The request was not completed because a failure 124 reflected in the Host Status Register bit. Device errors are a result 125 of a transaction collision, illegal command field, unclaimed cycle 126 (host initiated), or bus errors (collisions). 127 RETURN_UNSUPPORTED The SMBus operation is not supported. 128 129 **/ 130 VOID 131 EFIAPI 132 SmBusQuickWrite ( 133 IN UINTN SmBusAddress, 134 OUT RETURN_STATUS *Status OPTIONAL 135 ); 136 137 /** 138 Executes an SMBUS receive byte command. 139 140 Executes an SMBUS receive byte command on the SMBUS device specified by SmBusAddress. 141 Only the SMBUS slave address field of SmBusAddress is required. 142 The byte received from the SMBUS is returned. 143 If Status is not NULL, then the status of the executed command is returned in Status. 144 If Command in SmBusAddress is not zero, then ASSERT(). 145 If Length in SmBusAddress is not zero, then ASSERT(). 146 If any reserved bits of SmBusAddress are set, then ASSERT(). 147 148 @param SmBusAddress Address that encodes the SMBUS Slave Address, 149 SMBUS Command, SMBUS Data Length, and PEC. 150 @param Status Return status for the executed command. 151 This is an optional parameter and may be NULL. 152 RETURN_SUCCESS The SMBUS command was executed. 153 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 154 RETURN_DEVICE_ERROR The request was not completed because a failure 155 reflected in the Host Status Register bit. Device errors are a result 156 of a transaction collision, illegal command field, unclaimed cycle 157 (host initiated), or bus errors (collisions). 158 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect) 159 RETURN_UNSUPPORTED The SMBus operation is not supported. 160 161 @return The byte received from the SMBUS. 162 163 **/ 164 UINT8 165 EFIAPI 166 SmBusReceiveByte ( 167 IN UINTN SmBusAddress, 168 OUT RETURN_STATUS *Status OPTIONAL 169 ); 170 171 /** 172 Executes an SMBUS send byte command. 173 174 Executes an SMBUS send byte command on the SMBUS device specified by SmBusAddress. 175 The byte specified by Value is sent. 176 Only the SMBUS slave address field of SmBusAddress is required. Value is returned. 177 If Status is not NULL, then the status of the executed command is returned in Status. 178 If Command in SmBusAddress is not zero, then ASSERT(). 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 send. 185 @param Status Return status for the executed command. 186 This is an optional parameter and may be NULL. 187 RETURN_SUCCESS The SMBUS command was executed. 188 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 189 RETURN_DEVICE_ERROR The request was not completed because a failure 190 reflected in the Host Status Register bit. Device errors are a result 191 of a transaction collision, illegal command field, unclaimed cycle 192 (host initiated), or bus errors (collisions). 193 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect) 194 RETURN_UNSUPPORTED The SMBus operation is not supported. 195 196 @return The parameter of Value. 197 198 **/ 199 UINT8 200 EFIAPI 201 SmBusSendByte ( 202 IN UINTN SmBusAddress, 203 IN UINT8 Value, 204 OUT RETURN_STATUS *Status OPTIONAL 205 ); 206 207 /** 208 Executes an SMBUS read data byte command. 209 210 Executes an SMBUS read data byte command on the SMBUS device specified by SmBusAddress. 211 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 212 The 8-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 RETURN_SUCCESS The SMBUS command was executed. 222 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 223 RETURN_DEVICE_ERROR The request was not completed because a failure 224 reflected in the Host Status Register bit. Device errors are a result 225 of a transaction collision, illegal command field, unclaimed cycle 226 (host initiated), or bus errors (collisions). 227 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect) 228 RETURN_UNSUPPORTED The SMBus operation is not supported. 229 230 @return The byte read from the SMBUS. 231 232 **/ 233 UINT8 234 EFIAPI 235 SmBusReadDataByte ( 236 IN UINTN SmBusAddress, 237 OUT RETURN_STATUS *Status OPTIONAL 238 ); 239 240 /** 241 Executes an SMBUS write data byte command. 242 243 Executes an SMBUS write data byte command on the SMBUS device specified by SmBusAddress. 244 The 8-bit value specified by Value is written. 245 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 246 Value is returned. 247 If Status is not NULL, then the status of the executed command is returned in Status. 248 If Length in SmBusAddress is not zero, then ASSERT(). 249 If any reserved bits of SmBusAddress are set, then ASSERT(). 250 251 @param SmBusAddress Address that encodes the SMBUS Slave Address, 252 SMBUS Command, SMBUS Data Length, and PEC. 253 @param Value The 8-bit value to write. 254 @param Status Return status for the executed command. 255 This is an optional parameter and may be NULL. 256 RETURN_SUCCESS The SMBUS command was executed. 257 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 258 RETURN_DEVICE_ERROR The request was not completed because a failure 259 reflected in the Host Status Register bit. Device errors are a result 260 of a transaction collision, illegal command field, unclaimed cycle 261 (host initiated), or bus errors (collisions). 262 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect) 263 RETURN_UNSUPPORTED The SMBus operation is not supported. 264 265 @return The parameter of Value. 266 267 **/ 268 UINT8 269 EFIAPI 270 SmBusWriteDataByte ( 271 IN UINTN SmBusAddress, 272 IN UINT8 Value, 273 OUT RETURN_STATUS *Status OPTIONAL 274 ); 275 276 /** 277 Executes an SMBUS read data word command. 278 279 Executes an SMBUS read data word command on the SMBUS device specified by SmBusAddress. 280 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 281 The 16-bit value read from the SMBUS is returned. 282 If Status is not NULL, then the status of the executed command is returned in Status. 283 If Length in SmBusAddress is not zero, then ASSERT(). 284 If any reserved bits of SmBusAddress are set, then ASSERT(). 285 286 @param SmBusAddress Address that encodes the SMBUS Slave Address, 287 SMBUS Command, SMBUS Data Length, and PEC. 288 @param Status Return status for the executed command. 289 This is an optional parameter and may be NULL. 290 RETURN_SUCCESS The SMBUS command was executed. 291 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 292 RETURN_DEVICE_ERROR The request was not completed because a failure 293 reflected in the Host Status Register bit. Device errors are a result 294 of a transaction collision, illegal command field, unclaimed cycle 295 (host initiated), or bus errors (collisions). 296 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect) 297 RETURN_UNSUPPORTED The SMBus operation is not supported. 298 299 @return The byte read from the SMBUS. 300 301 **/ 302 UINT16 303 EFIAPI 304 SmBusReadDataWord ( 305 IN UINTN SmBusAddress, 306 OUT RETURN_STATUS *Status OPTIONAL 307 ); 308 309 /** 310 Executes an SMBUS write data word command. 311 312 Executes an SMBUS write data word command on the SMBUS device specified by SmBusAddress. 313 The 16-bit value specified by Value is written. 314 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 315 Value is returned. 316 If Status is not NULL, then the status of the executed command is returned in Status. 317 If Length in SmBusAddress is not zero, then ASSERT(). 318 If any reserved bits of SmBusAddress are set, then ASSERT(). 319 320 @param SmBusAddress Address that encodes the SMBUS Slave Address, 321 SMBUS Command, SMBUS Data Length, and PEC. 322 @param Value The 16-bit value to write. 323 @param Status Return status for the executed command. 324 This is an optional parameter and may be NULL. 325 RETURN_SUCCESS The SMBUS command was executed. 326 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 327 RETURN_DEVICE_ERROR The request was not completed because a failure 328 reflected in the Host Status Register bit. Device errors are a result 329 of a transaction collision, illegal command field, unclaimed cycle 330 (host initiated), or bus errors (collisions). 331 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect) 332 RETURN_UNSUPPORTED The SMBus operation is not supported. 333 334 @return The parameter of Value. 335 336 **/ 337 UINT16 338 EFIAPI 339 SmBusWriteDataWord ( 340 IN UINTN SmBusAddress, 341 IN UINT16 Value, 342 OUT RETURN_STATUS *Status OPTIONAL 343 ); 344 345 /** 346 Executes an SMBUS process call command. 347 348 Executes an SMBUS process call command on the SMBUS device specified by SmBusAddress. 349 The 16-bit value specified by Value is written. 350 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 351 The 16-bit value returned by the process call command is returned. 352 If Status is not NULL, then the status of the executed command is returned in Status. 353 If Length in SmBusAddress is not zero, then ASSERT(). 354 If any reserved bits of SmBusAddress are set, then ASSERT(). 355 356 @param SmBusAddress Address that encodes the SMBUS Slave Address, 357 SMBUS Command, SMBUS Data Length, and PEC. 358 @param Value The 16-bit value to write. 359 @param Status Return status for the executed command. 360 This is an optional parameter and may be NULL. 361 RETURN_SUCCESS The SMBUS command was executed. 362 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 363 RETURN_DEVICE_ERROR The request was not completed because a failure 364 reflected in the Host Status Register bit. Device errors are a result 365 of a transaction collision, illegal command field, unclaimed cycle 366 (host initiated), or bus errors (collisions). 367 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect) 368 RETURN_UNSUPPORTED The SMBus operation is not supported. 369 370 @return The 16-bit value returned by the process call command. 371 372 **/ 373 UINT16 374 EFIAPI 375 SmBusProcessCall ( 376 IN UINTN SmBusAddress, 377 IN UINT16 Value, 378 OUT RETURN_STATUS *Status OPTIONAL 379 ); 380 381 /** 382 Executes an SMBUS read block command. 383 384 Executes an SMBUS read block command on the SMBUS device specified by SmBusAddress. 385 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 386 Bytes are read from the SMBUS and stored in Buffer. 387 The number of bytes read is returned, and will never return a value larger than 32-bytes. 388 If Status is not NULL, then the status of the executed command is returned in Status. 389 It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read. 390 SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes. 391 If Length in SmBusAddress is not zero, then ASSERT(). 392 If Buffer is NULL, then ASSERT(). 393 If any reserved bits of SmBusAddress are set, then ASSERT(). 394 395 @param SmBusAddress Address that encodes the SMBUS Slave Address, 396 SMBUS Command, SMBUS Data Length, and PEC. 397 @param Buffer Pointer to the buffer to store the bytes read from the SMBUS. 398 @param Status Return status for the executed command. 399 This is an optional parameter and may be NULL. 400 RETURN_SUCCESS The SMBUS command was executed. 401 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 402 RETURN_DEVICE_ERROR The request was not completed because a failure 403 reflected in the Host Status Register bit. Device errors are a result 404 of a transaction collision, illegal command field, unclaimed cycle 405 (host initiated), or bus errors (collisions). 406 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect) 407 RETURN_UNSUPPORTED The SMBus operation is not supported. 408 409 @return The number of bytes read. 410 411 **/ 412 UINTN 413 EFIAPI 414 SmBusReadBlock ( 415 IN UINTN SmBusAddress, 416 OUT VOID *Buffer, 417 OUT RETURN_STATUS *Status OPTIONAL 418 ); 419 420 /** 421 Executes an SMBUS write block command. 422 423 Executes an SMBUS write block command on the SMBUS device specified by SmBusAddress. 424 The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required. 425 Bytes are written to the SMBUS from Buffer. 426 The number of bytes written is returned, and will never return a value larger than 32-bytes. 427 If Status is not NULL, then the status of the executed command is returned in Status. 428 If Length in SmBusAddress is zero or greater than 32, then ASSERT(). 429 If Buffer is NULL, then ASSERT(). 430 If any reserved bits of SmBusAddress are set, then ASSERT(). 431 432 @param SmBusAddress Address that encodes the SMBUS Slave Address, 433 SMBUS Command, SMBUS Data Length, and PEC. 434 @param Buffer Pointer to the buffer to store the bytes read from the SMBUS. 435 @param Status Return status for the executed command. 436 This is an optional parameter and may be NULL. 437 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 438 RETURN_DEVICE_ERROR The request was not completed because a failure 439 reflected in the Host Status Register bit. Device errors are a result 440 of a transaction collision, illegal command field, unclaimed cycle 441 (host initiated), or bus errors (collisions). 442 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect) 443 RETURN_UNSUPPORTED The SMBus operation is not supported. 444 445 @return The number of bytes written. 446 447 **/ 448 UINTN 449 EFIAPI 450 SmBusWriteBlock ( 451 IN UINTN SmBusAddress, 452 OUT VOID *Buffer, 453 OUT RETURN_STATUS *Status OPTIONAL 454 ); 455 456 /** 457 Executes an SMBUS block process call command. 458 459 Executes an SMBUS block process call command on the SMBUS device specified by SmBusAddress. 460 The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required. 461 Bytes are written to the SMBUS from WriteBuffer. Bytes are then read from the SMBUS into ReadBuffer. 462 If Status is not NULL, then the status of the executed command is returned in Status. 463 It is the caller's responsibility to make sure ReadBuffer is large enough for the total number of bytes read. 464 SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes. 465 If Length in SmBusAddress is zero or greater than 32, then ASSERT(). 466 If WriteBuffer is NULL, then ASSERT(). 467 If ReadBuffer is NULL, then ASSERT(). 468 If any reserved bits of SmBusAddress are set, then ASSERT(). 469 470 @param SmBusAddress Address that encodes the SMBUS Slave Address, 471 SMBUS Command, SMBUS Data Length, and PEC. 472 @param WriteBuffer Pointer to the buffer of bytes to write to the SMBUS. 473 @param ReadBuffer Pointer to the buffer of bytes to read from the SMBUS. 474 @param Status Return status for the executed command. 475 This is an optional parameter and may be NULL. 476 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 477 RETURN_DEVICE_ERROR The request was not completed because a failure 478 reflected in the Host Status Register bit. Device errors are a result 479 of a transaction collision, illegal command field, unclaimed cycle 480 (host initiated), or bus errors (collisions). 481 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect) 482 RETURN_UNSUPPORTED The SMBus operation is not supported. 483 484 @return The number of bytes written. 485 486 **/ 487 UINTN 488 EFIAPI 489 SmBusBlockProcessCall ( 490 IN UINTN SmBusAddress, 491 IN VOID *WriteBuffer, 492 OUT VOID *ReadBuffer, 493 OUT RETURN_STATUS *Status OPTIONAL 494 ); 495 496 497 #endif 498