1 /* 2 * Copyright (c) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @file usbfn_interface.h 18 * 19 * @brief Declares USB interface-specific definitions. 20 * 21 * @since 1.0 22 * @version 1.0 23 */ 24 25 #ifndef USBFN_INTERFACE_H 26 #define USBFN_INTERFACE_H 27 28 #include "usb_object.h" 29 #include "usbfn_request.h" 30 31 /** 32 * @brief Defines USB interfaces of the unspecified class. 33 */ 34 #define USB_INTERFACE_CLASS_UNSPEC 0x00 35 36 /** 37 * @brief Defines USB interfaces of the Audio class. 38 */ 39 #define USB_INTERFACE_CLASS_AUDIO 0x01 40 41 /** 42 * @brief Defines USB interfaces of the Communication Device Class (CDC). 43 */ 44 #define USB_INTERFACE_CLASS_CDC 0x02 45 46 /** 47 * @brief Defines USB interfaces of the Human Interface Device (HID) class. 48 */ 49 #define USB_INTERFACE_CLASS_HID 0x03 50 51 /** 52 * @brief Defines USB interfaces of the Physical class. 53 */ 54 #define USB_INTERFACE_CLASS_PHYSICAL 0x05 55 56 /** 57 * @brief Defines USB interfaces of the Image class. 58 */ 59 #define USB_INTERFACE_CLASS_IMAGE 0x06 60 61 /** 62 * @brief Defines USB interfaces of the Printer class. 63 */ 64 #define USB_INTERFACE_CLASS_PRINTER 0x07 65 66 /** 67 * @brief Defines USB interfaces of the Mass Storage (MSD) class. 68 */ 69 #define USB_INTERFACE_CLASS_MASS_STORAGE 0x08 70 71 /** 72 * @brief Defines USB interfaces of the Hub class. 73 */ 74 #define USB_INTERFACE_CLASS_HUB 0x09 75 76 /** 77 * @brief Defines USB interfaces of the CDC-Data class. 78 */ 79 #define USB_INTERFACE_CLASS_CDC_DATA 0x0a 80 81 /** 82 * @brief Defines USB interfaces of the Smart Card class. 83 */ 84 #define USB_INTERFACE_CLASS_SMARTCARD 0x0b 85 86 /** 87 * @brief Defines USB interfaces of the Firmware Upgrade class. 88 */ 89 #define USB_INTERFACE_CLASS_FIRM_UPD 0x0c 90 91 /** 92 * @brief Defines USB interfaces of the Content Security class. 93 */ 94 #define USB_INTERFACE_CLASS_SECURITY 0x0d 95 96 /** 97 * @brief Defines USB interfaces of the Video class. 98 */ 99 #define USB_INTERFACE_CLASS_VIDEO 0x0e 100 101 /** 102 * @brief Defines USB interfaces of the Diagnostic Device class. 103 */ 104 #define USB_INTERFACE_CLASS_DIAGNOSTIC 0xdc 105 106 /** 107 * @brief Defines USB interfaces of the Wireless Controller class. 108 */ 109 #define USB_INTERFACE_CLASS_WIRELESS 0xe0 110 111 /** 112 * @brief Defines USB interfaces of the Miscellaneous class. 113 */ 114 #define USB_INTERFACE_CLASS_IAD 0xef 115 116 /** 117 * @brief Defines USB interfaces of the Application Specific class. 118 */ 119 #define USB_INTERFACE_CLASS_APP_SPEC 0xfe 120 121 /** 122 * @brief Defines USB interfaces of the Vendor Specific class. 123 */ 124 #define USB_INTERFACE_CLASS_VENDOR 0xff 125 126 /** 127 * @brief Defines the USB device event status. 128 */ 129 typedef enum { 130 /** USB binding event */ 131 USBFN_STATE_BIND, 132 /** USB unbinding event */ 133 USBFN_STATE_UNBIND, 134 /** USB enabling event */ 135 USBFN_STATE_ENABLE, 136 /** USB disabling event */ 137 USBFN_STATE_DISABLE, 138 /** USB connection setup event */ 139 USBFN_STATE_SETUP, 140 /** USB suspending event */ 141 USBFN_STATE_SUSPEND, 142 /** USB resuming event */ 143 USBFN_STATE_RESUME, 144 } UsbFnDeviceState; 145 146 /** 147 * @brief Defines structure parameters for the USB interface request. 148 */ 149 struct UsbFnCtrlRequest { 150 /** Request type */ 151 uint8_t reqType; 152 /** Specific request */ 153 uint8_t request; 154 /** Request data value */ 155 uint16_t value; 156 /** Request index value */ 157 uint16_t index; 158 /** 159 * Number of bytes in the data communication phase, which must be less than the 160 * value of <b>bMaxPacketSize0</b> defined in the device descriptor 161 */ 162 uint16_t length; 163 } __attribute__((packed)); 164 165 /** 166 * @brief Defines the structure of the events received by the USB interface. 167 */ 168 struct UsbFnEvent { 169 /** Pointer to the received parameters of the control request */ 170 struct UsbFnCtrlRequest *setup; 171 UsbFnDeviceState type; 172 void *context; 173 }; 174 175 /** 176 * @brief Defines the USB interface information. 177 */ 178 struct UsbFnInterfaceInfo { 179 /** Interface index */ 180 uint8_t index; 181 /** Number of pipes */ 182 uint8_t numPipes; 183 /** Interface class */ 184 uint8_t interfaceClass; 185 /** Interface subclass */ 186 uint8_t subclass; 187 /** Interface protocol */ 188 uint8_t protocol; 189 /** Interface configuration index */ 190 uint8_t configIndex; 191 }; 192 193 /** 194 * @brief Defines USB interface objects. 195 */ 196 struct UsbFnInterface { 197 /** Pointer to the USB object */ 198 const struct UsbObject *object; 199 /** USB interface information */ 200 struct UsbFnInterfaceInfo info; 201 }; 202 203 /** 204 * @brief Defines the USB pipe information. 205 */ 206 struct UsbFnPipeInfo { 207 /** Pipe ID */ 208 uint8_t id; 209 /** Pipe type */ 210 UsbPipeType type; 211 /** Pipe direction */ 212 UsbPipeDirection dir; 213 /** Maximum size of data packets that can be sent or received over the pipe */ 214 uint16_t maxPacketSize; 215 /** Data transmission interval of the pipe */ 216 uint8_t interval; 217 }; 218 219 /** 220 * @brief Defines callback called when endpoint 0 receives a control event. 221 * 222 * This function needs to be defined by the function driver. 223 * 224 * @param event Indicates the pointer to the event information, including the event type and request. 225 */ 226 typedef void (*UsbFnEventCallback)(struct UsbFnEvent *event); 227 228 /** 229 * @brief Defines the callback called when the function interface obtains or sets custom attributes. 230 * 231 * This function needs to be defined by the function driver. 232 * 233 * @param interface Indicates the pointer to the USB interface object. 234 * @param name Indicates the pointer to the attribute name of the string type. 235 * @param value Indicates the pointer to the attribute value of the string type. 236 * 237 * @return Returns <b>0</b> if the operation is successful; 238 * returns a negative value defined in {@link UsbErrorType} otherwise. 239 */ 240 typedef int32_t (*UsbFnPropCallback)(const struct UsbFnInterface *intf, const char *name, const char *value); 241 242 /** 243 * @brief Defines custom attribute information. 244 */ 245 struct UsbFnRegistInfo { 246 /** Pointer to the attribute name */ 247 const char *name; 248 /** Pointer to the attribute value */ 249 const char *value; 250 /** Pointer to the callback for the request of obtaining custom attributes */ 251 UsbFnPropCallback getProp; 252 /** Pointer to the callback for the request of setting custom attributes */ 253 UsbFnPropCallback setProp; 254 }; 255 256 /** 257 * @brief Defines the callback called when the USB interface starts a thread to receive EP0 events, 258 * such as the setup event. 259 * 260 * @param interface Indicates the pointer to the USB interface object. 261 * @param eventMask Indicates the type of the event to be processed. 262 * The event is defined by <b>UsbFnDeviceState</b>. 263 * Each bit of <b>eventMask</b> indicates an event. 264 * For example, if the value of <b>eventMask</b> is <b>0xff</b>, all events are received; 265 * if the value of <b>eventMask</b> is <b>0x01</b>, only the <b>USBFN_STATE_BIND</b> event is received. 266 * @param callback Indicates the callback function called after a request is processed. 267 * It needs to be defined by the application. 268 * @param context Indicates the pointer to the private context data. 269 * 270 * @return Returns <b>0</b> if the operation is successful; returns a negative value 271 * defined in {@link UsbErrorType} otherwise. 272 */ 273 int32_t UsbFnStartRecvInterfaceEvent(struct UsbFnInterface *interface, uint32_t eventMask, 274 UsbFnEventCallback callback, void *context); 275 276 /** 277 * @brief Defines the callback called when the USB interface stops receiving EP0 events. 278 * 279 * @param interface Indicates the pointer to the USB interface object. 280 * 281 * @return Returns <b>0</b> if the operation is successful; returns a negative 282 * value defined in {@link UsbErrorType} otherwise. 283 */ 284 int32_t UsbFnStopRecvInterfaceEvent(struct UsbFnInterface *interface); 285 286 /** 287 * @brief Enables a USB interface. 288 * 289 * This function is mainly used to initialize a request queue and open a pipe. 290 * 291 * @param interface Indicates the pointer to the USB interface object. 292 * 293 * @return Returns a <b>#UsbFnInterfaceHandle</b> containing the USB interface information 294 * if the operation is successful; returns <b>NULL</b> otherwise. 295 */ 296 UsbFnInterfaceHandle UsbFnOpenInterface(struct UsbFnInterface *interface); 297 298 /** 299 * @brief Disables a USB interface. 300 * 301 * This function is mainly used to close a pipe and delete a request queue. 302 * 303 * @param UsbFnInterfaceHandle Indicates the handle of the USB interface object. 304 * 305 * @return Returns <b>0</b> if the operation is successful; returns a negative value 306 * defined in {@link UsbErrorType} otherwise. 307 */ 308 int32_t UsbFnCloseInterface(UsbFnInterfaceHandle handle); 309 310 /** 311 * @brief Obtains USB pipe information based on the specified pipe ID. 312 * 313 * @param interface Indicates the pointer to the USB interface object. 314 * @param pipeId Indicates the pipe ID. The value ranges from 0 to the total number of pipes on the USB interface. 315 * @param info Indicates the pointer to the obtained pipe information. 316 * 317 * @return Returns <b>0</b> if the operation is successful; returns a negative 318 * value defined in {@link UsbErrorType} otherwise. 319 */ 320 int32_t UsbFnGetInterfacePipeInfo(struct UsbFnInterface *interface, uint8_t pipeId, struct UsbFnPipeInfo *info); 321 322 /** 323 * @brief Registers custom attributes for a USB interface. 324 * 325 * In addition to custom attributes, you can use this function to register the callback function 326 * for the request of obtaining and setting custom attributes. 327 * 328 * @param interface Indicates the pointer to the USB interface object. 329 * @param registInfo Indicates the pointer to the attribute information. 330 * 331 * @return Returns <b>0</b> if the operation is successful; returns a negative 332 * value defined in {@link UsbErrorType} otherwise. 333 */ 334 int32_t UsbFnRegistInterfaceProp(const struct UsbFnInterface *interface, 335 const struct UsbFnRegistInfo *registInfo); 336 337 /** 338 * @brief Obtains custom attributes of a USB interface. 339 * 340 * Custom attributes can be any of the following: attributes of device descriptors, such as VID and PID, 341 * attributes of the USB interface defined in the HCS file, and attributes registered 342 * in the code at the application layer. 343 * For example, if <b>name</b> is <b>idVendor</b> when obtaining the VID, the obtained value will be 344 * stored in <b>value</b> as a hex string. 345 * 346 * @param interface Indicates the pointer to the USB interface object. 347 * @param name Indicates the pointer to the attribute name of the string type. 348 * @param value Indicates the pointer to the attribute value of the string type. Except integer data, 349 * which is a string converted from hex data, all the other types of data are strings by default. 350 * 351 * @return Returns <b>0</b> if the operation is successful; returns a negative 352 * value defined in {@link UsbErrorType} otherwise. 353 */ 354 int32_t UsbFnGetInterfaceProp(const struct UsbFnInterface *interface, 355 const char *name, char *value); 356 357 /** 358 * @brief Sets custom attributes of a USB interface. 359 * 360 * Custom attributes can be any of the following: attributes of device descriptors, such as VID and PID, 361 * attributes of the USB interface defined in the HCS file, and attributes registered 362 * in the code at the application layer. 363 * For example, if <b>name</b> is <b>idVendor</b> when setting the VID, the set value will be 364 * stored in <b>value</b> as a hex string. 365 * 366 * @param interface Indicates the pointer to the USB interface object. 367 * @param name Indicates the pointer to the attribute name of the string type. 368 * @param value Indicates the pointer to the attribute value of the string type. Except integer data, 369 * which is a string converted from hex data, all the other types of data are strings by default. 370 * 371 * @return Returns <b>0</b> if the operation is successful; returns a negative 372 * value defined in {@link UsbErrorType} otherwise. 373 */ 374 int32_t UsbFnSetInterfaceProp(const struct UsbFnInterface *interface, 375 const char *name, const char *value); 376 377 #endif /* USBFN_INTERFACE_H */ 378