Chapter 223. Configuration

223.1. CYGBLD_SYSTEMVIEW_ENABLED

These are the main developer configurable options for controlling CYGPKG_SYSTEMVIEW operation when CYGBLD_SYSTEMVIEW_ENABLED is enabled.

CYGBLD_SYSTEMVIEW_KERNEL_INSTRUMENT

This option allows the Kernel instrumentation to be replaced by SystemView event record generation, without having to explicitly add SystemView support to the existing eCos sources. A wrapper function is used to replace the low-level instrumentation call used by packages configured for Kernel instrumentation.

[Note]Note

The Kernel option CYGPKG_KERNEL_INSTRUMENT_BUFFER should be disabled when using CYGPKG_SYSTEMVIEW to capture Kernel instrumentation.

It is also recommended to disable the CYGDBG_KERNEL_INSTRUMENT_FLAGS feature, so that instrumentation events are generated unconditionally.

CYGFUN_SYSTEMVIEW_START_ON_INIT
If enabled then SystemView tracing is started automatically during application initialisation, so that application initialisation and startup events are captured. When this option is enabled and H/W debugging is being used, it is normally useful to have your debug session stop at the entry to the SEGGER_SYSVIEW_Start() function so that a host SystemView session can be synchronised to capture all events.
CYGFUN_SYSTEMVIEW_STOP_ON_EXIT
If enabled this option provides a CYG_SYSTRACE macro that is used by the cyg_test_exit() function to stop the SystemView event tracing. Since the normal test application exit implementation does not disable interrupts, it avoids continuing to record events when the main application thread has terminated.
CYGNUM_SYSTEMVIEW_RTT_BUFFER_SIZE
This specifies the size in bytes of the SystemView Target->Host buffer. NOTE: Depending on the target CPU frequency, and the enabled trace events a large buffer may be required to avoid capture overflow. The performance of the SystemView tracing to avoid overrun also depends on the other RTT loads on the system (e.g. diagnostics Terminal channel). Some tuning may be required in both the events captured and the RTT buffer sizes to ensure all events are captured in real-time.
CYGIMP_SYSTEMVIEW_USE_STATIC_BUFFER

If enabled then a statically allocated buffer for the configured maximum packlet size is used. If disabled then a stack buffer is used, with a lock used to serialise packet writing.

[Warning]Warning

It is important to ensure that the stack allocations of all threads are sufficient for the extra load of the RTT operations for recording events, and also for the transmission code if a “Recorder” is being used.

CYGNUM_SYSTEMVIEW_MAX_STRING_LEN
This option defines the maximum string length that can be passed to the SEGGER_SYSVIEW print and description routines. It also defines the maximum packet size, so will affect stack requirements if CYGIMP_SYSTEMVIEW_USE_STATIC_BUFFER is not enabled.
CYGIMP_SYSTEMVIEW_TRACE_ISR
When enabled this option controls generation of SystemView trace instrumentation for ISR entry/exit events. This is distinct from the extra information recorded when the Kernel instrumentation INTR events are being generated.
CYGIMP_SYSTEMVIEW_TRACE_TIMERS
When enabled this option controls generation of SystemView trace instrumentation for timer callback function events. This is distinct from the extra information recorded when the Kernel intsrumentation CLOCK and ALARM events are being generated.
CYGIMP_SYSTEMVIEW_TRACE_HEAP
When enabled this option controls generation of SystemView trace instrumentation for memory allocation events from the CYGPKG_MEMALLOC package.
CYGDAT_SYSTEMVIEW_APP_NAME
This is the string used for the Name property recorded for a SystemView trace. It can be used to identify specific applications when working with multiple “SystemView Data” captures.
CYGDAT_SYSTEMVIEW_CORE_NAME
This is the string used for the Core identificaion property recorded for a SystemView trace. It can identify the hardware architecture used for a capture. Normally this option will have a default value set by the platform architecture support.
CYGDAT_SYSTEMVIEW_DEVICE_NAME
This is the string used for the Device identificaion property recorded for a SystemView trace. It can identify the hardware device used for a capture. If this option is disabled then the HAL_PLATFORM_BOARD manifest is used.

223.2. CYGOPT_SYSTEMVIEW_RECORDER_HAL

The following options are specific to configurations where the simple, platform supplied, I/O channel support is used for direct communication with the SystemView application UART Recorder support. The eCos HAL Recorder implementation allows for Kernel instrumentation (and Infra tracing) to be generated without the Recorder itself increasing the instrumentation load.

CYGNUM_SYSTEMVIEW_RECORDER_HAL_UART_BAUD
This option defines the communication rate for the platform supplied low-level communication channel. The value configured here should match the value set for the host SystemView application Target->Recorder Configuration->UART selection.
CYGNUM_SYSTEMVIEW_RECORDER_HAL_TXBUF

This option defines the size of the temporary holding buffer used when transmitting data from the RTT buffer to the remote host SystemView application. This option is a compromise between the data footprint and the amount of data written by SystemView Record events.

