Overview

This chapter describes the programming interface of the log component. There are three steps should be followed to use the log component in specfic module,

step 1, define the macro LOG_ENABLE, likes as,

#define LOG_ENABLE 1

Note: LOG_ENABLE could be re-defined as a MODULE enabled flag such as,
#define LOG_ENABLE module_LOG_ENABLED_FLAG

step 2, include the log component header file, likes as,

#include "fsl_component_log.h"

step 3, define the log module by using macro LOG_MODULE_DEFINE, likes as,

LOG_MODULE_DEFINE(<module name>, <module log level>);

Note: The code block should be placed at the end of the header file including of the source code.

For example, In source file 1,

#define LOG_ENABLE MODULE1_CONFIG_LOG_ENABLE
#include "fsl_component_log.h"
LOG_MODULE_DEFINE(module1, kLOG_LevelTrace);

In source file 2,

#define LOG_ENABLE MODULE2_CONFIG_LOG_ENABLE
#include "fsl_component_log.h"
LOG_MODULE_DEFINE(module2, kLOG_LevelDebug);

Modules
	Log backend debug console

	Log backend ring buffer

	Log configuration

Data Structures
struct	log_module
	log module type More...

struct	log_backend
	Backend of log. More...

Macros
#define	LOG_FILE_NAME LOG_FILE_NAME_SET(LOG_FILE_NAME_RECURSIVE, LOG_FILE_NAME_INTERCEPT, __FILE__, 3) : __FILE__
	Source file name definition. More...

#define	LOG_BACKEND_DEFINE(name, puts) static log_backend_t name = {NULL, puts}
	Defines the log backend. More...

Typedefs
typedef enum _log_status	log_status_t
	log error code

typedef enum log_level	log_level_t
	log level definition More...

typedef struct log_module	log_module_t
	log module type

typedef void(*	log_backend_puts_t )(uint8_t *buffer, size_t length)
	Puts function type for log backend.

typedef log_status_t(*	log_backend_get_dump_buffer_t )(uint8_t *buffer, size_t length)
	Gets dump buffer from log backend.

typedef struct log_backend	log_backend_t
	Backend of log. More...

typedef unsigned int(*	log_get_timestamp_callback_t )(void)
	get time stamp function

Enumerations
enum	_log_status { kStatus_LOG_Success = kStatus_Success, kStatus_LOG_Error = MAKE_STATUS(kStatusGroup_LOG, 1), kStatus_LOG_Initialized = MAKE_STATUS(kStatusGroup_LOG, 2), kStatus_LOG_Uninitialized = MAKE_STATUS(kStatusGroup_LOG, 3), kStatus_LOG_LackResource = MAKE_STATUS(kStatusGroup_LOG, 4), kStatus_LOG_BackendExist = MAKE_STATUS(kStatusGroup_LOG, 5), kStatus_LOG_BackendNotFound = MAKE_STATUS(kStatusGroup_LOG, 6) }
	log error code More...

enum	log_level { kLOG_LevelNone = 0, kLOG_LevelFatal, kLOG_LevelError, kLOG_LevelWarning, kLOG_LevelInfo, kLOG_LevelDebug, kLOG_LevelTrace }
	log level definition More...

Functions
log_status_t	LOG_Init (void)
	Initializes the log component with the user configuration structure. More...

log_status_t	LOG_Deinit (void)
	De-initializes the log component. More...

void	LOG_Printf (log_module_t const module, log_level_t level, unsigned int timeStamp, char const format,...)
	Prints the format log string. More...

log_status_t	LOG_BackendRegister (log_backend_t *backend)
	Registers backend. More...

log_status_t	LOG_BackendUnregister (log_backend_t *backend)
	Unregisters backend. More...

log_status_t	LOG_SetTimestamp (log_get_timestamp_callback_t getTimeStamp)
	Sets the get timestamp function callback. More...

unsigned int	LOG_GetTimestamp (void)
	Gets current timestamp. More...

Data Structure Documentation

struct log_module

Data Fields
const char *	logModuleName
	Log module name.

log_level_t	level
	Log level of the module.

struct log_backend

Data Fields
struct log_backend *	next
	Next log backend pointer.

log_backend_puts_t	putStr
	Put data function of log backend.

Macro Definition Documentation

#define LOG_FILE_NAME LOG_FILE_NAME_SET(LOG_FILE_NAME_RECURSIVE, LOG_FILE_NAME_INTERCEPT, __FILE__, 3) : __FILE__

There is a macro __BASE_FILE__ could be used to get the current source file name in GCC. While the macro is unsupported by IAR in default, the __BASE_FILE__ is same as __FILE__ in IAR. To support the macro __BASE_FILE__, the extra option –no_path_in_file_macros should be added for IAR. But on Keil, only the source file name cannot be got through the macro __BASE_FILE__.

So, log component adds a macro LOG_FILE_NAME to get the current source file name during the compilation phase, when config LOG_ENABLE_FILE_WITH_PATH is disabled. There is a limitation, the length of file name should be not less than 2, and the supported MAX length of file name is 66 bytes. Otherwise the original string of __FILE__ will be linked.

#define LOG_BACKEND_DEFINE	(	name,
		puts
	)	static log_backend_t name = {NULL, puts}

