Update comments for coding style.

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

2 files changed, 163 insertions, 158 deletions

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmBase.h b/IntelFrameworkPkg/Include/Protocol/SmmBase.h
index e21b495eb6..11dd2f29f4 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmBase.h
+++ b/IntelFrameworkPkg/Include/Protocol/SmmBase.h
@@ -18,20 +18,20 @@
   call before boot services are terminated. On the other hand, handlers for services such as chipset

   workarounds for the century rollover in CMOS should provide commensurate services throughout

   preboot and OS runtime.

- 

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

-

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

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

 

   @par Revision Reference:

   This Protocol is defined in Framework of EFI SMM Core Interface Spec

   Version 0.9.

 

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

+

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

@@ -57,14 +57,14 @@ typedef struct _EFI_SMM_BASE_PROTOCOL             EFI_SMM_BASE_PROTOCOL;
 /**

   Entry Point to Callback service

 

-  @param  SmmImageHandle        A handle allocated by the SMM infrastructure code

-                                to uniquely designate a specific DXE SMM driver.

-  @param  CommunicationBuffer   A pointer to a collection of data in memory

-                                that will be conveyed from a non-SMM environment into an SMM environment.

-                                The buffer must be contiguous, physically mapped, and be a physical address.

-  @param  SourceSize            The size of the CommunicationBuffer.

+  @param[in]  SmmImageHandle        A handle allocated by the SMM infrastructure code

+                                    to uniquely designate a specific DXE SMM driver.

+  @param[in]  CommunicationBuffer   A pointer to a collection of data in memory

+                                    that will be conveyed from a non-SMM environment into an SMM environment.

+                                    The buffer must be contiguous, physically mapped, and be a physical address.

+  @param[in]  SourceSize            The size of the CommunicationBuffer.

 

-  @return Status code

+  @return     Status code

 

 **/

 typedef

@@ -82,22 +82,22 @@ EFI_STATUS
   Register a given driver into SMRAM.This is the equivalent of performing

   the LoadImage/StartImage into System Management Mode.

 

-  @param  This                  Protocol instance pointer.

-  @param  FilePath              Location of the image to be installed as the handler.

-  @param  SourceBuffer          Optional source buffer in case of the image file

-                                being in memory.

-  @param  SourceSize            Size of the source image file, if in memory.

-  @param  ImageHandle           The handle that the base driver uses to decode 

-                                the handler. Unique among SMM handlers only, 

-                                not unique across DXE/EFI.

-  @param  LegacyIA32Binary      An optional parameter that details that the associated 

-                                file is a real-mode IA-32 binary.

-

-  @retval EFI_SUCCESS           The operation was successful.

-  @retval EFI_OUT_OF_RESOURCES  There were no additional SMRAM resources to load the handler

-  @retval EFI_UNSUPPORTED       This platform does not support 16-bit handlers.

-  @retval EFI_UNSUPPORTED       In runtime.

-  @retval EFI_INVALID_PARAMETER The handlers was not the correct image type

+  @param[in]   This                  Protocol instance pointer.

+  @param[in]   FilePath              Location of the image to be installed as the handler.

+  @param[in]   SourceBuffer          Optional source buffer in case of the image file

+                                     being in memory.

+  @param[in]   SourceSize            Size of the source image file, if in memory.

+  @param[out]  ImageHandle           The handle that the base driver uses to decode 

+                                     the handler. Unique among SMM handlers only, 

+                                     not unique across DXE/EFI.

+  @param[in]   LegacyIA32Binary      An optional parameter that details that the associated 

+                                     file is a real-mode IA-32 binary.

+

+  @retval      EFI_SUCCESS           The operation was successful.

+  @retval      EFI_OUT_OF_RESOURCES  There were no additional SMRAM resources to load the handler

+  @retval      EFI_UNSUPPORTED       This platform does not support 16-bit handlers.

+  @retval      EFI_UNSUPPORTED       In runtime.

