/**
* Copyright (c) 2016 - 2017, 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 NRF_LOG_CTRL_H
#define NRF_LOG_CTRL_H
/**@file
* @addtogroup nrf_log Logger module
* @ingroup app_common
*
* @defgroup nrf_log_ctrl Functions for controlling nrf_log
* @{
* @ingroup nrf_log
* @brief The nrf_log control interface.
*/
#include "sdk_config.h"
#include "sdk_errors.h"
#include <stdint.h>
#include <stdbool.h>
#include "nrf_log_ctrl_internal.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Timestamp function prototype.
*
* @return Timestamp value.
*/
typedef uint32_t (*nrf_log_timestamp_func_t)(void);
/**@brief Macro for initializing the logs.
*
* @note If timestamps are disabled in the configuration, then the provided pointer
* can be NULL. Otherwise, it is expected that timestamp_getter is not NULL.
*
* @param timestamp_func Function that returns the timestamp.
*
* @return NRF_SUCCESS after successful initialization, otherwise an error code.
*/
#define NRF_LOG_INIT(timestamp_func) NRF_LOG_INTERNAL_INIT(timestamp_func)
/**@brief Macro for processing a single log entry from a queue of deferred logs.
*
* You can call this macro from the main context or from the error handler to process
* log entries one by one.
*
* @note If logs are not deferred, this call has no use and is defined as 'false'.
*
* @retval true There are more logs to process in the buffer.
* @retval false No more logs in the buffer.
*/
#define NRF_LOG_PROCESS() NRF_LOG_INTERNAL_PROCESS()
/** @brief Macro for processing all log entries from the buffer.
* It blocks until all buffered entries are processed by the backend.
*
* @note If logs are not deferred, this call has no use and is empty.
*/
#define NRF_LOG_FLUSH() NRF_LOG_INTERNAL_FLUSH()
/** @brief Macro for flushing log data before reset.
*
* @note If logs are not deferred, this call has no use and is empty.
*
* @note If RTT is used, then a breakpoint is hit once flushed.
*/
#define NRF_LOG_FINAL_FLUSH() NRF_LOG_INTERNAL_FINAL_FLUSH()
/** @brief Macro for changing functions that are used to handle log entries.
*
* @param default_handler Function for handling log entries.
* @param bytes_handler Function for handling hexdump entries.
*
*/
#define NRF_LOG_HANDLERS_SET(default_handler, bytes_handler) \
NRF_LOG_INTERNAL_HANDLERS_SET(default_handler, bytes_handler)
/**
* @brief Function prototype for handling a log entry.
*
* The backend must implement such prototype.
*
* @param severity_level Severity level of the entry.
* @param p_timestamp Pointer to the timestamp value. No timestamp if NULL.
* @param p_str Pointer to a formatted string.
* @param p_args Pointer to an array of arguments for a formatted string.
* @param nargs Number of arguments in p_args.
*
* @retval true If entry is successfully processed.
* @retval false If entry is not processed.
*/
typedef bool (*nrf_log_std_handler_t)(
uint8_t severity_level,
const uint32_t * const p_timestamp,
const char * const p_str,
uint32_t * p_args,
uint32_t nargs);
/**
* @brief Function prototype for handling a bytes-dumping log entry.
*
* The backend must implement such prototype. Two buffers are needed because data
* is stored internally in a circular buffer so it can be fragmented into up to
* two pieces.
*
* @param severity_level Severity level of the entry.
* @param p_timestamp Pointer to a timestamp value. No timestamp if NULL.
* @param p_str Prefix string for the bytes dump.
* @param offset Indication of how many bytes have already been processed.
* @param p_buf0 Pointer to the first part of data.
* @param buf0_length Number of bytes in the first part.
* @param p_buf1 Pointer to the second part of data. Optional.
* @param buf1_length Number of bytes in the second part.
*
* @return Number of bytes processed. If all bytes are processed, it should be a sum of
* buf0_length and buf1_length
*/
typedef uint32_t (*nrf_log_hexdump_handler_t)(
uint8_t severity_level,
const uint32_t * const p_timestamp,
const char * const p_str,
uint32_t offset,
const uint8_t * const p_buf0,
uint32_t buf0_length,
const uint8_t * const p_buf1,
uint32_t buf1_length);
/**
* @brief Function for initializing the frontend and the default backend.
*
* @ref NRF_LOG_INIT calls this function to initialize the frontend and the backend.
* If custom backend is used, then @ref NRF_LOG_INIT should not be called.
* Instead, frontend and user backend should be verbosely initialized.
*
* @param timestamp_func Function for getting a 32-bit timestamp.
*
* @return Error status.
*
*/
ret_code_t nrf_log_init(nrf_log_timestamp_func_t timestamp_func);
/**
* @brief Function for reinitializing the backend in blocking mode.
*/
ret_code_t nrf_log_blocking_backend_set(void);
/**
* @brief Function for initializing the logger frontend.
*
* The frontend is initialized with functions for handling log entries. Those
* functions are provided by the backend.
*
* @note This function needs to be called directly only if the @ref NRF_LOG_INIT macro
* is not used to initialize the logger.
*
* @param std_handler Function for handling standard log entries.
* @param hexdump_handler Function for handling hexdump log entries.
* @param timestamp_func Function for getting a timestamp. It cannot be NULL
* unless timestamping is disabled.
*/
void nrf_log_frontend_init(nrf_log_std_handler_t std_handler,
nrf_log_hexdump_handler_t hexdump_handler,
nrf_log_timestamp_func_t timestamp_func);
/**
* @brief Function for updating functions that handle log entries.
*
* @note Use this feature to change the log handling behavior in certain
* situations, like in a fault handler.
*
* @param std_handler Function for handling standard log entries.
* @param hexdump_handler Function for handling hexdump log entries.
*/
void nrf_log_handlers_set(nrf_log_std_handler_t std_handler,
nrf_log_hexdump_handler_t hexdump_handler);
/**
* @brief Function for handling a single log entry.
*
* Use this function only if the logs are buffered. It takes a single entry from the
* buffer and attempts to process it.
*
* @retval true If there are more entries to process.
* @retval false If there are no more entries to process.
*/
bool nrf_log_frontend_dequeue(void);
#ifdef __cplusplus
}
#endif
#endif // NRF_LOG_CTRL_H
/**
*@}
**/