This macro is used to define the log backend. The static global variable with parameter name is defined by the macro. And calling the function log_backend_register to register the backend with defined static global variable. For example, if there is a backend named test, the reference code is following,

*   static void puts(uint8_t *buffer, size_t length)
*   {
*       ...
*   }
*   LOG_BACKEND_DEFINE(test, puts);
* 

Parameters

name	The name of the log backend.
puts	The log string output function with log_backend_puts_t type.

Typedef Documentation

typedef enum log_level log_level_t

The log level behavior is following,
If level is kLOG_LevelTrace, trace, debug, info, warning, error, and fatal of log level will be printed.
If level is kLOG_LevelDebug, debug, info, warning, error, and fatal of log level will be printed.
If level is kLOG_LevelInfo, info, warning, error, and fatal of log level will be printed.
If level is kLOG_LevelWarning, warning, error, and fatal of log level will be printed.
If level is kLOG_LevelError, error, and fatal of log level will be printed.
If level is kLOG_LevelFatal, only fatal of log level will be printed.
If level is kLOG_LevelNone, no log level will be printed.

typedef struct log_backend log_backend_t

Enumeration Type Documentation

enum _log_status

Enumerator
kStatus_LOG_Success	Success.
kStatus_LOG_Error	Failed.
kStatus_LOG_Initialized	Initialized.
kStatus_LOG_Uninitialized	Uninitialized.
kStatus_LOG_LackResource	Lack resource.
kStatus_LOG_BackendExist	Backend exists.
kStatus_LOG_BackendNotFound	Backend not found.

enum log_level

The log level behavior is following,
If level is kLOG_LevelTrace, trace, debug, info, warning, error, and fatal of log level will be printed.
If level is kLOG_LevelDebug, debug, info, warning, error, and fatal of log level will be printed.
If level is kLOG_LevelInfo, info, warning, error, and fatal of log level will be printed.
If level is kLOG_LevelWarning, warning, error, and fatal of log level will be printed.
If level is kLOG_LevelError, error, and fatal of log level will be printed.
If level is kLOG_LevelFatal, only fatal of log level will be printed.
If level is kLOG_LevelNone, no log level will be printed.

Enumerator
kLOG_LevelNone	LOG level none.
kLOG_LevelFatal	LOG level fatal.
kLOG_LevelError	LOG level error.
kLOG_LevelWarning	LOG level warning.
kLOG_LevelInfo	LOG level info.
kLOG_LevelDebug	LOG level debug.
kLOG_LevelTrace	LOG level trace.

Function Documentation

log_status_t LOG_Init ( void )

This function configures the log component with user-defined settings. The user can configure the configuration structure. Example below shows how to use this API to configure the log component.

* LOG_Init();

*

Return values

kStatus_LOG_Success	The Log component initialization succeed.
kStatus_LOG_Initialized	Log component has been initialized.
kStatus_LOG_LackResource	Lack of resource.

log_status_t LOG_Deinit ( void )

This function de-initializes the log component.

Return values

kStatus_LOG_Success The log component de-initialization succeed.

void LOG_Printf	(	log_module_t const *	module,
		log_level_t	level,
		unsigned int	timeStamp,
		char const *	format,
			...
	)

This function prints the format log string. The timestamp and color are added to prefix by function. The log string color feature is set by the macro LOG_ENABLE_COLOR. The log string time stamp feature is set by the macro LOG_ENABLE_TIMESTAMP.

Parameters

module	the log module.
level	log level.
timeStamp	current timestamp.
format	formated log string.

log_status_t LOG_BackendRegister ( log_backend_t * backend )

This function registers the backend. The parameter of the function is defined by macro LOG_BACKEND_DEFINE.

Example below shows how to use this API to register the backend. step 1, define the backend node by calling LOG_BACKEND_DEFINE.

*   static void puts(uint8_t *buffer, size_t length)
*   {
*       ...
*   }
*   LOG_BACKEND_DEFINE(test, puts);
*  

step 2, call function LOG_BackendRegister to register the backend in same source file.

* LOG_BackendRegister(&test);

*

Parameters

backend The new backend.

Return values

kStatus_LOG_Success	The backend is registered.
kStatus_LOG_Uninitialized	The log component is not initialized.
kStatus_LOG_BackendExist	The backend has been registered.

log_status_t LOG_BackendUnregister ( log_backend_t * backend )

This function unregisters the backend.

Parameters

backend The backend.

Return values

kStatus_LOG_Success	The backend is unregistered.
kStatus_LOG_Uninitialized	The log component is not initialized.
kStatus_LOG_BackendNotFound	the backend is not found.

log_status_t LOG_SetTimestamp ( log_get_timestamp_callback_t getTimeStamp )

This function sets the get timestamp function callback. The feature is controlled by the macro LOG_ENABLE_TIMESTAMP.

Parameters

getTimeStamp get time stamp function callback.

Return values

kStatus_LOG_Success	Succeed.
kStatus_LOG_Uninitialized	The log component is not initialized.

unsigned int LOG_GetTimestamp ( void )

This function gets current timestamp. The feature is controlled by the macro LOG_ENABLE_TIMESTAMP.

Returns: Current timestamp.

Overview

Modules

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

Data Fields

Data Fields

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation