Convert some C-style comments to Doxygen style for coding standard compliance.

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

2 files changed, 98 insertions, 97 deletions

diff --git a/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.c b/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.c
index a12f536b41..5dfb98dc76 100644
--- a/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.c
+++ b/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.c
@@ -1,24 +1,24 @@
 /** @file

-  This driver module produces IDE_CONTROLLER_INIT protocol and will be used by 

+  This driver module produces IDE_CONTROLLER_INIT protocol and will be used by

   IDE Bus driver to support platform dependent timing information. This driver

   is responsible for early initialization of IDE controller.

 

   Copyright (c) 2008 - 2010, Intel Corporation. All rights reserved.<BR>

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

+  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 "IdeController.h"

 

-//

-//  EFI_DRIVER_BINDING_PROTOCOL instance

-//

+///

+///  EFI_DRIVER_BINDING_PROTOCOL instance

+///

 EFI_DRIVER_BINDING_PROTOCOL gIdeControllerDriverBinding = {

   IdeControllerSupported,

   IdeControllerStart,

@@ -46,34 +46,34 @@ EFI_IDE_CONTROLLER_INIT_PROTOCOL  gEfiIdeControllerInit = {
 ///  EFI_ATA_COLLECTIVE_MODE Template

 ///

 EFI_ATA_COLLECTIVE_MODE  gEfiAtaCollectiveModeTemplate = {

-  {           

-    TRUE,                   // PioMode.Valid

-    0                       // PioMode.Mode

+  {

+    TRUE,                   ///< PioMode.Valid

+    0                       ///< PioMode.Mode

   },

   {

-    TRUE,                   // SingleWordDmaMode.Valid

+    TRUE,                   ///< SingleWordDmaMode.Valid

     0

   },

   {

-    FALSE,                  // MultiWordDmaMode.Valid

+    FALSE,                  ///< MultiWordDmaMode.Valid

     0

   },

   {

-    TRUE,                   // UdmaMode.Valid

-    0                       // UdmaMode.Mode

+    TRUE,                   ///< UdmaMode.Valid

+    0                       ///< UdmaMode.Mode

   }

 };

 

 /**

-  Chipset Ide Driver EntryPoint function. It follows the standard EFI driver model. 

+  Chipset Ide Driver EntryPoint function. It follows the standard EFI driver model.

   It's called by StartImage() of DXE Core.

 

-  @param ImageHandle    While the driver image loaded be the ImageLoader(), 

-                        an image handle is assigned to this driver binary, 

+  @param ImageHandle    While the driver image loaded be the ImageLoader(),

+                        an image handle is assigned to this driver binary,

                         all activities of the driver is tied to this ImageHandle

   @param SystemTable    A pointer to the system table, for all BS(Boo Services) and

                         RT(Runtime Services)

-  

+

   @return EFI_STATUS    Status of  EfiLibInstallDriverBindingComponentName2().

 **/

 EFI_STATUS

@@ -105,12 +105,12 @@ InitializeIdeControllerDriver (
   Register Driver Binding protocol for this driver.

 

   @param This                   A pointer points to the Binding Protocol instance

-  @param Controller             The handle of controller to be tested. 

+  @param Controller             The handle of controller to be tested.

   @param RemainingDevicePath    A pointer to the device path. Ignored by device

                                 driver but used by bus driver

-  

-  @retval EFI_SUCCESS           Driver loaded. 

-  @retval !EFI_SUCESS           Driver not loaded. 

+

+  @retval EFI_SUCCESS           Driver loaded.

+  @retval !EFI_SUCESS           Driver not loaded.

 **/

 EFI_STATUS

 EFIAPI

@@ -185,16 +185,16 @@ Done:
 }

 

 /**

-  This routine is called right after the .Supported() called and return 

+  This routine is called right after the .Supported() called and return

   EFI_SUCCESS. Notes: The supported protocols are checked but the Protocols

-  are closed.  

+  are closed.

 

   @param This                   A pointer points to the Binding Protocol instance

   @param Controller             The handle of controller to be tested. Parameter

                                 passed by the caller

   @param RemainingDevicePath    A pointer to the device path. Should be ignored by

                                 device driver

-  

+

   @return EFI_STATUS            Status of InstallMultipleProtocolInterfaces()

 **/

 EFI_STATUS

@@ -232,7 +232,7 @@ IdeControllerStart (
   }

 

   //

-  // Install IDE_CONTROLLER_INIT protocol 

