diff options
| author | klu2 <klu2@6f19259b-4bc3-4df7-8a09-765794883524> | 2010-05-20 03:29:26 +0000 |
|---|---|---|
| committer | klu2 <klu2@6f19259b-4bc3-4df7-8a09-765794883524> | 2010-05-20 03:29:26 +0000 |
| commit | 20c1e33fe47a2179c1a016cac6b7d03bc4f5e125 (patch) | |
| tree | 6563340ff5778eaa3dae136ef6429167691c9e17 /PcAtChipsetPkg/Bus | |
| parent | 4e4a5f359d04a9551b2c74a3aeb7b10677988bc0 (diff) | |
| download | edk2-20c1e33fe47a2179c1a016cac6b7d03bc4f5e125.tar.gz edk2-20c1e33fe47a2179c1a016cac6b7d03bc4f5e125.tar.bz2 edk2-20c1e33fe47a2179c1a016cac6b7d03bc4f5e125.zip | |
Refine function comment to follow doxygen format.
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@10520 6f19259b-4bc3-4df7-8a09-765794883524
Diffstat (limited to 'PcAtChipsetPkg/Bus')
3 files changed, 348 insertions, 504 deletions
diff --git a/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/ComponentName.c b/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/ComponentName.c index 42f4bc97f7..5e56a62f47 100644 --- a/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/ComponentName.c +++ b/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/ComponentName.c @@ -47,7 +47,7 @@ GLOBAL_REMOVE_IF_UNREFERENCED EFI_UNICODE_STRING_TABLE mIdeControllerDriverNameT }
};
-//
+///
/// Controller Name Strings
///
GLOBAL_REMOVE_IF_UNREFERENCED EFI_UNICODE_STRING_TABLE mIdeControllerControllerNameTable[] = {
@@ -61,6 +61,27 @@ GLOBAL_REMOVE_IF_UNREFERENCED EFI_UNICODE_STRING_TABLE mIdeControllerControllerN }
};
+/**
+ Retrieves a Unicode string that is the user readable name of the EFI Driver.
+
+ @param This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
+ @param Language A pointer to a three character ISO 639-2 language identifier.
+ This is the language of the driver name that that the caller
+ is requesting, and it must match one of the languages specified
+ in SupportedLanguages. The number of languages supported by a
+ driver is up to the driver writer.
+ @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.
+ @retval EFI_INVALID_PARAMETER Language is NULL.
+ @retval EFI_INVALID_PARAMETER DriverName is NULL.
+ @retval EFI_UNSUPPORTED The driver specified by This does not support the
+ language specified by Language.
+**/
EFI_STATUS
EFIAPI
IdeControllerComponentNameGetDriverName (
@@ -68,32 +89,6 @@ IdeControllerComponentNameGetDriverName ( IN CHAR8 *Language,
OUT CHAR16 **DriverName
)
-/*++
-
- Routine Description:
- Retrieves a Unicode string that is the user readable name of the EFI Driver.
-
- Arguments:
- This - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
- Language - A pointer to a three character ISO 639-2 language identifier.
- This is the language of the driver name that that the caller
- is requesting, and it must match one of the languages specified
- in SupportedLanguages. The number of languages supported by a
- driver is up to the driver writer.
- 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.
-
- Returns:
- EFI_SUCCESS - The Unicode string for the Driver specified by This
- and the language specified by Language was returned
- in DriverName.
- EFI_INVALID_PARAMETER - Language is NULL.
- EFI_INVALID_PARAMETER - DriverName is NULL.
- EFI_UNSUPPORTED - The driver specified by This does not support the
- language specified by Language.
-
---*/
{
return LookupUnicodeString2 (
Language,
@@ -104,6 +99,46 @@ IdeControllerComponentNameGetDriverName ( );
}
+/**
+ Retrieves a Unicode string that is the user readable name of the controller
+ 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
+ This is managing. This handle specifies the controller
+ whose name is to be returned.
+ @param OPTIONAL The handle of the child controller to retrieve the name
+ of. This is an optional parameter that may be NULL. It
+ will be NULL for device drivers. It will also be NULL
+ for a bus drivers that wish to retrieve the name of the
+ bus controller. It will not be NULL for a bus driver
+ that wishes to retrieve the name of a child controller.
+ @param Language A pointer to a three character ISO 639-2 language
+ identifier. This is the language of the controller name
+ that that the caller is requesting, and it must match one
+ of the languages specified in SupportedLanguages. The
+ number of languages supported by a driver is up to the
+ driver writer.
+ @param ControllerName A pointer to the Unicode string to return. This Unicode
+ string is the name of the controller specified by
+ 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.
+ @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
+ @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
+ EFI_HANDLE.
+ @retval EFI_INVALID_PARAMETER Language is NULL.
+ @retval EFI_INVALID_PARAMETER ControllerName is NULL.
+ @retval EFI_UNSUPPORTED The driver specified by This is not currently
+ managing the controller specified by
+ ControllerHandle and ChildHandle.
+ @retval EFI_UNSUPPORTED The driver specified by This does not support the
+ language specified by Language.
+**/
EFI_STATUS
EFIAPI
IdeControllerComponentNameGetControllerName (
@@ -113,51 +148,6 @@ IdeControllerComponentNameGetControllerName ( IN CHAR8 *Language,
OUT CHAR16 **ControllerName
)
-/*++
-
- Routine Description:
- Retrieves a Unicode string that is the user readable name of the controller
- that is being managed by an EFI Driver.
-
- Arguments:
- This - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
- ControllerHandle - The handle of a controller that the driver specified by
- This is managing. This handle specifies the controller
- whose name is to be returned.
- ChildHandle - The handle of the child controller to retrieve the name
- of. This is an optional parameter that may be NULL. It
- will be NULL for device drivers. It will also be NULL
- for a bus drivers that wish to retrieve the name of the
- bus controller. It will not be NULL for a bus driver
- that wishes to retrieve the name of a child controller.
- Language - A pointer to a three character ISO 639-2 language
- identifier. This is the language of the controller name
- that that the caller is requesting, and it must match one
- of the languages specified in SupportedLanguages. The
- number of languages supported by a driver is up to the
- driver writer.
- ControllerName - A pointer to the Unicode string to return. This Unicode
- string is the name of the controller specified by
- ControllerHandle and ChildHandle in the language
- specified by Language from the point of view of the
- driver specified by This.
-
- Returns:
- 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.
- EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.
- EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid
- EFI_HANDLE.
- EFI_INVALID_PARAMETER - Language is NULL.
- EFI_INVALID_PARAMETER - ControllerName is NULL.
- EFI_UNSUPPORTED - The driver specified by This is not currently
- managing the controller specified by
- ControllerHandle and ChildHandle.
- EFI_UNSUPPORTED - The driver specified by This does not support the
- language specified by Language.
-
---*/
{
EFI_STATUS Status;
diff --git a/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.c b/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.c index 6194eaa612..a12f536b41 100644 --- a/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.c +++ b/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.c @@ -3,7 +3,7 @@ IDE Bus driver to support platform dependent timing information. This driver
is responsible for early initialization of IDE controller.
- Copyright (c) 2008 - 2009, Intel Corporation. All rights reserved.<BR>
+ 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
@@ -28,9 +28,9 @@ EFI_DRIVER_BINDING_PROTOCOL gIdeControllerDriverBinding = { NULL
};
-//
-// EFI_IDE_CONTROLLER_PROVATE_DATA Template
-//
+///
+/// EFI_IDE_CONTROLLER_PROVATE_DATA Template
+///
EFI_IDE_CONTROLLER_INIT_PROTOCOL gEfiIdeControllerInit = {
IdeInitGetChannelInfo,
IdeInitNotifyPhase,
@@ -42,9 +42,9 @@ EFI_IDE_CONTROLLER_INIT_PROTOCOL gEfiIdeControllerInit = { ICH_IDE_MAX_CHANNEL
};
-//
-// EFI_ATA_COLLECTIVE_MODE Template
-//
+///
+/// EFI_ATA_COLLECTIVE_MODE Template
+///
EFI_ATA_COLLECTIVE_MODE gEfiAtaCollectiveModeTemplate = {
{
TRUE, // PioMode.Valid
@@ -64,31 +64,24 @@ EFI_ATA_COLLECTIVE_MODE gEfiAtaCollectiveModeTemplate = { }
};
+/**
+ 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,
+ 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
EFIAPI
InitializeIdeControllerDriver (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
-/*++
- Routine Description:
-
- Chipset Ide Driver EntryPoint function. It follows the standard EFI driver
- model. It's called by StartImage() of DXE Core
-
- Argments:
-
- ImageHnadle -- 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
- *SystemTable -- A pointer to the system table, for all BS(Boo Services) and
- RT(Runtime Services)
-
- Retruns:
-
- Always call EfiLibInstallDriverBindingProtocol( ) and retrun the result
-
---*/
{
EFI_STATUS Status;
@@ -108,6 +101,17 @@ InitializeIdeControllerDriver ( return Status;
}
+/**
+ 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 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.
+**/
EFI_STATUS
EFIAPI
IdeControllerSupported (
@@ -115,24 +119,6 @@ IdeControllerSupported ( IN EFI_HANDLE Controller,
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
)
-/*++
-
- Routine Description:
-
- Register Driver Binding protocol for this driver.
-
- Arguments:
-
- This -- a pointer points to the Binding Protocol instance
- Controller -- The handle of controller to be tested.
- *RemainingDevicePath -- A pointer to the device path. Ignored by device
- driver but used by bus driver
-
- Returns:
-
- EFI_SUCCESS -- Driver loaded.
- other -- Driver not loaded.
---*/
{
EFI_STATUS Status;
EFI_PCI_IO_PROTOCOL *PciIo;
@@ -198,6 +184,19 @@ Done: return Status;
}
+/**
+ This routine is called right after the .Supported() called and return
+ EFI_SUCCESS. Notes: The supported protocols are checked but the Protocols
+ 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
EFIAPI
IdeControllerStart (
@@ -205,22 +204,6 @@ IdeControllerStart ( IN EFI_HANDLE Controller,
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
)
-/*++
-
- Routine Description:
-
- This routine is called right after the .Supported() called and return
- EFI_SUCCESS. Notes: The supported protocols are checked but the Protocols
- are closed.
-
- Arguments:
-
- This -- a pointer points to the Binding Protocol instance
- Controller -- The handle of controller to be tested. Parameter
- passed by the caller
- *RemainingDevicePath -- A pointer to the device path. Should be ignored by
- device driver
---*/
{
EFI_STATUS Status;
EFI_PCI_IO_PROTOCOL *PciIo;
@@ -258,6 +241,17 @@ IdeControllerStart ( );
}
+/**
+ Stop this driver on Controller Handle.
+
+ @param This Protocol instance pointer.
+ @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
+**/
EFI_STATUS
EFIAPI
IdeControllerStop (
@@ -266,22 +260,6 @@ IdeControllerStop ( IN UINTN NumberOfChildren,
IN EFI_HANDLE *ChildHandleBuffer
)
-/*++
-
- Routine Description:
- Stop this driver on Controller Handle.
-
- Arguments:
- This - Protocol instance pointer.
- Controller - Handle of device to stop driver on
- NumberOfChildren - Not used
- ChildHandleBuffer - Not used
-
- Returns:
- EFI_SUCCESS - This driver is removed DeviceHandle
- other - This driver was not removed from this device
-
---*/
{
EFI_STATUS Status;
EFI_IDE_CONTROLLER_INIT_PROTOCOL *IdeControllerInit;
@@ -334,6 +312,20 @@ 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.
+
+ @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,
+ 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.
+**/
EFI_STATUS
EFIAPI
IdeInitGetChannelInfo (
@@ -342,25 +334,6 @@ IdeInitGetChannelInfo ( OUT BOOLEAN *Enabled,
OUT UINT8 *MaxDevices
)
-/*++
-Routine Description:
-
- This function can be used to obtain information about a specified channel.
- It's usually used by IDE Bus driver during enumeration process.
-
-Arguments:
-
- This -- the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
- Channel -- Channel number (0 based, either 0 or 1)
- Enabled -- TRUE if the channel is enabled. If the channel is disabled,
- then it will no be enumerated.
- 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.
-
-Returns:
- EFI_STATUS
-
---*/
{
//
// Channel number (0 based, either 0 or 1)
@@ -375,7 +348,16 @@ Returns: return EFI_INVALID_PARAMETER;
}
+/**
+ 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
EFIAPI
IdeInitNotifyPhase (
@@ -383,26 +365,21 @@ IdeInitNotifyPhase ( IN EFI_IDE_CONTROLLER_ENUM_PHASE Phase,
IN UINT8 Channel
)
-/*++
-
-Routine Description:
-
- This function is called by IdeBus driver before executing certain actions.
- This allows IDE Controller Init to prepare for each action.
-
-Arguments:
-
- This -- the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
- Phase -- phase indicator defined by IDE_CONTROLLER_INIT protocol
- Channel -- Channel number (0 based, either 0 or 1)
-
-Returns:
-
---*/
{
return EFI_SUCCESS;
}
+/**
+ 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
+
+ @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.
+**/
EFI_STATUS
EFIAPI
IdeInitSubmitData (
@@ -411,27 +388,21 @@ IdeInitSubmitData ( IN UINT8 Device,
IN EFI_IDENTIFY_DATA *IdentifyData
)
-/*++
-
-Routine Description:
-
- 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
-
-Arguments:
-
- This -- the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
- Channel -- IDE channel number (0 based, either 0 or 1)
- Device -- IDE device number
- IdentifyData -- A pointer to EFI_IDENTIFY_DATA data structure
-
-Returns:
-
---*/
{
return EFI_SUCCESS;
}
+/**
+ This function is called by IdeBus driver to disqualify unsupported operation
+ 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.
+**/
EFI_STATUS
EFIAPI
IdeInitDisqualifyMode (
@@ -440,27 +411,22 @@ IdeInitDisqualifyMode ( IN UINT8 Device,
IN EFI_ATA_COLLECTIVE_MODE *BadModes
)
-/*++
-
-Routine Description:
-
- This function is called by IdeBus driver to disqualify unsupported operation
- mode on specfic IDE device
-
-Arguments:
-
- This -- the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
- Channel -- IDE channel number (0 based, either 0 or 1)
- Device -- IDE device number
- BadModes -- Operation mode indicator
-
-Returns:
-
---*/
{
return EFI_SUCCESS;
}
+/**
+ This function is called by IdeBus driver to calculate the best operation mode
+ 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_INVALID_PARAMETER Invalid channel id and device id.
+**/
EFI_STATUS
EFIAPI
IdeInitCalculateMode (
@@ -469,23 +435,6 @@ IdeInitCalculateMode ( IN UINT8 Device,
OUT EFI_ATA_COLLECTIVE_MODE **SupportedModes
)
-/*++
-
-Routine Description:
-
- This function is called by IdeBus driver to calculate the best operation mode
- supported by specific IDE device
-
-Arguments:
-
- This -- the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
- Channel -- IDE channel number (0 based, either 0 or 1)
- Device -- IDE device number
- SupportedModes -- Modes collection supported by IDE device
-
-Returns:
-
---*/
{
if (Channel >= ICH_IDE_MAX_CHANNEL || Device >= ICH_IDE_MAX_DEVICES) {
return EFI_INVALID_PARAMETER;
@@ -499,7 +448,17 @@ Returns: return EFI_SUCCESS;
}
+/**
+ This function is called by IdeBus driver to set appropriate timing on IDE
+ 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
EFIAPI
IdeInitSetTiming (
@@ -508,22 +467,6 @@ IdeInitSetTiming ( IN UINT8 Device,
IN EFI_ATA_COLLECTIVE_MODE *Modes
)
-/*++
-
-Routine Description:
-
- This function is called by IdeBus driver to set appropriate timing on IDE
- controller according supported operation mode
-
-Arguments:
-
- This -- the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.
- Channel -- IDE channel number (0 based, either 0 or 1)
- Device -- IDE device number
-
-Returns:
-
---*/
{
return EFI_SUCCESS;
}
diff --git a/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.h b/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.h index 1683e32a43..301b781337 100644 --- a/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.h +++ b/PcAtChipsetPkg/Bus/Pci/IdeControllerDxe/IdeController.h @@ -1,7 +1,7 @@ /** @file
Header file for IDE controller driver.
- Copyright (c) 2008, Intel Corporation. All rights reserved.<BR>
+ 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
@@ -49,6 +49,17 @@ extern EFI_COMPONENT_NAME2_PROTOCOL gIdeControllerComponentName2; //
// Driver binding functions declaration
//
+/**
+ 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 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.
+**/
EFI_STATUS
EFIAPI
IdeControllerSupported (
@@ -56,26 +67,21 @@ IdeControllerSupported ( IN EFI_HANDLE Controller,
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
)
-/*++
-
- Routine Description:
-
- Register Driver Binding protocol for this driver.
-
- Arguments:
-
- This -- a pointer points to the Binding Protocol instance
- Controller -- The handle of controller to be tested.
- *RemainingDevicePath -- A pointer to the device path. Ignored by device
- driver but used by bus driver
-
- Returns:
-
- EFI_SUCCESS -- Driver loaded.
- other -- Driver not loaded.
---*/
;
+/**
+ This routine is called right after the .Supported() called and return
+ EFI_SUCCESS. Notes: The supported protocols are checked but the Protocols
+ 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
EFIAPI
IdeControllerStart (
@@ -83,24 +89,19 @@ IdeControllerStart ( IN EFI_HANDLE Controller,
IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath
)
-/*++
-
- Routine Description:
-
- This routine is called right after the .Supported() called and return
- EFI_SUCCESS. Notes: The supported protocols are checked but the Protocols
- are closed.
-
- Arguments:
-
- This -- a pointer points to the Binding Protocol instance
- Controller -- The handle of controller to be tested. Parameter
- passed by the caller
- *RemainingDevicePath -- A pointer to the device path. Should be ignored by
- device driver
---*/
;
+/**
+ Stop this driver on Controller Handle.
+
+ @param This Protocol instance pointer.
+ @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
+**/
EFI_STATUS
EFIAPI
IdeControllerStop (
@@ -109,27 +110,25 @@ IdeControllerStop ( IN UINTN NumberOfChildren,
IN EFI_HANDLE *ChildHandleBuffer
)
-/*++
-
- Routine Description:
- Stop this driver on Controller Handle.
-
- Arguments:
- This - Protocol instance pointer.
- Controller - Handle of device to stop driver on
- NumberOfChildren - Not used
- ChildHandleBuffer - Not used
-
- Returns:
- EFI_SUCCESS - This driver is removed DeviceHandle
- other - This driver was not removed from this device
-
---*/
;
//
// 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.
+
+ @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,
+ 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.
+**/
EFI_STATUS
EFIAPI
IdeInitGetChannelInfo (
@@ -138,26 +137,18 @@ IdeInitGetChannelInfo ( OUT BOOLEAN *Enabled,
OUT UINT8 *MaxDevices
)
-/*++
-
-Routine Description:
-
- TODO: Add function description
-
-Arguments:
-
- This - TODO: add argument description
- Channel - TODO: add argument description
- Enabled - TODO: add argument description
- MaxDevices - TODO: add argument description
-
-Returns:
-
- TODO: add return values
-
---*/
;
+/**
+ 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
EFIAPI
IdeInitNotifyPhase (
@@ -165,25 +156,19 @@ IdeInitNotifyPhase ( IN EFI_IDE_CONTROLLER_ENUM_PHASE Phase,
OUT UINT8 Channel
)
-/*++
-
-Routine Description:
-
- TODO: Add function description
-
-Arguments:
-
- This - TODO: add argument description
- Phase - TODO: add argument description
- Channel - TODO: add argument description
-
-Returns:
-
- TODO: add return values
-
---*/
;
+/**
+ 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
+
+ @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.
+**/
EFI_STATUS
EFIAPI
IdeInitSubmitData (
@@ -192,52 +177,19 @@ IdeInitSubmitData ( IN UINT8 Device,
IN EFI_IDENTIFY_DATA *IdentifyData
)
-/*++
-
-Routine Description:
-
- TODO: Add function description
-
-Arguments:
-
- This - TODO: add argument description
- Channel - TODO: add argument description
- Device - TODO: add argument description
- IdentifyData - TODO: add argument description
-
-Returns:
-
- TODO: add return values
-
---*/
;
-EFI_STATUS
-EFIAPI
-IdeInitSubmitFailingModes (
- IN EFI_IDE_CONTROLLER_INIT_PROTOCOL *This,
- IN UINT8 Channel,
- IN UINT8 Device
- )
-/*++
-
-Routine Description:
-
- TODO: Add function description
-
-Arguments:
-
- This - TODO: add argument description
- Channel - TODO: add argument description
- Device - TODO: add argument description
-
-Returns:
-
- TODO: add return values
-
---*/
-;
+/**
+ This function is called by IdeBus driver to disqualify unsupported operation
+ 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.
+**/
EFI_STATUS
EFIAPI
IdeInitDisqualifyMode (
@@ -246,26 +198,20 @@ IdeInitDisqualifyMode ( IN UINT8 Device,
IN EFI_ATA_COLLECTIVE_MODE *BadModes
)
-/*++
-
-Routine Description:
-
- TODO: Add function description
-
-Arguments:
-
- This - TODO: add argument description
- Channel - TODO: add argument description
- Device - TODO: add argument description
- BadModes - TODO: add argument description
-
-Returns:
-
- TODO: add return values
-
---*/
;
+/**
+ This function is called by IdeBus driver to calculate the best operation mode
+ 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_INVALID_PARAMETER Invalid channel id and device id.
+**/
EFI_STATUS
EFIAPI
IdeInitCalculateMode (
@@ -274,26 +220,19 @@ IdeInitCalculateMode ( IN UINT8 Device,
IN EFI_ATA_COLLECTIVE_MODE **SupportedModes
)
-/*++
-
-Routine Description:
-
- TODO: Add function description
-
-Arguments:
-
- This - TODO: add argument description
- Channel - TODO: add argument description
- Device - TODO: add argument description
- SupportedModes - TODO: add argument description
-
-Returns:
-
- TODO: add return values
-
---*/
;
+/**
+ This function is called by IdeBus driver to set appropriate timing on IDE
+ 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
EFIAPI
IdeInitSetTiming (
@@ -302,29 +241,32 @@ IdeInitSetTiming ( IN UINT8 Device,
IN EFI_ATA_COLLECTIVE_MODE *Modes
)
-/*++
-
-Routine Description:
-
- TODO: Add function description
-
-Arguments:
-
- This - TODO: add argument description
- Channel - TODO: add argument description
- Device - TODO: add argument description
- Modes - TODO: add argument description
-
-Returns:
-
- TODO: add return values
-
---*/
;
//
// Forward reference declaration
//
+/**
+ Retrieves a Unicode string that is the user readable name of the EFI Driver.
+
+ @param This A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
+ @param Language A pointer to a three character ISO 639-2 language identifier.
+ This is the language of the driver name that that the caller
+ is requesting, and it must match one of the languages specified
+ in SupportedLanguages. The number of languages supported by a
+ driver is up to the driver writer.
+ @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.
+ @retval EFI_INVALID_PARAMETER Language is NULL.
+ @retval EFI_INVALID_PARAMETER DriverName is NULL.
+ @retval EFI_UNSUPPORTED The driver specified by This does not support the
+ language specified by Language.
+**/
EFI_STATUS
EFIAPI
IdeControllerComponentNameGetDriverName (
@@ -332,34 +274,48 @@ IdeControllerComponentNameGetDriverName ( IN CHAR8 *Language,
OUT CHAR16 **DriverName
)
-/*++
-
- Routine Description:
- Retrieves a Unicode string that is the user readable name of the EFI Driver.
-
- Arguments:
- This - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
- Language - A pointer to a three character ISO 639-2 language identifier.
- This is the language of the driver name that that the caller
- is requesting, and it must match one of the languages specified
- in SupportedLanguages. The number of languages supported by a
- driver is up to the driver writer.
- 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.
-
- Returns:
- EFI_SUCCESS - The Unicode string for the Driver specified by This
- and the language specified by Language was returned
- in DriverName.
- EFI_INVALID_PARAMETER - Language is NULL.
- EFI_INVALID_PARAMETER - DriverName is NULL.
- EFI_UNSUPPORTED - The driver specified by This does not support the
- language specified by Language.
-
---*/
;
+/**
+ Retrieves a Unicode string that is the user readable name of the controller
+ 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
+ This is managing. This handle specifies the controller
+ whose name is to be returned.
+ @param OPTIONAL The handle of the child controller to retrieve the name
+ of. This is an optional parameter that may be NULL. It
+ will be NULL for device drivers. It will also be NULL
+ for a bus drivers that wish to retrieve the name of the
+ bus controller. It will not be NULL for a bus driver
+ that wishes to retrieve the name of a child controller.
+ @param Language A pointer to a three character ISO 639-2 language
+ identifier. This is the language of the controller name
+ that that the caller is requesting, and it must match one
+ of the languages specified in SupportedLanguages. The
+ number of languages supported by a driver is up to the
+ driver writer.
+ @param ControllerName A pointer to the Unicode string to return. This Unicode
+ string is the name of the controller specified by
+ 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.
+ @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
+ @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
+ EFI_HANDLE.
+ @retval EFI_INVALID_PARAMETER Language is NULL.
+ @retval EFI_INVALID_PARAMETER ControllerName is NULL.
+ @retval EFI_UNSUPPORTED The driver specified by This is not currently
+ managing the controller specified by
+ ControllerHandle and ChildHandle.
+ @retval EFI_UNSUPPORTED The driver specified by This does not support the
+ language specified by Language.
+**/
EFI_STATUS
EFIAPI
IdeControllerComponentNameGetControllerName (
@@ -369,51 +325,6 @@ IdeControllerComponentNameGetControllerName ( IN CHAR8 *Language,
OUT CHAR16 **ControllerName
)
-/*++
-
- Routine Description:
- Retrieves a Unicode string that is the user readable name of the controller
- that is being managed by an EFI Driver.
-
- Arguments:
- This - A pointer to the EFI_COMPONENT_NAME_PROTOCOL instance.
- ControllerHandle - The handle of a controller that the driver specified by
- This is managing. This handle specifies the controller
- whose name is to be returned.
- ChildHandle - The handle of the child controller to retrieve the name
- of. This is an optional parameter that may be NULL. It
- will be NULL for device drivers. It will also be NULL
- for a bus drivers that wish to retrieve the name of the
- bus controller. It will not be NULL for a bus driver
- that wishes to retrieve the name of a child controller.
- Language - A pointer to a three character ISO 639-2 language
- identifier. This is the language of the controller name
- that that the caller is requesting, and it must match one
- of the languages specified in SupportedLanguages. The
- number of languages supported by a driver is up to the
- driver writer.
- ControllerName - A pointer to the Unicode string to return. This Unicode
- string is the name of the controller specified by
- ControllerHandle and ChildHandle in the language
- specified by Language from the point of view of the
- driver specified by This.
-
- Returns:
- 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.
- EFI_INVALID_PARAMETER - ControllerHandle is not a valid EFI_HANDLE.
- EFI_INVALID_PARAMETER - ChildHandle is not NULL and it is not a valid
- EFI_HANDLE.
- EFI_INVALID_PARAMETER - Language is NULL.
- EFI_INVALID_PARAMETER - ControllerName is NULL.
- EFI_UNSUPPORTED - The driver specified by This is not currently
- managing the controller specified by
- ControllerHandle and ChildHandle.
- EFI_UNSUPPORTED - The driver specified by This does not support the
- language specified by Language.
-
---*/
;
#endif
|