modify coding style to pass ecc tool and provide comments that complied with Doxgen.

[mirror_edk2.git] / MdeModulePkg / Bus / Usb / UsbBusDxe / UsbDesc.h

/** @file\r
\r
    Manage Usb Descriptor List\r
\r
Copyright (c) 2007, Intel Corporation\r
All rights reserved. This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution.  The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#ifndef _USB_DESCRIPTOR_H_\r
#define _USB_DESCRIPTOR_H_\r
\r
typedef enum {\r
  USB_MAX_INTERFACE_SETTING  = 8\r
}USB_INTERFACE_SETTING_MAX;\r
\r
//\r
// The RequestType in EFI_USB_DEVICE_REQUEST is composed of\r
// three fields: One bit direction, 2 bit type, and 5 bit\r
// target.\r
//\r
#define USB_REQUEST_TYPE(Dir, Type, Target) \\r
          ((UINT8)((((Dir) == EfiUsbDataIn ? 0x01 : 0) << 7) | (Type) | (Target)))\r
\r
//\r
// A common header for usb standard descriptor.\r
// Each stand descriptor has a length and type.\r
//\r
#pragma pack(1)\r
typedef struct {\r
  UINT8                   Len;\r
  UINT8                   Type;\r
} USB_DESC_HEAD;\r
#pragma pack()\r
\r
\r
//\r
// Each USB device has a device descriptor. Each device may\r
// have several configures. Each configure contains several\r
// interfaces. Each interface may have several settings. Each\r
// setting has several endpoints.\r
//\r
// EFI_USB_..._DESCRIPTOR must be the first member of the\r
// structure.\r
//\r
typedef struct {\r
  EFI_USB_ENDPOINT_DESCRIPTOR   Desc;\r
  UINT8                         Toggle;\r
} USB_ENDPOINT_DESC;\r
\r
typedef struct {\r
  EFI_USB_INTERFACE_DESCRIPTOR  Desc;\r
  USB_ENDPOINT_DESC             **Endpoints;\r
} USB_INTERFACE_SETTING;\r
\r
//\r
// An interface may have several settings. Use a\r
// fixed max number of settings to simplify code.\r
// It should sufice in most environments.\r
//\r
typedef struct {\r
  USB_INTERFACE_SETTING*        Settings[USB_MAX_INTERFACE_SETTING];\r
  UINTN                         NumOfSetting;\r
  UINT8                         ActiveIndex;  // Index of active setting\r
} USB_INTERFACE_DESC;\r
\r
typedef struct {\r
  EFI_USB_CONFIG_DESCRIPTOR     Desc;\r
  USB_INTERFACE_DESC            **Interfaces;\r
} USB_CONFIG_DESC;\r
\r
typedef struct {\r
  EFI_USB_DEVICE_DESCRIPTOR     Desc;\r
  USB_CONFIG_DESC               **Configs;\r
} USB_DEVICE_DESC;\r
\r
/**\r
  USB standard control transfer support routine. This\r
  function is used by USB device. It is possible that\r
  the device's interfaces are still waiting to be\r
  enumerated.\r
\r
  @param  UsbDev                The usb device.\r
  @param  Direction             The direction of data transfer.\r
  @param  Type                  Standard / class specific / vendor specific.\r
  @param  Target                The receiving target.\r
  @param  Request               Which request.\r
  @param  Value                 The wValue parameter of the request.\r
  @param  Index                 The wIndex parameter of the request.\r
  @param  Buf                   The buffer to receive data into / transmit from.\r
  @param  Length                The length of the buffer.\r
\r
  @retval EFI_SUCCESS           The control request is executed.\r
  @retval EFI_DEVICE_ERROR      Failed to execute the control transfer.\r
\r
**/\r
EFI_STATUS\r
UsbCtrlRequest (\r
  IN USB_DEVICE             *UsbDev,\r
  IN EFI_USB_DATA_DIRECTION Direction,\r
  IN UINTN                  Type,\r
  IN UINTN                  Target,\r
  IN UINTN                  Request,\r
  IN UINT16                 Value,\r
  IN UINT16                 Index,\r
  IN OUT VOID               *Buf,\r
  IN UINTN                  Length\r
  );\r
