Logging API

enum log_level_t

Log levels supported, ranging from most to least important

Constants

LOGL_EMERG
U-Boot is unstable
LOGL_ALERT
Action must be taken immediately
LOGL_CRIT
Critical conditions
LOGL_ERR
Error that prevents something from working
LOGL_WARNING
Warning may prevent optimal operation
LOGL_NOTICE
Normal but significant condition, printf()
LOGL_INFO
General information message
LOGL_DEBUG
Basic debug-level message
LOGL_DEBUG_CONTENT
Debug message showing full message content
LOGL_DEBUG_IO
Debug message showing hardware I/O access
LOGL_COUNT
Total number of valid log levels
LOGL_NONE
Used to indicate that there is no valid log level
LOGL_LEVEL_MASK
Mask for valid log levels
LOGL_FORCE_DEBUG
Mask to force output due to LOG_DEBUG
LOGL_FIRST
The first, most-important log level
LOGL_MAX
The last, least-important log level
LOGL_CONT
Use same log level as in previous call
enum log_category_t

Log categories supported.

Constants

LOGC_FIRST
First log category
LOGC_NONE
Default log category
LOGC_ARCH
Related to arch-specific code
LOGC_BOARD
Related to board-specific code
LOGC_CORE
Related to core features (non-driver-model)
LOGC_DM
Core driver-model
LOGC_DT
Device-tree
LOGC_EFI
EFI implementation
LOGC_ALLOC
Memory allocation
LOGC_SANDBOX
Related to the sandbox board
LOGC_BLOBLIST
Bloblist
LOGC_DEVRES
Device resources (devres_... functions)
LOGC_ACPI
Advanced Configuration and Power Interface (ACPI)
LOGC_BOOT
Related to boot process / boot image processing
LOGC_COUNT
Number of log categories
LOGC_END
Sentinel value for lists of log categories
LOGC_CONT
Use same category as in previous call

Description

Log categories between LOGC_FIRST and LOGC_NONE correspond to uclasses (i.e. enum uclass_id), but there are also some more generic categories.

Remember to update log_cat_name[] after adding a new category.

int _log(enum log_category_t cat, enum log_level_t level, const char *file, int line, const char *func, const char *fmt, ...)

Internal function to emit a new log record

Parameters

enum log_category_t cat
Category of log record (indicating which subsystem generated it)
enum log_level_t level
Level of log record (indicating its severity)
const char *file
File name of file where log record was generated
int line
Line number in file where log record was generated
const char *func
Function where log record was generated
const char *fmt
printf() format string for log record
...
Optional parameters, according to the format string fmt

Return

0 if log record was emitted, -ve on error

int _log_buffer(enum log_category_t cat, enum log_level_t level, const char *file, int line, const char *func, ulong addr, const void *data, uint width, uint count, uint linelen)

Internal function to print data buffer in hex and ascii form

Parameters

enum log_category_t cat
Category of log record (indicating which subsystem generated it)
enum log_level_t level
Level of log record (indicating its severity)
const char *file
File name of file where log record was generated
int line
Line number in file where log record was generated
const char *func
Function where log record was generated
ulong addr
Starting address to display at start of line
const void *data
pointer to data buffer
uint width
data value width. May be 1, 2, or 4.
uint count
number of values to display
uint linelen
Number of values to print per line; specify 0 for default length
assert(x)

assert expression is true

Parameters

x
expression to test

Description

If the expression x evaluates to false and _DEBUG evaluates to true, a panic message is written and the system stalls. The value of _DEBUG is set to true if DEBUG is defined before including common.h.

The expression x is always executed irrespective of the value of _DEBUG.

struct log_rec

a single log record

Definition

struct log_rec {
  enum log_category_t cat;
  enum log_level_t level;
  u16 line;
  u8 flags;
  const char *file;
  const char *func;
  const char *msg;
};

Members

cat
Category, representing a uclass or part of U-Boot
level
Severity level, less severe is higher
line
Line number where the log record was generated
flags
Flags for log record (enum log_rec_flags)
file
Name of file where the log record was generated (not allocated)
func
Function where the log record was generated (not allocated)
msg
Log message (allocated)

Description

Holds information about a single record in the log

Members marked as ‘not allocated’ are stored as pointers and the caller is responsible for making sure that the data pointed to is not overwritten. Members marked as ‘allocated’ are allocated (e.g. via strdup()) by the log system.

TODO(sjg**chromium.org**): Compress this struct down a bit to reduce space, e.g. a single u32 for cat, level, line and force_debug

struct log_driver

a driver which accepts and processes log records

Definition

struct log_driver {
  const char *name;
  int (*emit)(struct log_device *ldev, struct log_rec *rec);
  unsigned short flags;
};

Members

name
Name of driver
emit

emit a log record

Called by the log system to pass a log record to a particular driver for processing. The filter is checked before calling this function.

flags
Initial value for flags (use LOGDF_ENABLE to enable on start-up)
struct log_device

an instance of a log driver

Definition

struct log_device {
  unsigned short next_filter_num;
  unsigned short flags;
  struct log_driver *drv;
  struct list_head filter_head;
  struct list_head sibling_node;
};

Members

next_filter_num
Sequence number of next filter filter added (0=no filters yet). This increments with each new filter on the device, but never decrements
flags
Flags for this filter (enum log_device_flags)
drv
Pointer to driver for this device
filter_head
List of filters for this device
sibling_node
Next device in the list of all devices

Description

