File: i3_log.h

Contains printf style logging functions as used by the Cygnus Reach firmware stack. The log module is designed to be easily retargeted to the console IO of the target. It is designed to be easily removed for very small targets. The “mask” facility allows users to turn on and off logging on a per function basis.

Copyright

(c) Copyright 2023 i3 Product Development. All Rights Reserved. The Cygngus Reach firmware stack is shared under an MIT license.

Defines

LOG_MASK_ALWAYS

The lowest nibble is reserved to system things.

The logging system used by Reach relies on a “mask” to control the amount of logging. The “mask” concept here is chosen over the “level” concept so that masks can be assigned to specific features. Turning on all of the masks is likely to be too much information. You can turn on the logging from only the modules that you want to debug. Reach uses a few bits. You can assign your own bits. The lowest nibble is reserved to system things. Higher bits can be defined and used by the application. Cannot be supressed

LOG_MASK_ERROR

Prints red, cannot be supressed.

LOG_MASK_WARN

Prints yellow, cannot be supressed.

LOG_MASK_BARE

trailing

is omitted

LOG_MASK_REMOTE

Set this to indicate that a message should be shared remotely.

LOG_MASK_WEAK

These used by Reach features. Enable them to debug and understand.

print in weak functions

LOG_MASK_WIRE

show what is on the wire

LOG_MASK_REACH

show reach protocol exchanges

LOG_MASK_PARAMS

show parameter handling

LOG_MASK_FILES

show file handling

LOG_MASK_BLE

show BLE handling

LOG_MASK_DEBUG

show other reach features

LOG_MASK_AHSOKA

show ahsoka coding

I3_LOG(m, f, ...)

A macro allowing logging to be disabled by NO_REACH_LOGGING.

Logging can be completely excluded from the build by defining NO_REACH_LOGGING in reach-server.h.

LOG_REACH(format, ...)

A macro allowing logging to be disabled by NO_REACH_LOGGING.

LOG_ERROR(format, ...)

A macro allowing logging to be disabled by NO_REACH_LOGGING.

LOG_DUMP_WIRE(banner, buf, len)

A macro allowing logging to be disabled by NO_REACH_LOGGING.

LOG_DUMP_MASK(mask, banner, buf, len)

A macro allowing logging to be disabled by NO_REACH_LOGGING.

Functions

void i3_log_set_mask(uint32_t mask)

i3_log_set_mask

Sets the mask which determines whether or not a log statement generates output. See defines starting with LOG_MASK_.

uint32_t i3_log_get_mask(void)

i3_log_set_mask

Gets the mask which determines whether or not a log statement generates output. See defines starting with LOG_MASK_.

int i3_log_set_remote_cli_enable(bool enable)

i3_log_set_remote_cli_enable

Parameters:

enable – : Enabling the remote CLI can generate significant BLE traffic. This can slow down speed related things like file transfer. Hence this API allows the remote command line to be easily supressed. The initial state can be set in reach-server.h

Returns:

cr_ErrorCodes_NO_ERROR on success.

bool i3_log_get_remote_cli_enable()

i3_log_get_remote_cli_enable

Returns:

true if enabled.

void i3_log(const uint32_t mask, const char *fmt, ...)

i3_log

A printf style logging function conditioned on a mask. The mask is and’ed with the control set by i3_log_set_mask()

. The string is printed if the result is non-zero. See LOG_MASK_. ANSI color codes are inserted for errors (red), warnings (yellow) and Reach logging (cyan). The color reset code and a \r

are appended to all strings except for LOG_MASK_BARE. When the remote CLI is enabled the string is copied to the remote buffer and sent via pvtCr_cli_respond().

Parameters:

  • mask – See LOG_MASK_.

  • fmt – : standard printf format.

void i3_log_dump_buffer(const uint32_t mask, const char *banner, const uint8_t *ptr, const size_t len)

i3_log_dump_buffer

Logs a hex dump of a buffer. Used to view the contents of coded buffers sent and received. The buffer is dumped locally, and not remotely. The width of the dump is set by the DUMP_WIDTH defined just above this function.

Parameters:

  • mask – Enable or disable using the log module’s mask feature..

  • banner – A header to be displayed describing the hex dump.

  • ptr – A buffer of bytes to be displayed.

  • len – The number of bytes to be displayed..