X-Git-Url: https://git.proxmox.com/?a=blobdiff_plain;ds=sidebyside;f=MdeModulePkg%2FBus%2FUsb%2FUsbBusDxe%2FUsbDesc.h;h=dd7868bc1d40cd5de12cc7c8eb327ffed808b983;hb=8616fc4c134d866cb6298faaa5d2dd17242dae9c;hp=14f3c7feb0474b0b348feb86031d0847d163426e;hpb=78f64f281ae77848694035bd878caffdd19c1f59;p=mirror_edk2.git

diff --git a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h
index 14f3c7feb0..dd7868bc1d 100644
--- a/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h
+++ b/MdeModulePkg/Bus/Usb/UsbBusDxe/UsbDesc.h
@@ -1,5 +1,7 @@
 /** @file
 
+    Manage Usb Descriptor List
+
 Copyright (c) 2007, Intel Corporation
 All rights reserved. This program and the accompanying materials
 are licensed and made available under the terms and conditions of the BSD License
@@ -9,25 +11,14 @@ http://opensource.org/licenses/bsd-license.php
 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
-  Module Name:
-
-    UsbDesc.h
-
-  Abstract:
-
-    Manage Usb Descriptor List
-
-  Revision History
-
-
 **/
 
 #ifndef _USB_DESCRIPTOR_H_
 #define _USB_DESCRIPTOR_H_
 
-enum {
+typedef enum {
   USB_MAX_INTERFACE_SETTING  = 8
-};
+}USB_INTERFACE_SETTING_MAX;
 
 //
 // The RequestType in EFI_USB_DEVICE_REQUEST is composed of
@@ -89,6 +80,26 @@ typedef struct {
   USB_CONFIG_DESC               **Configs;
 } USB_DEVICE_DESC;
 
+/**
+  USB standard control transfer support routine. This
+  function is used by USB device. It is possible that
+  the device's interfaces are still waiting to be
+  enumerated.
+
+  @param  UsbDev                The usb device.
+  @param  Direction             The direction of data transfer.
+  @param  Type                  Standard / class specific / vendor specific.
+  @param  Target                The receiving target.
+  @param  Request               Which request.
+  @param  Value                 The wValue parameter of the request.
+  @param  Index                 The wIndex parameter of the request.
+  @param  Buf                   The buffer to receive data into / transmit from.
+  @param  Length                The length of the buffer.
+
+  @retval EFI_SUCCESS           The control request is executed.
+  @retval EFI_DEVICE_ERROR      Failed to execute the control transfer.
+
+**/
 EFI_STATUS
 UsbCtrlRequest (
   IN USB_DEVICE             *UsbDev,
@@ -102,16 +113,47 @@ UsbCtrlRequest (
   IN UINTN                  Length
   );
 
+/**
+  Return the max packet size for endpoint zero. This function
+  is the first function called to get descriptors during bus
+  enumeration.
+
+  @param  UsbDev                The usb device.
+
+  @retval EFI_SUCCESS           The max packet size of endpoint zero is retrieved.
+  @retval EFI_DEVICE_ERROR      Failed to retrieve it.
+
+**/
 EFI_STATUS
 UsbGetMaxPacketSize0 (
   IN USB_DEVICE           *UsbDev
   );
 
+/**
+  Free a device descriptor with its configurations.
+
+  @param  DevDesc               The device descriptor.
+
+  @return None.
+
+**/
 VOID
 UsbFreeDevDesc (
   IN USB_DEVICE_DESC      *DevDesc
   );
 
+/**
+  Retrieve the indexed string for the language. It requires two
+  steps to get a string, first to get the string's length. Then
+  the string itself.
+
+  @param  UsbDev                The usb device.
+  @param  StringIndex           The index of the string to retrieve.
+  @param  LangId                Language ID.
+
+  @return The created string descriptor or NULL.
+
+**/
 EFI_USB_STRING_DESCRIPTOR*
 UsbGetOneString (
   IN     USB_DEVICE       *UsbDev,
@@ -119,23 +161,70 @@ UsbGetOneString (
   IN     UINT16           LangId
   );
 
+/**
+  Build the whole array of descriptors. This function must
+  be called after UsbGetMaxPacketSize0 returns the max packet
+  size correctly for endpoint 0.
+
+  @param  UsbDev                The Usb device.
+
+  @retval EFI_SUCCESS           The descriptor table is build.
+  @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the descriptor.
+
+**/
 EFI_STATUS
 UsbBuildDescTable (
   IN USB_DEVICE           *UsbDev
   );
 
+/**
+  Set the device's address.
+
+  @param  UsbDev                The device to set address to.
+  @param  Address               The address to set.
+
+  @retval EFI_SUCCESS           The device is set to the address.
+  @retval Others                Failed to set the device address.
+
+**/
 EFI_STATUS
 UsbSetAddress (
   IN USB_DEVICE           *UsbDev,
   IN UINT8                Address
   );
 
+/**
+  Set the device's configuration. This function changes
+  the device's internal state. UsbSelectConfig changes
+  the Usb bus's internal state.
+
+  @param  UsbDev                The USB device to set configure to.
+  @param  ConfigIndex           The configure index to set.
+
+  @retval EFI_SUCCESS           The device is configured now.
+  @retval Others                Failed to set the device configure.
+
+**/
 EFI_STATUS
 UsbSetConfig (
   IN USB_DEVICE           *UsbDev,
   IN UINT8                ConfigIndex
   );
 
+/**
+  Usb UsbIo interface to clear the feature. This is should
+  only be used by HUB which is considered a device driver
+  on top of the UsbIo interface.
+
+  @param  UsbIo                 The UsbIo interface.
+  @param  Target                The target of the transfer: endpoint/device.
+  @param  Feature               The feature to clear.
+  @param  Index                 The wIndex parameter.
+
+  @retval EFI_SUCCESS           The device feature is cleared.
+  @retval Others                Failed to clear the feature.
+
+**/
 EFI_STATUS
 UsbIoClearFeature (
   IN  EFI_USB_IO_PROTOCOL *UsbIo,