XCORE SDK
XCORE Software Development Kit
Classes | Macros | Typedefs | Enumerations | Functions
rtos_usb_driver

Classes

struct  rtos_usb_ep_xfer_info_t
 
struct  rtos_usb_struct
 

Macros

#define RTOS_USB_ENDPOINT_COUNT_MAX   12
 
#define RTOS_USB_ISR_CALLBACK_ATTR   __attribute__((fptrgroup("rtos_usb_isr_cb_fptr_grp")))
 

Typedefs

typedef struct rtos_usb_struct rtos_usb_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)
 

Enumerations

enum  rtos_usb_packet_type_t { rtos_usb_data_packet , rtos_usb_setup_packet , rtos_usb_sof_packet }
 

Functions

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
 

Detailed Description

The public API for using the RTOS USB driver.

Macro Definition Documentation

◆ 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.

Typedef Documentation

◆ 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
ctxA pointer to the associated USB driver instance.
app_dataA pointer to application specific data provided by the application. Used to share data between this callback function and the application.
ep_addressThe address of the USB endpoint that the transfer has completed on.
xfer_lenThe length of the data transferred.
packet_typeThe type of packet transferred. See rtos_usb_packet_type_t.
resThe result of the transfer. See XUD_Result_t.

◆ rtos_usb_t

typedef struct rtos_usb_struct rtos_usb_t

Typedef to the RTOS USB driver instance struct.

Function Documentation

◆ 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
ctxA pointer to the USB driver instance to use.
timeoutThe maximum amount of time to wait for all endpoints to become ready before returning.
Return values
XUD_RES_OKAYif all the endpoints are ready to use.
XUD_RES_ERRif 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
ctxA pointer to the USB driver instance to use.
endpoint_addrThe address of the endpoint to check.
timeoutThe maximum amount of time to wait for the endpoint to become ready before returning.
Return values
XUD_RES_OKAYif the endpoint is ready to use.
XUD_RES_ERRif 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_addrIN or OUT endpoint address to reset.
Return values
XUD_SPEED_HSthe host has accepted that this device can execute at high speed.
XUD_SPEED_FSthe 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
ctxA pointer to the USB driver instance to use.
endpoint_addrThe address of the endpoint to perform the transfer on.
bufferA pointer to the buffer to transfer data into for OUT endpoints, or from for IN endpoints.
lenThe maximum number of bytes to receive for OUT endpoints, or the actual number of bytes to send for IN endpoints.
Return values
XUD_RES_OKAYif the transfer was requested successfully.
XUD_RES_RSTif 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()

void rtos_usb_init ( rtos_usb_t ctx,
uint32_t  io_core_mask,
rtos_usb_isr_cb_t  isr_cb,
void *  isr_app_data 
)

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
ctxA pointer to the USB driver instance to start.
io_core_maskA 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_cbThe callback function for the driver to call when transfers are completed.
isr_app_dataA 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
ctxA pointer to the USB driver instance to start.
io_core_maskA 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
ctxA pointer to the USB driver instance to use.
endpoint_addrThe address of the endpoint to wait for.
lenThe 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.
timeoutThe maximum amount of time to wait for the transfer to complete before returning.
Return values
XUD_RES_OKAYif the transfer was completed successfully.
XUD_RES_RSTif 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_ERRif 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
ctxA pointer to the USB driver instance to start.
endpoint_countThe 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_typeA 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_typeA 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.
speedThe speed at which the bus should operate. Either XUD_SPEED_FS or XUD_SPEED_HS. See XUD_BusSpeed_t in lib_xud.
power_sourceThe 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_idThe ID of the core on which to enable the USB interrupts.
sof_interrupt_core_idThe ID of the core on which to enable the SOF interrupt. Set to < 0 to disable the SoF interrupt if it is not needed.