Chapter 227. Configuration
Table of Contents
227.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 The Kernel option
CYGPKG_KERNEL_INSTRUMENT_BUFFER
should be disabled when usingCYGPKG_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 thecyg_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 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
andALARM
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 theHAL_PLATFORM_BOARD
manifest is used.
227.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.
227.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 | |
---|---|
Unlike the alternative
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 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.
227.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 | |
---|---|
This serial support is distinct from, and mutually exclusive to, the
separate direct-UART access support provided when using the
|
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.
2024-12-10 | eCosPro Non-Commercial Public License |