Fixed comments to follow coding standard.

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

1 files changed, 240 insertions, 202 deletions

diff --git a/MdePkg/Library/UefiRuntimeLib/RuntimeService.c b/MdePkg/Library/UefiRuntimeLib/RuntimeService.c
index b873495b3b..48db6bdcc8 100644
--- a/MdePkg/Library/UefiRuntimeLib/RuntimeService.c
+++ b/MdePkg/Library/UefiRuntimeLib/RuntimeService.c
@@ -1,20 +1,37 @@
-/*++

+/** @file

+  UEFI Runtime Library implementation for non IPF processor types.

 

-Copyright (c) 2006 - 2007, 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

-http://opensource.org/licenses/bsd-license.php

+  This library hides the global variable for the EFI Runtime Services so the

+  caller does not need to deal with the possiblitly of being called from an

+  OS virtual address space. All pointer values are different for a virtual 

+  mapping than from the normal physical mapping at boot services time.

 

-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

+  Copyright (c) 2006 - 2007, 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        

+  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.             

+

+**/

 

 #include <PiDxe.h>

 

 #include <RuntimeLibInternal.h>

 

+

+/**

+  Resets the entire platform.

+

+  @param  ResetType   The type of reset to perform.

+  @param  ResetStatus The status code for reset.

+  @param  DataSize    The size in bytes of reset data.

+  @param  ResetData   Pointer to data buffer that includes

+                      Null-Terminated Unicode string.

+

+**/

 VOID

 EFIAPI

 EfiResetSystem (

@@ -23,85 +40,64 @@ EfiResetSystem (
   IN UINTN                        DataSize,

   IN CHAR16                       *ResetData

   )

-/*++

-

-Routine Description:

-

-  Resets the entire platform.

+{

+  mRT->ResetSystem (ResetType, ResetStatus, DataSize, ResetData);

+}

 

-Arguments:

 

-  ResetType   - The type of reset to perform.

-  ResetStatus - The status code for the reset.

-  DataSize    - The size, in bytes, of ResetData.

-  ResetData   - A data buffer that includes a Null-terminated Unicode string, optionally

-                followed by additional binary data.

+/**

+  Return current time and date information, and time-keeping

+  capabilities of hardware platform.

 

-Returns:

+  @param  Time         A pointer to storage to receive a snapshot of the current time.

+  @param  Capabilities An optional pointer to a buffer to receive the real time clock device's

+                       capabilities.

 

-  None

+  @retval  EFI_SUCCESS  Success to execute the function.

+  @retval  !EFI_SUCCESS Failed to e3xecute the function.

 

---*/

-{

-  mRT->ResetSystem (ResetType, ResetStatus, DataSize, ResetData);

-}

-

-//

-// The following functions hide the mRT local global from the call to

-// runtime service in the EFI system table.

-//

+**/

 EFI_STATUS

 EFIAPI

 EfiGetTime (

   OUT EFI_TIME                    *Time,

   OUT EFI_TIME_CAPABILITIES       *Capabilities

   )

-/*++

-

-Routine Description:

-

-  Returns the current time and date information, and the time-keeping

-  capabilities of the hardware platform.

+{

+  return mRT->GetTime (Time, Capabilities);

+}

 

-Arguments:

 

-  Time          - A pointer to storage to receive a snapshot of the current time.

-  Capabilities  - An optional pointer to a buffer to receive the real time clock device's

-                  capabilities.

+/**

+  Set current time and date information.

 

-Returns:

+  @param  Time         A pointer to cache of time setting.

 

-  Status code

-

---*/

-{

-  return mRT->GetTime (Time, Capabilities);

-}

+  @retval  EFI_SUCCESS  Success to execute the function.

+  @retval  !EFI_SUCCESS Failed to execute the function.

 

+**/

 EFI_STATUS

 EFIAPI

 EfiSetTime (

   IN EFI_TIME                   *Time

   )

-/*++

-

-Routine Description:

-

-  Sets the current local time and date information.

-

-Arguments:

+{

+  return mRT->SetTime (Time);

+}

 

-  Time  - A pointer to the current time.

 

-Returns:

+/**

+  Return current wakeup alarm clock setting.

 

-  Status code

+  @param  Enabled Indicate if the alarm clock is enabled or disabled.

+  @param  Pending Indicate if the alarm signal is pending and requires acknowledgement.

+  @param  Time    Current alarm clock setting.

 

---*/

-{

-  return mRT->SetTime (Time);

-}

+  @retval  EFI_SUCCESS  Success to execute the function.

+  @retval  !EFI_SUCCESS Failed to e3xecute the function.

 

+**/

 EFI_STATUS

 EFIAPI

 EfiGetWakeupTime (

@@ -109,57 +105,49 @@ EfiGetWakeupTime (
   OUT BOOLEAN                     *Pending,

   OUT EFI_TIME                    *Time

   )

-/*++

-

-Routine Description:

-

-  Returns the current wakeup alarm clock setting.

+{

+  return mRT->GetWakeupTime (Enabled, Pending, Time);

+}

 

-Arguments:

 

-  Enabled - Indicates if the alarm is currently enabled or disabled.

-  Pending - Indicates if the alarm signal is pending and requires acknowledgement.

-  Time    - The current alarm setting.

 

-Returns:

+/**

+  Set current wakeup alarm clock.

 

-  Status code

+  @param  Enable Enable or disable current alarm clock..

+  @param  Time   Point to alarm clock setting.

 

---*/

-{

-  return mRT->GetWakeupTime (Enabled, Pending, Time);

-}

+  @retval  EFI_SUCCESS  Success to execute the function.

+  @retval  !EFI_SUCCESS Failed to e3xecute the function.

 

+**/

 EFI_STATUS

 EFIAPI

 EfiSetWakeupTime (

   IN BOOLEAN                      Enable,

   IN EFI_TIME                     *Time

   )

-/*++

-

-Routine Description:

-

-  Sets the system wakeup alarm clock time.

-

-Arguments:

-

-  Enable  - Enable or disable the wakeup alarm.

-  Time    - If Enable is TRUE, the time to set the wakeup alarm for.

-            If Enable is FALSE, then this parameter is optional, and may be NULL.

-

-Returns:

-

-  Status code

-

---*/

 {

   return mRT->SetWakeupTime (Enable, Time);

 }

 

 

+/**

+  Return value of variable.

+

+  @param  VariableName the name of the vendor's variable, it's a

+                       Null-Terminated Unicode String

+  @param  VendorGuid   Unify identifier for vendor.

+  @param  Attributes   Point to memory location to return the attributes of variable. If the point

+                       is NULL, the parameter would be ignored.

+  @param  DataSize     As input, point to the maxinum size of return Data-Buffer.

+                       As output, point to the actual size of the returned Data-Buffer.

+  @param  Data         Point to return Data-Buffer.

 

+  @retval  EFI_SUCCESS  Success to execute the function.

+  @retval  !EFI_SUCCESS Failed to e3xecute the function.

 

+**/

 EFI_STATUS

 EFIAPI

 EfiGetVariable (

@@ -169,32 +157,28 @@ EfiGetVariable (
   IN OUT UINTN                    *DataSize,

   OUT VOID                        *Data

   )

-/*++

-

-Routine Description:

-

-  Returns the value of a variable.

-

-Arguments:

+{

+  return mRT->GetVariable (VariableName, VendorGuid, Attributes, DataSize, Data);

+}

 

-  VariableName  - A Null-terminated Unicode string that is the name of the

-                  vendor's variable.

-  VendorGuid    - A unique identifier for the vendor.

-  Attributes    - If not NULL, a pointer to the memory location to return the

-                  attributes bitmask for the variable.

-  DataSize      - On input, the size in bytes of the return Data buffer.

-                  On output the size of data returned in Data.

-  Data          - The buffer to return the contents of the variable.

 

-Returns:

+/**

+  Enumerates variable's name.

 

-  Status code

+  @param  VariableNameSize As input, point to maxinum size of variable name.

+                           As output, point to actual size of varaible name.

+  @param  VariableName     As input, supplies the last VariableName that was returned by

+                           GetNextVariableName().

+                           As output, returns the name of variable. The name

+                           string is Null-Terminated Unicode string.

+  @param  VendorGuid       As input, supplies the last VendorGuid that was returned by

+                           GetNextVriableName().

+                           As output, returns the VendorGuid of the current variable.

 

---*/

-{

-  return mRT->GetVariable (VariableName, VendorGuid, Attributes, DataSize, Data);

-}

+  @retval  EFI_SUCCESS  Success to execute the function.

+  @retval  !EFI_SUCCESS Failed to e3xecute the function.

 

+**/

 EFI_STATUS

 EFIAPI

 EfiGetNextVariableName (

@@ -202,32 +186,26 @@ EfiGetNextVariableName (
   IN OUT CHAR16                   *VariableName,

   IN OUT EFI_GUID                 *VendorGuid

   )

-/*++

-

-Routine Description:

-

-  Enumerates the current variable names.

-

-Arguments:

+{

+  return mRT->GetNextVariableName (VariableNameSize, VariableName, VendorGuid);

+}

 

-  VariableNameSize  - The size of the VariableName buffer.

-  VariableName      - On input, supplies the last VariableName that was returned

-                      by GetNextVariableName().

-                      On output, returns the Nullterminated Unicode string of the

-                      current variable.

-  VendorGuid        - On input, supplies the last VendorGuid that was returned by

-                      GetNextVariableName().

-                      On output, returns the VendorGuid of the current variable.

 

-Returns:

+/**

+  Sets value of variable.

 

-  Status code

+  @param  VariableName the name of the vendor's variable, it's a

+                       Null-Terminated Unicode String

+  @param  VendorGuid   Unify identifier for vendor.

+  @param  Attributes   Point to memory location to return the attributes of variable. If the point

+                       is NULL, the parameter would be ignored.

+  @param  DataSize     The size in bytes of Data-Buffer.

+  @param  Data         Point to the content of the variable.

 

---*/

-{

-  return mRT->GetNextVariableName (VariableNameSize, VariableName, VendorGuid);

-}

+  @retval  EFI_SUCCESS  Success to execute the function.

+  @retval  !EFI_SUCCESS Failed to e3xecute the function.

 

+**/

 EFI_STATUS

 EFIAPI

 EfiSetVariable (

@@ -237,104 +215,69 @@ EfiSetVariable (
   IN UINTN                        DataSize,

   IN VOID                         *Data

   )

-/*++

-

-Routine Description:

-

-  Sets the value of a variable.

-

-Arguments:

+{

+  return mRT->SetVariable (VariableName, VendorGuid, Attributes, DataSize, Data);

+}

 

-  VariableName  - A Null-terminated Unicode string that is the name of the

-                  vendor's variable.

-  VendorGuid    - A unique identifier for the vendor.

-  Attributes    - Attributes bitmask to set for the variable.

-  DataSize      - The size in bytes of the Data buffer.

-  Data          - The contents for the variable.

 

-Returns:

+/**

+  Returns the next high 32 bits of platform's monotonic counter.

 

-  Status code

+  @param  HighCount Pointer to returned value.

 

---*/

-{

-  return mRT->SetVariable (VariableName, VendorGuid, Attributes, DataSize, Data);

-}

+  @retval  EFI_SUCCESS  Success to execute the function.

+  @retval  !EFI_SUCCESS Failed to e3xecute the function.

 

+**/

 EFI_STATUS

 EFIAPI

 EfiGetNextHighMonotonicCount (

   OUT UINT32                      *HighCount

   )

-/*++

-

-Routine Description:

-

-  Returns the next high 32 bits of the platform's monotonic counter.

+{

+  return mRT->GetNextHighMonotonicCount (HighCount);

+}

 

-Arguments:

 

-  HighCount - Pointer to returned value.

+/**

+  Determines the new virtual address that is to be used on subsequent memory accesses.

 

-Returns:

+  @param  DebugDisposition   Supplies type information for the pointer being converted.

+  @param  Address            The pointer to a pointer that is to be fixed to be the

+                             value needed for the new virtual address mapping being

+                             applied.

 

-  Status code

-

---*/

-{

-  return mRT->GetNextHighMonotonicCount (HighCount);

-}

+  @retval  EFI_SUCCESS  Success to execute the function.

+  @retval  !EFI_SUCCESS Failed to e3xecute the function.

 

+**/

 EFI_STATUS

 EFIAPI

 EfiConvertPointer (

   IN UINTN                  DebugDisposition,

   IN OUT VOID               **Address

   )

-/*++

-

-Routine Description:

-

-  Determines the new virtual address that is to be used on subsequent memory accesses.

-

-Arguments:

+{

+  return mRT->ConvertPointer (DebugDisposition, Address);

+}

 

-  DebugDisposition  - Supplies type information for the pointer being converted.

-  Address           - A pointer to a pointer that is to be fixed to be the value needed

-                      for the new virtual address mappings being applied.

 

-Returns:

+/**

+  Conver the standard Lib double linked list to a virtual mapping.

 

-  Status code

+  @param  DebugDisposition   Supplies type information for the pointer being converted.

+  @param  ListHead           Head of linked list to convert.

 

---*/

-{

-  return mRT->ConvertPointer (DebugDisposition, Address);

-}

+  @retval  EFI_SUCCESS  Success to execute the function.

+  @retval  !EFI_SUCCESS Failed to e3xecute the function.

 

+**/

 EFI_STATUS

 EFIAPI

 EfiConvertList (

   IN UINTN                DebugDisposition,

   IN OUT LIST_ENTRY       *ListHead

   )

-/*++

-

-Routine Description:

-

-  Conver the standard Lib double linked list to a virtual mapping.

-

-Arguments:

-

-  DebugDisposition - Argument to EfiConvertPointer (EFI 1.0 API)

-

-  ListHead         - Head of linked list to convert

-

-Returns:

-

-  EFI_SUCCESS

-

---*/

 {

   LIST_ENTRY  *Link;

   LIST_ENTRY  *NextLink;

@@ -401,6 +344,38 @@ EfiSetVirtualAddressMap (
 }

 

 

+/**

+  Passes capsules to the firmware with both virtual and physical mapping.

+  Depending on the intended consumption, the firmware may

+  process the capsule immediately. If the payload should persist across a

+  system reset, the reset value returned from EFI_QueryCapsuleCapabilities must

+  be passed into ResetSystem() and will cause the capsule to be processed by

+  the firmware as part of the reset process.

+

+  @param  CapsuleHeaderArray    Virtual pointer to an array of virtual pointers to the capsules

+                                being passed into update capsule. Each capsules is assumed to

+                                stored in contiguous virtual memory. The capsules in the

+                                CapsuleHeaderArray must be the same capsules as the

+                                ScatterGatherList. The CapsuleHeaderArray must

+                                have the capsules in the same order as the ScatterGatherList.

+  @param  CapsuleCount          Number of pointers to EFI_CAPSULE_HEADER in

+                                CaspuleHeaderArray.

+  @param  ScatterGatherList     Physical pointer to a set of

+                                EFI_CAPSULE_BLOCK_DESCRIPTOR that describes the

+                                location in physical memory of a set of capsules. See Related

+                                Definitions for an explanation of how more than one capsule is

+                                passed via this interface. The capsules in the

+                                ScatterGatherList must be in the same order as the

+                                CapsuleHeaderArray. This parameter is only referenced if

+                                the capsules are defined to persist across system reset.

+

+  @retval EFI_SUCCESS           Valid capsule was passed. I Valid capsule was passed. If

+                                CAPSULE_FLAGS_PERSIT_ACROSS_RESET is not set, the

+                                capsule has been successfully processed by the firmware.

+  @retval EFI_INVALID_PARAMETER CapsuleSize is NULL or ResetTye is NULL.

+  @retval EFI_DEVICE_ERROR      The capsule update was started, but failed due to a device error.

+

+**/

 EFI_STATUS

 EFIAPI

 EfiUpdateCapsule (

@@ -416,6 +391,38 @@ EfiUpdateCapsule (
                 );

 }

 

+

+/**

+  The QueryCapsuleCapabilities() function allows a caller to test to see if a capsule or

+  capsules can be updated via UpdateCapsule(). The Flags values in the capsule header and

+  size of the entire capsule is checked.

+  If the caller needs to query for generic capsule capability a fake EFI_CAPSULE_HEADER can be

+  constructed where CapsuleImageSize is equal to HeaderSize that is equal to sizeof

+  (EFI_CAPSULE_HEADER). To determine reset requirements,

+  CAPSULE_FLAGS_PERSIST_ACROSS_RESET should be set in the Flags field of the

+  EFI_CAPSULE_HEADER.

+  The firmware must support any capsule that has the

+  CAPSULE_FLAGS_PERSIST_ACROSS_RESET flag set in EFI_CAPSULE_HEADER. The

+  firmware sets the policy for what capsules are supported that do not have the

+  CAPSULE_FLAGS_PERSIST_ACROSS_RESET flag set.

+

+  @param  CapsuleHeaderArray    Virtual pointer to an array of virtual pointers to the capsules

+                                being passed into update capsule. The capsules are assumed to

+                                stored in contiguous virtual memory.

+  @param  CapsuleCount          Number of pointers to EFI_CAPSULE_HEADER in

+                                CaspuleHeaderArray.

+  @param  MaxiumCapsuleSize     On output the maximum size that UpdateCapsule() can

+                                support as an argument to UpdateCapsule() via

+                                CapsuleHeaderArray and ScatterGatherList.

+                                Undefined on input.

+  @param  ResetType             Returns the type of reset required for the capsule update.

+

+  @retval EFI_SUCCESS           Valid answer returned..

+  @retval EFI_INVALID_PARAMETER MaximumCapsuleSize is NULL.

+  @retval EFI_UNSUPPORTED       The capsule type is not supported on this platform, and

+                                MaximumCapsuleSize and ResetType are undefined.

+

+**/

 EFI_STATUS

 EFIAPI

 EfiQueryCapsuleCapabilities (

@@ -434,6 +441,37 @@ EfiQueryCapsuleCapabilities (
 }

 

 

+/**

+  The QueryVariableInfo() function allows a caller to obtain the information about the

+  maximum size of the storage space available for the EFI variables, the remaining size of the storage

+  space available for the EFI variables and the maximum size of each individual EFI variable,

+  associated with the attributes specified.

+  The returned MaximumVariableStorageSize, RemainingVariableStorageSize,

+  MaximumVariableSize information may change immediately after the call based on other

+  runtime activities including asynchronous error events. Also, these values associated with different

+  attributes are not additive in nature.

+

+  @param  Attributes            Attributes bitmask to specify the type of variables on

+                                which to return information. Refer to the

+                                GetVariable() function description.

+  @param  MaximumVariableStorageSize

+                                On output the maximum size of the storage space

+                                available for the EFI variables associated with the

+                                attributes specified.

+  @param  RemainingVariableStorageSize

+                                Returns the remaining size of the storage space

+                                available for the EFI variables associated with the

+                                attributes specified..

+  @param  MaximumVariableSize   Returns the maximum size of the individual EFI

+                                variables associated with the attributes specified.

+

+  @retval EFI_SUCCESS           Valid answer returned.

+  @retval EFI_INVALID_PARAMETER An invalid combination of attribute bits was supplied.

+  @retval EFI_UNSUPPORTED       EFI_UNSUPPORTED The attribute is not supported on this platform, and the

+                                MaximumVariableStorageSize,

+                                RemainingVariableStorageSize, MaximumVariableSize

+                                are undefined.

+**/

 EFI_STATUS

 EFIAPI

 EfiQueryVariableInfo (