these macros are used in place of the printf C function. The additionnal ***component*** parameter identifies the functionnal module which generates the message. At run time, the message will only be printed if the configured log level for the component is greater or equal than the macro level used in the code.
| macro | level letter | level value | level name |
component list is defined as an `enum` in [log.h](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/LOG/log.h). A new component can be defined by adding an item in this type, it must also be defined in the T tracer [T_messages.txt ](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/T/T_messages.txt).
Most oai sources are including LOG macros.
#### conditional code macros
```C
LOG_DEBUGFLAG(<flag>)
```
this macro is to be used in if statements. The condition is true if the flag has been set, as described in the [run time usage page](rtusage.md)
```C
if ( LOG_DEBUGFLAG(<flag>) {
/*
the code below is only executed if the corresponding
<flag>_debug option is set.
*/
......................
......................
}
```
[example in oai code](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/openair1/PHY/LTE_TRANSPORT/ulsch_demodulation.c#L396)
#### memory dump macros
```C
LOG_DUMPFLAG(<flag>)
```
this macro is to be used in if statements. The condition is true if the flag has been set, as described in the [run time usage page](rtusage.md). It is mainly provided to surround LOG_M macros or direct calls to `log_dump`which otherwise would be unconditionals.
```C
if ( LOG_DUMPFLAG(<flag>) {
/*
the code below is only executed if the corresponding
<flag>_dump option is set.
*/
LOG_M(.............
LOG_M(.............
log_dump(...
}
[example in oai code](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/openair1/PHY/LTE_TRANSPORT/prach.c#L205)
#### matlab format dump
```C
LOG_M(file, vector, data, len, dec, format)
```
|argument| type| description |
|:-----------|:-------|-----------------:|
| file | char* |path to the fle which will contain the dump |
|vector |char * |name of the dump, printed at the top of the dump file |
|data| void *| pointer to the memory to be dumpped |
|len | int | length of the data to be dumpped, in `dec` unit|
| dec| int | length of each data item.Interpretation depends on format|
|format| int | defines the type of data to be dumped|
This macro can be used to dump a buffer in a format that can be used for analyze via tools like matlab or octave. **It must be surrounded by LOG_DEBUGFLAG or LOG_DUMPFLAG macros, to prevent the dump to be built unconditionally.** The LOG_M macro points to the `write_file_matlab` function implemented in [log.c](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/LOG/log.c). **This function should be revisited for more understandable implementation and ease of use (format parameter ???)**
[example in oai code](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/openair1/PHY/LTE_TRANSPORT/prach.c#L205)
#### hexadecimal format dump
```C
LOG_DUMPMSG(c, f, b, s, x...)
```
dumps a memory region if the corresponding debug flag `f` is set as explained here [run time usage page](rtusage.md)
|argument| type| description |
|:-----------|:-------|-----------------:|
| c | int, component id (in `comp_name_t` enum)| used to print the message, as specified by the s and x arguments |
|f |int |flag used to filter the dump depending on the logs configuration. flag list is defined by the LOG_MASKMAP_INIT macro in [log.h](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/LOG/log.h) |
|b| void *| pointer to the memory to be dumpped |
|s | int | length of the data to be dumpped in char|
| x...| printf format and arguments| text string to be printed at the top of the dump|
This macro can be used to conditionaly dump a buffer, bytes by bytes, giving the integer value of each byte in hexadecimal form.
[example in oai code](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/openair2/RRC/LTE/rrc_eNB.c#L1181)
This macro points to the `log_dump` function, implemented in [log.c](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/LOG/log.c). This function can also dump buffers containing `double` data via the LOG_UDUMPMSG macro
```C
LOG_UDUMPMSG(c, b, s, f, x...)
```
|argument| type| description |
|:-----------|:-------|-----------------:|
| c | int, component id (in `comp_name_t` enum)| used to print the message, as specified by the s and x arguments |
|b| void *| pointer to the memory to be dumpped |
|s | int | length of the data to be dumpped in char|
|f| int | format of dumped data LOG_DUMP_CHAR or LOG_DUMP_DOUBLE|
| x...| printf format and arguments| text string to be printed at the top of the dump|
[example in oai code](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/openair1/SIMULATION/LTE_PHY/dlsim.c#L1974)
[logging facility developer main page](ldevusage.md)
### Initializing and configuring the logging facility
#### logging facility APIs
```C
int logInit (void);
```
Allocate the internal data used by the logging utility, set the configuration, using the [configuration module](../../../config/DOC/config.md)
```C
void logClean (void)
```
Reset console attributes (color settings) and possibly close opened log files. Logging facility is still usable after this call, the internal data are not freed.
```C
int set_log(int component, int level)
void set_glog(int level)
```
Set a component or all components logiing level. Messages which level is lower than this level are not printed to the console.
```C
void set_glog_onlinelog(int enable)
```
Enable or disable all logging messages. Even error level messages are discarded, which is not advised. This can be usefull to temporarily workaround high rate of logging messages.
```C
void set_component_filelog(int comp)
void close_component_filelog(int comp)
```
Redirect or reset to stdout the output stream used by the logging facility. When the output stream is redirected to a file, it is created under /tmp with a hard-coded filename including the componemt name.
```C
SET_LOG_DEBUG(flag)
CLEAR_LOG_DEBUG(flag)
SET_LOG_DUMP(flag)
CLEAR_LOG_DUMP(flag)
```
These macros are used to set or clear the corresponding bit flag, trigerring the activation or un-activation of conditional code or memory dumps generation.
Example of using the logging utility APIs can be found, for initialization and cleanup, in [lte-softmodem.c](../../../../targets/RT/USER/lte-softmodem.c) and in the [telnet server log command implementation](../../telnetsrv/telnetsrv_proccmd.c) for a complete access to the logging facility features.
#### components and debug flags definitions
Adding a new component is just adding an item in the `comp_name_t` enum defined in [log.h](../log.h) . You must also declare it in the T Tracer facility [message fefinitions](../../T/T_messages.txt).
To add a flag than can then be used for adding conditional code or memory dumps you have to add the flag definition in the `LOG_MASKMAP_INIT` macro, in [log.h](../log.h).
[logging facility developer main page](ldevusage.md)
1. Allow a flexible activation of console traces, by configuration or dynamically at any time while code is running.
Once the logging facility has been initialized and configured developpers use C preprocessor macros to include console messages in their code. At execution time, these traces will be printed or not to the console depending on the configuration, as described [here](rtusage.md). The logging facility also defines preprocessor macros to include condtional code, to dump memory blocks (buffers, messages...).
Most developpers will only use the log macros to add console messages to the code. The logging facility also provides an api that is used for initialization and configuration.
All macros are defined in [log.h](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/LOG/log.h) include file, which must be included in any source file using the logging facility macros.
[Adding console traces in oaicode](addconsoletrace.md)
[Configuring the logging facility](configurelog.md)
[log.h](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/LOG/log.h) also includes the prototypes of the functions that have to be called to initialize, configure or get the status of console logs.
#### console messages macros
```C
LOG_E(<component>,<format>,<argument>,...)
LOG_W(<component>,<format>,<argument>,...)
LOG_I(<component>,<format>,<argument>,...)
LOG_D(<component>,<format>,<argument>,...)
LOG_T(<component>,<format>,<argument>,...)
)
```
these macros are used in place of the printf C function. The additionnal ***component*** parameter identifies the functionnal module which generates the message. At run time, the message will only be printed if the configured log level for the component is greater or equal than the macro level used in the code.
| macro | level letter | level value | level name |
component list is defined as an `enum` in [log.h](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/LOG/log.h). A new component can be defined by adding an item in this type, it must also be defined in the T tracer [T_messages.txt ](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/T/T_messages.txt).
Most oai sources are including LOG macros.
#### conditional code macros
```C
LOG_DEBUGFLAG(<flag>)
```
this macro is to be used in if statements. The condition is true if the flag has been set, as described in the [run time usage page](rtusage.md)
```C
if ( LOG_DEBUGFLAG(<flag>) {
/*
the code below is only executed if the corresponding
<flag>_debug option is set.
*/
......................
......................
}
```
[example in oai code](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/openair1/PHY/LTE_TRANSPORT/ulsch_demodulation.c#L396)
#### memory dump macros
```C
LOG_DUMPFLAG(<flag>)
```
this macro is to be used in if statements. The condition is true if the flag has been set, as described in the [run time usage page](rtusage.md). It is mainly provided to surround LOG_M macros or direct calls to `log_dump`which otherwise would be unconditionals.
```C
if ( LOG_DUMPFLAG(<flag>) {
/*
the code below is only executed if the corresponding
<flag>_dump option is set.
*/
LOG_M(.............
LOG_M(.............
log_dump(...
}
[example in oai code](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/openair1/PHY/LTE_TRANSPORT/prach.c#L205)
#### matlab format dump
```C
LOG_M(file, vector, data, len, dec, format)
```
|argument| type| description |
|:-----------|:-------|-----------------:|
| file | char* |path to the fle which will contain the dump |
|vector |char * |name of the dump, printed at the top of the dump file |
|data| void *| pointer to the memory to be dumpped |
|len | int | length of the data to be dumpped, in `dec` unit|
| dec| int | length of each data item.Interpretation depends on format|
|format| int | defines the type of data to be dumped|
This macro can be used to dump a buffer in a format that can be used for analyze via tools like matlab or octave. **It must be surrounded by LOG_DEBUGFLAG or LOG_DUMPFLAG macros, to prevent the dump to be built unconditionally.** The LOG_M macro points to the `write_file_matlab` function implemented in [log.c](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/LOG/log.c). **This function should be revisited for more understandable implementation and ease of use (format parameter ???)**
[example in oai code](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/openair1/PHY/LTE_TRANSPORT/prach.c#L205)
#### hexadecimal format dump
```C
LOG_DUMPMSG(c, f, b, s, x...)
```
dumps a memory region if the corresponding debug flag `f` is set as explained here [run time usage page](rtusage.md)
|argument| type| description |
|:-----------|:-------|-----------------:|
| c | int, component id (in `comp_name_t` enum)| used to print the message, as specified by the s and x arguments |
|f |int |flag used to filter the dump depending on the logs configuration. flag list is defined by the LOG_MASKMAP_INIT macro in [log.h](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/LOG/log.h) |
|b| void *| pointer to the memory to be dumpped |
|s | int | length of the data to be dumpped in char|
| x...| printf format and arguments| text string to be printed at the top of the dump|
This macro can be used to conditionaly dump a buffer, bytes by bytes, giving the integer value of each byte in hexadecimal form.
[example in oai code](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/openair2/RRC/LTE/rrc_eNB.c#L1181)
This macro points to the `log_dump` function, implemented in [log.c](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/common/utils/LOG/log.c). This function can also dump buffers containing `double` data via the LOG_UDUMPMSG macro
```C
LOG_UDUMPMSG(c, b, s, f, x...)
```
|argument| type| description |
|:-----------|:-------|-----------------:|
| c | int, component id (in `comp_name_t` enum)| used to print the message, as specified by the s and x arguments |
|b| void *| pointer to the memory to be dumpped |
|s | int | length of the data to be dumpped in char|
|f| int | format of dumped data LOG_DUMP_CHAR or LOG_DUMP_DOUBLE|
| x...| printf format and arguments| text string to be printed at the top of the dump|
[example in oai code](https://gitlab.eurecom.fr/oai/openairinterface5g/blob/develop/openair1/SIMULATION/LTE_PHY/dlsim.c#L1974)
