USB Device Core API#

USBD_ConfigureBufAlignOctets()#

Description#

Configures the alignment of the internal buffers.

Files#

usbd_core.h/usbd_core.c

Prototype#

void  USBD_ConfigureBufAlignOctets (CPU_SIZE_T  buf_align_octets)

Arguments#

buf_align_octets

Buffer alignment, in octets.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional, if it is not called, the default value will be used.

  2. This function MUST be called before the USB device core is initialized via the USBD_Init() function.

USBD_ConfigureMemSeg()#

Description#

Configures the memory segment to use when allocating control data and buffers.

Files#

usbd_core.h/usbd_core.c

Prototype#

void  USBD_ConfigureMemSeg (MEM_SEG  *p_mem_seg,
                            MEM_SEG  *p_mem_seg_buf)

Arguments#

p_mem_seg

Pointer to memory segment to use when allocating control data. Can be the same segment used for p_mem_seg_buf. DEF_NULL means general purpose heap segment.

p_mem_seg_buf

Pointer to memory segment to use when allocating data buffers. Can be the same segment used for p_mem_seg. DEF_NULL means general purpose heap segment.

Returned Value#

None.

Notes / Warnings#

  1. This function is optional, if it is not called, the default value will be used.

  2. This function MUST be called before the USB device core is initialized via the USBD_Init() function.

USBD_Init()#

Description#

Initializes the USB device stack.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_Init (USBD_QTY_CFG  *p_qty_cfg,                 RTOS_ERR      *p_err)

Arguments#

p_qty_cfg

Pointer to the USBD configuration structure.

p_err

Pointer to variable that will receive the return error code from these functions:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

USBD_Init() must be called:

  • Only once from a product's application.

  • With the following conditions:

  • After the product's OS has been initialized.

  • Before the product's application calls any USB device stack function(s).

USBD_StdReqTimeoutSet()#

Description#

Assigns a new timeout delay for the USB device standard requests.

Files#

usbd_core.h/usbd_core.c

Prototype#

void  USBD_StdReqTimeoutSet (CPU_INT32U   std_req_timeout_ms,
                             RTOS_ERR    *p_err)

Arguments#

std_req_timeout_ms

New timeout, in milliseconds.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

USBD_DevAdd()#

Description#

Adds a device to the stack and creates the default control endpoints.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT08U  USBD_DevAdd (const  CPU_CHAR          *name,
                         const  RTOS_TASK_CFG     *p_task_cfg,
                         const  USBD_DEV_CFG      *p_dev_cfg,
                         const  USBD_DEV_DRV_CFG  *p_dev_drv_cfg,
                                USBD_BUS_FNCTS    *p_bus_fnct,
                                RTOS_ERR          *p_err)

Arguments#

name

Name of the USB controller.

p_task_cfg

Pointer to the task configuration structure.

p_dev_cfg

Pointer to the specific USB device configuration.

p_dev_drv_cfg

Pointer to the device driver configuration structure.

p_dev_hw_info

Pointer to the device hardware information structure.

p_bus_fnct

Pointer to the specific USB device bus events callback functions. Content MUST be persistent.

p_err

Pointer to the variable that will receive the returned error code from these functions:

  • RTOS_ERR_NONE

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_OS_ILLEGAL_RUN_TIME

  • RTOS_ERR_ALLOC

  • RTOS_ERR_DEV_ALLOC

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_EP_NONE_AVAIL

Returned Value#

  • The device number, if no errors are returned.

  • USBD_DEV_NBR_NONE, if any errors are returned.

Notes / Warnings#

Certain driver functions are required for the driver to work correctly with the core. The pointers to these functions are checked in this function to ensure they are valid and can be used throughout the core.

USBD_DevTaskPrioSet()#

Description#

Sets priority of the given device's task.

Files#

usbd_core.h/usbd_core.c

Prototype#

void  USBD_DevTaskPrioSet (CPU_INT08U       dev_nbr,
                           RTOS_TASK_PRIO   prio,
                           RTOS_ERR        *p_err)

Arguments#

dev_nbr

Device number.

prio

Priority of the device's task.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_ARG

Returned Value#

None.

Notes / Warnings#

None.

USBD_DevNbrGetFromName()#

Description#

Get device number from the USB controller name.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT08U  USBD_DevNbrGetFromName (const  CPU_CHAR  *name)

Arguments#

name

Name of the USB controller.

Returned Value#

Device number.

Notes / Warnings#

None.

USBD_DevStart()#

Description#

