MCUXpresso SDK API Reference Manual
Rev 2.12.1
NXP Semiconductors
|
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,
step 2, include the log component header file, likes as,
step 3, define the log module by using macro LOG_MODULE_DEFINE, likes as,
For example, In source file 1,
In source file 2,
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... | |
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. | |
#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,
name | The name of the log backend. |
puts | The log string output function with log_backend_puts_t type. |
enum log_status_t |
enum 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.
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.
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.
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.
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.
step 2, call function LOG_BackendRegister to register the backend in same source file.
backend | The new backend. |
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.
backend | The backend. |
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.
getTimeStamp | get time stamp function callback. |
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.