According to PI errata 0000690, word "Ide Bus driver" has been replaced with "Driver entity".

Signed-off-by: erictian
Reviewed-by: lgao4

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

2 files changed, 400 insertions, 122 deletions

diff --git a/DuetPkg/SataControllerDxe/SataController.c b/DuetPkg/SataControllerDxe/SataController.c
index ea8a06769..d1e85cc6e 100644
--- a/DuetPkg/SataControllerDxe/SataController.c
+++ b/DuetPkg/SataControllerDxe/SataController.c
@@ -604,22 +604,40 @@ SataControllerStop (
 // 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. Parallel ATA (PATA) controllers can support up to two channels.

-                        Advanced Host Controller Interface (AHCI) Serial ATA (SATA) controllers

-                        can support up to 32 channels, each of which can have up to 1 device.

-                        In the presence of a multiplier, each channel can have 15 devices.

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

-                        then it will no be enumerated.

-  @param MaxDevices     For Parallel ATA (PATA) controllers, this number will either be 1 or 2.

-                        For Serial ATA (SATA) controllers, it always be 1,

-                        but with a port multiplier, this number can be as large as 15.

-

-  @retval EFI_SUCCESS           Success to get channel information.

-  @retval EFI_INVALID_PARAMETER Invalid channel id.

+  Returns the information about the specified IDE channel.

+  

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

+  The driver entity uses this information during the enumeration process. 

+  

+  If Enabled is set to FALSE, the driver entity will not scan the channel. Note 

+  that it will not prevent an operating system driver from scanning the channel.

+  

+  For most of today's controllers, MaxDevices will either be 1 or 2. For SATA 

+  controllers, this value will always be 1. SATA configurations can contain SATA 

+  port multipliers. SATA port multipliers behave like SATA bridges and can support

+  up to 16 devices on the other side. If a SATA port out of the IDE controller 

+  is connected to a port multiplier, MaxDevices will be set to the number of SATA 

+  devices that the port multiplier supports. Because today's port multipliers 

+  support up to fifteen SATA devices, this number can be as large as fifteen. The IDE  

+  bus driver is required to scan for the presence of port multipliers behind an SATA 

+  controller and enumerate up to MaxDevices number of devices behind the port 

+  multiplier.    

+  

+  In this context, the devices behind a port multiplier constitute a channel.  

+  

+  @param[in]  This         The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

+  @param[in]  Channel      Zero-based channel number.

+  @param[out] Enabled      TRUE if this channel is enabled.  Disabled channels 

+                           are not scanned to see if any devices are present.

+  @param[out] MaxDevices   The maximum number of IDE devices that the bus driver

+                           can expect on this channel.  For the ATA/ATAPI 

+                           specification, version 6, this number will either be 

+                           one or two. For Serial ATA (SATA) configurations with a 

+                           port multiplier, this number can be as large as fifteen.

+

+  @retval EFI_SUCCESS             Information was returned without any errors.

+  @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).

+

 **/

 EFI_STATUS

 EFIAPI

@@ -645,14 +663,28 @@ IdeInitGetChannelInfo (
 }

 

 /**

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

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

+  The notifications from the driver entity that it is about to enter a certain

+  phase of the IDE channel enumeration process.

+  

+  This function can be used to notify the IDE controller driver to perform 

+  specific actions, including any chipset-specific initialization, so that the 

+  chipset is ready to enter the next phase. Seven notification points are defined 

+  at this time. 

+  

+  More synchronization points may be added as required in the future.  

+

+  @param[in] This      The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

+  @param[in] Phase     The phase during enumeration.

+  @param[in] Channel   Zero-based channel number.

 

-  @param This       The EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

-  @param Phase      Phase indicator defined by IDE_CONTROLLER_INIT protocol.

-  @param Channel    Channel number.

+  @retval EFI_SUCCESS             The notification was accepted without any errors.

+  @retval EFI_UNSUPPORTED         Phase is not supported.

+  @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).

+  @retval EFI_NOT_READY           This phase cannot be entered at this time; for 

+                                  example, an attempt was made to enter a Phase 

+                                  without having entered one or more previous 

+                                  Phase.

 

-  @retval EFI_SUCCESS   Success operation.

 **/

 EFI_STATUS

 EFIAPI

