Flash-backed circular logging system. More...

#include "esp_partition.h"
#include "esp_timer.h"
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include <stdint.h>

Include dependency graph for blackbox_logger.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	blackbox_logger_entry_view_t
	Blackbox logger entry view structure. More...

struct	blackbox_logger_parameters_t
	BlackBox logger configuration parameters structure. More...

struct	blackbox_logger_config_t
	BlackBox logger configuration structure. More...

struct	blackbox_logger_t
	BlackBox logger type structure. More...

Typedefs
typedef bool(*	blackbox_logger_iter_cb_t) (void , const blackbox_logger_entry_view_t )

Enumerations
enum	blackbox_logger_err_t { BLACKBOX_LOGGER_OK , BLACKBOX_LOGGER_ERR_FAIL , BLACKBOX_LOGGER_ERR_INVALID_ARG , BLACKBOX_LOGGER_ERR_NO_MEM , BLACKBOX_LOGGER_ERR_TIMEOUT , BLACKBOX_LOGGER_ERR_INVALID_CRC , BLACKBOX_LOGGER_ERR_INVALID_ENTRY , BLACKBOX_LOGGER_ERR_ERASE_FAIL , BLACKBOX_LOGGER_ERR_WRITE_FAIL , BLACKBOX_LOGGER_ERR_PROCESS_FAIL }
	BlackBox Logger status codes enum. More...

Functions
blackbox_logger_err_t	blackbox_logger_init (blackbox_logger_t logger_ptr, blackbox_logger_config_t config_ptr)
	Initialize BlackBox Logger.

blackbox_logger_err_t	blackbox_logger_write (blackbox_logger_t logger_ptr, const blackbox_logger_entry_view_t entry_ptr)
	Write an entry to flash.

blackbox_logger_err_t	blackbox_logger_read (const blackbox_logger_t logger_ptr, uint32_t read_offset, blackbox_logger_entry_view_t entry_ptr, size_t entry_buf_max_capacity)
	Read an entry from flash.

blackbox_logger_err_t	blackbox_logger_flush (blackbox_logger_t *logger_ptr)
	Flush buffered data to flash.

blackbox_logger_err_t	blackbox_logger_next_replay (blackbox_logger_t logger_ptr, blackbox_logger_iter_cb_t is_entry_processed_cb_func, void cb_arg_void_ptr, blackbox_logger_entry_view_t *entry_ptr, const size_t entry_buf_max_capacity)
	Replay next available log entry.

blackbox_logger_err_t	blackbox_logger_iterate_replay (blackbox_logger_t logger_ptr, blackbox_logger_iter_cb_t is_entry_processed_cb_func, void cb_arg_void_ptr, blackbox_logger_entry_view_t *entry_ptr, const size_t entry_buf_max_capacity)
	Iterate over available log entries.

void	blackbox_logger_get_parameters_defaults (blackbox_logger_parameters_t *parameter_ptr)
	Get Logger parameters defaults.

bool	blackbox_logger_has_replay_data (const blackbox_logger_t *logger_ptr)
	Is log data available for replay.

void	blackbox_logger_deinit (blackbox_logger_t *logger_ptr)
	De-init BlackBox Logger.

Detailed Description

Flash-backed circular logging system.

Author: Abanoub Salah

Features
- Power-loss resilient logging
- CRC-protected entries
- Circular buffer with overwrite protection
- Replay support for deferred transmission
- Designed for high-reliability embedded systems

Typedef Documentation

◆ blackbox_logger_iter_cb_t

typedef bool(* blackbox_logger_iter_cb_t) (void *, const blackbox_logger_entry_view_t *)

Iterator callback for replay definition

Enumeration Type Documentation

◆ blackbox_logger_err_t

enum blackbox_logger_err_t

BlackBox Logger status codes enum.

Enumerator
BLACKBOX_LOGGER_OK	Successful operation
BLACKBOX_LOGGER_ERR_FAIL	Failed operation
BLACKBOX_LOGGER_ERR_INVALID_ARG	Invalid arguments provided
BLACKBOX_LOGGER_ERR_NO_MEM	Insufficient memory available
BLACKBOX_LOGGER_ERR_TIMEOUT	The operation timed out
BLACKBOX_LOGGER_ERR_INVALID_CRC	Invalid CRC
BLACKBOX_LOGGER_ERR_INVALID_ENTRY	Invalid Logger entry
BLACKBOX_LOGGER_ERR_ERASE_FAIL	Failed to erase flash
BLACKBOX_LOGGER_ERR_WRITE_FAIL	Failed to write to flash
BLACKBOX_LOGGER_ERR_PROCESS_FAIL	Failed to process replay entry

Function Documentation

◆ blackbox_logger_deinit()

void blackbox_logger_deinit ( blackbox_logger_t * logger_ptr )

De-init BlackBox Logger.

De-init BlackBox Logger by flushing then stopping and deleting the timer and free-up used resources

Parameters

logger_ptr Pointer to BlackBox Logger instance

Here is the call graph for this function:

Here is the caller graph for this function:

◆ blackbox_logger_flush()

blackbox_logger_err_t blackbox_logger_flush ( blackbox_logger_t * logger_ptr )

Flush buffered data to flash.

Flush buffered data to flash taking into account wrap-around at flash-end
Calls notify callback if set and replay available
Log entry format is as follows
- [HEADER][PAYLOAD][TAIL][ALIGNMENT]...[HEADER][PAYLOAD][TAIL][ALIGNMENT]
Where:
- [HEADER]: Is a prefix to the payload with
  - Header magic number
  - Monotonically increasing ID
  - Payload length
- [PAYLOAD]: Entry data
- [TAIL]: Is a postfix to the payload with
  - CRC-16-Modbus for [HEADER][PAYLOAD]
  - Tail magic number
- [ALIGNMENT]: Stuffing to ensure next entry is aligned with system imposed alignment

Parameters

logger_ptr Pointer to BlackBox Logger instance

Returns: blackbox_logger_err_t Flush result

Return values

BLACKBOX_LOGGER_OK	Flush success
BLACKBOX_LOGGER_ERR_FAIL	Failed to write/erase partition
BLACKBOX_LOGGER_ERR_INVALID_ARG	Provided invalid argument(s)
BLACKBOX_LOGGER_ERR_NO_MEM	Flash is full
BLACKBOX_LOGGER_ERR_TIMEOUT	Timed out waiting for resource

Note

Writes won't extend to next sector to prevent entry fragmentation that means every sector beginning may have a start of an entry and will fail if entry is bigger than sector length

Function does not write buffer as a whole chunk it tries to fill available sector space first if possible to save on space

- Replay/Write offsets interaction behavior is configurable in kconfig

Keep old entries: Returns with 'no memory' error code
Replace old entries: Advance replay offset to the beginning of next write sector jumping-over any replay leftover in sector since they will get erased with the whole sector for coming fresh writes

Here is the call graph for this function:

Here is the caller graph for this function:

◆ blackbox_logger_get_parameters_defaults()

void blackbox_logger_get_parameters_defaults ( blackbox_logger_parameters_t * parameter_ptr )

Get Logger parameters defaults.

Parameters

parameter_ptr Pointer to parameters structure

Here is the caller graph for this function:

◆ blackbox_logger_has_replay_data()

bool blackbox_logger_has_replay_data ( const blackbox_logger_t * logger_ptr )

Is log data available for replay.

Parameters

logger_ptr Pointer to BlackBox Logger instance

Returns: true if data available, false otherwise

Here is the caller graph for this function:

◆ blackbox_logger_init()

blackbox_logger_err_t blackbox_logger_init	(	blackbox_logger_t *	logger_ptr,
		blackbox_logger_config_t *	config_ptr
	)

Initialize BlackBox Logger.

Initialize logger with provided configurations using parameters as hints for recover also setup a one-shot timer with a preset-time for flushing buffered data to flash

Parameters

logger_ptr	Pointer to BlackBox Logger instance
config_ptr	Pointer to BlackBox Logger configuration instance

Returns: blackbox_logger_err_t Initialize result

Return values

BLACKBOX_LOGGER_OK	Initialize success
BLACKBOX_FAIL	Initialize Fail
BLACKBOX_LOGGER_ERR_INVALID_ARG	Provided invalid argument(s)
BLACKBOX_LOGGER_ERR_NO_MEM	No available memory for resource allocation

Here is the call graph for this function:

Here is the caller graph for this function:

◆ blackbox_logger_iterate_replay()

blackbox_logger_err_t blackbox_logger_iterate_replay	(	blackbox_logger_t *	logger_ptr,
		blackbox_logger_iter_cb_t	is_entry_processed_cb_func,
		void *	cb_arg_void_ptr,
		blackbox_logger_entry_view_t *	entry_ptr,
		const size_t	entry_buf_max_capacity
	)

Iterate over available log entries.

Iterate over available log entries calling a callback function on success stopping-on empty log or when callback returns false

Parameters

logger_ptr	Pointer to BlackBox Logger instance
is_entry_processed_cb_func	Callback for when entry is available
cb_arg_void_ptr	Void pointer to callback argument
entry_ptr	Pointer to entry to read to
entry_buf_max_capacity	Provided buffer maximum capacity

Returns: blackbox_logger_err_t Replay result

Return values

BLACKBOX_LOGGER_OK	Replay success
BLACKBOX_LOGGER_ERR_FAIL	Failed to read from partition
BLACKBOX_LOGGER_ERR_INVALID_ARG	Provided invalid argument(s)
BLACKBOX_LOGGER_ERR_NO_MEM	No available memory for entry data
BLACKBOX_LOGGER_ERR_TIMEOUT	Timed out waiting for resource
BLACKBOX_LOGGER_ERR_INVALID_CRC	Invalid CRC for the entry
BLACKBOX_LOGGER_ERR_INVALID_ENTRY	Invalid entry found
BLACKBOX_LOGGER_ERR_PROCESS_FAIL	Callback refused/failed to process entry

