System Logging Overview

The OS Event Log is implemented as a kernel owned circular buffer in RAM. The kernel writes some of its own events into the log, such as information related to startup, process switches, etc. Applications in User-Mode are allowed to write to this buffer too via several logging APIs. When this buffer is full, the oldest logged event is over-written as a new event is logged.

In addition to parameters supplied upon invocation of OS Log APIs, the following additional information about the calling context are recorded in the log:

Functions are provided to retrieve or display the current content of the OS Event Log in RAM. There is also a function that saves the OS Event Log to an SD card.

Summary of Logging Functions

The OS Log functions are summarized below. All of these function prototypes and related definitions are in OSSystemLog.h.

Submit Information to Log

Log Filter Administration

Retrieve and Display Log

Capture Log to Persistent Memory

Common OS Log Arguments

Several of the OS Log API have a similar set of arguments. The description of these common arguments provide insight into how the OS event log works.

Category

Each logged event belongs to a predefined category. This makes it possible to inclusively or exclusively filter events belonging to specific categories.

The OS owns a range of categories such as OS_LOG_CATEGORY_OS, OS_LOG_CATEGORY_LOADER, OS_LOG_CATEGORY_SOUND, etc.

SDK users may log their own events using the category OS_LOG_CATEGORY_APP. Alternatively, custom logging categories may be defined with a numeric range of OS_LOG_CATEGORY_CUSTOM_RANGE_START through OS_LOG_CATEGORY_LAST inclusive.

Level

There exists a total of four levels at which events may be logged. Assignment of levels makes it possible to hierarchically exclude events of lesser importance.

The log levels arranged in ascending order are: OS_LOG_LEVEL_NOISE, OS_LOG_LEVEL_NOTICE, OS_LOG_LEVEL_WARNING, OS_LOG_LEVEL_ERROR.

Options

Several of the OS log API accept an 'options' argument. This argument is bitmapped, with each bit providing optional metadata about the information being logged. These options affect how the information is saved internally within the log, as well as how it is displayed. Multiple options may be expressed by bitwise OR-ing them together. Some options consist of more than one bit. The definitions of these options include both bit shift and mask.

Name Relevant Definitions Description
default OS_LOG_DATA_OPT_DEFAULT_MASK Corresponding with a numeric value of zero, this definition does not specify any options. Default behavior is assumed.
argument count OS_LOG_DATA_OPT_ARGC_MASK, OS_LOG_DATA_OPT_ARGC_SHIFT This mask specifies the number of user arguments to be logged.
data format OS_LOG_DATA_OPT_PRINT_FORMAT_MASK, OS_LOG_DATA_OPT_FILEFUNC_FORMAT_MASK, OS_LOG_DATA_OPT_RAW_FORMAT_MASK These masks specify the format of the logged data. It can be plain text, include a source file and function name, or be raw data format.
function enter or exit OS_LOG_DATA_OPT_FUNC_ENTER_MASK, OS_LOG_DATA_OPT_FUNC_EXIT_MASK These masks specify if the logged event corresponds with a function entry or function exit. This information is passed along through the log and causes an "entry" or "exit" note to be shown when the log is displayed.
ASCII keyword OS_LOG_DATA_OPT_KEY_ARG_MASK When this mask is specified, argument arg0 is assumed to correspond with four ASCII characters. When the log is displayed it will be shown as a keyword.

Revision History

2013/08/15 Fixed broken links.
2013/05/08 Automated cleanup pass.
2012/08/02 Cleanup Pass.
2012/05/23 Initial version.


CONFIDENTIAL