nRF52840 only: Module for easy support for any USB device configuration. More...
Modules | |
USBD Class Base module | |
nRF52840 only: The base for any class instance is defined in this module. | |
USB Device high level library core module | |
nRF52840 only: Core module that manages current USB state and process device requests. | |
USB standard descriptors | |
nRF52840 only: Module with types definitions used for standard descriptors. | |
USB standard requests | |
nRF52840 only: Module with types definitions used for standard requests processing. | |
USBD serial number generator | |
nRF52840 only: Generate a standard USB serial number that is unique for each device. | |
USBD string descriptors | |
nRF52840 only: USBD string descriptor management. | |
USB Device high level library variable types definition | |
nRF52840 only: All types used by USB Device high level library are defined here. This helps to avoid cross referencing into types in different files. | |
USB AUDIO class | |
nRF52840 only: Module with types, definitions, and API used by USB Audio class. | |
USB CDC ACM class | |
nRF52840 only: Module with types, definitions and API used by CDC ACM class. | |
USB Dummy class | |
nRF52840 only: Module with types, definitions, and API used by the USB Dummy class. | |
USB HID class | |
nRF52840 only: Module with generic HID event data processing. | |
USB MSC class | |
nRF52840 only: Module with types, definitions, and API used by the USB MSC class. | |
USB Nordic DFU Trigger class | |
nRF52840 only: Module with types, definitions, and API used by the USB Nordic DFU Trigger class. | |
USB Device library configuration | |
Data Structures | |
struct | app_usbd_config_t |
Configuration passed to app_usbd_init. More... | |
Macros | |
#define | APP_USBD_SOF_MAX 2047 |
Highest value of Frame Number in SOF packets. | |
#define | APP_USBD_PROVIDE_SOF_TIMESTAMP 0 |
True if SOF timestamping is really provided. More... | |
#define | APP_USBD_SOF_HANDLING_NORMAL_QUEUE 0 |
SOF event handling modes. More... | |
#define | APP_USBD_SOF_HANDLING_COMPRESS_QUEUE 1 |
Compress SOF events. | |
#define | APP_USBD_SOF_HANDLING_INTERRUPT 2 |
Handle SOF events in interrupt. | |
Functions | |
uint32_t | app_usbd_sof_timestamp_get (void) |
Timestamp function for the logger. More... | |
ret_code_t | app_usbd_init (app_usbd_config_t const *p_config) |
USB library initialization. More... | |
ret_code_t | app_usbd_uninit (void) |
USB library un-initialization. More... | |
ret_code_t | app_usbd_power_events_enable (void) |
Function to start USB related power events processing. More... | |
void | app_usbd_enable (void) |
Enable USBD. More... | |
void | app_usbd_disable (void) |
Disable USBD. More... | |
void | app_usbd_start (void) |
Request USBD to start. More... | |
void | app_usbd_stop (void) |
Stop USB. More... | |
void | app_usbd_suspend_req (void) |
Request library to suspend. More... | |
bool | app_usbd_wakeup_req (void) |
Request library to wake-up. More... | |
bool | app_usbd_active_check (void) |
Get information whether there is an active connection. More... | |
void | app_usbd_event_execute (app_usbd_internal_evt_t const *const p_event) |
USBD event processor. More... | |
bool | app_usbd_event_queue_process (void) |
Function that process events from the queue. More... | |
ret_code_t | app_usbd_class_append (app_usbd_class_inst_t const *p_cinst) |
Add class instance. More... | |
ret_code_t | app_usbd_class_remove (app_usbd_class_inst_t const *p_cinst) |
Remove class instance. More... | |
ret_code_t | app_usbd_class_remove_all (void) |
Remove all class instances. More... | |
ret_code_t | app_usbd_ep_handler_set (app_usbd_class_inst_t const *p_cinst, nrf_drv_usbd_ep_t ep, app_usbd_ep_event_handler_t handler) |
Change endpoint handler. More... | |
ret_code_t | app_usbd_class_sof_register (app_usbd_class_inst_t const *p_cinst) |
Register class instance as the one that requires SOF events. More... | |
ret_code_t | app_usbd_class_sof_unregister (app_usbd_class_inst_t const *p_cinst) |
Unregister class instance from SOF processing instances list. More... | |
ret_code_t | app_usbd_class_sof_interrupt_register (app_usbd_class_inst_t const *p_cinst, app_usbd_sof_interrupt_handler_t handler) |
Register class instance as the one that requires SOF events in interrupt. More... | |
ret_code_t | app_usbd_class_sof_interrupt_unregister (app_usbd_class_inst_t const *p_cinst) |
Unregister class instance from SOF processing in interrupt instances list. More... | |
ret_code_t | app_usbd_class_rwu_register (app_usbd_class_inst_t const *const p_inst) |
Register class on remote wake-up feature. More... | |
ret_code_t | app_usbd_class_rwu_unregister (app_usbd_class_inst_t const *const p_inst) |
Unregister class from remote wake-up feature. More... | |
bool | app_usbd_class_rwu_enabled_check (void) |
Check if there is any class with remote wakeup. More... | |
ret_code_t | app_usbd_class_descriptor_find (app_usbd_class_inst_t const *const p_cinst, uint8_t desc_type, uint8_t desc_index, uint8_t *p_desc, size_t *p_desc_len) |
Find a specified descriptor. More... | |
ret_code_t | app_usbd_interface_ep_reset (app_usbd_class_inst_t const *const p_cinst, uint8_t iface) |
Standard set interface request handle. More... | |
void | app_usbd_ep_enable (nrf_drv_usbd_ep_t ep) |
Enable selected endpoint. More... | |
void | app_usbd_ep_disable (nrf_drv_usbd_ep_t ep) |
Disable selected endpoint. More... | |
app_usbd_class_inst_t const * | app_usbd_iface_find (uint8_t iface, uint8_t *p_iface_idx) |
Search for selected interface. More... | |
ret_code_t | app_usbd_ep_transfer (nrf_drv_usbd_ep_t ep, nrf_drv_usbd_transfer_t const *const p_transfer) |
Endpoint transfer. More... | |
ret_code_t | app_usbd_ep_handled_transfer (nrf_drv_usbd_ep_t ep, nrf_drv_usbd_handler_desc_t const *const p_handler) |
Set up an endpoint handled transfer. More... | |
ret_code_t | app_usbd_iface_select (app_usbd_class_inst_t const *const p_inst, uint8_t iface_idx, uint8_t alternate) |
Select interface. More... | |
void | app_usbd_iface_deselect (app_usbd_class_inst_t const *const p_inst, uint8_t iface_idx) |
Deselect interface. More... | |
uint8_t | app_usbd_iface_selection_get (app_usbd_class_inst_t const *const p_inst, uint8_t iface_idx) |
Get selected interface. More... | |
void | app_usbd_all_iface_select_0 (void) |
Select alternate configuration 0 for all interfaces. More... | |
void | app_usbd_all_iface_deselect (void) |
Deselect all interfaces. More... | |
Iterate through classes lists | |
Functions that helps to iterate through internally chained classes. | |
app_usbd_class_inst_t const * | app_usbd_class_first_get (void) |
Get first class instance in the list. More... | |
static app_usbd_class_inst_t const * | app_usbd_class_next_get (app_usbd_class_inst_t const *const p_cinst) |
Get next instance in the list. More... | |
app_usbd_class_inst_t const * | app_usbd_class_sof_first_get (void) |
Get first instance in SOF list. More... | |
static app_usbd_class_inst_t const * | app_usbd_class_sof_next_get (app_usbd_class_inst_t const *const p_cinst) |
Get next instance in the SOF list. More... | |
app_usbd_class_inst_t const * | app_usbd_class_sof_interrupt_first_get (void) |
Get first instance in SOF interrupt list. More... | |
static app_usbd_class_inst_t const * | app_usbd_class_sof_interrupt_next_get (app_usbd_class_inst_t const *const p_cinst) |
Get next instance in the SOF interrupt list. More... | |
Communicate with interfaces, endpoints and instances inside usbd library | |
ret_code_t | app_usbd_iface_call (app_usbd_class_inst_t const *const p_class_inst, uint8_t iface_idx, app_usbd_complex_evt_t const *const p_event) |
Call interface event handler. More... | |
ret_code_t | app_usbd_ep_call (nrf_drv_usbd_ep_t ep, app_usbd_complex_evt_t const *const p_event) |
Call endpoint event handler. More... | |
void | app_usbd_all_call (app_usbd_complex_evt_t const *const p_event) |
Auxiliary function that process event by every instance in the list. More... | |
ret_code_t | app_usbd_all_until_served_call (app_usbd_complex_evt_t const *const p_event) |
Call interface event handlers and stop when served. More... | |
nRF52840 only: Module for easy support for any USB device configuration.
This module manages class instances that would create the USB device, manages endpoints and interfaces transactions.
#define APP_USBD_PROVIDE_SOF_TIMESTAMP 0 |
True if SOF timestamping is really provided.
SOF timestamping is really provided if it was requested and if the logger is enabled.
#define APP_USBD_SOF_HANDLING_NORMAL_QUEUE 0 |
SOF event handling modes.
Push SOF events into event queue.
bool app_usbd_active_check | ( | void | ) |
Get information whether there is an active connection.
Function to check if the communication with the bus is possible.
true | The bus is active. |
false | There is no connection or bus is suspended. |
void app_usbd_all_call | ( | app_usbd_complex_evt_t const *const | p_event | ) |
Auxiliary function that process event by every instance in the list.
This function ignores the result of called handler.
p_event | Event to pass to every instance. |
void app_usbd_all_iface_deselect | ( | void | ) |
Deselect all interfaces.
Auxiliary function to disable all interfaces.
void app_usbd_all_iface_select_0 | ( | void | ) |
Select alternate configuration 0 for all interfaces.
Auxiliary function that clears settings for all interfaces leaving them enabled.
ret_code_t app_usbd_all_until_served_call | ( | app_usbd_complex_evt_t const *const | p_event | ) |
Call interface event handlers and stop when served.
Call event handlers from instances as long as we get result different than NRF_ERROR_NOT_SUPPORTED
[in] | p_event | Event structure to send. |
ret_code_t app_usbd_class_append | ( | app_usbd_class_inst_t const * | p_cinst | ) |
Add class instance.
This function connects given instance into internal class instance chain and into all required endpoints. The instance event handler would be connected into endpoint by default, but this can be overwritten by app_usbd_ep_handler_set.
After successful attachment APP_USBD_EVT_INST_APPEND would be passed to class instance.
[in,out] | p_cinst | Instance to connect. Chain data would be written into writable instance data. |
NRF_SUCCESS | Instance successfully added. |
NRF_ERROR_BUSY | Endpoint(s) not available. |
ret_code_t app_usbd_class_descriptor_find | ( | app_usbd_class_inst_t const *const | p_cinst, |
uint8_t | desc_type, | ||
uint8_t | desc_index, | ||
uint8_t * | p_desc, | ||
size_t * | p_desc_len | ||
) |
Find a specified descriptor.
[in] | p_cinst | Class instance. |
[in] | desc_type | Descriptor type app_usbd_descriptor_t |
[in] | desc_index | Descriptor index. |
[out] | p_desc | Pointer to escriptor. |
[out] | p_desc_len | Length of descriptor. |
NRF_SUCCESS | Descriptor successfully found. |
NRF_ERROR_NOT_FOUND | Descriptor not found. |
app_usbd_class_inst_t const* app_usbd_class_first_get | ( | void | ) |
Get first class instance in the list.
Get first instance from the list of active class instances. That instance may be used then in app_usbd_class_next_get function.
|
inlinestatic |
Get next instance in the list.
Get the next instance from the list of active instances. Used to iterate through all instances.
[in] | p_cinst | The current instance from with next one is required. |
ret_code_t app_usbd_class_remove | ( | app_usbd_class_inst_t const * | p_cinst | ) |
Remove class instance.
Instance is removed from instance chain. Instance and event handlers are removed also from endpoints. Endpoints used by by the class instance are left disabled.
p_cinst | Instance pointer to remove. |
NRF_SUCCESS | Instance successfully removed. |
NRF_ERROR_NOT_FOUND | Instance not found in the instance chain. |
ret_code_t app_usbd_class_remove_all | ( | void | ) |
Remove all class instances.
This function basically calls app_usbd_class_remove on instances chain as long as there is any element left.
bool app_usbd_class_rwu_enabled_check | ( | void | ) |
Check if there is any class with remote wakeup.
The function checks internal registered class with remote wakeup counter.
true | The remote wakeup functionality is required by some class instance. |
false | There is no class instance that requires wakeup functionality. |
ret_code_t app_usbd_class_rwu_register | ( | app_usbd_class_inst_t const *const | p_inst | ) |
Register class on remote wake-up feature.
[in] | p_inst | Instance of the class. |
NRF_SUCCESS | Instance that requires remote wake-up registered. |
ret_code_t app_usbd_class_rwu_unregister | ( | app_usbd_class_inst_t const *const | p_inst | ) |
Unregister class from remote wake-up feature.
[in] | p_inst | Instance of the class. |
NRF_SUCCESS | Instance that requires remote wake-up removed. |
app_usbd_class_inst_t const* app_usbd_class_sof_first_get | ( | void | ) |
Get first instance in SOF list.
Start iteration through the list of instances that require SOF event processing.
app_usbd_class_inst_t const* app_usbd_class_sof_interrupt_first_get | ( | void | ) |
Get first instance in SOF interrupt list.
Start iteration through the list of instances that require SOF processing in interrupt.
|
inlinestatic |
Get next instance in the SOF interrupt list.
Get the next instance from the list of instances requiring SOF processing in interrupt. Used to iterate through all SOF instances that have SOF handlers.
p_cinst | The current instance from with next one is required. |
ret_code_t app_usbd_class_sof_interrupt_register | ( | app_usbd_class_inst_t const * | p_cinst, |
app_usbd_sof_interrupt_handler_t | handler | ||
) |
Register class instance as the one that requires SOF events in interrupt.
This function should be called in reaction on APP_USBD_EVT_INST_APPEND event. Connect the class instance to the list of instances that requires SOF processing. If none of the appended instances requires SOF event - it is disabled.
p_cinst | Instance that requires SOF event. |
handler | Handler to SOF event |
NRF_SUCCESS | Instance linked into SOF processing list. |
ret_code_t app_usbd_class_sof_interrupt_unregister | ( | app_usbd_class_inst_t const * | p_cinst | ) |
Unregister class instance from SOF processing in interrupt instances list.
Every class that calls app_usbd_class_sof_interrupt_register have to call also unregistering function in reaction to APP_USBD_EVT_INST_REMOVE event.
p_cinst | Instance to be unregistered from SOF processing in interrupt list. |
NRF_SUCCESS | Instance linked into SOF processing in interrupt list. |
NRF_ERROR_NOT_FOUND | Instance not found in the SOF processing in interrupt list. |
|
inlinestatic |
Get next instance in the SOF list.
Get the next instance from the list of instances requiring SOF event processing. Used to iterate through all SOF instances.
p_cinst | The current instance from with next one is required. |
ret_code_t app_usbd_class_sof_register | ( | app_usbd_class_inst_t const * | p_cinst | ) |
Register class instance as the one that requires SOF events.
This function should be called in reaction on APP_USBD_EVT_INST_APPEND event. Connect the class instance to the list of instances that requires SOF processing. If none of the appended instances requires SOF event - it is disabled.
p_cinst | Instance that requires SOF event. |
NRF_SUCCESS | Instance linked into SOF processing list. |
ret_code_t app_usbd_class_sof_unregister | ( | app_usbd_class_inst_t const * | p_cinst | ) |
Unregister class instance from SOF processing instances list.
Every class that calls app_usbd_class_sof_register have to call also unregistering function in reaction to APP_USBD_EVT_INST_REMOVE event.
p_cinst | Instance to be unregistered from SOF event processing list. |
NRF_SUCCESS | Instance linked into SOF processing list. |
NRF_ERROR_NOT_FOUND | Instance not found in the SOF processing list. |
void app_usbd_disable | ( | void | ) |
Disable USBD.
Disabled USDB peripheral cannot be accessed but also stops requesting High Frequency clock and releases power regulator.
void app_usbd_enable | ( | void | ) |
Enable USBD.
USBD is enabled. Since now the high frequency clock may be requested when USB RESET would be detected.
ret_code_t app_usbd_ep_call | ( | nrf_drv_usbd_ep_t | ep, |
app_usbd_complex_evt_t const *const | p_event | ||
) |
Call endpoint event handler.
Call event handler for the selected endpoint.
[in] | ep | Endpoint number. |
[in] | p_event | Event structure to send. |
void app_usbd_ep_disable | ( | nrf_drv_usbd_ep_t | ep | ) |
Disable selected endpoint.
ep | Endpoint number. |
void app_usbd_ep_enable | ( | nrf_drv_usbd_ep_t | ep | ) |
Enable selected endpoint.
Selected endpoint is enabled and cleared.
ep | Endpoint number. |
ret_code_t app_usbd_ep_handled_transfer | ( | nrf_drv_usbd_ep_t | ep, |
nrf_drv_usbd_handler_desc_t const *const | p_handler | ||
) |
Set up an endpoint handled transfer.
Configures a transfer handled by the feedback function.
ep | Endpoint number. |
p_handler | Function called when the next chunk of data is requested. |
NRF_ERROR_INVALID_STATE | The state of the USB device does not allow data transfer on the endpoint. |
ret_code_t app_usbd_ep_handler_set | ( | app_usbd_class_inst_t const * | p_cinst, |
nrf_drv_usbd_ep_t | ep, | ||
app_usbd_ep_event_handler_t | handler | ||
) |
Change endpoint handler.
This function may be called for the endpoint only if the class instance is already properly attached by the app_usbd_class_append function.
The endpoint event handler function can be only overwritten by the class instance that was connected into the endpoint.
[in] | p_cinst | Instance of a class that wish to set new event handler. It has to match currently configured instance for the selected endpoint. In other situation error would be returned. |
[in] | ep | Endpoint address to configure. |
[in] | handler | Event handler function to set. |
NRF_SUCCESS | New handler successfully set |
NRF_ERROR_INVALID_PARAM | p_cinst is not the same as currently set for the endpoint |
ret_code_t app_usbd_ep_transfer | ( | nrf_drv_usbd_ep_t | ep, |
nrf_drv_usbd_transfer_t const *const | p_transfer | ||
) |
Endpoint transfer.
ep | Endpoint number. |
p_transfer | Description of the transfer to be performed. The direction of the transfer is determined by the endpoint number. |
NRF_ERROR_INVALID_STATE | The state of the USB device does not allow data transfer on the endpoint. |
void app_usbd_event_execute | ( | app_usbd_internal_evt_t const *const | p_event | ) |
USBD event processor.
Function to be called on each event to be processed by the library.
bool app_usbd_event_queue_process | ( | void | ) |
Function that process events from the queue.
true | Event was processed. |
false | The event queue is empty. |
ret_code_t app_usbd_iface_call | ( | app_usbd_class_inst_t const *const | p_class_inst, |
uint8_t | iface_idx, | ||
app_usbd_complex_evt_t const *const | p_event | ||
) |
Call interface event handler.
Call event handler for selected interface.
[in,out] | p_class_inst | Class instance that holds selected interface. |
[in] | iface_idx | Index of the interface in class structure. |
[in] | p_event | Event structure to be processed. |
void app_usbd_iface_deselect | ( | app_usbd_class_inst_t const *const | p_inst, |
uint8_t | iface_idx | ||
) |
Deselect interface.
Disable the given interface. This function calls class interface deselection function or default interface selection function.
After calling this function all the endpoints from the interface have to be disabled.
[in,out] | p_inst | Instance of the class. |
[in] | iface_idx | Index of the interface inside class structure. |
app_usbd_class_inst_t const* app_usbd_iface_find | ( | uint8_t | iface, |
uint8_t * | p_iface_idx | ||
) |
Search for selected interface.
Function searches for the given interface number and returns the class that contains it. Optionally it can return interface index inside class instance.
[in] | iface | Interface number. |
[out] | p_iface_idx | Pointer to a variable that would hold interface index inside returned class instance. |
ret_code_t app_usbd_iface_select | ( | app_usbd_class_inst_t const *const | p_inst, |
uint8_t | iface_idx, | ||
uint8_t | alternate | ||
) |
Select interface.
Select the given interface. This function calls class interface selection function or default interface selection function.
After calling this function interface should be functional.
[in,out] | p_inst | Instance of the class. |
[in] | iface_idx | Index of the interface inside class structure. |
[in] | alternate | Alternate setting that should be selected. |
uint8_t app_usbd_iface_selection_get | ( | app_usbd_class_inst_t const *const | p_inst, |
uint8_t | iface_idx | ||
) |
Get selected interface.
Function retieves currently selected interface. If the class contains app_usbd_class_methods_t::iface_selection_get it is called. It it does not contain this function this function would return default, 0 value.
[in] | p_inst | Instance of the class. |
[in] | iface_idx | Index of the interface inside class structure. |
ret_code_t app_usbd_init | ( | app_usbd_config_t const * | p_config | ) |
USB library initialization.
Call this function before any configuration or class attachment. USBD peripheral would be ready to accept commands, and library would be ready, but it would not be connected to the bus. Call app_usbd_enable to enable USBD communication with the host.
p_config | Configuration. NULL pointer might be passed here and default configuration will be applied then. |
ret_code_t app_usbd_interface_ep_reset | ( | app_usbd_class_inst_t const *const | p_cinst, |
uint8_t | iface | ||
) |
Standard set interface request handle.
This function should be called when processing SET_INTERFACE request.
[in] | p_cinst | Instance of a class. |
[in] | iface | Interface number. |
ret_code_t app_usbd_power_events_enable | ( | void | ) |
Function to start USB related power events processing.
This function should be called after app_usbd_init and after all the required classes were appended (app_usbd_class_append).
NRF_SUCCESS | Power events successfully initialized. |
NRF_ERROR_INVALID_STATE | The state of the driver does not allow to enable the power events processing. |
uint32_t app_usbd_sof_timestamp_get | ( | void | ) |
Timestamp function for the logger.
void app_usbd_start | ( | void | ) |
Request USBD to start.
The function sends start request to the event queue. If the queue is enabled (APP_USBD_CONFIG_EVENT_QUEUE_ENABLE) it would be processed when the queue is processed. If queue is disabled it would be processed immediately inside this function. It means that if queue is disabled this function cannot be called from interrupt with priority higher than USB interrupt.
When start is processed it would:
void app_usbd_stop | ( | void | ) |
Stop USB.
The function sends stop request to the event queue. If the queue is enabled (APP_USBD_CONFIG_EVENT_QUEUE_ENABLE) it would be processed when the queue is processed. If queue is disabled it would be processed immediately inside this function. It means that if queue is disabled this function cannot be called from interrupt with priority higher than USB interrupt.
When the event is processed interrupts and USB pull-ups are disabled. The peripheral itself is left enabled so it can be programmed, but a HOST sees it as a peripheral disconnection.
void app_usbd_suspend_req | ( | void | ) |
Request library to suspend.
This function send suspend request to the event queue.
ret_code_t app_usbd_uninit | ( | void | ) |
USB library un-initialization.
bool app_usbd_wakeup_req | ( | void | ) |
Request library to wake-up.
This function send wakeup request to the event queue.
true | Wakeup generation has been started. |
false | No wakeup would be generated becouse it is disabled by the host. |