Add doxygen style comments for functions in DxeMain.

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

3 files changed, 232 insertions, 358 deletions

diff --git a/MdeModulePkg/Core/Dxe/Event/event.c b/MdeModulePkg/Core/Dxe/Event/event.c
index 13949169a0..f5ffbb7d4d 100644
--- a/MdeModulePkg/Core/Dxe/Event/event.c
+++ b/MdeModulePkg/Core/Dxe/Event/event.c
@@ -62,74 +62,47 @@ UINT32 mEventTable[] = {
   EVT_TIMER | EVT_NOTIFY_WAIT,

 };

 

+

+/**

+  Enter critical section by acquiring the lock on gEventQueueLock.

+

+**/

 STATIC

 VOID

 CoreAcquireEventLock (

   VOID

   )

-/*++

-

-Routine Description:

-

-  Enter critical section by acquiring the lock on gEventQueueLock.

-

-Arguments:

-

-  None

-

-Returns:

-

-  None

-

---*/

 {

   CoreAcquireLock (&gEventQueueLock);

 }

 

+

+/**

+  Exit critical section by releasing the lock on gEventQueueLock.

+

+**/

 STATIC

 VOID

 CoreReleaseEventLock (

   VOID

   )

-/*++

-

-Routine Description:

-

-  Exit critical section by releasing the lock on gEventQueueLock.

-

-Arguments:

-

-  None

-

-Returns:

-

-  None

-

---*/

 {

   CoreReleaseLock (&gEventQueueLock);

 }

 

 

-EFI_STATUS

-CoreInitializeEventServices (

-  VOID

-  )

-/*++

-

-Routine Description:

 

+/**

   Initializes "event" support and populates parts of the System and Runtime Table.

 

-Arguments:

-

-  None

-

-Returns:

 

-  EFI_SUCCESS - Always return success

+  @retval EFI_SUCCESS            Always return success

 

---*/

+**/

+EFI_STATUS

+CoreInitializeEventServices (

+  VOID

+  )

 {

   UINTN        Index;

 

@@ -143,25 +116,18 @@ Returns:
 }

 

 

-VOID

-CoreDispatchEventNotifies (

-  IN EFI_TPL      Priority

-  )

-/*++

-

-Routine Description:

 

+/**

   Dispatches all pending events.

 

-Arguments:

-

-  Priority - The task priority level of event notifications to dispatch

+  @param  Priority               The task priority level of event notifications 

+                                 to dispatch

 

-Returns:

-

-  None

-

---*/

+**/

+VOID

+CoreDispatchEventNotifies (

+  IN EFI_TPL      Priority

+  )

 {

   IEVENT          *Event;

   LIST_ENTRY      *Head;

@@ -207,26 +173,18 @@ Returns:
 }

 

 

+

+/**

+  Queues the event's notification function to fire.

+

+  @param  Event                  The Event to notify

+

+**/

 STATIC

 VOID

 CoreNotifyEvent (

   IN  IEVENT      *Event

   )