@@ -666,16 +698,43 @@ 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.

-

-  @param This           The EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

-  @param Channel        Channel number.

-  @param Device         Device number.

-  @param IdentifyData   A pointer to EFI_IDENTIFY_DATA data structure.

+  Submits the device information to the IDE controller driver.

+

+  This function is used by the driver entity to pass detailed information about 

+  a particular device to the IDE controller driver. The driver entity obtains 

+  this information by issuing an ATA or ATAPI IDENTIFY_DEVICE command. IdentifyData

+  is the pointer to the response data buffer. The IdentifyData buffer is owned 

+  by the driver entity, and the IDE controller driver must make a local copy 

+  of the entire buffer or parts of the buffer as needed. The original IdentifyData 

+  buffer pointer may not be valid when

+  

+    - EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() or

+    - EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() is called at a later point.

+    

+  The IDE controller driver may consult various fields of EFI_IDENTIFY_DATA to 

+  compute the optimum mode for the device. These fields are not limited to the 

+  timing information. For example, an implementation of the IDE controller driver 

+  may examine the vendor and type/mode field to match known bad drives.  

+  

+  The driver entity may submit drive information in any order, as long as it 

+  submits information for all the devices belonging to the enumeration group 

+  before EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() is called for any device

+  in that enumeration group. If a device is absent, EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()

+  should be called with IdentifyData set to NULL.  The IDE controller driver may 

+  not have any other mechanism to know whether a device is present or not. Therefore, 

+  setting IdentifyData to NULL does not constitute an error condition. 

+  EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() can be called only once for a 

+  given (Channel, Device) pair.  

+    

+  @param[in] This           A pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

+  @param[in] Channel        Zero-based channel number.

+  @param[in] Device         Zero-based device number on the Channel.

+  @param[in] IdentifyData   The device's response to the ATA IDENTIFY_DEVICE command.

+

+  @retval EFI_SUCCESS             The information was accepted without any errors.

+  @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).

+  @retval EFI_INVALID_PARAMETER   Device is invalid.

 

-  @retval EFI_SUCCESS           The information is accepted without any errors.

-  @retval EFI_INVALID_PARAMETER Invalid channel id or device id.

 **/

 EFI_STATUS

 EFIAPI

@@ -713,17 +772,44 @@ IdeInitSubmitData (
 }

 

 /**

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

-  @param Device     Device number.

-  @param BadModes   The modes that the device does not support and that

-                    should be disqualified.

-

-  @retval EFI_SUCCESS           The modes were accepted without any errors.

-  @retval EFI_INVALID_PARAMETER Invalid channel id or device id.

+  Disqualifies specific modes for an IDE device.

+

+  This function allows the driver entity or other drivers (such as platform 

+  drivers) to reject certain timing modes and request the IDE controller driver

+  to recalculate modes. This function allows the driver entity and the IDE 

+  controller driver to negotiate the timings on a per-device basis. This function 

+  is useful in the case of drives that lie about their capabilities. An example 

+  is when the IDE device fails to accept the timing modes that are calculated 

+  by the IDE controller driver based on the response to the Identify Drive command.

+

+  If the driver entity does not want to limit the ATA timing modes and leave that 

+  decision to the IDE controller driver, it can either not call this function for 

+  the given device or call this function and set the Valid flag to FALSE for all 

+  modes that are listed in EFI_ATA_COLLECTIVE_MODE.

+  

+  The driver entity may disqualify modes for a device in any order and any number 

+  of times.

+  

+  This function can be called multiple times to invalidate multiple modes of the 

+  same type (e.g., Programmed Input/Output [PIO] modes 3 and 4). See the ATA/ATAPI 

+  specification for more information on PIO modes.  

+  

+  For Serial ATA (SATA) controllers, this member function can be used to disqualify

+  a higher transfer rate mode on a given channel. For example, a platform driver

+  may inform the IDE controller driver to not use second-generation (Gen2) speeds 

+  for a certain SATA drive.

+  

+  @param[in] This       The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

+  @param[in] Channel    The zero-based channel number.

+  @param[in] Device     The zero-based device number on the Channel.

+  @param[in] BadModes   The modes that the device does not support and that

+                        should be disqualified.

+

+  @retval EFI_SUCCESS             The modes were accepted without any errors.

+  @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).

+  @retval EFI_INVALID_PARAMETER   Device is invalid.

+  @retval EFI_INVALID_PARAMETER   IdentifyData is NULL.

+                                

 **/

 EFI_STATUS

 EFIAPI

