From 2baabe0d4d045f061535213294d1797622f462cb Mon Sep 17 00:00:00 2001 From: klu2 Date: Sun, 28 Sep 2008 06:37:40 +0000 Subject: [PATCH] Synchronize function's comments with EFI 1.1 specification. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6059 6f19259b-4bc3-4df7-8a09-765794883524 --- MdePkg/Include/Protocol/UsbHostController.h | 87 +++++++++++++++------ 1 file changed, 64 insertions(+), 23 deletions(-) diff --git a/MdePkg/Include/Protocol/UsbHostController.h b/MdePkg/Include/Protocol/UsbHostController.h index 6f9a0109b2..fa9c145810 100644 --- a/MdePkg/Include/Protocol/UsbHostController.h +++ b/MdePkg/Include/Protocol/UsbHostController.h @@ -106,7 +106,8 @@ EFI_STATUS transfer endpoint is capable of sending or receiving. @param Request A pointer to the USB device request that will be sent to the USB device. - @param TransferDirection Specifies the data direction for the transfer. + @param TransferDirection Specifies the data direction for the transfer. There are three + values available, EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData. @param Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device. @param DataLength On input, indicates the size, in bytes, of the data buffer specified @@ -145,8 +146,12 @@ EFI_STATUS @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param DeviceAddress Represents the address of the target device on the USB, which is assigned during USB enumeration. - @param EndPointAddress The combination of an endpoint number and an endpoint - direction of the target USB device. + @param EndPointAddress The combination of an endpoint number and an endpoint + direction of the target USB device. Each endpoint address + supports data transfer in one direction except the control + endpoint (whose default endpoint address is 0). It is the + caller’s responsibility to make sure that the EndPointAddress + represents a bulk endpoint. @param MaximumPacketLength Indicates the maximum packet size that the default control transfer endpoint is capable of sending or receiving. @param Data A pointer to the buffer of data that will be transmitted to USB @@ -186,21 +191,32 @@ EFI_STATUS @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param DeviceAddress Represents the address of the target device on the USB, which is assigned during USB enumeration. - @param EndPointAddress The combination of an endpoint number and an endpoint - direction of the target USB device. + @param EndPointAddress The combination of an endpoint number and an endpoint + direction of the target USB device. Each endpoint address + supports data transfer in one direction except the control + endpoint (whose default endpoint address is 0). It is the + caller’s responsibility to make sure that the EndPointAddress + represents a bulk endpoint. @param IsSlowDevice Indicates whether the target device is slow device or full-speed device. @param MaximumPacketLength Indicates the maximum packet size that the default control transfer endpoint is capable of sending or receiving. @param IsNewTransfer If TRUE, an asynchronous interrupt pipe is built between the host - and the target interrupt endpoint. If FALSE, the specified - @param DataToggle A pointer to the data toggle value. + and the target interrupt endpoint. If FALSE, the specified asynchronous + interrupt pipe is canceled. If TRUE, and an interrupt transfer exists + for the target end point, then EFI_INVALID_PARAMETER is returned. + @param DataToggle A pointer to the data toggle value. On input, it is valid when + IsNewTransfer is TRUE, and it indicates the initial data toggle + value the asynchronous interrupt transfer should adopt. On output, + it is valid when IsNewTransfer is FALSE, and it is updated to indicate + the data toggle value of the subsequent asynchronous interrupt transfer. @param PollingInterval Indicates the interval, in milliseconds, that the asynchronous - interrupt transfer is polled. asynchronous interrupt pipe is canceled. + interrupt transfer is polled. @param DataLength Indicates the length of data to be received at the rate specified by PollingInterval from the target asynchronous interrupt - endpoint. - @param CallBackFunction The Callback function. + endpoint. This parameter is only required when IsNewTransfer is TRUE. + @param CallBackFunction The Callback function. This function is called at the rate specified by + PollingInterval. This parameter is only required when IsNewTransfer is TRUE. @param Context The context that is passed to the CallBackFunction. @retval EFI_SUCCESS The asynchronous interrupt transfer request has been successfully @@ -233,8 +249,12 @@ EFI_STATUS @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param DeviceAddress Represents the address of the target device on the USB, which is assigned during USB enumeration. - @param EndPointAddress The combination of an endpoint number and an endpoint - direction of the target USB device. + @param EndPointAddress The combination of an endpoint number and an endpoint + direction of the target USB device. Each endpoint address + supports data transfer in one direction except the control + endpoint (whose default endpoint address is 0). It is the + caller’s responsibility to make sure that the EndPointAddress + represents a bulk endpoint. @param IsSlowDevice Indicates whether the target device is slow device or full-speed device. @param MaximumPacketLength Indicates the maximum packet size that the default control @@ -243,7 +263,10 @@ EFI_STATUS device or received from USB device. asynchronous interrupt pipe is canceled. @param DataLength On input, the size, in bytes, of the data buffer specified by Data. On output, the number of bytes transferred. - @param DataToggle A pointer to the data toggle value. + @param DataToggle A pointer to the data toggle value. On input, it indicates the initial + data toggle value the synchronous interrupt transfer should adopt; + on output, it is updated to indicate the data toggle value of the + subsequent synchronous interrupt transfer. @param TimeOut Indicates the maximum time, in milliseconds, which the transfer is allowed to complete. @param TransferResult A pointer to the detailed result information from the synchronous @@ -277,8 +300,12 @@ EFI_STATUS @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param DeviceAddress Represents the address of the target device on the USB, which is assigned during USB enumeration. - @param EndPointAddress The combination of an endpoint number and an endpoint - direction of the target USB device. + @param EndPointAddress The combination of an endpoint number and an endpoint + direction of the target USB device. Each endpoint address + supports data transfer in one direction except the control + endpoint (whose default endpoint address is 0). It is the + caller’s responsibility to make sure that the EndPointAddress + represents a bulk endpoint. @param MaximumPacketLength Indicates the maximum packet size that the default control transfer endpoint is capable of sending or receiving. @param Data A pointer to the buffer of data that will be transmitted to USB @@ -313,15 +340,23 @@ EFI_STATUS @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param DeviceAddress Represents the address of the target device on the USB, which is assigned during USB enumeration. - @param EndPointAddress The combination of an endpoint number and an endpoint - direction of the target USB device. + @param EndPointAddress The combination of an endpoint number and an endpoint + direction of the target USB device. Each endpoint address + supports data transfer in one direction except the control + endpoint (whose default endpoint address is 0). It is the + caller’s responsibility to make sure that the EndPointAddress + represents a bulk endpoint. @param MaximumPacketLength Indicates the maximum packet size that the default control - transfer endpoint is capable of sending or receiving. + transfer endpoint is capable of sending or receiving. For isochronous + endpoints, this value is used to reserve the bus time in the schedule, + required for the perframe data payloads. The pipe may, on an ongoing basis, + actually use less bandwidth than that reserved. @param Data A pointer to the buffer of data that will be transmitted to USB device or received from USB device. asynchronous interrupt pipe is canceled. @param DataLength Specifies the length, in bytes, of the data to be sent to or received from the USB device. - @param IsochronousCallback The Callback function. + @param IsochronousCallback The Callback function.This function is called if the requested + isochronous transfer is completed. @param Context Data passed to the IsochronousCallback function. This is an optional parameter and may be NULL. @@ -366,7 +401,9 @@ EFI_STATUS @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param PortNumber Specifies the root hub port from which the status is to be retrieved. - This value is zero based. + This value is zero based. For example, if a root hub has two ports, + then the first port is numbered 0, and the second port is + numbered 1. @param PortStatus A pointer to the current port status bits and port status change bits. @retval EFI_SUCCESS The status of the USB root hub port specified by PortNumber @@ -387,7 +424,9 @@ EFI_STATUS @param This A pointer to the EFI_USB_HC_PROTOCOL instance. @param PortNumber Specifies the root hub port from which the status is to be retrieved. - This value is zero based. + This value is zero based. For example, if a root hub has two ports, + then the first port is numbered 0, and the second port is + numbered 1. @param PortFeature Indicates the feature selector associated with the feature set request. @@ -408,8 +447,10 @@ EFI_STATUS Clears a feature for the specified root hub port. @param This A pointer to the EFI_USB_HC_PROTOCOL instance. - @param PortNumber Specifies the root hub port from which the status is to be cleared. - This value is zero based. + @param PortNumber Specifies the root hub port from which the status is to be retrieved. + This value is zero based. For example, if a root hub has two ports, + then the first port is numbered 0, and the second port is + numbered 1. @param PortFeature Indicates the feature selector associated with the feature clear request.