USB Device Core API
USB Device API

Description

USB Device Core API.

Data Structures

struct  sl_usbd_device_config_t
 USB DEVICE CONFIGURATION DATA TYPE.
 
struct  sl_usbd_setup_req_t
 USB DEVICE MICROSOFT XTENDED PROPERTIES DATA TYPE.
 
struct  sl_usbd_class_driver_t
 INTERFACE CLASS DRIVER.

Functions

sl_status_t sl_usbd_core_init (void)
 Initialize the USB device stack.
 
sl_status_t sl_usbd_core_start_device (void)
 Start the device stack.
 
sl_status_t sl_usbd_core_stop_device (void)
 Stop the device stack.
 
sl_status_t sl_usbd_core_get_device_state (sl_usbd_device_state_t *p_dev_state)
 Get the current device state.
 
sl_status_t sl_usbd_core_get_device_speed (sl_usbd_device_speed_t *p_dev_speed)
 Get device speed.
 
sl_status_t sl_usbd_core_set_device_self_power (bool self_pwr)
 Set the device's current power source.
 
sl_status_t sl_usbd_core_get_device_configuration (sl_usbd_device_config_t **p_dev_cfg)
 Set the device's Microsoft vendor code.
 
sl_status_t sl_usbd_core_get_device_frame_number (uint16_t *p_frame_nbr)
 Get the last frame number from the driver.
 
sl_status_t sl_usbd_core_add_configuration (uint8_t attrib, uint16_t max_pwr, sl_usbd_device_speed_t spd, const char *p_name, uint8_t *p_cfg_nbr)
 Add a configuration attribute to the device.
 
sl_status_t sl_usbd_core_add_interface (uint8_t cfg_nbr, sl_usbd_class_driver_t *p_class_drv, void *p_if_class_arg, void *p_if_alt_class_arg, uint8_t class_code, uint8_t class_sub_code, uint8_t class_protocol_code, const char *p_name, uint8_t *p_if_nbr)
 Associate a configuration with its alternative-speed counterpart.
 
sl_status_t sl_usbd_core_add_alt_interface (uint8_t config_nbr, uint8_t if_nbr, void *p_class_arg, const char *p_name, uint8_t *p_if_alt_nbr)
 Add an alternate setting to a specific interface.
 
sl_status_t sl_usbd_core_add_interface_group (uint8_t config_nbr, uint8_t class_code, uint8_t class_sub_code, uint8_t class_protocol_code, uint8_t if_start, uint8_t if_cnt, const char *p_name, uint8_t *p_if_grp_num)
 Create an interface group.
 
sl_status_t sl_usbd_core_get_device_descriptor (uint8_t *p_buf, uint8_t max_len, uint8_t *p_desc_len)
 Get the device descriptor.
 
sl_status_t sl_usbd_core_get_configuration_descriptor (uint8_t *p_buf, uint16_t max_len, uint8_t config_ix, uint16_t *p_desc_len)
 Get a configuration descriptor.
 
sl_status_t sl_usbd_core_get_string_descriptor (uint8_t *p_buf, uint8_t max_len, uint8_t str_ix, uint8_t *p_desc_len)
 Get a string descriptor.
 
sl_status_t sl_usbd_core_add_string (const char *p_str)
 Add string to USB device.
 
sl_status_t sl_usbd_core_get_string_index (const char *p_str, uint8_t *p_str_ix)
 Get string index corresponding to a given string.
 
sl_status_t sl_usbd_core_write_08b_to_descriptor_buf (uint8_t val)
 Write an 8-bit value to the descriptor buffer.
 
sl_status_t sl_usbd_core_write_16b_to_descriptor_buf (uint16_t val)
 Write a 16-bit value in the descriptor buffer.
 
sl_status_t sl_usbd_core_write_24b_to_descriptor_buf (uint32_t val)
 Write a 24-bit value to the descriptor buffer.
 
sl_status_t sl_usbd_core_write_32b_to_descriptor_buf (uint32_t val)
 Write a 32-bit value to the descriptor buffer.
 
sl_status_t sl_usbd_core_write_buf_to_descriptor_buf (const uint8_t *p_buf, uint16_t len)
 Write a buffer into the descriptor buffer.
 
sl_status_t sl_usbd_core_write_control_sync (void *p_buf, uint32_t buf_len, uint16_t timeout_ms, bool end, uint32_t *p_xfer_len)
 Send data on the Control IN endpoint.
 
sl_status_t sl_usbd_core_read_control_sync (void *p_buf, uint32_t buf_len, uint16_t timeout_ms, uint32_t *p_xfer_len)
 Receive data on the Control OUT endpoint.
 
sl_status_t sl_usbd_core_add_bulk_endpoint (uint8_t config_nbr, uint8_t if_nbr, uint8_t if_alt_nbr, bool dir_in, uint16_t max_pkt_len, uint8_t *p_ep_addr)
 Add a bulk endpoint to alternate setting interface.
 
sl_status_t sl_usbd_core_read_bulk_sync (uint8_t ep_addr, void *p_buf, uint32_t buf_len, uint16_t timeout_ms, uint32_t *p_xfer_len)
 Receive data on Bulk OUT endpoint.
 
sl_status_t sl_usbd_core_read_bulk_async (uint8_t ep_addr, void *p_buf, uint32_t buf_len, sl_usbd_async_function_t async_fnct, void *p_async_arg)
 Receive data on Bulk OUT endpoint asynchronously.
 
sl_status_t sl_usbd_core_write_bulk_sync (uint8_t ep_addr, void *p_buf, uint32_t buf_len, uint16_t timeout_ms, bool end, uint32_t *p_xfer_len)
 Send data on a Bulk IN endpoint.
 
sl_status_t sl_usbd_core_write_bulk_async (uint8_t ep_addr, void *p_buf, uint32_t buf_len, sl_usbd_async_function_t async_fnct, void *p_async_arg, bool end)
 Send data on the Bulk IN endpoint asynchronously.
 
sl_status_t sl_usbd_core_add_interrupt_endpoint (uint8_t config_nbr, uint8_t if_nbr, uint8_t if_alt_nbr, bool dir_in, uint16_t max_pkt_len, uint16_t interval, uint8_t *p_ep_addr)
 Add an interrupt endpoint to an alternate setting interface.
 
sl_status_t sl_usbd_core_read_interrupt_sync (uint8_t ep_addr, void *p_buf, uint32_t buf_len, uint16_t timeout_ms, uint32_t *p_xfer_len)
 Receive data on the Interrupt OUT endpoint.
 
sl_status_t sl_usbd_core_read_interrupt_async (uint8_t ep_addr, void *p_buf, uint32_t buf_len, sl_usbd_async_function_t async_fnct, void *p_async_arg)
 Receive data on Interrupt OUT endpoint asynchronously.
 
sl_status_t sl_usbd_core_write_interrupt_sync (uint8_t ep_addr, void *p_buf, uint32_t buf_len, uint16_t timeout_ms, bool end, uint32_t *p_xfer_len)
 Send data on Interrupt IN endpoint.
 
sl_status_t sl_usbd_core_write_interrupt_async (uint8_t ep_addr, void *p_buf, uint32_t buf_len, sl_usbd_async_function_t async_fnct, void *p_async_arg, bool end)
 Send data on the Interrupt IN endpoint asynchronously.
 
sl_status_t sl_usbd_core_endpoint_write_zlp (uint8_t ep_addr, uint16_t timeout_ms)
 Add an isochronous endpoint to alternate setting interface.
 
sl_status_t sl_usbd_core_endpoint_read_zlp (uint8_t ep_addr, uint16_t timeout_ms)
 Receive zero-length packet from the host.
 
sl_status_t sl_usbd_core_abort_endpoint (uint8_t ep_addr)
 Abort I/O transfer on the endpoint.
 
