USB Device Vendor API#

USBD_Vendor_ConfigureMsExtPropertiesQty()#

Description#

Configures the quantity of Microsoft extended properties. Ignored when USBD_CFG_MS_OS_DESC_EN is set do DEF_DISABLED.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

void  USBD_Vendor_ConfigureMsExtPropertiesQty (CPU_INT08U  ms_ext_properties_qty)

Arguments#

ms_ext_properties_qty

Quantity of Microsoft extended properties.

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 Vendor class is initialized via the USBD_Vendor_Init() function.

USBD_Vendor_ConfigureMemSeg()#

Description#

Configures the memory segment to use when allocating control data.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

void  USBD_Vendor_ConfigureMemSeg (MEM_SEG  *p_mem_seg)

Arguments#

p_mem_seg

Pointer to memory segment to use when allocating control data. 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 Vendor class is initialized via the USBD_Vendor_Init() function.

USBD_Vendor_Init()#

Description#

Initializes the internal structures and variables used by the Vendor class.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

void USBD_Vendor_Init (USBD_VENDOR_QTY_CFG  *p_qty_cfg,                       RTOS_ERR             *p_err)

Arguments#

p_qty_cfg

Pointer to the vendor class configuration structure.

p_err

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

  • RTOS_ERR_NONE

  • RTOS_ERR_SEG_OVF

Returned Value#

None.

Notes / Warnings#

None.

USBD_Vendor_Add()#

Description#

Adds a new instance of the Vendor class.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

CPU_INT08U USBD_Vendor_Add (CPU_BOOLEAN             intr_en,
                            CPU_INT16U              interval,
                            USBD_VENDOR_REQ_FNCT    req_callback,
                            RTOS_ERR               *p_err)

Arguments#

intr_en

Interrupt endpoints IN and OUT flag:

  • DEF_TRUE Pair of interrupt endpoints added to interface.

  • DEF_FALSE Pair of interrupt endpoints not added to interface.

interval

Endpoint interval in milliseconds (must be a power of 2).

req_callback

Vendor-specific request callback.

p_err

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

  • RTOS_ERR_NONE

  • RTOS_ERR_CLASS_INSTANCE_ALLOC

Returned Value#

  • Class instance number, if no errors are returned.

  • USBD_CLASS_NBR_NONE, otherwise.

Notes / Warnings#

None.

USBD_Vendor_ConfigAdd()#

Description#

