You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: scripts/README.md
+92-32Lines changed: 92 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,102 +6,162 @@ This folder contains a lot of useful scripts that can speed up development for r
6
6
7
7
SOF has several build targets depending on whether you are building firmware, tooling, documentation or topologies. This directory has a helper for each.
8
8
9
-
### Firmware
9
+
### Firmware Build (`xtensa-build-zephyr.py`)
10
10
11
-
Firmware can either be built using west command directly or by the xtensa-build-zephyr.py script. This script wraps up the west commands and can build using either the Zephyr SDK compiler or the Cadence xtensa compiler for xtensa targets.
11
+
Firmware can either be built using west commands directly or by the `xtensa-build-zephyr.py` script. This script wraps up the west commands and can build using either the Zephyr SDK compiler or the Cadence xtensa compiler for xtensa targets.
12
12
13
-
Please run the script with --help to see all options.
13
+
Please run the script with `--help` to see all options.
14
14
15
15
E.g to build SOF for Intel Pantherlake:
16
16
17
-
1) Enable the python virtual environment for west. This should be in your SOF workspace installation direction. Default is ```~/work/sof``` (only needs run once).
17
+
1) Enable the python virtual environment for west. This should be in your SOF workspace installation directory. Default is `~/work/sof` (only needs run once).
18
+
18
19
```bash
19
20
source~/work/sof/.venv/bin/activate
20
21
```
21
-
2) Now run the build script. *Note: most build errors are a result of ingredients being out of sync with the west manifest. Please run ```west update``` and rebuild before fixing/reporting build errors.*
22
+
23
+
2) Now run the build script. *Note: most build errors are a result of ingredients being out of sync with the west manifest. Please run `west update` and rebuild before fixing/reporting build errors.*
Testbench is a host application that is used to run SOF processing modules on developers PC. This allows for module development using regular host based tooling.
31
+
This script can be used to locally reproduce the exact build steps and environment of specific CI validation tests.
29
32
30
-
Please run
31
33
```bash
32
-
./rebuild-testbench.sh --help
34
+
./scripts/test-repro-build.sh --help
33
35
```
34
-
for full options.
35
-
36
-
Testbench can be also be built for Cadence simulator targets.
37
36
38
-
###Tools and Topologies
37
+
## Tools and Topologies
39
38
40
39
Tooling and topology can be built together using one script. To build all topologies please run:
41
40
42
41
```bash
43
42
./scripts/build-tools.sh
44
43
```
45
44
46
-
This script can build:
47
-
1) sof-ctl
48
-
2) sof-logger
49
-
3) probes
50
-
4) all topology 1 & 2 and test topologies.
51
-
5) Local ALSA git version for alsa-lib and alsa-utils that have features not yet in distro version of ALSA packages.
45
+
**Options for `build-tools.sh`:**
46
+
47
+
*`-c` : Rebuild `ctl/` tool
48
+
*`-l` : Rebuild `logger/` tool
49
+
*`-p` : Rebuild `probes/` tool
50
+
*`-T` : Rebuild ALL `topology/` targets
51
+
*`-X` : Rebuild topology1 only
52
+
*`-Y` : Rebuild topology2 only
53
+
*`-t` : Rebuild test topologies
54
+
*`-A` : Clone and rebuild the local ALSA git version for `alsa-lib` and `alsa-utils` with latest non-distro features.
55
+
*`-C` : No build, only CMake re-configuration. Shows CMake targets.
56
+
57
+
*Warning: building tools is incremental by default. To build from scratch delete the `tools/build_tools` directory or use `-C`.*
58
+
59
+
### ALSA Specific Build (`build-alsa-tools.sh`)
60
+
61
+
If you want to pull down and explicitly recompile only the associated ALSA libraries from their public `alsa-lib` GitHub upstream independently of SOF topologies:
62
+
63
+
```bash
64
+
./scripts/build-alsa-tools.sh
65
+
```
66
+
67
+
## Testbench and Emulation
68
+
69
+
Testbench is a host application that is used to run SOF processing modules on developers PC. This allows for module development using regular host based tooling.
70
+
71
+
### Rebuilding the Testbench (`rebuild-testbench.sh`)
72
+
73
+
This script cleans and rebuilds the host test application binary. Ensure you supply the correct target platform wrapper or fuzzing backend.
74
+
75
+
**Usage Options:**
76
+
77
+
*`-p <platform>` : Build testbench binary for `xt-run` for selected platform (e.g. `-p tgl`). When omitted, performs a `BUILD_TYPE=native`, compile-only check.
78
+
*`-f` : Build testbench via a compiler provided by a fuzzer (default path: `.../AFL/afl-gcc`).
79
+
*`-j` : Number of parallel make jobs (defaults to `nproc`).
80
+
81
+
### Running the Testbench (`host-testbench.sh`)
82
+
83
+
Starts the testing sequences. This invokes specific components to ensure basic inputs process without segfaults.
84
+
85
+
```bash
86
+
./scripts/host-testbench.sh
87
+
```
88
+
89
+
### QEMU Check (`qemu-check.sh`)
90
+
91
+
Automated verifier for executing firmware builds under QEMU emulation.
* Runs all supported platforms by default if none are provided.
52
101
53
102
## SDK Support
54
103
55
104
There is some SDK support in this directory for speeding up or simplifying tasks with multiple steps.
56
105
57
-
### New Modules
106
+
### New Modules (`sdk-create-module.py`)
107
+
108
+
A new module can be created by running the SDK Create Module script. This python helper copies the SOF template audio module and renames all strings, Cmakefiles, and Kconfigs automatically. It also correctly registers a new DSP UUID and TOML entries.
58
109
59
-
A new module can be created by running the sdk-create-module script. This script will copy the template module and rename all strings, Cmakefiles, Kconfigs to match the new module. It will also create a UUID for the new module and a TOML manifest entry (for targets that need this).
110
+
Please run:
60
111
61
-
Please run
62
112
```bash
63
-
./sdk-create-module.py new_module_name
113
+
./scripts/sdk-create-module.py new_module_name
64
114
```
65
115
66
116
## Docker
67
117
68
-
The docker container provided in docker_build sets up a build environment for
69
-
building Sound Open Firmware. A working docker installation is needed to run
70
-
the docker build container.
118
+
The docker container provided in `docker_build` sets up a build environment for building Sound Open Firmware. A working docker installation is needed to run the docker build container.
119
+
120
+
*Note: In order to run docker as non sudo/root user please run:*
71
121
72
-
Note: In order to run docker as non sudo/root user please run.
73
122
```bash
74
123
sudo usermod -aG docker your-user-name
75
124
```
125
+
76
126
Then logout and login again.
77
127
78
-
Quick Start:
128
+
**Quick Start:**
129
+
130
+
First, build the docker container. This step needs to be done initially and when the toolchain or ALSA dependencies are updated.
79
131
80
-
First, build the docker container. This step needs to be done initially and
81
-
when the toolchain or alsa dependencies are updated.
82
132
```bash
83
133
cd scripts/docker_build
84
134
./docker-build.sh
85
135
```
136
+
86
137
After the container is built, it can be used to run the scripts.
The `debug_stream` framework is an abstract logging and live-data streaming mechanism allowing the DSP to asynchronously push structured or freeform diagnostic records immediately out to the host.
4
+
5
+
## Feature Overview
6
+
7
+
Unlike standard tracing (`mtrace`), which requires buffering and complex host parsing logic often tied directly to pipeline topologies or ALSA interfaces, the `debug_stream` bypasses the audio framework entirely. It utilizes the dedicated IPC Memory Windows (specifically the debug slot) to write data.
8
+
9
+
The stream is particularly useful for reporting:
10
+
11
+
1.**Thread Information:** Real-time data from Zephyr OS threads (like CPU runtime, context switch frequencies, or stack high-water marks).
12
+
2.**Text Messages (`ds_msg`):** Lightweight string prints that bypass the standard heavily-formatted logger.
13
+
14
+
## How to Enable
15
+
16
+
These features are disabled by default to save firmware footprint. You can enable them via Kconfig:
17
+
18
+
*`CONFIG_SOF_DEBUG_STREAM_SLOT=y` : Master switch. Reserves exactly one Memory Window 4k block (default Slot 3) mapping to host space.
*`CONFIG_SOF_DEBUG_STREAM_TEXT_MSG=y` : Allows calling `ds_msg("...", ...)` scattered throughout DSP C code to emit plain strings.
21
+
22
+
## Architecture
23
+
24
+
The architecture revolves around a "Slot" abstraction where data is copied sequentially over a ringbuffer into the ADSP debug window slot used for the debug stream (mapped over PCIe/SPI for the Host to read non-destructively).
25
+
26
+
```mermaid
27
+
graph TD
28
+
subgraph SOF Firmware
29
+
SysEvent["System Event / OS Timer"] --> |Triggers| DSThread["Thread Info Collector"]
The Sound Open Firmware (SOF) project carries a GNU Debugger (GDB) stub directly integrated with the framework's exception handlers. This translates commands sent by a GDB client (running on the host Linux machine) into architecture-specific logic.
4
+
5
+
## Feature Overview
6
+
7
+
Instead of completely relying on complex JTAG setups, developers can use this stub to dynamically introspect panic states, stack traces, and variable states during firmware execution, particularly inside isolated SoC DSP cores.
8
+
9
+
When the firmware faults or hits a defined breakpoint, the exception vector routes control into this stub. It then waits for GDB Remote Protocol packet streams (ASCII formatted over the SOF mailbox/shared memory window). The Host reads these mailbox slots and pushes/pulls responses to its active GNU Debugger session.
10
+
11
+
## Architecture
12
+
13
+
Data moves between the Host GDB environment, the physical mailboxes bounding the DSP domain, the DSP firmware's built-in stub, and the active exception state.
14
+
15
+
```mermaid
16
+
sequenceDiagram
17
+
participant GdbSession as Host GDB Client
18
+
participant IPC as SOF Driver / ALSA
19
+
participant Stub as Firmware GDB Stub (gdb_parser)
20
+
participant HW as DSP Context Registers
21
+
22
+
HW-->>Stub: Hard Fault / Breakpoint Hit
23
+
activate Stub
24
+
25
+
Note over Stub: Stores fault context (sregs/aregs)
GdbSession->>IPC: Send Packet (e.g., $g#67 to Read Regs)
30
+
IPC->>Stub: Passes 'g' string
31
+
32
+
Stub->>HW: Reads requested register values
33
+
HW-->>Stub: Values
34
+
35
+
Stub->>Stub: mem_to_hex() formatting
36
+
Stub-->>GdbSession: Returns hex payload via Mailbox
37
+
38
+
GdbSession->>IPC: Send Packet ($c#63 to Continue)
39
+
IPC->>Stub: Process 'c'
40
+
Stub->>HW: Restores Context, Retains Execution
41
+
deactivate Stub
42
+
```
43
+
44
+
## How to Enable
45
+
46
+
A basic GDB debugging configuration is exposed via Kconfig and must be explicitly bound:
47
+
48
+
*`CONFIG_GDB_DEBUG`: Needs to be toggled `=y` to compile `src/debug/gdb/gdb.c` into the main application.
49
+
50
+
Additionally, the overarching architecture requires the corresponding Exception vectors to be rewritten. In Zephyr OS based builds (which currently drive native architectures), fatal exception handling must be configured to pass register dumps recursively to `gdb_handle_exception()`.
51
+
52
+
## Usage and Protocols
53
+
54
+
The protocol adheres precisely to the standard GDB remote serial specification. Each string packet expects the format:
55
+
56
+
`$<packet-data>#<check-sum>`
57
+
58
+
Supported Command Handlers inside the Stub:
59
+
60
+
*`g` (Read all registers) / `G` (Write all registers)
61
+
*`m` (Read memory) / `M` (Write memory)
62
+
*`p` (Read specific register) / `P` (Write specific register)
63
+
*`v` (Query architecture/support details like `vCont`)
The SOF Telemetry subsystem is a suite of built-in diagnostics measuring code execution efficiencies, cycle overheads, and hardware I/O throughput.
4
+
5
+
## Feature Overview
6
+
7
+
Latency and real-time execution bounds are critical in DSP firmware. The telemetry feature provides mechanisms to monitor these bounds accurately without intrusive breakpoints or slowing down the pipeline too aggressively.
8
+
9
+
Capabilities include:
10
+
11
+
1.**Component Performance Tracking**: For every instantiated component in the graph, it measures the pure execution time bounds (min/max/average) of that component's `comp_copy()` routines.
12
+
2.**I/O Throughput Tracking**: Measures hardware bus speeds or message handling by counting bytes, state changes, or tokens across distinct interfaces: IPC, DMIC, I2S, HD/A, I2C, SPI, etc.
Measurements are batched into a ringbuffer locally, then synced across mapped ADSP memory windows into user space, limiting the impact on the active instruction cache.
16
+
17
+
## Architecture
18
+
19
+
The architecture bridges the component layer (like pure IPC or Audio Component wrappers) directly into independent statistics accumulators.
Telemetry depends strictly on NOT being built inside a host-userspace environment simulator (`depends on !SOF_USERSPACE_LL`). Ensure your target is a physical or emulated DSP target.
39
+
40
+
Settings to configure in `Kconfig`:
41
+
42
+
*`CONFIG_SOF_TELEMETRY=y` : Enable the overarching telemetry interfaces, giving you systick and basic task metrics over Memory Window 2 interfaces.
43
+
*`CONFIG_SOF_TELEMETRY_PERFORMANCE_MEASUREMENTS=y` : Adds granular tracking to audio components (creating the explicit `telemetry.c` ringbuffer maps via Memory Window 3 slots). Be aware that only a specific configured amount (`PERFORMANCE_DATA_ENTRIES_COUNT`) can be actively tracked due to RAM constraints.
44
+
*`CONFIG_SOF_TELEMETRY_IO_PERFORMANCE_MEASUREMENTS=y` : Instructs hardware and communication buses to start pumping data into the metrics collector.
45
+
46
+
## Extracting Data
47
+
48
+
You can fetch these metrics via `sof-logger` or standard IPC interrogation tools that support polling the corresponding debug window slots mapped for your particular platform's `ADSP_MW`.
0 commit comments