Update comments for Protocol definitions to match UEFI spec.

And add the missing comments for the data structure.

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

1 files changed, 62 insertions, 45 deletions

diff --git a/MdePkg/Include/Protocol/DriverBinding.h b/MdePkg/Include/Protocol/DriverBinding.h
index 9377891519..e5645f32e4 100644
--- a/MdePkg/Include/Protocol/DriverBinding.h
+++ b/MdePkg/Include/Protocol/DriverBinding.h
@@ -30,22 +30,27 @@
 typedef struct _EFI_DRIVER_BINDING_PROTOCOL  EFI_DRIVER_BINDING_PROTOCOL;

 

 /**

-  Test to see if this driver supports ControllerHandle. This service

-  is called by the EFI boot service ConnectController(). In

-  order to make drivers as small as possible, there are a few calling

-  restrictions for this service. ConnectController() must

-  follow these calling restrictions. If any other agent wishes to call

-  Supported() it must also follow these calling restrictions.

-

-  @param  This                Protocol instance pointer.

-  @param  ControllerHandle    Handle of device to test

-  @param  RemainingDevicePath Optional parameter use to pick a specific child

-                              device to start.

-

-  @retval EFI_SUCCESS         This driver supports this device

-  @retval EFI_ALREADY_STARTED This driver is already running on this device

-  @retval other               This driver does not support this device

-

+  Tests to see if this driver supports a given controller. If a child device is provided, 

+  it further tests to see if this driver supports creating a handle for the specified child device.

+

+  @param  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.

+  @param  ControllerHandle     The handle of the controller to test. This handle 

+                               must support a protocol interface that supplies 

+                               an I/O abstraction to the driver.

+  @param  RemainingDevicePath  A pointer to the remaining portion of a device path. 

+                               This parameter is ignored by device drivers, and is optional for bus drivers.

+

+

+  @retval EFI_SUCCESS         The device specified by ControllerHandle and

+                              RemainingDevicePath is supported by the driver specified by This.

+  @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and

+                              RemainingDevicePath is already being managed by the driver

+                              specified by This.

+  @retval EFI_ACCESS_DENIED   The device specified by ControllerHandle and

+                              RemainingDevicePath is already being managed by a different

+                              driver or an application that requires exclusive acces.

+  @retval EFI_UNSUPPORTED     The device specified by ControllerHandle and

+                              RemainingDevicePath is not supported by the driver specified by This.

 **/

 typedef

 EFI_STATUS

@@ -56,21 +61,27 @@ EFI_STATUS
   );

 

 /**

-  Start this driver on ControllerHandle. This service is called by the

-  EFI boot service ConnectController(). In order to make

-  drivers as small as possible, there are a few calling restrictions for

-  this service. ConnectController() must follow these

-  calling restrictions. If any other agent wishes to call Start() it

-  must also follow these calling restrictions.

-

-  @param  This                 Protocol instance pointer.

-  @param  ControllerHandle     Handle of device to bind driver to

-  @param  RemainingDevicePath  Optional parameter use to pick a specific child

-                               device to start.

-

-  @retval EFI_SUCCESS          This driver is added to ControllerHandle

-  @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle

-  @retval other                This driver does not support this device

+  Start this driver on ControllerHandle. The Start() function is designed to be 

+  invoked from the EFI boot service ConnectController(). As a result, much of 

+  the error checking on the parameters to Start() has been moved into this 

+  common boot service. It is legal to call Start() from other locations, 

+  but the following calling restrictions must be followed or the system behavior will not be deterministic.

+  1. ControllerHandle must be a valid EFI_HANDLE.

+  2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned

+     EFI_DEVICE_PATH_PROTOCOL.

+  3. Prior to calling Start(), the Supported() function for the driver specified by This must

+     have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.  

+

+  @param  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.

+  @param  ControllerHandle     The handle of the controller to start. This handle 

+                               must support a protocol interface that supplies 

+                               an I/O abstraction to the driver.

+  @param  RemainingDevicePath  A pointer to the remaining portion of a device path. 

+                               This parameter is ignored by device drivers, and is optional for bus drivers.

+

+  @retval EFI_SUCCESS          The device was started.

+  @retval EFI_ALREADY_STARTED  The device could not be started due to a device error.

+  @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.

 

 **/

 typedef

@@ -82,21 +93,27 @@ EFI_STATUS
   );

 

 /**

-  Stop this driver on ControllerHandle. This service is called by the

-  EFI boot service DisconnectController(). In order to

-  make drivers as small as possible, there are a few calling

-  restrictions for this service. DisconnectController()

-  must follow these calling restrictions. If any other agent wishes

-  to call Stop() it must also follow these calling restrictions.

+  Stop this driver on ControllerHandle. 

+  The Stop() function is designed to be invoked from the EFI boot service DisconnectController(). 

+  As a result, much of the error checking on the parameters to Stop() has been moved 

+  into this common boot service. It is legal to call Stop() from other locations, 

+  but the following calling restrictions must be followed or the system behavior will not be deterministic.

+  1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this

+     same driver's Start() function.

+  2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid

+     EFI_HANDLE. In addition, all of these handles must have been created in this driver’s

+     Start() function, and the Start() function must have called OpenProtocol() on

+     ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.

   

-  @param  This              Protocol instance pointer.

-  @param  ControllerHandle  Handle of device to stop driver on

-  @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of

-                            children is zero stop the entire bus driver.

-  @param  ChildHandleBuffer List of Child Handles to Stop.

-

-  @retval EFI_SUCCESS       This driver is removed ControllerHandle

-  @retval other             This driver was not removed from this device

+  @param  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.

+  @param  ControllerHandle  A handle to the device being stopped. The handle must 

+                            support a bus specific I/O protocol for the driver 

+                            to use to stop the device.

+  @param  NumberOfChildren  The number of child device handles in ChildHandleBuffer.

+  @param  ChildHandleBuffer An array of child handles to be freed. May be NULL if NumberOfChildren is 0.

+

+  @retval EFI_SUCCESS       The device was stopped.

+  @retval EFI_DEVICE_ERROR  The device could not be stopped due to a device error.

 

 **/

 typedef