sl_status_t sl_usbd_core_endpoint_read_complete (uint8_t ep_log_nbr)
 Notify USB stack that packet receive has completed.
 
sl_status_t sl_usbd_core_endpoint_write_complete (uint8_t ep_log_nbr)
 Notify USB stack that packet transmit has completed.
 
sl_status_t sl_usbd_core_endpoint_write_complete_extended (uint8_t ep_log_nbr, sl_status_t xfer_err)
 Notify USB stack that packet transmit has completed (see Note #1).
 
sl_status_t sl_usbd_core_stall_endpoint (uint8_t ep_addr, bool state)
 Stall the non-control endpoint.
 
sl_status_t sl_usbd_core_is_endpoint_stalled (uint8_t ep_addr, bool *p_ep_stall)
 Get the stall status of a non-control endpoint.
 
sl_status_t sl_usbd_core_get_max_endpoint_packet_size (uint8_t ep_addr, uint16_t *p_max_size)
 Retrieve the endpoint maximum packet size.
 
sl_status_t sl_usbd_core_get_max_phy_endpoint_number (uint8_t *p_ep_phy_nbr)
 Get the maximum physical endpoint number.
 
sl_status_t sl_usbd_core_get_max_open_endpoint_number (uint8_t *p_nbr_open)
 
__WEAK void sl_usbd_on_bus_event (sl_usbd_bus_event_t event)
 
__WEAK void sl_usbd_on_config_event (sl_usbd_config_event_t event, uint8_t config_nbr)

Macros

#define SL_USBD_FRAME_NBR_MAX   2047u
 
#define SL_USBD_FRAME_NBR_MASK   0b0000011111111111
 
#define SL_USBD_MICROFRAME_NBR_MASK   0b0011100000000000
 
#define SL_USBD_DEV_ATTRIB_SELF_POWERED   0x01u
 
#define SL_USBD_DEV_ATTRIB_REMOTE_WAKEUP   0x02u
 
#define SL_USBD_DESC_LEN_DEV   18u
 
#define SL_USBD_DESC_LEN_DEV_QUAL   10u
 
#define SL_USBD_DESC_LEN_HDR   2u
 
#define SL_USBD_DESC_LEN_CFG   9u
 
#define SL_USBD_DESC_LEN_OTHER_SPD_CFG   9u
 
#define SL_USBD_DESC_LEN_IF   9u
 
#define SL_USBD_DESC_LEN_IF_ASSOCIATION   8u
 
#define SL_USBD_DESC_LEN_EP   7u
 
#define SL_USBD_DESC_LEN_OTG   3u
 
#define SL_USBD_REQ_DIR_MASK   0x80u
 
#define SL_USBD_REQ_DIR_HOST_TO_DEVICE   0x00u
 
#define SL_USBD_REQ_DIR_DEVICE_TO_HOST   0x80u
 
#define SL_USBD_REQ_DIR_BIT   0x80u
 
#define SL_USBD_REQ_TYPE_MASK   0x60u
 
#define SL_USBD_REQ_TYPE_STANDARD   0x00u
 
#define SL_USBD_REQ_TYPE_CLASS   0x20u
 
#define SL_USBD_REQ_TYPE_VENDOR   0x40u
 
#define SL_USBD_REQ_TYPE_RESERVED   0x60u
 
#define SL_USBD_REQ_RECIPIENT_MASK   0x1Fu
 
#define SL_USBD_REQ_RECIPIENT_DEVICE   0x00u
 
#define SL_USBD_REQ_RECIPIENT_INTERFACE   0x01u
 
#define SL_USBD_REQ_RECIPIENT_ENDPOINT   0x02u
 
#define SL_USBD_REQ_RECIPIENT_OTHER   0x03u
 
#define SL_USBD_REQ_GET_STATUS   0u
 
#define SL_USBD_REQ_CLEAR_FEATURE   1u
 
#define SL_USBD_REQ_SET_FEATURE   3u
 
#define SL_USBD_REQ_SET_ADDRESS   5u
 
#define SL_USBD_REQ_GET_DESCRIPTOR   6u
 
#define SL_USBD_REQ_SET_DESCRIPTOR   7u
 
#define SL_USBD_REQ_GET_CONFIGURATION   8u
 
#define SL_USBD_REQ_SET_CONFIGURATION   9u
 
#define SL_USBD_REQ_GET_INTERFACE   10u
 
#define SL_USBD_REQ_SET_INTERFACE   11u
 
#define SL_USBD_REQ_SYNCH_FRAME   12u
 
#define SL_USBD_DESC_TYPE_DEVICE   1u
 
#define SL_USBD_DESC_TYPE_CONFIGURATION   2u
 
#define SL_USBD_DESC_TYPE_STRING   3u
 
#define SL_USBD_DESC_TYPE_INTERFACE   4u
 
#define SL_USBD_DESC_TYPE_ENDPOINT   5u
 
#define SL_USBD_DESC_TYPE_DEVICE_QUALIFIER   6u
 
#define SL_USBD_DESC_TYPE_OTHER_SPEED_CONFIGURATION   7u
 
#define SL_USBD_DESC_TYPE_INTERFACE_POWER   8u
 
#define SL_USBD_DESC_TYPE_OTG   9u
 
#define SL_USBD_DESC_TYPE_IAD   11u
 
#define SL_USBD_LANG_ID_ARABIC_SAUDI_ARABIA   0x0401u
 
#define SL_USBD_LANG_ID_CHINESE_TAIWAN   0x0404u
 
#define SL_USBD_LANG_ID_ENGLISH_US   0x0409u
 
#define SL_USBD_LANG_ID_ENGLISH_UK   0x0809u
 
#define SL_USBD_LANG_ID_FRENCH   0x040Cu
 
#define SL_USBD_LANG_ID_GERMAN   0x0407u
 
#define SL_USBD_LANG_ID_GREEK   0x0408u
 
#define SL_USBD_LANG_ID_ITALIAN   0x0410u
 
#define SL_USBD_LANG_ID_PORTUGUESE   0x0816u
 
#define SL_USBD_LANG_ID_SANSKRIT   0x044Fu
 
#define SL_USBD_CLASS_CODE_USE_IF_DESC   0x00u
 
#define SL_USBD_CLASS_CODE_AUDIO   0x01u
 
#define SL_USBD_CLASS_CODE_CDC_CONTROL   0x02u
 
#define SL_USBD_CLASS_CODE_HID   0x03u
 
#define SL_USBD_CLASS_CODE_PHYSICAL   0x05u
 
#define SL_USBD_CLASS_CODE_IMAGE   0x06u
 
#define SL_USBD_CLASS_CODE_PRINTER   0x07u
 
#define SL_USBD_CLASS_CODE_MASS_STORAGE   0x08u
 
#define SL_USBD_CLASS_CODE_HUB   0x09u
 
#define SL_USBD_CLASS_CODE_CDC_DATA   0x0Au
 
#define SL_USBD_CLASS_CODE_SMART_CARD   0x0Bu
 
#define SL_USBD_CLASS_CODE_CONTENT_SECURITY   0x0Du
 
#define SL_USBD_CLASS_CODE_VIDEO   0x0Eu
 
#define SL_USBD_CLASS_CODE_PERSONAL_HEALTHCARE   0x0Fu
 
#define SL_USBD_CLASS_CODE_DIAGNOSTIC_DEVICE   0xDCu
 
#define SL_USBD_CLASS_CODE_WIRELESS_CONTROLLER   0xE0u
 
#define SL_USBD_CLASS_CODE_MISCELLANEOUS   0xEFu
 
#define SL_USBD_CLASS_CODE_APPLICATION_SPECIFIC   0xFEu
 
#define SL_USBD_CLASS_CODE_VENDOR_SPECIFIC   0xFFu
 
#define SL_USBD_SUBCLASS_CODE_USE_IF_DESC   0x00u
 
#define SL_USBD_SUBCLASS_CODE_USE_COMMON_CLASS   0x02u
 
#define SL_USBD_SUBCLASS_CODE_VENDOR_SPECIFIC   0xFFu
 
#define SL_USBD_PROTOCOL_CODE_USE_IF_DESC   0x00u
 
#define SL_USBD_PROTOCOL_CODE_USE_IAD   0x01u
 
#define SL_USBD_PROTOCOL_CODE_VENDOR_SPECIFIC   0xFFu
 
#define SL_USBD_FEATURE_SEL_ENDPOINT_HALT   0u
 
#define SL_USBD_FEATURE_SEL_DEVICE_REMOTE_WAKEUP   1u
 
#define SL_USBD_FEATURE_SEL_TEST_MODE   2u
 
#define SL_USBD_MAX_BUS_PWR_LIMIT_mA   500u
 
#define SL_USBD_ENDPOINT_TYPE_MASK   0x03u
 
#define SL_USBD_ENDPOINT_TYPE_CTRL   0x00u
 
#define SL_USBD_ENDPOINT_TYPE_ISOC   0x01u
 
#define SL_USBD_ENDPOINT_TYPE_BULK   0x02u
 
#define SL_USBD_ENDPOINT_TYPE_INTR   0x03u
 
#define SL_USBD_ENDPOINT_TYPE_SYNC_MASK   0x0Cu
 
#define SL_USBD_ENDPOINT_TYPE_SYNC_NONE   0x00u
 
#define SL_USBD_ENDPOINT_TYPE_SYNC_ASYNC   0x04u
 
#define SL_USBD_ENDPOINT_TYPE_SYNC_ADAPTIVE   0x08u
 
#define SL_USBD_ENDPOINT_TYPE_SYNC_SYNC   0x0Cu
 
#define SL_USBD_ENDPOINT_TYPE_USAGE_MASK   0x30u
 
#define SL_USBD_ENDPOINT_TYPE_USAGE_DATA   0x00u
 
#define SL_USBD_ENDPOINT_TYPE_USAGE_FEEDBACK   0x10u
 
#define SL_USBD_ENDPOINT_TYPE_USAGE_IMPLICIT_FEEDBACK   0x20u
 
#define SL_USBD_ENDPOINT_NBR_MASK   0x0Fu
 
#define SL_USBD_ENDPOINT_MAX_NBR   32u
 
#define SL_USBD_ENDPOINT_DIR_MASK   0x80u
 
#define SL_USBD_ENDPOINT_DIR_BIT   0x80u
 
#define SL_USBD_ENDPOINT_DIR_OUT   0x00u
 
#define SL_USBD_ENDPOINT_DIR_IN   0x80u
 
#define SL_USBD_ENDPOINT_TRANSACTION_PER_UFRAME_1   1u
 
#define SL_USBD_ENDPOINT_TRANSACTION_PER_UFRAME_2   2u
 
#define SL_USBD_ENDPOINT_TRANSACTION_PER_UFRAME_3   3u
 
#define SL_USBD_ENDPOINT_MAX_INTERVAL_VAL   32768u
 
#define SL_USBD_MICROSOFT_COMPAT_ID_NULL   0u
 
#define SL_USBD_MICROSOFT_COMPAT_ID_RNDIS   1u
 
#define SL_USBD_MICROSOFT_COMPAT_ID_PTP   2u
 
#define SL_USBD_MICROSOFT_COMPAT_ID_MTP   3u
 
#define SL_USBD_MICROSOFT_COMPAT_ID_XUSB20   4u
 
#define SL_USBD_MICROSOFT_COMPAT_ID_BLUETOOTH   5u
 
#define SL_USBD_MICROSOFT_COMPAT_ID_WINUSB   6u
 
#define SL_USBD_MICROSOFT_COMPAT_ID_NONE   255u
 
#define SL_USBD_MICROSOFT_SUBCOMPAT_ID_NULL   0u
 
#define SL_USBD_MICROSOFT_SUBCOMPAT_ID_BLUETOOTH_1_1   1u
 
#define SL_USBD_MICROSOFT_SUBCOMPAT_ID_BLUETOOTH_1_2   2u
 
#define SL_USBD_MICROSOFT_SUBCOMPAT_ID_BLUETOOTH_EDR   3u
 
#define SL_USBD_MICROSOFT_PROPERTY_TYPE_REG_SZ   1u
 
#define SL_USBD_MICROSOFT_PROPERTY_TYPE_REG_EXPAND_SZ   2u
 
#define SL_USBD_MICROSOFT_PROPERTY_TYPE_REG_BINARY   3u
 
#define SL_USBD_MICROSOFT_PROPERTY_TYPE_REG_DWORD_LITTLE_ENDIAN   4u
 
#define SL_USBD_MICROSOFT_PROPERTY_TYPE_REG_DWORD_BIG_ENDIAN   5u
 
#define SL_USBD_MICROSOFT_PROPERTY_TYPE_REG_LINK   6u
 
#define SL_USBD_MICROSOFT_PROPERTY_TYPE_REG_MULTI_SZ   7u
 
#define SL_USBD_ENDPOINT_INFO_TYPE_CTRL   0x01u
 
#define SL_USBD_ENDPOINT_INFO_TYPE_ISOC   0x02u
 
#define SL_USBD_ENDPOINT_INFO_TYPE_BULK   0x04u
 
#define SL_USBD_ENDPOINT_INFO_TYPE_INTR   0x08u
 
#define SL_USBD_ENDPOINT_INFO_DIR_OUT   0x10u
 
#define SL_USBD_ENDPOINT_INFO_DIR_IN   0x20u
 
#define SL_USBD_CONFIG_NBR_NONE   255u
 
#define SL_USBD_CONFIG_NBR_SPD_BIT   0x80u
 
#define SL_USBD_INTERFACE_NBR_NONE   255u
 
#define SL_USBD_ALT_INTERFACE_NBR_NONE   255u
 
#define SL_USBD_INTERFACE_GROUP_NBR_NONE   255u
 
#define SL_USBD_ENDPOINT_ADDR_NONE   255u
 
#define SL_USBD_ENDPOINT_PHY_NONE   255u
 
#define SL_USBD_ENDPOINT_NBR_NONE   255u
 
#define SL_USBD_CLASS_NBR_NONE   255u
 
#define USBD_CFG_STR_EN   1
 
#define USBD_CFG_MS_OS_DESC_EN   0
 
#define USBD_CFG_URB_EXTRA_EN   0
 
#define SL_USBD_URB_MAX_NBR   SL_USBD_OPEN_ENDPOINTS_QUANTITY
 
#define SL_USBD_CORE_EVENT_BUS_NBR   7u
 
#define SL_USBD_CORE_EVENT_BUS_NBR_TOTAL   (SL_USBD_CORE_EVENT_BUS_NBR * SL_USBD_DEVICE_QUANTITY)
 
#define SL_USBD_CORE_EVENT_ASYNC_NBR   ((SL_USBD_OPEN_ENDPOINTS_QUANTITY * SL_USBD_DEVICE_QUANTITY) + SL_USBD_EXTRA_URB_QUANTITY)
 
#define SL_USBD_CORE_EVENT_NBR_TOTAL   (SL_USBD_CORE_EVENT_BUS_NBR_TOTAL + SL_USBD_CORE_EVENT_ASYNC_NBR)
 
#define SL_USBD_FRAME_NBR_GET(frame_nbr)   ((frame_nbr) & SL_USBD_FRAME_NBR_MASK)
 
#define SL_USBD_MICROFRAME_NBR_GET(microframe_nbr)   ((microframe_nbr) >> 11u)
 
#define SL_USBD_FRAME_NBR_DIFF_GET(frame_nbr1, frame_nbr2)
 
#define SL_USBD_ENDPOINT_PHY_TO_ADDR(ep_phy_nbr)
 
#define SL_USBD_ENDPOINT_ADDR_TO_PHY(ep_addr)
 
#define SL_USBD_ENDPOINT_ADDR_TO_LOG(ep_addr)   (uint8_t)((ep_addr) & SL_USBD_ENDPOINT_NBR_MASK)
 
#define SL_USBD_ENDPOINT_PHY_TO_LOG(ep_phy_nbr)   (ep_phy_nbr / 2u)
 
#define SL_USBD_ENDPOINT_LOG_TO_ADDR_IN(ep_log_nbr)   ((ep_log_nbr) | SL_USBD_ENDPOINT_DIR_IN)
 
#define SL_USBD_ENDPOINT_LOG_TO_ADDR_OUT(ep_log_nbr)   ((ep_log_nbr) | SL_USBD_ENDPOINT_DIR_OUT)
 
#define SL_USBD_ENDPOINT_IS_IN(ep_addr)   ((((ep_addr) & SL_USBD_ENDPOINT_DIR_MASK) != 0u) ? true : false)

Typedefs

typedef void(* sl_usbd_async_function_t) (uint8_t ep_addr, void *p_buf, uint32_t buf_len, uint32_t xfer_len, void *p_arg, sl_status_t status)

Enumerations

enum  sl_usbd_device_speed_t {
  SL_USBD_DEVICE_SPEED_INVALID = 0u ,
  SL_USBD_DEVICE_SPEED_LOW ,
  SL_USBD_DEVICE_SPEED_FULL ,
  SL_USBD_DEVICE_SPEED_HIGH
}
 
enum  sl_usbd_device_state_t {
  SL_USBD_DEVICE_STATE_NONE = 0 ,
  SL_USBD_DEVICE_STATE_INIT ,
  SL_USBD_DEVICE_STATE_ATTACHED ,
  SL_USBD_DEVICE_STATE_DEFAULT ,
  SL_USBD_DEVICE_STATE_ADDRESSED ,
  SL_USBD_DEVICE_STATE_CONFIGURED ,
  SL_USBD_DEVICE_STATE_SUSPENDED
}
 
enum  sl_usbd_bus_event_t {
  SL_USBD_EVENT_BUS_CONNECT = 0 ,
  SL_USBD_EVENT_BUS_DISCONNECT ,
  SL_USBD_EVENT_BUS_RESET ,
  SL_USBD_EVENT_BUS_SUSPEND ,
  SL_USBD_EVENT_BUS_RESUME
}
 
enum  sl_usbd_config_event_t {
  SL_USBD_EVENT_CONFIG_SET = 0 ,
  SL_USBD_EVENT_CONFIG_UNSET
}
 CONFIG EVENT DATA TYPE.

Function Documentation

◆ sl_usbd_core_init()

sl_status_t sl_usbd_core_init ( void  )

Initialize the USB device stack. 

                                            sl_usbd_core_init()
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) sli_usbd_core_init_internals() MUST be called ... :
  • (a) ONLY ONCE from a product's application;
  • (b) With the following conditions:
    • (1) AFTER the product's OS has been initialized.
    • (2) BEFORE the product's application calls any USB device stack function(s).

