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