Starts the device stack.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_DevStart (CPU_INT08U    dev_nbr,
                    RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

p_err

Pointer to the variable that receives the following returned error codes from these functions:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_SEG_OVF

  • RTOS_ERR_EP_NONE_AVAIL

  • RTOS_ERR_FAIL

Returned Value#

None.

Notes / Warnings#

The device stack can be only started if the device is in one of the following states:

  • USBD_DEV_STATE_NONE: Device controller has not been initialized.

  • USBD_DEV_STATE_INIT: Device controller is already initialized.

USBD_DevStop()#

Description#

Stops the device stack.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_DevStop (CPU_INT08U    dev_nbr,
                   RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

p_err

Pointer to variable that will receive the following return error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

Returned Value#

None.

Notes / Warnings#

None.

USBD_ConfigAdd()#

Description#

Adds a configuration attribute to the device.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT08U USBD_ConfigAdd ( CPU_INT08U      dev_nbr,
                            CPU_INT08U      attrib,
                            CPU_INT16U      max_pwr,
                            USBD_DEV_SPD    spd,
                            const CPU_CHAR *p_name,
                            RTOS_ERR       *p_err)

Arguments#

dev_nbr

Device number.

attrib

Available configuration attributes:

  • USBD_DEV_ATTRIB_SELF_POWERED: Power does not come from VBUS.

  • USBD_DEV_ATTRIB_REMOTE_WAKEUP: Remote wake-up feature enabled.

max_pwr

Bus power required for this device (see Note #1).

spd

Available configuration speeds.

USBD_DEV_SPD_FULL: Configuration is added to the full-speed configuration set.

USBD_DEV_SPD_HIGH: Configuration is added to the high-speed configuration set.

p_name

Pointer to a string that describes the configuration (see Note #2).

p_err

Pointers to the variable that receives the returned error code from these functions:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_ALLOC

  • RTOS_ERR_CONFIG_ALLOC

  • RTOS_ERR_INVALID_ARG

Returned Value#

  • Configuration number, if no errors are returned.

  • USBD_CONFIG_NBR_NONE, if any errors are returned.

Notes / Warnings#

  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 the 'max_pwr' argument should be between 0mA and 500mA.

  2. String support is optional: 'p_name' can be a NULL string pointer.

    • Configuration can only be added when the device is in the following states:

    • USBD_DEV_STATE_NONE: Device controller has not been initialized.

  3. USBD_DEV_STATE_INIT: Device controller is already initialized.

  4. A high-speed configuration can only be added if the device controller is high-speed.

USBD_ConfigOtherSpeed()#

Description#

Associate a configuration with its alternative-speed counterpart.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_ConfigOtherSpeed (CPU_INT08U    dev_nbr,
                            CPU_INT08U    config_nbr,
                            CPU_INT08U    config_other,
                            RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

config_nbr

Configuration number.

config_other

Other-speed configuration number.

p_err

Pointer to the variable that receives the returned error code from these functions:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

Returned Value#

None.

Notes / Warnings#

  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:

    • USBD_DEV_STATE_NONE Device controller has not been initialized.

    • USBD_DEV_STATE_INIT Device controller is already initialized.

USBD_DevStateGet()#

Description#

Gets the current device state.

Files#

usbd_core.h/usbd_core.c

Prototype#

USBD_DEV_STATE USBD_DevStateGet (CPU_INT08U    dev_nbr,
                                 RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

p_err

Pointer to the variable that receives the returned error code from this function :

  • RTOS_ERR_NONE

Returned Value#

  • Current device state, if no errors are returned.

  • USBD_DEV_STATE_NONE, if any errors are returned.

Notes / Warnings#

None.

USBD_DevSpdGet()#

Description#

Gets the device speed.

Files#

usbd_core.h/usbd_core.c

Prototype#

USBD_DEV_SPD USBD_DevSpdGet (CPU_INT08U    dev_nbr,
                             RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

p_err

Pointer to the variable that receives the returned error code from these functions:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

Returned Value#

  • The current device speed, if successful.

  • USBD_DEV_SPD_INVALID, if not successful.

Notes / Warnings#

None.

USBD_DevSelfPwrSet()#

Description#

Sets the device's current power source.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_DevSelfPwrSet (CPU_INT08U     dev_nbr,
                         CPU_BOOLEAN    self_pwr,
                         RTOS_ERR      *p_err)

Arguments#

dev_nbr

Device number.

self_pwr

The power source of the device :

  • DEF_TRUE: device is self-powered.

  • DEF_FALSE: device is bus-powered.

p_err

Pointer to the variable that receives the returned error code from this function :

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

None.

USBD_DevSetMS_VendorCode()#

Description#

Set the device's Microsoft vendor code.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_DevSetMS_VendorCode (CPU_INT08U    dev_nbr,
                               CPU_INT08U    vendor_code,
                               RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

vendor_code

Microsoft vendor code.

p_err

Pointer to the variable that receives the returned error code from this function:

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

The vendor code used must be different from any vendor bRequest value.

USBD_DevGetCfg()#

Description#

Gets the device's configuration.

Files#

usbd_core.h/usbd_core.c

Prototype#

USBD_DEV_CFG *USBD_DevCfgGet (CPU_INT08U    dev_nbr,
                              RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

p_err

Pointer to the variable that receives the returned error code from this function :

  • RTOS_ERR_NONE

Returned Value#

  • Pointer to device configuration, if no errors are returned.

  • Pointer to NULL, if any errors are returned.

Notes / Warnings#

None.

USBD_IF_Add()#

Description#

Adds an interface to a specific configuration.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT08U USBD_IF_Add ( CPU_INT08U        dev_nbr,
                         CPU_INT08U        cfg_nbr,
                         USBD_CLASS_DRV   *p_class_drv,
                         void             *p_if_class_arg,
                         void             *p_if_alt_class_arg,
                         CPU_INT08U        class_code,
                         CPU_INT08U        class_sub_code,
                         CPU_INT08U        class_protocol_code,
                   const CPU_CHAR         *p_name,
                         RTOS_ERR         *p_err)

Arguments#

dev_nbr

Device number.

cfg_nbr

Configuration index to add the interface.

p_class_drv

Pointer to interface driver.

p_if_class_arg

Pointer to interface driver argument.

p_if_alt_class_arg

Pointer to alternate interface argument.

class_code

Class code assigned by the USB-IF.

class_sub_code

Subclass code assigned by the USB-IF.

class_protocol_code

Protocol code assigned by the USB-IF.

p_name

Pointer to string describing the Interface.

p_err

Pointer to variable that will receive the return error code from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_IF_ALT_ALLOC

  • RTOS_ERR_ALLOC

  • RTOS_ERR_IF_ALLOC

Returned Value#

  • Interface number, if no errors are returned.

  • USBD_IF_NBR_NONE, if any errors are returned.

Notes / Warnings#

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

USBD_IF_AltAdd()#

Description#

Adds an alternate setting to a specific interface.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT08U USBD_IF_AltAdd ( CPU_INT08U    dev_nbr,
                            CPU_INT08U    config_nbr,
                            CPU_INT08U    if_nbr,
                            void         *p_class_arg,
                      const CPU_CHAR     *p_name,
                            RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

config_nbr

Configuration number.

if_nbr

Interface number.

p_class_arg

Pointer to alternate interface argument.

p_name

Pointer to alternate setting name.

p_err

Pointer to a variable that receives the returned error code from these functions:

  • RTOS_ERR_NONE

  • RTOS_ERR_IF_ALT_ALLOC

  • RTOS_ERR_ALLOC

Returned Value#

  • Interface alternate setting number, if no errors are returned.

  • USBD_IF_ALT_NBR_NONE, if any errors are returned.

Notes / Warnings#

None.

USBD_IF_Grp()#

Description#

Creates an interface group.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT08U USBD_IF_Grp ( CPU_INT08U    dev_nbr,
                         CPU_INT08U    config_nbr,
                         CPU_INT08U    class_code,
                         CPU_INT08U    class_sub_code,
                         CPU_INT08U    class_protocol_code,
                         CPU_INT08U    if_start,
                         CPU_INT08U    if_cnt,
                   const CPU_CHAR     *p_name,
                         RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number

config_nbr

Configuration number.

class_code

Class code assigned by the USB-IF.

class_sub_code

Subclass code assigned by the USB-IF.

class_protocol_code

Protocol code assigned by the USB-IF.

if_start

Interface number of the first interface that is associated with this group.

if_cnt

Number of consecutive interfaces that are associated with this group.

p_name

Pointer to the string that describes interface group.

p_err

Pointer to the variable that receives the returned error code from these functions:

  • RTOS_ERR_NONE

  • RTOS_ERR_ALLOC

  • RTOS_ERR_IF_GRP_ALLOC

  • RTOS_ERR_ALREADY_EXISTS

Returned Value#

  • Interface group number, if no errors are returned.

  • USBD_IF_GRP_NBR_NONE, if any errors are returned.

Notes / Warnings#

None.

USBD_DevFrameNbrGet()#

Description#

Get the last frame number from the driver.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT16U USBD_DevFrameNbrGet (CPU_INT08U    dev_nbr,
                                RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

p_err

Pointer to variable that will receive the return error code from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NOT_SUPPORTED

Returned Value#

The current frame number.

Notes / Warnings#

  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 USBD_FRAME_NBR_GET() or USBD_MICROFRAME_NBR_GET() to get the frame or microframe number only.

USBD_DescDevGet()#

Description#

Gets the device descriptor.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT08U USBD_DescDevGet (USBD_DRV     *p_drv,
                            CPU_INT08U   *p_buf,
                            CPU_INT08U    max_len,
                            RTOS_ERR     *p_err)

Arguments#

p_drv

Pointer to device driver structure.

p_buf

Pointer to the destination buffer.

max_len

Maximum number of bytes to write in destination buffer.

p_err

Pointer to the variable that receives the returned error code from these functions:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Number of bytes actually in the descriptor, if no errors are returned.

  • 0, if any errors are returned.

Notes / Warnings#

This function should be used by drivers that support the standard requests auto-reply (during the initialization process).

USBD_DescConfigGet()#

Description#

Gets a configuration descriptor.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT16U USBD_DescConfigGet (USBD_DRV     *p_drv,
                               CPU_INT08U   *p_buf,
                               CPU_INT16U    max_len,
                               CPU_INT08U    config_ix,
                               RTOS_ERR     *p_err)

Arguments#

p_drv

Pointer to device driver structure.

p_buf

Pointer to the destination buffer.

max_len

Maximum number of bytes to write in the destination buffer.

config_ix

Index of the desired configuration descriptor.

p_err

Pointer to the variable that receives the returned the error code from these functions:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Number of bytes actually in the descriptor, if no errors are returned.

  • 0, if any errors are returned.

Notes / Warnings#

This function should be used by drivers supporting a standard request's auto-reply, during the initialization process.

USBD_DescStrGet()#

Description#

Gets a string descriptor.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT08U USBD_DescStrGet (USBD_DRV     *p_drv,
                            CPU_INT08U   *p_buf,
                            CPU_INT08U    max_len,
                            CPU_INT08U    str_ix,
                            RTOS_ERR     *p_err)

Arguments#

p_drv

Pointer to the device driver structure.

p_buf

Pointer to the destination buffer.

max_len

Maximum number of bytes to write in destination buffer.

str_ix

Index of the desired string descriptor.

p_err

Pointer to variable that will receive the return error code from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Number of bytes actually in the descriptor, if no errors are returned.

  • 0, if any errors are returned.

Notes / Warnings#

This function should be used by drivers supporting a standard request's auto-reply, during the initialization process.

USBD_StrAdd()#

Description#

Adds a string to a USB device.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_StrAdd ( CPU_INT08U    dev_nbr,
             const CPU_CHAR     *p_str,
                   RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

p_str

Pointer to the string to add (see Notes).

p_err

Pointer to variable that will receive the return error code from these functions:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_ALLOC

Returned Value#

None.

Notes / Warnings#

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.

USBD_DescWr08()#

Description#

Writes an 8-bit value to the descriptor buffer.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_DescWr08 (CPU_INT08U   dev_nbr,
                    CPU_INT08U   val)

Arguments#

dev_nbr

Device number.

val

8-bit value to write in the descriptor buffer.

Returned Value#

None.

Notes / Warnings#

USB classes may use this function to append class-specific descriptors to the configuration descriptor.

USBD_DescWr16()#

Description#

Writes a 16-bit value to the descriptor buffer.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_DescWr16 (CPU_INT08U   dev_nbr,
                    CPU_INT16U   val)

Arguments#

dev_nbr

Device number.

val

16-bit value to write in descriptor buffer.

Returned Value#

none.

Notes / Warnings#

  1. USB classes may use this function to append class-specific descriptors to the configuration descriptor.

  2. USB descriptors are in little-endian format.

USBD_DescWr24()#

Description#

Writes a 24-bit value to the descriptor buffer.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_DescWr24 (CPU_INT08U   dev_nbr,
                    CPU_INT32U   val)

Arguments#

dev_nbr

Device number.

val

32-bit value containing 24 useful bits to write in the descriptor buffer.

Returned Value#

none.

Notes / Warnings#

  1. USB classes may use this function to append class-specific descriptors to the configuration descriptor.

  2. USB descriptors are in little-endian format.

USBD_DescWr32()#

Description#

Writes a 32-bit value to the descriptor buffer.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_DescWr32 (CPU_INT08U   dev_nbr,
                    CPU_INT32U   val)

Arguments#

dev_nbr

Device number.

val

32-bit value to write in the descriptor buffer.

Returned Value#

none.

Notes / Warnings#

  1. USB classes may use this function to append class-specific descriptors to the configuration descriptor.

  2. USB descriptors are in little-endian format.

USBD_DescWr()#

Description#

Writes a buffer into the descriptor buffer.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_DescWr ( CPU_INT08U    dev_nbr,
             const CPU_INT08U   *p_buf,
                   CPU_INT16U    len)

Arguments#

dev_nbr

Device number.

p_buf

Pointer to the buffer to write into the descriptor buffer.

len

Length of the buffer.

Returned Value#

None.

Notes / Warnings#

USB classes may use this function to append class-specific descriptors to the configuration descriptor.

USBD_BulkAdd()#

Description#

Adds a bulk endpoint to an alternate setting interface.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT08U USBD_BulkAdd (CPU_INT08U     dev_nbr,
                         CPU_INT08U     config_nbr,
                         CPU_INT08U     if_nbr,
                         CPU_INT08U     if_alt_nbr,
                         CPU_BOOLEAN    dir_in,
                         CPU_INT16U     max_pkt_len,
                         RTOS_ERR      *p_err)

Arguments#

dev_nbr

Device number.

config_nbr

Configuration number.

if_nbr

Interface number.

if_alt_nbr

Interface alternate setting number.

dir_in

DEF_NO OUT direction.

max_pkt_len

Endpoint maximum packet length (see Notes)

p_err

Pointer to the variable that receives the returned error code from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_EP_ALLOC

  • RTOS_ERR_EP_NONE_AVAIL

Returned Value#

  • Endpoint address, if no errors are returned.

  • USBD_EP_ADDR_NONE, if any errors are returned.

Notes / Warnings#

If the max_pkt_len argument is '0', the stack will allocate the first available BULK endpoint, regardless its maximum packet size.

USBD_IntrAdd()#

Description#

Adds an interrupt endpoint to an alternate setting interface.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT08U USBD_IntrAdd (CPU_INT08U     dev_nbr,
                         CPU_INT08U     config_nbr,
                         CPU_INT08U     if_nbr,
                         CPU_INT08U     if_alt_nbr,
                         CPU_BOOLEAN    dir_in,
                         CPU_INT16U     max_pkt_len,
                         CPU_INT16U     interval,
                         RTOS_ERR      *p_err)

Arguments#

dev_nbr

Device number.

config_nbr

Configuration number.

if_nbr

Interface number.

if_alt_nbr

Interface alternate setting number.

dir_in

  • DEF_NO: OUT direction.

  • DEF_YES: IN direction.

max_pkt_len

Endpoint maximum packet length. (see Note #1)

interval

Endpoint interval in frames or microframes.

p_err

Pointer to the variable that receives the returned error code from these functions:

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_EP_ALLOC

  • RTOS_ERR_EP_NONE_AVAIL

Returned Value#

  • Endpoint address, if no errors are returned.

  • USBD_EP_ADDR_NONE, if any errors are returned.

Notes / Warnings#

  1. If the max_pkt_len argument is '0', the stack will allocate the first available INTERRUPT endpoint, regardless its maximum packet size.

  2. For high-speed interrupt endpoints, the bInterval values 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 32768 microframes (i.e., 4096 frames) in high-speed.

USBD_IsocAdd()#

Description#

Adds an isochronous endpoint to alternate setting interface.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT08U USBD_IsocAdd (CPU_INT08U     dev_nbr,
                         CPU_INT08U     config_nbr,
                         CPU_INT08U     if_nbr,
                         CPU_INT08U     if_alt_nbr,
                         CPU_BOOLEAN    dir_in,
                         CPU_INT08U     attrib,
                         CPU_INT16U     max_pkt_len,
                         CPU_INT08U     transaction_frame,
                         CPU_INT16U     interval,
                         RTOS_ERR      *p_err)

Arguments#

dev_nbr

Device number.

config_nbr

Configuration number.

if_nbr

Interface number.

if_alt_nbr

Interface alternate setting number.

dir_in

DEF_NO, OUT direction.

attrib

Isochronous endpoint synchronization and usage type attributes.

max_pkt_len

Endpoint maximum packet length (see Note #1).

transaction_frame

Endpoint transactions per (micro)frame (see Note #2).

interval

Endpoint interval in frames or microframes.

p_err

Pointer to variable that will receive the return error code from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_EP_ALLOC

  • RTOS_ERR_EP_NONE_AVAIL

Returned Value#

  • Endpoint address, if no errors are returned.

  • USBD_EP_ADDR_NONE, if any errors are returned.

Notes / Warnings#

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

USBD_IsocSyncRefreshSet()#

Description#

Sets the synchronization feedback rate on the synchronization isochronous endpoint.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_IsocSyncRefreshSet (CPU_INT08U    dev_nbr,
                              CPU_INT08U    config_nbr,
                              CPU_INT08U    if_nbr,
                              CPU_INT08U    if_alt_nbr,
                              CPU_INT08U    synch_ep_addr,
                              CPU_INT08U    sync_refresh,
                              RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

config_nbr

Configuration number.

if_nbr

Interface number.

if_alt_nbr

Interface alternate setting number.

synch_ep_addr

Synchronization endpoint address.

sync_refresh

Exponent of synchronization feedback rate (see Note #3).

p_err

Pointer to variable that will receive the return error code from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_EP_INVALID

Returned Value#

None.

Notes / Warnings#

  1. Synchronization endpoints can only be associated when the device is in the following states:

    • USBD_DEV_STATE_NONE: Device controller has not been initialized.

    • USBD_DEV_STATE_INIT:Device controller is already initialized.

  2. For audio class 1.0, the interface class code must be 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 that for bmAttributes field no usage type for bits 5..4. But USB 2.0 specification, Table 9-13 "Standard Endpoint Descriptor" indicates that 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'.

USBD_IsocSyncAddrSet()#

Description#

Associates synchronization endpoint to isochronous endpoint.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_IsocSyncAddrSet (CPU_INT08U    dev_nbr,
                           CPU_INT08U    config_nbr,
                           CPU_INT08U    if_nbr,
                           CPU_INT08U    if_alt_nbr,
                           CPU_INT08U    data_ep_addr,
                           CPU_INT08U    sync_addr,
                           RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

config_nbr

Configuration number.

if_nbr

Interface number.

if_alt_nbr

Interface alternate setting number.

data_ep_addr

Data endpoint address.

sync_addr

Associated synchronization endpoint.

p_err

Pointer to variable that will receive the return error code from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_EP_INVALID

Returned Value#

none.

Notes / Warnings#

  1. Synchronization endpoints can only be associated when the device is in the following states:

    • USBD_DEV_STATE_NONE Device controller has not been initialized.

    • USBD_DEV_STATE_INIT Device controller is already initialized.

  2. For audio class 1.0, interface class code must be USBD_CLASS_CODE_AUDIO and protocol 'zero'.

USBD_EP_MaxPhyNbrGet()#

Description#

Gets the maximum physical endpoint number.

Files#

usbd_core.h/usbd_core.c

Prototype#

CPU_INT08U USBD_EP_MaxPhyNbrGet (CPU_INT08U   dev_nbr)

Arguments#

dev_nbr

Device number.

Returned Value#

  • Maximum physical endpoint number, if no errors are returned.

  • USBD_EP_NBR_NONE, if any errors are returned.

Notes / Warnings#

None.

USBD_EventConn()#

Description#

Notifies the USB connection bus events to the device stack.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_EventConn (USBD_DRV   *p_drv)

Arguments#

p_drv

Pointer to device driver.

Returned Value#

None.

Notes / Warnings#

None.

USBD_EventDisconn()#

Description#

Notifies the USB disconnection bus events to the device stack.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_EventDisconn (USBD_DRV   *p_drv)

Arguments#

p_drv

Pointer to device driver.

Returned Value#

None.

Notes / Warnings#

None.

USBD_EventHS()#

Description#

Notifies the USB High-Speed bus events to the device stack.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_EventHS (USBD_DRV   *p_drv)

Arguments#

p_drv

Pointer to device driver.

Returned Value#

None.

Notes / Warnings#

None.

USBD_EventReset()#

Description#

Notifies the USB reset bus events to the device stack.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_EventReset (USBD_DRV   *p_drv)

Arguments#

p_drv

Pointer to device driver.

Returned Value#

None.

Notes / Warnings#

None.

USBD_EventSuspend()#

Description#

Notifies the USB suspend bus events to the device stack.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_EventSuspend (USBD_DRV   *p_drv)

Arguments#

p_drv

Pointer to device driver.

Returned Value#

None.

Notes / Warnings#

None.

USBD_EventResume()#

Description#

Notifies the USB resume bus events to the device stack.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_EventResume (USBD_DRV   *p_drv)

Arguments#

p_drv

Pointer to device driver.

Returned Value#

None.

Notes / Warnings#

None.

USBD_EventSetup()#

Description#

Sends a USB setup event to the core task.

Files#

usbd_core.h/usbd_core.c

Prototype#

void USBD_EventSetup (USBD_DRV   *p_drv,
                      void       *p_buf)

Arguments#

p_drv

Pointer to device driver.

p_buf

Pointer to the setup packet.

Returned Value#

None.

Notes / Warnings#

None.

USBD_BulkRx()#

Description#

Receives data on Bulk OUT endpoint.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

CPU_INT32U USBD_BulkRx (CPU_INT08U    dev_nbr,
                        CPU_INT08U    ep_addr,
                        void         *p_buf,
                        CPU_INT32U    buf_len,
                        CPU_INT16U    timeout_ms,
                        RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

p_buf

Pointer to the destination buffer to receive data (see Note #1).

buf_len

Number of octets to receive.

timeout_ms

Timeout in milliseconds.

p_err

Pointer to the variable that receives the following returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_FAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_POOL_EMPTY

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Number of octets received, if no errors are returned.

  • 0, if any errors returned.

Notes / Warnings#

  1. Receive buffer must be aligned with a single word (minimum).

USBD_BulkRxAsync()#

Description#

Receives data on Bulk OUT endpoint asynchronously.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

void USBD_BulkRxAsync (CPU_INT08U         dev_nbr,
                       CPU_INT08U         ep_addr,
                       void              *p_buf,
                       CPU_INT32U         buf_len,
                       USBD_ASYNC_FNCT    async_fnct,
                       void              *p_async_arg,
                       RTOS_ERR          *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

p_buf

Pointer to the destination buffer to receive data (see Note #1).

buf_len

Number of octets to receive.

async_fnct

Function that will be invoked upon completion of receive operation.

p_async_arg

Pointer to the argument that will be passed as parameter of 'async_fnct'.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

  1. Receive buffer must be aligned with a single word (minimum).

USBD_BulkTx()#

Description#

Sends data on a Bulk IN endpoint.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

CPU_INT32U USBD_BulkTx (CPU_INT08U     dev_nbr,
                        CPU_INT08U     ep_addr,
                        void          *p_buf,
                        CPU_INT32U     buf_len,
                        CPU_INT16U     timeout_ms,
                        CPU_BOOLEAN    end,
                        RTOS_ERR      *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

p_buf

Pointer to buffer of data that will be transmitted (see Note #2).

buf_len

Number of octets to transmit.

timeout_ms

Timeout in milliseconds.

end

End-of-transfer flag (see Note #3).

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Number of octets transmitted, if no errors are returned.

  • 0, if any errors returned.

Notes / Warnings#

  1. This function SHOULD NOT be called from interrupt service routine (ISR).

  2. Transmit buffer must be aligned with a single word (minimum).

  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.

USBD_BulkTxAsync()#

Description#

Sends data on the Bulk IN endpoint asynchronously.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

void USBD_BulkTxAsync (CPU_INT08U         dev_nbr,
                       CPU_INT08U         ep_addr,
                       void              *p_buf,
                       CPU_INT32U         buf_len,
                       USBD_ASYNC_FNCT    async_fnct,
                       void              *p_async_arg,
                       CPU_BOOLEAN        end,
                       RTOS_ERR          *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

p_buf

Pointer to the buffer of data that will be transmitted (see Note #1).

buf_len

Number of octets to transmit.

async_fnct

Function that will be invoked upon completion of transmit operation.

p_async_arg

Pointer to the argument that will be passed as parameter of 'async_fnct'.

end

End-of-transfer flag (see Note #2).

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

  1. Transmit buffer must be aligned with a single word (minimum).

  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.

USBD_IntrRx()#

Description#

Receives data on the Interrupt OUT endpoint.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

CPU_INT32U USBD_IntrRx (CPU_INT08U    dev_nbr,
                        CPU_INT08U    ep_addr,
                        void         *p_buf,
                        CPU_INT32U    buf_len,
                        CPU_INT16U    timeout_ms,
                        RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

p_buf

Pointer to the destination buffer to receive data (see Note #2).

buf_len

Number of octets to receive.

timeout_ms

Timeout in milliseconds.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Number of octets received, if no errors are returned.

  • 0, if any errors returned.

Notes / Warnings#

  1. This function SHOULD NOT be called from interrupt service routine (ISR).

  2. Receive buffer must be aligned with a single word (minimum).

USBD_IntrRxAsync()#

Description#

Receives data on Interrupt OUT endpoint asynchronously.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

void USBD_IntrRxAsync (CPU_INT08U         dev_nbr,
                       CPU_INT08U         ep_addr,
                       void              *p_buf,
                       CPU_INT32U         buf_len,
                       USBD_ASYNC_FNCT    async_fnct,
                       void              *p_async_arg,
                       RTOS_ERR          *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

p_buf

Pointer to the destination buffer to receive data (see Note #1).

buf_len

Number of octets to receive.

async_fnct

Function that will be invoked upon completion of receive operation.

p_async_arg

Pointer to argument that will be passed as parameter of 'async_fnct'.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

  1. Receive buffer must be aligned with a single word (minimum).

USBD_IntrTx()#

Description#

Sends data on Interrupt IN endpoint.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

CPU_INT32U USBD_IntrTx (CPU_INT08U     dev_nbr,
                        CPU_INT08U     ep_addr,
                        void          *p_buf,
                        CPU_INT32U     buf_len,
                        CPU_INT16U     timeout_ms,
                        CPU_BOOLEAN    end,
                        RTOS_ERR      *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

p_buf

Pointer to the buffer of data that will be transmitted (see Note #2).

buf_len

Number of octets to transmit.

timeout_ms

Timeout in milliseconds.

end

End-of-transfer flag (see Note #3).

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Number of octets transmitted, if no errors are returned.

  • 0, if any errors returned.

Notes / Warnings#

  1. This function SHOULD NOT be called from interrupt service routine (ISR).

  2. Transmit buffer must be aligned with a single word (minimum).

  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.

USBD_IntrTxAsync()#

Description#

Sends data on the Interrupt IN endpoint asynchronously.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

void USBD_IntrTxAsync (CPU_INT08U         dev_nbr,
                       CPU_INT08U         ep_addr,
                       void              *p_buf,
                       CPU_INT32U         buf_len,
                       USBD_ASYNC_FNCT    async_fnct,
                       void              *p_async_arg,
                       CPU_BOOLEAN        end,
                       RTOS_ERR          *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

p_buf

Pointer to the buffer of data that will be transmitted (see Note #1).

buf_len

Number of octets to transmit.

async_fnct

Function that will be invoked upon completion of transmit operation.

p_async_arg

Pointer to the argument that will be passed as parameter of 'async_fnct'.

end

End-of-transfer flag (see Note #2).

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

  1. Transmit buffer must be aligned with a single word (minimum).

  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.

USBD_IsocRxAsync()#

Description#

Receives data on an isochronous OUT endpoint asynchronously.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

void USBD_IsocRxAsync (CPU_INT08U         dev_nbr,
                       CPU_INT08U         ep_addr,
                       void              *p_buf,
                       CPU_INT32U         buf_len,
                       USBD_ASYNC_FNCT    async_fnct,
                       void              *p_async_arg,
                       RTOS_ERR          *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

p_buf

Pointer to the destination buffer to receive data (see Note #1).

buf_len

Number of octets to receive.

async_fnct

Function that will be invoked upon completion of a receive operation.

p_async_arg

Pointer to the argument that will be passed as parameter of 'async_fnct'.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

  1. Receive buffer must be aligned with a single word (minimum).

USBD_IsocTxAsync()#

Description#

Sends data on an isochronous IN endpoint asynchronously.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

void USBD_IsocTxAsync (CPU_INT08U         dev_nbr,
                       CPU_INT08U         ep_addr,
                       void              *p_buf,
                       CPU_INT32U         buf_len,
                       USBD_ASYNC_FNCT    async_fnct,
                       void              *p_async_arg,
                       RTOS_ERR          *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

p_buf

Pointer to the buffer of data that will be transmitted (see Note #1).

buf_len

Number of octets to transmit.

async_fnct

Function that will be invoked upon completion of transmit operation.

p_async_arg

Pointer to the argument that will be passed as parameter of 'async_fnct'.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

  1. Transmit buffer must be aligned with a single word (minimum).

USBD_CtrlRx()#

Description#

Receives data on the Control OUT endpoint.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

CPU_INT32U USBD_CtrlRx (CPU_INT08U     dev_nbr,
                        void          *p_buf,
                        CPU_INT32U     buf_len,
                        CPU_INT16U     timeout_ms,
                        RTOS_ERR      *p_err)

Arguments#

dev_nbr

Device number.

p_buf

Pointer to the destination buffer to receive data.

buf_len

Number of octets to receive.

timeout_ms

Timeout in milliseconds.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_RX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Number of octets received, if no errors are returned.

  • 0, if any errors returned.

Notes / Warnings#

None.

USBD_CtrlTx()#

Description#

Sends data on the Control IN endpoint.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

CPU_INT32U USBD_CtrlTx (CPU_INT08U     dev_nbr,
                        void          *p_buf,
                        CPU_INT32U     buf_len,
                        CPU_INT16U     timeout_ms,
                        CPU_BOOLEAN    end,
                        RTOS_ERR      *p_err)

Arguments#

dev_nbr

Device number.

p_buf

Pointer to the buffer of data that will be sent.

buf_len

Number of octets to transmit.

timeout_ms

Timeout in milliseconds.

end

End-of-transfer flag (see Note #1).

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_INVALID_DEV_STATE

  • RTOS_ERR_NULL_PTR

  • RTOS_ERR_EP_QUEUING

  • RTOS_ERR_TX

  • RTOS_ERR_NOT_READY

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

  • Number of octets transmitted, if no errors are returned.

  • 0, if any errors returned.

Notes / Warnings#

  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.

USBD_EP_MaxPktSizeGet()#

Description#

Retrieves the endpoint maximum packet size.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

CPU_INT16U USBD_EP_MaxPktSizeGet (CPU_INT08U    dev_nbr,
                                  CPU_INT08U    ep_addr,
                                  RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_EP_INVALID

Returned Value#

  • Maximum packet size, if no errors are returned.

  • 0, if any errors returned.

Notes / Warnings#

None.

USBD_EP_MaxNbrOpenGet()#

Description#

Retrieves the maximum number of opened endpoints.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

CPU_INT08U USBD_EP_MaxNbrOpenGet (CPU_INT08U   dev_nbr)

Arguments#

dev_nbr

Device number.

Returned Value#

  • Maximum number of opened endpoints, if no errors are returned.

  • 0, if any errors returned.

Notes / Warnings#

None.

USBD_EP_Abort()#

Description#

Aborts I/O transfer on the endpoint.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

void USBD_EP_Abort (CPU_INT08U    dev_nbr,
                    CPU_INT08U    ep_addr,
                    RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_NONE_WAITING

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

None.

USBD_EP_Stall()#

Description#

Stalls the non-control endpoint.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

void USBD_EP_Stall (CPU_INT08U     dev_nbr,
                    CPU_INT08U     ep_addr,
                    CPU_BOOLEAN    state,
                    RTOS_ERR      *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

state

Endpoint stall state.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_NONE_WAITING

  • RTOS_ERR_EP_INVALID

  • RTOS_ERR_OS_SCHED_LOCKED

  • RTOS_ERR_NOT_AVAIL

  • RTOS_ERR_FAIL

  • RTOS_ERR_WOULD_OVF

  • RTOS_ERR_OS_OBJ_DEL

  • RTOS_ERR_INVALID_HANDLE

  • RTOS_ERR_WOULD_BLOCK

  • RTOS_ERR_IS_OWNER

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

None.

USBD_EP_IsStalled()#

Description#

Gets the stall status of a non-control endpoint.

Files#

usbd_ep.h/usbd_ep.c

Prototype#

CPU_BOOLEAN USBD_EP_IsStalled (CPU_INT08U    dev_nbr,
                               CPU_INT08U    ep_addr,
                               RTOS_ERR     *p_err)

Arguments#

dev_nbr

Device number.

ep_addr

Endpoint address.

p_err

Pointer to the variable that will receive one of these returned error codes from this function :

  • RTOS_ERR_NONE

  • RTOS_ERR_EP_INVALID

Returned Value#

  • DEF_TRUE, if endpoint is stalled.

  • DEF_FALSE, if endpoint is not stalled.

Notes / Warnings#

None.