This holding buffer can be smaller than the SystemView RTT buffer, and never needs to be larger. The buffer minimises the number of SEGGER_RTT_ReadUpBufferNoLock() calls and provides for a tighter TX loop transmitting bytes to the host SystemView application, which may be important since for the HAL Recorder world the performance/latency of the event transmission will affect the application performance and the timing of the system.

Also, due to the ordering of the initialisation code it is possible for a number of Kernel instrumentation events to be generated (and recorded in the SystemView RTT buffer) prior to the HAL communication channel being initialised and pending RTT data forwarded to the host SystemView application.

CYGOPT_SYSTEMVIEW_RECORDER_HAL_WAIT
When enabled this option will block the system in the HAL Recorder callback until an active SystemView connection is started. This can be used to ensure no event overflow occurs, allowing for a complete application startup to be instrumented. This option should only be enabled when explicitly required by the developer, since the target will be unresponsive until a SystemView connection is established.

223.3. CYGOPT_SYSTEMVIEW_RECORDER

As an alternative to the H/W debugger J-Link RTT direct-memory-access method of obtaining continuous events, the remote SystemView application can utilise a network connection or a UART connection to communicate with a target application supplied continuous recorder instance. This option, when enabled, provides the run-time support for such recorders. This uses a helper thread to periodically poll the SystemView buffer and forward data using the appropriate eCos I/O world.

[Note]Note

Unlike the alternative CYGOPT_SYSTEMVIEW_RECORDER_HAL approach, this Recorder does not rely on target platform specific support, but purely on normal eCos support. However, since the standard eCos thread and device driver interfaces are used, it means that if Kernel instrumentation is enabled then the Recorder helper threads and drivers will record events as well as the application threads/drivers being analysed.

This means that this helper thread Recorder approach is not recommended for Kernel instrumented configuration.

The following options are common to the Recorder support, irrespective of the configured transport options.

CYGNUM_SYSTEMVIEW_RECORDER_PRI

The Recorder thread priority is normally low to minimise the instrusiveness of the SystemView support (defaults to 1 higher than “idle”). The priority can be raised if overflows are detected due to the thread not being scheduled often enough, though the first approach (if possible) may just be to increase the SystemView buffer size (CYGNUM_SYSTEMVIEW_RTT_BUFFER_SIZE).

[Note]Note

It should be noted that since the recorder is a normal eCos thread, the operation of the recorder thread will cause SystemView thread events to be generated, and other events depending on the configuration options selected.

CYGNUM_SYSTEMVIEW_RECORDER_TX_IDLE
This option specifies the delay in milliseconds between checks for pending data from the remote SystemView application when the TX side is idle. When TX data is available the channel is also checked for pending RX.
CYGNUM_SYSTEMVIEW_RECORDER_TX_POLL

This option specifies the number of milliseconds the Recorder thread will sleep between polled checks for pending data for the remote SystemView application. The actual delay depends on the period of the scheduler tick, which is defined by the target configuration, but is normally ~10ms. So the delay implemented by this option will be rounded to the next higher scheduler tick boundary.

This setting in conjunction with the Recorder thread priority, the idle delay, the size of the RTT buffer and the corresponding TX threshold, can be tuned to avoid loss of instrumentation (RTT overflow) and the timeliness of TX to the SystemView application when matching the bandwidth of the Recorder channel with the frequency of SystemView events being recorded.

CYGNUM_SYSTEMVIEW_RECORDER_TX_WATERMARK
This option sets the threshold for the SystemView RTT buffer fill used to trigger a transmission to the application over the communication channel. This option can be tuned to affect the frequency of the Recorder write operations used to flush the RTT event buffer.

As well as the common Recorder options above, the configured transport channels may provide further options for the helper thread based Recorder configuration.

223.3.1. CYGBLD_SYSTEMVIEW_RECORDER_UART

This option enables the UART based continuous recording support to be available to the CYGOPT_SYSTEMVIEW_RECORDER world.

[Note]Note

This serial support is distinct from, and mutually exclusive to, the separate direct-UART access support provided when using the CYGOPT_SYSTEMVIEW_RECORDER_HAL feature.

This presents a serial I/O connection that can be accessed by the remote SystemView application to obtain event records. If the relevant packages are configured this can be a U(S)ART connection or a CDC-ACM (USB) connection. The SystemView event delivery is via the threaded CYGOPT_SYSTEMVIEW_RECORDER support.

CYGDAT_SYSTEMVIEW_RECORDER_UART_DEVICE
This option specifies the name of the serial peripheral device to use for the SystemView UART Recorder channel. This needs to be configured appropriately for the target, to an available device that will not be used by the normal application code. The serial channel is dedicated to SystemView event transport.
CYGNUM_SYSTEMVIEW_RECORDER_UART_BAUD
This option specifies the communication rate to be used for the Recorder serial channel. It should match the setting configured for the host SystemView application UART Recorder.