+ 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