-/*++

-

-Routine Description:

-

-  Queues the event's notification function to fire

-

-Arguments:

-

-  Event       - The Event to notify

-

-Returns:

-

-  None

-

---*/

 {

 

   //

@@ -253,23 +211,17 @@ Returns:
 

 

 

+

+/**

+  Signals all events in the EventGroup.

+

+  @param  EventGroup             The list to signal

+

+**/

 VOID

 CoreNotifySignalList (

   IN EFI_GUID     *EventGroup

   )

-/*++

-

-Routine Description:

-  Signals all events in the EventGroup

-

-Arguments:

-  EventGroup - The list to signal

-

-Returns:

-

-  None

-

---*/

 {

   LIST_ENTRY              *Link;

   LIST_ENTRY              *Head;

@@ -288,6 +240,25 @@ Returns:
   CoreReleaseEventLock ();

 }

 

+

+/**

+  Creates a general-purpose event structure.

+

+  @param  Type                   The type of event to create and its mode and 

+                                 attributes 

+  @param  NotifyTpl              The task priority level of event notifications 

+  @param  NotifyFunction         Pointer to the events notification function 

+  @param  NotifyContext          Pointer to the notification functions context; 

+                                 corresponds to parameter "Context" in the 

+                                 notification function 

+  @param  Event                  Pointer to the newly created event if the call 

+                                 succeeds; undefined otherwise 

+

+  @retval EFI_SUCCESS            The event structure was created 

+  @retval EFI_INVALID_PARAMETER  One of the parameters has an invalid value 

+  @retval EFI_OUT_OF_RESOURCES   The event could not be allocated

+

+**/

 EFI_STATUS

 EFIAPI

 CoreCreateEvent (

@@ -297,30 +268,32 @@ CoreCreateEvent (
   IN VOID                     *NotifyContext, OPTIONAL

   OUT EFI_EVENT               *Event

   )

-/*++

-

-Routine Description:

-  Creates a general-purpose event structure

-

-Arguments:

-  Type                - The type of event to create and its mode and attributes

-  NotifyTpl           - The task priority level of event notifications

-  NotifyFunction      - Pointer to the events notification function

-  NotifyContext       - Pointer to the notification functions context; corresponds to

-                        parameter "Context" in the notification function

-  Event               - Pointer to the newly created event if the call succeeds; undefined otherwise

-

-Returns:

-  EFI_SUCCESS           - The event structure was created

-  EFI_INVALID_PARAMETER - One of the parameters has an invalid value

-  EFI_OUT_OF_RESOURCES  - The event could not be allocated

-

---*/

 {

   return CoreCreateEventEx (Type, NotifyTpl, NotifyFunction, NotifyContext, NULL, Event);

 }

 

 

+

+/**

+  Creates a general-purpose event structure

+

+  @param  Type                   The type of event to create and its mode and 

+                                 attributes 

+  @param  NotifyTpl              The task priority level of event notifications 

+  @param  NotifyFunction         Pointer to the events notification function 

+  @param  NotifyContext          Pointer to the notification functions context; 

+                                 corresponds to parameter "Context" in the 

+                                 notification function 

+  @param  EventGroup             GUID for EventGroup if NULL act the same as 

+                                 gBS->CreateEvent(). 

+  @param  Event                  Pointer to the newly created event if the call 

+                                 succeeds; undefined otherwise 

+

+  @retval EFI_SUCCESS            The event structure was created 

+  @retval EFI_INVALID_PARAMETER  One of the parameters has an invalid value 

+  @retval EFI_OUT_OF_RESOURCES   The event could not be allocated

+

+**/

 EFI_STATUS

 EFIAPI

 CoreCreateEventEx (

@@ -331,26 +304,6 @@ CoreCreateEventEx (
   IN CONST EFI_GUID           *EventGroup,    OPTIONAL

   OUT EFI_EVENT               *Event

   )

-/*++

-

-Routine Description:

-  Creates a general-purpose event structure

-

-Arguments:

-  Type                - The type of event to create and its mode and attributes

-  NotifyTpl           - The task priority level of event notifications

-  NotifyFunction      - Pointer to the events notification function

-  NotifyContext       - Pointer to the notification functions context; corresponds to

-                        parameter "Context" in the notification function

-  EventGroup          - GUID for EventGroup if NULL act the same as gBS->CreateEvent().

-  Event               - Pointer to the newly created event if the call succeeds; undefined otherwise

-

-Returns:

-  EFI_SUCCESS           - The event structure was created

-  EFI_INVALID_PARAMETER - One of the parameters has an invalid value

-  EFI_OUT_OF_RESOURCES  - The event could not be allocated

-

---*/

 {

   EFI_STATUS      Status;

   IEVENT          *IEvent;

@@ -482,28 +435,21 @@ Returns:
 

 

 

-EFI_STATUS

-EFIAPI

-CoreSignalEvent (

-  IN EFI_EVENT    UserEvent

-  )

-/*++

-

-Routine Description:

 

+/**

   Signals the event.  Queues the event to be notified if needed

 

-Arguments:

-

-  UserEvent - The event to signal

-

-Returns:

+  @param  UserEvent              The event to signal 

 

-  EFI_INVALID_PARAMETER - Parameters are not valid.

+  @retval EFI_INVALID_PARAMETER  Parameters are not valid. 

+  @retval EFI_SUCCESS            The event was signaled.

 

-  EFI_SUCCESS - The event was signaled.

-

---*/

+**/

+EFI_STATUS

+EFIAPI

+CoreSignalEvent (

+  IN EFI_EVENT    UserEvent

+  )

 {

   IEVENT          *Event;

 

@@ -549,29 +495,22 @@ Returns:
 }

 

 

+

+/**

+  Check the status of an event.

+

+  @param  UserEvent              The event to check 

+

+  @retval EFI_SUCCESS            The event is in the signaled state 

+  @retval EFI_NOT_READY          The event is not in the signaled state 

+  @retval EFI_INVALID_PARAMETER  Event is of type EVT_NOTIFY_SIGNAL

+

+**/

 EFI_STATUS

 EFIAPI

 CoreCheckEvent (

   IN EFI_EVENT        UserEvent

   )

-/*++

-

-Routine Description:

-

-  Check the status of an event

-

-Arguments:

-

-  UserEvent - The event to check

-

-Returns:

-

-  EFI_SUCCESS           - The event is in the signaled state

-  EFI_NOT_READY         - The event is not in the signaled state

-  EFI_INVALID_PARAMETER - Event is of type EVT_NOTIFY_SIGNAL

-

---*/

-

 {

   IEVENT      *Event;

   EFI_STATUS  Status;

@@ -625,6 +564,21 @@ Returns:
 

 

 

+

+/**

+  Stops execution until an event is signaled.

+

+  @param  NumberOfEvents         The number of events in the UserEvents array 

+  @param  UserEvents             An array of EFI_EVENT 

+  @param  UserIndex              Pointer to the index of the event which 

+                                 satisfied the wait condition 

+

+  @retval EFI_SUCCESS            The event indicated by Index was signaled. 

+  @retval EFI_INVALID_PARAMETER  The event indicated by Index has a notification 

+                                 function or Event was not a valid type 

+  @retval EFI_UNSUPPORTED        The current TPL is not TPL_APPLICATION

+

+**/

 EFI_STATUS

 EFIAPI

 CoreWaitForEvent (

@@ -632,27 +586,6 @@ CoreWaitForEvent (
   IN EFI_EVENT    *UserEvents,

   OUT UINTN       *UserIndex

   )

-/*++

-

-Routine Description:

-

-  Stops execution until an event is signaled.

-

-Arguments:

-

-  NumberOfEvents  - The number of events in the UserEvents array

-  UserEvents      - An array of EFI_EVENT

-  UserIndex       - Pointer to the index of the event which satisfied the wait condition

-

-Returns:

-

-  EFI_SUCCESS           - The event indicated by Index was signaled.

-  EFI_INVALID_PARAMETER - The event indicated by Index has a notification function or

-                          Event was not a valid type

-  EFI_UNSUPPORTED       - The current TPL is not TPL_APPLICATION

-

---*/

-

 {

   EFI_STATUS      Status;

   UINTN           Index;

@@ -687,29 +620,21 @@ Returns:
 }

 

 

-EFI_STATUS

-EFIAPI

-CoreCloseEvent (

-  IN EFI_EVENT    UserEvent

-  )

-/*++

-

-Routine Description:

 

+/**

   Closes an event and frees the event structure.

 

-Arguments:

-

-  UserEvent - Event to close

+  @param  UserEvent              Event to close 

 

-Returns:

-

-  EFI_INVALID_PARAMETER - Parameters are not valid.

-

-  EFI_SUCCESS - The event has been closed

-

---*/

+  @retval EFI_INVALID_PARAMETER  Parameters are not valid. 

+  @retval EFI_SUCCESS            The event has been closed

 

+**/

+EFI_STATUS

+EFIAPI

+CoreCloseEvent (

+  IN EFI_EVENT    UserEvent

+  )

 {

   EFI_STATUS  Status;

   IEVENT      *Event;

diff --git a/MdeModulePkg/Core/Dxe/Event/timer.c b/MdeModulePkg/Core/Dxe/Event/timer.c
index 7a49c2a3bd..1388512fb8 100644
--- a/MdeModulePkg/Core/Dxe/Event/timer.c
+++ b/MdeModulePkg/Core/Dxe/Event/timer.c
@@ -19,12 +19,26 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 //

 // Internal prototypes

 //

+/**

+  Returns the current system time.

+

+  @return The current system time

+

+**/

 STATIC

 UINT64

 CoreCurrentSystemTime (

   VOID

   );

 

+/**

+  Checks the sorted timer list against the current system time.

+  Signals any expired event timer.

+

+  @param  CheckEvent             Not used 

+  @param  Context                Not used

+

+**/

 STATIC

 VOID

 EFIAPI

@@ -33,6 +47,13 @@ CoreCheckTimers (
   IN VOID         *Context

   );

 

+/**

+  Inserts the timer event.

+

+  @param  Event                  Points to the internal structure of timer event 

+                                 to be installed

+

+**/

 STATIC

 VOID

 CoreInsertEventTimer (

@@ -54,25 +75,15 @@ static UINT64           mEfiSystemTime = 0;
 // Timer functions

 //

 

+

+/**

+  Initializes timer support.

+

+**/

 VOID

 CoreInitializeTimer (

   VOID

   )

-/*++

-

-Routine Description:

-

-  Initializes timer support

-

-Arguments:

-

-  None

-

-Returns:

-

-  None

-

---*/

 {

   EFI_STATUS  Status;

 

@@ -86,26 +97,18 @@ Returns:
   ASSERT_EFI_ERROR (Status);

 }

 

+

+/**

+  Returns the current system time.

+

+  @return The current system time

+

+**/

 STATIC

 UINT64

 CoreCurrentSystemTime (

   VOID

   )

-/*++

-

-Routine Description:

-

-  Returns the current system time

-

-Arguments:

-

-  None

-

-Returns:

-

-  Returns the current system time

-

---*/

 {

   UINT64          SystemTime;

 

@@ -115,26 +118,19 @@ Returns:
   return SystemTime;

 }

 

+

+/**

+  Called by the platform code to process a tick.

+

+  @param  Duration               The number of 100ns elasped since the last call 

+                                 to TimerTick

+

+**/

 VOID

 EFIAPI

 CoreTimerTick (

   IN UINT64   Duration

   )

-/*++

-

-Routine Description:

-

-  Called by the platform code to process a tick.

-

-Arguments:

-

-  Duration    - The number of 100ns elasped since the last call to TimerTick

-

-Returns:

-

-  None

-

---*/

 {

   IEVENT          *Event;

 

@@ -166,6 +162,15 @@ Returns:
   CoreReleaseLock (&mEfiSystemTimeLock);

 }

 

+

+/**

+  Checks the sorted timer list against the current system time.

+  Signals any expired event timer.

+

+  @param  CheckEvent             Not used 

+  @param  Context                Not used

+

+**/

 STATIC

 VOID

 EFIAPI

@@ -173,24 +178,6 @@ CoreCheckTimers (
   IN EFI_EVENT            CheckEvent,

   IN VOID                 *Context

   )

-/*++

-

-Routine Description:

-

-  Checks the sorted timer list against the current system time.

-  Signals any expired event timer.

-

-Arguments:

-

-  CheckEvent  - Not used

-

-  Context     - Not used

-

-Returns:

-

-  None

-

---*/

 {

   UINT64                  SystemTime;

   IEVENT                  *Event;

@@ -255,26 +242,19 @@ Returns:
   CoreReleaseLock (&mEfiTimerLock);

 }

 

+

+/**

+  Inserts the timer event.

+

+  @param  Event                  Points to the internal structure of timer event 

+                                 to be installed

+

+**/

 STATIC

 VOID

 CoreInsertEventTimer (

   IN IEVENT   *Event

   )

-/*++

-

-Routine Description:

-

-  Inserts the timer event

-

-Arguments:

-

-  Event - Points to the internal structure of timer event to be installed

-

-Returns:

-

-  None

-

---*/

 {

   UINT64          TriggerTime;

   LIST_ENTRY      *Link;

@@ -305,6 +285,22 @@ Returns:
 

 

 

+

+/**

+  Sets the type of timer and the trigger time for a timer event.

+

+  @param  UserEvent              The timer event that is to be signaled at the 

+                                 specified time 

+  @param  Type                   The type of time that is specified in 

+                                 TriggerTime 

+  @param  TriggerTime            The number of 100ns units until the timer 

+                                 expires 

+

+  @retval EFI_SUCCESS            The event has been set to be signaled at the 

+                                 requested time 

+  @retval EFI_INVALID_PARAMETER  Event or Type is not valid

+

+**/

 EFI_STATUS

 EFIAPI

 CoreSetTimer (

@@ -312,24 +308,6 @@ CoreSetTimer (
   IN EFI_TIMER_DELAY      Type,

   IN UINT64               TriggerTime

   )

-/*++

-

-Routine Description:

-

-  Sets the type of timer and the trigger time for a timer event.

-

-Arguments:

-

-  UserEvent   - The timer event that is to be signaled at the specified time

-  Type        - The type of time that is specified in TriggerTime

-  TriggerTime - The number of 100ns units until the timer expires

-

-Returns:

-

-  EFI_SUCCESS           - The event has been set to be signaled at the requested time

-  EFI_INVALID_PARAMETER - Event or Type is not valid

-

---*/

 {

   IEVENT      *Event;

 

diff --git a/MdeModulePkg/Core/Dxe/Event/tpl.c b/MdeModulePkg/Core/Dxe/Event/tpl.c
index 694d731712..02597f3254 100644
--- a/MdeModulePkg/Core/Dxe/Event/tpl.c
+++ b/MdeModulePkg/Core/Dxe/Event/tpl.c
@@ -15,27 +15,18 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 

 #include <DxeMain.h>

 

+

+/**

+  Set Interrupt State.

+

+  @param  Enable  The state of enable or disable interrupt

+

+**/

 STATIC

 VOID

 CoreSetInterruptState (

   IN BOOLEAN      Enable

   )

-/*++

-

-Routine Description:

-  

-  Set Interrupt State

-  

-Arguments:

-  

-  Enable - The state of enable or disable interrupt

-  

-Returns:

-  

-  None

-

---*/

-

 {

   if (gCpu != NULL) {

     if (Enable) {

@@ -49,25 +40,19 @@ Returns:
 //

 // Return the highest set bit

 //

+

+/**

+  Return the highest set bit.

+

+  @param  Number  The value to check 

+

+  @return Bit position of the highest set bit

+

+**/

 UINTN

 CoreHighestSetBit (

   IN UINTN     Number

   )

-/*++

-

-Routine Description:

-  

-  Return the highest set bit

-  

-Arguments:

-  

-  Number - The value to check

-  

-Returns:

-  

-  Bit position of the highest set bit

-

---*/

 {

   UINTN   msb;

   

@@ -81,27 +66,21 @@ Returns:
 

 

 

-EFI_TPL

-EFIAPI

-CoreRaiseTpl (

-  IN EFI_TPL      NewTpl

-  )

-/*++

-

-Routine Description:

 

+/**

   Raise the task priority level to the new level.

   High level is implemented by disabling processor interrupts.

 

-Arguments:

-

-  NewTpl  - New task priority level

-    

-Returns:

+  @param  NewTpl  New task priority level 

 

-  The previous task priority level

+  @return The previous task priority level

 

---*/

+**/

+EFI_TPL

+EFIAPI

+CoreRaiseTpl (

+  IN EFI_TPL      NewTpl

+  )

 {

   EFI_TPL     OldTpl;

 

@@ -126,27 +105,19 @@ Returns:
 

 

 

+

+/**

+  Lowers the task priority to the previous value.   If the new

+  priority unmasks events at a higher priority, they are dispatched.

+

+  @param  NewTpl  New, lower, task priority

+

+**/

 VOID

 EFIAPI

 CoreRestoreTpl (

   IN EFI_TPL NewTpl

   )

-/*++

-

-Routine Description:

-

-  Lowers the task priority to the previous value.   If the new 

-  priority unmasks events at a higher priority, they are dispatched.

-

-Arguments:

-

-  NewTpl  - New, lower, task priority

-    

-Returns:

-

-  None

-

---*/

 {

   EFI_TPL     OldTpl;