USB Device Core API#
USB Device Core API.
Modules#
Enumerations#
DATA TYPES.
BUS EVENT DATA TYPE.
CONFIG EVENT DATA TYPE.
Typedefs#
EP ASYNCHRONOUS CALLBACK API.
Functions#
FUNCTION PROTOTYPES.
Start the device stack.
Stop the device stack.
Get the current device state.
Get device speed.
Set the device's current power source.
Set the device's Microsoft vendor code.
Get the last frame number from the driver.
Add a configuration attribute to the device.
Associate a configuration with its alternative-speed counterpart.
Add an alternate setting to a specific interface.
Create an interface group.
Get the device descriptor.
Get a configuration descriptor.
Get a string descriptor.
Add string to USB device.
Get string index corresponding to a given string.
Write an 8-bit value to the descriptor buffer.
Write a 16-bit value in the descriptor buffer.
Write a 24-bit value to the descriptor buffer.
Write a 32-bit value to the descriptor buffer.
Write a buffer into the descriptor buffer.
Send data on the Control IN endpoint.
Receive data on the Control OUT endpoint.
Add a bulk endpoint to alternate setting interface.
Receive data on Bulk OUT endpoint.
Receive data on Bulk OUT endpoint asynchronously.
Send data on a Bulk IN endpoint.
Send data on the Bulk IN endpoint asynchronously.
Add an interrupt endpoint to an alternate setting interface.
Receive data on the Interrupt OUT endpoint.
Receive data on Interrupt OUT endpoint asynchronously.
Send data on Interrupt IN endpoint.
Send data on the Interrupt IN endpoint asynchronously.
Add an isochronous endpoint to alternate setting interface.
Receive zero-length packet from the host.
Abort I/O transfer on the endpoint.
Notify USB stack that packet receive has completed.
Notify USB stack that packet transmit has completed.
Notify USB stack that packet transmit has completed (see Note #1).
Stall the non-control endpoint.
Get the stall status of a non-control endpoint.
Retrieve the endpoint maximum packet size.
Get the maximum physical endpoint number.
Macros#
MODULE.
CONFIGURATION ATTRIBUTES.
DEVICE DESCRIPTOR LENGTH.
SUB-CLASS CODES.
PROTOCOL CODES.
FEATURE SELECTORS.
DEVICE POWER CONSTRAINS.
ENDPOINT TYPE.
ENDPOINT ADDRESS.
MICROSOFT OS DESCRIPTOR DEFINES.
USB EP INFORMATION TABLE DEFINES.
USB OBJECT NUMBER.
USB DEFAULT CONFIGS.
USB CORE EVENTS.
GLOBAL CONSTANTS.
ENDPOINT CONVERSION MACROS.
Enumeration Documentation#
sl_usbd_device_speed_t#
sl_usbd_device_speed_t
DATA TYPES.
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_INVALID | |
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). |
414
of file protocol/usb/inc/sl_usbd_core.h
sl_usbd_device_state_t#
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.
Enumerator | |
---|---|
SL_USBD_DEVICE_STATE_NONE | |
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 |
448
of file protocol/usb/inc/sl_usbd_core.h
sl_usbd_bus_event_t#
sl_usbd_bus_event_t
BUS EVENT DATA TYPE.
Enumerator | |
---|---|
SL_USBD_EVENT_BUS_CONNECT | |
SL_USBD_EVENT_BUS_DISCONNECT | |
SL_USBD_EVENT_BUS_RESET | |
SL_USBD_EVENT_BUS_SUSPEND | |
SL_USBD_EVENT_BUS_RESUME |
462
of file protocol/usb/inc/sl_usbd_core.h
sl_usbd_config_event_t#
sl_usbd_config_event_t
CONFIG EVENT DATA TYPE.
Enumerator | |
---|---|
SL_USBD_EVENT_CONFIG_SET | |
SL_USBD_EVENT_CONFIG_UNSET |
474
of file protocol/usb/inc/sl_usbd_core.h
Typedef Documentation#
sl_usbd_async_function_t#
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) )(uint8_t ep_addr, void *p_buf, uint32_t buf_len, uint32_t xfer_len, void *p_arg, sl_status_t status)
EP ASYNCHRONOUS CALLBACK API.
588
of file protocol/usb/inc/sl_usbd_core.h
Function Documentation#
sl_usbd_core_init#
sl_status_t sl_usbd_core_init (void )
FUNCTION PROTOTYPES.
N/A |
CONFIGURATION OVERRIDE FUNCTIONS USBD CORE FUNCTIONS
Note(s) : (1) USB Spec 2.0, Section 5.5 states "Control transfers allow access to different parts of a device. Control transfers are intended to support configuration/command/status type communication flows between client software and its function".
(a) "Each USB device is required to implement the Default Control Pipe as a message pipe. This pipe is used by the USB System Software. The Default Control Pipe provides access to the USB device's configuration, status, and control information".
The 'sl_usbd_core_ep_XXXX()' functions perform operations in the default endpoint. Class drivers should use 'sl_usbd_core_ep_XXXX()' to send/receive class specific requests.
sl_usbd_core_init()
Initialize the USB device stack.
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).
685
of file protocol/usb/inc/sl_usbd_core.h
sl_usbd_core_start_device#
sl_status_t sl_usbd_core_start_device (void )
Start the device stack.
N/A |
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.
696
of file protocol/usb/inc/sl_usbd_core.h
sl_usbd_core_stop_device#
sl_status_t sl_usbd_core_stop_device (void )
Stop the device stack.
N/A |
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
703
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | p_dev_state | Pointer 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.
714
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | p_dev_speed | Pointer 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.
725
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | self_pwr | The power source of the device :
|
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
736
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | p_dev_cfg | Pointer 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.
Note
(1) The vendor code used MUST be different from any vendor bRequest value.
Get the device configuration.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
761
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | p_frame_nbr | Pointer 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.
781
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | attrib | Available configuration attributes.
|
N/A | max_pwr | Bus power required for this device (see Note #1). |
N/A | spd | Available configuration speeds.
|
N/A | p_name | Pointer to string describing the configuration (see Note #2). |
N/A | p_cfg_nbr | Pointer 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.
816
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | cfg_nbr | Configuration index to add the interface. |
N/A | p_class_drv | Pointer to interface driver. |
N/A | p_if_class_arg | Pointer to interface driver argument. |
N/A | p_if_alt_class_arg | Pointer to alternate interface argument. |
N/A | class_code | Class code assigned by the USB-IF. |
N/A | class_sub_code | Subclass code assigned by the USB-IF. |
N/A | class_protocol_code | protocol code assigned by the USB-IF. |
N/A | p_name | Pointer to string describing the Interface. |
N/A | p_if_nbr | Pointer 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) 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.
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."
873
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | config_nbr | Configuration number. |
N/A | if_nbr | Interface number. |
N/A | p_class_arg | Pointer to alternate interface argument. |
N/A | p_name | Pointer to alternate setting name. |
N/A | p_if_alt_nbr | Pointer 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.
900
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | config_nbr | Configuration number. |
N/A | class_code | Class code assigned by the USB-IF. |
N/A | class_sub_code | Subclass code assigned by the USB-IF. |
N/A | class_protocol_code | protocol code assigned by the USB-IF. |
N/A | if_start | Interface number of the first interface that is associated with this group. |
N/A | if_cnt | Number of consecutive interfaces that are associated with this group. |
N/A | p_name | Pointer to the string that describes the interface group. |
N/A | p_if_grp_num | Pointer 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.
929
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | p_buf | Pointer to the destination buffer. |
N/A | max_len | Maximum number of bytes to write in destination buffer. |
N/A | p_desc_len | Pointer 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).
954
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | p_buf | Pointer to the destination buffer. |
N/A | max_len | Maximum number of bytes to write in the destination buffer. |
N/A | config_ix | Index of the desired configuration descriptor. |
N/A | p_desc_len | Pointer 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.
976
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | p_buf | Pointer to the destination buffer. |
N/A | max_len | Maximum number of bytes to write in destination buffer. |
N/A | str_ix | Index of the desired string descriptor. |
N/A | p_desc_len | Pointer 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.
1000
of file protocol/usb/inc/sl_usbd_core.h
sl_usbd_core_add_string#
sl_status_t sl_usbd_core_add_string (const char * p_str)
Add string to USB device.
N/A | p_str | Pointer 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.
1022
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | p_str | Pointer to string. |
N/A | p_str_ix | Pointer to variable where string index will be returned. |
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
1035
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | val | 8-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.
1049
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | val | 16-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.
1063
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | val | 32-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.
1077
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | val | 32-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.
1091
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | p_buf | Pointer to the buffer to write into the descriptor buffer. |
N/A | len | Length 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.
1105
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | p_buf | Pointer to the buffer of data that will be sent (see Note #2). |
N/A | buf_len | Number of octets to transmit. |
N/A | timeout_ms | Timeout in milliseconds. |
N/A | end | End-of-transfer flag (see Note #1). |
N/A | p_xfer_len | Pointer 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.
1130
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | p_buf | Pointer to the destination buffer to receive data (see Note #1). |
N/A | buf_len | Number of octets to receive. |
N/A | timeout_ms | Timeout in milliseconds. |
N/A | p_xfer_len | Pointer 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.
1153
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | config_nbr | Configuration number. |
N/A | if_nbr | Interface number. |
N/A | if_alt_nbr | Interface alternate setting number. |
N/A | dir_in | Endpoint direction.
|
N/A | max_pkt_len | Endpoint maximum packet length (see Note #1) |
N/A | p_ep_addr | Pointer 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.
1182
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | ep_addr | Endpoint address. |
N/A | p_buf | Pointer to the destination buffer to receive data (see Note #1). |
N/A | buf_len | Number of octets to receive. |
N/A | timeout_ms | Timeout in milliseconds. |
N/A | p_xfer_len | Pointer 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.
1208
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | ep_addr | Endpoint address. |
N/A | p_buf | Pointer to the destination buffer to receive data (see Note #1). |
N/A | buf_len | Number of octets to receive. |
N/A | async_fnct | Function that will be invoked upon completion of receive operation. |
N/A | p_async_arg | Pointer 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.
1231
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | ep_addr | Endpoint address. |
N/A | p_buf | Pointer to buffer of data that will be transmitted (see Note #2). |
N/A | buf_len | Number of octets to transmit. |
N/A | timeout_ms | Timeout in milliseconds. |
N/A | end | End-of-transfer flag (see Note #3). |
N/A | p_xfer_len | Pointer 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.
1263
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | ep_addr | Endpoint address. |
N/A | p_buf | Pointer to the buffer of data that will be transmitted (see Note #1). |
N/A | buf_len | Number of octets to transmit. |
N/A | async_fnct | Function that will be invoked upon completion of transmit operation. |
N/A | p_async_arg | Pointer to the argument that will be passed as parameter of 'async_fnct'. |
N/A | end | End-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.
1292
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | config_nbr | Configuration number. |
N/A | if_nbr | Interface number. |
N/A | if_alt_nbr | Interface alternate setting number. |
N/A | dir_in | Endpoint Direction.
|
N/A | max_pkt_len | Endpoint maximum packet length. (see Note #1) |
N/A | interval | Endpoint interval in frames or microframes. |
N/A | p_ep_addr | Pointer 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.
1325
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | ep_addr | Endpoint address. |
N/A | p_buf | Pointer to the destination buffer to receive data (see Note #2). |
N/A | buf_len | Number of octets to receive. |
N/A | timeout_ms | Timeout in milliseconds. |
N/A | p_xfer_len | Pointer 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.
1354
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | ep_addr | Endpoint address. |
N/A | p_buf | Pointer to the destination buffer to receive data (see Note #1). |
N/A | buf_len | Number of octets to receive. |
N/A | async_fnct | Function that will be invoked upon completion of receive operation. |
N/A | p_async_arg | Pointer 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.
1377
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | ep_addr | Endpoint address. |
N/A | p_buf | Pointer to the buffer of data that will be transmitted (see Note #2). |
N/A | buf_len | Number of octets to transmit. |
N/A | timeout_ms | Timeout in milliseconds. |
N/A | end | End-of-transfer flag (see Note #3). |
N/A | p_xfer_len | Pointer 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.
1409
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | ep_addr | Endpoint address. |
N/A | p_buf | Pointer to the buffer of data that will be transmitted (see Note #1). |
N/A | buf_len | Number of octets to transmit. |
N/A | async_fnct | Function that will be invoked upon completion of transmit operation. |
N/A | p_async_arg | Pointer to the argument that will be passed as parameter of 'async_fnct'. |
N/A | end | End-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.
1438
of file protocol/usb/inc/sl_usbd_core.h
sl_usbd_core_endpoint_write_zlp#
sl_status_t sl_usbd_core_endpoint_write_zlp (uint8_t ep_addr, uint16_t timeout_ms, if_alt_nbr, dir_in, attrib, max_pkt_len, transaction_frame, interval, p_ep_addr)
Add an isochronous endpoint to alternate setting interface.
N/A | ep_addr | Endpoint address. |
N/A | timeout_ms | Timeout in milliseconds. |
N/A | if_alt_nbr | Interface alternate setting number. |
N/A | dir_in | Data endpoint address. |
N/A | attrib | Associated synchronization endpoint. |
N/A | max_pkt_len | Endpoint maximum packet length (see Note #1). |
N/A | transaction_frame | Endpoint transactions per (micro)frame (see Note #2). |
N/A | interval | Endpoint interval in frames or microframes. |
N/A | p_ep_addr | Pointer 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.
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.
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.
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.
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.
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.
1630
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | ep_addr | Endpoint address. |
N/A | timeout_ms | Timeout 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.
1644
of file protocol/usb/inc/sl_usbd_core.h
sl_usbd_core_abort_endpoint#
sl_status_t sl_usbd_core_abort_endpoint (uint8_t ep_addr)
Abort I/O transfer on the endpoint.
N/A | ep_addr | Endpoint address. |
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
1654
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | ep_log_nbr | Endpoint logical number. |
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
1663
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | ep_log_nbr | Endpoint logical number. |
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
1672
of file protocol/usb/inc/sl_usbd_core.h
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).
N/A | ep_log_nbr | Endpoint logical number. |
N/A | xfer_err | Error 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.
1686
of file protocol/usb/inc/sl_usbd_core.h
sl_usbd_core_stall_endpoint#
sl_status_t sl_usbd_core_stall_endpoint (uint8_t ep_addr, bool state)
Stall the non-control endpoint.
N/A | ep_addr | Endpoint address. |
N/A | state | Endpoint stall state. |
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
1698
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | ep_addr | Endpoint address. |
N/A | p_ep_stall | Pointer 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.
1712
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | ep_addr | Endpoint address. |
N/A | p_max_size | Pointer 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.
1726
of file protocol/usb/inc/sl_usbd_core.h
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.
N/A | p_ep_phy_nbr | Pointer 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.
1738
of file protocol/usb/inc/sl_usbd_core.h
sl_usbd_core_get_max_open_endpoint_number#
sl_status_t sl_usbd_core_get_max_open_endpoint_number (uint8_t * p_nbr_open)
N/A | p_nbr_open |
1740
of file protocol/usb/inc/sl_usbd_core.h
sl_usbd_on_bus_event#
__WEAK void sl_usbd_on_bus_event (sl_usbd_bus_event_t event)
N/A | event |
1743
of file protocol/usb/inc/sl_usbd_core.h
sl_usbd_on_config_event#
__WEAK void sl_usbd_on_config_event (sl_usbd_config_event_t event, uint8_t config_nbr)
N/A | event | |
N/A | config_nbr |
1745
of file protocol/usb/inc/sl_usbd_core.h