(1c353409bd)

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

Variables
char	_dv_log_offset []

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__);                        \
    if (kDeviceLogBypassUartAddress != 0) {                      \
      /* 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((const log_fields_t*)((char*)&kLogFields + (uintptr_t)&_dv_log_offset), \
                           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

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.

Definition at line 132 of file log.h.

◆ LOG_ERROR

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

Log a non-fatal error.

Parameters

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.

Definition at line 188 of file log.h.

◆ LOG_FATAL

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

Log a fatal error.

Parameters

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.

Definition at line 201 of file log.h.

◆ LOG_INFO

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

Log an informational message.

Parameters

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.

Definition at line 168 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 154 of file log.h.

◆ LOG_WARNING

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

Log a warning.

Parameters

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.

Definition at line 178 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 119 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

arg	an arg/expression to check

Definition at line 109 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

typedef enum log_severity log_severity_t

Log severities available.

Additional log severities can be added as necessary.

Enumeration Type Documentation

◆ log_severity

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

Parameters

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

Parameters

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.

Definition at line 85 of file log.c.

(1c353409bd)

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Data Structure Documentation

◆ log_fields

Macro Definition Documentation

◆ LOG

◆ LOG_ERROR

◆ LOG_FATAL

◆ LOG_INFO

◆ LOG_MAKE_FIELDS_

◆ LOG_WARNING

◆ OT_CHECK_VALID_LOG_ARGS

◆ OT_FAIL_IF_64_BIT_LOG

Typedef Documentation

◆ log_fields_t

◆ log_severity_t

Enumeration Type Documentation

◆ log_severity

Function Documentation

◆ base_log_internal_core()

◆ base_log_internal_dv()