1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
|
/**
* 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
/**
*@}
**/
|