Since drivers are set up at build-time we need to have a separate device for the run-time aspects of drivers (currently just a list of filters to apply to records send to this device).

enum log_filter_flags

Flags which modify a filter

Constants

LOGFF_HAS_CAT
Filter has a category list
LOGFF_DENY
Filter denies matching messages
LOGFF_LEVEL_MIN
Filter’s level is a minimum, not a maximum
struct log_filter

criteria to filter out log messages

Definition

struct log_filter {
  int filter_num;
  int flags;
  enum log_category_t cat_list[LOGF_MAX_CATEGORIES];
  enum log_level_t level;
  const char *file_list;
  struct list_head sibling_node;
};

Members

filter_num
Sequence number of this filter. This is returned when adding a new filter, and must be provided when removing a previously added filter.
flags
Flags for this filter (LOGFF_...)
cat_list
List of categories to allow (terminated by LOGC_END). If empty then all categories are permitted. Up to LOGF_MAX_CATEGORIES entries can be provided
level
Maximum (or minimum, if LOGFF_MIN_LEVEL) log level to allow
file_list
List of files to allow, separated by comma. If NULL then all files are permitted
sibling_node
Next filter in the list of filters for this log device

Description

If a message matches all criteria, then it is allowed. If LOGFF_DENY is set, then it is denied instead.

const char * log_get_cat_name(enum log_category_t cat)

Get the name of a category

Parameters

enum log_category_t cat
Category to look up

Return

category name (which may be a uclass driver name) if found, or
“<invalid>” if invalid, or “<missing>” if not found. All error responses begin with ‘<’.
enum log_category_t log_get_cat_by_name(const char *name)

Look up a category by name

Parameters

const char *name
Name to look up

Return

Category, or LOGC_NONE if not found

const char * log_get_level_name(enum log_level_t level)

Get the name of a log level

Parameters

enum log_level_t level
Log level to look up

Return

Log level name (in ALL CAPS)

enum log_level_t log_get_level_by_name(const char *name)

Look up a log level by name

Parameters

const char *name
Name to look up

Return

Log level, or LOGL_NONE if not found

struct log_device * log_device_find_by_name(const char *drv_name)

Look up a log device by its driver’s name

Parameters

const char *drv_name
Name of the driver

Return

the log device, or NULL if not found

bool log_has_cat(enum log_category_t cat_list[], enum log_category_t cat)

check if a log category exists within a list

Parameters

enum log_category_t cat_list[]
List of categories to check, at most LOGF_MAX_CATEGORIES entries long, terminated by LC_END if fewer
enum log_category_t cat
Category to search for

Return

true if cat is in cat_list, else false

bool log_has_file(const char *file_list, const char *file)

check if a file is with a list

Parameters

const char *file_list
List of files to check, separated by comma
const char *file
File to check for. This string is matched against the end of each file in the list, i.e. ignoring any preceding path. The list is intended to consist of relative pathnames, e.g. common/main.c,cmd/log.c

Return

true if file is in file_list, else false

int log_add_filter_flags(const char *drv_name, enum log_category_t cat_list[], enum log_level_t level, const char *file_list, int flags)

Add a new filter to a log device, specifying flags

Parameters

const char *drv_name
Driver name to add the filter to (since each driver only has a single device)
enum log_category_t cat_list[]
List of categories to allow (terminated by LOGC_END). If empty then all categories are permitted. Up to LOGF_MAX_CATEGORIES entries can be provided
enum log_level_t level
Maximum (or minimum, if LOGFF_LEVEL_MIN) log level to allow
const char *file_list
List of files to allow, separated by comma. If NULL then all files are permitted
int flags
Flags for this filter (LOGFF_...)

Return

the sequence number of the new filter (>=0) if the filter was added, or a -ve value on error
int log_add_filter(const char *drv_name, enum log_category_t cat_list[], enum log_level_t max_level, const char *file_list)

Add a new filter to a log device

Parameters

const char *drv_name
Driver name to add the filter to (since each driver only has a single device)
enum log_category_t cat_list[]
List of categories to allow (terminated by LOGC_END). If empty then all categories are permitted. Up to LOGF_MAX_CATEGORIES entries can be provided
enum log_level_t max_level
Maximum log level to allow
const char *file_list
List of files to allow, separated by comma. If NULL then all files are permitted

Return

the sequence number of the new filter (>=0) if the filter was added, or a -ve value on error
int log_remove_filter(const char *drv_name, int filter_num)

Remove a filter from a log device

Parameters

const char *drv_name
Driver name to remove the filter from (since each driver only has a single device)
int filter_num
Filter number to remove (as returned by log_add_filter())

Return

0 if the filter was removed, -ENOENT if either the driver or the filter number was not found
int log_device_set_enable(struct log_driver *drv, bool enable)

Enable or disable a log device

Parameters

struct log_driver *drv
Driver of device to enable
bool enable
true to enable, false to disable return 0 if OK, -ENOENT if the driver was not found

Description

Devices are referenced by their driver, so use LOG_GET_DRIVER(name) to pass the driver to this function. For example if the driver is declared with LOG_DRIVER(wibble) then pass LOG_GET_DRIVER(wibble) here.

int log_init(void)

Set up the log system ready for use

Parameters

void
no arguments

Return

0 if OK, -ENOMEM if out of memory

int log_get_default_format(void)

get default log format

Parameters

void
no arguments

Description

The default log format is configurable via CONFIG_LOGF_FILE, CONFIG_LOGF_LINE, and CONFIG_LOGF_FUNC.

Return

default log format