Component: Asserts & Tracing

Macro name

CYGPKG_INFRA_DEBUG

Type

Boolean

Description

The eCos source code contains a significant amount of internal debugging support, in the form of assertions and tracing. Assertions check at runtime that various conditions are as expected; if not, execution is halted. Tracing takes the form of text messages that are output whenever certain events occur, or whenever functions are called or return. The most important property of these checks and messages is that they are not required for the program to run. It is prudent to develop software with assertions enabled, but disable them when making a product release, thus removing the overhead of that checking. It is possible to enable assertions and tracing independently. There are also options controlling the exact behavior of the assertion and tracing facilities, thus giving users finer control over the code and data size requirements.

Component: Use asserts

Macro name

CYGDBG_USE_ASSERTS

Type

Boolean

Description

If this option is defined, asserts in the code are tested. Assert functions (CYG_ASSERT()) are defined in "include/cyg/infra/cyg_ass.h" within the "install" tree. If it is not defined, these result in no additional object code and no checking of the asserted conditions.

Option: Preconditions

Macro name

CYGDBG_INFRA_DEBUG_PRECONDITIONS

Type

Boolean

Description

This option allows individual control of preconditions. A precondition is one type of assert, which it is useful to control separately from more general asserts. The function is CYG_PRECONDITION(condition,msg).

Option: Postconditions

Macro name

CYGDBG_INFRA_DEBUG_POSTCONDITIONS

Type

Boolean

Description

This option allows individual control of postconditions. A postcondition is one type of assert, which it is useful to control separately from more general asserts. The function is CYG_POSTCONDITION(condition,msg).

Option: Loop invariants

Macro name

CYGDBG_INFRA_DEBUG_LOOP_INVARIANTS

Type

Boolean

Description

This option allows individual control of loop invariants. A loop invariant is one type of assert, which it is useful to control separately from more general asserts, particularly since a loop invariant is typically evaluated a great many times when used correctly. The function is CYG_LOOP_INVARIANT(condition,msg).

Option: Use assert text

Macro name

CYGDBG_INFRA_DEBUG_ASSERT_MESSAGE

Type

Boolean

Description

All assertions within eCos contain a text message which should give some information about the condition being tested. These text messages will end up being embedded in the application image and hence there is a significant penalty in terms of image size. It is possible to suppress the use of these messages by disabling this option. This results in smaller code size, but there is less human-readable information if an assertion actually gets triggered.

Component: Use tracing

Macro name

CYGDBG_USE_TRACING

Type

Boolean

Description

If this option is defined, tracing operations result in output or logging, depending on other options. This may have adverse effects on performance, if the time taken to output message overwhelms the available CPU power or output bandwidth. Trace functions (CYG_TRACE())are defined in include/cyg/infra/cyg_trac.h within the install tree. If it is not defined, these result in no additional object code and no trace information.

Option: Trace function reports

Macro name

CYGDBG_INFRA_DEBUG_FUNCTION_REPORTS

Type

Boolean

Description

This option allows individual control of function entry/exit tracing, independent of more general tracing output. This may be useful to remove clutter from a trace log.

Option: Use trace text

Macro name

CYGDBG_INFRA_DEBUG_TRACE_MESSAGE

Type

Boolean

Description

All trace calls within eCos contain a text message which should give some information about the circumstances. These text messages will end up being embedded in the application image and hence there is a significant penalty in terms of image size. It is possible to suppress the use of these messages by disabling this option. This results in smaller code size, but there is less human-readable information available in the trace output, possibly only filenames and line numbers.

Option: Null output

Macro name

CYGDBG_INFRA_DEBUG_TRACE_ASSERT_NULL

Type

Radio

Description

A null output module which is useful when debugging interactively; the output routines can be breakpointed rather than have them actually "print" something.

Option: Simple output

Macro name

CYGDBG_INFRA_DEBUG_TRACE_ASSERT_SIMPLE

Type

Radio

Description

An output module which produces simple output from tracing and assertion events.

Option: Fancy output

Macro name

CYGDBG_INFRA_DEBUG_TRACE_ASSERT_FANCY

Type

Radio

Description

An output module which produces fancy output from tracing and assertion events.

Component: Buffered tracing

Macro name

CYGDBG_INFRA_DEBUG_TRACE_ASSERT_BUFFER

Type

Radio

Description

An output module which buffers output from tracing and assertion events. The stored messages are output when an assert fires, or cyg_trace_output() is called. Of course, there will only be stored messages if tracing per se (CYGDBG_USE_TRACING) is enabled above.

Option: Trace buffer size

Macro name

CYGDBG_INFRA_DEBUG_TRACE_BUFFER_SIZE

Type

Count

Description

The size of the trace buffer. This counts the number of trace records stored. When the buffer fills it either wraps, stops recording, or generates output.

Option: Wrap trace buffer when full

Macro name

CYGDBG_INFRA_DEBUG_TRACE_BUFFER_WRAP

Type

Radio

Description

When the trace buffer has filled with records it starts again at the beginning. Hence only the last CYGDBG_INFRA_DEBUG_TRACE_BUFFER_SIZE messages will be recorded.

Option: Halt trace buffer when full

Macro name

CYGDBG_INFRA_DEBUG_TRACE_BUFFER_HALT

Type

Radio

Description

When the trace buffer has filled with records it stops recording. Hence only the first CYGDBG_INFRA_DEBUG_TRACE_BUFFER_SIZE messages will be recorded.

Option: Print trace buffer when full

Macro name

CYGDBG_INFRA_DEBUG_TRACE_BUFFER_PRINT

Type

Radio

Description

When the trace buffer has filled with records it prints the contents of the buffer. The buffer is then emptied and the system continues.

Option: Print trace buffer on assert fail

Macro name

CYGDBG_INFRA_DEBUG_TRACE_BUFFER_PRINT_ON_ASSERT

Type

Boolean

Description

When an assertion fails the trace buffer will be printed to the default diagnostic device.

Option: Use function names

Macro name

CYGDBG_INFRA_DEBUG_FUNCTION_PSEUDOMACRO

Type

Boolean

Description

All trace and assert calls within eCos contain a reference to the builtin macro "__PRETTY_FUNCTION__", which evaluates to a string containing the name of the current function. This is useful when reading a trace log. It is possible to suppress the use of the function name by disabling this option. This results in smaller code size, but there is less human-readable information available in the trace output, possibly only filenames and line numbers.