diff --git a/MdeModulePkg/Core/Dxe/DebugImageInfo.h b/MdeModulePkg/Core/Dxe/DebugImageInfo.h
index 5f05a90a52..26a5bb185c 100644
--- a/MdeModulePkg/Core/Dxe/DebugImageInfo.h
+++ b/MdeModulePkg/Core/Dxe/DebugImageInfo.h
@@ -22,99 +22,69 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
#define EFI_DEBUG_TABLE_ENTRY_SIZE (sizeof (VOID *))
+
+/**
+ Creates and initializes the DebugImageInfo Table. Also creates the configuration
+ table and registers it into the system table.
+
+ Note:
+ This function allocates memory, frees it, and then allocates memory at an
+ address within the initial allocation. Since this function is called early
+ in DXE core initialization (before drivers are dispatched), this should not
+ be a problem.
+
+**/
VOID
CoreInitializeDebugImageInfoTable (
VOID
)
-/*++
-
-Routine Description:
-
- Creates and initializes the DebugImageInfo Table. Also creates the configuration
- table and registers it into the system table.
-
-Arguments:
- None
-
-Returns:
- NA
-
-Notes:
- This function allocates memory, frees it, and then allocates memory at an
- address within the initial allocation. Since this function is called early
- in DXE core initialization (before drivers are dispatched), this should not
- be a problem.
-
---*/
;
-VOID
-CoreUpdateDebugTableCrc32 (
- VOID
- )
-/*++
-
-Routine Description:
+/**
Update the CRC32 in the Debug Table.
Since the CRC32 service is made available by the Runtime driver, we have to
wait for the Runtime Driver to be installed before the CRC32 can be computed.
This function is called elsewhere by the core when the runtime architectural
protocol is produced.
-Arguments:
- None
-
-Returns:
- NA
-
---*/
+**/
+VOID
+CoreUpdateDebugTableCrc32 (
+ VOID
+ )
;
+
+/**
+ Adds a new DebugImageInfo structure to the DebugImageInfo Table. Re-Allocates
+ the table if it's not large enough to accomidate another entry.
+
+ @param ImageInfoType type of debug image information
+ @param LoadedImage pointer to the loaded image protocol for the image being
+ loaded
+ @param ImageHandle image handle for the image being loaded
+
+**/
VOID
CoreNewDebugImageInfoEntry (
UINT32 ImageInfoType,
EFI_LOADED_IMAGE_PROTOCOL *LoadedImage,
EFI_HANDLE ImageHandle
)
-/*++
-
-Routine Description:
-
- Adds a new DebugImageInfo structure to the DebugImageInfo Table. Re-Allocates
- the table if it's not large enough to accomidate another entry.
-
-Arguments:
-
- ImageInfoType - type of debug image information
- LoadedImage - pointer to the loaded image protocol for the image being loaded
- ImageHandle - image handle for the image being loaded
-
-Returns:
- NA
-
---*/
;
+
+/**
+ Removes and frees an entry from the DebugImageInfo Table.
+
+ @param ImageHandle image handle for the image being unloaded
+
+**/
VOID
CoreRemoveDebugImageInfoEntry (
EFI_HANDLE ImageHandle
)
-/*++
-
-Routine Description:
-
- Removes and frees an entry from the DebugImageInfo Table.
-
-Arguments:
-
- ImageHandle - image handle for the image being unloaded
-
-Returns:
-
- NA
-
---*/
;
#endif
diff --git a/MdeModulePkg/Core/Dxe/Dispatcher/Dispatcher.c b/MdeModulePkg/Core/Dxe/Dispatcher/Dispatcher.c
index 01d2c9fe5a..554a07c42b 100644
--- a/MdeModulePkg/Core/Dxe/Dispatcher/Dispatcher.c
+++ b/MdeModulePkg/Core/Dxe/Dispatcher/Dispatcher.c
@@ -1,4 +1,4 @@
-/**@file
+/** @file
DXE Dispatcher.
Step #1 - When a FV protocol is added to the system every driver in the FV
@@ -26,7 +26,7 @@
Depex - Dependency Expresion.
SOR - Schedule On Request - Don't schedule if this bit is set.
-Copyright (c) 2006 - 2007, Intel Corporation
+Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -94,12 +94,40 @@ FV_FILEPATH_DEVICE_PATH mFvDevicePath;
//
// Function Prototypes
//
+/**
+ Insert InsertedDriverEntry onto the mScheduledQueue. To do this you
+ must add any driver with a before dependency on InsertedDriverEntry first.
+ You do this by recursively calling this routine. After all the Befores are
+ processed you can add InsertedDriverEntry to the mScheduledQueue.
+ Then you can add any driver with an After dependency on InsertedDriverEntry
+ by recursively calling this routine.
+
+ @param InsertedDriverEntry The driver to insert on the ScheduledLink Queue
+
+**/
STATIC
VOID
CoreInsertOnScheduledQueueWhileProcessingBeforeAndAfter (
IN EFI_CORE_DRIVER_ENTRY *InsertedDriverEntry
);
+/**
+ Event notification that is fired every time a FV dispatch protocol is added.
+ More than one protocol may have been added when this event is fired, so you
+ must loop on CoreLocateHandle () to see how many protocols were added and
+ do the following to each FV:
+ If the Fv has already been processed, skip it. If the Fv has not been
+ processed then mark it as being processed, as we are about to process it.
+ Read the Fv and add any driver in the Fv to the mDiscoveredList.The
+ mDiscoveredList is never free'ed and contains variables that define
+ the other states the DXE driver transitions to..
+ While you are at it read the A Priori file into memory.
+ Place drivers in the A Priori list onto the mScheduledQueue.
+
+ @param Event The Event that is being processed, not used.
+ @param Context Event Context, not used.
+
+**/
STATIC
VOID
EFIAPI
@@ -108,6 +136,19 @@ CoreFwVolEventProtocolNotify (
IN VOID *Context
);
+/**
+ Convert FvHandle and DriverName into an EFI device path
+
+ @param Fv Fv protocol, needed to read Depex info out of
+ FLASH.
+ @param FvHandle Handle for Fv, needed in the
+ EFI_CORE_DRIVER_ENTRY so that the PE image can be
+ read out of the FV at a later time.
+ @param DriverName Name of driver to add to mDiscoveredList.
+
+ @return Pointer to device path constructed from FvHandle and DriverName
+
+**/
STATIC
EFI_DEVICE_PATH_PROTOCOL *
CoreFvToDevicePath (
@@ -116,6 +157,26 @@ CoreFvToDevicePath (
IN EFI_GUID *DriverName
);
+/**
+ Add an entry to the mDiscoveredList. Allocate memory to store the DriverEntry,
+ and initilize any state variables. Read the Depex from the FV and store it
+ in DriverEntry. Pre-process the Depex to set the SOR, Before and After state.
+ The Discovered list is never free'ed and contains booleans that represent the
+ other possible DXE driver states.
+
+ @param Fv Fv protocol, needed to read Depex info out of
+ FLASH.
+ @param FvHandle Handle for Fv, needed in the
+ EFI_CORE_DRIVER_ENTRY so that the PE image can be
+ read out of the FV at a later time.
+ @param DriverName Name of driver to add to mDiscoveredList.
+
+ @retval EFI_SUCCESS If driver was added to the mDiscoveredList.
+ @retval EFI_ALREADY_STARTED The driver has already been started. Only one
+ DriverName may be active in the system at any one
+ time.
+
+**/
STATIC
EFI_STATUS
CoreAddToDriverList (
@@ -124,6 +185,18 @@ CoreAddToDriverList (
IN EFI_GUID *DriverName
);
+/**
+ Get the driver from the FV through driver name, and produce a FVB protocol on FvHandle.
+
+ @param Fv The FIRMWARE_VOLUME protocol installed on the FV.
+ @param FvHandle The handle which FVB protocol installed on.
+ @param DriverName The driver guid specified.
+
+ @retval EFI_OUT_OF_RESOURCES No enough memory or other resource.
+ @retval EFI_VOLUME_CORRUPTED Corrupted volume.
+ @retval EFI_SUCCESS Function successfully returned.
+
+**/
STATIC
EFI_STATUS
CoreProcessFvImageFile (
@@ -132,81 +205,52 @@ CoreProcessFvImageFile (
IN EFI_GUID *DriverName
);
+
+/**
+ Enter critical section by gaining lock on mDispatcherLock.
+
+**/
STATIC
VOID
CoreAcquireDispatcherLock (
VOID
)
-/*++
-
-Routine Description:
-
- Enter critical section by gaining lock on mDispatcherLock
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
-
{
CoreAcquireLock (&mDispatcherLock);
}
+
+/**
+ Exit critical section by releasing lock on mDispatcherLock.
+
+**/
STATIC
VOID
CoreReleaseDispatcherLock (
VOID
)
-/*++
-
-Routine Description:
-
- Exit critical section by releasing lock on mDispatcherLock
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
{
CoreReleaseLock (&mDispatcherLock);
}
+
+/**
+ Read Depex and pre-process the Depex for Before and After. If Section Extraction
+ protocol returns an error via ReadSection defer the reading of the Depex.
+
+ @param DriverEntry Driver to work on.
+
+ @retval EFI_SUCCESS Depex read and preprossesed
+ @retval EFI_PROTOCOL_ERROR The section extraction protocol returned an error
+ and Depex reading needs to be retried.
+ @retval Error DEPEX not found.
+
+**/
STATIC
EFI_STATUS
CoreGetDepexSectionAndPreProccess (
IN EFI_CORE_DRIVER_ENTRY *DriverEntry
)
-/*++
-
-Routine Description:
-
- Read Depex and pre-process the Depex for Before and After. If Section Extraction
- protocol returns an error via ReadSection defer the reading of the Depex.
-
-Arguments:
-
- DriverEntry - Driver to work on.
-
-Returns:
-
- EFI_SUCCESS - Depex read and preprossesed
-
- EFI_PROTOCOL_ERROR - The section extraction protocol returned an error and
- Depex reading needs to be retried.
-
- Other Error - DEPEX not found.
-
---*/
{
EFI_STATUS Status;
EFI_SECTION_TYPE SectionType;
@@ -255,6 +299,21 @@ Returns:
return Status;
}
+
+/**
+ Check every driver and locate a matching one. If the driver is found, the Unrequested
+ state flag is cleared.
+
+ @param FirmwareVolumeHandle The handle of the Firmware Volume that contains
+ the firmware file specified by DriverName.
+ @param DriverName The Driver name to put in the Dependent state.
+
+ @retval EFI_SUCCESS The DriverName was found and it's SOR bit was
+ cleared
+ @retval EFI_NOT_FOUND The DriverName does not exist or it's SOR bit was
+ not set.
+
+**/
EFI_DXESERVICE
EFI_STATUS
EFIAPI
@@ -262,27 +321,6 @@ CoreSchedule (
IN EFI_HANDLE FirmwareVolumeHandle,
IN EFI_GUID *DriverName
)
-/*++
-
-Routine Description:
-
- Check every driver and locate a matching one. If the driver is found, the Unrequested
- state flag is cleared.
-
-Arguments:
-
- FirmwareVolumeHandle - The handle of the Firmware Volume that contains the firmware
- file specified by DriverName.
-
- DriverName - The Driver name to put in the Dependent state.
-
-Returns:
-
- EFI_SUCCESS - The DriverName was found and it's SOR bit was cleared
-
- EFI_NOT_FOUND - The DriverName does not exist or it's SOR bit was not set.
-
---*/
{
LIST_ENTRY *Link;
EFI_CORE_DRIVER_ENTRY *DriverEntry;
@@ -310,6 +348,19 @@ Returns:
}
+
+/**
+ Convert a driver from the Untrused back to the Scheduled state
+
+ @param FirmwareVolumeHandle The handle of the Firmware Volume that contains
+ the firmware file specified by DriverName.
+ @param DriverName The Driver name to put in the Scheduled state
+
+ @retval EFI_SUCCESS The file was found in the untrusted state, and it
+ was promoted to the trusted state.
+ @retval EFI_NOT_FOUND The file was not found in the untrusted state.
+
+**/
EFI_DXESERVICE
EFI_STATUS
EFIAPI
@@ -317,27 +368,6 @@ CoreTrust (
IN EFI_HANDLE FirmwareVolumeHandle,
IN EFI_GUID *DriverName
)
-/*++
-
-Routine Description:
-
- Convert a driver from the Untrused back to the Scheduled state
-
-Arguments:
-
- FirmwareVolumeHandle - The handle of the Firmware Volume that contains the firmware
- file specified by DriverName.
-
- DriverName - The Driver name to put in the Scheduled state
-
-Returns:
-
- EFI_SUCCESS - The file was found in the untrusted state, and it was promoted
- to the trusted state.
-
- EFI_NOT_FOUND - The file was not found in the untrusted state.
-
---*/
{
LIST_ENTRY *Link;
EFI_CORE_DRIVER_ENTRY *DriverEntry;
@@ -366,37 +396,29 @@ Returns:
}
+
+/**
+ This is the main Dispatcher for DXE and it exits when there are no more
+ drivers to run. Drain the mScheduledQueue and load and start a PE
+ image for each driver. Search the mDiscoveredList to see if any driver can
+ be placed on the mScheduledQueue. If no drivers are placed on the
+ mScheduledQueue exit the function. On exit it is assumed the Bds()
+ will be called, and when the Bds() exits the Dispatcher will be called
+ again.
+
+ NONE
+
+ @retval EFI_ALREADY_STARTED The DXE Dispatcher is already running
+ @retval EFI_NOT_FOUND No DXE Drivers were dispatched
+ @retval EFI_SUCCESS One or more DXE Drivers were dispatched
+
+**/
EFI_DXESERVICE
EFI_STATUS
EFIAPI
CoreDispatcher (
VOID
)
-/*++
-
-Routine Description:
-
- This is the main Dispatcher for DXE and it exits when there are no more
- drivers to run. Drain the mScheduledQueue and load and start a PE
- image for each driver. Search the mDiscoveredList to see if any driver can
- be placed on the mScheduledQueue. If no drivers are placed on the
- mScheduledQueue exit the function. On exit it is assumed the Bds()
- will be called, and when the Bds() exits the Dispatcher will be called
- again.
-
-Arguments:
-
- NONE
-
-Returns:
-
- EFI_ALREADY_STARTED - The DXE Dispatcher is already running
-
- EFI_NOT_FOUND - No DXE Drivers were dispatched
-
- EFI_SUCCESS - One or more DXE Drivers were dispatched
-
---*/
{
EFI_STATUS Status;
EFI_STATUS ReturnStatus;
@@ -524,31 +546,23 @@ Returns:
return ReturnStatus;
}
+
+/**
+ Insert InsertedDriverEntry onto the mScheduledQueue. To do this you
+ must add any driver with a before dependency on InsertedDriverEntry first.
+ You do this by recursively calling this routine. After all the Befores are
+ processed you can add InsertedDriverEntry to the mScheduledQueue.
+ Then you can add any driver with an After dependency on InsertedDriverEntry
+ by recursively calling this routine.
+
+ @param InsertedDriverEntry The driver to insert on the ScheduledLink Queue
+
+**/
STATIC
VOID
CoreInsertOnScheduledQueueWhileProcessingBeforeAndAfter (
IN EFI_CORE_DRIVER_ENTRY *InsertedDriverEntry
)
-/*++
-
-Routine Description:
-
- Insert InsertedDriverEntry onto the mScheduledQueue. To do this you
- must add any driver with a before dependency on InsertedDriverEntry first.
- You do this by recursively calling this routine. After all the Befores are
- processed you can add InsertedDriverEntry to the mScheduledQueue.
- Then you can add any driver with an After dependency on InsertedDriverEntry
- by recursively calling this routine.
-
-Arguments:
-
- InsertedDriverEntry - The driver to insert on the ScheduledLink Queue
-
-Returns:
-
- NONE
-
---*/
{
LIST_ENTRY *Link;
EFI_CORE_DRIVER_ENTRY *DriverEntry;
@@ -595,28 +609,22 @@ Returns:
}
}
+
+/**
+ Return TRUE if the Fv has been processed, FALSE if not.
+
+ @param FvHandle The handle of a FV that's being tested
+
+ @retval TRUE Fv protocol on FvHandle has been processed
+ @retval FALSE Fv protocol on FvHandle has not yet been
+ processed
+
+**/
STATIC
BOOLEAN
FvHasBeenProcessed (
IN EFI_HANDLE FvHandle
)
-/*++
-
-Routine Description:
-
- Return TRUE if the Fv has been processed, FALSE if not.
-
-Arguments:
-
- FvHandle - The handle of a FV that's being tested
-
-Returns:
-
- TRUE - Fv protocol on FvHandle has been processed
-
- FALSE - Fv protocol on FvHandle has not yet been processed
-
---*/
{
LIST_ENTRY *Link;
KNOWN_HANDLE *KnownHandle;
@@ -630,28 +638,20 @@ Returns:
return FALSE;
}
+
+/**
+ Remember that Fv protocol on FvHandle has had it's drivers placed on the
+ mDiscoveredList. This fucntion adds entries on the mFvHandleList. Items are
+ never removed/freed from the mFvHandleList.
+
+ @param FvHandle The handle of a FV that has been processed
+
+**/
STATIC
VOID
FvIsBeingProcesssed (
IN EFI_HANDLE FvHandle
)
-/*++
-
-Routine Description:
-
- Remember that Fv protocol on FvHandle has had it's drivers placed on the
- mDiscoveredList. This fucntion adds entries on the mFvHandleList. Items are
- never removed/freed from the mFvHandleList.
-
-Arguments:
-
- FvHandle - The handle of a FV that has been processed
-
-Returns:
-
- None
-
---*/
{
KNOWN_HANDLE *KnownHandle;
@@ -665,6 +665,20 @@ Returns:
+
+/**
+ Convert FvHandle and DriverName into an EFI device path
+
+ @param Fv Fv protocol, needed to read Depex info out of
+ FLASH.
+ @param FvHandle Handle for Fv, needed in the
+ EFI_CORE_DRIVER_ENTRY so that the PE image can be
+ read out of the FV at a later time.
+ @param DriverName Name of driver to add to mDiscoveredList.
+
+ @return Pointer to device path constructed from FvHandle and DriverName
+
+**/
STATIC
EFI_DEVICE_PATH_PROTOCOL *
CoreFvToDevicePath (
@@ -672,26 +686,6 @@ CoreFvToDevicePath (
IN EFI_HANDLE FvHandle,
IN EFI_GUID *DriverName
)
-/*++
-
-Routine Description:
-
- Convert FvHandle and DriverName into an EFI device path
-
-Arguments:
-
- Fv - Fv protocol, needed to read Depex info out of FLASH.
-
- FvHandle - Handle for Fv, needed in the EFI_CORE_DRIVER_ENTRY so that the
- PE image can be read out of the FV at a later time.
-
- DriverName - Name of driver to add to mDiscoveredList.
-
-Returns:
-
- Pointer to device path constructed from FvHandle and DriverName
-
---*/
{
EFI_STATUS Status;
EFI_DEVICE_PATH_PROTOCOL *FvDevicePath;
@@ -723,39 +717,33 @@ Returns:
+
+/**
+ Add an entry to the mDiscoveredList. Allocate memory to store the DriverEntry,
+ and initilize any state variables. Read the Depex from the FV and store it
+ in DriverEntry. Pre-process the Depex to set the SOR, Before and After state.
+ The Discovered list is never free'ed and contains booleans that represent the
+ other possible DXE driver states.
+
+ @param Fv Fv protocol, needed to read Depex info out of
+ FLASH.
+ @param FvHandle Handle for Fv, needed in the
+ EFI_CORE_DRIVER_ENTRY so that the PE image can be
+ read out of the FV at a later time.
+ @param DriverName Name of driver to add to mDiscoveredList.
+
+ @retval EFI_SUCCESS If driver was added to the mDiscoveredList.
+ @retval EFI_ALREADY_STARTED The driver has already been started. Only one
+ DriverName may be active in the system at any one
+ time.
+
+**/
EFI_STATUS
CoreAddToDriverList (
IN EFI_FIRMWARE_VOLUME2_PROTOCOL *Fv,
IN EFI_HANDLE FvHandle,
IN EFI_GUID *DriverName
)
-/*++
-
-Routine Description:
-
- Add an entry to the mDiscoveredList. Allocate memory to store the DriverEntry,
- and initilize any state variables. Read the Depex from the FV and store it
- in DriverEntry. Pre-process the Depex to set the SOR, Before and After state.
- The Discovered list is never free'ed and contains booleans that represent the
- other possible DXE driver states.
-
-Arguments:
-
- Fv - Fv protocol, needed to read Depex info out of FLASH.
-
- FvHandle - Handle for Fv, needed in the EFI_CORE_DRIVER_ENTRY so that the
- PE image can be read out of the FV at a later time.
-
- DriverName - Name of driver to add to mDiscoveredList.
-
-Returns:
-
- EFI_SUCCESS - If driver was added to the mDiscoveredList.
-
- EFI_ALREADY_STARTED - The driver has already been started. Only one DriverName
- may be active in the system at any one time.
-
---*/
{
EFI_CORE_DRIVER_ENTRY *DriverEntry;
@@ -784,32 +772,25 @@ Returns:
return EFI_SUCCESS;
}
+
+/**
+ Check if a FV Image type file (EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE) is
+ described by a EFI_HOB_FIRMWARE_VOLUME2 Hob.
+
+ @param FvHandle The handle which FVB protocol installed on.
+ @param DriverName The driver guid specified.
+
+ @retval TRUE This file is found in a EFI_HOB_FIRMWARE_VOLUME2
+ Hob.
+ @retval FALSE Not found.
+
+**/
STATIC
BOOLEAN
FvFoundInHobFv2 (
IN EFI_HANDLE FvHandle,
IN CONST EFI_GUID *DriverName
)
-/*++
-
-Routine Description:
-
- Check if a FV Image type file (EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE) is
- described by a EFI_HOB_FIRMWARE_VOLUME2 Hob.
-
-Arguments:
-
- FvHandle - The handle which FVB protocol installed on.
- DriverName - The driver guid specified.
-
-Returns:
-
- TRUE - This file is found in a EFI_HOB_FIRMWARE_VOLUME2 Hob.
-
- FALSE - Not found.
-
-
---*/
{
EFI_PEI_HOB_POINTERS HobFv2;
@@ -826,34 +807,25 @@ Returns:
}
+
+/**
+ Get the driver from the FV through driver name, and produce a FVB protocol on FvHandle.
+
+ @param Fv The FIRMWARE_VOLUME protocol installed on the FV.
+ @param FvHandle The handle which FVB protocol installed on.
+ @param DriverName The driver guid specified.
+
+ @retval EFI_OUT_OF_RESOURCES No enough memory or other resource.
+ @retval EFI_VOLUME_CORRUPTED Corrupted volume.
+ @retval EFI_SUCCESS Function successfully returned.
+
+**/
EFI_STATUS
CoreProcessFvImageFile (
IN EFI_FIRMWARE_VOLUME2_PROTOCOL *Fv,
IN EFI_HANDLE FvHandle,
IN EFI_GUID *DriverName
)
-/*++
-
-Routine Description:
-
- Get the driver from the FV through driver name, and produce a FVB protocol on FvHandle.
-
-Arguments:
-
- Fv - The FIRMWARE_VOLUME protocol installed on the FV.
- FvHandle - The handle which FVB protocol installed on.
- DriverName - The driver guid specified.
-
-Returns:
-
- EFI_OUT_OF_RESOURCES - No enough memory or other resource.
-
- EFI_VOLUME_CORRUPTED - Corrupted volume.
-
- EFI_SUCCESS - Function successfully returned.
-
-
---*/
{
EFI_STATUS Status;
EFI_SECTION_TYPE SectionType;
@@ -932,6 +904,24 @@ Returns:
return Status;
}
+
+/**
+ Event notification that is fired every time a FV dispatch protocol is added.
+ More than one protocol may have been added when this event is fired, so you
+ must loop on CoreLocateHandle () to see how many protocols were added and
+ do the following to each FV:
+ If the Fv has already been processed, skip it. If the Fv has not been
+ processed then mark it as being processed, as we are about to process it.
+ Read the Fv and add any driver in the Fv to the mDiscoveredList.The
+ mDiscoveredList is never free'ed and contains variables that define
+ the other states the DXE driver transitions to..
+ While you are at it read the A Priori file into memory.
+ Place drivers in the A Priori list onto the mScheduledQueue.
+
+ @param Event The Event that is being processed, not used.
+ @param Context Event Context, not used.
+
+**/
STATIC
VOID
EFIAPI
@@ -939,36 +929,6 @@ CoreFwVolEventProtocolNotify (
IN EFI_EVENT Event,
IN VOID *Context
)
-/*++
-
-Routine Description:
-
- Event notification that is fired every time a FV dispatch protocol is added.
- More than one protocol may have been added when this event is fired, so you
- must loop on CoreLocateHandle () to see how many protocols were added and
- do the following to each FV:
-
- If the Fv has already been processed, skip it. If the Fv has not been
- processed then mark it as being processed, as we are about to process it.
-
- Read the Fv and add any driver in the Fv to the mDiscoveredList.The
- mDiscoveredList is never free'ed and contains variables that define
- the other states the DXE driver transitions to..
-
- While you are at it read the A Priori file into memory.
- Place drivers in the A Priori list onto the mScheduledQueue.
-
-Arguments:
-
- Event - The Event that is being processed, not used.
-
- Context - Event Context, not used.
-
-Returns:
-
- None
-
---*/
{
EFI_STATUS Status;
EFI_STATUS GetNextFileStatus;
@@ -1181,26 +1141,16 @@ Returns:
}
+
+/**
+ Initialize the dispatcher. Initialize the notification function that runs when
+ a FV protocol is added to the system.
+
+**/
VOID
CoreInitializeDispatcher (
VOID
)
-/*++
-
-Routine Description:
-
- Initialize the dispatcher. Initialize the notification function that runs when
- a FV protocol is added to the system.
-
-Arguments:
-
- NONE
-
-Returns:
-
- NONE
-
---*/
{
mFwVolEvent = CoreCreateProtocolNotifyEvent (
&gEfiFirmwareVolume2ProtocolGuid,
@@ -1215,26 +1165,16 @@ Returns:
//
// Function only used in debug builds
//
+
+/**
+ Traverse the discovered list for any drivers that were discovered but not loaded
+ because the dependency experessions evaluated to false.
+
+**/
VOID
CoreDisplayDiscoveredNotDispatched (
VOID
)
-/*++
-
-Routine Description:
-
- Traverse the discovered list for any drivers that were discovered but not loaded
- because the dependency experessions evaluated to false
-
-Arguments:
-
- NONE
-
-Returns:
-
- NONE
-
---*/
{
LIST_ENTRY *Link;
EFI_CORE_DRIVER_ENTRY *DriverEntry;
@@ -1242,7 +1182,7 @@ Returns:
for (Link = mDiscoveredList.ForwardLink;Link !=&mDiscoveredList; Link = Link->ForwardLink) {
DriverEntry = CR(Link, EFI_CORE_DRIVER_ENTRY, Link, EFI_CORE_DRIVER_ENTRY_SIGNATURE);
if (DriverEntry->Dependent) {
- DEBUG ((EFI_D_LOAD, "Driver %g was discovered but not loaded!!\n", &DriverEntry->FileName));
+ DEBUG ((DEBUG_LOAD, "Driver %g was discovered but not loaded!!\n", &DriverEntry->FileName));
}
}
}
diff --git a/MdeModulePkg/Core/Dxe/Dispatcher/dependency.c b/MdeModulePkg/Core/Dxe/Dispatcher/dependency.c
index 62bdb14e40..21f08c2a9c 100644
--- a/MdeModulePkg/Core/Dxe/Dispatcher/dependency.c
+++ b/MdeModulePkg/Core/Dxe/Dispatcher/dependency.c
@@ -30,32 +30,20 @@ BOOLEAN *mDepexEvaluationStackPointer = NULL;
// Worker functions
//
+
+/**
+ Grow size of the Depex stack
+
+ @retval EFI_SUCCESS Stack successfully growed.
+ @retval EFI_OUT_OF_RESOURCES There is not enough system memory to grow the
+ stack.
+
+**/
STATIC
EFI_STATUS
GrowDepexStack (
VOID
)
-/*++
-
-Routine Description:
-
- Grow size of the Depex stack
-
-Arguments:
-
- Stack - Old stack on the way in and new stack on the way out
-
- StackSize - New size of the stack
-
-Returns:
-
- EFI_SUCCESS - Stack successfully growed.
-
- EFI_OUT_OF_RESOURCES - There is not enough system memory to grow the stack.
-
-
-
---*/
{
BOOLEAN *NewStack;
UINTN Size;
@@ -97,28 +85,22 @@ Returns:
}
+
+/**
+ Push an element onto the Boolean Stack
+
+ @param Value BOOLEAN to push.
+
+ @retval EFI_SUCCESS The value was pushed onto the stack.
+ @retval EFI_OUT_OF_RESOURCES There is not enough system memory to grow the
+ stack.
+
+**/
STATIC
EFI_STATUS
PushBool (
IN BOOLEAN Value
)
-/*++
-
-Routine Description:
-
- Push an element onto the Boolean Stack
-
-Arguments:
-
- Value - BOOLEAN to push.
-
-Returns:
-
- EFI_SUCCESS - The value was pushed onto the stack.
-
- EFI_OUT_OF_RESOURCES - There is not enough system memory to grow the stack.
-
---*/
{
EFI_STATUS Status;
@@ -145,28 +127,21 @@ Returns:
}
+
+/**
+ Pop an element from the Boolean stack.
+
+ @param Value BOOLEAN to pop.
+
+ @retval EFI_SUCCESS The value was popped onto the stack.
+ @retval EFI_ACCESS_DENIED The pop operation underflowed the stack
+
+**/
STATIC
EFI_STATUS
PopBool (
OUT BOOLEAN *Value
)
-/*++
-
-Routine Description:
-
- Pop an element from the Boolean stack.
-
-Arguments:
-
- Value - BOOLEAN to pop.
-
-Returns:
-
- EFI_SUCCESS - The value was popped onto the stack.
-
- EFI_ACCESS_DENIED - The pop operation underflowed the stack
-
---*/
{
//
// Check for a stack underflow condition
@@ -184,29 +159,23 @@ Returns:
}
+
+/**
+ Preprocess dependency expression and update DriverEntry to reflect the
+ state of Before, After, and SOR dependencies. If DriverEntry->Before
+ or DriverEntry->After is set it will never be cleared. If SOR is set
+ it will be cleared by CoreSchedule(), and then the driver can be
+ dispatched.
+
+ @param DriverEntry DriverEntry element to update
+
+ @retval EFI_SUCCESS It always works.
+
+**/
EFI_STATUS
CorePreProcessDepex (
IN EFI_CORE_DRIVER_ENTRY *DriverEntry
)
-/*++
-
-Routine Description:
-
- Preprocess dependency expression and update DriverEntry to reflect the
- state of Before, After, and SOR dependencies. If DriverEntry->Before
- or DriverEntry->After is set it will never be cleared. If SOR is set
- it will be cleared by CoreSchedule(), and then the driver can be
- dispatched.
-
-Arguments:
-
- DriverEntry - DriverEntry element to update
-
-Returns:
-
- EFI_SUCCESS - It always works.
-
---*/
{
UINT8 *Iterator;
@@ -231,31 +200,24 @@ Returns:
}
+
+/**
+ This is the POSTFIX version of the dependency evaluator. This code does
+ not need to handle Before or After, as it is not valid to call this
+ routine in this case. The SOR is just ignored and is a nop in the grammer.
+ POSTFIX means all the math is done on top of the stack.
+
+ @param DriverEntry DriverEntry element to update
+
+ @retval TRUE If driver is ready to run.
+ @retval FALSE If driver is not ready to run or some fatal error
+ was found.
+
+**/
BOOLEAN
CoreIsSchedulable (
IN EFI_CORE_DRIVER_ENTRY *DriverEntry
)
-/*++
-
-Routine Description:
-
- This is the POSTFIX version of the dependency evaluator. This code does
- not need to handle Before or After, as it is not valid to call this
- routine in this case. The SOR is just ignored and is a nop in the grammer.
-
- POSTFIX means all the math is done on top of the stack.
-
-Arguments:
-
- DriverEntry - DriverEntry element to update
-
-Returns:
-
- TRUE - If driver is ready to run.
-
- FALSE - If driver is not ready to run or some fatal error was found.
-
---*/
{
EFI_STATUS Status;
UINT8 *Iterator;
@@ -444,3 +406,4 @@ Done:
return FALSE;
}
+
diff --git a/MdeModulePkg/Core/Dxe/DxeMain.h b/MdeModulePkg/Core/Dxe/DxeMain.h
index 2830e10a03..30f7fe33be 100644
--- a/MdeModulePkg/Core/Dxe/DxeMain.h
+++ b/MdeModulePkg/Core/Dxe/DxeMain.h
@@ -1,9 +1,9 @@
-/**@file
+/** @file
The internal header file includes the common header files, defines
internal structure and functions used by DxeCore module.
-Copyright (c) 2006 - 2007, Intel Corporation
+Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -230,27 +230,33 @@ extern EFI_RUNTIME_ARCH_PROTOCOL gRuntimeTemplate;
//
+
+/**
+ Called to initialize the pool.
+
+**/
VOID
CoreInitializePool (
VOID
)
-/*++
-
-Routine Description:
-
- Called to initialize the pool.
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
;
+
+/**
+ Called to initialize the memory map and add descriptors to
+ the current descriptor list.
+ The first descriptor that is added must be general usable
+ memory as the addition allocates heap.
+
+ @param Type The type of memory to add
+ @param Start The starting address in the memory range Must be
+ page aligned
+ @param NumberOfPages The number of pages in the range
+ @param Attribute Attributes of the memory to add
+
+ @return None. The range is added to the memory map
+
+**/
VOID
CoreAddMemoryDescriptor (
IN EFI_MEMORY_TYPE Type,
@@ -258,114 +264,59 @@ CoreAddMemoryDescriptor (
IN UINT64 NumberOfPages,
IN UINT64 Attribute
)
-/*++
-
-Routine Description:
-
- Called to initialize the memory map and add descriptors to
- the current descriptor list.
-
- The first descriptor that is added must be general usable
- memory as the addition allocates heap.
-
-Arguments:
-
- Type - The type of memory to add
-
- Start - The starting address in the memory range
- Must be page aligned
-
- NumberOfPages - The number of pages in the range
-
- Attribute - Attributes of the memory to add
-
-Returns:
-
- None. The range is added to the memory map
-
---*/
;
+
+/**
+ Release memory lock on mGcdMemorySpaceLock.
+
+**/
VOID
CoreReleaseGcdMemoryLock (
VOID
)
-/*++
-
-Routine Description:
- Release memory lock on mGcdMemorySpaceLock
-
-Arguments:
- None
-
-Returns:
- None
-
---*/
;
+
+/**
+ Acquire memory lock on mGcdMemorySpaceLock.
+
+**/
VOID
CoreAcquireGcdMemoryLock (
VOID
)
-/*++
-
-Routine Description:
- Acquire memory lock on mGcdMemorySpaceLock
-
-Arguments:
- None
-
-Returns:
- None
-
---*/
;
-EFI_STATUS
-CoreInitializeMemoryServices (
- IN VOID **HobStart,
- IN EFI_PHYSICAL_ADDRESS *MemoryBaseAddress,
- IN UINT64 *MemoryLength
- )
-/*++
-Routine Description:
-
- External function. Initializes the GCD and memory services based on the memory
+/**
+ External function. Initializes the GCD and memory services based on the memory
descriptor HOBs. This function is responsible for priming the GCD map and the
memory map, so memory allocations and resource allocations can be made. The first
part of this function can not depend on any memory services until at least one
memory descriptor is provided to the memory services. Then the memory services
can be used to intialize the GCD map.
-Arguments:
+ @param HobStart The start address of the HOB.
+ @param MemoryBaseAddress Start address of memory region found to init DXE
+ core.
+ @param MemoryLength Length of memory region found to init DXE core.
- HobStart - The start address of the HOB.
-
- MemoryBaseAddress - Start address of memory region found to init DXE core.
-
- MemoryLength - Length of memory region found to init DXE core.
+ @retval EFI_SUCCESS Memory services successfully initialized.
-Returns:
-
- EFI_SUCCESS - Memory services successfully initialized.
-
---*/
+**/
+EFI_STATUS
+CoreInitializeMemoryServices (
+ IN VOID **HobStart,
+ IN EFI_PHYSICAL_ADDRESS *MemoryBaseAddress,
+ IN UINT64 *MemoryLength
+ )
;
-EFI_STATUS
-CoreInitializeGcdServices (
- IN OUT VOID **HobStart,
- IN EFI_PHYSICAL_ADDRESS MemoryBaseAddress,
- IN UINT64 MemoryLength
- )
-/*++
-Routine Description:
-
- External function. Initializes the GCD and memory services based on the memory
+/**
+ External function. Initializes the GCD and memory services based on the memory
descriptor HOBs. This function is responsible for priming the GCD map and the
memory map, so memory allocations and resource allocations can be made. The first
part of this function can not depend on any memory services until at least one
@@ -373,397 +324,311 @@ Routine Description:
can be used to intialize the GCD map. The HobStart will be relocated to a pool
buffer.
-Arguments:
+ @param HobStart The start address of the HOB
+ @param MemoryBaseAddress Start address of memory region found to init DXE
+ core.
+ @param MemoryLength Length of memory region found to init DXE core.
- HobStart - The start address of the HOB
-
- MemoryBaseAddress - Start address of memory region found to init DXE core.
-
- MemoryLength - Length of memory region found to init DXE core.
+ @retval EFI_SUCCESS GCD services successfully initialized.
-
-Returns:
-
- EFI_SUCCESS - GCD services successfully initialized.
-
---*/
+**/
+EFI_STATUS
+CoreInitializeGcdServices (
+ IN OUT VOID **HobStart,
+ IN EFI_PHYSICAL_ADDRESS MemoryBaseAddress,
+ IN UINT64 MemoryLength
+ )
;
+
+/**
+ Initializes "event" support and populates parts of the System and Runtime Table.
+
+
+ @retval EFI_SUCCESS Always return success
+
+**/
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
-
---*/
;
+
+/**
+ Add the Image Services to EFI Boot Services Table and install the protocol
+ interfaces for this image.
+
+ @param HobStart The HOB to initialize
+
+ @return Status code.
+
+**/
EFI_STATUS
CoreInitializeImageServices (
IN VOID *HobStart
)
-/*++
-
-Routine Description:
-
- Add the Image Services to EFI Boot Services Table and install the protocol
- interfaces for this image.
-
-Arguments:
-
- HobStart - The HOB to initialize
-
-Returns:
-
- Status code.
-
---*/
;
+
+/**
+ Creates an event that is fired everytime a Protocol of a specific type is installed.
+
+**/
VOID
CoreNotifyOnArchProtocolInstallation (
VOID
)
-/*++
-
-Routine Description:
- Creates an event that is fired everytime a Protocol of a specific type is installed
-
-Arguments:
- NONE
-
-Returns:
- NONE
-
---*/
;
+
+/**
+ Return TRUE if all AP services are availible.
+
+
+ @retval EFI_SUCCESS All AP services are available
+ @retval EFI_NOT_FOUND At least one AP service is not available
+
+**/
EFI_STATUS
CoreAllEfiServicesAvailable (
VOID
)
-/*++
-
-Routine Description:
- Return TRUE if all AP services are availible.
-
-Arguments:
- NONE
-
-Returns:
- EFI_SUCCESS - All AP services are available
- EFI_NOT_FOUND - At least one AP service is not available
-
---*/
;
+
+/**
+ Calcualte the 32-bit CRC in a EFI table using the service provided by the
+ gRuntime service.
+
+ @param Hdr Pointer to an EFI standard header
+
+**/
VOID
CalculateEfiHdrCrc (
IN OUT EFI_TABLE_HEADER *Hdr
)
-/*++
-
-Routine Description:
-
- Calcualte the 32-bit CRC in a EFI table using the service provided by the
- gRuntime service.
-
-Arguments:
-
- Hdr - Pointer to an EFI standard header
-
-Returns:
-
- None
-
---*/
;
+
+/**
+ 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
-
---*/
;
+
+/**
+ Initialize the dispatcher. Initialize the notification function that runs when
+ a FV protocol is added to the system.
+
+**/
VOID
CoreInitializeDispatcher (
VOID
)
-/*++
-
-Routine Description:
-
- Initialize the dispatcher. Initialize the notification function that runs when
- a FV protocol is added to the system.
-
-Arguments:
-
- NONE
-
-Returns:
-
- NONE
-
---*/
;
+
+/**
+ This is the POSTFIX version of the dependency evaluator. This code does
+ not need to handle Before or After, as it is not valid to call this
+ routine in this case. The SOR is just ignored and is a nop in the grammer.
+ POSTFIX means all the math is done on top of the stack.
+
+ @param DriverEntry DriverEntry element to update
+
+ @retval TRUE If driver is ready to run.
+ @retval FALSE If driver is not ready to run or some fatal error
+ was found.
+
+**/
BOOLEAN
CoreIsSchedulable (
IN EFI_CORE_DRIVER_ENTRY *DriverEntry
)
-/*++
-
-Routine Description:
-
- This is the POSTFIX version of the dependency evaluator. This code does
- not need to handle Before or After, as it is not valid to call this
- routine in this case. The SOR is just ignored and is a nop in the grammer.
-
- POSTFIX means all the math is done on top of the stack.
-
-Arguments:
-
- DriverEntry - DriverEntry element to update
-
-Returns:
-
- TRUE - If driver is ready to run.
-
- FALSE - If driver is not ready to run or some fatal error was found.
-
---*/
;
+
+/**
+ Preprocess dependency expression and update DriverEntry to reflect the
+ state of Before, After, and SOR dependencies. If DriverEntry->Before
+ or DriverEntry->After is set it will never be cleared. If SOR is set
+ it will be cleared by CoreSchedule(), and then the driver can be
+ dispatched.
+
+ @param DriverEntry DriverEntry element to update
+
+ @retval EFI_SUCCESS It always works.
+
+**/
EFI_STATUS
CorePreProcessDepex (
IN EFI_CORE_DRIVER_ENTRY *DriverEntry
)
-/*++
-
-Routine Description:
-
- Preprocess dependency expression and update DriverEntry to reflect the
- state of Before, After, and SOR dependencies. If DriverEntry->Before
- or DriverEntry->After is set it will never be cleared. If SOR is set
- it will be cleared by CoreSchedule(), and then the driver can be
- dispatched.
-
-Arguments:
-
- DriverEntry - DriverEntry element to update
-
-Returns:
-
- EFI_SUCCESS - It always works.
-
---*/
;
+
+/**
+ Terminates all boot services.
+
+ @param ImageHandle Handle that identifies the exiting image.
+ @param MapKey Key to the latest memory map.
+
+ @retval EFI_SUCCESS Boot Services terminated
+ @retval EFI_INVALID_PARAMETER MapKey is incorrect.
+
+**/
EFI_STATUS
EFIAPI
CoreExitBootServices (
IN EFI_HANDLE ImageHandle,
IN UINTN MapKey
)
-/*++
-
-Routine Description:
-
- UEFI 2.0 API to terminate Boot Services
-
-Arguments:
-
- ImageHandle - Handle that represents the identity of the calling image
-
- MapKey -Key to the latest memory map.
-
-Returns:
-
- EFI_SUCCESS - Boot Services terminated
- EFI_INVALID_PARAMETER - MapKey is incorrect.
-
---*/
;
+
+/**
+ Make sure the memory map is following all the construction rules,
+ it is the last time to check memory map error before exit boot services.
+
+ @param MapKey Memory map key
+
+ @retval EFI_INVALID_PARAMETER Memory map not consistent with construction
+ rules.
+ @retval EFI_SUCCESS Valid memory map.
+
+**/
EFI_STATUS
CoreTerminateMemoryMap (
IN UINTN MapKey
)
-/*++
-
-Routine Description:
-
- Make sure the memory map is following all the construction rules,
- it is the last time to check memory map error before exit boot services.
-
-Arguments:
-
- MapKey - Memory map key
-
-Returns:
-
- EFI_INVALID_PARAMETER - Memory map not consistent with construction rules.
-
- EFI_SUCCESS - Valid memory map.
-
---*/
;
+
+/**
+ Signals all events in the EventGroup.
+
+ @param EventGroup The list to signal
+
+**/
VOID
CoreNotifySignalList (
IN EFI_GUID *EventGroup
)
-/*++
-
-Routine Description:
-
- Signals all events on the requested list
-
-Arguments:
-
- SignalType - The list to signal
-
-Returns:
-
- None
-
---*/
;
+
+/**
+ Boot Service called to add, modify, or remove a system configuration table from
+ the EFI System Table.
+
+ @param Guid Pointer to the GUID for the entry to add, update, or
+ remove
+ @param Table Pointer to the configuration table for the entry to add,
+ update, or remove, may be NULL.
+
+ @return EFI_SUCCESS Guid, Table pair added, updated, or removed.
+ @return EFI_INVALID_PARAMETER Input GUID not valid.
+ @return EFI_NOT_FOUND Attempted to delete non-existant entry
+ @return EFI_OUT_OF_RESOURCES Not enough memory available
+
+**/
EFI_STATUS
EFIAPI
CoreInstallConfigurationTable (
IN EFI_GUID *Guid,
IN VOID *Table
)
-/*++
-
-Routine Description:
-
- Boot Service called to add, modify, or remove a system configuration table from
- the EFI System Table.
-
-Arguments:
-
- Guid: Pointer to the GUID for the entry to add, update, or remove
- Table: Pointer to the configuration table for the entry to add, update, or
- remove, may be NULL.
-
-Returns:
-
- EFI_SUCCESS Guid, Table pair added, updated, or removed.
- EFI_INVALID_PARAMETER Input GUID not valid.
- EFI_NOT_FOUND Attempted to delete non-existant entry
- EFI_OUT_OF_RESOURCES Not enough memory available
-
---*/
;
+
+/**
+ Raise the task priority level to the new level.
+ High level is implemented by disabling processor interrupts.
+
+ @param NewTpl New task priority level
+
+ @return The previous task priority level
+
+**/
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:
-
- The previous task priority level
-
---*/
;
+
+/**
+ 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
-
---*/
;
+
+/**
+ Introduces a fine-grained stall.
+
+ @param Microseconds The number of microseconds to stall execution.
+
+ @retval EFI_SUCCESS Execution was stalled for at least the requested
+ amount of microseconds.
+ @retval EFI_NOT_AVAILABLE_YET gMetronome is not available yet
+
+**/
EFI_STATUS
EFIAPI
CoreStall (
IN UINTN Microseconds
)
-/*++
-
-Routine Description:
-
- Introduces a fine-grained stall.
-
-Arguments:
-
- Microseconds The number of microseconds to stall execution
-
-Returns:
-
- EFI_SUCCESS - Execution was stalled for at least the requested amount
- of microseconds.
-
- EFI_NOT_AVAILABLE_YET - gMetronome is not available yet
-
---*/
;
+
+/**
+ Sets the system's watchdog timer.
+
+ @param Timeout The number of seconds to set the watchdog timer to.
+ A value of zero disables the timer.
+ @param WatchdogCode The numeric code to log on a watchdog timer timeout
+ event. The firmware reserves codes 0x0000 to 0xFFFF.
+ Loaders and operating systems may use other timeout
+ codes.
+ @param DataSize The size, in bytes, of WatchdogData.
+ @param WatchdogData A data buffer that includes a Null-terminated Unicode
+ string, optionally followed by additional binary data.
+ The string is a description that the call may use to
+ further indicate the reason to be logged with a
+ watchdog event.
+
+ @return EFI_SUCCESS Timeout has been set
+ @return EFI_NOT_AVAILABLE_YET WatchdogTimer is not available yet
+ @return EFI_UNSUPPORTED System does not have a timer (currently not used)
+ @return EFI_DEVICE_ERROR Could not complete due to hardware error
+
+**/
EFI_STATUS
EFIAPI
CoreSetWatchdogTimer (
@@ -772,34 +637,24 @@ CoreSetWatchdogTimer (
IN UINTN DataSize,
IN CHAR16 *WatchdogData OPTIONAL
)
-/*++
-
-Routine Description:
-
- Sets the system's watchdog timer.
-
-Arguments:
-
- Timeout The number of seconds. Zero disables the timer.
-
- ///////following three parameters are left for platform specific using
-
- WatchdogCode The numberic code to log. 0x0 to 0xffff are firmware
- DataSize Size of the optional data
- WatchdogData Optional Null terminated unicode string followed by binary
- data.
-
-Returns:
-
- EFI_SUCCESS Timeout has been set
- EFI_NOT_AVAILABLE_YET WatchdogTimer is not available yet
- EFI_UNSUPPORTED System does not have a timer (currently not used)
- EFI_DEVICE_ERROR Could not complete due to hardware error
-
---*/
;
+
+/**
+ Wrapper function to CoreInstallProtocolInterfaceNotify. This is the public API which
+ Calls the private one which contains a BOOLEAN parameter for notifications
+
+ @param UserHandle The handle to install the protocol handler on,
+ or NULL if a new handle is to be allocated
+ @param Protocol The protocol to add to the handle
+ @param InterfaceType Indicates whether Interface is supplied in
+ native form.
+ @param Interface The interface for the protocol being added
+
+ @return Status code
+
+**/
EFI_STATUS
EFIAPI
CoreInstallProtocolInterface (
@@ -808,31 +663,26 @@ CoreInstallProtocolInterface (
IN EFI_INTERFACE_TYPE InterfaceType,
IN VOID *Interface
)
-/*++
-
-Routine Description:
-
- Wrapper function to CoreInstallProtocolInterfaceNotify. This is the public API which
- Calls the private one which contains a BOOLEAN parameter for notifications
-
-Arguments:
-
- UserHandle - The handle to install the protocol handler on,
- or NULL if a new handle is to be allocated
-
- Protocol - The protocol to add to the handle
-
- InterfaceType - Indicates whether Interface is supplied in native form.
-
- Interface - The interface for the protocol being added
-
-Returns:
-
- Status code
-
---*/
;
+
+/**
+ Installs a protocol interface into the boot services environment.
+
+ @param UserHandle The handle to install the protocol handler on,
+ or NULL if a new handle is to be allocated
+ @param Protocol The protocol to add to the handle
+ @param InterfaceType Indicates whether Interface is supplied in
+ native form.
+ @param Interface The interface for the protocol being added
+ @param Notify indicates whether notify the notification list
+ for this protocol
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
+ @retval EFI_SUCCESS Protocol interface successfully installed
+
+**/
EFI_STATUS
CoreInstallProtocolInterfaceNotify (
IN OUT EFI_HANDLE *UserHandle,
@@ -841,100 +691,75 @@ CoreInstallProtocolInterfaceNotify (
IN VOID *Interface,
IN BOOLEAN Notify
)
-/*++
-
-Routine Description:
-
- Installs a protocol interface into the boot services environment.
-
-Arguments:
-
- UserHandle - The handle to install the protocol handler on,
- or NULL if a new handle is to be allocated
-
- Protocol - The protocol to add to the handle
-
- InterfaceType - Indicates whether Interface is supplied in native form.
-
- Interface - The interface for the protocol being added
-
- Notify - Whether to notify the notification list for this protocol
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_OUT_OF_RESOURCES - No enough buffer to allocate
-
- EFI_SUCCESS - Protocol interface successfully installed
-
---*/
;
+
+/**
+ Installs a list of protocol interface into the boot services environment.
+ This function calls InstallProtocolInterface() in a loop. If any error
+ occures all the protocols added by this function are removed. This is
+ basically a lib function to save space.
+
+ @param Handle The handle to install the protocol handlers on,
+ or NULL if a new handle is to be allocated
+ @param ... EFI_GUID followed by protocol instance. A NULL
+ terminates the list. The pairs are the
+ arguments to InstallProtocolInterface(). All the
+ protocols are added to Handle.
+
+ @retval EFI_INVALID_PARAMETER Handle is NULL.
+ @retval EFI_SUCCESS Protocol interfaces successfully installed.
+
+**/
EFI_STATUS
EFIAPI
CoreInstallMultipleProtocolInterfaces (
IN OUT EFI_HANDLE *Handle,
...
)
-/*++
-
-Routine Description:
-
- Installs a list of protocol interface into the boot services environment.
- This function calls InstallProtocolInterface() in a loop. If any error
- occures all the protocols added by this function are removed. This is
- basically a lib function to save space.
-
-Arguments:
-
- Handle - The handle to install the protocol handlers on,
- or NULL if a new handle is to be allocated
- ... - EFI_GUID followed by protocol instance. A NULL terminates the
- list. The pairs are the arguments to InstallProtocolInterface().
- All the protocols are added to Handle.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Handle is NULL.
-
- EFI_SUCCESS - Protocol interfaces successfully installed.
-
---*/
;
+
+/**
+ Uninstalls a list of protocol interface in the boot services environment.
+ This function calls UnisatllProtocolInterface() in a loop. This is
+ basically a lib function to save space.
+
+ @param Handle The handle to uninstall the protocol
+ @param ... EFI_GUID followed by protocol instance. A NULL
+ terminates the list. The pairs are the
+ arguments to UninstallProtocolInterface(). All
+ the protocols are added to Handle.
+
+ @return Status code
+
+**/
EFI_STATUS
EFIAPI
CoreUninstallMultipleProtocolInterfaces (
IN EFI_HANDLE Handle,
...
)
-/*++
-
-Routine Description:
-
- Uninstalls a list of protocol interface in the boot services environment.
- This function calls UnisatllProtocolInterface() in a loop. This is
- basically a lib function to save space.
-
-Arguments:
-
- Handle - The handle to uninstall the protocol
-
- ... - EFI_GUID followed by protocol instance. A NULL terminates the
- list. The pairs are the arguments to UninstallProtocolInterface().
- All the protocols are added to Handle.
-
-Returns:
-
- Status code
-
---*/
;
+
+/**
+ Reinstall a protocol interface on a device handle. The OldInterface for Protocol is replaced by the NewInterface.
+
+ @param UserHandle Handle on which the interface is to be
+ reinstalled
+ @param Protocol The numeric ID of the interface
+ @param OldInterface A pointer to the old interface
+ @param NewInterface A pointer to the new interface
+
+ @retval EFI_SUCCESS The protocol interface was installed
+ @retval EFI_NOT_FOUND The OldInterface on the handle was not found
+ @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value
+
+**/
EFI_STATUS
EFIAPI
CoreReinstallProtocolInterface (
@@ -943,32 +768,23 @@ CoreReinstallProtocolInterface (
IN VOID *OldInterface,
IN VOID *NewInterface
)
-/*++
-
-Routine Description:
-
- Reinstall a protocol interface on a device handle. The OldInterface for Protocol is replaced by the NewInterface.
-
-Arguments:
-
- UserHandle - Handle on which the interface is to be reinstalled
- Protocol - The numeric ID of the interface
- OldInterface - A pointer to the old interface
- NewInterface - A pointer to the new interface
-
-
-Returns:
-
- Status code.
-
- On EFI_SUCCESS The protocol interface was installed
- On EFI_NOT_FOUND The OldInterface on the handle was not found
- On EFI_INVALID_PARAMETER One of the parameters has an invalid value
-
---*/
;
+
+/**
+ Uninstalls all instances of a protocol:interfacer from a handle.
+ If the last protocol interface is remove from the handle, the
+ handle is freed.
+
+ @param UserHandle The handle to remove the protocol handler from
+ @param Protocol The protocol, of protocol:interface, to remove
+ @param Interface The interface, of protocol:interface, to remove
+
+ @retval EFI_INVALID_PARAMETER Protocol is NULL.
+ @retval EFI_SUCCESS Protocol interface successfully uninstalled.
+
+**/
EFI_STATUS
EFIAPI
CoreUninstallProtocolInterface (
@@ -976,32 +792,21 @@ CoreUninstallProtocolInterface (
IN EFI_GUID *Protocol,
IN VOID *Interface
)
-/*++
-
-Routine Description:
-
- Uninstalls all instances of a protocol:interfacer from a handle.
- If the last protocol interface is remove from the handle, the
- handle is freed.
-
-Arguments:
-
- UserHandle - The handle to remove the protocol handler from
-
- Protocol - The protocol, of protocol:interface, to remove
-
- Interface - The interface, of protocol:interface, to remove
-
-Returns:
-
- EFI_INVALID_PARAMETER - Protocol is NULL.
-
- EFI_SUCCESS - Protocol interface successfully uninstalled.
-
---*/
;
+
+/**
+ Queries a handle to determine if it supports a specified protocol.
+
+ @param UserHandle The handle being queried.
+ @param Protocol The published unique identifier of the protocol.
+ @param Interface Supplies the address where a pointer to the
+ corresponding Protocol Interface is returned.
+
+ @return The requested protocol interface for the handle
+
+**/
EFI_STATUS
EFIAPI
CoreHandleProtocol (
@@ -1009,29 +814,30 @@ CoreHandleProtocol (
IN EFI_GUID *Protocol,
OUT VOID **Interface
)
-/*++
-
-Routine Description:
-
- Queries a handle to determine if it supports a specified protocol.
-
-Arguments:
-
- UserHandle - The handle being queried.
-
- Protocol - The published unique identifier of the protocol.
-
- Interface - Supplies the address where a pointer to the corresponding Protocol
- Interface is returned.
-
-Returns:
-
- The requested protocol interface for the handle
-
---*/
;
+
+/**
+ Locates the installed protocol handler for the handle, and
+ invokes it to obtain the protocol interface. Usage information
+ is registered in the protocol data base.
+
+ @param UserHandle The handle to obtain the protocol interface on
+ @param Protocol The ID of the protocol
+ @param Interface The location to return the protocol interface
+ @param ImageHandle The handle of the Image that is opening the
+ protocol interface specified by Protocol and
+ Interface.
+ @param ControllerHandle The controller handle that is requiring this
+ interface.
+ @param Attributes The open mode of the protocol interface
+ specified by Handle and Protocol.
+
+ @retval EFI_INVALID_PARAMETER Protocol is NULL.
+ @retval EFI_SUCCESS Get the protocol interface.
+
+**/
EFI_STATUS
EFIAPI
CoreOpenProtocol (
@@ -1042,40 +848,21 @@ CoreOpenProtocol (
IN EFI_HANDLE ControllerHandle,
IN UINT32 Attributes
)
-/*++
-
-Routine Description:
-
- Locates the installed protocol handler for the handle, and
- invokes it to obtain the protocol interface. Usage information
- is registered in the protocol data base.
-
-Arguments:
-
- UserHandle - The handle to obtain the protocol interface on
-
- Protocol - The ID of the protocol
-
- Interface - The location to return the protocol interface
-
- ImageHandle - The handle of the Image that is opening the protocol interface
- specified by Protocol and Interface.
-
- ControllerHandle - The controller handle that is requiring this interface.
-
- Attributes - The open mode of the protocol interface specified by Handle
- and Protocol.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Protocol is NULL.
-
- EFI_SUCCESS - Get the protocol interface.
-
---*/
;
+
+/**
+ Return information about Opened protocols in the system
+
+ @param UserHandle The handle to close the protocol interface on
+ @param Protocol The ID of the protocol
+ @param EntryBuffer A pointer to a buffer of open protocol
+ information in the form of
+ EFI_OPEN_PROTOCOL_INFORMATION_ENTRY structures.
+ @param EntryCount Number of EntryBuffer entries
+
+**/
EFI_STATUS
EFIAPI
CoreOpenProtocolInformation (
@@ -1084,62 +871,70 @@ CoreOpenProtocolInformation (
OUT EFI_OPEN_PROTOCOL_INFORMATION_ENTRY **EntryBuffer,
OUT UINTN *EntryCount
)
-/*++
-
-Routine Description:
-
- Return information about Opened protocols in the system
-
-Arguments:
-
- UserHandle - The handle to close the protocol interface on
-
- Protocol - The ID of the protocol
-
- EntryBuffer - A pointer to a buffer of open protocol information in the form of
- EFI_OPEN_PROTOCOL_INFORMATION_ENTRY structures.
-
- EntryCount - Number of EntryBuffer entries
-
-Returns:
-
-
---*/
;
+
+/**
+ Closes a protocol on a handle that was opened using OpenProtocol().
+
+ @param UserHandle The handle for the protocol interface that was
+ previously opened with OpenProtocol(), and is
+ now being closed.
+ @param Protocol The published unique identifier of the protocol.
+ It is the caller's responsibility to pass in a
+ valid GUID.
+ @param AgentHandle The handle of the agent that is closing the
+ protocol interface.
+ @param ControllerHandle If the agent that opened a protocol is a driver
+ that follows the EFI Driver Model, then this
+ parameter is the controller handle that required
+ the protocol interface. If the agent does not
+ follow the EFI Driver Model, then this parameter
+ is optional and may be NULL.
+
+ @retval EFI_SUCCESS The protocol instance was closed.
+ @retval EFI_INVALID_PARAMETER Handle, AgentHandle or ControllerHandle is not a
+ valid EFI_HANDLE.
+ @retval EFI_NOT_FOUND Can not find the specified protocol or
+ AgentHandle.
+
+**/
EFI_STATUS
EFIAPI
CoreCloseProtocol (
IN EFI_HANDLE UserHandle,
IN EFI_GUID *Protocol,
- IN EFI_HANDLE ImageHandle,
+ IN EFI_HANDLE AgentHandle,
IN EFI_HANDLE ControllerHandle
)
-/*++
-
-Routine Description:
-
- Close Protocol
-
-Arguments:
-
- UserHandle - The handle to close the protocol interface on
-
- Protocol - The ID of the protocol
-
- ImageHandle - The user of the protocol to close
-
- ControllerHandle - The user of the protocol to close
-
-Returns:
-
- EFI_INVALID_PARAMETER - Protocol is NULL.
-
---*/
;
+
+/**
+ Retrieves the list of protocol interface GUIDs that are installed on a handle in a buffer allocated
+ from pool.
+
+ @param UserHandle The handle from which to retrieve the list of
+ protocol interface GUIDs.
+ @param ProtocolBuffer A pointer to the list of protocol interface GUID
+ pointers that are installed on Handle.
+ @param ProtocolBufferCount A pointer to the number of GUID pointers present
+ in ProtocolBuffer.
+
+ @retval EFI_SUCCESS The list of protocol interface GUIDs installed
+ on Handle was returned in ProtocolBuffer. The
+ number of protocol interface GUIDs was returned
+ in ProtocolBufferCount.
+ @retval EFI_INVALID_PARAMETER Handle is NULL.
+ @retval EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE.
+ @retval EFI_INVALID_PARAMETER ProtocolBuffer is NULL.
+ @retval EFI_INVALID_PARAMETER ProtocolBufferCount is NULL.
+ @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
+ results.
+
+**/
EFI_STATUS
EFIAPI
CoreProtocolsPerHandle (
@@ -1147,38 +942,23 @@ CoreProtocolsPerHandle (
OUT EFI_GUID ***ProtocolBuffer,
OUT UINTN *ProtocolBufferCount
)
-/*++
-
-Routine Description:
-
- Retrieves the list of protocol interface GUIDs that are installed on a handle in a buffer allocated
- from pool.
-
-Arguments:
-
- UserHandle - The handle from which to retrieve the list of protocol interface
- GUIDs.
-
- ProtocolBuffer - A pointer to the list of protocol interface GUID pointers that are
- installed on Handle.
-
- ProtocolBufferCount - A pointer to the number of GUID pointers present in
- ProtocolBuffer.
-
-Returns:
- EFI_SUCCESS - The list of protocol interface GUIDs installed on Handle was returned in
- ProtocolBuffer. The number of protocol interface GUIDs was
- returned in ProtocolBufferCount.
- EFI_INVALID_PARAMETER - Handle is NULL.
- EFI_INVALID_PARAMETER - Handle is not a valid EFI_HANDLE.
- EFI_INVALID_PARAMETER - ProtocolBuffer is NULL.
- EFI_INVALID_PARAMETER - ProtocolBufferCount is NULL.
- EFI_OUT_OF_RESOURCES - There is not enough pool memory to store the results.
-
---*/
;
+
+/**
+ Add a new protocol notification record for the request protocol.
+
+ @param Protocol The requested protocol to add the notify
+ registration
+ @param Event The event to signal
+ @param Registration Returns the registration record
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_SUCCESS Successfully returned the registration record
+ that has been added
+
+**/
EFI_STATUS
EFIAPI
CoreRegisterProtocolNotify (
@@ -1186,31 +966,28 @@ CoreRegisterProtocolNotify (
IN EFI_EVENT Event,
OUT VOID **Registration
)
-/*++
-
-Routine Description:
-
- Add a new protocol notification record for the request protocol.
-
-Arguments:
-
- Protocol - The requested protocol to add the notify registration
-
- Event - The event to signal
-
- Registration - Returns the registration record
-
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_SUCCESS - Successfully returned the registration record that has been added
-
---*/
;
+
+/**
+ Locates the requested handle(s) and returns them in Buffer.
+
+ @param SearchType The type of search to perform to locate the
+ handles
+ @param Protocol The protocol to search for
+ @param SearchKey Dependant on SearchType
+ @param BufferSize On input the size of Buffer. On output the
+ size of data returned.
+ @param Buffer The buffer to return the results in
+
+ @retval EFI_BUFFER_TOO_SMALL Buffer too small, required buffer size is
+ returned in BufferSize.
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_SUCCESS Successfully found the requested handle(s) and
+ returns them in Buffer.
+
+**/
EFI_STATUS
EFIAPI
CoreLocateHandle (
@@ -1220,68 +997,58 @@ CoreLocateHandle (
IN OUT UINTN *BufferSize,
OUT EFI_HANDLE *Buffer
)
-/*++
-
-Routine Description:
-
- Locates the requested handle(s) and returns them in Buffer.
-
-Arguments:
-
- SearchType - The type of search to perform to locate the handles
-
- Protocol - The protocol to search for
-
- SearchKey - Dependant on SearchType
-
- BufferSize - On input the size of Buffer. On output the
- size of data returned.
-
- Buffer - The buffer to return the results in
-
-
-Returns:
-
- EFI_BUFFER_TOO_SMALL - Buffer too small, required buffer size is returned in BufferSize.
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_SUCCESS - Successfully found the requested handle(s) and returns them in Buffer.
-
---*/
;
+
+/**
+ Locates the handle to a device on the device path that best matches the specified protocol.
+
+ @param Protocol The protocol to search for.
+ @param DevicePath On input, a pointer to a pointer to the device
+ path. On output, the device path pointer is
+ modified to point to the remaining part of the
+ devicepath.
+ @param Device A pointer to the returned device handle.
+
+ @retval EFI_SUCCESS The resulting handle was returned.
+ @retval EFI_NOT_FOUND No handles matched the search.
+ @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
+
+**/
EFI_STATUS
EFIAPI
CoreLocateDevicePath (
IN EFI_GUID *Protocol,
- IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath,
+ IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath,
OUT EFI_HANDLE *Device
)
-/*++
-
-Routine Description:
-
- Locates the handle to a device on the device path that supports the specified protocol.
-
-Arguments:
-
- Protocol - The protocol to search for.
- FilePath - On input, a pointer to a pointer to the device path. On output, the device
- path pointer is modified to point to the remaining part of the devicepath.
- Device - A pointer to the returned device handle.
-
-Returns:
-
- EFI_SUCCESS - The resulting handle was returned.
- EFI_NOT_FOUND - No handles matched the search.
- EFI_INVALID_PARAMETER - One of the parameters has an invalid value.
-
---*/
;
+
+/**
+ Function returns an array of handles that support the requested protocol
+ in a buffer allocated from pool. This is a version of CoreLocateHandle()
+ that allocates a buffer for the caller.
+
+ @param SearchType Specifies which handle(s) are to be returned.
+ @param Protocol Provides the protocol to search by. This
+ parameter is only valid for SearchType
+ ByProtocol.
+ @param SearchKey Supplies the search key depending on the
+ SearchType.
+ @param NumberHandles The number of handles returned in Buffer.
+ @param Buffer A pointer to the buffer to return the requested
+ array of handles that support Protocol.
+
+ @retval EFI_SUCCESS The result array of handles was returned.
+ @retval EFI_NOT_FOUND No handles match the search.
+ @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
+ matching results.
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+
+**/
EFI_STATUS
EFIAPI
CoreLocateHandleBuffer (
@@ -1291,35 +1058,26 @@ CoreLocateHandleBuffer (
IN OUT UINTN *NumberHandles,
OUT EFI_HANDLE **Buffer
)
-/*++
-
-Routine Description:
-
- Function returns an array of handles that support the requested protocol
- in a buffer allocated from pool. This is a version of CoreLocateHandle()
- that allocates a buffer for the caller.
-
-Arguments:
-
- SearchType - Specifies which handle(s) are to be returned.
- Protocol - Provides the protocol to search by.
- This parameter is only valid for SearchType ByProtocol.
- SearchKey - Supplies the search key depending on the SearchType.
- NumberHandles - The number of handles returned in Buffer.
- Buffer - A pointer to the buffer to return the requested array of
- handles that support Protocol.
-
-Returns:
-
- EFI_SUCCESS - The result array of handles was returned.
- EFI_NOT_FOUND - No handles match the search.
- EFI_OUT_OF_RESOURCES - There is not enough pool memory to store the matching results.
- EFI_INVALID_PARAMETER - Invalid parameter
-
---*/
;
+
+/**
+ Return the first Protocol Interface that matches the Protocol GUID. If
+ Registration is pasased in return a Protocol Instance that was just add
+ to the system. If Retistration is NULL return the first Protocol Interface
+ you find.
+
+ @param Protocol The protocol to search for
+ @param Registration Optional Registration Key returned from
+ RegisterProtocolNotify()
+ @param Interface Return the Protocol interface (instance).
+
+ @retval EFI_SUCCESS If a valid Interface is returned
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_NOT_FOUND Protocol interface not found
+
+**/
EFI_STATUS
EFIAPI
CoreLocateProtocol (
@@ -1327,76 +1085,56 @@ CoreLocateProtocol (
IN VOID *Registration OPTIONAL,
OUT VOID **Interface
)
-/*++
-
-Routine Description:
-
- Return the first Protocol Interface that matches the Protocol GUID. If
- Registration is pasased in return a Protocol Instance that was just add
- to the system. If Retistration is NULL return the first Protocol Interface
- you find.
-
-Arguments:
-
- Protocol - The protocol to search for
-
- Registration - Optional Registration Key returned from RegisterProtocolNotify()
-
- Interface - Return the Protocol interface (instance).
-
-Returns:
-
- EFI_SUCCESS - If a valid Interface is returned
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_NOT_FOUND - Protocol interface not found
-
---*/
;
+
+/**
+ return handle database key.
+
+
+ @return Handle database key.
+
+**/
UINT64
CoreGetHandleDatabaseKey (
VOID
)
-/*++
-
-Routine Description:
-
- return handle database key.
-
-Arguments:
-
- None
-
-Returns:
-
- Handle database key.
-
---*/
;
+
+/**
+ Go connect any handles that were created or modified while a image executed.
+
+ @param Key The Key to show that the handle has been
+ created/modified
+
+**/
VOID
CoreConnectHandlesByKey (
UINT64 Key
)
-/*++
-
-Routine Description:
-
- Go connect any handles that were created or modified while a image executed.
-
-Arguments:
-
- Key - The Key to show that the handle has been created/modified
-
-Returns:
-
- None
---*/
;
+
+/**
+ Connects one or more drivers to a controller.
+
+ @param ControllerHandle Handle of the controller to be
+ connected.
+ @param DriverImageHandle DriverImageHandle A pointer to an
+ ordered list of driver image
+ handles.
+ @param RemainingDevicePath RemainingDevicePath A pointer to
+ the device path that specifies a
+ child of the controller specified
+ by ControllerHandle.
+ @param Recursive Whether the function would be
+ called recursively or not.
+
+ @return Status code.
+
+**/
EFI_STATUS
EFIAPI
CoreConnectController (
@@ -1405,31 +1143,43 @@ CoreConnectController (
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL,
IN BOOLEAN Recursive
)
-/*++
-
-Routine Description:
-
- Connects one or more drivers to a controller.
-
-Arguments:
-
- ControllerHandle - Handle of the controller to be connected.
-
- DriverImageHandle - DriverImageHandle A pointer to an ordered list of driver image handles.
-
- RemainingDevicePath - RemainingDevicePath A pointer to the device path that specifies a child of the
- controller specified by ControllerHandle.
-
- Recursive - - Whether the function would be called recursively or not.
-
-Returns:
-
- Status code.
-
---*/
;
+
+/**
+ Disonnects a controller from a driver
+
+ @param ControllerHandle ControllerHandle The handle of
+ the controller from which
+ driver(s) are to be
+ disconnected.
+ @param DriverImageHandle DriverImageHandle The driver to
+ disconnect from ControllerHandle.
+ @param ChildHandle ChildHandle The handle of the
+ child to destroy.
+
+ @retval EFI_SUCCESS One or more drivers were
+ disconnected from the controller.
+ @retval EFI_SUCCESS On entry, no drivers are managing
+ ControllerHandle.
+ @retval EFI_SUCCESS DriverImageHandle is not NULL,
+ and on entry DriverImageHandle is
+ not managing ControllerHandle.
+ @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid
+ EFI_HANDLE.
+ @retval EFI_INVALID_PARAMETER DriverImageHandle is not NULL,
+ and it is not a valid EFI_HANDLE.
+ @retval EFI_INVALID_PARAMETER ChildHandle is not NULL, and it
+ is not a valid EFI_HANDLE.
+ @retval EFI_OUT_OF_RESOURCES There are not enough resources
+ available to disconnect any
+ drivers from ControllerHandle.
+ @retval EFI_DEVICE_ERROR The controller could not be
+ disconnected because of a device
+ error.
+
+**/
EFI_STATUS
EFIAPI
CoreDisconnectController (
@@ -1437,34 +1187,28 @@ CoreDisconnectController (
IN EFI_HANDLE DriverImageHandle OPTIONAL,
IN EFI_HANDLE ChildHandle OPTIONAL
)
-/*++
-
-Routine Description:
-
- Disonnects a controller from a driver
-
-Arguments:
-
- ControllerHandle - ControllerHandle The handle of the controller from which driver(s)
- are to be disconnected.
- DriverImageHandle - DriverImageHandle The driver to disconnect from ControllerHandle.
- ChildHandle - ChildHandle The handle of the child to destroy.
-
-Returns:
-
- EFI_SUCCESS - One or more drivers were disconnected from the controller.
- EFI_SUCCESS - On entry, no drivers are managing ControllerHandle.
- EFI_SUCCESS - DriverImageHandle is not NULL, and on entry DriverImageHandle is not managing ControllerHandle.
- EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.
- EFI_INVALID_PARAMETER - DriverImageHandle is not NULL, and it is not a valid EFI_HANDLE.
- EFI_INVALID_PARAMETER - ChildHandle is not NULL, and it is not a valid EFI_HANDLE.
- EFI_OUT_OF_RESOURCES - There are not enough resources available to disconnect any drivers from ControllerHandle.
- EFI_DEVICE_ERROR - The controller could not be disconnected because of a device error.
-
---*/
;
+
+/**
+ Allocates pages from the memory map.
+
+ @param Type The type of allocation to perform
+ @param MemoryType The type of memory to turn the allocated pages
+ into
+ @param NumberOfPages The number of pages to allocate
+ @param Memory A pointer to receive the base allocated memory
+ address
+
+ @return Status. On success, Memory is filled in with the base address allocated
+ @retval EFI_INVALID_PARAMETER Parameters violate checking rules defined in
+ spec.
+ @retval EFI_NOT_FOUND Could not allocate pages match the requirement.
+ @retval EFI_OUT_OF_RESOURCES No enough pages to allocate.
+ @retval EFI_SUCCESS Pages successfully allocated.
+
+**/
EFI_STATUS
EFIAPI
CoreAllocatePages (
@@ -1473,108 +1217,87 @@ CoreAllocatePages (
IN UINTN NumberOfPages,
IN OUT EFI_PHYSICAL_ADDRESS *Memory
)
-/*++
-
-Routine Description:
-
- Allocates pages from the memory map.
-
-Arguments:
-
- Type - The type of allocation to perform
-
- MemoryType - The type of memory to turn the allocated pages into
-
- NumberOfPages - The number of pages to allocate
-
- Memory - A pointer to receive the base allocated memory address
-
-Returns:
-
- Status. On success, Memory is filled in with the base address allocated
-
- EFI_INVALID_PARAMETER - Parameters violate checking rules defined in spec.
-
- EFI_NOT_FOUND - Could not allocate pages match the requirement.
-
- EFI_OUT_OF_RESOURCES - No enough pages to allocate.
-
- EFI_SUCCESS - Pages successfully allocated.
-
---*/
;
+
+/**
+ Frees previous allocated pages.
+
+ @param Memory Base address of memory being freed
+ @param NumberOfPages The number of pages to free
+
+ @retval EFI_NOT_FOUND Could not find the entry that covers the range
+ @retval EFI_INVALID_PARAMETER Address not aligned
+ @return EFI_SUCCESS -Pages successfully freed.
+
+**/
EFI_STATUS
EFIAPI
CoreFreePages (
IN EFI_PHYSICAL_ADDRESS Memory,
IN UINTN NumberOfPages
)
-/*++
-
-Routine Description:
-
- Frees previous allocated pages.
-
-Arguments:
-
- Memory - Base address of memory being freed
-
- NumberOfPages - The number of pages to free
-
-Returns:
-
- EFI_NOT_FOUND - Could not find the entry that covers the range
-
- EFI_INVALID_PARAMETER - Address not aligned
-
- EFI_SUCCESS -Pages successfully freed.
-
---*/
;
+
+/**
+ This function returns a copy of the current memory map. The map is an array of
+ memory descriptors, each of which describes a contiguous block of memory.
+
+ @param MemoryMapSize A pointer to the size, in bytes, of the
+ MemoryMap buffer. On input, this is the size of
+ the buffer allocated by the caller. On output,
+ it is the size of the buffer returned by the
+ firmware if the buffer was large enough, or the
+ size of the buffer needed to contain the map if
+ the buffer was too small.
+ @param MemoryMap A pointer to the buffer in which firmware places
+ the current memory map.
+ @param MapKey A pointer to the location in which firmware
+ returns the key for the current memory map.
+ @param DescriptorSize A pointer to the location in which firmware
+ returns the size, in bytes, of an individual
+ EFI_MEMORY_DESCRIPTOR.
+ @param DescriptorVersion A pointer to the location in which firmware
+ returns the version number associated with the
+ EFI_MEMORY_DESCRIPTOR.
+
+ @retval EFI_SUCCESS The memory map was returned in the MemoryMap
+ buffer.
+ @retval EFI_BUFFER_TOO_SMALL The MemoryMap buffer was too small. The current
+ buffer size needed to hold the memory map is
+ returned in MemoryMapSize.
+ @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
+
+**/
EFI_STATUS
EFIAPI
CoreGetMemoryMap (
IN OUT UINTN *MemoryMapSize,
- IN OUT EFI_MEMORY_DESCRIPTOR *Desc,
+ IN OUT EFI_MEMORY_DESCRIPTOR *MemoryMap,
OUT UINTN *MapKey,
OUT UINTN *DescriptorSize,
OUT UINT32 *DescriptorVersion
)
-/*++
-
-Routine Description:
-
- Returns the current memory map.
-
-Arguments:
-
- MemoryMapSize - On input the buffer size of MemoryMap allocated by caller
- On output the required buffer size to contain the memory map
-
- Desc - The buffer to return the current memory map
-
- MapKey - The address to return the current map key
-
- DescriptorSize - The size in bytes for an individual EFI_MEMORY_DESCRIPTOR
-
- DescriptorVersion - The version number associated with the EFI_MEMORY_DESCRIPTOR
-
-Returns:
-
- EFI_SUCCESS The current memory map was returned successfully
-
- EFI_BUFFER_TOO_SMALL The MemoryMap buffer was too small
-
- EFI_INVALID_PARAMETER One of the parameters has an invalid value
-
---*/
;
+
+/**
+ Allocate pool of a particular type.
+
+ @param PoolType Type of pool to allocate
+ @param Size The amount of pool to allocate
+ @param Buffer The address to return a pointer to the allocated
+ pool
+
+ @retval EFI_INVALID_PARAMETER PoolType not valid
+ @retval EFI_OUT_OF_RESOURCES Size exceeds max pool size or allocation failed.
+ @retval EFI_SUCCESS Pool successfully allocated.
+
+**/
EFI_STATUS
EFIAPI
CoreAllocatePool (
@@ -1582,57 +1305,54 @@ CoreAllocatePool (
IN UINTN Size,
OUT VOID **Buffer
)
-/*++
-
-Routine Description:
-
- Allocate pool of a particular type.
-
-Arguments:
-
- PoolType - Type of pool to allocate
-
- Size - The amount of pool to allocate
-
- Buffer - The address to return a pointer to the allocated pool
-
-Returns:
-
- EFI_INVALID_PARAMETER - PoolType not valid
-
- EFI_OUT_OF_RESOURCES - Size exceeds max pool size or allocation failed.
-
- EFI_SUCCESS - Pool successfully allocated.
-
---*/
;
+
+/**
+ Frees pool.
+
+ @param Buffer The allocated pool entry to free
+
+ @retval EFI_INVALID_PARAMETER Buffer is not a valid value.
+ @retval EFI_SUCCESS Pool successfully freed.
+
+**/
EFI_STATUS
EFIAPI
CoreFreePool (
IN VOID *Buffer
)
-/*++
-
-Routine Description:
-
- Frees pool.
-
-Arguments:
-
- Buffer - The allocated pool entry to free
-
-Returns:
-
- EFI_INVALID_PARAMETER - Buffer is not a valid value.
-
- EFI_SUCCESS - Pool successfully freed.
-
---*/
;
+
+/**
+ Loads an EFI image into memory and returns a handle to the image.
+
+ @param BootPolicy If TRUE, indicates that the request originates
+ from the boot manager, and that the boot
+ manager is attempting to load FilePath as a
+ boot selection.
+ @param ParentImageHandle The caller's image handle.
+ @param FilePath The specific file path from which the image is
+ loaded.
+ @param SourceBuffer If not NULL, a pointer to the memory location
+ containing a copy of the image to be loaded.
+ @param SourceSize The size in bytes of SourceBuffer.
+ @param ImageHandle Pointer to the returned image handle that is
+ created when the image is successfully loaded.
+
+ @retval EFI_SUCCESS The image was loaded into memory.
+ @retval EFI_NOT_FOUND The FilePath was not found.
+ @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
+ @retval EFI_UNSUPPORTED The image type is not supported, or the device
+ path cannot be parsed to locate the proper
+ protocol for loading the file.
+ @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
+ resources.
+
+**/
EFI_STATUS
EFIAPI
CoreLoadImage (
@@ -1643,63 +1363,49 @@ CoreLoadImage (
IN UINTN SourceSize,
OUT EFI_HANDLE *ImageHandle
)
-/*++
-
-Routine Description:
-
- Loads an EFI image into memory and returns a handle to the image.
-
-Arguments:
-
- BootPolicy - If TRUE, indicates that the request originates from the boot manager,
- and that the boot manager is attempting to load FilePath as a boot selection.
- ParentImageHandle - The caller's image handle.
- FilePath - The specific file path from which the image is loaded.
- SourceBuffer - If not NULL, a pointer to the memory location containing a copy of
- the image to be loaded.
- SourceSize - The size in bytes of SourceBuffer.
- ImageHandle - Pointer to the returned image handle that is created when the image
- is successfully loaded.
-
-Returns:
-
- EFI_SUCCESS - The image was loaded into memory.
- EFI_NOT_FOUND - The FilePath was not found.
- EFI_INVALID_PARAMETER - One of the parameters has an invalid value.
- EFI_UNSUPPORTED - The image type is not supported, or the device path cannot be
- parsed to locate the proper protocol for loading the file.
- EFI_OUT_OF_RESOURCES - Image was not loaded due to insufficient resources.
---*/
;
+
+/**
+ Unloads an image.
+
+ @param ImageHandle Handle that identifies the image to be
+ unloaded.
+
+ @retval EFI_SUCCESS The image has been unloaded.
+ @retval EFI_UNSUPPORTED The image has been sarted, and does not support
+ unload.
+ @retval EFI_INVALID_PARAMPETER ImageHandle is not a valid image handle.
+
+**/
EFI_STATUS
EFIAPI
CoreUnloadImage (
IN EFI_HANDLE ImageHandle
)
-/*++
-
-Routine Description:
-
- Unload the specified image.
-
-Arguments:
-
- ImageHandle - The specified image handle.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Image handle is NULL.
-
- EFI_UNSUPPORTED - Attempt to unload an unsupported image.
-
- EFI_SUCCESS - Image successfully unloaded.
-
---*/
;
+
+/**
+ Transfer control to a loaded image's entry point.
+
+ @param ImageHandle Handle of image to be started.
+ @param ExitDataSize Pointer of the size to ExitData
+ @param ExitData Pointer to a pointer to a data buffer that
+ includes a Null-terminated Unicode string,
+ optionally followed by additional binary data.
+ The string is a description that the caller may
+ use to further indicate the reason for the
+ image's exit.
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
+ @retval EFI_SUCCESS Successfully transfer control to the image's
+ entry point.
+
+**/
EFI_STATUS
EFIAPI
CoreStartImage (
@@ -1707,35 +1413,33 @@ CoreStartImage (
OUT UINTN *ExitDataSize,
OUT CHAR16 **ExitData OPTIONAL
)
-/*++
-
-Routine Description:
-
- Transfer control to a loaded image's entry point.
-
-Arguments:
-
- ImageHandle - Handle of image to be started.
-
- ExitDataSize - Pointer of the size to ExitData
-
- ExitData - Pointer to a pointer to a data buffer that includes a Null-terminated
- Unicode string, optionally followed by additional binary data. The string
- is a description that the caller may use to further indicate the reason for
- the image's exit.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_OUT_OF_RESOURCES - No enough buffer to allocate
-
- EFI_SUCCESS - Successfully transfer control to the image's entry point.
-
---*/
;
+
+/**
+ Terminates the currently loaded EFI image and returns control to boot services.
+
+ @param ImageHandle Handle that identifies the image. This
+ parameter is passed to the image on entry.
+ @param Status The image's exit code.
+ @param ExitDataSize The size, in bytes, of ExitData. Ignored if
+ ExitStatus is EFI_SUCCESS.
+ @param ExitData Pointer to a data buffer that includes a
+ Null-terminated Unicode string, optionally
+ followed by additional binary data. The string
+ is a description that the caller may use to
+ further indicate the reason for the image's
+ exit.
+
+ @retval EFI_INVALID_PARAMETER Image handle is NULL or it is not current
+ image.
+ @retval EFI_SUCCESS Successfully terminates the currently loaded
+ EFI image.
+ @retval EFI_ACCESS_DENIED Should never reach there.
+ @retval EFI_OUT_OF_RESOURCES Could not allocate pool
+
+**/
EFI_STATUS
EFIAPI
CoreExit (
@@ -1744,36 +1448,28 @@ CoreExit (
IN UINTN ExitDataSize,
IN CHAR16 *ExitData OPTIONAL
)
-/*++
-
-Routine Description:
-
- Terminates the currently loaded EFI image and returns control to boot services.
-
-Arguments:
-
- ImageHandle - Handle that identifies the image. This parameter is passed to the image
- on entry.
- Status - The image's exit code.
- ExitDataSize - The size, in bytes, of ExitData. Ignored if ExitStatus is
- EFI_SUCCESS.
- ExitData - Pointer to a data buffer that includes a Null-terminated Unicode string,
- optionally followed by additional binary data. The string is a
- description that the caller may use to further indicate the reason for
- the image's exit.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Image handle is NULL or it is not current image.
-
- EFI_SUCCESS - Successfully terminates the currently loaded EFI image.
-
- EFI_ACCESS_DENIED - Should never reach there.
-
---*/
;
+
+/**
+ 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 (
@@ -1781,33 +1477,32 @@ CoreCreateEvent (
IN EFI_TPL NotifyTpl,
IN EFI_EVENT_NOTIFY NotifyFunction,
IN VOID *NotifyContext,
- OUT EFI_EVENT *pEvent
+ 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 event's notification function
- NotifyContext - Pointer to the notification function's context; corresponds to
- parameter "Context" in the notification function
- pEvent - 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
-
---*/
;
+
+/**
+ 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 (
@@ -1818,29 +1513,25 @@ 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
- EventGrout - 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
-
---*/
;
+
+/**
+ 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 (
@@ -1848,52 +1539,42 @@ 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
-
---*/
;
+
+/**
+ Signals the event. Queues the event to be notified if needed
+
+ @param UserEvent The event to signal
+
+ @retval EFI_INVALID_PARAMETER Parameters are not valid.
+ @retval EFI_SUCCESS The event was signaled.
+
+**/
EFI_STATUS
EFIAPI
CoreSignalEvent (
IN EFI_EVENT Event
)
-/*++
-
-Routine Description:
-
- Signals the event. Queues the event to be notified if needed
-
-Arguments:
-
- Event - The event to signal
-
-Returns:
-
- EFI_INVALID_PARAMETER - Parameters are not valid.
-
- EFI_SUCCESS - The event was signaled.
-
---*/
;
+
+/**
+ 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 (
@@ -1901,78 +1582,58 @@ 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
-
---*/
;
+
+/**
+ Closes an event and frees the event structure.
+
+ @param UserEvent Event to close
+
+ @retval EFI_INVALID_PARAMETER Parameters are not valid.
+ @retval EFI_SUCCESS The event has been closed
+
+**/
EFI_STATUS
EFIAPI
CoreCloseEvent (
IN EFI_EVENT Event
)
-/*++
-
-Routine Description:
-
- Closes an event and frees the event structure.
-
-Arguments:
-
- UserEvent - Event to close
-
-Returns:
-
- EFI_INVALID_PARAMETER - Parameters are not valid.
-
- EFI_SUCCESS - The event has been closed
-
---*/
;
+
+/**
+ 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 Event
)
-/*++
-
-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
-
---*/
;
+
+/**
+ Adds reserved memory, system memory, or memory-mapped I/O resources to the
+ global coherency domain of the processor.
+
+ @param GcdMemoryType Memory type of the memory space.
+ @param BaseAddress Base address of the memory space.
+ @param Length Length of the memory space.
+ @param Capabilities alterable attributes of the memory space.
+
+ @retval EFI_SUCCESS Merged this memory space into GCD map.
+
+**/
EFI_STATUS
CoreAddMemorySpace (
IN EFI_GCD_MEMORY_TYPE GcdMemoryType,
@@ -1980,30 +1641,26 @@ CoreAddMemorySpace (
IN UINT64 Length,
IN UINT64 Capabilities
)
-/*++
-
-Routine Description:
-
- Add a segment of memory space to GCD map and add all available pages in this segment
- as memory descriptors.
-
-Arguments:
-
- GcdMemoryType - Memory type of the segment.
-
- BaseAddress - Base address of the segment.
-
- Length - Length of the segment.
-
- Capabilities - alterable attributes of the segment.
-
-Returns:
-
- EFI_SUCCESS - Merged this segment into GCD map.
-
---*/
;
+
+/**
+ Allocates nonexistent memory, reserved memory, system memory, or memorymapped
+ I/O resources from the global coherency domain of the processor.
+
+ @param GcdAllocateType The type of allocate operation
+ @param GcdMemoryType The desired memory type
+ @param Alignment Align with 2^Alignment
+ @param Length Length to allocate
+ @param BaseAddress Base address to allocate
+ @param ImageHandle The image handle consume the allocated space.
+ @param DeviceHandle The device handle consume the allocated space.
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_NOT_FOUND No descriptor contains the desired space.
+ @retval EFI_SUCCESS Memory space successfully allocated.
+
+**/
EFI_STATUS
CoreAllocateMemorySpace (
IN EFI_GCD_ALLOCATE_TYPE GcdAllocateType,
@@ -2014,195 +1671,141 @@ CoreAllocateMemorySpace (
IN EFI_HANDLE ImageHandle,
IN EFI_HANDLE DeviceHandle OPTIONAL
)
-/*++
-
-Routine Description:
-
- Allocate memory space on GCD map.
-
-Arguments:
-
- GcdAllocateType - The type of allocate operation
-
- GcdMemoryType - The desired memory type
-
- Alignment - Align with 2^Alignment
-
- Length - Length to allocate
-
- BaseAddress - Base address to allocate
-
- ImageHandle - The image handle consume the allocated space.
-
- DeviceHandle - The device handle consume the allocated space.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter.
-
- EFI_NOT_FOUND - No descriptor contains the desired space.
-
- EFI_SUCCESS - Memory space successfully allocated.
-
---*/
;
+
+/**
+ Frees nonexistent memory, reserved memory, system memory, or memory-mapped
+ I/O resources from the global coherency domain of the processor.
+
+ @param BaseAddress Base address of the memory space.
+ @param Length Length of the memory space.
+
+ @retval EFI_SUCCESS Space successfully freed.
+
+**/
EFI_STATUS
CoreFreeMemorySpace (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
IN UINT64 Length
)
-/*++
-
-Routine Description:Routine Description:
-
- Free a segment of memory space in GCD map.
-
-Arguments:
-
- BaseAddress - Base address of the segment.
-
- Length - Length of the segment.
-
-Returns:
-
- EFI_SUCCESS - Space successfully freed.
-
---*/
;
+
+/**
+ Removes reserved memory, system memory, or memory-mapped I/O resources from
+ the global coherency domain of the processor.
+
+ @param BaseAddress Base address of the memory space.
+ @param Length Length of the memory space.
+
+ @retval EFI_SUCCESS Successfully remove a segment of memory space.
+
+**/
EFI_STATUS
CoreRemoveMemorySpace (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
IN UINT64 Length
)
-/*++
-
-Routine Description:Routine Description:
-
- Remove a segment of memory space in GCD map.
-
-Arguments:
-
- BaseAddress - Base address of the segment.
-
- Length - Length of the segment.
-
-Returns:
-
- EFI_SUCCESS - Successfully a segment of memory space.
-
---*/
;
+
+/**
+ Retrieves the descriptor for a memory region containing a specified address.
+
+ @param BaseAddress Specified start address
+ @param Descriptor Specified length
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_SUCCESS Successfully get memory space descriptor.
+
+**/
EFI_STATUS
CoreGetMemorySpaceDescriptor (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
OUT EFI_GCD_MEMORY_SPACE_DESCRIPTOR *Descriptor
)
-/*++
-
-Routine Description:
-
- Search all entries in GCD map which contains specified segment and build it to a descriptor.
-
-Arguments:
-
- BaseAddress - Specified start address
-
- Descriptor - Specified length
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_SUCCESS - Successfully get memory space descriptor.
-
---*/
;
+
+/**
+ Modifies the attributes for a memory region in the global coherency domain of the
+ processor.
+
+ @param BaseAddress Specified start address
+ @param Length Specified length
+ @param Attributes Specified attributes
+
+ @retval EFI_SUCCESS Successfully set attribute of a segment of
+ memory space.
+
+**/
EFI_STATUS
CoreSetMemorySpaceAttributes (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
IN UINT64 Length,
IN UINT64 Attributes
)
-/*++
-
-Routine Description:
-
- Set memory space with specified attributes.
-
-Arguments:
-
- BaseAddress - Specified start address
-
- Length - Specified length
-
- Attributes - Specified attributes
-
-Returns:
-
- EFI_SUCCESS - Successfully set attribute of a segment of memory space.
-
---*/
;
+
+/**
+ Returns a map of the memory resources in the global coherency domain of the
+ processor.
+
+ @param NumberOfDescriptors Number of descriptors.
+ @param MemorySpaceMap Descriptor array
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
+ @retval EFI_SUCCESS Successfully get memory space map.
+
+**/
EFI_STATUS
CoreGetMemorySpaceMap (
OUT UINTN *NumberOfDescriptors,
OUT EFI_GCD_MEMORY_SPACE_DESCRIPTOR **MemorySpaceMap
)
-/*++
-
-Routine Description:
-
- Transer all entries of GCD memory map into memory descriptors and pass to caller.
-
-Arguments:
-
- NumberOfDescriptors - Number of descriptors.
-
- MemorySpaceMap - Descriptor array
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_OUT_OF_RESOURCES - No enough buffer to allocate
-
- EFI_SUCCESS - Successfully get memory space map.
-
---*/
;
+
+/**
+ Adds reserved I/O or I/O resources to the global coherency domain of the processor.
+
+ @param GcdIoType IO type of the segment.
+ @param BaseAddress Base address of the segment.
+ @param Length Length of the segment.
+
+ @retval EFI_SUCCESS Merged this segment into GCD map.
+ @retval EFI_INVALID_PARAMETER Parameter not valid
+
+**/
EFI_STATUS
CoreAddIoSpace (
IN EFI_GCD_IO_TYPE GcdIoType,
IN EFI_PHYSICAL_ADDRESS BaseAddress,
IN UINT64 Length
)
-/*++
-
-Routine Description:
-
- Add a segment of IO space to GCD map.
-
-Arguments:
-
- GcdIoType - IO type of the segment.
-
- BaseAddress - Base address of the segment.
-
- Length - Length of the segment.
-
-Returns:
-
- EFI_SUCCESS - Merged this segment into GCD map.
-
---*/
;
+
+/**
+ Allocates nonexistent I/O, reserved I/O, or I/O resources from the global coherency
+ domain of the processor.
+
+ @param GcdAllocateType The type of allocate operation
+ @param GcdIoType The desired IO type
+ @param Alignment Align with 2^Alignment
+ @param Length Length to allocate
+ @param BaseAddress Base address to allocate
+ @param ImageHandle The image handle consume the allocated space.
+ @param DeviceHandle The device handle consume the allocated space.
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_NOT_FOUND No descriptor contains the desired space.
+ @retval EFI_SUCCESS IO space successfully allocated.
+
+**/
EFI_STATUS
CoreAllocateIoSpace (
IN EFI_GCD_ALLOCATE_TYPE GcdAllocateType,
@@ -2213,173 +1816,120 @@ CoreAllocateIoSpace (
IN EFI_HANDLE ImageHandle,
IN EFI_HANDLE DeviceHandle OPTIONAL
)
-/*++
-
-Routine Description:
-
- Allocate IO space on GCD map.
-
-Arguments:
-
- GcdAllocateType - The type of allocate operation
-
- GcdIoType - The desired IO type
-
- Alignment - Align with 2^Alignment
-
- Length - Length to allocate
-
- BaseAddress - Base address to allocate
-
- ImageHandle - The image handle consume the allocated space.
-
- DeviceHandle - The device handle consume the allocated space.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter.
-
- EFI_NOT_FOUND - No descriptor contains the desired space.
-
- EFI_SUCCESS - IO space successfully allocated.
-
---*/
;
+
+/**
+ Frees nonexistent I/O, reserved I/O, or I/O resources from the global coherency
+ domain of the processor.
+
+ @param BaseAddress Base address of the segment.
+ @param Length Length of the segment.
+
+ @retval EFI_SUCCESS Space successfully freed.
+
+**/
EFI_STATUS
CoreFreeIoSpace (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
IN UINT64 Length
)
-/*++
-
-Routine Description:Routine Description:
-
- Free a segment of IO space in GCD map.
-
-Arguments:
-
- BaseAddress - Base address of the segment.
-
- Length - Length of the segment.
-
-Returns:
-
- EFI_SUCCESS - Space successfully freed.
-
---*/
;
+
+/**
+ Removes reserved I/O or I/O resources from the global coherency domain of the
+ processor.
+
+ @param BaseAddress Base address of the segment.
+ @param Length Length of the segment.
+
+ @retval EFI_SUCCESS Successfully removed a segment of IO space.
+
+**/
EFI_STATUS
CoreRemoveIoSpace (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
IN UINT64 Length
)
-/*++
-
-Routine Description:Routine Description:
-
- Remove a segment of IO space in GCD map.
-
-Arguments:
-
- BaseAddress - Base address of the segment.
-
- Length - Length of the segment.
-
-Returns:
-
- EFI_SUCCESS - Successfully removed a segment of IO space.
-
---*/
;
+
+/**
+ Retrieves the descriptor for an I/O region containing a specified address.
+
+ @param BaseAddress Specified start address
+ @param Descriptor Specified length
+
+ @retval EFI_INVALID_PARAMETER Descriptor is NULL.
+ @retval EFI_SUCCESS Successfully get the IO space descriptor.
+
+**/
EFI_STATUS
CoreGetIoSpaceDescriptor (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
OUT EFI_GCD_IO_SPACE_DESCRIPTOR *Descriptor
)
-/*++
-
-Routine Description:
-
- Search all entries in GCD map which contains specified segment and build it to a descriptor.
-
-Arguments:
-
- BaseAddress - Specified start address
-
- Descriptor - Specified length
-
-Returns:
-
- EFI_INVALID_PARAMETER - Descriptor is NULL.
-
- EFI_SUCCESS - Successfully get the IO space descriptor.
-
---*/
;
+
+/**
+ Returns a map of the I/O resources in the global coherency domain of the processor.
+
+ @param NumberOfDescriptors Number of descriptors.
+ @param IoSpaceMap Descriptor array
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
+ @retval EFI_SUCCESS Successfully get IO space map.
+
+**/
EFI_STATUS
CoreGetIoSpaceMap (
OUT UINTN *NumberOfDescriptors,
OUT EFI_GCD_IO_SPACE_DESCRIPTOR **IoSpaceMap
)
-/*++
-
-Routine Description:
-
- Transer all entries of GCD IO map into IO descriptors and pass to caller.
-
-Arguments:
-
- NumberOfDescriptors - Number of descriptors.
-
- IoSpaceMap - Descriptor array
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_OUT_OF_RESOURCES - No enough buffer to allocate
-
- EFI_SUCCESS - Successfully get IO space map.
-
---*/
;
+
+/**
+ This is the main Dispatcher for DXE and it exits when there are no more
+ drivers to run. Drain the mScheduledQueue and load and start a PE
+ image for each driver. Search the mDiscoveredList to see if any driver can
+ be placed on the mScheduledQueue. If no drivers are placed on the
+ mScheduledQueue exit the function. On exit it is assumed the Bds()
+ will be called, and when the Bds() exits the Dispatcher will be called
+ again.
+
+ NONE
+
+ @retval EFI_ALREADY_STARTED The DXE Dispatcher is already running
+ @retval EFI_NOT_FOUND No DXE Drivers were dispatched
+ @retval EFI_SUCCESS One or more DXE Drivers were dispatched
+
+**/
EFI_DXESERVICE
EFI_STATUS
EFIAPI
CoreDispatcher (
VOID
)
-/*++
-
-Routine Description:
-
- This is the main Dispatcher for DXE and it exits when there are no more
- drivers to run. Drain the mScheduledQueue and load and start a PE
- image for each driver. Search the mDiscoveredList to see if any driver can
- be placed on the mScheduledQueue. If no drivers are placed on the
- mScheduledQueue exit the function. On exit it is assumed the Bds()
- will be called, and when the Bds() exits the Dispatcher will be called
- again.
-
-Arguments:
-
- NONE
-
-Returns:
-
- EFI_ALREADY_STARTED - The DXE Dispatcher is already running
-
- EFI_NOT_FOUND - No DXE Drivers were dispatched
-
- EFI_SUCCESS - One or more DXE Drivers were dispatched
-
---*/
;
+
+/**
+ Check every driver and locate a matching one. If the driver is found, the Unrequested
+ state flag is cleared.
+
+ @param FirmwareVolumeHandle The handle of the Firmware Volume that contains
+ the firmware file specified by DriverName.
+ @param DriverName The Driver name to put in the Dependent state.
+
+ @retval EFI_SUCCESS The DriverName was found and it's SOR bit was
+ cleared
+ @retval EFI_NOT_FOUND The DriverName does not exist or it's SOR bit
+ was not set.
+
+**/
EFI_DXESERVICE
EFI_STATUS
EFIAPI
@@ -2387,29 +1937,21 @@ CoreSchedule (
IN EFI_HANDLE FirmwareVolumeHandle,
IN EFI_GUID *DriverName
)
-/*++
-
-Routine Description:
-
- Check every driver and locate a matching one. If the driver is found, the Unrequested
- state flag is cleared.
-
-Arguments:
-
- FirmwareVolumeHandle - The handle of the Firmware Volume that contains the firmware
- file specified by DriverName.
-
- DriverName - The Driver name to put in the Dependent state.
-
-Returns:
-
- EFI_SUCCESS - The DriverName was found and it's SOR bit was cleared
-
- EFI_NOT_FOUND - The DriverName does not exist or it's SOR bit was not set.
-
---*/
;
+
+/**
+ Convert a driver from the Untrused back to the Scheduled state
+
+ @param FirmwareVolumeHandle The handle of the Firmware Volume that contains
+ the firmware file specified by DriverName.
+ @param DriverName The Driver name to put in the Scheduled state
+
+ @retval EFI_SUCCESS The file was found in the untrusted state, and
+ it was promoted to the trusted state.
+ @retval EFI_NOT_FOUND The file was not found in the untrusted state.
+
+**/
EFI_DXESERVICE
EFI_STATUS
EFIAPI
@@ -2417,248 +1959,185 @@ CoreTrust (
IN EFI_HANDLE FirmwareVolumeHandle,
IN EFI_GUID *DriverName
)
-/*++
-
-Routine Description:
-
- Convert a driver from the Untrused back to the Scheduled state
-
-Arguments:
-
- FirmwareVolumeHandle - The handle of the Firmware Volume that contains the firmware
- file specified by DriverName.
-
- DriverName - The Driver name to put in the Scheduled state
-
-Returns:
-
- EFI_SUCCESS - The file was found in the untrusted state, and it was promoted
- to the trusted state.
-
- EFI_NOT_FOUND - The file was not found in the untrusted state.
-
---*/
;
+
+/**
+ Helper function called as part of the code needed
+ to allocate the proper sized buffer for various
+ EFI interfaces.
+
+ @param Status Current status
+ @param Buffer Current allocated buffer, or NULL
+ @param BufferSize Current buffer size needed
+
+ @retval TRUE if the buffer was reallocated and the caller
+ should try the API again.
+ @retval FALSE buffer could not be allocated and the caller
+ should not try the API again.
+
+**/
BOOLEAN
CoreGrowBuffer (
IN OUT EFI_STATUS *Status,
IN OUT VOID **Buffer,
IN UINTN BufferSize
)
-/*++
-
-Routine Description:
-
- Helper function called as part of the code needed
- to allocate the proper sized buffer for various
- EFI interfaces.
-
-Arguments:
-
- Status - Current status
-
- Buffer - Current allocated buffer, or NULL
-
- BufferSize - Current buffer size needed
-
-Returns:
-
- TRUE - if the buffer was reallocated and the caller
- should try the API again.
-
- FALSE - buffer could not be allocated and the caller
- should not try the API again.
-
---*/
;
+
+/**
+ This routine is the driver initialization entry point. It initializes the
+ libraries, and registers two notification functions. These notification
+ functions are responsible for building the FV stack dynamically.
+
+ @param ImageHandle The image handle.
+ @param SystemTable The system table.
+
+ @retval EFI_SUCCESS Function successfully returned.
+
+**/
EFI_STATUS
EFIAPI
FwVolDriverInit (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
-/*++
-
-Routine Description:
- This routine is the driver initialization entry point. It initializes the
- libraries, and registers two notification functions. These notification
- functions are responsible for building the FV stack dynamically.
-
-Arguments:
- ImageHandle - The image handle.
- SystemTable - The system table.
-
-Returns:
- EFI_SUCCESS - Function successfully returned.
-
---*/
;
+
+/**
+ Entry point of the section extraction code. Initializes an instance of the
+ section extraction interface and installs it on a new handle.
+
+ @param ImageHandle A handle for the image that is initializing this driver
+ @param SystemTable A pointer to the EFI system table
+
+ @retval EFI_SUCCESS Driver initialized successfully
+ @retval EFI_OUT_OF_RESOURCES Could not allocate needed resources
+
+**/
EFI_STATUS
EFIAPI
InitializeSectionExtraction (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
-/*++
-
-Routine Description:
- Entry point of the section extraction code. Initializes an instance of the
- section extraction interface and installs it on a new handle.
-
-Arguments:
- ImageHandle EFI_HANDLE: A handle for the image that is initializing this driver
- SystemTable EFI_SYSTEM_TABLE: A pointer to the EFI system table
-
-Returns:
- EFI_SUCCESS: Driver initialized successfully
- EFI_OUT_OF_RESOURCES: Could not allocate needed resources
-
---*/
;
+
+/**
+ This DXE service routine is used to process a firmware volume. In
+ particular, it can be called by BDS to process a single firmware
+ volume found in a capsule.
+
+ @param FvHeader pointer to a firmware volume header
+ @param Size the size of the buffer pointed to by FvHeader
+ @param FVProtocolHandle the handle on which a firmware volume protocol
+ was produced for the firmware volume passed in.
+
+ @retval EFI_OUT_OF_RESOURCES if an FVB could not be produced due to lack of
+ system resources
+ @retval EFI_VOLUME_CORRUPTED if the volume was corrupted
+ @retval EFI_SUCCESS a firmware volume protocol was produced for the
+ firmware volume
+
+**/
EFI_STATUS
CoreProcessFirmwareVolume (
IN VOID *FvHeader,
IN UINTN Size,
OUT EFI_HANDLE *FVProtocolHandle
)
-/*++
-
-Routine Description:
- This DXE service routine is used to process a firmware volume. In
- particular, it can be called by BDS to process a single firmware
- volume found in a capsule.
-
-Arguments:
- FvHeader - pointer to a firmware volume header
- Size - the size of the buffer pointed to by FvHeader
- FVProtocolHandle - the handle on which a firmware volume protocol
- was produced for the firmware volume passed in.
-
-Returns:
- EFI_OUT_OF_RESOURCES - if an FVB could not be produced due to lack of
- system resources
- EFI_VOLUME_CORRUPTED - if the volume was corrupted
- EFI_SUCCESS - a firmware volume protocol was produced for the
- firmware volume
-
---*/
;
//
//Functions used during debug buils
//
+
+/**
+ Displays Architectural protocols that were not loaded and are required for DXE
+ core to function Only used in Debug Builds.
+
+**/
VOID
CoreDisplayMissingArchProtocols (
VOID
)
-/*++
-
- Routine Description:
- Displays Architectural protocols that were not loaded and are required for DXE core to function
- Only used in Debug Builds
-
- Arguments:
- NONE
-
- Returns:
- NONE
-
---*/;
+;
+
+/**
+ Traverse the discovered list for any drivers that were discovered but not loaded
+ because the dependency experessions evaluated to false.
+
+**/
VOID
CoreDisplayDiscoveredNotDispatched (
VOID
)
-/*++
+;
- Routine Description:
- Traverse the discovered list for any drivers that were discovered but not loaded
- because the dependency experessions evaluated to false
+/**
+ Place holder function until all the Boot Services and Runtime Services are available.
- Arguments:
- NONE
-
- Returns:
-
- NONE
-
---*/;
+ @return EFI_NOT_AVAILABLE_YET
+**/
EFI_STATUS
EFIAPI
CoreEfiNotAvailableYetArg0 (
VOID
)
-/*++
-
-Routine Description:
-
- Place holder function until all the Boot Services and Runtime Services are available
-
-Arguments:
-
- None
-
-Returns:
-
- EFI_NOT_AVAILABLE_YET
-
---*/
;
+
+/**
+ Place holder function until all the Boot Services and Runtime Services are available.
+
+ @param Arg1 Undefined
+
+ @return EFI_NOT_AVAILABLE_YET
+
+**/
EFI_STATUS
EFIAPI
CoreEfiNotAvailableYetArg1 (
UINTN Arg1
)
-/*++
-
-Routine Description:
-
- Place holder function until all the Boot Services and Runtime Services are available
-
-Arguments:
-
- Arg1 - Undefined
-
-Returns:
-
- EFI_NOT_AVAILABLE_YET
-
---*/
;
+
+/**
+ Place holder function until all the Boot Services and Runtime Services are available.
+
+ @param Arg1 Undefined
+ @param Arg2 Undefined
+
+ @return EFI_NOT_AVAILABLE_YET
+
+**/
EFI_STATUS
EFIAPI
CoreEfiNotAvailableYetArg2 (
UINTN Arg1,
UINTN Arg2
)
-/*++
-
-Routine Description:
-
- Place holder function until all the Boot Services and Runtime Services are available
-
-Arguments:
-
- Arg1 - Undefined
-
- Arg2 - Undefined
-
-Returns:
-
- EFI_NOT_AVAILABLE_YET
-
---*/
;
+
+/**
+ Place holder function until all the Boot Services and Runtime Services are available.
+
+ @param Arg1 Undefined
+ @param Arg2 Undefined
+ @param Arg3 Undefined
+
+ @return EFI_NOT_AVAILABLE_YET
+
+**/
EFI_STATUS
EFIAPI
CoreEfiNotAvailableYetArg3 (
@@ -2666,27 +2145,20 @@ CoreEfiNotAvailableYetArg3 (
UINTN Arg2,
UINTN Arg3
)
-/*++
-
-Routine Description:
-
- Place holder function until all the Boot Services and Runtime Services are available
-
-Arguments:
-
- Arg1 - Undefined
-
- Arg2 - Undefined
-
- Arg3 - Undefined
-
-Returns:
-
- EFI_NOT_AVAILABLE_YET
-
---*/
;
+
+/**
+ Place holder function until all the Boot Services and Runtime Services are available.
+
+ @param Arg1 Undefined
+ @param Arg2 Undefined
+ @param Arg3 Undefined
+ @param Arg4 Undefined
+
+ @return EFI_NOT_AVAILABLE_YET
+
+**/
EFI_STATUS
EFIAPI
CoreEfiNotAvailableYetArg4 (
@@ -2695,29 +2167,21 @@ CoreEfiNotAvailableYetArg4 (
UINTN Arg3,
UINTN Arg4
)
-/*++
-
-Routine Description:
-
- Place holder function until all the Boot Services and Runtime Services are available
-
-Arguments:
-
- Arg1 - Undefined
-
- Arg2 - Undefined
-
- Arg3 - Undefined
-
- Arg4 - Undefined
-
-Returns:
-
- EFI_NOT_AVAILABLE_YET
-
---*/
;
+
+/**
+ Place holder function until all the Boot Services and Runtime Services are available.
+
+ @param Arg1 Undefined
+ @param Arg2 Undefined
+ @param Arg3 Undefined
+ @param Arg4 Undefined
+ @param Arg5 Undefined
+
+ @return EFI_NOT_AVAILABLE_YET
+
+**/
EFI_STATUS
EFIAPI
CoreEfiNotAvailableYetArg5 (
@@ -2727,57 +2191,67 @@ CoreEfiNotAvailableYetArg5 (
UINTN Arg4,
UINTN Arg5
)
-/*++
-
-Routine Description:
-
- Place holder function until all the Boot Services and Runtime Services are available
-
-Arguments:
-
- Arg1 - Undefined
-
- Arg2 - Undefined
-
- Arg3 - Undefined
-
- Arg4 - Undefined
-
- Arg5 - Undefined
-
-Returns:
-
- EFI_NOT_AVAILABLE_YET
-
---*/
;
+
+/**
+ Searches for a Protocol Interface passed from PEI through a HOB.
+
+ @param ProtocolGuid The Protocol GUID to search for in the HOB List
+ @param Interface A pointer to the interface for the Protocol GUID
+
+ @retval EFI_SUCCESS The Protocol GUID was found and its interface is
+ returned in Interface
+ @retval EFI_NOT_FOUND The Protocol GUID was not found in the HOB List
+
+**/
EFI_STATUS
CoreGetPeiProtocol (
IN EFI_GUID *ProtocolGuid,
IN VOID **Interface
)
-/*++
-
-Routine Description:
-
- Searches for a Protocol Interface passed from PEI through a HOB
-
-Arguments:
-
- ProtocolGuid - The Protocol GUID to search for in the HOB List
-
- Interface - A pointer to the interface for the Protocol GUID
-
-Returns:
-
- EFI_SUCCESS - The Protocol GUID was found and its interface is returned in Interface
-
- EFI_NOT_FOUND - The Protocol GUID was not found in the HOB List
-
---*/
;
-
+
+
+/**
+ Given a compressed source buffer, this function retrieves the size of the
+ uncompressed buffer and the size of the scratch buffer required to decompress
+ the compressed source buffer.
+
+ The GetInfo() function retrieves the size of the uncompressed buffer and the
+ temporary scratch buffer required to decompress the buffer specified by Source
+ and SourceSize. If the size of the uncompressed buffer or the size of the
+ scratch buffer cannot be determined from the compressed data specified by
+ Source and SourceData, then EFI_INVALID_PARAMETER is returned. Otherwise, the
+ size of the uncompressed buffer is returned in DestinationSize, the size of
+ the scratch buffer is returned in ScratchSize, and EFI_SUCCESS is returned.
+ The GetInfo() function does not have scratch buffer available to perform a
+ thorough checking of the validity of the source data. It just retrieves the
+ "Original Size" field from the beginning bytes of the source data and output
+ it as DestinationSize. And ScratchSize is specific to the decompression
+ implementation.
+
+ @param This A pointer to the EFI_DECOMPRESS_PROTOCOL instance.
+ @param Source The source buffer containing the compressed data.
+ @param SourceSize The size, in bytes, of the source buffer.
+ @param DestinationSize A pointer to the size, in bytes, of the
+ uncompressed buffer that will be generated when the
+ compressed buffer specified by Source and
+ SourceSize is decompressed.
+ @param ScratchSize A pointer to the size, in bytes, of the scratch
+ buffer that is required to decompress the
+ compressed buffer specified by Source and
+ SourceSize.
+
+ @retval EFI_SUCCESS The size of the uncompressed data was returned in
+ DestinationSize and the size of the scratch buffer
+ was returned in ScratchSize.
+ @retval EFI_INVALID_PARAMETER The size of the uncompressed data or the size of
+ the scratch buffer cannot be determined from the
+ compressed data specified by Source and
+ SourceSize.
+
+**/
EFI_STATUS
DxeMainUefiDecompressGetInfo (
IN EFI_DECOMPRESS_PROTOCOL *This,
@@ -2787,6 +2261,41 @@ DxeMainUefiDecompressGetInfo (
OUT UINT32 *ScratchSize
);
+
+/**
+ Decompresses a compressed source buffer.
+
+ The Decompress() function extracts decompressed data to its original form.
+ This protocol is designed so that the decompression algorithm can be
+ implemented without using any memory services. As a result, the Decompress()
+ Function is not allowed to call AllocatePool() or AllocatePages() in its
+ implementation. It is the caller��s responsibility to allocate and free the
+ Destination and Scratch buffers.
+ If the compressed source data specified by Source and SourceSize is
+ sucessfully decompressed into Destination, then EFI_SUCCESS is returned. If
+ the compressed source data specified by Source and SourceSize is not in a
+ valid compressed data format, then EFI_INVALID_PARAMETER is returned.
+
+ @param This A pointer to the EFI_DECOMPRESS_PROTOCOL instance.
+ @param Source The source buffer containing the compressed data.
+ @param SourceSize SourceSizeThe size of source data.
+ @param Destination On output, the destination buffer that contains
+ the uncompressed data.
+ @param DestinationSize The size of the destination buffer. The size of
+ the destination buffer needed is obtained from
+ EFI_DECOMPRESS_PROTOCOL.GetInfo().
+ @param Scratch A temporary scratch buffer that is used to perform
+ the decompression.
+ @param ScratchSize The size of scratch buffer. The size of the
+ scratch buffer needed is obtained from GetInfo().
+
+ @retval EFI_SUCCESS Decompression completed successfully, and the
+ uncompressed buffer is returned in Destination.
+ @retval EFI_INVALID_PARAMETER The source buffer specified by Source and
+ SourceSize is corrupted (not in a valid
+ compressed format).
+
+**/
EFI_STATUS
EFIAPI
DxeMainUefiDecompress (
@@ -2799,48 +2308,21 @@ DxeMainUefiDecompress (
IN UINT32 ScratchSize
);
-EFI_STATUS
-DxeMainTianoDecompressGetInfo (
- IN EFI_TIANO_DECOMPRESS_PROTOCOL *This,
- IN VOID *Source,
- IN UINT32 SourceSize,
- OUT UINT32 *DestinationSize,
- OUT UINT32 *ScratchSize
- );
+/**
+ SEP member function. This function creates and returns a new section stream
+ handle to represent the new section stream.
-EFI_STATUS
-EFIAPI
-DxeMainTianoDecompress (
- IN EFI_TIANO_DECOMPRESS_PROTOCOL *This,
- IN VOID *Source,
- IN UINT32 SourceSize,
- IN OUT VOID *Destination,
- IN UINT32 DestinationSize,
- IN OUT VOID *Scratch,
- IN UINT32 ScratchSize
- );
+ @param SectionStreamLength Size in bytes of the section stream.
+ @param SectionStream Buffer containing the new section stream.
+ @param SectionStreamHandle A pointer to a caller allocated UINTN that on
+ output contains the new section stream handle.
-EFI_STATUS
-DxeMainCustomDecompressGetInfo (
- IN EFI_CUSTOMIZED_DECOMPRESS_PROTOCOL *This,
- IN VOID *Source,
- IN UINT32 SourceSize,
- OUT UINT32 *DestinationSize,
- OUT UINT32 *ScratchSize
- );
-
-EFI_STATUS
-EFIAPI
-DxeMainCustomDecompress (
- IN EFI_CUSTOMIZED_DECOMPRESS_PROTOCOL *This,
- IN VOID *Source,
- IN UINT32 SourceSize,
- IN OUT VOID *Destination,
- IN UINT32 DestinationSize,
- IN OUT VOID *Scratch,
- IN UINT32 ScratchSize
- );
+ @retval EFI_SUCCESS The section stream is created successfully.
+ @retval EFI_OUT_OF_RESOURCES memory allocation failed.
+ @retval EFI_INVALID_PARAMETER Section stream does not end concident with end
+ of last section.
+**/
EFI_STATUS
EFIAPI
OpenSectionStream (
@@ -2849,6 +2331,65 @@ OpenSectionStream (
OUT UINTN *SectionStreamHandle
);
+
+
+/**
+ SEP member function. Retrieves requested section from section stream.
+
+ @param SectionStreamHandle The section stream from which to extract the
+ requested section.
+ @param SectionType A pointer to the type of section to search for.
+ @param SectionDefinitionGuid If the section type is EFI_SECTION_GUID_DEFINED,
+ then SectionDefinitionGuid indicates which of
+ these types of sections to search for.
+ @param SectionInstance Indicates which instance of the requested
+ section to return.
+ @param Buffer Double indirection to buffer. If *Buffer is
+ non-null on input, then the buffer is caller
+ allocated. If Buffer is NULL, then the buffer
+ is callee allocated. In either case, the
+ requried buffer size is returned in *BufferSize.
+ @param BufferSize On input, indicates the size of *Buffer if
+ *Buffer is non-null on input. On output,
+ indicates the required size (allocated size if
+ callee allocated) of *Buffer.
+ @param AuthenticationStatus A pointer to a caller-allocated UINT32 that
+ indicates the authentication status of the
+ output buffer. If the input section��s
+ GuidedSectionHeader.Attributes field
+ has the EFI_GUIDED_SECTION_AUTH_STATUS_VALID
+ bit as clear, AuthenticationStatus must return
+ zero. Both local bits (19:16) and aggregate
+ bits (3:0) in AuthenticationStatus are returned
+ by ExtractSection(). These bits reflect the
+ status of the extraction operation. The bit
+ pattern in both regions must be the same, as
+ the local and aggregate authentication statuses
+ have equivalent meaning at this level. If the
+ function returns anything other than
+ EFI_SUCCESS, the value of *AuthenticationStatus
+ is undefined.
+
+ @retval EFI_SUCCESS Section was retrieved successfully
+ @retval EFI_PROTOCOL_ERROR A GUID defined section was encountered in the
+ section stream with its
+ EFI_GUIDED_SECTION_PROCESSING_REQUIRED bit set,
+ but there was no corresponding GUIDed Section
+ Extraction Protocol in the handle database.
+ *Buffer is unmodified.
+ @retval EFI_NOT_FOUND An error was encountered when parsing the
+ SectionStream. This indicates the SectionStream
+ is not correctly formatted.
+ @retval EFI_NOT_FOUND The requested section does not exist.
+ @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to process
+ the request.
+ @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
+ @retval EFI_WARN_TOO_SMALL The size of the caller allocated input buffer is
+ insufficient to contain the requested section.
+ The input buffer is filled and section contents
+ are truncated.
+
+**/
EFI_STATUS
EFIAPI
GetSection (
@@ -2861,6 +2402,18 @@ GetSection (
OUT UINT32 *AuthenticationStatus
);
+
+/**
+ SEP member function. Deletes an existing section stream
+
+ @param StreamHandleToClose Indicates the stream to close
+
+ @retval EFI_SUCCESS The section stream is closed sucessfully.
+ @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
+ @retval EFI_INVALID_PARAMETER Section stream does not end concident with end
+ of last section.
+
+**/
EFI_STATUS
EFIAPI
CloseSectionStream (
diff --git a/MdeModulePkg/Core/Dxe/DxeMain/DxeMain.c b/MdeModulePkg/Core/Dxe/DxeMain/DxeMain.c
index 0f785ddbe0..b0a5c60f28 100644
--- a/MdeModulePkg/Core/Dxe/DxeMain/DxeMain.c
+++ b/MdeModulePkg/Core/Dxe/DxeMain/DxeMain.c
@@ -1,7 +1,7 @@
-/**@file
+/** @file
DXE Core Main Entry Point
-Copyright (c) 2006 - 2007, Intel Corporation
+Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -228,26 +228,21 @@ EFI_DECOMPRESS_PROTOCOL gEfiDecompress = {
//
// Main entry point to the DXE Core
//
+
+/**
+ Main entry point to DXE Core.
+
+ @param HobStart Pointer to the beginning of the HOB List from
+ PEI
+
+ @return This function should never return
+
+**/
VOID
EFIAPI
DxeMain (
IN VOID *HobStart
)
-/*++
-
-Routine Description:
-
- Main entry point to DXE Core.
-
-Arguments:
-
- HobStart - Pointer to the beginning of the HOB List from PEI
-
-Returns:
-
- This function should never return
-
---*/
{
EFI_STATUS Status;
EFI_PHYSICAL_ADDRESS MemoryBaseAddress;
@@ -335,7 +330,7 @@ Returns:
gDxeCoreImageHandle
);
- DEBUG ((EFI_D_INFO | EFI_D_LOAD, "HOBLIST address in DXE = 0x%016lx\n", (UINT64) (UINTN) HobStart));
+ DEBUG ((DEBUG_INFO | DEBUG_LOAD, "HOBLIST address in DXE = 0x%016lx\n", (UINT64) (UINTN) HobStart));
//
// Initialize the Event Services
@@ -438,26 +433,19 @@ Returns:
}
+
+/**
+ Place holder function until all the Boot Services and Runtime Services are
+ available.
+
+ @return EFI_NOT_AVAILABLE_YET
+
+**/
EFI_STATUS
EFIAPI
CoreEfiNotAvailableYetArg0 (
VOID
)
-/*++
-
-Routine Description:
-
- Place holder function until all the Boot Services and Runtime Services are available
-
-Arguments:
-
- None
-
-Returns:
-
- EFI_NOT_AVAILABLE_YET
-
---*/
{
//
// This function should never be executed. If it does, then the architectural protocols
@@ -468,26 +456,21 @@ Returns:
return EFI_NOT_AVAILABLE_YET;
}
+
+/**
+ Place holder function until all the Boot Services and Runtime Services are
+ available.
+
+ @param Arg1 Undefined
+
+ @return EFI_NOT_AVAILABLE_YET
+
+**/
EFI_STATUS
EFIAPI
CoreEfiNotAvailableYetArg1 (
UINTN Arg1
)
-/*++
-
-Routine Description:
-
- Place holder function until all the Boot Services and Runtime Services are available
-
-Arguments:
-
- Arg1 - Undefined
-
-Returns:
-
- EFI_NOT_AVAILABLE_YET
-
---*/
{
//
// This function should never be executed. If it does, then the architectural protocols
@@ -498,29 +481,22 @@ Returns:
return EFI_NOT_AVAILABLE_YET;
}
+
+/**
+ Place holder function until all the Boot Services and Runtime Services are available.
+
+ @param Arg1 Undefined
+ @param Arg2 Undefined
+
+ @return EFI_NOT_AVAILABLE_YET
+
+**/
EFI_STATUS
EFIAPI
CoreEfiNotAvailableYetArg2 (
UINTN Arg1,
UINTN Arg2
)
-/*++
-
-Routine Description:
-
- Place holder function until all the Boot Services and Runtime Services are available
-
-Arguments:
-
- Arg1 - Undefined
-
- Arg2 - Undefined
-
-Returns:
-
- EFI_NOT_AVAILABLE_YET
-
---*/
{
//
// This function should never be executed. If it does, then the architectural protocols
@@ -531,6 +507,17 @@ Returns:
return EFI_NOT_AVAILABLE_YET;
}
+
+/**
+ Place holder function until all the Boot Services and Runtime Services are available.
+
+ @param Arg1 Undefined
+ @param Arg2 Undefined
+ @param Arg3 Undefined
+
+ @return EFI_NOT_AVAILABLE_YET
+
+**/
EFI_STATUS
EFIAPI
CoreEfiNotAvailableYetArg3 (
@@ -538,25 +525,6 @@ CoreEfiNotAvailableYetArg3 (
UINTN Arg2,
UINTN Arg3
)
-/*++
-
-Routine Description:
-
- Place holder function until all the Boot Services and Runtime Services are available
-
-Arguments:
-
- Arg1 - Undefined
-
- Arg2 - Undefined
-
- Arg3 - Undefined
-
-Returns:
-
- EFI_NOT_AVAILABLE_YET
-
---*/
{
//
// This function should never be executed. If it does, then the architectural protocols
@@ -567,6 +535,18 @@ Returns:
return EFI_NOT_AVAILABLE_YET;
}
+
+/**
+ Place holder function until all the Boot Services and Runtime Services are available.
+
+ @param Arg1 Undefined
+ @param Arg2 Undefined
+ @param Arg3 Undefined
+ @param Arg4 Undefined
+
+ @return EFI_NOT_AVAILABLE_YET
+
+**/
EFI_STATUS
EFIAPI
CoreEfiNotAvailableYetArg4 (
@@ -575,27 +555,6 @@ CoreEfiNotAvailableYetArg4 (
UINTN Arg3,
UINTN Arg4
)
-/*++
-
-Routine Description:
-
- Place holder function until all the Boot Services and Runtime Services are available
-
-Arguments:
-
- Arg1 - Undefined
-
- Arg2 - Undefined
-
- Arg3 - Undefined
-
- Arg4 - Undefined
-
-Returns:
-
- EFI_NOT_AVAILABLE_YET
-
---*/
{
//
// This function should never be executed. If it does, then the architectural protocols
@@ -606,6 +565,19 @@ Returns:
return EFI_NOT_AVAILABLE_YET;
}
+
+/**
+ Place holder function until all the Boot Services and Runtime Services are available.
+
+ @param Arg1 Undefined
+ @param Arg2 Undefined
+ @param Arg3 Undefined
+ @param Arg4 Undefined
+ @param Arg5 Undefined
+
+ @return EFI_NOT_AVAILABLE_YET
+
+**/
EFI_STATUS
EFIAPI
CoreEfiNotAvailableYetArg5 (
@@ -615,29 +587,6 @@ CoreEfiNotAvailableYetArg5 (
UINTN Arg4,
UINTN Arg5
)
-/*++
-
-Routine Description:
-
- Place holder function until all the Boot Services and Runtime Services are available
-
-Arguments:
-
- Arg1 - Undefined
-
- Arg2 - Undefined
-
- Arg3 - Undefined
-
- Arg4 - Undefined
-
- Arg5 - Undefined
-
-Returns:
-
- EFI_NOT_AVAILABLE_YET
-
---*/
{
//
// This function should never be executed. If it does, then the architectural protocols
@@ -649,30 +598,23 @@ Returns:
}
+
+/**
+ Searches for a Protocol Interface passed from PEI through a HOB.
+
+ @param ProtocolGuid The Protocol GUID to search for in the HOB List
+ @param Interface A pointer to the interface for the Protocol GUID
+
+ @retval EFI_SUCCESS The Protocol GUID was found and its interface is
+ returned in Interface
+ @retval EFI_NOT_FOUND The Protocol GUID was not found in the HOB List
+
+**/
EFI_STATUS
CoreGetPeiProtocol (
IN EFI_GUID *ProtocolGuid,
IN VOID **Interface
)
-/*++
-
-Routine Description:
-
- Searches for a Protocol Interface passed from PEI through a HOB
-
-Arguments:
-
- ProtocolGuid - The Protocol GUID to search for in the HOB List
-
- Interface - A pointer to the interface for the Protocol GUID
-
-Returns:
-
- EFI_SUCCESS - The Protocol GUID was found and its interface is returned in Interface
-
- EFI_NOT_FOUND - The Protocol GUID was not found in the HOB List
-
---*/
{
EFI_HOB_GUID_TYPE *GuidHob;
VOID *Buffer;
@@ -691,26 +633,18 @@ Returns:
}
+
+/**
+ Calcualte the 32-bit CRC in a EFI table using the service provided by the
+ gRuntime service.
+
+ @param Hdr Pointer to an EFI standard header
+
+**/
VOID
CalculateEfiHdrCrc (
IN OUT EFI_TABLE_HEADER *Hdr
)
-/*++
-
-Routine Description:
-
- Calcualte the 32-bit CRC in a EFI table using the service provided by the
- gRuntime service.
-
-Arguments:
-
- Hdr - Pointer to an EFI standard header
-
-Returns:
-
- None
-
---*/
{
UINT32 Crc;
@@ -727,30 +661,23 @@ Returns:
+
+/**
+ Terminates all boot services.
+
+ @param ImageHandle Handle that identifies the exiting image.
+ @param MapKey Key to the latest memory map.
+
+ @retval EFI_SUCCESS Boot Services terminated
+ @retval EFI_INVALID_PARAMETER MapKey is incorrect.
+
+**/
EFI_STATUS
EFIAPI
CoreExitBootServices (
IN EFI_HANDLE ImageHandle,
IN UINTN MapKey
)
-/*++
-
-Routine Description:
-
- Terminates all boot services.
-
-Arguments:
-
- ImageHandle - Handle that identifies the exiting image.
-
- MapKey -Key to the latest memory map.
-
-Returns:
-
- EFI_SUCCESS - Boot Services terminated
- EFI_INVALID_PARAMETER - MapKey is incorrect.
-
---*/
{
EFI_STATUS Status;
EFI_STATUS StatusTemp;
@@ -847,7 +774,48 @@ Returns:
return Status;
}
+
+/**
+ Given a compressed source buffer, this function retrieves the size of the
+ uncompressed buffer and the size of the scratch buffer required to decompress
+ the compressed source buffer.
+
+ The GetInfo() function retrieves the size of the uncompressed buffer and the
+ temporary scratch buffer required to decompress the buffer specified by Source
+ and SourceSize. If the size of the uncompressed buffer or the size of the
+ scratch buffer cannot be determined from the compressed data specified by
+ Source and SourceData, then EFI_INVALID_PARAMETER is returned. Otherwise, the
+ size of the uncompressed buffer is returned in DestinationSize, the size of
+ the scratch buffer is returned in ScratchSize, and EFI_SUCCESS is returned.
+ The GetInfo() function does not have scratch buffer available to perform a
+ thorough checking of the validity of the source data. It just retrieves the
+ "Original Size" field from the beginning bytes of the source data and output
+ it as DestinationSize. And ScratchSize is specific to the decompression
+ implementation.
+
+ @param This A pointer to the EFI_DECOMPRESS_PROTOCOL instance.
+ @param Source The source buffer containing the compressed data.
+ @param SourceSize The size, in bytes, of the source buffer.
+ @param DestinationSize A pointer to the size, in bytes, of the
+ uncompressed buffer that will be generated when the
+ compressed buffer specified by Source and
+ SourceSize is decompressed.
+ @param ScratchSize A pointer to the size, in bytes, of the scratch
+ buffer that is required to decompress the
+ compressed buffer specified by Source and
+ SourceSize.
+
+ @retval EFI_SUCCESS The size of the uncompressed data was returned in
+ DestinationSize and the size of the scratch buffer
+ was returned in ScratchSize.
+ @retval EFI_INVALID_PARAMETER The size of the uncompressed data or the size of
+ the scratch buffer cannot be determined from the
+ compressed data specified by Source and
+ SourceSize.
+
+**/
EFI_STATUS
+EFIAPI
DxeMainUefiDecompressGetInfo (
IN EFI_DECOMPRESS_PROTOCOL *This,
IN VOID *Source,
@@ -864,6 +832,41 @@ DxeMainUefiDecompressGetInfo (
return UefiDecompressGetInfo (Source, SourceSize, DestinationSize, ScratchSize);
}
+
+/**
+ Decompresses a compressed source buffer.
+
+ The Decompress() function extracts decompressed data to its original form.
+ This protocol is designed so that the decompression algorithm can be
+ implemented without using any memory services. As a result, the Decompress()
+ Function is not allowed to call AllocatePool() or AllocatePages() in its
+ implementation. It is the caller��s responsibility to allocate and free the
+ Destination and Scratch buffers.
+ If the compressed source data specified by Source and SourceSize is
+ sucessfully decompressed into Destination, then EFI_SUCCESS is returned. If
+ the compressed source data specified by Source and SourceSize is not in a
+ valid compressed data format, then EFI_INVALID_PARAMETER is returned.
+
+ @param This A pointer to the EFI_DECOMPRESS_PROTOCOL instance.
+ @param Source The source buffer containing the compressed data.
+ @param SourceSize SourceSizeThe size of source data.
+ @param Destination On output, the destination buffer that contains
+ the uncompressed data.
+ @param DestinationSize The size of the destination buffer. The size of
+ the destination buffer needed is obtained from
+ EFI_DECOMPRESS_PROTOCOL.GetInfo().
+ @param Scratch A temporary scratch buffer that is used to perform
+ the decompression.
+ @param ScratchSize The size of scratch buffer. The size of the
+ scratch buffer needed is obtained from GetInfo().
+
+ @retval EFI_SUCCESS Decompression completed successfully, and the
+ uncompressed buffer is returned in Destination.
+ @retval EFI_INVALID_PARAMETER The source buffer specified by Source and
+ SourceSize is corrupted (not in a valid
+ compressed format).
+
+**/
EFI_STATUS
EFIAPI
DxeMainUefiDecompress (
diff --git a/MdeModulePkg/Core/Dxe/DxeMain/DxeProtocolNotify.c b/MdeModulePkg/Core/Dxe/DxeMain/DxeProtocolNotify.c
index a3d4bbaaac..42a7a054e6 100644
--- a/MdeModulePkg/Core/Dxe/DxeMain/DxeProtocolNotify.c
+++ b/MdeModulePkg/Core/Dxe/DxeMain/DxeProtocolNotify.c
@@ -45,23 +45,19 @@ ARCHITECTURAL_PROTOCOL_ENTRY mArchProtocols[] = {
};
+
+/**
+ Return TRUE if all AP services are availible.
+
+
+ @retval EFI_SUCCESS All AP services are available
+ @retval EFI_NOT_FOUND At least one AP service is not available
+
+**/
EFI_STATUS
CoreAllEfiServicesAvailable (
VOID
)
-/*++
-
-Routine Description:
- Return TRUE if all AP services are availible.
-
-Arguments:
- NONE
-
-Returns:
- EFI_SUCCESS - All AP services are available
- EFI_NOT_FOUND - At least one AP service is not available
-
---*/
{
ARCHITECTURAL_PROTOCOL_ENTRY *Entry;
@@ -74,33 +70,25 @@ Returns:
return EFI_SUCCESS;
}
-STATIC
-VOID
-EFIAPI
-GenericArchProtocolNotify (
- IN EFI_EVENT Event,
- IN VOID *Context
- )
-/*++
-Routine Description:
+/**
Notification event handler registered by CoreNotifyOnArchProtocolInstallation ().
This notify function is registered for every architectural protocol. This handler
updates mArchProtocol[] array entry with protocol instance data and sets it's
present flag to TRUE. If any constructor is required it is executed. The EFI
System Table headers are updated.
-Arguments:
+ @param Event The Event that is being processed, not used.
+ @param Context Event Context, not used.
- Event - The Event that is being processed, not used.
-
- Context - Event Context, not used.
-
-Returns:
-
- None
-
---*/
+**/
+STATIC
+VOID
+EFIAPI
+GenericArchProtocolNotify (
+ IN EFI_EVENT Event,
+ IN VOID *Context
+ )
{
EFI_STATUS Status;
ARCHITECTURAL_PROTOCOL_ENTRY *Entry;
@@ -184,22 +172,15 @@ Returns:
+
+/**
+ Creates an event that is fired everytime a Protocol of a specific type is installed.
+
+**/
VOID
CoreNotifyOnArchProtocolInstallation (
VOID
)
-/*++
-
-Routine Description:
- Creates an event that is fired everytime a Protocol of a specific type is installed
-
-Arguments:
- NONE
-
-Returns:
- NONE
-
---*/
{
EFI_STATUS Status;
ARCHITECTURAL_PROTOCOL_ENTRY *Entry;
@@ -256,23 +237,16 @@ static const GUID_TO_STRING_PROTOCOL_ENTRY MissingProtocols[] = {
{ &gEfiRealTimeClockArchProtocolGuid, (CHAR16 *)L"Real Time Clock" }
};
+
+/**
+ Displays Architectural protocols that were not loaded and are required for DXE
+ core to function. Only used in Debug Builds.
+
+**/
VOID
CoreDisplayMissingArchProtocols (
VOID
)
-/*++
-
-Routine Description:
- Displays Architectural protocols that were not loaded and are required for DXE core to function
- Only used in Debug Builds
-
-Arguments:
- NONE
-
-Returns:
- NONE
-
---*/
{
const GUID_TO_STRING_PROTOCOL_ENTRY *MissingEntry;
ARCHITECTURAL_PROTOCOL_ENTRY *Entry;
@@ -282,7 +256,7 @@ Returns:
MissingEntry = MissingProtocols;
for (MissingEntry = MissingProtocols; TRUE ; MissingEntry++) {
if (CompareGuid (Entry->ProtocolGuid, MissingEntry->ProtocolGuid)) {
- DEBUG ((EFI_D_ERROR, "\n%s Arch Protocol not present!!\n", MissingEntry->GuidString));
+ DEBUG ((DEBUG_ERROR, "\n%s Arch Protocol not present!!\n", MissingEntry->GuidString));
break;
}
}
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);
}
+
+/**
+ Initializes "event" support and populates parts of the System and Runtime Table.
+
+
+ @retval EFI_SUCCESS Always return success
+
+**/
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
-
---*/
{
UINTN Index;
@@ -143,25 +116,18 @@ Returns:
}
+
+/**
+ Dispatches all pending events.
+
+ @param Priority The task priority level of event notifications
+ to dispatch
+
+**/
VOID
CoreDispatchEventNotifies (
IN EFI_TPL Priority
)
-/*++
-
-Routine Description:
-
- Dispatches all pending events.
-
-Arguments:
-
- Priority - The task priority level of event notifications to dispatch
-
-Returns:
-
- None
-
---*/
{
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:
+
+/**
+ Signals the event. Queues the event to be notified if needed
+
+ @param UserEvent The event to signal
+
+ @retval EFI_INVALID_PARAMETER Parameters are not valid.
+ @retval EFI_SUCCESS The event was signaled.
+
+**/
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:
-
- EFI_INVALID_PARAMETER - Parameters are not valid.
-
- EFI_SUCCESS - The event was signaled.
-
---*/
{
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:
}
+
+/**
+ Closes an event and frees the event structure.
+
+ @param UserEvent Event to close
+
+ @retval EFI_INVALID_PARAMETER Parameters are not valid.
+ @retval EFI_SUCCESS The event has been closed
+
+**/
EFI_STATUS
EFIAPI
CoreCloseEvent (
IN EFI_EVENT UserEvent
)
-/*++
-
-Routine Description:
-
- Closes an event and frees the event structure.
-
-Arguments:
-
- UserEvent - Event to close
-
-Returns:
-
- EFI_INVALID_PARAMETER - Parameters are not valid.
-
- EFI_SUCCESS - The event has been closed
-
---*/
-
{
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:
+
+/**
+ Raise the task priority level to the new level.
+ High level is implemented by disabling processor interrupts.
+
+ @param NewTpl New task priority level
+
+ @return The previous task priority level
+
+**/
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:
-
- The previous task priority level
-
---*/
{
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;
diff --git a/MdeModulePkg/Core/Dxe/Exec.h b/MdeModulePkg/Core/Dxe/Exec.h
index 7ead363a3b..05d22e444d 100644
--- a/MdeModulePkg/Core/Dxe/Exec.h
+++ b/MdeModulePkg/Core/Dxe/Exec.h
@@ -73,120 +73,76 @@ typedef struct {
// Internal prototypes
//
+
+/**
+ Dispatches all pending events.
+
+ @param Priority The task priority level of event notifications
+ to dispatch
+
+**/
VOID
CoreDispatchEventNotifies (
IN EFI_TPL Priority
)
-/*++
-
-Routine Description:
-
- Dispatches all pending events.
-
-Arguments:
-
- Priority - The task priority level of event notifications to dispatch
-
-Returns:
-
- None
-
---*/
;
+
+/**
+ 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
-
---*/
;
+
+/**
+ Disables CPU interrupts.
+
+ @retval EFI_SUCCESS If interrupts were disabled in the CPU.
+ @retval EFI_INVALID_PARAMETER State is NULL.
+
+**/
BOOLEAN
GetInterruptState (
VOID
)
-/*++
-
-Routine Description:
-
- Disables CPU interrupts.
-
-Arguments:
-
- This - Protocol instance structure
-
- State - Pointer to the CPU's current interrupt state
-
-Returns:
-
- EFI_SUCCESS - If interrupts were disabled in the CPU.
-
- EFI_INVALID_PARAMETER - State is NULL.
-
---*/
;
//
// Exported functions
//
+
+/**
+ A function out of date, should be removed.
+
+**/
VOID
CoreEventVirtualAddressFixup (
VOID
)
-/*++
-
-Routine Description:
-
- A function out of date, should be removed.
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
;
+
+/**
+ Initializes timer support.
+
+**/
VOID
CoreInitializeTimer (
VOID
)
-/*++
-
-Routine Description:
-
- Initializes timer support
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
;
//
@@ -197,6 +153,5 @@ extern EFI_LOCK gEventQueueLock;
extern UINTN gEventPending;
extern LIST_ENTRY gEventQueue[];
extern LIST_ENTRY gEventSignalQueue;
-extern UINT8 gHSB[];
#endif
diff --git a/MdeModulePkg/Core/Dxe/FwVol/Ffs.c b/MdeModulePkg/Core/Dxe/FwVol/Ffs.c
index b62fab9cd9..736e840cb7 100644
--- a/MdeModulePkg/Core/Dxe/FwVol/Ffs.c
+++ b/MdeModulePkg/Core/Dxe/FwVol/Ffs.c
@@ -19,24 +19,20 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
#define PHYSICAL_ADDRESS_TO_POINTER(Address) ((VOID *)((UINTN)(Address)))
+/**
+ Get the FFS file state by checking the highest bit set in the header's state field.
+
+ @param ErasePolarity Erase polarity attribute of the firmware volume
+ @param FfsHeader Points to the FFS file header
+
+ @return FFS File state
+
+**/
EFI_FFS_FILE_STATE
GetFileState (
IN UINT8 ErasePolarity,
IN EFI_FFS_FILE_HEADER *FfsHeader
)
-/*++
-
-Routine Description:
- Get the FFS file state by checking the highest bit set in the header's state field
-
-Arguments:
- ErasePolarity - Erase polarity attribute of the firmware volume
- FfsHeader - Points to the FFS file header
-
-Returns:
- FFS File state
-
---*/
{
EFI_FFS_FILE_STATE FileState;
UINT8 HighestBit;
@@ -56,27 +52,24 @@ Returns:
}
+
+/**
+ Check if a block of buffer is erased.
+
+ @param ErasePolarity Erase polarity attribute of the firmware volume
+ @param InBuffer The buffer to be checked
+ @param BufferSize Size of the buffer in bytes
+
+ @retval TRUE The block of buffer is erased
+ @retval FALSE The block of buffer is not erased
+
+**/
BOOLEAN
IsBufferErased (
IN UINT8 ErasePolarity,
IN VOID *InBuffer,
IN UINTN BufferSize
)
-/*++
-
-Routine Description:
- Check if a block of buffer is erased
-
-Arguments:
- ErasePolarity - Erase polarity attribute of the firmware volume
- InBuffer - The buffer to be checked
- BufferSize - Size of the buffer in bytes
-
-Returns:
- TRUE - The block of buffer is erased
- FALSE - The block of buffer is not erased
-
---*/
{
UINTN Count;
UINT8 EraseByte;
@@ -99,35 +92,32 @@ Returns:
}
+
+/**
+ Verify checksum of the firmware volume header.
+
+ @param FvHeader Points to the firmware volume header to be checked
+
+ @retval TRUE Checksum verification passed
+ @retval FALSE Checksum verification failed
+
+**/
BOOLEAN
VerifyFvHeaderChecksum (
IN EFI_FIRMWARE_VOLUME_HEADER *FvHeader
)
-/*++
-
-Routine Description:
- Verify checksum of the firmware volume header
-
-Arguments:
- FvHeader - Points to the firmware volume header to be checked
-
-Returns:
- TRUE - Checksum verification passed
- FALSE - Checksum verification failed
-
---*/
{
UINT32 Index;
UINT32 HeaderLength;
UINT16 Checksum;
- UINT16 *ptr;
+ UINT16 *Ptr;
HeaderLength = FvHeader->HeaderLength;
- ptr = (UINT16 *)FvHeader;
+ Ptr = (UINT16 *)FvHeader;
Checksum = 0;
for (Index = 0; Index < HeaderLength / sizeof (UINT16); Index++) {
- Checksum = (UINT16)(Checksum + ptr[Index]);
+ Checksum = (UINT16)(Checksum + Ptr[Index]);
}
if (Checksum == 0) {
@@ -137,33 +127,30 @@ Returns:
}
}
+
+/**
+ Verify checksum of the FFS file header.
+
+ @param FfsHeader Points to the FFS file header to be checked
+
+ @retval TRUE Checksum verification passed
+ @retval FALSE Checksum verification failed
+
+**/
STATIC
BOOLEAN
VerifyHeaderChecksum (
IN EFI_FFS_FILE_HEADER *FfsHeader
)
-/*++
-
-Routine Description:
- Verify checksum of the FFS file header
-
-Arguments:
- FfsHeader - Points to the FFS file header to be checked
-
-Returns:
- TRUE - Checksum verification passed
- FALSE - Checksum verification failed
-
---*/
{
UINT32 Index;
- UINT8 *ptr;
+ UINT8 *Ptr;
UINT8 HeaderChecksum;
- ptr = (UINT8 *)FfsHeader;
+ Ptr = (UINT8 *)FfsHeader;
HeaderChecksum = 0;
for (Index = 0; Index < sizeof(EFI_FFS_FILE_HEADER); Index++) {
- HeaderChecksum = (UINT8)(HeaderChecksum + ptr[Index]);
+ HeaderChecksum = (UINT8)(HeaderChecksum + Ptr[Index]);
}
HeaderChecksum = (UINT8) (HeaderChecksum - FfsHeader->State - FfsHeader->IntegrityCheck.Checksum.File);
@@ -176,27 +163,24 @@ Returns:
}
+
+/**
+ Check if it's a valid FFS file header.
+
+ @param ErasePolarity Erase polarity attribute of the firmware volume
+ @param FfsHeader Points to the FFS file header to be checked
+ @param FileState FFS file state to be returned
+
+ @retval TRUE Valid FFS file header
+ @retval FALSE Invalid FFS file header
+
+**/
BOOLEAN
IsValidFfsHeader (
IN UINT8 ErasePolarity,
IN EFI_FFS_FILE_HEADER *FfsHeader,
OUT EFI_FFS_FILE_STATE *FileState
)
-/*++
-
-Routine Description:
- Check if it's a valid FFS file header
-
-Arguments:
- ErasePolarity - Erase polarity attribute of the firmware volume
- FfsHeader - Points to the FFS file header to be checked
- FileState - FFS file state to be returned
-
-Returns:
- TRUE - Valid FFS file header
- FALSE - Invalid FFS file header
-
---*/
{
*FileState = GetFileState (ErasePolarity, FfsHeader);
@@ -218,26 +202,23 @@ Returns:
}
+
+/**
+ Check if it's a valid FFS file.
+ Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
+
+ @param ErasePolarity Erase polarity attribute of the firmware volume
+ @param FfsHeader Points to the FFS file to be checked
+
+ @retval TRUE Valid FFS file
+ @retval FALSE Invalid FFS file
+
+**/
BOOLEAN
IsValidFfsFile (
IN UINT8 ErasePolarity,
IN EFI_FFS_FILE_HEADER *FfsHeader
)
-/*++
-
-Routine Description:
- Check if it's a valid FFS file.
- Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
-
-Arguments:
- ErasePolarity - Erase polarity attribute of the firmware volume
- FfsHeader - Points to the FFS file to be checked
-
-Returns:
- TRUE - Valid FFS file
- FALSE - Invalid FFS file
-
---*/
{
EFI_FFS_FILE_STATE FileState;
@@ -258,3 +239,4 @@ Returns:
}
}
+
diff --git a/MdeModulePkg/Core/Dxe/FwVol/FwVol.c b/MdeModulePkg/Core/Dxe/FwVol/FwVol.c
index 60c5fa19a2..bdf87731fb 100644
--- a/MdeModulePkg/Core/Dxe/FwVol/FwVol.c
+++ b/MdeModulePkg/Core/Dxe/FwVol/FwVol.c
@@ -1,9 +1,9 @@
-/**@file
+/** @file
Firmware File System driver that produce Firmware Volume protocol.
Layers on top of Firmware Block protocol to produce a file abstraction
of FV based files.
-Copyright (c) 2006 - 2007 Intel Corporation. <BR>
+Copyright (c) 2006 - 2008 Intel Corporation. <BR>
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -53,29 +53,26 @@ FV_DEVICE mFvDevice = {
// FFS helper functions
//
+
+/**
+ given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and
+ copy the volume header into it.
+
+ @param Fvb The FW_VOL_BLOCK_PROTOCOL instance from which to
+ read the volume header
+ @param FwVolHeader Pointer to pointer to allocated buffer in which
+ the volume header is returned.
+
+ @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.
+ @retval EFI_SUCCESS Successfully read volume header to the allocated
+ buffer.
+
+**/
EFI_STATUS
GetFwVolHeader (
IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb,
OUT EFI_FIRMWARE_VOLUME_HEADER **FwVolHeader
)
-/*++
-
-Routine Description:
- given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and
- copy the volume header into it.
-
-Arguments:
- Fvb - The FW_VOL_BLOCK_PROTOCOL instance from which to read the volume
- header
- FwVolHeader - Pointer to pointer to allocated buffer in which the volume
- header is returned.
-
-Returns:
- EFI_OUT_OF_RESOURCES - No enough buffer could be allocated.
- EFI_SUCCESS - Successfully read volume header to the allocated buffer.
-
---*/
-
{
EFI_STATUS Status;
EFI_FIRMWARE_VOLUME_HEADER TempFvh;
@@ -119,23 +116,20 @@ Returns:
}
+
+/**
+ Free FvDevice resource when error happens
+
+ @param FvDevice pointer to the FvDevice to be freed.
+
+ @return None.
+
+**/
STATIC
VOID
FreeFvDeviceResource (
IN FV_DEVICE *FvDevice
)
-/*++
-
-Routine Description:
- Free FvDevice resource when error happens
-
-Arguments:
- FvDevice - pointer to the FvDevice to be freed.
-
-Returns:
- None.
-
---*/
{
FFS_FILE_LIST_ENTRY *FfsFileEntry;
LIST_ENTRY *NextEntry;
@@ -174,24 +168,21 @@ Returns:
}
+
+/**
+ Check if a FV is consistent and allocate cache
+
+ @param FvDevice pointer to the FvDevice to be checked.
+
+ @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.
+ @retval EFI_SUCCESS FV is consistent and cache is allocated.
+ @retval EFI_VOLUME_CORRUPTED File system is corrupted.
+
+**/
EFI_STATUS
FvCheck (
IN OUT FV_DEVICE *FvDevice
)
-/*++
-
-Routine Description:
- Check if a FV is consistent and allocate cache
-
-Arguments:
- FvDevice - pointer to the FvDevice to be checked.
-
-Returns:
- EFI_OUT_OF_RESOURCES - No enough buffer could be allocated.
- EFI_SUCCESS - FV is consistent and cache is allocated.
- EFI_VOLUME_CORRUPTED - File system is corrupted.
-
---*/
{
EFI_STATUS Status;
EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb;
@@ -380,6 +371,17 @@ Done:
}
+
+/**
+ This notification function is invoked when an instance of the
+ EFI_FW_VOLUME_BLOCK_PROTOCOL is produced. It layers an instance of the
+ EFI_FIRMWARE_VOLUME2_PROTOCOL on the same handle. This is the function where
+ the actual initialization of the EFI_FIRMWARE_VOLUME2_PROTOCOL is done.
+
+ @param Event The event that occured
+ @param Context For EFI compatiblity. Not used.
+
+**/
STATIC
VOID
EFIAPI
@@ -387,23 +389,6 @@ NotifyFwVolBlock (
IN EFI_EVENT Event,
IN VOID *Context
)
-/*++
-
-Routine Description:
- This notification function is invoked when an instance of the
- EFI_FW_VOLUME_BLOCK_PROTOCOL is produced. It layers an instance of the
- EFI_FIRMWARE_VOLUME2_PROTOCOL on the same handle. This is the function where
- the actual initialization of the EFI_FIRMWARE_VOLUME2_PROTOCOL is done.
-
-Arguments:
- Event - The event that occured
- Context - For EFI compatiblity. Not used.
-
-Returns:
-
- None.
-
---*/
{
EFI_HANDLE Handle;
EFI_STATUS Status;
@@ -515,27 +500,24 @@ Returns:
}
+
+/**
+ This routine is the driver initialization entry point. It initializes the
+ libraries, and registers two notification functions. These notification
+ functions are responsible for building the FV stack dynamically.
+
+ @param ImageHandle The image handle.
+ @param SystemTable The system table.
+
+ @retval EFI_SUCCESS Function successfully returned.
+
+**/
EFI_STATUS
EFIAPI
FwVolDriverInit (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
-/*++
-
-Routine Description:
- This routine is the driver initialization entry point. It initializes the
- libraries, and registers two notification functions. These notification
- functions are responsible for building the FV stack dynamically.
-
-Arguments:
- ImageHandle - The image handle.
- SystemTable - The system table.
-
-Returns:
- EFI_SUCCESS - Function successfully returned.
-
---*/
{
gEfiFwVolBlockEvent = CoreCreateProtocolNotifyEvent (
&gEfiFirmwareVolumeBlockProtocolGuid,
@@ -548,3 +530,4 @@ Returns:
return EFI_SUCCESS;
}
+
diff --git a/MdeModulePkg/Core/Dxe/FwVol/FwVolAttrib.c b/MdeModulePkg/Core/Dxe/FwVol/FwVolAttrib.c
index 54abc0bfd6..8b637e82ce 100644
--- a/MdeModulePkg/Core/Dxe/FwVol/FwVolAttrib.c
+++ b/MdeModulePkg/Core/Dxe/FwVol/FwVolAttrib.c
@@ -15,26 +15,23 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
#include <DxeMain.h>
+
+/**
+ Retrieves attributes, insures positive polarity of attribute bits, returns
+ resulting attributes in output parameter.
+
+ @param This Calling context
+ @param Attributes output buffer which contains attributes
+
+ @retval EFI_SUCCESS Successfully got volume attributes
+
+**/
EFI_STATUS
EFIAPI
FvGetVolumeAttributes (
IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
OUT EFI_FV_ATTRIBUTES *Attributes
)
-/*++
-
-Routine Description:
- Retrieves attributes, insures positive polarity of attribute bits, returns
- resulting attributes in output parameter
-
-Arguments:
- This - Calling context
- Attributes - output buffer which contains attributes
-
-Returns:
- EFI_SUCCESS - Successfully got volume attributes
-
---*/
{
EFI_STATUS Status;
FV_DEVICE *FvDevice;
@@ -67,30 +64,41 @@ Returns:
}
+
+/**
+ Sets current attributes for volume
+
+ @param This Calling context
+ @param Attributes At input, contains attributes to be set. At output
+ contains new value of FV
+
+ @retval EFI_UNSUPPORTED Could not be set.
+
+**/
EFI_STATUS
EFIAPI
FvSetVolumeAttributes (
IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
IN OUT EFI_FV_ATTRIBUTES *Attributes
)
-/*++
-
-Routine Description:
- Sets current attributes for volume
-
-Arguments:
- This - Calling context
- Attributes - At input, contains attributes to be set. At output contains
- new value of FV
-
-Returns:
- EFI_UNSUPPORTED - Could not be set.
-
---*/
{
return EFI_UNSUPPORTED;
}
+
+/**
+ Return information of type InformationType for the requested firmware
+ volume.
+
+ @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
+ @param InformationType InformationType for requested.
+ @param BufferSize On input, size of Buffer.On output, the amount of data
+ returned in Buffer.
+ @param Buffer A poniter to the data buffer to return.
+
+ @retval EFI_SUCCESS Successfully got volume Information.
+
+**/
EFI_STATUS
EFIAPI
FvGetVolumeInfo (
@@ -99,27 +107,25 @@ FvGetVolumeInfo (
IN OUT UINTN *BufferSize,
OUT VOID *Buffer
)
-/*++
-
-Routine Description:
- Return information of type InformationType for the requested firmware
- volume.
-
-Arguments:
- This - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
- InformationType - InformationType for requested.
- BufferSize - On input, size of Buffer.On output, the amount of
- data returned in Buffer.
- Buffer - A poniter to the data buffer to return.
-Returns:
- EFI_SUCCESS - Successfully got volume Information.
-
---*/
{
return EFI_UNSUPPORTED;
}
+
+/**
+ Set information of type InformationType for the requested firmware
+ volume.
+
+ @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
+ @param InformationType InformationType for requested.
+ @param BufferSize On input, size of Buffer.On output, the amount of data
+ returned in Buffer.
+ @param Buffer A poniter to the data buffer to return.
+
+ @retval EFI_SUCCESS Successfully set volume Information.
+
+**/
EFI_STATUS
EFIAPI
FvSetVolumeInfo (
@@ -128,24 +134,9 @@ FvSetVolumeInfo (
IN UINTN BufferSize,
IN CONST VOID *Buffer
)
-/*++
-
-Routine Description:
- Set information of type InformationType for the requested firmware
- volume.
-
-Arguments:
- This - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
- InformationType - InformationType for requested.
- BufferSize - On input, size of Buffer.On output, the amount of
- data returned in Buffer.
- Buffer - A poniter to the data buffer to return.
-Returns:
- EFI_SUCCESS - Successfully set volume Information.
-
---*/
{
return EFI_UNSUPPORTED;
}
+
diff --git a/MdeModulePkg/Core/Dxe/FwVol/FwVolRead.c b/MdeModulePkg/Core/Dxe/FwVol/FwVolRead.c
index 5b5b6599e5..0eda2e5d3e 100644
--- a/MdeModulePkg/Core/Dxe/FwVol/FwVolRead.c
+++ b/MdeModulePkg/Core/Dxe/FwVol/FwVolRead.c
@@ -36,23 +36,20 @@ Required Alignment Alignment Value in FFS Alignment Value in
UINT8 mFvAttributes[] = {0, 4, 7, 9, 10, 12, 15, 16};
+
+/**
+ Convert the FFS File Attributes to FV File Attributes
+
+ @param FfsAttributes The attributes of UINT8 type.
+
+ @return The attributes of EFI_FV_FILE_ATTRIBUTES
+
+**/
STATIC
EFI_FV_FILE_ATTRIBUTES
FfsAttributes2FvFileAttributes (
IN EFI_FFS_FILE_ATTRIBUTES FfsAttributes
)
-/*++
-
- Routine Description:
- Convert the FFS File Attributes to FV File Attributes
-
- Arguments:
- FfsAttributes - The attributes of UINT8 type.
-
- Returns:
- The attributes of EFI_FV_FILE_ATTRIBUTES
-
---*/
{
FfsAttributes = (EFI_FFS_FILE_ATTRIBUTES)((FfsAttributes & FFS_ATTRIB_DATA_ALIGNMENT) >> 3);
ASSERT (FfsAttributes < 8);
@@ -61,6 +58,53 @@ FfsAttributes2FvFileAttributes (
}
+
+/**
+ Given the input key, search for the next matching file in the volume.
+
+ @param This Indicates the calling context.
+ @param Key Key is a pointer to a caller allocated
+ buffer that contains implementation specific
+ data that is used to track where to begin
+ the search for the next file. The size of
+ the buffer must be at least This->KeySize
+ bytes long. To reinitialize the search and
+ begin from the beginning of the firmware
+ volume, the entire buffer must be cleared to
+ zero. Other than clearing the buffer to
+ initiate a new search, the caller must not
+ modify the data in the buffer between calls
+ to GetNextFile().
+ @param FileType FileType is a pointer to a caller allocated
+ EFI_FV_FILETYPE. The GetNextFile() API can
+ filter it's search for files based on the
+ value of *FileType input. A *FileType input
+ of 0 causes GetNextFile() to search for
+ files of all types. If a file is found, the
+ file's type is returned in *FileType.
+ *FileType is not modified if no file is
+ found.
+ @param NameGuid NameGuid is a pointer to a caller allocated
+ EFI_GUID. If a file is found, the file's
+ name is returned in *NameGuid. *NameGuid is
+ not modified if no file is found.
+ @param Attributes Attributes is a pointer to a caller
+ allocated EFI_FV_FILE_ATTRIBUTES. If a file
+ is found, the file's attributes are returned
+ in *Attributes. *Attributes is not modified
+ if no file is found.
+ @param Size Size is a pointer to a caller allocated
+ UINTN. If a file is found, the file's size
+ is returned in *Size. *Size is not modified
+ if no file is found.
+
+ @retval EFI_SUCCESS Successfully find the file.
+ @retval EFI_DEVICE_ERROR Device error.
+ @retval EFI_ACCESS_DENIED Fv could not read.
+ @retval EFI_NOT_FOUND No matching file found.
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+
+**/
EFI_STATUS
EFIAPI
FvGetNextFile (
@@ -69,51 +113,8 @@ FvGetNextFile (
IN OUT EFI_FV_FILETYPE *FileType,
OUT EFI_GUID *NameGuid,
OUT EFI_FV_FILE_ATTRIBUTES *Attributes,
- OUT UINTN *Size
+ OUT UINTN *Size
)
-/*++
-
-Routine Description:
- Given the input key, search for the next matching file in the volume.
-
-Arguments:
- This - Indicates the calling context.
- FileType - FileType is a pointer to a caller allocated
- EFI_FV_FILETYPE. The GetNextFile() API can filter it's
- search for files based on the value of *FileType input.
- A *FileType input of 0 causes GetNextFile() to search for
- files of all types. If a file is found, the file's type
- is returned in *FileType. *FileType is not modified if
- no file is found.
- Key - Key is a pointer to a caller allocated buffer that
- contains implementation specific data that is used to
- track where to begin the search for the next file.
- The size of the buffer must be at least This->KeySize
- bytes long. To reinitialize the search and begin from
- the beginning of the firmware volume, the entire buffer
- must be cleared to zero. Other than clearing the buffer
- to initiate a new search, the caller must not modify the
- data in the buffer between calls to GetNextFile().
- NameGuid - NameGuid is a pointer to a caller allocated EFI_GUID.
- If a file is found, the file's name is returned in
- *NameGuid. *NameGuid is not modified if no file is
- found.
- Attributes - Attributes is a pointer to a caller allocated
- EFI_FV_FILE_ATTRIBUTES. If a file is found, the file's
- attributes are returned in *Attributes. *Attributes is
- not modified if no file is found.
- Size - Size is a pointer to a caller allocated UINTN.
- If a file is found, the file's size is returned in *Size.
- *Size is not modified if no file is found.
-
-Returns:
- EFI_SUCCESS - Successfully find the file.
- EFI_DEVICE_ERROR - Device error.
- EFI_ACCESS_DENIED - Fv could not read.
- EFI_NOT_FOUND - No matching file found.
- EFI_INVALID_PARAMETER - Invalid parameter
-
---*/
{
EFI_STATUS Status;
FV_DEVICE *FvDevice;
@@ -218,6 +219,47 @@ Returns:
}
+
+/**
+ Locates a file in the firmware volume and
+ copies it to the supplied buffer.
+
+ @param This Indicates the calling context.
+ @param NameGuid Pointer to an EFI_GUID, which is the
+ filename.
+ @param Buffer Buffer is a pointer to pointer to a buffer
+ in which the file or section contents or are
+ returned.
+ @param BufferSize BufferSize is a pointer to caller allocated
+ UINTN. On input *BufferSize indicates the
+ size in bytes of the memory region pointed
+ to by Buffer. On output, *BufferSize
+ contains the number of bytes required to
+ read the file.
+ @param FoundType FoundType is a pointer to a caller allocated
+ EFI_FV_FILETYPE that on successful return
+ from Read() contains the type of file read.
+ This output reflects the file type
+ irrespective of the value of the SectionType
+ input.
+ @param FileAttributes FileAttributes is a pointer to a caller
+ allocated EFI_FV_FILE_ATTRIBUTES. On
+ successful return from Read(),
+ *FileAttributes contains the attributes of
+ the file read.
+ @param AuthenticationStatus AuthenticationStatus is a pointer to a
+ caller allocated UINTN in which the
+ authentication status is returned.
+
+ @retval EFI_SUCCESS Successfully read to memory buffer.
+ @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
+ @retval EFI_NOT_FOUND Not found.
+ @retval EFI_DEVICE_ERROR Device error.
+ @retval EFI_ACCESS_DENIED Could not read.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
+
+**/
EFI_STATUS
EFIAPI
FvReadFile (
@@ -229,44 +271,6 @@ FvReadFile (
OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes,
OUT UINT32 *AuthenticationStatus
)
-/*++
-
-Routine Description:
- Locates a file in the firmware volume and
- copies it to the supplied buffer.
-
-Arguments:
- This - Indicates the calling context.
- NameGuid - Pointer to an EFI_GUID, which is the filename.
- Buffer - Buffer is a pointer to pointer to a buffer in
- which the file or section contents or are returned.
- BufferSize - BufferSize is a pointer to caller allocated
- UINTN. On input *BufferSize indicates the size
- in bytes of the memory region pointed to by
- Buffer. On output, *BufferSize contains the number
- of bytes required to read the file.
- FoundType - FoundType is a pointer to a caller allocated
- EFI_FV_FILETYPE that on successful return from Read()
- contains the type of file read. This output reflects
- the file type irrespective of the value of the
- SectionType input.
- FileAttributes - FileAttributes is a pointer to a caller allocated
- EFI_FV_FILE_ATTRIBUTES. On successful return from
- Read(), *FileAttributes contains the attributes of
- the file read.
- AuthenticationStatus - AuthenticationStatus is a pointer to a caller
- allocated UINTN in which the authentication status
- is returned.
-Returns:
- EFI_SUCCESS - Successfully read to memory buffer.
- EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
- EFI_NOT_FOUND - Not found.
- EFI_DEVICE_ERROR - Device error.
- EFI_ACCESS_DENIED - Could not read.
- EFI_INVALID_PARAMETER - Invalid parameter.
- EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
-
---*/
{
EFI_STATUS Status;
FV_DEVICE *FvDevice;
@@ -361,6 +365,35 @@ Returns:
}
+
+/**
+ Locates a section in a given FFS File and
+ copies it to the supplied buffer (not including section header).
+
+ @param This Indicates the calling context.
+ @param NameGuid Pointer to an EFI_GUID, which is the
+ filename.
+ @param SectionType Indicates the section type to return.
+ @param SectionInstance Indicates which instance of sections with a
+ type of SectionType to return.
+ @param Buffer Buffer is a pointer to pointer to a buffer
+ in which the file or section contents or are
+ returned.
+ @param BufferSize BufferSize is a pointer to caller allocated
+ UINTN.
+ @param AuthenticationStatus AuthenticationStatus is a pointer to a
+ caller allocated UINT32 in which the
+ authentication status is returned.
+
+ @retval EFI_SUCCESS Successfully read the file section into
+ buffer.
+ @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
+ @retval EFI_NOT_FOUND Section not found.
+ @retval EFI_DEVICE_ERROR Device error.
+ @retval EFI_ACCESS_DENIED Could not read.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+
+**/
EFI_STATUS
EFIAPI
FvReadFileSection (
@@ -372,34 +405,6 @@ FvReadFileSection (
IN OUT UINTN *BufferSize,
OUT UINT32 *AuthenticationStatus
)
-/*++
-
- Routine Description:
- Locates a section in a given FFS File and
- copies it to the supplied buffer (not including section header).
-
- Arguments:
- This - Indicates the calling context.
- NameGuid - Pointer to an EFI_GUID, which is the filename.
- SectionType - Indicates the section type to return.
- SectionInstance - Indicates which instance of sections with a type of
- SectionType to return.
- Buffer - Buffer is a pointer to pointer to a buffer in which
- the file or section contents or are returned.
- BufferSize - BufferSize is a pointer to caller allocated UINTN.
- AuthenticationStatus -AuthenticationStatus is a pointer to a caller
- allocated UINT32 in which the authentication status
- is returned.
-
- Returns:
- EFI_SUCCESS - Successfully read the file section into buffer.
- EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
- EFI_NOT_FOUND - Section not found.
- EFI_DEVICE_ERROR - Device error.
- EFI_ACCESS_DENIED - Could not read.
- EFI_INVALID_PARAMETER - Invalid parameter.
-
---*/
{
EFI_STATUS Status;
FV_DEVICE *FvDevice;
@@ -482,3 +487,4 @@ Done:
return Status;
}
+
diff --git a/MdeModulePkg/Core/Dxe/FwVol/FwVolWrite.c b/MdeModulePkg/Core/Dxe/FwVol/FwVolWrite.c
index a053a96d43..5fe01a4889 100644
--- a/MdeModulePkg/Core/Dxe/FwVol/FwVolWrite.c
+++ b/MdeModulePkg/Core/Dxe/FwVol/FwVolWrite.c
@@ -16,6 +16,28 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
#include <DxeMain.h>
+
+/**
+ Writes one or more files to the firmware volume.
+
+ @param This Indicates the calling context.
+ @param NumberOfFiles Number of files.
+ @param WritePolicy WritePolicy indicates the level of reliability
+ for the write in the event of a power failure or
+ other system failure during the write operation.
+ @param FileData FileData is an pointer to an array of
+ EFI_FV_WRITE_DATA. Each element of array
+ FileData represents a file to be written.
+
+ @retval EFI_SUCCESS Files successfully written to firmware volume
+ @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
+ @retval EFI_DEVICE_ERROR Device error.
+ @retval EFI_WRITE_PROTECTED Write protected.
+ @retval EFI_NOT_FOUND Not found.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_UNSUPPORTED This function not supported.
+
+**/
EFI_STATUS
EFIAPI
FvWriteFile (
@@ -24,31 +46,8 @@ FvWriteFile (
IN EFI_FV_WRITE_POLICY WritePolicy,
IN EFI_FV_WRITE_FILE_DATA *FileData
)
-/*++
-
- Routine Description:
- Writes one or more files to the firmware volume.
-
- Arguments:
- This - Indicates the calling context.
- NumberOfFiles - Number of files.
- WritePolicy - WritePolicy indicates the level of reliability for
- the write in the event of a power failure or other
- system failure during the write operation.
- FileData - FileData is an pointer to an array of EFI_FV_WRITE_DATA.
- Each element of FileData[] represents a file to be written.
-
- Returns:
- EFI_SUCCESS - Files successfully written to firmware volume
- EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
- EFI_DEVICE_ERROR - Device error.
- EFI_WRITE_PROTECTED - Write protected.
- EFI_NOT_FOUND - Not found.
- EFI_INVALID_PARAMETER - Invalid parameter.
- EFI_UNSUPPORTED - This function not supported.
-
---*/
{
return EFI_UNSUPPORTED;
}
+
diff --git a/MdeModulePkg/Core/Dxe/FwVolBlock.h b/MdeModulePkg/Core/Dxe/FwVolBlock.h
index 9cd17326c9..809540b575 100644
--- a/MdeModulePkg/Core/Dxe/FwVolBlock.h
+++ b/MdeModulePkg/Core/Dxe/FwVolBlock.h
@@ -47,106 +47,123 @@ typedef struct {
+/**
+ This routine is the driver initialization entry point. It initializes the
+ libraries, consumes FV hobs and NT_NON_MM_FV environment variable and
+ produces instances of FW_VOL_BLOCK_PROTOCOL as appropriate.
+
+ @param ImageHandle The image handle.
+ @param SystemTable The system table.
+
+ @retval EFI_SUCCESS Successfully initialized firmware volume block
+ driver.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockDriverInit (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
-/*++
-
-Routine Description:
- This routine is the driver initialization entry point. It initializes the
- libraries, consumes FV hobs and NT_NON_MM_FV environment variable and
- produces instances of FW_VOL_BLOCK_PROTOCOL as appropriate.
-Arguments:
- ImageHandle - The image handle.
- SystemTable - The system table.
-Returns:
- EFI_SUCCESS - Successfully initialized firmware volume block driver.
---*/
;
+
+/**
+ Retrieves Volume attributes. No polarity translations are done.
+
+ @param This Calling context
+ @param Attributes output buffer which contains attributes
+
+ @retval EFI_SUCCESS The firmware volume attributes were returned.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockGetAttributes (
IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
OUT EFI_FVB_ATTRIBUTES *Attributes
)
-/*++
-
-Routine Description:
- Retrieves Volume attributes. No polarity translations are done.
-
-Arguments:
- This - Calling context
- Attributes - output buffer which contains attributes
-
-Returns:
- EFI_SUCCESS - The firmware volume attributes were returned.
-
---*/
;
+
+/**
+ Modifies the current settings of the firmware volume according to the input parameter.
+
+ @param This Calling context
+ @param Attributes input buffer which contains attributes
+
+ @retval EFI_SUCCESS The firmware volume attributes were returned.
+ @retval EFI_INVALID_PARAMETER The attributes requested are in conflict with
+ the capabilities as declared in the firmware
+ volume header.
+ @retval EFI_UNSUPPORTED Not supported.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockSetAttributes (
IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
IN CONST EFI_FVB_ATTRIBUTES *Attributes
)
-/*++
-
-Routine Description:
- Modifies the current settings of the firmware volume according to the input parameter.
-
-Arguments:
- This - Calling context
- Attributes - input buffer which contains attributes
-
-Returns:
- EFI_SUCCESS - The firmware volume attributes were returned.
- EFI_INVALID_PARAMETER - The attributes requested are in conflict with the capabilities as
- declared in the firmware volume header.
- EFI_UNSUPPORTED - Not supported.
---*/
;
+
+/**
+ The EraseBlock() function erases one or more blocks as denoted by the
+ variable argument list. The entire parameter list of blocks must be verified
+ prior to erasing any blocks. If a block is requested that does not exist
+ within the associated firmware volume (it has a larger index than the last
+ block of the firmware volume), the EraseBlock() function must return
+ EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.
+
+ @param This Calling context
+ @param ... Starting LBA followed by Number of Lba to erase.
+ a -1 to terminate the list.
+
+ @retval EFI_SUCCESS The erase request was successfully completed.
+ @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled
+ state.
+ @retval EFI_DEVICE_ERROR The block device is not functioning correctly
+ and could not be written. The firmware device
+ may have been partially erased.
+ @retval EFI_INVALID_PARAMETER One or more of the LBAs listed in the variable
+ argument list do
+ @retval EFI_UNSUPPORTED Not supported.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockEraseBlock (
IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
...
)
-/*++
-
-Routine Description:
- The EraseBlock() function erases one or more blocks as denoted by the
-variable argument list. The entire parameter list of blocks must be verified
-prior to erasing any blocks. If a block is requested that does not exist
-within the associated firmware volume (it has a larger index than the last
-block of the firmware volume), the EraseBlock() function must return
-EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.
-
-Arguments:
- This - Calling context
- ... - Starting LBA followed by Number of Lba to erase. a -1 to terminate
- the list.
-
-Returns:
- EFI_SUCCESS - The erase request was successfully completed.
- EFI_ACCESS_DENIED - The firmware volume is in the WriteDisabled state.
- EFI_DEVICE_ERROR - The block device is not functioning correctly and could not be
- written. The firmware device may have been partially erased.
- EFI_INVALID_PARAMETER - One or more of the LBAs listed in the variable argument list do
- EFI_UNSUPPORTED - Not supported.
-
---*/
;
+
+/**
+ Read the specified number of bytes from the block to the input buffer.
+
+ @param This Indicates the calling context.
+ @param Lba The starting logical block index to read.
+ @param Offset Offset into the block at which to begin reading.
+ @param NumBytes Pointer to a UINT32. At entry, *NumBytes
+ contains the total size of the buffer. At exit,
+ *NumBytes contains the total number of bytes
+ actually read.
+ @param Buffer Pinter to a caller-allocated buffer that
+ contains the destine for the read.
+
+ @retval EFI_SUCCESS The firmware volume was read successfully.
+ @retval EFI_BAD_BUFFER_SIZE The read was attempted across an LBA boundary.
+ @retval EFI_ACCESS_DENIED Access denied.
+ @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not
+ be read.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockReadBlock (
@@ -156,30 +173,34 @@ FwVolBlockReadBlock (
IN OUT UINTN *NumBytes,
IN OUT UINT8 *Buffer
)
-/*++
-
-Routine Description:
- Read the specified number of bytes from the block to the input buffer.
-
-Arguments:
- This - Indicates the calling context.
- Lba - The starting logical block index to read.
- Offset - Offset into the block at which to begin reading.
- NumBytes - Pointer to a UINT32. At entry, *NumBytes contains the
- total size of the buffer. At exit, *NumBytes contains the
- total number of bytes actually read.
- Buffer - Pinter to a caller-allocated buffer that contains the destine
- for the read.
-
-Returns:
- EFI_SUCCESS - The firmware volume was read successfully.
- EFI_BAD_BUFFER_SIZE - The read was attempted across an LBA boundary.
- EFI_ACCESS_DENIED - Access denied.
- EFI_DEVICE_ERROR - The block device is malfunctioning and could not be read.
---*/
;
+
+/**
+ Writes the specified number of bytes from the input buffer to the block.
+
+ @param This Indicates the calling context.
+ @param Lba The starting logical block index to write to.
+ @param Offset Offset into the block at which to begin writing.
+ @param NumBytes Pointer to a UINT32. At entry, *NumBytes
+ contains the total size of the buffer. At exit,
+ *NumBytes contains the total number of bytes
+ actually written.
+ @param Buffer Pinter to a caller-allocated buffer that
+ contains the source for the write.
+
+ @retval EFI_SUCCESS The firmware volume was written successfully.
+ @retval EFI_BAD_BUFFER_SIZE The write was attempted across an LBA boundary.
+ On output, NumBytes contains the total number of
+ bytes actually written.
+ @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled
+ state.
+ @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not
+ be written.
+ @retval EFI_UNSUPPORTED Not supported.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockWriteBlock (
@@ -189,54 +210,47 @@ FwVolBlockWriteBlock (
IN OUT UINTN *NumBytes,
IN UINT8 *Buffer
)
-/*++
-
-Routine Description:
- Writes the specified number of bytes from the input buffer to the block.
-
-Arguments:
- This - Indicates the calling context.
- Lba - The starting logical block index to write to.
- Offset - Offset into the block at which to begin writing.
- NumBytes - Pointer to a UINT32. At entry, *NumBytes contains the
- total size of the buffer. At exit, *NumBytes contains the
- total number of bytes actually written.
- Buffer - Pinter to a caller-allocated buffer that contains the source
- for the write.
-
-Returns:
- EFI_SUCCESS - The firmware volume was written successfully.
- EFI_BAD_BUFFER_SIZE - The write was attempted across an LBA boundary. On output,
- NumBytes contains the total number of bytes actually written.
- EFI_ACCESS_DENIED - The firmware volume is in the WriteDisabled state.
- EFI_DEVICE_ERROR - The block device is malfunctioning and could not be written.
- EFI_UNSUPPORTED - Not supported.
---*/
;
+
+/**
+ Get Fvb's base address.
+
+ @param This Indicates the calling context.
+ @param Address Fvb device base address.
+
+ @retval EFI_SUCCESS Successfully got Fvb's base address.
+ @retval EFI_UNSUPPORTED Not supported.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockGetPhysicalAddress (
IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
OUT EFI_PHYSICAL_ADDRESS *Address
)
-/*++
-
-Routine Description:
- Get Fvb's base address.
-
-Arguments:
- This - Indicates the calling context.
- Address - Fvb device base address.
-
-Returns:
- EFI_SUCCESS - Successfully got Fvb's base address.
- EFI_UNSUPPORTED - Not supported.
---*/
;
+
+/**
+ Retrieves the size in bytes of a specific block within a firmware volume.
+
+ @param This Indicates the calling context.
+ @param Lba Indicates the block for which to return the
+ size.
+ @param BlockSize Pointer to a caller-allocated UINTN in which the
+ size of the block is returned.
+ @param NumberOfBlocks Pointer to a caller-allocated UINTN in which the
+ number of consecutive blocks starting with Lba
+ is returned. All blocks in this range have a
+ size of BlockSize.
+
+ @retval EFI_SUCCESS The firmware volume base address is returned.
+ @retval EFI_INVALID_PARAMETER The requested LBA is out of range.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockGetBlockSize (
@@ -245,71 +259,52 @@ FwVolBlockGetBlockSize (
OUT UINTN *BlockSize,
OUT UINTN *NumberOfBlocks
)
-/*++
-
-Routine Description:
- Retrieves the size in bytes of a specific block within a firmware volume.
-
-Arguments:
- This - Indicates the calling context.
- Lba - Indicates the block for which to return the size.
- BlockSize - Pointer to a caller-allocated UINTN in which the size of the
- block is returned.
- NumberOfBlocks - Pointer to a caller-allocated UINTN in which the number of
- consecutive blocks starting with Lba is returned. All blocks
- in this range have a size of BlockSize.
-Returns:
- EFI_SUCCESS - The firmware volume base address is returned.
- EFI_INVALID_PARAMETER - The requested LBA is out of range.
---*/
;
+
+/**
+ This routine is the driver initialization entry point. It initializes the
+ libraries, consumes FV hobs and NT_NON_MM_FV environment variable and
+ produces instances of FW_VOL_BLOCK_PROTOCOL as appropriate.
+
+ @param ImageHandle The image handle.
+ @param SystemTable The system table.
+
+ @retval EFI_SUCCESS Successfully initialized firmware volume block
+ driver.
+
+**/
EFI_STATUS
FwVolBlockDriverInit (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
-/*++
-
-Routine Description:
- This routine is the driver initialization entry point. It initializes the
- libraries, consumes FV hobs and NT_NON_MM_FV environment variable and
- produces instances of FW_VOL_BLOCK_PROTOCOL as appropriate.
-Arguments:
- ImageHandle - The image handle.
- SystemTable - The system table.
-Returns:
- Status code
-
---*/
;
+
+/**
+ This routine produces a firmware volume block protocol on a given
+ buffer.
+
+ @param BaseAddress base address of the firmware volume image
+ @param Length length of the firmware volume image
+ @param ParentHandle handle of parent firmware volume, if this image
+ came from an FV image file in another firmware
+ volume (ala capsules)
+ @param FvProtocol Firmware volume block protocol produced.
+
+ @retval EFI_VOLUME_CORRUPTED Volume corrupted.
+ @retval EFI_OUT_OF_RESOURCES No enough buffer to be allocated.
+ @retval EFI_SUCCESS Successfully produced a FVB protocol on given
+ buffer.
+
+**/
EFI_STATUS
ProduceFVBProtocolOnBuffer (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
IN UINT64 Length,
IN EFI_HANDLE ParentHandle,
- OUT EFI_HANDLE *FvProtocolHandle OPTIONAL
+ OUT EFI_HANDLE *FvProtocol OPTIONAL
)
-/*++
-
-Routine Description:
- This routine produces a firmware volume block protocol on a given
- buffer.
-
-Arguments:
- BaseAddress - base address of the firmware volume image
- Length - length of the firmware volume image
- ParentHandle - handle of parent firmware volume, if this
- image came from an FV image file in another
- firmware volume (ala capsules)
- FvProtocolHandle - Firmware volume block protocol produced.
-
-Returns:
- EFI_VOLUME_CORRUPTED - Volume corrupted.
- EFI_OUT_OF_RESOURCES - No enough buffer to be allocated.
- EFI_SUCCESS - Successfully produced a FVB protocol on given buffer.
-
---*/
;
#endif
diff --git a/MdeModulePkg/Core/Dxe/FwVolBlock/FwVolBlock.c b/MdeModulePkg/Core/Dxe/FwVolBlock/FwVolBlock.c
index d507167594..62795b2f35 100644
--- a/MdeModulePkg/Core/Dxe/FwVolBlock/FwVolBlock.c
+++ b/MdeModulePkg/Core/Dxe/FwVolBlock/FwVolBlock.c
@@ -1,11 +1,11 @@
-/**@file
- Firmware Volume Block protocol.. Consumes FV hobs and creates
+/** @file
+ Firmware Volume Block protocol. Consumes FV hobs and creates
appropriate block protocols.
Also consumes NT_NON_MM_FV envinronment variable and produces appropriate
block protocols fro them also... (this is TBD)
-Copyright (c) 2006, Intel Corporation
+Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -58,25 +58,22 @@ EFI_FW_VOL_BLOCK_DEVICE mFwVolBlock = {
+
+/**
+ Retrieves Volume attributes. No polarity translations are done.
+
+ @param This Calling context
+ @param Attributes output buffer which contains attributes
+
+ @retval EFI_SUCCESS The firmware volume attributes were returned.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockGetAttributes (
IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
OUT EFI_FVB_ATTRIBUTES *Attributes
)
-/*++
-
-Routine Description:
- Retrieves Volume attributes. No polarity translations are done.
-
-Arguments:
- This - Calling context
- Attributes - output buffer which contains attributes
-
-Returns:
- EFI_SUCCESS - The firmware volume attributes were returned.
-
---*/
{
EFI_FW_VOL_BLOCK_DEVICE *FvbDevice;
@@ -91,67 +88,87 @@ Returns:
}
+
+/**
+ Modifies the current settings of the firmware volume according to the input parameter.
+
+ @param This Calling context
+ @param Attributes input buffer which contains attributes
+
+ @retval EFI_SUCCESS The firmware volume attributes were returned.
+ @retval EFI_INVALID_PARAMETER The attributes requested are in conflict with
+ the capabilities as declared in the firmware
+ volume header.
+ @retval EFI_UNSUPPORTED Not supported.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockSetAttributes (
IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
IN CONST EFI_FVB_ATTRIBUTES *Attributes
)
-/*++
-
-Routine Description:
- Modifies the current settings of the firmware volume according to the input parameter.
-
-Arguments:
- This - Calling context
- Attributes - input buffer which contains attributes
-
-Returns:
- EFI_SUCCESS - The firmware volume attributes were returned.
- EFI_INVALID_PARAMETER - The attributes requested are in conflict with the capabilities as
- declared in the firmware volume header.
- EFI_UNSUPPORTED - Not supported.
---*/
{
return EFI_UNSUPPORTED;
}
+
+/**
+ The EraseBlock() function erases one or more blocks as denoted by the
+ variable argument list. The entire parameter list of blocks must be verified
+ prior to erasing any blocks. If a block is requested that does not exist
+ within the associated firmware volume (it has a larger index than the last
+ block of the firmware volume), the EraseBlock() function must return
+ EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.
+
+ @param This Calling context
+ @param ... Starting LBA followed by Number of Lba to erase.
+ a -1 to terminate the list.
+
+ @retval EFI_SUCCESS The erase request was successfully completed.
+ @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled
+ state.
+ @retval EFI_DEVICE_ERROR The block device is not functioning correctly
+ and could not be written. The firmware device
+ may have been partially erased.
+ @retval EFI_INVALID_PARAMETER One or more of the LBAs listed in the variable
+ argument list do
+ @retval EFI_UNSUPPORTED Not supported.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockEraseBlock (
IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
...
)
-/*++
-
-Routine Description:
- The EraseBlock() function erases one or more blocks as denoted by the
-variable argument list. The entire parameter list of blocks must be verified
-prior to erasing any blocks. If a block is requested that does not exist
-within the associated firmware volume (it has a larger index than the last
-block of the firmware volume), the EraseBlock() function must return
-EFI_INVALID_PARAMETER without modifying the contents of the firmware volume.
-
-Arguments:
- This - Calling context
- ... - Starting LBA followed by Number of Lba to erase. a -1 to terminate
- the list.
-
-Returns:
- EFI_SUCCESS - The erase request was successfully completed.
- EFI_ACCESS_DENIED - The firmware volume is in the WriteDisabled state.
- EFI_DEVICE_ERROR - The block device is not functioning correctly and could not be
- written. The firmware device may have been partially erased.
- EFI_INVALID_PARAMETER - One or more of the LBAs listed in the variable argument list do
- EFI_UNSUPPORTED - Not supported.
-
---*/
{
return EFI_UNSUPPORTED;
}
+
+/**
+ Read the specified number of bytes from the block to the input buffer.
+
+ @param This Indicates the calling context.
+ @param Lba The starting logical block index to read.
+ @param Offset Offset into the block at which to begin reading.
+ @param NumBytes Pointer to a UINT32. At entry, *NumBytes
+ contains the total size of the buffer. At exit,
+ *NumBytes contains the total number of bytes
+ actually read.
+ @param Buffer Pinter to a caller-allocated buffer that
+ contains the destine for the read.
+
+ @retval EFI_SUCCESS The firmware volume was read successfully.
+ @retval EFI_BAD_BUFFER_SIZE The read was attempted across an LBA boundary.
+ @retval EFI_ACCESS_DENIED Access denied.
+ @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not
+ be read.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockReadBlock (
@@ -161,27 +178,6 @@ FwVolBlockReadBlock (
IN OUT UINTN *NumBytes,
IN OUT UINT8 *Buffer
)
-/*++
-
-Routine Description:
- Read the specified number of bytes from the block to the input buffer.
-
-Arguments:
- This - Indicates the calling context.
- Lba - The starting logical block index to read.
- Offset - Offset into the block at which to begin reading.
- NumBytes - Pointer to a UINT32. At entry, *NumBytes contains the
- total size of the buffer. At exit, *NumBytes contains the
- total number of bytes actually read.
- Buffer - Pinter to a caller-allocated buffer that contains the destine
- for the read.
-
-Returns:
- EFI_SUCCESS - The firmware volume was read successfully.
- EFI_BAD_BUFFER_SIZE - The read was attempted across an LBA boundary.
- EFI_ACCESS_DENIED - Access denied.
- EFI_DEVICE_ERROR - The block device is malfunctioning and could not be read.
---*/
{
EFI_FW_VOL_BLOCK_DEVICE *FvbDevice;
EFI_FIRMWARE_VOLUME_HEADER *FwVolHeader;
@@ -242,6 +238,31 @@ Returns:
}
+
+/**
+ Writes the specified number of bytes from the input buffer to the block.
+
+ @param This Indicates the calling context.
+ @param Lba The starting logical block index to write to.
+ @param Offset Offset into the block at which to begin writing.
+ @param NumBytes Pointer to a UINT32. At entry, *NumBytes
+ contains the total size of the buffer. At exit,
+ *NumBytes contains the total number of bytes
+ actually written.
+ @param Buffer Pinter to a caller-allocated buffer that
+ contains the source for the write.
+
+ @retval EFI_SUCCESS The firmware volume was written successfully.
+ @retval EFI_BAD_BUFFER_SIZE The write was attempted across an LBA boundary.
+ On output, NumBytes contains the total number of
+ bytes actually written.
+ @retval EFI_ACCESS_DENIED The firmware volume is in the WriteDisabled
+ state.
+ @retval EFI_DEVICE_ERROR The block device is malfunctioning and could not
+ be written.
+ @retval EFI_UNSUPPORTED Not supported.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockWriteBlock (
@@ -251,53 +272,28 @@ FwVolBlockWriteBlock (
IN OUT UINTN *NumBytes,
IN UINT8 *Buffer
)
-/*++
-
-Routine Description:
- Writes the specified number of bytes from the input buffer to the block.
-
-Arguments:
- This - Indicates the calling context.
- Lba - The starting logical block index to write to.
- Offset - Offset into the block at which to begin writing.
- NumBytes - Pointer to a UINT32. At entry, *NumBytes contains the
- total size of the buffer. At exit, *NumBytes contains the
- total number of bytes actually written.
- Buffer - Pinter to a caller-allocated buffer that contains the source
- for the write.
-
-Returns:
- EFI_SUCCESS - The firmware volume was written successfully.
- EFI_BAD_BUFFER_SIZE - The write was attempted across an LBA boundary. On output,
- NumBytes contains the total number of bytes actually written.
- EFI_ACCESS_DENIED - The firmware volume is in the WriteDisabled state.
- EFI_DEVICE_ERROR - The block device is malfunctioning and could not be written.
- EFI_UNSUPPORTED - Not supported.
---*/
{
return EFI_UNSUPPORTED;
}
+
+/**
+ Get Fvb's base address.
+
+ @param This Indicates the calling context.
+ @param Address Fvb device base address.
+
+ @retval EFI_SUCCESS Successfully got Fvb's base address.
+ @retval EFI_UNSUPPORTED Not supported.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockGetPhysicalAddress (
IN CONST EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *This,
OUT EFI_PHYSICAL_ADDRESS *Address
)
-/*++
-
-Routine Description:
- Get Fvb's base address.
-
-Arguments:
- This - Indicates the calling context.
- Address - Fvb device base address.
-
-Returns:
- EFI_SUCCESS - Successfully got Fvb's base address.
- EFI_UNSUPPORTED - Not supported.
---*/
{
EFI_FW_VOL_BLOCK_DEVICE *FvbDevice;
@@ -312,6 +308,24 @@ Returns:
}
+
+/**
+ Retrieves the size in bytes of a specific block within a firmware volume.
+
+ @param This Indicates the calling context.
+ @param Lba Indicates the block for which to return the
+ size.
+ @param BlockSize Pointer to a caller-allocated UINTN in which the
+ size of the block is returned.
+ @param NumberOfBlocks Pointer to a caller-allocated UINTN in which the
+ number of consecutive blocks starting with Lba
+ is returned. All blocks in this range have a
+ size of BlockSize.
+
+ @retval EFI_SUCCESS The firmware volume base address is returned.
+ @retval EFI_INVALID_PARAMETER The requested LBA is out of range.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockGetBlockSize (
@@ -320,23 +334,6 @@ FwVolBlockGetBlockSize (
IN OUT UINTN *BlockSize,
IN OUT UINTN *NumberOfBlocks
)
-/*++
-
-Routine Description:
- Retrieves the size in bytes of a specific block within a firmware volume.
-
-Arguments:
- This - Indicates the calling context.
- Lba - Indicates the block for which to return the size.
- BlockSize - Pointer to a caller-allocated UINTN in which the size of the
- block is returned.
- NumberOfBlocks - Pointer to a caller-allocated UINTN in which the number of
- consecutive blocks starting with Lba is returned. All blocks
- in this range have a size of BlockSize.
-Returns:
- EFI_SUCCESS - The firmware volume base address is returned.
- EFI_INVALID_PARAMETER - The requested LBA is out of range.
---*/
{
UINTN TotalBlocks;
EFI_FW_VOL_BLOCK_DEVICE *FvbDevice;
@@ -379,6 +376,24 @@ Returns:
}
+
+/**
+ This routine produces a firmware volume block protocol on a given
+ buffer.
+
+ @param BaseAddress base address of the firmware volume image
+ @param Length length of the firmware volume image
+ @param ParentHandle handle of parent firmware volume, if this image
+ came from an FV image file in another firmware
+ volume (ala capsules)
+ @param FvProtocol Firmware volume block protocol produced.
+
+ @retval EFI_VOLUME_CORRUPTED Volume corrupted.
+ @retval EFI_OUT_OF_RESOURCES No enough buffer to be allocated.
+ @retval EFI_SUCCESS Successfully produced a FVB protocol on given
+ buffer.
+
+**/
EFI_STATUS
ProduceFVBProtocolOnBuffer (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
@@ -386,26 +401,6 @@ ProduceFVBProtocolOnBuffer (
IN EFI_HANDLE ParentHandle,
OUT EFI_HANDLE *FvProtocol OPTIONAL
)
-/*++
-
-Routine Description:
- This routine produces a firmware volume block protocol on a given
- buffer.
-
-Arguments:
- BaseAddress - base address of the firmware volume image
- Length - length of the firmware volume image
- ParentHandle - handle of parent firmware volume, if this
- image came from an FV image file in another
- firmware volume (ala capsules)
- FvProtocol - Firmware volume block protocol produced.
-
-Returns:
- EFI_VOLUME_CORRUPTED - Volume corrupted.
- EFI_OUT_OF_RESOURCES - No enough buffer to be allocated.
- EFI_SUCCESS - Successfully produced a FVB protocol on given buffer.
-
---*/
{
EFI_STATUS Status;
EFI_FW_VOL_BLOCK_DEVICE *FvbDev;
@@ -511,24 +506,25 @@ Returns:
}
+
+/**
+ This routine is the driver initialization entry point. It initializes the
+ libraries, consumes FV hobs and NT_NON_MM_FV environment variable and
+ produces instances of FW_VOL_BLOCK_PROTOCOL as appropriate.
+
+ @param ImageHandle The image handle.
+ @param SystemTable The system table.
+
+ @retval EFI_SUCCESS Successfully initialized firmware volume block
+ driver.
+
+**/
EFI_STATUS
EFIAPI
FwVolBlockDriverInit (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
-/*++
-
-Routine Description:
- This routine is the driver initialization entry point. It initializes the
- libraries, consumes FV hobs and NT_NON_MM_FV environment variable and
- produces instances of FW_VOL_BLOCK_PROTOCOL as appropriate.
-Arguments:
- ImageHandle - The image handle.
- SystemTable - The system table.
-Returns:
- EFI_SUCCESS - Successfully initialized firmware volume block driver.
---*/
{
EFI_PEI_HOB_POINTERS FvHob;
//
@@ -546,33 +542,30 @@ Returns:
}
+
+/**
+ This DXE service routine is used to process a firmware volume. In
+ particular, it can be called by BDS to process a single firmware
+ volume found in a capsule.
+
+ @param FvHeader pointer to a firmware volume header
+ @param Size the size of the buffer pointed to by FvHeader
+ @param FVProtocolHandle the handle on which a firmware volume protocol
+ was produced for the firmware volume passed in.
+
+ @retval EFI_OUT_OF_RESOURCES if an FVB could not be produced due to lack of
+ system resources
+ @retval EFI_VOLUME_CORRUPTED if the volume was corrupted
+ @retval EFI_SUCCESS a firmware volume protocol was produced for the
+ firmware volume
+
+**/
EFI_STATUS
CoreProcessFirmwareVolume (
IN VOID *FvHeader,
IN UINTN Size,
OUT EFI_HANDLE *FVProtocolHandle
)
-/*++
-
-Routine Description:
- This DXE service routine is used to process a firmware volume. In
- particular, it can be called by BDS to process a single firmware
- volume found in a capsule.
-
-Arguments:
- FvHeader - pointer to a firmware volume header
- Size - the size of the buffer pointed to by FvHeader
- FVProtocolHandle - the handle on which a firmware volume protocol
- was produced for the firmware volume passed in.
-
-Returns:
- EFI_OUT_OF_RESOURCES - if an FVB could not be produced due to lack of
- system resources
- EFI_VOLUME_CORRUPTED - if the volume was corrupted
- EFI_SUCCESS - a firmware volume protocol was produced for the
- firmware volume
-
---*/
{
VOID *Ptr;
EFI_STATUS Status;
@@ -604,3 +597,4 @@ Returns:
}
+
diff --git a/MdeModulePkg/Core/Dxe/FwVolDriver.h b/MdeModulePkg/Core/Dxe/FwVolDriver.h
index 6469670d04..d89043e6b5 100644
--- a/MdeModulePkg/Core/Dxe/FwVolDriver.h
+++ b/MdeModulePkg/Core/Dxe/FwVolDriver.h
@@ -1,4 +1,4 @@
-/**@file
+/** @file
Firmware File System protocol. Layers on top of Firmware
Block protocol to produce a file abstraction of FV based files.
@@ -14,8 +14,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
-#ifndef __FWVOL_H
-#define __FWVOL_H
+#ifndef __FW_VOL_DRIVER_H_
+#define __FW_VOL_DRIVER_H_
#define FV2_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('_', 'F', 'V', '2')
@@ -48,50 +48,90 @@ typedef struct {
#define FV_DEVICE_FROM_THIS(a) CR(a, FV_DEVICE, Fv, FV2_DEVICE_SIGNATURE)
+/**
+ Retrieves attributes, insures positive polarity of attribute bits, returns
+ resulting attributes in output parameter.
+ @param This Calling context
+ @param Attributes output buffer which contains attributes
+
+ @retval EFI_SUCCESS Successfully got volume attributes
+
+**/
EFI_STATUS
EFIAPI
FvGetVolumeAttributes (
IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
OUT EFI_FV_ATTRIBUTES *Attributes
)
-/*++
-
-Routine Description:
- Retrieves attributes, insures positive polarity of attribute bits, returns
- resulting attributes in output parameter
-
-Arguments:
- This - Calling context
- Attributes - output buffer which contains attributes
-
-Returns:
- EFI_SUCCESS - Successfully got volume attributes
-
---*/
;
+
+/**
+ Sets current attributes for volume
+
+ @param This Calling context
+ @param Attributes At input, contains attributes to be set. At output
+ contains new value of FV
+
+ @retval EFI_UNSUPPORTED Could not be set.
+
+**/
EFI_STATUS
EFIAPI
FvSetVolumeAttributes (
IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
IN OUT EFI_FV_ATTRIBUTES *Attributes
)
-/*++
-
-Routine Description:
- Sets current attributes for volume
-
-Arguments:
- This - Calling context
- Attributes - At input, contains attributes to be set. At output contains
- new value of FV
-
-Returns:
- EFI_UNSUPPORTED - Could not be set.
---*/
;
+
+/**
+ Given the input key, search for the next matching file in the volume.
+
+ @param This Indicates the calling context.
+ @param Key Key is a pointer to a caller allocated
+ buffer that contains implementation specific
+ data that is used to track where to begin
+ the search for the next file. The size of
+ the buffer must be at least This->KeySize
+ bytes long. To reinitialize the search and
+ begin from the beginning of the firmware
+ volume, the entire buffer must be cleared to
+ zero. Other than clearing the buffer to
+ initiate a new search, the caller must not
+ modify the data in the buffer between calls
+ to GetNextFile().
+ @param FileType FileType is a pointer to a caller allocated
+ EFI_FV_FILETYPE. The GetNextFile() API can
+ filter it's search for files based on the
+ value of *FileType input. A *FileType input
+ of 0 causes GetNextFile() to search for
+ files of all types. If a file is found, the
+ file's type is returned in *FileType.
+ *FileType is not modified if no file is
+ found.
+ @param NameGuid NameGuid is a pointer to a caller allocated
+ EFI_GUID. If a file is found, the file's
+ name is returned in *NameGuid. *NameGuid is
+ not modified if no file is found.
+ @param Attributes Attributes is a pointer to a caller
+ allocated EFI_FV_FILE_ATTRIBUTES. If a file
+ is found, the file's attributes are returned
+ in *Attributes. *Attributes is not modified
+ if no file is found.
+ @param Size Size is a pointer to a caller allocated
+ UINTN. If a file is found, the file's size
+ is returned in *Size. *Size is not modified
+ if no file is found.
+
+ @retval EFI_SUCCESS Successfully find the file.
+ @retval EFI_DEVICE_ERROR Device error.
+ @retval EFI_ACCESS_DENIED Fv could not read.
+ @retval EFI_NOT_FOUND No matching file found.
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+
+**/
EFI_STATUS
EFIAPI
FvGetNextFile (
@@ -102,52 +142,50 @@ FvGetNextFile (
OUT EFI_FV_FILE_ATTRIBUTES *Attributes,
OUT UINTN *Size
)
-/*++
-
-Routine Description:
- Given the input key, search for the next matching file in the volume.
-
-Arguments:
- This - Indicates the calling context.
- FileType - FileType is a pointer to a caller allocated
- EFI_FV_FILETYPE. The GetNextFile() API can filter it's
- search for files based on the value of *FileType input.
- A *FileType input of 0 causes GetNextFile() to search for
- files of all types. If a file is found, the file's type
- is returned in *FileType. *FileType is not modified if
- no file is found.
- Key - Key is a pointer to a caller allocated buffer that
- contains implementation specific data that is used to
- track where to begin the search for the next file.
- The size of the buffer must be at least This->KeySize
- bytes long. To reinitialize the search and begin from
- the beginning of the firmware volume, the entire buffer
- must be cleared to zero. Other than clearing the buffer
- to initiate a new search, the caller must not modify the
- data in the buffer between calls to GetNextFile().
- NameGuid - NameGuid is a pointer to a caller allocated EFI_GUID.
- If a file is found, the file's name is returned in
- *NameGuid. *NameGuid is not modified if no file is
- found.
- Attributes - Attributes is a pointer to a caller allocated
- EFI_FV_FILE_ATTRIBUTES. If a file is found, the file's
- attributes are returned in *Attributes. *Attributes is
- not modified if no file is found.
- Size - Size is a pointer to a caller allocated UINTN.
- If a file is found, the file's size is returned in *Size.
- *Size is not modified if no file is found.
-
-Returns:
- EFI_SUCCESS - Successfully find the file.
- EFI_DEVICE_ERROR - Device error.
- EFI_ACCESS_DENIED - Fv could not read.
- EFI_NOT_FOUND - No matching file found.
- EFI_INVALID_PARAMETER - Invalid parameter
-
---*/
;
+
+/**
+ Locates a file in the firmware volume and
+ copies it to the supplied buffer.
+
+ @param This Indicates the calling context.
+ @param NameGuid Pointer to an EFI_GUID, which is the
+ filename.
+ @param Buffer Buffer is a pointer to pointer to a buffer
+ in which the file or section contents or are
+ returned.
+ @param BufferSize BufferSize is a pointer to caller allocated
+ UINTN. On input *BufferSize indicates the
+ size in bytes of the memory region pointed
+ to by Buffer. On output, *BufferSize
+ contains the number of bytes required to
+ read the file.
+ @param FoundType FoundType is a pointer to a caller allocated
+ EFI_FV_FILETYPE that on successful return
+ from Read() contains the type of file read.
+ This output reflects the file type
+ irrespective of the value of the SectionType
+ input.
+ @param FileAttributes FileAttributes is a pointer to a caller
+ allocated EFI_FV_FILE_ATTRIBUTES. On
+ successful return from Read(),
+ *FileAttributes contains the attributes of
+ the file read.
+ @param AuthenticationStatus AuthenticationStatus is a pointer to a
+ caller allocated UINTN in which the
+ authentication status is returned.
+
+ @retval EFI_SUCCESS Successfully read to memory buffer.
+ @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
+ @retval EFI_NOT_FOUND Not found.
+ @retval EFI_DEVICE_ERROR Device error.
+ @retval EFI_ACCESS_DENIED Could not read.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
+
+**/
EFI_STATUS
EFIAPI
FvReadFile (
@@ -159,46 +197,37 @@ FvReadFile (
OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes,
OUT UINT32 *AuthenticationStatus
)
-/*++
-
-Routine Description:
- Locates a file in the firmware volume and
- copies it to the supplied buffer.
-
-Arguments:
- This - Indicates the calling context.
- NameGuid - Pointer to an EFI_GUID, which is the filename.
- Buffer - Buffer is a pointer to pointer to a buffer in
- which the file or section contents or are returned.
- BufferSize - BufferSize is a pointer to caller allocated
- UINTN. On input *BufferSize indicates the size
- in bytes of the memory region pointed to by
- Buffer. On output, *BufferSize contains the number
- of bytes required to read the file.
- FoundType - FoundType is a pointer to a caller allocated
- EFI_FV_FILETYPE that on successful return from Read()
- contains the type of file read. This output reflects
- the file type irrespective of the value of the
- SectionType input.
- FileAttributes - FileAttributes is a pointer to a caller allocated
- EFI_FV_FILE_ATTRIBUTES. On successful return from
- Read(), *FileAttributes contains the attributes of
- the file read.
- AuthenticationStatus - AuthenticationStatus is a pointer to a caller
- allocated UINTN in which the authentication status
- is returned.
-Returns:
- EFI_SUCCESS - Successfully read to memory buffer.
- EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
- EFI_NOT_FOUND - Not found.
- EFI_DEVICE_ERROR - Device error.
- EFI_ACCESS_DENIED - Could not read.
- EFI_INVALID_PARAMETER - Invalid parameter.
- EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
-
---*/
;
+
+/**
+ Locates a section in a given FFS File and
+ copies it to the supplied buffer (not including section header).
+
+ @param This Indicates the calling context.
+ @param NameGuid Pointer to an EFI_GUID, which is the
+ filename.
+ @param SectionType Indicates the section type to return.
+ @param SectionInstance Indicates which instance of sections with a
+ type of SectionType to return.
+ @param Buffer Buffer is a pointer to pointer to a buffer
+ in which the file or section contents or are
+ returned.
+ @param BufferSize BufferSize is a pointer to caller allocated
+ UINTN.
+ @param AuthenticationStatus AuthenticationStatus is a pointer to a
+ caller allocated UINT32 in which the
+ authentication status is returned.
+
+ @retval EFI_SUCCESS Successfully read the file section into
+ buffer.
+ @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
+ @retval EFI_NOT_FOUND Section not found.
+ @retval EFI_DEVICE_ERROR Device error.
+ @retval EFI_ACCESS_DENIED Could not read.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+
+**/
EFI_STATUS
EFIAPI
FvReadFileSection (
@@ -210,36 +239,30 @@ FvReadFileSection (
IN OUT UINTN *BufferSize,
OUT UINT32 *AuthenticationStatus
)
-/*++
-
- Routine Description:
- Locates a section in a given FFS File and
- copies it to the supplied buffer (not including section header).
-
- Arguments:
- This - Indicates the calling context.
- NameGuid - Pointer to an EFI_GUID, which is the filename.
- SectionType - Indicates the section type to return.
- SectionInstance - Indicates which instance of sections with a type of
- SectionType to return.
- Buffer - Buffer is a pointer to pointer to a buffer in which
- the file or section contents or are returned.
- BufferSize - BufferSize is a pointer to caller allocated UINTN.
- AuthenticationStatus -AuthenticationStatus is a pointer to a caller
- allocated UINT32 in which the authentication status
- is returned.
-
- Returns:
- EFI_SUCCESS - Successfully read the file section into buffer.
- EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
- EFI_NOT_FOUND - Section not found.
- EFI_DEVICE_ERROR - Device error.
- EFI_ACCESS_DENIED - Could not read.
- EFI_INVALID_PARAMETER - Invalid parameter.
-
---*/
;
+
+/**
+ Writes one or more files to the firmware volume.
+
+ @param This Indicates the calling context.
+ @param NumberOfFiles Number of files.
+ @param WritePolicy WritePolicy indicates the level of reliability
+ for the write in the event of a power failure or
+ other system failure during the write operation.
+ @param FileData FileData is an pointer to an array of
+ EFI_FV_WRITE_DATA. Each element of array
+ FileData represents a file to be written.
+
+ @retval EFI_SUCCESS Files successfully written to firmware volume
+ @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
+ @retval EFI_DEVICE_ERROR Device error.
+ @retval EFI_WRITE_PROTECTED Write protected.
+ @retval EFI_NOT_FOUND Not found.
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_UNSUPPORTED This function not supported.
+
+**/
EFI_STATUS
EFIAPI
FvWriteFile (
@@ -248,31 +271,22 @@ FvWriteFile (
IN EFI_FV_WRITE_POLICY WritePolicy,
IN EFI_FV_WRITE_FILE_DATA *FileData
)
-/*++
-
- Routine Description:
- Writes one or more files to the firmware volume.
-
- Arguments:
- This - Indicates the calling context.
- WritePolicy - WritePolicy indicates the level of reliability for
- the write in the event of a power failure or other
- system failure during the write operation.
- FileData - FileData is an pointer to an array of EFI_FV_WRITE_DATA.
- Each element of FileData[] represents a file to be written.
-
- Returns:
- EFI_SUCCESS - Files successfully written to firmware volume
- EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
- EFI_DEVICE_ERROR - Device error.
- EFI_WRITE_PROTECTED - Write protected.
- EFI_NOT_FOUND - Not found.
- EFI_INVALID_PARAMETER - Invalid parameter.
- EFI_UNSUPPORTED - This function not supported.
-
---*/
;
+
+/**
+ Return information of type InformationType for the requested firmware
+ volume.
+
+ @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
+ @param InformationType InformationType for requested.
+ @param BufferSize On input, size of Buffer.On output, the amount of data
+ returned in Buffer.
+ @param Buffer A poniter to the data buffer to return.
+
+ @retval EFI_SUCCESS Successfully got volume Information.
+
+**/
EFI_STATUS
EFIAPI
FvGetVolumeInfo (
@@ -281,25 +295,23 @@ FvGetVolumeInfo (
IN OUT UINTN *BufferSize,
OUT VOID *Buffer
)
-/*++
-
-Routine Description:
- Return information of type InformationType for the requested firmware
- volume.
-
-Arguments:
- This - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
- InformationType - InformationType for requested.
- BufferSize - On input, size of Buffer.On output, the amount of
- data returned in Buffer.
- Buffer - A poniter to the data buffer to return.
-Returns:
- EFI_SUCCESS - Successfully got volume Information.
-
---*/
;
+
+/**
+ Set information of type InformationType for the requested firmware
+ volume.
+
+ @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
+ @param InformationType InformationType for requested.
+ @param BufferSize On input, size of Buffer.On output, the amount of data
+ returned in Buffer.
+ @param Buffer A poniter to the data buffer to return.
+
+ @retval EFI_SUCCESS Successfully set volume Information.
+
+**/
EFI_STATUS
EFIAPI
FvSetVolumeInfo (
@@ -308,22 +320,6 @@ FvSetVolumeInfo (
IN UINTN BufferSize,
IN CONST VOID *Buffer
)
-/*++
-
-Routine Description:
- Set information of type InformationType for the requested firmware
- volume.
-
-Arguments:
- This - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
- InformationType - InformationType for requested.
- BufferSize - On input, size of Buffer.On output, the amount of
- data returned in Buffer.
- Buffer - A poniter to the data buffer to return.
-Returns:
- EFI_SUCCESS - Successfully set volume Information.
-
---*/
;
//
@@ -338,175 +334,153 @@ typedef enum {
} EFI_CHECKSUM_TYPE;
+
+/**
+ Check if a block of buffer is erased.
+
+ @param ErasePolarity Erase polarity attribute of the firmware volume
+ @param InBuffer The buffer to be checked
+ @param BufferSize Size of the buffer in bytes
+
+ @retval TRUE The block of buffer is erased
+ @retval FALSE The block of buffer is not erased
+
+**/
BOOLEAN
IsBufferErased (
IN UINT8 ErasePolarity,
IN VOID *Buffer,
IN UINTN BufferSize
)
-/*++
-
-Routine Description:
- Check if a block of buffer is erased
-
-Arguments:
- ErasePolarity - Erase polarity attribute of the firmware volume
- Buffer - The buffer to be checked
- BufferSize - Size of the buffer in bytes
-
-Returns:
- TRUE - The block of buffer is erased
- FALSE - The block of buffer is not erased
-
---*/
;
+
+/**
+ Get the FFS file state by checking the highest bit set in the header's state field.
+
+ @param ErasePolarity Erase polarity attribute of the firmware volume
+ @param FfsHeader Points to the FFS file header
+
+ @return FFS File state
+
+**/
EFI_FFS_FILE_STATE
GetFileState (
IN UINT8 ErasePolarity,
IN EFI_FFS_FILE_HEADER *FfsHeader
)
-/*++
-
-Routine Description:
- Get the FFS file state by checking the highest bit set in the header's state field
-
-Arguments:
- ErasePolarity - Erase polarity attribute of the firmware volume
- FfsHeader - Points to the FFS file header
-
-Returns:
- FFS File state
-
---*/
;
+
+/**
+ Set the FFS file state.
+
+ @param State The state to be set.
+ @param FfsHeader Points to the FFS file header
+
+ @return None.
+
+**/
VOID
SetFileState (
IN UINT8 State,
IN EFI_FFS_FILE_HEADER *FfsHeader
)
-/*++
-
-Routine Description:
- Set the FFS file state.
-
-Arguments:
- State - The state to be set.
- FfsHeader - Points to the FFS file header
-
-Returns:
- None.
-
---*/
;
+
+/**
+ Verify checksum of the firmware volume header.
+
+ @param FvHeader Points to the firmware volume header to be checked
+
+ @retval TRUE Checksum verification passed
+ @retval FALSE Checksum verification failed
+
+**/
BOOLEAN
VerifyFvHeaderChecksum (
IN EFI_FIRMWARE_VOLUME_HEADER *FvHeader
)
-/*++
-
-Routine Description:
- Verify checksum of the firmware volume header
-
-Arguments:
- FvHeader - Points to the firmware volume header to be checked
-
-Returns:
- TRUE - Checksum verification passed
- FALSE - Checksum verification failed
-
---*/
;
+
+/**
+ Check if it's a valid FFS file header.
+
+ @param ErasePolarity Erase polarity attribute of the firmware volume
+ @param FfsHeader Points to the FFS file header to be checked
+ @param FileState FFS file state to be returned
+
+ @retval TRUE Valid FFS file header
+ @retval FALSE Invalid FFS file header
+
+**/
BOOLEAN
IsValidFfsHeader (
IN UINT8 ErasePolarity,
IN EFI_FFS_FILE_HEADER *FfsHeader,
OUT EFI_FFS_FILE_STATE *FileState
)
-/*++
-
-Routine Description:
- Check if it's a valid FFS file header
-
-Arguments:
- ErasePolarity - Erase polarity attribute of the firmware volume
- FfsHeader - Points to the FFS file header to be checked
- FileState - FFS file state to be returned
-
-Returns:
- TRUE - Valid FFS file header
- FALSE - Invalid FFS file header
-
---*/
;
+
+/**
+ Check if it's a valid FFS file.
+ Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
+
+ @param ErasePolarity Erase polarity attribute of the firmware volume
+ @param FfsHeader Points to the FFS file to be checked
+
+ @retval TRUE Valid FFS file
+ @retval FALSE Invalid FFS file
+
+**/
BOOLEAN
IsValidFfsFile (
IN UINT8 ErasePolarity,
IN EFI_FFS_FILE_HEADER *FfsHeader
)
-/*++
-
-Routine Description:
- Check if it's a valid FFS file.
- Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
-
-Arguments:
- ErasePolarity - Erase polarity attribute of the firmware volume
- FfsHeader - Points to the FFS file to be checked
-
-Returns:
- TRUE - Valid FFS file
- FALSE - Invalid FFS file
-
---*/
;
+
+/**
+ given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and
+ copy the volume header into it.
+
+ @param Fvb The FW_VOL_BLOCK_PROTOCOL instance from which to
+ read the volume header
+ @param FwVolHeader Pointer to pointer to allocated buffer in which
+ the volume header is returned.
+
+ @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.
+ @retval EFI_SUCCESS Successfully read volume header to the allocated
+ buffer.
+
+**/
EFI_STATUS
GetFwVolHeader (
IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL *Fvb,
OUT EFI_FIRMWARE_VOLUME_HEADER **FwVolHeader
)
-/*++
-
-Routine Description:
- given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and
- copy the volume header into it.
-
-Arguments:
- Fvb - The FW_VOL_BLOCK_PROTOCOL instance from which to read the volume
- header
- FwVolHeader - Pointer to pointer to allocated buffer in which the volume
- header is returned.
-
-Returns:
- Status code.
-
---*/
;
+
+/**
+ Check if a FV is consistent and allocate cache
+
+ @param FvDevice pointer to the FvDevice to be checked.
+
+ @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.
+ @retval EFI_SUCCESS FV is consistent and cache is allocated.
+ @retval EFI_VOLUME_CORRUPTED File system is corrupted.
+
+**/
EFI_STATUS
FvCheck (
IN OUT FV_DEVICE *FvDevice
)
-/*++
-
-Routine Description:
- Check if a FV is consistent and allocate cache
-
-Arguments:
- FvDevice - pointer to the FvDevice to be checked.
-
-Returns:
- EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
- EFI_SUCCESS - FV is consistent and cache is allocated.
- EFI_VOLUME_CORRUPTED - File system is corrupted.
-
---*/
;
#endif
diff --git a/MdeModulePkg/Core/Dxe/Gcd/gcd.c b/MdeModulePkg/Core/Dxe/Gcd/gcd.c
index 23477be047..b6a0f1b763 100644
--- a/MdeModulePkg/Core/Dxe/Gcd/gcd.c
+++ b/MdeModulePkg/Core/Dxe/Gcd/gcd.c
@@ -89,86 +89,58 @@ GCD_ATTRIBUTE_CONVERSION_ENTRY mAttributeConversionTable[] = {
{ 0, 0, FALSE }
};
+
+/**
+ Acquire memory lock on mGcdMemorySpaceLock.
+
+**/
VOID
CoreAcquireGcdMemoryLock (
VOID
)
-/*++
-
-Routine Description:
- Acquire memory lock on mGcdMemorySpaceLock
-
-Arguments:
- None
-
-Returns:
- None
-
---*/
{
CoreAcquireLock (&mGcdMemorySpaceLock);
}
+
+/**
+ Release memory lock on mGcdMemorySpaceLock.
+
+**/
VOID
CoreReleaseGcdMemoryLock (
VOID
)
-/*++
-
-Routine Description:
- Release memory lock on mGcdMemorySpaceLock
-
-Arguments:
- None
-
-Returns:
- None
-
---*/
{
CoreReleaseLock (&mGcdMemorySpaceLock);
}
+
+/**
+ Acquire memory lock on mGcdIoSpaceLock.
+
+**/
STATIC
VOID
CoreAcquireGcdIoLock (
VOID
)
-/*++
-
-Routine Description:
- Acquire memory lock on mGcdIoSpaceLock
-
-Arguments:
- None
-
-Returns:
- None
-
---*/
{
CoreAcquireLock (&mGcdIoSpaceLock);
}
+
+/**
+ Release memory lock on mGcdIoSpaceLock.
+
+**/
STATIC
VOID
CoreReleaseGcdIoLock (
VOID
)
-/*++
-
-Routine Description:
- Release memory lock on mGcdIoSpaceLock
-
-Arguments:
- None
-
-Returns:
- None
-
---*/
{
CoreReleaseLock (&mGcdIoSpaceLock);
}
@@ -178,6 +150,19 @@ Returns:
//
// GCD Initialization Worker Functions
//
+
+/**
+ Aligns a value to the specified boundary.
+
+ @param Value 64 bit value to align
+ @param Alignment Log base 2 of the boundary to align Value to
+ @param RoundUp TRUE if Value is to be rounded up to the nearest
+ aligned boundary. FALSE is Value is to be
+ rounded down to the nearest aligned boundary.
+
+ @return A 64 bit value is the aligned to the value nearest Value with an alignment by Alignment.
+
+**/
STATIC
UINT64
AlignValue (
@@ -185,24 +170,6 @@ AlignValue (
IN UINTN Alignment,
IN BOOLEAN RoundUp
)
-/*++
-
-Routine Description:
-
- Aligns a value to the specified boundary.
-
-Arguments:
-
- Value - 64 bit value to align
- Alignment - Log base 2 of the boundary to align Value to
- RoundUp - TRUE if Value is to be rounded up to the nearest aligned boundary.
- FALSE is Value is to be rounded down to the nearest aligned boundary.
-
-Returns:
-
- A 64 bit value is the aligned to the value nearest Value with an alignment by Alignment.
-
---*/
{
UINT64 AlignmentMask;
@@ -213,50 +180,38 @@ Returns:
return Value & (~AlignmentMask);
}
+
+/**
+ Aligns address to the page boundary.
+
+ @param Value 64 bit address to align
+
+ @return A 64 bit value is the aligned to the value nearest Value with an alignment by Alignment.
+
+**/
STATIC
UINT64
PageAlignAddress (
IN UINT64 Value
)
-/*++
-
-Routine Description:
-
- Aligns address to the page boundary.
-
-Arguments:
-
- Value - 64 bit address to align
-
-Returns:
-
- A 64 bit value is the aligned to the value nearest Value with an alignment by Alignment.
-
---*/
{
return AlignValue (Value, EFI_PAGE_SHIFT, TRUE);
}
+
+/**
+ Aligns length to the page boundary.
+
+ @param Value 64 bit length to align
+
+ @return A 64 bit value is the aligned to the value nearest Value with an alignment by Alignment.
+
+**/
STATIC
UINT64
PageAlignLength (
IN UINT64 Value
)
-/*++
-
-Routine Description:
-
- Aligns length to the page boundary.
-
-Arguments:
-
- Value - 64 bit length to align
-
-Returns:
-
- A 64 bit value is the aligned to the value nearest Value with an alignment by Alignment.
-
---*/
{
return AlignValue (Value, EFI_PAGE_SHIFT, FALSE);
}
@@ -264,29 +219,23 @@ Returns:
//
// GCD Memory Space Worker Functions
//
+
+/**
+ Allocate pool for two entries.
+
+ @param TopEntry An entry of GCD map
+ @param BottomEntry An entry of GCD map
+
+ @retval EFI_OUT_OF_RESOURCES No enough buffer to be allocated.
+ @retval EFI_SUCCESS Both entries successfully allocated.
+
+**/
STATIC
EFI_STATUS
CoreAllocateGcdMapEntry (
IN OUT EFI_GCD_MAP_ENTRY **TopEntry,
IN OUT EFI_GCD_MAP_ENTRY **BottomEntry
)
-/*++
-
-Routine Description:
-
- Allocate pool for two entries.
-
-Arguments:
-
- TopEntry - An entry of GCD map
- BottomEntry - An entry of GCD map
-
-Returns:
-
- EFI_OUT_OF_RESOURCES - No enough buffer to be allocated.
- EFI_SUCCESS - Both entries successfully allocated.
-
---*/
{
*TopEntry = CoreAllocateZeroBootServicesPool (sizeof (EFI_GCD_MAP_ENTRY));
if (*TopEntry == NULL) {
@@ -302,6 +251,21 @@ Returns:
return EFI_SUCCESS;
}
+
+/**
+ Internal function. Inserts a new descriptor into a sorted list
+
+ @param Link The linked list to insert the range BaseAddress
+ and Length into
+ @param Entry A pointer to the entry that is inserted
+ @param BaseAddress The base address of the new range
+ @param Length The length of the new range in bytes
+ @param TopEntry Top pad entry to insert if needed.
+ @param BottomEntry Bottom pad entry to insert if needed.
+
+ @retval EFI_SUCCESS The new range was inserted into the linked list
+
+**/
STATIC
EFI_STATUS
CoreInsertGcdMapEntry (
@@ -312,31 +276,6 @@ CoreInsertGcdMapEntry (
IN EFI_GCD_MAP_ENTRY *TopEntry,
IN EFI_GCD_MAP_ENTRY *BottomEntry
)
-/*++
-
-Routine Description:
-
- Internal function. Inserts a new descriptor into a sorted list
-
-Arguments:
-
- Link - The linked list to insert the range BaseAddress and Length into
-
- Entry - A pointer to the entry that is inserted
-
- BaseAddress - The base address of the new range
-
- Length - The length of the new range in bytes
-
- TopEntry - Top pad entry to insert if needed.
-
- BottomEntry - Bottom pad entry to insert if needed.
-
-Returns:
-
- EFI_SUCCESS - The new range was inserted into the linked list
-
---*/
{
ASSERT (Length != 0);
ASSERT (TopEntry->Signature == 0);
@@ -359,6 +298,19 @@ Returns:
return EFI_SUCCESS;
}
+
+/**
+ Merge the Gcd region specified by Link and its adjacent entry
+
+ @param Link Specify the entry to be merged (with its
+ adjacent entry).
+ @param Forward Direction (forward or backward).
+ @param Map Boundary.
+
+ @retval EFI_SUCCESS Successfully returned.
+ @retval EFI_UNSUPPORTED These adjacent regions could not merge.
+
+**/
STATIC
EFI_STATUS
CoreMergeGcdMapEntry (
@@ -366,27 +318,6 @@ CoreMergeGcdMapEntry (
IN BOOLEAN Forward,
IN LIST_ENTRY *Map
)
-/*++
-
-Routine Description:
-
- Merge the Gcd region specified by Link and its adjacent entry
-
-Arguments:
-
- Link - Specify the entry to be merged (with its adjacent entry).
-
- Forward - Direction (forward or backward).
-
- Map - Boundary.
-
-Returns:
-
- EFI_SUCCESS - Successfully returned.
-
- EFI_UNSUPPORTED - These adjacent regions could not merge.
-
---*/
{
LIST_ENTRY *AdjacentLink;
EFI_GCD_MAP_ENTRY *Entry;
@@ -441,6 +372,19 @@ Returns:
return EFI_SUCCESS;
}
+
+/**
+ Merge adjacent entries on total chain.
+
+ @param TopEntry Top entry of GCD map.
+ @param BottomEntry Bottom entry of GCD map.
+ @param StartLink Start link of the list for this loop.
+ @param EndLink End link of the list for this loop.
+ @param Map Boundary.
+
+ @retval EFI_SUCCESS GCD map successfully cleaned up.
+
+**/
STATIC
EFI_STATUS
CoreCleanupGcdMapEntry (
@@ -450,29 +394,6 @@ CoreCleanupGcdMapEntry (
IN LIST_ENTRY *EndLink,
IN LIST_ENTRY *Map
)
-/*++
-
-Routine Description:
-
- Merge adjacent entries on total chain.
-
-Arguments:
-
- TopEntry - Top entry of GCD map.
-
- BottomEntry - Bottom entry of GCD map.
-
- StartLink - Start link of the list for this loop.
-
- EndLink - End link of the list for this loop.
-
- Map - Boundary.
-
-Returns:
-
- EFI_SUCCESS - GCD map successfully cleaned up.
-
---*/
{
LIST_ENTRY *Link;
@@ -493,6 +414,22 @@ Returns:
return EFI_SUCCESS;
}
+
+/**
+ Search a segment of memory space in GCD map. The result is a range of GCD entry list.
+
+ @param BaseAddress The start address of the segment.
+ @param Length The length of the segment.
+ @param StartLink The first GCD entry involves this segment of
+ memory space.
+ @param EndLink The first GCD entry involves this segment of
+ memory space.
+ @param Map Points to the start entry to search.
+
+ @retval EFI_SUCCESS Successfully found the entry.
+ @retval EFI_NOT_FOUND Not found.
+
+**/
STATIC
EFI_STATUS
CoreSearchGcdMapEntry (
@@ -502,31 +439,6 @@ CoreSearchGcdMapEntry (
OUT LIST_ENTRY **EndLink,
IN LIST_ENTRY *Map
)
-/*++
-
-Routine Description:
-
- Search a segment of memory space in GCD map. The result is a range of GCD entry list.
-
-Arguments:
-
- BaseAddress - The start address of the segment.
-
- Length - The length of the segment.
-
- StartLink - The first GCD entry involves this segment of memory space.
-
- EndLink - The first GCD entry involves this segment of memory space.
-
- Map - Points to the start entry to search.
-
-Returns:
-
- EFI_SUCCESS - Successfully found the entry.
-
- EFI_NOT_FOUND - Not found.
-
---*/
{
LIST_ENTRY *Link;
EFI_GCD_MAP_ENTRY *Entry;
@@ -554,26 +466,20 @@ Returns:
return EFI_NOT_FOUND;
}
+
+/**
+ Count the amount of GCD map entries.
+
+ @param Map Points to the start entry to do the count loop.
+
+ @return The count.
+
+**/
STATIC
UINTN
CoreCountGcdMapEntry (
IN LIST_ENTRY *Map
)
-/*++
-
-Routine Description:
-
- Count the amount of GCD map entries.
-
-Arguments:
-
- Map - Points to the start entry to do the count loop.
-
-Returns:
-
- The count.
-
---*/
{
UINTN Count;
LIST_ENTRY *Link;
@@ -588,26 +494,20 @@ Returns:
}
+
+/**
+ Return the memory attribute specified by Attributes
+
+ @param Attributes A num with some attribute bits on.
+
+ @return The enum value of memory attribute.
+
+**/
STATIC
UINT64
ConverToCpuArchAttributes (
UINT64 Attributes
)
-/*++
-
-Routine Description:
-
- Return the memory attribute specified by Attributes
-
-Arguments:
-
- Attributes - A num with some attribute bits on.
-
-Returns:
-
- The enum value of memory attribute.
-
---*/
{
if ( (Attributes & EFI_MEMORY_UC) == EFI_MEMORY_UC) {
return EFI_MEMORY_UC;
@@ -633,6 +533,30 @@ Returns:
}
+
+/**
+ Do operation on a segment of memory space specified (add, free, remove, change attribute ...).
+
+ @param Operation The type of the operation
+ @param GcdMemoryType Additional information for the operation
+ @param GcdIoType Additional information for the operation
+ @param BaseAddress Start address of the segment
+ @param Length length of the segment
+ @param Capabilities The alterable attributes of a newly added entry
+ @param Attributes The attributes needs to be set
+
+ @retval EFI_INVALID_PARAMETER Length is 0 or address (length) not aligned when
+ setting attribute.
+ @retval EFI_SUCCESS Action successfully done.
+ @retval EFI_UNSUPPORTED Could not find the proper descriptor on this
+ segment or set an upsupported attribute.
+ @retval EFI_ACCESS_DENIED Operate on an space non-exist or is used for an
+ image.
+ @retval EFI_NOT_FOUND Free a non-using space or remove a non-exist
+ space, and so on.
+ @retval EFI_OUT_OF_RESOURCES No buffer could be allocated.
+
+**/
STATIC
EFI_STATUS
CoreConvertSpace (
@@ -644,46 +568,6 @@ CoreConvertSpace (
IN UINT64 Capabilities,
IN UINT64 Attributes
)
-/*++
-
-Routine Description:
-
- Do operation on a segment of memory space specified (add, free, remove, change attribute ...).
-
-Arguments:
-
- Operation - The type of the operation
-
- GcdMemoryType - Additional information for the operation
-
- GcdIoType - Additional information for the operation
-
- BaseAddress - Start address of the segment
-
- Length - length of the segment
-
- Capabilities - The alterable attributes of a newly added entry
-
- Attributes - The attributes needs to be set
-
-Returns:
-
- EFI_INVALID_PARAMETER - Length is 0 or address (length) not aligned when setting attribute.
-
- EFI_SUCCESS - Action successfully done.
-
- EFI_UNSUPPORTED - Could not find the proper descriptor on this segment or
- set an upsupported attribute.
-
- EFI_ACCESS_DENIED - Operate on an space non-exist or is used for an image.
-
- EFI_NOT_FOUND - Free a non-using space or remove a non-exist space, and so on.
-
- EFI_OUT_OF_RESOURCES - No buffer could be allocated.
-
-Returns:
-
---*/
{
EFI_STATUS Status;
LIST_ENTRY *Map;
@@ -901,6 +785,22 @@ Done:
return Status;
}
+
+/**
+ Check whether an entry could be used to allocate space.
+
+ @param Operation Allocate memory or IO
+ @param Entry The entry to be tested
+ @param GcdMemoryType The desired memory type
+ @param GcdIoType The desired IO type
+
+ @retval EFI_NOT_FOUND The memory type does not match or there's an
+ image handle on the entry.
+ @retval EFI_UNSUPPORTED The operation unsupported.
+ @retval EFI_SUCCESS It's ok for this entry to be used to allocate
+ space.
+
+**/
STATIC
EFI_STATUS
CoreAllocateSpaceCheckEntry (
@@ -909,31 +809,6 @@ CoreAllocateSpaceCheckEntry (
IN EFI_GCD_MEMORY_TYPE GcdMemoryType,
IN EFI_GCD_IO_TYPE GcdIoType
)
-/*++
-
-Routine Description:
-
- Check whether an entry could be used to allocate space.
-
-Arguments:
-
- Operation - Allocate memory or IO
-
- Entry - The entry to be tested
-
- GcdMemoryType - The desired memory type
-
- GcdIoType - The desired IO type
-
-Returns:
-
- EFI_NOT_FOUND - The memory type does not match or there's an image handle on the entry.
-
- EFI_UNSUPPORTED - The operation unsupported.
-
- EFI_SUCCESS - It's ok for this entry to be used to allocate space.
-
---*/
{
if (Entry->ImageHandle != NULL) {
return EFI_NOT_FOUND;
@@ -955,6 +830,25 @@ Returns:
return EFI_SUCCESS;
}
+
+/**
+ Allocate space on specified address and length.
+
+ @param Operation The type of operation (memory or IO)
+ @param GcdAllocateType The type of allocate operation
+ @param GcdMemoryType The desired memory type
+ @param GcdIoType The desired IO type
+ @param Alignment Align with 2^Alignment
+ @param Length Length to allocate
+ @param BaseAddress Base address to allocate
+ @param ImageHandle The image handle consume the allocated space.
+ @param DeviceHandle The device handle consume the allocated space.
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_NOT_FOUND No descriptor for the desired space exists.
+ @retval EFI_SUCCESS Space successfully allocated.
+
+**/
STATIC
EFI_STATUS
CoreAllocateSpace (
@@ -968,41 +862,6 @@ CoreAllocateSpace (
IN EFI_HANDLE ImageHandle,
IN EFI_HANDLE DeviceHandle OPTIONAL
)
-/*++
-
-Routine Description:
-
- Allocate space on specified address and length.
-
-Arguments:
-
- Operation - The type of operation (memory or IO)
-
- GcdAllocateType - The type of allocate operation
-
- GcdMemoryType - The desired memory type
-
- GcdIoType - The desired IO type
-
- Alignment - Align with 2^Alignment
-
- Length - Length to allocate
-
- BaseAddress - Base address to allocate
-
- ImageHandle - The image handle consume the allocated space.
-
- DeviceHandle - The device handle consume the allocated space.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter.
-
- EFI_NOT_FOUND - No descriptor for the desired space exists.
-
- EFI_SUCCESS - Space successfully allocated.
-
---*/
{
EFI_STATUS Status;
EFI_PHYSICAL_ADDRESS AlignmentMask;
@@ -1224,6 +1083,19 @@ Done:
return Status;
}
+
+/**
+ Add a segment of memory to GCD map.
+
+ @param GcdMemoryType Memory type of the segment.
+ @param BaseAddress Base address of the segment.
+ @param Length Length of the segment.
+ @param Capabilities alterable attributes of the segment.
+
+ @retval EFI_INVALID_PARAMETER Invalid parameters.
+ @retval EFI_SUCCESS Successfully add a segment of memory space.
+
+**/
STATIC
EFI_STATUS
CoreInternalAddMemorySpace (
@@ -1232,29 +1104,6 @@ CoreInternalAddMemorySpace (
IN UINT64 Length,
IN UINT64 Capabilities
)
-/*++
-
-Routine Description:
-
- Add a segment of memory to GCD map.
-
-Arguments:
-
- GcdMemoryType - Memory type of the segment.
-
- BaseAddress - Base address of the segment.
-
- Length - Length of the segment.
-
- Capabilities - alterable attributes of the segment.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameters.
-
- EFI_SUCCESS - Successfully add a segment of memory space.
-
---*/
{
//
// Make sure parameters are valid
@@ -1269,6 +1118,24 @@ Returns:
//
// GCD Core Services
//
+
+/**
+ Allocates nonexistent memory, reserved memory, system memory, or memorymapped
+ I/O resources from the global coherency domain of the processor.
+
+ @param GcdAllocateType The type of allocate operation
+ @param GcdMemoryType The desired memory type
+ @param Alignment Align with 2^Alignment
+ @param Length Length to allocate
+ @param BaseAddress Base address to allocate
+ @param ImageHandle The image handle consume the allocated space.
+ @param DeviceHandle The device handle consume the allocated space.
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_NOT_FOUND No descriptor contains the desired space.
+ @retval EFI_SUCCESS Memory space successfully allocated.
+
+**/
EFI_STATUS
CoreAllocateMemorySpace (
IN EFI_GCD_ALLOCATE_TYPE GcdAllocateType,
@@ -1279,38 +1146,6 @@ CoreAllocateMemorySpace (
IN EFI_HANDLE ImageHandle,
IN EFI_HANDLE DeviceHandle OPTIONAL
)
-/*++
-
-Routine Description:
-
- Allocates nonexistent memory, reserved memory, system memory, or memorymapped
-I/O resources from the global coherency domain of the processor.
-
-Arguments:
-
- GcdAllocateType - The type of allocate operation
-
- GcdMemoryType - The desired memory type
-
- Alignment - Align with 2^Alignment
-
- Length - Length to allocate
-
- BaseAddress - Base address to allocate
-
- ImageHandle - The image handle consume the allocated space.
-
- DeviceHandle - The device handle consume the allocated space.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter.
-
- EFI_NOT_FOUND - No descriptor contains the desired space.
-
- EFI_SUCCESS - Memory space successfully allocated.
-
---*/
{
return CoreAllocateSpace (
GCD_ALLOCATE_MEMORY_OPERATION,
@@ -1325,6 +1160,19 @@ Returns:
);
}
+
+/**
+ Adds reserved memory, system memory, or memory-mapped I/O resources to the
+ global coherency domain of the processor.
+
+ @param GcdMemoryType Memory type of the memory space.
+ @param BaseAddress Base address of the memory space.
+ @param Length Length of the memory space.
+ @param Capabilities alterable attributes of the memory space.
+
+ @retval EFI_SUCCESS Merged this memory space into GCD map.
+
+**/
EFI_STATUS
CoreAddMemorySpace (
IN EFI_GCD_MEMORY_TYPE GcdMemoryType,
@@ -1332,28 +1180,6 @@ CoreAddMemorySpace (
IN UINT64 Length,
IN UINT64 Capabilities
)
-/*++
-
-Routine Description:
-
- Adds reserved memory, system memory, or memory-mapped I/O resources to the
-global coherency domain of the processor.
-
-Arguments:
-
- GcdMemoryType - Memory type of the memory space.
-
- BaseAddress - Base address of the memory space.
-
- Length - Length of the memory space.
-
- Capabilities - alterable attributes of the memory space.
-
-Returns:
-
- EFI_SUCCESS - Merged this memory space into GCD map.
-
---*/
{
EFI_STATUS Status;
EFI_PHYSICAL_ADDRESS PageBaseAddress;
@@ -1409,83 +1235,60 @@ Returns:
return Status;
}
+
+/**
+ Frees nonexistent memory, reserved memory, system memory, or memory-mapped
+ I/O resources from the global coherency domain of the processor.
+
+ @param BaseAddress Base address of the memory space.
+ @param Length Length of the memory space.
+
+ @retval EFI_SUCCESS Space successfully freed.
+
+**/
EFI_STATUS
CoreFreeMemorySpace (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
IN UINT64 Length
)
-/*++
-
-Routine Description:
-
- Frees nonexistent memory, reserved memory, system memory, or memory-mapped
-I/O resources from the global coherency domain of the processor.
-
-Arguments:
-
- BaseAddress - Base address of the memory space.
-
- Length - Length of the memory space.
-
-Returns:
-
- EFI_SUCCESS - Space successfully freed.
-
---*/
{
return CoreConvertSpace (GCD_FREE_MEMORY_OPERATION, (EFI_GCD_MEMORY_TYPE) 0, (EFI_GCD_IO_TYPE) 0, BaseAddress, Length, 0, 0);
}
+
+/**
+ Removes reserved memory, system memory, or memory-mapped I/O resources from
+ the global coherency domain of the processor.
+
+ @param BaseAddress Base address of the memory space.
+ @param Length Length of the memory space.
+
+ @retval EFI_SUCCESS Successfully remove a segment of memory space.
+
+**/
EFI_STATUS
CoreRemoveMemorySpace (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
IN UINT64 Length
)
-/*++
-
-Routine Description:
-
- Removes reserved memory, system memory, or memory-mapped I/O resources from
-the global coherency domain of the processor.
-
-Arguments:
-
- BaseAddress - Base address of the memory space.
-
- Length - Length of the memory space.
-
-Returns:
-
- EFI_SUCCESS - Successfully remove a segment of memory space.
-
---*/
{
return CoreConvertSpace (GCD_REMOVE_MEMORY_OPERATION, (EFI_GCD_MEMORY_TYPE) 0, (EFI_GCD_IO_TYPE) 0, BaseAddress, Length, 0, 0);
}
+
+/**
+ Build a memory descriptor according to an entry.
+
+ @param Descriptor The descriptor to be built
+ @param Entry According to this entry
+
+**/
STATIC
VOID
BuildMemoryDescriptor (
IN OUT EFI_GCD_MEMORY_SPACE_DESCRIPTOR *Descriptor,
IN EFI_GCD_MAP_ENTRY *Entry
)
-/*++
-
-Routine Description:
-
- Build a memory descriptor according to an entry.
-
-Arguments:
-
- Descriptor - The descriptor to be built
-
- Entry - According to this entry
-
-Returns:
-
- None
-
---*/
{
Descriptor->BaseAddress = Entry->BaseAddress;
Descriptor->Length = Entry->EndAddress - Entry->BaseAddress + 1;
@@ -1496,30 +1299,22 @@ Returns:
Descriptor->DeviceHandle = Entry->DeviceHandle;
}
+
+/**
+ Retrieves the descriptor for a memory region containing a specified address.
+
+ @param BaseAddress Specified start address
+ @param Descriptor Specified length
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_SUCCESS Successfully get memory space descriptor.
+
+**/
EFI_STATUS
CoreGetMemorySpaceDescriptor (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
OUT EFI_GCD_MEMORY_SPACE_DESCRIPTOR *Descriptor
)
-/*++
-
-Routine Description:
-
- Retrieves the descriptor for a memory region containing a specified address.
-
-Arguments:
-
- BaseAddress - Specified start address
-
- Descriptor - Specified length
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_SUCCESS - Successfully get memory space descriptor.
-
---*/
{
EFI_STATUS Status;
LIST_ENTRY *StartLink;
@@ -1554,63 +1349,47 @@ Returns:
return Status;
}
+
+/**
+ Modifies the attributes for a memory region in the global coherency domain of the
+ processor.
+
+ @param BaseAddress Specified start address
+ @param Length Specified length
+ @param Attributes Specified attributes
+
+ @retval EFI_SUCCESS Successfully set attribute of a segment of
+ memory space.
+
+**/
EFI_STATUS
CoreSetMemorySpaceAttributes (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
IN UINT64 Length,
IN UINT64 Attributes
)
-/*++
-
-Routine Description:
-
- Modifies the attributes for a memory region in the global coherency domain of the
-processor.
-
-Arguments:
-
- BaseAddress - Specified start address
-
- Length - Specified length
-
- Attributes - Specified attributes
-
-Returns:
-
- EFI_SUCCESS - Successfully set attribute of a segment of memory space.
-
---*/
{
return CoreConvertSpace (GCD_SET_ATTRIBUTES_MEMORY_OPERATION, (EFI_GCD_MEMORY_TYPE) 0, (EFI_GCD_IO_TYPE) 0, BaseAddress, Length, 0, Attributes);
}
+
+/**
+ Returns a map of the memory resources in the global coherency domain of the
+ processor.
+
+ @param NumberOfDescriptors Number of descriptors.
+ @param MemorySpaceMap Descriptor array
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
+ @retval EFI_SUCCESS Successfully get memory space map.
+
+**/
EFI_STATUS
CoreGetMemorySpaceMap (
OUT UINTN *NumberOfDescriptors,
OUT EFI_GCD_MEMORY_SPACE_DESCRIPTOR **MemorySpaceMap
)
-/*++
-
-Routine Description:
-
- Returns a map of the memory resources in the global coherency domain of the
-processor.
-
-Arguments:
-
- NumberOfDescriptors - Number of descriptors.
-
- MemorySpaceMap - Descriptor array
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_OUT_OF_RESOURCES - No enough buffer to allocate
-
- EFI_SUCCESS - Successfully get memory space map.
-
---*/
{
EFI_STATUS Status;
LIST_ENTRY *Link;
@@ -1661,32 +1440,24 @@ Done:
return Status;
}
+
+/**
+ Adds reserved I/O or I/O resources to the global coherency domain of the processor.
+
+ @param GcdIoType IO type of the segment.
+ @param BaseAddress Base address of the segment.
+ @param Length Length of the segment.
+
+ @retval EFI_SUCCESS Merged this segment into GCD map.
+ @retval EFI_INVALID_PARAMETER Parameter not valid
+
+**/
EFI_STATUS
CoreAddIoSpace (
IN EFI_GCD_IO_TYPE GcdIoType,
IN EFI_PHYSICAL_ADDRESS BaseAddress,
IN UINT64 Length
)
-/*++
-
-Routine Description:
-
- Adds reserved I/O or I/O resources to the global coherency domain of the processor.
-
-Arguments:
-
- GcdIoType - IO type of the segment.
-
- BaseAddress - Base address of the segment.
-
- Length - Length of the segment.
-
-Returns:
-
- EFI_SUCCESS - Merged this segment into GCD map.
- EFI_INVALID_PARAMETER - Parameter not valid
-
---*/
{
//
// Make sure parameters are valid
@@ -1697,6 +1468,24 @@ Returns:
return CoreConvertSpace (GCD_ADD_IO_OPERATION, (EFI_GCD_MEMORY_TYPE) 0, GcdIoType, BaseAddress, Length, 0, 0);
}
+
+/**
+ Allocates nonexistent I/O, reserved I/O, or I/O resources from the global coherency
+ domain of the processor.
+
+ @param GcdAllocateType The type of allocate operation
+ @param GcdIoType The desired IO type
+ @param Alignment Align with 2^Alignment
+ @param Length Length to allocate
+ @param BaseAddress Base address to allocate
+ @param ImageHandle The image handle consume the allocated space.
+ @param DeviceHandle The device handle consume the allocated space.
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter.
+ @retval EFI_NOT_FOUND No descriptor contains the desired space.
+ @retval EFI_SUCCESS IO space successfully allocated.
+
+**/
EFI_STATUS
CoreAllocateIoSpace (
IN EFI_GCD_ALLOCATE_TYPE GcdAllocateType,
@@ -1707,38 +1496,6 @@ CoreAllocateIoSpace (
IN EFI_HANDLE ImageHandle,
IN EFI_HANDLE DeviceHandle OPTIONAL
)
-/*++
-
-Routine Description:
-
- Allocates nonexistent I/O, reserved I/O, or I/O resources from the global coherency
-domain of the processor.
-
-Arguments:
-
- GcdAllocateType - The type of allocate operation
-
- GcdIoType - The desired IO type
-
- Alignment - Align with 2^Alignment
-
- Length - Length to allocate
-
- BaseAddress - Base address to allocate
-
- ImageHandle - The image handle consume the allocated space.
-
- DeviceHandle - The device handle consume the allocated space.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter.
-
- EFI_NOT_FOUND - No descriptor contains the desired space.
-
- EFI_SUCCESS - IO space successfully allocated.
-
---*/
{
return CoreAllocateSpace (
GCD_ALLOCATE_IO_OPERATION,
@@ -1753,83 +1510,60 @@ Returns:
);
}
+
+/**
+ Frees nonexistent I/O, reserved I/O, or I/O resources from the global coherency
+ domain of the processor.
+
+ @param BaseAddress Base address of the segment.
+ @param Length Length of the segment.
+
+ @retval EFI_SUCCESS Space successfully freed.
+
+**/
EFI_STATUS
CoreFreeIoSpace (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
IN UINT64 Length
)
-/*++
-
-Routine Description:
-
- Frees nonexistent I/O, reserved I/O, or I/O resources from the global coherency
-domain of the processor.
-
-Arguments:
-
- BaseAddress - Base address of the segment.
-
- Length - Length of the segment.
-
-Returns:
-
- EFI_SUCCESS - Space successfully freed.
-
---*/
{
return CoreConvertSpace (GCD_FREE_IO_OPERATION, (EFI_GCD_MEMORY_TYPE) 0, (EFI_GCD_IO_TYPE) 0, BaseAddress, Length, 0, 0);
}
+
+/**
+ Removes reserved I/O or I/O resources from the global coherency domain of the
+ processor.
+
+ @param BaseAddress Base address of the segment.
+ @param Length Length of the segment.
+
+ @retval EFI_SUCCESS Successfully removed a segment of IO space.
+
+**/
EFI_STATUS
CoreRemoveIoSpace (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
IN UINT64 Length
)
-/*++
-
-Routine Description:
-
- Removes reserved I/O or I/O resources from the global coherency domain of the
-processor.
-
-Arguments:
-
- BaseAddress - Base address of the segment.
-
- Length - Length of the segment.
-
-Returns:
-
- EFI_SUCCESS - Successfully removed a segment of IO space.
-
---*/
{
return CoreConvertSpace (GCD_REMOVE_IO_OPERATION, (EFI_GCD_MEMORY_TYPE) 0, (EFI_GCD_IO_TYPE) 0, BaseAddress, Length, 0, 0);
}
+
+/**
+ Build a IO descriptor according to an entry.
+
+ @param Descriptor The descriptor to be built
+ @param Entry According to this entry
+
+**/
STATIC
VOID
BuildIoDescriptor (
IN EFI_GCD_IO_SPACE_DESCRIPTOR *Descriptor,
IN EFI_GCD_MAP_ENTRY *Entry
)
-/*++
-
-Routine Description:
-
- Build a IO descriptor according to an entry.
-
-Arguments:
-
- Descriptor - The descriptor to be built
-
- Entry - According to this entry
-
-Returns:
-
- None
-
---*/
{
Descriptor->BaseAddress = Entry->BaseAddress;
Descriptor->Length = Entry->EndAddress - Entry->BaseAddress + 1;
@@ -1838,30 +1572,22 @@ Returns:
Descriptor->DeviceHandle = Entry->DeviceHandle;
}
+
+/**
+ Retrieves the descriptor for an I/O region containing a specified address.
+
+ @param BaseAddress Specified start address
+ @param Descriptor Specified length
+
+ @retval EFI_INVALID_PARAMETER Descriptor is NULL.
+ @retval EFI_SUCCESS Successfully get the IO space descriptor.
+
+**/
EFI_STATUS
CoreGetIoSpaceDescriptor (
IN EFI_PHYSICAL_ADDRESS BaseAddress,
OUT EFI_GCD_IO_SPACE_DESCRIPTOR *Descriptor
)
-/*++
-
-Routine Description:
-
- Retrieves the descriptor for an I/O region containing a specified address.
-
-Arguments:
-
- BaseAddress - Specified start address
-
- Descriptor - Specified length
-
-Returns:
-
- EFI_INVALID_PARAMETER - Descriptor is NULL.
-
- EFI_SUCCESS - Successfully get the IO space descriptor.
-
---*/
{
EFI_STATUS Status;
LIST_ENTRY *StartLink;
@@ -1896,32 +1622,23 @@ Returns:
return Status;
}
+
+/**
+ Returns a map of the I/O resources in the global coherency domain of the processor.
+
+ @param NumberOfDescriptors Number of descriptors.
+ @param IoSpaceMap Descriptor array
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
+ @retval EFI_SUCCESS Successfully get IO space map.
+
+**/
EFI_STATUS
CoreGetIoSpaceMap (
OUT UINTN *NumberOfDescriptors,
OUT EFI_GCD_IO_SPACE_DESCRIPTOR **IoSpaceMap
)
-/*++
-
-Routine Description:
-
- Returns a map of the I/O resources in the global coherency domain of the processor.
-
-Arguments:
-
- NumberOfDescriptors - Number of descriptors.
-
- IoSpaceMap - Descriptor array
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_OUT_OF_RESOURCES - No enough buffer to allocate
-
- EFI_SUCCESS - Successfully get IO space map.
-
---*/
{
EFI_STATUS Status;
LIST_ENTRY *Link;
@@ -1972,29 +1689,24 @@ Done:
return Status;
}
+
+/**
+ Converts a Resource Descriptor HOB attributes mask to an EFI Memory Descriptor
+ capabilities mask
+
+ @param GcdMemoryType Type of resource in the GCD memory map.
+ @param Attributes The attribute mask in the Resource Descriptor
+ HOB.
+
+ @return The capabilities mask for an EFI Memory Descriptor.
+
+**/
STATIC
UINT64
CoreConvertResourceDescriptorHobAttributesToCapabilities (
EFI_GCD_MEMORY_TYPE GcdMemoryType,
UINT64 Attributes
)
-/*++
-
-Routine Description:
-
- Converts a Resource Descriptor HOB attributes mask to an EFI Memory Descriptor
- capabilities mask
-
-Arguments:
-
- GcdMemoryType - Type of resource in the GCD memory map.
- Attributes - The attribute mask in the Resource Descriptor HOB.
-
-Returns:
-
- The capabilities mask for an EFI Memory Descriptor.
-
---*/
{
UINT64 Capabilities;
GCD_ATTRIBUTE_CONVERSION_ENTRY *Conversion;
@@ -2013,34 +1725,29 @@ Returns:
return Capabilities;
}
-EFI_STATUS
-CoreInitializeMemoryServices (
- IN VOID **HobStart,
- OUT EFI_PHYSICAL_ADDRESS *MemoryBaseAddress,
- OUT UINT64 *MemoryLength
- )
-/*++
-Routine Description:
-
- External function. Initializes the GCD and memory services based on the memory
+/**
+ External function. Initializes the GCD and memory services based on the memory
descriptor HOBs. This function is responsible for priming the GCD map and the
memory map, so memory allocations and resource allocations can be made. The first
part of this function can not depend on any memory services until at least one
memory descriptor is provided to the memory services. Then the memory services
can be used to intialize the GCD map.
-Arguments:
+ @param HobStart The start address of the HOB.
+ @param MemoryBaseAddress Start address of memory region found to init DXE
+ core.
+ @param MemoryLength Length of memory region found to init DXE core.
- HobStart - The start address of the HOB.
- MemoryBaseAddress - Start address of memory region found to init DXE core.
- MemoryLength - Length of memory region found to init DXE core.
+ @retval EFI_SUCCESS Memory services successfully initialized.
-Returns:
-
- EFI_SUCCESS - Memory services successfully initialized.
-
---*/
+**/
+EFI_STATUS
+CoreInitializeMemoryServices (
+ IN VOID **HobStart,
+ OUT EFI_PHYSICAL_ADDRESS *MemoryBaseAddress,
+ OUT UINT64 *MemoryLength
+ )
{
EFI_PEI_HOB_POINTERS Hob;
EFI_MEMORY_TYPE_INFORMATION *EfiMemoryTypeInformation;
@@ -2235,38 +1942,30 @@ Returns:
return EFI_SUCCESS;
}
+
+/**
+ External function. Initializes the GCD and memory services based on the memory
+ descriptor HOBs. This function is responsible for priming the GCD map and the
+ memory map, so memory allocations and resource allocations can be made. The first
+ part of this function can not depend on any memory services until at least one
+ memory descriptor is provided to the memory services. Then the memory services
+ can be used to intialize the GCD map. The HobStart will be relocated to a pool
+ buffer.
+
+ @param HobStart The start address of the HOB
+ @param MemoryBaseAddress Start address of memory region found to init DXE
+ core.
+ @param MemoryLength Length of memory region found to init DXE core.
+
+ @retval EFI_SUCCESS GCD services successfully initialized.
+
+**/
EFI_STATUS
CoreInitializeGcdServices (
IN OUT VOID **HobStart,
IN EFI_PHYSICAL_ADDRESS MemoryBaseAddress,
IN UINT64 MemoryLength
)
-/*++
-
-Routine Description:
-
- External function. Initializes the GCD and memory services based on the memory
- descriptor HOBs. This function is responsible for priming the GCD map and the
- memory map, so memory allocations and resource allocations can be made. The first
- part of this function can not depend on any memory services until at least one
- memory descriptor is provided to the memory services. Then the memory services
- can be used to intialize the GCD map. The HobStart will be relocated to a pool
- buffer.
-
-Arguments:
-
- HobStart - The start address of the HOB
-
- MemoryBaseAddress - Start address of memory region found to init DXE core.
-
- MemoryLength - Length of memory region found to init DXE core.
-
-
-Returns:
-
- EFI_SUCCESS - GCD services successfully initialized.
-
---*/
{
EFI_PEI_HOB_POINTERS Hob;
VOID *NewHobList;
diff --git a/MdeModulePkg/Core/Dxe/Hand/DriverSupport.c b/MdeModulePkg/Core/Dxe/Hand/DriverSupport.c
index 72ebc8e897..09adddfb53 100644
--- a/MdeModulePkg/Core/Dxe/Hand/DriverSupport.c
+++ b/MdeModulePkg/Core/Dxe/Hand/DriverSupport.c
@@ -17,7 +17,28 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
//
// Driver Support Function Prototypes
-//
+//
+/**
+ Connects a controller to a driver.
+
+ @param ControllerHandle Handle of the controller to be
+ connected.
+ @param ContextDriverImageHandles DriverImageHandle A pointer to an
+ ordered list of driver image
+ handles.
+ @param RemainingDevicePath RemainingDevicePath A pointer to
+ the device path that specifies a
+ child of the controller
+ specified by ControllerHandle.
+
+ @retval EFI_SUCCESS One or more drivers were
+ connected to ControllerHandle.
+ @retval EFI_OUT_OF_RESOURCES No enough system resources to
+ complete the request.
+ @retval EFI_NOT_FOUND No drivers were connected to
+ ControllerHandle.
+
+**/
EFI_STATUS
CoreConnectSingleController (
IN EFI_HANDLE ControllerHandle,
@@ -28,6 +49,25 @@ CoreConnectSingleController (
//
// Driver Support Functions
//
+
+/**
+ Connects one or more drivers to a controller.
+
+ @param ControllerHandle Handle of the controller to be
+ connected.
+ @param DriverImageHandle DriverImageHandle A pointer to an
+ ordered list of driver image
+ handles.
+ @param RemainingDevicePath RemainingDevicePath A pointer to
+ the device path that specifies a
+ child of the controller specified
+ by ControllerHandle.
+ @param Recursive Whether the function would be
+ called recursively or not.
+
+ @return Status code.
+
+**/
EFI_STATUS
EFIAPI
CoreConnectController (
@@ -36,28 +76,6 @@ CoreConnectController (
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL,
IN BOOLEAN Recursive
)
-/*++
-
-Routine Description:
-
- Connects one or more drivers to a controller.
-
-Arguments:
-
- ControllerHandle - Handle of the controller to be connected.
-
- DriverImageHandle - DriverImageHandle A pointer to an ordered list of driver image handles.
-
- RemainingDevicePath - RemainingDevicePath A pointer to the device path that specifies a child of the
- controller specified by ControllerHandle.
-
- Recursive - Whether the function would be called recursively or not.
-
-Returns:
-
- Status code.
-
---*/
{
EFI_STATUS Status;
EFI_STATUS ReturnStatus;
@@ -195,6 +213,26 @@ Returns:
return ReturnStatus;
}
+
+/**
+ Add Driver Binding Protocols from Context Driver Image Handles to sorted
+ Driver Binding Protocol list.
+
+ @param DriverBindingHandle Handle of the driver binding
+ protocol.
+ @param NumberOfSortedDriverBindingProtocols Number Of sorted driver binding
+ protocols
+ @param SortedDriverBindingProtocols The sorted protocol list.
+ @param DriverBindingHandleCount Driver Binding Handle Count.
+ @param DriverBindingHandleBuffer The buffer of driver binding
+ protocol to be modified.
+ @param IsImageHandle Indicate whether
+ DriverBindingHandle is an image
+ handle
+
+ @return None.
+
+**/
VOID
AddSortedDriverBindingProtocol (
IN EFI_HANDLE DriverBindingHandle,
@@ -204,32 +242,6 @@ AddSortedDriverBindingProtocol (
IN OUT EFI_HANDLE *DriverBindingHandleBuffer,
IN BOOLEAN IsImageHandle
)
-/*++
-
-Routine Description:
-
- Add Driver Binding Protocols from Context Driver Image Handles to sorted
- Driver Binding Protocol list.
-
-Arguments:
-
- DriverBindingHandle - Handle of the driver binding protocol.
-
- NumberOfSortedDriverBindingProtocols - Number Of sorted driver binding protocols
-
- SortedDriverBindingProtocols - The sorted protocol list.
-
- DriverBindingHandleCount - Driver Binding Handle Count.
-
- DriverBindingHandleBuffer - The buffer of driver binding protocol to be modified.
-
- IsImageHandle - Indicate whether DriverBindingHandle is an image handle
-
-Returns:
-
- None.
-
---*/
{
EFI_STATUS Status;
EFI_DRIVER_BINDING_PROTOCOL *DriverBinding;
@@ -324,32 +336,34 @@ Returns:
}
}
+
+/**
+ Connects a controller to a driver.
+
+ @param ControllerHandle Handle of the controller to be
+ connected.
+ @param ContextDriverImageHandles DriverImageHandle A pointer to an
+ ordered list of driver image
+ handles.
+ @param RemainingDevicePath RemainingDevicePath A pointer to
+ the device path that specifies a
+ child of the controller
+ specified by ControllerHandle.
+
+ @retval EFI_SUCCESS One or more drivers were
+ connected to ControllerHandle.
+ @retval EFI_OUT_OF_RESOURCES No enough system resources to
+ complete the request.
+ @retval EFI_NOT_FOUND No drivers were connected to
+ ControllerHandle.
+
+**/
EFI_STATUS
CoreConnectSingleController (
IN EFI_HANDLE ControllerHandle,
IN EFI_HANDLE *ContextDriverImageHandles OPTIONAL,
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
)
-/*++
-
-Routine Description:
-
- Connects a controller to a driver.
-
-Arguments:
-
- ControllerHandle - Handle of the controller to be connected.
- ContextDriverImageHandles - DriverImageHandle A pointer to an ordered list of driver image handles.
- RemainingDevicePath - RemainingDevicePath A pointer to the device path that specifies a child
- of the controller specified by ControllerHandle.
-
-Returns:
-
- EFI_SUCCESS - One or more drivers were connected to ControllerHandle.
- EFI_OUT_OF_RESOURCES - No enough system resources to complete the request.
- EFI_NOT_FOUND - No drivers were connected to ControllerHandle.
-
---*/
{
EFI_STATUS Status;
UINTN Index;
@@ -610,6 +624,40 @@ Returns:
}
+
+/**
+ Disonnects a controller from a driver
+
+ @param ControllerHandle ControllerHandle The handle of
+ the controller from which
+ driver(s) are to be
+ disconnected.
+ @param DriverImageHandle DriverImageHandle The driver to
+ disconnect from ControllerHandle.
+ @param ChildHandle ChildHandle The handle of the
+ child to destroy.
+
+ @retval EFI_SUCCESS One or more drivers were
+ disconnected from the controller.
+ @retval EFI_SUCCESS On entry, no drivers are managing
+ ControllerHandle.
+ @retval EFI_SUCCESS DriverImageHandle is not NULL,
+ and on entry DriverImageHandle is
+ not managing ControllerHandle.
+ @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid
+ EFI_HANDLE.
+ @retval EFI_INVALID_PARAMETER DriverImageHandle is not NULL,
+ and it is not a valid EFI_HANDLE.
+ @retval EFI_INVALID_PARAMETER ChildHandle is not NULL, and it
+ is not a valid EFI_HANDLE.
+ @retval EFI_OUT_OF_RESOURCES There are not enough resources
+ available to disconnect any
+ drivers from ControllerHandle.
+ @retval EFI_DEVICE_ERROR The controller could not be
+ disconnected because of a device
+ error.
+
+**/
EFI_STATUS
EFIAPI
CoreDisconnectController (
@@ -617,31 +665,6 @@ CoreDisconnectController (
IN EFI_HANDLE DriverImageHandle OPTIONAL,
IN EFI_HANDLE ChildHandle OPTIONAL
)
-/*++
-
-Routine Description:
-
- Disonnects a controller from a driver
-
-Arguments:
-
- ControllerHandle - ControllerHandle The handle of the controller from which driver(s)
- are to be disconnected.
- DriverImageHandle - DriverImageHandle The driver to disconnect from ControllerHandle.
- ChildHandle - ChildHandle The handle of the child to destroy.
-
-Returns:
-
- EFI_SUCCESS - One or more drivers were disconnected from the controller.
- EFI_SUCCESS - On entry, no drivers are managing ControllerHandle.
- EFI_SUCCESS - DriverImageHandle is not NULL, and on entry DriverImageHandle is not managing ControllerHandle.
- EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.
- EFI_INVALID_PARAMETER - DriverImageHandle is not NULL, and it is not a valid EFI_HANDLE.
- EFI_INVALID_PARAMETER - ChildHandle is not NULL, and it is not a valid EFI_HANDLE.
- EFI_OUT_OF_RESOURCES - There are not enough resources available to disconnect any drivers from ControllerHandle.
- EFI_DEVICE_ERROR - The controller could not be disconnected because of a device error.
-
---*/
{
EFI_STATUS Status;
IHANDLE *Handle;
diff --git a/MdeModulePkg/Core/Dxe/Hand/Notify.c b/MdeModulePkg/Core/Dxe/Hand/Notify.c
index 8d64a5c883..7ee81b984e 100644
--- a/MdeModulePkg/Core/Dxe/Hand/Notify.c
+++ b/MdeModulePkg/Core/Dxe/Hand/Notify.c
@@ -15,23 +15,17 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
#include <DxeMain.h>
+
+/**
+ Signal event for every protocol in protocol entry.
+
+ @param ProtEntry Protocol entry
+
+**/
VOID
CoreNotifyProtocolEntry (
IN PROTOCOL_ENTRY *ProtEntry
)
-/*++
-
-Routine Description:
-
- Signal event for every protocol in protocol entry.
-
-Arguments:
-
- ProtEntry - Protocol entry
-
-Returns:
-
---*/
{
PROTOCOL_NOTIFY *ProtNotify;
LIST_ENTRY *Link;
@@ -45,31 +39,23 @@ Returns:
}
+
+/**
+ Removes Protocol from the protocol list (but not the handle list).
+
+ @param Handle The handle to remove protocol on.
+ @param Protocol GUID of the protocol to be moved
+ @param Interface The interface of the protocol
+
+ @return Protocol Entry
+
+**/
PROTOCOL_INTERFACE *
CoreRemoveInterfaceFromProtocol (
IN IHANDLE *Handle,
IN EFI_GUID *Protocol,
IN VOID *Interface
)
-/*++
-
-Routine Description:
-
- Removes Protocol from the protocol list (but not the handle list).
-
-Arguments:
-
- Handle - The handle to remove protocol on.
-
- Protocol - GUID of the protocol to be moved
-
- Interface - The interface of the protocol
-
-Returns:
-
- Protocol Entry
-
---*/
{
PROTOCOL_INTERFACE *Prot;
PROTOCOL_NOTIFY *ProtNotify;
@@ -107,6 +93,20 @@ Returns:
+
+/**
+ Add a new protocol notification record for the request protocol.
+
+ @param Protocol The requested protocol to add the notify
+ registration
+ @param Event The event to signal
+ @param Registration Returns the registration record
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_SUCCESS Successfully returned the registration record
+ that has been added
+
+**/
EFI_STATUS
EFIAPI
CoreRegisterProtocolNotify (
@@ -114,28 +114,6 @@ CoreRegisterProtocolNotify (
IN EFI_EVENT Event,
OUT VOID **Registration
)
-/*++
-
-Routine Description:
-
- Add a new protocol notification record for the request protocol.
-
-Arguments:
-
- Protocol - The requested protocol to add the notify registration
-
- Event - The event to signal
-
- Registration - Returns the registration record
-
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_SUCCESS - Successfully returned the registration record that has been added
-
---*/
{
PROTOCOL_ENTRY *ProtEntry;
PROTOCOL_NOTIFY *ProtNotify;
@@ -194,6 +172,21 @@ Returns:
+
+/**
+ Reinstall a protocol interface on a device handle. The OldInterface for Protocol is replaced by the NewInterface.
+
+ @param UserHandle Handle on which the interface is to be
+ reinstalled
+ @param Protocol The numeric ID of the interface
+ @param OldInterface A pointer to the old interface
+ @param NewInterface A pointer to the new interface
+
+ @retval EFI_SUCCESS The protocol interface was installed
+ @retval EFI_NOT_FOUND The OldInterface on the handle was not found
+ @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value
+
+**/
EFI_STATUS
EFIAPI
CoreReinstallProtocolInterface (
@@ -202,29 +195,6 @@ CoreReinstallProtocolInterface (
IN VOID *OldInterface,
IN VOID *NewInterface
)
-/*++
-
-Routine Description:
-
- Reinstall a protocol interface on a device handle. The OldInterface for Protocol is replaced by the NewInterface.
-
-Arguments:
-
- UserHandle - Handle on which the interface is to be reinstalled
- Protocol - The numeric ID of the interface
- OldInterface - A pointer to the old interface
- NewInterface - A pointer to the new interface
-
-
-Returns:
-
- Status code.
-
- On EFI_SUCCESS The protocol interface was installed
- On EFI_NOT_FOUND The OldInterface on the handle was not found
- On EFI_INVALID_PARAMETER One of the parameters has an invalid value
-
---*/
{
EFI_STATUS Status;
IHANDLE *Handle;
diff --git a/MdeModulePkg/Core/Dxe/Hand/handle.c b/MdeModulePkg/Core/Dxe/Hand/handle.c
index 36d81997c9..d95cef76df 100644
--- a/MdeModulePkg/Core/Dxe/Hand/handle.c
+++ b/MdeModulePkg/Core/Dxe/Hand/handle.c
@@ -1,6 +1,6 @@
/** @file
- UEFI handle & protocol handling
+ UEFI handle & protocol handling.
Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
@@ -28,75 +28,48 @@ EFI_LOCK gProtocolDatabaseLock = EFI_INITIALIZE_LOCK_VARIABLE (TPL
UINT64 gHandleDatabaseKey = 0;
+
+/**
+ Acquire lock on gProtocolDatabaseLock.
+
+**/
VOID
CoreAcquireProtocolLock (
VOID
)
-/*++
-
-Routine Description:
-
- Acquire lock on gProtocolDatabaseLock.
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
{
CoreAcquireLock (&gProtocolDatabaseLock);
}
+
+/**
+ Release lock on gProtocolDatabaseLock.
+
+**/
VOID
CoreReleaseProtocolLock (
VOID
)
-/*++
-
-Routine Description:
-
- Release lock on gProtocolDatabaseLock.
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
{
CoreReleaseLock (&gProtocolDatabaseLock);
}
+
+/**
+ Check whether a handle is a valid EFI_HANDLE
+
+ @param UserHandle The handle to check
+
+ @retval EFI_INVALID_PARAMETER The handle is NULL or not a valid EFI_HANDLE.
+ @retval EFI_SUCCESS The handle is valid EFI_HANDLE.
+
+**/
EFI_STATUS
CoreValidateHandle (
IN EFI_HANDLE UserHandle
)
-/*++
-
-Routine Description:
-
- Check whether a handle is a valid EFI_HANDLE
-
-Arguments:
-
- UserHandle - The handle to check
-
-Returns:
-
- EFI_INVALID_PARAMETER - The handle is NULL or not a valid EFI_HANDLE.
-
- EFI_SUCCESS - The handle is valid EFI_HANDLE.
-
---*/
{
IHANDLE *Handle;
@@ -111,30 +84,22 @@ Returns:
}
+
+/**
+ Finds the protocol entry for the requested protocol.
+ The gProtocolDatabaseLock must be owned
+
+ @param Protocol The ID of the protocol
+ @param Create Create a new entry if not found
+
+ @return Protocol entry
+
+**/
PROTOCOL_ENTRY *
CoreFindProtocolEntry (
IN EFI_GUID *Protocol,
IN BOOLEAN Create
)
-/*++
-
-Routine Description:
-
- Finds the protocol entry for the requested protocol.
-
- The gProtocolDatabaseLock must be owned
-
-Arguments:
-
- Protocol - The ID of the protocol
-
- Create - Create a new entry if not found
-
-Returns:
-
- Protocol entry
-
---*/
{
LIST_ENTRY *Link;
PROTOCOL_ENTRY *Item;
@@ -190,34 +155,25 @@ Returns:
}
+
+/**
+ Finds the protocol instance for the requested handle and protocol.
+ Note: This function doesn't do parameters checking, it's caller's responsibility
+ to pass in valid parameters.
+
+ @param Handle The handle to search the protocol on
+ @param Protocol GUID of the protocol
+ @param Interface The interface for the protocol being searched
+
+ @return Protocol instance (NULL: Not found)
+
+**/
PROTOCOL_INTERFACE *
CoreFindProtocolInterface (
IN IHANDLE *Handle,
IN EFI_GUID *Protocol,
IN VOID *Interface
)
-/*++
-
-Routine Description:
-
- Finds the protocol instance for the requested handle and protocol.
-
- Note: This function doesn't do parameters checking, it's caller's responsibility
- to pass in valid parameters.
-
-Arguments:
-
- Handle - The handle to search the protocol on
-
- Protocol - GUID of the protocol
-
- Interface - The interface for the protocol being searched
-
-Returns:
-
- Protocol instance (NULL: Not found)
-
---*/
{
PROTOCOL_INTERFACE *Prot;
PROTOCOL_ENTRY *ProtEntry;
@@ -253,27 +209,22 @@ Returns:
return Prot;
}
+
+/**
+ Removes an event from a register protocol notify list on a protocol.
+
+ @param Event The event to search for in the protocol
+ database.
+
+ @return EFI_SUCCESS if the event was found and removed.
+ @return EFI_NOT_FOUND if the event was not found in the protocl database.
+
+**/
STATIC
EFI_STATUS
CoreUnregisterProtocolNotifyEvent (
IN EFI_EVENT Event
)
-/*++
-
-Routine Description:
-
- Removes an event from a register protocol notify list on a protocol.
-
-Arguments:
-
- Event - The event to search for in the protocol database.
-
-Returns:
-
- EFI_SUCCESS if the event was found and removed.
- EFI_NOT_FOUND if the event was not found in the protocl database.
-
---*/
{
LIST_ENTRY *Link;
PROTOCOL_ENTRY *ProtEntry;
@@ -308,25 +259,20 @@ Returns:
}
+
+/**
+ Removes all the events in the protocol database that match Event.
+
+ @param Event The event to search for in the protocol
+ database.
+
+ @return EFI_SUCCESS when done searching the entire database.
+
+**/
EFI_STATUS
CoreUnregisterProtocolNotify (
IN EFI_EVENT Event
)
-/*++
-
-Routine Description:
-
- Removes all the events in the protocol database that match Event.
-
-Arguments:
-
- Event - The event to search for in the protocol database.
-
-Returns:
-
- EFI_SUCCESS when done searching the entire database.
-
---*/
{
EFI_STATUS Status;
@@ -339,6 +285,21 @@ Returns:
+
+/**
+ Wrapper function to CoreInstallProtocolInterfaceNotify. This is the public API which
+ Calls the private one which contains a BOOLEAN parameter for notifications
+
+ @param UserHandle The handle to install the protocol handler on,
+ or NULL if a new handle is to be allocated
+ @param Protocol The protocol to add to the handle
+ @param InterfaceType Indicates whether Interface is supplied in
+ native form.
+ @param Interface The interface for the protocol being added
+
+ @return Status code
+
+**/
EFI_STATUS
EFIAPI
CoreInstallProtocolInterface (
@@ -347,29 +308,6 @@ CoreInstallProtocolInterface (
IN EFI_INTERFACE_TYPE InterfaceType,
IN VOID *Interface
)
-/*++
-
-Routine Description:
-
- Wrapper function to CoreInstallProtocolInterfaceNotify. This is the public API which
- Calls the private one which contains a BOOLEAN parameter for notifications
-
-Arguments:
-
- UserHandle - The handle to install the protocol handler on,
- or NULL if a new handle is to be allocated
-
- Protocol - The protocol to add to the handle
-
- InterfaceType - Indicates whether Interface is supplied in native form.
-
- Interface - The interface for the protocol being added
-
-Returns:
-
- Status code
-
---*/
{
return CoreInstallProtocolInterfaceNotify (
UserHandle,
@@ -380,6 +318,24 @@ Returns:
);
}
+
+/**
+ Installs a protocol interface into the boot services environment.
+
+ @param UserHandle The handle to install the protocol handler on,
+ or NULL if a new handle is to be allocated
+ @param Protocol The protocol to add to the handle
+ @param InterfaceType Indicates whether Interface is supplied in
+ native form.
+ @param Interface The interface for the protocol being added
+ @param Notify indicates whether notify the notification list
+ for this protocol
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
+ @retval EFI_SUCCESS Protocol interface successfully installed
+
+**/
EFI_STATUS
CoreInstallProtocolInterfaceNotify (
IN OUT EFI_HANDLE *UserHandle,
@@ -388,35 +344,6 @@ CoreInstallProtocolInterfaceNotify (
IN VOID *Interface,
IN BOOLEAN Notify
)
-/*++
-
-Routine Description:
-
- Installs a protocol interface into the boot services environment.
-
-Arguments:
-
- UserHandle - The handle to install the protocol handler on,
- or NULL if a new handle is to be allocated
-
- Protocol - The protocol to add to the handle
-
- InterfaceType - Indicates whether Interface is supplied in native form.
-
- Interface - The interface for the protocol being added
-
- Notify - indicates whether notify the notification list
- for this protocol
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_OUT_OF_RESOURCES - No enough buffer to allocate
-
- EFI_SUCCESS - Protocol interface successfully installed
-
---*/
{
PROTOCOL_INTERFACE *Prot;
PROTOCOL_ENTRY *ProtEntry;
@@ -439,7 +366,7 @@ Returns:
//
// Print debug message
//
- DEBUG((EFI_D_ERROR | EFI_D_INFO, "InstallProtocolInterface: %g %p\n", Protocol, Interface));
+ DEBUG((DEBUG_ERROR | DEBUG_INFO, "InstallProtocolInterface: %g %p\n", Protocol, Interface));
Status = EFI_OUT_OF_RESOURCES;
Prot = NULL;
@@ -574,38 +501,32 @@ Done:
+
+/**
+ Installs a list of protocol interface into the boot services environment.
+ This function calls InstallProtocolInterface() in a loop. If any error
+ occures all the protocols added by this function are removed. This is
+ basically a lib function to save space.
+
+ @param Handle The handle to install the protocol handlers on,
+ or NULL if a new handle is to be allocated
+ @param ... EFI_GUID followed by protocol instance. A NULL
+ terminates the list. The pairs are the
+ arguments to InstallProtocolInterface(). All the
+ protocols are added to Handle.
+
+ @retval EFI_INVALID_PARAMETER Handle is NULL.
+ @retval EFI_SUCCESS Protocol interfaces successfully installed.
+
+**/
EFI_STATUS
EFIAPI
CoreInstallMultipleProtocolInterfaces (
IN OUT EFI_HANDLE *Handle,
...
)
-/*++
-
-Routine Description:
-
- Installs a list of protocol interface into the boot services environment.
- This function calls InstallProtocolInterface() in a loop. If any error
- occures all the protocols added by this function are removed. This is
- basically a lib function to save space.
-
-Arguments:
-
- Handle - The handle to install the protocol handlers on,
- or NULL if a new handle is to be allocated
- ... - EFI_GUID followed by protocol instance. A NULL terminates the
- list. The pairs are the arguments to InstallProtocolInterface().
- All the protocols are added to Handle.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Handle is NULL.
-
- EFI_SUCCESS - Protocol interfaces successfully installed.
-
---*/
{
- VA_LIST args;
+ VA_LIST Args;
EFI_STATUS Status;
EFI_GUID *Protocol;
VOID *Interface;
@@ -628,17 +549,17 @@ Returns:
//
// Check for duplicate device path and install the protocol interfaces
//
- VA_START (args, Handle);
+ VA_START (Args, Handle);
for (Index = 0, Status = EFI_SUCCESS; !EFI_ERROR (Status); Index++) {
//
// If protocol is NULL, then it's the end of the list
//
- Protocol = VA_ARG (args, EFI_GUID *);
+ Protocol = VA_ARG (Args, EFI_GUID *);
if (Protocol == NULL) {
break;
}
- Interface = VA_ARG (args, VOID *);
+ Interface = VA_ARG (Args, VOID *);
//
// Make sure you are installing on top a device path that has already been added.
@@ -666,10 +587,10 @@ Returns:
//
// Reset the va_arg back to the first argument.
//
- VA_START (args, Handle);
+ VA_START (Args, Handle);
for (; Index > 1; Index--) {
- Protocol = VA_ARG (args, EFI_GUID *);
- Interface = VA_ARG (args, VOID *);
+ Protocol = VA_ARG (Args, EFI_GUID *);
+ Interface = VA_ARG (Args, VOID *);
CoreUninstallProtocolInterface (*Handle, Protocol, Interface);
}
*Handle = OldHandle;
@@ -682,32 +603,26 @@ Returns:
return Status;
}
+
+/**
+ Attempts to disconnect all drivers that are using the protocol interface being queried.
+ If failed, reconnect all drivers disconnected.
+ Note: This function doesn't do parameters checking, it's caller's responsibility
+ to pass in valid parameters.
+
+ @param UserHandle The handle on which the protocol is installed
+ @param Prot The protocol to disconnect drivers from
+
+ @retval EFI_SUCCESS Drivers using the protocol interface are all
+ disconnected
+ @retval EFI_ACCESS_DENIED Failed to disconnect one or all of the drivers
+
+**/
EFI_STATUS
CoreDisconnectControllersUsingProtocolInterface (
IN EFI_HANDLE UserHandle,
IN PROTOCOL_INTERFACE *Prot
)
-/*++
-
-Routine Description:
-
- Attempts to disconnect all drivers that are using the protocol interface being queried.
- If failed, reconnect all drivers disconnected.
-
- Note: This function doesn't do parameters checking, it's caller's responsibility
- to pass in valid parameters.
-
-Arguments:
-
- UserHandle - The handle on which the protocol is installed
- Prot - The protocol to disconnect drivers from
-
-Returns:
-
- EFI_SUCCESS - Drivers using the protocol interface are all disconnected
- EFI_ACCESS_DENIED - Failed to disconnect one or all of the drivers
-
---*/
{
EFI_STATUS Status;
BOOLEAN ItemFound;
@@ -773,6 +688,20 @@ Returns:
}
+
+/**
+ Uninstalls all instances of a protocol:interfacer from a handle.
+ If the last protocol interface is remove from the handle, the
+ handle is freed.
+
+ @param UserHandle The handle to remove the protocol handler from
+ @param Protocol The protocol, of protocol:interface, to remove
+ @param Interface The interface, of protocol:interface, to remove
+
+ @retval EFI_INVALID_PARAMETER Protocol is NULL.
+ @retval EFI_SUCCESS Protocol interface successfully uninstalled.
+
+**/
EFI_STATUS
EFIAPI
CoreUninstallProtocolInterface (
@@ -780,29 +709,6 @@ CoreUninstallProtocolInterface (
IN EFI_GUID *Protocol,
IN VOID *Interface
)
-/*++
-
-Routine Description:
-
- Uninstalls all instances of a protocol:interfacer from a handle.
- If the last protocol interface is remove from the handle, the
- handle is freed.
-
-Arguments:
-
- UserHandle - The handle to remove the protocol handler from
-
- Protocol - The protocol, of protocol:interface, to remove
-
- Interface - The interface, of protocol:interface, to remove
-
-Returns:
-
- EFI_INVALID_PARAMETER - Protocol is NULL.
-
- EFI_SUCCESS - Protocol interface successfully uninstalled.
-
---*/
{
EFI_STATUS Status;
IHANDLE *Handle;
@@ -897,51 +803,45 @@ Done:
+
+/**
+ Uninstalls a list of protocol interface in the boot services environment.
+ This function calls UnisatllProtocolInterface() in a loop. This is
+ basically a lib function to save space.
+
+ @param Handle The handle to uninstall the protocol
+ @param ... EFI_GUID followed by protocol instance. A NULL
+ terminates the list. The pairs are the
+ arguments to UninstallProtocolInterface(). All
+ the protocols are added to Handle.
+
+ @return Status code
+
+**/
EFI_STATUS
EFIAPI
CoreUninstallMultipleProtocolInterfaces (
IN EFI_HANDLE Handle,
...
)
-/*++
-
-Routine Description:
-
- Uninstalls a list of protocol interface in the boot services environment.
- This function calls UnisatllProtocolInterface() in a loop. This is
- basically a lib function to save space.
-
-Arguments:
-
- Handle - The handle to uninstall the protocol
-
- ... - EFI_GUID followed by protocol instance. A NULL terminates the
- list. The pairs are the arguments to UninstallProtocolInterface().
- All the protocols are added to Handle.
-
-Returns:
-
- Status code
-
---*/
{
EFI_STATUS Status;
- VA_LIST args;
+ VA_LIST Args;
EFI_GUID *Protocol;
VOID *Interface;
UINTN Index;
- VA_START (args, Handle);
+ VA_START (Args, Handle);
for (Index = 0, Status = EFI_SUCCESS; !EFI_ERROR (Status); Index++) {
//
// If protocol is NULL, then it's the end of the list
//
- Protocol = VA_ARG (args, EFI_GUID *);
+ Protocol = VA_ARG (Args, EFI_GUID *);
if (Protocol == NULL) {
break;
}
- Interface = VA_ARG (args, VOID *);
+ Interface = VA_ARG (Args, VOID *);
//
// Uninstall it
@@ -957,10 +857,10 @@ Returns:
//
// Reset the va_arg back to the first argument.
//
- VA_START (args, Handle);
+ VA_START (Args, Handle);
for (; Index > 1; Index--) {
- Protocol = VA_ARG(args, EFI_GUID *);
- Interface = VA_ARG(args, VOID *);
+ Protocol = VA_ARG(Args, EFI_GUID *);
+ Interface = VA_ARG(Args, VOID *);
CoreInstallProtocolInterface (&Handle, Protocol, EFI_NATIVE_INTERFACE, Interface);
}
}
@@ -968,29 +868,22 @@ Returns:
return Status;
}
+
+/**
+ Locate a certain GUID protocol interface in a Handle's protocols.
+
+ @param UserHandle The handle to obtain the protocol interface on
+ @param Protocol The GUID of the protocol
+
+ @return The requested protocol interface for the handle
+
+**/
STATIC
PROTOCOL_INTERFACE *
CoreGetProtocolInterface (
IN EFI_HANDLE UserHandle,
IN EFI_GUID *Protocol
)
-/*++
-
-Routine Description:
-
- Locate a certain GUID protocol interface in a Handle's protocols.
-
-Arguments:
-
- UserHandle - The handle to obtain the protocol interface on
-
- Protocol - The GUID of the protocol
-
-Returns:
-
- The requested protocol interface for the handle
-
---*/
{
EFI_STATUS Status;
PROTOCOL_ENTRY *ProtEntry;
@@ -1019,6 +912,18 @@ Returns:
}
+
+/**
+ Queries a handle to determine if it supports a specified protocol.
+
+ @param UserHandle The handle being queried.
+ @param Protocol The published unique identifier of the protocol.
+ @param Interface Supplies the address where a pointer to the
+ corresponding Protocol Interface is returned.
+
+ @return The requested protocol interface for the handle
+
+**/
EFI_STATUS
EFIAPI
CoreHandleProtocol (
@@ -1026,26 +931,6 @@ CoreHandleProtocol (
IN EFI_GUID *Protocol,
OUT VOID **Interface
)
-/*++
-
-Routine Description:
-
- Queries a handle to determine if it supports a specified protocol.
-
-Arguments:
-
- UserHandle - The handle being queried.
-
- Protocol - The published unique identifier of the protocol.
-
- Interface - Supplies the address where a pointer to the corresponding Protocol
- Interface is returned.
-
-Returns:
-
- The requested protocol interface for the handle
-
---*/
{
return CoreOpenProtocol (
UserHandle,
@@ -1058,6 +943,27 @@ Returns:
}
+
+/**
+ Locates the installed protocol handler for the handle, and
+ invokes it to obtain the protocol interface. Usage information
+ is registered in the protocol data base.
+
+ @param UserHandle The handle to obtain the protocol interface on
+ @param Protocol The ID of the protocol
+ @param Interface The location to return the protocol interface
+ @param ImageHandle The handle of the Image that is opening the
+ protocol interface specified by Protocol and
+ Interface.
+ @param ControllerHandle The controller handle that is requiring this
+ interface.
+ @param Attributes The open mode of the protocol interface
+ specified by Handle and Protocol.
+
+ @retval EFI_INVALID_PARAMETER Protocol is NULL.
+ @retval EFI_SUCCESS Get the protocol interface.
+
+**/
EFI_STATUS
EFIAPI
CoreOpenProtocol (
@@ -1068,37 +974,6 @@ CoreOpenProtocol (
IN EFI_HANDLE ControllerHandle,
IN UINT32 Attributes
)
-/*++
-
-Routine Description:
-
- Locates the installed protocol handler for the handle, and
- invokes it to obtain the protocol interface. Usage information
- is registered in the protocol data base.
-
-Arguments:
-
- UserHandle - The handle to obtain the protocol interface on
-
- Protocol - The ID of the protocol
-
- Interface - The location to return the protocol interface
-
- ImageHandle - The handle of the Image that is opening the protocol interface
- specified by Protocol and Interface.
-
- ControllerHandle - The controller handle that is requiring this interface.
-
- Attributes - The open mode of the protocol interface specified by Handle
- and Protocol.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Protocol is NULL.
-
- EFI_SUCCESS - Get the protocol interface.
-
---*/
{
EFI_STATUS Status;
PROTOCOL_INTERFACE *Prot;
@@ -1298,6 +1173,32 @@ Done:
}
+
+/**
+ Closes a protocol on a handle that was opened using OpenProtocol().
+
+ @param UserHandle The handle for the protocol interface that was
+ previously opened with OpenProtocol(), and is
+ now being closed.
+ @param Protocol The published unique identifier of the protocol.
+ It is the caller's responsibility to pass in a
+ valid GUID.
+ @param AgentHandle The handle of the agent that is closing the
+ protocol interface.
+ @param ControllerHandle If the agent that opened a protocol is a driver
+ that follows the EFI Driver Model, then this
+ parameter is the controller handle that required
+ the protocol interface. If the agent does not
+ follow the EFI Driver Model, then this parameter
+ is optional and may be NULL.
+
+ @retval EFI_SUCCESS The protocol instance was closed.
+ @retval EFI_INVALID_PARAMETER Handle, AgentHandle or ControllerHandle is not a
+ valid EFI_HANDLE.
+ @retval EFI_NOT_FOUND Can not find the specified protocol or
+ AgentHandle.
+
+**/
EFI_STATUS
EFIAPI
CoreCloseProtocol (
@@ -1306,31 +1207,6 @@ CoreCloseProtocol (
IN EFI_HANDLE AgentHandle,
IN EFI_HANDLE ControllerHandle
)
-/*++
-
-Routine Description:
-
- Closes a protocol on a handle that was opened using OpenProtocol().
-
-Arguments:
-
- UserHandle - The handle for the protocol interface that was previously opened
- with OpenProtocol(), and is now being closed.
- Protocol - The published unique identifier of the protocol. It is the caller's
- responsibility to pass in a valid GUID.
- AgentHandle - The handle of the agent that is closing the protocol interface.
- ControllerHandle - If the agent that opened a protocol is a driver that follows the
- EFI Driver Model, then this parameter is the controller handle
- that required the protocol interface. If the agent does not follow
- the EFI Driver Model, then this parameter is optional and may be NULL.
-
-Returns:
-
- EFI_SUCCESS - The protocol instance was closed.
- EFI_INVALID_PARAMETER - Handle, AgentHandle or ControllerHandle is not a valid EFI_HANDLE.
- EFI_NOT_FOUND - Can not find the specified protocol or AgentHandle.
-
---*/
{
EFI_STATUS Status;
PROTOCOL_INTERFACE *ProtocolInterface;
@@ -1397,6 +1273,18 @@ Done:
+
+/**
+ Return information about Opened protocols in the system
+
+ @param UserHandle The handle to close the protocol interface on
+ @param Protocol The ID of the protocol
+ @param EntryBuffer A pointer to a buffer of open protocol
+ information in the form of
+ EFI_OPEN_PROTOCOL_INFORMATION_ENTRY structures.
+ @param EntryCount Number of EntryBuffer entries
+
+**/
EFI_STATUS
EFIAPI
CoreOpenProtocolInformation (
@@ -1405,27 +1293,6 @@ CoreOpenProtocolInformation (
OUT EFI_OPEN_PROTOCOL_INFORMATION_ENTRY **EntryBuffer,
OUT UINTN *EntryCount
)
-/*++
-
-Routine Description:
-
- Return information about Opened protocols in the system
-
-Arguments:
-
- UserHandle - The handle to close the protocol interface on
-
- Protocol - The ID of the protocol
-
- EntryBuffer - A pointer to a buffer of open protocol information in the form of
- EFI_OPEN_PROTOCOL_INFORMATION_ENTRY structures.
-
- EntryCount - Number of EntryBuffer entries
-
-Returns:
-
-
---*/
{
EFI_STATUS Status;
PROTOCOL_INTERFACE *ProtocolInterface;
@@ -1500,6 +1367,30 @@ Done:
+
+/**
+ Retrieves the list of protocol interface GUIDs that are installed on a handle in a buffer allocated
+ from pool.
+
+ @param UserHandle The handle from which to retrieve the list of
+ protocol interface GUIDs.
+ @param ProtocolBuffer A pointer to the list of protocol interface GUID
+ pointers that are installed on Handle.
+ @param ProtocolBufferCount A pointer to the number of GUID pointers present
+ in ProtocolBuffer.
+
+ @retval EFI_SUCCESS The list of protocol interface GUIDs installed
+ on Handle was returned in ProtocolBuffer. The
+ number of protocol interface GUIDs was returned
+ in ProtocolBufferCount.
+ @retval EFI_INVALID_PARAMETER Handle is NULL.
+ @retval EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE.
+ @retval EFI_INVALID_PARAMETER ProtocolBuffer is NULL.
+ @retval EFI_INVALID_PARAMETER ProtocolBufferCount is NULL.
+ @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
+ results.
+
+**/
EFI_STATUS
EFIAPI
CoreProtocolsPerHandle (
@@ -1507,35 +1398,6 @@ CoreProtocolsPerHandle (
OUT EFI_GUID ***ProtocolBuffer,
OUT UINTN *ProtocolBufferCount
)
-/*++
-
-Routine Description:
-
- Retrieves the list of protocol interface GUIDs that are installed on a handle in a buffer allocated
- from pool.
-
-Arguments:
-
- UserHandle - The handle from which to retrieve the list of protocol interface
- GUIDs.
-
- ProtocolBuffer - A pointer to the list of protocol interface GUID pointers that are
- installed on Handle.
-
- ProtocolBufferCount - A pointer to the number of GUID pointers present in
- ProtocolBuffer.
-
-Returns:
- EFI_SUCCESS - The list of protocol interface GUIDs installed on Handle was returned in
- ProtocolBuffer. The number of protocol interface GUIDs was
- returned in ProtocolBufferCount.
- EFI_INVALID_PARAMETER - Handle is NULL.
- EFI_INVALID_PARAMETER - Handle is not a valid EFI_HANDLE.
- EFI_INVALID_PARAMETER - ProtocolBuffer is NULL.
- EFI_INVALID_PARAMETER - ProtocolBufferCount is NULL.
- EFI_OUT_OF_RESOURCES - There is not enough pool memory to store the results.
-
---*/
{
EFI_STATUS Status;
IHANDLE *Handle;
@@ -1600,48 +1462,35 @@ Done:
}
+
+/**
+ return handle database key.
+
+
+ @return Handle database key.
+
+**/
UINT64
CoreGetHandleDatabaseKey (
VOID
)
-/*++
-
-Routine Description:
-
- return handle database key.
-
-Arguments:
-
- None
-
-Returns:
-
- Handle database key.
-
---*/
{
return gHandleDatabaseKey;
}
+
+/**
+ Go connect any handles that were created or modified while a image executed.
+
+ @param Key The Key to show that the handle has been
+ created/modified
+
+**/
VOID
CoreConnectHandlesByKey (
UINT64 Key
)
-/*++
-
-Routine Description:
-
- Go connect any handles that were created or modified while a image executed.
-
-Arguments:
-
- Key - The Key to show that the handle has been created/modified
-
-Returns:
-
- None
---*/
{
UINTN Count;
LIST_ENTRY *Link;
diff --git a/MdeModulePkg/Core/Dxe/Hand/locate.c b/MdeModulePkg/Core/Dxe/Hand/locate.c
index 959e988831..9c42383791 100644
--- a/MdeModulePkg/Core/Dxe/Hand/locate.c
+++ b/MdeModulePkg/Core/Dxe/Hand/locate.c
@@ -38,6 +38,18 @@ IHANDLE *
OUT VOID **Interface
);
+/**
+ Routine to get the next Handle, when you are searching for all handles.
+
+ @param Position Information about which Handle to seach for.
+ @param Interface Return the interface structure for the matching
+ protocol.
+
+ @retval IHANDLE An IHANDLE is returned if the next Position is
+ not the end of the list. A NULL_HANDLE is
+ returned if it's the end of the list.
+
+**/
STATIC
IHANDLE *
CoreGetNextLocateAllHandles (
@@ -45,6 +57,19 @@ CoreGetNextLocateAllHandles (
OUT VOID **Interface
);
+/**
+ Routine to get the next Handle, when you are searching for register protocol
+ notifies.
+
+ @param Position Information about which Handle to seach for.
+ @param Interface Return the interface structure for the matching
+ protocol.
+
+ @retval IHANDLE An IHANDLE is returned if the next Position is
+ not the end of the list. A NULL_HANDLE is
+ returned if it's the end of the list.
+
+**/
STATIC
IHANDLE *
CoreGetNextLocateByRegisterNotify (
@@ -52,6 +77,18 @@ CoreGetNextLocateByRegisterNotify (
OUT VOID **Interface
);
+/**
+ Routine to get the next Handle, when you are searching for a given protocol.
+
+ @param Position Information about which Handle to seach for.
+ @param Interface Return the interface structure for the matching
+ protocol.
+
+ @retval IHANDLE An IHANDLE is returned if the next Position is
+ not the end of the list. A NULL_HANDLE is
+ returned if it's the end of the list.
+
+**/
STATIC
IHANDLE *
CoreGetNextLocateByProtocol (
@@ -59,13 +96,25 @@ CoreGetNextLocateByProtocol (
OUT VOID **Interface
);
-//
-//
-//
+/**
+ Locates the requested handle(s) and returns them in Buffer.
+ @param SearchType The type of search to perform to locate the
+ handles
+ @param Protocol The protocol to search for
+ @param SearchKey Dependant on SearchType
+ @param BufferSize On input the size of Buffer. On output the
+ size of data returned.
+ @param Buffer The buffer to return the results in
-
+ @retval EFI_BUFFER_TOO_SMALL Buffer too small, required buffer size is
+ returned in BufferSize.
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_SUCCESS Successfully found the requested handle(s) and
+ returns them in Buffer.
+
+**/
EFI_STATUS
EFIAPI
CoreLocateHandle (
@@ -75,35 +124,6 @@ CoreLocateHandle (
IN OUT UINTN *BufferSize,
OUT EFI_HANDLE *Buffer
)
-/*++
-
-Routine Description:
-
- Locates the requested handle(s) and returns them in Buffer.
-
-Arguments:
-
- SearchType - The type of search to perform to locate the handles
-
- Protocol - The protocol to search for
-
- SearchKey - Dependant on SearchType
-
- BufferSize - On input the size of Buffer. On output the
- size of data returned.
-
- Buffer - The buffer to return the results in
-
-
-Returns:
-
- EFI_BUFFER_TOO_SMALL - Buffer too small, required buffer size is returned in BufferSize.
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_SUCCESS - Successfully found the requested handle(s) and returns them in Buffer.
-
---*/
{
EFI_STATUS Status;
LOCATE_POSITION Position;
@@ -243,29 +263,25 @@ Returns:
}
+
+/**
+ Routine to get the next Handle, when you are searching for all handles.
+
+ @param Position Information about which Handle to seach for.
+ @param Interface Return the interface structure for the matching
+ protocol.
+
+ @retval IHANDLE An IHANDLE is returned if the next Position is
+ not the end of the list. A NULL_HANDLE is
+ returned if it's the end of the list.
+
+**/
STATIC
IHANDLE *
CoreGetNextLocateAllHandles (
IN OUT LOCATE_POSITION *Position,
OUT VOID **Interface
)
-/*++
-
-Routine Description:
-
- Routine to get the next Handle, when you are searching for all handles.
-
-Arguments:
-
- Position - Information about which Handle to seach for.
-
- Interface - Return the interface structure for the matching protocol.
-
-Returns:
- IHANDLE - An IHANDLE is returned if the next Position is not the end of the
- list. A NULL_HANDLE is returned if it's the end of the list.
-
---*/
{
IHANDLE *Handle;
@@ -287,30 +303,26 @@ Returns:
}
+
+/**
+ Routine to get the next Handle, when you are searching for register protocol
+ notifies.
+
+ @param Position Information about which Handle to seach for.
+ @param Interface Return the interface structure for the matching
+ protocol.
+
+ @retval IHANDLE An IHANDLE is returned if the next Position is
+ not the end of the list. A NULL_HANDLE is
+ returned if it's the end of the list.
+
+**/
STATIC
IHANDLE *
CoreGetNextLocateByRegisterNotify (
IN OUT LOCATE_POSITION *Position,
OUT VOID **Interface
)
-/*++
-
-Routine Description:
-
- Routine to get the next Handle, when you are searching for register protocol
- notifies.
-
-Arguments:
-
- Position - Information about which Handle to seach for.
-
- Interface - Return the interface structure for the matching protocol.
-
-Returns:
- IHANDLE - An IHANDLE is returned if the next Position is not the end of the
- list. A NULL_HANDLE is returned if it's the end of the list.
-
---*/
{
IHANDLE *Handle;
PROTOCOL_NOTIFY *ProtNotify;
@@ -343,29 +355,25 @@ Returns:
}
+
+/**
+ Routine to get the next Handle, when you are searching for a given protocol.
+
+ @param Position Information about which Handle to seach for.
+ @param Interface Return the interface structure for the matching
+ protocol.
+
+ @retval IHANDLE An IHANDLE is returned if the next Position is
+ not the end of the list. A NULL_HANDLE is
+ returned if it's the end of the list.
+
+**/
STATIC
IHANDLE *
CoreGetNextLocateByProtocol (
IN OUT LOCATE_POSITION *Position,
OUT VOID **Interface
)
-/*++
-
-Routine Description:
-
- Routine to get the next Handle, when you are searching for a given protocol.
-
-Arguments:
-
- Position - Information about which Handle to seach for.
-
- Interface - Return the interface structure for the matching protocol.
-
-Returns:
- IHANDLE - An IHANDLE is returned if the next Position is not the end of the
- list. A NULL_HANDLE is returned if it's the end of the list.
-
---*/
{
IHANDLE *Handle;
LIST_ENTRY *Link;
@@ -410,6 +418,22 @@ Returns:
+
+/**
+ Locates the handle to a device on the device path that best matches the specified protocol.
+
+ @param Protocol The protocol to search for.
+ @param DevicePath On input, a pointer to a pointer to the device
+ path. On output, the device path pointer is
+ modified to point to the remaining part of the
+ devicepath.
+ @param Device A pointer to the returned device handle.
+
+ @retval EFI_SUCCESS The resulting handle was returned.
+ @retval EFI_NOT_FOUND No handles matched the search.
+ @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
+
+**/
EFI_STATUS
EFIAPI
CoreLocateDevicePath (
@@ -417,26 +441,6 @@ CoreLocateDevicePath (
IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath,
OUT EFI_HANDLE *Device
)
-/*++
-
-Routine Description:
-
- Locates the handle to a device on the device path that best matches the specified protocol.
-
-Arguments:
-
- Protocol - The protocol to search for.
- DevicePath - On input, a pointer to a pointer to the device path. On output, the device
- path pointer is modified to point to the remaining part of the devicepath.
- Device - A pointer to the returned device handle.
-
-Returns:
-
- EFI_SUCCESS - The resulting handle was returned.
- EFI_NOT_FOUND - No handles matched the search.
- EFI_INVALID_PARAMETER - One of the parameters has an invalid value.
-
---*/
{
INTN SourceSize;
INTN Size;
@@ -469,7 +473,7 @@ Returns:
// The source path can only have 1 instance
//
if (CoreIsDevicePathMultiInstance (SourcePath)) {
- DEBUG((EFI_D_ERROR, "LocateDevicePath: Device path has too many instances\n"));
+ DEBUG((DEBUG_ERROR, "LocateDevicePath: Device path has too many instances\n"));
return EFI_INVALID_PARAMETER;
}
@@ -533,6 +537,23 @@ Returns:
+
+/**
+ Return the first Protocol Interface that matches the Protocol GUID. If
+ Registration is pasased in return a Protocol Instance that was just add
+ to the system. If Retistration is NULL return the first Protocol Interface
+ you find.
+
+ @param Protocol The protocol to search for
+ @param Registration Optional Registration Key returned from
+ RegisterProtocolNotify()
+ @param Interface Return the Protocol interface (instance).
+
+ @retval EFI_SUCCESS If a valid Interface is returned
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_NOT_FOUND Protocol interface not found
+
+**/
EFI_STATUS
EFIAPI
CoreLocateProtocol (
@@ -540,32 +561,6 @@ CoreLocateProtocol (
IN VOID *Registration OPTIONAL,
OUT VOID **Interface
)
-/*++
-
-Routine Description:
-
- Return the first Protocol Interface that matches the Protocol GUID. If
- Registration is pasased in return a Protocol Instance that was just add
- to the system. If Retistration is NULL return the first Protocol Interface
- you find.
-
-Arguments:
-
- Protocol - The protocol to search for
-
- Registration - Optional Registration Key returned from RegisterProtocolNotify()
-
- Interface - Return the Protocol interface (instance).
-
-Returns:
-
- EFI_SUCCESS - If a valid Interface is returned
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_NOT_FOUND - Protocol interface not found
-
---*/
{
EFI_STATUS Status;
LOCATE_POSITION Position;
@@ -631,6 +626,29 @@ Done:
+
+/**
+ Function returns an array of handles that support the requested protocol
+ in a buffer allocated from pool. This is a version of CoreLocateHandle()
+ that allocates a buffer for the caller.
+
+ @param SearchType Specifies which handle(s) are to be returned.
+ @param Protocol Provides the protocol to search by. This
+ parameter is only valid for SearchType
+ ByProtocol.
+ @param SearchKey Supplies the search key depending on the
+ SearchType.
+ @param NumberHandles The number of handles returned in Buffer.
+ @param Buffer A pointer to the buffer to return the requested
+ array of handles that support Protocol.
+
+ @retval EFI_SUCCESS The result array of handles was returned.
+ @retval EFI_NOT_FOUND No handles match the search.
+ @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
+ matching results.
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+
+**/
EFI_STATUS
EFIAPI
CoreLocateHandleBuffer (
@@ -640,32 +658,6 @@ CoreLocateHandleBuffer (
IN OUT UINTN *NumberHandles,
OUT EFI_HANDLE **Buffer
)
-/*++
-
-Routine Description:
-
- Function returns an array of handles that support the requested protocol
- in a buffer allocated from pool. This is a version of CoreLocateHandle()
- that allocates a buffer for the caller.
-
-Arguments:
-
- SearchType - Specifies which handle(s) are to be returned.
- Protocol - Provides the protocol to search by.
- This parameter is only valid for SearchType ByProtocol.
- SearchKey - Supplies the search key depending on the SearchType.
- NumberHandles - The number of handles returned in Buffer.
- Buffer - A pointer to the buffer to return the requested array of
- handles that support Protocol.
-
-Returns:
-
- EFI_SUCCESS - The result array of handles was returned.
- EFI_NOT_FOUND - No handles match the search.
- EFI_OUT_OF_RESOURCES - There is not enough pool memory to store the matching results.
- EFI_INVALID_PARAMETER - Invalid parameter
-
---*/
{
EFI_STATUS Status;
UINTN BufferSize;
@@ -723,3 +715,4 @@ Returns:
}
+
diff --git a/MdeModulePkg/Core/Dxe/Image.h b/MdeModulePkg/Core/Dxe/Image.h
index e233104a50..0b8201ee5e 100644
--- a/MdeModulePkg/Core/Dxe/Image.h
+++ b/MdeModulePkg/Core/Dxe/Image.h
@@ -89,6 +89,30 @@ typedef struct {
// Abstractions for reading image contents
//
+
+/**
+ Opens a file for (simple) reading. The simple read abstraction
+ will access the file either from a memory copy, from a file
+ system interface, or from the load file interface.
+
+ @param BootPolicy Policy for Open Image File.
+ @param SourceBuffer Pointer to the memory location containing copy
+ of the image to be loaded.
+ @param SourceSize The size in bytes of SourceBuffer.
+ @param FilePath The specific file path from which the image is
+ loaded
+ @param DeviceHandle Pointer to the return device handle.
+ @param ImageFileHandle Pointer to the image file handle.
+ @param AuthenticationStatus Pointer to a caller-allocated UINT32 in which
+ the authentication status is returned.
+
+ @retval EFI_SUCCESS Image file successfully opened.
+ @retval EFI_LOAD_ERROR If the caller passed a copy of the file, and
+ SourceSize is 0.
+ @retval EFI_INVALID_PARAMETER File path is not valid.
+ @retval EFI_NOT_FOUND File not found.
+
+**/
EFI_STATUS
CoreOpenImageFile (
IN BOOLEAN BootPolicy,
@@ -99,33 +123,24 @@ CoreOpenImageFile (
IN IMAGE_FILE_HANDLE *ImageFileHandle,
OUT UINT32 *AuthenticationStatus
)
-/*++
-
-Routine Description:
-
- Opens a file for (simple) reading. The simple read abstraction
- will access the file either from a memory copy, from a file
- system interface, or from the load file interface.
-
-Arguments:
-
- BootPolicy - Policy for Open Image File.
- SourceBuffer - Pointer to the memory location containing copy
- of the image to be loaded.
- SourceSize - The size in bytes of SourceBuffer.
- FilePath - The specific file path from which the image is loaded
- DeviceHandle - Pointer to the return device handle.
- ImageFileHandle - Pointer to the image file handle.
- AuthenticationStatus - Pointer to a caller-allocated UINT32 in which the authentication status is returned.
-
-Returns:
-
- A handle to access the file
-
---*/
;
+
+/**
+ Read image file (specified by UserHandle) into user specified buffer with specified offset
+ and length.
+
+ @param UserHandle Image file handle
+ @param Offset Offset to the source file
+ @param ReadSize For input, pointer of size to read; For output,
+ pointer of size actually read.
+ @param Buffer Buffer to write into
+
+ @retval EFI_SUCCESS Successfully read the specified part of file
+ into buffer.
+
+**/
EFI_STATUS
EFIAPI
CoreReadImageFile (
@@ -134,56 +149,39 @@ CoreReadImageFile (
IN OUT UINTN *ReadSize,
OUT VOID *Buffer
)
-/*++
-
-Routine Description:
-
- Read image file (specified by UserHandle) into user specified buffer with specified offset
- and length.
-
-Arguments:
-
- UserHandle - Image file handle
-
- Offset - Offset to the source file
-
- ReadSize - For input, pointer of size to read;
- For output, pointer of size actually read.
-
- Buffer - Buffer to write into
-
-Returns:
-
- EFI_SUCCESS - Successfully read the specified part of file into buffer.
-
---*/
;
+
+/**
+ A function out of date, should be removed.
+
+ @param ImageFileHandle Handle of the file to close
+
+**/
VOID
EFIAPI
CoreCloseImageFile (
IN IMAGE_FILE_HANDLE *ImageFileHandle
)
-/*++
-
-Routine Description:
-
- A function out of date, should be removed.
-
-Arguments:
-
- ImageFileHandle - Handle of the file to close
-
-Returns:
-
- None
-
---*/
;
//
// Image processing worker functions
//
+
+/**
+ Search a handle to a device on a specified device path that supports a specified protocol,
+ interface of that protocol on that handle is another output.
+
+ @param Protocol The protocol to search for
+ @param FilePath The specified device path
+ @param Interface Interface of the protocol on the handle
+ @param Handle The handle to the device on the specified device
+ path that supports the protocol.
+
+ @return Status code.
+
+**/
EFI_STATUS
CoreDevicePathToInterface (
IN EFI_GUID *Protocol,
@@ -191,30 +189,30 @@ CoreDevicePathToInterface (
OUT VOID **Interface,
OUT EFI_HANDLE *Handle
)
-/*++
-
-Routine Description:
-
- Search a handle to a device on a specified device path that supports a specified protocol,
- interface of that protocol on that handle is another output.
-
-Arguments:
-
- Protocol - The protocol to search for
-
- FilePath - The specified device path
-
- Interface - Interface of the protocol on the handle
-
- Handle - The handle to the device on the specified device path that supports the protocol.
-
-Returns:
-
- Status code.
-
---*/
;
+
+/**
+ Loads, relocates, and invokes a PE/COFF image
+
+ @param BootPolicy If TRUE, indicates that the request originates
+ from the boot manager, and that the boot
+ manager is attempting to load FilePath as a
+ boot selection.
+ @param Pe32Handle The handle of PE32 image
+ @param Image PE image to be loaded
+ @param DstBuffer The buffer to store the image
+ @param EntryPoint A pointer to the entry point
+ @param Attribute The bit mask of attributes to set for the load
+ PE image
+
+ @retval EFI_SUCCESS The file was loaded, relocated, and invoked
+ @retval EFI_OUT_OF_RESOURCES There was not enough memory to load and
+ relocate the PE/COFF file
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_BUFFER_TOO_SMALL Buffer for image is too small
+
+**/
EFI_STATUS
CoreLoadPeImage (
IN BOOLEAN BootPolicy,
@@ -224,76 +222,36 @@ CoreLoadPeImage (
OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,
IN UINT32 Attribute
)
-/*++
-
-Routine Description:
-
- Loads, relocates, and invokes a PE/COFF image
-
-Arguments:
-
- BootPolicy - Policy for Open Image File.
- Pe32Handle - The handle of PE32 image
- Image - PE image to be loaded
- DstBuffer - The buffer to store the image
- EntryPoint - A pointer to the entry point
- Attribute - The bit mask of attributes to set for the load PE image
-
-Returns:
-
- EFI_SUCCESS - The file was loaded, relocated, and invoked
-
- EFI_OUT_OF_RESOURCES - There was not enough memory to load and relocate the PE/COFF file
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_BUFFER_TOO_SMALL - Buffer for image is too small
-
---*/
;
+
+/**
+ Get the image's private data from its handle.
+
+ @param ImageHandle The image handle
+
+ @return Return the image private data associated with ImageHandle.
+
+**/
LOADED_IMAGE_PRIVATE_DATA *
CoreLoadedImageInfo (
IN EFI_HANDLE ImageHandle
)
-/*++
-
-Routine Description:
-
- TODO: Add function description
-
-Arguments:
-
- ImageHandle - TODO: add argument description
-
-Returns:
-
- TODO: add return values
-
---*/
;
+
+/**
+ Unloads EFI image from memory.
+
+ @param Image EFI image
+ @param FreePage Free allocated pages
+
+**/
VOID
CoreUnloadAndCloseImage (
IN LOADED_IMAGE_PRIVATE_DATA *Image,
IN BOOLEAN FreePage
)
-/*++
-
-Routine Description:
-
- Unloads EFI image from memory.
-
-Arguments:
-
- Image - EFI image
- FreePage - Free allocated pages
-
-Returns:
-
- None
-
---*/
;
@@ -301,6 +259,36 @@ Returns:
// Exported Image functions
//
+
+/**
+ Loads an EFI image into memory and returns a handle to the image with extended parameters.
+
+ @param This Calling context
+ @param ParentImageHandle The caller's image handle.
+ @param FilePath The specific file path from which the image is
+ loaded.
+ @param SourceBuffer If not NULL, a pointer to the memory location
+ containing a copy of the image to be loaded.
+ @param SourceSize The size in bytes of SourceBuffer.
+ @param DstBuffer The buffer to store the image.
+ @param NumberOfPages For input, specifies the space size of the
+ image by caller if not NULL. For output,
+ specifies the actual space size needed.
+ @param ImageHandle Image handle for output.
+ @param EntryPoint Image entry point for output.
+ @param Attribute The bit mask of attributes to set for the load
+ PE image.
+
+ @retval EFI_SUCCESS The image was loaded into memory.
+ @retval EFI_NOT_FOUND The FilePath was not found.
+ @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
+ @retval EFI_UNSUPPORTED The image type is not supported, or the device
+ path cannot be parsed to locate the proper
+ protocol for loading the file.
+ @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
+ resources.
+
+**/
EFI_STATUS
EFIAPI
CoreLoadImageEx (
@@ -315,63 +303,25 @@ CoreLoadImageEx (
OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,
IN UINT32 Attribute
)
-/*++
-
-Routine Description:
-
- Loads an EFI image into memory and returns a handle to the image with extended parameters.
-
-Arguments:
-
- ParentImageHandle - The caller's image handle.
- FilePath - The specific file path from which the image is loaded.
- SourceBuffer - If not NULL, a pointer to the memory location containing a copy of
- the image to be loaded.
- SourceSize - The size in bytes of SourceBuffer.
- DstBuffer - The buffer to store the image.
- NumberOfPages - For input, specifies the space size of the image by caller if not NULL.
- For output, specifies the actual space size needed.
- ImageHandle - Image handle for output.
- EntryPoint - Image entry point for output.
- Attribute - The bit mask of attributes to set for the load PE image.
-
-Returns:
-
- EFI_SUCCESS - The image was loaded into memory.
- EFI_NOT_FOUND - The FilePath was not found.
- EFI_INVALID_PARAMETER - One of the parameters has an invalid value.
- EFI_UNSUPPORTED - The image type is not supported, or the device path cannot be
- parsed to locate the proper protocol for loading the file.
- EFI_OUT_OF_RESOURCES - Image was not loaded due to insufficient resources.
---*/
;
+
+/**
+ Unload the specified image.
+
+ @param This Indicates the calling context.
+ @param ImageHandle The specified image handle.
+
+ @retval EFI_INVALID_PARAMETER Image handle is NULL.
+ @retval EFI_UNSUPPORTED Attempt to unload an unsupported image.
+ @retval EFI_SUCCESS Image successfully unloaded.
+
+**/
EFI_STATUS
EFIAPI
CoreUnloadImageEx (
IN EFI_PE32_IMAGE_PROTOCOL *This,
IN EFI_HANDLE ImageHandle
)
-/*++
-
-Routine Description:
-
- Unload the specified image.
-
-Arguments:
-
- This - Indicates the calling context.
-
- ImageHandle - The specified image handle.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Image handle is NULL.
-
- EFI_UNSUPPORTED - Attempt to unload an unsupported image.
-
- EFI_SUCCESS - Image successfully unloaded.
-
---*/
;
#endif
diff --git a/MdeModulePkg/Core/Dxe/Image/Image.c b/MdeModulePkg/Core/Dxe/Image/Image.c
index 95528b8996..7c66f07d76 100644
--- a/MdeModulePkg/Core/Dxe/Image/Image.c
+++ b/MdeModulePkg/Core/Dxe/Image/Image.c
@@ -72,26 +72,20 @@ LOADED_IMAGE_PRIVATE_DATA mCorePrivateImage = {
};
+
+/**
+ Add the Image Services to EFI Boot Services Table and install the protocol
+ interfaces for this image.
+
+ @param HobStart The HOB to initialize
+
+ @return Status code.
+
+**/
EFI_STATUS
CoreInitializeImageServices (
IN VOID *HobStart
)
-/*++
-
-Routine Description:
-
- Add the Image Services to EFI Boot Services Table and install the protocol
- interfaces for this image.
-
-Arguments:
-
- HobStart - The HOB to initialize
-
-Returns:
-
- Status code.
-
---*/
{
EFI_STATUS Status;
LOADED_IMAGE_PRIVATE_DATA *Image;
@@ -161,6 +155,28 @@ Returns:
);
}
+
+/**
+ Loads, relocates, and invokes a PE/COFF image
+
+ @param BootPolicy If TRUE, indicates that the request originates
+ from the boot manager, and that the boot
+ manager is attempting to load FilePath as a
+ boot selection.
+ @param Pe32Handle The handle of PE32 image
+ @param Image PE image to be loaded
+ @param DstBuffer The buffer to store the image
+ @param EntryPoint A pointer to the entry point
+ @param Attribute The bit mask of attributes to set for the load
+ PE image
+
+ @retval EFI_SUCCESS The file was loaded, relocated, and invoked
+ @retval EFI_OUT_OF_RESOURCES There was not enough memory to load and
+ relocate the PE/COFF file
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_BUFFER_TOO_SMALL Buffer for image is too small
+
+**/
EFI_STATUS
CoreLoadPeImage (
IN BOOLEAN BootPolicy,
@@ -170,32 +186,6 @@ CoreLoadPeImage (
OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,
IN UINT32 Attribute
)
-/*++
-
-Routine Description:
-
- Loads, relocates, and invokes a PE/COFF image
-
-Arguments:
- BootPolicy - If TRUE, indicates that the request originates from the boot manager,
- and that the boot manager is attempting to load FilePath as a boot selection.
- Pe32Handle - The handle of PE32 image
- Image - PE image to be loaded
- DstBuffer - The buffer to store the image
- EntryPoint - A pointer to the entry point
- Attribute - The bit mask of attributes to set for the load PE image
-
-Returns:
-
- EFI_SUCCESS - The file was loaded, relocated, and invoked
-
- EFI_OUT_OF_RESOURCES - There was not enough memory to load and relocate the PE/COFF file
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_BUFFER_TOO_SMALL - Buffer for image is too small
-
---*/
{
EFI_STATUS Status;
BOOLEAN DstBufAlocated;
@@ -477,7 +467,7 @@ Returns:
CHAR8 EfiFileName[256];
if (Image->ImageContext.Machine != IMAGE_FILE_MACHINE_IA64) {
- DEBUG ((EFI_D_INFO | EFI_D_LOAD,
+ DEBUG ((DEBUG_INFO | DEBUG_LOAD,
"Loading driver at 0x%10p EntryPoint=0x%10p ",
(VOID *)(UINTN)Image->ImageContext.ImageAddress,
(VOID *)(UINTN)Image->ImageContext.EntryPoint));
@@ -485,7 +475,7 @@ Returns:
//
// For IPF Image, the real entry point should be print.
//
- DEBUG ((EFI_D_INFO | EFI_D_LOAD,
+ DEBUG ((DEBUG_INFO | DEBUG_LOAD,
"Loading driver at 0x%10p EntryPoint=0x%10p ",
(VOID *)(UINTN)Image->ImageContext.ImageAddress,
(VOID *)(UINTN)(*(UINT64 *)(UINTN)Image->ImageContext.EntryPoint)));
@@ -517,9 +507,9 @@ Returns:
break;
}
}
- DEBUG ((EFI_D_INFO | EFI_D_LOAD, "%a", EfiFileName)); // &Image->ImageContext.PdbPointer[StartIndex]));
+ DEBUG ((DEBUG_INFO | DEBUG_LOAD, "%a", EfiFileName)); // &Image->ImageContext.PdbPointer[StartIndex]));
}
- DEBUG ((EFI_D_INFO | EFI_D_LOAD, "\n"));
+ DEBUG ((DEBUG_INFO | DEBUG_LOAD, "\n"));
DEBUG_CODE_END ();
@@ -543,25 +533,19 @@ Done:
}
+
+/**
+ Get the image's private data from its handle.
+
+ @param ImageHandle The image handle
+
+ @return Return the image private data associated with ImageHandle.
+
+**/
LOADED_IMAGE_PRIVATE_DATA *
CoreLoadedImageInfo (
IN EFI_HANDLE ImageHandle
)
-/*++
-
-Routine Description:
-
- Get the image's private data from its handle.
-
-Arguments:
-
- ImageHandle - The image handle
-
-Returns:
-
- Return the image private data associated with ImageHandle.
-
---*/
{
EFI_STATUS Status;
EFI_LOADED_IMAGE_PROTOCOL *LoadedImage;
@@ -575,13 +559,50 @@ Returns:
if (!EFI_ERROR (Status)) {
Image = LOADED_IMAGE_PRIVATE_DATA_FROM_THIS (LoadedImage);
} else {
- DEBUG ((EFI_D_LOAD, "CoreLoadedImageInfo: Not an ImageHandle %x\n", ImageHandle));
+ DEBUG ((DEBUG_LOAD, "CoreLoadedImageInfo: Not an ImageHandle %x\n", ImageHandle));
Image = NULL;
}
return Image;
}
+
+/**
+ Loads an EFI image into memory and returns a handle to the image.
+
+ @param BootPolicy If TRUE, indicates that the request originates
+ from the boot manager, and that the boot
+ manager is attempting to load FilePath as a
+ boot selection.
+ @param ParentImageHandle The caller's image handle.
+ @param FilePath The specific file path from which the image is
+ loaded.
+ @param SourceBuffer If not NULL, a pointer to the memory location
+ containing a copy of the image to be loaded.
+ @param SourceSize The size in bytes of SourceBuffer.
+ @param DstBuffer The buffer to store the image
+ @param NumberOfPages If not NULL, it inputs a pointer to the page
+ number of DstBuffer and outputs a pointer to
+ the page number of the image. If this number is
+ not enough, return EFI_BUFFER_TOO_SMALL and
+ this parameter contains the required number.
+ @param ImageHandle Pointer to the returned image handle that is
+ created when the image is successfully loaded.
+ @param EntryPoint A pointer to the entry point
+ @param Attribute The bit mask of attributes to set for the load
+ PE image
+
+ @retval EFI_SUCCESS The image was loaded into memory.
+ @retval EFI_NOT_FOUND The FilePath was not found.
+ @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
+ @retval EFI_BUFFER_TOO_SMALL The buffer is too small
+ @retval EFI_UNSUPPORTED The image type is not supported, or the device
+ path cannot be parsed to locate the proper
+ protocol for loading the file.
+ @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
+ resources.
+
+**/
STATIC
EFI_STATUS
CoreLoadImageCommon (
@@ -596,40 +617,6 @@ CoreLoadImageCommon (
OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,
IN UINT32 Attribute
)
-/*++
-
-Routine Description:
-
- Loads an EFI image into memory and returns a handle to the image.
-
-Arguments:
-
- BootPolicy - If TRUE, indicates that the request originates from the boot manager,
- and that the boot manager is attempting to load FilePath as a boot selection.
- ParentImageHandle - The caller's image handle.
- FilePath - The specific file path from which the image is loaded.
- SourceBuffer - If not NULL, a pointer to the memory location containing a copy of
- the image to be loaded.
- SourceSize - The size in bytes of SourceBuffer.
- DstBuffer - The buffer to store the image
- NumberOfPages - If not NULL, it inputs a pointer to the page number of DstBuffer and outputs
- a pointer to the page number of the image. If this number is not enough,
- return EFI_BUFFER_TOO_SMALL and this parameter contains the required number.
- ImageHandle - Pointer to the returned image handle that is created when the image
- is successfully loaded.
- EntryPoint - A pointer to the entry point
- Attribute - The bit mask of attributes to set for the load PE image
-
-Returns:
-
- EFI_SUCCESS - The image was loaded into memory.
- EFI_NOT_FOUND - The FilePath was not found.
- EFI_INVALID_PARAMETER - One of the parameters has an invalid value.
- EFI_BUFFER_TOO_SMALL - The buffer is too small
- EFI_UNSUPPORTED - The image type is not supported, or the device path cannot be
- parsed to locate the proper protocol for loading the file.
- EFI_OUT_OF_RESOURCES - Image was not loaded due to insufficient resources.
---*/
{
LOADED_IMAGE_PRIVATE_DATA *Image;
LOADED_IMAGE_PRIVATE_DATA *ParentImage;
@@ -656,7 +643,7 @@ Returns:
ParentImage = CoreLoadedImageInfo (ParentImageHandle);
if (ParentImage == NULL) {
- DEBUG((EFI_D_LOAD|EFI_D_ERROR, "LoadImageEx: Parent handle not an image handle\n"));
+ DEBUG((DEBUG_LOAD|DEBUG_ERROR, "LoadImageEx: Parent handle not an image handle\n"));
return EFI_INVALID_PARAMETER;
}
@@ -721,7 +708,7 @@ Returns:
Image->Signature = LOADED_IMAGE_PRIVATE_DATA_SIGNATURE;
Image->Info.SystemTable = gDxeCoreST;
Image->Info.DeviceHandle = DeviceHandle;
- Image->Info.Revision = EFI_LOADED_IMAGE_INFORMATION_REVISION;
+ Image->Info.Revision = EFI_LOADED_IMAGE_PROTOCOL_REVISION;
Image->Info.FilePath = CoreDuplicateDevicePath (FilePath);
Image->Info.ParentHandle = ParentImageHandle;
@@ -836,6 +823,33 @@ Done:
+
+/**
+ Loads an EFI image into memory and returns a handle to the image.
+
+ @param BootPolicy If TRUE, indicates that the request originates
+ from the boot manager, and that the boot
+ manager is attempting to load FilePath as a
+ boot selection.
+ @param ParentImageHandle The caller's image handle.
+ @param FilePath The specific file path from which the image is
+ loaded.
+ @param SourceBuffer If not NULL, a pointer to the memory location
+ containing a copy of the image to be loaded.
+ @param SourceSize The size in bytes of SourceBuffer.
+ @param ImageHandle Pointer to the returned image handle that is
+ created when the image is successfully loaded.
+
+ @retval EFI_SUCCESS The image was loaded into memory.
+ @retval EFI_NOT_FOUND The FilePath was not found.
+ @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
+ @retval EFI_UNSUPPORTED The image type is not supported, or the device
+ path cannot be parsed to locate the proper
+ protocol for loading the file.
+ @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
+ resources.
+
+**/
EFI_STATUS
EFIAPI
CoreLoadImage (
@@ -846,33 +860,6 @@ CoreLoadImage (
IN UINTN SourceSize,
OUT EFI_HANDLE *ImageHandle
)
-/*++
-
-Routine Description:
-
- Loads an EFI image into memory and returns a handle to the image.
-
-Arguments:
-
- BootPolicy - If TRUE, indicates that the request originates from the boot manager,
- and that the boot manager is attempting to load FilePath as a boot selection.
- ParentImageHandle - The caller's image handle.
- FilePath - The specific file path from which the image is loaded.
- SourceBuffer - If not NULL, a pointer to the memory location containing a copy of
- the image to be loaded.
- SourceSize - The size in bytes of SourceBuffer.
- ImageHandle - Pointer to the returned image handle that is created when the image
- is successfully loaded.
-
-Returns:
-
- EFI_SUCCESS - The image was loaded into memory.
- EFI_NOT_FOUND - The FilePath was not found.
- EFI_INVALID_PARAMETER - One of the parameters has an invalid value.
- EFI_UNSUPPORTED - The image type is not supported, or the device path cannot be
- parsed to locate the proper protocol for loading the file.
- EFI_OUT_OF_RESOURCES - Image was not loaded due to insufficient resources.
---*/
{
EFI_STATUS Status;
@@ -897,6 +884,36 @@ Returns:
}
+
+/**
+ Loads an EFI image into memory and returns a handle to the image with extended parameters.
+
+ @param This Calling context
+ @param ParentImageHandle The caller's image handle.
+ @param FilePath The specific file path from which the image is
+ loaded.
+ @param SourceBuffer If not NULL, a pointer to the memory location
+ containing a copy of the image to be loaded.
+ @param SourceSize The size in bytes of SourceBuffer.
+ @param DstBuffer The buffer to store the image.
+ @param NumberOfPages For input, specifies the space size of the
+ image by caller if not NULL. For output,
+ specifies the actual space size needed.
+ @param ImageHandle Image handle for output.
+ @param EntryPoint Image entry point for output.
+ @param Attribute The bit mask of attributes to set for the load
+ PE image.
+
+ @retval EFI_SUCCESS The image was loaded into memory.
+ @retval EFI_NOT_FOUND The FilePath was not found.
+ @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
+ @retval EFI_UNSUPPORTED The image type is not supported, or the device
+ path cannot be parsed to locate the proper
+ protocol for loading the file.
+ @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
+ resources.
+
+**/
EFI_STATUS
EFIAPI
CoreLoadImageEx (
@@ -911,36 +928,6 @@ CoreLoadImageEx (
OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,
IN UINT32 Attribute
)
-/*++
-
-Routine Description:
-
- Loads an EFI image into memory and returns a handle to the image with extended parameters.
-
-Arguments:
-
- This - Calling context
- ParentImageHandle - The caller's image handle.
- FilePath - The specific file path from which the image is loaded.
- SourceBuffer - If not NULL, a pointer to the memory location containing a copy of
- the image to be loaded.
- SourceSize - The size in bytes of SourceBuffer.
- DstBuffer - The buffer to store the image.
- NumberOfPages - For input, specifies the space size of the image by caller if not NULL.
- For output, specifies the actual space size needed.
- ImageHandle - Image handle for output.
- EntryPoint - Image entry point for output.
- Attribute - The bit mask of attributes to set for the load PE image.
-
-Returns:
-
- EFI_SUCCESS - The image was loaded into memory.
- EFI_NOT_FOUND - The FilePath was not found.
- EFI_INVALID_PARAMETER - One of the parameters has an invalid value.
- EFI_UNSUPPORTED - The image type is not supported, or the device path cannot be
- parsed to locate the proper protocol for loading the file.
- EFI_OUT_OF_RESOURCES - Image was not loaded due to insufficient resources.
---*/
{
return CoreLoadImageCommon (
TRUE,
@@ -956,6 +943,25 @@ Returns:
);
}
+
+/**
+ Transfer control to a loaded image's entry point.
+
+ @param ImageHandle Handle of image to be started.
+ @param ExitDataSize Pointer of the size to ExitData
+ @param ExitData Pointer to a pointer to a data buffer that
+ includes a Null-terminated Unicode string,
+ optionally followed by additional binary data.
+ The string is a description that the caller may
+ use to further indicate the reason for the
+ image's exit.
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
+ @retval EFI_SUCCESS Successfully transfer control to the image's
+ entry point.
+
+**/
EFI_STATUS
EFIAPI
CoreStartImage (
@@ -963,32 +969,6 @@ CoreStartImage (
OUT UINTN *ExitDataSize,
OUT CHAR16 **ExitData OPTIONAL
)
-/*++
-
-Routine Description:
-
- Transfer control to a loaded image's entry point.
-
-Arguments:
-
- ImageHandle - Handle of image to be started.
-
- ExitDataSize - Pointer of the size to ExitData
-
- ExitData - Pointer to a pointer to a data buffer that includes a Null-terminated
- Unicode string, optionally followed by additional binary data. The string
- is a description that the caller may use to further indicate the reason for
- the image's exit.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_OUT_OF_RESOURCES - No enough buffer to allocate
-
- EFI_SUCCESS - Successfully transfer control to the image's entry point.
-
---*/
{
EFI_STATUS Status;
LOADED_IMAGE_PRIVATE_DATA *Image;
@@ -1048,7 +1028,7 @@ Returns:
//
DEBUG_CODE_BEGIN ();
if (EFI_ERROR (Image->Status)) {
- DEBUG ((EFI_D_ERROR, "Error: Image at %10p start failed: %r\n", Image->Info.ImageBase, Image->Status));
+ DEBUG ((DEBUG_ERROR, "Error: Image at %10p start failed: %r\n", Image->Info.ImageBase, Image->Status));
}
DEBUG_CODE_END ();
@@ -1083,15 +1063,15 @@ Returns:
if (Image->ExitDataSize != 0 || Image->ExitData != NULL) {
DEBUG (
- (EFI_D_LOAD,
+ (DEBUG_LOAD,
"StartImage: ExitDataSize %d, ExitData %x",
Image->ExitDataSize,
Image->ExitData)
);
if (Image->ExitData != NULL) {
- DEBUG ((EFI_D_LOAD, " (%hs)", Image->ExitData));
+ DEBUG ((DEBUG_LOAD, " (%hs)", Image->ExitData));
}
- DEBUG ((EFI_D_LOAD, "\n"));
+ DEBUG ((DEBUG_LOAD, "\n"));
}
DEBUG_CODE_END ();
@@ -1130,27 +1110,19 @@ Returns:
}
+
+/**
+ Unloads EFI image from memory.
+
+ @param Image EFI image
+ @param FreePage Free allocated pages
+
+**/
VOID
CoreUnloadAndCloseImage (
IN LOADED_IMAGE_PRIVATE_DATA *Image,
IN BOOLEAN FreePage
)
-/*++
-
-Routine Description:
-
- Unloads EFI image from memory.
-
-Arguments:
-
- Image - EFI image
- FreePage - Free allocated pages
-
-Returns:
-
- None
-
---*/
{
EFI_STATUS Status;
UINTN HandleCount;
@@ -1281,6 +1253,30 @@ Returns:
+
+/**
+ Terminates the currently loaded EFI image and returns control to boot services.
+
+ @param ImageHandle Handle that identifies the image. This
+ parameter is passed to the image on entry.
+ @param Status The image's exit code.
+ @param ExitDataSize The size, in bytes, of ExitData. Ignored if
+ ExitStatus is EFI_SUCCESS.
+ @param ExitData Pointer to a data buffer that includes a
+ Null-terminated Unicode string, optionally
+ followed by additional binary data. The string
+ is a description that the caller may use to
+ further indicate the reason for the image's
+ exit.
+
+ @retval EFI_INVALID_PARAMETER Image handle is NULL or it is not current
+ image.
+ @retval EFI_SUCCESS Successfully terminates the currently loaded
+ EFI image.
+ @retval EFI_ACCESS_DENIED Should never reach there.
+ @retval EFI_OUT_OF_RESOURCES Could not allocate pool
+
+**/
EFI_STATUS
EFIAPI
CoreExit (
@@ -1289,35 +1285,6 @@ CoreExit (
IN UINTN ExitDataSize,
IN CHAR16 *ExitData OPTIONAL
)
-/*++
-
-Routine Description:
-
- Terminates the currently loaded EFI image and returns control to boot services.
-
-Arguments:
-
- ImageHandle - Handle that identifies the image. This parameter is passed to the image
- on entry.
- Status - The image's exit code.
- ExitDataSize - The size, in bytes, of ExitData. Ignored if ExitStatus is
- EFI_SUCCESS.
- ExitData - Pointer to a data buffer that includes a Null-terminated Unicode string,
- optionally followed by additional binary data. The string is a
- description that the caller may use to further indicate the reason for
- the image's exit.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Image handle is NULL or it is not current image.
-
- EFI_SUCCESS - Successfully terminates the currently loaded EFI image.
-
- EFI_ACCESS_DENIED - Should never reach there.
-
- EFI_OUT_OF_RESOURCES - Could not allocate pool
-
---*/
{
LOADED_IMAGE_PRIVATE_DATA *Image;
EFI_TPL OldTpl;
@@ -1347,7 +1314,7 @@ Returns:
// Image has been started, verify this image can exit
//
if (Image != mCurrentImage) {
- DEBUG ((EFI_D_LOAD|EFI_D_ERROR, "Exit: Image is not exitable image\n"));
+ DEBUG ((DEBUG_LOAD|DEBUG_ERROR, "Exit: Image is not exitable image\n"));
Status = EFI_INVALID_PARAMETER;
goto Done;
}
@@ -1388,28 +1355,24 @@ Done:
+
+/**
+ Unloads an image.
+
+ @param ImageHandle Handle that identifies the image to be
+ unloaded.
+
+ @retval EFI_SUCCESS The image has been unloaded.
+ @retval EFI_UNSUPPORTED The image has been sarted, and does not support
+ unload.
+ @retval EFI_INVALID_PARAMPETER ImageHandle is not a valid image handle.
+
+**/
EFI_STATUS
EFIAPI
CoreUnloadImage (
IN EFI_HANDLE ImageHandle
)
-/*++
-
-Routine Description:
-
- Unloads an image.
-
-Arguments:
-
- ImageHandle - Handle that identifies the image to be unloaded.
-
-Returns:
-
- EFI_SUCCESS - The image has been unloaded.
- EFI_UNSUPPORTED - The image has been sarted, and does not support unload.
- EFI_INVALID_PARAMPETER - ImageHandle is not a valid image handle.
-
---*/
{
EFI_STATUS Status;
LOADED_IMAGE_PRIVATE_DATA *Image;
@@ -1460,33 +1423,24 @@ Done:
}
+
+/**
+ Unload the specified image.
+
+ @param This Indicates the calling context.
+ @param ImageHandle The specified image handle.
+
+ @retval EFI_INVALID_PARAMETER Image handle is NULL.
+ @retval EFI_UNSUPPORTED Attempt to unload an unsupported image.
+ @retval EFI_SUCCESS Image successfully unloaded.
+
+**/
EFI_STATUS
EFIAPI
CoreUnloadImageEx (
IN EFI_PE32_IMAGE_PROTOCOL *This,
IN EFI_HANDLE ImageHandle
)
-/*++
-
-Routine Description:
-
- Unload the specified image.
-
-Arguments:
-
- This - Indicates the calling context.
-
- ImageHandle - The specified image handle.
-
-Returns:
-
- EFI_INVALID_PARAMETER - Image handle is NULL.
-
- EFI_UNSUPPORTED - Attempt to unload an unsupported image.
-
- EFI_SUCCESS - Image successfully unloaded.
-
---*/
{
return CoreUnloadImage (ImageHandle);
}
diff --git a/MdeModulePkg/Core/Dxe/Image/ImageFile.c b/MdeModulePkg/Core/Dxe/Image/ImageFile.c
index 7ff867e181..7cb2576c4f 100644
--- a/MdeModulePkg/Core/Dxe/Image/ImageFile.c
+++ b/MdeModulePkg/Core/Dxe/Image/ImageFile.c
@@ -15,6 +15,30 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
#include <DxeMain.h>
+
+/**
+ Opens a file for (simple) reading. The simple read abstraction
+ will access the file either from a memory copy, from a file
+ system interface, or from the load file interface.
+
+ @param BootPolicy Policy for Open Image File.
+ @param SourceBuffer Pointer to the memory location containing copy
+ of the image to be loaded.
+ @param SourceSize The size in bytes of SourceBuffer.
+ @param FilePath The specific file path from which the image is
+ loaded
+ @param DeviceHandle Pointer to the return device handle.
+ @param ImageFileHandle Pointer to the image file handle.
+ @param AuthenticationStatus Pointer to a caller-allocated UINT32 in which
+ the authentication status is returned.
+
+ @retval EFI_SUCCESS Image file successfully opened.
+ @retval EFI_LOAD_ERROR If the caller passed a copy of the file, and
+ SourceSize is 0.
+ @retval EFI_INVALID_PARAMETER File path is not valid.
+ @retval EFI_NOT_FOUND File not found.
+
+**/
EFI_STATUS
CoreOpenImageFile (
IN BOOLEAN BootPolicy,
@@ -25,36 +49,6 @@ CoreOpenImageFile (
IN IMAGE_FILE_HANDLE *ImageFileHandle,
OUT UINT32 *AuthenticationStatus
)
-/*++
-
-Routine Description:
-
- Opens a file for (simple) reading. The simple read abstraction
- will access the file either from a memory copy, from a file
- system interface, or from the load file interface.
-
-Arguments:
-
- BootPolicy - Policy for Open Image File.
- SourceBuffer - Pointer to the memory location containing copy
- of the image to be loaded.
- SourceSize - The size in bytes of SourceBuffer.
- FilePath - The specific file path from which the image is loaded
- DeviceHandle - Pointer to the return device handle.
- ImageFileHandle - Pointer to the image file handle.
- AuthenticationStatus - Pointer to a caller-allocated UINT32 in which the authentication status is returned.
-
-Returns:
-
- EFI_SUCCESS - Image file successfully opened.
-
- EFI_LOAD_ERROR - If the caller passed a copy of the file, and SourceSize is 0.
-
- EFI_INVALID_PARAMETER - File path is not valid.
-
- EFI_NOT_FOUND - File not found.
-
---*/
{
EFI_STATUS Status;
EFI_DEVICE_PATH_PROTOCOL *TempFilePath;
@@ -318,7 +312,7 @@ Returns:
//
// Nothing else to try
//
- DEBUG ((EFI_D_LOAD|EFI_D_WARN, "CoreOpenImageFile: Device did not support a known load protocol\n"));
+ DEBUG ((DEBUG_LOAD|DEBUG_WARN, "CoreOpenImageFile: Device did not support a known load protocol\n"));
Status = EFI_NOT_FOUND;
Done:
@@ -340,6 +334,21 @@ Done:
+
+/**
+ Read image file (specified by UserHandle) into user specified buffer with specified offset
+ and length.
+
+ @param UserHandle Image file handle
+ @param Offset Offset to the source file
+ @param ReadSize For input, pointer of size to read; For output,
+ pointer of size actually read.
+ @param Buffer Buffer to write into
+
+ @retval EFI_SUCCESS Successfully read the specified part of file
+ into buffer.
+
+**/
EFI_STATUS
EFIAPI
CoreReadImageFile (
@@ -348,29 +357,6 @@ CoreReadImageFile (
IN OUT UINTN *ReadSize,
OUT VOID *Buffer
)
-/*++
-
-Routine Description:
-
- Read image file (specified by UserHandle) into user specified buffer with specified offset
- and length.
-
-Arguments:
-
- UserHandle - Image file handle
-
- Offset - Offset to the source file
-
- ReadSize - For input, pointer of size to read;
- For output, pointer of size actually read.
-
- Buffer - Buffer to write into
-
-Returns:
-
- EFI_SUCCESS - Successfully read the specified part of file into buffer.
-
---*/
{
UINTN EndPosition;
IMAGE_FILE_HANDLE *FHand;
@@ -393,6 +379,20 @@ Returns:
return EFI_SUCCESS;
}
+
+/**
+ Search a handle to a device on a specified device path that supports a specified protocol,
+ interface of that protocol on that handle is another output.
+
+ @param Protocol The protocol to search for
+ @param FilePath The specified device path
+ @param Interface Interface of the protocol on the handle
+ @param Handle The handle to the device on the specified device
+ path that supports the protocol.
+
+ @return Status code.
+
+**/
EFI_STATUS
CoreDevicePathToInterface (
IN EFI_GUID *Protocol,
@@ -400,28 +400,6 @@ CoreDevicePathToInterface (
OUT VOID **Interface,
OUT EFI_HANDLE *Handle
)
-/*++
-
-Routine Description:
-
- Search a handle to a device on a specified device path that supports a specified protocol,
- interface of that protocol on that handle is another output.
-
-Arguments:
-
- Protocol - The protocol to search for
-
- FilePath - The specified device path
-
- Interface - Interface of the protocol on the handle
-
- Handle - The handle to the device on the specified device path that supports the protocol.
-
-Returns:
-
- Status code.
-
---*/
{
EFI_STATUS Status;
@@ -432,37 +410,28 @@ Returns:
return Status;
}
+
+/**
+ Helper function called as part of the code needed
+ to allocate the proper sized buffer for various
+ EFI interfaces.
+
+ @param Status Current status
+ @param Buffer Current allocated buffer, or NULL
+ @param BufferSize Current buffer size needed
+
+ @retval TRUE if the buffer was reallocated and the caller
+ should try the API again.
+ @retval FALSE buffer could not be allocated and the caller
+ should not try the API again.
+
+**/
BOOLEAN
CoreGrowBuffer (
IN OUT EFI_STATUS *Status,
IN OUT VOID **Buffer,
IN UINTN BufferSize
)
-/*++
-
-Routine Description:
-
- Helper function called as part of the code needed
- to allocate the proper sized buffer for various
- EFI interfaces.
-
-Arguments:
-
- Status - Current status
-
- Buffer - Current allocated buffer, or NULL
-
- BufferSize - Current buffer size needed
-
-Returns:
-
- TRUE - if the buffer was reallocated and the caller
- should try the API again.
-
- FALSE - buffer could not be allocated and the caller
- should not try the API again.
-
---*/
{
BOOLEAN TryAgain;
@@ -506,3 +475,4 @@ Returns:
return TryAgain;
}
+
diff --git a/MdeModulePkg/Core/Dxe/Library.h b/MdeModulePkg/Core/Dxe/Library.h
index 7c15c938e2..067f0dab5e 100644
--- a/MdeModulePkg/Core/Dxe/Library.h
+++ b/MdeModulePkg/Core/Dxe/Library.h
@@ -11,356 +11,286 @@ http://opensource.org/licenses/bsd-license.php
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
---*/
+
+**/
#ifndef _DXE_LIBRARY_H_
#define _DXE_LIBRARY_H_
+
+/**
+ Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid.
+
+ @param Value Describes the class/subclass/operation of the
+ hardware or software entity that the Status Code
+ relates to.
+
+**/
VOID
CoreReportProgressCode (
IN EFI_STATUS_CODE_VALUE Value
)
-/*++
-
-Routine Description:
-
- Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid.
-
-Arguments:
-
- Value - Describes the class/subclass/operation of the hardware or software entity
- that the Status Code relates to.
-
-Returns:
-
- None
-
---*/
;
+
+/**
+ Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid,
+ with a handle as additional information.
+
+ @param Value Describes the class/subclass/operation of the
+ hardware or software entity that the Status Code
+ relates to.
+ @param Handle Additional information.
+
+**/
VOID
CoreReportProgressCodeSpecific (
IN EFI_STATUS_CODE_VALUE Value,
IN EFI_HANDLE Handle
)
-/*++
-
-Routine Description:
-
- Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid,
- with a handle as additional information.
-
-Arguments:
-
- Value - Describes the class/subclass/operation of the hardware or software entity
- that the Status Code relates to.
-
- Handle - Additional information.
-
-Returns:
-
- None
-
---*/
;
+
+/**
+ Raising to the task priority level of the mutual exclusion
+ lock, and then acquires ownership of the lock.
+
+ @param Lock The lock to acquire
+
+ @return Lock owned
+
+**/
VOID
CoreAcquireLock (
IN EFI_LOCK *Lock
)
-/*++
-
-Routine Description:
-
- Raising to the task priority level of the mutual exclusion
- lock, and then acquires ownership of the lock.
-
-Arguments:
-
- Lock - The lock to acquire
-
-Returns:
-
- Lock owned
-
---*/
;
-EFI_STATUS
-CoreAcquireLockOrFail (
- IN EFI_LOCK *Lock
- )
-/*++
-
-Routine Description:
+/**
Initialize a basic mutual exclusion lock. Each lock
provides mutual exclusion access at it's task priority
level. Since there is no-premption (at any TPL) or
multiprocessor support, acquiring the lock only consists
of raising to the locks TPL.
-
-Arguments:
- Lock - The EFI_LOCK structure to initialize
-
-Returns:
+ @param Lock The EFI_LOCK structure to initialize
- EFI_SUCCESS - Lock Owned.
- EFI_ACCESS_DENIED - Reentrant Lock Acquisition, Lock not Owned.
+ @retval EFI_SUCCESS Lock Owned.
+ @retval EFI_ACCESS_DENIED Reentrant Lock Acquisition, Lock not Owned.
---*/
+**/
+EFI_STATUS
+CoreAcquireLockOrFail (
+ IN EFI_LOCK *Lock
+ )
;
+
+/**
+ Releases ownership of the mutual exclusion lock, and
+ restores the previous task priority level.
+
+ @param Lock The lock to release
+
+ @return Lock unowned
+
+**/
VOID
CoreReleaseLock (
IN EFI_LOCK *Lock
)
-/*++
-
-Routine Description:
-
- Releases ownership of the mutual exclusion lock, and
- restores the previous task priority level.
-
-Arguments:
-
- Lock - The lock to release
-
-Returns:
-
- Lock unowned
-
---*/
;
//
// Device Path functions
//
+
+/**
+ Calculate the size of a whole device path.
+
+ @param DevicePath The pointer to the device path data.
+
+ @return Size of device path data structure..
+
+**/
UINTN
CoreDevicePathSize (
IN EFI_DEVICE_PATH_PROTOCOL *DevicePath
)
-/*++
-
-Routine Description:
-
- Calculate the size of a whole device path.
-
-Arguments:
-
- DevicePath - The pointer to the device path data.
-
-Returns:
-
- Size of device path data structure..
-
---*/
;
+
+/**
+ Return TRUE is this is a multi instance device path.
+
+ @param DevicePath A pointer to a device path data structure.
+
+ @retval TRUE If DevicePath is multi instance. FALSE - If
+ DevicePath is not multi instance.
+
+**/
BOOLEAN
CoreIsDevicePathMultiInstance (
IN EFI_DEVICE_PATH_PROTOCOL *DevicePath
)
-/*++
-
-Routine Description:
- Return TRUE is this is a multi instance device path.
-
-Arguments:
- DevicePath - A pointer to a device path data structure.
-
-
-Returns:
- TRUE - If DevicePath is multi instance. FALSE - If DevicePath is not multi
- instance.
-
---*/
;
+
+/**
+ Duplicate a new device path data structure from the old one.
+
+ @param DevicePath A pointer to a device path data structure.
+
+ @return A pointer to the new allocated device path data.
+ @return Caller must free the memory used by DevicePath if it is no longer needed.
+
+**/
EFI_DEVICE_PATH_PROTOCOL *
CoreDuplicateDevicePath (
IN EFI_DEVICE_PATH_PROTOCOL *DevicePath
)
-/*++
-
-Routine Description:
- Duplicate a new device path data structure from the old one.
-
-Arguments:
- DevicePath - A pointer to a device path data structure.
-
-Returns:
- A pointer to the new allocated device path data.
- Caller must free the memory used by DevicePath if it is no longer needed.
-
---*/
;
+
+/**
+ Function is used to append a Src1 and Src2 together.
+
+ @param Src1 A pointer to a device path data structure.
+ @param Src2 A pointer to a device path data structure.
+
+ @return A pointer to the new device path is returned.
+ @return NULL is returned if space for the new device path could not be allocated from pool.
+ @return It is up to the caller to free the memory used by Src1 and Src2 if they are no longer needed.
+
+**/
EFI_DEVICE_PATH_PROTOCOL *
CoreAppendDevicePath (
IN EFI_DEVICE_PATH_PROTOCOL *Src1,
- IN EFI_DEVICE_PATH_PROTOCOL *Node
+ IN EFI_DEVICE_PATH_PROTOCOL *Src2
)
-/*++
-
-Routine Description:
- Function is used to append a Src1 and Src2 together.
-
-Arguments:
- Src1 - A pointer to a device path data structure.
-
- Node - A pointer to a device path data structure.
-
-Returns:
-
- A pointer to the new device path is returned.
- NULL is returned if space for the new device path could not be allocated from pool.
- It is up to the caller to free the memory used by Src1 and Src2 if they are no longer needed.
-
---*/
;
+
+/**
+ Allocate pool of type EfiBootServicesData, the size is specified with AllocationSize.
+
+ @param AllocationSize Size to allocate.
+
+ @return Pointer of the allocated pool.
+
+**/
VOID *
CoreAllocateBootServicesPool (
IN UINTN AllocationSize
)
-/*++
-
-Routine Description:
-
- Allocate pool of type EfiBootServicesData, the size is specified with AllocationSize.
-
-Arguments:
-
- AllocationSize - Size to allocate.
-
-Returns:
-
- Pointer of the allocated pool.
-
---*/
;
+
+/**
+ Allocate pool of type EfiBootServicesData and zero it, the size is specified with AllocationSize.
+
+ @param AllocationSize Size to allocate.
+
+ @return Pointer of the allocated pool.
+
+**/
VOID *
CoreAllocateZeroBootServicesPool (
IN UINTN AllocationSize
)
-/*++
-
-Routine Description:
-
- Allocate pool of type EfiBootServicesData and zero it, the size is specified with AllocationSize.
-
-Arguments:
-
- AllocationSize - Size to allocate.
-
-Returns:
-
- Pointer of the allocated pool.
-
---*/
;
+
+/**
+ Find a config table by name in system table's ConfigurationTable.
+
+ @param Guid The table name to look for
+ @param Table Pointer of the config table
+
+ @retval EFI_NOT_FOUND Could not find the table in system table's
+ ConfigurationTable.
+ @retval EFI_SUCCESS Table successfully found.
+
+**/
EFI_STATUS
CoreGetConfigTable (
IN EFI_GUID *Guid,
IN OUT VOID **Table
)
-/*++
-
-Routine Description:
-
- Find a config table by name in system table's ConfigurationTable.
-
-Arguments:
-
- Guid - The table name to look for
-
- Table - Pointer of the config table
-
-Returns:
-
- EFI_NOT_FOUND - Could not find the table in system table's ConfigurationTable.
-
- EFI_SUCCESS - Table successfully found.
-
---*/
;
+
+/**
+ Allocate pool of specified size with EfiRuntimeServicesData type, and copy specified buffer to this pool.
+
+ @param AllocationSize Size to allocate.
+ @param Buffer Specified buffer that will be copy to the allocated
+ pool
+
+ @return Pointer of the allocated pool.
+
+**/
VOID *
CoreAllocateRuntimeCopyPool (
IN UINTN AllocationSize,
IN VOID *Buffer
)
-/*++
-
-Routine Description:
-
- Allocate pool of specified size with EfiRuntimeServicesData type, and copy specified buffer to this pool.
-
-Arguments:
-
- AllocationSize - Size to allocate.
-
- Buffer - Specified buffer that will be copy to the allocated pool
-
-Returns:
-
- Pointer of the allocated pool.
-
---*/
;
+
+/**
+ Allocate pool of type EfiRuntimeServicesData, the size is specified with AllocationSize.
+
+ @param AllocationSize Size to allocate.
+
+ @return Pointer of the allocated pool.
+
+**/
VOID *
CoreAllocateRuntimePool (
IN UINTN AllocationSize
)
-/*++
-
-Routine Description:
-
- Allocate pool of type EfiRuntimeServicesData, the size is specified with AllocationSize.
-
-Arguments:
-
- AllocationSize - Size to allocate.
-
-Returns:
-
- Pointer of the allocated pool.
-
---*/
;
+
+/**
+ Allocate pool of specified size with EfiBootServicesData type, and copy specified buffer to this pool.
+
+ @param AllocationSize Size to allocate.
+ @param Buffer Specified buffer that will be copy to the allocated
+ pool
+
+ @return Pointer of the allocated pool.
+
+**/
VOID *
CoreAllocateCopyPool (
IN UINTN AllocationSize,
IN VOID *Buffer
)
-/*++
-
-Routine Description:
-
- Allocate pool of specified size with EfiBootServicesData type, and copy specified buffer to this pool.
-
-Arguments:
-
- AllocationSize - Size to allocate.
-
- Buffer - Specified buffer that will be copy to the allocated pool
-
-Returns:
-
- Pointer of the allocated pool.
-
---*/
;
+
+/**
+ Create a protocol notification event and return it.
+
+ @param ProtocolGuid Protocol to register notification event on.
+ @param NotifyTpl Maximum TPL to signal the NotifyFunction.
+ @param NotifyFunction EFI notification routine.
+ @param NotifyContext Context passed into Event when it is created.
+ @param Registration Registration key returned from
+ RegisterProtocolNotify().
+ @param SignalFlag Boolean value to decide whether kick the event after
+ register or not.
+
+ @return The EFI_EVENT that has been registered to be signaled when a ProtocolGuid
+ is added to the system.
+
+**/
EFI_EVENT
CoreCreateProtocolNotifyEvent (
IN EFI_GUID *ProtocolGuid,
@@ -370,32 +300,6 @@ CoreCreateProtocolNotifyEvent (
OUT VOID **Registration,
IN BOOLEAN SignalFlag
)
-/*++
-
-Routine Description:
-
- Create a protocol notification event and return it.
-
-Arguments:
-
- ProtocolGuid - Protocol to register notification event on.
-
- NotifyTpl - Maximum TPL to signal the NotifyFunction.
-
- NotifyFuncition - EFI notification routine.
-
- NotifyContext - Context passed into Event when it is created.
-
- Registration - Registration key returned from RegisterProtocolNotify().
-
- SignalFlag - Boolean value to decide whether kick the event after register or not.
-
-Returns:
-
- The EFI_EVENT that has been registered to be signaled when a ProtocolGuid
- is added to the system.
-
---*/
;
#endif
diff --git a/MdeModulePkg/Core/Dxe/Library/Library.c b/MdeModulePkg/Core/Dxe/Library/Library.c
index b0f9a0f55d..fa53788371 100644
--- a/MdeModulePkg/Core/Dxe/Library/Library.c
+++ b/MdeModulePkg/Core/Dxe/Library/Library.c
@@ -1,7 +1,7 @@
-/**@file
+/** @file
DXE Core library services.
-Copyright (c) 2006 - 2007, Intel Corporation
+Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -14,7 +14,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
#include <DxeMain.h>
-UINTN mErrorLevel = EFI_D_ERROR | EFI_D_LOAD;
+UINTN mErrorLevel = DEBUG_ERROR | DEBUG_LOAD;
EFI_DXE_DEVICE_HANDLE_EXTENDED_DATA mStatusCodeData = {
{
@@ -25,30 +25,22 @@ EFI_DXE_DEVICE_HANDLE_EXTENDED_DATA mStatusCodeData = {
NULL
};
+
+/**
+ Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid,
+ with a handle as additional information.
+
+ @param Value Describes the class/subclass/operation of the
+ hardware or software entity that the Status Code
+ relates to.
+ @param Handle Additional information.
+
+**/
VOID
CoreReportProgressCodeSpecific (
IN EFI_STATUS_CODE_VALUE Value,
IN EFI_HANDLE Handle
)
-/*++
-
-Routine Description:
-
- Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid,
- with a handle as additional information.
-
-Arguments:
-
- Value - Describes the class/subclass/operation of the hardware or software entity
- that the Status Code relates to.
-
- Handle - Additional information.
-
-Returns:
-
- None
-
---*/
{
mStatusCodeData.DataHeader.Size = sizeof (EFI_DXE_DEVICE_HANDLE_EXTENDED_DATA) - sizeof (EFI_STATUS_CODE_DATA);
mStatusCodeData.Handle = Handle;
@@ -64,26 +56,19 @@ Returns:
}
}
+
+/**
+ Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid.
+
+ @param Value Describes the class/subclass/operation of the
+ hardware or software entity that the Status Code
+ relates to.
+
+**/
VOID
CoreReportProgressCode (
IN EFI_STATUS_CODE_VALUE Value
)
-/*++
-
-Routine Description:
-
- Report status code of type EFI_PROGRESS_CODE by caller ID gEfiCallerIdGuid.
-
-Arguments:
-
- Value - Describes the class/subclass/operation of the hardware or software entity
- that the Status Code relates to.
-
-Returns:
-
- None
-
---*/
{
if ((gStatusCode != NULL) && (gStatusCode->ReportStatusCode != NULL) ) {
gStatusCode->ReportStatusCode (
@@ -97,25 +82,19 @@ Returns:
}
+
+/**
+ Allocate pool of type EfiBootServicesData, the size is specified with AllocationSize.
+
+ @param AllocationSize Size to allocate.
+
+ @return Pointer of the allocated pool.
+
+**/
VOID *
CoreAllocateBootServicesPool (
IN UINTN AllocationSize
)
-/*++
-
-Routine Description:
-
- Allocate pool of type EfiBootServicesData, the size is specified with AllocationSize.
-
-Arguments:
-
- AllocationSize - Size to allocate.
-
-Returns:
-
- Pointer of the allocated pool.
-
---*/
{
VOID *Memory;
@@ -124,25 +103,19 @@ Returns:
}
+
+/**
+ Allocate pool of type EfiBootServicesData and zero it, the size is specified with AllocationSize.
+
+ @param AllocationSize Size to allocate.
+
+ @return Pointer of the allocated pool.
+
+**/
VOID *
CoreAllocateZeroBootServicesPool (
IN UINTN AllocationSize
)
-/*++
-
-Routine Description:
-
- Allocate pool of type EfiBootServicesData and zero it, the size is specified with AllocationSize.
-
-Arguments:
-
- AllocationSize - Size to allocate.
-
-Returns:
-
- Pointer of the allocated pool.
-
---*/
{
VOID *Memory;
@@ -152,28 +125,22 @@ Returns:
}
+
+/**
+ Allocate pool of specified size with EfiBootServicesData type, and copy specified buffer to this pool.
+
+ @param AllocationSize Size to allocate.
+ @param Buffer Specified buffer that will be copy to the allocated
+ pool
+
+ @return Pointer of the allocated pool.
+
+**/
VOID *
CoreAllocateCopyPool (
IN UINTN AllocationSize,
IN VOID *Buffer
)
-/*++
-
-Routine Description:
-
- Allocate pool of specified size with EfiBootServicesData type, and copy specified buffer to this pool.
-
-Arguments:
-
- AllocationSize - Size to allocate.
-
- Buffer - Specified buffer that will be copy to the allocated pool
-
-Returns:
-
- Pointer of the allocated pool.
-
---*/
{
VOID *Memory;
@@ -185,25 +152,19 @@ Returns:
+
+/**
+ Allocate pool of type EfiRuntimeServicesData, the size is specified with AllocationSize.
+
+ @param AllocationSize Size to allocate.
+
+ @return Pointer of the allocated pool.
+
+**/
VOID *
CoreAllocateRuntimePool (
IN UINTN AllocationSize
)
-/*++
-
-Routine Description:
-
- Allocate pool of type EfiRuntimeServicesData, the size is specified with AllocationSize.
-
-Arguments:
-
- AllocationSize - Size to allocate.
-
-Returns:
-
- Pointer of the allocated pool.
-
---*/
{
VOID *Memory;
@@ -211,29 +172,22 @@ Returns:
return Memory;
}
+
+/**
+ Allocate pool of specified size with EfiRuntimeServicesData type, and copy specified buffer to this pool.
+
+ @param AllocationSize Size to allocate.
+ @param Buffer Specified buffer that will be copy to the allocated
+ pool
+
+ @return Pointer of the allocated pool.
+
+**/
VOID *
CoreAllocateRuntimeCopyPool (
IN UINTN AllocationSize,
IN VOID *Buffer
)
-/*++
-
-Routine Description:
-
- Allocate pool of specified size with EfiRuntimeServicesData type, and copy specified buffer to this pool.
-
-Arguments:
-
- AllocationSize - Size to allocate.
-
- Buffer - Specified buffer that will be copy to the allocated pool
-
-Returns:
-
- Pointer of the allocated pool.
-
---*/
-
{
VOID *Memory;
@@ -250,31 +204,23 @@ Returns:
//
-
-EFI_STATUS
-CoreAcquireLockOrFail (
- IN EFI_LOCK *Lock
- )
-/*++
-
-Routine Description:
-
+/**
Initialize a basic mutual exclusion lock. Each lock
provides mutual exclusion access at it's task priority
level. Since there is no-premption (at any TPL) or
multiprocessor support, acquiring the lock only consists
of raising to the locks TPL.
-Arguments:
+ @param Lock The EFI_LOCK structure to initialize
- Lock - The EFI_LOCK structure to initialize
+ @retval EFI_SUCCESS Lock Owned.
+ @retval EFI_ACCESS_DENIED Reentrant Lock Acquisition, Lock not Owned.
-Returns:
-
- EFI_SUCCESS - Lock Owned.
- EFI_ACCESS_DENIED - Reentrant Lock Acquisition, Lock not Owned.
-
---*/
+**/
+EFI_STATUS
+CoreAcquireLockOrFail (
+ IN EFI_LOCK *Lock
+ )
{
ASSERT (Lock != NULL);
ASSERT (Lock->Lock != EfiLockUninitialized);
@@ -293,26 +239,20 @@ Returns:
}
+
+/**
+ Raising to the task priority level of the mutual exclusion
+ lock, and then acquires ownership of the lock.
+
+ @param Lock The lock to acquire
+
+ @return Lock owned
+
+**/
VOID
CoreAcquireLock (
IN EFI_LOCK *Lock
)
-/*++
-
-Routine Description:
-
- Raising to the task priority level of the mutual exclusion
- lock, and then acquires ownership of the lock.
-
-Arguments:
-
- Lock - The lock to acquire
-
-Returns:
-
- Lock owned
-
---*/
{
ASSERT (Lock != NULL);
ASSERT (Lock->Lock == EfiLockReleased);
@@ -322,26 +262,20 @@ Returns:
}
+
+/**
+ Releases ownership of the mutual exclusion lock, and
+ restores the previous task priority level.
+
+ @param Lock The lock to release
+
+ @return Lock unowned
+
+**/
VOID
CoreReleaseLock (
IN EFI_LOCK *Lock
)
-/*++
-
-Routine Description:
-
- Releases ownership of the mutual exclusion lock, and
- restores the previous task priority level.
-
-Arguments:
-
- Lock - The lock to release
-
-Returns:
-
- Lock unowned
-
---*/
{
EFI_TPL Tpl;
@@ -356,25 +290,19 @@ Returns:
}
+
+/**
+ Calculate the size of a whole device path.
+
+ @param DevicePath The pointer to the device path data.
+
+ @return Size of device path data structure..
+
+**/
UINTN
CoreDevicePathSize (
IN EFI_DEVICE_PATH_PROTOCOL *DevicePath
)
-/*++
-
-Routine Description:
-
- Calculate the size of a whole device path.
-
-Arguments:
-
- DevicePath - The pointer to the device path data.
-
-Returns:
-
- Size of device path data structure..
-
---*/
{
EFI_DEVICE_PATH_PROTOCOL *Start;
@@ -397,24 +325,20 @@ Returns:
}
+
+/**
+ Return TRUE is this is a multi instance device path.
+
+ @param DevicePath A pointer to a device path data structure.
+
+ @retval TRUE If DevicePath is multi instance. FALSE - If
+ DevicePath is not multi instance.
+
+**/
BOOLEAN
CoreIsDevicePathMultiInstance (
IN EFI_DEVICE_PATH_PROTOCOL *DevicePath
)
-/*++
-
-Routine Description:
- Return TRUE is this is a multi instance device path.
-
-Arguments:
- DevicePath - A pointer to a device path data structure.
-
-
-Returns:
- TRUE - If DevicePath is multi instance. FALSE - If DevicePath is not multi
- instance.
-
---*/
{
EFI_DEVICE_PATH_PROTOCOL *Node;
@@ -434,23 +358,20 @@ Returns:
+
+/**
+ Duplicate a new device path data structure from the old one.
+
+ @param DevicePath A pointer to a device path data structure.
+
+ @return A pointer to the new allocated device path data.
+ @return Caller must free the memory used by DevicePath if it is no longer needed.
+
+**/
EFI_DEVICE_PATH_PROTOCOL *
CoreDuplicateDevicePath (
IN EFI_DEVICE_PATH_PROTOCOL *DevicePath
)
-/*++
-
-Routine Description:
- Duplicate a new device path data structure from the old one.
-
-Arguments:
- DevicePath - A pointer to a device path data structure.
-
-Returns:
- A pointer to the new allocated device path data.
- Caller must free the memory used by DevicePath if it is no longer needed.
-
---*/
{
EFI_DEVICE_PATH_PROTOCOL *NewDevicePath;
UINTN Size;
@@ -474,28 +395,23 @@ Returns:
+
+/**
+ Function is used to append a Src1 and Src2 together.
+
+ @param Src1 A pointer to a device path data structure.
+ @param Src2 A pointer to a device path data structure.
+
+ @return A pointer to the new device path is returned.
+ @return NULL is returned if space for the new device path could not be allocated from pool.
+ @return It is up to the caller to free the memory used by Src1 and Src2 if they are no longer needed.
+
+**/
EFI_DEVICE_PATH_PROTOCOL *
CoreAppendDevicePath (
IN EFI_DEVICE_PATH_PROTOCOL *Src1,
IN EFI_DEVICE_PATH_PROTOCOL *Src2
)
-/*++
-
-Routine Description:
- Function is used to append a Src1 and Src2 together.
-
-Arguments:
- Src1 - A pointer to a device path data structure.
-
- Src2 - A pointer to a device path data structure.
-
-Returns:
-
- A pointer to the new device path is returned.
- NULL is returned if space for the new device path could not be allocated from pool.
- It is up to the caller to free the memory used by Src1 and Src2 if they are no longer needed.
-
---*/
{
UINTN Size;
UINTN Size1;
@@ -530,6 +446,23 @@ Returns:
+
+/**
+ Create a protocol notification event and return it.
+
+ @param ProtocolGuid Protocol to register notification event on.
+ @param NotifyTpl Maximum TPL to signal the NotifyFunction.
+ @param NotifyFunction EFI notification routine.
+ @param NotifyContext Context passed into Event when it is created.
+ @param Registration Registration key returned from
+ RegisterProtocolNotify().
+ @param SignalFlag Boolean value to decide whether kick the event after
+ register or not.
+
+ @return The EFI_EVENT that has been registered to be signaled when a ProtocolGuid
+ is added to the system.
+
+**/
EFI_EVENT
CoreCreateProtocolNotifyEvent (
IN EFI_GUID *ProtocolGuid,
@@ -539,32 +472,6 @@ CoreCreateProtocolNotifyEvent (
OUT VOID **Registration,
IN BOOLEAN SignalFlag
)
-/*++
-
-Routine Description:
-
- Create a protocol notification event and return it.
-
-Arguments:
-
- ProtocolGuid - Protocol to register notification event on.
-
- NotifyTpl - Maximum TPL to signal the NotifyFunction.
-
- NotifyFuncition - EFI notification routine.
-
- NotifyContext - Context passed into Event when it is created.
-
- Registration - Registration key returned from RegisterProtocolNotify().
-
- SignalFlag - Boolean value to decide whether kick the event after register or not.
-
-Returns:
-
- The EFI_EVENT that has been registered to be signaled when a ProtocolGuid
- is added to the system.
-
---*/
{
EFI_STATUS Status;
EFI_EVENT Event;
@@ -604,3 +511,4 @@ Returns:
return Event;
}
+
diff --git a/MdeModulePkg/Core/Dxe/Mem/Page.c b/MdeModulePkg/Core/Dxe/Mem/Page.c
index daf00f237d..9ec83141ac 100644
--- a/MdeModulePkg/Core/Dxe/Mem/Page.c
+++ b/MdeModulePkg/Core/Dxe/Mem/Page.c
@@ -91,12 +91,30 @@ EFI_MEMORY_TYPE_INFORMATION gMemoryTypeInformation[EfiMaxMemoryType + 1] = {
//
// Internal prototypes
//
+/**
+ Find untested but initialized memory regions in GCD map and convert them to be DXE allocatable.
+
+**/
STATIC
VOID
PromoteMemoryResource (
VOID
-);
+ );
+/**
+ Internal function. Adds a ranges to the memory map.
+ The range must not already exist in the map.
+
+ @param Type The type of memory range to add
+ @param Start The starting address in the memory range Must be
+ paged aligned
+ @param End The last address in the range Must be the last
+ byte of a page
+ @param Attribute The attributes of the memory range to add
+
+ @return None. The range is added to the memory map
+
+**/
STATIC
VOID
CoreAddRange (
@@ -106,12 +124,33 @@ CoreAddRange (
IN UINT64 Attribute
);
+/**
+ Internal function. Moves any memory descriptors that are on the
+ temporary descriptor stack to heap.
+
+**/
STATIC
VOID
CoreFreeMemoryMapStack (
VOID
);
+/**
+ Internal function. Converts a memory range to the specified type.
+ The range must exist in the memory map.
+
+ @param Start The first address of the range Must be page
+ aligned
+ @param NumberOfPages The number of pages to convert
+ @param NewType The new type for the memory range
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_NOT_FOUND Could not find a descriptor cover the specified
+ range or convertion not allowed.
+ @retval EFI_SUCCESS Successfully converts the memory range to the
+ specified type.
+
+**/
STATIC
EFI_STATUS
CoreConvertPages (
@@ -120,90 +159,79 @@ CoreConvertPages (
IN EFI_MEMORY_TYPE NewType
);
+/**
+ Internal function. Removes a descriptor entry.
+
+ @param Entry The entry to remove
+
+**/
STATIC
VOID
RemoveMemoryMapEntry (
MEMORY_MAP *Entry
);
+/**
+ Internal function. Deque a descriptor entry from the mFreeMemoryMapEntryList.
+ If the list is emtry, then allocate a new page to refuel the list.
+ Please Note this algorithm to allocate the memory map descriptor has a property
+ that the memory allocated for memory entries always grows, and will never really be freed
+ For example, if the current boot uses 2000 memory map entries at the maximum point, but
+ ends up with only 50 at the time the OS is booted, then the memory associated with the 1950
+ memory map entries is still allocated from EfiBootServicesMemory.
+
+
+ @return The Memory map descriptor dequed from the mFreeMemoryMapEntryList
+
+**/
STATIC
MEMORY_MAP *
AllocateMemoryMapEntry (
VOID
);
+
+/**
+ Enter critical section by gaining lock on gMemoryLock.
+
+**/
VOID
CoreAcquireMemoryLock (
VOID
)
-/*++
-
-Routine Description:
-
- Enter critical section by gaining lock on gMemoryLock
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
{
CoreAcquireLock (&gMemoryLock);
}
+
+/**
+ Exit critical section by releasing lock on gMemoryLock.
+
+**/
VOID
CoreReleaseMemoryLock (
VOID
)
-/*++
-
-Routine Description:
-
- Exit critical section by releasing lock on gMemoryLock
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
{
CoreReleaseLock (&gMemoryLock);
}
+
+/**
+ Find untested but initialized memory regions in GCD map and convert them to be DXE allocatable.
+
+**/
STATIC
VOID
PromoteMemoryResource (
VOID
)
-/*++
-
-Routine Description:
-
- Find untested but initialized memory regions in GCD map and convert them to be DXE allocatable.
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
{
LIST_ENTRY *Link;
EFI_GCD_MAP_ENTRY *Entry;
- DEBUG ((EFI_D_ERROR | EFI_D_PAGE, "Promote the memory resource\n"));
+ DEBUG ((DEBUG_ERROR | DEBUG_PAGE, "Promote the memory resource\n"));
CoreAcquireGcdMemoryLock ();
@@ -246,6 +274,22 @@ Returns:
return;
}
+
+/**
+ Called to initialize the memory map and add descriptors to
+ the current descriptor list.
+ The first descriptor that is added must be general usable
+ memory as the addition allocates heap.
+
+ @param Type The type of memory to add
+ @param Start The starting address in the memory range Must be
+ page aligned
+ @param NumberOfPages The number of pages in the range
+ @param Attribute Attributes of the memory to add
+
+ @return None. The range is added to the memory map
+
+**/
VOID
CoreAddMemoryDescriptor (
IN EFI_MEMORY_TYPE Type,
@@ -253,32 +297,6 @@ CoreAddMemoryDescriptor (
IN UINT64 NumberOfPages,
IN UINT64 Attribute
)
-/*++
-
-Routine Description:
-
- Called to initialize the memory map and add descriptors to
- the current descriptor list.
-
- The first descriptor that is added must be general usable
- memory as the addition allocates heap.
-
-Arguments:
-
- Type - The type of memory to add
-
- Start - The starting address in the memory range
- Must be page aligned
-
- NumberOfPages - The number of pages in the range
-
- Attribute - Attributes of the memory to add
-
-Returns:
-
- None. The range is added to the memory map
-
---*/
{
EFI_PHYSICAL_ADDRESS End;
EFI_STATUS Status;
@@ -416,6 +434,21 @@ Returns:
}
+
+/**
+ Internal function. Adds a ranges to the memory map.
+ The range must not already exist in the map.
+
+ @param Type The type of memory range to add
+ @param Start The starting address in the memory range Must be
+ paged aligned
+ @param End The last address in the range Must be the last
+ byte of a page
+ @param Attribute The attributes of the memory range to add
+
+ @return None. The range is added to the memory map
+
+**/
STATIC
VOID
CoreAddRange (
@@ -424,30 +457,6 @@ CoreAddRange (
IN EFI_PHYSICAL_ADDRESS End,
IN UINT64 Attribute
)
-/*++
-
-Routine Description:
-
- Internal function. Adds a ranges to the memory map.
- The range must not already exist in the map.
-
-Arguments:
-
- Type - The type of memory range to add
-
- Start - The starting address in the memory range
- Must be paged aligned
-
- End - The last address in the range
- Must be the last byte of a page
-
- Attribute - The attributes of the memory range to add
-
-Returns:
-
- None. The range is added to the memory map
-
---*/
{
LIST_ENTRY *Link;
MEMORY_MAP *Entry;
@@ -457,7 +466,7 @@ Returns:
ASSERT_LOCKED (&gMemoryLock);
- DEBUG ((EFI_D_PAGE, "AddRange: %lx-%lx to %d\n", Start, End, Type));
+ DEBUG ((DEBUG_PAGE, "AddRange: %lx-%lx to %d\n", Start, End, Type));
//
// Memory map being altered so updated key
@@ -527,27 +536,17 @@ Returns:
return ;
}
+
+/**
+ Internal function. Moves any memory descriptors that are on the
+ temporary descriptor stack to heap.
+
+**/
STATIC
VOID
CoreFreeMemoryMapStack (
VOID
)
-/*++
-
-Routine Description:
-
- Internal function. Moves any memory descriptors that are on the
- temporary descriptor stack to heap.
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
{
MEMORY_MAP *Entry;
MEMORY_MAP *Entry2;
@@ -615,64 +614,49 @@ Returns:
mFreeMapStack -= 1;
}
+
+/**
+ Internal function. Removes a descriptor entry.
+
+ @param Entry The entry to remove
+
+**/
STATIC
VOID
RemoveMemoryMapEntry (
MEMORY_MAP *Entry
)
-/*++
-
-Routine Description:
-
- Internal function. Removes a descriptor entry.
-
-Arguments:
-
- Entry - The entry to remove
-
-Returns:
-
- None
-
---*/
{
RemoveEntryList (&Entry->Link);
Entry->Link.ForwardLink = NULL;
if (Entry->FromPages) {
- //
- // Insert the free memory map descriptor to the end of mFreeMemoryMapEntryList
- //
+ //
+ // Insert the free memory map descriptor to the end of mFreeMemoryMapEntryList
+ //
InsertTailList (&mFreeMemoryMapEntryList, &Entry->Link);
}
}
+
+/**
+ Internal function. Deque a descriptor entry from the mFreeMemoryMapEntryList.
+ If the list is emtry, then allocate a new page to refuel the list.
+ Please Note this algorithm to allocate the memory map descriptor has a property
+ that the memory allocated for memory entries always grows, and will never really be freed
+ For example, if the current boot uses 2000 memory map entries at the maximum point, but
+ ends up with only 50 at the time the OS is booted, then the memory associated with the 1950
+ memory map entries is still allocated from EfiBootServicesMemory.
+
+
+ @return The Memory map descriptor dequed from the mFreeMemoryMapEntryList
+
+**/
STATIC
MEMORY_MAP *
AllocateMemoryMapEntry (
VOID
)
-/*++
-
-Routine Description:
-
- Internal function. Deque a descriptor entry from the mFreeMemoryMapEntryList.
- If the list is emtry, then allocate a new page to refuel the list.
- Please Note this algorithm to allocate the memory map descriptor has a property
- that the memory allocated for memory entries always grows, and will never really be freed
- For example, if the current boot uses 2000 memory map entries at the maximum point, but
- ends up with only 50 at the time the OS is booted, then the memory associated with the 1950
- memory map entries is still allocated from EfiBootServicesMemory.
-
-Arguments:
-
- NONE
-
-Returns:
-
- The Memory map descriptor dequed from the mFreeMemoryMapEntryList
-
---*/
{
MEMORY_MAP* FreeDescriptorEntries;
MEMORY_MAP* Entry;
@@ -704,6 +688,23 @@ Returns:
return Entry;
}
+
+/**
+ Internal function. Converts a memory range to the specified type.
+ The range must exist in the memory map.
+
+ @param Start The first address of the range Must be page
+ aligned
+ @param NumberOfPages The number of pages to convert
+ @param NewType The new type for the memory range
+
+ @retval EFI_INVALID_PARAMETER Invalid parameter
+ @retval EFI_NOT_FOUND Could not find a descriptor cover the specified
+ range or convertion not allowed.
+ @retval EFI_SUCCESS Successfully converts the memory range to the
+ specified type.
+
+**/
STATIC
EFI_STATUS
CoreConvertPages (
@@ -711,32 +712,6 @@ CoreConvertPages (
IN UINT64 NumberOfPages,
IN EFI_MEMORY_TYPE NewType
)
-/*++
-
-Routine Description:
-
- Internal function. Converts a memory range to the specified type.
- The range must exist in the memory map.
-
-Arguments:
-
- Start - The first address of the range
- Must be page aligned
-
- NumberOfPages - The number of pages to convert
-
- NewType - The new type for the memory range
-
-Returns:
-
- EFI_INVALID_PARAMETER - Invalid parameter
-
- EFI_NOT_FOUND - Could not find a descriptor cover the specified range
- or convertion not allowed.
-
- EFI_SUCCESS - Successfully converts the memory range to the specified type.
-
---*/
{
UINT64 NumberOfBytes;
@@ -777,7 +752,7 @@ Returns:
}
if (Link == &gMemoryMap) {
- DEBUG ((EFI_D_ERROR | EFI_D_PAGE, "ConvertPages: failed to find range %lx - %lx\n", Start, End));
+ DEBUG ((DEBUG_ERROR | DEBUG_PAGE, "ConvertPages: failed to find range %lx - %lx\n", Start, End));
return EFI_NOT_FOUND;
}
@@ -790,13 +765,13 @@ Returns:
RangeEnd = Entry->End;
}
- DEBUG ((EFI_D_PAGE, "ConvertRange: %lx-%lx to %d\n", Start, RangeEnd, NewType));
+ DEBUG ((DEBUG_PAGE, "ConvertRange: %lx-%lx to %d\n", Start, RangeEnd, NewType));
//
// Debug code - verify conversion is allowed
//
if (!(NewType == EfiConventionalMemory ? 1 : 0) ^ (Entry->Type == EfiConventionalMemory ? 1 : 0)) {
- DEBUG ((EFI_D_ERROR , "ConvertPages: Incompatible memory types\n"));
+ DEBUG ((DEBUG_ERROR , "ConvertPages: Incompatible memory types\n"));
return EFI_NOT_FOUND;
}
@@ -909,6 +884,20 @@ Returns:
}
+
+/**
+ Internal function. Finds a consecutive free page range below
+ the requested address.
+
+ @param MaxAddress The address that the range must be below
+ @param NumberOfPages Number of pages needed
+ @param NewType The type of memory the range is going to be
+ turned into
+ @param Alignment Bits to align with
+
+ @return The base address of the range, or 0 if the range was not found
+
+**/
STATIC
UINT64
CoreFindFreePagesI (
@@ -917,28 +906,6 @@ CoreFindFreePagesI (
IN EFI_MEMORY_TYPE NewType,
IN UINTN Alignment
)
-/*++
-
-Routine Description:
-
- Internal function. Finds a consecutive free page range below
- the requested address.
-
-Arguments:
-
- MaxAddress - The address that the range must be below
-
- NumberOfPages - Number of pages needed
-
- NewType - The type of memory the range is going to be turned into
-
- Alignment - Bits to align with
-
-Returns:
-
- The base address of the range, or 0 if the range was not found
-
---*/
{
UINT64 NumberOfBytes;
UINT64 Target;
@@ -1038,6 +1005,20 @@ Returns:
return Target;
}
+
+/**
+ Internal function. Finds a consecutive free page range below
+ the requested address
+
+ @param MaxAddress The address that the range must be below
+ @param NoPages Number of pages needed
+ @param NewType The type of memory the range is going to be
+ turned into
+ @param Alignment Bits to align with
+
+ @return The base address of the range, or 0 if the range was not found.
+
+**/
STATIC
UINT64
FindFreePages (
@@ -1046,28 +1027,6 @@ FindFreePages (
IN EFI_MEMORY_TYPE NewType,
IN UINTN Alignment
)
-/*++
-
-Routine Description:
-
- Internal function. Finds a consecutive free page range below
- the requested address
-
-Arguments:
-
- MaxAddress - The address that the range must be below
-
- NoPages - Number of pages needed
-
- NewType - The type of memory the range is going to be turned into
-
- Alignment - Bits to align with
-
-Returns:
-
- The base address of the range, or 0 if the range was not found.
-
---*/
{
UINT64 NewMaxAddress;
UINT64 Start;
@@ -1103,6 +1062,25 @@ Returns:
}
+
+/**
+ Allocates pages from the memory map.
+
+ @param Type The type of allocation to perform
+ @param MemoryType The type of memory to turn the allocated pages
+ into
+ @param NumberOfPages The number of pages to allocate
+ @param Memory A pointer to receive the base allocated memory
+ address
+
+ @return Status. On success, Memory is filled in with the base address allocated
+ @retval EFI_INVALID_PARAMETER Parameters violate checking rules defined in
+ spec.
+ @retval EFI_NOT_FOUND Could not allocate pages match the requirement.
+ @retval EFI_OUT_OF_RESOURCES No enough pages to allocate.
+ @retval EFI_SUCCESS Pages successfully allocated.
+
+**/
EFI_STATUS
EFIAPI
CoreAllocatePages (
@@ -1111,35 +1089,6 @@ CoreAllocatePages (
IN UINTN NumberOfPages,
IN OUT EFI_PHYSICAL_ADDRESS *Memory
)
-/*++
-
-Routine Description:
-
- Allocates pages from the memory map.
-
-Arguments:
-
- Type - The type of allocation to perform
-
- MemoryType - The type of memory to turn the allocated pages into
-
- NumberOfPages - The number of pages to allocate
-
- Memory - A pointer to receive the base allocated memory address
-
-Returns:
-
- Status. On success, Memory is filled in with the base address allocated
-
- EFI_INVALID_PARAMETER - Parameters violate checking rules defined in spec.
-
- EFI_NOT_FOUND - Could not allocate pages match the requirement.
-
- EFI_OUT_OF_RESOURCES - No enough pages to allocate.
-
- EFI_SUCCESS - Pages successfully allocated.
-
---*/
{
EFI_STATUS Status;
UINT64 Start;
@@ -1219,33 +1168,24 @@ Done:
+
+/**
+ Frees previous allocated pages.
+
+ @param Memory Base address of memory being freed
+ @param NumberOfPages The number of pages to free
+
+ @retval EFI_NOT_FOUND Could not find the entry that covers the range
+ @retval EFI_INVALID_PARAMETER Address not aligned
+ @return EFI_SUCCESS -Pages successfully freed.
+
+**/
EFI_STATUS
EFIAPI
CoreFreePages (
IN EFI_PHYSICAL_ADDRESS Memory,
IN UINTN NumberOfPages
)
-/*++
-
-Routine Description:
-
- Frees previous allocated pages.
-
-Arguments:
-
- Memory - Base address of memory being freed
-
- NumberOfPages - The number of pages to free
-
-Returns:
-
- EFI_NOT_FOUND - Could not find the entry that covers the range
-
- EFI_INVALID_PARAMETER - Address not aligned
-
- EFI_SUCCESS -Pages successfully freed.
-
---*/
{
EFI_STATUS Status;
LIST_ENTRY *Link;
@@ -1311,6 +1251,37 @@ Returns:
+
+/**
+ This function returns a copy of the current memory map. The map is an array of
+ memory descriptors, each of which describes a contiguous block of memory.
+
+ @param MemoryMapSize A pointer to the size, in bytes, of the
+ MemoryMap buffer. On input, this is the size of
+ the buffer allocated by the caller. On output,
+ it is the size of the buffer returned by the
+ firmware if the buffer was large enough, or the
+ size of the buffer needed to contain the map if
+ the buffer was too small.
+ @param MemoryMap A pointer to the buffer in which firmware places
+ the current memory map.
+ @param MapKey A pointer to the location in which firmware
+ returns the key for the current memory map.
+ @param DescriptorSize A pointer to the location in which firmware
+ returns the size, in bytes, of an individual
+ EFI_MEMORY_DESCRIPTOR.
+ @param DescriptorVersion A pointer to the location in which firmware
+ returns the version number associated with the
+ EFI_MEMORY_DESCRIPTOR.
+
+ @retval EFI_SUCCESS The memory map was returned in the MemoryMap
+ buffer.
+ @retval EFI_BUFFER_TOO_SMALL The MemoryMap buffer was too small. The current
+ buffer size needed to hold the memory map is
+ returned in MemoryMapSize.
+ @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
+
+**/
EFI_STATUS
EFIAPI
CoreGetMemoryMap (
@@ -1320,36 +1291,6 @@ CoreGetMemoryMap (
OUT UINTN *DescriptorSize,
OUT UINT32 *DescriptorVersion
)
-/*++
-
-Routine Description:
-
- This function returns a copy of the current memory map. The map is an array of
- memory descriptors, each of which describes a contiguous block of memory.
-
-Arguments:
-
- MemoryMapSize - A pointer to the size, in bytes, of the MemoryMap buffer. On
- input, this is the size of the buffer allocated by the caller.
- On output, it is the size of the buffer returned by the firmware
- if the buffer was large enough, or the size of the buffer needed
- to contain the map if the buffer was too small.
- MemoryMap - A pointer to the buffer in which firmware places the current memory map.
- MapKey - A pointer to the location in which firmware returns the key for the
- current memory map.
- DescriptorSize - A pointer to the location in which firmware returns the size, in
- bytes, of an individual EFI_MEMORY_DESCRIPTOR.
- DescriptorVersion - A pointer to the location in which firmware returns the version
- number associated with the EFI_MEMORY_DESCRIPTOR.
-
-Returns:
-
- EFI_SUCCESS - The memory map was returned in the MemoryMap buffer.
- EFI_BUFFER_TOO_SMALL - The MemoryMap buffer was too small. The current buffer size
- needed to hold the memory map is returned in MemoryMapSize.
- EFI_INVALID_PARAMETER - One of the parameters has an invalid value.
-
---*/
{
EFI_STATUS Status;
UINTN Size;
@@ -1506,32 +1447,24 @@ Done:
return Status;
}
+
+/**
+ Internal function. Used by the pool functions to allocate pages
+ to back pool allocation requests.
+
+ @param PoolType The type of memory for the new pool pages
+ @param NumberOfPages No of pages to allocate
+ @param Alignment Bits to align.
+
+ @return The allocated memory, or NULL
+
+**/
VOID *
CoreAllocatePoolPages (
IN EFI_MEMORY_TYPE PoolType,
IN UINTN NumberOfPages,
IN UINTN Alignment
)
-/*++
-
-Routine Description:
-
- Internal function. Used by the pool functions to allocate pages
- to back pool allocation requests.
-
-Arguments:
-
- PoolType - The type of memory for the new pool pages
-
- NumberOfPages - No of pages to allocate
-
- Alignment - Bits to align.
-
-Returns:
-
- The allocated memory, or NULL
-
---*/
{
UINT64 Start;
@@ -1544,7 +1477,7 @@ Returns:
// Convert it to boot services data
//
if (Start == 0) {
- DEBUG ((EFI_D_ERROR | EFI_D_PAGE, "AllocatePoolPages: failed to allocate %d pages\n", NumberOfPages));
+ DEBUG ((DEBUG_ERROR | DEBUG_PAGE, "AllocatePoolPages: failed to allocate %d pages\n", NumberOfPages));
} else {
CoreConvertPages (Start, NumberOfPages, PoolType);
}
@@ -1552,55 +1485,40 @@ Returns:
return (VOID *)(UINTN)Start;
}
+
+/**
+ Internal function. Frees pool pages allocated via AllocatePoolPages ()
+
+ @param Memory The base address to free
+ @param NumberOfPages The number of pages to free
+
+**/
VOID
CoreFreePoolPages (
IN EFI_PHYSICAL_ADDRESS Memory,
IN UINTN NumberOfPages
)
-/*++
-
-Routine Description:
-
- Internal function. Frees pool pages allocated via AllocatePoolPages ()
-
-Arguments:
-
- Memory - The base address to free
-
- NumberOfPages - The number of pages to free
-
-Returns:
-
- None
-
---*/
{
CoreConvertPages (Memory, NumberOfPages, EfiConventionalMemory);
}
+
+/**
+ Make sure the memory map is following all the construction rules,
+ it is the last time to check memory map error before exit boot services.
+
+ @param MapKey Memory map key
+
+ @retval EFI_INVALID_PARAMETER Memory map not consistent with construction
+ rules.
+ @retval EFI_SUCCESS Valid memory map.
+
+**/
EFI_STATUS
CoreTerminateMemoryMap (
IN UINTN MapKey
)
-/*++
-
-Routine Description:
-
- Make sure the memory map is following all the construction rules,
- it is the last time to check memory map error before exit boot services.
-
-Arguments:
-
- MapKey - Memory map key
-
-Returns:
-
- EFI_INVALID_PARAMETER - Memory map not consistent with construction rules.
-
- EFI_SUCCESS - Valid memory map.
-
---*/
{
EFI_STATUS Status;
LIST_ENTRY *Link;
@@ -1622,17 +1540,17 @@ Returns:
Entry = CR(Link, MEMORY_MAP, Link, MEMORY_MAP_SIGNATURE);
if (Entry->Attribute & EFI_MEMORY_RUNTIME) {
if (Entry->Type == EfiACPIReclaimMemory || Entry->Type == EfiACPIMemoryNVS) {
- DEBUG((EFI_D_ERROR, "ExitBootServices: ACPI memory entry has RUNTIME attribute set.\n"));
+ DEBUG((DEBUG_ERROR, "ExitBootServices: ACPI memory entry has RUNTIME attribute set.\n"));
CoreReleaseMemoryLock ();
return EFI_INVALID_PARAMETER;
}
if (Entry->Start & (EFI_ACPI_RUNTIME_PAGE_ALLOCATION_ALIGNMENT - 1)) {
- DEBUG((EFI_D_ERROR, "ExitBootServices: A RUNTIME memory entry is not on a proper alignment.\n"));
+ DEBUG((DEBUG_ERROR, "ExitBootServices: A RUNTIME memory entry is not on a proper alignment.\n"));
CoreReleaseMemoryLock ();
return EFI_INVALID_PARAMETER;
}
if ((Entry->End + 1) & (EFI_ACPI_RUNTIME_PAGE_ALLOCATION_ALIGNMENT - 1)) {
- DEBUG((EFI_D_ERROR, "ExitBootServices: A RUNTIME memory entry is not on a proper alignment.\n"));
+ DEBUG((DEBUG_ERROR, "ExitBootServices: A RUNTIME memory entry is not on a proper alignment.\n"));
CoreReleaseMemoryLock ();
return EFI_INVALID_PARAMETER;
}
@@ -1662,3 +1580,4 @@ Returns:
+
diff --git a/MdeModulePkg/Core/Dxe/Mem/pool.c b/MdeModulePkg/Core/Dxe/Mem/pool.c
index 6a98cdcca1..1adaa1f269 100644
--- a/MdeModulePkg/Core/Dxe/Mem/pool.c
+++ b/MdeModulePkg/Core/Dxe/Mem/pool.c
@@ -77,25 +77,15 @@ LIST_ENTRY PoolHeadList;
//
//
+
+/**
+ Called to initialize the pool.
+
+**/
VOID
CoreInitializePool (
VOID
)
-/*++
-
-Routine Description:
-
- Called to initialize the pool.
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
{
UINTN Type;
UINTN Index;
@@ -111,26 +101,20 @@ Returns:
InitializeListHead (&PoolHeadList);
}
+
+/**
+ Look up pool head for specified memory type.
+
+ @param MemoryType Memory type of which pool head is looked for
+
+ @return Pointer of Corresponding pool head.
+
+**/
STATIC
POOL *
LookupPoolHead (
IN EFI_MEMORY_TYPE MemoryType
)
-/*++
-
-Routine Description:
-
- Look up pool head for specified memory type.
-
-Arguments:
-
- MemoryType - Memory type of which pool head is looked for
-
-Returns:
-
- Pointer of Corresponding pool head.
-
---*/
{
LIST_ENTRY *Link;
POOL *Pool;
@@ -171,6 +155,20 @@ Returns:
+
+/**
+ Allocate pool of a particular type.
+
+ @param PoolType Type of pool to allocate
+ @param Size The amount of pool to allocate
+ @param Buffer The address to return a pointer to the allocated
+ pool
+
+ @retval EFI_INVALID_PARAMETER PoolType not valid
+ @retval EFI_OUT_OF_RESOURCES Size exceeds max pool size or allocation failed.
+ @retval EFI_SUCCESS Pool successfully allocated.
+
+**/
EFI_STATUS
EFIAPI
CoreAllocatePool (
@@ -178,29 +176,6 @@ CoreAllocatePool (
IN UINTN Size,
OUT VOID **Buffer
)
-/*++
-
-Routine Description:
-
- Allocate pool of a particular type.
-
-Arguments:
-
- PoolType - Type of pool to allocate
-
- Size - The amount of pool to allocate
-
- Buffer - The address to return a pointer to the allocated pool
-
-Returns:
-
- EFI_INVALID_PARAMETER - PoolType not valid
-
- EFI_OUT_OF_RESOURCES - Size exceeds max pool size or allocation failed.
-
- EFI_SUCCESS - Pool successfully allocated.
-
---*/
{
EFI_STATUS Status;
@@ -236,31 +211,22 @@ Returns:
}
+
+/**
+ Internal function to allocate pool of a particular type.
+ Caller must have the memory lock held
+
+ @param PoolType Type of pool to allocate
+ @param Size The amount of pool to allocate
+
+ @return The allocate pool, or NULL
+
+**/
VOID *
CoreAllocatePoolI (
IN EFI_MEMORY_TYPE PoolType,
IN UINTN Size
)
-/*++
-
-Routine Description:
-
- Internal function to allocate pool of a particular type.
-
- Caller must have the memory lock held
-
-
-Arguments:
-
- PoolType - Type of pool to allocate
-
- Size - The amount of pool to allocate
-
-Returns:
-
- The allocate pool, or NULL
-
---*/
{
POOL *Pool;
POOL_FREE *Free;
@@ -270,7 +236,7 @@ Returns:
VOID *Buffer;
UINTN Index;
UINTN FSize;
- UINTN offset;
+ UINTN Offset;
UINTN Adjustment;
UINTN NoPages;
@@ -322,23 +288,23 @@ Returns:
//
// Carve up new page into free pool blocks
//
- offset = 0;
- while (offset < DEFAULT_PAGE_ALLOCATION) {
+ Offset = 0;
+ while (Offset < DEFAULT_PAGE_ALLOCATION) {
ASSERT (Index < MAX_POOL_LIST);
FSize = LIST_TO_SIZE(Index);
- while (offset + FSize <= DEFAULT_PAGE_ALLOCATION) {
- Free = (POOL_FREE *) &NewPage[offset];
+ while (Offset + FSize <= DEFAULT_PAGE_ALLOCATION) {
+ Free = (POOL_FREE *) &NewPage[Offset];
Free->Signature = POOL_FREE_SIGNATURE;
Free->Index = (UINT32)Index;
InsertHeadList (&Pool->FreeList[Index], &Free->Link);
- offset += FSize;
+ Offset += FSize;
}
Index -= 1;
}
- ASSERT (offset == DEFAULT_PAGE_ALLOCATION);
+ ASSERT (Offset == DEFAULT_PAGE_ALLOCATION);
Index = SIZE_TO_LIST(Size);
}
@@ -368,7 +334,7 @@ Done:
DEBUG_CLEAR_MEMORY (Buffer, Size - POOL_OVERHEAD);
DEBUG (
- (EFI_D_POOL,
+ (DEBUG_POOL,
"AllocatePoolI: Type %x, Addr %x (len %x) %,d\n",
PoolType,
Buffer,
@@ -382,7 +348,7 @@ Done:
Pool->Used += Size;
} else {
- DEBUG ((EFI_D_ERROR | EFI_D_POOL, "AllocatePool: failed to allocate %d bytes\n", Size));
+ DEBUG ((DEBUG_ERROR | DEBUG_POOL, "AllocatePool: failed to allocate %d bytes\n", Size));
}
return Buffer;
@@ -390,28 +356,21 @@ Done:
+
+/**
+ Frees pool.
+
+ @param Buffer The allocated pool entry to free
+
+ @retval EFI_INVALID_PARAMETER Buffer is not a valid value.
+ @retval EFI_SUCCESS Pool successfully freed.
+
+**/
EFI_STATUS
EFIAPI
CoreFreePool (
IN VOID *Buffer
)
-/*++
-
-Routine Description:
-
- Frees pool.
-
-Arguments:
-
- Buffer - The allocated pool entry to free
-
-Returns:
-
- EFI_INVALID_PARAMETER - Buffer is not a valid value.
-
- EFI_SUCCESS - Pool successfully freed.
-
---*/
{
EFI_STATUS Status;
@@ -426,30 +385,21 @@ Returns:
}
+
+/**
+ Internal function to free a pool entry.
+ Caller must have the memory lock held
+
+ @param Buffer The allocated pool entry to free
+
+ @retval EFI_INVALID_PARAMETER Buffer not valid
+ @retval EFI_SUCCESS Buffer successfully freed.
+
+**/
EFI_STATUS
CoreFreePoolI (
IN VOID *Buffer
)
-/*++
-
-Routine Description:
-
- Internal function to free a pool entry.
-
- Caller must have the memory lock held
-
-
-Arguments:
-
- Buffer - The allocated pool entry to free
-
-Returns:
-
- EFI_INVALID_PARAMETER - Buffer not valid
-
- EFI_SUCCESS - Buffer successfully freed.
-
---*/
{
POOL *Pool;
POOL_HEAD *Head;
@@ -460,7 +410,7 @@ Returns:
UINTN Size;
CHAR8 *NewPage;
UINTN FSize;
- UINTN offset;
+ UINTN Offset;
BOOLEAN AllFree;
ASSERT(NULL != Buffer);
@@ -501,7 +451,7 @@ Returns:
return EFI_INVALID_PARAMETER;
}
Pool->Used -= Size;
- DEBUG ((EFI_D_POOL, "FreePool: %x (len %x) %,d\n", Head->Data, Head->Size - POOL_OVERHEAD, Pool->Used));
+ DEBUG ((DEBUG_POOL, "FreePool: %x (len %x) %,d\n", Head->Data, Head->Size - POOL_OVERHEAD, Pool->Used));
//
// Determine the pool list
@@ -545,17 +495,17 @@ Returns:
Index = Free->Index;
AllFree = TRUE;
- offset = 0;
+ Offset = 0;
- while ((offset < DEFAULT_PAGE_ALLOCATION) && (AllFree)) {
+ while ((Offset < DEFAULT_PAGE_ALLOCATION) && (AllFree)) {
FSize = LIST_TO_SIZE(Index);
- while (offset + FSize <= DEFAULT_PAGE_ALLOCATION) {
- Free = (POOL_FREE *) &NewPage[offset];
+ while (Offset + FSize <= DEFAULT_PAGE_ALLOCATION) {
+ Free = (POOL_FREE *) &NewPage[Offset];
ASSERT(NULL != Free);
if (Free->Signature != POOL_FREE_SIGNATURE) {
AllFree = FALSE;
}
- offset += FSize;
+ Offset += FSize;
}
Index -= 1;
}
@@ -570,15 +520,15 @@ Returns:
Free = (POOL_FREE *) &NewPage[0];
ASSERT(NULL != Free);
Index = Free->Index;
- offset = 0;
+ Offset = 0;
- while (offset < DEFAULT_PAGE_ALLOCATION) {
+ while (Offset < DEFAULT_PAGE_ALLOCATION) {
FSize = LIST_TO_SIZE(Index);
- while (offset + FSize <= DEFAULT_PAGE_ALLOCATION) {
- Free = (POOL_FREE *) &NewPage[offset];
+ while (Offset + FSize <= DEFAULT_PAGE_ALLOCATION) {
+ Free = (POOL_FREE *) &NewPage[Offset];
ASSERT(NULL != Free);
RemoveEntryList (&Free->Link);
- offset += FSize;
+ Offset += FSize;
}
Index -= 1;
}
diff --git a/MdeModulePkg/Core/Dxe/Misc/DebugImageInfo.c b/MdeModulePkg/Core/Dxe/Misc/DebugImageInfo.c
index 90e5738532..e318b4239f 100644
--- a/MdeModulePkg/Core/Dxe/Misc/DebugImageInfo.c
+++ b/MdeModulePkg/Core/Dxe/Misc/DebugImageInfo.c
@@ -26,30 +26,22 @@ static EFI_DEBUG_IMAGE_INFO_TABLE_HEADER mDebugInfoTableHeader = {
static EFI_SYSTEM_TABLE_POINTER *mDebugTable = NULL;
+
+/**
+ Creates and initializes the DebugImageInfo Table. Also creates the configuration
+ table and registers it into the system table.
+
+ Note:
+ This function allocates memory, frees it, and then allocates memory at an
+ address within the initial allocation. Since this function is called early
+ in DXE core initialization (before drivers are dispatched), this should not
+ be a problem.
+
+**/
VOID
CoreInitializeDebugImageInfoTable (
VOID
)
-/*++
-
-Routine Description:
-
- Creates and initializes the DebugImageInfo Table. Also creates the configuration
- table and registers it into the system table.
-
-Arguments:
- None
-
-Returns:
- NA
-
-Notes:
- This function allocates memory, frees it, and then allocates memory at an
- address within the initial allocation. Since this function is called early
- in DXE core initialization (before drivers are dispatched), this should not
- be a problem.
-
---*/
{
EFI_STATUS Status;
EFI_PHYSICAL_ADDRESS Mem;
@@ -97,56 +89,42 @@ Notes:
ASSERT_EFI_ERROR (Status);
}
-VOID
-CoreUpdateDebugTableCrc32 (
- VOID
- )
-/*++
-
-Routine Description:
+/**
Update the CRC32 in the Debug Table.
Since the CRC32 service is made available by the Runtime driver, we have to
wait for the Runtime Driver to be installed before the CRC32 can be computed.
This function is called elsewhere by the core when the runtime architectural
protocol is produced.
-Arguments:
- None
-
-Returns:
- NA
-
---*/
+**/
+VOID
+CoreUpdateDebugTableCrc32 (
+ VOID
+ )
{
ASSERT(mDebugTable != NULL);
mDebugTable->Crc32 = 0;
gDxeCoreBS->CalculateCrc32 ((VOID *)mDebugTable, sizeof (EFI_SYSTEM_TABLE_POINTER), &mDebugTable->Crc32);
}
+
+/**
+ Adds a new DebugImageInfo structure to the DebugImageInfo Table. Re-Allocates
+ the table if it's not large enough to accomidate another entry.
+
+ @param ImageInfoType type of debug image information
+ @param LoadedImage pointer to the loaded image protocol for the image being
+ loaded
+ @param ImageHandle image handle for the image being loaded
+
+**/
VOID
CoreNewDebugImageInfoEntry (
IN UINT32 ImageInfoType,
IN EFI_LOADED_IMAGE_PROTOCOL *LoadedImage,
IN EFI_HANDLE ImageHandle
)
-/*++
-
-Routine Description:
-
- Adds a new DebugImageInfo structure to the DebugImageInfo Table. Re-Allocates
- the table if it's not large enough to accomidate another entry.
-
-Arguments:
-
- ImageInfoType - type of debug image information
- LoadedImage - pointer to the loaded image protocol for the image being loaded
- ImageHandle - image handle for the image being loaded
-
-Returns:
- NA
-
---*/
{
EFI_DEBUG_IMAGE_INFO *Table;
EFI_DEBUG_IMAGE_INFO *NewTable;
@@ -211,25 +189,17 @@ Returns:
}
+
+/**
+ Removes and frees an entry from the DebugImageInfo Table.
+
+ @param ImageHandle image handle for the image being unloaded
+
+**/
VOID
CoreRemoveDebugImageInfoEntry (
EFI_HANDLE ImageHandle
)
-/*++
-
-Routine Description:
-
- Removes and frees an entry from the DebugImageInfo Table.
-
-Arguments:
-
- ImageHandle - image handle for the image being unloaded
-
-Returns:
-
- NA
-
---*/
{
EFI_DEBUG_IMAGE_INFO *Table;
UINTN Index;
@@ -252,3 +222,4 @@ Returns:
mDebugInfoTableHeader.UpdateStatus &= ~EFI_DEBUG_IMAGE_INFO_UPDATE_IN_PROGRESS;
}
+
diff --git a/MdeModulePkg/Core/Dxe/Misc/InstallConfigurationTable.c b/MdeModulePkg/Core/Dxe/Misc/InstallConfigurationTable.c
index 26db2fbc1f..95d0393a84 100644
--- a/MdeModulePkg/Core/Dxe/Misc/InstallConfigurationTable.c
+++ b/MdeModulePkg/Core/Dxe/Misc/InstallConfigurationTable.c
@@ -20,30 +20,23 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
UINTN mSystemTableAllocateSize = 0;
+
+/**
+ Find a config table by name in system table's ConfigurationTable.
+
+ @param Guid The table name to look for
+ @param Table Pointer of the config table
+
+ @retval EFI_NOT_FOUND Could not find the table in system table's
+ ConfigurationTable.
+ @retval EFI_SUCCESS Table successfully found.
+
+**/
EFI_STATUS
CoreGetConfigTable (
IN EFI_GUID *Guid,
OUT VOID **Table
)
-/*++
-
-Routine Description:
-
- Find a config table by name in system table's ConfigurationTable.
-
-Arguments:
-
- Guid - The table name to look for
-
- Table - Pointer of the config table
-
-Returns:
-
- EFI_NOT_FOUND - Could not find the table in system table's ConfigurationTable.
-
- EFI_SUCCESS - Table successfully found.
-
---*/
{
UINTN Index;
@@ -59,33 +52,28 @@ Returns:
+
+/**
+ Boot Service called to add, modify, or remove a system configuration table from
+ the EFI System Table.
+
+ @param Guid Pointer to the GUID for the entry to add, update, or
+ remove
+ @param Table Pointer to the configuration table for the entry to add,
+ update, or remove, may be NULL.
+
+ @return EFI_SUCCESS Guid, Table pair added, updated, or removed.
+ @return EFI_INVALID_PARAMETER Input GUID not valid.
+ @return EFI_NOT_FOUND Attempted to delete non-existant entry
+ @return EFI_OUT_OF_RESOURCES Not enough memory available
+
+**/
EFI_STATUS
EFIAPI
CoreInstallConfigurationTable (
IN EFI_GUID *Guid,
IN VOID *Table
)
-/*++
-
-Routine Description:
-
- Boot Service called to add, modify, or remove a system configuration table from
- the EFI System Table.
-
-Arguments:
-
- Guid - Pointer to the GUID for the entry to add, update, or remove
- Table - Pointer to the configuration table for the entry to add, update, or
- remove, may be NULL.
-
-Returns:
-
- EFI_SUCCESS Guid, Table pair added, updated, or removed.
- EFI_INVALID_PARAMETER Input GUID not valid.
- EFI_NOT_FOUND Attempted to delete non-existant entry
- EFI_OUT_OF_RESOURCES Not enough memory available
-
---*/
{
UINTN Index;
EFI_CONFIGURATION_TABLE *EfiConfigurationTable;
diff --git a/MdeModulePkg/Core/Dxe/Misc/SetWatchdogTimer.c b/MdeModulePkg/Core/Dxe/Misc/SetWatchdogTimer.c
index 94e8db35ab..c17c1a8deb 100644
--- a/MdeModulePkg/Core/Dxe/Misc/SetWatchdogTimer.c
+++ b/MdeModulePkg/Core/Dxe/Misc/SetWatchdogTimer.c
@@ -17,7 +17,28 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
#define WATCHDOG_TIMER_CALIBRATE_PER_SECOND 10000000
+/**
+ Sets the system's watchdog timer.
+ @param Timeout The number of seconds to set the watchdog timer to.
+ A value of zero disables the timer.
+ @param WatchdogCode The numeric code to log on a watchdog timer timeout
+ event. The firmware reserves codes 0x0000 to 0xFFFF.
+ Loaders and operating systems may use other timeout
+ codes.
+ @param DataSize The size, in bytes, of WatchdogData.
+ @param WatchdogData A data buffer that includes a Null-terminated Unicode
+ string, optionally followed by additional binary data.
+ The string is a description that the call may use to
+ further indicate the reason to be logged with a
+ watchdog event.
+
+ @return EFI_SUCCESS Timeout has been set
+ @return EFI_NOT_AVAILABLE_YET WatchdogTimer is not available yet
+ @return EFI_UNSUPPORTED System does not have a timer (currently not used)
+ @return EFI_DEVICE_ERROR Could not complete due to hardware error
+
+**/
EFI_STATUS
EFIAPI
CoreSetWatchdogTimer (
@@ -26,31 +47,6 @@ CoreSetWatchdogTimer (
IN UINTN DataSize,
IN CHAR16 *WatchdogData OPTIONAL
)
-/*++
-
-Routine Description:
-
- Sets the system's watchdog timer.
-
-Arguments:
-
- Timeout The number of seconds. Zero disables the timer.
-
- ///////following three parameters are left for platform specific using
-
- WatchdogCode The numberic code to log. 0x0 to 0xffff are firmware
- DataSize Size of the optional data
- WatchdogData Optional Null terminated unicode string followed by binary
- data.
-
-Returns:
-
- EFI_SUCCESS Timeout has been set
- EFI_NOT_AVAILABLE_YET WatchdogTimer is not available yet
- EFI_UNSUPPORTED System does not have a timer (currently not used)
- EFI_DEVICE_ERROR Could not complete due to hardware error
-
---*/
{
EFI_STATUS Status;
diff --git a/MdeModulePkg/Core/Dxe/Misc/Stall.c b/MdeModulePkg/Core/Dxe/Misc/Stall.c
index db32c1fa3a..8ab48e6cf3 100644
--- a/MdeModulePkg/Core/Dxe/Misc/Stall.c
+++ b/MdeModulePkg/Core/Dxe/Misc/Stall.c
@@ -20,29 +20,22 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
#include <DxeMain.h>
+
+/**
+ Introduces a fine-grained stall.
+
+ @param Microseconds The number of microseconds to stall execution.
+
+ @retval EFI_SUCCESS Execution was stalled for at least the requested
+ amount of microseconds.
+ @retval EFI_NOT_AVAILABLE_YET gMetronome is not available yet
+
+**/
EFI_STATUS
EFIAPI
CoreStall (
IN UINTN Microseconds
)
-/*++
-
-Routine Description:
-
- Introduces a fine-grained stall.
-
-Arguments:
-
- Microseconds The number of microseconds to stall execution
-
-Returns:
-
- EFI_SUCCESS - Execution was stalled for at least the requested amount
- of microseconds.
-
- EFI_NOT_AVAILABLE_YET - gMetronome is not available yet
-
---*/
{
UINT32 Counter;
UINT32 Remainder;
diff --git a/MdeModulePkg/Core/Dxe/SectionExtraction/CoreSectionExtraction.c b/MdeModulePkg/Core/Dxe/SectionExtraction/CoreSectionExtraction.c
index 8d33322c42..54049cffb6 100644
--- a/MdeModulePkg/Core/Dxe/SectionExtraction/CoreSectionExtraction.c
+++ b/MdeModulePkg/Core/Dxe/SectionExtraction/CoreSectionExtraction.c
@@ -1,4 +1,4 @@
-/**@file
+/** @file
Section Extraction Protocol implementation.
Stream database is implemented as a linked list of section streams,
@@ -27,7 +27,7 @@
3) A support protocol is not found, and the data is not available to be read
without it. This results in EFI_PROTOCOL_ERROR.
-Copyright (c) 2006 - 2007, Intel Corporation
+Copyright (c) 2006 - 2008, Intel Corporation
All rights reserved. This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
@@ -100,6 +100,21 @@ typedef struct {
// Local prototypes
//
+/**
+ Worker function. Determine if the input stream:child matches the input type.
+
+ @param Stream Indicates the section stream associated with the
+ child
+ @param Child Indicates the child to check
+ @param SearchType Indicates the type of section to check against
+ for
+ @param SectionDefinitionGuid Indicates the GUID to check against if the type
+ is EFI_SECTION_GUID_DEFINED
+
+ @retval TRUE The child matches
+ @retval FALSE The child doesn't match
+
+**/
STATIC
BOOLEAN
ChildIsType (
@@ -110,6 +125,15 @@ ChildIsType (
);
#if 0
+/**
+ RPN callback function. Removes a stale section stream and re-initializes it
+ with an updated AuthenticationStatus.
+
+ @param Event The event that fired
+ @param RpnContext A pointer to the context that allows us to
+ identify the relevent encapsulation...
+
+**/
STATIC
VOID
EFIAPI
@@ -120,6 +144,16 @@ NotifyGuidedExtraction (
#endif
#if 0
+/**
+ Worker function. Constructor for RPN event if needed to keep AuthenticationStatus
+ cache correct when a missing GUIDED_SECTION_EXTRACTION_PROTOCOL appears.
+
+ @param ParentStream Indicates the parent of the ecnapsulation
+ section (child)
+ @param ChildNode Indicates the child node that is the
+ encapsulation section.
+
+**/
STATIC
VOID
CreateGuidedExtractionRpnEvent (
@@ -128,6 +162,18 @@ CreateGuidedExtractionRpnEvent (
);
#endif
+/**
+ Worker function. Search stream database for requested stream handle.
+
+ @param SearchHandle Indicates which stream to look for.
+ @param FoundStream Output pointer to the found stream.
+
+ @retval EFI_SUCCESS StreamHandle was found and *FoundStream contains
+ the stream node.
+ @retval EFI_NOT_FOUND SearchHandle was not found in the stream
+ database.
+
+**/
STATIC
EFI_STATUS
FindStreamNode (
@@ -135,6 +181,32 @@ FindStreamNode (
OUT CORE_SECTION_STREAM_NODE **FoundStream
);
+/**
+ Worker function Recursively searches / builds section stream database
+ looking for requested section.
+
+ @param SourceStream Indicates the section stream in which to do the
+ search.
+ @param SearchType Indicates the type of section to search for.
+ @param SectionInstance Indicates which instance of section to find.
+ This is an in/out parameter to deal with
+ recursions.
+ @param SectionDefinitionGuid Guid of section definition
+ @param FoundChild Output indicating the child node that is found.
+ @param FoundStream Output indicating which section stream the child
+ was found in. If this stream was generated as a
+ result of an encapsulation section, the
+ streamhandle is visible within the SEP driver
+ only.
+ @param AuthenticationStatus Indicates the authentication status of the found section.
+
+ @retval EFI_SUCCESS Child node was found and returned.
+ EFI_OUT_OF_RESOURCES- Memory allocation failed.
+ @retval EFI_NOT_FOUND Requested child node does not exist.
+ @retval EFI_PROTOCOL_ERROR a required GUIDED section extraction protocol
+ does not exist
+
+**/
STATIC
EFI_STATUS
FindChildNode (
@@ -147,6 +219,27 @@ FindChildNode (
OUT UINT32 *AuthenticationStatus
);
+/**
+ Worker function. Constructor for new child nodes.
+
+ @param Stream Indicates the section stream in which to add the
+ child.
+ @param ChildOffset Indicates the offset in Stream that is the
+ beginning of the child section.
+ @param ChildNode Indicates the Callee allocated and initialized
+ child.
+
+ @retval EFI_SUCCESS Child node was found and returned.
+ EFI_OUT_OF_RESOURCES- Memory allocation failed.
+ @retval EFI_PROTOCOL_ERROR Encapsulation sections produce new stream
+ handles when the child node is created. If the
+ section type is GUID defined, and the extraction
+ GUID does not exist, and producing the stream
+ requires the GUID, then a protocol error is
+ generated and no child is produced. Values
+ returned by OpenSectionStreamEx.
+
+**/
STATIC
EFI_STATUS
CreateChildNode (
@@ -155,12 +248,51 @@ CreateChildNode (
OUT CORE_SECTION_CHILD_NODE **ChildNode
);
+/**
+ Worker function. Destructor for child nodes.
+
+ @param ChildNode Indicates the node to destroy
+
+**/
STATIC
VOID
FreeChildNode (
IN CORE_SECTION_CHILD_NODE *ChildNode
);
+/**
+ Worker function. Constructor for section streams.
+
+ @param SectionStreamLength Size in bytes of the section stream.
+ @param SectionStream Buffer containing the new section stream.
+ @param AllocateBuffer Indicates whether the stream buffer is to be
+ copied or the input buffer is to be used in
+ place. AuthenticationStatus- Indicates the
+ default authentication status for the new
+ stream.
+ @param AuthenticationStatus A pointer to a caller-allocated UINT32 that
+ indicates the authentication status of the
+ output buffer. If the input section��s
+ GuidedSectionHeader.Attributes field
+ has the EFI_GUIDED_SECTION_AUTH_STATUS_VALID
+ bit as clear, AuthenticationStatus must return
+ zero. Both local bits (19:16) and aggregate
+ bits (3:0) in AuthenticationStatus are returned
+ by ExtractSection(). These bits reflect the
+ status of the extraction operation. The bit
+ pattern in both regions must be the same, as
+ the local and aggregate authentication statuses
+ have equivalent meaning at this level. If the
+ function returns anything other than
+ EFI_SUCCESS, the value of *AuthenticationStatus
+ is undefined.
+ @param SectionStreamHandle A pointer to a caller allocated section stream
+ handle.
+
+ @retval EFI_SUCCESS Stream was added to stream database.
+ @retval EFI_OUT_OF_RESOURCES memory allocation failed.
+
+**/
STATIC
EFI_STATUS
OpenSectionStreamEx (
@@ -171,6 +303,15 @@ OpenSectionStreamEx (
OUT UINTN *SectionStreamHandle
);
+/**
+ Check if a stream is valid.
+
+ @param SectionStream The section stream to be checked
+ @param SectionStreamLength The length of section stream
+
+ @return A boolean value indicating the validness of the section stream.
+
+**/
STATIC
BOOLEAN
IsValidSectionStream (
@@ -178,6 +319,90 @@ IsValidSectionStream (
IN UINTN SectionStreamLength
);
+/**
+ The ExtractSection() function processes the input section and
+ allocates a buffer from the pool in which it returns the section
+ contents. If the section being extracted contains
+ authentication information (the section's
+ GuidedSectionHeader.Attributes field has the
+ EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit set), the values
+ returned in AuthenticationStatus must reflect the results of
+ the authentication operation. Depending on the algorithm and
+ size of the encapsulated data, the time that is required to do
+ a full authentication may be prohibitively long for some
+ classes of systems. To indicate this, use
+ EFI_SECURITY_POLICY_PROTOCOL_GUID, which may be published by
+ the security policy driver (see the Platform Initialization
+ Driver Execution Environment Core Interface Specification for
+ more details and the GUID definition). If the
+ EFI_SECURITY_POLICY_PROTOCOL_GUID exists in the handle
+ database, then, if possible, full authentication should be
+ skipped and the section contents simply returned in the
+ OutputBuffer. In this case, the
+ EFI_AUTH_STATUS_PLATFORM_OVERRIDE bit AuthenticationStatus
+ must be set on return. ExtractSection() is callable only from
+ TPL_NOTIFY and below. Behavior of ExtractSection() at any
+ EFI_TPL above TPL_NOTIFY is undefined. Type EFI_TPL is
+ defined in RaiseTPL() in the UEFI 2.0 specification.
+
+
+ @param This Indicates the
+ EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL instance.
+
+ @param InputSection Buffer containing the input GUIDed section
+ to be processed. OutputBuffer OutputBuffer
+ is allocated from boot services pool
+ memory and contains the new section
+ stream. The caller is responsible for
+ freeing this buffer.
+ @param OutputBuffer *OutputBuffer is allocated from boot services
+ pool memory and contains the new section stream.
+ The caller is responsible for freeing this buffer.
+ @param OutputSize A pointer to a caller-allocated UINTN in
+ which the size of OutputBuffer allocation
+ is stored. If the function returns
+ anything other than EFI_SUCCESS, the value
+ of OutputSize is undefined.
+
+ @param AuthenticationStatus A pointer to a caller-allocated
+ UINT32 that indicates the
+ authentication status of the
+ output buffer. If the input
+ section's
+ GuidedSectionHeader.Attributes
+ field has the
+ EFI_GUIDED_SECTION_AUTH_STATUS_VAL
+ bit as clear, AuthenticationStatus
+ must return zero. Both local bits
+ (19:16) and aggregate bits (3:0)
+ in AuthenticationStatus are
+ returned by ExtractSection().
+ These bits reflect the status of
+ the extraction operation. The bit
+ pattern in both regions must be
+ the same, as the local and
+ aggregate authentication statuses
+ have equivalent meaning at this
+ level. If the function returns
+ anything other than EFI_SUCCESS,
+ the value of AuthenticationStatus
+ is undefined.
+
+
+ @retval EFI_SUCCESS The InputSection was successfully
+ processed and the section contents were
+ returned.
+
+ @retval EFI_OUT_OF_RESOURCES The system has insufficient
+ resources to process the
+ request.
+
+ @retval EFI_INVALID_PARAMETER The GUID in InputSection does
+ not match this instance of the
+ GUIDed Section Extraction
+ Protocol.
+
+**/
EFI_STATUS
EFIAPI
CustomGuidedSectionExtract (
@@ -198,27 +423,24 @@ EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL mCustomGuidedSectionExtractionProtocol =
CustomGuidedSectionExtract
};
+
+/**
+ Entry point of the section extraction code. Initializes an instance of the
+ section extraction interface and installs it on a new handle.
+
+ @param ImageHandle A handle for the image that is initializing this driver
+ @param SystemTable A pointer to the EFI system table
+
+ @retval EFI_SUCCESS Driver initialized successfully
+ @retval EFI_OUT_OF_RESOURCES Could not allocate needed resources
+
+**/
EFI_STATUS
EFIAPI
InitializeSectionExtraction (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
-/*++
-
-Routine Description:
- Entry point of the section extraction code. Initializes an instance of the
- section extraction interface and installs it on a new handle.
-
-Arguments:
- ImageHandle EFI_HANDLE: A handle for the image that is initializing this driver
- SystemTable EFI_SYSTEM_TABLE: A pointer to the EFI system table
-
-Returns:
- EFI_SUCCESS: Driver initialized successfully
- EFI_OUT_OF_RESOURCES: Could not allocate needed resources
-
---*/
{
EFI_STATUS Status;
EFI_GUID *ExtractHandlerGuidTable;
@@ -246,6 +468,22 @@ Returns:
return Status;
}
+
+/**
+ SEP member function. This function creates and returns a new section stream
+ handle to represent the new section stream.
+
+ @param SectionStreamLength Size in bytes of the section stream.
+ @param SectionStream Buffer containing the new section stream.
+ @param SectionStreamHandle A pointer to a caller allocated UINTN that on
+ output contains the new section stream handle.
+
+ @retval EFI_SUCCESS The section stream is created successfully.
+ @retval EFI_OUT_OF_RESOURCES memory allocation failed.
+ @retval EFI_INVALID_PARAMETER Section stream does not end concident with end
+ of last section.
+
+**/
EFI_STATUS
EFIAPI
OpenSectionStream (
@@ -253,26 +491,6 @@ OpenSectionStream (
IN VOID *SectionStream,
OUT UINTN *SectionStreamHandle
)
-/*++
-
-Routine Description:
- SEP member function. This function creates and returns a new section stream
- handle to represent the new section stream.
-
-Arguments:
- This - Indicates the calling context.
- SectionStreamLength - Size in bytes of the section stream.
- SectionStream - Buffer containing the new section stream.
- SectionStreamHandle - A pointer to a caller allocated UINTN that on output
- contains the new section stream handle.
-
-Returns:
- EFI_SUCCESS
- EFI_OUT_OF_RESOURCES - memory allocation failed.
- EFI_INVALID_PARAMETER - section stream does not end concident with end of
- last section.
-
---*/
{
//
// Check to see section stream looks good...
@@ -290,6 +508,64 @@ Returns:
);
}
+
+/**
+ SEP member function. Retrieves requested section from section stream.
+
+ @param SectionStreamHandle The section stream from which to extract the
+ requested section.
+ @param SectionType A pointer to the type of section to search for.
+ @param SectionDefinitionGuid If the section type is EFI_SECTION_GUID_DEFINED,
+ then SectionDefinitionGuid indicates which of
+ these types of sections to search for.
+ @param SectionInstance Indicates which instance of the requested
+ section to return.
+ @param Buffer Double indirection to buffer. If *Buffer is
+ non-null on input, then the buffer is caller
+ allocated. If Buffer is NULL, then the buffer
+ is callee allocated. In either case, the
+ requried buffer size is returned in *BufferSize.
+ @param BufferSize On input, indicates the size of *Buffer if
+ *Buffer is non-null on input. On output,
+ indicates the required size (allocated size if
+ callee allocated) of *Buffer.
+ @param AuthenticationStatus A pointer to a caller-allocated UINT32 that
+ indicates the authentication status of the
+ output buffer. If the input section��s
+ GuidedSectionHeader.Attributes field
+ has the EFI_GUIDED_SECTION_AUTH_STATUS_VALID
+ bit as clear, AuthenticationStatus must return
+ zero. Both local bits (19:16) and aggregate
+ bits (3:0) in AuthenticationStatus are returned
+ by ExtractSection(). These bits reflect the
+ status of the extraction operation. The bit
+ pattern in both regions must be the same, as
+ the local and aggregate authentication statuses
+ have equivalent meaning at this level. If the
+ function returns anything other than
+ EFI_SUCCESS, the value of *AuthenticationStatus
+ is undefined.
+
+ @retval EFI_SUCCESS Section was retrieved successfully
+ @retval EFI_PROTOCOL_ERROR A GUID defined section was encountered in the
+ section stream with its
+ EFI_GUIDED_SECTION_PROCESSING_REQUIRED bit set,
+ but there was no corresponding GUIDed Section
+ Extraction Protocol in the handle database.
+ *Buffer is unmodified.
+ @retval EFI_NOT_FOUND An error was encountered when parsing the
+ SectionStream. This indicates the SectionStream
+ is not correctly formatted.
+ @retval EFI_NOT_FOUND The requested section does not exist.
+ @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to process
+ the request.
+ @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
+ @retval EFI_WARN_TOO_SMALL The size of the caller allocated input buffer is
+ insufficient to contain the requested section.
+ The input buffer is filled and section contents
+ are truncated.
+
+**/
EFI_STATUS
EFIAPI
GetSection (
@@ -301,51 +577,6 @@ GetSection (
IN OUT UINTN *BufferSize,
OUT UINT32 *AuthenticationStatus
)
-/*++
-
-Routine Description:
- SEP member function. Retrieves requested section from section stream.
-
-Arguments:
- SectionStreamHandle: The section stream from which to extract the requested
- section.
- SectionType: A pointer to the type of section to search for.
- SectionDefinitionGuid: If the section type is EFI_SECTION_GUID_DEFINED, then
- SectionDefinitionGuid indicates which of these types
- of sections to search for.
- SectionInstance: Indicates which instance of the requested section to
- return.
- Buffer: Double indirection to buffer. If *Buffer is non-null on
- input, then the buffer is caller allocated. If
- *Buffer is NULL, then the buffer is callee allocated.
- In either case, the requried buffer size is returned
- in *BufferSize.
- BufferSize: On input, indicates the size of *Buffer if *Buffer is
- non-null on input. On output, indicates the required
- size (allocated size if callee allocated) of *Buffer.
- AuthenticationStatus: Indicates the authentication status of the retrieved
- section.
-
-Returns:
- EFI_SUCCESS: Section was retrieved successfully
- EFI_PROTOCOL_ERROR: A GUID defined section was encountered in the section
- stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED
- bit set, but there was no corresponding GUIDed Section
- Extraction Protocol in the handle database. *Buffer is
- unmodified.
- EFI_NOT_FOUND: An error was encountered when parsing the SectionStream.
- This indicates the SectionStream is not correctly
- formatted.
- EFI_NOT_FOUND: The requested section does not exist.
- EFI_OUT_OF_RESOURCES: The system has insufficient resources to process the
- request.
- EFI_INVALID_PARAMETER: The SectionStreamHandle does not exist.
- EFI_WARN_TOO_SMALL: The size of the caller allocated input buffer is
- insufficient to contain the requested section. The
- input buffer is filled and contents are section contents
- are truncated.
-
---*/
{
CORE_SECTION_STREAM_NODE *StreamNode;
EFI_TPL OldTpl;
@@ -430,27 +661,23 @@ GetSection_Done:
}
+
+/**
+ SEP member function. Deletes an existing section stream
+
+ @param StreamHandleToClose Indicates the stream to close
+
+ @retval EFI_SUCCESS The section stream is closed sucessfully.
+ @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
+ @retval EFI_INVALID_PARAMETER Section stream does not end concident with end
+ of last section.
+
+**/
EFI_STATUS
EFIAPI
CloseSectionStream (
IN UINTN StreamHandleToClose
)
-/*++
-
-Routine Description:
- SEP member function. Deletes an existing section stream
-
-Arguments:
- This - Indicates the calling context.
- StreamHandleToClose - Indicates the stream to close
-
-Returns:
- EFI_SUCCESS
- EFI_OUT_OF_RESOURCES - memory allocation failed.
- EFI_INVALID_PARAMETER - section stream does not end concident with end of
- last section.
-
---*/
{
CORE_SECTION_STREAM_NODE *StreamNode;
EFI_TPL OldTpl;
@@ -486,6 +713,22 @@ Returns:
}
+
+/**
+ Worker function. Determine if the input stream:child matches the input type.
+
+ @param Stream Indicates the section stream associated with the
+ child
+ @param Child Indicates the child to check
+ @param SearchType Indicates the type of section to check against
+ for
+ @param SectionDefinitionGuid Indicates the GUID to check against if the type
+ is EFI_SECTION_GUID_DEFINED
+
+ @retval TRUE The child matches
+ @retval FALSE The child doesn't match
+
+**/
STATIC
BOOLEAN
ChildIsType (
@@ -494,22 +737,6 @@ ChildIsType (
IN EFI_SECTION_TYPE SearchType,
IN EFI_GUID *SectionDefinitionGuid
)
-/*++
-
-Routine Description:
- Worker function. Determine if the input stream:child matches the input type.
-
-Arguments:
- Stream - Indicates the section stream associated with the child
- Child - Indicates the child to check
- SearchType - Indicates the type of section to check against for
- SectionDefinitionGuid - Indicates the GUID to check against if the type is
- EFI_SECTION_GUID_DEFINED
-Returns:
- TRUE - The child matches
- FALSE - The child doesn't match
-
---*/
{
EFI_GUID_DEFINED_SECTION *GuidedSection;
@@ -527,6 +754,33 @@ Returns:
}
+
+/**
+ Worker function Recursively searches / builds section stream database
+ looking for requested section.
+
+ @param SourceStream Indicates the section stream in which to do the
+ search.
+ @param SearchType Indicates the type of section to search for.
+ @param SectionInstance Indicates which instance of section to find.
+ This is an in/out parameter to deal with
+ recursions.
+ @param SectionDefinitionGuid Guid of section definition
+ @param FoundChild Output indicating the child node that is found.
+ @param FoundStream Output indicating which section stream the child
+ was found in. If this stream was generated as a
+ result of an encapsulation section, the
+ streamhandle is visible within the SEP driver
+ only.
+ @param AuthenticationStatus Indicates the authentication status of the found section.
+
+ @retval EFI_SUCCESS Child node was found and returned.
+ EFI_OUT_OF_RESOURCES- Memory allocation failed.
+ @retval EFI_NOT_FOUND Requested child node does not exist.
+ @retval EFI_PROTOCOL_ERROR a required GUIDED section extraction protocol
+ does not exist
+
+**/
STATIC
EFI_STATUS
FindChildNode (
@@ -538,33 +792,6 @@ FindChildNode (
OUT CORE_SECTION_STREAM_NODE **FoundStream,
OUT UINT32 *AuthenticationStatus
)
-/*++
-
-Routine Description:
- Worker function Recursively searches / builds section stream database
- looking for requested section.
-
-Arguments:
- SourceStream - Indicates the section stream in which to do the search.
- SearchType - Indicates the type of section to search for.
- SectionInstance - Indicates which instance of section to find. This is
- an in/out parameter to deal with recursions.
- SectionDefinitionGuid - Guid of section definition
- FoundChild - Output indicating the child node that is found.
- FoundStream - Output indicating which section stream the child was
- found in. If this stream was generated as a result of
- an encapsulation section, the streamhandle is visible
- within the SEP driver only.
- AuthenticationStatus- Indicates the authentication status of the found section.
-
-Returns:
- EFI_SUCCESS - Child node was found and returned.
- EFI_OUT_OF_RESOURCES- Memory allocation failed.
- EFI_NOT_FOUND - Requested child node does not exist.
- EFI_PROTOCOL_ERROR - a required GUIDED section extraction protocol does not
- exist
-
---*/
{
CORE_SECTION_CHILD_NODE *CurrentChildNode;
CORE_SECTION_CHILD_NODE *RecursedChildNode;
@@ -684,6 +911,28 @@ Returns:
}
+
+/**
+ Worker function. Constructor for new child nodes.
+
+ @param Stream Indicates the section stream in which to add the
+ child.
+ @param ChildOffset Indicates the offset in Stream that is the
+ beginning of the child section.
+ @param ChildNode Indicates the Callee allocated and initialized
+ child.
+
+ @retval EFI_SUCCESS Child node was found and returned.
+ EFI_OUT_OF_RESOURCES- Memory allocation failed.
+ @retval EFI_PROTOCOL_ERROR Encapsulation sections produce new stream
+ handles when the child node is created. If the
+ section type is GUID defined, and the extraction
+ GUID does not exist, and producing the stream
+ requires the GUID, then a protocol error is
+ generated and no child is produced. Values
+ returned by OpenSectionStreamEx.
+
+**/
STATIC
EFI_STATUS
CreateChildNode (
@@ -691,28 +940,6 @@ CreateChildNode (
IN UINT32 ChildOffset,
OUT CORE_SECTION_CHILD_NODE **ChildNode
)
-/*++
-
-Routine Description:
- Worker function. Constructor for new child nodes.
-
-Arguments:
- Stream - Indicates the section stream in which to add the child.
- ChildOffset - Indicates the offset in Stream that is the beginning
- of the child section.
- ChildNode - Indicates the Callee allocated and initialized child.
-
-Returns:
- EFI_SUCCESS - Child node was found and returned.
- EFI_OUT_OF_RESOURCES- Memory allocation failed.
- EFI_PROTOCOL_ERROR - Encapsulation sections produce new stream handles when
- the child node is created. If the section type is GUID
- defined, and the extraction GUID does not exist, and
- producing the stream requires the GUID, then a protocol
- error is generated and no child is produced.
- Values returned by OpenSectionStreamEx.
-
---*/
{
EFI_STATUS Status;
EFI_COMMON_SECTION_HEADER *SectionHeader;
@@ -939,26 +1166,22 @@ Returns:
#if 0
+/**
+ Worker function. Constructor for RPN event if needed to keep AuthenticationStatus
+ cache correct when a missing GUIDED_SECTION_EXTRACTION_PROTOCOL appears...
+
+ @param ParentStream Indicates the parent of the ecnapsulation
+ section (child)
+ @param ChildNode Indicates the child node that is the
+ encapsulation section.
+
+**/
STATIC
VOID
CreateGuidedExtractionRpnEvent (
IN CORE_SECTION_STREAM_NODE *ParentStream,
IN CORE_SECTION_CHILD_NODE *ChildNode
)
-/*++
-
-Routine Description:
- Worker function. Constructor for RPN event if needed to keep AuthenticationStatus
- cache correct when a missing GUIDED_SECTION_EXTRACTION_PROTOCOL appears...
-
-Arguments:
- ParentStream - Indicates the parent of the ecnapsulation section (child)
- ChildNode - Indicates the child node that is the encapsulation section.
-
-Returns:
- None
-
---*/
{
RPN_EVENT_CONTEXT *Context;
@@ -984,6 +1207,15 @@ Returns:
#if 0
+/**
+ RPN callback function. Removes a stale section stream and re-initializes it
+ with an updated AuthenticationStatus.
+
+ @param Event The event that fired
+ @param RpnContext A pointer to the context that allows us to
+ identify the relevent encapsulation...
+
+**/
STATIC
VOID
EFIAPI
@@ -991,21 +1223,6 @@ NotifyGuidedExtraction (
IN EFI_EVENT Event,
IN VOID *RpnContext
)
-/*++
-
-Routine Description:
- RPN callback function. Removes a stale section stream and re-initializes it
- with an updated AuthenticationStatus.
-
-Arguments:
- Event - The event that fired
- RpnContext - A pointer to the context that allows us to identify
- the relevent encapsulation...
-
-Returns:
- None
-
---*/
{
EFI_STATUS Status;
EFI_GUID_DEFINED_SECTION *GuidedHeader;
@@ -1064,24 +1281,17 @@ Returns:
}
#endif
+/**
+ Worker function. Destructor for child nodes.
+ @param ChildNode Indicates the node to destroy
+
+**/
STATIC
VOID
FreeChildNode (
IN CORE_SECTION_CHILD_NODE *ChildNode
)
-/*++
-
-Routine Description:
- Worker function. Destructor for child nodes.
-
-Arguments:
- ChildNode - Indicates the node to destroy
-
-Returns:
- none
-
---*/
{
ASSERT (ChildNode->Signature == CORE_SECTION_CHILD_SIGNATURE);
//
@@ -1103,6 +1313,40 @@ Returns:
}
+
+/**
+ Worker function. Constructor for section streams.
+
+ @param SectionStreamLength Size in bytes of the section stream.
+ @param SectionStream Buffer containing the new section stream.
+ @param AllocateBuffer Indicates whether the stream buffer is to be
+ copied or the input buffer is to be used in
+ place. AuthenticationStatus- Indicates the
+ default authentication status for the new
+ stream.
+ @param AuthenticationStatus A pointer to a caller-allocated UINT32 that
+ indicates the authentication status of the
+ output buffer. If the input section��s
+ GuidedSectionHeader.Attributes field
+ has the EFI_GUIDED_SECTION_AUTH_STATUS_VALID
+ bit as clear, AuthenticationStatus must return
+ zero. Both local bits (19:16) and aggregate
+ bits (3:0) in AuthenticationStatus are returned
+ by ExtractSection(). These bits reflect the
+ status of the extraction operation. The bit
+ pattern in both regions must be the same, as
+ the local and aggregate authentication statuses
+ have equivalent meaning at this level. If the
+ function returns anything other than
+ EFI_SUCCESS, the value of *AuthenticationStatus
+ is undefined.
+ @param SectionStreamHandle A pointer to a caller allocated section stream
+ handle.
+
+ @retval EFI_SUCCESS Stream was added to stream database.
+ @retval EFI_OUT_OF_RESOURCES memory allocation failed.
+
+**/
STATIC
EFI_STATUS
OpenSectionStreamEx (
@@ -1112,25 +1356,6 @@ OpenSectionStreamEx (
IN UINT32 AuthenticationStatus,
OUT UINTN *SectionStreamHandle
)
-/*++
-
- Routine Description:
- Worker function. Constructor for section streams.
-
- Arguments:
- SectionStreamLength - Size in bytes of the section stream.
- SectionStream - Buffer containing the new section stream.
- AllocateBuffer - Indicates whether the stream buffer is to be copied
- or the input buffer is to be used in place.
- AuthenticationStatus- Indicates the default authentication status for the
- new stream.
- SectionStreamHandle - A pointer to a caller allocated section stream handle.
-
- Returns:
- EFI_SUCCESS - Stream was added to stream database.
- EFI_OUT_OF_RESOURCES - memory allocation failed.
-
---*/
{
CORE_SECTION_STREAM_NODE *NewStream;
EFI_TPL OldTpl;
@@ -1195,27 +1420,25 @@ OpenSectionStreamEx (
}
+
+/**
+ Worker function. Search stream database for requested stream handle.
+
+ @param SearchHandle Indicates which stream to look for.
+ @param FoundStream Output pointer to the found stream.
+
+ @retval EFI_SUCCESS StreamHandle was found and *FoundStream contains
+ the stream node.
+ @retval EFI_NOT_FOUND SearchHandle was not found in the stream
+ database.
+
+**/
STATIC
EFI_STATUS
FindStreamNode (
IN UINTN SearchHandle,
OUT CORE_SECTION_STREAM_NODE **FoundStream
)
-/*++
-
- Routine Description:
- Worker function. Search stream database for requested stream handle.
-
- Arguments:
- SearchHandle - Indicates which stream to look for.
- FoundStream - Output pointer to the found stream.
-
- Returns:
- EFI_SUCCESS - StreamHandle was found and *FoundStream contains
- the stream node.
- EFI_NOT_FOUND - SearchHandle was not found in the stream database.
-
---*/
{
CORE_SECTION_STREAM_NODE *StreamNode;
@@ -1237,26 +1460,22 @@ FindStreamNode (
}
+
+/**
+ Check if a stream is valid.
+
+ @param SectionStream The section stream to be checked
+ @param SectionStreamLength The length of section stream
+
+ @return A boolean value indicating the validness of the section stream.
+
+**/
STATIC
BOOLEAN
IsValidSectionStream (
IN VOID *SectionStream,
IN UINTN SectionStreamLength
)
-/*++
-
-Routine Description:
- Check if a stream is valid.
-
-Arguments:
- SectionStream - The section stream to be checked
- SectionStreamLength - The length of section stream
-
-Returns:
- TRUE
- FALSE
-
---*/
{
UINTN TotalLength;
UINTN SectionLength;
@@ -1319,16 +1538,18 @@ Returns:
defined in RaiseTPL() in the UEFI 2.0 specification.
- @param This Indicates the
- EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL instance.
-
+ @param This Indicates the
+ EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL instance.
+
@param InputSection Buffer containing the input GUIDed section
to be processed. OutputBuffer OutputBuffer
is allocated from boot services pool
memory and contains the new section
stream. The caller is responsible for
freeing this buffer.
-
+ @param OutputBuffer *OutputBuffer is allocated from boot services
+ pool memory and contains the new section stream.
+ The caller is responsible for freeing this buffer.
@param OutputSize A pointer to a caller-allocated UINTN in
which the size of OutputBuffer allocation
is stored. If the function returns
@@ -1360,13 +1581,13 @@ Returns:
is undefined.
- @retval EFI_SUCCESS The InputSection was successfully
- processed and the section contents were
- returned.
+ @retval EFI_SUCCESS The InputSection was successfully
+ processed and the section contents were
+ returned.
- @retval EFI_OUT_OF_RESOURCES The system has insufficient
- resources to process the
- request.
+ @retval EFI_OUT_OF_RESOURCES The system has insufficient
+ resources to process the
+ request.
@retval EFI_INVALID_PARAMETER The GUID in InputSection does
not match this instance of the
@@ -1401,14 +1622,14 @@ CustomGuidedSectionExtract (
// Call GetInfo to get the size and attribute of input guided section data.
//
Status = ExtractGuidedSectionGetInfo (
- InputSection,
- &OutputBufferSize,
- &ScratchBufferSize,
- &SectionAttribute
- );
+ InputSection,
+ &OutputBufferSize,
+ &ScratchBufferSize,
+ &SectionAttribute
+ );
if (EFI_ERROR (Status)) {
- DEBUG ((EFI_D_ERROR, "GetInfo from guided section Failed - %r\n", Status));
+ DEBUG ((DEBUG_ERROR, "GetInfo from guided section Failed - %r\n", Status));
return Status;
}
@@ -1452,7 +1673,7 @@ CustomGuidedSectionExtract (
if (ScratchBuffer != NULL) {
CoreFreePool (ScratchBuffer);
}
- DEBUG ((EFI_D_ERROR, "Extract guided section Failed - %r\n", Status));
+ DEBUG ((DEBUG_ERROR, "Extract guided section Failed - %r\n", Status));
return Status;
}
diff --git a/MdeModulePkg/Core/Dxe/gcd.h b/MdeModulePkg/Core/Dxe/gcd.h
index 2672e1ec91..abe8730124 100644
--- a/MdeModulePkg/Core/Dxe/gcd.h
+++ b/MdeModulePkg/Core/Dxe/gcd.h
@@ -14,8 +14,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
-#ifndef _GCD_H
-#define _GCD_H
+#ifndef _GCD_H_
+#define _GCD_H_
//
// GCD Operations
diff --git a/MdeModulePkg/Core/Dxe/hand.h b/MdeModulePkg/Core/Dxe/hand.h
index 98669dea35..e52b7e390d 100644
--- a/MdeModulePkg/Core/Dxe/hand.h
+++ b/MdeModulePkg/Core/Dxe/hand.h
@@ -100,220 +100,151 @@ typedef struct {
//
+
+/**
+ Finds the protocol entry for the requested protocol.
+ The gProtocolDatabaseLock must be owned
+
+ @param Protocol The ID of the protocol
+ @param Create Create a new entry if not found
+
+ @return Protocol entry
+
+**/
PROTOCOL_ENTRY *
CoreFindProtocolEntry (
IN EFI_GUID *Protocol,
IN BOOLEAN Create
)
-/*++
-
-Routine Description:
-
- Finds the protocol entry for the requested protocol.
-
- The gProtocolDatabaseLock must be owned
-
-Arguments:
-
- Protocol - The ID of the protocol
-
- Create - Create a new entry if not found
-
-Returns:
-
- Protocol entry
-
---*/
;
+
+/**
+ Signal event for every protocol in protocol entry.
+
+ @param ProtEntry Protocol entry
+
+**/
VOID
CoreNotifyProtocolEntry (
IN PROTOCOL_ENTRY *ProtEntry
)
-/*++
-
-Routine Description:
-
- Signal event for every protocol in protocol entry.
-
-Arguments:
-
- ProtEntry - Protocol entry
-
-Returns:
-
---*/
;
+
+/**
+ Finds the protocol instance for the requested handle and protocol.
+ Note: This function doesn't do parameters checking, it's caller's responsibility
+ to pass in valid parameters.
+
+ @param Handle The handle to search the protocol on
+ @param Protocol GUID of the protocol
+ @param Interface The interface for the protocol being searched
+
+ @return Protocol instance (NULL: Not found)
+
+**/
PROTOCOL_INTERFACE *
CoreFindProtocolInterface (
IN IHANDLE *Handle,
IN EFI_GUID *Protocol,
IN VOID *Interface
)
-/*++
-
-Routine Description:
-
- Finds the protocol instance for the requested handle and protocol.
-
- Note: This function doesn't do parameters checking, it's caller's responsibility
- to pass in valid parameters.
-
-Arguments:
-
- Handle - The handle to search the protocol on
-
- Protocol - GUID of the protocol
-
- Interface - The interface for the protocol being searched
-
-Returns:
-
- Protocol instance (NULL: Not found)
-
---*/
;
+
+/**
+ Removes Protocol from the protocol list (but not the handle list).
+
+ @param Handle The handle to remove protocol on.
+ @param Protocol GUID of the protocol to be moved
+ @param Interface The interface of the protocol
+
+ @return Protocol Entry
+
+**/
PROTOCOL_INTERFACE *
CoreRemoveInterfaceFromProtocol (
IN IHANDLE *Handle,
IN EFI_GUID *Protocol,
IN VOID *Interface
)
-/*++
-
-Routine Description:
-
- Removes Protocol from the protocol list (but not the handle list).
-
-Arguments:
-
- Handle - The handle to remove protocol on.
-
- Protocol - GUID of the protocol to be moved
-
- Interface - The interface of the protocol
-
-Returns:
-
- Protocol Entry
-
---*/
;
+
+/**
+ Removes all the events in the protocol database that match Event.
+
+ @param Event The event to search for in the protocol
+ database.
+
+ @return EFI_SUCCESS when done searching the entire database.
+
+**/
EFI_STATUS
CoreUnregisterProtocolNotify (
IN EFI_EVENT Event
)
-/*++
-
-Routine Description:
-
- Removes all the events in the protocol database that match Event.
-
-Arguments:
-
- Event - The event to search for in the protocol database.
-
-Returns:
-
- EFI_SUCCESS when done searching the entire database.
-
---*/
;
+
+/**
+ Attempts to disconnect all drivers that are using the protocol interface being queried.
+ If failed, reconnect all drivers disconnected.
+ Note: This function doesn't do parameters checking, it's caller's responsibility
+ to pass in valid parameters.
+
+ @param UserHandle The handle on which the protocol is installed
+ @param Prot The protocol to disconnect drivers from
+
+ @retval EFI_SUCCESS Drivers using the protocol interface are all
+ disconnected
+ @retval EFI_ACCESS_DENIED Failed to disconnect one or all of the drivers
+
+**/
EFI_STATUS
CoreDisconnectControllersUsingProtocolInterface (
IN EFI_HANDLE UserHandle,
IN PROTOCOL_INTERFACE *Prot
)
-/*++
-
-Routine Description:
-
- Attempts to disconnect all drivers that are using the protocol interface being queried.
- If failed, reconnect all drivers disconnected.
-
- Note: This function doesn't do parameters checking, it's caller's responsibility
- to pass in valid parameters.
-
-Arguments:
-
- UserHandle - The handle on which the protocol is installed
- Prot - The protocol to disconnect drivers from
-
-Returns:
-
- EFI_SUCCESS - Drivers using the protocol interface are all disconnected
- EFI_ACCESS_DENIED - Failed to disconnect one or all of the drivers
-
---*/
;
+
+/**
+ Acquire lock on gProtocolDatabaseLock.
+
+**/
VOID
CoreAcquireProtocolLock (
VOID
)
-/*++
-
-Routine Description:
-
- Acquire lock on gProtocolDatabaseLock.
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
;
+
+/**
+ Release lock on gProtocolDatabaseLock.
+
+**/
VOID
CoreReleaseProtocolLock (
VOID
)
-/*++
-
-Routine Description:
-
- Release lock on gProtocolDatabaseLock.
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
;
+
+/**
+ Check whether a handle is a valid EFI_HANDLE
+
+ @param UserHandle The handle to check
+
+ @retval EFI_INVALID_PARAMETER The handle is NULL or not a valid EFI_HANDLE.
+ @retval EFI_SUCCESS The handle is valid EFI_HANDLE.
+
+**/
EFI_STATUS
CoreValidateHandle (
IN EFI_HANDLE UserHandle
)
-/*++
-
-Routine Description:
-
- Check whether a handle is a valid EFI_HANDLE
-
-Arguments:
-
- UserHandle - The handle to check
-
-Returns:
-
- EFI_INVALID_PARAMETER - The handle is NULL or not a valid EFI_HANDLE.
-
- EFI_SUCCESS - The handle is valid EFI_HANDLE.
-
---*/
;
//
diff --git a/MdeModulePkg/Core/Dxe/imem.h b/MdeModulePkg/Core/Dxe/imem.h
index a9df0ba5b0..0caaa4303e 100644
--- a/MdeModulePkg/Core/Dxe/imem.h
+++ b/MdeModulePkg/Core/Dxe/imem.h
@@ -11,7 +11,8 @@ http://opensource.org/licenses/bsd-license.php
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
---*/
+
+**/
#ifndef _IMEM_H_
#define _IMEM_H_
@@ -55,155 +56,100 @@ typedef struct {
// Internal prototypes
//
+
+/**
+ Internal function. Used by the pool functions to allocate pages
+ to back pool allocation requests.
+
+ @param PoolType The type of memory for the new pool pages
+ @param NumberOfPages No of pages to allocate
+ @param Alignment Bits to align.
+
+ @return The allocated memory, or NULL
+
+**/
VOID *
CoreAllocatePoolPages (
IN EFI_MEMORY_TYPE PoolType,
IN UINTN NumberOfPages,
IN UINTN Alignment
)
-/*++
-
-Routine Description:
-
- Internal function. Used by the pool functions to allocate pages
- to back pool allocation requests.
-
-Arguments:
-
- PoolType - The type of memory for the new pool pages
-
- NumberOfPages - No of pages to allocate
-
- Alignment - Bits to align.
-
-Returns:
-
- The allocated memory, or NULL
-
---*/
;
+
+/**
+ Internal function. Frees pool pages allocated via AllocatePoolPages ()
+
+ @param Memory The base address to free
+ @param NumberOfPages The number of pages to free
+
+**/
VOID
CoreFreePoolPages (
IN EFI_PHYSICAL_ADDRESS Memory,
IN UINTN NumberOfPages
)
-/*++
-
-Routine Description:
-
- Internal function. Frees pool pages allocated via AllocatePoolPages ()
-
-Arguments:
-
- Memory - The base address to free
-
- NumberOfPages - The number of pages to free
-
-Returns:
-
- None
-
---*/
;
+
+/**
+ Internal function to allocate pool of a particular type.
+ Caller must have the memory lock held
+
+ @param PoolType Type of pool to allocate
+ @param Size The amount of pool to allocate
+
+ @return The allocate pool, or NULL
+
+**/
VOID *
CoreAllocatePoolI (
IN EFI_MEMORY_TYPE PoolType,
IN UINTN Size
)
-/*++
-
-Routine Description:
-
- Internal function to allocate pool of a particular type.
-
- Caller must have the memory lock held
-
-
-Arguments:
-
- PoolType - Type of pool to allocate
-
- Size - The amount of pool to allocate
-
-Returns:
-
- The allocate pool, or NULL
-
---*/
;
+
+/**
+ Internal function to free a pool entry.
+ Caller must have the memory lock held
+
+ @param Buffer The allocated pool entry to free
+
+ @retval EFI_INVALID_PARAMETER Buffer not valid
+ @retval EFI_SUCCESS Buffer successfully freed.
+
+**/
EFI_STATUS
CoreFreePoolI (
IN VOID *Buffer
)
-/*++
-
-Routine Description:
-
- Internal function to free a pool entry.
-
- Caller must have the memory lock held
-
-
-Arguments:
-
- Buffer - The allocated pool entry to free
-
-Returns:
-
- EFI_INVALID_PARAMETER - Buffer not valid
-
- EFI_SUCCESS - Buffer successfully freed.
-
---*/
;
+
+/**
+ Enter critical section by gaining lock on gMemoryLock.
+
+**/
VOID
CoreAcquireMemoryLock (
VOID
)
-/*++
-
-Routine Description:
-
- Enter critical section by gaining lock on gMemoryLock
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
;
+
+/**
+ Exit critical section by releasing lock on gMemoryLock.
+
+**/
VOID
CoreReleaseMemoryLock (
VOID
)
-/*++
-
-Routine Description:
-
- Exit critical section by releasing lock on gMemoryLock
-
-Arguments:
-
- None
-
-Returns:
-
- None
-
---*/
;