| nRF5 SDK v12.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Macros | Typedefs | Functions
Functions for controlling nrf_log
Logger module

The nrf_log control interface. More...

## Macros
#define | NRF_LOG_INIT(timestamp_func) NRF_LOG_INTERNAL_INIT(timestamp_func)
| Macro for initializing the logs. More...
#define | NRF_LOG_PROCESS() NRF_LOG_INTERNAL_PROCESS()
| Macro for processing a single log entry from a queue of deferred logs. More...
#define | NRF_LOG_FLUSH() NRF_LOG_INTERNAL_FLUSH()
| Macro for processing all log entries from the buffer. It blocks until all buffered entries are processed by the backend. More...
#define | NRF_LOG_FINAL_FLUSH() NRF_LOG_INTERNAL_FINAL_FLUSH()
| Macro for flushing log data before reset. More...
#define | NRF_LOG_HANDLERS_SET(default_handler, bytes_handler) NRF_LOG_INTERNAL_HANDLERS_SET(default_handler, bytes_handler)
| Macro for changing functions that are used to handle log entries. More...

## Typedefs
typedef uint32_t(* | nrf_log_timestamp_func_t )(void)
| Timestamp function prototype. More...
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)
| Function prototype for handling a log entry. More...
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)
| Function prototype for handling a bytes-dumping log entry. More...

## Functions
ret_code_t | nrf_log_init (nrf_log_timestamp_func_t timestamp_func)
| Function for initializing the frontend and the default backend. More...
ret_code_t | nrf_log_blocking_backend_set (void)
| Function for reinitializing the backend in blocking mode.
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)
| Function for initializing the logger frontend. More...
void | nrf_log_handlers_set (nrf_log_std_handler_t std_handler, nrf_log_hexdump_handler_t hexdump_handler)
| Function for updating functions that handle log entries. More...
bool | nrf_log_frontend_dequeue (void)
| Function for handling a single log entry. More...

## Detailed Description

The nrf_log control interface.

## Macro Definition Documentation

#define NRF_LOG_FINAL_FLUSH | ( |  | ) | NRF_LOG_INTERNAL_FINAL_FLUSH()

Macro for flushing log data before reset.

Note
  If logs are not deferred, this call has no use and is empty.
  If RTT is used, then a breakpoint is hit once flushed.

#define NRF_LOG_FLUSH | ( |  | ) | NRF_LOG_INTERNAL_FLUSH()

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_HANDLERS_SET | ( |  | default_handler,
|  |  | bytes_handler
| ) |  | NRF_LOG_INTERNAL_HANDLERS_SET(default_handler, bytes_handler)

Macro for changing functions that are used to handle log entries.

Parameters

  default_handler | Function for handling log entries.
  bytes_handler | Function for handling hexdump entries.

#define NRF_LOG_INIT | ( |  | timestamp_func | ) | NRF_LOG_INTERNAL_INIT(timestamp_func)

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.

Parameters

  timestamp_func | Function that returns the timestamp.

Returns
  NRF_SUCCESS after successful initialization, otherwise an error code.

#define NRF_LOG_PROCESS | ( |  | ) | NRF_LOG_INTERNAL_PROCESS()

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'.

Return values

  true | There are more logs to process in the buffer.
  false | No more logs in the buffer.

## Typedef Documentation

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)

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.

Parameters

  severity_level | Severity level of the entry.
  p_timestamp | Pointer to a timestamp value. No timestamp if NULL.
  p_str | Prefix string for the bytes dump.
  offset | Indication of how many bytes have already been processed.
  p_buf0 | Pointer to the first part of data.
  buf0_length | Number of bytes in the first part.
  p_buf1 | Pointer to the second part of data. Optional.
  buf1_length | Number of bytes in the second part.

Returns
  Number of bytes processed. If all bytes are processed, it should be a sum of buf0_length and buf1_length

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)

Function prototype for handling a log entry.

The backend must implement such prototype.

Parameters

  severity_level | Severity level of the entry.
  p_timestamp | Pointer to the timestamp value. No timestamp if NULL.
  p_str | Pointer to a formatted string.
  p_args | Pointer to an array of arguments for a formatted string.
  nargs | Number of arguments in p_args.

Return values

  true | If entry is successfully processed.
  false | If entry is not processed.

typedef uint32_t(* nrf_log_timestamp_func_t)(void)

Timestamp function prototype.

Returns
  Timestamp value.

## Function Documentation

bool nrf_log_frontend_dequeue | ( | void |  | ) |

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.

Return values

  true | If there are more entries to process.
  false | If there are no more entries to process.

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
| ) |  |

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 NRF_LOG_INIT macro is not used to initialize the logger.

Parameters

  std_handler | Function for handling standard log entries.
  hexdump_handler | Function for handling hexdump log entries.
  timestamp_func | Function for getting a timestamp. It cannot be NULL unless timestamping is disabled.

void nrf_log_handlers_set | ( | nrf_log_std_handler_t | std_handler,
|  | nrf_log_hexdump_handler_t | hexdump_handler
| ) |  |

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.

Parameters

  std_handler | Function for handling standard log entries.
  hexdump_handler | Function for handling hexdump log entries.

ret_code_t nrf_log_init | ( | nrf_log_timestamp_func_t | timestamp_func | ) |

Function for initializing the frontend and the default backend.

NRF_LOG_INIT calls this function to initialize the frontend and the backend. If custom backend is used, then NRF_LOG_INIT should not be called. Instead, frontend and user backend should be verbosely initialized.

Parameters

  timestamp_func | Function for getting a 32-bit timestamp.

Returns
  Error status.