Software APIs
Data Structures | Macros | Typedefs | Enumerations | Functions
log.h File Reference

(c534d13)

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...
 

Detailed Description

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.


Data Structure Documentation

◆ log_fields

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.

Definition at line 63 of file log.h.

Data Fields
const char * file_name Name of the file at which a LOG line occurs, e.g.

__FILE__. There are no requirements for this string, other than that it be some kind of UNIX-like pathname.

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.

Macro Definition Documentation

◆ LOG

#define LOG (   severity,
  format,
  ... 
)
Value:
do { \
OT_CHECK_VALID_LOG_ARGS(__VA_ARGS__); \
/* clang-format off */ \
/* Put DV-only log constants in .logs.* sections, which
* the linker will dutifully discard.
* Unfortunately, clang-format really mangles these
* declarations, so we format them manually. */ \
__attribute__((section(".logs.fields"))) \
static const log_fields_t kLogFields = \
LOG_MAKE_FIELDS_(severity, format, ##__VA_ARGS__); \
base_log_internal_dv(&kLogFields, \
OT_VA_ARGS_COUNT(format, ##__VA_ARGS__), \
##__VA_ARGS__); /* clang-format on */ \
} else { \
static const log_fields_t log_fields = \
LOG_MAKE_FIELDS_(severity, format, ##__VA_ARGS__); \
base_log_internal_core(&log_fields, ##__VA_ARGS__); \
} \
} while (false)

Basic logging macro that all other logging macros delegate to.

Prefer to use a LOG function with a specified severity, instead.

Parameters
severitya severity of type log_severity_t.
formata format string, as described in print.h. This must be a string literal.
...format parameters matching the format string.

Definition at line 130 of file log.h.

◆ LOG_ERROR

#define LOG_ERROR (   ...)    LOG(kLogSeverityError, __VA_ARGS__)

Log a non-fatal error.

Parameters
severitya severity of type log_severity_t.
formata format string, as described in print.h. This must be a string literal.
...format parameters matching the format string.

Definition at line 186 of file log.h.

◆ LOG_FATAL

#define LOG_FATAL (   ...)    LOG(kLogSeverityFatal, __VA_ARGS__)

Log a fatal error.

Parameters
severitya severity of type log_severity_t.
formata 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.

Definition at line 199 of file log.h.

◆ LOG_INFO

#define LOG_INFO (   ...)    LOG(kLogSeverityInfo, __VA_ARGS__)

Log an informational message.

Parameters
severitya severity of type log_severity_t.
formata format string, as described in print.h. This must be a string literal.
...format parameters matching the format string.

Definition at line 166 of file log.h.

◆ LOG_MAKE_FIELDS_

#define LOG_MAKE_FIELDS_ (   _severity,
  _format,
  ... 
)
Value:
{ \
.severity = _severity, .file_name = "" __FILE__ "", .line = __LINE__, \
.nargs = OT_VA_ARGS_COUNT(_format, ##__VA_ARGS__), .format = _format, \
}

Implementation detail of LOG.

Definition at line 152 of file log.h.

◆ LOG_WARNING

#define LOG_WARNING (   ...)    LOG(kLogSeverityWarn, __VA_ARGS__)

Log a warning.

Parameters
severitya severity of type log_severity_t.
formata format string, as described in print.h. This must be a string literal.
...format parameters matching the format string.

Definition at line 176 of file log.h.

◆ OT_CHECK_VALID_LOG_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.

Parameters
...the variable args list

Definition at line 117 of file log.h.

◆ OT_FAIL_IF_64_BIT_LOG

#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.

Parameters
argan arg/expression to check

Definition at line 107 of file log.h.

Typedef Documentation

◆ log_fields_t

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.

◆ log_severity_t

Log severities available.

Additional log severities can be added as necessary.

Enumeration Type Documentation

◆ log_severity

Log severities available.

Additional log severities can be added as necessary.

Definition at line 46 of file log.h.

Function Documentation

◆ base_log_internal_core()

void base_log_internal_core ( const log_fields_t log,
  ... 
)

Implementation detail.

Implementation detail.

Parameters
logthe log data to log.
...format parameters matching the format string.

Definition at line 47 of file log.c.

◆ base_log_internal_dv()

void base_log_internal_dv ( const log_fields_t log,
uint32_t  nargs,
  ... 
)

Implementation detail.

Implementation detail.

Parameters
loga 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.
nargsthe number of arguments passed to the format string.
...format parameters matching the format string.

Definition at line 85 of file log.c.