1.Updated EFI_FVB_ATTRIBUTES to EFI_FVB_ATTRIBUTES_2 to follow PI spec.
[people/mcb30/edk2.git] / edk2 / MdePkg / Include / Pi / PiDxeCis.h
index cfcefb9..574ee46 100644 (file)
@@ -115,7 +115,9 @@ typedef struct {
   /// \r
   EFI_PHYSICAL_ADDRESS  BaseAddress;\r
 \r
+  ///\r
   /// Number of bytes in the I/O region.\r
+  ///\r
   UINT64                Length;\r
 \r
   /// \r
@@ -147,12 +149,31 @@ typedef struct {
   Adds reserved memory, system memory, or memory-mapped I/O resources to the\r
   global coherency domain of the processor.\r
 \r
-  @param  GcdMemoryType    Memory type of the memory space.\r
-  @param  BaseAddress      Base address of the memory space.\r
-  @param  Length           Length of the memory space.\r
-  @param  Capabilities     alterable attributes of the memory space.\r
-\r
-  @retval EFI_SUCCESS           Merged this memory space into GCD map.\r
+  @param  GcdMemoryType    The type of memory resource being added.\r
+  @param  BaseAddress      The physical address that is the start address\r
+                           of the memory resource being added.\r
+  @param  Length           The size, in bytes, of the memory resource that\r
+                           is being added.\r
+  @param  Capabilities     The bit mask of attributes that the memory \r
+                           resource region supports.\r
+\r
+  @retval EFI_SUCCESS            The memory resource was added to the global\r
+                                 coherency domain of the processor.\r
+  @retval EFI_INVALID_PARAMETER  GcdMemoryType is invalid.\r
+  @retval EFI_INVALID_PARAMETER  Length is zero.\r
+  @retval EFI_OUT_OF_RESOURCES   There are not enough system resources to add\r
+                                 the memory resource to the global coherency \r
+                                 domain of the processor.\r
+  @retval EFI_UNSUPPORTED        The processor does not support one or more bytes\r
+                                 of the memory resource range specified by \r
+                                 BaseAddress and Length.\r
+  @retval EFI_ACCESS_DENIED      One or more bytes of the memory resource range\r
+                                 specified by BaseAddress and Length conflicts \r
+                                 with a memory resource range that was previously\r
+                                 added to the global coherency domain of the processor.\r
+  @retval EFI_ACCESS_DENIED      One or more bytes of the memory resource range\r
+                                 specified by BaseAddress and Length was allocated\r
+                                 in a prior call to AllocateMemorySpace()..\r
 \r
 **/\r
 typedef\r
@@ -169,17 +190,30 @@ EFI_STATUS
   Allocates nonexistent memory, reserved memory, system memory, or memorymapped\r
   I/O resources from the global coherency domain of the processor.\r
 \r
-  @param  GcdAllocateType  The type of allocate operation\r
-  @param  GcdMemoryType    The desired memory type\r
-  @param  Alignment        Align with 2^Alignment\r
-  @param  Length           Length to allocate\r
-  @param  BaseAddress      Base address to allocate\r
-  @param  Imagehandle      The image handle consume the allocated space.\r
-  @param  DeviceHandle     The device handle consume the allocated space.\r
+  @param  GcdAllocateType  The type of allocation to perform.\r
+  @param  GcdMemoryType    The type of memory resource being allocated.\r
+  @param  Alignment        The log base 2 of the boundary that BaseAddress must\r
+                           be aligned on output. Align with 2^Alignment.\r
+  @param  Length           The size in bytes of the memory resource range that\r
+                           is being allocated.\r
+  @param  BaseAddress      A pointer to a physical address to allocate.\r
+  @param  Imagehandle      The image handle of the agent that is allocating \r
+                           the memory resource.\r
+  @param  DeviceHandle     The device handle for which the memory resource\r
+                           is being allocated.\r
+\r
+  @retval EFI_INVALID_PARAMETER GcdAllocateType is invalid.\r
+  @retval EFI_INVALID_PARAMETER GcdMemoryType is invalid.\r
+  @retval EFI_INVALID_PARAMETER Length is zero.\r
+  @retval EFI_INVALID_PARAMETER BaseAddress is NULL.\r
+  @retval EFI_INVALID_PARAMETER ImageHandle is NULL.\r
+  @retval EFI_NOT_FOUND         The memory resource request could not be satisfied.\r
+                                No descriptor contains the desired space.\r
+  @retval EFI_OUT_OF_RESOURCES  There are not enough system resources to allocate the memory\r
+                                resource from the global coherency domain of the processor.\r
+  @retval EFI_SUCCESS           The memory resource was allocated from the global coherency\r
+                                domain of the processor.\r
 \r
-  @retval EFI_INVALID_PARAMETER Invalid parameter.\r
-  @retval EFI_NOT_FOUND         No descriptor contains the desired space.\r
-  @retval EFI_SUCCESS           Memory space successfully allocated.\r
 \r
 **/\r
 typedef\r
@@ -199,10 +233,18 @@ EFI_STATUS
   Frees nonexistent memory, reserved memory, system memory, or memory-mapped\r
   I/O resources from the global coherency domain of the processor.\r
 \r
-  @param  BaseAddress      Base address of the segment.\r
-  @param  Length           Length of the segment.\r
+  @param  BaseAddress      The physical address that is the start address of the memory resource being freed.\r
+  @param  Length           The size in bytes of the memory resource range that is being freed.\r
 \r
-  @retval EFI_SUCCESS           Space successfully freed.\r
+  @retval EFI_SUCCESS           The memory resource was freed from the global coherency domain of\r
+                                the processor.\r
+  @retval EFI_INVALID_PARAMETER Length is zero.   \r
+  @retval EFI_UNSUPPORTED       The processor does not support one or more bytes of the memory\r
+                                resource range specified by BaseAddress and Length.\r
+  @retval EFI_NOT_FOUND         The memory resource range specified by BaseAddress and\r
+                                Length was not allocated with previous calls to AllocateMemorySpace().\r
+  @retval EFI_OUT_OF_RESOURCES  There are not enough system resources to free the memory resource\r
+                                from the global coherency domain of the processor.\r
 \r
 **/\r
 typedef\r
@@ -217,10 +259,21 @@ EFI_STATUS
   Removes reserved memory, system memory, or memory-mapped I/O resources from\r
   the global coherency domain of the processor.\r
 \r
-  @param  BaseAddress      Base address of the memory space.\r
-  @param  Length           Length of the memory space.\r
-\r
-  @retval EFI_SUCCESS           Successfully remove a segment of memory space.\r
+  @param  BaseAddress      The physical address that is the start address of the memory resource being removed.\r
+  @param  Length           The size in bytes of the memory resource that is being removed.\r
+\r
+  @retval EFI_SUCCESS           The memory resource was removed from the global coherency\r
+                                domain of the processor.\r
+  @retval EFI_INVALID_PARAMETER Length is zero. \r
+  @retval EFI_UNSUPPORTED       The processor does not support one or more bytes of the memory\r
+                                resource range specified by BaseAddress and Length.\r
+  @retval EFI_NOT_FOUND         One or more bytes of the memory resource range specified by\r
+                                BaseAddress and Length was not added with previous calls to\r
+                                AddMemorySpace().\r
+  @retval EFI_ACCESS_DEFINED    One or more bytes of the memory resource range specified by\r
+                                BaseAddress and Length has been allocated with AllocateMemorySpace().\r
+  @retval EFI_OUT_OF_RESOURCES  There are not enough system resources to remove the memory\r
+                                resource from the global coherency domain of the processor.\r
 \r
 **/\r
 typedef\r
@@ -234,11 +287,13 @@ EFI_STATUS
 /**\r
   Retrieves the descriptor for a memory region containing a specified address.\r
 \r
-  @param  BaseAddress      Specified start address\r
-  @param  Descriptor       Specified length\r
+  @param  BaseAddress      The physical address that is the start address of a memory region.\r
+  @param  Descriptor       A pointer to a caller allocated descriptor.\r
 \r
-  @retval EFI_INVALID_PARAMETER Invalid parameter\r
-  @retval EFI_SUCCESS           Successfully get memory space descriptor.\r
+  @retval EFI_SUCCESS           The descriptor for the memory resource region containing\r
+                                BaseAddress was returned in Descriptor.\r
+  @retval EFI_INVALID_PARAMETER Descriptor is NULL.\r
+  @retval EFI_NOT_FOUND         A memory resource range containing BaseAddress was not found.\r
 \r
 **/\r
 typedef\r
@@ -253,11 +308,20 @@ EFI_STATUS
   Modifies the attributes for a memory region in the global coherency domain of the\r
   processor.\r
 \r
-  @param  BaseAddress      Specified start address\r
-  @param  Length           Specified length\r
-  @param  Attributes       Specified attributes\r
-\r
-  @retval EFI_SUCCESS           Successfully set attribute of a segment of memory space.\r
+  @param  BaseAddress      The physical address that is the start address of a memory region.\r
+  @param  Length           The size in bytes of the memory region.\r
+  @param  Attributes       The bit mask of attributes to set for the memory region.\r
+\r
+  @retval EFI_SUCCESS           The attributes were set for the memory region.\r
+  @retval EFI_INVALID_PARAMETER Length is zero. \r
+  @retval EFI_UNSUPPORTED       The processor does not support one or more bytes of the memory\r
+                                resource range specified by BaseAddress and Length.\r
+  @retval EFI_UNSUPPORTED       The bit mask of attributes is not support for the memory resource\r
+                                range specified by BaseAddress and Length.\r
+  @retval EFI_ACCESS_DEFINED    The attributes for the memory resource range specified by\r
+                                BaseAddress and Length cannot be modified.\r
+  @retval EFI_OUT_OF_RESOURCES  There are not enough system resources to modify the attributes of\r
+                                the memory resource range.\r
 \r
 **/\r
 typedef\r
@@ -273,12 +337,15 @@ EFI_STATUS
   Returns a map of the memory resources in the global coherency domain of the\r
   processor.\r
 \r
-  @param  NumberOfDescriptors Number of descriptors.\r
-  @param  MemorySpaceMap      Descriptor array\r
+  @param  NumberOfDescriptors A pointer to number of descriptors returned in the MemorySpaceMap buffer.\r
+  @param  MemorySpaceMap      A pointer to the array of EFI_GCD_MEMORY_SPACE_DESCRIPTORs.\r
 \r
-  @retval EFI_INVALID_PARAMETER Invalid parameter\r
-  @retval EFI_OUT_OF_RESOURCES  No enough buffer to allocate\r
-  @retval EFI_SUCCESS           Successfully get memory space map.\r
+  @retval EFI_SUCCESS           The memory space map was returned in the MemorySpaceMap\r
+                                buffer, and the number of descriptors in MemorySpaceMap was\r
+                                returned in NumberOfDescriptors.\r
+  @retval EFI_INVALID_PARAMETER NumberOfDescriptors is NULL.\r
+  @retval EFI_INVALID_PARAMETER MemorySpaceMap is NULL.\r
+  @retval EFI_OUT_OF_RESOURCES  There are not enough resources to allocate MemorySpaceMap.\r
 \r
 **/\r
 typedef\r
@@ -292,11 +359,25 @@ EFI_STATUS
 /**\r
   Adds reserved I/O or I/O resources to the global coherency domain of the processor.\r
 \r
-  @param  GcdIoType        IO type of the segment.\r
-  @param  BaseAddress      Base address of the segment.\r
-  @param  Length           Length of the segment.\r
-\r
-  @retval EFI_SUCCESS           Merged this segment into GCD map.\r
+  @param  GcdIoType        The type of I/O resource being added.\r
+  @param  BaseAddress      The physical address that is the start address of the I/O resource being added.\r
+  @param  Length           The size in bytes of the I/O resource that is being added.\r
+\r
+  @retval EFI_SUCCESS           The I/O resource was added to the global coherency domain of\r
+                                the processor.\r
+  @retval EFI_INVALID_PARAMETER GcdIoType is invalid.\r
+  @retval EFI_INVALID_PARAMETER Length is zero.\r
+  @retval EFI_OUT_OF_RESOURCES  There are not enough system resources to add the I/O resource to\r
+                                the global coherency domain of the processor.\r
+  @retval EFI_UNSUPPORTED       The processor does not support one or more bytes of the I/O\r
+                                resource range specified by BaseAddress and Length.\r
+  @retval EFI_ACCESS_DENIED     One or more bytes of the I/O resource range specified by\r
+                                BaseAddress and Length conflicts with an I/O resource\r
+                                range that was previously added to the global coherency domain\r
+                                of the processor.\r
+  @retval EFI_ACCESS_DENIED     One or more bytes of the I/O resource range specified by\r
+                                BaseAddress and Length was allocated in a prior call to\r
+                                AllocateIoSpace().\r
 \r
 **/\r
 typedef\r
@@ -312,17 +393,24 @@ EFI_STATUS
   Allocates nonexistent I/O, reserved I/O, or I/O resources from the global coherency\r
   domain of the processor.\r
 \r
-  @param  GcdAllocateType  The type of allocate operation\r
-  @param  GcdIoType        The desired IO type\r
-  @param  Alignment        Align with 2^Alignment\r
-  @param  Length           Length to allocate\r
-  @param  BaseAddress      Base address to allocate\r
-  @param  Imagehandle      The image handle consume the allocated space.\r
-  @param  DeviceHandle     The device handle consume the allocated space.\r
-\r
-  @retval EFI_INVALID_PARAMETER Invalid parameter.\r
-  @retval EFI_NOT_FOUND         No descriptor contains the desired space.\r
-  @retval EFI_SUCCESS           IO space successfully allocated.\r
+  @param  GcdAllocateType  The type of allocation to perform.\r
+  @param  GcdIoType        The type of I/O resource being allocated.\r
+  @param  Alignment        The log base 2 of the boundary that BaseAddress must be aligned on output.\r
+  @param  Length           The size in bytes of the I/O resource range that is being allocated.\r
+  @param  BaseAddress      A pointer to a physical address.\r
+  @param  Imagehandle      The image handle of the agent that is allocating the I/O resource.\r
+  @param  DeviceHandle     The device handle for which the I/O resource is being allocated.\r
+\r
+  @retval EFI_SUCCESS           The I/O resource was allocated from the global coherency domain\r
+                                of the processor.\r
+  @retval EFI_INVALID_PARAMETER GcdAllocateType is invalid.\r
+  @retval EFI_INVALID_PARAMETER GcdIoType is invalid.\r
+  @retval EFI_INVALID_PARAMETER Length is zero.\r
+  @retval EFI_INVALID_PARAMETER BaseAddress is NULL.\r
+  @retval EFI_INVALID_PARAMETER ImageHandle is NULL.\r
+  @retval EFI_OUT_OF_RESOURCES  There are not enough system resources to allocate the I/O\r
+                                resource from the global coherency domain of the processor.\r
+  @retval EFI_NOT_FOUND         The I/O resource request could not be satisfied.\r
 \r
 **/\r
 typedef\r
@@ -342,10 +430,18 @@ EFI_STATUS
   Frees nonexistent I/O, reserved I/O, or I/O resources from the global coherency\r
   domain of the processor.\r
 \r
-  @param  BaseAddress      Base address of the segment.\r
-  @param  Length           Length of the segment.\r
+  @param  BaseAddress      The physical address that is the start address of the I/O resource being freed.\r
+  @param  Length           The size in bytes of the I/O resource range that is being freed.\r
 \r
-  @retval EFI_SUCCESS           Space successfully freed.\r
+  @retval EFI_SUCCESS           The I/O resource was freed from the global coherency domain of the\r
+                                processor.\r
+  @retval EFI_INVALID_PARAMETER Length is zero.\r
+  @retval EFI_UNSUPPORTED       The processor does not support one or more bytes of the I/O resource\r
+                                range specified by BaseAddress and Length.\r
+  @retval EFI_NOT_FOUND         The I/O resource range specified by BaseAddress and Length\r
+                                was not allocated with previous calls to AllocateIoSpace().\r
+  @retval EFI_OUT_OF_RESOURCES  There are not enough system resources to free the I/O resource from\r
+                                the global coherency domain of the processor.\r
 \r
 **/\r
 typedef\r
@@ -360,10 +456,23 @@ EFI_STATUS
   Removes reserved I/O or I/O resources from the global coherency domain of the\r
   processor.\r
 \r
-  @param  BaseAddress      Base address of the segment.\r
-  @param Length Length of the segment.\r
-\r
-  @retval EFI_SUCCESS           Successfully removed a segment of IO space.\r
+  @param  BaseAddress      A pointer to a physical address that is the start address of the I/O resource being\r
+                           removed.\r
+  @param Length            The size in bytes of the I/O resource that is being removed.\r
+\r
+  @retval EFI_SUCCESS           The I/O resource was removed from the global coherency domain\r
+                                of the processor.\r
+  @retval EFI_INVALID_PARAMETER Length is zero.\r
+  @retval EFI_UNSUPPORTED       The processor does not support one or more bytes of the I/O\r
+                                resource range specified by BaseAddress and Length.\r
+  @retval EFI_NOT_FOUND         One or more bytes of the I/O resource range specified by\r
+                                BaseAddress and Length was not added with previous\r
+                                calls to AddIoSpace().\r
+  @retval EFI_ACCESS_DENIED     One or more bytes of the I/O resource range specified by\r
+                                BaseAddress and Length has been allocated with\r
+                                AllocateIoSpace().\r
+  @retval EFI_OUT_OF_RESOURCES  There are not enough system resources to remove the I/O\r
+                                resource from the global coherency domain of the processor.\r
 \r
 **/\r
 typedef\r
@@ -377,11 +486,13 @@ EFI_STATUS
 /**\r
   Retrieves the descriptor for an I/O region containing a specified address.\r
 \r
-  @param  BaseAddress      Specified start address\r
-  @param  Descriptor       Specified length\r
+  @param  BaseAddress      The physical address that is the start address of an I/O region.\r
+  @param  Descriptor       A pointer to a caller allocated descriptor.\r
 \r
+  @retval EFI_SUCCESS           The descriptor for the I/O resource region containing\r
+                                BaseAddress was returned in Descriptor.\r
   @retval EFI_INVALID_PARAMETER Descriptor is NULL.\r
-  @retval EFI_SUCCESS           Successfully get the IO space descriptor.\r
+  @retval EFI_NOT_FOUND         An I/O resource range containing BaseAddress was not found.\r
 \r
 **/\r
 typedef\r
@@ -395,12 +506,16 @@ EFI_STATUS
 /**\r
   Returns a map of the I/O resources in the global coherency domain of the processor.\r
 \r
-  @param  NumberOfDescriptors Number of descriptors.\r
-  @param  MemorySpaceMap      Descriptor array\r
+  @param  NumberOfDescriptors A pointer to number of descriptors returned in the IoSpaceMap buffer.\r
+  @param  MemorySpaceMap      A pointer to the array of EFI_GCD_IO_SPACE_DESCRIPTORs.\r
+\r
+  @retval EFI_SUCCESS           The I/O space map was returned in the IoSpaceMap buffer, and\r
+                                the number of descriptors in IoSpaceMap was returned in\r
+                                NumberOfDescriptors.\r
+  @retval EFI_INVALID_PARAMETER NumberOfDescriptors is NULL.\r
+  @retval EFI_INVALID_PARAMETER IoSpaceMap is NULL.\r
+  @retval EFI_OUT_OF_RESOURCES  There are not enough resources to allocate IoSpaceMap.\r
 \r
-  @retval EFI_INVALID_PARAMETER Invalid parameter\r
-  @retval EFI_OUT_OF_RESOURCES  No enough buffer to allocate\r
-  @retval EFI_SUCCESS           Successfully get IO space map.\r
 \r
 **/\r
 typedef\r
@@ -416,7 +531,17 @@ EFI_STATUS
 /**\r
   Loads and executed DXE drivers from firmware volumes.\r
 \r
-  @return Status of dispatching and execution DXE drivers.\r
+  The Dispatch() function searches for DXE drivers in firmware volumes that have been \r
+  installed since the last time the Dispatch() service was called. It then evaluates \r
+  the dependency expressions of all the DXE drivers and loads and executes those DXE\r
+  drivers whose dependency expression evaluate to TRUE. This service must interact with\r
+  the Security Architectural Protocol to authenticate DXE drivers before they are executed.\r
+  This process is continued until no more DXE drivers can be executed.\r
+\r
+  @retval EFI_SUCCESS         One or more DXE driver were dispatched.\r
+  @retval EFI_NOT_FOUND       No DXE drivers were dispatched.\r
+  @retval EFI_ALREADY_STARTED An attempt is being made to start the DXE Dispatcher recursively.\r
+                              Thus no action was taken.\r
 \r
 **/\r
 typedef\r
@@ -430,16 +555,18 @@ EFI_STATUS
   Clears the Schedule on Request (SOR) flag for a component that is stored in a firmware volume.\r
 \r
   @param  FirmwareVolumeHandle The handle of the firmware volume that contains the file specified by FileName.\r
-  @param  DriverName           A pointer to the name of the file in a firmware volume.\r
+  @param  FileName             A pointer to the name of the file in a firmware volume.\r
 \r
-  @return Status of clearing SOR.\r
+  @retval EFI_SUCCESS         The DXE driver was found and its SOR bit was cleared.\r
+  @retval EFI_NOT_FOUND       The DXE driver does not exist, or the DXE driver exists and its SOR\r
+                              bit is not set.\r
 \r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_SCHEDULE)(\r
   IN EFI_HANDLE  FirmwareVolumeHandle,\r
-  IN EFI_GUID    *DriverName\r
+  IN CONST EFI_GUID    *FileName\r
   )\r
 ;\r
 \r
@@ -451,13 +578,14 @@ EFI_STATUS
 \r
   @return Status of promoting FFS from untrusted to trusted\r
           state.\r
+  @retval EFI_NOT_FOUND       The file was not found in the untrusted state.\r
 \r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_TRUST)(\r
   IN EFI_HANDLE  FirmwareVolumeHandle,\r
-  IN EFI_GUID    *DriverName\r
+  IN CONST EFI_GUID    *FileName\r
   )\r
 ;\r
 \r
