* Copyright (c) 2021-2023 Huawei Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
* @file usbfn_interface.h
*
* @brief Declares USB interface-specific definitions.
*
* @since 1.0
* @version 1.0
*/
#ifndef USBFN_INTERFACE_H
#define USBFN_INTERFACE_H
#include "usb_object.h"
#include "usbfn_request.h"
* @brief Defines USB interfaces of the unspecified class.
*/
#define USB_INTERFACE_CLASS_UNSPEC 0x00
* @brief Defines USB interfaces of the Audio class.
*/
#define USB_INTERFACE_CLASS_AUDIO 0x01
* @brief Defines USB interfaces of the Communication Device Class (CDC).
*/
#define USB_INTERFACE_CLASS_CDC 0x02
* @brief Defines USB interfaces of the Human Interface Device (HID) class.
*/
#define USB_INTERFACE_CLASS_HID 0x03
* @brief Defines USB interfaces of the Physical class.
*/
#define USB_INTERFACE_CLASS_PHYSICAL 0x05
* @brief Defines USB interfaces of the Image class.
*/
#define USB_INTERFACE_CLASS_IMAGE 0x06
* @brief Defines USB interfaces of the Printer class.
*/
#define USB_INTERFACE_CLASS_PRINTER 0x07
* @brief Defines USB interfaces of the Mass Storage (MSD) class.
*/
#define USB_INTERFACE_CLASS_MASS_STORAGE 0x08
* @brief Defines USB interfaces of the Hub class.
*/
#define USB_INTERFACE_CLASS_HUB 0x09
* @brief Defines USB interfaces of the CDC-Data class.
*/
#define USB_INTERFACE_CLASS_CDC_DATA 0x0a
* @brief Defines USB interfaces of the Smart Card class.
*/
#define USB_INTERFACE_CLASS_SMARTCARD 0x0b
* @brief Defines USB interfaces of the Firmware Upgrade class.
*/
#define USB_INTERFACE_CLASS_FIRM_UPD 0x0c
* @brief Defines USB interfaces of the Content Security class.
*/
#define USB_INTERFACE_CLASS_SECURITY 0x0d
* @brief Defines USB interfaces of the Video class.
*/
#define USB_INTERFACE_CLASS_VIDEO 0x0e
* @brief Defines USB interfaces of the Diagnostic Device class.
*/
#define USB_INTERFACE_CLASS_DIAGNOSTIC 0xdc
* @brief Defines USB interfaces of the Wireless Controller class.
*/
#define USB_INTERFACE_CLASS_WIRELESS 0xe0
* @brief Defines USB interfaces of the Miscellaneous class.
*/
#define USB_INTERFACE_CLASS_IAD 0xef
* @brief Defines USB interfaces of the Application Specific class.
*/
#define USB_INTERFACE_CLASS_APP_SPEC 0xfe
* @brief Defines USB interfaces of the Vendor Specific class.
*/
#define USB_INTERFACE_CLASS_VENDOR 0xff
* @brief Defines the USB device event status.
*/
typedef enum {
USBFN_STATE_BIND,
USBFN_STATE_UNBIND,
USBFN_STATE_ENABLE,
USBFN_STATE_DISABLE,
USBFN_STATE_SETUP,
USBFN_STATE_SUSPEND,
USBFN_STATE_RESUME,
} UsbFnDeviceState;
* @brief Defines structure parameters for the USB interface request.
*/
struct UsbFnCtrlRequest {
uint8_t reqType;
uint8_t request;
uint16_t value;
uint16_t index;
* Number of bytes in the data communication phase, which must be less than the
* value of <b>bMaxPacketSize0</b> defined in the device descriptor
*/
uint16_t length;
} __attribute__((packed));
* @brief Defines the structure of the events received by the USB interface.
*/
struct UsbFnEvent {
struct UsbFnCtrlRequest *setup;
UsbFnDeviceState type;
void *context;
};
* @brief Defines the USB interface information.
*/
struct UsbFnInterfaceInfo {
uint8_t index;
uint8_t numPipes;
uint8_t interfaceClass;
uint8_t subclass;
uint8_t protocol;
uint8_t configIndex;
};
* @brief Defines USB interface objects.
*/
struct UsbFnInterface {
const struct UsbObject *object;
struct UsbFnInterfaceInfo info;
};
* @brief Defines the USB pipe information.
*/
struct UsbFnPipeInfo {
uint8_t id;
UsbPipeType type;
UsbPipeDirection dir;
uint16_t maxPacketSize;
uint8_t interval;
};
* @brief Defines callback called when endpoint 0 receives a control event.
*
* This function needs to be defined by the function driver.
*
* @param event Indicates the pointer to the event information, including the event type and request.
*/
typedef void (*UsbFnEventCallback)(struct UsbFnEvent *event);
* @brief Defines the callback called when the function interface obtains or sets custom attributes.
*
* This function needs to be defined by the function driver.
*
* @param interface Indicates the pointer to the USB interface object.
* @param name Indicates the pointer to the attribute name of the string type.
* @param value Indicates the pointer to the attribute value of the string type.
*
* @return Returns <b>0</b> if the operation is successful;
* returns a negative value defined in {@link UsbErrorType} otherwise.
*/
typedef int32_t (*UsbFnPropCallback)(const struct UsbFnInterface *intf, const char *name, const char *value);
* @brief Defines custom attribute information.
*/
struct UsbFnRegistInfo {
const char *name;
const char *value;
UsbFnPropCallback getProp;
UsbFnPropCallback setProp;
};
#ifdef __cplusplus
extern "C" {
#endif
* @brief Defines the callback called when the USB interface starts a thread to receive EP0 events,
* such as the setup event.
*
* @param interface Indicates the pointer to the USB interface object.
* @param eventMask Indicates the type of the event to be processed.
* The event is defined by <b>UsbFnDeviceState</b>.
* Each bit of <b>eventMask</b> indicates an event.
* For example, if the value of <b>eventMask</b> is <b>0xff</b>, all events are received;
* if the value of <b>eventMask</b> is <b>0x01</b>, only the <b>USBFN_STATE_BIND</b> event is received.
* @param callback Indicates the callback function called after a request is processed.
* It needs to be defined by the application.
* @param context Indicates the pointer to the private context data.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value
* defined in {@link UsbErrorType} otherwise.
*/
int32_t UsbFnStartRecvInterfaceEvent(
struct UsbFnInterface *interface, uint32_t eventMask, UsbFnEventCallback callback, void *context);
* @brief Defines the callback called when the USB interface stops receiving EP0 events.
*
* @param interface Indicates the pointer to the USB interface object.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative
* value defined in {@link UsbErrorType} otherwise.
*/
int32_t UsbFnStopRecvInterfaceEvent(struct UsbFnInterface *interface);
* @brief Enables a USB interface.
*
* This function is mainly used to initialize a request queue and open a pipe.
*
* @param interface Indicates the pointer to the USB interface object.
*
* @return Returns a <b>#UsbFnInterfaceHandle</b> containing the USB interface information
* if the operation is successful; returns <b>NULL</b> otherwise.
*/
UsbFnInterfaceHandle UsbFnOpenInterface(struct UsbFnInterface *interface);
* @brief Disables a USB interface.
*
* This function is mainly used to close a pipe and delete a request queue.
*
* @param UsbFnInterfaceHandle Indicates the handle of the USB interface object.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative value
* defined in {@link UsbErrorType} otherwise.
*/
int32_t UsbFnCloseInterface(UsbFnInterfaceHandle handle);
* @brief Obtains USB pipe information based on the specified pipe ID.
*
* @param interface Indicates the pointer to the USB interface object.
* @param pipeId Indicates the pipe ID. The value ranges from 0 to the total number of pipes on the USB interface.
* @param info Indicates the pointer to the obtained pipe information.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative
* value defined in {@link UsbErrorType} otherwise.
*/
int32_t UsbFnGetInterfacePipeInfo(struct UsbFnInterface *interface, uint8_t pipeId, struct UsbFnPipeInfo *info);
* @brief Registers custom attributes for a USB interface.
*
* In addition to custom attributes, you can use this function to register the callback function
* for the request of obtaining and setting custom attributes.
*
* @param interface Indicates the pointer to the USB interface object.
* @param registInfo Indicates the pointer to the attribute information.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative
* value defined in {@link UsbErrorType} otherwise.
*/
int32_t UsbFnRegistInterfaceProp(const struct UsbFnInterface *interface, const struct UsbFnRegistInfo *registInfo);
* @brief Obtains custom attributes of a USB interface.
*
* Custom attributes can be any of the following: attributes of device descriptors, such as VID and PID,
* attributes of the USB interface defined in the HCS file, and attributes registered
* in the code at the application layer.
* For example, if <b>name</b> is <b>idVendor</b> when obtaining the VID, the obtained value will be
* stored in <b>value</b> as a hex string.
*
* @param interface Indicates the pointer to the USB interface object.
* @param name Indicates the pointer to the attribute name of the string type.
* @param value Indicates the pointer to the attribute value of the string type. Except integer data,
* which is a string converted from hex data, all the other types of data are strings by default.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative
* value defined in {@link UsbErrorType} otherwise.
*/
int32_t UsbFnGetInterfaceProp(const struct UsbFnInterface *interface, const char *name, char *value);
* @brief Sets custom attributes of a USB interface.
*
* Custom attributes can be any of the following: attributes of device descriptors, such as VID and PID,
* attributes of the USB interface defined in the HCS file, and attributes registered
* in the code at the application layer.
* For example, if <b>name</b> is <b>idVendor</b> when setting the VID, the set value will be
* stored in <b>value</b> as a hex string.
*
* @param interface Indicates the pointer to the USB interface object.
* @param name Indicates the pointer to the attribute name of the string type.
* @param value Indicates the pointer to the attribute value of the string type. Except integer data,
* which is a string converted from hex data, all the other types of data are strings by default.
*
* @return Returns <b>0</b> if the operation is successful; returns a negative
* value defined in {@link UsbErrorType} otherwise.
*/
int32_t UsbFnSetInterfaceProp(const struct UsbFnInterface *interface, const char *name, const char *value);
#ifdef __cplusplus
}
#endif
#endif