MCUXpresso SDK API Reference Manual  Rev 2.12.1
NXP Semiconductors
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Log

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_t
 log module type More...
 
struct  log_backend_t
 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 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 unsigned int(* log_get_timestamp_callback_t )(void)
 get time stamp function
 

Enumerations

enum  log_status_t {
  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_t {
  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_t

Data Fields

const char * logModuleName
 Log module name.
 
log_level_t level
 Log level of the module.
 
struct log_backend_t

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
nameThe name of the log backend.
putsThe log string output function with log_backend_puts_t type.

Enumeration Type Documentation

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.

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.

*
Return values
kStatus_LOG_SuccessThe Log component initialization succeed.
kStatus_LOG_InitializedLog component has been initialized.
kStatus_LOG_LackResourceLack of resource.
log_status_t LOG_Deinit ( void  )

This function de-initializes the log component.

Return values
kStatus_LOG_SuccessThe 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
modulethe log module.
levellog level.
timeStampcurrent timestamp.
formatformated 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.

*
Parameters
backendThe new backend.
Return values
kStatus_LOG_SuccessThe backend is registered.
kStatus_LOG_UninitializedThe log component is not initialized.
kStatus_LOG_BackendExistThe backend has been registered.
log_status_t LOG_BackendUnregister ( log_backend_t backend)

This function unregisters the backend.

Parameters
backendThe backend.
Return values
kStatus_LOG_SuccessThe backend is unregistered.
kStatus_LOG_UninitializedThe log component is not initialized.
kStatus_LOG_BackendNotFoundthe 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
getTimeStampget time stamp function callback.
Return values
kStatus_LOG_SuccessSucceed.
kStatus_LOG_UninitializedThe 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.