@@ -756,18 +842,58 @@ IdeInitDisqualifyMode (
 }

 

 /**

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

-  @param Device             Device number.

-  @param SupportedModes     The optimum modes for the device.

-

-  @retval EFI_SUCCESS           Supported modes are returned.

-  @retval EFI_INVALID_PARAMETER Invalid channel id or device id.

-  @retval EFI_OUT_OF_RESOURCES  Fail to allocate pool.

-  @retval EFI_NOT_READY         Identify data of the device is not ready.

+  Returns the information about the optimum modes for the specified IDE device.

+

+  This function is used by the driver entity to obtain the optimum ATA modes for

+  a specific device.  The IDE controller driver takes into account the following 

+  while calculating the mode:

+    - The IdentifyData inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()

+    - The BadModes inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode()

+

+  The driver entity is required to call EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() 

+  for all the devices that belong to an enumeration group before calling 

+  EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() for any device in the same group.  

+  

+  The IDE controller driver will use controller- and possibly platform-specific 

+  algorithms to arrive at SupportedModes.  The IDE controller may base its 

+  decision on user preferences and other considerations as well. This function 

+  may be called multiple times because the driver entity may renegotiate the mode 

+  with the IDE controller driver using EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode().

+    

+  The driver entity may collect timing information for various devices in any 

+  order. The driver entity is responsible for making sure that all the dependencies

+  are satisfied. For example, the SupportedModes information for device A that 

+  was previously returned may become stale after a call to 

+  EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() for device B.

+  

+  The buffer SupportedModes is allocated by the callee because the caller does 

+  not necessarily know the size of the buffer. The type EFI_ATA_COLLECTIVE_MODE 

+  is defined in a way that allows for future extensibility and can be of variable 

+  length. This memory pool should be deallocated by the caller when it is no 

+  longer necessary.  

+  

+  The IDE controller driver for a Serial ATA (SATA) controller can use this 

+  member function to force a lower speed (first-generation [Gen1] speeds on a 

+  second-generation [Gen2]-capable hardware).  The IDE controller driver can 

+  also allow the driver entity to stay with the speed that has been negotiated 

+  by the physical layer.

+  

+  @param[in]  This             The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

+  @param[in]  Channel          A zero-based channel number.

+  @param[in]  Device           A zero-based device number on the Channel.

+  @param[out] SupportedModes   The optimum modes for the device.

+

+  @retval EFI_SUCCESS             SupportedModes was returned.

+  @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).

+  @retval EFI_INVALID_PARAMETER   Device is invalid. 

+  @retval EFI_INVALID_PARAMETER   SupportedModes is NULL.

+  @retval EFI_NOT_READY           Modes cannot be calculated due to a lack of 

+                                  data.  This error may happen if 

+                                  EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() 

+                                  and EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyData() 

+                                  were not called for at least one drive in the 

+                                  same enumeration group.

+

 **/

 EFI_STATUS

 EFIAPI

@@ -844,15 +970,27 @@ IdeInitCalculateMode (
 }

 

 /**

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

-  @param Device     Device number.

-  @param Modes      The modes to set.

+  Commands the IDE controller driver to program the IDE controller hardware

+  so that the specified device can operate at the specified mode.

+

+  This function is used by the driver entity to instruct the IDE controller 

+  driver to program the IDE controller hardware to the specified modes. This 

+  function can be called only once for a particular device. For a Serial ATA 

+  (SATA) Advanced Host Controller Interface (AHCI) controller, no controller-

+  specific programming may be required.

+

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

+  @param[in] Channel   Zero-based channel number.

+  @param[in] Device    Zero-based device number on the Channel.

+  @param[in] Modes     The modes to set.

+

+  @retval EFI_SUCCESS             The command was accepted without any errors.

+  @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).

+  @retval EFI_INVALID_PARAMETER   Device is invalid.

+  @retval EFI_NOT_READY           Modes cannot be set at this time due to lack of data.

+  @retval EFI_DEVICE_ERROR        Modes cannot be set due to hardware failure.

+                                  The driver entity should not use this device.

 

-  @retval EFI_SUCCESS   Sucess operation.

 **/

 EFI_STATUS

 EFIAPI

