1 /** @file 2 Smbus Library Services that do SMBus transactions and also 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, 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 20 #include <Base.h> 21 22 #include <Library/DebugLib.h> 23 #include <Library/S3BootScriptLib.h> 24 #include <Library/SmbusLib.h> 25 #include <Library/S3SmbusLib.h> 26 27 /** 28 Saves an SMBus operation to S3 script to be replayed on S3 resume. 29 30 This function provides a standard way to save SMBus operation to S3 boot Script. 31 The data can either be of the Length byte, word, or a block of data. 32 If it falis to save S3 boot script, then ASSERT (). 33 34 @param SmbusOperation Signifies which particular SMBus hardware protocol instance that it will use to 35 execute the SMBus transactions. 36 @param SmBusAddress Address that encodes the SMBUS Slave Address, 37 SMBUS Command, SMBUS Data Length, and PEC. 38 @param Length Signifies the number of bytes that this operation will do. The maximum number of 39 bytes can be revision specific and operation specific. 40 @param Buffer Contains the value of data to execute to the SMBus slave device. Not all operations 41 require this argument. The length of this buffer is identified by Length. 42 43 **/ 44 VOID InternalSaveSmBusExecToBootScript(IN EFI_SMBUS_OPERATION SmbusOperation,IN UINTN SmBusAddress,IN UINTN Length,IN OUT VOID * Buffer)45 InternalSaveSmBusExecToBootScript ( 46 IN EFI_SMBUS_OPERATION SmbusOperation, 47 IN UINTN SmBusAddress, 48 IN UINTN Length, 49 IN OUT VOID *Buffer 50 ) 51 { 52 RETURN_STATUS Status; 53 54 Status = S3BootScriptSaveSmbusExecute ( 55 SmBusAddress, 56 SmbusOperation, 57 &Length, 58 Buffer 59 ); 60 ASSERT (Status == RETURN_SUCCESS); 61 } 62 63 /** 64 Executes an SMBUS quick read command and saves the value in the S3 script to be replayed 65 on S3 resume. 66 67 Executes an SMBUS quick read command on the SMBUS device specified by SmBusAddress. 68 Only the SMBUS slave address field of SmBusAddress is required. 69 If Status is not NULL, then the status of the executed command is returned in Status. 70 If PEC is set in SmBusAddress, then ASSERT(). 71 If Command in SmBusAddress is not zero, then ASSERT(). 72 If Length in SmBusAddress is not zero, then ASSERT(). 73 If any reserved bits of SmBusAddress are set, then ASSERT(). 74 75 @param SmBusAddress Address that encodes the SMBUS Slave Address, 76 SMBUS Command, SMBUS Data Length, and PEC. 77 @param Status Return status for the executed command. 78 This is an optional parameter and may be NULL. 79 80 **/ 81 VOID 82 EFIAPI S3SmBusQuickRead(IN UINTN SmBusAddress,OUT RETURN_STATUS * Status OPTIONAL)83 S3SmBusQuickRead ( 84 IN UINTN SmBusAddress, 85 OUT RETURN_STATUS *Status OPTIONAL 86 ) 87 { 88 SmBusQuickRead (SmBusAddress, Status); 89 90 InternalSaveSmBusExecToBootScript (EfiSmbusQuickRead, SmBusAddress, 0, NULL); 91 } 92 93 /** 94 Executes an SMBUS quick write command and saves the value in the S3 script to be replayed 95 on S3 resume. 96 97 Executes an SMBUS quick write command on the SMBUS device specified by SmBusAddress. 98 Only the SMBUS slave address field of SmBusAddress is required. 99 If Status is not NULL, then the status of the executed command is returned in Status. 100 If PEC is set in SmBusAddress, then ASSERT(). 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 **/ 111 VOID 112 EFIAPI S3SmBusQuickWrite(IN UINTN SmBusAddress,OUT RETURN_STATUS * Status OPTIONAL)113 S3SmBusQuickWrite ( 114 IN UINTN SmBusAddress, 115 OUT RETURN_STATUS *Status OPTIONAL 116 ) 117 { 118 SmBusQuickWrite (SmBusAddress, Status); 119 120 InternalSaveSmBusExecToBootScript (EfiSmbusQuickWrite, SmBusAddress, 0, NULL); 121 } 122 123 /** 124 Executes an SMBUS receive byte command and saves the value in the S3 script to be replayed 125 on S3 resume. 126 127 Executes an SMBUS receive byte command on the SMBUS device specified by SmBusAddress. 128 Only the SMBUS slave address field of SmBusAddress is required. 129 The byte received from the SMBUS is returned. 130 If Status is not NULL, then the status of the executed command is returned in Status. 131 If Command in SmBusAddress is not zero, then ASSERT(). 132 If Length in SmBusAddress is not zero, then ASSERT(). 133 If any reserved bits of SmBusAddress are set, then ASSERT(). 134 135 @param SmBusAddress Address that encodes the SMBUS Slave Address, 136 SMBUS Command, SMBUS Data Length, and PEC. 137 @param Status Return status for the executed command. 138 This is an optional parameter and may be NULL. 139 140 @return The byte received from the SMBUS. 141 142 **/ 143 UINT8 144 EFIAPI S3SmBusReceiveByte(IN UINTN SmBusAddress,OUT RETURN_STATUS * Status OPTIONAL)145 S3SmBusReceiveByte ( 146 IN UINTN SmBusAddress, 147 OUT RETURN_STATUS *Status OPTIONAL 148 ) 149 { 150 UINT8 Byte; 151 152 Byte = SmBusReceiveByte (SmBusAddress, Status); 153 154 InternalSaveSmBusExecToBootScript (EfiSmbusReceiveByte, SmBusAddress, 1, &Byte); 155 156 return Byte; 157 } 158 159 /** 160 Executes an SMBUS send byte command and saves the value in the S3 script to be replayed 161 on S3 resume. 162 163 Executes an SMBUS send byte command on the SMBUS device specified by SmBusAddress. 164 The byte specified by Value is sent. 165 Only the SMBUS slave address field of SmBusAddress is required. Value is returned. 166 If Status is not NULL, then the status of the executed command is returned in Status. 167 If Command in SmBusAddress is not zero, then ASSERT(). 168 If Length in SmBusAddress is not zero, then ASSERT(). 169 If any reserved bits of SmBusAddress are set, then ASSERT(). 170 171 @param SmBusAddress Address that encodes the SMBUS Slave Address, 172 SMBUS Command, SMBUS Data Length, and PEC. 173 @param Value The 8-bit value to send. 174 @param Status Return status for the executed command. 175 This is an optional parameter and may be NULL. 176 177 @return The parameter of Value. 178 179 **/ 180 UINT8 181 EFIAPI S3SmBusSendByte(IN UINTN SmBusAddress,IN UINT8 Value,OUT RETURN_STATUS * Status OPTIONAL)182 S3SmBusSendByte ( 183 IN UINTN SmBusAddress, 184 IN UINT8 Value, 185 OUT RETURN_STATUS *Status OPTIONAL 186 ) 187 { 188 UINT8 Byte; 189 190 Byte = SmBusSendByte (SmBusAddress, Value, Status); 191 192 InternalSaveSmBusExecToBootScript (EfiSmbusSendByte, SmBusAddress, 1, &Byte); 193 194 return Byte; 195 } 196 197 /** 198 Executes an SMBUS read data byte command and saves the value in the S3 script to be replayed 199 on S3 resume. 200 201 Executes an SMBUS read data byte command on the SMBUS device specified by SmBusAddress. 202 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 203 The 8-bit value read from the SMBUS is returned. 204 If Status is not NULL, then the status of the executed command is returned in Status. 205 If Length in SmBusAddress is not zero, then ASSERT(). 206 If any reserved bits of SmBusAddress are set, then ASSERT(). 207 208 @param SmBusAddress Address that encodes the SMBUS Slave Address, 209 SMBUS Command, SMBUS Data Length, and PEC. 210 @param Status Return status for the executed command. 211 This is an optional parameter and may be NULL. 212 213 @return The byte read from the SMBUS. 214 215 **/ 216 UINT8 217 EFIAPI S3SmBusReadDataByte(IN UINTN SmBusAddress,OUT RETURN_STATUS * Status OPTIONAL)218 S3SmBusReadDataByte ( 219 IN UINTN SmBusAddress, 220 OUT RETURN_STATUS *Status OPTIONAL 221 ) 222 { 223 UINT8 Byte; 224 225 Byte = SmBusReadDataByte (SmBusAddress, Status); 226 227 InternalSaveSmBusExecToBootScript (EfiSmbusReadByte, SmBusAddress, 1, &Byte); 228 229 return Byte; 230 } 231 232 /** 233 Executes an SMBUS write data byte command and saves the value in the S3 script to be replayed 234 on S3 resume. 235 236 Executes an SMBUS write data byte command on the SMBUS device specified by SmBusAddress. 237 The 8-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 8-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 UINT8 254 EFIAPI S3SmBusWriteDataByte(IN UINTN SmBusAddress,IN UINT8 Value,OUT RETURN_STATUS * Status OPTIONAL)255 S3SmBusWriteDataByte ( 256 IN UINTN SmBusAddress, 257 IN UINT8 Value, 258 OUT RETURN_STATUS *Status OPTIONAL 259 ) 260 { 261 UINT8 Byte; 262 263 Byte = SmBusWriteDataByte (SmBusAddress, Value, Status); 264 265 InternalSaveSmBusExecToBootScript (EfiSmbusWriteByte, SmBusAddress, 1, &Byte); 266 267 return Byte; 268 } 269 270 /** 271 Executes an SMBUS read data word command and saves the value in the S3 script to be replayed 272 on S3 resume. 273 274 Executes an SMBUS read data word command on the SMBUS device specified by SmBusAddress. 275 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 276 The 16-bit value read from the SMBUS is returned. 277 If Status is not NULL, then the status of the executed command is returned in Status. 278 If Length in SmBusAddress is not zero, then ASSERT(). 279 If any reserved bits of SmBusAddress are set, then ASSERT(). 280 281 @param SmBusAddress Address that encodes the SMBUS Slave Address, 282 SMBUS Command, SMBUS Data Length, and PEC. 283 @param Status Return status for the executed command. 284 This is an optional parameter and may be NULL. 285 286 @return The byte read from the SMBUS. 287 288 **/ 289 UINT16 290 EFIAPI S3SmBusReadDataWord(IN UINTN SmBusAddress,OUT RETURN_STATUS * Status OPTIONAL)291 S3SmBusReadDataWord ( 292 IN UINTN SmBusAddress, 293 OUT RETURN_STATUS *Status OPTIONAL 294 ) 295 { 296 UINT16 Word; 297 298 Word = SmBusReadDataWord (SmBusAddress, Status); 299 300 InternalSaveSmBusExecToBootScript (EfiSmbusReadWord, SmBusAddress, 2, &Word); 301 302 return Word; 303 } 304 305 /** 306 Executes an SMBUS write data word command and saves the value in the S3 script to be replayed 307 on S3 resume. 308 309 Executes an SMBUS write data word command on the SMBUS device specified by SmBusAddress. 310 The 16-bit value specified by Value is written. 311 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 312 Value is returned. 313 If Status is not NULL, then the status of the executed command is returned in Status. 314 If Length in SmBusAddress is not zero, then ASSERT(). 315 If any reserved bits of SmBusAddress are set, then ASSERT(). 316 317 @param SmBusAddress Address that encodes the SMBUS Slave Address, 318 SMBUS Command, SMBUS Data Length, and PEC. 319 @param Value The 16-bit value to write. 320 @param Status Return status for the executed command. 321 This is an optional parameter and may be NULL. 322 323 @return The parameter of Value. 324 325 **/ 326 UINT16 327 EFIAPI S3SmBusWriteDataWord(IN UINTN SmBusAddress,IN UINT16 Value,OUT RETURN_STATUS * Status OPTIONAL)328 S3SmBusWriteDataWord ( 329 IN UINTN SmBusAddress, 330 IN UINT16 Value, 331 OUT RETURN_STATUS *Status OPTIONAL 332 ) 333 { 334 UINT16 Word; 335 336 Word = SmBusWriteDataWord (SmBusAddress, Value, Status); 337 338 InternalSaveSmBusExecToBootScript (EfiSmbusWriteWord, SmBusAddress, 2, &Word); 339 340 return Word; 341 } 342 343 /** 344 Executes an SMBUS process call command and saves the value in the S3 script to be replayed 345 on S3 resume. 346 347 Executes an SMBUS process call command on the SMBUS device specified by SmBusAddress. 348 The 16-bit value specified by Value is written. 349 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 350 The 16-bit value returned by the process call command is returned. 351 If Status is not NULL, then the status of the executed command is returned in Status. 352 If Length in SmBusAddress is not zero, then ASSERT(). 353 If any reserved bits of SmBusAddress are set, then ASSERT(). 354 355 @param SmBusAddress Address that encodes the SMBUS Slave Address, 356 SMBUS Command, SMBUS Data Length, and PEC. 357 @param Value The 16-bit value to write. 358 @param Status Return status for the executed command. 359 This is an optional parameter and may be NULL. 360 361 @return The 16-bit value returned by the process call command. 362 363 **/ 364 UINT16 365 EFIAPI S3SmBusProcessCall(IN UINTN SmBusAddress,IN UINT16 Value,OUT RETURN_STATUS * Status OPTIONAL)366 S3SmBusProcessCall ( 367 IN UINTN SmBusAddress, 368 IN UINT16 Value, 369 OUT RETURN_STATUS *Status OPTIONAL 370 ) 371 { 372 UINT16 Word; 373 374 Word = SmBusProcessCall (SmBusAddress, Value, Status); 375 376 InternalSaveSmBusExecToBootScript (EfiSmbusProcessCall, SmBusAddress, 2, &Value); 377 378 return Word; 379 } 380 381 /** 382 Executes an SMBUS read block command and saves the value in the S3 script to be replayed 383 on S3 resume. 384 385 Executes an SMBUS read block command on the SMBUS device specified by SmBusAddress. 386 Only the SMBUS slave address and SMBUS command fields of SmBusAddress are required. 387 Bytes are read from the SMBUS and stored in Buffer. 388 The number of bytes read is returned, and will never return a value larger than 32-bytes. 389 If Status is not NULL, then the status of the executed command is returned in Status. 390 It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read. 391 SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes. 392 If Length in SmBusAddress is not zero, then ASSERT(). 393 If Buffer is NULL, then ASSERT(). 394 If any reserved bits of SmBusAddress are set, then ASSERT(). 395 396 @param SmBusAddress Address that encodes the SMBUS Slave Address, 397 SMBUS Command, SMBUS Data Length, and PEC. 398 @param Buffer Pointer to the buffer to store the bytes read from the SMBUS. 399 @param Status Return status for the executed command. 400 This is an optional parameter and may be NULL. 401 402 @return The number of bytes read. 403 404 **/ 405 UINTN 406 EFIAPI S3SmBusReadBlock(IN UINTN SmBusAddress,OUT VOID * Buffer,OUT RETURN_STATUS * Status OPTIONAL)407 S3SmBusReadBlock ( 408 IN UINTN SmBusAddress, 409 OUT VOID *Buffer, 410 OUT RETURN_STATUS *Status OPTIONAL 411 ) 412 { 413 UINTN Length; 414 415 Length = SmBusReadBlock (SmBusAddress, Buffer, Status); 416 417 InternalSaveSmBusExecToBootScript (EfiSmbusReadBlock, SmBusAddress, Length, Buffer); 418 419 return Length; 420 } 421 422 /** 423 Executes an SMBUS write block command and saves the value in the S3 script to be replayed 424 on S3 resume. 425 426 Executes an SMBUS write block command on the SMBUS device specified by SmBusAddress. 427 The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required. 428 Bytes are written to the SMBUS from Buffer. 429 The number of bytes written is returned, and will never return a value larger than 32-bytes. 430 If Status is not NULL, then the status of the executed command is returned in Status. 431 If Length in SmBusAddress is zero or greater than 32, then ASSERT(). 432 If Buffer is NULL, then ASSERT(). 433 If any reserved bits of SmBusAddress are set, then ASSERT(). 434 435 @param SmBusAddress Address that encodes the SMBUS Slave Address, 436 SMBUS Command, SMBUS Data Length, and PEC. 437 @param Buffer Pointer to the buffer to store the bytes read from the SMBUS. 438 @param Status Return status for the executed command. 439 This is an optional parameter and may be NULL. 440 441 @return The number of bytes written. 442 443 **/ 444 UINTN 445 EFIAPI S3SmBusWriteBlock(IN UINTN SmBusAddress,OUT VOID * Buffer,OUT RETURN_STATUS * Status OPTIONAL)446 S3SmBusWriteBlock ( 447 IN UINTN SmBusAddress, 448 OUT VOID *Buffer, 449 OUT RETURN_STATUS *Status OPTIONAL 450 ) 451 { 452 UINTN Length; 453 454 Length = SmBusWriteBlock (SmBusAddress, Buffer, Status); 455 456 InternalSaveSmBusExecToBootScript (EfiSmbusWriteBlock, SmBusAddress, SMBUS_LIB_LENGTH (SmBusAddress), Buffer); 457 458 return Length; 459 } 460 461 /** 462 Executes an SMBUS block process call command and saves the value in the S3 script to be replayed 463 on S3 resume. 464 465 Executes an SMBUS block process call command on the SMBUS device specified by SmBusAddress. 466 The SMBUS slave address, SMBUS command, and SMBUS length fields of SmBusAddress are required. 467 Bytes are written to the SMBUS from WriteBuffer. Bytes are then read from the SMBUS into ReadBuffer. 468 If Status is not NULL, then the status of the executed command is returned in Status. 469 It is the caller's responsibility to make sure ReadBuffer is large enough for the total number of bytes read. 470 SMBUS supports a maximum transfer size of 32 bytes, so Buffer does not need to be any larger than 32 bytes. 471 If Length in SmBusAddress is zero or greater than 32, then ASSERT(). 472 If WriteBuffer is NULL, then ASSERT(). 473 If ReadBuffer is NULL, then ASSERT(). 474 If any reserved bits of SmBusAddress are set, then ASSERT(). 475 476 @param SmBusAddress Address that encodes the SMBUS Slave Address, 477 SMBUS Command, SMBUS Data Length, and PEC. 478 @param WriteBuffer Pointer to the buffer of bytes to write to the SMBUS. 479 @param ReadBuffer Pointer to the buffer of bytes to read from the SMBUS. 480 @param Status Return status for the executed command. 481 This is an optional parameter and may be NULL. 482 483 @return The number of bytes written. 484 485 **/ 486 UINTN 487 EFIAPI S3SmBusBlockProcessCall(IN UINTN SmBusAddress,IN VOID * WriteBuffer,OUT VOID * ReadBuffer,OUT RETURN_STATUS * Status OPTIONAL)488 S3SmBusBlockProcessCall ( 489 IN UINTN SmBusAddress, 490 IN VOID *WriteBuffer, 491 OUT VOID *ReadBuffer, 492 OUT RETURN_STATUS *Status OPTIONAL 493 ) 494 { 495 UINTN Length; 496 497 Length = SmBusBlockProcessCall (SmBusAddress, WriteBuffer, ReadBuffer, Status); 498 499 InternalSaveSmBusExecToBootScript (EfiSmbusBWBRProcessCall, SmBusAddress, SMBUS_LIB_LENGTH (SmBusAddress), ReadBuffer); 500 501 return Length; 502 } 503