logger.h File Reference

Logging facility, supports verbosity levels. More...

#include <Uefi.h>

Go to the source code of this file.

Data Structures
struct	loggers_t
	logging facility data type, contains logging function pointer for each log level More...

Macros
#define	TRACE_HERE   LOG.trace(L"%a#%d",__FILE__,__LINE__);
	helper macro to log a TRACE message containing the current file and line
#define	ON_ERROR_WARN(TEXT)   if(result!=EFI_SUCCESS) LOG.warn(TEXT);
	helper macro to quickly log a WARN message if an EFI result is anything but EFI_SUCCESS More...
#define	ON_ERROR_RETURN(TEXT, RV)
	helper macro to quickly log an ERROR message and return if an EFI result is anything but EFI_SUCCESS More...

Typedefs
typedef void	logger_print_function_t(LOGLEVEL level, CHAR16 *msg)
	function pointer for log output functions More...
typedef void EFIAPI	logger_function_t(UINT16 *fmt,...)
	function pointer for logging functions to be invoked directly More...

Enumerations
enum	LOGLEVEL {   OFF =0, ERROR, WARN, INFO,   DEBUG, TRACE }
	the list of log levels More...

Functions
LOGLEVEL	get_log_level ()
	Fetches the current log level. More...
LOGLEVEL	set_log_level (LOGLEVEL level)
	Sets a new log level. More...
void	reset_logger_entry_counts ()
	Resets all log levels' message counts. More...
UINTN	get_logger_entry_count (LOGLEVEL level)
	Gets a log level's message count. More...
void	kill ()
	Immediately halts the UEFI environment. More...
logger_print_function_t *	set_logger_function (logger_print_function_t *func)
	Sets a new log writer. More...

Variables
const CHAR16 *	logger_level_names []
	list of log level's printable names
const loggers_t	LOG
	The global logging facility. More...

Detailed Description

Logging facility, supports verbosity levels.

Author

Richard Nusser

Copyright

2017-2018 Richard Nusser

License

GPLv3 (see http://www.gnu.org/licenses/)

See also

https://github.com/rinusser/UEFIStarter

Macro Definition Documentation

ON_ERROR_WARN

#define ON_ERROR_WARN

(

TEXT

)

if(result!=EFI_SUCCESS) LOG.warn(TEXT);

helper macro to quickly log a WARN message if an EFI result is anything but EFI_SUCCESS

Parameters

TEXT	the text to log

ON_ERROR_RETURN

#define ON_ERROR_RETURN	(		TEXT,
			RV
	)

Value:

if(result!=EFI_SUCCESS) \
  { \
    LOG.error(L"%s() returned status %d (%r)",TEXT,result,result); \
    return RV; \
  }

helper macro to quickly log an ERROR message and return if an EFI result is anything but EFI_SUCCESS

Parameters

TEXT	the text to log
RV	the value to return

Typedef Documentation

logger_print_function_t

typedef void logger_print_function_t(LOGLEVEL level, CHAR16 *msg)

function pointer for log output functions

Parameters

level	the log level to output at
msg	the log message to print, as UTF-16

logger_function_t

typedef void EFIAPI logger_function_t(UINT16 *fmt,...)

function pointer for logging functions to be invoked directly

Parameters

fmt	the message's format string, as UTF-16 - takes same format as Print() functions
...	any additional arguments matching the format string placeholders

Enumeration Type Documentation

LOGLEVEL

enum LOGLEVEL

the list of log levels

Enumerator
OFF	disable logging: la-la-la, I can't hear you
ERROR	error messages: something definitely broke
WARN	warnings: something may have broken
INFO	informative messages: just in case something breaks
DEBUG	debug messages: something breaks and I'm trying to fix it
TRACE	trace messages: something breaks and I don't know what or where

Function Documentation

get_log_level()

LOGLEVEL get_log_level

(

)

Fetches the current log level.

Returns

the current log level

set_log_level()

LOGLEVEL set_log_level

(

LOGLEVEL

level

)

Sets a new log level.

You can disable logging by calling this with log level "OFF".

Parameters

level

the new log level to use

Returns

the previous log level

reset_logger_entry_counts()

void reset_logger_entry_counts

(

)

Resets all log levels' message counts.

Used e.g. by the test framework to detect which tests generated errors.

get_logger_entry_count()

UINTN get_logger_entry_count

(

LOGLEVEL

level

)

Gets a log level's message count.

Parameters

level

the log level to get the count for

Returns

the number of logged messages at the given level since the last reset

kill()

void kill

(

)

Immediately halts the UEFI environment.

Use this to e.g. debug issues in graphical animations where it's vital to stop everything before the target gets painted over.

Technically the emitted interrupt 3 is usually used for debuggers but the UEFI specification requires INT 3 to be unassigned by default, thus halting everything. If you use this function with a debugger attached this will probably trigger the debugger instead.

set_logger_function()

logger_print_function_t* set_logger_function

(

logger_print_function_t *

func

)

Sets a new log writer.

Use this to replace the built-in text mode writer, e.g. to output log messages in a graphical environment

Parameters

func	the new log writer function

Returns

the previous log writer function

Variable Documentation

LOG

const loggers_t LOG

The global logging facility.

This contains function pointers for each log level, so users can call e.g. LOG.debug() to log a debug message.