Code scrub:

MdeModulePkg/Universal/PcatRealTimeClockRuntimeDxe

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6426 6f19259b-4bc3-4df7-8a09-765794883524

1 files changed, 120 insertions, 234 deletions

diff --git a/MdeModulePkg/Universal/PcatRealTimeClockRuntimeDxe/PcRtc.h b/MdeModulePkg/Universal/PcatRealTimeClockRuntimeDxe/PcRtc.h
index cebcd23add..5a6fe762e3 100644
--- a/MdeModulePkg/Universal/PcatRealTimeClockRuntimeDxe/PcRtc.h
+++ b/MdeModulePkg/Universal/PcatRealTimeClockRuntimeDxe/PcRtc.h
@@ -145,100 +145,100 @@ typedef union {
 

 #pragma pack()

 

+/**

+  Initialize RTC.

+

+  @param  Global            For global use inside this module.

+

+  @retval EFI_DEVICE_ERROR  Initialization failed due to device error.

+  @retval EFI_SUCCESS       Initialization successful.

+

+**/

 EFI_STATUS

 PcRtcInit (

   IN PC_RTC_MODULE_GLOBALS  *Global

   )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

-

-  Global  - GC_TODO: add argument description

+;

 

-Returns:

+/**

+  Sets the current local time and date information.

 

-  GC_TODO: add return values

+  @param  Time                  A pointer to the current time.

+  @param  Global                For global use inside this module.

 

---*/

-;

+  @retval EFI_SUCCESS           The operation completed successfully.

+  @retval EFI_INVALID_PARAMETER A time field is out of range.

+  @retval EFI_DEVICE_ERROR      The time could not be set due due to hardware error.

 

+**/

 EFI_STATUS

 PcRtcSetTime (

   IN EFI_TIME               *Time,

   IN PC_RTC_MODULE_GLOBALS  *Global

   )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

-

-  Time    - GC_TODO: add argument description

-  Global  - GC_TODO: add argument description

+;

 

-Returns:

+/**

+  Returns the current time and date information, and the time-keeping capabilities

+  of the hardware platform.

 

-  GC_TODO: add return values

+  @param  Time          A pointer to storage to receive a snapshot of the current time.

+  @param  Capabilities  An optional pointer to a buffer to receive the real time clock

+                        device's capabilities.

+  @param  Global        For global use inside this module.

 

---*/

-;

+  @retval EFI_SUCCESS            The operation completed successfully.

+  @retval EFI_INVALID_PARAMETER  Time is NULL.

+  @retval EFI_DEVICE_ERROR       The time could not be retrieved due to hardware error.

 

+**/

 EFI_STATUS

 PcRtcGetTime (

   OUT EFI_TIME              *Time,

-  IN  EFI_TIME_CAPABILITIES *Capabilities,

+  OUT EFI_TIME_CAPABILITIES *Capabilities, OPTIONAL

   IN  PC_RTC_MODULE_GLOBALS *Global

   )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

-

-  Time          - GC_TODO: add argument description

-  Capabilities  - GC_TODO: add argument description

-  Global        - GC_TODO: add argument description

+;

 

-Returns:

+/**

+  Sets the system wakeup alarm clock time.

 

-  GC_TODO: add return values

+  @param  Enabled  Enable or disable the wakeup alarm.

+  @param  Time     If Enable is TRUE, the time to set the wakeup alarm for.

+                   If Enable is FALSE, then this parameter is optional, and may be NULL.

+  @param  Global   For global use inside this module.

 

---*/

-;

+  @retval EFI_SUCCESS           If Enable is TRUE, then the wakeup alarm was enabled.

+                                If Enable is FALSE, then the wakeup alarm was disabled.

+  @retval EFI_INVALID_PARAMETER A time field is out of range.

+  @retval EFI_DEVICE_ERROR      The wakeup time could not be set due to a hardware error.

+  @retval EFI_UNSUPPORTED       A wakeup timer is not supported on this platform.

 

+**/

 EFI_STATUS

 PcRtcSetWakeupTime (

   IN BOOLEAN                Enable,

-  OUT EFI_TIME              *Time,

-  IN  PC_RTC_MODULE_GLOBALS *Global

+  IN EFI_TIME               *Time,  OPTIONAL

+  IN PC_RTC_MODULE_GLOBALS  *Global

   )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

-

-  Enable  - GC_TODO: add argument description

-  Time    - GC_TODO: add argument description

-  Global  - GC_TODO: add argument description

+;

 

-Returns:

+/**

+  Returns the current wakeup alarm clock setting.

 

-  GC_TODO: add return values

+  @param  Enabled  Indicates if the alarm is currently enabled or disabled.

+  @param  Pending  Indicates if the alarm signal is pending and requires acknowledgement.

+  @param  Time     The current alarm setting.

+  @param  Global   For global use inside this module.

 

---*/

-;

+  @retval EFI_SUCCESS           The alarm settings were returned.

+  @retval EFI_INVALID_PARAMETER Enabled is NULL.

+  @retval EFI_INVALID_PARAMETER Pending is NULL.

+  @retval EFI_INVALID_PARAMETER Time is NULL.

+  @retval EFI_DEVICE_ERROR      The wakeup time could not be retrieved due to a hardware error.

+  @retval EFI_UNSUPPORTED       A wakeup timer is not supported on this platform.

 

+**/

 EFI_STATUS

 PcRtcGetWakeupTime (

   OUT BOOLEAN               *Enabled,

@@ -246,157 +246,75 @@ PcRtcGetWakeupTime (
   OUT EFI_TIME              *Time,

   IN  PC_RTC_MODULE_GLOBALS *Global

   )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

+;

 

-  Enabled - GC_TODO: add argument description

-  Pending - GC_TODO: add argument description

-  Time    - GC_TODO: add argument description

-  Global  - GC_TODO: add argument description

+/**

+  The user Entry Point for PcRTC module.

 

-Returns:

+  This is the entrhy point for PcRTC module. It installs the UEFI runtime service

+  including GetTime(),SetTime(),GetWakeupTime(),and SetWakeupTime().

 

-  GC_TODO: add return values

+  @param  ImageHandle    The firmware allocated handle for the EFI image.

+  @param  SystemTable    A pointer to the EFI System Table.

 

---*/

-;

+  @retval EFI_SUCCESS    The entry point is executed successfully.

+  @retval Others         Some error occurs when executing this entry point.

 

+**/

 EFI_STATUS

 EFIAPI

 InitializePcRtc (

   IN EFI_HANDLE                            ImageHandle,

   IN EFI_SYSTEM_TABLE                      *SystemTable

   )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

-

-  ImageHandle - GC_TODO: add argument description

-  SystemTable - GC_TODO: add argument description

-

-Returns:

-

-  GC_TODO: add return values

-

---*/

 ;

 

-UINT8

-BcdToDecimal (

-  IN  UINT8 BcdValue

-  )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

-

-  BcdValue  - GC_TODO: add argument description

-

-Returns:

+/**

+  See if all fields of a variable of EFI_TIME type is correct.

 

-  GC_TODO: add return values

+  @param   Time   The time to be checked.

 

---*/

-;

+  @retval  EFI_INVALID_PARAMETER  Some fields of Time are not correct.

+  @retval  EFI_SUCCESS            Time is a valid EFI_TIME variable.

 

+**/

 EFI_STATUS

 RtcTimeFieldsValid (

   IN EFI_TIME *Time

   )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

-

-  Time  - GC_TODO: add argument description

-

-Returns:

-

-  GC_TODO: add return values

-

---*/

 ;

 

-UINT8

-DecimaltoBcd (

-  IN  UINT8 DecValue

-  )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

-

-  DecValue  - GC_TODO: add argument description

-

-Returns:

+/**

+  Converts time from EFI_TIME format defined by UEFI spec to RTC's.

 

-  GC_TODO: add return values

+  This function converts time from EFI_TIME format defined by UEFI spec to RTC's.

+  If data mode of RTC is BCD, then converts EFI_TIME to it.

+  If RTC is in 12-hour format, then converts EFI_TIME to it.

 

---*/

-;

+  @param   Time       On input, the time data read from UEFI to convert

+                      On output, the time converted to RTC format

+  @param   RegisterB  Value of Register B of RTC, indicating data mode

+  @param   Century    It is set according to EFI_TIME Time.

 

+**/

 VOID

 ConvertEfiTimeToRtcTime (

-  IN EFI_TIME       *Time,

-  IN RTC_REGISTER_B RegisterB,

-  IN UINT8          *Century

+  IN OUT EFI_TIME        *Time,

+  IN     RTC_REGISTER_B  RegisterB,

+  OUT    UINT8           *Century

   )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

-

-  Time      - GC_TODO: add argument description

-  RegisterB - GC_TODO: add argument description

-  Century   - GC_TODO: add argument description

-

-Returns:

-

-  GC_TODO: add return values

-

---*/

 ;

 

+/**

+  See if centry register of RTC is valid.

+

+  @retval  EFI_SUCCESS       Century register is valid.

+  @retval  EFI_DEVICE_ERROR  Century register is NOT valid.

+**/

 EFI_STATUS

 RtcTestCenturyRegister (

   VOID

   )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

-

-  None

-

-Returns:

-

-  GC_TODO: add return values

-

---*/

 ;

 

 /**

@@ -413,6 +331,9 @@ Returns:
   @param   RegisterB  Value of Register B of RTC, indicating data mode

                       and hour format.

 

+  @retval  EFI_INVALID_PARAMETER  Parameters passed in are invalid.

+  @retval  EFI_SUCCESS            Convert RTC time to EFI time successfully.

+

 **/

 EFI_STATUS

 ConvertRtcTimeToEfiTime (

@@ -421,76 +342,41 @@ ConvertRtcTimeToEfiTime (
   IN     RTC_REGISTER_B  RegisterB

   );

 

+/**

+  Wait for a period for the RTC to be ready.

+

+  @param    Timeout  Tell how long it should take to wait.

+

+  @retval   EFI_DEVICE_ERROR   RTC device error.

+  @retval   EFI_SUCCESS        RTC is updated and ready.  

+**/

 EFI_STATUS

 RtcWaitToUpdate (

   UINTN Timeout

   )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

-

-  Timeout - GC_TODO: add argument description

-

-Returns:

-

-  GC_TODO: add return values

-

---*/

-;

-

-UINT8

-RtcSaveContext (

-  IN  PC_RTC_MODULE_GLOBALS  *Global

-  )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

-

-  Global  - GC_TODO: add argument description

-

-Returns:

-

-  GC_TODO: add return values

-

---*/

 ;

 

-VOID

-RtcRestoreContext (

-  IN  UINT8                 SavedAddressRegister,

-  IN  PC_RTC_MODULE_GLOBALS *Global

-  )

-/*++

-

-Routine Description:

-

-  GC_TODO: Add function description

-

-Arguments:

-

-  SavedAddressRegister  - GC_TODO: add argument description

-  Global                - GC_TODO: add argument description

-

-Returns:

-

-  GC_TODO: add return values

+/**

+  See if field Day of an EFI_TIME is correct.

 

---*/

-;

+  @param    Time   Its Day field is to be checked.

 

+  @retval   TRUE   Day field of Time is correct.

+  @retval   FALSE  Day field of Time is NOT correct.

+**/

 BOOLEAN

 DayValid (

   IN  EFI_TIME  *Time

   );

 

+/**

+  Check if it is a leapyear.

+

+  @param    Time   The time to be checked.

+

+  @retval   TRUE   It is a leapyear.

+  @retval   FALSE  It is NOT a leapyear.

+**/

 BOOLEAN

 IsLeapYear (

   IN EFI_TIME   *Time