OSLogReport

Syntax

#include <cafe/os/OSSystemLog.h>

BOOL OSLogReport(u32 retrievalOptions, void* pWorkspace, u32 workSpaceSize);

Parameters

retrievalOptions Bitmap of options which may reduce the amount of reported events. Multiple options may be expressed by bitwise OR-ing them together. For more information, see OS Log Retrieval Options.
pWorkspace The act of retrieving and displaying the contents of the event log requires a workspace buffer. The caller may specify a larger buffer to see deeper event log history. The size of the specified workspace must be greater than sizeof(OS_LOG_RETRIEVAL).
workSpaceSize Size of available memory referred to by pWorkspace.

OS Log Retrieval Options

Option Category Description
OS_LOG_RETRIEVAL_OPT_DEFAULT_MASK default Corresponding with a numeric value of zero, this definition does not specify any options. Default behavior is assumed, reporting all logged events, subject to filter policy established by OSLogSetFilterPolicy.
OS_LOG_RETRIEVAL_OPT_EXCLUDE_CORE0_MASK, OS_LOG_RETRIEVAL_OPT_EXCLUDE_CORE1_MASK, OS_LOG_RETRIEVAL_OPT_EXCLUDE_CORE2_MASK core exclusion Exclude events logged by specific cores.
OS_LOG_RETRIEVAL_OPT_EXCLUDE_USER_NOISE_MASK, OS_LOG_RETRIEVAL_OPT_EXCLUDE_USER_NOTICE_MASK, OS_LOG_RETRIEVAL_OPT_EXCLUDE_USER_WARNING_MASK, OS_LOG_RETRIEVAL_OPT_EXCLUDE_USER_ERROR_MASK usermode log level exclusion Exclude specific usermode event levels. Note that events at these levels may still be occupying space in the log. These options just prevent them from being reported.
OS_LOG_RETRIEVAL_OPT_EXCLUDE_KERNEL_NOISE_MASK, OS_LOG_RETRIEVAL_OPT_EXCLUDE_KERNEL_NOTICE_MASK, OS_LOG_RETRIEVAL_OPT_EXCLUDE_KERNEL_WARNING_MASK, OS_LOG_RETRIEVAL_OPT_EXCLUDE_KERNEL_ERROR_MASK kernelmode log level exclusion Exclude specific kernelmode event levels. Note that events at these levels may still be occupying space in the log. These options just prevent them from being reported.
OS_LOG_RETRIEVAL_OPT_IGNORE_FILTERS_MASK retrieve all When set, no events shall be excluded during the retrieval process. Any other retrievalOptions bits for excluding events are ignored. Filter policy established by OSLogSetFilterPolicy is ignored for any events which are already saved in the log.

Return Values

TRUE if successful, FALSE if unsuccessful.

Description

Displays the contents of the event log using OSReport. Each log entry is reported with at least one line of output, potentially more for entries containing variable length or printable data.

There are several fields in the reported log entry. The following example log output line will be considered when describing reported log fields below.

001 7779825 U2 15 e. 1-003 00000068 00000069 0000006a 0000006b En functionCallWithFourArgs @ line 666
Field Example Description
1 001 Log session, which may increment across OS restarts. In some cases the OS event log will persist across normal OS restarts. This field is used to differentiate booted log sessions.
2 7779825 Timestamp since system startup in units of microseconds.
3 U U indicates that log was submitted by usermode, K indicates that log was submitted by kernelmode. Note that events logged in kernelmode use an internal set of event categories, the definitions for which are not provided to SDK users.
4 2 CPU core ID on which the code that submitted the log entry was executing.
5 15 Process ID of the executing code that submitted the log entry.
6 e e indicates that interrupts were enabled within the calling context when the log was submitted, . indicates that they were not.
7 . p indicates that interrupts were pending within the calling context when the log was submitted, . indicates that they were not.
8 1 Level of the logged event.
9 003 Category of the logged event.
10-13 00000068, 00000069, 0000006a, 0000006b Arbitrary word arguments passed when log was submitted. These fields are optional and may not be present for some entries. Only these OS Log API are capable of submitting arguments: OSLogArgs, OSLogFunc.
14 En En indicates function entry and Ex indicates function exit. This output is driven by log options OS_LOG_DATA_OPT_FUNC_ENTER_MASK and OS_LOG_DATA_OPT_FUNC_EXIT_MASK.
15 functionCallWithFourArgs When OS Log API OSLogFunc is used, the name of function which submitted the log is provided.
16 @ line 666 When OS Log API OSLogFunc is used, a reference source file line number is provided.

Specification of retrievalOptions argument may exclude some events which currently exist in the log. Events that currently exist in the log but are excluded because of subsequent policy established by OSLogSetFilterPolicy are not reported unless the OS_LOG_RETRIEVAL_OPT_IGNORE_FILTERS_MASK option is specified.

Do Not Call From

None.

See Also

System Logging Overview
APP_TRACE_* Macros
OSLogArgs
OSLogBuffer
OSLogFunc
OSLogPrintf
OSLogRetrieve
OSLogSaveCrashDump
OSLogSetFilterPolicy

Revision History

2015-03-11 Various style fixes.
2013-05-08 Automated cleanup pass.
2012-05-23 Initial version.


CONFIDENTIAL