Zephyr module to integrate with Modality's trace-based testing and analysis tools.
NOTE: Upstream support for external tracing modules has not yet landed; see the Zephyr PR. In the meantime, use Auxon's fork of Zephyr.
For detailed steps, see How to Instrument Your Zephyr System.
-
Install Modality. The examples below assume that you extracted the Modality tarball package to
/usr/local/modality
. -
Add the module in this repo to the
ZEPHYR_EXTRA_MODULES
CMake list.list(APPEND ZEPHYR_EXTRA_MODULES /path/to/modality-zephyr)
-
Tell CMake where to find Modality and what target triple you're building for. This step is only necessary when using the Modality tarball package. If you're using the Debian package, Modality will be found automatically and when possible, your target triple will be inferred.
set( MODALITY_PROBE_ROOT "/usr/local/modality" CACHE PATH "Modality tarball package installation directory") set( MODALITY_PROBE_TARGET_TRIPLE "thumbv7m-none-eabi" CACHE STRING "Target triple") list(APPEND CMAKE_MODULE_PATH "${MODALITY_PROBE_ROOT}/cmake")
-
Enable and configure tracing either in the Zephyr
menuconfig
or in aprj.conf
file- Select "External tracing support" in Zephyr → Sub Systems and OS Services → Tracing Support → Tracing Format
- Select "Modality probe tracing support" in Zephyr → Modules → ExternalTracing → Modality Probe Tracing
- Further configuration of the Modality integration can be done under Modality Probe Tracing once it's enabled.
-
Modality groups your system into one or more components. Run the update-manifest.py script for each component. You'll need to re-run this script whenever you add a new thread to your Zephyr system. This script accepts the following options:
--component
- Required. Path to the directory containing source files for this component.--component-name
- Optional. Name of component to be created. Defaults tomodality-component
.--thread-names
- Required. List of thread names to add as probes. You must provide the names of all threads in this component.
./tools/update-manifest.py \ --component modality-component \ --thread-names "consumer_thread" "producer_thread"
-
Create a
Modality.toml
configuration file.- The default
collector_connections
address in Zephyr isudp://192.0.2.2:2718
; you can change this viamenuconfig
: Zephyr → Modules → ExternalTracing → Modality Probe Tracing → IO Transport Configuration; modify "Collector IP address" and "Collector UDP port number." - The
control_connections
IP address is Zephyr's IPv4 address, which defaults to192.0.2.1
. - You can change Zephyr's IPv4 address via
menuconfig
: Zephyr → Sub Systems and OS Services → Networking → Link layer and IP networking support → Network Libraries → Set network settings for applications; modify "My IPv4 address" - The default
control_connections
UDP port in Zephyr is34355
; you can change this viamenuconfig
: Zephyr → Modules → ExternalTracing → Modality Probe Tracing → IO Transport Configuration; modify "Control plane UDP port number."
# Modality.toml modalityd = "http://localhost:14181/v1/" collector_connections = [ "udp://192.0.2.2:2718" ] control_connections = [ "udp://192.0.2.1:34355" ]
- The default
-
Create a
SUT.toml
definition file, then callmodality sut create <directory containing SUT.toml>
to create it.# SUT.toml name = "example" tags = ["Zephyr"] component_paths = [ "./modality-component", ]
$ modality sut create . $ modality sut list NAME COMPONENTS SESSIONS example 1 0
-
Get Zephyr networking tools and run the setup script in a separate terminal to proxy networking from qemu.
./net-setup.sh
-
Fetch the Zephyr workspace resources.
cd example-workspace/ west init -l modality-example west update source zephyr/zephyr-env.sh
-
Build the modality-zephyr example.
cd modality-example/ west build -b qemu_cortex_m3
-
Create the example SUT and open a session
./sut-up.sh
-
Run the example
west build -t run
trace: Initializing tracing *** Booting Zephyr OS build zephyr-v2.6.0-1-ge6858b1f2010 *** trace: Registering probe ID 63422 for thread 'consumer_thread' trace: Registering probe ID 45765 for thread 'producer_thread' Modality Zephyr Example Producer started trace: Allocated control plane message queue for thread 'producer_thread' Producing 0 Consumer started Consuming 0 trace: Tracing IO thread started Producing 1 Consuming 1 Main loop Producing 2 Consuming 2 Producing 3 Consuming 3 Main loop Producing 4 Consuming 4 Producing 5 Consuming 5 Main loop Producing 6 Consuming 6 trace: Sent control message to thread 'producer_thread' trace: Thread producer_thread processed a control message Producing 7 Consuming 7
-
View the trace log
$ modality log ║ * ║ (45765:1:0:1, THREAD_CREATE @ PRODUCER_THREAD, payload=-1) ║ ║ ║ ║ ║ * (63422:1:0:1, THREAD_CREATE @ CONSUMER_THREAD, payload=-1) ║ ║ ║ ║ * ║ (45765:1:0:2, THREAD_SWITCHED_IN @ PRODUCER_THREAD, payload=-1) ║ ║ ║ ║ * ║ (45765:1:0:3, PRODUCING @ PRODUCER_THREAD, payload=0) ║ ║ ║ ║ * ║ (45765:1:0:4, THREAD_SLEEP @ PRODUCER_THREAD, payload=50) ║ ║ ║ ║ * ║ (45765:1:0:5, THREAD_SWITCHED_OUT @ PRODUCER_THREAD) ║ ║ ║ ║ ╚═»╗ PRODUCER_THREAD interacted with CONSUMER_THREAD ║ ║ ║ ║ ║ * (63422:2:0:3, THREAD_SWITCHED_IN @ CONSUMER_THREAD, payload=-1) ║ ║ ║ ║ ║ * (63422:2:0:4, RX_MSG @ CONSUMER_THREAD, outcome=PASS) ║ ║ ║ ║ ║ * (63422:2:0:5, THREAD_SWITCHED_OUT @ CONSUMER_THREAD) ║ ║ ║ ║ ╔«═╝ CONSUMER_THREAD interacted with PRODUCER_THREAD ║ ║ ║ ║ * ║ (45765:3:1:3, THREAD_SWITCHED_IN @ PRODUCER_THREAD, payload=-1) ║ ║ ║ ╚═»╗ ║ modalityd interacted with PRODUCER_THREAD ║ ║ ║ ║ * ║ (45765:4:1:5, PRODUCING @ PRODUCER_THREAD, payload=1) ║ ║ ║ ║ * ║ (45765:4:1:6, THREAD_SLEEP @ PRODUCER_THREAD, payload=50) ║ ║ ║ ║ * ║ (45765:4:1:7, THREAD_SWITCHED_OUT @ PRODUCER_THREAD) . . . . . . . . .
Run the tools/update-manifest.py script to add the Zephyr tracing event and thread probe definitions to an existing Modality component. Probe IDs are generated from a hash of their associated thread name.
You may run update-manifest.py to create a new Modality component.
NOTE: After adding or removing a thread from your Zephyr system, you must run update-manifest.py for the relevant component.
./tools/update-manifest.py \
--component modality-component \
--thread-names "consumer_thread" "producer_thread"
See LICENSE for more details.
Copyright 2020 Auxon Corporation
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.