817 lines
29 KiB
C
817 lines
29 KiB
C
|
/**
|
||
|
|
* Copyright (c) 2017 - 2021, Nordic Semiconductor ASA
|
||
|
|
*
|
||
|
|
* All rights reserved.
|
||
|
|
*
|
||
|
|
* Redistribution and use in source and binary forms, with or without modification,
|
||
|
|
* are permitted provided that the following conditions are met:
|
||
|
|
*
|
||
|
|
* 1. Redistributions of source code must retain the above copyright notice, this
|
||
|
|
* list of conditions and the following disclaimer.
|
||
|
|
*
|
||
|
|
* 2. Redistributions in binary form, except as embedded into a Nordic
|
||
|
|
* Semiconductor ASA integrated circuit in a product or a software update for
|
||
|
|
* such product, must reproduce the above copyright notice, this list of
|
||
|
|
* conditions and the following disclaimer in the documentation and/or other
|
||
|
|
* materials provided with the distribution.
|
||
|
|
*
|
||
|
|
* 3. Neither the name of Nordic Semiconductor ASA nor the names of its
|
||
|
|
* contributors may be used to endorse or promote products derived from this
|
||
|
|
* software without specific prior written permission.
|
||
|
|
*
|
||
|
|
* 4. This software, with or without modification, must only be used with a
|
||
|
|
* Nordic Semiconductor ASA integrated circuit.
|
||
|
|
*
|
||
|
|
* 5. Any software provided in binary form under this license must not be reverse
|
||
|
|
* engineered, decompiled, modified and/or disassembled.
|
||
|
|
*
|
||
|
|
* THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
|
||
|
|
* OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
||
|
|
* OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||
|
|
* DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
|
||
|
|
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||
|
|
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
|
||
|
|
* GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||
|
|
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||
|
|
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
|
||
|
|
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
|
|
*
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef APP_USBD_H__
|
||
|
|
#define APP_USBD_H__
|
||
|
|
|
||
|
|
#include "nrf_drv_usbd.h"
|
||
|
|
#include "app_usbd_types.h"
|
||
|
|
#include "app_usbd_class_base.h"
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C" {
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @defgroup app_usbd USB Device high level library
|
||
|
|
* @ingroup app_common
|
||
|
|
*
|
||
|
|
* @brief @tagAPI52840 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.
|
||
|
|
* @{
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Highest value of Frame Number in SOF packets.
|
||
|
|
*/
|
||
|
|
#define APP_USBD_SOF_MAX 2047
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief True if SOF timestamping is really provided.
|
||
|
|
*
|
||
|
|
* SOF timestamping is really provided if it was requested and if the logger is enabled.
|
||
|
|
*/
|
||
|
|
#if ((APP_USBD_CONFIG_SOF_TIMESTAMP_PROVIDE) && (NRF_LOG_ENABLED))
|
||
|
|
#define APP_USBD_PROVIDE_SOF_TIMESTAMP 1
|
||
|
|
#else
|
||
|
|
#define APP_USBD_PROVIDE_SOF_TIMESTAMP 0
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief SOF event handling modes.
|
||
|
|
*/
|
||
|
|
#define APP_USBD_SOF_HANDLING_NORMAL_QUEUE 0 //!< Push SOF events into event queue.
|
||
|
|
#define APP_USBD_SOF_HANDLING_COMPRESS_QUEUE 1 //!< Compress SOF events.
|
||
|
|
#define APP_USBD_SOF_HANDLING_INTERRUPT 2 //!< Handle SOF events in interrupt.
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Configuration passed to @ref app_usbd_init.
|
||
|
|
*/
|
||
|
|
typedef struct {
|
||
|
|
#if (!(APP_USBD_CONFIG_EVENT_QUEUE_ENABLE)) || defined(__SDK_DOXYGEN__)
|
||
|
|
/**
|
||
|
|
* @brief User defined event handler.
|
||
|
|
*
|
||
|
|
* This function is called on every event from the interrupt.
|
||
|
|
* It is prepared for external user function that would queue events to be processed
|
||
|
|
* from the main context.
|
||
|
|
* It should be used with operating systems with its own implementation of the queue.
|
||
|
|
*
|
||
|
|
* @param p_event The event structure pointer.
|
||
|
|
*
|
||
|
|
* @note This field is available only when USB internal queue is disabled
|
||
|
|
* (see @ref APP_USBD_CONFIG_EVENT_QUEUE_ENABLE).
|
||
|
|
*/
|
||
|
|
void (*ev_handler)(app_usbd_internal_evt_t const * const p_event);
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#if (APP_USBD_CONFIG_EVENT_QUEUE_ENABLE) || defined(__SDK_DOXYGEN__)
|
||
|
|
/**
|
||
|
|
* @brief User defined event handler.
|
||
|
|
*
|
||
|
|
* This function is called on every event from the interrupt.
|
||
|
|
*
|
||
|
|
* @param p_event The event structure pointer.
|
||
|
|
* @param queued The event is visible in the queue.
|
||
|
|
* If queue conflict is detected the event might not be accessible inside queue
|
||
|
|
* until all write operations finish.
|
||
|
|
* See @ref nrf_atfifo for more details.
|
||
|
|
*
|
||
|
|
* @note This field is available only when USBD internal queue is configured
|
||
|
|
* (see @ref APP_USBD_CONFIG_EVENT_QUEUE_ENABLE).
|
||
|
|
*
|
||
|
|
* @note If is set to NULL no event would be called from interrupt.
|
||
|
|
* @note This function is called before event is processed.
|
||
|
|
* It means that if the event type is @ref APP_USBD_EVT_DRV_SETUP,
|
||
|
|
* there would not be setup field present in the event structure.
|
||
|
|
*/
|
||
|
|
void (*ev_isr_handler)(app_usbd_internal_evt_t const * const p_event, bool queued);
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief User defined event processor
|
||
|
|
*
|
||
|
|
* This function is called while state event is processed.
|
||
|
|
*
|
||
|
|
* * @note This field is available only when USBD internal queue is configured
|
||
|
|
* (see @ref APP_USBD_CONFIG_EVENT_QUEUE_ENABLE).
|
||
|
|
*
|
||
|
|
* @param event Event type.
|
||
|
|
* Only following events are sent into this function:
|
||
|
|
* - APP_USBD_EVT_DRV_SOF
|
||
|
|
* - APP_USBD_EVT_DRV_RESET - Note that it also exits suspend
|
||
|
|
* - APP_USBD_EVT_DRV_SUSPEND
|
||
|
|
* - APP_USBD_EVT_DRV_RESUME - It is also generated when remote wakeup is generated
|
||
|
|
* - APP_USBD_EVT_START
|
||
|
|
* - APP_USBD_EVT_STOP
|
||
|
|
* - APP_USBD_EVT_STATE_CHANGED
|
||
|
|
* - APP_USBD_EVT_POWER_DETECTED
|
||
|
|
* - APP_USBD_EVT_POWER_REMOVED
|
||
|
|
* - APP_USBD_EVT_POWER_READY
|
||
|
|
*/
|
||
|
|
void (*ev_state_proc)(app_usbd_event_type_t event);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief SOF processing required by the user event processing.
|
||
|
|
*
|
||
|
|
* This flag would enable SOF processing for the user events regardless of the fact if any
|
||
|
|
* of the implemented class requires SOF event.
|
||
|
|
*
|
||
|
|
* @note SOF event would be enabled anyway if any of the appended class requires SOF processing.
|
||
|
|
*/
|
||
|
|
bool enable_sof;
|
||
|
|
} app_usbd_config_t;
|
||
|
|
|
||
|
|
|
||
|
|
#if (APP_USBD_PROVIDE_SOF_TIMESTAMP) || defined(__SDK_DOXYGEN__)
|
||
|
|
/**
|
||
|
|
* @brief Timestamp function for the logger.
|
||
|
|
*
|
||
|
|
* @return Current frame number taken directly from the last processed SOF.
|
||
|
|
*/
|
||
|
|
uint32_t app_usbd_sof_timestamp_get(void);
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief 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 @ref app_usbd_enable to enable USBD communication with the host.
|
||
|
|
*
|
||
|
|
* @param p_config Configuration. NULL pointer might be passed here and default
|
||
|
|
* configuration will be applied then.
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_init(app_usbd_config_t const * p_config);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief USB library un-initialization.
|
||
|
|
*
|
||
|
|
* @note Currently not supported.
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_uninit(void);
|
||
|
|
|
||
|
|
#if (APP_USBD_CONFIG_POWER_EVENTS_PROCESS) || defined(__SDK_DOXYGEN__)
|
||
|
|
/**
|
||
|
|
* @brief Function to start USB related power events processing.
|
||
|
|
*
|
||
|
|
* This function should be called after @ref app_usbd_init and after all the
|
||
|
|
* required classes were appended (@ref app_usbd_class_append).
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS Power events successfully initialized.
|
||
|
|
* @retval NRF_ERROR_INVALID_STATE The state of the driver does not allow to enable
|
||
|
|
* the power events processing.
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_power_events_enable(void);
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Enable USBD.
|
||
|
|
*
|
||
|
|
* USBD is enabled.
|
||
|
|
* Since now the high frequency clock may be requested when USB RESET would be detected.
|
||
|
|
*/
|
||
|
|
void app_usbd_enable(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Disable USBD.
|
||
|
|
*
|
||
|
|
* Disabled USDB peripheral cannot be accessed but also stops requesting
|
||
|
|
* High Frequency clock and releases power regulator.
|
||
|
|
*
|
||
|
|
* @note This function cannot be called when USB is started. Stop it first.
|
||
|
|
*/
|
||
|
|
void app_usbd_disable(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Request USBD to start.
|
||
|
|
*
|
||
|
|
* The function sends start request to the event queue.
|
||
|
|
* If the queue is enabled (@ref 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:
|
||
|
|
* 1. Start library.
|
||
|
|
* 2. Enable interrupts.
|
||
|
|
* 3. Enable USB pull-ups.
|
||
|
|
*
|
||
|
|
* @note
|
||
|
|
* In some specific circumstances the library can be left not started and this function would
|
||
|
|
* silently exit.
|
||
|
|
* This may happen if some glitches appears on USB power line or if the plug was disconnected before
|
||
|
|
* whole starting process finishes.
|
||
|
|
* User would get the event from POWER peripheral then.
|
||
|
|
* Also no @ref APP_USBD_EVT_STARTED event would be generated to the classes and user event handler.
|
||
|
|
* For the safe code it is recommended to wait for @ref APP_USBD_EVT_STARTED event if anything
|
||
|
|
* has to be initialized after USB driver is started (just before enabling the interrupts).
|
||
|
|
* If library is properly started the @ref APP_USBD_EVT_STARTED event passed to the user handler
|
||
|
|
* from this function body.
|
||
|
|
*/
|
||
|
|
void app_usbd_start(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Stop USB.
|
||
|
|
*
|
||
|
|
* The function sends stop request to the event queue.
|
||
|
|
* If the queue is enabled (@ref 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.
|
||
|
|
*
|
||
|
|
* @note
|
||
|
|
* If the library is not started when this function is called it exits silently - also
|
||
|
|
* no @ref APP_USBD_EVT_STOPPED is generated.
|
||
|
|
*/
|
||
|
|
void app_usbd_stop(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Request library to suspend.
|
||
|
|
*
|
||
|
|
* This function send suspend request to the event queue.
|
||
|
|
*
|
||
|
|
* @note This function should only be called after @ref APP_USBD_EVT_DRV_SUSPEND os received.
|
||
|
|
* Internal suspend request processing would give no effect if the bus is not in suspend state.
|
||
|
|
*/
|
||
|
|
void app_usbd_suspend_req(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Request library to wake-up.
|
||
|
|
*
|
||
|
|
* This function send wakeup request to the event queue.
|
||
|
|
*
|
||
|
|
* @note Calling this function does not mean that peripheral is active - the wakeup request is sent
|
||
|
|
* into message queue and needs to be processed.
|
||
|
|
*
|
||
|
|
* @retval true Wakeup generation has been started.
|
||
|
|
* @retval false No wakeup would be generated becouse it is disabled by the host.
|
||
|
|
*/
|
||
|
|
bool app_usbd_wakeup_req(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Get information whether there is an active connection.
|
||
|
|
*
|
||
|
|
* Function to check if the communication with the bus is possible.
|
||
|
|
*
|
||
|
|
* @retval true The bus is active.
|
||
|
|
* @retval false There is no connection or bus is suspended.
|
||
|
|
*/
|
||
|
|
bool app_usbd_active_check(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief USBD event processor.
|
||
|
|
*
|
||
|
|
* Function to be called on each event to be processed by the library.
|
||
|
|
*/
|
||
|
|
void app_usbd_event_execute(app_usbd_internal_evt_t const * const p_event);
|
||
|
|
|
||
|
|
|
||
|
|
#if (APP_USBD_CONFIG_EVENT_QUEUE_ENABLE) || defined(__SDK_DOXYGEN__)
|
||
|
|
/**
|
||
|
|
* @brief Function that process events from the queue.
|
||
|
|
*
|
||
|
|
* @note This function calls @ref app_usbd_event_execute internally.
|
||
|
|
*
|
||
|
|
* @retval true Event was processed.
|
||
|
|
* @retval false The event queue is empty.
|
||
|
|
*/
|
||
|
|
bool app_usbd_event_queue_process(void);
|
||
|
|
#endif
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief 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 @ref app_usbd_ep_handler_set.
|
||
|
|
*
|
||
|
|
* After successful attachment @ref APP_USBD_EVT_INST_APPEND would be passed to class instance.
|
||
|
|
*
|
||
|
|
* @note This function can only be called after USBD library is initialized but still disabled.
|
||
|
|
* Assertion would be generated otherwise.
|
||
|
|
*
|
||
|
|
* @param[in,out] p_cinst Instance to connect. Chain data would be written into writable instance data.
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS Instance successfully added.
|
||
|
|
* @retval NRF_ERROR_BUSY Endpoint(s) not available.
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_class_append(app_usbd_class_inst_t const * p_cinst);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief 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.
|
||
|
|
*
|
||
|
|
* @note This function can only be called after USBD library is initialized but still disabled.
|
||
|
|
* Assertion would be generated otherwise.
|
||
|
|
*
|
||
|
|
* @param p_cinst Instance pointer to remove.
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS Instance successfully removed.
|
||
|
|
* @retval NRF_ERROR_NOT_FOUND Instance not found in the instance chain.
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_class_remove(app_usbd_class_inst_t const * p_cinst);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Remove all class instances.
|
||
|
|
*
|
||
|
|
* This function basically calls @ref app_usbd_class_remove
|
||
|
|
* on instances chain as long as there is any element left.
|
||
|
|
*
|
||
|
|
* @note This function can only be called after USBD library is initialized but still disabled.
|
||
|
|
* Assertion would be generated otherwise.
|
||
|
|
*
|
||
|
|
* @sa app_usbd_class_remove
|
||
|
|
*
|
||
|
|
* @return Is should always return @ref NRF_SUCCESS.
|
||
|
|
* Any error value returned would mean there is an error inside the library.
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_class_remove_all(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Change endpoint handler.
|
||
|
|
*
|
||
|
|
* This function may be called for the endpoint only if the class instance is
|
||
|
|
* already properly attached by the @ref app_usbd_class_append function.
|
||
|
|
*
|
||
|
|
* The endpoint event handler function can be only overwritten by the class instance
|
||
|
|
* that was connected into the endpoint.
|
||
|
|
*
|
||
|
|
* @note This function can only be called after USBD library is initialized but still disabled.
|
||
|
|
* Assertion would be generated otherwise.
|
||
|
|
*
|
||
|
|
* @param[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.
|
||
|
|
* @param[in] ep Endpoint address to configure.
|
||
|
|
* @param[in] handler Event handler function to set.
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS New handler successfully set
|
||
|
|
* @retval NRF_ERROR_INVALID_PARAM p_cinst is not the same as currently set for 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);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief 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.
|
||
|
|
*
|
||
|
|
* @param p_cinst Instance that requires SOF event.
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS Instance linked into SOF processing list.
|
||
|
|
*
|
||
|
|
* @sa app_usbd_class_sof_unregister
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_class_sof_register(app_usbd_class_inst_t const * p_cinst);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Unregister class instance from SOF processing instances list.
|
||
|
|
*
|
||
|
|
* Every class that calls @ref app_usbd_class_sof_register have to call also unregistering function
|
||
|
|
* in reaction to @ref APP_USBD_EVT_INST_REMOVE event.
|
||
|
|
*
|
||
|
|
* @param p_cinst Instance to be unregistered from SOF event processing list.
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS Instance linked into SOF processing list.
|
||
|
|
* @retval NRF_ERROR_NOT_FOUND Instance not found in the SOF processing list.
|
||
|
|
*
|
||
|
|
* @sa app_usbd_class_sof_register
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_class_sof_unregister(app_usbd_class_inst_t const * p_cinst);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief 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.
|
||
|
|
*
|
||
|
|
* @param p_cinst Instance that requires SOF event.
|
||
|
|
* @param handler Handler to SOF event
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS Instance linked into SOF processing list.
|
||
|
|
*
|
||
|
|
* @sa app_usbd_class_sof_interrupt_unregister
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_class_sof_interrupt_register(app_usbd_class_inst_t const * p_cinst,
|
||
|
|
app_usbd_sof_interrupt_handler_t handler);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Unregister class instance from SOF processing in interrupt instances list.
|
||
|
|
*
|
||
|
|
* Every class that calls @ref app_usbd_class_sof_interrupt_register have to call
|
||
|
|
* also unregistering function in reaction to @ref APP_USBD_EVT_INST_REMOVE event.
|
||
|
|
*
|
||
|
|
* @param p_cinst Instance to be unregistered from SOF processing in interrupt list.
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS Instance linked into SOF processing in interrupt list.
|
||
|
|
* @retval NRF_ERROR_NOT_FOUND Instance not found in the SOF processing in interrupt list.
|
||
|
|
*
|
||
|
|
* @sa app_usbd_class_sof_interrupt_register
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_class_sof_interrupt_unregister(app_usbd_class_inst_t const * p_cinst);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Register class on remote wake-up feature.
|
||
|
|
*
|
||
|
|
* @param[in] p_inst Instance of the class.
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS Instance that requires remote wake-up registered.
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_class_rwu_register(app_usbd_class_inst_t const * const p_inst);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Unregister class from remote wake-up feature.
|
||
|
|
*
|
||
|
|
* @param[in] p_inst Instance of the class.
|
||
|
|
*
|
||
|
|
* @retval NRF_SUCCESS Instance that requires remote wake-up removed.
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_class_rwu_unregister(app_usbd_class_inst_t const * const p_inst);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Check if there is any class with remote wakeup.
|
||
|
|
*
|
||
|
|
* The function checks internal registered class with remote wakeup counter.
|
||
|
|
*
|
||
|
|
* @sa app_usbd_class_rwu_register, app_usbd_class_rwu_unregister
|
||
|
|
*
|
||
|
|
* @retval true The remote wakeup functionality is required by some class instance.
|
||
|
|
* @retval false There is no class instance that requires wakeup functionality.
|
||
|
|
*/
|
||
|
|
bool app_usbd_class_rwu_enabled_check(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Find a specified descriptor.
|
||
|
|
*
|
||
|
|
* @param[in] p_cinst Class instance.
|
||
|
|
* @param[in] desc_type Descriptor type @ref app_usbd_descriptor_t
|
||
|
|
* @param[in] desc_index Descriptor index.
|
||
|
|
* @param[out] p_desc Pointer to escriptor.
|
||
|
|
* @param[out] p_desc_len Length of descriptor.
|
||
|
|
*
|
||
|
|
* @return Standard error code @ref ret_code_t
|
||
|
|
* @retval NRF_SUCCESS Descriptor successfully found.
|
||
|
|
* @retval NRF_ERROR_NOT_FOUND Descriptor not found.
|
||
|
|
* */
|
||
|
|
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);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Standard set interface request handle.
|
||
|
|
*
|
||
|
|
* This function should be called when processing SET_INTERFACE request.
|
||
|
|
*
|
||
|
|
* @param[in] p_cinst Instance of a class.
|
||
|
|
* @param[in] iface Interface number.
|
||
|
|
*
|
||
|
|
* @return Standard error code.
|
||
|
|
*
|
||
|
|
* @note Selected interface to reset has to be part of given class.
|
||
|
|
* */
|
||
|
|
ret_code_t app_usbd_interface_ep_reset(app_usbd_class_inst_t const * const p_cinst,
|
||
|
|
uint8_t iface);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Enable selected endpoint.
|
||
|
|
*
|
||
|
|
* Selected endpoint is enabled and cleared.
|
||
|
|
*
|
||
|
|
* @param ep Endpoint number.
|
||
|
|
*/
|
||
|
|
void app_usbd_ep_enable(nrf_drv_usbd_ep_t ep);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Disable selected endpoint.
|
||
|
|
*
|
||
|
|
* @param ep Endpoint number.
|
||
|
|
*/
|
||
|
|
void app_usbd_ep_disable(nrf_drv_usbd_ep_t ep);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @name Iterate through classes lists
|
||
|
|
*
|
||
|
|
* Functions that helps to iterate through internally chained classes.
|
||
|
|
* @{
|
||
|
|
*/
|
||
|
|
/**
|
||
|
|
* @brief Get first class instance in the list.
|
||
|
|
*
|
||
|
|
* Get first instance from the list of active class instances.
|
||
|
|
* That instance may be used then in @ref app_usbd_class_next_get function.
|
||
|
|
*
|
||
|
|
* @return First instance in the list or NULL if there are no instances available.
|
||
|
|
*/
|
||
|
|
app_usbd_class_inst_t const * app_usbd_class_first_get(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Get next instance in the list.
|
||
|
|
*
|
||
|
|
* Get the next instance from the list of active instances.
|
||
|
|
* Used to iterate through all instances.
|
||
|
|
*
|
||
|
|
* @param[in] p_cinst The current instance from with next one is required.
|
||
|
|
*
|
||
|
|
* @return Next instance to the given one or NULL if there is no more instances in the list.
|
||
|
|
*/
|
||
|
|
static inline app_usbd_class_inst_t const * app_usbd_class_next_get(
|
||
|
|
app_usbd_class_inst_t const * const p_cinst)
|
||
|
|
{
|
||
|
|
ASSERT(NULL != p_cinst);
|
||
|
|
return app_usbd_class_data_access(p_cinst)->p_next;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Get first instance in SOF list.
|
||
|
|
*
|
||
|
|
* Start iteration through the list of instances that require SOF event processing.
|
||
|
|
*
|
||
|
|
* @return First instance in the list or NULL if the list is empty.
|
||
|
|
*
|
||
|
|
* @sa app_usbd_class_first_get
|
||
|
|
*/
|
||
|
|
app_usbd_class_inst_t const * app_usbd_class_sof_first_get(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief 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.
|
||
|
|
*
|
||
|
|
* @param p_cinst The current instance from with next one is required.
|
||
|
|
*
|
||
|
|
* @return Next instance to the given one or NULL if there is no more instances in the list.
|
||
|
|
*/
|
||
|
|
static inline app_usbd_class_inst_t const * app_usbd_class_sof_next_get(
|
||
|
|
app_usbd_class_inst_t const * const p_cinst)
|
||
|
|
{
|
||
|
|
ASSERT(NULL != p_cinst);
|
||
|
|
return app_usbd_class_data_access(p_cinst)->p_sof_next;
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Get first instance in SOF interrupt list.
|
||
|
|
*
|
||
|
|
* Start iteration through the list of instances that require SOF processing in interrupt.
|
||
|
|
*
|
||
|
|
* @return First instance in the list or NULL if the list is empty.
|
||
|
|
*
|
||
|
|
* @sa app_usbd_class_first_get
|
||
|
|
*/
|
||
|
|
app_usbd_class_inst_t const * app_usbd_class_sof_interrupt_first_get(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief 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.
|
||
|
|
*
|
||
|
|
* @param p_cinst The current instance from with next one is required.
|
||
|
|
*
|
||
|
|
* @return Next instance to the given one or NULL if there is no more instances in the list.
|
||
|
|
*/
|
||
|
|
static inline app_usbd_class_inst_t const * app_usbd_class_sof_interrupt_next_get(
|
||
|
|
app_usbd_class_inst_t const * const p_cinst)
|
||
|
|
{
|
||
|
|
ASSERT(NULL != p_cinst);
|
||
|
|
return app_usbd_class_data_access(p_cinst)->p_sof_next;
|
||
|
|
}
|
||
|
|
/** @} */
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief 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.
|
||
|
|
*
|
||
|
|
* @param[in] iface Interface number.
|
||
|
|
* @param[out] p_iface_idx Pointer to a variable that would hold interface index inside returned
|
||
|
|
* class instance.
|
||
|
|
*
|
||
|
|
* @return Pointer to the class structure that cointain given interface or NULL if not found.
|
||
|
|
*/
|
||
|
|
app_usbd_class_inst_t const * app_usbd_iface_find(uint8_t iface, uint8_t * p_iface_idx);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @name Communicate with interfaces, endpoints and instances inside usbd library
|
||
|
|
*
|
||
|
|
* @{
|
||
|
|
*/
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Call interface event handler.
|
||
|
|
*
|
||
|
|
* Call event handler for selected interface.
|
||
|
|
* @param[in,out] p_class_inst Class instance that holds selected interface.
|
||
|
|
* @param[in] iface_idx Index of the interface in class structure.
|
||
|
|
* @param[in] p_event Event structure to be processed.
|
||
|
|
*
|
||
|
|
* @return Operation status.
|
||
|
|
*/
|
||
|
|
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);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Call endpoint event handler.
|
||
|
|
*
|
||
|
|
* Call event handler for the selected endpoint.
|
||
|
|
* @param[in] ep Endpoint number.
|
||
|
|
* @param[in] p_event Event structure to send.
|
||
|
|
*
|
||
|
|
* @return Operation status.
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_ep_call(nrf_drv_usbd_ep_t ep, app_usbd_complex_evt_t const * const p_event);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Auxiliary function that process event by every instance in the list.
|
||
|
|
*
|
||
|
|
* This function ignores the result of called handler.
|
||
|
|
*
|
||
|
|
* @param p_event Event to pass to every instance.
|
||
|
|
*/
|
||
|
|
void app_usbd_all_call(app_usbd_complex_evt_t const * const p_event);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Call interface event handlers and stop when served.
|
||
|
|
*
|
||
|
|
* Call event handlers from instances as long as we get result different than @ref NRF_ERROR_NOT_SUPPORTED
|
||
|
|
* @param[in] p_event Event structure to send.
|
||
|
|
*
|
||
|
|
* @return Operation status or @ref NRF_ERROR_NOT_SUPPORTED if none of instances in the list can support given event.
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_all_until_served_call(app_usbd_complex_evt_t const * const p_event);
|
||
|
|
/** @} */
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Endpoint transfer.
|
||
|
|
*
|
||
|
|
* @param ep Endpoint number.
|
||
|
|
* @param p_transfer Description of the transfer to be performed.
|
||
|
|
* The direction of the transfer is determined by the
|
||
|
|
* endpoint number.
|
||
|
|
*
|
||
|
|
* @retval NRF_ERROR_INVALID_STATE The state of the USB device does not allow
|
||
|
|
* data transfer on the endpoint.
|
||
|
|
* @return Values returned by @ref nrf_drv_usbd_ep_transfer.
|
||
|
|
*
|
||
|
|
* @sa app_usbd_ep_handled_transfer
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_ep_transfer(
|
||
|
|
nrf_drv_usbd_ep_t ep,
|
||
|
|
nrf_drv_usbd_transfer_t const * const p_transfer);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Set up an endpoint handled transfer.
|
||
|
|
*
|
||
|
|
* Configures a transfer handled by the feedback function.
|
||
|
|
*
|
||
|
|
* @param ep Endpoint number.
|
||
|
|
* @param p_handler Function called when the next chunk of data is requested.
|
||
|
|
*
|
||
|
|
* @retval NRF_ERROR_INVALID_STATE The state of the USB device does not allow
|
||
|
|
* data transfer on the endpoint.
|
||
|
|
* @return Values returned by @ref nrf_drv_usbd_ep_handled_transfer.
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_ep_handled_transfer(
|
||
|
|
nrf_drv_usbd_ep_t ep,
|
||
|
|
nrf_drv_usbd_handler_desc_t const * const p_handler);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief 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.
|
||
|
|
*
|
||
|
|
* @param[in,out] p_inst Instance of the class.
|
||
|
|
* @param[in] iface_idx Index of the interface inside class structure.
|
||
|
|
* @param[in] alternate Alternate setting that should be selected.
|
||
|
|
*
|
||
|
|
* @return Standard error code.
|
||
|
|
*/
|
||
|
|
ret_code_t app_usbd_iface_select(
|
||
|
|
app_usbd_class_inst_t const * const p_inst,
|
||
|
|
uint8_t iface_idx,
|
||
|
|
uint8_t alternate);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief 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.
|
||
|
|
*
|
||
|
|
* @param[in,out] p_inst Instance of the class.
|
||
|
|
* @param[in] iface_idx Index of the interface inside class structure.
|
||
|
|
*/
|
||
|
|
void app_usbd_iface_deselect(
|
||
|
|
app_usbd_class_inst_t const * const p_inst,
|
||
|
|
uint8_t iface_idx);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Get selected interface.
|
||
|
|
*
|
||
|
|
* Function retieves currently selected interface.
|
||
|
|
* If the class contains @ref 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.
|
||
|
|
*
|
||
|
|
* @param[in] p_inst Instance of the class.
|
||
|
|
* @param[in] iface_idx Index of the interface inside class structure.
|
||
|
|
*
|
||
|
|
* @return Selected alternate interface setting.
|
||
|
|
*/
|
||
|
|
uint8_t app_usbd_iface_selection_get(
|
||
|
|
app_usbd_class_inst_t const * const p_inst,
|
||
|
|
uint8_t iface_idx);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Select alternate configuration 0 for all interfaces.
|
||
|
|
*
|
||
|
|
* Auxiliary function that clears settings for all interfaces leaving them enabled.
|
||
|
|
*/
|
||
|
|
void app_usbd_all_iface_select_0(void);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Deselect all interfaces.
|
||
|
|
*
|
||
|
|
* Auxiliary function to disable all interfaces.
|
||
|
|
*/
|
||
|
|
void app_usbd_all_iface_deselect(void);
|
||
|
|
|
||
|
|
/** @} */
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif
|
||
|
|
|
||
|
|
#endif /* APP_USBD_H__ */
|