1 /** @file 2 Smbus Library Services that conduct SMBus transactions and enable the operatation 3 to be replayed during an S3 resume. This library class maps directly on top 4 of the SmbusLib class. 5 6 Copyright (c) 2007 - 2010, Intel Corporation. All rights reserved.<BR> 7 8 This program and the accompanying materials 9 are licensed and made available under the terms and conditions 10 of the BSD License which accompanies this distribution. The 11 full text of the license may be found at 12 http://opensource.org/licenses/bsd-license.php 13 14 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 15 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 16 17 **/ 18 19 #ifndef __S3_SMBUS_LIB_H__ 20 #define __S3_SMBUS_LIB_H__ 21 22 /** 23 Executes an SMBUS quick read command, and saves the value in the S3 script to be replayed 24 on S3 resume. 25 26 Executes an SMBUS quick read command on the SMBUS device specified by SmBusAddress. 27 Only the SMBUS slave address field of SmBusAddress is required. 28 If Status is not NULL, then the status of the executed command is returned in Status. 29 If PEC is set in SmBusAddress, then ASSERT(). 30 If Command in SmBusAddress is not zero, then ASSERT(). 31 If Length in SmBusAddress is not zero, then ASSERT(). 32 If any reserved bits of SmBusAddress are set, then ASSERT(). 33 34 @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, 35 SMBUS Command, SMBUS Data Length, and PEC. 36 @param[out] Status The return status for the executed command. 37 This is an optional parameter and may be NULL. 38 RETURN_SUCCESS The SMBUS command was executed. 39 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 40 RETURN_DEVICE_ERROR The request was not completed because a failure 41 was recorded in the Host Status Register bit. Device errors are a result 42 of a transaction collision, illegal command field, unclaimed cycle 43 (host initiated), or bus error (collision). 44 RETURN_UNSUPPORTED The SMBus operation is not supported. 45 46 **/ 47 VOID 48 EFIAPI 49 S3SmBusQuickRead ( 50 IN UINTN SmBusAddress, 51 OUT RETURN_STATUS *Status OPTIONAL 52 ); 53 54 /** 55 Executes an SMBUS quick write command, and saves the value in the S3 script to be replayed 56 on S3 resume. 57 58 Executes an SMBUS quick write command on the SMBUS device specified by SmBusAddress. 59 Only the SMBUS slave address field of SmBusAddress is required. 60 If Status is not NULL, then the status of the executed command is returned in Status. 61 If PEC is set in SmBusAddress, then ASSERT(). 62 If Command in SmBusAddress is not zero, then ASSERT(). 63 If Length in SmBusAddress is not zero, then ASSERT(). 64 If any reserved bits of SmBusAddress are set, then ASSERT(). 65 66 @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, 67 SMBUS Command, SMBUS Data Length, and PEC. 68 @param[out] Status The return status for the executed command. 69 This is an optional parameter and may be NULL. 70 RETURN_SUCCESS The SMBUS command was executed. 71 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 72 RETURN_DEVICE_ERROR The request was not completed because a failure 73 was recorded in the Host Status Register bit. Device errors are a result 74 of a transaction collision, illegal command field, unclaimed cycle 75 (host initiated), or bus error (collision). 76 RETURN_UNSUPPORTED The SMBus operation is not supported. 77 78 **/ 79 VOID 80 EFIAPI 81 S3SmBusQuickWrite ( 82 IN UINTN SmBusAddress, 83 OUT RETURN_STATUS *Status OPTIONAL 84 ); 85 86 /** 87 Executes an SMBUS receive byte command, and saves the value in the S3 script to be replayed 88 on S3 resume. 89 90 Executes an SMBUS receive byte command on the SMBUS device specified by SmBusAddress. 91 Only the SMBUS slave address field of SmBusAddress is required. 92 The byte received from the SMBUS is returned. 93 If Status is not NULL, then the status of the executed command is returned in Status. 94 If Command in SmBusAddress is not zero, then ASSERT(). 95 If Length in SmBusAddress is not zero, then ASSERT(). 96 If any reserved bits of SmBusAddress are set, then ASSERT(). 97 98 @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, 99 SMBUS Command, SMBUS Data Length, and PEC. 100 @param[out] Status The return status for the executed command. 101 This is an optional parameter and may be NULL. 102 RETURN_SUCCESS The SMBUS command was executed. 103 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 104 RETURN_DEVICE_ERROR The request was not completed because a failure 105 was recorded in the Host Status Register bit. Device errors are a result 106 of a transaction collision, illegal command field, unclaimed cycle 107 (host initiated), or bus error (collision). 108 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). 109 RETURN_UNSUPPORTED The SMBus operation is not supported. 110 111 @return The byte received from the SMBUS. 112 113 **/ 114 UINT8 115 EFIAPI 116 S3SmBusReceiveByte ( 117 IN UINTN SmBusAddress, 118 OUT RETURN_STATUS *Status OPTIONAL 119 ); 120 121 /** 122 Executes an SMBUS send byte command, and saves the value in the S3 script to be replayed 123 on S3 resume. 124 125 Executes an SMBUS send byte command on the SMBUS device specified by SmBusAddress. 126 The byte specified by Value is sent. 127 Only the SMBUS slave address field of SmBusAddress is required. Value is returned. 128 If Status is not NULL, then the status of the executed command is returned in Status. 129 If Command in SmBusAddress is not zero, then ASSERT(). 130 If Length in SmBusAddress is not zero, then ASSERT(). 131 If any reserved bits of SmBusAddress are set, then ASSERT(). 132 133 @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, 134 SMBUS Command, SMBUS Data Length, and PEC. 135 @param[in] Value The 8-bit value to send. 136 @param[out] Status The return status for the executed command. 137 This is an optional parameter and may be NULL. 138 RETURN_SUCCESS The SMBUS command was executed. 139 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 140 RETURN_DEVICE_ERROR The request was not completed because a failure 141 was recorded in the Host Status Register bit. Device errors are a result 142 of a transaction collision, illegal command field, unclaimed cycle 143 (host initiated), or bus errors (collisions). 144 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). 145 RETURN_UNSUPPORTED The SMBus operation is not supported. 146 147 @return The parameter of Value. 148 149 **/ 150 UINT8 151 EFIAPI 152 S3SmBusSendByte ( 153 IN UINTN SmBusAddress, 154 IN UINT8 Value, 155 OUT RETURN_STATUS *Status OPTIONAL 156 ); 157 158 /** 159 Executes an SMBUS read data byte command, and saves the value in the S3 script to be replayed 160 on S3 resume. 161 162 Executes an SMBUS read data byte command on the SMBUS device specified by SmBusAddress. 163 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 164 The 8-bit value read from the SMBUS is returned. 165 If Status is not NULL, then the status of the executed command is returned in Status. 166 If Length in SmBusAddress is not zero, then ASSERT(). 167 If any reserved bits of SmBusAddress are set, then ASSERT(). 168 169 @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, 170 SMBUS Command, SMBUS Data Length, and PEC. 171 @param[out] Status The return status for the executed command. 172 This is an optional parameter and may be NULL. 173 RETURN_SUCCESS The SMBUS command was executed. 174 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 175 RETURN_DEVICE_ERROR The request was not completed because a failure 176 was recorded in the Host Status Register bit. Device errors are a result 177 of a transaction collision, illegal command field, unclaimed cycle 178 (host initiated), or bus error (collision). 179 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). 180 RETURN_UNSUPPORTED The SMBus operation is not supported. 181 182 @return The byte read from the SMBUS. 183 184 **/ 185 UINT8 186 EFIAPI 187 S3SmBusReadDataByte ( 188 IN UINTN SmBusAddress, 189 OUT RETURN_STATUS *Status OPTIONAL 190 ); 191 192 /** 193 Executes an SMBUS write data byte command, and saves the value in the S3 script to be replayed 194 on S3 resume. 195 196 Executes an SMBUS write data byte command on the SMBUS device specified by SmBusAddress. 197 The 8-bit value specified by Value is written. 198 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 199 Value is returned. 200 If Status is not NULL, then the status of the executed command is returned in Status. 201 If Length in SmBusAddress is not zero, then ASSERT(). 202 If any reserved bits of SmBusAddress are set, then ASSERT(). 203 204 @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, 205 SMBUS Command, SMBUS Data Length, and PEC. 206 @param[in] Value The 8-bit value to write. 207 @param[out] Status The return status for the executed command. 208 This is an optional parameter and may be NULL. 209 RETURN_SUCCESS The SMBUS command was executed. 210 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 211 RETURN_DEVICE_ERROR The request was not completed because a failure 212 was recorded in the Host Status Register bit. Device errors are a result 213 of a transaction collision, illegal command field, unclaimed cycle 214 (host initiated), or bus error (collision). 215 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). 216 RETURN_UNSUPPORTED The SMBus operation is not supported. 217 218 @return The parameter of Value. 219 220 **/ 221 UINT8 222 EFIAPI 223 S3SmBusWriteDataByte ( 224 IN UINTN SmBusAddress, 225 IN UINT8 Value, 226 OUT RETURN_STATUS *Status OPTIONAL 227 ); 228 229 /** 230 Executes an SMBUS read data word command, and saves the value in the S3 script to be replayed 231 on S3 resume. 232 233 Executes an SMBUS read data word command on the SMBUS device specified by SmBusAddress. 234 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 235 The 16-bit value read from the SMBUS is returned. 236 If Status is not NULL, then the status of the executed command is returned in Status. 237 If Length in SmBusAddress is not zero, then ASSERT(). 238 If any reserved bits of SmBusAddress are set, then ASSERT(). 239 240 @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, 241 SMBUS Command, SMBUS Data Length, and PEC. 242 @param[out] Status The return status for the executed command. 243 This is an optional parameter and may be NULL. 244 RETURN_SUCCESS The SMBUS command was executed. 245 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 246 RETURN_DEVICE_ERROR The request was not completed because a failure 247 was recorded in the Host Status Register bit. Device errors are a result 248 of a transaction collision, illegal command field, unclaimed cycle 249 (host initiated), or bus error (collision). 250 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). 251 RETURN_UNSUPPORTED The SMBus operation is not supported. 252 253 @return The byte read from the SMBUS. 254 255 **/ 256 UINT16 257 EFIAPI 258 S3SmBusReadDataWord ( 259 IN UINTN SmBusAddress, 260 OUT RETURN_STATUS *Status OPTIONAL 261 ); 262 263 /** 264 Executes an SMBUS write data word command, and saves the value in the S3 script to be replayed 265 on S3 resume. 266 267 Executes an SMBUS write data word command on the SMBUS device specified by SmBusAddress. 268 The 16-bit value specified by Value is written. 269 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 270 Value is returned. 271 If Status is not NULL, then the status of the executed command is returned in Status. 272 If Length in SmBusAddress is not zero, then ASSERT(). 273 If any reserved bits of SmBusAddress are set, then ASSERT(). 274 275 @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, 276 SMBUS Command, SMBUS Data Length, and PEC. 277 @param[in] Value The 16-bit value to write. 278 @param[out] Status The return status for the executed command. 279 This is an optional parameter and may be NULL. 280 RETURN_SUCCESS The SMBUS command was executed. 281 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 282 RETURN_DEVICE_ERROR The request was not completed because a failure 283 was recorded in the Host Status Register bit. Device errors are a result 284 of a transaction collision, illegal command field, unclaimed cycle 285 (host initiated), or bus error (collision). 286 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). 287 RETURN_UNSUPPORTED The SMBus operation is not supported. 288 289 @return The parameter of Value. 290 291 **/ 292 UINT16 293 EFIAPI 294 S3SmBusWriteDataWord ( 295 IN UINTN SmBusAddress, 296 IN UINT16 Value, 297 OUT RETURN_STATUS *Status OPTIONAL 298 ); 299 300 /** 301 Executes an SMBUS process call command, and saves the value in the S3 script to be replayed 302 on S3 resume. 303 304 Executes an SMBUS process call command on the SMBUS device specified by SmBusAddress. 305 The 16-bit value specified by Value is written. 306 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 307 The 16-bit value returned by the process call command is returned. 308 If Status is not NULL, then the status of the executed command is returned in Status. 309 If Length in SmBusAddress is not zero, then ASSERT(). 310 If any reserved bits of SmBusAddress are set, then ASSERT(). 311 312 @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, 313 SMBUS Command, SMBUS Data Length, and PEC. 314 @param[in] Value The 16-bit value to write. 315 @param[out] Status The return status for the executed command. 316 This is an optional parameter and may be NULL. 317 RETURN_SUCCESS The SMBUS command was executed. 318 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 319 RETURN_DEVICE_ERROR The request was not completed because a failure 320 was recorded in the Host Status Register bit. Device errors are a result 321 of a transaction collision, illegal command field, unclaimed cycle 322 (host initiated), or bus error (collision). 323 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). 324 RETURN_UNSUPPORTED The SMBus operation is not supported. 325 326 @return The 16-bit value returned by the process call command. 327 328 **/ 329 UINT16 330 EFIAPI 331 S3SmBusProcessCall ( 332 IN UINTN SmBusAddress, 333 IN UINT16 Value, 334 OUT RETURN_STATUS *Status OPTIONAL 335 ); 336 337 /** 338 Executes an SMBUS read block command, and saves the value in the S3 script to be replayed 339 on S3 resume. 340 341 Executes an SMBUS read block command on the SMBUS device specified by SmBusAddress. 342 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 343 Bytes are read from the SMBUS and stored in Buffer. 344 The number of bytes read is returned, and will never return a value larger than 32-bytes. 345 If Status is not NULL, then the status of the executed command is returned in Status. 346 It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read. 347 SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes. 348 If Length in SmBusAddress is not zero, then ASSERT(). 349 If Buffer is NULL, then ASSERT(). 350 If any reserved bits of SmBusAddress are set, then ASSERT(). 351 352 @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, 353 SMBUS Command, SMBUS Data Length, and PEC. 354 @param[out] Buffer The pointer to the buffer to store the bytes read from the SMBUS. 355 @param[out] Status The return status for the executed command. 356 This is an optional parameter and may be NULL. 357 RETURN_SUCCESS The SMBUS command was executed. 358 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 359 RETURN_DEVICE_ERROR The request was not completed because a failure 360 was recorded in the Host Status Register bit. Device errors are a result 361 of a transaction collision, illegal command field, unclaimed cycle 362 (host initiated), or bus error (collision). 363 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). 364 RETURN_UNSUPPORTED The SMBus operation is not supported. 365 366 @return The number of bytes read. 367 368 **/ 369 UINTN 370 EFIAPI 371 S3SmBusReadBlock ( 372 IN UINTN SmBusAddress, 373 OUT VOID *Buffer, 374 OUT RETURN_STATUS *Status OPTIONAL 375 ); 376 377 /** 378 Executes an SMBUS write block command, and saves the value in the S3 script to be replayed 379 on S3 resume. 380 381 Executes an SMBUS write block command on the SMBUS device specified by SmBusAddress. 382 The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required. 383 Bytes are written to the SMBUS from Buffer. 384 The number of bytes written is returned, and will never return a value larger than 32-bytes. 385 If Status is not NULL, then the status of the executed command is returned in Status. 386 If Length in SmBusAddress is zero or greater than 32, then ASSERT(). 387 If Buffer is NULL, then ASSERT(). 388 If any reserved bits of SmBusAddress are set, then ASSERT(). 389 390 @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, 391 SMBUS Command, SMBUS Data Length, and PEC. 392 @param[out] Buffer The pointer to the buffer to store the bytes read from the SMBUS. 393 @param[out] Status The return status for the executed command. 394 This is an optional parameter and may be NULL. 395 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 396 RETURN_DEVICE_ERROR The request was not completed because a failure 397 was recorded in the Host Status Register bit. Device errors are a result 398 of a transaction collision, illegal command field, unclaimed cycle 399 (host initiated), or bus error (collision). 400 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). 401 RETURN_UNSUPPORTED The SMBus operation is not supported. 402 403 @return The number of bytes written. 404 405 **/ 406 UINTN 407 EFIAPI 408 S3SmBusWriteBlock ( 409 IN UINTN SmBusAddress, 410 OUT VOID *Buffer, 411 OUT RETURN_STATUS *Status OPTIONAL 412 ); 413 414 /** 415 Executes an SMBUS block process call command, and saves the value in the S3 script to be replayed 416 on S3 resume. 417 418 Executes an SMBUS block process call command on the SMBUS device specified by SmBusAddress. 419 The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required. 420 Bytes are written to the SMBUS from WriteBuffer. Bytes are then read from the SMBUS into ReadBuffer. 421 If Status is not NULL, then the status of the executed command is returned in Status. 422 It is the caller's responsibility to make sure ReadBuffer is large enough for the total number of bytes read. 423 SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes. 424 If Length in SmBusAddress is zero or greater than 32, then ASSERT(). 425 If WriteBuffer is NULL, then ASSERT(). 426 If ReadBuffer is NULL, then ASSERT(). 427 If any reserved bits of SmBusAddress are set, then ASSERT(). 428 429 @param[in] SmBusAddress The address that encodes the SMBUS Slave Address, 430 SMBUS Command, SMBUS Data Length, and PEC. 431 @param[in] WriteBuffer The pointer to the buffer of bytes to write to the SMBUS. 432 @param[out] ReadBuffer The pointer to the buffer of bytes to read from the SMBUS. 433 @param[out] Status The return status for the executed command. 434 This is an optional parameter and may be NULL. 435 RETURN_TIMEOUT A timeout occurred while executing the SMBUS command. 436 RETURN_DEVICE_ERROR The request was not completed because a failure 437 was recorded in the Host Status Register bit. Device errors are a result 438 of a transaction collision, illegal command field, unclaimed cycle 439 (host initiated), or bus error (collision). 440 RETURN_CRC_ERROR The checksum is not correct (PEC is incorrect). 441 RETURN_UNSUPPORTED The SMBus operation is not supported. 442 443 @return The number of bytes written. 444 445 **/ 446 UINTN 447 EFIAPI 448 S3SmBusBlockProcessCall ( 449 IN UINTN SmBusAddress, 450 IN VOID *WriteBuffer, 451 OUT VOID *ReadBuffer, 452 OUT RETURN_STATUS *Status OPTIONAL 453 ); 454 455 #endif 456