+  @retval      EFI_INVALID_PARAMETER The handlers was not the correct image type

 

 **/

 typedef

@@ -115,12 +115,12 @@ EFI_STATUS
   Removes a handler from execution within SMRAM.  This is the equivalent of performing

   the UnloadImage in System Management Mode.

 

-  @param  This                  Protocol instance pointer.

-  @param  ImageHandle           The handler to be removed.

+  @param[in]  This                  Protocol instance pointer.

+  @param[in]  ImageHandle           The handler to be removed.

 

-  @retval EFI_SUCCESS           The operation was successful

-  @retval EFI_INVALID_PARAMETER The handler did not exist

-  @retval EFI_UNSUPPORTED       In runtime.

+  @retval     EFI_SUCCESS           The operation was successful

+  @retval     EFI_INVALID_PARAMETER The handler did not exist

+  @retval     EFI_UNSUPPORTED       In runtime.

 

 **/

 typedef

@@ -136,13 +136,13 @@ EFI_STATUS
   EFI service.  The BASE protocol driver is responsible for doing

   any of the copies such that the data lives in boot-service-accessible RAM.

 

-  @param  This                  Protocol instance pointer.

-  @param  ImageHandle           The handle of the registered driver.

-  @param  CommunicationBuffer   Pointer to the buffer to convey into SMRAM.

-  @param  SourceSize            The size of the data buffer being passed in.

+  @param[in]      This                  Protocol instance pointer.

+  @param[in]      ImageHandle           The handle of the registered driver.

+  @param[in,out]  CommunicationBuffer   Pointer to the buffer to convey into SMRAM.

+  @param[in,out]  SourceSize            The size of the data buffer being passed in.

 

-  @retval EFI_SUCCESS           The message was successfully posted

-  @retval EFI_INVALID_PARAMETER The buffer was NULL

+  @retval         EFI_SUCCESS           The message was successfully posted

+  @retval         EFI_INVALID_PARAMETER The buffer was NULL

 

 **/

 typedef

@@ -158,20 +158,20 @@ EFI_STATUS
   Register a callback to execute within SMM.

   This allows receipt of messages created with EFI_SMM_BASE_PROTOCOL.Communicate().

 

-  @param  This                  Protocol instance pointer.

-  @param  SmmImageHandle        Handle of the callback service.

-  @param  CallbackAddress       Address of the callback service.

-  @param  MakeLast              If present, will stipulate that the handler is posted to 

-                                be executed last in the dispatch table.

-  @param  FloatingPointSave     This is an optional parameter which informs the

-                                EFI_SMM_ACCESS_PROTOCOL Driver core if it needs to save

-                                the floating point register state. If any of the handlers

-                                require this, then the state will be saved for all of the handlers.

-

-  @retval EFI_SUCCESS           The operation was successful

-  @retval EFI_OUT_OF_RESOURCES  Not enough space in the dispatch queue

-  @retval EFI_UNSUPPORTED       In runtime.

-  @retval EFI_UNSUPPORTED       The caller is not in SMM.

+  @param[in]  This                  Protocol instance pointer.

+  @param[in]  SmmImageHandle        Handle of the callback service.

+  @param[in]  CallbackAddress       Address of the callback service.

+  @param[in]  MakeLast              If present, will stipulate that the handler is posted to 

+                                    be executed last in the dispatch table.

+  @param[in]  FloatingPointSave     This is an optional parameter which informs the

+                                    EFI_SMM_ACCESS_PROTOCOL Driver core if it needs to save

+                                    the floating point register state. If any of the handlers

+                                    require this, then the state will be saved for all of the handlers.

+

+  @retval     EFI_SUCCESS           The operation was successful

+  @retval     EFI_OUT_OF_RESOURCES  Not enough space in the dispatch queue

+  @retval     EFI_UNSUPPORTED       In runtime.

