+ Returns the information about the optimum modes for the specified IDE device.\r
+\r
+ This function is used by the driver entity to obtain the optimum ATA modes for\r
+ a specific device. The IDE controller driver takes into account the following \r
+ while calculating the mode:\r
+ - The IdentifyData inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData()\r
+ - The BadModes inputs to EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode()\r
+\r
+ The driver entity is required to call EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() \r
+ for all the devices that belong to an enumeration group before calling \r
+ EFI_IDE_CONTROLLER_INIT_PROTOCOL.CalculateMode() for any device in the same group. \r
+ \r
+ The IDE controller driver will use controller- and possibly platform-specific \r
+ algorithms to arrive at SupportedModes. The IDE controller may base its \r
+ decision on user preferences and other considerations as well. This function \r
+ may be called multiple times because the driver entity may renegotiate the mode \r
+ with the IDE controller driver using EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode().\r
+ \r
+ The driver entity may collect timing information for various devices in any \r
+ order. The driver entity is responsible for making sure that all the dependencies\r
+ are satisfied. For example, the SupportedModes information for device A that \r
+ was previously returned may become stale after a call to \r
+ EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyMode() for device B.\r
+ \r
+ The buffer SupportedModes is allocated by the callee because the caller does \r
+ not necessarily know the size of the buffer. The type EFI_ATA_COLLECTIVE_MODE \r
+ is defined in a way that allows for future extensibility and can be of variable \r
+ length. This memory pool should be deallocated by the caller when it is no \r
+ longer necessary. \r
+ \r
+ The IDE controller driver for a Serial ATA (SATA) controller can use this \r
+ member function to force a lower speed (first-generation [Gen1] speeds on a \r
+ second-generation [Gen2]-capable hardware). The IDE controller driver can \r
+ also allow the driver entity to stay with the speed that has been negotiated \r
+ by the physical layer.\r
+ \r
+ @param[in] This The pointer to the EFI_IDE_CONTROLLER_INIT_PROTOCOL instance.\r
+ @param[in] Channel A zero-based channel number.\r
+ @param[in] Device A zero-based device number on the Channel.\r
+ @param[out] SupportedModes The optimum modes for the device.\r
+\r
+ @retval EFI_SUCCESS SupportedModes was returned.\r
+ @retval EFI_INVALID_PARAMETER Channel is invalid (Channel >= ChannelCount).\r
+ @retval EFI_INVALID_PARAMETER Device is invalid. \r
+ @retval EFI_INVALID_PARAMETER SupportedModes is NULL.\r
+ @retval EFI_NOT_READY Modes cannot be calculated due to a lack of \r
+ data. This error may happen if \r
+ EFI_IDE_CONTROLLER_INIT_PROTOCOL.SubmitData() \r
+ and EFI_IDE_CONTROLLER_INIT_PROTOCOL.DisqualifyData() \r
+ were not called for at least one drive in the \r
+ same enumeration group.\r