◆ sl_usbd_core_start_device()

sl_status_t sl_usbd_core_start_device ( void  )

Start the device stack.

Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Device stack can be only started if the device is in one of the following states:
  • SL_USBD_DEVICE_STATE_NONE Device controller has not been initialized.
  • SL_USBD_DEVICE_STATE_INIT Device controller is already initialized.

◆ sl_usbd_core_stop_device()

sl_status_t sl_usbd_core_stop_device ( void  )

Stop the device stack.

Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_get_device_state()

sl_status_t sl_usbd_core_get_device_state ( sl_usbd_device_state_t *  p_dev_state)

Get the current device state.

Parameters
p_dev_statePointer to device state to be returned. Set to current device state, if no errors are returned, or SL_USBD_DEVICE_STATE_NONE, if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_get_device_speed()

sl_status_t sl_usbd_core_get_device_speed ( sl_usbd_device_speed_t *  p_dev_speed)

Get device speed.

Parameters
p_dev_speedPointer to the variable that will be set to device speed upon return. It will be set to current device speed, if successful, or SL_USBD_DEVICE_SPEED_INVALID, if unsuccessful.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_set_device_self_power()

sl_status_t sl_usbd_core_set_device_self_power ( bool  self_pwr)

Set the device's current power source.

Parameters
self_pwrThe power source of the device :
  • true device is self-powered.
  • false device is bus-powered.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_get_device_configuration()