diff --git a/DuetPkg/SataControllerDxe/SataController.h b/DuetPkg/SataControllerDxe/SataController.h
index 0352178ba..d2a929f3b 100644
--- a/DuetPkg/SataControllerDxe/SataController.h
+++ b/DuetPkg/SataControllerDxe/SataController.h
@@ -181,21 +181,40 @@ SataControllerStop (
 // 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. Parallel ATA (PATA) controllers can support up to two channels.

-                        Advanced Host Controller Interface (AHCI) Serial ATA (SATA) controllers

-                        can support up to 32 channels, each of which can have up to one device.

-                        In the presence of a multiplier, each channel can have 15 devices.

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

-                        then it will no be enumerated.

-  @param MaxDevices     For Parallel ATA (PATA) controllers, this number will either be 1 or 2.

-                        For Serial ATA (SATA) controllers with a port multiplier, this number can be as large as 15.

-

-  @retval EFI_SUCCESS           Success to get channel information.

-  @retval EFI_INVALID_PARAMETER Invalid channel id.

+  Returns the information about the specified IDE channel.

+  

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

+  The driver entity uses this information during the enumeration process. 

+  

+  If Enabled is set to FALSE, the driver entity will not scan the channel. Note 

+  that it will not prevent an operating system driver from scanning the channel.

+  

+  For most of today's controllers, MaxDevices will either be 1 or 2. For SATA 

+  controllers, this value will always be 1. SATA configurations can contain SATA 

+  port multipliers. SATA port multipliers behave like SATA bridges and can support

+  up to 16 devices on the other side. If a SATA port out of the IDE controller 

+  is connected to a port multiplier, MaxDevices will be set to the number of SATA 

+  devices that the port multiplier supports. Because today's port multipliers 

+  support up to fifteen SATA devices, this number can be as large as fifteen. The IDE  

+  bus driver is required to scan for the presence of port multipliers behind an SATA 

+  controller and enumerate up to MaxDevices number of devices behind the port 

+  multiplier.    

+  

+  In this context, the devices behind a port multiplier constitute a channel.  

+  

+  @param[in]  This         The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

+  @param[in]  Channel      Zero-based channel number.

+  @param[out] Enabled      TRUE if this channel is enabled.  Disabled channels 

+                           are not scanned to see if any devices are present.

+  @param[out] MaxDevices   The maximum number of IDE devices that the bus driver

+                           can expect on this channel.  For the ATA/ATAPI 

+                           specification, version 6, this number will either be 

+                           one or two. For Serial ATA (SATA) configurations with a 

+                           port multiplier, this number can be as large as fifteen.

+

+  @retval EFI_SUCCESS             Information was returned without any errors.

+  @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).

+

 **/

 EFI_STATUS

 EFIAPI