@@ -468,13 +596,21 @@ EFI_STATUS
   @param  Size                 The size, in bytes, of the firmware volume.\r
   @param  FirmwareVolumeHandle On output, a pointer to the created handle.\r
 \r
-  @return Status of processing FV.\r
+  @retval EFI_SUCCESS          The EFI_FIRMWARE_VOLUME_PROTOCOL and\r
+                               EFI_DEVICE_PATH_PROTOCOL were installed onto\r
+                               FirmwareVolumeHandle for the firmware volume described\r
+                               by FirmwareVolumeHeader and Size.\r
+  @retval EFI_VOLUME_CORRUPTED The firmware volume described by FirmwareVolumeHeader\r
+                               and Size is corrupted.\r
+  @retval EFI_OUT_OF_RESOURCES There are not enough system resources available to produce the\r
+                               EFI_FIRMWARE_VOLUME_PROTOCOL and EFI_DEVICE_PATH_PROTOCOL \r
+                               for the firmware volume described by FirmwareVolumeHeader and Size.\r
 \r
 **/\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_PROCESS_FIRMWARE_VOLUME)(\r
-  IN VOID                             *FvHeader,\r
+  IN CONST VOID                       *FirmwareVolumeHeader,\r
   IN UINTN                            Size,\r
   OUT EFI_HANDLE                      *FirmwareVolumeHandle\r
   )\r