/** * @file kmdw_usbh.h * @brief usbh 2.0 APIs * * @copyright Copyright (c) 2019 Kneron Inc. All rights reserved. */ #ifndef __KMDW_USBH_H__ #define __KMDW_USBH_H__ #include #include #include "usb_def.h" /// ==== USB Constants and Defines ==== /// Status code values returned by USB library functions. typedef enum { usbOK = 0U, ///< Function completed with no error usbTimeout, ///< Function completed; time-out occurred usbInvalidParameter, ///< Invalid Parameter error: a mandatory parameter was missing or specified an incorrect object usbThreadError = 0x10U, ///< CMSIS-RTOS Thread creation/termination failed usbTimerError, ///< CMSIS-RTOS Timer creation/deletion failed usbSemaphoreError, ///< CMSIS-RTOS Semaphore creation failed usbMutexError, ///< CMSIS-RTOS Mutex creation failed usbControllerError = 0x20U, ///< Controller does not exist usbDeviceError, ///< Device does not exist usbDriverError, ///< Driver function produced error usbDriverBusy, ///< Driver function is busy usbMemoryError, ///< Memory management function produced error usbNotConfigured, ///< Device is not configured (is connected) usbClassErrorADC, ///< Audio Device Class (ADC) error (no device or device produced error) usbClassErrorCDC, ///< Communication Device Class (CDC) error (no device or device produced error) usbClassErrorHID, ///< Human Interface Device (HID) error (no device or device produced error) usbClassErrorMSC, ///< Mass Storage Device (MSC) error (no device or device produced error) usbClassErrorCustom, ///< Custom device Class (Class) error (no device or device produced error) usbUnsupportedClass, ///< Unsupported Class usbTransferStall = 0x40U, ///< Transfer handshake was stall usbTransferError, ///< Transfer error usbUnknownError = 0xFFU ///< Unspecified USB error } usbStatus; /* USB Host Constants and Defines */ /// USB Host Notification enumerated constants typedef enum { USBH_NOTIFY_CONNECT = 0U, ///< Port connection happened USBH_NOTIFY_DISCONNECT, ///< Port disconnection happened USBH_NOTIFY_OVERCURRENT, ///< Port overcurrent happened USBH_NOTIFY_REMOTE_WAKEUP, ///< Port remote wakeup signaling happened USBH_NOTIFY_READY, ///< Device was successfully enumerated, initialized and is ready for communication USBH_NOTIFY_UNKNOWN_DEVICE, ///< Device was successfully enumerated but there is no driver for it USBH_NOTIFY_INSUFFICIENT_POWER, ///< Device requires more power consumption than available USBH_NOTIFY_CONFIGURATION_FAILED, ///< Device was not successfully configured (not enough resources) USBH_NOTIFY_INITIALIZATION_FAILED ///< Device was not successfully initialized } USBH_NOTIFY; /* USB Host Pipe handle type */ typedef uint32_t USBH_PIPE_HANDLE; // ==== USB Host Functions ==== /// \brief Get version of USB Host stack /// \return version (major.minor.revision : mmnnnrrrr decimal) extern uint32_t USBH_GetVersion(void); /// \brief Initialize USB Host stack and controller /// \param[in] ctrl index of USB Host controller. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_Initialize(uint8_t ctrl); /// \brief De-initialize USB Host stack and controller /// \param[in] ctrl index of USB Host controller. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_Uninitialize(uint8_t ctrl); /// \brief Suspend a root HUB port on specified controller /// \param[in] ctrl index of USB Host controller. /// \param[in] port root HUB port. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_Port_Suspend(uint8_t ctrl, uint8_t port); /// \brief Resume a root HUB port on specified controller /// \param[in] ctrl index of USB Host controller. /// \param[in] port root HUB port. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_Port_Resume(uint8_t ctrl, uint8_t port); /// \brief Get index of USB Host controller to which USB Device is connected /// \param[in] device index of USB Device. /// \return index of USB Host controller or non-existing USB Host controller : /// - value != 255 : index of USB Host controller /// - value 255 : non-existing USB Host controller extern uint8_t USBH_Device_GetController(uint8_t device); /// \brief Get index of USB Host Root HUB port to which USB Device is connected /// \param[in] device index of USB Device. /// \return index of USB Host Root HUB port or non-existing USB Host Root HUB port : /// - value <= 15 : index of USB Host Root HUB port /// - value 255 : non-existing USB Host Root HUB port extern uint8_t USBH_Device_GetPort(uint8_t device); /// \brief Get status of USB Device /// \param[in] device index of USB Device. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_Device_GetStatus(uint8_t device); /// \brief Get communication speed of USB Device /// \param[in] device index of USB Device. /// \return communication speed : /// - USB_SPEED_LOW = low speed /// - USB_SPEED_FULL = full speed /// - USB_SPEED_HIGH = high speed extern int32_t USBH_Device_GetSpeed(uint8_t device); /// \brief Get communication address of USB Device /// \param[in] device index of USB Device. /// \return enumerated address or invalid address : /// - value <= 127 : enumerated address /// - value 255 : invalid address extern uint8_t USBH_Device_GetAddress(uint8_t device); /// \brief Get Vendor ID (VID) of USB Device /// \param[in] device index of USB Device. /// \return Vendor ID. extern uint16_t USBH_Device_GetVID(uint8_t device); /// \brief Get Product ID (PID) of USB Device /// \param[in] device index of USB Device. /// \return Product ID. extern uint16_t USBH_Device_GetPID(uint8_t device); /// \brief Get String Descriptor of USB Device /// \param[in] device index of USB Device. /// \param[in] index index of string descriptor. /// \param[in] language_id language ID. /// \param[out] descriptor_data pointer to where descriptor data will be read. /// \param[in] descriptor_length maximum descriptor length. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_Device_GetStringDescriptor(uint8_t device, uint8_t index, uint16_t language_id, uint8_t *descriptor_data, uint16_t descriptor_length); /// \brief Callback function called when some event has happened on corresponding controller and port /// \param[in] ctrl index of USB Host controller. /// \param[in] port index of Root HUB port. /// \param[in] device index of USB Device : /// - value <= 127: index of of USB Device for device notifications /// - value 255: no device information for port notifications /// \param[in] notify notification : /// - USBH_NOTIFY_CONNECT = Port connection happened /// - USBH_NOTIFY_DISCONNECT = Port disconnection happened /// - USBH_NOTIFY_OVERCURRENT = Port overcurrent happened /// - USBH_NOTIFY_REMOTE_WAKEUP = Port remote wakeup signaling happened /// - USBH_NOTIFY_READY = Device was successfully enumerated, initialized and is ready for communication /// - USBH_NOTIFY_UNKNOWN_DEVICE = Device was successfully enumerated but there is no driver for it /// - USBH_NOTIFY_INSUFFICIENT_POWER = Device requires more power consumption than available /// - USBH_NOTIFY_CONFIGURATION_FAILED = Device was not successfully configured (not enough resources) /// - USBH_NOTIFY_INITIALIZATION_FAILED = Device was not successfully initialized extern void USBH_Notify(uint8_t ctrl, uint8_t port, uint8_t device, USBH_NOTIFY notify); // ==== USB Host Custom Class Functions ==== /// \brief Get Device instance of Custom Class Device /// \param[in] instance instance of Custom Class Device. /// \return instance of Device or non-existing Device instance : /// - value <= 127 : instance of Device /// - value 255 : non-existing Device instance extern uint8_t USBH_CustomClass_GetDevice(uint8_t instance); /// \brief Get status of Custom Class Device /// \param[in] instance instance of Custom Class Device. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_CustomClass_GetStatus(uint8_t instance); /// \brief Callback function called when custom class device is connected and needs /// to configure resources used by custom class device instance /// \param[in] device index of USB Device. /// \param[in] ptr_dev_desc pointer to device descriptor. /// \param[in] ptr_cfg_desc pointer to configuration descriptor. /// \return index of configured custom class device instance or configuration failed : /// - value <= 127 : index of configured custom class device instance /// - value 255 : configuration failed extern uint8_t USBH_CustomClass_Configure(uint8_t device, const USB_DEVICE_DESCRIPTOR *ptr_dev_desc, const USB_CONFIGURATION_DESCRIPTOR *ptr_cfg_desc); /// \brief Callback function called when custom class device is disconnected and needs /// to de-configure resources used by custom class device instance /// \param[in] instance index of custom class device instance. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_CustomClass_Unconfigure(uint8_t instance); /// \brief Callback function called when custom class device is connected and needs /// to initialize custom class device instance /// \param[in] instance index of custom class device instance. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_CustomClass_Initialize(uint8_t instance); /// \brief Callback function called when custom class device is disconnected and needs /// to de-initialize custom class device instance /// \param[in] instance index of custom class device instance. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_CustomClass_Uninitialize(uint8_t instance); /// \brief Create Pipe /// \param[in] device index of USB Device. /// \param[in] ep_addr endpoint address : /// - ep_addr.0..3 : address /// - ep_addr.7 : direction /// \param[in] ep_type endpoint type. /// \param[in] ep_max_packet_size endpoint maximum packet size. /// \param[in] ep_interval endpoint polling interval. /// \return pipe handle or pipe creation failed : /// - value > 0 : pipe handle /// - value 0 : pipe creation failed extern USBH_PIPE_HANDLE USBH_PipeCreate(uint8_t device, uint8_t ep_addr, uint8_t ep_type, uint16_t ep_max_packet_size, uint8_t ep_interval); /// \brief Update Pipe /// \param[in] pipe_hndl pipe handle. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_PipeUpdate(USBH_PIPE_HANDLE pipe_hndl); /// \brief Delete Pipe /// \param[in] pipe_hndl pipe handle. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_PipeDelete(USBH_PIPE_HANDLE pipe_hndl); /// \brief Reset Pipe (reset data toggle) /// \param[in] pipe_hndl pipe handle. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_PipeReset(USBH_PIPE_HANDLE pipe_hndl); /// \brief Receive data on Pipe /// \param[in] pipe_hndl pipe handle. /// \param[out] buf buffer that receives data. /// \param[in] len maximum number of bytes to receive. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_PipeReceive(USBH_PIPE_HANDLE pipe_hndl, uint8_t *buf, uint32_t len); /// \brief Get result of receive data operation on Pipe /// \param[in] pipe_hndl pipe handle. /// \return number of successfully received data bytes. extern uint32_t USBH_PipeReceiveGetResult(USBH_PIPE_HANDLE pipe_hndl); /// \brief Send data on Pipe /// \param[in] pipe_hndl pipe handle. /// \param[in] buf buffer containing data bytes to send. /// \param[in] len number of bytes to send. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_PipeSend(USBH_PIPE_HANDLE pipe_hndl, const uint8_t *buf, uint32_t len); /// \brief Get result of send data operation on Pipe /// \param[in] pipe_hndl pipe handle. /// \return number of successfully sent data bytes. extern uint32_t USBH_PipeSendGetResult(USBH_PIPE_HANDLE pipe_hndl); /// \brief Abort send/receive operation on Pipe /// \param[in] pipe_hndl pipe handle. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_PipeAbort(USBH_PIPE_HANDLE pipe_hndl); /// \brief Do a Control Transfer on Default Pipe /// \param[in] device index of USB Device. /// \param[in] setup_packet pointer to setup packet. /// \param[in,out] data buffer containing data bytes to send or where data should be received in data stage of Control Transfer. /// \param[in] len number of bytes to send or receive in data stage of Control Transfer. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_ControlTransfer(uint8_t device, const USB_SETUP_PACKET *setup_packet, uint8_t *data, uint32_t len); /// \brief Standard Device Request on Default Pipe - GET_STATUS /// \param[in] device index of USB Device. /// \param[in] recipient recipient. /// \param[in] index interface or endpoint index. /// \param[out] ptr_stat_dat pointer to where status data should be received. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_DeviceRequest_GetStatus(uint8_t device, uint8_t recipient, uint8_t index, uint8_t *ptr_stat_dat); /// \brief Standard Device Request on Default Pipe - CLEAR_FEATURE /// \param[in] device index of USB Device. /// \param[in] recipient recipient. /// \param[in] index interface or endpoint index. /// \param[in] feature_selector feature selector. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_DeviceRequest_ClearFeature(uint8_t device, uint8_t recipient, uint8_t index, uint8_t feature_selector); /// \brief Standard Device Request on Default Pipe - SET_FEATURE /// \param[in] device index of USB Device. /// \param[in] recipient recipient. /// \param[in] index interface or endpoint index. /// \param[in] feature_selector feature selector. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_DeviceRequest_SetFeature(uint8_t device, uint8_t recipient, uint8_t index, uint8_t feature_selector); /// \brief Standard Device Request on Default Pipe - SET_ADDRESS /// \param[in] device index of USB Device. /// \param[in] device_address device address. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_DeviceRequest_SetAddress(uint8_t device, uint8_t device_address); /// \brief Standard Device Request on Default Pipe - GET_DESCRIPTOR /// \param[in] device index of USB Device. /// \param[in] recipient recipient. /// \param[in] descriptor_type descriptor type. /// \param[in] descriptor_index descriptor index. /// \param[in] language_id language ID. /// \param[out] descriptor_data pointer to where descriptor data will be read. /// \param[in] descriptor_length maximum descriptor length. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_DeviceRequest_GetDescriptor(uint8_t device, uint8_t recipient, uint8_t descriptor_type, uint8_t descriptor_index, uint16_t language_id, uint8_t *descriptor_data, uint16_t descriptor_length); /// \brief Standard Device Request on Default Pipe - SET_DESCRIPTOR /// \param[in] device index of USB Device. /// \param[in] recipient recipient. /// \param[in] descriptor_type descriptor type. /// \param[in] descriptor_index descriptor index. /// \param[in] language_id language ID. /// \param[in] descriptor_data pointer to descriptor data to be written. /// \param[in] descriptor_length descriptor length. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_DeviceRequest_SetDescriptor(uint8_t device, uint8_t recipient, uint8_t descriptor_type, uint8_t descriptor_index, uint16_t language_id, const uint8_t *descriptor_data, uint16_t descriptor_length); /// \brief Standard Device Request on Default Pipe - GET_CONFIGURATION /// \param[in] device index of USB Device. /// \param[out] ptr_configuration pointer to where configuration will be read. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_DeviceRequest_GetConfiguration(uint8_t device, uint8_t *ptr_configuration); /// \brief Standard Device Request on Default Pipe - SET_CONFIGURATION /// \param[in] device index of USB Device. /// \param[in] configuration configuration. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_DeviceRequest_SetConfiguration(uint8_t device, uint8_t configuration); /// \brief Standard Device Request on Default Pipe - GET_INTERFACE /// \param[in] device index of USB Device. /// \param[in] index interface index. /// \param[out] ptr_alternate pointer to where alternate setting data will be read. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_DeviceRequest_GetInterface(uint8_t device, uint8_t index, uint8_t *ptr_alternate); /// \brief Standard Device Request on Default Pipe - SET_INTERFACE /// \param[in] device index of USB Device. /// \param[in] index interface index. /// \param[in] alternate alternate setting. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_DeviceRequest_SetInterface(uint8_t device, uint8_t index, uint8_t alternate); /// \brief Standard Device Request on Default Pipe - SYNCH_FRAME /// \param[in] device index of USB Device. /// \param[in] index interface or endpoint index. /// \param[out] ptr_frame_number pointer to where frame number data will be read. /// \return status code that indicates the execution status of the function as defined with \ref usbStatus. extern usbStatus USBH_DeviceRequest_SynchFrame(uint8_t device, uint8_t index, uint8_t *ptr_frame_number); // below is a set of extended functions for isochronous transfer typedef void (*USBH_CB_ISR_Isoch_transfer)(uint32_t *payload, uint32_t length); extern USBH_PIPE_HANDLE USBH_Pipe_ISOCH_PipeDelete(USBH_PIPE_HANDLE pipe_hndl); extern USBH_PIPE_HANDLE USBH_Pipe_ISOCH_PipeCreate(uint8_t device, uint8_t ep_addr, uint32_t wMaxPacketSize, uint8_t bInterval, uint8_t *buf, uint32_t buf_size); extern usbStatus USBH_Pipe_ISOCH_Start(USBH_PIPE_HANDLE pipe_hndl, USBH_CB_ISR_Isoch_transfer isoch_cb); extern usbStatus USBH_Pipe_ISOCH_Stop(USBH_PIPE_HANDLE pipe_hndl); #endif