eCosTM Reference Manual
Prev | Chapter 16. Package: Infrastructure | Next

# 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.

Prev | Home | Next
Package: Infrastructure | Up | Component: Startup options