sl_status_t sl_usbd_core_get_device_configuration ( sl_usbd_device_config_t **  p_dev_cfg)

Set the device's Microsoft vendor code.

Parameters
vendor_codeMicrosoft vendor code.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) The vendor code used MUST be different from any vendor bRequest value.

Get the device configuration.

Parameters
p_dev_cfgPointer to a variable of type (sl_usbd_device_config_t *) which will receive the memory address of device configuration structure upon return. The variable will be set to point to device configuration, if no errors are returned, or it will be set to NULL if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_get_device_frame_number()

sl_status_t sl_usbd_core_get_device_frame_number ( uint16_t *  p_frame_nbr)

Get the last frame number from the driver.

Parameters
p_frame_nbrPointer to variable that will receive frame number.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) The frame number will always be in the range of 0-2047 (11 bits).
(2) Frame number returned to the caller contains the frame and microframe numbers. It is encoded following this 16-bit format: 
*               | 15 | 14 | 13 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
*               |  0    0 |  microframe  |                  frame                     |
*
Caller must use the macros SL_USBD_FRAME_NBR_GET() or SL_USBD_MICROFRAME_NBR_GET() to get the frame or microframe number only.

◆ sl_usbd_core_add_configuration()

sl_status_t sl_usbd_core_add_configuration ( uint8_t  attrib,
uint16_t  max_pwr,
sl_usbd_device_speed_t  spd,
const char *  p_name,
uint8_t *  p_cfg_nbr 
)

Add a configuration attribute to the device.

Parameters
attribAvailable configuration attributes.
  • SL_USBD_DEV_ATTRIB_SELF_POWERED Power does not come from VBUS.
  • SL_USBD_DEV_ATTRIB_REMOTE_WAKEUP Remote wakeup feature enabled.
max_pwrBus power required for this device (see Note #1).
spdAvailable configuration speeds.
  • SL_USBD_DEVICE_SPEED_FULL Configuration is added in the full-speed configuration set.
p_namePointer to string describing the configuration (see Note #2).
p_cfg_nbrPointer to variable that will receive the configuration number. It will be set to the configuration number, if no errors are returned, otherwise it will be set to SL_USBD_CONFIG_NBR_NONE if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) USB spec 2.0 (section 7.2.1.3/4) defines power constraints for bus-powered devices: "A low-power function draws up to one unit load from the USB cable when operational" "A function is high-power if, when fully powered, draws over one, but no more than five, unit loads from the USB cable." A unit load is defined as 100mA, so 'max_pwr' argument should be between 0 mA and 500mA
(2) String support is optional: 'p_name' can be a NULL string pointer.
(3) Configuration can only be added when the device is in the following states:
  • SL_USBD_DEVICE_STATE_NONE Device controller has not been initialized.
  • SL_USBD_DEVICE_STATE_INIT Device controller is already initialized.

◆ sl_usbd_core_add_interface()

sl_status_t sl_usbd_core_add_interface ( uint8_t  cfg_nbr,
sl_usbd_class_driver_t *  p_class_drv,
void *  p_if_class_arg,
void *  p_if_alt_class_arg,
uint8_t  class_code,
uint8_t  class_sub_code,
uint8_t  class_protocol_code,
const char *  p_name,
uint8_t *  p_if_nbr 
)

Associate a configuration with its alternative-speed counterpart.

Parameters
config_nbrConfiguration number.
config_otherOther-speed configuration number.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Configurations from high- and full-speed can be associated with each other to provide comparable functionality regardless of speed.
(2) Configuration can ONLY be associated when the device is in the following states:
  • SL_USBD_DEVICE_STATE_NONE Device controller has not been initialized.
  • SL_USBD_DEVICE_STATE_INIT Device controller is already initialized.

Add an interface to a specific configuration.

Parameters
cfg_nbrConfiguration index to add the interface.
p_class_drvPointer to interface driver.
p_if_class_argPointer to interface driver argument.
p_if_alt_class_argPointer to alternate interface argument.
class_codeClass code assigned by the USB-IF.
class_sub_codeSubclass code assigned by the USB-IF.
class_protocol_codeprotocol code assigned by the USB-IF.
p_namePointer to string describing the Interface.
p_if_nbrPointer to a variable that will receive interface number after creation. The variable will be set to the interface number, if no errors are returned, otherwise it is set to SL_USBD_INTERFACE_NBR_NONE.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) USB Spec 2.0 Interface (section 9.6.5) states: "An interface may include alternate settings that allow the endpoints and/or their characteristics to be varied after the device has been configured. The default setting for an interface is always an alternate setting of zero."

