• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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