+  @retval     EFI_UNSUPPORTED       The caller is not in SMM.

 

 **/

 typedef

@@ -190,20 +190,20 @@ EFI_STATUS
   by Buffer.  This function allocates pages from EFI SMRAM Memory as needed to grow the

   requested pool type.  All allocations are eight-byte aligned.

 

-  @param  This                  Protocol instance pointer.

-  @param  PoolType              The type of pool to allocate.

-                                The only supported type is EfiRuntimeServicesData;

-                                the interface will internally map this runtime request to 

-                                SMRAM for IA-32 and leave as this type for the Itanium 

-                                processor family. Other types can be ignored.

-  @param  Size                  The number of bytes to allocate from the pool.

-  @param  Buffer                A pointer to a pointer to the allocated buffer if the call

-                                succeeds; undefined otherwise.

-

-  @retval EFI_SUCCESS           The requested number of bytes was allocated.

-  @retval EFI_OUT_OF_RESOURCES  The pool requested could not be allocated.

-  @retval EFI_INVALID_PARAMETER PoolType was invalid.

-  @retval EFI_UNSUPPORTED       In runtime.

+  @param[in]   This                  Protocol instance pointer.

+  @param[in]   PoolType              The type of pool to allocate.

+                                     The only supported type is EfiRuntimeServicesData;

+                                     the interface will internally map this runtime request to 

+                                     SMRAM for IA-32 and leave as this type for the Itanium 

+                                     processor family. Other types can be ignored.

+  @param[in]   Size                  The number of bytes to allocate from the pool.

+  @param[out]  Buffer                A pointer to a pointer to the allocated buffer if the call

+                                     succeeds; undefined otherwise.

+

+  @retval      EFI_SUCCESS           The requested number of bytes was allocated.

+  @retval      EFI_OUT_OF_RESOURCES  The pool requested could not be allocated.

+  @retval      EFI_INVALID_PARAMETER PoolType was invalid.

+  @retval      EFI_UNSUPPORTED       In runtime.

 

 **/

 typedef

@@ -220,12 +220,12 @@ EFI_STATUS
   On return, the memory's type is EFI SMRAM Memory.  The Buffer that is freed must

   have been allocated by SmmAllocatePool().

 

-  @param  This                  Protocol instance pointer.

-  @param  Buffer                Pointer to the buffer allocation.

+  @param[in]  This                  Protocol instance pointer.

+  @param[in]  Buffer                Pointer to the buffer allocation.

 

-  @retval EFI_SUCCESS           The memory was returned to the system.

-  @retval EFI_INVALID_PARAMETER Buffer was invalid.

-  @retval EFI_UNSUPPORTED       In runtime.

+  @retval     EFI_SUCCESS           The memory was returned to the system.

+  @retval     EFI_INVALID_PARAMETER Buffer was invalid.

+  @retval     EFI_UNSUPPORTED       In runtime.

 

 **/

 typedef

@@ -238,10 +238,13 @@ EFI_STATUS
 /**

   This routine tells caller if execution context is SMM or not.

 

-  @param  This                  Protocol instance pointer.

-  @param  InSmm                 Whether the caller is inside SMM for IA-32 or servicing a PMI for the Itanium processor family.

+  @param[in]   This                   Protocol instance pointer.

+  @param[out]  InSmm                  Whether the caller is inside SMM for IA-32

+                                      or servicing a PMI for the Itanium processor

+	     			 family.

 

-  @retval EFI_SUCCESS           The operation was successful

+  @retval      EFI_SUCCESS            The operation was successful

+  @retval      EFI_INVALID_PARAMETER  InSmm was NULL.

 

 **/

 typedef

@@ -257,12 +260,12 @@ EFI_STATUS
   location of the SMST in its entry point and then cache it in some driver

   global variable so that the SMST can be invoked in subsequent callbacks.

 

-  @param  This                  Protocol instance pointer.

-  @param  Smst                  Pointer to the SMST.

