1 /* 2 * Copyright (c) 2021-2023 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 #ifdef __cplusplus 257 extern "C" { 258 #endif 259 260 /** 261 * @brief Defines the callback called when the USB interface starts a thread to receive EP0 events, 262 * such as the setup event. 263 * 264 * @param interface Indicates the pointer to the USB interface object. 265 * @param eventMask Indicates the type of the event to be processed. 266 * The event is defined by <b>UsbFnDeviceState</b>. 267 * Each bit of <b>eventMask</b> indicates an event. 268 * For example, if the value of <b>eventMask</b> is <b>0xff</b>, all events are received; 269 * if the value of <b>eventMask</b> is <b>0x01</b>, only the <b>USBFN_STATE_BIND</b> event is received. 270 * @param callback Indicates the callback function called after a request is processed. 271 * It needs to be defined by the application. 272 * @param context Indicates the pointer to the private context data. 273 * 274 * @return Returns <b>0</b> if the operation is successful; returns a negative value 275 * defined in {@link UsbErrorType} otherwise. 276 */ 277 int32_t UsbFnStartRecvInterfaceEvent( 278 struct UsbFnInterface *interface, uint32_t eventMask, UsbFnEventCallback callback, void *context); 279 280 /** 281 * @brief Defines the callback called when the USB interface stops receiving EP0 events. 282 * 283 * @param interface Indicates the pointer to the USB interface object. 284 * 285 * @return Returns <b>0</b> if the operation is successful; returns a negative 286 * value defined in {@link UsbErrorType} otherwise. 287 */ 288 int32_t UsbFnStopRecvInterfaceEvent(struct UsbFnInterface *interface); 289 290 /** 291 * @brief Enables a USB interface. 292 * 293 * This function is mainly used to initialize a request queue and open a pipe. 294 * 295 * @param interface Indicates the pointer to the USB interface object. 296 * 297 * @return Returns a <b>#UsbFnInterfaceHandle</b> containing the USB interface information 298 * if the operation is successful; returns <b>NULL</b> otherwise. 299 */ 300 UsbFnInterfaceHandle UsbFnOpenInterface(struct UsbFnInterface *interface); 301 302 /** 303 * @brief Disables a USB interface. 304 * 305 * This function is mainly used to close a pipe and delete a request queue. 306 * 307 * @param UsbFnInterfaceHandle Indicates the handle of the USB interface object. 308 * 309 * @return Returns <b>0</b> if the operation is successful; returns a negative value 310 * defined in {@link UsbErrorType} otherwise. 311 */ 312 int32_t UsbFnCloseInterface(UsbFnInterfaceHandle handle); 313 314 /** 315 * @brief Obtains USB pipe information based on the specified pipe ID. 316 * 317 * @param interface Indicates the pointer to the USB interface object. 318 * @param pipeId Indicates the pipe ID. The value ranges from 0 to the total number of pipes on the USB interface. 319 * @param info Indicates the pointer to the obtained pipe information. 320 * 321 * @return Returns <b>0</b> if the operation is successful; returns a negative 322 * value defined in {@link UsbErrorType} otherwise. 323 */ 324 int32_t UsbFnGetInterfacePipeInfo(struct UsbFnInterface *interface, uint8_t pipeId, struct UsbFnPipeInfo *info); 325 326 /** 327 * @brief Registers custom attributes for a USB interface. 328 * 329 * In addition to custom attributes, you can use this function to register the callback function 330 * for the request of obtaining and setting custom attributes. 331 * 332 * @param interface Indicates the pointer to the USB interface object. 333 * @param registInfo Indicates the pointer to the attribute information. 334 * 335 * @return Returns <b>0</b> if the operation is successful; returns a negative 336 * value defined in {@link UsbErrorType} otherwise. 337 */ 338 int32_t UsbFnRegistInterfaceProp(const struct UsbFnInterface *interface, const struct UsbFnRegistInfo *registInfo); 339 340 /** 341 * @brief Obtains custom attributes of a USB interface. 342 * 343 * Custom attributes can be any of the following: attributes of device descriptors, such as VID and PID, 344 * attributes of the USB interface defined in the HCS file, and attributes registered 345 * in the code at the application layer. 346 * For example, if <b>name</b> is <b>idVendor</b> when obtaining the VID, the obtained value will be 347 * stored in <b>value</b> as a hex string. 348 * 349 * @param interface Indicates the pointer to the USB interface object. 350 * @param name Indicates the pointer to the attribute name of the string type. 351 * @param value Indicates the pointer to the attribute value of the string type. Except integer data, 352 * which is a string converted from hex data, all the other types of data are strings by default. 353 * 354 * @return Returns <b>0</b> if the operation is successful; returns a negative 355 * value defined in {@link UsbErrorType} otherwise. 356 */ 357 int32_t UsbFnGetInterfaceProp(const struct UsbFnInterface *interface, const char *name, char *value); 358 359 /** 360 * @brief Sets custom attributes of a USB interface. 361 * 362 * Custom attributes can be any of the following: attributes of device descriptors, such as VID and PID, 363 * attributes of the USB interface defined in the HCS file, and attributes registered 364 * in the code at the application layer. 365 * For example, if <b>name</b> is <b>idVendor</b> when setting the VID, the set value will be 366 * stored in <b>value</b> as a hex string. 367 * 368 * @param interface Indicates the pointer to the USB interface object. 369 * @param name Indicates the pointer to the attribute name of the string type. 370 * @param value Indicates the pointer to the attribute value of the string type. Except integer data, 371 * which is a string converted from hex data, all the other types of data are strings by default. 372 * 373 * @return Returns <b>0</b> if the operation is successful; returns a negative 374 * value defined in {@link UsbErrorType} otherwise. 375 */ 376 int32_t UsbFnSetInterfaceProp(const struct UsbFnInterface *interface, const char *name, const char *value); 377 378 #ifdef __cplusplus 379 } 380 #endif 381 382 #endif /* USBFN_INTERFACE_H */ 383