hal_log.h File Reference

Logging component. More...

Detailed Description

Logging component.

Purpose

HALFRED Hardware Abstraction Layer

Version

Revision

1500

License

$License$

Copyright

$Copyright$

#include "hal_config.h"
#include "hal_iodevice.h"
#include <stdint.h>
#include <stdbool.h>
#include <inttypes.h>

Go to the source code of this file.

Macros
#define	HAL_ENABLE_LOG   0
#define	HAL_LOG_LAST_CHANNEL   0
#define	HAL_LOG_CHANNEL   DEFAULT
#define	DEFAULT_LOG_CHANNEL   0
#define	HAL_LOG_LEVEL   HAL_LOG_LEVEL_NOTICE
#define	HAL_LOG_LEVEL_EMERGENCY   0
#define	HAL_LOG_LEVEL_ALERT   1
#define	HAL_LOG_LEVEL_CRITICAL   2
#define	HAL_LOG_LEVEL_ERROR   3
#define	HAL_LOG_LEVEL_WARNING   4
#define	HAL_LOG_LEVEL_NOTICE   5
#define	HAL_LOG_LEVEL_INFO   6
#define	HAL_LOG_LEVEL_DEBUG   7
#define	HAL_LOG_EMERGENCY(...)   HAL_LOG(HAL_LOG_LEVEL_EMERGENCY, __VA_ARGS__)
#define	HAL_LOG_ALERT(...)   HAL_LOG(HAL_LOG_LEVEL_ALERT, __VA_ARGS__)
#define	HAL_LOG_CRITICAL(...)   HAL_LOG(HAL_LOG_LEVEL_CRITICAL, __VA_ARGS__)
#define	HAL_LOG_ERROR(...)   HAL_LOG(HAL_LOG_LEVEL_ERROR, __VA_ARGS__)
#define	HAL_LOG_WARNING(...)   HAL_LOG(HAL_LOG_LEVEL_WARNING, __VA_ARGS__)
#define	HAL_LOG_NOTICE(...)   HAL_LOG(HAL_LOG_LEVEL_NOTICE, __VA_ARGS__)
#define	HAL_LOG_INFO(...)   HAL_LOG(HAL_LOG_LEVEL_INFO, __VA_ARGS__)
#define	HAL_LOG_DEBUG(...)   HAL_LOG(HAL_LOG_LEVEL_DEBUG, __VA_ARGS__)
#define	HAL_ASSERT(condition)   if(!(condition)) do { HAL_LOG_CRITICAL("Assertion failed in " __FILE__ ":%u\n", __LINE__); } while(0)
#define	HAL_ASSERT_AND_EXECUTE(condition)   HAL_ASSERT(condition); else
#define	HAL_LOG(level,...)

Typedefs
typedef uint32_t	HAL_LOG_Time

Functions
bool	HAL_LOG_SetChannelOutput (const uint8_t channel, IODevice const iodev)
bool	HAL_LOG_SetChannelTimeSource (const uint8_t channel, HAL_LOG_Time(*timeSourceFunction)(void))
bool	HAL_LOG_EnableChannel (const uint8_t channel)
bool	HAL_LOG_DisableChannel (const uint8_t channel)
bool	HAL_LOG_IsChannelEnabled (const uint8_t channel)

Typedef Documentation

typedef uint32_t HAL_LOG_Time

defgroup hal_log LOG module

Introduction

The logging module in HAL (called LOG) provides a standard way for user applications to report their condition. The LOG module supports:

• up to 255 logging channels, each capable of using different I/O interface
• Compile-time managed subchannels, for even better control of output messages
• Syslog-compatible standard log severity levels
• Variety of compile-time switches that reduces footprint of disabled options to 0
• cstdio-like API for comfortable and fast formatted output
• Runtime assertions
  • The LOG module is also used internally by other HAL modules, to report their errors and log status.

Module architecture The module itself consists of 1 header file and 1 source file. The vast majority of log customization is provided via preprocessing layer. Runtime operation uses standard C library, or proprietary "printf" functions for formatting output. The attached custom library is vastly faster than the stdio implementation, and does not require using dynamic memory allocation.

