owner-nrf52sdk/nRF5_SDK_17.0.2/components/libraries/svc/nrf_svci_async_function.h

/**
 * Copyright (c) 2017 - 2020, 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.
 *
 */
/** @file
 *
 * @defgroup sdk_nrf_svci_async_function Asynchronous Supervisor function interface
 * @{
 * @ingroup app_common
 *
 * @brief Macros to create Asynchronous Supervisor interface functions.
 */

#ifndef NRF_SVC_ASYNC_FUNCTION_H__
#define NRF_SVC_ASYNC_FUNCTION_H__

#include "nrf_svci.h"
#include "nrf_svci_async_handler.h"

#ifdef __cplusplus
extern "C" {
#endif

/**@brief Macro for creating type definition for SVCI interface init function.
 *
 * @warning     Do not call this macro directly! Use @ref NRF_SVCI_ASYNC_FUNC_DECLARE instead.
 *
 * @param[in]   name        Name of async request function. Will be appended with _async_fn_t.
 * @param[in]   param_type  Parameter type.
 * @param[in]   state_type  State type.
 *
 * @retval Type definition a named SVCI async init function.
 */
#define NRF_SVCI_ACYNC_FUNC_TYPEDEF(name, param_type, state_type)                       \
typedef uint32_t (* name ## _async_fn_t)(param_type * p_param, state_type * p_state)


/**@brief Macro for creating type definition for SVCI interface event function.
 *
 * @warning     Do not call this macro directly! Use @ref NRF_SVCI_ASYNC_FUNC_DECLARE instead.
 *
 * @details Calling this function with sys-events will report @ref NRF_ERROR_BUSY until
 *          the asynchronous calls is finished, at which time it will report either
 *          NRF_SUCCESS or any another error-message.
 *
 * @param[in]   name        Name of the event function. Will be appended with _event_fn_t
 * @param[in]   state_type  Type parameter for the state.
 *
 * @retval Type definition for a named SVCI async event function.
 */
#define NRF_SVCI_ASYNC_EVENT_FUNC_TYPEDEF(name, state_type)                             \
typedef uint32_t (* name ## _event_fn_t)(uint32_t sys_evt, state_type * p_state)


/**@brief Macro for creating a declaration of a named async function for the SVCI interface.
 *
 * @details     The async interface provides a method to call into a external application
 *              through the SVCI interface without relying on allocated or reserved memory inside the
 *              external application.
 *
 *              This macro declares variables and function types in use by the async SVCI interface.
 *
 * @note        This is intended to be invoked in a header file shared by both the
 *              caller and the recipient (handler).
 *
 * @param[in]   svci_num    SVC indirect number.
 * @param[in]   name        Name of the async function.
 * @param[in]   param_type  Type of the param used for the async interface.
 * @param[in]   state_type  Type of the state used for the async interface.
 *
 * @retval  A type definition of NAME_svc_async_t to be used for async access
 *          through the SVCI interface.
 */
#define NRF_SVCI_ASYNC_FUNC_DECLARE(svci_num,                                           \
                                    name,                                               \
                                    param_type,                                         \
                                    state_type)                                         \
/*lint --e{19} */                                                                       \
NRF_SVCI_ACYNC_FUNC_TYPEDEF(name, param_type, state_type);                              \
NRF_SVCI_ASYNC_EVENT_FUNC_TYPEDEF(name, state_type);                                    \
                                                                                        \
typedef struct                                                                          \
{                                                                                       \
    name ## _async_fn_t     async_func;                                                 \
    name ## _event_fn_t     sys_evt_handler;                                            \
    state_type              state;                                                      \
} name ## _svci_async_t;



//lint -save --e{10, 19, 40, 102} -esym(526, *_init) -esym(628, *_init)

/**@brief Macro for defining a named SVCI async interface.
 *
 * @details     The async interface provides a method to call into an external application
 *              through the SVCI interface without relying on allocated or reserved memory inside the
 *              external application.
 *
 *              Running this macro creates a defintion of the structure that holds the
 *              information about the async function, the event handler, and the state.
 *
 *              Running this macro also defines convenience functions to the SVCI interface.
 *
 *              The available functions are:
 *              -NAME_init            -    Function to call to set up the async SVCI interface.
 *              -NAME                 -    Function to call the async SVCI interface.
 *              -NAME_on_sys_event    -    Function to report sys events to the async
 *                                         SVCI interface.
 *              -NAME_is_initialized  -    Function to check if the async SVCI interface is
 *                                         initialized and ready to use.
 *
 * @note        Invoking this macro is only possible in a source file as the macro creates
 *              a static variable for the async interface as well as static functions to call
 *              into the async interface.
 *
 * @param[in]   svci_num    SVC indirect number.
 * @param[in]   name        Name of the async function.
 * @param[in]   param_type  Type of the param used for the async interface.
 *
 * @retval Instance of the async SVCI interface and convenience functions for using it.
 */
#define NRF_SVCI_ASYNC_FUNC_DEFINE(svci_num, name, param_type)                                  \
                                                                                                \
SVCI(svci_num, uint32_t, name ## _svci_async_init, name ## _svci_async_t *, p_async);           \
static name ## _svci_async_t name ## _svci_async_def = {0};                                     \
                                                                                                \
static __INLINE uint32_t name ## _init (void)                                                   \
{                                                                                               \
    return name ## _svci_async_init(&name ## _svci_async_def);                                  \
}                                                                                               \
                                                                                                \
static __INLINE uint32_t name(param_type * p_param)                                             \
{                                                                                               \
    return name ## _svci_async_def.async_func(p_param, &name ## _svci_async_def.state);         \
}                                                                                               \
                                                                                                \
static __INLINE uint32_t name ## _on_sys_evt(uint32_t sys_evt)                                  \
{                                                                                               \
    return name ## _svci_async_def.sys_evt_handler(sys_evt, &name ## _svci_async_def.state);    \
}                                                                                               \
                                                                                                \
static __INLINE uint32_t name ## _is_initialized(void)                                          \
{                                                                                               \
    return (name ## _svci_async_def.async_func != NULL  &&                                      \
        name ## _svci_async_def.sys_evt_handler != NULL );                                      \
}

//lint -restore

#ifdef __cplusplus
}
#endif

#endif // NRF_SVC_ASYNC_FUNCTION_H__

/** @} */