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_device.h 18 * 19 * @brief Declares the APIs for managing USB devices. 20 * 21 * @since 1.0 22 * @version 1.0 23 */ 24 25 #ifndef USBFN_DEVICE_H 26 #define USBFN_DEVICE_H 27 28 #include "device_resource_if.h" 29 #include "usb_ddk.h" 30 #include "usb_object.h" 31 #include "usbfn_interface.h" 32 33 /** 34 * @brief Defines a USB device object, which is obtained when a device is created. 35 * 36 * <b>UsbFnDevice</b> corresponds to the device object in the USB specifications. 37 * Wherein, <b>object</b> is the identifier of the device, 38 * <b>numInterfaces</b>indicates the number of interfaces. 39 */ 40 struct UsbFnDevice { 41 /** USB device object */ 42 struct UsbObject object; 43 /** Number of interfaces */ 44 uint8_t numInterfaces; 45 }; 46 47 /** 48 * @brief Defines the descriptor type. 49 * 50 * The descriptor type can be defined in the HCS or the driver code. 51 */ 52 typedef enum { 53 /** Descriptor defined in the HCS */ 54 USBFN_DESC_DATA_TYPE_PROP, 55 /** Descriptor defined in the driver */ 56 USBFN_DESC_DATA_TYPE_DESC, 57 } UsbFnDescDataType; 58 59 /** 60 * @brief Defines a USB string. 61 */ 62 struct UsbString { 63 /** String ID */ 64 uint8_t id; 65 /** String encoded in UTF-8 format */ 66 const char *s; 67 }; 68 69 /** 70 * @brief Defines a USB string in a specific language. 71 * 72 * 73 * @see http://www.usb.org/developers/docs/USB_LANGIDs.pdf 74 */ 75 struct UsbFnStrings { 76 /** Language of USB strings, for example, 0x0409 for en-us */ 77 uint16_t language; 78 /** Pointer to USB strings */ 79 struct UsbString *strings; 80 }; 81 82 /** 83 * @brief Defines a USB device. 84 * 85 * The <b>UsbFnFunction</b> structure contains multiple strings and descriptors. 86 * It is used to describe a functional device, for example, a serial port or network adapter. 87 */ 88 struct UsbFnFunction { 89 /** Pointer to the function driver name: 90 * Naming format: f_generic.x acm.x ecm.x 91 * Use the symbol dot (.) as the separator. <b>f_generic</b> is the common driver 92 * capability provided by this API, 93 * whereas <b>acm</b> or <b>ecm</b> is the function drive capability provided by the kernel. 94 * A value does not need to be assigned to the descriptor. 95 * You can simply use <b>UsbFnCreateDevice</b> to create a device. 96 */ 97 bool enable; 98 const char *funcName; 99 /** Double pointer to USB strings in a specified language */ 100 struct UsbFnStrings **strings; 101 /** Double pointer to Full-Speed descriptors */ 102 struct UsbDescriptorHeader **fsDescriptors; 103 /** Double pointer to High-Speed descriptors */ 104 struct UsbDescriptorHeader **hsDescriptors; 105 /** Double pointer to SuperSpeed descriptors */ 106 struct UsbDescriptorHeader **ssDescriptors; 107 /** Double pointer to SuperSpeed Plus descriptors */ 108 struct UsbDescriptorHeader **sspDescriptors; 109 }; 110 111 /** 112 * @brief Defines a USB configuration descriptor. 113 */ 114 struct UsbFnConfiguration { 115 /** Configuration ID */ 116 uint8_t configurationValue; 117 /** Configuration string index */ 118 uint8_t iConfiguration; 119 /** Configuration attributes */ 120 uint8_t attributes; 121 /** Maximum current */ 122 uint16_t maxPower; 123 /** Double pointer to USB devices */ 124 struct UsbFnFunction **functions; 125 }; 126 127 /** 128 * @brief Defines a USB device descriptor. 129 */ 130 struct UsbFnDeviceDesc { 131 /** Pointer to the standard USB device descriptor */ 132 struct UsbDeviceDescriptor *deviceDesc; 133 /** Double pointer to USB strings in a specified language */ 134 struct UsbFnStrings **deviceStrings; 135 /** Double pointer to USB configuration descriptors */ 136 struct UsbFnConfiguration **configs; 137 }; 138 139 /** 140 * @brief Defines the descriptor data of USB devices. 141 */ 142 struct UsbFnDescriptorData { 143 union { 144 /** Pointer to device resource node attributes */ 145 const struct DeviceResourceNode *property; 146 /** Pointer to the USB device descriptor */ 147 struct UsbFnDeviceDesc *descriptor; 148 }; 149 /** Descriptor type */ 150 UsbFnDescDataType type; 151 uint8_t functionMask; 152 }; 153 154 #ifdef __cplusplus 155 extern "C" { 156 #endif 157 158 /** 159 * @brief Creates a USB device. 160 * 161 * You can use this function to create a descriptor and bind it to a USB device of the specified UDC. 162 * 163 * @param udcName Indicates the pointer to the UDC name, which is obtained based on the UDC driver. 164 * @param descriptor Indicates the pointer to USB device descriptor data. 165 * 166 * @return Returns the pointer to the <b>UsbFnDevice</b> if the operation is successful; 167 * returns <b>NULL</b> otherwise. 168 */ 169 const struct UsbFnDevice *UsbFnCreateDevice(const char *udcName, struct UsbFnDescriptorData *descriptor); 170 171 /** 172 * @brief Deletes a specified USB device. 173 * 174 * 175 * 176 * @param fnDevice Indicates the pointer to the USB device object. 177 * 178 * @return Returns <b>0</b> if the operation is successful; returns a negative value 179 * defined in {@link UsbErrorType} otherwise. 180 */ 181 int32_t UsbFnRemoveDevice(struct UsbFnDevice *fnDevice); 182 const struct UsbFnDevice *UsbFnGetDevice(const char *udcName); 183 int32_t UsbFnGetDeviceState(struct UsbFnDevice *fnDevice, UsbFnDeviceState *devState); 184 185 /** 186 * @brief Obtains a USB interface based on the specified interface index. 187 * 188 * 189 * 190 * @param fnDevice Indicates the pointer to the USB device object. 191 * @param interfaceIndex Indicates the interface index, which is numbered from <b>0</b>. 192 * 193 * @return Returns the pointer to the <b>UsbFnInterface</b> if the operation is successful; 194 * returns <b>NULL</b> otherwise. 195 */ 196 const struct UsbFnInterface *UsbFnGetInterface(struct UsbFnDevice *fnDevice, uint8_t interfaceIndex); 197 int32_t UsbFnMemTestTrigger(bool enable); 198 199 #ifdef __cplusplus 200 } 201 #endif 202 203 #endif /* USBFN_DEVICE_H */ 204