modify coding style to pass ecc tool and provide comments that complied with Doxgen.

[mirror_edk2.git] / MdeModulePkg / Universal / WatchdogTimerDxe / WatchdogTimer.h

diff --git a/MdeModulePkg/Universal/WatchdogTimerDxe/WatchdogTimer.h b/MdeModulePkg/Universal/WatchdogTimerDxe/WatchdogTimer.h
index 0117d287bbc304b82078794129ce3e45ab74a664..103ad06d9fd7444b7c316d53aaeef129a1bcda5e 100644 (file)
--- a/MdeModulePkg/Universal/WatchdogTimerDxe/WatchdogTimer.h
+++ b/MdeModulePkg/Universal/WatchdogTimerDxe/WatchdogTimer.h
@@ -29,9 +29,27 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #include <Protocol/WatchdogTimer.h>\r
 \r
 \r
-//\r
-// Function Prototypes\r
-//\r
+/**\r
+  This function registers a handler that is to be invoked when the watchdog\r
+  timer fires.  By default, the EFI_WATCHDOG_TIMER protocol will call the\r
+  Runtime Service ResetSystem() when the watchdog timer fires.  If a\r
+  NotifyFunction is registered, then the NotifyFunction will be called before\r
+  the Runtime Service ResetSystem() is called.  If NotifyFunction is NULL, then\r
+  the watchdog handler is unregistered.  If a watchdog handler is registered,\r
+  then EFI_SUCCESS is returned.  If an attempt is made to register a handler\r
+  when a handler is already registered, then EFI_ALREADY_STARTED is returned.\r
+  If an attempt is made to uninstall a handler when a handler is not installed,\r
+  then return EFI_INVALID_PARAMETER.\r
+\r
+  @param  This                  The EFI_WATCHDOG_TIMER_ARCH_PROTOCOL instance.\r
+  @param  NotifyFunction        The function to call when the watchdog timer fires.  If this\r
+                                is NULL, then the handler will be unregistered.\r
+\r
+  @return EFI_SUCCESS           The watchdog timer handler was registered or unregistered.\r
+  @return EFI_ALREADY_STARTED   NotifyFunction is not NULL, and a handler is already registered.\r
+  @return EFI_INVALID_PARAMETER NotifyFunction is NULL, and a handler was not previously registered.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 WatchdogTimerDriverRegisterHandler (\r
@@ -39,6 +57,22 @@ WatchdogTimerDriverRegisterHandler (
   IN EFI_WATCHDOG_TIMER_NOTIFY         NotifyFunction\r
   );\r
 \r
+/**\r
+  This function sets the amount of time to wait before firing the watchdog\r
+  timer to TimerPeriod 100 nS units.  If TimerPeriod is 0, then the watchdog\r
+  timer is disabled.\r
+\r
+  @param  This              The EFI_WATCHDOG_TIMER_ARCH_PROTOCOL instance.\r
+  @param  TimerPeriod       The amount of time in 100 nS units to wait before the watchdog\r
+                            timer is fired.  If TimerPeriod is zero, then the watchdog\r
+                            timer is disabled.\r
+\r
+  @return EFI_SUCCESS       The watchdog timer has been programmed to fire in Time\r
+                            100 nS units.\r
+  @return EFI_DEVICE_ERROR  A watchdog timer could not be programmed due to a device\r
+                            error.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 WatchdogTimerDriverSetTimerPeriod (\r
@@ -46,6 +80,21 @@ WatchdogTimerDriverSetTimerPeriod (
   IN UINT64                            TimerPeriod\r
   );\r
 \r
+/**\r
+  This function retrieves the amount of time the system will wait before firing\r
+  the watchdog timer.  This period is returned in TimerPeriod, and EFI_SUCCESS\r
+  is returned.  If TimerPeriod is NULL, then EFI_INVALID_PARAMETER is returned.\r
+\r
+  @param  This                    The EFI_WATCHDOG_TIMER_ARCH_PROTOCOL instance.\r
+  @param  TimerPeriod             A pointer to the amount of time in 100 nS units that the system\r
+                                  will wait before the watchdog timer is fired.  If TimerPeriod of\r
+                                  zero is returned, then the watchdog timer is disabled.\r
+\r
+  @return EFI_SUCCESS             The amount of time that the system will wait before\r
+                                  firing the watchdog timer was returned in TimerPeriod.\r
+  @return EFI_INVALID_PARAMETER   TimerPeriod is NULL.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 WatchdogTimerDriverGetTimerPeriod (\r
@@ -53,6 +102,15 @@ WatchdogTimerDriverGetTimerPeriod (
   IN UINT64                            *TimerPeriod\r
   );\r
 \r
+/**\r
+  Initialize the Watchdog Timer Architectural Protocol driver.\r
+\r
+  @param  ImageHandle             ImageHandle of the loaded driver.\r
+  @param  SystemTable             Pointer to the System Table.\r
+\r
+  @return EFI_SUCCESS             Timer Architectural Protocol created.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 WatchdogTimerDriverInitialize (\r