+  @param[in]  This                  Protocol instance pointer.

+  @param[in]  Smst                  Pointer to the SMST.

 

-  @retval EFI_SUCCESS           The operation was successful

-  @retval EFI_INVALID_PARAMETER Smst was invalid.

-  @retval EFI_UNSUPPORTED       Not in SMM.

+  @retval     EFI_SUCCESS           The operation was successful

+  @retval     EFI_INVALID_PARAMETER Smst was invalid.

+  @retval     EFI_UNSUPPORTED       Not in SMM.

 

 **/

 typedef

@@ -277,39 +280,46 @@ EFI_STATUS
   This protocol is used to install SMM handlers for support of subsequent SMI/PMI

   activations. This protocol is available on both IA-32 and Itanium-based systems.

 

-  @param Register

-  Registers a handler to run in System Management RAM (SMRAM).

-

-  @param UnRegister

-  Removes a handler from execution in SMRAM.

-

-  @param Communicate

-  Sends/receives a message for a registered handler.

-

-  @param RegisterCallback

-  Registers a callback from the constructor.

-

-  @param InSmm

-  Detects whether the caller is inside or outside of SMM. SName

-

-  @param SmmAllocatePool

-  Allocates SMRAM.

-

-  @param SmmFreePool

-  Deallocates SMRAM.

-

-  @param GetSmstLocation

-  Retrieves the location of the System Management System Table (SMST).

-

 **/

 struct _EFI_SMM_BASE_PROTOCOL {

+  ///

+  ///  Registers a handler to run in System Management RAM (SMRAM).

+  ///

   EFI_SMM_REGISTER_HANDLER    Register;

+

+  ///

+  ///  Removes a handler from execution in SMRAM.

+  ///

   EFI_SMM_UNREGISTER_HANDLER  UnRegister;

+

+  ///

+  ///  Sends/receives a message for a registered handler.

+  ///

   EFI_SMM_COMMUNICATE         Communicate;

+

+  ///

+  ///  Registers a callback from the constructor.

+  ///

   EFI_SMM_CALLBACK_SERVICE    RegisterCallback;

+

+  ///

+  ///  Detects whether the caller is inside or outside of SMM. SName

+  ///

   EFI_SMM_INSIDE_OUT          InSmm;

+

+  ///

+  ///  Allocates SMRAM.

+  ///

   EFI_SMM_ALLOCATE_POOL       SmmAllocatePool;

+

+  ///

+  ///  Deallocates SMRAM.

+  ///

   EFI_SMM_FREE_POOL           SmmFreePool;

+

+  ///

+  ///  Retrieves the location of the System Management System Table (SMST).

+  ///

   EFI_SMM_GET_SMST_LOCATION   GetSmstLocation;

 };

 

diff --git a/IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h b/IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h
index 95a6d51bf5..c17bb4442f 100644
--- a/IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h
+++ b/IntelFrameworkPkg/Include/Protocol/SmmPowerButtonDispatch.h
@@ -1,21 +1,19 @@
 /** @file

   Provides the parent dispatch service for the power button SMI source generator.

 

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

-

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

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

-

-  Module Name:  SmmPowerButtonDispatch.h

-

   @par Revision Reference:

   This Protocol is defined in Framework of EFI SMM Core Interface Spec

   Version 0.9.

 

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

+

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

@@ -56,13 +54,11 @@ typedef struct {
 /**

   Dispatch function for a Power Button SMI handler.

 

-  @param  DispatchHandle        Handle of this dispatch function.

-  @param  DispatchContext       Pointer to the dispatch function's context.

-                                The DispatchContext fields are filled in

-                                by the dispatching driver prior to

-                                invoking this dispatch function.

-

-  @return None

+  @param[in]  DispatchHandle        Handle of this dispatch function.

+  @param[in]  DispatchContext       Pointer to the dispatch function's context.

+                                    The DispatchContext fields are filled in

+                                    by the dispatching driver prior to

+                                    invoking this dispatch function.

 

 **/

 typedef

