From 162ed594438ab8d39f89b43e6d645ca24e1e1e65 Mon Sep 17 00:00:00 2001 From: qhuang8 Date: Fri, 9 May 2008 07:08:30 +0000 Subject: 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 --- MdeModulePkg/Core/Dxe/Event/event.c | 325 ++++++++++++++---------------------- MdeModulePkg/Core/Dxe/Event/timer.c | 170 ++++++++----------- MdeModulePkg/Core/Dxe/Event/tpl.c | 95 ++++------- 3 files changed, 232 insertions(+), 358 deletions(-) (limited to 'MdeModulePkg/Core/Dxe/Event') 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 + +/** + 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; -- cgit v1.2.3