◆ sl_usbd_core_add_alt_interface()

sl_status_t sl_usbd_core_add_alt_interface ( uint8_t  config_nbr,
uint8_t  if_nbr,
void *  p_class_arg,
const char *  p_name,
uint8_t *  p_if_alt_nbr 
)

Add an alternate setting to a specific interface.

Parameters
config_nbrConfiguration number.
if_nbrInterface number.
p_class_argPointer to alternate interface argument.
p_namePointer to alternate setting name.
p_if_alt_nbrPointer to variable that will receive alternate setting number upon return. It will be set to interface alternate setting number if no error(s) are returned, or SL_USBD_ALT_INTERFACE_NBR_NONE if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_add_interface_group()

sl_status_t sl_usbd_core_add_interface_group ( uint8_t  config_nbr,
uint8_t  class_code,
uint8_t  class_sub_code,
uint8_t  class_protocol_code,
uint8_t  if_start,
uint8_t  if_cnt,
const char *  p_name,
uint8_t *  p_if_grp_num 
)

Create an interface group.

Parameters
config_nbrConfiguration number.
class_codeClass code assigned by the USB-IF.
class_sub_codeSubclass code assigned by the USB-IF.
class_protocol_codeprotocol code assigned by the USB-IF.
if_startInterface number of the first interface that is associated with this group.
if_cntNumber of consecutive interfaces that are associated with this group.
p_namePointer to the string that describes the interface group.
p_if_grp_numPointer to the variable that will receive interface group number upon return. The variable is set to interface group number if no errors are returned, or SL_USBD_INTERFACE_GROUP_NBR_NONE if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_get_device_descriptor()

sl_status_t sl_usbd_core_get_device_descriptor ( uint8_t *  p_buf,
uint8_t  max_len,
uint8_t *  p_desc_len 
)

Get the device descriptor.

Parameters
p_bufPointer to the destination buffer.
max_lenMaximum number of bytes to write in destination buffer.
p_desc_lenPointer to a variable that will receive the actual size of the descriptor. The variable is set to number of bytes actually in the descriptor if no errors are returned, or set to 0 if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) This function should be used by drivers that supporting the standard requests auto-reply, (during the initialization process).

◆ sl_usbd_core_get_configuration_descriptor()

sl_status_t sl_usbd_core_get_configuration_descriptor ( uint8_t *  p_buf,
uint16_t  max_len,
uint8_t  config_ix,
uint16_t *  p_desc_len 
)

Get a configuration descriptor.

Parameters
p_bufPointer to the destination buffer.
max_lenMaximum number of bytes to write in the destination buffer.
config_ixIndex of the desired configuration descriptor.
p_desc_lenPointer to a variable that will receive the actual size of the descriptor. The variable is set to number of bytes actually in the descriptor if no errors are returned, or set to 0 if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) This function should be used by drivers supporting a standard request's auto-reply, during the initialization process.

◆ sl_usbd_core_get_string_descriptor()

sl_status_t sl_usbd_core_get_string_descriptor ( uint8_t *  p_buf,
uint8_t  max_len,
uint8_t  str_ix,
uint8_t *  p_desc_len 
)

Get a string descriptor.

Parameters
p_bufPointer to the destination buffer.
max_lenMaximum number of bytes to write in destination buffer.
str_ixIndex of the desired string descriptor.
p_desc_lenPointer to a variable that will receive the actual size of the descriptor. The variable is set to number of bytes actually in the descriptor if no errors are returned, or set to 0 if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) This function should be used by drivers supporting a standard request's auto-reply, during the initialization process.

◆ sl_usbd_core_add_string()

sl_status_t sl_usbd_core_add_string ( const char *  p_str)

Add string to USB device.

Parameters
p_strPointer to string to add (see Note #1).
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) USB spec 2.0 chapter 9.5 states: "Where appropriate, descriptors contain references to string descriptors that provide displayable information describing a descriptor in human-readable form. The inclusion of string descriptors is optional. However, the reference fields within descriptors are mandatory. If a device does not support string descriptors, string reference fields must be reset to zero to indicate no string descriptor is available". Since string descriptors are optional, 'p_str' could be a NULL pointer.

◆ sl_usbd_core_get_string_index()

sl_status_t sl_usbd_core_get_string_index ( const char *  p_str,
uint8_t *  p_str_ix 
)

Get string index corresponding to a given string.

Parameters
p_strPointer to string.
p_str_ixPointer to variable where string index will be returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_write_08b_to_descriptor_buf()

sl_status_t sl_usbd_core_write_08b_to_descriptor_buf ( uint8_t  val)

Write an 8-bit value to the descriptor buffer.

Parameters
val8-bit value to write in the descriptor buffer.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) USB classes may use this function to append class-specific descriptors to the configuration descriptor.

◆ sl_usbd_core_write_16b_to_descriptor_buf()

sl_status_t sl_usbd_core_write_16b_to_descriptor_buf ( uint16_t  val)

Write a 16-bit value in the descriptor buffer.

Parameters
val16-bit value.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) USB classes may use this function to append class-specific descriptors to the configuration descriptor.
(2) USB descriptors are in little-endian format.

◆ sl_usbd_core_write_24b_to_descriptor_buf()

sl_status_t sl_usbd_core_write_24b_to_descriptor_buf ( uint32_t  val)

Write a 24-bit value to the descriptor buffer.

Parameters
val32-bit value containing 24 useful bits to write in the descriptor buffer.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) USB classes may use this function to append class-specific descriptors to the configuration descriptor.
(2) USB descriptors are in little-endian format.

◆ sl_usbd_core_write_32b_to_descriptor_buf()

sl_status_t sl_usbd_core_write_32b_to_descriptor_buf ( uint32_t  val)

Write a 32-bit value to the descriptor buffer.

Parameters
val32-bit value to write in the descriptor buffer.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) USB classes may use this function to append class-specific descriptors to the configuration descriptor.
(2) USB descriptors are in little-endian format.

◆ sl_usbd_core_write_buf_to_descriptor_buf()

sl_status_t sl_usbd_core_write_buf_to_descriptor_buf ( const uint8_t *  p_buf,
uint16_t  len 
)

Write a buffer into the descriptor buffer.

Parameters
p_bufPointer to the buffer to write into the descriptor buffer.
lenLength of the buffer.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) USB classes may use this function to append class-specific descriptors to the configuration descriptor.

◆ sl_usbd_core_write_control_sync()

sl_status_t sl_usbd_core_write_control_sync ( void *  p_buf,
uint32_t  buf_len,
uint16_t  timeout_ms,
bool  end,
uint32_t *  p_xfer_len 
)