@@ -208,14 +227,28 @@ IdeInitGetChannelInfo (
 ;

 

 /**

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

+  The notifications from the driver entity that it is about to enter a certain

+  phase of the IDE channel enumeration process.

+  

+  This function can be used to notify the IDE controller driver to perform 

+  specific actions, including any chipset-specific initialization, so that the 

+  chipset is ready to enter the next phase. Seven notification points are defined 

+  at this time. 

+  

+  More synchronization points may be added as required in the future.  

+

+  @param[in] This      The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

+  @param[in] Phase     The phase during enumeration.

+  @param[in] Channel   Zero-based channel number.

+

+  @retval EFI_SUCCESS             The notification was accepted without any errors.

+  @retval EFI_UNSUPPORTED         Phase is not supported.

+  @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).

+  @retval EFI_NOT_READY           This phase cannot be entered at this time; for 

+                                  example, an attempt was made to enter a Phase 

+                                  without having entered one or more previous 

+                                  Phase.

 

-  @retval EFI_SUCCESS   Success operation.

 **/

 EFI_STATUS

 EFIAPI

@@ -227,16 +260,43 @@ 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.

+  Submits the device information to the IDE controller driver.

+

+  This function is used by the driver entity to pass detailed information about 

+  a particular device to the IDE controller driver. The driver entity obtains 

+  this information by issuing an ATA or ATAPI IDENTIFY_DEVICE command. IdentifyData

+  is the pointer to the response data buffer. The IdentifyData buffer is owned 

+  by the driver entity, and the IDE controller driver must make a local copy 

+  of the entire buffer or parts of the buffer as needed. The original IdentifyData 

+  buffer pointer may not be valid when

+  

+    - EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() or

+    - EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() is called at a later point.

+    

+  The IDE controller driver may consult various fields of EFI_IDENTIFY_DATA to 

+  compute the optimum mode for the device. These fields are not limited to the 

+  timing information. For example, an implementation of the IDE controller driver 

+  may examine the vendor and type/mode field to match known bad drives.  

+  

+  The driver entity may submit drive information in any order, as long as it 

+  submits information for all the devices belonging to the enumeration group 

+  before EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() is called for any device

+  in that enumeration group. If a device is absent, EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()

+  should be called with IdentifyData set to NULL.  The IDE controller driver may 

+  not have any other mechanism to know whether a device is present or not. Therefore, 

+  setting IdentifyData to NULL does not constitute an error condition. 

+  EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() can be called only once for a 

+  given (Channel, Device) pair.  

+    

+  @param[in] This           A pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

+  @param[in] Channel        Zero-based channel number.

+  @param[in] Device         Zero-based device number on the Channel.

+  @param[in] IdentifyData   The device's response to the ATA IDENTIFY_DEVICE command.

+

+  @retval EFI_SUCCESS             The information was accepted without any errors.

+  @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).

+  @retval EFI_INVALID_PARAMETER   Device is invalid.

 

-  @param This           The EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

-  @param Channel        Channel number.

-  @param Device         Device number.

-  @param IdentifyData   A pointer to EFI_IDENTIFY_DATA data structure.

-

-  @retval EFI_SUCCESS           The information was accepted without any errors.

-  @retval EFI_INVALID_PARAMETER Invalid channel id or device id.

 **/

 EFI_STATUS

 EFIAPI

