protocol/lufa/LUFA-git/LUFA/Drivers/USB/Core/StdRequestType.h

   1 /*
   2              LUFA Library
   3      Copyright (C) Dean Camera, 2014.
   4
   5   dean [at] fourwalledcubicle [dot] com
   6            www.lufa-lib.org
   7 */
   8
   9 /*
  10   Copyright 2014  Dean Camera (dean [at] fourwalledcubicle [dot] com)
  11
  12   Permission to use, copy, modify, distribute, and sell this
  13   software and its documentation for any purpose is hereby granted
  14   without fee, provided that the above copyright notice appear in
  15   all copies and that both that the copyright notice and this
  16   permission notice and warranty disclaimer appear in supporting
  17   documentation, and that the name of the author not be used in
  18   advertising or publicity pertaining to distribution of the
  19   software without specific, written prior permission.
  20
  21   The author disclaims all warranties with regard to this
  22   software, including all implied warranties of merchantability
  23   and fitness.  In no event shall the author be liable for any
  24   special, indirect or consequential damages or any damages
  25   whatsoever resulting from loss of use, data or profits, whether
  26   in an action of contract, negligence or other tortious action,
  27   arising out of or in connection with the use or performance of
  28   this software.
  29 */
  30
  31 /** \file
  32  *  \brief USB control endpoint request definitions.
  33  *  \copydetails Group_StdRequest
  34  *
  35  *  \note This file should not be included directly. It is automatically included as needed by the USB driver
  36  *        dispatch header located in LUFA/Drivers/USB/USB.h.
  37  */
  38
  39 /** \ingroup Group_USB
  40  *  \defgroup Group_StdRequest Standard USB Requests
  41  *  \brief USB control endpoint request definitions.
  42  *
  43  *  This module contains definitions for the various control request parameters, so that the request
  44  *  details (such as data direction, request recipient, etc.) can be extracted via masking.
  45  *
  46  *  @{
  47  */
  48
  49 #ifndef __STDREQTYPE_H__
  50 #define __STDREQTYPE_H__
  51
  52         /* Includes: */
  53                 #include "../../../Common/Common.h"
  54                 #include "USBMode.h"
  55
  56         /* Enable C linkage for C++ Compilers: */
  57                 #if defined(__cplusplus)
  58                         extern "C" {
  59                 #endif
  60
  61         /* Preprocessor Checks: */
  62                 #if !defined(__INCLUDE_FROM_USB_DRIVER)
  63                         #error Do not include this file directly. Include LUFA/Drivers/USB/USB.h instead.
  64                 #endif
  65
  66         /* Public Interface - May be used in end-application: */
  67                 /* Macros: */
  68                         /** Mask for the request type parameter, to indicate the direction of the request data (Host to Device
  69                          *  or Device to Host). The result of this mask should then be compared to the request direction masks.
  70                          *
  71                          *  \see \c REQDIR_* macros for masks indicating the request data direction.
  72                          */
  73                         #define CONTROL_REQTYPE_DIRECTION  0x80
  74
  75                         /** Mask for the request type parameter, to indicate the type of request (Device, Class or Vendor
  76                          *  Specific). The result of this mask should then be compared to the request type masks.
  77                          *
  78                          *  \see \c REQTYPE_* macros for masks indicating the request type.
  79                          */
  80                         #define CONTROL_REQTYPE_TYPE       0x60
  81
  82                         /** Mask for the request type parameter, to indicate the recipient of the request (Device, Interface
  83                          *  Endpoint or Other). The result of this mask should then be compared to the request recipient
  84                          *  masks.
  85                          *
  86                          *  \see \c REQREC_* macros for masks indicating the request recipient.
  87                          */
  88                         #define CONTROL_REQTYPE_RECIPIENT  0x1F
  89
  90                         /** \name Control Request Data Direction Masks */
  91                         //@{
  92                         /** Request data direction mask, indicating that the request data will flow from host to device.
  93                          *
  94                          *  \see \ref CONTROL_REQTYPE_DIRECTION macro.
  95                          */
  96                         #define REQDIR_HOSTTODEVICE        (0 << 7)
  97
  98                         /** Request data direction mask, indicating that the request data will flow from device to host.
  99                          *
 100                          *  \see \ref CONTROL_REQTYPE_DIRECTION macro.
 101                          */
 102                         #define REQDIR_DEVICETOHOST        (1 << 7)
 103                         //@}
 104
 105                         /** \name Control Request Type Masks */
 106                         //@{
 107                         /** Request type mask, indicating that the request is a standard request.
 108                          *
 109                          *  \see \ref CONTROL_REQTYPE_TYPE macro.
 110                          */
 111                         #define REQTYPE_STANDARD           (0 << 5)
 112
 113                         /** Request type mask, indicating that the request is a class-specific request.
 114                          *
 115                          *  \see \ref CONTROL_REQTYPE_TYPE macro.
 116                          */
 117                         #define REQTYPE_CLASS              (1 << 5)
 118
 119                         /** Request type mask, indicating that the request is a vendor specific request.
 120                          *
 121                          *  \see \ref CONTROL_REQTYPE_TYPE macro.
 122                          */
 123                         #define REQTYPE_VENDOR             (2 << 5)
 124                         //@}
 125
 126                         /** \name Control Request Recipient Masks */
 127                         //@{
 128                         /** Request recipient mask, indicating that the request is to be issued to the device as a whole.
 129                          *
 130                          *  \see \ref CONTROL_REQTYPE_RECIPIENT macro.
 131                          */
 132                         #define REQREC_DEVICE              (0 << 0)
 133
 134                         /** Request recipient mask, indicating that the request is to be issued to an interface in the
 135                          *  currently selected configuration.
 136                          *
 137                          *  \see \ref CONTROL_REQTYPE_RECIPIENT macro.
 138                          */
 139                         #define REQREC_INTERFACE           (1 << 0)
 140
 141                         /** Request recipient mask, indicating that the request is to be issued to an endpoint in the
 142                          *  currently selected configuration.
 143                          *
 144                          *  \see \ref CONTROL_REQTYPE_RECIPIENT macro.
 145                          */
 146                         #define REQREC_ENDPOINT            (2 << 0)
 147
 148                         /** Request recipient mask, indicating that the request is to be issued to an unspecified element
 149                          *  in the currently selected configuration.
 150                          *
 151                          *  \see \ref CONTROL_REQTYPE_RECIPIENT macro.
 152                          */
 153                         #define REQREC_OTHER               (3 << 0)
 154                         //@}
 155
 156                 /* Type Defines: */
 157                         /** \brief Standard USB Control Request
 158                          *
 159                          *  Type define for a standard USB control request.
 160                          *
 161                          *  \see The USB 2.0 specification for more information on standard control requests.
 162                          */
 163                         typedef struct
 164                         {
 165                                 uint8_t  bmRequestType; /**< Type of the request. */
 166                                 uint8_t  bRequest; /**< Request command code. */
 167                                 uint16_t wValue; /**< wValue parameter of the request. */
 168                                 uint16_t wIndex; /**< wIndex parameter of the request. */
 169                                 uint16_t wLength; /**< Length of the data to transfer in bytes. */
 170                         } ATTR_PACKED USB_Request_Header_t;
 171
 172                 /* Enums: */
 173                         /** Enumeration for the various standard request commands. These commands are applicable when the
 174                          *  request type is \ref REQTYPE_STANDARD (with the exception of \ref REQ_GetDescriptor, which is always
 175                          *  handled regardless of the request type value).
 176                          *
 177                          *  \see Chapter 9 of the USB 2.0 Specification.
 178                          */
 179                         enum USB_Control_Request_t
 180                         {
 181                                 REQ_GetStatus           = 0, /**< Implemented in the library for device and endpoint recipients. Passed
 182                                                               *   to the user application for other recipients via the
 183                                                               *   \ref EVENT_USB_Device_ControlRequest() event when received in
 184                                                               *   device mode. */
 185                                 REQ_ClearFeature        = 1, /**< Implemented in the library for device and endpoint recipients. Passed
 186                                                               *   to the user application for other recipients via the
 187                                                               *   \ref EVENT_USB_Device_ControlRequest() event when received in
 188                                                               *   device mode. */
 189                                 REQ_SetFeature          = 3, /**< Implemented in the library for device and endpoint recipients. Passed
 190                                                               *   to the user application for other recipients via the
 191                                                               *   \ref EVENT_USB_Device_ControlRequest() event when received in
 192                                                               *   device mode. */
 193                                 REQ_SetAddress          = 5, /**< Implemented in the library for the device recipient. Passed
 194                                                               *   to the user application for other recipients via the
 195                                                               *   \ref EVENT_USB_Device_ControlRequest() event when received in
 196                                                               *   device mode. */
 197                                 REQ_GetDescriptor       = 6, /**< Implemented in the library for device and interface recipients. Passed to the
 198                                                               *   user application for other recipients via the
 199                                                               *   \ref EVENT_USB_Device_ControlRequest() event when received in
 200                                                               *   device mode. */
 201                                 REQ_SetDescriptor       = 7, /**< Not implemented in the library, passed to the user application
 202                                                               *   via the \ref EVENT_USB_Device_ControlRequest() event when received in
 203                                                               *   device mode. */
 204                                 REQ_GetConfiguration    = 8, /**< Implemented in the library for the device recipient. Passed
 205                                                               *   to the user application for other recipients via the
 206                                                               *   \ref EVENT_USB_Device_ControlRequest() event when received in
 207                                                               *   device mode. */
 208                                 REQ_SetConfiguration    = 9, /**< Implemented in the library for the device recipient. Passed
 209                                                               *   to the user application for other recipients via the
 210                                                               *   \ref EVENT_USB_Device_ControlRequest() event when received in
 211                                                               *   device mode. */
 212                                 REQ_GetInterface        = 10, /**< Not implemented in the library, passed to the user application
 213                                                               *   via the \ref EVENT_USB_Device_ControlRequest() event when received in
 214                                                               *   device mode. */
 215                                 REQ_SetInterface        = 11, /**< Not implemented in the library, passed to the user application
 216                                                               *   via the \ref EVENT_USB_Device_ControlRequest() event when received in
 217                                                               *   device mode. */
 218                                 REQ_SynchFrame          = 12, /**< Not implemented in the library, passed to the user application
 219                                                               *   via the \ref EVENT_USB_Device_ControlRequest() event when received in
 220                                                               *   device mode. */
 221                         };
 222
 223                         /** Feature Selector values for Set Feature and Clear Feature standard control requests directed to the device, interface
 224                          *  and endpoint recipients.
 225                          */
 226                         enum USB_Feature_Selectors_t
 227                         {
 228                                 FEATURE_SEL_EndpointHalt       = 0x00, /**< Feature selector for Clear Feature or Set Feature commands. When
 229                                                                         *   used in a Set Feature or Clear Feature request this indicates that an
 230                                                                         *   endpoint (whose address is given elsewhere in the request) should have
 231                                                                         *   its stall condition changed.
 232                                                                         */
 233                                 FEATURE_SEL_DeviceRemoteWakeup = 0x01, /**< Feature selector for Device level Remote Wakeup enable set or clear.
 234                                                                     *   This feature can be controlled by the host on devices which indicate
 235                                                                     *   remote wakeup support in their descriptors to selectively disable or
 236                                                                     *   enable remote wakeup.
 237                                                                     */
 238                                 FEATURE_SEL_TestMode           = 0x02, /**< Feature selector for Test Mode features, used to test the USB controller
 239                                                                     *   to check for incorrect operation.
 240                                                                     */
 241                         };
 242
 243         /* Private Interface - For use in library only: */
 244                 #if !defined(__DOXYGEN__)
 245                         /* Macros: */
 246                                 #define FEATURE_SELFPOWERED_ENABLED     (1 << 0)
 247                                 #define FEATURE_REMOTE_WAKEUP_ENABLED   (1 << 1)
 248                 #endif
 249
 250         /* Disable C linkage for C++ Compilers: */
 251                 #if defined(__cplusplus)
 252                         }
 253                 #endif
 254
 255 #endif
 256
 257 /** @} */
 258