@@ -75,22 +71,22 @@ VOID
 /**

   Provides the parent dispatch service for a given SMI source generator

 

-  @param  This                  Pointer to the EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL instance.

-  @param  DispatchFunction      Function to install.

-  @param  DispatchContext       Pointer to the dispatch function's context.

-                                The caller fills this context in before calling

-                                the register function to indicate to the register

-                                function the Power Button SMI phase for which the dispatch

-                                function should be invoked.

-  @param  DispatchHandle        Handle generated by the dispatcher to track the function instance.

-

-  @retval EFI_SUCCESS           The dispatch function has been successfully

-                                registered and the SMI source has been enabled.

-  @retval EFI_DEVICE_ERROR      The driver was unable to enable the SMI source.

-  @retval EFI_OUT_OF_RESOURCES  Not enough memory (system or SMM) to manage this

-                                child.

-  @retval EFI_INVALID_PARAMETER DispatchContext is invalid. The Power Button SMI

-                                phase is not within valid range.

+  @param[in]   This                  Pointer to the EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL instance.

+  @param[in]   DispatchFunction      Function to install.

+  @param[in]   DispatchContext       Pointer to the dispatch function's context.

+                                     The caller fills this context in before calling

+                                     the register function to indicate to the register

+                                     function the Power Button SMI phase for which the dispatch

+                                     function should be invoked.

+  @param[out]  DispatchHandle        Handle generated by the dispatcher to track the function instance.

+

+  @retval      EFI_SUCCESS           The dispatch function has been successfully

+                                     registered and the SMI source has been enabled.

+  @retval      EFI_DEVICE_ERROR      The driver was unable to enable the SMI source.

+  @retval      EFI_OUT_OF_RESOURCES  Not enough memory (system or SMM) to manage this

+                                     child.

+  @retval      EFI_INVALID_PARAMETER DispatchContext is invalid. The Power Button SMI

+                                     phase is not within valid range.

 

 **/

 typedef

@@ -105,14 +101,15 @@ EFI_STATUS
 /**

   Unregisters a power-button service.

 

-  @param  This                  Pointer to the EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL instance.

-  @param  DispatchHandle        Handle of the service to remove.

+  @param[in]  This                  Pointer to the EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL instance.

+  @param[in]  DispatchHandle        Handle of the service to remove.

 

-  @retval EFI_SUCCESS           The dispatch function has been successfully

-                                unregistered and the SMI source has been disabled

-                                if there are no other registered child dispatch

-                                functions for this SMI source.

-  @retval EFI_INVALID_PARAMETER Handle is invalid.

+  @retval     EFI_SUCCESS           The dispatch function has been successfully

+                                    unregistered and the SMI source has been

+				    disabled if there are no other registered

+				    child dispatch functions for this SMI

+				    source.

+  @retval     EFI_INVALID_PARAMETER Handle is invalid.

 

 **/

 typedef

@@ -122,22 +119,20 @@ EFI_STATUS
   IN EFI_HANDLE                                        DispatchHandle

   );

 

-//

-// Interface structure for the SMM Power Button SMI Dispatch Protocol

-//

 /**

   @par Protocol Description:

   Provides the parent dispatch service for the SMM power button SMI source generator.

 

-  @param Register

-  Installs a child service to be dispatched by this protocol.

-

-  @param UnRegister

-  Removes a child service dispatched by this protocol.

-

 **/

 struct _EFI_SMM_POWER_BUTTON_DISPATCH_PROTOCOL {

+  ///

+  ///  Installs a child service to be dispatched by this protocol.

+  ///

   EFI_SMM_POWER_BUTTON_REGISTER   Register;

+

+  ///

+  ///  Removes a child service dispatched by this protocol.

+  ///

   EFI_SMM_POWER_BUTTON_UNREGISTER UnRegister;

 };