|
enum | rtos_usb_packet_type_t { rtos_usb_data_packet
, rtos_usb_setup_packet
, rtos_usb_sof_packet
} |
|
|
int | rtos_usb_endpoint_ready (rtos_usb_t *ctx, uint32_t endpoint_addr, unsigned timeout) |
|
XUD_Result_t | rtos_usb_all_endpoints_ready (rtos_usb_t *ctx, unsigned timeout) |
|
XUD_Result_t | rtos_usb_endpoint_transfer_start (rtos_usb_t *ctx, uint32_t endpoint_addr, uint8_t *buffer, size_t len) |
|
XUD_BusSpeed_t | rtos_usb_endpoint_reset (rtos_usb_t *ctx, uint32_t endpoint_addr) |
|
void | rtos_usb_start (rtos_usb_t *ctx, size_t endpoint_count, XUD_EpType endpoint_out_type[], XUD_EpType endpoint_in_type[], XUD_BusSpeed_t speed, XUD_PwrConfig power_source, unsigned interrupt_core_id, int sof_interrupt_core_id) |
|
void | rtos_usb_init (rtos_usb_t *ctx, uint32_t io_core_mask, rtos_usb_isr_cb_t isr_cb, void *isr_app_data) |
|
XUD_Result_t | rtos_usb_simple_transfer_complete (rtos_usb_t *ctx, uint32_t endpoint_addr, size_t *len, unsigned timeout) |
|
void | rtos_usb_simple_init (rtos_usb_t *ctx, uint32_t io_core_mask) |
|
#define | RTOS_USB_OUT_EP 0 |
|
#define | RTOS_USB_IN_EP 1 |
|
The public API for using the RTOS USB driver.
◆ RTOS_USB_ENDPOINT_COUNT_MAX
#define RTOS_USB_ENDPOINT_COUNT_MAX 12 |
The maximum number of USB endpoint numbers supported by the RTOS USB driver.
◆ RTOS_USB_ISR_CALLBACK_ATTR
#define RTOS_USB_ISR_CALLBACK_ATTR __attribute__((fptrgroup("rtos_usb_isr_cb_fptr_grp"))) |
This attribute must be specified on the RTOS USB interrupt callback function provided by the application.
◆ RTOS_USB_OUT_EP
#define RTOS_USB_OUT_EP 0 |
This is used to index into the second dimension of many of the RTOS USB driver's endpoint arrays.
◆ rtos_usb_isr_cb_t
typedef void(* rtos_usb_isr_cb_t) (rtos_usb_t *ctx, void *app_data, uint32_t ep_address, size_t xfer_len, rtos_usb_packet_type_t packet_type, XUD_Result_t res) |
Function pointer type for application provided RTOS USB interrupt callback function.
This callback function is called when there is a USB transfer interrupt.
- Parameters
-
ctx | A pointer to the associated USB driver instance. |
app_data | A pointer to application specific data provided by the application. Used to share data between this callback function and the application. |
ep_address | The address of the USB endpoint that the transfer has completed on. |
xfer_len | The length of the data transferred. |
packet_type | The type of packet transferred. See rtos_usb_packet_type_t. |
res | The result of the transfer. See XUD_Result_t. |
◆ rtos_usb_t
Typedef to the RTOS USB driver instance struct.
◆ rtos_usb_all_endpoints_ready()
XUD_Result_t rtos_usb_all_endpoints_ready |
( |
rtos_usb_t * |
ctx, |
|
|
unsigned |
timeout |
|
) |
| |
Checks to see if all endpoints are ready to use.
- Parameters
-
ctx | A pointer to the USB driver instance to use. |
timeout | The maximum amount of time to wait for all endpoints to become ready before returning. |
- Return values
-
XUD_RES_OKAY | if all the endpoints are ready to use. |
XUD_RES_ERR | if not all the endpoints are ready to use. |
◆ rtos_usb_endpoint_ready()
int rtos_usb_endpoint_ready |
( |
rtos_usb_t * |
ctx, |
|
|
uint32_t |
endpoint_addr, |
|
|
unsigned |
timeout |
|
) |
| |
Checks to see if a particular endpoint is ready to use.
- Parameters
-
ctx | A pointer to the USB driver instance to use. |
endpoint_addr | The address of the endpoint to check. |
timeout | The maximum amount of time to wait for the endpoint to become ready before returning. |
- Return values
-
XUD_RES_OKAY | if the endpoint is ready to use. |
XUD_RES_ERR | if the endpoint is not ready to use. |
◆ rtos_usb_endpoint_reset()
XUD_BusSpeed_t rtos_usb_endpoint_reset |
( |
rtos_usb_t * |
ctx, |
|
|
uint32_t |
endpoint_addr |
|
) |
| |
This function will complete a reset on an endpoint. The address of the endpoint to reset must be provided, and may be either direction (IN or OUT) endpoint. If there is an associated endpoint of the opposite direction, however, it will also be reset.
The return value should be inspected to find the new bus-speed.
- Parameters
-
endpoint_addr | IN or OUT endpoint address to reset. |
- Return values
-
XUD_SPEED_HS | the host has accepted that this device can execute at high speed. |
XUD_SPEED_FS | the device is running at full speed. |
◆ rtos_usb_endpoint_transfer_start()
XUD_Result_t rtos_usb_endpoint_transfer_start |
( |
rtos_usb_t * |
ctx, |
|
|
uint32_t |
endpoint_addr, |
|
|
uint8_t * |
buffer, |
|
|
size_t |
len |
|
) |
| |
Requests a transfer on a USB endpoint. This function returns immediately. When the transfer is complete, the application's ISR callback provided to rtos_usb_start() will be called.
- Parameters
-
ctx | A pointer to the USB driver instance to use. |
endpoint_addr | The address of the endpoint to perform the transfer on. |
buffer | A pointer to the buffer to transfer data into for OUT endpoints, or from for IN endpoints. |
len | The maximum number of bytes to receive for OUT endpoints, or the actual number of bytes to send for IN endpoints. |
- Return values
-
XUD_RES_OKAY | if the transfer was requested successfully. |
XUD_RES_RST | if the transfer was not requested and the USB bus needs to be reset. In this case, the application should reset the USB bus. |
◆ rtos_usb_init()
Initializes an RTOS USB driver instance. This must only be called by the tile that owns the driver instance. It should be called prior to starting the RTOS, and must be called before any of the core USB driver functions are called with this instance.
This will create an RTOS thread that runs lib_xud's main loop. This thread is created with the highest priority and with preemption disabled.
- Note
- Due to implementation details of lib_xud, it is only possible to have one USB instance per application. Functionally this is not an issue, as no xcore chips have more than one USB interface.
-
If using the Tiny USB stack, then this function should not be called directly by the application. The xcore device port for Tiny USB takes care of calling this, as well as all other USB driver functions.
- Parameters
-
ctx | A pointer to the USB driver instance to start. |
io_core_mask | A bitmask representing the cores on which the low level USB I/O thread created by the driver is allowed to run. Bit 0 is core 0, bit 1 is core 1, etc. |
isr_cb | The callback function for the driver to call when transfers are completed. |
isr_app_data | A pointer to application specific data to pass to the application's ISR callback function isr_cb . |
◆ rtos_usb_simple_init()
void rtos_usb_simple_init |
( |
rtos_usb_t * |
ctx, |
|
|
uint32_t |
io_core_mask |
|
) |
| |
Initializes an RTOS USB driver instance. This must only be called by the tile that owns the driver instance. It should be called prior to starting the RTOS, and must be called before any of the core USB driver functions are called with this instance.
This initialization function may be used instead of rtos_usb_init() if the application is not using a USB stack. This allows application threads to wait for transfers to complete with the rtos_usb_simple_transfer_complete() function. The application cannot provide its own ISR callback when initialized with this function. This provides a similar programming interface as a traditional bare metal xcore application using lib_xud.
This will create an RTOS thread that runs lib_xud's main loop. This thread is created with the highest priority and with preemption disabled.
- Note
- Due to implementation details of lib_xud, it is only possible to have one USB instance per application. Functionally this is not an issue, as no xcore chips have more than one USB interface.
- Parameters
-
ctx | A pointer to the USB driver instance to start. |
io_core_mask | A bitmask representing the cores on which the low level USB I/O thread created by the driver is allowed to run. Bit 0 is core 0, bit 1 is core 1, etc. |
◆ rtos_usb_simple_transfer_complete()
XUD_Result_t rtos_usb_simple_transfer_complete |
( |
rtos_usb_t * |
ctx, |
|
|
uint32_t |
endpoint_addr, |
|
|
size_t * |
len, |
|
|
unsigned |
timeout |
|
) |
| |
This function may be called to wait for a transfer on a particular endpoint to complete. This requires that the USB instance was initialized with rtos_usb_simple_init().
- Parameters
-
ctx | A pointer to the USB driver instance to use. |
endpoint_addr | The address of the endpoint to wait for. |
len | The actual number of bytes transferred. For IN endpoints, this will be the same as the length requested by rtos_usb_endpoint_transfer_start(). For OUT endpoints, it may be less. |
timeout | The maximum amount of time to wait for the transfer to complete before returning. |
- Return values
-
XUD_RES_OKAY | if the transfer was completed successfully. |
XUD_RES_RST | if the transfer was not able to complete and the USB bus needs to be reset. In this case, the application should reset the USB bus. |
XUD_RES_ERR | if there was an unexpected error transferring the data. |
◆ rtos_usb_start()
void rtos_usb_start |
( |
rtos_usb_t * |
ctx, |
|
|
size_t |
endpoint_count, |
|
|
XUD_EpType |
endpoint_out_type[], |
|
|
XUD_EpType |
endpoint_in_type[], |
|
|
XUD_BusSpeed_t |
speed, |
|
|
XUD_PwrConfig |
power_source, |
|
|
unsigned |
interrupt_core_id, |
|
|
int |
sof_interrupt_core_id |
|
) |
| |
Starts the USB driver instance's low level USB I/O thread and enables its interrupts on the requested core. This must only be called by the tile that owns the driver instance. It must be called after starting the RTOS from an RTOS thread.
rtos_usb_init() must be called on this USB driver instance prior to calling this.
- Parameters
-
ctx | A pointer to the USB driver instance to start. |
endpoint_count | The number of endpoints that will be used by the application. A single endpoint here includes both its IN and OUT endpoints. For example, if the application uses EP0_IN, EP0_OUT, EP1_IN, EP2_IN, EP2_OUT, EP3_OUT, then the endpoint count specified here should be 4 (endpoint 0 through endpoint 3) regardless of the lack of EP1_OUT and EP3_IN. If these two endpoints were used, the count would still be 4.
If for whatever reason, the application needs to use a particular endpoint number, say only EP6 in addition to EP0, then the count here needs to be 7, even though endpoints 1 through 5 are unused. All unused endpoints must be marked as disabled in the two endpoint type lists endpoint_out_type and endpoint_in_type . |
endpoint_out_type | A list of the endpoint types for each output endpoint. Index 0 represents the type for EP0_OUT, and so on. See XUD_EpType in lib_xud. If the endpoint is unused, it must be set to XUD_EPTYPE_DIS. |
endpoint_in_type | A list of the endpoint types for each input endpoint. Index 0 represents the type for EP0_IN, and so on. See XUD_EpType in lib_xud. If the endpoint is unused, it must be set to XUD_EPTYPE_DIS. |
speed | The speed at which the bus should operate. Either XUD_SPEED_FS or XUD_SPEED_HS. See XUD_BusSpeed_t in lib_xud. |
power_source | The source of the device's power. Either bus powered (XUD_PWR_BUS) or self powered (XUD_PWR_SELF). See XUD_PwrConfig in lib_xud. |
interrupt_core_id | The ID of the core on which to enable the USB interrupts. |
sof_interrupt_core_id | The ID of the core on which to enable the SOF interrupt. Set to < 0 to disable the SoF interrupt if it is not needed. |