Note: See blackbox_logger_next_replay notes since this function loop call it

Here is the call graph for this function:

◆ blackbox_logger_next_replay()

blackbox_logger_err_t blackbox_logger_next_replay	(	blackbox_logger_t *	logger_ptr,
		blackbox_logger_iter_cb_t	is_entry_processed_cb_func,
		void *	cb_arg_void_ptr,
		blackbox_logger_entry_view_t *	entry_ptr,
		const size_t	entry_buf_max_capacity
	)

Replay next available log entry.

calling a callback function on next available log entry then advance replay offset on callback returns true otherwise returns with error code

Parameters

logger_ptr	Pointer to BlackBox Logger instance
is_entry_processed_cb_func	Callback for when entry is available
cb_arg_void_ptr	Void pointer to callback argument
entry_ptr	Pointer to entry to read to
entry_buf_max_capacity	Provided buffer maximum capacity

Returns: blackbox_logger_err_t Replay result

Return values

BLACKBOX_LOGGER_OK	Replay success
BLACKBOX_LOGGER_ERR_FAIL	Failed to read from partition
BLACKBOX_LOGGER_ERR_INVALID_ARG	Provided invalid argument(s)
BLACKBOX_LOGGER_ERR_NO_MEM	No available memory for entry data
BLACKBOX_LOGGER_ERR_TIMEOUT	Timed out waiting for resource
BLACKBOX_LOGGER_ERR_INVALID_CRC	Invalid CRC for the entry
BLACKBOX_LOGGER_ERR_INVALID_ENTRY	Invalid entry found
BLACKBOX_LOGGER_ERR_PROCESS_FAIL	Callback refused/failed to process entry

Note

Function assumes every entry header starts at an aligned memory address

replay_offset gets incremented if callback function return true which means entry was processed

- On-Corrupt entry recovery strategy

If entry validation fails, assume flash corruption or power-loss mid-write
Synchronize replay_offset to write_offset to prevent undefined behavior
This guarantees forward progress at the cost of losing corrupted entries

Here is the call graph for this function:

Here is the caller graph for this function:

◆ blackbox_logger_read()

blackbox_logger_err_t blackbox_logger_read	(	const blackbox_logger_t *	logger_ptr,
		uint32_t	read_offset,
		blackbox_logger_entry_view_t *	entry_ptr,
		size_t	entry_buf_max_capacity
	)

Read an entry from flash.

Read to a buffer with a capacity provided by caller from a given flash offset

Parameters

logger_ptr	Pointer to BlackBox Logger instance
read_offset	Offset to read from
entry_ptr	Pointer to entry to be logged
entry_buf_max_capacity	Provided buffer maximum capacity

Returns: blackbox_logger_err_t read result

Return values

BLACKBOX_LOGGER_OK	Read success
BLACKBOX_LOGGER_ERR_FAIL	Failed to read from partition
BLACKBOX_LOGGER_ERR_INVALID_ARG	Provided invalid argument(s)
BLACKBOX_LOGGER_ERR_NO_MEM	No available memory for entry data
BLACKBOX_LOGGER_ERR_TIMEOUT	Timed out waiting for resource
BLACKBOX_LOGGER_ERR_INVALID_CRC	Invalid CRC for the entry
BLACKBOX_LOGGER_ERR_INVALID_ENTRY	Invalid entry found

Here is the call graph for this function:

Here is the caller graph for this function:

◆ blackbox_logger_write()

blackbox_logger_err_t blackbox_logger_write	(	blackbox_logger_t *	logger_ptr,
		const blackbox_logger_entry_view_t *	entry_ptr
	)

Write an entry to flash.

Write to buffer first with a pre-defined maximum length if exceeded, it gets flushed. Entries are wrapped between header and tail with crc16 to ensures data integrity after power loss Look at blackbox_logger_flush for more details

Parameters

logger_ptr	Pointer to BlackBox Logger instance
entry_ptr	Pointer to entry to be logged

Returns: blackbox_logger_err_t Write result

Return values

BLACKBOX_LOGGER_OK	Write success
BLACKBOX_LOGGER_ERR_FAIL	Failed to flush writing buffer
BLACKBOX_LOGGER_ERR_INVALID_ARG	Provided invalid argument(s)
BLACKBOX_LOGGER_ERR_NO_MEM	No available memory for resource allocation
BLACKBOX_LOGGER_ERR_TIMEOUT	Timed out waiting for resource

Note: Maximum entry length is set by 'batch size' in kconfig and must be less than or equal to 'sector size' and sized must be aligned to system imposed alignments

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ blackbox_logger_iter_cb_t

Enumeration Type Documentation

◆ blackbox_logger_err_t

Function Documentation

◆ blackbox_logger_deinit()

◆ blackbox_logger_flush()

◆ blackbox_logger_get_parameters_defaults()

◆ blackbox_logger_has_replay_data()

◆ blackbox_logger_init()

◆ blackbox_logger_iterate_replay()

◆ blackbox_logger_next_replay()

◆ blackbox_logger_read()

◆ blackbox_logger_write()