Send data on the Control IN endpoint.

Parameters
p_bufPointer to the buffer of data that will be sent (see Note #2).
buf_lenNumber of octets to transmit.
timeout_msTimeout in milliseconds.
endEnd-of-transfer flag (see Note #1).
p_xfer_lenPointer to a variable that will be set to the number of octets transmitted. The variable is set to the number of octets transmitted if no errors are returned, otherwise it is set to 0.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) If end-of-transfer is set and transfer length is multiple of maximum packet size, a zero-length packet is transferred to indicate a short transfer to the host.
(2) Transmit buffer must be 32 bits aligned.

◆ sl_usbd_core_read_control_sync()

sl_status_t sl_usbd_core_read_control_sync ( void *  p_buf,
uint32_t  buf_len,
uint16_t  timeout_ms,
uint32_t *  p_xfer_len 
)

Receive data on the Control OUT endpoint.

Parameters
p_bufPointer to the destination buffer to receive data (see Note #1).
buf_lenNumber of octets to receive.
timeout_msTimeout in milliseconds.
p_xfer_lenPointer to a variable that will be set to the number of octets received. The variable is set to the number of octets received if no errors are returned, otherwise it is set to 0.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Receive buffer must be 32 bits aligned.

◆ sl_usbd_core_add_bulk_endpoint()

sl_status_t sl_usbd_core_add_bulk_endpoint ( uint8_t  config_nbr,
uint8_t  if_nbr,
uint8_t  if_alt_nbr,
bool  dir_in,
uint16_t  max_pkt_len,
uint8_t *  p_ep_addr 
)

Add a bulk endpoint to alternate setting interface.

Parameters
config_nbrConfiguration number.
if_nbrInterface number.
if_alt_nbrInterface alternate setting number.
dir_inEndpoint direction.
  • true IN direction.
  • false OUT direction.
max_pkt_lenEndpoint maximum packet length (see Note #1)
p_ep_addrPointer to a variable that will receive the new endpoint address. The variable will be set to endpoint address if no errors are returned, otherwise it will be set to SL_USBD_ENDPOINT_ADDR_NONE.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) If the 'max_pkt_len' argument is '0', the stack will allocate the first available BULK endpoint, regardless its maximum packet size.

◆ sl_usbd_core_read_bulk_sync()

sl_status_t sl_usbd_core_read_bulk_sync ( uint8_t  ep_addr,
void *  p_buf,
uint32_t  buf_len,
uint16_t  timeout_ms,
uint32_t *  p_xfer_len 
)

Receive data on Bulk OUT endpoint.

Parameters
ep_addrEndpoint address.
p_bufPointer to the destination buffer to receive data (see Note #1).
buf_lenNumber of octets to receive.
timeout_msTimeout in milliseconds.
p_xfer_lenPointer to a variable that will be set to the number of octets received. The variable is set to the number of octets received if no errors are returned, otherwise it is set to 0.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Receive buffer must be 32 bits aligned.

◆ sl_usbd_core_read_bulk_async()

sl_status_t sl_usbd_core_read_bulk_async ( uint8_t  ep_addr,
void *  p_buf,
uint32_t  buf_len,
sl_usbd_async_function_t  async_fnct,
void *  p_async_arg 
)

Receive data on Bulk OUT endpoint asynchronously.

Parameters
ep_addrEndpoint address.
p_bufPointer to the destination buffer to receive data (see Note #1).
buf_lenNumber of octets to receive.
async_fnctFunction that will be invoked upon completion of receive operation.
p_async_argPointer to the argument that will be passed as parameter of 'async_fnct'.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Receive buffer must be 32 bits aligned.

◆ sl_usbd_core_write_bulk_sync()

sl_status_t sl_usbd_core_write_bulk_sync ( uint8_t  ep_addr,
void *  p_buf,
uint32_t  buf_len,
uint16_t  timeout_ms,
bool  end,
uint32_t *  p_xfer_len 
)

Send data on a Bulk IN endpoint.

Parameters
ep_addrEndpoint address.
p_bufPointer to buffer of data that will be transmitted (see Note #2).
buf_lenNumber of octets to transmit.
timeout_msTimeout in milliseconds.
endEnd-of-transfer flag (see Note #3).
p_xfer_lenPointer to a variable that will receive the number of octets transmitted. The variable is set to the number of octets transmitted if no errors are returned, otherwise it is set to 0.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) This function SHOULD NOT be called from interrupt service routine (ISR).
(2) Transmit buffer must be 32 bits aligned.
(3) If end-of-transfer is set and transfer length is multiple of maximum packet sizes, a zero-length packet is transferred to indicate a short transfer to the host.

◆ sl_usbd_core_write_bulk_async()

sl_status_t sl_usbd_core_write_bulk_async ( uint8_t  ep_addr,
void *  p_buf,
uint32_t  buf_len,
sl_usbd_async_function_t  async_fnct,
void *  p_async_arg,
bool  end 
)

Send data on the Bulk IN endpoint asynchronously.

Parameters
ep_addrEndpoint address.
p_bufPointer to the buffer of data that will be transmitted (see Note #1).
buf_lenNumber of octets to transmit.
async_fnctFunction that will be invoked upon completion of transmit operation.
p_async_argPointer to the argument that will be passed as parameter of 'async_fnct'.
endEnd-of-transfer flag (see Note #2).
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Transmit buffer must be 32 bits aligned.
(2) If end-of-transfer is set and transfer length is multiple of maximum packet size, a zero-length packet is transferred to indicate a short transfer to the host.

◆ sl_usbd_core_add_interrupt_endpoint()

sl_status_t sl_usbd_core_add_interrupt_endpoint ( uint8_t  config_nbr,
uint8_t  if_nbr,
uint8_t  if_alt_nbr,
bool  dir_in,
uint16_t  max_pkt_len,
uint16_t  interval,
uint8_t *  p_ep_addr 
)

Add an interrupt endpoint to an alternate setting interface.

Parameters
config_nbrConfiguration number.
if_nbrInterface number.
if_alt_nbrInterface alternate setting number.
dir_inEndpoint Direction.
  • true IN direction.
  • false OUT direction.
max_pkt_lenEndpoint maximum packet length. (see Note #1)
intervalEndpoint interval in frames or microframes.
p_ep_addrPointer to a variable that will receive the new endpoint address. The variable will be set to endpoint address if no errors are returned, otherwise it will be set to SL_USBD_ENDPOINT_ADDR_NONE.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) If the 'max_pkt_len' argument is '0', the stack will allocate the first available INTERRUPT endpoint, regardless its maximum packet size.

◆ sl_usbd_core_read_interrupt_sync()

sl_status_t sl_usbd_core_read_interrupt_sync ( uint8_t  ep_addr,
void *  p_buf,
uint32_t  buf_len,
uint16_t  timeout_ms,
uint32_t *  p_xfer_len 
)

Receive data on the Interrupt OUT endpoint.

Parameters
ep_addrEndpoint address.
p_bufPointer to the destination buffer to receive data (see Note #2).
buf_lenNumber of octets to receive.
timeout_msTimeout in milliseconds.
p_xfer_lenPointer to a variable that will be set to the number of octets received. The variable is set to the number of octets received if no errors are returned, otherwise it is set to 0.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) This function SHOULD NOT be called from interrupt service routine (ISR).
(2) Receive buffer must be 32 bits aligned.

◆ sl_usbd_core_read_interrupt_async()

sl_status_t sl_usbd_core_read_interrupt_async ( uint8_t  ep_addr,
void *  p_buf,
uint32_t  buf_len,
sl_usbd_async_function_t  async_fnct,
void *  p_async_arg 
)

Receive data on Interrupt OUT endpoint asynchronously.

Parameters
ep_addrEndpoint address.
p_bufPointer to the destination buffer to receive data (see Note #1).
buf_lenNumber of octets to receive.
async_fnctFunction that will be invoked upon completion of receive operation.
p_async_argPointer to argument that will be passed as parameter of 'async_fnct'.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Receive buffer must be 32 bits aligned.

◆ sl_usbd_core_write_interrupt_sync()

sl_status_t sl_usbd_core_write_interrupt_sync ( uint8_t  ep_addr,
void *  p_buf,
uint32_t  buf_len,
uint16_t  timeout_ms,
bool  end,
uint32_t *  p_xfer_len 
)

Send data on Interrupt IN endpoint.

Parameters
ep_addrEndpoint address.
p_bufPointer to the buffer of data that will be transmitted (see Note #2).
buf_lenNumber of octets to transmit.
timeout_msTimeout in milliseconds.
endEnd-of-transfer flag (see Note #3).
p_xfer_lenPointer to a variable that will be set to the number of octets transmitted. The variable is set to the number of octets transmitted if no errors are returned, otherwise it is set to 0.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) This function SHOULD NOT be called from interrupt service routine (ISR).
(2) Transmit buffer must be 32 bits aligned.
(3) If end-of-transfer is set and transfer length is multiple of maximum packet size, a zero-length packet is transferred to indicate a short transfer to the host.

◆ sl_usbd_core_write_interrupt_async()

sl_status_t sl_usbd_core_write_interrupt_async ( uint8_t  ep_addr,
void *  p_buf,
uint32_t  buf_len,
sl_usbd_async_function_t  async_fnct,
void *  p_async_arg,
bool  end 
)

Send data on the Interrupt IN endpoint asynchronously.

Parameters
ep_addrEndpoint address.
p_bufPointer to the buffer of data that will be transmitted (see Note #1).
buf_lenNumber of octets to transmit.
async_fnctFunction that will be invoked upon completion of transmit operation.
p_async_argPointer to the argument that will be passed as parameter of 'async_fnct'.
endEnd-of-transfer flag (see Note #2).
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Transmit buffer must be 32 bits aligned.
(2) If end-of-transfer is set and transfer length is multiple of maximum packet size, a zero-length packet is transferred to indicate a short transfer to the host.

◆ sl_usbd_core_endpoint_write_zlp()

sl_status_t sl_usbd_core_endpoint_write_zlp ( uint8_t  ep_addr,
uint16_t  timeout_ms 
)

Add an isochronous endpoint to alternate setting interface.

Parameters
config_nbrConfiguration number.
if_nbrInterface number.
if_alt_nbrInterface alternate setting number.
dir_inEndpoint Direction :
  • true, IN direction.
  • false, OUT direction.
attribIsochronous endpoint synchronization and usage type attributes.
max_pkt_lenEndpoint maximum packet length (see Note #1).
transaction_frameEndpoint transactions per (micro)frame (see Note #2).
intervalEndpoint interval in frames or microframes.
p_ep_addrPointer to a variable that will receive the new endpoint address. The variable will be set to endpoint address if no errors are returned, otherwise it will be set to SL_USBD_ENDPOINT_ADDR_NONE.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) If the 'max_pkt_len' argument is '0', the stack allocates the first available ISOCHRONOUS endpoint regardless of its maximum packet size.
(2) For full-speed endpoints, 'transaction_frame' must be set to 1 since there is no support for high-bandwidth endpoints.
(3) For full-/high-speed isochronous endpoints, bInterval value must be in the range from 1 to 16. The bInterval value is used as the exponent for a 2^(bInterval-1) value. Maximum polling interval value is 2^(16-1) = 32768 frames in full-speed and 32768 microframes (i.e., 4096 frames) in high-speed.

Receive data on an isochronous OUT endpoint asynchronously.

Parameters
ep_addrEndpoint address.
p_bufPointer to the destination buffer to receive data (see Note #1).
buf_lenNumber of octets to receive.
async_fnctFunction that will be invoked upon completion of a receive operation.
p_async_argPointer to the argument that will be passed as parameter of 'async_fnct'.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Receive buffer must be 32 bits aligned.

Send data on an isochronous IN endpoint asynchronously.

Parameters
ep_addrEndpoint address.
p_bufPointer to the buffer of data that will be transmitted (see Note #1).
buf_lenNumber of octets to transmit.
async_fnctFunction that will be invoked upon completion of transmit operation.
p_async_argPointer to the argument that will be passed as parameter of 'async_fnct'.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Transmit buffer must be 32 bits aligned.

Set synchronization feedback rate on synchronization isochronous endpoint.

Parameters
config_nbrConfiguration number.
if_nbrInterface number.
if_alt_nbrInterface alternate setting number.
synch_ep_addrSynchronization endpoint address.
sync_refreshExponent of synchronization feedback rate (see Note #3).
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Synchronization endpoints can ONLY be associated when the device is in the following states:
  • SL_USBD_DEVICE_STATE_NONE Device controller has not been initialized.
  • SL_USBD_DEVICE_STATE_INIT Device controller is already initialized.
(2) For audio class 1.0, the interface class code must be SL_USBD_CLASS_CODE_AUDIO and protocol 'zero'
(3) If explicit synchronization mechanism is needed to maintain synchronization during transfers, the information carried over the synchronization path must be available every 2 ^ (10 - P) frames, with P ranging from 1 to 9 (512 ms down to 2 ms).
(4) Table 4-22 "Standard AS Isochronous Synch Endpoint Descriptor" of Audio 1.0 specification indicates for bmAttributes field no usage type for bits 5..4. But USB 2.0 specification, Table 9-13 "Standard Endpoint Descriptor" indicates several types of usage. When an explicit feedback is defined for a asynchronous isochronous endpoint, the associated synch feedback should use the Usage type 'Feedback endpoint'.

Associate synchronization endpoint to isochronous endpoint.

Parameters
config_nbrConfiguration number.
if_nbrInterface number.
if_alt_nbrInterface alternate setting number.
data_ep_addrData endpoint address.
sync_addrAssociated synchronization endpoint.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Synchronization endpoints can ONLY be associated when the device is in the following states:
  • SL_USBD_DEVICE_STATE_NONE Device controller has not been initialized.
  • SL_USBD_DEVICE_STATE_INIT Device controller is already initialized.
(2) For audio class 1.0, interface class code must be SL_USBD_CLASS_CODE_AUDIO and protocol 'zero'.

Send zero-length packet to the host.

Parameters
ep_addrEndpoint address.
timeout_msTimeout in milliseconds.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) This function should only be called during a synchronous transfer.

◆ sl_usbd_core_endpoint_read_zlp()

sl_status_t sl_usbd_core_endpoint_read_zlp ( uint8_t  ep_addr,
uint16_t  timeout_ms 
)

Receive zero-length packet from the host.

Parameters
ep_addrEndpoint address.
timeout_msTimeout in milliseconds.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) This function should only be called during a synchronous transfer.

◆ sl_usbd_core_abort_endpoint()

sl_status_t sl_usbd_core_abort_endpoint ( uint8_t  ep_addr)

Abort I/O transfer on the endpoint.

Parameters
ep_addrEndpoint address.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_endpoint_read_complete()

sl_status_t sl_usbd_core_endpoint_read_complete ( uint8_t  ep_log_nbr)

Notify USB stack that packet receive has completed.

Parameters
ep_log_nbrEndpoint logical number.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_endpoint_write_complete()

sl_status_t sl_usbd_core_endpoint_write_complete ( uint8_t  ep_log_nbr)

Notify USB stack that packet transmit has completed.

Parameters
ep_log_nbrEndpoint logical number.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_endpoint_write_complete_extended()

sl_status_t sl_usbd_core_endpoint_write_complete_extended ( uint8_t  ep_log_nbr,
sl_status_t  xfer_err 
)

Notify USB stack that packet transmit has completed (see Note #1).

Parameters
ep_log_nbrEndpoint logical number.
xfer_errError code returned by the USB driver.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) This function is an alternative to the function sl_usbd_core_endpoint_write_complete() so that a USB device driver can return to the core an error code upon the Tx transfer completion.

◆ sl_usbd_core_stall_endpoint()

sl_status_t sl_usbd_core_stall_endpoint ( uint8_t  ep_addr,
bool  state 
)

Stall the non-control endpoint.

Parameters
ep_addrEndpoint address.
stateEndpoint stall state.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_is_endpoint_stalled()

sl_status_t sl_usbd_core_is_endpoint_stalled ( uint8_t  ep_addr,
bool *  p_ep_stall 
)

Get the stall status of a non-control endpoint.

Parameters
ep_addrEndpoint address.
p_ep_stallPointer to a boolean that will receive the endpoint stalled status. The boolean variable is set to true if endpoint is stalled, or is set to false if endpoint is not stalled.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_get_max_endpoint_packet_size()

sl_status_t sl_usbd_core_get_max_endpoint_packet_size ( uint8_t  ep_addr,
uint16_t *  p_max_size 
)

Retrieve the endpoint maximum packet size.

Parameters
ep_addrEndpoint address.
p_max_sizePointer to a variable that will receive the maximum packet size upon return. The variable is set to the maximum packet size if no errors are returned, otherwise it is set to 0.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_core_get_max_phy_endpoint_number()

sl_status_t sl_usbd_core_get_max_phy_endpoint_number ( uint8_t *  p_ep_phy_nbr)

Get the maximum physical endpoint number.

Parameters
p_ep_phy_nbrPointer to variable where maximum physical endpoint number will be returned. If no errors are returned, the variable will be set to maximum physical endpoint number, otherwise it will be set to SL_USBD_ENDPOINT_PHY_NONE.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

Macro Definition Documentation

◆ SL_USBD_FRAME_NBR_MAX

#define SL_USBD_FRAME_NBR_MAX   2047u 
                                              FRAME

Note(s) : (1) Section 8.3.3 of USB spec 2.0 describes the frame number as: "The frame number field is an 11-bit field that is incremented by the host on a per-frame basis. The frame number field rolls over upon reaching its maximum value of 7FFH and is sent only in SOF tokens at the start of each (micro)frame."

◆ SL_USBD_REQ_DIR_MASK

#define SL_USBD_REQ_DIR_MASK   0x80u 
                                  REQUEST CHARACTERISTICS

Note(s) : (1) Request types are defined in USB spec 2.0, section 9.3, Table 9-2, 'RequestType' field.

◆ SL_USBD_REQ_GET_STATUS

#define SL_USBD_REQ_GET_STATUS   0u 
                                      STANDARD REQUESTS

Note(s) : (1) Request types are defined in USB spec 2.0, section 9.4, Table 9-4, 'RequestType' field.

◆ SL_USBD_DESC_TYPE_DEVICE

#define SL_USBD_DESC_TYPE_DEVICE   1u 
                                      DESCRIPTOR TYPES

Note(s) : (1) Descriptors types are defined in the USB spec 2.0 section 9.2.6, Table 9-5.

◆ SL_USBD_LANG_ID_ARABIC_SAUDI_ARABIA

#define SL_USBD_LANG_ID_ARABIC_SAUDI_ARABIA   0x0401u 
                                      LANGUAGE IDENTIFIERS

Note(s) : (1) Languages identifier are defined in "http://www.usb.org/developers/docs/USB_LANGIDs.pdf".

◆ SL_USBD_CLASS_CODE_USE_IF_DESC

#define SL_USBD_CLASS_CODE_USE_IF_DESC   0x00u 
                                          CLASS CODES

Note(s) : (1) Class codes are defined in "http://www.usb.org/developers/defined_class". 

      (2) Class code information can be placed in the Device descriptor or in the Interface
          descriptor. Some defined class code are allowed to be used only in the Device
          descriptor, others can used in both Device and Interface descriptors and come can
          only be used in Interface Descriptors.

      (3) Subclass & protocol codes are defined in the relevant class drivers.

◆ SL_USBD_FRAME_NBR_DIFF_GET

#define SL_USBD_FRAME_NBR_DIFF_GET (   frame_nbr1,
  frame_nbr2 
)
Value:
(((frame_nbr2) >= (frame_nbr1)) \
? ((frame_nbr2) - (frame_nbr1)) \
: ((SL_USBD_FRAME_NBR_MAX + 1u + (frame_nbr2)) - (frame_nbr1)))
SL_USBD_FRAME_NBR_MAX
#define SL_USBD_FRAME_NBR_MAX
Definition: sl_usbd_core.h:72

◆ SL_USBD_ENDPOINT_PHY_TO_ADDR

#define SL_USBD_ENDPOINT_PHY_TO_ADDR (   ep_phy_nbr)
Value:
( ((ep_phy_nbr) / 2u) \
| (((ep_phy_nbr) % 2u) ? SL_USBD_ENDPOINT_DIR_BIT : 0x00u))

◆ SL_USBD_ENDPOINT_ADDR_TO_PHY

#define SL_USBD_ENDPOINT_ADDR_TO_PHY (   ep_addr)
Value:
((((ep_addr) & SL_USBD_ENDPOINT_NBR_MASK) * 2u) \
+ ((((ep_addr) & SL_USBD_ENDPOINT_DIR_MASK) != 0u) ? 1u : 0u))

Enumeration Type Documentation

◆ sl_usbd_device_speed_t

enum sl_usbd_device_speed_t 
                                  USB DEVICE SPEED DATA TYPE
Note
(1) 'Universal Serial Bus Specification Rev 2.0', section 4.2.1 defines three data rates:
  • (a) The USB Low-Speed (LS) signaling bit rate is 1.5 Mb/s.
  • (b) The USB Full-Speed (FS) signaling bit rate is 12 Mb/s.
  • (c) The USB High-Speed (HS) signaling bit rate is 480 Mb/s.
Enumerator
SL_USBD_DEVICE_SPEED_LOW 

Low-Speed (see Note #1a).

SL_USBD_DEVICE_SPEED_FULL 

Full-Speed (see Note #1b).

SL_USBD_DEVICE_SPEED_HIGH 

High-Speed (see Note #1c).

◆ sl_usbd_device_state_t

enum sl_usbd_device_state_t 
                                  USB DEVICE STATES DATA TYPE
Note
(1) 'Universal Serial Bus Specification Rev 2.0', section 9.1.1 defines seven visible device states:
  • (a) SL_USBD_DEVICE_STATE_INIT : Device is not attached to the USB.
  • (b) SL_USBD_DEVICE_STATE_ATTACHED : Device is attached to the USB, but not powered.
  • (c) USBD_DEV_STATE_POWERED : Device is attached to the USB and powered, but has not been reset.
  • (d) SL_USBD_DEVICE_STATE_DEFAULT : Device is attached to the USB and powered and has been reset, but has not been assigned a unique address. Device responds at the default address.
  • (e) SL_USBD_DEVICE_STATE_ADDRESSED : Device is attached to the USB, powered, has been reset, and a unique device address has been assigned. Device is not configured.
  • (f) SL_USBD_DEVICE_STATE_CONFIGURED : Device is attached to the USB, powered, has been reset, has a unique address, is configured, and is not suspended. The host may now use the function provided by the device.
  • (g) SL_USBD_DEVICE_STATE_SUSPENDED : Device is, at minimum, attached to the USB and is powered and has not seen bus activity for 3 ms. It may also have a unique address and be configured for use. However, because the device is suspended, the host may not use the device's function.
(2) An additional state is added (USBD_DEV_STATE_START) to determine if the device controller has been initialized.

◆ sl_usbd_config_event_t

enum sl_usbd_config_event_t

CONFIG EVENT DATA TYPE.