\r
/**\r
  Return the max packet size for endpoint zero. This function\r
  is the first function called to get descriptors during bus\r
  enumeration.\r
\r
  @param  UsbDev                The usb device.\r
\r
  @retval EFI_SUCCESS           The max packet size of endpoint zero is retrieved.\r
  @retval EFI_DEVICE_ERROR      Failed to retrieve it.\r
\r
**/\r
EFI_STATUS\r
UsbGetMaxPacketSize0 (\r
  IN USB_DEVICE           *UsbDev\r
  );\r
\r
/**\r
  Free a device descriptor with its configurations.\r
\r
  @param  DevDesc               The device descriptor.\r
\r
  @return None.\r
\r
**/\r
VOID\r
UsbFreeDevDesc (\r
  IN USB_DEVICE_DESC      *DevDesc\r
  );\r
\r
/**\r
  Retrieve the indexed string for the language. It requires two\r
  steps to get a string, first to get the string's length. Then\r
  the string itself.\r
\r
  @param  UsbDev                The usb device.\r
  @param  StringIndex           The index of the string to retrieve.\r
  @param  LangId                Language ID.\r
\r
  @return The created string descriptor or NULL.\r
\r
**/\r
EFI_USB_STRING_DESCRIPTOR*\r
UsbGetOneString (\r
  IN     USB_DEVICE       *UsbDev,\r
  IN     UINT8            StringIndex,\r
  IN     UINT16           LangId\r
  );\r
\r
/**\r
  Build the whole array of descriptors. This function must\r
  be called after UsbGetMaxPacketSize0 returns the max packet\r
  size correctly for endpoint 0.\r
\r
  @param  UsbDev                The Usb device.\r
\r
  @retval EFI_SUCCESS           The descriptor table is build.\r
  @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the descriptor.\r
\r
**/\r
EFI_STATUS\r
UsbBuildDescTable (\r
  IN USB_DEVICE           *UsbDev\r
  );\r
\r
/**\r
  Set the device's address.\r
\r
  @param  UsbDev                The device to set address to.\r
  @param  Address               The address to set.\r
\r
  @retval EFI_SUCCESS           The device is set to the address.\r
  @retval Others                Failed to set the device address.\r
\r
**/\r
EFI_STATUS\r
UsbSetAddress (\r
  IN USB_DEVICE           *UsbDev,\r
  IN UINT8                Address\r
  );\r
\r
/**\r
  Set the device's configuration. This function changes\r
  the device's internal state. UsbSelectConfig changes\r
  the Usb bus's internal state.\r
\r
  @param  UsbDev                The USB device to set configure to.\r
  @param  ConfigIndex           The configure index to set.\r
\r
  @retval EFI_SUCCESS           The device is configured now.\r
  @retval Others                Failed to set the device configure.\r
\r
**/\r
EFI_STATUS\r
UsbSetConfig (\r
  IN USB_DEVICE           *UsbDev,\r
  IN UINT8                ConfigIndex\r
  );\r
\r
/**\r
  Usb UsbIo interface to clear the feature. This is should\r
  only be used by HUB which is considered a device driver\r
  on top of the UsbIo interface.\r
\r
  @param  UsbIo                 The UsbIo interface.\r
  @param  Target                The target of the transfer: endpoint/device.\r
  @param  Feature               The feature to clear.\r
  @param  Index                 The wIndex parameter.\r
\r
  @retval EFI_SUCCESS           The device feature is cleared.\r
  @retval Others                Failed to clear the feature.\r
\r
**/\r
EFI_STATUS\r
UsbIoClearFeature (\r
  IN  EFI_USB_IO_PROTOCOL *UsbIo,\r
  IN  UINTN               Target,\r
  IN  UINT16              Feature,\r
  IN  UINT16              Index\r
  );\r
#endif\r