USB Device Vendor API
USB Device API

Description

USB Device Vendor API.

Data Structures

struct  sl_usbd_vendor_callbacks_t
 Vendor callbacks.

Functions

sl_status_t sl_usbd_vendor_init (void)
 Initialize the internal structures and variables used by the Vendor class.
 
sl_status_t sl_usbd_vendor_create_instance (bool intr_en, uint16_t interval, sl_usbd_vendor_callbacks_t *p_vendor_callbacks, uint8_t *p_class_nbr)
 Add a new instance of the Vendor class.
 
sl_status_t sl_usbd_vendor_add_to_configuration (uint8_t class_nbr, uint8_t config_nbr)
 Add the Vendor class instance into the specified configuration (see Note #1).
 
sl_status_t sl_usbd_vendor_is_enabled (uint8_t class_nbr, bool *p_enabled)
 Get the vendor class enable state.
 
sl_status_t sl_usbd_vendor_read_bulk_sync (uint8_t class_nbr, void *p_buf, uint32_t buf_len, uint16_t timeout, uint32_t *p_xfer_len)
 Add a Microsoft OS extended property to this vendor class instance.
 
sl_status_t sl_usbd_vendor_write_bulk_sync (uint8_t class_nbr, void *p_buf, uint32_t buf_len, uint16_t timeout, bool end, uint32_t *p_xfer_len)
 Send data to the host through Bulk IN endpoint.
 
sl_status_t sl_usbd_vendor_read_bulk_async (uint8_t class_nbr, void *p_buf, uint32_t buf_len, sl_usbd_vendor_async_function_t async_fnct, void *p_async_arg)
 Receive data from the host through the Bulk OUT endpoint.
 
sl_status_t sl_usbd_vendor_write_bulk_async (uint8_t class_nbr, void *p_buf, uint32_t buf_len, sl_usbd_vendor_async_function_t async_fnct, void *p_async_arg, bool end)
 Send data to the host through the Bulk IN endpoint.
 
sl_status_t sl_usbd_vendor_read_interrupt_sync (uint8_t class_nbr, void *p_buf, uint32_t buf_len, uint16_t timeout, uint32_t *p_xfer_len)
 Receive data from the the host through the Interrupt OUT endpoint.
 
sl_status_t sl_usbd_vendor_write_interrupt_sync (uint8_t class_nbr, void *p_buf, uint32_t buf_len, uint16_t timeout, bool end, uint32_t *p_xfer_len)
 Send data to the host through the Interrupt IN endpoint.
 
sl_status_t sl_usbd_vendor_read_interrupt_async (uint8_t class_nbr, void *p_buf, uint32_t buf_len, sl_usbd_vendor_async_function_t async_fnct, void *p_async_arg)
 Receive data from the host through Interrupt OUT endpoint.
 
sl_status_t sl_usbd_vendor_write_interrupt_async (uint8_t class_nbr, void *p_buf, uint32_t buf_len, sl_usbd_vendor_async_function_t async_fnct, void *p_async_arg, bool end)
 Send data to the host through the Interrupt IN endpoint.

Typedefs

typedef void(* sl_usbd_vendor_async_function_t) (uint8_t class_nbr, void *p_buf, uint32_t buf_len, uint32_t xfer_len, void *p_callback_arg, sl_status_t status)
 App callback used for async comm.

Function Documentation

◆ sl_usbd_vendor_init()

sl_status_t sl_usbd_vendor_init ( void  )

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

Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_vendor_create_instance()

sl_status_t sl_usbd_vendor_create_instance ( bool  intr_en,
uint16_t  interval,
sl_usbd_vendor_callbacks_t *  p_vendor_callbacks,
uint8_t *  p_class_nbr 
)

Add a new instance of the Vendor class.

Parameters
intr_enInterrupt endpoints IN and OUT flag:
  • true Pair of interrupt endpoints added to interface.
  • false Pair of interrupt endpoints not added to interface.
intervalEndpoint interval in milliseconds (must be a power of 2).
p_vendor_callbacksPointer to vendor callback structure. [Content MUST be persistent]
p_class_nbrPointer to a variable that will receive class instance number, if no errors are returned, or SL_USBD_CLASS_NBR_NONE otherwise.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_vendor_add_to_configuration()

sl_status_t sl_usbd_vendor_add_to_configuration ( uint8_t  class_nbr,
uint8_t  config_nbr 
)

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

Parameters
class_nbrClass instance number.
config_nbrConfiguration index to which to add the Vendor class instance.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(1) Called several times, it creates multiple instances and configurations. For instance, the following architecture could be created : 
*               FS
*               |-- Configuration 0
*                   |-- Interface 0 (Vendor 0)
*               |-- Configuration 1
*                   |-- Interface 0 (Vendor 0)
*                   |-- Interface 1 (Vendor 1)
*
In that 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
*

◆ sl_usbd_vendor_is_enabled()

sl_status_t sl_usbd_vendor_is_enabled ( uint8_t  class_nbr,
bool *  p_enabled 
)

Get the vendor class enable state.

Parameters
class_nbrClass instance number.
p_enabledPointer to a variable that will receive the enable state. The variable is set to true, if the Vendor class is enabled, and is set to false if the Vendor class is NOT enabled.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_vendor_read_bulk_sync()

sl_status_t sl_usbd_vendor_read_bulk_sync ( uint8_t  class_nbr,
void *  p_buf,
uint32_t  buf_len,
uint16_t  timeout,
uint32_t *  p_xfer_len 
)

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

Parameters
class_nbrClass instance number.
property_typeProperty type (see Note #2).
  • OS_PROPERTY_TYPE_REG_SZ
  • OS_PROPERTY_TYPE_REG_EXPAND_SZ
  • OS_PROPERTY_TYPE_REG_BINARY
  • OS_PROPERTY_TYPE_REG_DWORD_LITTLE_ENDIAN
  • OS_PROPERTY_TYPE_REG_DWORD_BIG_ENDIAN
  • OS_PROPERTY_TYPE_REG_LINK
  • OS_PROPERTY_TYPE_REG_MULTI_SZ
p_property_namePointer to the buffer that contains the property name. -— Buffer assumed to be persistent -—
property_name_lenLength of the property name in octets.
p_propertyPointer to the buffer that contains the property name. -— Buffer assumed to be persistent -—
property_lenLength of the property in octets.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(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'.

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

Parameters
class_nbrClass instance number.
p_bufPointer to the receive buffer.
buf_lenReceive the buffer length in octets.
timeoutTimeout in milliseconds.
p_xfer_lenPointer to a variable that will receive transfer length. The variable is set to number of octets received, if no errors are returned, or is set to 0 if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_vendor_write_bulk_sync()

sl_status_t sl_usbd_vendor_write_bulk_sync ( uint8_t  class_nbr,
void *  p_buf,
uint32_t  buf_len,
uint16_t  timeout,
bool  end,
uint32_t *  p_xfer_len 
)

Send data to the host through Bulk IN endpoint.

This function is blocking.

Parameters
class_nbrClass instance number.
p_bufPointer to the transmit buffer.
buf_lenTransmit the buffer length in octets.
timeoutTimeout in milliseconds.
endEnd-of-transfer flag (see Note #1).
p_xfer_lenPointer to a variable that will receive transfer length. The variable is set to number of octets received, if no errors are returned, or is set to 0 if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(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.

◆ sl_usbd_vendor_read_bulk_async()

sl_status_t sl_usbd_vendor_read_bulk_async ( uint8_t  class_nbr,
void *  p_buf,
uint32_t  buf_len,
sl_usbd_vendor_async_function_t  async_fnct,
void *  p_async_arg 
)

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

Parameters
class_nbrClass instance number.
p_bufPointer to the receive buffer.
buf_lenReceive buffer length in octets.
async_fnctReceive the the callback.
p_async_argAdditional argument provided by the application for the receive callback.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_vendor_write_bulk_async()

sl_status_t sl_usbd_vendor_write_bulk_async ( uint8_t  class_nbr,
void *  p_buf,
uint32_t  buf_len,
sl_usbd_vendor_async_function_t  async_fnct,
void *  p_async_arg,
bool  end 
)

Send data to the host through the 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.

Parameters
class_nbrClass instance number.
p_bufPointer to the transmit buffer.
buf_lenTransmit buffer length in octets.
async_fnctTransmit the callback.
p_async_argAdditional argument provided by the application for the transmit callback.
endEnd-of-transfer flag (see Note #1).
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(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.

◆ sl_usbd_vendor_read_interrupt_sync()

sl_status_t sl_usbd_vendor_read_interrupt_sync ( uint8_t  class_nbr,
void *  p_buf,
uint32_t  buf_len,
uint16_t  timeout,
uint32_t *  p_xfer_len 
)

Receive data from the the host through the Interrupt OUT endpoint.

This function is blocking.

Parameters
class_nbrClass instance number.
p_bufPointer to the receive buffer.
buf_lenReceive buffer length in octets.
timeoutTimeout in milliseconds.
p_xfer_lenPointer to a variable that will receive transfer length. The variable is set to number of octets received, if no errors are returned, or is set to 0 if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_vendor_write_interrupt_sync()

sl_status_t sl_usbd_vendor_write_interrupt_sync ( uint8_t  class_nbr,
void *  p_buf,
uint32_t  buf_len,
uint16_t  timeout,
bool  end,
uint32_t *  p_xfer_len 
)

Send data to the host through the Interrupt IN endpoint.

This function is blocking.

Parameters
class_nbrClass instance number.
p_bufPointer to the transmit buffer.
buf_lenTransmit buffer length in octets.
timeoutTimeout in milliseconds.
endEnd-of-transfer flag (see Note #1).
p_xfer_lenPointer to a variable that will receive transfer length. The variable is set to number of octets received, if no errors are returned, or is set to 0 if any errors are returned.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(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.

◆ sl_usbd_vendor_read_interrupt_async()

sl_status_t sl_usbd_vendor_read_interrupt_async ( uint8_t  class_nbr,
void *  p_buf,
uint32_t  buf_len,
sl_usbd_vendor_async_function_t  async_fnct,
void *  p_async_arg 
)

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

Parameters
class_nbrClass instance number.
p_bufPointer to the receive buffer.
buf_lenReceive buffer length in octets.
async_fnctReceive callback.
p_async_argAdditional argument provided by application for the receive callback.
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.

◆ sl_usbd_vendor_write_interrupt_async()

sl_status_t sl_usbd_vendor_write_interrupt_async ( uint8_t  class_nbr,
void *  p_buf,
uint32_t  buf_len,
sl_usbd_vendor_async_function_t  async_fnct,
void *  p_async_arg,
bool  end 
)

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

Parameters
class_nbrClass instance number.
p_bufPointer to the transmit buffer.
buf_lenTransmit buffer length in octets.
async_fnctTransmit callback.
p_async_argAdditional argument provided by the application for the transmit callback.
endEnd-of-transfer flag (see Note #1).
Returns
Returns SL_STATUS_OK on success or another SL_STATUS code on failure.
Note
(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.

Typedef Documentation

◆ sl_usbd_vendor_async_function_t

typedef void(* sl_usbd_vendor_async_function_t) (uint8_t class_nbr, void *p_buf, uint32_t buf_len, uint32_t xfer_len, void *p_callback_arg, sl_status_t status)

App callback used for async comm.