From 3ea80ba2e4ae19eb564173e203d7bab00055ff56 Mon Sep 17 00:00:00 2001 From: darylm503 Date: Thu, 3 Jun 2010 02:15:55 +0000 Subject: [PATCH] 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 --- .../Bus/Pci/IdeControllerDxe/IdeController.c | 104 +++++++++--------- .../Bus/Pci/IdeControllerDxe/IdeController.h | 91 +++++++-------- 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.
- 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.
- 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. -- 2.39.2