@@ -249,17 +309,44 @@ IdeInitSubmitData (
 ;

 

 /**

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

-  @param Device     Device number.

-  @param BadModes   The modes that the device does not support and that

-                    should be disqualified.

-

-  @retval EFI_SUCCESS           The modes were accepted without any errors.

-  @retval EFI_INVALID_PARAMETER Invalid channel id or device id.

+  Disqualifies specific modes for an IDE device.

+

+  This function allows the driver entity or other drivers (such as platform 

+  drivers) to reject certain timing modes and request the IDE controller driver

+  to recalculate modes. This function allows the driver entity and the IDE 

+  controller driver to negotiate the timings on a per-device basis. This function 

+  is useful in the case of drives that lie about their capabilities. An example 

+  is when the IDE device fails to accept the timing modes that are calculated 

+  by the IDE controller driver based on the response to the Identify Drive command.

+

+  If the driver entity does not want to limit the ATA timing modes and leave that 

+  decision to the IDE controller driver, it can either not call this function for 

+  the given device or call this function and set the Valid flag to FALSE for all 

+  modes that are listed in EFI_ATA_COLLECTIVE_MODE.

+  

+  The driver entity may disqualify modes for a device in any order and any number 

+  of times.

+  

+  This function can be called multiple times to invalidate multiple modes of the 

+  same type (e.g., Programmed Input/Output [PIO] modes 3 and 4). See the ATA/ATAPI 

+  specification for more information on PIO modes.  

+  

+  For Serial ATA (SATA) controllers, this member function can be used to disqualify

+  a higher transfer rate mode on a given channel. For example, a platform driver

+  may inform the IDE controller driver to not use second-generation (Gen2) speeds 

+  for a certain SATA drive.

+  

+  @param[in] This       The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

+  @param[in] Channel    The zero-based channel number.

+  @param[in] Device     The zero-based device number on the Channel.

+  @param[in] BadModes   The modes that the device does not support and that

+                        should be disqualified.

+

+  @retval EFI_SUCCESS             The modes were accepted without any errors.

+  @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).

+  @retval EFI_INVALID_PARAMETER   Device is invalid.

+  @retval EFI_INVALID_PARAMETER   IdentifyData is NULL.

+                                

 **/

 EFI_STATUS

 EFIAPI

@@ -272,17 +359,58 @@ IdeInitDisqualifyMode (
 ;

 

 /**

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

-  @param Device             Device number.

-  @param SupportedModes     The optimum modes for the device.

+  Returns the information about the optimum modes for the specified IDE device.

+

+  This function is used by the driver entity to obtain the optimum ATA modes for

+  a specific device.  The IDE controller driver takes into account the following 

+  while calculating the mode:

+    - The IdentifyData inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()

+    - The BadModes inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode()

+

+  The driver entity is required to call EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() 

+  for all the devices that belong to an enumeration group before calling 

+  EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() for any device in the same group.  

+  

+  The IDE controller driver will use controller- and possibly platform-specific 

+  algorithms to arrive at SupportedModes.  The IDE controller may base its 

+  decision on user preferences and other considerations as well. This function 

+  may be called multiple times because the driver entity may renegotiate the mode 

+  with the IDE controller driver using EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode().

+    

+  The driver entity may collect timing information for various devices in any 

+  order. The driver entity is responsible for making sure that all the dependencies

+  are satisfied. For example, the SupportedModes information for device A that 

+  was previously returned may become stale after a call to 

+  EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() for device B.

+  

+  The buffer SupportedModes is allocated by the callee because the caller does 

+  not necessarily know the size of the buffer. The type EFI_ATA_COLLECTIVE_MODE 

+  is defined in a way that allows for future extensibility and can be of variable 

+  length. This memory pool should be deallocated by the caller when it is no 

+  longer necessary.  

+  

+  The IDE controller driver for a Serial ATA (SATA) controller can use this 

+  member function to force a lower speed (first-generation [Gen1] speeds on a 

+  second-generation [Gen2]-capable hardware).  The IDE controller driver can 

+  also allow the driver entity to stay with the speed that has been negotiated 

+  by the physical layer.

+  

+  @param[in]  This             The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.

+  @param[in]  Channel          A zero-based channel number.

+  @param[in]  Device           A zero-based device number on the Channel.

+  @param[out] SupportedModes   The optimum modes for the device.

+

+  @retval EFI_SUCCESS             SupportedModes was returned.

+  @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).

+  @retval EFI_INVALID_PARAMETER   Device is invalid. 

+  @retval EFI_INVALID_PARAMETER   SupportedModes is NULL.

+  @retval EFI_NOT_READY           Modes cannot be calculated due to a lack of 

+                                  data.  This error may happen if 

+                                  EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() 

+                                  and EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyData() 

+                                  were not called for at least one drive in the 

+                                  same enumeration group.

 

-  @retval EFI_SUCCESS           SupportedModes was returned.

-  @retval EFI_OUT_OF_RESOURCES  Fail to allocate pool.

-  @retval EFI_INVALID_PARAMETER Invalid channel id or device id.

 **/

 EFI_STATUS

 EFIAPI

@@ -295,15 +423,27 @@ IdeInitCalculateMode (
 ;

 

 /**

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

-  @param Device     Device number.

-  @param Modes      The modes to set.

+  Commands the IDE controller driver to program the IDE controller hardware

+  so that the specified device can operate at the specified mode.

+

+  This function is used by the driver entity to instruct the IDE controller 

+  driver to program the IDE controller hardware to the specified modes. This 

+  function can be called only once for a particular device. For a Serial ATA 

+  (SATA) Advanced Host Controller Interface (AHCI) controller, no controller-

+  specific programming may be required.

+

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

+  @param[in] Channel   Zero-based channel number.

+  @param[in] Device    Zero-based device number on the Channel.

+  @param[in] Modes     The modes to set.

+

+  @retval EFI_SUCCESS             The command was accepted without any errors.

+  @retval EFI_INVALID_PARAMETER   Channel is invalid (Channel >= ChannelCount).

+  @retval EFI_INVALID_PARAMETER   Device is invalid.

+  @retval EFI_NOT_READY           Modes cannot be set at this time due to lack of data.

+  @retval EFI_DEVICE_ERROR        Modes cannot be set due to hardware failure.

+                                  The driver entity should not use this device.

 

-  @retval EFI_SUCCESS   Sucess operation.

 **/

 EFI_STATUS

 EFIAPI