Diagnostic level This module uses standard syslog log detail naming. Below we list all of the detail levels in order from least detail to the most:

• HAL_LOG_LEVEL_EMERGENCY (1)
• HAL_LOG_LEVEL_ALERT (2)
• HAL_LOG_LEVEL_CRITICAL (3)
• HAL_LOG_LEVEL_ERROR (4)
• HAL_LOG_LEVEL_WARNING (5)
• HAL_LOG_LEVEL_NOTICE (6)
• HAL_LOG_LEVEL_INFO (7)
• HAL_LOG_LEVEL_DEBUG (8)

The Log module provides simple way to manage globally the log detail of all channels: In order to override default value (INFORMATIONAL level), user should define macro HAL_LOG_MAX_LEVEL with the level of choice.

Log channels Log subchannels Assertions Compile time API Global: [Required] HAL_ENABLE_LOG (0) Global log on/off switch [Optional] HAL_LOG_LAST_CHANNEL (0) amount of log channels available [Optional] HAL_LOG_LEVEL (HAL_LOG_LEVEL_INFO) Global maximum verbosity of log messages. All messages of higher detail will be discarded at compile time Per module: [Optional] HAL_LOG_CHANNEL (DEFAULT) Defines the Log channel. Every channel has to have unique name. If not provided, the LOG module will use DEFAULT channel [Required/Optional] ($CHANNEL)_LOG_CHANNEL (0) Defines descriptor number of LOG channel (basically each channel should have distinct ($CHANNEL)_LOG_CHANNEL value). The value 0 is reserved for DEFAULT LOG channel [Optional] ($CHANNEL)_LOG_CHANNEL_ENABLED (1) main on/off switch of the LOG channel [Optional] ($CHANNEL)_LOG_CHANNEL_LEVEL (HAL_LOG_LEVEL) [Optional] HAL_LOG_SUBCHANNEL () Allows to create virtual subchannel over the same interface as parent channel. [Optional] ($CHANNEL)_($SUBCHANNEL)_LOG_SUBCHANNEL_ENABLED (1) main on/off switch of the LOG subchannel [Optional] ($CHANNEL)_LOG_CHANNEL_LEVEL (($CHANNEL)_LOG_CHANNEL_LEVEL)

Function Documentation

bool HAL_LOG_SetChannelOutput	(	const uint8_t	channel,
		IODevice const	iodev
	)

Binds I/O device to log channel

Parameters

[in]	channel	channel number to have I/O device assigned
[in]	pointer	to I/O device descriptor

Returns

true when the operation was successful; false otherwise

Note

provided channel number shall be macro, that was defined in hal_config.h for clearance (i.e. ZBCOMM_CHANNEL_NUMBER)

bool HAL_LOG_SetChannelTimeSource	(	const uint8_t	channel,
		HAL_LOG_Time(*)(void)	timeSourceFunction
	)

Binds time source to log channel

Parameters

[in]	channel	channel number to have time source assigned
[in]	callback	that returns current system time when invoked

Returns

true when the operation was successful; false otherwise

Note

provided channel number shall be macro, that was defined in hal_config.h for clearance (i.e. ZBCOMM_CHANNEL_NUMBER)

bool HAL_LOG_EnableChannel

(

const uint8_t

channel

)

Enables log channel output

Parameters

[in]

channel

channel number to be enabled

Returns

true when the operation was successful; false otherwise

Note

provided channel number shall be macro, that was defined in hal_config.h for clearance (i.e. ZBCOMM_CHANNEL_NUMBER)

bool HAL_LOG_DisableChannel

(

const uint8_t

channel

)

Disables log channel output

Parameters

[in]

channel

v to be disabled

Returns

true when the operation was successful; false otherwise

Note

provided channel number shall be macro, that was defined in hal_config.h for clearance (i.e. ZBCOMM_CHANNEL_NUMBER)

bool HAL_LOG_IsChannelEnabled

(

const uint8_t

channel

)

Returns information whether the channel is enabled or not

Parameters

[in]

channel

channel number

Returns

logical value

Note

provided channel number shall be macro, that was defined in hal_config.h for clearance (i.e. ZBCOMM_CHANNEL_NUMBER)