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 Cygnus 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 in app_log_masks.h. Cannot be suppressed
-
LOG_MASK_ERROR¶
Prints red, cannot be suppressed.
-
LOG_MASK_WARN¶
Prints yellow, cannot be suppressed.
-
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 suppressed. The initial state can be set in reach-server.h
- Returns:
cr_ErrorCodes_NO_ERROR on success.
-
bool i3_log_get_remote_cli_enable(void)¶
i3_log_get_remote_cli_enable
- Returns:
true if enabled.
-
int i3_log_set_ble_error_state(bool errors_detected)¶
i3_log_set_ble_error_state
In the event of BLE communication issues (particularly if notifications cannot be sent), making the logger aware of this means it can avoid attempting to use the BLE connection to send log messages. This makes it safe to use LOG_MASK_ERROR to log error information.
- Returns:
cr_ErrorCodes_NO_ERROR on success.
-
bool i3_log_get_ble_error_state(void)¶
i3_log_get_ble_error_state
- Returns:
true if a BLE error has been detected.
-
int i3_log_get_remote_buffer(char **pRcli, size_t *pBufSize)¶
i3_log_get_remote_buffer
Retrieve the pointer and size of the remote buffer. Intended to be used by implementations that override the weak i3_log() given here.
- Parameters:
pRcli – pointer to char pointer of buffer.
pBufSize – pointer to the size of the buffer.
- Returns:
zero.
- void i3_log (const uint32_t mask, const char *fmt,...) __attribute__((format(__printf__
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 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..
-
void i3_log_persistent_init(void)¶
i3_log_persistent_init
Persistent Logging: Simple code will sprintf into a circular buffer. This buffer should persist across warm boots It can be dumped to the regular log on request.
Creates a buffer that persists across warm resets.
-
void i3_log_persist(const char *fmt, ...)¶
i3_log_persist
A printf style logging function. Has no OS dependency. Just sprintf into a buffer. The buffer is designed to persist over a (warm) reboot. The simple function should also have no OS dependency so that it can be called regardless of the state of the OS.
- Parameters:
fmt – : standard printf format.
-
void i3_log_persistent_clear(void)¶
i3_log_persistent_clear
Clears the persistent buffer.