+  // Install IDE_CONTROLLER_INIT protocol

   //

   return gBS->InstallMultipleProtocolInterfaces (

                 &Controller,

@@ -242,15 +242,15 @@ IdeControllerStart (
 }

 

 /**

-  Stop this driver on Controller Handle. 

+  Stop this driver on Controller Handle.

 

   @param This               Protocol instance pointer.

-  @param Controller         Handle of device to stop driver on 

+  @param Controller         Handle of device to stop driver on

   @param NumberOfChildren   Not used

   @param ChildHandleBuffer  Not used

-  

-  @retval EFI_SUCESS        This driver is removed DeviceHandle 

-  @retval !EFI_SUCCESS      This driver was not removed from this device 

+

+  @retval EFI_SUCESS        This driver is removed DeviceHandle

+  @retval !EFI_SUCCESS      This driver was not removed from this device

 **/

 EFI_STATUS

 EFIAPI

@@ -313,16 +313,16 @@ IdeControllerStop (
 // Interface functions of IDE_CONTROLLER_INIT protocol

 //

 /**

-  This function can be used to obtain information about a specified channel. 

-  It's usually used by IDE Bus driver during enumeration process.  

+  This function can be used to obtain information about a specified channel.

+  It's usually used by IDE Bus driver during enumeration process.

 

   @param This           the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

   @param Channel        Channel number (0 based, either 0 or 1)

-  @param Enabled        TRUE if the channel is enabled. If the channel is disabled, 

+  @param Enabled        TRUE if the channel is enabled. If the channel is disabled,

                         then it will no be enumerated.

   @param MaxDevices     The Max number of IDE devices that the bus driver can expect

                         on this channel. For ATA/ATAPI, this number is either 1 or 2.

-  

+

   @retval EFI_SUCCESS           Success to get channel information

   @retval EFI_INVALID_PARAMETER Invalid channel id.

 **/

@@ -349,13 +349,13 @@ IdeInitGetChannelInfo (
 }

 

 /**

-  This function is called by IdeBus driver before executing certain actions. 

-  This allows IDE Controller Init to prepare for each action.  

+  This function is called by IdeBus driver before executing certain actions.

+  This allows IDE Controller Init to prepare for each action.

 

   @param This       the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

   @param Phase      phase indicator defined by IDE_CONTROLLER_INIT protocol

   @param Channel    Channel number (0 based, either 0 or 1)

-  

+

   @return EFI_SUCCESS Success operation.

 **/

 EFI_STATUS

@@ -371,14 +371,14 @@ IdeInitNotifyPhase (
 

 /**

   This function is called by IdeBus driver to submit EFI_IDENTIFY_DATA data structure

-  obtained from IDE deivce. This structure is used to set IDE timing  

+  obtained from IDE deivce. This structure is used to set IDE timing

 

   @param This           The EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

   @param Channel        IDE channel number (0 based, either 0 or 1)

   @param Device         IDE device number

   @param IdentifyData   A pointer to EFI_IDENTIFY_DATA data structure

-  

-  @return EFI_SUCCESS   Success operation. 

+

+  @return EFI_SUCCESS   Success operation.

 **/

 EFI_STATUS

 EFIAPI

@@ -394,14 +394,14 @@ IdeInitSubmitData (
 

 /**

   This function is called by IdeBus driver to disqualify unsupported operation

-  mode on specfic IDE device  

+  mode on specfic IDE device

 

   @param This       the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

   @param Channel    IDE channel number (0 based, either 0 or 1)

   @param Device     IDE device number

   @param BadModes   Operation mode indicator

-  

-  @return EFI_SUCCESS Success operation. 

+

+  @return EFI_SUCCESS Success operation.

 **/

 EFI_STATUS

 EFIAPI

@@ -417,14 +417,14 @@ IdeInitDisqualifyMode (
 

 /**

   This function is called by IdeBus driver to calculate the best operation mode

-  supported by specific IDE device  

+  supported by specific IDE device

 

   @param This               the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

   @param Channel            IDE channel number (0 based, either 0 or 1)

   @param Device             IDE device number

   @param SupportedModes     Modes collection supported by IDE device

-  

-  @retval EFI_OUT_OF_RESOURCES  Fail to allocate pool. 

+

+  @retval EFI_OUT_OF_RESOURCES  Fail to allocate pool.

   @retval EFI_INVALID_PARAMETER Invalid channel id and device id.

 **/

 EFI_STATUS

@@ -450,13 +450,13 @@ IdeInitCalculateMode (
 

 /**

   This function is called by IdeBus driver to set appropriate timing on IDE

-  controller according supported operation mode.  

+  controller according supported operation mode.

 

   @param This       the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

   @param Channel    IDE channel number (0 based, either 0 or 1)

   @param Device     IDE device number

   @param Modes      IDE device modes

-  

+

   @retval EFI_SUCCESS Sucess operation.

 **/

 EFI_STATUS

diff --git a/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.h b/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.h
index 301b781337..581361d24f 100644
--- a/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.h
+++ b/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.h
@@ -2,13 +2,13 @@
   Header file for IDE controller driver.

 

   Copyright (c) 2008 - 2010, Intel Corporation. All rights reserved.<BR>

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

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

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

 

 **/

 

@@ -36,13 +36,14 @@ extern EFI_DRIVER_BINDING_PROTOCOL  gIdeControllerDriverBinding;
 extern EFI_COMPONENT_NAME_PROTOCOL  gIdeControllerComponentName;

 extern EFI_COMPONENT_NAME2_PROTOCOL gIdeControllerComponentName2;

 

-//

-// Supports 2 channel max

-//

+///

+/// Supports 2 channel max

+///

 #define ICH_IDE_MAX_CHANNEL 0x02

-//

-// Supports 2 devices max

-//

+

+///

+/// Supports 2 devices max

+///

 #define ICH_IDE_MAX_DEVICES 0x02

 #define ICH_IDE_ENUMER_ALL  FALSE

 

@@ -53,12 +54,12 @@ extern EFI_COMPONENT_NAME2_PROTOCOL gIdeControllerComponentName2;
   Register Driver Binding protocol for this driver.

 

   @param This                   A pointer points to the Binding Protocol instance

-  @param Controller             The handle of controller to be tested. 

+  @param Controller             The handle of controller to be tested.

   @param RemainingDevicePath    A pointer to the device path. Ignored by device

                                 driver but used by bus driver

-  

-  @retval EFI_SUCCESS           Driver loaded. 

-  @retval !EFI_SUCESS           Driver not loaded. 

+

+  @retval EFI_SUCCESS           Driver loaded.

+  @retval !EFI_SUCESS           Driver not loaded.

 **/

 EFI_STATUS

 EFIAPI

@@ -70,16 +71,16 @@ IdeControllerSupported (
 ;

 

 /**

-  This routine is called right after the .Supported() called and return 

+  This routine is called right after the .Supported() called and return

   EFI_SUCCESS. Notes: The supported protocols are checked but the Protocols

-  are closed.  

+  are closed.

 

   @param This                   A pointer points to the Binding Protocol instance

   @param Controller             The handle of controller to be tested. Parameter

                                 passed by the caller

   @param RemainingDevicePath    A pointer to the device path. Should be ignored by

                                 device driver

-  

+

   @return EFI_STATUS            Status of InstallMultipleProtocolInterfaces()

 **/

 EFI_STATUS

@@ -92,15 +93,15 @@ IdeControllerStart (
 ;

 

 /**

-  Stop this driver on Controller Handle. 

+  Stop this driver on Controller Handle.

 

   @param This               Protocol instance pointer.

-  @param Controller         Handle of device to stop driver on 

+  @param Controller         Handle of device to stop driver on

   @param NumberOfChildren   Not used

   @param ChildHandleBuffer  Not used

-  

-  @retval EFI_SUCESS        This driver is removed DeviceHandle 

-  @retval !EFI_SUCCESS      This driver was not removed from this device 

+

+  @retval EFI_SUCESS        This driver is removed DeviceHandle

+  @retval !EFI_SUCCESS      This driver was not removed from this device

 **/

 EFI_STATUS

 EFIAPI

@@ -116,16 +117,16 @@ IdeControllerStop (
 // IDE controller init functions declaration

 //

 /**

-  This function can be used to obtain information about a specified channel. 

-  It's usually used by IDE Bus driver during enumeration process.  

+  This function can be used to obtain information about a specified channel.

+  It's usually used by IDE Bus driver during enumeration process.

 

   @param This           the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

   @param Channel        Channel number (0 based, either 0 or 1)

-  @param Enabled        TRUE if the channel is enabled. If the channel is disabled, 

+  @param Enabled        TRUE if the channel is enabled. If the channel is disabled,

                         then it will no be enumerated.

   @param MaxDevices     The Max number of IDE devices that the bus driver can expect

                         on this channel. For ATA/ATAPI, this number is either 1 or 2.

-  

+

   @retval EFI_SUCCESS           Success to get channel information

   @retval EFI_INVALID_PARAMETER Invalid channel id.

 **/

@@ -140,13 +141,13 @@ IdeInitGetChannelInfo (
 ;

 

 /**

-  This function is called by IdeBus driver before executing certain actions. 

-  This allows IDE Controller Init to prepare for each action.  

+  This function is called by IdeBus driver before executing certain actions.

+  This allows IDE Controller Init to prepare for each action.

 

   @param This       the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

   @param Phase      phase indicator defined by IDE_CONTROLLER_INIT protocol

   @param Channel    Channel number (0 based, either 0 or 1)

-  

+

   @return EFI_SUCCESS Success operation.

 **/

 EFI_STATUS

@@ -160,14 +161,14 @@ IdeInitNotifyPhase (
 

 /**

   This function is called by IdeBus driver to submit EFI_IDENTIFY_DATA data structure

-  obtained from IDE deivce. This structure is used to set IDE timing  

+  obtained from IDE deivce. This structure is used to set IDE timing

 

   @param This           The EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

   @param Channel        IDE channel number (0 based, either 0 or 1)

   @param Device         IDE device number

   @param IdentifyData   A pointer to EFI_IDENTIFY_DATA data structure

-  

-  @return EFI_SUCCESS   Success operation. 

+

+  @return EFI_SUCCESS   Success operation.

 **/

 EFI_STATUS

 EFIAPI

@@ -181,14 +182,14 @@ IdeInitSubmitData (
 

 /**

   This function is called by IdeBus driver to disqualify unsupported operation

-  mode on specfic IDE device  

+  mode on specfic IDE device

 

   @param This       the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

   @param Channel    IDE channel number (0 based, either 0 or 1)

   @param Device     IDE device number

   @param BadModes   Operation mode indicator

-  

-  @return EFI_SUCCESS Success operation. 

+

+  @return EFI_SUCCESS Success operation.

 **/

 EFI_STATUS

 EFIAPI

@@ -202,14 +203,14 @@ IdeInitDisqualifyMode (
 

 /**

   This function is called by IdeBus driver to calculate the best operation mode

-  supported by specific IDE device  

+  supported by specific IDE device

 

   @param This               the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

   @param Channel            IDE channel number (0 based, either 0 or 1)

   @param Device             IDE device number

   @param SupportedModes     Modes collection supported by IDE device

-  

-  @retval EFI_OUT_OF_RESOURCES  Fail to allocate pool. 

+

+  @retval EFI_OUT_OF_RESOURCES  Fail to allocate pool.

   @retval EFI_INVALID_PARAMETER Invalid channel id and device id.

 **/

 EFI_STATUS

@@ -224,13 +225,13 @@ IdeInitCalculateMode (
 

 /**

   This function is called by IdeBus driver to set appropriate timing on IDE

-  controller according supported operation mode.  

+  controller according supported operation mode.

 

   @param This       the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

   @param Channel    IDE channel number (0 based, either 0 or 1)

   @param Device     IDE device number

   @param Modes      IDE device modes

-  

+

   @retval EFI_SUCCESS Sucess operation.

 **/

 EFI_STATUS

@@ -258,7 +259,7 @@ IdeInitSetTiming (
   @param DriverName     A pointer to the Unicode string to return.  This Unicode string

                         is the name of the driver specified by This in the language

                         specified by Language.

-  

+

   @retval EFI_SUCCESS           The Unicode string for the Driver specified by This

                                 and the language specified by Language was returned

                                 in DriverName.

@@ -278,7 +279,7 @@ IdeControllerComponentNameGetDriverName (
 

 /**

   Retrieves a Unicode string that is the user readable name of the controller

-  that is being managed by an EFI Driver.  

+  that is being managed by an EFI Driver.

 

   @param This                   A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.

   @param ControllerHandle       The handle of a controller that the driver specified by

@@ -301,7 +302,7 @@ IdeControllerComponentNameGetDriverName (
                                 ControllerHandle and ChildHandle in the language

                                 specified by Language from the point of view of the

                                 driver specified by This.

-  

+

   @retval EFI_SUCCESS           The Unicode string for the user readable name in the

                                 language specified by Language for the driver

                                 specified by This was returned in DriverName.