Generic logging APIs. More...
#include <stdbool.h>
#include <stdint.h>
#include "sw/device/lib/arch/device.h"
#include "sw/device/lib/base/macros.h"
Go to the source code of this file.
Data Structures | |
struct | log_fields |
Represents log metadata used to format a log line. More... | |
Macros | |
#define | OT_FAIL_IF_64_BIT_LOG(arg) OT_FAIL_IF_64_BIT(arg, LOG) |
A macro that wraps the OT_FAIL_IF_64_BIT macro, providing the name of the LOG macro for better error messages. More... | |
#define | OT_CHECK_VALID_LOG_ARGS(...) OT_VA_FOR_EACH(OT_FAIL_IF_64_BIT_LOG, ##__VA_ARGS__) |
A macro that checks the variable arguments of the LOG function are valid at compile time, by asserting that each of the argument is not a standard C integer type with a width of 64 bits. More... | |
#define | LOG(severity, format, ...) |
Basic logging macro that all other logging macros delegate to. More... | |
#define | LOG_MAKE_FIELDS_(_severity, _format, ...) |
Implementation detail of LOG . More... | |
#define | LOG_INFO(...) LOG(kLogSeverityInfo, __VA_ARGS__) |
Log an informational message. More... | |
#define | LOG_WARNING(...) LOG(kLogSeverityWarn, __VA_ARGS__) |
Log a warning. More... | |
#define | LOG_ERROR(...) LOG(kLogSeverityError, __VA_ARGS__) |
Log a non-fatal error. More... | |
#define | LOG_FATAL(...) LOG(kLogSeverityFatal, __VA_ARGS__) |
Log a fatal error. More... | |
Typedefs | |
typedef enum log_severity | log_severity_t |
Log severities available. More... | |
typedef struct log_fields | log_fields_t |
Represents log metadata used to format a log line. More... | |
Enumerations | |
enum | log_severity { kLogSeverityInfo, kLogSeverityWarn, kLogSeverityError, kLogSeverityFatal } |
Log severities available. More... | |
Functions | |
void | base_log_internal_core (const log_fields_t *log,...) |
Implementation detail. More... | |
void | base_log_internal_dv (const log_fields_t *log, uint32_t nargs,...) |
Implementation detail. More... | |
Generic logging APIs.
The logging APIs below take a format string with a variable number of arguments for the type specifiers. The APIs are designed to provide a way for attaching the log severity, file name, and line number information along with the message to provide an easier path to debug. These parameters form a log prefix, which is prepended to the actual message being printed. The following is a brief description of these:
log_type: Severity of the message: info, warning, error or fatal
file name: Name of the file using FILE
line number: Line where the print originated using LINE
Log macros support OpenTitan formatting specifiers; see print.h for details the subset of C specifier syntax supported.
The precise mechanism for logging is dependent on the target device. On core devices, like Verilator, logs are printed using whatever stdout
is set to in print.h. DV testbenches may use an alternative, more efficient mechanism.
In DV mode, some format specifiers may be unsupported, such as s.
Definition in file log.h.
struct log_fields |
Represents log metadata used to format a log line.
Any modification to this struct must be made with caution due to external assumptions. A post-processing script parses the ELF file and extracts the log fields. The said script uses 20-byte size as the delimiter to collect the log fields. Any changes to this struct must be accompanied with the updates to the script, located here: util/device_sw_utils/extract_sw_logs.py.
Data Fields | ||
---|---|---|
const char * | file_name |
Name of the file at which a LOG line occurs, e.g.
|
const char * | format | The actual format string. |
uint32_t | line |
Indicates the line number at which the LOG line occurs, e.g., __LINE__ . |
uint32_t | nargs |
Indicates the number of arguments passed to the format string. This value used only in DV mode, and is ignored by non-DV logging. |
log_severity_t | severity | Indicates the severity of the LOG. |
#define LOG | ( | severity, | |
format, | |||
... | |||
) |
Basic logging macro that all other logging macros delegate to.
Prefer to use a LOG function with a specified severity, instead.
severity | a severity of type log_severity_t . |
format | a format string, as described in print.h. This must be a string literal. |
... | format parameters matching the format string. |
#define LOG_ERROR | ( | ... | ) | LOG(kLogSeverityError, __VA_ARGS__) |
#define LOG_FATAL | ( | ... | ) | LOG(kLogSeverityFatal, __VA_ARGS__) |
Log a fatal error.
severity | a severity of type log_severity_t . |
format | a format string, as described in print.h. This must be a string literal. |
... | format parameters matching the format string. |
It is the user's responsibility to follow this up with a call to abort()
to immediately stop the execution.
#define LOG_INFO | ( | ... | ) | LOG(kLogSeverityInfo, __VA_ARGS__) |
#define LOG_MAKE_FIELDS_ | ( | _severity, | |
_format, | |||
... | |||
) |
Implementation detail of LOG
.
#define LOG_WARNING | ( | ... | ) | LOG(kLogSeverityWarn, __VA_ARGS__) |
#define OT_CHECK_VALID_LOG_ARGS | ( | ... | ) | OT_VA_FOR_EACH(OT_FAIL_IF_64_BIT_LOG, ##__VA_ARGS__) |
A macro that checks the variable arguments of the LOG
function are valid at compile time, by asserting that each of the argument is not a standard C integer type with a width of 64 bits.
Any such invalid argument will cause a relevant error via a static assertion.
... | the variable args list |
#define OT_FAIL_IF_64_BIT_LOG | ( | arg | ) | OT_FAIL_IF_64_BIT(arg, LOG) |
typedef struct log_fields log_fields_t |
Represents log metadata used to format a log line.
Any modification to this struct must be made with caution due to external assumptions. A post-processing script parses the ELF file and extracts the log fields. The said script uses 20-byte size as the delimiter to collect the log fields. Any changes to this struct must be accompanied with the updates to the script, located here: util/device_sw_utils/extract_sw_logs.py.
typedef enum log_severity log_severity_t |
Log severities available.
Additional log severities can be added as necessary.
enum log_severity |
void base_log_internal_core | ( | const log_fields_t * | log, |
... | |||
) |
void base_log_internal_dv | ( | const log_fields_t * | log, |
uint32_t | nargs, | ||
... | |||
) |
Implementation detail.
Implementation detail.
log | a pointer to log data to log. Note that this pointer is likely to be invalid at runtime, since the pointed-to data will have been stripped from the binary. |
nargs | the number of arguments passed to the format string. |
... | format parameters matching the format string. |