Adds the Vendor class instance into the specified configuration (see Note #1).

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

void USBD_Vendor_ConfigAdd (CPU_INT08U    class_nbr,
                            CPU_INT08U    dev_nbr,
                            CPU_INT08U    config_nbr,
                            RTOS_ERR     *p_err)

Arguments#

class_nbr

Class instance number.

dev_nbr

Device number.

config_nbr

Configuration index to which to add the Vendor class instance.

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_IF_ALT_ALLOC

  • RTOS_ERR_ALLOC

  • RTOS_ERR_CLASS_INSTANCE_ALLOC

  • RTOS_ERR_IF_ALLOC

  • RTOS_ERR_INVALID_ARG

  • RTOS_ERR_EP_ALLOC

  • RTOS_ERR_EP_NONE_AVAIL

Returned Value#

None.

Notes / Warnings#

  1. Called several times, it creates multiple instances and configurations. For instance, the following architecture could be created:

    HS

|-- Configuration 0
|-- Interface 0 (Vendor 0)
|-- Configuration 1
|-- Interface 0 (Vendor 0)
|-- Interface 1 (Vendor 1)

    In this example, there are two instances of Vendor class: 'Vendor 0' and '1', and two possible configurations: 'Configuration 0' and '1'. 'Configuration 1' is composed of two interfaces.

    Each class instance has an association with one of the interfaces. If 'Configuration 1' is activated by the host, it allows the host to access two different functionalities offered by the device.

  2. Configuration Descriptor corresponding to a Vendor-specific device has the following format:

    Configuration Descriptor
|-- Interface Descriptor (Vendor class)
|-- Endpoint Descriptor (Bulk OUT)
|-- Endpoint Descriptor (Bulk IN)
|-- Endpoint Descriptor (Interrupt OUT) - optional
|-- Endpoint Descriptor (Interrupt IN) - optional

USBD_Vendor_IsConn()#

Description#

Gets the vendor class connection state.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

CPU_BOOLEAN USBD_Vendor_IsConn (CPU_INT08U   class_nbr)

Arguments#

class_nbr

Class instance number.

Returned Value#

  • DEF_YES, if the Vendor class is connected.

  • DEF_NO, if the Vendor class is not connected.

Notes / Warnings#

None.

USBD_Vendor_IntrRd()#

Description#

Receives the data from the host through the Interrupt OUT endpoint. This function is blocking.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

CPU_INT32U USBD_Vendor_IntrRd (CPU_INT08U    class_nbr,
                               void         *p_buf,
                               CPU_INT32U    buf_len,
                               CPU_INT16U    timeout,
                               RTOS_ERR     *p_err)

Arguments#

class_nbr

Class instance number.

p_buf

Pointer to the receive buffer.

buf_len

Receive buffer length in octets.

timeout

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_CLASS_STATE

  • 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 are returned.

Notes / Warnings#

None.

USBD_Vendor_IntrRdAsync()#

Description#

Receives the data from the host through Interrupt OUT endpoint. This function is non-blocking and returns immediately after transfer preparation. Upon transfer completion, a callback provided by the application will be called to finalize the transfer.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

void USBD_Vendor_IntrRdAsync (CPU_INT08U                class_nbr,
                              void                     *p_buf,
                              CPU_INT32U                buf_len,
                              USBD_VENDOR_ASYNC_FNCT    async_fnct,
                              void                     *p_async_arg,
                              RTOS_ERR                 *p_err)

Arguments#

class_nbr

Class instance number.

p_buf

Pointer to the receive buffer.

buf_len

Receive the buffer length in octets.

async_fnct

Receive the callback.

p_async_arg

Additional argument provided by application for the receive callback.

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_CLASS_STATE

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

None.

USBD_Vendor_IntrWr()#

Description#

Sends data to the host through the Interrupt IN endpoint. This function is blocking.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

CPU_INT32U USBD_Vendor_IntrWr (CPU_INT08U     class_nbr,
                               void          *p_buf,
                               CPU_INT32U     buf_len,
                               CPU_INT16U     timeout,
                               CPU_BOOLEAN    end,
                               RTOS_ERR      *p_err)

Arguments#

class_nbr

Class instance number.

p_buf

Pointer to the transmit buffer.

buf_len

Transmit buffer length in octets.

timeout

Timeout in milliseconds.

end

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

p_err

  • 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_CLASS_STATE

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

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

  • 0, if any errors are returned.

Notes / Warnings#

  1. If the end-of-transfer is set and the transfer length is a multiple of the maximum packet size, a zero-length packet is transferred to signal the end of transfer to the host.

USBD_Vendor_IntrWrAsync()#

Description#

Send the data to the host through the Interrupt IN endpoint. This function is non-blocking and returns immediately after transfer preparation. Upon transfer completion, a callback provided by the application will be called to finalize the transfer.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

void USBD_Vendor_IntrWrAsync (CPU_INT08U                class_nbr,
                              void                     *p_buf,
                              CPU_INT32U                buf_len,
                              USBD_VENDOR_ASYNC_FNCT    async_fnct,
                              void                     *p_async_arg,
                              CPU_BOOLEAN               end,
                              RTOS_ERR                 *p_err)

Arguments#

class_nbr

Class instance number.

p_buf

Pointer to the transmit buffer.

buf_len

Transmit buffer length in octets.

async_fnct

Transmit callback.

p_async_arg

Additional argument provided by the application for the transmit callback.

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_IS_OWNER

  • RTOS_ERR_INVALID_CLASS_STATE

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

  1. If the end-of-transfer is set and the transfer length is a multiple of the maximum packet size, a zero-length packet is transferred to signal the end of transfer to the host.

USBD_Vendor_MS_ExtPropertyAdd()#

Description#

Adds a Microsoft OS extended property to this vendor class instance.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

void USBD_Vendor_MS_ExtPropertyAdd ( CPU_INT08U    class_nbr,
                                     CPU_INT08U    property_type,
                               const CPU_INT08U   *p_property_name,
                                     CPU_INT16U    property_name_len,
                               const CPU_INT08U   *p_property,
                                     CPU_INT32U    property_len,
                                     RTOS_ERR     *p_err)

Arguments#

class_nbr

Class instance number.

property_type

Property type (see Note #2).

  • USBD_MS_OS_PROPERTY_TYPE_REG_SZ

  • USBD_MS_OS_PROPERTY_TYPE_REG_EXPAND_SZ

  • USBD_MS_OS_PROPERTY_TYPE_REG_BINARY

  • USBD_MS_OS_PROPERTY_TYPE_REG_DWORD_LITTLE_ENDIAN

  • USBD_MS_OS_PROPERTY_TYPE_REG_DWORD_BIG_ENDIAN

  • USBD_MS_OS_PROPERTY_TYPE_REG_LINK

  • USBD_MS_OS_PROPERTY_TYPE_REG_MULTI_SZ

p_property_name

Pointer to the buffer that contains the property name.

---- Buffer assumed to be persistent ----

property_name_len

Length of the property name in octets.

p_property

Pointer to the buffer that contains the property.

---- Buffer assumed to be persistent ----

property_len

Length of the property in octets.

p_err

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

  • RTOS_ERR_NONE

Returned Value#

None.

Notes / Warnings#

  1. For more information on Microsoft OS descriptors, see http://msdn.microsoft.com/en-us/library/windows/hardware/gg463179.aspx .

  2. For more information on property types, refer to "Table 3. Property Data Types" of "Extended Properties OS Feature Descriptor Specification" document provided by Microsoft available at:

    http://msdn.microsoft.com/en-us/library/windows/hardware/gg463179.aspx

USBD_Vendor_Rd()#

Description#

Receive the data from the host through the Bulk OUT endpoint. This function is blocking.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

CPU_INT32U USBD_Vendor_Rd (CPU_INT08U    class_nbr,
                           void         *p_buf,
                           CPU_INT32U    buf_len,
                           CPU_INT16U    timeout,
                           RTOS_ERR     *p_err)

Arguments#

class_nbr

Class instance number.

p_buf

Pointer to the receive buffer.

buf_len

Receive the buffer length in octets.

timeout

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_CLASS_STATE

  • 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 are returned.

Notes / Warnings#

None.

USBD_Vendor_RdAsync()#

Description#

Receive the data from the host through the Bulk OUT endpoint. This function is non-blocking are returns immediately after transfer preparation. Upon transfer completion, a callback provided by the application will be called to finalize the transfer.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

void USBD_Vendor_RdAsync (CPU_INT08U                class_nbr,
                          void                     *p_buf,
                          CPU_INT32U                buf_len,
                          USBD_VENDOR_ASYNC_FNCT    async_fnct,
                          void                     *p_async_arg,
                          RTOS_ERR                 *p_err)

Arguments#

class_nbr

Class instance number.

p_buf

Pointer to the receive buffer.

buf_len

Receive buffer length in octets.

async_fnct

Receive the the callback.

p_async_arg

Additional argument provided by the application for the receive callback.

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_CLASS_STATE

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

None.

USBD_Vendor_Wr()#

Description#

Sends the data to host through Bulk IN endpoint. This function is blocking.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

CPU_INT32U USBD_Vendor_Wr (CPU_INT08U     class_nbr,
                           void          *p_buf,
                           CPU_INT32U     buf_len,
                           CPU_INT16U     timeout,
                           CPU_BOOLEAN    end,
                           RTOS_ERR      *p_err)

Arguments#

class_nbr

Class instance number.

p_buf

Pointer to the transmit buffer.

buf_len

Transmit the buffer length in octets.

timeout

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_IS_OWNER

  • RTOS_ERR_INVALID_CLASS_STATE

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

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

  • 0, if any errors are returned.

Notes / Warnings#

  1. If the end-of-transfer is set and the transfer length is a multiple of the maximum packet size, a zero-length packet is transferred to signal the end of transfer to the host.

USBD_Vendor_WrAsync()#

Description#

Sends the data to host through Bulk IN endpoint. This function is non-blocking and returns immediately after transfer preparation. Upon transfer completion, a callback provided by the application will be called to finalize the transfer.

Files#

usbd_vendor.h/usbd_vendor.c

Prototype#

void USBD_Vendor_WrAsync (CPU_INT08U                class_nbr,
                          void                     *p_buf,
                          CPU_INT32U                buf_len,
                          USBD_VENDOR_ASYNC_FNCT    async_fnct,
                          void                     *p_async_arg,
                          CPU_BOOLEAN               end,
                          RTOS_ERR                 *p_err)

Arguments#

class_nbr

Class instance number.

p_buf

Pointer to the transmit buffer.

buf_len

Transmit buffer length in octets.

async_fnct

Transmit the callback.

p_async_arg

Additional argument provided by the application for the transmit callback.

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_IS_OWNER

  • RTOS_ERR_INVALID_CLASS_STATE

  • RTOS_ERR_INVALID_EP_STATE

  • RTOS_ERR_ABORT

  • RTOS_ERR_TIMEOUT

Returned Value#

None.

Notes / Warnings#

  1. If the end-of-transfer is set and the transfer length is a multiple of the maximum packet size, a zero-length packet is transferred to signal the end of transfer to the host.