diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 00000000..bd028faa --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,94 @@ +--- +name: Build and Deploy SOF Documentation + +on: + push: + branches: + - master + - main + tags: + - 'v*' + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + name: Build Documentation + runs-on: ubuntu-latest + + steps: + - name: Checkout Documentation Source + uses: actions/checkout@v4 + + - name: Set up Python 3.13 + uses: actions/setup-python@v5 + with: + python-version: '3.13' + + - name: Install Base System Dependencies + run: | + sudo apt-get update + sudo apt-get install -y doxygen graphviz ninja-build cmake default-jre + + - name: Install Python Documentation Dependencies + run: | + pip install -r scripts/requirements.txt -c scripts/constraints.txt + pip install pyyaml + + - name: Optional API Docs (Clone SOF & Doxygen) + continue-on-error: true + run: | + git clone --depth 1 https://github.com/thesofproject/sof.git _deps/sof + if ! grep -q "zephyr/include" _deps/sof/doc/sof.doxygen.in; then + echo "INPUT += @top_srcdir@/zephyr/include" >> _deps/sof/doc/sof.doxygen.in + fi + cmake -GNinja -S _deps/sof/doc -B _build_doxy + ninja -C _build_doxy doc + + - name: Generate Dynamic Platform & Algorithm Matrices + run: | + python3 scripts/generate_matrices.py + + - name: Build Sphinx Documentation + run: | + if [ -d "_build_doxy" ]; then + make html VERBOSE=1 SOF_DOC_BUILD=_build_doxy + else + make html VERBOSE=1 + fi + + - name: Prepare Publish Directory Structure + run: | + mkdir -p _site/latest + cp -r _build/html/* _site/latest/ + # Landing redirect to /latest/ + echo '' > _site/index.html + echo 'Redirecting to latest SOF documentation...' >> _site/index.html + touch _site/.nojekyll + + - name: Upload Pages Artifact + if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') + uses: actions/upload-pages-artifact@v3 + with: + path: _site + + deploy: + name: Deploy to GitHub Pages + needs: build + if: github.ref == 'refs/heads/master' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 6087d756..1131141f 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -64,7 +64,7 @@ jobs: - name: configure and build SOF API docs (Doxygen) run: | - git clone https://github.com/thesofproject/sof + git clone --depth 1 https://github.com/thesofproject/sof if ! grep -q "zephyr/include" sof/doc/sof.doxygen.in; then echo "INPUT += @top_srcdir@/zephyr/include" \ >> sof/doc/sof.doxygen.in @@ -156,7 +156,7 @@ jobs: - name: configure and build SOF API docs (Doxygen) run: | - git clone https://github.com/thesofproject/sof + git clone --depth 1 https://github.com/thesofproject/sof if ! grep -q "zephyr/include" sof/doc/sof.doxygen.in; then echo "INPUT += @top_srcdir@/zephyr/include" \ >> sof/doc/sof.doxygen.in diff --git a/.github/workflows/woke_pr.yml b/.github/workflows/woke_pr.yml index 88291b00..f452df02 100755 --- a/.github/workflows/woke_pr.yml +++ b/.github/workflows/woke_pr.yml @@ -16,6 +16,11 @@ on: branches: - master +permissions: + contents: read + pull-requests: write + checks: write + jobs: woke_pr: name: woke check for patch @@ -27,7 +32,7 @@ jobs: github-token: ${{ secrets.GITHUB_TOKEN }} # Change reviewdog reporter if you need # [github-pr-check,github-check,github-pr-review]. - reporter: github-pr-review + reporter: github-pr-check # Change reporter level if you need. # GitHub Status Check won't become failure with warning. level: warning diff --git a/.gitignore b/.gitignore index 35ffcd58..86e853ba 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ _build *.warnings .tox MANIFEST +_generated_*.rst diff --git a/.wokeignore b/.wokeignore index 2f1f79d6..44bd49d3 100644 --- a/.wokeignore +++ b/.wokeignore @@ -1,6 +1,7 @@ # The following files can be ignored when running Woke. rules-woke.yaml +.wokeignore conf.py *.pu tox.ini @@ -12,7 +13,13 @@ release.rst introduction/index.rst maintainers/merge_rights.rst contribute/process/bug-tracking.rst +contribute/process/images/* getting_started/setup/setup_up_2_board.rst +developer_guides/setup_special_device/setup_up_2_board.rst +developer_guides/virtualization/virtualization.rst +developer_guides/firmware/component-tutorial/tut-ii-topology.rst +developer_guides/subsystem_architecture/host/linux_driver/architecture/sof_driver_arch.rst +developer_guides/tech/compile_wsl.rst developer_guides/virtualization/files/q-v6.sh developer_guides/topology/topology.rst developer_guides/fuzzing/testbench_afl_fuzzing.rst diff --git a/Makefile b/Makefile index 64785f0d..d8381b1e 100644 --- a/Makefile +++ b/Makefile @@ -51,7 +51,12 @@ else # by disabling UML diagrams in the conf.py file. endif -html: apidocs +PYTHON ?= python3 + +generate_data: + $(PYTHON) scripts/generate_matrices.py + +html: generate_data apidocs $(SPHINXBUILD) -j auto -t $(DOC_TAG) -b html \ -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) \ -D breathe_projects.'SOF Project'="${SOF_DOC_BUILD}"/doxygen/xml \ diff --git a/algos/index.rst b/algos/index.rst index 6cd9fb9c..db12fed6 100644 --- a/algos/index.rst +++ b/algos/index.rst @@ -10,34 +10,8 @@ SOF contains several permissively-licensed and royalty-free audio processing algorithms that can be used alongside proprietary processing components to build pipelines. -.. csv-table:: Supplied Audio Processing Algorithms - :header: "Processing", "Description", "Generic C", "SIMD Support", "Status", "Milestone" - :widths: 10, 30, 10, 10, 10, 10 +.. include:: _generated_modules_table.rst - "Acoustical Echo Cancellation (mockup)", "Attenuates speaker originated acoustical coupling in microphone capture signal", "Yes", "N/A", "Planned", "1.6" - "Asynchronous sample rate conversion", "Converts between common sample rates and connects pipelines with different clock domains", "Yes", "Xtensa HiFi3", "Upstream", "1.5" - "Channel selector", "Copies the selected channel from the source buffer to the sink buffer", "Yes", "N/A", "Upstream", "1.4" - "Crossover", "Splits up audio into at most four different bands for individual processing", "Yes", "(Possible via IIR)", "Upstream", "1.5" - "DCBlocker", "Simple highpass filter to remove DC components from audio", "Yes", "N/A", "Upstream", "1.4" - "Demultiplexer", "Copies PCM sample frames from one source buffer to multiple sink buffers with configurable channels", "Yes", "N/A", "Upstream", "1.4" - "Dynamic Range Processor", "Compresses and expands an audio signal to bring out quiet sounds and dampening loud sounds", "Yes", "Yes", "In Progress", "1.7 (expected)" - "FIR equalizer", "Enhances frequency response with a finite impulse response filter, e.g. improve speaker sound", "Yes", "Xtensa HiFi3", "Upstream", "1.4" - "IIR equalizer", "Enhances frequency response with an infinite impulse response filter, e.g. cancel DC component or improve speaker sound", "Yes", "Xtensa HiFi3", "Upstream", "1.4" - "Mixer", "Sums with unity gain and saturation source buffers of multiple pipelines to a single output sink buffer", "Yes", "No", "Upstream", "1.0" - "Multi-microphone beamformer", "Enhances directivity of microphone array towards steer direction and attenuates diffuse noise", "Yes", "Yes", "Upstream", "1.6" - "PCM converter", "Not a dedicated component but provides for DAI and host components conversion between PCM formats e.g. S16_LE, S24_LE, and S32_LE", "Yes", "Xtensa HiFi3", "Upstream", "1.5" - "Sample rate conversion", "Converts between common sample rates to connect multi-rate synchronous pipelines", "Yes", "Xtensa HiFi3", "Upstream", "1.3" - "Volume", "Provides real-time stream gain controls to the user", "Yes", "Xtensa HiFi3", "Upstream", "1.0" +.. note:: -Algorithm Specific Information -****************************** - -Further information on specific algorithms is forthcoming. - -.. toctree:: - :maxdepth: 1 - - demux/demux.rst - eq/equalizers_tuning - src/sample_rate_conversion - tdfb/time_domain_fixed_beamformer + For detailed algorithm implementation guides, filter tuning workflows, and design tools, consult the :ref:`algorithm-specific-information` section in Developer Guides. diff --git a/architectures/index.rst b/architectures/index.rst index a82a0be0..c95b2d3b 100644 --- a/architectures/index.rst +++ b/architectures/index.rst @@ -1,20 +1,620 @@ .. _architectures: -Architecture -####################### +Architecture & System Design +############################ -SOF is intended to run on many different hardware architectures and is therefore -not coupled to any particular DSP or host hardware architecture. The SOF -|TSC| ensures that any DSP or host architecture specific code is partitioned to -reside in architecture-specific directories with generic APIs to common code. +Sound Open Firmware (SOF) is built upon the **Zephyr RTOS** and is designed to run across diverse hardware architectures without being coupled to any specific DSP or host processor. SOF is designed to run on any architecture and SoC supported by Zephyr—spanning Tensilica Xtensa, ARM Cortex-M, and RISC-V targets. The architecture is strictly modular: silicon-specific and platform-specific implementations reside in partitioned directories and Zephyr device drivers, exposing generic, standardized APIs to the core framework. -This section outlines the architecture at a high level; however, the source code -should always be consulted for the low level details. +System & Software Architecture +****************************** -.. toctree:: - :maxdepth: 2 +The SOF software ecosystem supports two foundational deployment models tailored for different device form-factors: - host/index - firmware/index +1. **Host-Based Architecture**: Where the audio DSP is coupled to an application processor running a general-purpose operating system (**Linux**, **Android**, or **ChromeOS**). The host manages firmware lifecycle, parses topologies, and streams audio over DMA memory windows via inter-processor communication (IPC). +2. **Hostless (Standalone / Embedded) Architecture**: Where SOF firmware runs autonomously directly on a microcontroller or standalone DSP (such as the **ESP32-P4** or **Teensy 4.1 / i.MX RT1062**) atop Zephyr RTOS without requiring a host CPU or external operating system. +Host-Based System & Software Architecture +========================================= + +In host-based deployments (such as PCs, Chromebooks, smartphones, automotive infotainment, and servers), the audio stack is vertically integrated across the host OS, hardware interconnect, and DSP firmware: + +.. graphviz:: + :caption: SOF Host-Based End-to-End System & Software Stack Architecture + :align: center + + digraph system_stack { + rankdir=TB; + nodesep=0.32; + ranksep=0.36; + node [shape=box, style="filled,rounded", fontname="Verdana", fontsize=9, margin="0.12,0.06"]; + edge [fontname="Verdana", fontsize=8, color="#555555"]; + + // 1. HOST OS (TOP) + subgraph cluster_host { + label = "Host OS (Linux / Android / ChromeOS)"; + style = "filled,rounded"; + color = "#2b5b84"; + fillcolor = "#eef4f9"; + fontname = "Verdana-Bold"; + fontsize = 11; + fontcolor = "#1a364f"; + + subgraph cluster_user { + label = "User Space Applications & Audio Frameworks"; + style = "dashed,rounded"; + color = "#4b79a1"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + + apps [label="Audio Apps / Media Players\n(Chromium, WebRTC, Media Player)", fillcolor="#d4e6f1"]; + servers [label="Sound Servers & Audio Frameworks\n(PipeWire, PulseAudio, CRAS (ChromeOS), AudioFlinger (Android))", fillcolor="#d4e6f1"]; + alsalib [label="ALSA Libraries & Audio HAL\n(libasound, tinyalsa, alsa-ucm, sof-ctl)", fillcolor="#d4e6f1"]; + + apps -> servers -> alsalib [weight=10]; + } + + subgraph cluster_kernel { + label = "Linux Kernel Space (sound/soc/sof & ASoC Framework)"; + style = "dashed,rounded"; + color = "#4b79a1"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + + asoc [label="ALSA Core & ASoC Framework\n(PCM Streams, Controls, DAPM)", fillcolor="#d5f5e3"]; + + subgraph cluster_sof_core { + label = "sound/soc/sof Core Framework"; + style = "filled,rounded"; + color = "#27ae60"; + fillcolor = "#e8f8f5"; + fontname = "Verdana-Bold"; + fontsize = 8; + + sof_ipc [label="IPC Message Engine\n(IPC4 & IPC3 Protocol Engine)", fillcolor="#a3e4d7"]; + sof_tplg [label="Topology Parser\n(Topology v1 / v2 Engine)", fillcolor="#a3e4d7"]; + sof_pm [label="Power & Stream Manager\n(D0ix / D3 Suspend-Resume)", fillcolor="#a3e4d7"]; + + { rank=same; sof_ipc; sof_tplg; sof_pm; } + } + + buses [label="Hardware Platform & Bus Drivers\n(Intel PCI / SoundWire Manager / HDA, AMD ACP, NXP SAI, MediaTek)", fillcolor="#d5f5e3"]; + + alsalib -> asoc [weight=10]; + asoc -> sof_tplg [weight=10, style=dashed, label="parse .tplg"]; + asoc -> sof_ipc; + asoc -> sof_pm; + sof_ipc -> buses; + sof_tplg -> buses [weight=10, style=invis]; + sof_pm -> buses; + } + } + + // 2. HARDWARE INTERCONNECT (MIDDLE) + subgraph cluster_interconnect { + label = "Hardware Bus & Interconnect"; + style = "filled,rounded"; + color = "#e67e22"; + fillcolor = "#fef9e7"; + fontname = "Verdana-Bold"; + fontsize = 10; + fontcolor = "#7e5109"; + + hw_doorbell [label="Hardware Doorbells\n(Host & DSP IRQ Lines)", fillcolor="#fdebd0", shape=ellipse]; + hw_mailbox [label="Shared Mailbox SRAM\n(IPC Command & Reply Windows)", fillcolor="#fdebd0", shape=box3d]; + hw_dma [label="Host DMA Buffer Windows\n(PCM Audio Streaming Windows)", fillcolor="#fdebd0", shape=box3d]; + + { rank=same; hw_doorbell; hw_mailbox; hw_dma; } + } + + buses -> hw_doorbell [color="#e67e22", penwidth=1.5]; + buses -> hw_mailbox [color="#e67e22", penwidth=1.5, weight=10]; + buses -> hw_dma [color="#e67e22", penwidth=1.5]; + + // 3. AUDIO DSP FIRMWARE (BOTTOM) + subgraph cluster_dsp { + label = "Audio DSP Firmware (SOF on Zephyr RTOS)"; + style = "filled,rounded"; + color = "#7d3c98"; + fillcolor = "#f4ecf7"; + fontname = "Verdana-Bold"; + fontsize = 11; + fontcolor = "#4a235a"; + + dsp_ipc [label="DSP IPC Driver\n(Message Dispatcher & Handlers)", fillcolor="#d7bde2"]; + + subgraph cluster_dsp_services { + label = "DSP Core Infrastructure & Modules"; + style = "dashed,rounded"; + color = "#8e44ad"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + + mem [label="Heterogeneous Memory System\n(HP/LP SRAM, Dynamic IMR Paging)", fillcolor="#d2b4de"]; + llext [label="LLEXT Dynamic Module Loader\n(Zephyr Linkable Loadable Extension)", fillcolor="#d2b4de"]; + sched [label="Real-Time Pipeline Schedulers\n(LL Timer, EDF & Event Framework)", fillcolor="#d2b4de"]; + + { rank=same; mem; llext; sched; } + } + + subgraph cluster_pipelines { + label = "Audio Processing Graph (DAG)"; + style = "dashed,rounded"; + color = "#8e44ad"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + + components [label="Audio Modules & Components\n(Volume, Mixer, SRC, EQ, AEC, Beamformer, Codecs, Spatial)", fillcolor="#ebdef0"]; + buffers [label="Zero-Copy Cache-Aligned Buffers\n(HP/LP SRAM Ring Buffers)", fillcolor="#ebdef0"]; + + components -> buffers [dir=both]; + } + + subgraph cluster_dsp_bottom { + label = "Hardware Abstraction & RTOS Foundation"; + style = "dashed,rounded"; + color = "#8e44ad"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + + dai_drivers [label="Hardware Interface Drivers (DAI)\n(SoundWire Peripherals, I2S / SSP, DMIC / PDM, HD-Audio)", fillcolor="#bb8fce"]; + zephyr [label="Zephyr RTOS Kernel\n(Multi-Threading, SMP/AMP, Sync, Native Drivers)", fillcolor="#bb8fce"]; + + { rank=same; dai_drivers; zephyr; } + } + + dsp_ipc -> llext [color="#7d3c98", weight=10]; + dsp_ipc -> mem [color="#7d3c98"]; + dsp_ipc -> sched [color="#7d3c98"]; + sched -> components [color="#7d3c98", label="trigger"]; + llext -> components [color="#7d3c98", style=dotted, label="load", weight=10]; + mem -> buffers [color="#7d3c98", style=dotted]; + buffers -> dai_drivers [color="#7d3c98"]; + zephyr -> sched [dir=back, style=dashed, color="#8e44ad", label="OS threads"]; + } + + hw_doorbell -> dsp_ipc [color="#7d3c98", penwidth=1.5, constraint=false]; + hw_mailbox -> dsp_ipc [color="#7d3c98", penwidth=1.5, weight=10]; + hw_dma -> buffers [color="#7d3c98", penwidth=1.5]; + } + +Host Driver Stack (Linux ASoC) +============================== +The host-side driver is integrated directly upstream in the mainline Linux kernel under ``sound/soc/sof/``. Its primary responsibilities include: + +* **DSP Lifecycle Management**: Bringing the DSP out of reset, downloading signed firmware manifests, configuring boot addresses, and handling runtime power management (D0ix, D3 suspend/resume). +* **Topology Parsing**: Loading compiled binary topology containers (``.tplg``) and translating ALSA controls and widgets into runtime DSP pipeline instantiation commands. +* **IPC Transport**: Coordinating bidirectional communication with the DSP via hardware mailboxes, interrupt doorbells, and shared memory windows. +* **ALSA Device Exposure**: Exposing standard PCM playback/capture devices, mixer controls, and byte controls to user-space audio servers (PipeWire, PulseAudio, CRAS, AudioFlinger) and ALSA applications (via ``libasound`` and ``tinyalsa``). + +Hostless (Standalone) Embedded Architecture +=========================================== + +In hostless deployments (such as smart speakers, conference microphones, standalone audio bridges, hearing aids, IoT voice endpoints, and embedded test cards like the **ESP32-P4** and **Teensy 4.1 / i.MX RT1062**), SOF executes completely autonomously without requiring a host processor or general-purpose operating system: + +* **Autonomous Zephyr Application**: SOF operates as a self-contained Zephyr RTOS native application. It initializes on-chip peripherals, configures audio clocks, and begins pipeline processing immediately upon boot without waiting for host firmware downloads or handshakes. +* **Static Pre-Compiled Topologies**: Instead of relying on a host kernel driver to dynamically parse binary ``.tplg`` files at runtime, hostless systems utilize pre-compiled static topology graphs embedded directly in firmware flash ROM or compiled into static C data structures. +* **Direct Hardware Audio IO**: Audio data streams enter and exit directly through physical digital audio interfaces (I2S, TDM, SoundWire, or PDM microphone arrays), on-chip USB Audio Class (UAC2) endpoints, and Bluetooth audio controllers supporting modern wireless profiles (A2DP sink/source, HFP/mSBC voice call, LE Audio / LC3, and Auracast broadcast), eliminating the need for host DMA memory windows. +* **Deterministic Local Scheduling**: Periodic execution is autonomously driven by the Zephyr RTOS Low-Latency (LL) timer scheduler or Earliest Deadline First (EDF) event scheduler, delivering sub-millisecond audio processing with zero host scheduling jitter. +* **Local Controls & Embedded Telemetry**: Volume, mute, EQ profiles, and audio routing are controlled locally via GPIO buttons, rotary encoders, or local Zephyr application threads, with real-time diagnostic trace logging streamed over UART or USB CDC. + +.. graphviz:: + :caption: SOF Hostless Embedded System Architecture (ESP32-P4 / Teensy 4.1) + :align: center + + digraph hostless_stack { + rankdir=TB; + nodesep=0.32; + ranksep=0.36; + node [shape=box, style="filled,rounded", fontname="Verdana", fontsize=9, margin="0.12,0.06"]; + edge [fontname="Verdana", fontsize=8, color="#555555"]; + + // 1. LOCAL APPLICATION & CONTROL LAYER (TOP) + subgraph cluster_app { + label = "Local Application & Embedded Control"; + style = "filled,rounded"; + color = "#2b5b84"; + fillcolor = "#eef4f9"; + fontname = "Verdana-Bold"; + fontsize = 11; + fontcolor = "#1a364f"; + + subgraph cluster_app_inner { + label = "Embedded Application Logic & Controls"; + style = "dashed,rounded"; + color = "#4b79a1"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + + app_logic [label="Native Embedded Application\n(Zephyr Audio App / Main Loop)", fillcolor="#d4e6f1"]; + app_ctrl [label="Physical User Controls\n(GPIO Buttons, Volume Knobs)", fillcolor="#d4e6f1"]; + app_cli [label="Local Management & Telemetry\n(UART CLI, USB CDC Logging)", fillcolor="#d4e6f1"]; + + { rank=same; app_logic; app_ctrl; app_cli; } + } + } + + // 2. HOSTLESS AUDIO DSP FIRMWARE (MIDDLE) + subgraph cluster_firmware { + label = "Hostless SOF Firmware (ESP32-P4 / Teensy 4.1 / Embedded MCU)"; + style = "filled,rounded"; + color = "#27ae60"; + fillcolor = "#eafaf1"; + fontname = "Verdana-Bold"; + fontsize = 11; + fontcolor = "#145a32"; + + subgraph cluster_mgmt { + label = "Static Topology & Autonomous Engine"; + style = "dashed,rounded"; + color = "#27ae60"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + + static_tplg [label="Static Pre-Compiled Topology\n(ROM-Embedded Graph Manifest)", fillcolor="#a3e4d7"]; + sched [label="Autonomous Pipeline Scheduler\n(Low-Latency LL Timer & EDF)", fillcolor="#a3e4d7"]; + local_ctrl [label="Local Parameter Controller\n(Internal Volume / EQ Handlers)", fillcolor="#a3e4d7"]; + + { rank=same; static_tplg; sched; local_ctrl; } + } + + subgraph cluster_pipeline { + label = "Real-Time Audio Processing Pipeline (DAG)"; + style = "dashed,rounded"; + color = "#27ae60"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + + comp_in [label="Input Capture DAI Copier\n(SRAM Buffer Ingest)", fillcolor="#a9dfbf"]; + comp_proc [label="Audio Processing Chain\n(SRC, Volume, Parametric EQ, DRC, AEC, Beamforming)", fillcolor="#a9dfbf"]; + comp_out [label="Output Playback DAI Copier\n(SRAM Buffer Egress)", fillcolor="#a9dfbf"]; + + { rank=same; comp_in; comp_proc; comp_out; } + comp_in -> comp_proc -> comp_out; + } + + subgraph cluster_hal { + label = "Hardware Abstraction & Zephyr RTOS Foundation"; + style = "dashed,rounded"; + color = "#27ae60"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + + dai_in [label="Input Peripheral Drivers (RX)\n(PDM Demux, I2S RX, BT HCI RX)", fillcolor="#bb8fce"]; + zephyr [label="Zephyr RTOS Kernel\n(Multi-Threading, Timers, Power Gating)", fillcolor="#bb8fce"]; + dai_out [label="Output Peripheral Drivers (TX)\n(I2S / SoundWire TX, BT HCI TX)", fillcolor="#bb8fce"]; + + { rank=same; dai_in; zephyr; dai_out; } + } + + app_ctrl -> sched [color="#2b5b84", weight=10]; + sched -> comp_proc [label="trigger", color="#1e8449", weight=10]; + comp_proc -> zephyr [style=invis, weight=10]; + + app_logic -> static_tplg [color="#2b5b84"]; + app_cli -> local_ctrl [color="#2b5b84"]; + + static_tplg -> comp_in [style=dashed, label="instantiate", color="#1e8449"]; + local_ctrl -> comp_out [style=dashed, label="control", color="#1e8449"]; + + dai_in -> comp_in [dir=both, color="#27ae60"]; + comp_out -> dai_out [color="#27ae60"]; + zephyr -> sched [dir=back, style=dashed, color="#27ae60", label="OS timers", constraint=false]; + } + + // 3. PHYSICAL AUDIO INTERFACES & HARDWARE (BOTTOM) + subgraph cluster_hw { + label = "Hardware Audio Interfaces & Physical Endpoints"; + style = "filled,rounded"; + color = "#8e44ad"; + fillcolor = "#f4ecf7"; + fontname = "Verdana-Bold"; + fontsize = 11; + fontcolor = "#4a235a"; + + subgraph cluster_endpoints { + label = "Physical Audio Transducers & External Codecs"; + style = "dashed,rounded"; + color = "#a569bd"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + + hw_in [label="Digital Microphones & Line-In\n(PDM / DMIC Array, I2S ADC)", fillcolor="#d2b4de", shape=cds]; + hw_bt [label="Bluetooth Audio Transceiver\n(A2DP Sink/Source, HFP/mSBC, LE Audio / LC3, Auracast)", fillcolor="#d2b4de", shape=cds]; + hw_out [label="Smart Amps, Speakers & DACs\n(I2S / SoundWire, Line Out)", fillcolor="#d2b4de", shape=cds]; + + { rank=same; hw_in; hw_bt; hw_out; } + } + + zephyr -> hw_bt [style=invis, weight=10]; + } + + hw_in -> dai_in [dir=both, color="#8e44ad"]; + hw_bt -> dai_in [dir=both, color="#8e44ad"]; + dai_out -> hw_bt [color="#8e44ad"]; + dai_out -> hw_out [color="#8e44ad"]; + } + +High-Level Firmware Architecture +******************************** + +The SOF firmware architecture is strictly partitioned into two decoupled tiers: + +1. **SOF Application Layer (Upper Part)**: Houses the audio signal processing engine, real-time pipeline schedulers, inter-processor communication (IPC) protocol decoders, dynamic module loading (LLEXT), and heterogeneous memory management. +2. **Zephyr RTOS Layer (Lower Part)**: Provides the real-time operating system kernel, preemptive multi-threading, SMP multi-core load balancing, hardware timer ticks, device drivers (DMA, DAI, mailbox), and platform hardware abstraction layers (HAL). + +.. graphviz:: + :caption: Sound Open Firmware (SOF) High-Level Firmware Architecture: Application & Zephyr RTOS Layers + :align: center + + digraph fw_architecture { + rankdir=TB; + nodesep=0.40; + ranksep=0.42; + compound=true; + node [shape=box, style="filled,rounded", fontname="Verdana", fontsize=9, margin="0.16,0.08"]; + edge [fontname="Verdana", fontsize=8, color="#555555"]; + + // ========================================================================= + // UPPER PART: SOF APPLICATION LAYER + // ========================================================================= + subgraph cluster_sof_app { + label = "SOF Application Layer (Audio Framework & Processing)"; + style = "filled,rounded"; + color = "#1b4f72"; + fillcolor = "#eef4f9"; + fontname = "Verdana-Bold"; + fontsize = 12; + fontcolor = "#154360"; + margin = 16; + + // Row 1: Framework Services, Control & Scheduling + subgraph cluster_sof_services { + label = "Framework Services, Control & Scheduling"; + style = "dashed,rounded"; + color = "#2980b9"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + margin = 12; + + sof_ipc [label="IPC Protocol Engine\n(IPC4 & IPC3 Protocol Dispatcher,\nCommand & Response Handlers)", fillcolor="#d4e6f1", width=3.3]; + sof_mem [label="Heterogeneous Memory System\n(HP/LP SRAM Pools, Dynamic IMR Paging,\nCache-Aligned Ring Buffers)", fillcolor="#ebdef0", width=3.5]; + sof_sched [label="Real-Time Pipeline Schedulers\n(Low-Latency LL Timer & EDF Schedulers,\nAudio Task Queues)", fillcolor="#fdebd0", width=3.4]; + + sof_ipc -> sof_mem -> sof_sched [style=invis, weight=10]; + { rank=same; sof_ipc; sof_mem; sof_sched; } + } + + // Row 2: Audio Processing Graph & Endpoints + subgraph cluster_sof_pipeline { + label = "Audio Processing Graph (DAG), Modules & Stream Endpoints"; + style = "dashed,rounded"; + color = "#2980b9"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + margin = 12; + + sof_ep_host [label="Host Audio Endpoints\n(Host DMA Copier Ingest Streams)", fillcolor="#f9e79f", width=3.3]; + sof_modules [label="Audio Processing Modules & LLEXT Loader\n(Volume, Mixer, SRC, EQ, DRC, AEC, Beamformer,\nDynamic Relocatable LLEXT Modules)", fillcolor="#a9dfbf", width=3.5]; + sof_ep_dai [label="DAI Audio Endpoints\n(SoundWire, I2S, PDM Copiers)", fillcolor="#f9e79f", width=3.4]; + + sof_ep_host -> sof_modules [label="PCM In", color="#27ae60", constraint=false]; + sof_modules -> sof_ep_dai [label="PCM Out", color="#27ae60", constraint=false]; + sof_ep_host -> sof_modules -> sof_ep_dai [style=invis, weight=10]; + { rank=same; sof_ep_host; sof_modules; sof_ep_dai; } + } + + // Intra-Application Alignment & Signals + sof_ipc -> sof_ep_host [style=invis, weight=20]; + sof_mem -> sof_modules [style=invis, weight=20]; + sof_sched -> sof_ep_dai [style=invis, weight=20]; + + sof_ipc -> sof_ep_host [label="controls", style=dotted, color="#2980b9", constraint=false]; + sof_mem -> sof_modules [label="buffers", style=dotted, color="#7d3c98", constraint=false]; + sof_sched -> sof_modules [label="triggers", color="#d35400", constraint=false]; + } + + // ========================================================================= + // LOWER PART: ZEPHYR RTOS LAYER + // ========================================================================= + subgraph cluster_zephyr_rtos { + label = "Zephyr RTOS Layer (Operating System & Platform HAL)"; + style = "filled,rounded"; + color = "#27ae60"; + fillcolor = "#eafaf1"; + fontname = "Verdana-Bold"; + fontsize = 12; + fontcolor = "#145a32"; + margin = 16; + + // Row 3: Device Drivers & Hardware HAL + subgraph cluster_z_drivers { + label = "Device Drivers & Hardware Abstraction (HAL)"; + style = "dashed,rounded"; + color = "#27ae60"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + margin = 12; + + z_dma_mbx [label="Host DMA & Mailbox Drivers\n(HDA DMA, DW-DMA, Host IPC Doorbell Driver)", fillcolor="#d4e6f1", width=3.3]; + z_mem_hal [label="Memory Management & Cache HAL\n(sys_heap / k_malloc, Cache Coherence)", fillcolor="#ebdef0", width=3.5]; + z_dai_drv [label="DAI Interface Drivers\n(SoundWire Manager/Device, I2S, DMIC)", fillcolor="#d4e6f1", width=3.4]; + + z_dma_mbx -> z_mem_hal -> z_dai_drv [style=invis, weight=10]; + { rank=same; z_dma_mbx; z_mem_hal; z_dai_drv; } + } + + // Row 4: Kernel Core, Scheduling & Power Subsystems + subgraph cluster_z_core { + label = "Zephyr Kernel Core, Scheduling & Power Subsystems"; + style = "dashed,rounded"; + color = "#27ae60"; + fillcolor = "#ffffff"; + fontname = "Verdana-Bold"; + fontsize = 9; + margin = 12; + + z_log [label="Zephyr Logging & Tracing\n(Dictionary Logging, Trace DMA Hooks)", fillcolor="#eaeded", width=3.3]; + z_kernel [label="Kernel Multi-Threading & SMP\n(Threads, Workqueues, Semaphores,\nMulti-Core DSP Load Balancing)", fillcolor="#d5f5e3", width=3.5]; + z_timer_pm [label="Clocks, Timers & Power Management\n(Core Timer Tick, Device PM, D0ix / D3)", fillcolor="#fdebd0", width=3.4]; + + z_log -> z_kernel -> z_timer_pm [style=invis, weight=10]; + { rank=same; z_log; z_kernel; z_timer_pm; } + } + + // Intra-Zephyr Alignment & Signals + z_dma_mbx -> z_log [style=invis, weight=20]; + z_mem_hal -> z_kernel [style=invis, weight=20]; + z_dai_drv -> z_timer_pm [style=invis, weight=20]; + + z_dma_mbx -> z_log [label="trace DMA", style=dotted, color="#7f8c8d", constraint=false]; + z_mem_hal -> z_kernel [label="allocates", style=dashed, color="#7d3c98", constraint=false]; + z_dai_drv -> z_timer_pm [label="PM clock gating", style=dotted, color="#d35400", constraint=false]; + z_timer_pm -> z_kernel [label="timer ticks", color="#27ae60", constraint=false]; + } + + // ========================================================================= + // INTER-LAYER SPINES (STRAIGHT DOWN PARALLEL VERTICAL EDGES) + // ========================================================================= + sof_ep_host -> z_dma_mbx [label="DMA & IPC APIs", color="#2980b9", weight=20]; + sof_modules -> z_mem_hal [label="SRAM Heap & Cache APIs", color="#7d3c98", weight=20]; + sof_ep_dai -> z_dai_drv [label="DAI Driver APIs", color="#2980b9", weight=20]; + } + +Firmware Subsystem Architecture Breakdown +========================================= + +The firmware stack comprises the following key components across the two layers: + +* **Audio Processing Modules**: Standardized DSP processing components chained within directed acyclic graphs (DAGs). Core components include Volume / Mute, Software Mixer, Sample Rate Converter (SRC), Parametric Equalizer (EQ FIR/IIR), Dynamic Range Compressor (DRC), Acoustic Echo Cancellation (AEC), Direction-of-Arrival (DoA) Beamformer, and Spatial Audio. +* **Dynamic Module Loader (LLEXT)**: Enables out-of-tree and closed-source vendor algorithms to be dynamically loaded, linked, and verified into DSP SRAM at runtime without rebuilding the base firmware. +* **Real-Time Pipeline Schedulers**: Coordinates pipeline execution periods. Low-Latency (LL) timer-driven tasks run at fixed 1ms intervals (or native audio frames), while Earliest Deadline First (EDF) and workqueue tasks handle bulk non-real-time audio transformations. +* **IPC Protocol Engine**: Handles asynchronous communication with the host OS over platform doorbells and mailboxes, supporting both Intel IPC4 and legacy IPC3 message formats. +* **Heterogeneous Memory System**: Manages partitioned memory pools spanning High-Power (HP) and Low-Power (LP) SRAM, dynamic Intermediate Memory Residency (IMR) DRAM paging, and cache-aligned zero-copy audio ring buffers. +* **Audio Stream Endpoints**: Interface boundaries that move audio data between host shared memory (Host DMA Copier) and physical audio interface hardware (SoundWire, I2S, PDM copiers). +* **Zephyr RTOS Integration**: Powers the underlying DSP core with preemptive multi-threading, SMP multi-core task migration, architecture hardware timers, unified device drivers, runtime power management (D0ix/D3), and high-throughput dictionary logging. + + +Audio Topology Architecture +*************************** + +Audio routing, component interconnects, and signal processing chains in SOF are completely decoupled from firmware code. Instead of hardcoding audio graphs in C, SOF uses **ALSA Topology**. + +What is an SOF Topology? +======================== + +A topology configuration file defines the complete audio hardware and software graph: +* **Digital Audio Interfaces (DAI)**: Physical link configurations connected to external codecs, SoundWire links, PDM microphones, or HDMI transmitters. +* **Pipeline Layout**: Directed acyclic graphs (DAG) defining which components (Volume, Mixer, SRC, EQ, DRC, AEC) are chained together. +* **Stream Parameters**: Supported sample rates, channel maps, sample bit depths, and scheduling periods (e.g. 1ms low-latency timer or bulk). +* **ALSA Mixer Controls**: Volume faders, mute switches, enum multiplexers, and vendor-specific binary coefficient blobs. + +Audio Processing Pipelines (DAGs) +================================= +At the heart of the firmware is the audio processing pipeline framework: +* **Directed Acyclic Graphs (DAGs)**: Audio pipelines are constructed as graphs of processing components connected by audio buffers. +* **Zero-Copy Buffer Management**: Ring buffers are allocated in cache-aligned SRAM to ensure minimum latency and zero memory copying between adjacent components. +* **Schedulers**: Periodic execution is coordinated by the **Low Latency (LL)** timer-based scheduler or the **Earliest Deadline First (EDF)** event scheduler, supporting both sub-millisecond real-time paths and bulk processing. + +.. graphviz:: + :caption: SOF Audio Processing Pipeline Graph (DAG) and ALSA Control Bindings + :align: center + + digraph audio_pipeline { + rankdir=LR; + nodesep=0.25; + ranksep=0.35; + node [shape=box, style="filled,rounded", fontname="Verdana", fontsize=9, margin="0.12,0.06"]; + edge [fontname="Verdana", fontsize=8, color="#333333"]; + + subgraph cluster_host_dma { + label = "Host Memory Window"; + style = "filled,rounded"; + color = "#2980b9"; + fillcolor = "#ebf5fb"; + fontname = "Verdana-Bold"; + fontsize = 9; + + host_stream [label="Host Audio Stream\n(PCM Playback)", fillcolor="#aed6f1", shape=cds]; + host_dma_comp [label="Host Component\n(DMA Reader)", fillcolor="#d4e6f1"]; + host_stream -> host_dma_comp; + } + + subgraph cluster_pipeline_core { + label = "SOF Audio Pipeline Graph (Scheduled Periodically)"; + style = "filled,rounded"; + color = "#27ae60"; + fillcolor = "#eafaf1"; + fontname = "Verdana-Bold"; + fontsize = 10; + fontcolor = "#1e8449"; + + comp_vol [label="Volume / Mute\n(Linear/Log Ramp)", fillcolor="#a9dfbf"]; + comp_src [label="Sample Rate Converter\n(Polyphase Resampler)", fillcolor="#a9dfbf"]; + comp_eq [label="Parametric EQ\n(IIR/FIR Biquads)", fillcolor="#a9dfbf"]; + comp_drc [label="Dynamic Range\nCompressor (DRC)", fillcolor="#a9dfbf"]; + + comp_vol -> comp_src -> comp_eq -> comp_drc; + } + + subgraph cluster_dai_out { + label = "Physical Audio Interface"; + style = "filled,rounded"; + color = "#8e44ad"; + fillcolor = "#f4ecf7"; + fontname = "Verdana-Bold"; + fontsize = 9; + + dai_comp [label="DAI Copier\n(Output Component)", fillcolor="#d7bde2"]; + dai_hw [label="Physical Codec / Speakers\n(SoundWire / I2S / HDA)", fillcolor="#bb8fce", shape=cds]; + + dai_comp -> dai_hw; + } + + host_dma_comp -> comp_vol [weight=10]; + comp_drc -> dai_comp [weight=10]; + + subgraph cluster_controls { + label = "Real-Time Host Control & Tuning (IPC)"; + style = "dashed,rounded"; + color = "#d35400"; + fillcolor = "#fef5e7"; + fontname = "Verdana-Bold"; + fontsize = 8; + fontcolor = "#a04000"; + + ctl_vol [label="ALSA Volume Mixer\nControl (Fader)", fillcolor="#edbb99"]; + ctl_eq [label="ALSA EQ Coefficients\nBlob Control", fillcolor="#edbb99"]; + + ctl_vol -> ctl_eq [style=invis]; + } + + ctl_vol -> comp_vol [style=dashed, color="#d35400", label="IPC Set Value"]; + ctl_eq -> comp_eq [style=dashed, color="#d35400", label="IPC Set Data"]; + } + +Topology 2 Architecture +======================= + +Modern topologies are authored using **Topology 2 (ALSA Conf / m4)**: +* **Human-Readable Configurations**: High-level graph definitions specifying audio pipelines, widgets, DAIs, and buffer bindings. +* **Pre-Processing & Validation**: Topology compiler tools (``alsatplg`` / ``tplg2``) validate buffer constraints, clock dividers, and memory requirements before producing the binary ``.tplg`` container. +* **Runtime Dynamic Graph Building**: When the host OS boots, the kernel driver parses the binary container and sends IPC messages instructing the DSP firmware to construct the requested graph dynamically. +* **Static ROM Topologies (Hostless)**: In standalone embedded deployments, topologies are pre-compiled into static ROM manifests or C structs embedded directly into the firmware image, removing runtime parsing overhead. + + +.. note:: + For detailed subsystem implementation specifications, host driver internals, and firmware architectural layers, see the :ref:`subsystem-architecture-guides` in Developer Guides. diff --git a/conf.py b/conf.py index 2fb06251..640bc215 100755 --- a/conf.py +++ b/conf.py @@ -34,9 +34,26 @@ extensions = ['breathe', 'sphinx.ext.graphviz', 'sphinxcontrib.plantuml', 'sphinx.ext.todo', 'sphinx.ext.extlinks', - 'sphinxcontrib.jquery' + 'sphinxcontrib.jquery', + 'sphinx_copybutton', + 'sphinx_tabs.tabs' ] +# Copybutton configuration: strip console prompts ($, #, >>>) and handle continuation lines +copybutton_prompt_text = r">>> |\.\.\. |\$ |# |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " +copybutton_prompt_is_regexp = True +copybutton_line_continuation_character = "\\" + +# Sphinx-tabs configuration +sphinx_tabs_disable_tab_closing = True +sphinx_tabs_disable_css_loading = True + +try: + import myst_parser + extensions.append('myst_parser') +except ImportError: + pass + graphviz_output_format='svg' graphviz_dot_args=[ @@ -77,7 +94,7 @@ # General information about the project. project = u'SOF Project' -copyright = u'2024, SOF Project' +copyright = u'2026, SOF Project' author = u'SOF Project developers' # The version info for the project you're documenting, acts as replacement for @@ -105,7 +122,21 @@ # Note: a virtualenv created inside this source tree (.venv, venv, env, ...) # would otherwise be scanned by Sphinx and flood the build with warnings # about .rst files shipped in installed packages. -exclude_patterns = ['_build', '.tox', '.venv*', 'venv', 'env'] +exclude_patterns = [ + '_build', + '.tox', + '.venv*', + 'venv', + 'env', + 'README.md', + 'scripts/*.md', + 'sof', + 'sof/**', + '_deps', + '_deps/**', + '_build_doxy', + '_build_doxy/**', +] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' @@ -119,30 +150,41 @@ # a list of builtin themes. # try: - import sphinx_rtd_theme -except ImportError: - html_theme = 'alabaster' - # This is required for the alabaster theme - # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars - html_sidebars = { - '**': [ - 'relations.html', # needs 'show_related': True theme option to display - 'searchbox.html', - ] - } - sys.stderr.write('Warning: sphinx_rtd_theme missing. Use pip to install it.\n') -else: - html_theme = "sphinx_rtd_theme" + import pydata_sphinx_theme + html_theme = "pydata_sphinx_theme" html_theme_options = { - 'canonical_url': '', - 'analytics_id': 'GTM-M4BL5NF', - 'logo_only': False, - 'prev_next_buttons_location': 'None', - # Toc options - 'collapse_navigation': False, - 'sticky_navigation': True, - 'navigation_depth': 4, + "github_url": "https://github.com/thesofproject/sof", + "external_links": [ + {"name": "SOF Project Website", "url": "https://sofproject.org"} + ], + "navbar_end": ["theme-switcher", "navbar-icon-links"], } +except ImportError: + try: + import sphinx_rtd_theme + except ImportError: + html_theme = 'alabaster' + # This is required for the alabaster theme + # refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars + html_sidebars = { + '**': [ + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + ] + } + sys.stderr.write('Warning: sphinx_rtd_theme missing. Use pip to install it.\n') + else: + html_theme = "sphinx_rtd_theme" + html_theme_options = { + 'canonical_url': '', + 'analytics_id': 'GTM-M4BL5NF', + 'logo_only': False, + 'prev_next_buttons_location': 'None', + # Toc options + 'collapse_navigation': False, + 'sticky_navigation': True, + 'navigation_depth': 4, + } # Here's where we (manually) list the document versions maintained on @@ -170,7 +212,7 @@ # html_theme_options = {} html_logo = 'images/logo_sof_white_200w.png' -html_favicon = 'images/sof-favicon-16x16.png' +html_favicon = 'images/sof-favicon.svg' numfig = True #numfig_secnum_depth = (2) @@ -221,6 +263,11 @@ def filter(self, record): except AttributeError: app.add_stylesheet('sof-custom.css') + try: + app.add_js_file('sof-custom.js') + except AttributeError: + app.add_javascript('sof-custom.js') + # Custom sidebar templates, must be a dictionary that maps document names # to template names. # diff --git a/data/legacy_platforms.yaml b/data/legacy_platforms.yaml new file mode 100644 index 00000000..520278fd --- /dev/null +++ b/data/legacy_platforms.yaml @@ -0,0 +1,169 @@ +# SOF Legacy Platforms Database (Platforms No Longer Supported in Mainline) +# Used to generate the legacy platforms compatibility matrix. +# Each SoC has its own distinct row. + +legacy_platforms: + - id: byt + vendor: Intel + name: Bay Trail (BYT) + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi2 EP + cores_clocks: "1 @ 50 - 400 MHz" + platform_clock: "25 MHz" + memory: "96 KB IRAM / 192 KB DRAM" + audio_interfaces: "3 x SSP (I2S, PCM)" + + - id: mrfl + vendor: Intel + name: Merrifield (MRFL) + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi2 EP + cores_clocks: "1 @ 50 - 400 MHz" + platform_clock: "25 MHz" + memory: "96 KB IRAM / 192 KB DRAM" + audio_interfaces: "3 x SSP (I2S, PCM)" + + - id: cht + vendor: Intel + name: Cherry Trail (CHT) + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi2 EP + cores_clocks: "1 @ 50 - 400 MHz" + platform_clock: "19.2 MHz" + memory: "96 KB IRAM / 192 KB DRAM" + audio_interfaces: "6 x SSP (I2S, PCM)" + + - id: bsw + vendor: Intel + name: Braswell (BSW) + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi2 EP + cores_clocks: "1 @ 50 - 400 MHz" + platform_clock: "19.2 MHz" + memory: "96 KB IRAM / 192 KB DRAM" + audio_interfaces: "6 x SSP (I2S, PCM)" + + - id: bdw + vendor: Intel + name: Broadwell (BDW) + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi2 EP + cores_clocks: "1 @ 50 - 400 MHz" + platform_clock: "24 MHz" + memory: "320 KB IRAM / 640 KB DRAM" + audio_interfaces: "2 x SSP (I2S, PCM)" + + - id: apl + vendor: Intel + name: Apollo Lake (APL) + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi3 + cores_clocks: "2 @ 100 - 400 MHz" + platform_clock: "19.2 MHz" + memory: "128 KB LP SRAM / 512 KB HP SRAM" + audio_interfaces: "6 x SSP (I2S, PCM), HDA, DMIC" + + - id: glk + vendor: Intel + name: Gemini Lake (GLK) + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi3 + cores_clocks: "2 @ 100 - 400 MHz" + platform_clock: "19.2 MHz" + memory: "128 KB LP SRAM / 512 KB HP SRAM" + audio_interfaces: "6 x SSP (I2S, PCM), HDA, DMIC" + + - id: cnl + vendor: Intel + name: Cannon Lake (CNL) + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi3 + cores_clocks: "4 @ 120 - 400 MHz" + platform_clock: "24 MHz" + memory: "64 KB LP / 3008 KB HP SRAM" + audio_interfaces: "3 x SSP (I2S, PCM), HDA, DMIC, SoundWire" + + - id: whl + vendor: Intel + name: Whiskey Lake (WHL) + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi3 + cores_clocks: "4 @ 120 - 400 MHz" + platform_clock: "24 MHz" + memory: "64 KB LP / 3008 KB HP SRAM" + audio_interfaces: "3 x SSP (I2S, PCM), HDA, DMIC, SoundWire" + + - id: cml + vendor: Intel + name: Comet Lake (CML) + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi3 + cores_clocks: "4 @ 120 - 400 MHz" + platform_clock: "24 MHz" + memory: "64 KB LP / 3008 KB HP SRAM" + audio_interfaces: "3 x SSP (I2S, PCM), HDA, DMIC, SoundWire" + + - id: snc + vendor: Intel + name: Sue Creek (SNC) + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi3 + cores_clocks: "2 @ 120 - 400 MHz" + platform_clock: "24 MHz" + memory: "64 KB LP SRAM / 4096 KB HP SRAM" + audio_interfaces: "6 x SSP (I2S, PCM), DMIC" + + - id: icl + vendor: Intel + name: Ice Lake (ICL) + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi3 + cores_clocks: "4 @ 120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 3008 KB HP SRAM" + audio_interfaces: "6 x SSP (I2S, PCM), HDA, DMIC, SoundWire" + + - id: jsl + vendor: Intel + name: Jasper Lake (JSL) + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi3 + cores_clocks: "2 @ 120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 1024 KB HP SRAM" + audio_interfaces: "3 x SSP (I2S, PCM), HDA, DMIC, SoundWire" + + - id: tgl_ipc3 + vendor: Intel + name: Tiger Lake (TGL) with IPC3 + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi3 + cores_clocks: "4 @ 120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 2944 KB HP SRAM" + audio_interfaces: "6 x SSP (I2S, PCM), HDA, DMIC, SoundWire" + + - id: adl_ipc3 + vendor: Intel + name: Alder Lake (ADL) with IPC3 + last_release: "2.2" + branch: stable-v2.2 + dsp_arch: Xtensa HiFi3 + cores_clocks: "4 @ 120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 2944 KB HP SRAM" + audio_interfaces: "6 x SSP (I2S, PCM), HDA, DMIC, SoundWire" diff --git a/data/modules.yaml b/data/modules.yaml new file mode 100644 index 00000000..0b277a58 --- /dev/null +++ b/data/modules.yaml @@ -0,0 +1,404 @@ +# SOF Supported Algorithms & Processing Modules Database (Single Source of Truth) + +modules: + # --- Basic Routing & Foundational DSP --- + - id: volume + name: "Volume / Mute" + source: "SOF" + category: "Basic Routing & Level" + status: "Upstream" + description: "Multi-channel software volume attenuation, smooth ramp, and mute control." + simd: ["ARM", "HiFi 3", "HiFi 4", "HiFi 5", "RISCV", "Scalar C"] + key_features: + - "Per-channel linear and log gain curves" + - "Smooth zipper noise attenuation" + - "Zero-overhead bypass when set to 0dB" + + - id: mixer + name: "Audio Mixer" + source: "SOF" + category: "Basic Routing & Level" + status: "Upstream" + description: "N-to-M channel audio stream summer with clipping protection and saturation." + simd: ["ARM", "HiFi 3", "HiFi 5", "RISCV", "Scalar C"] + key_features: + - "Concurrent playback mixing" + - "Dynamic input stream attachment/detachment" + - "Saturation and clipping protection" + + - id: src + name: "Sample Rate Converter (SRC)" + source: "SOF" + category: "Foundational DSP" + status: "Upstream" + description: "Polyphase FIR resampler converting between standard sample rates (8kHz to 192kHz)." + simd: ["HiFi 2 EP", "HiFi 3", "HiFi 4", "HiFi 5", "RISCV", "Scalar C"] + key_features: + - "High SNR polyphase filtering" + - "Low group delay" + - "Multi-channel synchronous resampling" + + - id: asrc + name: "Asynchronous SRC (ASRC)" + source: "SOF" + category: "Foundational DSP" + status: "Upstream" + description: "Drift-compensated asynchronous sample rate converter for independent clock domains." + simd: ["HiFi 3", "HiFi 5", "RISCV", "Scalar C"] + key_features: + - "Farrow polynomial interpolation" + - "Continuous clock drift tracking" + - "Decoupled clock domain bridging" + + - id: demux + name: "Audio Demux" + source: "SOF" + category: "Basic Routing & Level" + status: "Upstream" + description: "Demultiplexes a single multi-channel audio stream into multiple downstream sink pipelines." + simd: ["Scalar C"] + key_features: + - "Multi-channel stream demultiplexing" + - "Dynamic route splitting" + - "Zero-copy sample extraction" + + - id: mux + name: "Audio Mux" + source: "SOF" + category: "Basic Routing & Level" + status: "Upstream" + description: "Multiplexes multiple synchronized input streams into a combined multi-channel output stream." + simd: ["Scalar C"] + key_features: + - "Multi-source stream multiplexing" + - "Configurable input channel mapping" + - "Synchronized buffer alignment" + + - id: channel_map + name: "Channel Map / Remap" + source: "SOF" + category: "Basic Routing & Level" + status: "Upstream" + description: "Flexible channel remapping, slot swapping, and channel replication component." + simd: ["Scalar C"] + key_features: + - "Arbitrary slot and channel routing" + - "Mono to stereo/surround replication" + - "Channel swap and mute masking" + + - id: tone + name: "Tone Generator" + source: "SOF" + category: "Diagnostics & Testing" + status: "Upstream" + description: "Synthesizes diagnostic test tones for audio path verification." + simd: ["RISCV", "Scalar C"] + key_features: + - "Sine wave generation" + - "Configurable frequency and amplitude" + - "Per-channel tone routing" + + # --- Audio Enhancement & Filtering --- + - id: eq_fir + name: "Parametric Equalizer (EQ FIR)" + source: "SOF" + category: "Audio Enhancement" + status: "Upstream" + description: "High-order finite impulse response (FIR) filter for precise phase and frequency response tuning." + simd: ["ARM", "HiFi 2 EP", "HiFi 3", "HiFi 4", "HiFi 5", "RISCV", "Scalar C"] + key_features: + - "High-order linear-phase FIR filtering" + - "Speaker and room impulse response correction" + - "Live runtime coefficient updates over IPC" + + - id: eq_iir + name: "Parametric Equalizer (EQ IIR)" + source: "SOF" + category: "Audio Enhancement" + status: "Upstream" + description: "Cascaded biquad infinite impulse response (IIR) parametric equalizer." + simd: ["ARM", "HiFi 2 EP", "HiFi 3", "HiFi 4", "HiFi 5", "RISCV", "Scalar C"] + key_features: + - "Cascaded second-order biquad sections" + - "Parametric peak, notch, low/high shelf" + - "Low computational latency" + + - id: drc + name: "Dynamic Range Compressor (DRC)" + source: "SOF" + category: "Audio Enhancement" + status: "Upstream" + description: "Wideband dynamic range compressor with configurable attack, release, and threshold curves." + simd: ["ARM", "HiFi 3", "HiFi 4", "RISCV", "Scalar C"] + key_features: + - "Speaker excursion and thermal protection" + - "Configurable attack, release, and knee" + - "Peak and RMS signal level detection" + + - id: multiband_drc + name: "Multiband DRC" + source: "SOF" + category: "Audio Enhancement" + status: "Upstream" + description: "Multi-band dynamic range compressor with independent compression across frequency subbands." + simd: ["HiFi 3", "HiFi 4", "RISCV", "Scalar C"] + key_features: + - "Subband crossover splitting" + - "Per-band threshold and ratio controls" + - "Comprehensive speaker protection" + + - id: crossover + name: "Crossover Filter" + source: "SOF" + category: "Audio Enhancement" + status: "Upstream" + description: "2-way and 3-way Linkwitz-Riley crossover filter for multi-driver audio systems." + simd: ["HiFi 3", "RISCV", "Scalar C"] + key_features: + - "Linkwitz-Riley 4th order (LR4) splitting" + - "Flat magnitude sum across crossover point" + - "Multi-way woofer, tweeter, and sub routing" + + - id: dcblock + name: "DC Blocker" + source: "SOF" + category: "Audio Enhancement" + status: "Upstream" + description: "High-pass filter removing hardware DC bias and sub-audible hum." + simd: ["ARM", "HiFi 3", "HiFi 4", "RISCV", "Scalar C"] + key_features: + - "Removes DC bias from digital mics and ADCs" + - "Sub-audible rumble attenuation" + - "Near-zero phase distortion in audio band" + + - id: smart_amp + name: "Smart Amp Protection" + source: "SOF" + category: "Speaker Protection" + status: "Upstream" + description: "Speaker protection algorithm monitoring voltage/current feedback to maximize loudness safely." + simd: ["HiFi 3", "HiFi 4", "Scalar C"] + key_features: + - "Real-time voice coil temperature estimation" + - "Membrane excursion limiting" + - "Maximizes acoustic output without damage" + + # --- Voice, Telephony & Speech --- + - id: tdfb + name: "Beamformer (TDFB)" + source: "SOF" + category: "Voice & Telephony" + status: "Upstream" + description: "Time-Domain Fixed Beamformer combining multi-microphone inputs to isolate target speakers." + simd: ["HiFi 2 EP", "HiFi 3", "HiFi 4", "HiFi 5", "RISCV", "Scalar C"] + key_features: + - "Multi-mic circular and linear array support" + - "Broadside and endfire steering" + - "Spatial diffuse noise suppression" + + - id: webrtc_aec + name: "WebRTC Echo Cancellation (AEC)" + source: "WebRTC" + category: "Voice & Telephony" + status: "Active Development" + description: "Full-duplex acoustic echo cancellation removing loudspeaker playback from microphone capture." + simd: ["HiFi 3", "HiFi 4", "VFPU", "Scalar C"] + key_features: + - "Subband adaptive filter convergence" + - "Multi-channel reference loopback alignment" + - "Robust double-talk detection" + + - id: webrtc_aecm + name: "WebRTC Mobile AEC (AECM)" + source: "WebRTC" + category: "Voice & Telephony" + status: "Active Development" + description: "Lightweight mobile acoustic echo canceller tailored for power-constrained DSPs and embedded targets." + simd: ["HiFi 3", "HiFi 4", "VFPU", "Scalar C"] + key_features: + - "Fixed-point low-complexity processing" + - "Optimized for earbuds and wearables" + - "Low RAM and cycle footprint" + + - id: webrtc_ns + name: "WebRTC Noise Suppression (NS)" + source: "WebRTC" + category: "Voice & Telephony" + status: "Active Development" + description: "Spectral subtraction stationary noise suppression for voice clarity." + simd: ["HiFi 3", "HiFi 4", "VFPU", "Scalar C"] + key_features: + - "Stationary background noise reduction" + - "Configurable aggressiveness levels" + - "Preserves speech formant clarity" + + - id: webrtc_ns2 + name: "WebRTC Neural NS (NS2 / RNNoise)" + source: "WebRTC" + category: "Voice & Telephony" + status: "Active Development" + description: "Recurrent neural network deep learning noise suppression for non-stationary acoustic noise." + simd: ["HiFi 3", "HiFi 4", "VFPU", "Scalar C"] + key_features: + - "Recurrent neural network (RNN) inference" + - "Non-stationary transient noise elimination" + - "High speech perceptual quality" + + - id: webrtc_vad + name: "WebRTC Voice Activity Detector (VAD)" + source: "WebRTC" + category: "Voice & Telephony" + status: "Active Development" + description: "Low-power speech presence detector for call management and pipeline gating." + simd: ["HiFi 3", "Scalar C"] + key_features: + - "Multi-band energy likelihood estimation" + - "Sub-frame voice decision gating" + - "Ultra-low power listening states" + + - id: webrtc_agc + name: "WebRTC Automatic Gain Control (AGC)" + source: "WebRTC" + category: "Voice & Telephony" + status: "Active Development" + description: "Adaptive digital gain controller and peak limiter for uniform speech loudness." + simd: ["HiFi 3", "HiFi 4", "Scalar C"] + key_features: + - "Dynamic gain adjustment" + - "Saturation prevention limiter" + - "Normalizes quiet and loud speakers" + + - id: wov_kpb + name: "Key Phrase Buffer (KPB / WoV)" + source: "SOF" + category: "Voice & Telephony" + status: "Upstream" + description: "Low-power Wake-on-Voice pre-roll history circular buffer." + simd: ["Scalar C"] + key_features: + - "Ultra-low power DSP listening mode (D0ix)" + - "Zero-latency audio pre-roll buffer playback" + - "Multi-slot capture streaming to host" + + - id: microwakeword + name: "microWakeWord (TFLite Micro)" + source: "Google" + category: "Voice & Telephony" + status: "Active Development" + description: "Embedded deep neural network keyword detector running on TensorFlow Lite for Microcontrollers." + simd: ["HiFi 3", "HiFi 4", "Scalar C"] + key_features: + - "On-device neural network keyword spotting" + - "TFLite Micro runtime execution" + - "Low false-reject and false-alarm rates" + + # --- Codecs & Compression --- + - id: aac_dec + name: "AAC Decoder" + source: "FFmpeg" + category: "Codecs & Compression" + status: "Active Development" + description: "MPEG-4 Advanced Audio Coding (AAC-LC / HE-AAC) decoder." + simd: ["VFPU", "HiFi 3", "HiFi 4", "HiFi 5", "Scalar C"] + key_features: + - "Vector floating-point hardware acceleration" + - "MPEG-4 AAC-LC and HE-AAC profile support" + - "Direct pipeline integration" + + - id: aac_enc + name: "AAC Encoder" + source: "FFmpeg" + category: "Codecs & Compression" + status: "Active Development" + description: "MPEG-4 AAC audio bitstream encoder for Bluetooth and streaming egress." + simd: ["VFPU", "HiFi 3", "HiFi 4", "HiFi 5", "Scalar C"] + key_features: + - "Low-power bitstream encoding" + - "Configurable bitrates and sample rates" + - "Optimized MDCT and psychoacoustic model" + + - id: mp3_dec + name: "MP3 Decoder" + source: "FFmpeg" + category: "Codecs & Compression" + status: "Active Development" + description: "MPEG-1/2 Audio Layer III decoder leveraging optimized subband synthesis and MDCT." + simd: ["VFPU", "HiFi 3", "HiFi 4", "HiFi 5", "Scalar C"] + key_features: + - "Hardware VFPU SIMD acceleration" + - "High-throughput low-overhead DSP execution" + - "Full bit reservoir and Huffman decoding" + + - id: mp3_enc + name: "MP3 Encoder" + source: "FFmpeg" + category: "Codecs & Compression" + status: "Active Development" + description: "Real-time fixed-point MP3 audio encoder for recording and broadcast." + simd: ["VFPU", "HiFi 3", "HiFi 4", "Scalar C"] + key_features: + - "Low-complexity fixed-point encoding" + - "Efficient subband analysis filterbank" + - "Standard MPEG-1 Layer III bitstream generation" + + - id: flac_dec + name: "FLAC Decoder" + source: "FFmpeg" + category: "Codecs & Compression" + status: "Active Development" + description: "Free Lossless Audio Codec decoder delivering bit-exact high-resolution audio." + simd: ["VFPU", "HiFi 3", "HiFi 4", "Scalar C"] + key_features: + - "Lossless 16/24-bit audio decompression" + - "Fast linear prediction decoding" + - "Zero fidelity loss playback" + + - id: opus_dec + name: "Opus Decoder" + source: "FFmpeg" + category: "Codecs & Compression" + status: "Active Development" + description: "Interactive speech and music decoder optimized for ultra-low delay streaming." + simd: ["VFPU", "HiFi 3", "HiFi 4", "Scalar C"] + key_features: + - "SILK speech and CELT music mode support" + - "Sub-20ms algorithmic latency" + - "Dynamic bitrate and bandwidth adaptation" + + - id: vorbis_dec + name: "Vorbis Decoder" + source: "FFmpeg" + category: "Codecs & Compression" + status: "Active Development" + description: "Ogg Vorbis lossy audio decoder with variable bitrate support." + simd: ["VFPU", "HiFi 3", "HiFi 4", "Scalar C"] + key_features: + - "General-purpose variable bitrate decompression" + - "Vector quantization floor decoding" + - "Low memory footprint" + + # --- Spatial Audio --- + - id: steam_audio + name: "Steam Audio Spatializer" + source: "Steam Audio" + category: "Spatial Audio" + status: "Active Development" + description: "3D binaural spatializer using Head-Related Transfer Functions (HRTF)." + simd: ["VFPU", "HiFi 4", "HiFi 5", "Scalar C"] + key_features: + - "Spherical 3D sound positioning" + - "Convolution-based HRTF binaural rendering" + - "Dynamic listener and source orientation" + + # --- Diagnostics & Tools --- + - id: probes_telemetry + name: "Real-Time Probes & Telemetry" + source: "SOF" + category: "Diagnostics & Tools" + status: "Upstream" + description: "Non-intrusive runtime audio probing and log extraction across pipeline points." + simd: ["Scalar C"] + key_features: + - "Direct probe DMA streaming over TCP port 9999" + - "Zero overhead when probe taps are inactive" + - "Multi-point simultaneous stream tapping" diff --git a/data/platforms.yaml b/data/platforms.yaml new file mode 100644 index 00000000..ee9dfded --- /dev/null +++ b/data/platforms.yaml @@ -0,0 +1,643 @@ +# SOF Supported Platforms Database (Single Source of Truth) +# Used to generate documentation tables, compatibility matrices, and web cards. +# Each SoC has its own distinct row. + +platforms: + - id: tgl + vendor: Intel + family: CAVS 2.5 + name: Tiger Lake (TGL) + dsp_arch: Xtensa HiFi3 + cores: 4 + clock_range: "120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 2944 KB HP SRAM" + audio_interfaces: + - "6 x SSP (I2S, TDM, PCM)" + - "HD-Audio (HDA)" + - "DMIC / PDM (up to 4 channels)" + - "SoundWire (SDW 1.1/1.2)" + ipc_versions: + - IPC4 + - IPC3 + zephyr_target: intel_adsp_cavs25 + target_alias: tgl + test_dut: Spider + status: Mainline Active + + - id: tgl_h + vendor: Intel + family: CAVS 2.5 + name: Tiger Lake-H (TGL-H) + dsp_arch: Xtensa HiFi3 + cores: 4 + clock_range: "120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 2944 KB HP SRAM" + audio_interfaces: + - "6 x SSP (I2S, TDM, PCM)" + - "HD-Audio (HDA)" + - "DMIC / PDM" + - "SoundWire (SDW 1.1/1.2)" + ipc_versions: + - IPC4 + - IPC3 + zephyr_target: intel_adsp_cavs25_tgph + target_alias: tgl-h + status: Mainline Active + + - id: adl + vendor: Intel + family: CAVS 2.5 + name: Alder Lake (ADL) + dsp_arch: Xtensa HiFi3 + cores: 4 + clock_range: "120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 2944 KB HP SRAM" + audio_interfaces: + - "6 x SSP (I2S, TDM, PCM)" + - "HD-Audio (HDA)" + - "DMIC / PDM" + - "SoundWire (SDW 1.2)" + ipc_versions: + - IPC4 + zephyr_target: intel_adsp_cavs25 + target_alias: adl + status: Mainline Active + + - id: adl_n + vendor: Intel + family: CAVS 2.5 + name: Alder Lake-N (ADL-N) + dsp_arch: Xtensa HiFi3 + cores: 2 + clock_range: "120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 2048 KB HP SRAM" + audio_interfaces: + - "SSP (I2S, PCM)" + - "HD-Audio (HDA)" + - "DMIC / PDM" + - "SoundWire" + ipc_versions: + - IPC4 + zephyr_target: intel_adsp_cavs25 + target_alias: adl-n + status: Mainline Active + + - id: adl_s + vendor: Intel + family: CAVS 2.5 + name: Alder Lake-S (ADL-S) + dsp_arch: Xtensa HiFi3 + cores: 4 + clock_range: "120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 2944 KB HP SRAM" + audio_interfaces: + - "6 x SSP (I2S, TDM, PCM)" + - "HD-Audio (HDA)" + - "DMIC / PDM" + - "SoundWire (SDW 1.2)" + ipc_versions: + - IPC4 + zephyr_target: intel_adsp_cavs25_tgph + target_alias: adl-s + status: Mainline Active + + - id: rpl + vendor: Intel + family: CAVS 2.5 + name: Raptor Lake (RPL) + dsp_arch: Xtensa HiFi3 + cores: 4 + clock_range: "120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 2944 KB HP SRAM" + audio_interfaces: + - "6 x SSP (I2S, TDM, PCM)" + - "HD-Audio (HDA)" + - "DMIC / PDM" + - "SoundWire (SDW 1.2)" + ipc_versions: + - IPC4 + zephyr_target: intel_adsp_cavs25 + target_alias: rpl + status: Mainline Active + + - id: rpl_s + vendor: Intel + family: CAVS 2.5 + name: Raptor Lake-S (RPL-S) + dsp_arch: Xtensa HiFi3 + cores: 4 + clock_range: "120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 2944 KB HP SRAM" + audio_interfaces: + - "6 x SSP (I2S, TDM, PCM)" + - "HD-Audio (HDA)" + - "DMIC / PDM" + - "SoundWire (SDW 1.2)" + ipc_versions: + - IPC4 + zephyr_target: intel_adsp_cavs25_tgph + target_alias: rpl-s + status: Mainline Active + + - id: mtl + vendor: Intel + family: ACE 1.5 + name: Meteor Lake (MTL) + dsp_arch: Xtensa HiFi4 + cores: 4 + clock_range: "120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 2944 KB HP SRAM / IMR Paging" + audio_interfaces: + - "HD-Audio (HDA)" + - "SoundWire (SDW 1.2 multi-link)" + - "SSP (I2S, PCM)" + - "DMIC / PDM" + ipc_versions: + - IPC4 + zephyr_target: intel_adsp_ace15_mtlm + target_alias: mtl + status: Mainline Active + + - id: arl + vendor: Intel + family: ACE 1.5 + name: Arrow Lake (ARL) + dsp_arch: Xtensa HiFi4 + cores: 4 + clock_range: "120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 2944 KB HP SRAM / IMR Paging" + audio_interfaces: + - "HD-Audio (HDA)" + - "SoundWire (SDW 1.2)" + - "SSP (I2S, PCM)" + - "DMIC / PDM" + ipc_versions: + - IPC4 + zephyr_target: intel_adsp_ace15_mtlm + target_alias: arl + status: Mainline Active + + - id: arl_s + vendor: Intel + family: ACE 1.5 + name: Arrow Lake-S (ARL-S) + dsp_arch: Xtensa HiFi4 + cores: 4 + clock_range: "120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "64 KB LP SRAM / 2944 KB HP SRAM / IMR Paging" + audio_interfaces: + - "HD-Audio (HDA)" + - "SoundWire (SDW 1.2)" + - "SSP (I2S, PCM)" + - "DMIC / PDM" + ipc_versions: + - IPC4 + zephyr_target: intel_adsp_ace15_mtlm + target_alias: arl-s + test_dut: Dragon Fly + status: Mainline Active + + - id: lnl + vendor: Intel + family: ACE 2.0 + name: Lunar Lake (LNL) + dsp_arch: Xtensa HiFi4 + cores: 4 + clock_range: "120 - 400 MHz" + platform_clock: "38.4 MHz" + memory: "SRAM / IMR Paging / Power Islands" + audio_interfaces: + - "HD-Audio (HDA)" + - "SoundWire (SDW 1.2)" + - "SSP (I2S, PCM)" + - "DMIC / PDM" + ipc_versions: + - IPC4 + zephyr_target: intel_adsp_ace20_lnl + target_alias: lnl + status: Mainline Active + + - id: ptl + vendor: Intel + family: ACE 3.0 + name: Panther Lake (PTL) + dsp_arch: Xtensa HiFi5 + cores: 4 + clock_range: "120 - 800 MHz" + platform_clock: "38.4 MHz" + memory: "HP SRAM / LP SRAM / Dynamic IMR Paging" + audio_interfaces: + - "SoundWire (SDW 1.2 multi-link)" + - "HD-Audio (HDA)" + - "SSP (I2S, PCM)" + - "DMIC / PDM" + ipc_versions: + - IPC4 + zephyr_target: intel_ace30_ptl + target_alias: ptl + test_dut: Aphid + status: Mainline Active + + - id: wcl + vendor: Intel + family: ACE 3.0 + name: Wildcat Lake (WCL) + dsp_arch: Xtensa HiFi4 + cores: 4 + clock_range: "120 - 800 MHz" + platform_clock: "38.4 MHz" + memory: "HP SRAM / LP SRAM / Dynamic IMR Paging" + audio_interfaces: + - "SoundWire" + - "HD-Audio" + - "SSP (I2S, PCM)" + - "DMIC / PDM" + ipc_versions: + - IPC4 + zephyr_target: intel_ace30_wcl + target_alias: wcl + status: Mainline Active + + - id: nvl + vendor: Intel + family: ACE 4.0 + name: Nova Lake (NVL) + dsp_arch: Xtensa HiFi5 + cores: 4 + clock_range: "120 - 800 MHz" + platform_clock: "38.4 MHz" + memory: "HP SRAM / LP SRAM / Dynamic IMR Paging" + audio_interfaces: + - "SoundWire" + - "HD-Audio" + - "SSP (I2S, PCM)" + - "DMIC / PDM" + ipc_versions: + - IPC4 + zephyr_target: intel_adsp_ace40_nvl + target_alias: nvl + status: Mainline Active + + - id: nvl_s + vendor: Intel + family: ACE 4.0 + name: Nova Lake-S (NVL-S) + dsp_arch: Xtensa HiFi5 + cores: 4 + clock_range: "120 - 800 MHz" + platform_clock: "38.4 MHz" + memory: "HP SRAM / LP SRAM / Dynamic IMR Paging" + audio_interfaces: + - "SoundWire" + - "HD-Audio" + - "SSP (I2S, PCM)" + - "DMIC / PDM" + ipc_versions: + - IPC4 + zephyr_target: intel_adsp_ace40_nvls + target_alias: nvl-s + status: Mainline Active + + - id: amd_renoir + vendor: AMD + family: Renoir + name: AMD Renoir + dsp_arch: Xtensa HiFi3 + cores: 1 + clock_range: "200 - 600 MHz" + platform_clock: "Variable" + memory: "20 KB LP SRAM / 1152 KB IRAM/DRAM" + audio_interfaces: + - "1 x SP (I2S, PCM)" + - "1 x BT (I2S, PCM)" + - "DMIC" + ipc_versions: + - IPC3 + - IPC4 + zephyr_target: amd_renoir + target_alias: rn + status: Mainline Supported + + - id: amd_rembrandt + vendor: AMD + family: Rembrandt + name: AMD Rembrandt + dsp_arch: Xtensa HiFi5 + cores: 1 + clock_range: "200 - 800 MHz" + platform_clock: "Variable" + memory: "1.75 MB HP SRAM / 512 KB IRAM/DRAM" + audio_interfaces: + - "1 x SP (I2S, PCM)" + - "1 x BT (I2S, PCM)" + - "1 x HS (I2S, PCM)" + - "DMIC" + ipc_versions: + - IPC4 + zephyr_target: amd_rembrandt + target_alias: rmb + status: Mainline Supported + + - id: amd_phoenix + vendor: AMD + family: Phoenix + name: AMD Phoenix + dsp_arch: Xtensa HiFi5 + cores: 1 + clock_range: "200 - 800 MHz" + platform_clock: "Variable" + memory: "1.75 MB HP SRAM / 512 KB IRAM/DRAM" + audio_interfaces: + - "1 x SP (I2S, PCM)" + - "1 x BT (I2S, PCM)" + - "1 x HS (I2S, PCM)" + - "DMIC" + ipc_versions: + - IPC4 + zephyr_target: acp_7_0 + target_alias: acp_7_0 + status: Mainline Supported + + - id: amd_strix + vendor: AMD + family: Strix + name: AMD Strix Point + dsp_arch: Xtensa HiFi5 + cores: 1 + clock_range: "200 - 800 MHz" + platform_clock: "Variable" + memory: "1.75 MB HP SRAM / 512 KB IRAM/DRAM" + audio_interfaces: + - "1 x SP (I2S, PCM)" + - "1 x BT (I2S, PCM)" + - "1 x HS (I2S, PCM)" + - "DMIC" + ipc_versions: + - IPC4 + zephyr_target: acp_7_x + target_alias: acp7x + status: Mainline Supported + + - id: nxp_imx8 + vendor: NXP + family: i.MX8 + name: NXP i.MX8 + dsp_arch: Xtensa HiFi4 + cores: 1 + clock_range: "666 MHz" + platform_clock: "Variable" + memory: "64 KB TCM / 448 KB OCRAM / 8 MB SDRAM" + audio_interfaces: + - "1 x ESAI" + - "1 x SAI" + ipc_versions: + - IPC3 + - IPC4 + zephyr_target: nxp_imx8 + target_alias: imx8 + status: Mainline Supported + + - id: nxp_imx8x + vendor: NXP + family: i.MX8X + name: NXP i.MX8X + dsp_arch: Xtensa HiFi4 + cores: 1 + clock_range: "640 MHz" + platform_clock: "Variable" + memory: "64 KB TCM / 448 KB OCRAM / 8 MB SDRAM" + audio_interfaces: + - "1 x ESAI" + - "1 x SAI" + ipc_versions: + - IPC3 + - IPC4 + zephyr_target: nxp_imx8x + target_alias: imx8x + status: Mainline Supported + + - id: nxp_imx8m + vendor: NXP + family: i.MX8M + name: NXP i.MX8M + dsp_arch: Xtensa HiFi4 + cores: 1 + clock_range: "800 MHz" + platform_clock: "Variable" + memory: "64 KB TCM / 256 KB OCRAM / 8 MB SDRAM" + audio_interfaces: + - "1 x SAI" + - "MICFIL" + ipc_versions: + - IPC3 + - IPC4 + zephyr_target: nxp_imx8m + target_alias: imx8m + status: Mainline Supported + + - id: nxp_imx8m_cm7 + vendor: NXP + family: i.MX8M + name: NXP i.MX8M Mini (M7) + dsp_arch: ARM Cortex-M7 + cores: 1 + clock_range: "800 MHz" + platform_clock: "Variable" + memory: "128 KB TCM / DDR" + audio_interfaces: + - "1 x SAI" + - "MICFIL" + ipc_versions: + - IPC3 + - IPC4 + zephyr_target: imx8m_cm7 + target_alias: imx8m_cm7 + status: Mainline Supported + + - id: nxp_imx8ulp + vendor: NXP + family: i.MX8ULP + name: NXP i.MX8ULP + dsp_arch: Xtensa HiFi4 + cores: 1 + clock_range: "520 MHz" + platform_clock: "Variable" + memory: "64 KB TCM / 256 KB OCRAM / 8 MB SDRAM" + audio_interfaces: + - "1 x SAI" + ipc_versions: + - IPC3 + - IPC4 + zephyr_target: nxp_imx8ulp + target_alias: imx8ulp + status: Mainline Supported + + - id: nxp_imx95 + vendor: NXP + family: i.MX95 + name: NXP i.MX95 + dsp_arch: ARM Cortex-M7 + cores: 1 + clock_range: "800 MHz" + platform_clock: "Variable" + memory: "1 MB SRAM / DDR" + audio_interfaces: + - "1 x SAI" + - "ESAI" + ipc_versions: + - IPC3 + - IPC4 + zephyr_target: imx95 + target_alias: imx95 + status: Active Development + + - id: mtk_mt8195 + vendor: MediaTek + family: MT8195 + name: MediaTek MT8195 + dsp_arch: Xtensa HiFi4 + cores: 1 + clock_range: "220 - 720 MHz" + platform_clock: "Variable" + memory: "256 KB SRAM / 16 MB DRAM" + audio_interfaces: + - "2 x TDM Out" + - "1 x TDM In" + - "DMIC" + ipc_versions: + - IPC3 + - IPC4 + zephyr_target: mtk_mt8195 + target_alias: mt8195 + status: Mainline Supported + + - id: mtk_mt8186 + vendor: MediaTek + family: MT8186 + name: MediaTek MT8186 + dsp_arch: Xtensa HiFi5 + cores: 1 + clock_range: "300 - 800 MHz" + platform_clock: "Variable" + memory: "512 KB SRAM / DRAM" + audio_interfaces: + - "2 x I2S Out" + - "1 x I2S In" + - "DMIC" + ipc_versions: + - IPC3 + - IPC4 + zephyr_target: mtk_mt8186 + target_alias: mt8186 + status: Mainline Supported + + - id: mtk_mt8188 + vendor: MediaTek + family: MT8188 + name: MediaTek MT8188 + dsp_arch: Xtensa HiFi5 + cores: 1 + clock_range: "26 - 800 MHz" + platform_clock: "Variable" + memory: "512 KB SRAM / 17 MB DRAM" + audio_interfaces: + - "2 x TDM Out" + - "1 x TDM In" + - "DMIC" + ipc_versions: + - IPC3 + - IPC4 + zephyr_target: mtk_mt8188 + target_alias: mt8188 + status: Mainline Supported + + - id: mtk_mt8196 + vendor: MediaTek + family: MT8196 + name: MediaTek MT8196 + dsp_arch: Xtensa HiFi5 + cores: 1 + clock_range: "26 - 800 MHz" + platform_clock: "Variable" + memory: "SRAM / DRAM" + audio_interfaces: + - "TDM" + - "I2S" + - "DMIC" + ipc_versions: + - IPC4 + zephyr_target: mtk_mt8196 + target_alias: mt8196 + status: Active Development + + - id: teensy_41 + vendor: PJRC / NXP + family: i.MX RT1062 + name: Teensy 4.1 Audio DSP + dsp_arch: ARM Cortex-M7 (FPU + DSP instructions) + cores: 1 + clock_range: "600 MHz" + platform_clock: "24 MHz OSC" + memory: "1024 KB On-chip RAM / 8 MB PSRAM / 16 MB Flash" + audio_interfaces: + - "I2S / SAI (Controller / Target)" + - "PDM Digital Microphone" + - "S/PDIF" + - "USB Audio 2.0 High-Speed Device/Host" + ipc_versions: + - N/A + zephyr_target: teensy41 + target_alias: teensy41 + status: Active Integration + notes: "Direct microcontroller audio processing and hardware-in-the-loop bridge" + + - id: esp32_p4 + vendor: Espressif + family: ESP32-P4 + name: ESP32-P4 Audio Bridge & Loopback Card + dsp_arch: RISC-V Dual-Core HP + FPU + cores: 2 + clock_range: "400 MHz" + platform_clock: "40 MHz XTAL" + memory: "768 KB HP SRAM / 16-32 MB PSRAM" + audio_interfaces: + - "I2S (Controller & Target mode, configurable MCLK/BCLK/WS)" + - "PDM (Controller & Target stereo PDM Tx/Rx)" + - "High-Speed USB Audio Bridge" + ipc_versions: + - N/A + zephyr_target: esp32p4 + target_alias: esp32-p4 + test_dut: "Pallas (Tx) / Ceres (Rx) Loopback Pair" + status: Active Integration + notes: "Essential test card for automated I2S/PDM loopback verification across Spider and Aphid" + + - id: qemu_sim + vendor: Emulation + family: Simulation + name: QEMU DSP Simulator (ptl-sim, tgl-sim) + dsp_arch: Xtensa HiFi3 / HiFi4 / HiFi5 + cores: "1 - 4" + clock_range: "Host Virtual Clock" + platform_clock: "N/A" + memory: "Simulated SRAM & Shared Host Memory" + audio_interfaces: + - "DMA File Sink / Source" + - "Virtual IPC Mailbox" + ipc_versions: + - IPC3 + - IPC4 + zephyr_target: native_sim / qemu_xtensa + target_alias: sim + status: Mainline Active + notes: "Enables headless CI pipeline validation and developer unit testing without physical silicon" diff --git a/data/sof_bin_releases.json b/data/sof_bin_releases.json new file mode 100644 index 00000000..2b48bc28 --- /dev/null +++ b/data/sof_bin_releases.json @@ -0,0 +1,122 @@ +[ + { + "tag_name": "v2025.12.2", + "name": "v2025.12.2", + "published_at": "2026-01-27", + "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.12.2", + "asset_name": "sof-bin-2025.12.2.tar.gz", + "asset_url": "https://github.com/thesofproject/sof-bin/releases/download/v2025.12.2/sof-bin-2025.12.2.tar.gz", + "asset_size_mb": 12.9, + "prerelease": false + }, + { + "tag_name": "v2025.12.1", + "name": "v2025.12.1", + "published_at": "2026-01-22", + "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.12.1", + "asset_name": "sof-bin-2025.12.1.tar.gz", + "asset_url": "https://github.com/thesofproject/sof-bin/releases/download/v2025.12.1/sof-bin-2025.12.1.tar.gz", + "asset_size_mb": 12.9, + "prerelease": false + }, + { + "tag_name": "v2025.12", + "name": "v2025.12", + "published_at": "2025-12-19", + "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.12", + "asset_name": "sof-bin-2025.12.tar.gz", + "asset_url": "https://github.com/thesofproject/sof-bin/releases/download/v2025.12/sof-bin-2025.12.tar.gz", + "asset_size_mb": 12.8, + "prerelease": false + }, + { + "tag_name": "v2025.05.1", + "name": "v2025.05.1", + "published_at": "2025-08-19", + "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.05.1", + "asset_name": "sof-bin-2025.05.1.tar.gz", + "asset_url": "https://github.com/thesofproject/sof-bin/releases/download/v2025.05.1/sof-bin-2025.05.1.tar.gz", + "asset_size_mb": 11.3, + "prerelease": false + }, + { + "tag_name": "v2025.05", + "name": "v2025.05", + "published_at": "2025-06-13", + "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.05", + "asset_name": "sof-bin-2025.05.tar.gz", + "asset_url": "https://github.com/thesofproject/sof-bin/releases/download/v2025.05/sof-bin-2025.05.tar.gz", + "asset_size_mb": 11.3, + "prerelease": false + }, + { + "tag_name": "v2025.01.1", + "name": "v2025.01.1", + "published_at": "2025-03-31", + "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.01.1", + "asset_name": "sof-bin-2025.01.1.tar.gz", + "asset_url": "https://github.com/thesofproject/sof-bin/releases/download/v2025.01.1/sof-bin-2025.01.1.tar.gz", + "asset_size_mb": 10.0, + "prerelease": false + }, + { + "tag_name": "v2025.01", + "name": "v2025.01", + "published_at": "2025-01-31", + "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.01", + "asset_name": "sof-bin-2025.01.tar.gz", + "asset_url": "https://github.com/thesofproject/sof-bin/releases/download/v2025.01/sof-bin-2025.01.tar.gz", + "asset_size_mb": 10.0, + "prerelease": false + }, + { + "tag_name": "v2024.09.2", + "name": "v2024.09.2", + "published_at": "2024-12-05", + "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2024.09.2", + "asset_name": "sof-bin-2024.09.2.tar.gz", + "asset_url": "https://github.com/thesofproject/sof-bin/releases/download/v2024.09.2/sof-bin-2024.09.2.tar.gz", + "asset_size_mb": 9.7, + "prerelease": false + }, + { + "tag_name": "v2024.09.1", + "name": "v2024.09.1", + "published_at": "2024-11-08", + "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2024.09.1", + "asset_name": "sof-bin-2024.09.1.tar.gz", + "asset_url": "https://github.com/thesofproject/sof-bin/releases/download/v2024.09.1/sof-bin-2024.09.1.tar.gz", + "asset_size_mb": 9.7, + "prerelease": false + }, + { + "tag_name": "v2024.09", + "name": "v2024.09", + "published_at": "2024-09-27", + "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2024.09", + "asset_name": "sof-bin-2024.09.tar.gz", + "asset_url": "https://github.com/thesofproject/sof-bin/releases/download/v2024.09/sof-bin-2024.09.tar.gz", + "asset_size_mb": 9.7, + "prerelease": false + }, + { + "tag_name": "v2024.06", + "name": "v2024.06", + "published_at": "2024-07-18", + "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2024.06", + "asset_name": "sof-bin-2024.06.tar.gz", + "asset_url": "https://github.com/thesofproject/sof-bin/releases/download/v2024.06/sof-bin-2024.06.tar.gz", + "asset_size_mb": 9.4, + "prerelease": false + }, + { + "tag_name": "v2024.03", + "name": "v2024.03", + "published_at": "2024-04-02", + "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2024.03", + "asset_name": "sof-bin-2024.03.tar.gz", + "asset_url": "https://github.com/thesofproject/sof-bin/releases/download/v2024.03/sof-bin-2024.03.tar.gz", + "asset_size_mb": 7.8, + "prerelease": false + } +] \ No newline at end of file diff --git a/algos/demux/demux.rst b/developer_guides/algorithms/demux/demux.rst similarity index 100% rename from algos/demux/demux.rst rename to developer_guides/algorithms/demux/demux.rst diff --git a/algos/demux/images/demux.png b/developer_guides/algorithms/demux/images/demux.png similarity index 100% rename from algos/demux/images/demux.png rename to developer_guides/algorithms/demux/images/demux.png diff --git a/algos/demux/images/mux.png b/developer_guides/algorithms/demux/images/mux.png similarity index 100% rename from algos/demux/images/mux.png rename to developer_guides/algorithms/demux/images/mux.png diff --git a/algos/demux/images/muxdemux.png b/developer_guides/algorithms/demux/images/muxdemux.png similarity index 100% rename from algos/demux/images/muxdemux.png rename to developer_guides/algorithms/demux/images/muxdemux.png diff --git a/algos/eq/Picture_FIR_equalized_response.png b/developer_guides/algorithms/eq/Picture_FIR_equalized_response.png similarity index 100% rename from algos/eq/Picture_FIR_equalized_response.png rename to developer_guides/algorithms/eq/Picture_FIR_equalized_response.png diff --git a/algos/eq/Picture_FIR_impulse_response.png b/developer_guides/algorithms/eq/Picture_FIR_impulse_response.png similarity index 100% rename from algos/eq/Picture_FIR_impulse_response.png rename to developer_guides/algorithms/eq/Picture_FIR_impulse_response.png diff --git a/algos/eq/Picture_FIR_response.png b/developer_guides/algorithms/eq/Picture_FIR_response.png similarity index 100% rename from algos/eq/Picture_FIR_response.png rename to developer_guides/algorithms/eq/Picture_FIR_response.png diff --git a/algos/eq/Picture_FIR_response_absolute.png b/developer_guides/algorithms/eq/Picture_FIR_response_absolute.png similarity index 100% rename from algos/eq/Picture_FIR_response_absolute.png rename to developer_guides/algorithms/eq/Picture_FIR_response_absolute.png diff --git a/algos/eq/Picture_FIR_right_channel_equalized.png b/developer_guides/algorithms/eq/Picture_FIR_right_channel_equalized.png similarity index 100% rename from algos/eq/Picture_FIR_right_channel_equalized.png rename to developer_guides/algorithms/eq/Picture_FIR_right_channel_equalized.png diff --git a/algos/eq/Picture_IIR_FIR_target_vs_achieved_response.png b/developer_guides/algorithms/eq/Picture_IIR_FIR_target_vs_achieved_response.png similarity index 100% rename from algos/eq/Picture_IIR_FIR_target_vs_achieved_response.png rename to developer_guides/algorithms/eq/Picture_IIR_FIR_target_vs_achieved_response.png diff --git a/algos/eq/Picture_iir_absolute_response.png b/developer_guides/algorithms/eq/Picture_iir_absolute_response.png similarity index 100% rename from algos/eq/Picture_iir_absolute_response.png rename to developer_guides/algorithms/eq/Picture_iir_absolute_response.png diff --git a/algos/eq/Picture_iir_filter_response_vs_ideal_target.png b/developer_guides/algorithms/eq/Picture_iir_filter_response_vs_ideal_target.png similarity index 100% rename from algos/eq/Picture_iir_filter_response_vs_ideal_target.png rename to developer_guides/algorithms/eq/Picture_iir_filter_response_vs_ideal_target.png diff --git a/algos/eq/Picture_iir_impulse_response.png b/developer_guides/algorithms/eq/Picture_iir_impulse_response.png similarity index 100% rename from algos/eq/Picture_iir_impulse_response.png rename to developer_guides/algorithms/eq/Picture_iir_impulse_response.png diff --git a/algos/eq/Picture_iir_poles_and_zeros.png b/developer_guides/algorithms/eq/Picture_iir_poles_and_zeros.png similarity index 100% rename from algos/eq/Picture_iir_poles_and_zeros.png rename to developer_guides/algorithms/eq/Picture_iir_poles_and_zeros.png diff --git a/algos/eq/Picture_iir_simulated_left_and_channel_responses.png b/developer_guides/algorithms/eq/Picture_iir_simulated_left_and_channel_responses.png similarity index 100% rename from algos/eq/Picture_iir_simulated_left_and_channel_responses.png rename to developer_guides/algorithms/eq/Picture_iir_simulated_left_and_channel_responses.png diff --git a/algos/eq/Picture_imported_frequency_response_for_iir.png b/developer_guides/algorithms/eq/Picture_imported_frequency_response_for_iir.png similarity index 100% rename from algos/eq/Picture_imported_frequency_response_for_iir.png rename to developer_guides/algorithms/eq/Picture_imported_frequency_response_for_iir.png diff --git a/algos/eq/Picture_raw_frequency_response.png b/developer_guides/algorithms/eq/Picture_raw_frequency_response.png similarity index 100% rename from algos/eq/Picture_raw_frequency_response.png rename to developer_guides/algorithms/eq/Picture_raw_frequency_response.png diff --git a/algos/eq/Picture_response_with_smoothing.png b/developer_guides/algorithms/eq/Picture_response_with_smoothing.png similarity index 100% rename from algos/eq/Picture_response_with_smoothing.png rename to developer_guides/algorithms/eq/Picture_response_with_smoothing.png diff --git a/algos/eq/Picture_right_channel_FIR_absolute_response.png b/developer_guides/algorithms/eq/Picture_right_channel_FIR_absolute_response.png similarity index 100% rename from algos/eq/Picture_right_channel_FIR_absolute_response.png rename to developer_guides/algorithms/eq/Picture_right_channel_FIR_absolute_response.png diff --git a/algos/eq/Picture_right_channel_response.png b/developer_guides/algorithms/eq/Picture_right_channel_response.png similarity index 100% rename from algos/eq/Picture_right_channel_response.png rename to developer_guides/algorithms/eq/Picture_right_channel_response.png diff --git a/algos/eq/Picture_simulated_IIR_FIR_frequency_response.png b/developer_guides/algorithms/eq/Picture_simulated_IIR_FIR_frequency_response.png similarity index 100% rename from algos/eq/Picture_simulated_IIR_FIR_frequency_response.png rename to developer_guides/algorithms/eq/Picture_simulated_IIR_FIR_frequency_response.png diff --git a/algos/eq/Picture_simulated_left_and_right_channel_responses.png b/developer_guides/algorithms/eq/Picture_simulated_left_and_right_channel_responses.png similarity index 100% rename from algos/eq/Picture_simulated_left_and_right_channel_responses.png rename to developer_guides/algorithms/eq/Picture_simulated_left_and_right_channel_responses.png diff --git a/algos/eq/Picture_speaker_meas.jpg b/developer_guides/algorithms/eq/Picture_speaker_meas.jpg similarity index 100% rename from algos/eq/Picture_speaker_meas.jpg rename to developer_guides/algorithms/eq/Picture_speaker_meas.jpg diff --git a/algos/eq/Picture_tested_speaker_frequency_response.png b/developer_guides/algorithms/eq/Picture_tested_speaker_frequency_response.png similarity index 100% rename from algos/eq/Picture_tested_speaker_frequency_response.png rename to developer_guides/algorithms/eq/Picture_tested_speaker_frequency_response.png diff --git a/algos/eq/equalizers_tuning.rst b/developer_guides/algorithms/eq/equalizers_tuning.rst similarity index 100% rename from algos/eq/equalizers_tuning.rst rename to developer_guides/algorithms/eq/equalizers_tuning.rst diff --git a/algos/src/images/equiripple.png b/developer_guides/algorithms/src/images/equiripple.png similarity index 100% rename from algos/src/images/equiripple.png rename to developer_guides/algorithms/src/images/equiripple.png diff --git a/algos/src/images/kaiser.png b/developer_guides/algorithms/src/images/kaiser.png similarity index 100% rename from algos/src/images/kaiser.png rename to developer_guides/algorithms/src/images/kaiser.png diff --git a/algos/src/images/poly32.png b/developer_guides/algorithms/src/images/poly32.png similarity index 100% rename from algos/src/images/poly32.png rename to developer_guides/algorithms/src/images/poly32.png diff --git a/algos/src/images/poly34.png b/developer_guides/algorithms/src/images/poly34.png similarity index 100% rename from algos/src/images/poly34.png rename to developer_guides/algorithms/src/images/poly34.png diff --git a/algos/src/sample_rate_conversion.rst b/developer_guides/algorithms/src/sample_rate_conversion.rst similarity index 100% rename from algos/src/sample_rate_conversion.rst rename to developer_guides/algorithms/src/sample_rate_conversion.rst diff --git a/algos/src/src_2stage.txt b/developer_guides/algorithms/src/src_2stage.txt similarity index 100% rename from algos/src/src_2stage.txt rename to developer_guides/algorithms/src/src_2stage.txt diff --git a/algos/src/src_std_int32_table.h b/developer_guides/algorithms/src/src_std_int32_table.h similarity index 100% rename from algos/src/src_std_int32_table.h rename to developer_guides/algorithms/src/src_std_int32_table.h diff --git a/algos/tdfb/beamformer_delay_and_sum.png b/developer_guides/algorithms/tdfb/beamformer_delay_and_sum.png similarity index 100% rename from algos/tdfb/beamformer_delay_and_sum.png rename to developer_guides/algorithms/tdfb/beamformer_delay_and_sum.png diff --git a/algos/tdfb/circular_array.png b/developer_guides/algorithms/tdfb/circular_array.png similarity index 100% rename from algos/tdfb/circular_array.png rename to developer_guides/algorithms/tdfb/circular_array.png diff --git a/algos/tdfb/circular_di.png b/developer_guides/algorithms/tdfb/circular_di.png similarity index 100% rename from algos/tdfb/circular_di.png rename to developer_guides/algorithms/tdfb/circular_di.png diff --git a/algos/tdfb/circular_filters.png b/developer_guides/algorithms/tdfb/circular_filters.png similarity index 100% rename from algos/tdfb/circular_filters.png rename to developer_guides/algorithms/tdfb/circular_filters.png diff --git a/algos/tdfb/circular_polar.png b/developer_guides/algorithms/tdfb/circular_polar.png similarity index 100% rename from algos/tdfb/circular_polar.png rename to developer_guides/algorithms/tdfb/circular_polar.png diff --git a/algos/tdfb/circular_spatial.png b/developer_guides/algorithms/tdfb/circular_spatial.png similarity index 100% rename from algos/tdfb/circular_spatial.png rename to developer_guides/algorithms/tdfb/circular_spatial.png diff --git a/algos/tdfb/circular_wng.png b/developer_guides/algorithms/tdfb/circular_wng.png similarity index 100% rename from algos/tdfb/circular_wng.png rename to developer_guides/algorithms/tdfb/circular_wng.png diff --git a/algos/tdfb/line_array.png b/developer_guides/algorithms/tdfb/line_array.png similarity index 100% rename from algos/tdfb/line_array.png rename to developer_guides/algorithms/tdfb/line_array.png diff --git a/algos/tdfb/lshape_array.png b/developer_guides/algorithms/tdfb/lshape_array.png similarity index 100% rename from algos/tdfb/lshape_array.png rename to developer_guides/algorithms/tdfb/lshape_array.png diff --git a/algos/tdfb/lshape_array_rot.png b/developer_guides/algorithms/tdfb/lshape_array_rot.png similarity index 100% rename from algos/tdfb/lshape_array_rot.png rename to developer_guides/algorithms/tdfb/lshape_array_rot.png diff --git a/algos/tdfb/rectangular_array.png b/developer_guides/algorithms/tdfb/rectangular_array.png similarity index 100% rename from algos/tdfb/rectangular_array.png rename to developer_guides/algorithms/tdfb/rectangular_array.png diff --git a/algos/tdfb/time_domain_fixed_beamformer.rst b/developer_guides/algorithms/tdfb/time_domain_fixed_beamformer.rst similarity index 100% rename from algos/tdfb/time_domain_fixed_beamformer.rst rename to developer_guides/algorithms/tdfb/time_domain_fixed_beamformer.rst diff --git a/algos/tdfb/two_beams_left.png b/developer_guides/algorithms/tdfb/two_beams_left.png similarity index 100% rename from algos/tdfb/two_beams_left.png rename to developer_guides/algorithms/tdfb/two_beams_left.png diff --git a/algos/tdfb/two_beams_right.png b/developer_guides/algorithms/tdfb/two_beams_right.png similarity index 100% rename from algos/tdfb/two_beams_right.png rename to developer_guides/algorithms/tdfb/two_beams_right.png diff --git a/algos/tdfb/xyz_array.png b/developer_guides/algorithms/tdfb/xyz_array.png similarity index 100% rename from algos/tdfb/xyz_array.png rename to developer_guides/algorithms/tdfb/xyz_array.png diff --git a/developer_guides/index.rst b/developer_guides/index.rst index 5ac976e5..854e6716 100644 --- a/developer_guides/index.rst +++ b/developer_guides/index.rst @@ -36,3 +36,97 @@ Some how-to technical notes that help explain how you can use SOF capabilities. tech/build-cmocka tech/compile_wsl + +Remote Deployment with ktest +**************************** + +Set up a target device and environment to deploy and test kernels over SSH using ``ktest``. + +.. toctree:: + :maxdepth: 1 + + ktest/setup_ktest_environment + +Set up SOF on a special device +****************************** + +SOF also runs on the MinnowBoard Turbot and the Up Squared board with Hifiberry Dac+. + +.. toctree:: + :maxdepth: 1 + + setup_special_device/setup_minnowboard_turbot + setup_special_device/setup_up_2_board + +Debug Audio issues on Intel platforms +************************************* + +Intel platforms rely on different versions of DSP and audio hardware +interfaces. The following sections provide hints for integrators and +users when audio components are not working properly or are broken. + +.. toctree:: + :maxdepth: 1 + + intel_debug/introduction + intel_debug/suggestions + +SOF on NXP platforms +******************** + +This section provides guides for integrators and for users working with i.MX platforms. + +.. toctree:: + :maxdepth: 1 + + nxp/sof_imx_user_guide + +Building loadable modules using LMDK +************************************ + +This section describes the process of building loadable modules using LMDK. + +.. toctree:: + :maxdepth: 1 + + loadable_modules/lmdk_user_guide + +.. _subsystem-architecture-guides: + +Detailed Subsystem Architecture Guides +************************************** + +For in-depth implementation specifications, driver models, and platform-specific firmware layers, consult the dedicated architectural guides below: + +.. toctree:: + :maxdepth: 2 + + subsystem_architecture/host/index + subsystem_architecture/firmware/index + +Platform Specific Information +***************************** + +Further information on specific platforms can be found here. + +.. toctree:: + :maxdepth: 2 + + intel-legacy/index + intel-cavs/index + +.. _algorithm-specific-information: + +Algorithm Specific Information +****************************** + +Further information on specific algorithms, filter tuning, and design tools: + +.. toctree:: + :maxdepth: 1 + + algorithms/demux/demux.rst + algorithms/eq/equalizers_tuning + algorithms/src/sample_rate_conversion + algorithms/tdfb/time_domain_fixed_beamformer + diff --git a/platforms/intel-cavs/apollolake/apl-memory.rst b/developer_guides/intel-cavs/apollolake/apl-memory.rst similarity index 100% rename from platforms/intel-cavs/apollolake/apl-memory.rst rename to developer_guides/intel-cavs/apollolake/apl-memory.rst diff --git a/platforms/intel-cavs/apollolake/images/apl-memory.dot b/developer_guides/intel-cavs/apollolake/images/apl-memory.dot similarity index 100% rename from platforms/intel-cavs/apollolake/images/apl-memory.dot rename to developer_guides/intel-cavs/apollolake/images/apl-memory.dot diff --git a/platforms/intel-cavs/apollolake/index.rst b/developer_guides/intel-cavs/apollolake/index.rst similarity index 100% rename from platforms/intel-cavs/apollolake/index.rst rename to developer_guides/intel-cavs/apollolake/index.rst diff --git a/platforms/intel-cavs/cannonlake/cnl-config.rst b/developer_guides/intel-cavs/cannonlake/cnl-config.rst similarity index 100% rename from platforms/intel-cavs/cannonlake/cnl-config.rst rename to developer_guides/intel-cavs/cannonlake/cnl-config.rst diff --git a/platforms/intel-cavs/cannonlake/cnl-memory.rst b/developer_guides/intel-cavs/cannonlake/cnl-memory.rst similarity index 100% rename from platforms/intel-cavs/cannonlake/cnl-memory.rst rename to developer_guides/intel-cavs/cannonlake/cnl-memory.rst diff --git a/platforms/intel-cavs/cannonlake/images/cnl-memory.dot b/developer_guides/intel-cavs/cannonlake/images/cnl-memory.dot similarity index 100% rename from platforms/intel-cavs/cannonlake/images/cnl-memory.dot rename to developer_guides/intel-cavs/cannonlake/images/cnl-memory.dot diff --git a/platforms/intel-cavs/cannonlake/index.rst b/developer_guides/intel-cavs/cannonlake/index.rst similarity index 100% rename from platforms/intel-cavs/cannonlake/index.rst rename to developer_guides/intel-cavs/cannonlake/index.rst diff --git a/platforms/intel-cavs/commons/images/core-enable.pu b/developer_guides/intel-cavs/commons/images/core-enable.pu similarity index 100% rename from platforms/intel-cavs/commons/images/core-enable.pu rename to developer_guides/intel-cavs/commons/images/core-enable.pu diff --git a/platforms/intel-cavs/commons/images/work-smp-cavs.pu b/developer_guides/intel-cavs/commons/images/work-smp-cavs.pu similarity index 100% rename from platforms/intel-cavs/commons/images/work-smp-cavs.pu rename to developer_guides/intel-cavs/commons/images/work-smp-cavs.pu diff --git a/platforms/intel-cavs/commons/images/work-st.pu b/developer_guides/intel-cavs/commons/images/work-st.pu similarity index 100% rename from platforms/intel-cavs/commons/images/work-st.pu rename to developer_guides/intel-cavs/commons/images/work-st.pu diff --git a/platforms/intel-cavs/commons/index.rst b/developer_guides/intel-cavs/commons/index.rst similarity index 100% rename from platforms/intel-cavs/commons/index.rst rename to developer_guides/intel-cavs/commons/index.rst diff --git a/platforms/intel-cavs/commons/multicore-processing.rst b/developer_guides/intel-cavs/commons/multicore-processing.rst similarity index 100% rename from platforms/intel-cavs/commons/multicore-processing.rst rename to developer_guides/intel-cavs/commons/multicore-processing.rst diff --git a/platforms/intel-cavs/commons/work-queue.rst b/developer_guides/intel-cavs/commons/work-queue.rst similarity index 100% rename from platforms/intel-cavs/commons/work-queue.rst rename to developer_guides/intel-cavs/commons/work-queue.rst diff --git a/platforms/intel-cavs/icelake/icl-config.rst b/developer_guides/intel-cavs/icelake/icl-config.rst similarity index 100% rename from platforms/intel-cavs/icelake/icl-config.rst rename to developer_guides/intel-cavs/icelake/icl-config.rst diff --git a/platforms/intel-cavs/icelake/icl-memory.rst b/developer_guides/intel-cavs/icelake/icl-memory.rst similarity index 100% rename from platforms/intel-cavs/icelake/icl-memory.rst rename to developer_guides/intel-cavs/icelake/icl-memory.rst diff --git a/platforms/intel-cavs/icelake/index.rst b/developer_guides/intel-cavs/icelake/index.rst similarity index 100% rename from platforms/intel-cavs/icelake/index.rst rename to developer_guides/intel-cavs/icelake/index.rst diff --git a/platforms/intel-cavs/images/cavs-platform-deps.pu b/developer_guides/intel-cavs/images/cavs-platform-deps.pu similarity index 100% rename from platforms/intel-cavs/images/cavs-platform-deps.pu rename to developer_guides/intel-cavs/images/cavs-platform-deps.pu diff --git a/platforms/intel-cavs/index.rst b/developer_guides/intel-cavs/index.rst similarity index 100% rename from platforms/intel-cavs/index.rst rename to developer_guides/intel-cavs/index.rst diff --git a/platforms/intel-cavs/tigerlake/images/tgl-memory.dot b/developer_guides/intel-cavs/tigerlake/images/tgl-memory.dot similarity index 100% rename from platforms/intel-cavs/tigerlake/images/tgl-memory.dot rename to developer_guides/intel-cavs/tigerlake/images/tgl-memory.dot diff --git a/platforms/intel-cavs/tigerlake/index.rst b/developer_guides/intel-cavs/tigerlake/index.rst similarity index 100% rename from platforms/intel-cavs/tigerlake/index.rst rename to developer_guides/intel-cavs/tigerlake/index.rst diff --git a/platforms/intel-cavs/tigerlake/tgl-config.rst b/developer_guides/intel-cavs/tigerlake/tgl-config.rst similarity index 100% rename from platforms/intel-cavs/tigerlake/tgl-config.rst rename to developer_guides/intel-cavs/tigerlake/tgl-config.rst diff --git a/platforms/intel-cavs/tigerlake/tgl-memory.rst b/developer_guides/intel-cavs/tigerlake/tgl-memory.rst similarity index 100% rename from platforms/intel-cavs/tigerlake/tgl-memory.rst rename to developer_guides/intel-cavs/tigerlake/tgl-memory.rst diff --git a/platforms/intel-legacy/baytrail/index.rst b/developer_guides/intel-legacy/baytrail/index.rst similarity index 100% rename from platforms/intel-legacy/baytrail/index.rst rename to developer_guides/intel-legacy/baytrail/index.rst diff --git a/platforms/intel-legacy/broadwell/index.rst b/developer_guides/intel-legacy/broadwell/index.rst similarity index 100% rename from platforms/intel-legacy/broadwell/index.rst rename to developer_guides/intel-legacy/broadwell/index.rst diff --git a/platforms/intel-legacy/index.rst b/developer_guides/intel-legacy/index.rst similarity index 100% rename from platforms/intel-legacy/index.rst rename to developer_guides/intel-legacy/index.rst diff --git a/platforms/intel-legacy/merrifield/index.rst b/developer_guides/intel-legacy/merrifield/index.rst similarity index 100% rename from platforms/intel-legacy/merrifield/index.rst rename to developer_guides/intel-legacy/merrifield/index.rst diff --git a/getting_started/intel_debug/introduction.rst b/developer_guides/intel_debug/introduction.rst similarity index 100% rename from getting_started/intel_debug/introduction.rst rename to developer_guides/intel_debug/introduction.rst diff --git a/getting_started/intel_debug/suggestions.rst b/developer_guides/intel_debug/suggestions.rst similarity index 100% rename from getting_started/intel_debug/suggestions.rst rename to developer_guides/intel_debug/suggestions.rst diff --git a/getting_started/setup_linux/setup_ktest_environment.rst b/developer_guides/ktest/setup_ktest_environment.rst similarity index 98% rename from getting_started/setup_linux/setup_ktest_environment.rst rename to developer_guides/ktest/setup_ktest_environment.rst index 2836890c..ed7bc90e 100644 --- a/getting_started/setup_linux/setup_ktest_environment.rst +++ b/developer_guides/ktest/setup_ktest_environment.rst @@ -251,11 +251,11 @@ Configure SSH without password Build and install the kernel with ktest *************************************** -Follow the `prepare build environment `_ instructions before proceeding. +Follow the :ref:`prepare build environment ` instructions before proceeding. 1. Prepare the ktest environment. - If you run this in a different terminal than you used for the `prepare build environment `_ instructions, you need to re-set the SOF_WORKSPACE variable by running ``export SOF_WORKSPACE = ~/work/sof``. + If you run this in a different terminal than you used for the :ref:`prepare build environment ` instructions, you need to re-set the SOF_WORKSPACE variable by running ``export SOF_WORKSPACE=~/work/sof``. .. code-block:: bash diff --git a/getting_started/loadable_modules/lmdk_user_guide.rst b/developer_guides/loadable_modules/lmdk_user_guide.rst similarity index 100% rename from getting_started/loadable_modules/lmdk_user_guide.rst rename to developer_guides/loadable_modules/lmdk_user_guide.rst diff --git a/getting_started/nxp/sof_imx_user_guide.rst b/developer_guides/nxp/sof_imx_user_guide.rst similarity index 100% rename from getting_started/nxp/sof_imx_user_guide.rst rename to developer_guides/nxp/sof_imx_user_guide.rst diff --git a/getting_started/setup_special_device/images/minnow_turbot.png b/developer_guides/setup_special_device/images/minnow_turbot.png similarity index 100% rename from getting_started/setup_special_device/images/minnow_turbot.png rename to developer_guides/setup_special_device/images/minnow_turbot.png diff --git a/getting_started/setup_special_device/setup_minnowboard_turbot.rst b/developer_guides/setup_special_device/setup_minnowboard_turbot.rst similarity index 100% rename from getting_started/setup_special_device/setup_minnowboard_turbot.rst rename to developer_guides/setup_special_device/setup_minnowboard_turbot.rst diff --git a/getting_started/setup_special_device/setup_up_2_board.rst b/developer_guides/setup_special_device/setup_up_2_board.rst similarity index 98% rename from getting_started/setup_special_device/setup_up_2_board.rst rename to developer_guides/setup_special_device/setup_up_2_board.rst index 091eb418..e4f36c6f 100644 --- a/getting_started/setup_special_device/setup_up_2_board.rst +++ b/developer_guides/setup_special_device/setup_up_2_board.rst @@ -54,7 +54,7 @@ guide, if needed. 3. Update kernel ================ -Follow :ref:`Build Linux kernel` section +Follow the :ref:`install-locally` guide. 4. Firmware =========== diff --git a/architectures/firmware/index.rst b/developer_guides/subsystem_architecture/firmware/index.rst similarity index 64% rename from architectures/firmware/index.rst rename to developer_guides/subsystem_architecture/firmware/index.rst index 86c79454..646d15fd 100644 --- a/architectures/firmware/index.rst +++ b/developer_guides/subsystem_architecture/firmware/index.rst @@ -3,6 +3,8 @@ Firmware Architecture ##################### +For the high-level system, hostless, and audio pipeline architectures, see :ref:`architectures`. + .. toctree:: :maxdepth: 1 diff --git a/architectures/firmware/intel/ace/iadk_modules.rst b/developer_guides/subsystem_architecture/firmware/intel/ace/iadk_modules.rst similarity index 100% rename from architectures/firmware/intel/ace/iadk_modules.rst rename to developer_guides/subsystem_architecture/firmware/intel/ace/iadk_modules.rst diff --git a/architectures/firmware/intel/ace/index.rst b/developer_guides/subsystem_architecture/firmware/intel/ace/index.rst similarity index 100% rename from architectures/firmware/intel/ace/index.rst rename to developer_guides/subsystem_architecture/firmware/intel/ace/index.rst diff --git a/architectures/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-ldr.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-ldr.rst similarity index 100% rename from architectures/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-ldr.rst rename to developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-ldr.rst diff --git a/architectures/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-rom.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-rom.rst similarity index 100% rename from architectures/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-rom.rst rename to developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-rom.rst diff --git a/architectures/firmware/intel/cavs/cavs-boot/apollolake/images/apl-rom-flow.pu b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/images/apl-rom-flow.pu similarity index 100% rename from architectures/firmware/intel/cavs/cavs-boot/apollolake/images/apl-rom-flow.pu rename to developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/images/apl-rom-flow.pu diff --git a/architectures/firmware/intel/cavs/cavs-boot/apollolake/index.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/index.rst similarity index 100% rename from architectures/firmware/intel/cavs/cavs-boot/apollolake/index.rst rename to developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/index.rst diff --git a/architectures/firmware/intel/cavs/cavs-boot/cavs-dsp-boot-overview.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/cavs-dsp-boot-overview.rst similarity index 100% rename from architectures/firmware/intel/cavs/cavs-boot/cavs-dsp-boot-overview.rst rename to developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/cavs-dsp-boot-overview.rst diff --git a/architectures/firmware/intel/cavs/cavs-boot/images/boot-dsp.pu b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/boot-dsp.pu similarity index 100% rename from architectures/firmware/intel/cavs/cavs-boot/images/boot-dsp.pu rename to developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/boot-dsp.pu diff --git a/architectures/firmware/intel/cavs/cavs-boot/images/boot-ldr-flow.pu b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/boot-ldr-flow.pu similarity index 100% rename from architectures/firmware/intel/cavs/cavs-boot/images/boot-ldr-flow.pu rename to developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/boot-ldr-flow.pu diff --git a/architectures/firmware/intel/cavs/cavs-boot/images/loading-bins.pu b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/loading-bins.pu similarity index 100% rename from architectures/firmware/intel/cavs/cavs-boot/images/loading-bins.pu rename to developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/loading-bins.pu diff --git a/architectures/firmware/intel/cavs/cavs-boot/images/write-bin.pu b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/write-bin.pu similarity index 100% rename from architectures/firmware/intel/cavs/cavs-boot/images/write-bin.pu rename to developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/write-bin.pu diff --git a/architectures/firmware/intel/cavs/cavs-boot/index.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/index.rst similarity index 100% rename from architectures/firmware/intel/cavs/cavs-boot/index.rst rename to developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/index.rst diff --git a/architectures/firmware/intel/cavs/images/idc-send-message.pu b/developer_guides/subsystem_architecture/firmware/intel/cavs/images/idc-send-message.pu similarity index 100% rename from architectures/firmware/intel/cavs/images/idc-send-message.pu rename to developer_guides/subsystem_architecture/firmware/intel/cavs/images/idc-send-message.pu diff --git a/architectures/firmware/intel/cavs/index.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/index.rst similarity index 100% rename from architectures/firmware/intel/cavs/index.rst rename to developer_guides/subsystem_architecture/firmware/intel/cavs/index.rst diff --git a/architectures/firmware/intel/cavs/smp/index.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/smp/index.rst similarity index 100% rename from architectures/firmware/intel/cavs/smp/index.rst rename to developer_guides/subsystem_architecture/firmware/intel/cavs/smp/index.rst diff --git a/architectures/firmware/intel/index.rst b/developer_guides/subsystem_architecture/firmware/intel/index.rst similarity index 100% rename from architectures/firmware/intel/index.rst rename to developer_guides/subsystem_architecture/firmware/intel/index.rst diff --git a/architectures/firmware/sof-common/components/component-mgmt-api.rst b/developer_guides/subsystem_architecture/firmware/sof-common/components/component-mgmt-api.rst similarity index 100% rename from architectures/firmware/sof-common/components/component-mgmt-api.rst rename to developer_guides/subsystem_architecture/firmware/sof-common/components/component-mgmt-api.rst diff --git a/architectures/firmware/sof-common/components/component-module-api.rst b/developer_guides/subsystem_architecture/firmware/sof-common/components/component-module-api.rst similarity index 100% rename from architectures/firmware/sof-common/components/component-module-api.rst rename to developer_guides/subsystem_architecture/firmware/sof-common/components/component-module-api.rst diff --git a/architectures/firmware/sof-common/components/component-overview.rst b/developer_guides/subsystem_architecture/firmware/sof-common/components/component-overview.rst similarity index 100% rename from architectures/firmware/sof-common/components/component-overview.rst rename to developer_guides/subsystem_architecture/firmware/sof-common/components/component-overview.rst diff --git a/architectures/firmware/sof-common/components/images/comp-copy-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-copy-flow.pu similarity index 100% rename from architectures/firmware/sof-common/components/images/comp-copy-flow.pu rename to developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-copy-flow.pu diff --git a/architectures/firmware/sof-common/components/images/comp-dev-states.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-dev-states.pu similarity index 100% rename from architectures/firmware/sof-common/components/images/comp-dev-states.pu rename to developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-dev-states.pu diff --git a/architectures/firmware/sof-common/components/images/comp-driver.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-driver.pu similarity index 100% rename from architectures/firmware/sof-common/components/images/comp-driver.pu rename to developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-driver.pu diff --git a/architectures/firmware/sof-common/components/images/comp-module-api.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-module-api.pu similarity index 100% rename from architectures/firmware/sof-common/components/images/comp-module-api.pu rename to developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-module-api.pu diff --git a/architectures/firmware/sof-common/components/images/comp-new-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-new-flow.pu similarity index 100% rename from architectures/firmware/sof-common/components/images/comp-new-flow.pu rename to developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-new-flow.pu diff --git a/architectures/firmware/sof-common/components/images/comp-prepare-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-prepare-flow.pu similarity index 100% rename from architectures/firmware/sof-common/components/images/comp-prepare-flow.pu rename to developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-prepare-flow.pu diff --git a/architectures/firmware/sof-common/components/images/component-mgmt-api.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/component-mgmt-api.pu similarity index 100% rename from architectures/firmware/sof-common/components/images/component-mgmt-api.pu rename to developer_guides/subsystem_architecture/firmware/sof-common/components/images/component-mgmt-api.pu diff --git a/architectures/firmware/sof-common/components/index.rst b/developer_guides/subsystem_architecture/firmware/sof-common/components/index.rst similarity index 100% rename from architectures/firmware/sof-common/components/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-common/components/index.rst diff --git a/architectures/firmware/sof-common/index.rst b/developer_guides/subsystem_architecture/firmware/sof-common/index.rst similarity index 100% rename from architectures/firmware/sof-common/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-common/index.rst diff --git a/architectures/firmware/sof-xtos/drivers/dai/images/dai-ops.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/images/dai-ops.pu similarity index 100% rename from architectures/firmware/sof-xtos/drivers/dai/images/dai-ops.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/images/dai-ops.pu diff --git a/architectures/firmware/sof-xtos/drivers/dai/images/dai-set-config.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/images/dai-set-config.pu similarity index 100% rename from architectures/firmware/sof-xtos/drivers/dai/images/dai-set-config.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/images/dai-set-config.pu diff --git a/architectures/firmware/sof-xtos/drivers/dai/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/index.rst similarity index 100% rename from architectures/firmware/sof-xtos/drivers/dai/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/index.rst diff --git a/architectures/firmware/sof-xtos/drivers/dma/images/dma-ops.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/images/dma-ops.pu similarity index 100% rename from architectures/firmware/sof-xtos/drivers/dma/images/dma-ops.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/images/dma-ops.pu diff --git a/architectures/firmware/sof-xtos/drivers/dma/images/dma-transfer.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/images/dma-transfer.pu similarity index 100% rename from architectures/firmware/sof-xtos/drivers/dma/images/dma-transfer.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/images/dma-transfer.pu diff --git a/architectures/firmware/sof-xtos/drivers/dma/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/index.rst similarity index 100% rename from architectures/firmware/sof-xtos/drivers/dma/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/index.rst diff --git a/architectures/firmware/sof-xtos/drivers/dma/intel/hda-dma.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/hda-dma.rst similarity index 100% rename from architectures/firmware/sof-xtos/drivers/dma/intel/hda-dma.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/hda-dma.rst diff --git a/architectures/firmware/sof-xtos/drivers/dma/intel/images/hda-host-output.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-host-output.pu similarity index 100% rename from architectures/firmware/sof-xtos/drivers/dma/intel/images/hda-host-output.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-host-output.pu diff --git a/architectures/firmware/sof-xtos/drivers/dma/intel/images/hda-link.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-link.pu similarity index 100% rename from architectures/firmware/sof-xtos/drivers/dma/intel/images/hda-link.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-link.pu diff --git a/architectures/firmware/sof-xtos/drivers/dma/intel/images/hda-start-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-start-flow.pu similarity index 100% rename from architectures/firmware/sof-xtos/drivers/dma/intel/images/hda-start-flow.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-start-flow.pu diff --git a/architectures/firmware/sof-xtos/drivers/dma/intel/images/hda-stop-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-stop-flow.pu similarity index 100% rename from architectures/firmware/sof-xtos/drivers/dma/intel/images/hda-stop-flow.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-stop-flow.pu diff --git a/architectures/firmware/sof-xtos/drivers/dma/intel/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/index.rst similarity index 100% rename from architectures/firmware/sof-xtos/drivers/dma/intel/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/index.rst diff --git a/architectures/firmware/sof-xtos/drivers/images/device-disco.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-disco.pu similarity index 100% rename from architectures/firmware/sof-xtos/drivers/images/device-disco.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-disco.pu diff --git a/architectures/firmware/sof-xtos/drivers/images/device-probe.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-probe.pu similarity index 100% rename from architectures/firmware/sof-xtos/drivers/images/device-probe.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-probe.pu diff --git a/architectures/firmware/sof-xtos/drivers/images/device-remove.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-remove.pu similarity index 100% rename from architectures/firmware/sof-xtos/drivers/images/device-remove.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-remove.pu diff --git a/architectures/firmware/sof-xtos/drivers/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/index.rst similarity index 100% rename from architectures/firmware/sof-xtos/drivers/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/index.rst diff --git a/architectures/firmware/sof-xtos/images/edf-scheduler-deps.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/edf-scheduler-deps.pu similarity index 100% rename from architectures/firmware/sof-xtos/images/edf-scheduler-deps.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/images/edf-scheduler-deps.pu diff --git a/architectures/firmware/sof-xtos/images/edf-scheduler-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/edf-scheduler-flow.pu similarity index 100% rename from architectures/firmware/sof-xtos/images/edf-scheduler-flow.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/images/edf-scheduler-flow.pu diff --git a/architectures/firmware/sof-xtos/images/fw-arch-diag.png b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/fw-arch-diag.png similarity index 100% rename from architectures/firmware/sof-xtos/images/fw-arch-diag.png rename to developer_guides/subsystem_architecture/firmware/sof-xtos/images/fw-arch-diag.png diff --git a/architectures/firmware/sof-xtos/images/ll-scheduler-deps.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/ll-scheduler-deps.pu similarity index 100% rename from architectures/firmware/sof-xtos/images/ll-scheduler-deps.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/images/ll-scheduler-deps.pu diff --git a/architectures/firmware/sof-xtos/images/ll-scheduler-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/ll-scheduler-flow.pu similarity index 100% rename from architectures/firmware/sof-xtos/images/ll-scheduler-flow.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/images/ll-scheduler-flow.pu diff --git a/architectures/firmware/sof-xtos/images/memory-zones.dot b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/memory-zones.dot similarity index 100% rename from architectures/firmware/sof-xtos/images/memory-zones.dot rename to developer_guides/subsystem_architecture/firmware/sof-xtos/images/memory-zones.dot diff --git a/architectures/firmware/sof-xtos/images/runtime-zone.dot b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/runtime-zone.dot similarity index 100% rename from architectures/firmware/sof-xtos/images/runtime-zone.dot rename to developer_guides/subsystem_architecture/firmware/sof-xtos/images/runtime-zone.dot diff --git a/architectures/firmware/sof-xtos/images/scheduler-ops.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/scheduler-ops.pu similarity index 100% rename from architectures/firmware/sof-xtos/images/scheduler-ops.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/images/scheduler-ops.pu diff --git a/architectures/firmware/sof-xtos/images/system-zone.dot b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/system-zone.dot similarity index 100% rename from architectures/firmware/sof-xtos/images/system-zone.dot rename to developer_guides/subsystem_architecture/firmware/sof-xtos/images/system-zone.dot diff --git a/architectures/firmware/sof-xtos/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/index.rst similarity index 100% rename from architectures/firmware/sof-xtos/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/index.rst diff --git a/architectures/firmware/sof-xtos/kd_integration/images/kd-component-diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-component-diagram.pu similarity index 100% rename from architectures/firmware/sof-xtos/kd_integration/images/kd-component-diagram.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-component-diagram.pu diff --git a/architectures/firmware/sof-xtos/kd_integration/images/kd-e2e-sequence-diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-e2e-sequence-diagram.pu similarity index 100% rename from architectures/firmware/sof-xtos/kd_integration/images/kd-e2e-sequence-diagram.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-e2e-sequence-diagram.pu diff --git a/architectures/firmware/sof-xtos/kd_integration/images/kd-state-diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-state-diagram.pu similarity index 100% rename from architectures/firmware/sof-xtos/kd_integration/images/kd-state-diagram.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-state-diagram.pu diff --git a/architectures/firmware/sof-xtos/kd_integration/images/kd-timing-diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-timing-diagram.pu similarity index 100% rename from architectures/firmware/sof-xtos/kd_integration/images/kd-timing-diagram.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-timing-diagram.pu diff --git a/architectures/firmware/sof-xtos/kd_integration/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/index.rst similarity index 100% rename from architectures/firmware/sof-xtos/kd_integration/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/index.rst diff --git a/architectures/firmware/sof-xtos/kd_integration/kd-integration.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/kd-integration.rst similarity index 100% rename from architectures/firmware/sof-xtos/kd_integration/kd-integration.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/kd-integration.rst diff --git a/architectures/firmware/sof-xtos/mem-mgmt.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/mem-mgmt.rst similarity index 100% rename from architectures/firmware/sof-xtos/mem-mgmt.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/mem-mgmt.rst diff --git a/architectures/firmware/sof-xtos/overview.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/overview.rst similarity index 100% rename from architectures/firmware/sof-xtos/overview.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/overview.rst diff --git a/architectures/firmware/sof-xtos/pipelines/images/ppl-new.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-new.pu similarity index 100% rename from architectures/firmware/sof-xtos/pipelines/images/ppl-new.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-new.pu diff --git a/architectures/firmware/sof-xtos/pipelines/images/ppl-op-downstream.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-op-downstream.pu similarity index 100% rename from architectures/firmware/sof-xtos/pipelines/images/ppl-op-downstream.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-op-downstream.pu diff --git a/architectures/firmware/sof-xtos/pipelines/images/ppl-operations.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-operations.pu similarity index 100% rename from architectures/firmware/sof-xtos/pipelines/images/ppl-operations.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-operations.pu diff --git a/architectures/firmware/sof-xtos/pipelines/images/ppl-params.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-params.pu similarity index 100% rename from architectures/firmware/sof-xtos/pipelines/images/ppl-params.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-params.pu diff --git a/architectures/firmware/sof-xtos/pipelines/images/ppl-reset.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-reset.pu similarity index 100% rename from architectures/firmware/sof-xtos/pipelines/images/ppl-reset.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-reset.pu diff --git a/architectures/firmware/sof-xtos/pipelines/images/ppl-struct.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-struct.pu similarity index 100% rename from architectures/firmware/sof-xtos/pipelines/images/ppl-struct.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-struct.pu diff --git a/architectures/firmware/sof-xtos/pipelines/images/ppl-task.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-task.pu similarity index 100% rename from architectures/firmware/sof-xtos/pipelines/images/ppl-task.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-task.pu diff --git a/architectures/firmware/sof-xtos/pipelines/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/index.rst similarity index 100% rename from architectures/firmware/sof-xtos/pipelines/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/index.rst diff --git a/architectures/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-idle.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-idle.pu similarity index 100% rename from architectures/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-idle.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-idle.pu diff --git a/architectures/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-init.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-init.pu similarity index 100% rename from architectures/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-init.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-init.pu diff --git a/architectures/firmware/sof-xtos/pm-runtime/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/index.rst similarity index 100% rename from architectures/firmware/sof-xtos/pm-runtime/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/index.rst diff --git a/architectures/firmware/sof-xtos/pm-runtime/intel/images/dsp-core-lps-cavs-d0-d0i3-d0.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/intel/images/dsp-core-lps-cavs-d0-d0i3-d0.pu similarity index 100% rename from architectures/firmware/sof-xtos/pm-runtime/intel/images/dsp-core-lps-cavs-d0-d0i3-d0.pu rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/intel/images/dsp-core-lps-cavs-d0-d0i3-d0.pu diff --git a/architectures/firmware/sof-xtos/pm-runtime/intel/pm-dsp-core-cavs.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/intel/pm-dsp-core-cavs.rst similarity index 100% rename from architectures/firmware/sof-xtos/pm-runtime/intel/pm-dsp-core-cavs.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/intel/pm-dsp-core-cavs.rst diff --git a/architectures/firmware/sof-xtos/pm-runtime/pm-dsp-core.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/pm-dsp-core.rst similarity index 100% rename from architectures/firmware/sof-xtos/pm-runtime/pm-dsp-core.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/pm-dsp-core.rst diff --git a/architectures/firmware/sof-xtos/schedulers.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/schedulers.rst similarity index 100% rename from architectures/firmware/sof-xtos/schedulers.rst rename to developer_guides/subsystem_architecture/firmware/sof-xtos/schedulers.rst diff --git a/architectures/firmware/sof-zephyr/app_layer/images/app_layer_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/app_layer/images/app_layer_diagram.pu similarity index 100% rename from architectures/firmware/sof-zephyr/app_layer/images/app_layer_diagram.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/app_layer/images/app_layer_diagram.pu diff --git a/architectures/firmware/sof-zephyr/app_layer/index.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/app_layer/index.rst similarity index 100% rename from architectures/firmware/sof-zephyr/app_layer/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/app_layer/index.rst diff --git a/architectures/firmware/sof-zephyr/images/overview_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/images/overview_diagram.pu similarity index 100% rename from architectures/firmware/sof-zephyr/images/overview_diagram.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/images/overview_diagram.pu diff --git a/architectures/firmware/sof-zephyr/images/sof_lib.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/images/sof_lib.pu similarity index 100% rename from architectures/firmware/sof-zephyr/images/sof_lib.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/images/sof_lib.pu diff --git a/architectures/firmware/sof-zephyr/images/sof_lib_zephyr.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/images/sof_lib_zephyr.pu similarity index 100% rename from architectures/firmware/sof-zephyr/images/sof_lib_zephyr.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/images/sof_lib_zephyr.pu diff --git a/architectures/firmware/sof-zephyr/index.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/index.rst similarity index 100% rename from architectures/firmware/sof-zephyr/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/index.rst diff --git a/architectures/firmware/sof-zephyr/mpp_layer/async_messaging.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/async_messaging.rst similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/async_messaging.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/async_messaging.rst diff --git a/architectures/firmware/sof-zephyr/mpp_layer/dp_scheduling.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/dp_scheduling.rst similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/dp_scheduling.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/dp_scheduling.rst diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_cons_same_core.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_cons_same_core.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_cons_same_core.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_cons_same_core.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_primary_cons_secondary_core.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_primary_cons_secondary_core.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_primary_cons_secondary_core.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_primary_cons_secondary_core.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_1.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_1.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_1.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_1.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_2.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_2.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_2.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_2.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_3.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_3.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_3.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_3.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_4.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_4.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_4.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_4.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_5.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_5.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_5.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_5.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1a.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1a.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1a.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1a.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2a.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2a.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2a.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2a.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_3.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_3.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_3.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_3.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_4.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_4.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_4.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_4.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_5.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_5.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_5.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_5.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_6.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_6.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_6.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_6.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_7.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_7.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_7.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_7.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_1.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_1.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_1.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_1.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_2.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_2.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_2.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_2.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_3.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_3.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_3.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_3.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_4.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_4.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_4.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_4.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_5.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_5.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_5.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_5.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_6.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_6.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_6.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_6.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_7.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_7.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_7.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_7.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_1.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_1.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_1.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_1.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_2.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_2.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_2.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_2.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/pic1_chains.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/pic1_chains.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/pic1_chains.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/pic1_chains.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_delete_instance.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_delete_instance.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_delete_instance.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_delete_instance.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_init_instance.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_init_instance.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_init_instance.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_init_instance.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_load.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_load.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_load.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_load.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_layer_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_layer_diagram.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/mpp_layer_diagram.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_layer_diagram.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_DP_secondary_core_timeline.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_DP_secondary_core_timeline.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_DP_secondary_core_timeline.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_DP_secondary_core_timeline.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_LL_DP_timeline.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_LL_DP_timeline.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_LL_DP_timeline.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_LL_DP_timeline.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_multiple_cores_timeline.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_multiple_cores_timeline.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_multiple_cores_timeline.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_multiple_cores_timeline.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_task_with_budget.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_task_with_budget.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_task_with_budget.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_task_with_budget.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_diagram.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_diagram.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_diagram.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_threads_periodic_update.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_threads_periodic_update.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_threads_periodic_update.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_threads_periodic_update.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_zephyr.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_zephyr.pu similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_zephyr.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_zephyr.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/index.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/index.rst similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/index.rst diff --git a/architectures/firmware/sof-zephyr/mpp_layer/lib_manager.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/lib_manager.rst similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/lib_manager.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/lib_manager.rst diff --git a/architectures/firmware/sof-zephyr/mpp_layer/mpp_overview.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/mpp_overview.rst similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/mpp_overview.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/mpp_overview.rst diff --git a/architectures/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst similarity index 100% rename from architectures/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst diff --git a/architectures/firmware/sof-zephyr/overview.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/overview.rst similarity index 100% rename from architectures/firmware/sof-zephyr/overview.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/overview.rst diff --git a/architectures/firmware/sof-zephyr/rtos_layer/images/kernel_services.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/kernel_services.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/images/kernel_services.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/kernel_services.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/images/power/dsp_fw_power_states.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/dsp_fw_power_states.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/images/power/dsp_fw_power_states.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/dsp_fw_power_states.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/images/power/dx_state_transitions.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/dx_state_transitions.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/images/power/dx_state_transitions.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/dx_state_transitions.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/images/power/flow_disable_d0i3.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_disable_d0i3.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/images/power/flow_disable_d0i3.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_disable_d0i3.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/images/power/flow_dsp_idle.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_dsp_idle.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/images/power/flow_dsp_idle.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_dsp_idle.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/images/power/flow_enable_d0i3.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_enable_d0i3.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/images/power/flow_enable_d0i3.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_enable_d0i3.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/images/power/flow_primary_core_power_down.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_primary_core_power_down.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/images/power/flow_primary_core_power_down.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_primary_core_power_down.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_boot.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_boot.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_boot.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_boot.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_power_down.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_power_down.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_power_down.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_power_down.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/images/power/power_components.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/power_components.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/images/power/power_components.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/power_components.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/images/zephyr_kernel_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/zephyr_kernel_diagram.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/images/zephyr_kernel_diagram.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/zephyr_kernel_diagram.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/index.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/index.rst similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/index.rst diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/dmic_driver.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/dmic_driver.rst similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/dmic_driver.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/dmic_driver.rst diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_diagram.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_diagram.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_diagram.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_init.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_init.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_init.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_init.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_release.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_release.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_release.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_release.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_state_transitions.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_state_transitions.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_state_transitions.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_state_transitions.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/hda/hda_driver.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/hda_driver.rst similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/hda/hda_driver.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/hda_driver.rst diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_capture.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_capture.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_capture.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_capture.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_io_driver_deps.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_io_driver_deps.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_io_driver_deps.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_io_driver_deps.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_playback.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_playback.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_playback.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_playback.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_diagram.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_diagram.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_diagram.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_tdm.dot b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_tdm.dot similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_tdm.dot rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_tdm.dot diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/images/io_drivers_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/images/io_drivers_diagram.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/images/io_drivers_diagram.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/images/io_drivers_diagram.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/io_drivers/index.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/index.rst similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/io_drivers/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/index.rst diff --git a/architectures/firmware/sof-zephyr/rtos_layer/memory_management/heap_sharing.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/heap_sharing.rst similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/memory_management/heap_sharing.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/heap_sharing.rst diff --git a/architectures/firmware/sof-zephyr/rtos_layer/memory_management/images/dynamic_module_load.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/dynamic_module_load.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/memory_management/images/dynamic_module_load.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/dynamic_module_load.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/memory_management/images/heaps.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/heaps.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/memory_management/images/heaps.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/heaps.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation_from_memory_driver.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation_from_memory_driver.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation_from_memory_driver.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation_from_memory_driver.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_initialization.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_initialization.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_initialization.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_initialization.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_management_layers.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_management_layers.pu similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_management_layers.pu rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_management_layers.pu diff --git a/architectures/firmware/sof-zephyr/rtos_layer/memory_management/index.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/index.rst similarity index 65% rename from architectures/firmware/sof-zephyr/rtos_layer/memory_management/index.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/index.rst index 68d4e180..fbaddd30 100644 --- a/architectures/firmware/sof-zephyr/rtos_layer/memory_management/index.rst +++ b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/index.rst @@ -21,6 +21,15 @@ The memory support functionality is delivered at two levels: .. uml:: images/memory_management_layers.pu :caption: Example of Memory Management layers and interfaces +Memory Hierarchy & Dynamic Paging +********************************* + +SOF manages heterogeneous memory spaces across DSP and host domains: + +* **Tightly Coupled Memories (IRAM/DRAM)**: Low-latency memory dedicated to performance-critical DSP interrupt service routines and real-time audio threads. +* **High-Power / Low-Power SRAM Pools**: Dynamically power-gated SRAM banks utilized to minimize power draw during active playback and low-power idle. +* **Isolated Memory Regions (IMR) & Dynamic Paging**: For platforms with constrained on-chip SRAM, SOF dynamically pages code and data between host DRAM (IMR) and DSP SRAM, enabling large features (like complex neural networks or large codec libraries) to execute without requiring oversized on-chip SRAM. + Read More ********* diff --git a/architectures/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_driver.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_driver.rst similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_driver.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_driver.rst diff --git a/architectures/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_flows.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_flows.rst similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_flows.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_flows.rst diff --git a/architectures/firmware/sof-zephyr/rtos_layer/memory_management/memory_zones.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_zones.rst similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/memory_management/memory_zones.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_zones.rst diff --git a/architectures/firmware/sof-zephyr/rtos_layer/memory_management/mpp_memory_management.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/mpp_memory_management.rst similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/memory_management/mpp_memory_management.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/mpp_memory_management.rst diff --git a/architectures/firmware/sof-zephyr/rtos_layer/power_management.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/power_management.rst similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/power_management.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/power_management.rst diff --git a/architectures/firmware/sof-zephyr/rtos_layer/zephyr_kernel_overview.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/zephyr_kernel_overview.rst similarity index 100% rename from architectures/firmware/sof-zephyr/rtos_layer/zephyr_kernel_overview.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/zephyr_kernel_overview.rst diff --git a/architectures/firmware/sof-zephyr/zephyr_api_integration.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/zephyr_api_integration.rst similarity index 100% rename from architectures/firmware/sof-zephyr/zephyr_api_integration.rst rename to developer_guides/subsystem_architecture/firmware/sof-zephyr/zephyr_api_integration.rst diff --git a/architectures/host/index.rst b/developer_guides/subsystem_architecture/host/index.rst similarity index 61% rename from architectures/host/index.rst rename to developer_guides/subsystem_architecture/host/index.rst index a7a3cd13..170d0654 100644 --- a/architectures/host/index.rst +++ b/developer_guides/subsystem_architecture/host/index.rst @@ -3,6 +3,8 @@ Host Architecture ################# +For the high-level system and software stack architecture, see :ref:`architectures`. + .. toctree:: :maxdepth: 1 diff --git a/architectures/host/linux_driver/architecture/images/sof-driver-arch-1.png b/developer_guides/subsystem_architecture/host/linux_driver/architecture/images/sof-driver-arch-1.png similarity index 100% rename from architectures/host/linux_driver/architecture/images/sof-driver-arch-1.png rename to developer_guides/subsystem_architecture/host/linux_driver/architecture/images/sof-driver-arch-1.png diff --git a/architectures/host/linux_driver/architecture/images/sof-driver-arch-2.png b/developer_guides/subsystem_architecture/host/linux_driver/architecture/images/sof-driver-arch-2.png similarity index 100% rename from architectures/host/linux_driver/architecture/images/sof-driver-arch-2.png rename to developer_guides/subsystem_architecture/host/linux_driver/architecture/images/sof-driver-arch-2.png diff --git a/architectures/host/linux_driver/architecture/sof_driver_arch.rst b/developer_guides/subsystem_architecture/host/linux_driver/architecture/sof_driver_arch.rst similarity index 100% rename from architectures/host/linux_driver/architecture/sof_driver_arch.rst rename to developer_guides/subsystem_architecture/host/linux_driver/architecture/sof_driver_arch.rst diff --git a/developer_guides/unit_tests.rst b/developer_guides/unit_tests.rst index 93e0e0e7..355ff751 100644 --- a/developer_guides/unit_tests.rst +++ b/developer_guides/unit_tests.rst @@ -6,7 +6,7 @@ Unit Tests Prerequisites ************* -This guide assumes that you have the proper setup and that you know how to build firmware. If this is not correct, follow the instructions at :doc:`../getting_started/build-guide/build-from-scratch` first. +This guide assumes that you have the proper setup and that you know how to build firmware. If this is not correct, follow the instructions at :ref:`build_sof` first. `Cmocka `_ is fetched and built automatically. For a successful compilation, it needs a toolchain thats supports C stdlib. diff --git a/faq/index.rst b/faq/index.rst new file mode 100644 index 00000000..9a134303 --- /dev/null +++ b/faq/index.rst @@ -0,0 +1,134 @@ +.. _faq: + +Frequently Asked Questions (FAQ) +################################ + +This page addresses common architectural, algorithmic, development, and licensing questions regarding the Sound Open Firmware (SOF) ecosystem. + +.. contents:: FAQ Categories + :local: + :depth: 2 + +General & Architecture +********************** + +What is Sound Open Firmware (SOF)? +================================== +Sound Open Firmware (SOF) is an open-source, vendor-neutral audio Digital Signal Processing (DSP) firmware infrastructure, SDK, and host driver framework governed under the Linux Foundation. It enables deterministic, ultra-low-latency, power-efficient audio signal processing across personal computers, smartphones, smart speakers, automotive infotainment, and embedded microcontrollers. + +How does SOF differ from traditional audio DSP firmware? +======================================================== +Traditional audio DSP solutions rely on proprietary, closed-source binary blobs supplied by silicon vendors, offering little transparency, rigid pipeline configurations, and high friction for custom audio algorithms. SOF is: + +* **Open and Permissive**: Built with transparent BSD 3-Clause and MIT code, allowing developers to inspect, modify, debug, and optimize every line of firmware code. +* **Architecture-Independent**: Operates seamlessly across Tensilica Xtensa, ARM Cortex-M, and RISC-V DSPs. +* **Decoupled from Firmware**: Uses dynamic ALSA Topology (Topology 2) rather than hardcoded C pipelines, enabling dynamic runtime graph instantiation. +* **Upstream First**: Supported natively in upstream Linux kernel releases (``sound/soc/sof/``). + +What deployment models does SOF support? +======================================== +SOF supports two foundational architectures: + +* **Host-Based Architecture**: Coupled to a host application processor running **Linux**, **Android**, or **ChromeOS**. The host OS driver stack controls power states (D0ix/D3) and streams PCM audio over DMA windows via IPC (IPC3/IPC4). +* **Hostless (Standalone / Embedded) Architecture**: Runs autonomously on microcontrollers and embedded DSPs (such as **ESP32-P4** or **Teensy 4.1 / i.MX RT1062**) atop the Zephyr RTOS, streaming audio directly between physical peripherals (I2S, PDM, Bluetooth) using static ROM topologies without requiring a host PC. + +Which Real-Time Operating System (RTOS) does SOF use? +===================================================== +Modern SOF releases run natively on the **Zephyr RTOS**, providing robust hardware abstraction layers (HAL), POSIX thread synchronization primitives, dynamic device drivers, and real-time scheduling. Legacy deployments also support Cadence Xtensa XTOS. + +Which IPC protocols are supported? +================================== +SOF supports two Inter-Processor Communication (IPC) protocols: + +* **IPC4**: A structured, multi-part messaging protocol designed for modern Intel (cAVS 2.5+, ACE 1.x, ACE 3.x) and AMD platforms. It supports granular pipeline gating, modular dynamic loading, and multi-core scheduling. +* **IPC3**: A lightweight, mailbox-based message protocol used across earlier Intel CAVS architectures and legacy embedded DSP targets. + +Audio Processing & Module Development +************************************* + +Can I create and load custom audio processing modules? +====================================================== +Yes. SOF provides two development workflows for custom audio processing: + +1. **In-Tree Modules**: Authored directly in C or assembly and compiled statically into the target firmware image. +2. **Dynamic LLEXT Modules**: Compiled into relocatable ELF loadable extensions (**LLEXT**) and dynamically loaded, linked, and instantiated on demand by the host OS kernel driver without restarting the firmware or recompiling the base image. + +Can proprietary or commercial algorithms be integrated? +======================================================= +Yes. Because the SOF firmware core is licensed under the permissive **BSD 3-Clause** license, commercial hardware vendors and audio algorithm companies can integrate proprietary IP (either compiled directly or loaded dynamically as LLEXT binaries) without triggering copyleft requirements. + +What audio processing components are available out-of-the-box? +============================================================== +SOF includes a rich catalog of production-grade audio processing components: + +* **Core Mixing & Routing**: Volume control with smooth volume ramping, multi-channel Mixers, Matrix Mixers, Demux, and Multiplexers. +* **Sample Rate Conversion**: High-order polyphase fractional and synchronous Sample Rate Converters (SRC). +* **Acoustic Tuning**: Parametric IIR/FIR Equalizers (EQ) and multi-band Dynamic Range Control (DRC). +* **Voice & Spatial Processing**: Directional Microphone Beamforming (TDFB), Acoustic Echo Cancellation (AEC), and Wake-on-Voice (WoV). +* **Hardware-Accelerated Codecs**: MP3 and AAC decoders optimized for Tensilica Vector Floating-Point Units (VFPU). +* **Spatial Audio**: Valve Steam Audio HRTF 3D binaural spatial rendering. + +Refer to the :ref:`Audio Algorithms & Features Catalog ` for technical specifications and testbench instructions. + +How are audio signal pipelines defined? +======================================= +Audio pipelines in SOF are decoupled from firmware code and defined externally using **ALSA Topology (Topology 2)** files. Topology files define audio endpoints (DAIs), processing components (Volume, EQ, DRC), buffer sizes, scheduling periods, and mixer controls. The host OS driver reads the compiled binary ``.tplg`` file and issues IPC commands to instruct the DSP firmware to dynamically construct the requested pipeline DAG in DSP memory. + +Hardware & Platform Support +*************************** + +Where can I review hardware compatibility? +========================================== +The living :ref:`Supported Platforms Matrix ` details all supported silicon architectures, core frequencies, memory tiers, audio interfaces, and IPC protocols across: + +* **Intel Platforms**: Tiger Lake (TGL / CAVS 2.5), Meteor Lake (MTL / ACE 1.5), Arrow Lake (ARL-S / ACE 1.5), Lunar Lake (LNL / ACE 2.0), and Panther Lake (PTL / ACE 3.0). +* **AMD Platforms**: Renoir, Rembrandt, Phoenix, and Strix. +* **NXP Platforms**: i.MX8, i.MX8M, and i.MX9. +* **MediaTek Platforms**: MT8195 and MT8186. +* **Embedded Microcontrollers**: NXP i.MX RT1062 (**Teensy 4.1**) and Espressif **ESP32-P4** RISC-V audio bridges. + +Can SOF run without a host computer? +==================================== +Yes. The **Hostless (Standalone) Architecture** allows SOF to run independently on microcontrollers and embedded processors such as the **Teensy 4.1 (ARM Cortex-M7)** and **ESP32-P4 (dual-core RISC-V)**. In hostless mode, pipelines are instantiated at boot from static ROM configurations, processing audio directly between local microphones, line-ins, codecs, and Bluetooth transceivers. + +What physical audio buses and peripherals are supported? +======================================================== +SOF interfaces with all modern audio buses: + +* **MIPI SoundWire**: Low-power, two-wire digital audio and control bus for digital microphones and smart amplifiers. +* **I2S / TDM / SAI**: Inter-IC Sound and Time-Division Multiplexed multi-channel serial buses. +* **PDM (Pulse-Density Modulation)**: Direct digital microphone arrays with hardware decimation and CIC filters. +* **Intel HD-Audio (HDA)**: High-definition audio links for PC codecs and HDMI/DisplayPort audio. +* **Bluetooth Audio**: Direct Bluetooth HCI audio streaming supporting **A2DP Sink/Source**, **HFP / mSBC**, and **LE Audio (LC3 / Auracast)**. + +Testing, Simulation & Telemetry +******************************* + +How can I test SOF without physical hardware? +============================================= +SOF provides two simulation options: + +1. **Host Testbench (`testbench`)**: Compiles DSP processing components into native Linux executables. You can feed multi-channel WAV files through any SOF component (EQ, SRC, DRC, Beamforming) on your x86_64 or ARM development PC to verify bit-exact outputs, measure latency, and detect memory leaks with Valgrind. +2. **QEMU DSP Simulator**: Provides full-system instruction-level emulation (`native_sim`, `qemu_xtensa`, `ptl-sim`, `tgl-sim`) to validate driver handshakes, IPC messaging, firmware boot flows, and exception handlers in automated CI without needing physical development boards. + +How do I capture DSP firmware logs and trace data? +================================================== +SOF uses an efficient string dictionary extraction system (**smex**). Format strings are extracted from firmware ELF binaries during compilation into a dictionary file (``.ldc``), allowing the DSP to transmit compact numeric trace IDs over DMA without CPU overhead. On the host, tools such as **sof-logger** and the **TCP Probe Server** (port 9999) decode these trace packets in real time. + +Licensing & Community Governance +******************************** + +What licenses apply to the SOF codebase? +======================================== +* **Firmware Core**: Permissive **BSD 3-Clause** license (with select third-party helpers under MIT). +* **Linux Driver Stack**: Upstream Linux kernel drivers in ``sound/soc/sof/`` are licensed under **GPLv2**. Core platform-independent driver abstraction headers are dual-licensed **BSD 3-Clause / GPLv2**. +* **Topology & SDK Tools**: Build scripts, packaging utilities (`rimage`), and topology compilers are licensed under **BSD 3-Clause** or **MIT**. + +How is the project governed? +============================ +SOF is an open-source project hosted under the **Linux Foundation**. Technical architecture, roadmap priorities, and code review standards are directed by the **SOF Technical Steering Committee (TSC)**, representing member companies and independent open-source developers. All meetings, RFCs, and discussions are open to the public on GitHub. + +Where should I ask questions or report bugs? +============================================ +* **GitHub Discussions & Issues**: Open an issue or join architectural RFC discussions on the `SOF GitHub Repository `_. +* **Slack Community**: Join the `SOF Slack Workspace `_ to chat with firmware engineers, kernel maintainers, and community audio developers. diff --git a/getting_started/build-guide/build-3rd-party-toolchain.rst b/getting_started/build-guide/build-3rd-party-toolchain.rst deleted file mode 100644 index 2beb0ffc..00000000 --- a/getting_started/build-guide/build-3rd-party-toolchain.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. _build-3rd-party-toolchain: - -Build SOF with a 3rd Party Toolchain -#################################### - -A "3rd party toolchain" is a supported toolchain provided by an external -organization. - -Toolchains are provided by various vendors and are available under a -variety of commercial, academic, or open source terms; visit the providers' -websites for further information. - -.. contents:: - :local: - :depth: 3 - -Cadence® Tensilica® Xtensa® C/C++ Compiler (XCC) -************************************************ - -.. note:: - Currently |APL|, |CNL| and |ICL| targets are verified with Xtensa C/C++ - Compiler (xt-xcc). The xt-clang compiler is not supported. - -The Xtensa compiler provides support for HiFi coprocessor SIMD instructions. -An example below depicts how to enable conditional compilation of the code depending -on the toolchain installed and the coproccessor model on a target system. - -.. code-block:: c - - /* Select optimized code variant when xt-xcc compiler is used */ - #if defined __XCC__ - #include - #define FIR_GENERIC 0 - #if XCHAL_HAVE_HIFI2EP == 1 - #define FIR_HIFIEP 1 - #define FIR_HIFI3 0 - #elif XCHAL_HAVE_HIFI3 == 1 - #define FIR_HIFI3 1 - #define FIR_HIFIEP 0 - #else - #error "No HIFIEP or HIFI3 found. Cannot build FIR module." - #endif - #else - /* GCC */ - #define FIR_GENERIC 1 - #define FIR_HIFIEP 0 - #define FIR_HIFI3 0 - #endif - - -Once you have installed the toolchain according to procedures outlined in the -toolchain documentation, see the :ref:`build-from-scratch` chapter on how to build -FW binaries. diff --git a/getting_started/build-guide/build-from-scratch.rst b/getting_started/build-guide/build-from-scratch.rst deleted file mode 100644 index 4c0519af..00000000 --- a/getting_started/build-guide/build-from-scratch.rst +++ /dev/null @@ -1,613 +0,0 @@ -.. _build-from-scratch: - -Build toolchains and SOF from sources -##################################### - -.. contents:: - :local: - :depth: 3 - -You may boot and test |SOF| on a target machine or VM. Current target -Intel platforms include: |BYT|, |CHT|, |HSW|, |BDW|, |APL|, |CNL|, |ICL|, |JSL|, and |TGL|. - -Support also exists for NXP i.MX8/i.MX8X/i.MX8M platforms. - -The following steps describe how to install the SOF development environment on -Ubuntu 16.04, 18.04, 18.10, and 20.04, and Fedora 36. They should work on Ubuntu -19.04, 19.10 and other Linux distributions with minor or no modifications. - -.. note:: - - Building the toolchains from source might take several hours. We - recommend that you use Docker to build SOF. For more information, - see :ref:`build-with-docker`. - -Step 1. Set up the workspace directory -************************************** - -Point the ``$SOF_WORKSPACE`` environment variable to the directory in -which you store all sof work. - -The code examples assume ``$SOF_WORKSPACE`` is the top-level working -directory. Clone all git repositories at the same directory level -because some default configuration files refer to other clones using -relative locations like ``../sof/``. - -Make sure that ``$SOF_WORKSPACE`` has adequate disk space when -building the toolchain. About 15GB is needed per toolchain. You can -reclaim some of the disk space after building the toolchain. - - .. code-block:: bash - - SOF_WORKSPACE=~/work/sof - mkdir -p "$SOF_WORKSPACE" - -Step 2. Set up build environment -******************************** - -Install package dependencies -============================ -.. note:: - - This guide uses Ubuntu/Fedora as an example but any modern distribution can be - used for SOF development. - -Due to continuous default package updates in distributions, SOF -documentation may not include explicit instructions for possible missing -tools and packages. When you encounter missing dependencies, refer to your -distribution's documentation on how to install them. - -* For Fedora (tested with v36, other recent versions should work fine): - - .. code-block:: bash - - sudo dnf group install "Development Tools" "C Development Tools and Libraries" - sudo dnf install ncurses-devel gtk3-devel gettext-devel texinfo help2man \ - glibc-static libstdc++-static openssl-devel tree - -* For Ubuntu 20.04: - - .. code-block:: bash - - sudo apt install build-essential git autoconf flex bison texinfo help2man \ - gawk libtool-bin libncurses5 libncurses5-dev libssl-dev libgtk-3-dev \ - tree ninja-build gettext libasound2-dev - -* For Ubuntu 18.10: - - .. code-block:: bash - - sudo apt-get install build-essential git libgtk-3-dev libsdl1.2-dev \ - libspice-protocol-dev libspice-server-dev libusb-1.0-0-dev \ - libusbredirhost-dev libtool-bin acpica-tools valgrind texinfo \ - virt-manager qemu-kvm libvirt-daemon-system libvirt-clients virtinst \ - libfdt-dev libssl-dev pkg-config help2man gawk libncurses5 \ - libncurses5-dev - -* For Ubuntu 16.04 and 18.04: - - .. code-block:: bash - - sudo apt-get install build-essential git libgtk-3-dev libsdl1.2-dev \ - libspice-protocol-dev libspice-server-dev libusb-1.0-0-dev \ - libusbredirhost-dev libtool-bin iasl valgrind texinfo virt-manager \ - qemu-kvm libvirt-bin virtinst libfdt-dev libssl-dev pkg-config help2man \ - gawk libncurses5 libncurses5-dev - -If you are using Ubuntu 16.04, the gcc version must be updated to gcc 7.3+ -in order for the Advanced Linux Sound Architecture (ALSA) to build. - -.. code-block:: bash - - sudo add-apt-repository ppa:ubuntu-toolchain-r/test - sudo apt-get update - sudo apt-get install gcc-7 g++-7 - sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 70 --slave /usr/bin/g++ g++ /usr/bin/g++-7 - -Install CMake -============= - -If you use Ubuntu 18.04+ or Fedora you can install CMake with apt/dnf: - -.. code-block:: bash - - sudo apt-get install cmake # Ubuntu - sudo dnf install cmake # Fedora - -For Ubuntu 16.04, CMake from apt is outdated and you must install CMake from -sources. Refer to this short guide: https://cmake.org/install/. - -Build alsa-lib and alsa-utils from source -========================================= - -This project requires some new features in :git-alsa:`alsa-lib` and -:git-alsa:`alsa-utils`, so build the newest ALSA from source code. - -.. warning:: - - Installing alsa-lib systemwide may break some audio applications. - Only perform this if you know what you are doing. We recommend that you - install it locally (under $HOME) or use Docker - (see :ref:`build-with-docker`.) - -.. code-block:: bash - - cd "$SOF_WORKSPACE" - git clone git://git.alsa-project.org/alsa-lib - cd alsa-lib - # To install alsa-lib systemwide - ./gitcompile - # To install alsa-lib locally - ./gitcompile --prefix=$HOME/local - sudo make install - -(Optional) To enable alsabat's frequency analysis, install the FFT library -before you configure alsa-utils. - -.. code-block:: bash - - sudo apt-get install libfftw3-dev libfftw3-doc # Ubuntu - sudo dnf install fftw3-devel # Fedora - -Clone, build, and install alsa-utils. - -.. code-block:: bash - - cd "$SOF_WORKSPACE" - git clone git://git.alsa-project.org/alsa-utils - cd alsa-utils - # To install alsa-utils systemwide - ./gitcompile - # To install alsa-utils locally - ./gitcompile --prefix=$HOME/local \ - --with-alsa-inc-prefix=$HOME/local/include \ - --with-alsa-prefix=$HOME/local/lib \ - --with-systemdsystemunitdir=$HOME/local/lib/systemd \ - --with-udev-rules-dir=$HOME/local/lib/udev - sudo make install - -If you run into alsa-lib linking errors, try to re-build it with the libdir -parameter. - -.. code-block:: bash - - cd ../alsa-lib - ./gitcompile --prefix=/usr --libdir=/usr/lib/x86_64-linux-gnu/ - sudo make install - cd ../alsa-utils - ./gitcompile --prefix=/usr --with-curses=ncurses --disable-xmlto --disable-bat - sudo make install - -.. note:: - - If the gitcompile script does not work, refer to the INSTALL file for - manual build instructions. - -Create or append to the ``LD_LIBRARY_PATH`` environment variable. - -.. code-block:: bash - - export LD_LIBRARY_PATH="${SOF_WORKSPACE}"/alsa-lib/src/.libs:$LD_LIBRARY_PATH - -.. _build-toolchains-from-source: - -Step 3. Build toolchains from source -************************************ - -Build the xtensa cross-compilation toolchains with crosstool-ng for -Intel |BYT|, |CHT|, |HSW|, |BDW|, |APL|, |CNL|, |ICL|, |JSL|, |TGL| -platforms and NXP i.MX8/i.MX8X/i.MX8M platforms. Building the toolchains -may take about an hour but only once and it removes the dependency on -the Docker image. - -For more details go to https://crosstool-ng.github.io/ - -crosstool-ng -============ - -Clone both repos and check out the ``sof-gcc10.2`` and ``sof-gcc10x`` branch. - -.. code-block:: bash - - cd "$SOF_WORKSPACE" - git clone https://github.com/thesofproject/xtensa-overlay - git clone https://github.com/thesofproject/crosstool-ng - git -C xtensa-overlay/ checkout sof-gcc10.2 - git -C crosstool-ng/ checkout sof-gcc10x - -Build crosstool-ng and install it in its own source directory. - -.. code-block:: bash - - cd crosstool-ng/ - ./bootstrap - ./configure --prefix=$(pwd) - make - make install - -Toolchains -========== - -The config files provided refer to ``../xtensa-overlay/`` and point at -different ``./builds/xtensa-*-elf`` subdirectories. Copy the ones you -want to ``.config`` and build the cross-compiler(s) for your target -platform(s). Note that ``./ct-ng build`` requires an network connection -to download gcc components. While other steps take minutes at most, -building all toolchains may last about an hour depending on your network -connection and the performance of your system. - -.. code-block:: bash - - unset LD_LIBRARY_PATH - - # byt = Bay Trail / Cherry Trail - # hsw = Haswell/Broadwell - # apl = Apollo Lake - # cnl = Cannon Lake, Ice Lake, Jasper Lake, and Tiger Lake - # imx = i.MX8/i.MX8X - # imx8m = i.MX8M - - # Omit the toolchains you don't want to save (a lot of) time - time for i in byt hsw apl cnl imx imx8m; do - cp config-$i-gcc10.2-gdb9 .config && - time ./ct-ng build || break - done - - # ... or just build all toolchains - time for i in config*gcc10.2-gdb9; do - cp "$i" .config && time ./ct-ng build || break - done - - -``./ct-ng`` is a Linux kernel style Makefile; so the sample commands below -can be used to fix some out of date ``config-*-gcc10.2-gdb9`` file or find -default values missing from it: - -.. code-block:: bash - - ./ct-ng help - cp config-apl-gcc10.2-gdb9 .config - ./ct-ng oldconfig V=1 - diff -u config-apl-gcc10.2-gdb9 .config - -"Install" toolchains in the expected location by linking -from ``$SOF_WORKSPACE`` to them: - -.. code-block:: bash - - ls builds/ - # xtensa-apl-elf xtensa-byt-elf xtensa-cnl-elf xtensa-hsw-elf xtensa-imx-elf xtensa-imx8m-elf - cd "$SOF_WORKSPACE" - for i in crosstool-ng/builds/xtensa-*; do ln -s "$i"; done - -Remove the temporary build files (~7GB per toolchain): - -.. code-block:: bash - - rm -rf $SOF_WORKSPACE/crosstool-ng/.build - -.. note:: - - |HSW| and |BDW| share the same toolchain: xtensa-hsw-elf - - |BYT| and |CHT| share the same toolchain: xtensa-byt-elf - - |CNL|, |ICL|, |JSL| and |TGL| share the same toolchain: xtensa-cnl-elf - - i.MX8 and i.MX8X share the same toolchain: xtensa-imx-elf - - -Additional headers -================== - -To get some required headers, clone the following newlib repository and -switch to the `xtensa` branch. - -.. code-block:: bash - - cd "$SOF_WORKSPACE" - git clone https://github.com/jcmvbkbc/newlib-xtensa - cd newlib-xtensa - git checkout -b xtensa origin/xtensa - -Temporarily add toolchains to your PATH variable. This is *not* required -when using the high-level, "every day" build scripts described in the -next sections. It's only required for this once-off ``newlib`` headers -step or when invoking CMake manually. In other words, you don't need to -change your PATH permanently which would interfere with other, non-SOF -work. - -.. code-block:: bash - - for i in "${SOF_WORKSPACE}"/xtensa-*-elf; do PATH="$PATH:$i"/bin; done - -Build and install the newlib headers for each toolchain: - -.. code-block:: bash - - XTENSA_ROOT="${SOF_WORKSPACE}"/xtensa-root - cd "${SOF_WORKSPACE}"/newlib-xtensa - time for toolchain in ../xtensa-*-elf; do - ./configure --target="${toolchain#../}" --prefix="$XTENSA_ROOT" && - make && make install || break; - rm etc/config.cache - done - ls "$XTENSA_ROOT" - => share xtensa-apl-elf xtensa-byt-elf xtensa-cnl-elf xtensa-hsw-elf ... - -This should take a few minutes. - -.. note:: - - ``--prefix=`` expects an absolute path. Define XTENSA_ROOT according to - your environment. - -The required headers are now in ``"$SOF_WORKSPACE"/xtensa-root``, and -cross-compilation toolchains for xtensa DSPs are set up. - -.. _build-and-sign-firmware-binaries-from-scratch: - -Step 4. Build and sign firmware binaries -**************************************** - -After the SOF environment is set up, clone the *sof* repo: - -.. code-block:: bash - - cd "$SOF_WORKSPACE" - git clone --recursive https://github.com/thesofproject/sof - cd sof - - -Copy the commented ``installer/sample-config.mk`` to -``installer/config.mk``, then select a list of platforms and provide an -optional target hostname in the latter file. Then run the installer: - -.. code-block:: bash - - make -C installer/ [ -j 4 ] - -Adjust the ``-j 4`` example to your number of CPU cores or remove it -when the build fails. - -This builds multiple platforms in parallel and deploys firmware and -topologies to ``/lib/firmware/intel/`` on the local or remote -destination that you configured. It builds with the default platform -configurations the first time and then switches to incremental builds -which preserves any ``make menuconfig`` or other configuration changes -you made. These two ways to build are described below, so read on if you -need finer control on the build system and configuration. Otherwise you -can skip the next two sections. - -The installer also builds and deploys some user-space binaries from the -``sof/tools/`` subdirectory. - -.. note:: - - The installer is much faster than the lower level ``./scripts/``, - on which it relies, because it does not delete the build - directories every time it runs. However, some "big" configuration - changes, such as switching to a different toolchain or some rare - build failures, can leave the ``installer-builds/build_*`` - directories in an inappropriate state. In such a case, just delete - these directories and run the installer again. - - .. code-block:: bash - - rm -rf $SOF_WORKSPACE/sof/installer-builds - make -C installer/ - -Re-configure and rebuild from scratch -===================================== - -To rebuild |SOF| from scratch, the installer Makefile above relies on -the :git-sof-mainline:`scripts/xtensa-build-all.sh` script. If you need -finer control or to troubleshoot some build issue you can also use it -directly. To build the firmware for all platforms: - -.. code-block:: bash - - cd "$SOF_WORKSPACE"/sof/ - ./scripts/xtensa-build-all.sh -a - -.. note:: - - This script works only if the cross-compiler and ``xtensa-root`` are - siblings in the same ``sof`` directory, as instructed above. - -As of May 2021, you may specify one or more of the following platform -arguments: ``byt``, ``cht``, ``bdw``, ``hsw``, ``apl``, ``skl``, ``kbl``, ``cnl``, -``sue``, ``icl``, ``jsl``, ``tgl``, ``tgl-h``, ``imx8``, ``imx8x``, ``imx8m``. Example: - -.. code-block:: bash - - ./scripts/xtensa-build-all.sh byt - ./scripts/xtensa-build-all.sh byt apl - -For the latest platforms list and help message, run the script without -any argument. You can also enable debug builds with -d, enable rom -builds with -r and speed up the build with -j [n] - -.. code-block:: bash - - ./scripts/xtensa-build-all.sh -d byt - ./scripts/xtensa-build-all.sh -d -r apl - ./scripts/xtensa-build-all.sh -d -r -j 4 apl - -.. note:: - The ``xtensa-build-all.sh`` script uses ``rimage`` to build the final - firmware image. ``rimage`` uses by default a public key included in the - sof repo for signing. However, if you need to use some other external key - for signing you can specify the path to your key as environment variable - before invoking the build: - - .. code-block:: bash - - export PRIVATE_KEY_OPTION=-DRIMAGE_PRIVATE_KEY=/path_to_key/private.pem - - The same export mechanism should work also when building with Docker. - -Incremental builds -================== - -This is a more detailed build guide for the *sof* repo. Unlike -``xtensa-build-all.sh``, this doesn't rebuild everything every time. The -installer Makefile above relies on this for incremental builds. - -Snippets below assume that your current directory is the root of the -``sof`` clone (``"$SOF_WORKSPACE"/sof/``). - -CMake recommends out-of-tree builds. Among others, this lets you build -different configurations/platforms in different build directories from -the same source without starting from scratch. - -.. note:: - - The ``-j`` argument tells make how many processes to use concurrently. - Select a value that matches your build system. - -for |BYT|: - -.. code-block:: bash - - mkdir build_byt && cd build_byt - cmake -DTOOLCHAIN=xtensa-byt-elf -DROOT_DIR="$XTENSA_ROOT"/xtensa-byt-elf -DINIT_CONFIG=baytrail_defconfig .. - make help # lists all available targets - make bin -j4 VERBOSE=1 - -You can replace ``byt`` above with any other platform listed in the help -output of the ``sof/scripts/xtensa-build-all.sh``. Find the toolchain -matching each platform in the same script or above. - - -.. note:: - - After the cmake step, you can customize your build with - 'make menuconfig'. - - DEBUG and ROM options are available for the FW binary build. Enable them - with 'make menuconfig'. - -.. code-block:: bash - - mkdir build_cnl_custom && cd build_cnl_custom - cmake -DTOOLCHAIN=xtensa-cnl-elf -DROOT_DIR="$XTENSA_ROOT"/xtensa-cnl-elf -DINIT_CONFIG=cannonlake_defconfig .. - make menuconfig # select/deselect options and save - make bin -j4 - -.. note:: - - If you have `Ninja `_ installed, you can use it - instead of Make. Just type *cmake -GNinja ...* during the configuration - step. - - -Firmware build results -====================== - -The firmware binary files are located in build_/src/arch/xtensa/. -The installer copies them to your target machine's ``/lib/firmware/intel/sof`` -folder. - -.. code-block:: bash - - sof-apl.ri sof-bdw.ri sof-byt.ri sof-cht.ri sof-cnl.ri sof-hsw.ri - -.. _build-topology-and-tools-from-scratch: - -Step 5. Build topology and tools -******************************** - -You can probably skip this section if you use the firmware installer in -the previous section. - -One-step rebuild from scratch -============================= - -Without any argument :git-sof-mainline:`scripts/build-tools.sh` builds -the default CMake target "ALL" of :git-sof-mainline:`tools/`. - -.. code-block:: bash - - cd "$SOF_WORKSPACE"/sof/ - ./scripts/build-tools.sh - -To see the list of options, run :git-sof-mainline:`scripts/build-tools.sh` with the ``-h`` option. - -.. code-block:: bash - - ./scripts/build-tools.sh -h - -Incremental build -================= - -.. code-block:: bash - - cd "$SOF_WORKSPACE"/sof/tools/ - mkdir build_tools && cd build_tools - cmake .. - make -j4 - -If your ``cmake --version`` is 3.13 or higher, you may prefer the new -B option: - -.. code-block:: bash - - cmake -B build_tools/ - make -C build_tools/ -j4 VERBOSE=1 - rm -rf build_tools/ # no need to change directory ever - -Topology and tools build results -================================ - -The topology files are located in the *tools/build_tools/topology* -folder. The installer Makefile copies them to the target machine's -``/lib/firmware/intel/sof-tplg/`` folder. - -The *sof-logger* tool is in the *tools/build_tools/logger* folder. The -installer Makefile copies them to the target directory of your choice. - -.. _Build Linux kernel: - -Step 6. Build Linux kernel -************************** - -|SOF| uses the Linux kernel dev branch, and it must work with other dev -branch firmware and topology. This short section shows how to build -Debian kernel packages tested on Ubuntu in a small number of commands. -Note that these commands rebuild everything from scratch every time which -makes then unsuitably slow for development. If you need to make kernel -code changes, ignore this and look at -:ref:`setup-ktest-environment`, the `README `_ file of -the kconfig repo, and the :ref:`sof_driver_arch`. - -#. Build the kernel with this branch. - - .. code-block:: bash - - sudo apt-get install bison flex libelf-dev - cd "$SOF_WORKSPACE" - git clone https://github.com/thesofproject/linux - cd linux - git checkout topic/sof-dev - make defconfig - git clone https://github.com/thesofproject/kconfig - scripts/kconfig/merge_config.sh .config ./kconfig/base-defconfig ./kconfig/sof-defconfig ./kconfig/mach-driver-defconfig ./kconfig/hdaudio-codecs-defconfig - - Optionally, you can also run ``make menuconfig``, navigate to - Device Drivers > Sound card support > Advanced Linux Sound - Architecture, and select the **Prefer SOF driver over SST on BY/CHT - platforms** option. - -#. Make the kernel deb package to install on the target machine. - - .. code-block:: bash - - make deb-pkg -j 4 - -#. Copy the three resulting *.deb* files from $SOF_WORKSPACE to the - target machine and install them. - - .. code-block:: bash - - sudo dpkg -i /absolute/path/to/deb/file - sudo apt-get install -f diff --git a/getting_started/build-guide/build-with-docker.rst b/getting_started/build-guide/build-with-docker.rst deleted file mode 100644 index de972829..00000000 --- a/getting_started/build-guide/build-with-docker.rst +++ /dev/null @@ -1,191 +0,0 @@ -.. _build-with-docker: - -Build SOF with Docker -##################### - -.. contents:: - :local: - :depth: 3 - -This guide will show you how to use a Docker image containing the -|SOF| build environment. - -Set up the workspace directory -****************************** - -1. Point the ``$SOF_WORKSPACE`` environment variable to the directory - in which you store all SOF work. - - .. code-block:: bash - - SOF_WORKSPACE=~/work/sof - mkdir -p "$SOF_WORKSPACE" - -#. Clone the SOF repository. - - .. code-block:: bash - - cd "$SOF_WORKSPACE" - git clone --recurse-submodules https://github.com/thesofproject/sof.git - -Set up Docker -************* - -Docker is a popular container management framework. To install Docker and get the Docker image with the SOF build environment: - -1. Install Docker. - - For information on how to install Docker on Ubuntu, visit `Install - Docker Engine on Ubuntu - `__. - - For information on how to install Docker on other Linux - distributions, visit `Install Docker Engine - `__. - -#. Optionally, configure Docker to run under a proxy. - - For more information about configuring Docker to use a proxy, visit - `HTTP/HTTPS proxy - `__. - -#. To use Docker without ``sudo``, add your user to the `docker` group. - - For more information, visit - `Post-installation steps for Linux `__. - -#. Get a Docker image with the SOF build environment. - - To easily build SOF binaries, we need a Docker image containing all - of the cross-compiler and build environment dependencies. Get the - Docker image by using one of the following options: - - - Option 1. Pull the Docker image from Docker Hub and retag the image with `sof` for scripts: - - .. code-block:: bash - - docker pull thesofproject/sof - docker tag thesofproject/sof sof - - .. note:: - - Since there is not yet an offical |SOF| presence on - Dockerhub, the image is hosted in a personal Docker Hub repo - until the official image can go live. - - - Option 2. Build a Docker image: - - .. note:: - - Building the container from DockerFile takes more than two hours, - so we recommend using the pre-built image (Option 1). - - Run the Docker build from the SOF repository. - - .. code-block:: bash - - cd "${SOF_WORKSPACE}"/sof/scripts/docker_build/sof_qemu - ./docker-build.sh - cd "${SOF_WORKSPACE}"/sof/scripts/docker_build/sof_builder - ./docker-build.sh - - Verify that the docker image is built successfully. - - .. code-block:: bash - - docker images - - #REPOSITORY TAG IMAGE ID CREATED SIZE - #sof latest c8b0e8913fcb 2 days ago 1.46 GB - -Build firmware binaries with Docker -*********************************** - -Build with scripts -================== - -To build the SOF binaries for all platforms: - -.. code-block:: bash - - cd "${SOF_WORKSPACE}"/sof/ - ./scripts/docker-run.sh ./scripts/xtensa-build-all.sh -a - -``./scripts/docker-run.sh`` mounts the *sof* and directories into the -Docker container and builds them inside the container. You can access -the build result outside the container after the build. - -To build the SOF binaries for one or more platforms: - -.. code-block:: bash - - cd "${SOF_WORKSPACE}"/sof/ - # Bay Trail - ./scripts/docker-run.sh ./scripts/xtensa-build-all.sh byt - # Bay Trail and Apollo Lake - ./scripts/docker-run.sh ./scripts/xtensa-build-all.sh byt apl - -Build inside container -====================== - -1. Enter the container bash: - - .. code-block:: bash - - cd "${SOF_WORKSPACE}"/sof/ - ./scripts/docker-run.sh bash - -#. From inside the container, follow the manual configuration and build - steps. For more information, see - :ref:`build-and-sign-firmware-binaries-from-scratch`. - -Firmware build results -====================== - -The firmware binary files are located in the -``build_/src/arch/xtensa/`` directory. Copy them to the -``/lib/firmware/intel/sof`` directory on the target machine. - -.. code-block:: bash - - sof-apl.ri sof-bdw.ri sof-byt.ri sof-cht.ri sof-cnl.ri sof-hsw.ri - -.. _docker-topology-tools: - -Build topology and tools with Docker -************************************ - -Build with scripts -================== - -Build the SOF tools and topology files. - -.. code-block:: bash - - cd "${SOF_WORKSPACE}"/sof/ - ./scripts/docker-run.sh ./scripts/build-tools.sh - -Build inside container -====================== - -1. Enter the container bash: - - .. code-block:: bash - - cd "${SOF_WORKSPACE}"/sof/ - ./scripts/docker-run.sh bash - -2. From inside the container, change to the ``tools`` directory and - follow the manual configuration and build steps. For more - information, see :ref:`build-topology-and-tools-from-scratch`. - -Topology and tools build results -================================ - -The topology files are located in the -``"$SOF_WORKSPACE"/sof/tools/build_tools/topology`` folder. Copy the -files to the ``/lib/firmware/intel/sof-tplg`` directory on the target -machine. - -The *sof-logger* tool is located in the ``tools/logger`` directory. Copy -it to the ``/usr/bin`` directory on the target machine. diff --git a/getting_started/build-guide/build-with-zephyr.rst b/getting_started/build-guide/build-with-zephyr.rst deleted file mode 100644 index e3eb035d..00000000 --- a/getting_started/build-guide/build-with-zephyr.rst +++ /dev/null @@ -1,267 +0,0 @@ -.. _build-with-zephyr: - -Build SOF with `Zephyr `_ -##################################################### - -.. contents:: - :local: - :depth: 3 - -This guide describes how to build and run |SOF| as a Zephyr application. - -.. note:: - - The following example uses ``$ZEPHYR_WORKSPACE`` as the working - directory for both SOF and Zephyr projects. - -Prepare -******* - -- The easiest way to build Zephyr is to use its recommended toolchain which is included in its SDK. Refer to `Install Zephyr SDK `_ for details. - -- Install **west**. Zephyr uses west as a source management and building system. Follow - the Zephyr `Getting Started `_ guide for dependencies and for the west installation. - -Clone and initialize SOF project -******************************** - -Initialize the west manifest ``$ZEPHYR_WORKSPACE/sof/west.yml`` using the ``west tool``: - - - Clone the SOF repository: - - .. code-block:: bash - - mkdir $ZEPHYR_WORKSPACE && cd $ZEPHYR_WORKSPACE - west init -m https://github.com/thesofproject/sof - - - Or initialize the west manifest from the existing SOF clone. Note that when using the Python convenience script, as described in the next section, this is not mandatory. - - .. code-block:: bash - - cd $ZEPHYR_WORKSPACE - west init -l ./sof - - - .. note:: - | Since the Zephyr project also uses the west manifest, your west tool might already be initialized to manifest Zephyr. In this case, west issues the following error during initialization: - | *"FATAL ERROR: already initialized in $ZEPHYR_WORKSPACE, aborting."* - | - | To verify that the manifest is currently used by the west tool, execute the following command from the ``$ZEPHYR_WORKSPACE`` directory: - | ``west config -l``. - | - | If command output shows the following, remove the ``$ZEPHYR_WORKSPACE/.west`` directory and reinitialize the west manifest using one of the two methods described above: - | *manifest.path=zephyr* - | *manifest.file=west.yml* - - .. important:: - The SOF project **must** be cloned to the ``sof`` directory because this name is hardcoded in the west manifest file. Failure to do so may result in SOF dependencies being cloned into a newly created ``$ZEPHYR_WORKSPACE/sof/rimage`` directory along with other undesirable consequences. - - **All commands described in the guide from this point should be executed from the $ZEPHYR_WORKSPACE directory.** - - -Check out and build using Python convenience script -*************************************************** - -The SOF project offers a Python convenience script, ``./sof/scripts/xtensa-build-zephyr.py``, that provides a friendly build process for the end user. It is a wrapper for a **west tool** that performs steps described in the `Check out and build using west tool directly`_ section below. - -This script can be used on both Windows and Linux operating systems. Note that it will be removed when the SOF project creates better integration with west tool commands. - -The script automates the following steps that are required to build firmware for the SOF platform: - - Initializes your west tool to SOF's west manifest. - - Clones and checks out SOF and Zephyr dependencies. - - Builds a firmware ``.elf`` file for the requested platform. - - Builds a **rimage tool**. - - Uses the **rimage tool** and a **private key** to sign the ``.elf`` file. It produces a final firmware image file with the ``.ri`` extension. - - Uses the **smex tool** to generate debugging symbols file with the ``.ldc`` extension. - -| A list of platforms that can be built with the script is shown in this help message: -| ``./sof/scripts/xtensa-build-zephyr.py --help`` - -Usage example 1: - You cloned the SOF project and you want to build firmware for the *Tigerlake* platform. - - .. code-block:: bash - - ./sof/scripts/xtensa-build-zephyr.py -u tgl - - Running this command will: - - - Initialize west to the ``./sof/west.yml`` manifest if it is not already initialized. - - Clone and check out projects to the revision defined in the ``./sof/west.yml`` file: - - - SOFs submodules (Rimage and Tomlc99) - - Zephyr project - - Zephyr project dependencies needed by SOF in ``$ZEPHYR_WORKSPACE/modules`` directory - - - Build a signed firmware image ``./build-tgl/zephyr/zephyr.ri`` and debug symbols file ``./build-sof-staging/sof/sof-tgl.ldc``. - - .. note:: - You may wish to rebuild all files from scratch. To do this, add a ``-p`` flag to the script invocation. To provide better build verbosity, use the ``-v`` flag. Make sure to check ``--help`` to see all build options. - -Usage example 2: - Your environment is set up as a cloned SOF project and you are working on a fork/branch of the Zephyr and Rimage submodules. You want to build a *Tigerlake* platform with your changes. - - .. code-block:: bash - - ./sof/scripts/xtensa-build-zephyr.py tgl - - Running this command will: - - - Initialize west to the ``./sof/west.yml`` manifest if it is not already initialized. - - Build a signed firmware image ``./build-tgl/zephyr/zephyr.ri`` and debug symbols file ``./build-sof-staging/sof/sof-tgl.ldc``. - - Skip cloning dependencies and check them out to revisions from the ``./sof/west.yml`` manifest. - -Usage example 3: - Your environment is set up as a cloned SOF project and you are working on a fork/branch of the Zephyr and Rimage submodules. You want to restore default revisions for SOF dependencies from the ``./sof/west.yml`` manifest. - - .. code-block:: bash - - ./sof/scripts/xtensa-build-zephyr.py -u - - Running this command will: - - - Initialize west to the ``./sof/west.yml`` manifest if it is not already initialized. - - Clone and checkout projects to revisions defined in the ``./sof/west.yml`` file. - - Skip building the firmware image. - -Output directory - For convenience, the ``xtensa-build-zephyr.py`` script copies all - firmware files into a single, staging directory: - - .. code-block:: bash - - $ tree build-sof-staging/ - - build-sof-staging/ - ├── sof - │   ├── community - │   │   ├── sof-apl.ri - │   │   ├── sof-imx8.ri - │   │   └── sof-tgl-h.ri - - -Check out and build using west tool directly -******************************************** - -#. Clone and check out SOF dependencies such as submodules, the Zephyr project, and some of its modules needed by SOF: - - .. code-block:: bash - - west update - - .. important:: - This command will check out revisions specified in the ``$ZEPHYR_WORKSPACE/sof/west.yml`` file for the following projects: - - Rimage (SOF submodule) - - Tomlc99 (Rimage submodule) - - Zephyr - - projects in ``$ZEPHYR_WORKSPACE/modules`` directory. - - **Make sure you back up your work before changing revisions!** - This will not affect your SOF project revision. - -#. Build a board. Make sure to use the appropriate Zephyr SDK or other toolchain of your choice. Boards to build are listed in the ``$ZEPHYR_WORKSPACE/sof/app/boards`` directory. - - .. code-block:: bash - - west build --build-dir build-tgl --board intel_adsp/cavs25 ./sof/app - - - Note that the SOF project defines platform names that have Zephyr board counterparts. In the above example, the *Tigerlake* platform matches the ``intel_adsp/cavs25`` Zephyr board target (see `Zephyr HWMv2 board terminology `_). This is why the output directory is named ``build-tgl``; however, you may use any name you wish. - - .. note:: - To add verbosity to the build output use the -v -v flags. Example: - ``west -v -v build --build-dir build-tgl --board intel_adsp/cavs25 ./sof/app`` - - To perform a complete clean rebuild, use the --pristine flag. Example: - ``west -v -v build --build-dir build-tgl --pristine always --board intel_adsp/cavs25 ./sof/app`` - - The ``.elf`` file produced by the ``west build`` is missing a - manifest and signature. A a result, you must sign the file using the **rimage tool** - and a **private key** to generate the final firmware image (``.ri`` file). - -#. Build the rimage tool by running the following: - - .. code-block:: bash - - cmake -B ./build-rimage -S ./sof/rimage - cmake --build ./build-rimage - -#. Sign the firmware using the rimage tool and a private key by running the following: - - .. code-block:: bash - - west sign --build-dir ./build-tgl -t rimage --tool-path ./build-rimage/rimage --tool-data ./sof/rimage/config -- -k ./sof/keys/otc_private_key_3k.pem - - **The signed output firmware image file is** ``./build-tgl/zephyr/zephyr.ri`` **.** - - .. note:: - The SOF project provides some pre-generated key pairs of different lengths: - - ``./sof/keys/otc_private_key_3k.pem`` + ``./sof/keys/otc_public_key_3k.pem`` - - ``./sof/keys/otc_private_key.pem`` + ``./sof/keys/otc_public_key.pem`` - - You may wish to generate your own set of keys for firmware signing. - -#. (Optional) Generate debug symbols. - - .. code-block::bash - - ./build-tgl/zephyr/smex_ep/build/smex -l ./build-tgl/zephyr/zephyr.ldc ./build-tgl/zephyr/zephyr.elf - - The output file ``./build-tgl/zephyr/zephyr.ldc`` may be used for reading firmware logs. - -Run -*** - -#. Copy the firmware image(s) to the usual location on all your target - systems. Example: - - .. code-block:: bash - - sudo rsync -a build-sof-staging/sof/ testsystemN.local:/lib/firmware/intel/sof/ - - Note that ``rsync`` also works locally and, unlike ``cp -R``, it is always - idempotent. You may want to use the ``rsync -a --delete`` option to - make absolutely sure you're not running some older version, **but do so - only after first backing up your original sof/ directory**. The - ``--delete`` option is dangerous; use it only in very well-tested - scripts. - - Also make sure nothing in ``/lib/firmware/updates`` takes precedence. Refer to `Firmware search paths `_. - -#. Reboot the system. Note that the location and name of your SOF - firmware image may vary by system. Search your kernel logs with - ``journalctl -k -g sof``, looking for a line - such as the following to identify which file under ``/lib/firmware/`` your hardware is using: - - ``sof-audio-pci 0000:00:0e.0: request_firmware intel/sof/community/sof-apl.ri successful`` - -#. Verify that the new firmware is being used by running the following: - - .. code-block:: bash - - dmesg | grep zephyr - - You should see a line such as the following: - - ``sof-audio-pci 0000:00:0e.0: Firmware info: used compiler GCC 9:2:0 zephyr used optimization flags -Os`` - -For firmware log extraction, use -``zephyr/boards/xtensa/intel_adsp_cavs15/tools/README.md``. - -You might also need to build and update your system audio topology file. For -details see :ref:`build-from-scratch`. - - -Troubleshoot -************ - -#. The west tool version is older than the minimal version requirement defined in the ``./sof/west.yml`` manifest. - - | The manifest file defines the minimal yaml schema version that sets compatibility with west tool according to `Zephyr documentation `_. If your west tools version is not sufficient to process the manifest file, west raises an exception (reference to west 0.12.0 for Windows): - - .. code-block:: bash - - west.manifest.ManifestVersionError: ('0.13', WindowsPath('$ZEPHYR_WORKSPACE/.west/manifest-tmp/west.yml')) - - | In this example, ``./sof/west.yml`` defines minimal version as ``0.13`` while the west tool used has version ``0.12.0``. Update your west tool to a newer version. - diff --git a/getting_started/index.rst b/getting_started/index.rst index 3d585a7c..65ba0480 100644 --- a/getting_started/index.rst +++ b/getting_started/index.rst @@ -3,84 +3,672 @@ Getting Started Guides ###################### -Refer to the following getting started guides if you are new to SOF or if you are performing a task for the first time. +Getting started with Sound Open Firmware (SOF) involves setting up the **Zephyr RTOS** development environment, obtaining the **SOF SDK** and required toolchains, building and signing firmware images for your target hardware or simulator, and deploying the audio topology and binaries. All SOF development—including firmware source code, toolchain integration, Linux kernel drivers, topology definitions, and automated CI testing—happens openly on `GitHub `_. -Build SOF -********* +The high-level steps to get started include: -SOF can be built natively on a host PC or within a container. Use the -container method if the version of your distro is more than six months old. -The SOF SDK uses a recent version of some external dependencies so the -current distro release is always preferred. +1. **Prepare Your Environment**: Set up the Zephyr development workspace, install ``west``, and configure host dependencies and the Zephyr SDK. +2. **Obtain Firmware Toolchains**: Use the recommended Zephyr SDK toolchain or platform-specific cross-compilers (such as Cadence XCC or open-source Clang/LLVM). +3. **Build and Sign Firmware**: Compile firmware with ``west build`` or the Python build scripts, and generate signed manifests using ``rimage``. +4. **Compile Audio Topologies**: Build ALSA Topology 2 configuration graphs (``.tplg``) matching your audio pipeline and hardware interfaces. +5. **Deploy & Validate**: Install the firmware and topology onto target hardware or validate in simulation using the Host Testbench or QEMU DSP simulators. -.. toctree:: - :maxdepth: 1 +SOF SDK & Development Workflow +****************************** + +The SOF SDK provides a complete toolkit connecting source code authoring to compilation, firmware manifest generation, code signing, simulation, and real-time on-target telemetry: + +.. graphviz:: + :caption: SOF SDK Tooling & Development Workflow + :align: center + + digraph sdk_workflow { + rankdir=TB; + nodesep=0.32; + ranksep=0.36; + node [shape=box, style="filled,rounded", fontname="Verdana", fontsize=9, margin="0.12,0.06"]; + edge [fontname="Verdana", fontsize=8, color="#555555"]; + + // 1. SOURCE REPOSITORIES (TOP) + subgraph cluster_sources { + label = "1. Source Code & Configuration Repositories"; + style = "filled,rounded"; + color = "#2c3e50"; + fillcolor = "#eaeded"; + fontname = "Verdana-Bold"; + fontsize = 10; + fontcolor = "#17202a"; + + src_tuning [label="Tuning & Control Scripts\n(Python, Octave EQ/DRC Scripts)", width=2.4, fixedsize=shape, fillcolor="#d5dbdb"]; + src_fw [label="Firmware Source Code (C & ASM)\n(DSP Components, Drivers, Zephyr app)", fillcolor="#d5dbdb"]; + src_tplg [label="Topology 2 Configurations\n(ALSA Conf / m4 Graphs)", width=2.4, fixedsize=shape, fillcolor="#d5dbdb"]; + + { rank=same; src_tuning; src_fw; src_tplg; } + } + + // 2. BUILD & PACKAGING TOOLING (SECOND) + subgraph cluster_build { + label = "2. Build, Packaging & Signing Tooling"; + style = "filled,rounded"; + color = "#2980b9"; + fillcolor = "#ebf5fb"; + fontname = "Verdana-Bold"; + fontsize = 10; + fontcolor = "#1b4f72"; + + tool_llvm [label="Firmware Toolchain\n(Zephyr SDK / Clang / Cadence XCC)", fillcolor="#aed6f1"]; + tool_smex [label="smex Trace Extractor\n(String Dictionary Extractor)", width=2.2, fixedsize=shape, fillcolor="#aed6f1"]; + tool_rimage [label="rimage Signing Tool\n(Manifest & Security Header)", fillcolor="#aed6f1"]; + tool_alsatplg [label="Topology Compiler\n(alsatplg / tplg2)", width=2.2, fixedsize=shape, fillcolor="#aed6f1"]; + + { rank=same; tool_smex; tool_rimage; tool_alsatplg; } + } + + // 3. GENERATED ARTIFACTS (THIRD) + subgraph cluster_artifacts { + label = "3. Generated Build Artifacts"; + style = "filled,rounded"; + color = "#27ae60"; + fillcolor = "#eafaf1"; + fontname = "Verdana-Bold"; + fontsize = 10; + fontcolor = "#145a32"; + + art_dict [label="Trace Dictionary\n(sof-*.ldc)", width=2.2, fixedsize=shape, fillcolor="#a9dfbf", shape=note]; + art_fw [label="Signed Firmware Binary\n(sof-*.ri / sof-*.bin)", fillcolor="#a9dfbf", shape=note]; + art_tplg [label="Compiled Topology Container\n(sof-*.tplg)", width=2.2, fixedsize=shape, fillcolor="#a9dfbf", shape=note]; - build-guide/build-from-scratch - build-guide/build-with-docker - build-guide/build-3rd-party-toolchain - build-guide/build-with-zephyr + { rank=same; art_dict; art_fw; art_tplg; } + } -Set up SOF on a Linux machine -***************************** + // 4. VALIDATION & DEPLOYMENT (BOTTOM) + subgraph cluster_validation { + label = "4. Simulation & Hardware-in-the-Loop Validation"; + style = "filled,rounded"; + color = "#8e44ad"; + fillcolor = "#f4ecf7"; + fontname = "Verdana-Bold"; + fontsize = 10; + fontcolor = "#4a235a"; -You can build the Linux kernel with the latest SOF code and install it locally or remotely with ktest. + runtime_diag [label="Live Probing & Telemetry\n(TCP Probe Server 9999, sof-logger)", width=3.3, fixedsize=shape, fillcolor="#d2b4de"]; + sim_qemu [label="QEMU DSP Simulators\n(ptl-sim, tgl-sim in CI)", fillcolor="#d7bde2"]; + dut_boards [label="Target DUTs & Hardware Boards\n(Spider TGL, Dragon Fly ARL, Aphid PTL, Teensy 4.1)", width=3.3, fixedsize=shape, fillcolor="#d2b4de"]; -Do this first: + sim_tb [label="Host Testbench\n(Bit-Exact Audio Testing)", fillcolor="#d7bde2"]; + esp_bridges [label="ESP32-P4 Audio Bridges\n(I2S / PDM Loopback Cards)", fillcolor="#d2b4de"]; -.. toctree:: - :maxdepth: 1 + { rank=same; runtime_diag; sim_qemu; dut_boards; } + { rank=same; sim_tb; esp_bridges; } + } - setup_linux/prepare_build_environment + // Center spine (Firmware) + src_fw -> tool_llvm [label="compile", weight=20]; + tool_llvm -> tool_rimage [label="ELF", weight=20]; + tool_rimage -> art_fw [weight=20]; + art_fw -> sim_qemu [label="load", weight=20]; -Then proceed based on if you are installing locally or through ktest: + // Left Column + src_tuning -> tool_smex [style=invis, weight=10]; + tool_llvm -> tool_smex [label="ELF", constraint=false]; + tool_smex -> art_dict [weight=10]; + art_dict -> runtime_diag [label="decode", weight=10]; -.. toctree:: - :maxdepth: 1 + // Right Column + src_tplg -> tool_alsatplg [label="compile", weight=10]; + tool_alsatplg -> art_tplg [weight=10]; + art_tplg -> dut_boards [label="deploy", weight=10]; + art_fw -> dut_boards [label="deploy", constraint=false]; - setup_linux/install_locally - setup_linux/setup_ktest_environment + src_tuning -> sim_tb [style=dotted, label="tune", constraint=false]; + src_fw -> sim_tb [style=dotted, label="unit test", constraint=false]; + dut_boards -> esp_bridges [dir=both, label="Audio IO", weight=10]; + dut_boards -> runtime_diag [label="Trace DMA", constraint=false]; + } -Set up SOF on a special device +Core SDK Ingredients +==================== + +* **Firmware Toolchain**: The **Zephyr SDK** is the default toolchain for most platforms. Proprietary compilers like the **Cadence Xtensa compiler (XCC)** are also available and supported for production Intel/Xtensa builds, while open-source **Clang/LLVM Xtensa with Integrated Assembler (IAS)** is available for developers who do not have access to the Cadence compiler. SOF includes optimized SIMD support across target architectures: + + * **Tensilica Xtensa**: HiFi 3, HiFi 4, and HiFi 5 DSP SIMD instruction sets. + * **ARM**: ARM Cortex-M DSP extensions, Helium (Armv8.1-M Vector Extension / MVE), and Neon SIMD. + * **RISC-V**: RISC-V "V" Vector Extension (RVV 1.0) and Packed SIMD / DSP extensions. + +* **Firmware Packaging & Signing (`rimage`)**: Converts compiled ELF binaries into platform-specific signed manifests with optional security headers. + +* **Trace & Log Decoding (`smex` & `sof-logger`)**: Extracts format strings from ELF binaries into a dictionary file (``.ldc``), allowing the DSP to transmit compressed numeric trace IDs decoded in real time on the host. SOF also integrates natively with **Zephyr logging and tracing capabilities** (including Zephyr log backends and dictionary-based logging) for unified system and driver diagnostics. + +* **Real-Time Telemetry & Probing**: The TCP probe server captures raw, multi-channel DMA audio stream taps at runtime over TCP port 9999 without interrupting pipeline execution. + +* **Simulation Environments**: + + * **Host Testbench (`testbench`)**: Compiles DSP processing components into native host executables, allowing bit-exact verification, valgrind memory checking, and audio quality analysis using standard audio files. + * **QEMU DSP Simulators**: Full-system instruction-level simulators (`ptl-sim`, `tgl-sim`) used in automated CI pipelines, and can be used for debug, simulation of cache, and memory usage. + +* **Algorithm Tuning Tools**: Python, MATLAB, and Octave scripts used to calculate filter coefficients for parametric equalizers, DRCs, and beamforming arrays, and to tune modules for best performance. + +.. _build_sof: +.. _build-with-zephyr: +.. _build-from-scratch: +.. _build-with-docker: +.. _build-3rd-party-toolchain: +.. _docker-topology-tools: +.. _build-toolchains-from-source: + +Build and Install SOF Firmware ****************************** -SOF also runs on the MinnowBoard Turbot and the Up Squared board with Hifiberry Dac+. +This guide provides step-by-step instructions to set up the SOF SDK workspace, install system dependencies and the Zephyr SDK toolchain, build firmware images for target DSP platforms, and build host userspace tools. + +All instructions below can be copied directly into your terminal. + +Prerequisites & System Dependencies +=================================== + +Install the required host packages and build tools for your Linux distribution: + +.. tabs:: + + .. tab:: Ubuntu / Debian + + .. code-block:: bash + + sudo apt update && sudo apt install --no-install-recommends \ + git cmake ninja-build gperf ccache dfu-util device-tree-compiler wget \ + python3-dev python3-pip python3-setuptools python3-tk python3-wheel xz-utils file \ + make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1 default-jre python3-venv \ + octave libssl-dev libtool gettext libncurses-dev + + .. tab:: Fedora / RHEL + + .. code-block:: bash + + sudo dnf groupinstall -y "Development Tools" && sudo dnf install -y \ + git cmake ninja-build gperf ccache dfu-util dtc wget \ + python3-devel python3-pip python3-setuptools xz file \ + make gcc gcc-c++ SDL2-devel libmagic java-latest-openjdk-headless \ + octave openssl-devel libtool gettext-devel ncurses-devel + +Step 1: Set Up Workspace & Clone Repositories +============================================= + +Define the workspace directory and clone the SOF SDK source repositories: + +.. code-block:: bash + + export SOF_WORKSPACE=$HOME/work/sof + mkdir -p ${SOF_WORKSPACE} + cd ${SOF_WORKSPACE} + + # Clone core SOF repositories + git clone --progress --recursive https://github.com/thesofproject/sof.git + git clone --progress https://github.com/thesofproject/sof-test.git + git clone --progress https://github.com/thesofproject/sof-docs.git + git clone --progress https://github.com/thesofproject/sof-bin.git + +Step 2: Set Up Python Environment & West +======================================== + +Create a dedicated Python virtual environment, install ``west``, and fetch all Zephyr and SOF dependencies: + +.. code-block:: bash + + cd ${SOF_WORKSPACE} + + # Create and activate Python virtual environment + python3 -m venv .venv + source .venv/bin/activate + + # Install and initialize west + pip install west + west init . + west zephyr-export + west packages pip --install + + # Install documentation and SDK requirements + pip install -r sof-docs/scripts/requirements.txt + + # Initialize and update SOF west manifest + rm -fr .west + west init -l sof + west update + +Step 3: Install Zephyr SDK Toolchain (Mandatory) +================================================ + +The **Zephyr SDK** is the mandatory cross-compilation toolchain required for building SOF. Download and install the official toolchain using ``west sdk install``: + +.. code-block:: bash + + cd ${SOF_WORKSPACE}/zephyr + west sdk install + cd ${SOF_WORKSPACE} + +Optional: Cadence Xtensa Tools (Proprietary XCC) +------------------------------------------------ + +Developers with a Cadence Tensilica license can compile firmware using the proprietary Cadence compiler suite. Ensure your Xtensa tools and core registry are installed and set the environment variables: + +.. code-block:: bash + + # Set path to Cadence Xtensa installation + export XTENSA_TOOLS_ROOT=/path/to/myXtensa + export XTENSA_BUILDS_DIR=${XTENSA_TOOLS_ROOT}/install/builds + export XTENSA_SYSTEM=${XTENSA_BUILDS_DIR}///config + export ZEPHYR_TOOLCHAIN_VARIANT=xt-clang # or xcc + +The SOF build script ``xtensa-build-zephyr.py`` automatically checks for ``XTENSA_TOOLS_ROOT`` and configures the build for your target core. + +Optional: LLVM / Clang Xtensa Toolchain (Open-Source Fork) +---------------------------------------------------------- + +For open-source development on Intel ADSP Xtensa targets without a Cadence license, use the open-source Xtensa LLVM/Clang development fork (`llvm-project `_). + +1. **Clone and Build LLVM/Clang Compiler**: + + .. code-block:: bash + + cd ${SOF_WORKSPACE} + + # Clone the Xtensa development fork (llvm-stable branch) + git clone -b llvm-stable https://github.com/lgirdwood/llvm-project.git + cd llvm-project + + # Configure and build LLVM and Clang + cmake -G Ninja -S llvm -B build \ + -DCMAKE_BUILD_TYPE=Release \ + -DLLVM_ENABLE_PROJECTS="clang;lld" \ + -DLLVM_TARGETS_TO_BUILD="host" \ + -DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD="Xtensa" \ + -DLLVM_ENABLE_ASSERTIONS=OFF \ + -DLLVM_OPTIMIZED_TABLEGEN=ON + + ninja -C build + +2. **Build compiler-rt Builtins**: + + Intel ADSP targets require specific builtins to be compiled with correct target features (windowed ABI, HiFi coprocessor disabled to prevent boot-time exceptions): + + .. code-block:: bash + + # Compile and install compiler-rt builtins for Xtensa Windowed ABI + ./scripts/build_windowed_rt.sh + + # (Optional) For Call0 ABI if needed: + # ./scripts/build_call0_rt.sh + +3. **Integrate Fork Development Branches into Workspace**: + + Pull the required ``llvm-stable`` development branches into your workspace repositories: + + .. code-block:: bash + + cd ${SOF_WORKSPACE} + + # 1. SOF repository + cd sof + git remote add lgirdwood https://github.com/lgirdwood/sof.git + git fetch lgirdwood llvm-stable + git checkout -b llvm-stable-work + git pull lgirdwood llvm-stable + cd .. + + # 2. Zephyr repository + cd zephyr + git remote add lgirdwood https://github.com/lgirdwood/zephyr.git + git fetch lgirdwood llvm-stable + git checkout -b llvm-stable-work + git pull lgirdwood llvm-stable + cd .. + + # 3. Xtensa HAL repository (modules/hal/xtensa) + cd modules/hal/xtensa + git remote add lgirdwood https://github.com/lgirdwood/hal_xtensa.git + git fetch lgirdwood llvm-stable + git checkout -b llvm-stable-work + git pull lgirdwood llvm-stable + cd ../../.. + +4. **Build SOF Using Clang**: + + Pass ``--llvm-clang`` pointing to your LLVM build directory: + + .. code-block:: bash + + cd ${SOF_WORKSPACE} + source .venv/bin/activate + + # Meteor Lake / Arrow Lake (mtl / arl) + ./sof/scripts/xtensa-build-zephyr.py -p mtl --llvm-clang ${SOF_WORKSPACE}/llvm-project/build --build-dir-suffix -llvm + + # Tiger Lake (tgl) + ./sof/scripts/xtensa-build-zephyr.py -p tgl --llvm-clang ${SOF_WORKSPACE}/llvm-project/build --build-dir-suffix -llvm + + # Panther Lake (ptl) + ./sof/scripts/xtensa-build-zephyr.py -p ptl --llvm-clang ${SOF_WORKSPACE}/llvm-project/build --build-dir-suffix -llvm + +.. note:: + + **Integrated Assembler (IAS) Mandatory Policy**: All compilation targeting Xtensa via LLVM Clang must use the LLVM Integrated Assembler (IAS) (enabled by default with ``-fintegrated-as -mtext-section-literals -mlongcalls``). Never pass ``-fno-integrated-as``, as legacy GNU Assembler (GAS) cannot resolve label-difference relocations on Xtensa branch trampolines. + +Step 4: Build Firmware Images +============================= + +Build firmware binaries for your target platform using the SOF build script ``xtensa-build-zephyr.py``: + +- **Build for all supported platforms**: + + .. code-block:: bash + + ./sof/scripts/xtensa-build-zephyr.py -a + +- **Build for a specific platform target**: + + .. code-block:: bash + + # Examples: tgl (Tiger Lake), mtl (Meteor Lake), ptl (Panther Lake), imx8 (NXP i.MX8) + ./sof/scripts/xtensa-build-zephyr.py tgl + +- **Output Staging Directory**: + The build produces signed firmware binaries and trace dictionary files placed in the staging directory: + + .. code-block:: text + + build-sof-staging/sof/ + ├── community/ + │ ├── sof-tgl.ri # Signed firmware image (with optional security headers) + │ └── sof-tgl.ldc # SMEX trace dictionary for log decoding + +Step 5: Deploy Firmware to Target Device +======================================== + +The SOF build script provides a built-in ``--deployable-build`` option that generates target filesystem directories and packages a deployable tarball: + +1. **Build with Deployable Layout**: + + .. code-block:: bash + + cd ${SOF_WORKSPACE} + + # Build deployable firmware package for your target platform + ./sof/scripts/xtensa-build-zephyr.py --deployable-build tgl + +2. **Deployable Output Layout**: + The resulting files in ``build-sof-staging/`` match the target Linux filesystem paths based on IPC architecture: + + - **IPC4 Platforms** (e.g. Tiger Lake, Meteor Lake, Arrow Lake, Panther Lake, Lunar Lake): + + .. code-block:: text + + build-sof-staging/sof/intel/sof-ipc4/ + └── tgl/ + ├── community/ + │ └── sof-tgl.ri # Signed firmware image + ├── dbgkey/ + │ └── sof-tgl.ri # Debug-key signed firmware + ├── sof-tgl.ri # Default symlink + └── sof-tgl.ldc # SMEX trace dictionary + + - **IPC3 Platforms** (e.g. Apollo Lake, Cannon Lake, Ice Lake): + + .. code-block:: text + + build-sof-staging/sof/intel/sof/ + ├── community/ + │ └── sof-apl.ri + └── sof-apl.ldc + +3. **Deploy to Target Device (DUT)**: + Transfer the files to your target development board over SSH: + + .. code-block:: bash + + # Option A: Deploy complete archive via tarball extraction + scp build-sof-staging/sof-*.tar.gz root@:/tmp/ + ssh root@ 'tar -C / -xzf /tmp/sof-*.tar.gz && rm /tmp/sof-*.tar.gz' + + # Option B: Direct copy of firmware binary and trace dictionary + # (Target path for IPC4: /lib/firmware/intel/sof-ipc4//) + scp build-sof-staging/sof/intel/sof-ipc4/tgl/community/sof-tgl.ri root@:/lib/firmware/intel/sof-ipc4/tgl/ + scp build-sof-staging/sof/intel/sof-ipc4/tgl/sof-tgl.ldc root@:/etc/sof/ + +4. **Reload Kernel Audio Driver**: + Reload the SOF sound driver module to initialize the new firmware image: + + .. code-block:: bash + + # Unload and reload PCI audio driver (example for Tiger Lake) + ssh root@ 'modprobe -r snd_sof_pci_intel_tgl && modprobe snd_sof_pci_intel_tgl' + + # Check dmesg for DSP firmware boot verification + ssh root@ 'dmesg | grep -i sof' + +Step 6: Build Host Tools & Testbench +==================================== + +Build the host userspace utilities (such as ``sof-ctl``, topology compiler, and logging tools) as well as the native host audio testbench: + +.. code-block:: bash + + cd ${SOF_WORKSPACE} + + # Build all userspace tools + ./sof/scripts/build-tools.sh -A + ./sof/scripts/build-tools.sh + + # Build native host testbench for bit-exact algorithm verification + ./sof/scripts/rebuild-testbench.sh + +.. _build-and-install-sof-linux-drivers: +.. _prepare-build-environment: +.. _install-locally: + +Build and Install SOF Linux Drivers +*********************************** + +These instructions will help you set up a development environment for the SOF branch of the Linux kernel, configure and compile the kernel with the latest SOF audio drivers, and install it locally on your machine alongside your distribution's default kernel. + +Prerequisites +============= + +* **Development device**: PC running Fedora 35+ or Ubuntu 20.04+. +* **Target device**: PC running Fedora 35+ or Ubuntu 20.04+, with Secure Boot disabled. If the target device is different than the development device, you must be able to SSH into the target (typically on the same local network or VPN). + +Step 1: Set Up Workspace +======================== + +Create a dedicated working directory for kernel development: + +.. code-block:: bash + + export SOF_WORKSPACE=~/work/sof + mkdir -p $SOF_WORKSPACE + cd $SOF_WORKSPACE + +Step 2: Install Kernel Build Dependencies +========================================= + +Install the required build tools and libraries for your Linux distribution: + +.. tabs:: + + .. tab:: Ubuntu / Debian + + .. code-block:: bash + + sudo apt update + sudo apt install -y git libncurses-dev gawk flex bison openssl libssl-dev dkms \ + libelf-dev libudev-dev libpci-dev libiberty-dev autoconf dwarves zstd + + .. tab:: Fedora / RHEL + + .. code-block:: bash + + sudo dnf install -y fedpkg ccache + fedpkg clone -a kernel + cd kernel + sudo dnf builddep -y kernel.spec + cd .. + +Step 3: Download Configuration Scripts & Kernel Source +====================================================== + +Clone the SOF kernel configuration repository and the SOF Linux kernel fork: + +.. code-block:: bash + + cd $SOF_WORKSPACE + + # Download SOF kconfig helper scripts + git clone https://github.com/thesofproject/kconfig.git + +.. _get-kernel-source: + + # Clone SOF Linux kernel source + git clone https://github.com/thesofproject/linux.git --depth=1 + cd linux + +.. note:: + + If a maintainer requests that you check out a specific branch to test a fix, add ``-b `` to the ``git clone`` command. Alternatively, download a zip archive from the `SOF Linux fork on GitHub `_. + +Step 4: Configure the Kernel +============================ + +1. **Load base kernel configuration**: + Copy the running kernel's configuration to use as a baseline: + + .. code-block:: bash + + cd $SOF_WORKSPACE/linux + cp /boot/config-$(uname -r)* .config + +2. **Apply SOF-specific driver configuration**: + The SOF configuration scripts update the base configuration to enable the latest SOF audio drivers. Run one of the following scripts based on your needs (press **Enter** to accept default prompts): + + - **For most users**: + + .. code-block:: bash + + ../kconfig/kconfig-distro-sof-update.sh + + - **For additional debug logging and experimental platform support**: + + .. code-block:: bash + + ../kconfig/kconfig-distro-sof-dev-update.sh + + .. note:: + + By default, these scripts run ``make localmodconfig`` to compile only the modules currently loaded on your system, significantly reducing compile times. If you want to compile all standard modules, remove or comment out the line ``make localmodconfig`` from the script before running it. + +.. _compile-kernel-step: + +Step 5: Compile the Kernel +========================== + +Compile the kernel and modules: + +.. code-block:: bash + + cd $SOF_WORKSPACE/linux + make -j$(nproc --all) + +.. _install-kernel-step: + +Step 6: Install the Kernel Locally +================================== + +Install the compiled kernel modules and kernel image: + +.. code-block:: bash + + cd $SOF_WORKSPACE/linux + sudo make modules_install + sudo make install + +Your custom kernel is now installed alongside your distribution's default kernel. + +Step 7: Boot and Verify +======================= + +1. Reboot your computer. +2. At the GRUB boot menu, select the newly installed kernel (it will have ``-sof`` appended to its version string). On Ubuntu, this may be located under the **Advanced options for Ubuntu** submenu. +3. Once booted, verify that the SOF driver initialized correctly: + + .. code-block:: bash + + uname -r + dmesg | grep -i sof + +Update and Rebuild the Kernel +============================= + +To update your kernel source and rebuild when new driver fixes are available: + +1. **Pull the latest changes**: + + .. code-block:: bash + + cd $SOF_WORKSPACE/linux + git pull + +2. **Clean previous build artifacts** (recommended after branch switches or major code changes): + + .. code-block:: bash + + make clean + +3. **Recompile and reinstall**: + + .. code-block:: bash + + make -j$(nproc --all) + sudo make modules_install + sudo make install + +4. Reboot and select the updated kernel to test. + +Remove the Custom Kernel +======================== + +If you no longer need the custom kernel or need to revert to your distribution's stock kernel: + +.. tabs:: -.. toctree:: - :maxdepth: 1 + .. tab:: Ubuntu / Debian - setup_special_device/setup_minnowboard_turbot - setup_special_device/setup_up_2_board + .. code-block:: bash -Debug Audio issues on Intel platforms -************************************* + cd $SOF_WORKSPACE/linux + sudo rm /boot/*-$(make kernelversion) + sudo rm -rf /lib/modules/$(make kernelversion) + sudo update-grub -Intel platforms rely on different versions of DSP and audio hardware -interfaces. The following sections provide hints for integrators and -users when audio components are not working properly or are broken. + .. tab:: Fedora / RHEL -.. toctree:: - :maxdepth: 1 + .. code-block:: bash - intel_debug/introduction - intel_debug/suggestions + cd $SOF_WORKSPACE/linux + sudo rm /boot/*-$(make kernelversion)* + sudo rm -rf /lib/modules/$(make kernelversion) + sudo grubby --remove-kernel=/boot/vmlinuz-$(make kernelversion) -SOF on NXP platforms -******************** +.. note:: -This section provides guides for integrators and for users working with i.MX platforms. + **Remote Kernel Deployment with ktest**: If you have dedicated test hardware and wish to automate kernel installation and testing over SSH, see :ref:`setup-ktest-environment` in the Developer Guides. -.. toctree:: - :maxdepth: 1 +Next Steps +********** - nxp/sof_imx_user_guide +Congratulations! You have set up your development environment, built and installed the Sound Open Firmware DSP binary, and installed the matching SOF Linux kernel drivers. -Building loadable modules using LMDK -************************************ +You are now ready to begin developing, testing, and debugging with Sound Open Firmware: -This section descibes process of building loadable modules using LMDK. +* Explore :ref:`architectures` to understand the firmware execution model, audio pipelines, and topology architecture. +* Learn about developing custom audio processing algorithms in :ref:`algos`. +* Follow hands-on testing, debugging, and probe streaming tutorials in :ref:`developer_guides`. +* Review hardware setup, board pinouts, and loopback setups in :ref:`platforms`. -.. toctree:: - :maxdepth: 1 - loadable_modules/lmdk_user_guide diff --git a/getting_started/setup_linux/install_locally.rst b/getting_started/setup_linux/install_locally.rst deleted file mode 100644 index ce50ec8f..00000000 --- a/getting_started/setup_linux/install_locally.rst +++ /dev/null @@ -1,134 +0,0 @@ -.. _install-locally: - -Install the Kernel Locally -########################## - -.. contents:: - :local: - :depth: 3 - -Introduction -************ - -Make sure you have `set up your development environment `_ before following these steps. This page will guide you through the process of installing the kernel locally on your machine. It will be installed in addition to your distro's default kernel so that you can always change back to that in case something goes wrong. If you are interested in learning more about this process, there are lots of online guides available, for example `Fedora* Quick Docs `_, `Arch Linux documentation `_ or `this wiki page `_. - - -Build and install the kernel -**************************** - -1. Change directory to ``~/work/sof/linux`` that you created on the setup page. - -#. Load the base kernel configuration. - - The following command copies the configuration of the booted kernel so that it will be used as a base: - - .. code-block:: bash - - cp /boot/config-$(uname -r)* .config - - -#. Apply the SOF-specific configuration. - - - The following scripts update your base configuration so that it uses the latest SOF modules. Run only one of them depending on your needs. If it prompts you with any questions, just press **Enter** to accept the default value. Note that, by default, these scripts will set the configuration to only compile modules that are currently loaded in order to lower compile times. This means that when you've booted from the custom kernel, some external devices may not work if they were not connected while running this script. If you want to compile all modules, delete the line ``make localmodconfig`` from the script you will run in this step. - - - For most users: - - .. code-block:: bash - - ../kconfig/kconfig-distro-sof-update.sh - - - - For additional logging and experimental device support: - - .. code-block:: bash - - ../kconfig/kconfig-distro-sof-dev-update.sh - - .. _compile-kernel-step: - -#. Compile the kernel. - - The first time you run this command, it can take a while (over 30 minutes on some machines), so grab a coffee or take an exercise break while it runs. - - .. code-block:: bash - - make -j$(nproc --all) - - .. _install-kernel-step: - -#. Install the kernel. - - .. code-block:: bash - - sudo make modules_install - sudo make install - -If all went well, your freshly-built kernel will be installed and available at next boot. Restart your computer, and you should have the option to pick a kernel when it turns on. Select the kernel which name has ``-sof`` at the end of it, and your computer should boot as normal using the kernel you just built. On Ubuntu*, the kernel option may be hidden behind the **Advanced options for Ubuntu** submenu. - -Update and rebuild -****************** - -If you need to try some new changes, download the updated code and rebuild the kernel. - -Update the kernel cloned with git ---------------------------------- - -If you originally cloned the repo using git, perform the following steps to update and rebuild the kernel: - -1. Pull the changes. - - .. code-block:: bash - - git pull - -#. Clean the directory. - - .. note:: You should clean up after switching branches or configuration or any other major code change. If you just pulled some minor updates, it's likely unnecessary and will increase your build time. - - .. code:: bash - - make clean - -#. Repeat :ref:`steps 4` :ref:`and 5` to rebuild and reinstall the kernel. - -#. Reboot your computer, and select the kernel with ``-sof`` at the end of its name to test it. - -Update the kernel downloaded via zip ------------------------------------- - -Unfortunately, if you downloaded via zip, the entire process has to be restarted from the :ref:`Get the kernel source` step. There is no good way to incrementally update. However, the kernel build should be faster now as part of it will be cached. - -Make sure you delete the old folder before starting over: - -.. code-block:: bash - - cd .. - rm -rf linux - - -Remove the kernel -***************** - -If you run into issues or no longer need the custom kernel, you can remove it. - -- Ubuntu: - - .. code-block:: bash - - cd ~/work/sof/linux - sudo rm /boot/*-$(make kernelversion) - sudo rm -rf /lib/modules/$(make kernelversion) - sudo update-grub - -- Fedora: - - .. code-block:: bash - - cd ~/work/sof/linux - sudo rm /boot/*-$(make kernelversion)* - sudo rm -rf /lib/modules/$(make kernelversion) - sudo grubby --remove-kernel=/boot/vmlinuz-$(make kernelversion) - - -After rebooting, you should be back to your old kernel with all traces of the custom kernel installation gone. If you'd like, you can also delete the ``~sof`` directory to save disk space. diff --git a/getting_started/setup_linux/prepare_build_environment.rst b/getting_started/setup_linux/prepare_build_environment.rst deleted file mode 100644 index d86cb6aa..00000000 --- a/getting_started/setup_linux/prepare_build_environment.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. _prepare-build-environment: - -Set up a Development Environment to Build the Kernel -#################################################### - -These instructions will help you set up a development environment for the SOF branch of the Linux kernel. If you have dedicated test hardware, you can use ktest to install it over ssh. Otherwise, you can install it locally on your device in addition to your default kernel. - -Review the following prerequisites: - -- **Development device:** PC running Fedora* 35+ or Ubuntu* 20.04+. - -- **Target device:** PC running Fedora 35+ or Ubuntu 20.04+, with secure boot disabled. If the target device is different than the development device, you must be able to ssh into the target, which is typically on the same local network/VPN. - -1. Create a working directory. - - This directory can be located anywhere. Simply change the ``SOF_WORKSPACE`` variable if you would like to store your sources somewhere else. - - .. code-block:: bash - - export SOF_WORKSPACE=~/work/sof - mkdir -p $SOF_WORKSPACE - cd $SOF_WORKSPACE - -#. Install kernel build dependencies. - - - Fedora (see `their guide `_ for details): - - .. code-block:: bash - - sudo dnf install fedpkg - fedpkg clone -a kernel - cd kernel - sudo dnf builddep kernel.spec - sudo dnf install ccache - cd .. - - - Ubuntu (see `their page `_ for details): - - .. code-block:: bash - - sudo apt update - sudo apt install git libncurses-dev gawk flex bison openssl libssl-dev dkms libelf-dev libudev-dev libpci-dev libiberty-dev autoconf dwarves zstd - -#. Download the configuration scripts. - - .. code-block:: bash - - git clone https://github.com/thesofproject/kconfig.git - - .. _get-kernel-source: - -#. Get the kernel source. - - There are two ways to get the kernel source. We strongly recommend using git as it makes updates **much** easier, but the zip download may be more successful if you have an unstable connection. - - - Option 1: Clone with git. - - .. code-block:: bash - - git clone https://github.com/thesofproject/linux.git --depth=1 - cd linux - - .. note:: - - If a maintainer requests that you check out a different branch to test a bug fix, add ``-b [branch]`` to the end of this command, where `[branch]` is the branch name. - - - Option 2: Download via zip. - - Visit the SOF Linux fork at https://github.com/thesofproject/linux. If a maintainer asks you to test a specific branch, click the dropdown with the text "topic/sof-dev" and select the branch they asked you to test. Then, click the green **Code** dropdown and select **Download ZIP**. Once it is downloaded, extract it to the directory you created in the previous step: - - .. code-block:: bash - - cd ~/Downloads - unzip linux-*.zip -d $SOF_WORKSPACE - cd $SOF_WORKSPACE - mv linux-* linux - cd linux - -Your device should now be ready to configure and build the kernel. How to proceed depends on if you are installing :ref:`locally` or on :ref:`dedicated test hardware`. diff --git a/images/sof-favicon-16x16.png b/images/sof-favicon-16x16.png index 65388680..93bc02aa 100644 Binary files a/images/sof-favicon-16x16.png and b/images/sof-favicon-16x16.png differ diff --git a/images/sof-favicon-32x32.png b/images/sof-favicon-32x32.png new file mode 100644 index 00000000..f234f547 Binary files /dev/null and b/images/sof-favicon-32x32.png differ diff --git a/images/sof-favicon-dark-16x16.png b/images/sof-favicon-dark-16x16.png new file mode 100644 index 00000000..9dfca361 Binary files /dev/null and b/images/sof-favicon-dark-16x16.png differ diff --git a/images/sof-favicon-dark.png b/images/sof-favicon-dark.png new file mode 100644 index 00000000..1ab2ccdb Binary files /dev/null and b/images/sof-favicon-dark.png differ diff --git a/images/sof-favicon-light-16x16.png b/images/sof-favicon-light-16x16.png new file mode 100644 index 00000000..f9ee7456 Binary files /dev/null and b/images/sof-favicon-light-16x16.png differ diff --git a/images/sof-favicon-light.png b/images/sof-favicon-light.png new file mode 100644 index 00000000..94d8f932 Binary files /dev/null and b/images/sof-favicon-light.png differ diff --git a/images/sof-favicon.svg b/images/sof-favicon.svg new file mode 100644 index 00000000..aba644d1 --- /dev/null +++ b/images/sof-favicon.svg @@ -0,0 +1,17 @@ + + + + + + + diff --git a/images/vendors/amd.svg b/images/vendors/amd.svg new file mode 100644 index 00000000..3bb92b98 --- /dev/null +++ b/images/vendors/amd.svg @@ -0,0 +1,8 @@ + + + + + + + AMD + \ No newline at end of file diff --git a/images/vendors/espressif.svg b/images/vendors/espressif.svg new file mode 100644 index 00000000..ef5c2363 --- /dev/null +++ b/images/vendors/espressif.svg @@ -0,0 +1,6 @@ + + + + + ESP32 + \ No newline at end of file diff --git a/images/vendors/intel.svg b/images/vendors/intel.svg new file mode 100644 index 00000000..5558d42d --- /dev/null +++ b/images/vendors/intel.svg @@ -0,0 +1,7 @@ + + + + + + intel + \ No newline at end of file diff --git a/images/vendors/mediatek.svg b/images/vendors/mediatek.svg new file mode 100644 index 00000000..0fba5766 --- /dev/null +++ b/images/vendors/mediatek.svg @@ -0,0 +1,6 @@ + + + + + MTK + \ No newline at end of file diff --git a/images/vendors/nxp.svg b/images/vendors/nxp.svg new file mode 100644 index 00000000..20fc9f35 --- /dev/null +++ b/images/vendors/nxp.svg @@ -0,0 +1,10 @@ + + + + + + + N + X + P + \ No newline at end of file diff --git a/images/vendors/pjrc.svg b/images/vendors/pjrc.svg new file mode 100644 index 00000000..aac71acd --- /dev/null +++ b/images/vendors/pjrc.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + 4.1 + \ No newline at end of file diff --git a/images/vendors/qemu.svg b/images/vendors/qemu.svg new file mode 100644 index 00000000..5896112f --- /dev/null +++ b/images/vendors/qemu.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/index.rst b/index.rst index 500c5794..db782943 100644 --- a/index.rst +++ b/index.rst @@ -1,30 +1,40 @@ .. _SOF_home: -SOF Project documentation -######################### +Sound Open Firmware Documentation +################################# -Welcome to the SOF Project (version |version|) documentation. +Welcome to the **Sound Open Firmware (SOF)** technical documentation portal (version |version|). -For information about the changes and additions for releases, please -consult the published :ref:`release` documentation. +Sound Open Firmware is a permissively licensed, open-source audio DSP firmware, SDK, and Linux/Zephyr audio framework providing vendor-independent, transparent audio processing infrastructure across diverse DSP hardware architectures. -Source code for the SOF Project is maintained in the -`SOF Project GitHub repo`_, and is provided under the BSD 3-clause -license. +.. note:: + Looking for high-level project announcements, community blogs, and events? Visit the main `SOF Project Website `_. -.. _BSD 3-clause license: - https://github.com/thesofproject/sof/blob/master/LICENCE +Overview & Quick Navigation +*************************** -.. _SOF Project GitHub repo: https://github.com/thesofproject +* :ref:`Getting Started ` + Set up your build environment, compile firmware for target platforms, and run tests in simulation. +* :ref:`Architecture & System Design ` + End-to-end system design: Host Linux ASoC drivers, IPC protocols (IPC3/IPC4), Zephyr RTOS integration, and memory paging. +* :ref:`Supported Platforms Matrix ` + Hardware compatibility list spanning Intel CAVS/ACE, AMD, NXP, MediaTek, Teensy 4.1, and ESP32-P4 bridges. +* :ref:`Audio Algorithms & Features ` + Processing modules catalog: Volume, Mixer, SRC, EQ, DRC, AEC, Beamforming, WoV, AAC/MP3 VFPU, and Steam Audio. +* :ref:`Developer Guides ` + Deep-dives into Topology 2, LLEXT dynamic module loading, real-time trace probing, and debugging. +* :ref:`API Reference ` + Doxygen-generated C API documentation for firmware interfaces, components, and driver ABIs. +* :ref:`Frequently Asked Questions (FAQ) ` + Quick answers to architectural, algorithmic, hardware compatibility, simulation, and licensing questions. - -Sections -******** +Documentation Sections +********************** .. toctree:: :maxdepth: 1 - SOF project website + SOF Project Website introduction/index.rst getting_started/index.rst architectures/index.rst @@ -37,3 +47,4 @@ Sections maintainers/index.rst api/index.rst presentations/index.rst + faq/index.rst diff --git a/introduction/images/sof-waveform.jpeg b/introduction/images/sof-waveform.jpeg new file mode 100644 index 00000000..dba1deba Binary files /dev/null and b/introduction/images/sof-waveform.jpeg differ diff --git a/introduction/index.rst b/introduction/index.rst index 6b007c57..99b0c2fd 100644 --- a/introduction/index.rst +++ b/introduction/index.rst @@ -3,246 +3,76 @@ Introduction to the SOF Project ############################### -|SOF| (SOF) is an open source audio Digital Signal Processing (DSP) firmware -infrastructure and SDK. SOF provides infrastructure, real-time control -pieces, and audio drivers as a community project. The project is governed by -the |SOF| |TSC| (TSC) that includes prominent and active developers from the -community. SOF is developed in public and hosted on the github platform. +Sound Open Firmware (SOF) is a permissively licensed, open-source, vendor-independent audio Digital Signal Processing (DSP) firmware infrastructure, SDK, and host driver framework. -The firmware and SDK are intended for developers who are interested in -audio or signal processing on modern DSPs. SOF provides a framework where -audio developers can create, test, and tune the following: +Governed under the Linux Foundation and directed by the SOF Technical Steering Committee (TSC), the project provides transparent, real-time audio processing infrastructure for modern computing devices spanning embedded microcontrollers to multi-core client architectures. -- Audio processing pipelines and topologies. +.. figure:: images/sof-waveform.jpeg + :alt: Sound Open Firmware audio DSP processing + :align: center -- Audio processing components. +Project Mission +*************** -- DSP infrastructure and drivers. +The mission of the SOF project is to: -- Host OS infrastructure and drivers. +1. **Democratize Audio DSP Development**: Provide open-source audio firmware and software infrastructure that can be blended with audio processing algorithms (including 3rd-party proprietary algorithms) to provide developers with a rich, customizable method to bring high-quality audio processing to many devices. +2. **Standardize Across Architectures**: Enable a unified firmware core and API capable of running seamlessly across diverse DSP architectures (Xtensa HiFi3/HiFi4/HiFi5, ARM Cortex-M, RISC-V) and silicon vendors (Intel, AMD, NXP, MediaTek, Espressif, PJRC). +3. **Foster Innovation in Audio Algorithms**: Empower audio algorithm researchers and software engineers to develop, deploy, and tune advanced signal processing modules (e.g. spatial audio, voice processing, noise cancellation, neural audio processing) with standard tooling. +4. **Deliver Enterprise-Grade Reliability & Low Power**: Support aggressive power gating (D0ix runtime idle, D3 cold suspend), dynamic memory paging (IMR), and low-latency audio pipelines meeting demanding client and embedded requirements. -.. figure:: images/pipeline-overview.png - :align: center - :alt: SDK Overview - :width: 1000px - :height: 300px +Benefits of Audio DSP Offloading +******************************** - `Example Equalizer pipeline with host OS control of EQ coefficients and pipeline volume.` +Modern computing platforms incorporate dedicated audio DSPs to offload real-time signal processing from host general-purpose CPUs. Offloading audio workloads to SOF provides four foundational advantages: +1. **Lower Power than Host CPU**: Audio DSPs are purpose-built architectures optimized for continuous, energy-efficient streaming with specialized SIMD instruction sets (such as Tensilica HiFi or ARM Helium) and aggressive power gating (D0ix states, power-islanded SRAM pools). Offloading allows power-hungry host CPU cores and high-speed DRAM interfaces to remain in deep sleep states (C-states / S0ix) during audio playback and always-on voice listening. +2. **Lower Latency Processing than Host**: Operating on dedicated real-time DSP hardware running the Zephyr RTOS enables deterministic, sub-millisecond pipeline scheduling without the scheduling jitter, thread preemption, page faults, or context-switching overhead inherent in general-purpose host operating systems. +3. **More Vertical Audio Stack**: All audio pre-processing (microphone array beamforming, acoustic echo cancellation, noise suppression) and post-processing (parametric equalization, dynamic range compression, speaker protection, spatial audio) are centralized directly within the DSP firmware for all physical audio endpoints (SoundWire, I2S, HD-Audio, USB, Bluetooth). This establishes a consistent, high-fidelity signal chain independent of host OS variants or user-space sound servers. +4. **Free Up Host CPU for Other Work**: Intensive signal processing tasks—such as high-order polyphase sample rate conversion (SRC), multi-stream mixing, codec decoding/encoding, and neural speech enhancement—execute entirely on the DSP, liberating valuable host CPU cycles and memory bandwidth for applications, gaming, and OS workloads. -|SOF| has a modular and generic codebase and can be ported to different DSP -architectures or host platforms. See the list of currently supported DSP -architecures and supported platforms. +Architecture Overview +********************* +Sound Open Firmware supports two foundational deployment models tailored for diverse device form-factors: -SDK Introduction and Overview -============================= +* **Host-Based Architecture**: Where the audio DSP is coupled to a host application processor running **Linux**, **Android**, or **ChromeOS**. The host OS driver stack (mainline Linux ``sound/soc/sof/``) manages firmware lifecycle, dynamic topology loading, and power management (D0ix/D3), while audio data streams through host DMA memory windows via IPC (IPC3/IPC4). +* **Hostless (Standalone / Embedded) Architecture**: Where SOF runs autonomously on microcontrollers and standalone DSPs (such as the **ESP32-P4** or **Teensy 4.1 / i.MX RT1062**) atop the Zephyr RTOS. These systems process audio directly between physical hardware peripherals (I2S, SoundWire, PDM microphones, and Bluetooth transceivers) using ROM-embedded static topologies. -The |SOF| SDK is comprised of many ingredients that can be customized for -use in the firmware/software development lifecycle. Customization allows for -a "best fit" development approach where the SDK can be optimized for a -particular process or environment. Some SDK ingredients are optional while -there can be more than once choice for other ingredients as shown in the diagram below. +.. seealso:: + For complete system stack diagrams, hostless designs, real-time pipeline DAGs, and memory hierarchy details, refer to the comprehensive :ref:`Architecture & System Design ` documentation. -.. figure:: images/sdk-overview.png - :align: center - :alt: SDK Overview - :width: 1000px - `SDK example configuration showing development flow for SOF on the Intel Apollo Lake platform running Linux OS. Note the choice of compiler toolchains and choice of optional DSP emulators.` +Development & Build Workflows +***************************** +The SOF project provides a comprehensive SDK comprising modern LLVM/Clang cross-compiler toolchains with Integrated Assembler (IAS), firmware image packaging and signing utilities (``rimage``), real-time string dictionary extractors (``smex``), QEMU DSP simulation environments, and automated hardware-in-the-loop test bridges. -SOF source code, tools, and topologies --------------------------------------- +.. seealso:: + To explore the full SDK development workflow diagram and step-by-step compilation guides, see the :ref:`Getting Started Guides `. -All firmware, tools, and topologies exists in the main SOF git repository. -On a high level, the repo contains: +Licensing & Governance +********************** -- Firmware - written in C with some architecture-specific assembler; it does not link to external dependencies. +The SOF project embraces open, permissive licensing to encourage broad industry adoption while protecting community contributions: -- Test Bench - allows firmware components and pipelines to run on developers' host PCs. +Firmware License +================ +* **BSD 3-Clause License**: The core firmware codebase is released under the permissive BSD 3-Clause license, with certain helper components under MIT. +* **Proprietary & 3rd-Party Modules**: The permissive license permits commercial vendors and research teams to implement custom or proprietary audio processing modules without being forced to open-source proprietary IP. -- Image Tools - C tools for converting ELF files to binary firmware images that can run on HW. +Host Driver License +=================== +* **Dual BSD / GPLv2**: Core platform-independent driver abstractions are dual-licensed BSD 3-Clause / GPLv2. +* **Linux Kernel Upstream (GPLv2)**: The Linux kernel integration layers upstream in ``sound/soc/sof/`` are licensed under the GNU General Public License v2 (GPLv2). -- Debug Tools - scripts and tools that can be used to debug firmware. +Topology & SDK Tools License +============================ +* All topology definitions, build scripts, packaging utilities (`rimage`), and development tools are licensed under permissive licenses (BSD 3-Clause or MIT). -- Trace Tools - text-based tools that can display tracing data from firmware. +Project Governance +================== +SOF is an open-source project hosted under the Linux Foundation. Technical direction is governed by the **Technical Steering Committee (TSC)**, representing member companies, independent developers, and audio hardware manufacturers. All architectural decisions, RFCs, and code reviews are conducted transparently in public on GitHub. -- Tuning Tools - MATLAB/Octave scripts that can be used to create tuning coefficients for audio components. - -- Runtime Tools - command line applications that can be used to exchange data with running firmware. - -- Topologies - real and example topologies that show construction of simple and complex audio processing pipelines. - - -Host OS Drivers ---------------- - -SOF can be configured and controlled by a host OS driver or it can -optionally run as standalone firmware. SOF host drivers currently support -Linux OS. - -The SOF driver has a modular stack-based architecture that is dual-licensed -BSD & GPL code, allowing it to be ported to other OSes and RTOSes. - -The host driver is responsible for: - -- Loading firmware from the host file system into DSP memories and booting. - -- Loading topologies from the host file system into DSP. - -- Exposing audio control devices to applications. - -- Exposing audio data endpoints to applications. - -- Managing IPC communication between the host and DSP. - -- Abstraction of the host-side DSP hardware to common API operations. - -The Linux SOF ALSA/ASoC driver is upstream in Linux v5.2 onwards. - - -Firmware Toolchain ------------------- - -GNU GCC can be used as a free SOF compiler alongside proprietary DSP vendor -compilers. The choice of compiler is up to the user, depending on features -and budget. GCC complier is open source. - - -DSP Emulator ------------- - -Qemu can be used to provide a functional emulator to simultaneously trace and -debug driver and DSP firmware code. Proprietary emulators are also available. - -Emulation is also used within SOF CI for feature validation prior to merging -new code. - - -General FAQ -=========== - -What license does the firmware use? - The firmware is released using a standard BSD 3-clause license with some - files released under MIT. - -Do I need to open source my firmware code changes? - No. The firmware BSD and MIT licensed code means you can keep code - changes private. Patches are always welcomed if you do decide to open - source work. - -What license does the host driver use? - Most of the host driver code is dual-licensed BSD or GLPLv2 only - (user's choice). The part of the driver that is GPLv2 only is the Linux - integration layer at the top of the driver stack. - -Do I need to open source my driver code changes? - No, for the bottom two layers of the driver stack. For example, if you are - porting the driver to another OS, these changes can be kept private. Note - that all driver GPL source files are Linux-specific and should not be - ported to another OS. - -How can I get involved? - The best way to get involved is via github. You can also join our - low-volume `mailing list `_. - -What is the development model? - |SOF| is entirely developed on github. Patches via Pull Requests are - reviewed, discussed, and tested by CI before being merged. The intended - release cadence is every 6 - 8 weeks. A stable release is tagged after - passing QA; development continues for the next release. - -Who works on |SOF|? - Professional developers from a number of companies (check the git - logs if you want to know) with some hobbyist developers, too. - -How do I add support for host architecture X? - See the SOF architecture pages. - -How do I add support for host platform X? - Adding a new host platform is a lot simpler than adding a new DSP - architecture. A new host platform consists of adding a new src/platform/ - directory, together with mappings for memory, IRQs, GPIOs, and peripheral - devices in the DSP memory space. New drivers may also have to be added - (e.g. for DMA, I2S) to the drivers directory. - -How do I port to other OSes? - See the SOF host architecture page. - -What audio components are supported? - |SOF| now supports a small library of free and open source components that - are distrubuted alongside the source code. SOF can also support proprietary - audio processing components provided they are wrapped to use the SOF - component API. See the audio components page for a list of open - source components and their capabilites. - -How do I create my own pipelines? - Pipelines are currently defined using the M4 macro processing language. - The M4 topology is then preprocessed to the alsaconf format before being - compiled into a binary. An Eclipse-based GUI for pipeline construction is - currently under development. - - Today, both static (built in) and dynamic (loaded at runtime) pipelines are - supported in upstream. - -Can I add my own media encoder/decoders? - Yes. - -Can I add non-audio functions? - Yes. The instruction sets used by DSPs are also good at non-audio - processing tasks such as low-power sensor signal processing. If - your DSP has physical IO ports to which other non-audio devices can be connected, then data can also be processed from these devices. - -Toolchain FAQ -============= - -Which Xtensa toolchains does SOF currently support? - Two toolchain families are currently supported by SOF: The GCC and the Cadence XCC. - - These families are subdivided into toolchains per Xtensa ISA because the Tensilica architecture contains a variable instruction set so you must use the toolchain variant that matches your platform. - - 1. Custom, open-source GCC toolchains built with crosstool-NG as - documented in the getting started guide. These must be built from - source. For instructions, refer to the following: - - - :ref:`build-toolchains-from-source` in the Getting Started Guide - for building SOF from scratch - - - `Toolchains and embedded distributions `_ - - 2. Cadence's partially closed source toolchains. The Cadence XCC compiler - is proprietary but uses the open source GNU binutils. XCC must be - bought from Cadence. For more information, see: - - - :ref:`build-3rd-party-toolchain` - - - `Cadence IP portfolio `_ - - The Cadence binutils patches or overlays are located in the SOF git - repo. - - Note that Cadence is not the only Tensilica user; some Xtensa - toolchains come from `elsewhere `_. However, as of June 2020, all platforms - supported by SOF come from Cadence. - -What are the primary differences between Cadence and gcc toolchains? - gcc toolchains are completely open source. Cadence's toolchains use either - a gcc-based or a clang-based open source frontend and a closed-source - backend that matches the platform. - - XCC supports full Xtensa HiFi SIMD intrinsics whereas GCC has no HiFi SIMD - support. This can lead to large performance differences, especially in - code that deals with audio processing. - -Cadence xt-xcc or Cadence xt-clang? - It depends on the platform. As of June 2020, most platforms supported by - SOF rely on xt-xcc. Going forward, all newer platforms require xt-clang. - The gcc frontend doesn't support unusually large registers, hence the move - to xt-clang. - - Note that xt-xcc does not fully support C99. xt-clang does. - -Is support for other toolchains forthcoming? - Going forward, we would like to support the LLVM C compiler. Patches are - welcome. +.. seealso:: + For answers to common architectural, audio module development, platform compatibility, simulation, and licensing questions, see the dedicated :ref:`Frequently Asked Questions (FAQ) ` page. diff --git a/platforms/index.rst b/platforms/index.rst index a582511d..07d48b06 100644 --- a/platforms/index.rst +++ b/platforms/index.rst @@ -8,27 +8,7 @@ Supported Platforms Platform and board specific support is continually added to the SOF project as documented below. -.. csv-table:: Supported Platforms - :header: "Platform", "Architecture", "Cores/Clocks", "Platform Clock", "Memory", "Audio Interfaces" - :widths: 20, 20, 10, 10, 10, 20 - - "Host Testbench", "PC command line", "N/A", "N/A", "N/A", "N/A Files are used to simulate audio interfaces" - "Qemu", "All supported SOF HW platforms", "N/A", "N/A", "N/A", "WiP Files will be used to simulate audio interfaces" - "Intel Tiger Lake with IPC4", "Xtensa HiFi3", "4 @ 120 - 400MHz", "38.4MHz", "64KB LP SRAM / 2944KB HP SRAM", "6 x SSP (I2S, PCM), HDA, DMIC, Soundwire" - "Intel Alder Lake with IPC4", "Xtensa HiFi3", "4 @ 120 - 400MHz", "38.4MHz", "64KB LP SRAM / 2944KB HP SRAM", "6 x SSP (I2S, PCM), HDA, DMIC, Soundwire" - "NXP i.MX8", "Xtensa HiFi4", "1 @ 666MHz", "TBD", "64 KB TCM / 448 KB OCRAM / 8MB SDRAM", "1 x ESAI, 1 x SAI" - "NXP i.MX8X", "Xtensa HiFi4", "1 @ 640MHz", "TBD", "64 KB TCM / 448 KB OCRAM / 8MB SDRAM", "1 x ESAI, 1 x SAI" - "NXP i.MX8M", "Xtensa HiFi4", "1 @ 800MHz", "TBD", "64 KB TCM / 256 KB OCRAM / 8MB SDRAM", "1 x SAI, MICFIL" - "NXP i.MX8ULP", "Xtensa HiFi4", "1 @ 520MHz", "TBD", "64 KB TCM / 256 KB OCRAM / 8MB SDRAM", "1 x SAI" - "AMD Renoir", "Xtensa HiFi3", "1 @ 200-600MHz", "TBD", "20 KB LP SRAM / 1152 KB IRAM/DRAM", "1 x SP (I2S, PCM), 1 x BT (I2S, PCM), DMIC" - "AMD Rembrandt", "Xtensa HiFi5", "1 @ 200-800MHz", "TBD", "1.75 MB HP SRAM / 512 KB IRAM/DRAM", "1 x SP (I2S, PCM), 1 x BT (I2S, PCM), 1 x HS(I2S, PCM), DMIC" - "Mediatek mt8195", "Xtensa HiFi4", "1 @ 220 - 720MHz", "TBD", "256 KB SRAM / 16 MB DRAM", "2 x TDM Out, 1 x TDM In, DMIC" - "Mediatek mt8186", "Xtensa HiFi5", "1 @ 300 - 800MHz", "TBD", "512 KB SRAM / DRAM", "2 x I2S Out, 1 x I2S In, DMIC" - "Mediatek mt8188", "Xtensa HiFi5", "1 @ 26 - 800MHz", "TBD", "512 KB SRAM / 17 MB DRAM", "2 x TDM Out, 1 x TDM In, DMIC" - -When support for a new platform is being added, certain interfaces required by -SOF infrastructure must be implemented. Refer to Platform API documentation -for details. +.. include:: _generated_platforms_table.rst Some platforms have been supported by SOF in the past, but are no longer supported in SOF mainline ("main" branch). Below table lists such platforms, @@ -36,57 +16,9 @@ the last SOF major release that had support for the platform and the stable branch to use. For every SOF release, a stable branch is created and critical bugfixes can be submitted and released via these stable branches. -.. csv-table:: Platforms No Longer Supported in Mainline - :header: "Platform", "Last Release", "Branch", "Architecture", "Cores/Clocks", "Platform Clock", "Memory", "Audio Interfaces" - :widths: 20, 10, 10, 20, 10, 10, 10, 20 - - "Intel Bay Trail / Merrifield", "2.2", "stable-v2.2", "Xtensa HiFi2 EP", "1 @ 50 - 400MHz", "25MHz", "96KB IRAM / 192KB DRAM", "3 x SSP (I2S, PCM)" - "Intel Cherry Trail / Braswell", "2.2", "stable-v2.2", "Xtensa HiFi2 EP", "1 @ 50 - 400MHz", "19.2MHz", "96KB IRAM / 192KB DRAM", "6 x SSP (I2S, PCM)" - "Intel Broadwell", "2.2", "stable-v2.2", "Xtensa HiFi2 EP", "1 @ 50 - 400MHz", "24MHz", "320KB IRAM / 640KB DRAM", "2 x SSP (I2S, PCM)" - "Intel Apollo Lake / Gemini Lake", "2.2", "stable-v2.2", "Xtensa HiFi3", "2 @ 100 - 400MHz", "19.2MHz", "128KB LP SRAM / 512KB HP SRAM", "6 x SSP (I2S, PCM), HDA, DMIC" - "Intel Cannon Lake / Whiskey Lake / Comet Lake", "2.2", "stable-v2.2", "Xtensa HiFi3", "4 @ 120 - 400MHz", "24MHz", "64KB LP / 3008KB HP SRAM", "3 x SSP (I2S, PCM), HDA, DMIC, Soundwire" - "Intel Sue Creek", "2.2", "stable-v2.2", "Xtensa HiFi3", "2 @ 120 - 400MHz","24MHz", "64KB LP SRAM / 4096KB HP SRAM", "6 x SSP (I2S, PCM), DMIC" - "Intel Ice Lake", "2.2", "stable-v2.2", "Xtensa HiFi3", "4 @ 120 - 400MHz", "38.4MHz", "64KB LP SRAM / 3008KB HP SRAM", "6 x SSP (I2S, PCM), HDA, DMIC, Soundwire" - "Intel Jasper Lake", "2.2", "stable-v2.2", "Xtensa HiFi3", "2 @ 120 - 400MHz", "38.4MHz", "64KB LP SRAM / 1024KB HP SRAM", "3 x SSP (I2S, PCM), HDA, DMIC, Soundwire" - "Intel Tiger Lake with IPC3", "2.2", "stable-v2.2", "Xtensa HiFi3", "4 @ 120 - 400MHz", "38.4MHz", "64KB LP SRAM / 2944KB HP SRAM", "6 x SSP (I2S, PCM), HDA, DMIC, Soundwire" - "Intel Alder Lake with IPC3", "2.2", "stable-v2.2", "Xtensa HiFi3", "4 @ 120 - 400MHz", "38.4MHz", "64KB LP SRAM / 2944KB HP SRAM", "6 x SSP (I2S, PCM), HDA, DMIC, Soundwire" +.. include:: _generated_legacy_platforms_table.rst The periodic sof-bin releases contain latest binaries for all platforms, both from SOF main and latest binaries from "stable-vX.YY" branches. - -Minimum Platform Requirements -***************************** - -Footprint -========= - -DSP platforms can vary from vendor to vendor but in general SOF can run on -small platforms like Intel Bay Trail DSP with 96kb of instruction RAM and 168kb -of data RAM. The SOF footprint can be shrunk to approximately 50kb of TEXT -and DATA by fine-tuning runtime features via Kconfig. - -DSP Clock Speed -=============== - -Required DSP clock speed depends on the DSP processing load, so it can vary greatly depending on pipeline topology and the algorithm design that is running. SOF can run several volume passthrough pipelines on the Intel Bay Trail DSP at 50MHz using unoptimized C code (SIMD disabled and compiled with GCC). - -Toolchain -========= - -It's recommended to use the best optimizing compiler available for your DSP ISA; however, GCC can also be used provided it has your DSP architecture support. GCC will produce functional code, but it may not necessarily be the fastest code for your DSP architecture. - - -.. TODO: Replace with reference to API tree once created. - -Platform Specific Information -***************************** - -Further information on specific platforms can be found here. - -.. toctree:: - :maxdepth: 2 - - intel-legacy/index - intel-cavs/index diff --git a/release.rst b/release.rst index ee119d71..1b52522d 100644 --- a/release.rst +++ b/release.rst @@ -1,59 +1,99 @@ .. _release: -Release -####### +Firmware Binary Releases +######################## -Firmware and Tools -****************** - -The SOF firmware and tools can be downloaded either as a compressed source -release, binary release, or via Git. - -Git ---- - -All project SOF source code is maintained in the https://github.com/thesofproject -repository and includes folders for SOF, SOF tools and topologies, the Linux -kernel, and documentation. Download the source code as a zip or tar.gz file: - -.. code-block:: bash - - git clone https://github.com/thesofproject/sof.git - cd sof.git - git checkout master -b master +Sound Open Firmware distributes official, pre-compiled, and signed firmware binaries, +compiled ALSA topology files (``.tplg``), and target installation tools through the official +`sof-bin `_ repository on GitHub. +Unlike building from source, binary releases are tested, package-ready archives suitable +for end users, Linux distributions, and automated lab deployment across Intel, AMD, and NXP targets. -Source and Binary Releases --------------------------- +Official Binary Releases +************************ -The latest SOF release is v2.11.0 (Sept 2024). +.. include:: _generated_sof_bin_releases.rst -View new feature information and release downloads for the latest and -previous releases on GitHub. Firmware and SDK tool source code and binary -releases are located here as well: +Release Contents +**************** - https://github.com/thesofproject/sof/releases +Each official release archive (``sof-bin-YYYY.MM[.patch].tar.gz``) contains complete firmware bundles +organized by architecture and IPC protocol: -Binary releases for different platforms are made available via the ``sof-bin`` repository: +* **Signed DSP Firmware** (``.ri``): Cryptographically signed binaries for CAVS (Intel Tiger Lake), ACE 1.5 (Meteor Lake, Arrow Lake), and ACE 3.0 (Panther Lake). +* **Compiled ALSA Topologies** (``.tplg``): Hardware-specific pipeline routing, codec DAIs, clocking, and audio algorithm graphs. +* **Dual IPC Support**: Separate trees for IPC3 (legacy CAVS) and IPC4 (modern ACE platforms). +* **Automated Installation Script** (``install.sh``): Shell script that copies binaries to the correct system paths and creates platform symlinks. +* **Tools and Diagnostic Utilities**: User-space utilities for debugging, probing, and topology verification. - https://github.com/thesofproject/sof-bin - -Intermediate releases are also included on this page. General releases -include the "vX.Y" naming convention and are tagged on GitHub as such. - - -Linux Driver -************ - -The SOF Linux driver is upstreamed from Linux version 5.2 onwards. It is -included as part of official Linux releases from v5.2. +Installation Guide +****************** -The following SOF Linux driver development branch includes new features that -are integrated prior to upstreaming. +To install or upgrade the firmware binaries on a Linux host or target DUT: .. code-block:: bash - git clone https://github.com/thesofproject/linux.git - cd linux.git - git checkout origin/sof-dev -b sof-dev - + # 1. Download the release archive (replace with your desired version) + curl -L -O https://github.com/thesofproject/sof-bin/releases/download/v2025.12.2/sof-bin-2025.12.2.tar.gz + + # 2. Extract the archive + tar -xzf sof-bin-2025.12.2.tar.gz + cd sof-bin-2025.12.2 + + # 3. Run the installer script (copies firmware & topologies to /lib/firmware/) + sudo ./install.sh + + # 4. Reload the audio driver or reboot + sudo modprobe -r snd_sof_pci_intel_tgl && sudo modprobe snd_sof_pci_intel_tgl + +Target Filesystem Layout +======================== + +The installer stages binaries into standard Linux firmware paths: + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Destination Path + - Description + * - ``/lib/firmware/intel/sof/`` + - Signed firmware binaries (e.g. ``sof-tgl.ri``, ``sof-mtl.ri``, ``sof-ptl.ri``) + * - ``/lib/firmware/intel/sof-tplg/`` + - ALSA topology binary graphs (e.g. ``sof-tgl-nocodec.tplg``, ``sof-mtl-rt711.tplg``) + * - ``/lib/firmware/intel/sof-ipc4/`` + - IPC4 platform firmware images and topologies + +Release Cadence & Maintenance +***************************** + +SOF binary releases follow a **Calendar Versioning (CalVer)** scheme: ``vYYYY.MM[.patch]``: + +* **Major Releases** (``vYYYY.MM``): Published periodically (aligned with upstream Linux kernel and Zephyr LTS releases). +* **Maintenance & Patch Releases** (``vYYYY.MM.patch``): Critical bug fixes, hardware workarounds, and topology updates published from dedicated stable branches (e.g. ``stable-v2025.12``). +* **Daily CI Builds**: In addition to tagged releases, the `sof-bin main branch `_ is updated daily with verified builds from the firmware development tree. + +.. seealso:: + + * `sof-bin GitHub Releases `_ + * `sof-bin GitHub Repository `_ + * For instructions on building custom firmware from source code, refer to the :ref:`build_sof` section in Getting Started. + +.. raw:: html + + diff --git a/scripts/constraints.txt b/scripts/constraints.txt index 199286b4..48ae0da1 100644 --- a/scripts/constraints.txt +++ b/scripts/constraints.txt @@ -15,22 +15,33 @@ # pip install -r scripts/requirements.txt # pip freeze > scripts/constraints.txt # then re-add this header +accessible-pygments==0.0.5 alabaster==1.0.0 babel==2.18.0 +beautifulsoup4==4.15.0 breathe==4.36.0 -certifi==2026.5.20 -charset-normalizer==3.4.7 +certifi==2026.7.22 +charset-normalizer==3.5.1 docutils==0.22.4 -idna==3.18 -imagesize==2.0.0 +idna==3.19 +imagesize==2.0.1 Jinja2==3.1.6 +markdown-it-py==4.2.0 MarkupSafe==3.0.3 -packaging==26.2 -Pygments==2.20.0 +mdit-py-plugins==0.6.1 +mdurl==0.1.2 +myst-parser==5.1.0 +packaging==26.3 +pydata-sphinx-theme==0.21.0 +Pygments==2.21.0 +PyYAML==6.0.3 requests==2.34.2 roman-numerals==4.1.0 snowballstemmer==3.1.1 +soupsieve==2.9.2 Sphinx==9.1.0 +sphinx-copybutton==0.5.2 +sphinx-tabs==3.5.0 sphinx_rtd_theme==3.1.0 sphinxcontrib-applehelp==2.0.0 sphinxcontrib-devhelp==2.0.0 @@ -40,4 +51,5 @@ sphinxcontrib-jsmath==1.0.1 sphinxcontrib-plantuml==0.31 sphinxcontrib-qthelp==2.0.0 sphinxcontrib-serializinghtml==2.0.0 +typing_extensions==4.16.0 urllib3==2.7.0 diff --git a/scripts/generate_matrices.py b/scripts/generate_matrices.py new file mode 100644 index 00000000..5c5da31d --- /dev/null +++ b/scripts/generate_matrices.py @@ -0,0 +1,263 @@ +#!/usr/bin/env python3 +""" +generate_matrices.py - Generate RST tables and documentation from YAML databases and GitHub API. + +Reads: + - data/platforms.yaml + - data/legacy_platforms.yaml + - data/modules.yaml + - data/sof_bin_releases.json (fallback cache) + - GitHub API: thesofproject/sof-bin releases + +Outputs: + - platforms/_generated_platforms_table.rst + - platforms/_generated_legacy_platforms_table.rst + - algos/_generated_modules_table.rst + - _generated_sof_bin_releases.rst +""" + +import json +import sys +import urllib.request +from pathlib import Path +import yaml + +SCRIPT_DIR = Path(__file__).resolve().parent +DOCS_DIR = SCRIPT_DIR.parent +DATA_DIR = DOCS_DIR / "data" + +def load_yaml(file_path): + with open(file_path, "r", encoding="utf-8") as f: + return yaml.safe_load(f) + +VENDOR_MAP = { + "Intel": ("intel", "images/vendors/intel.svg"), + "AMD": ("amd", "images/vendors/amd.svg"), + "NXP": ("nxp", "images/vendors/nxp.svg"), + "MediaTek": ("mediatek", "images/vendors/mediatek.svg"), + "PJRC / NXP": ("pjrc", "images/vendors/pjrc.svg"), + "Espressif": ("espressif", "images/vendors/espressif.svg"), + "Emulation": ("qemu", "images/vendors/qemu.svg"), +} + +def write_vendor_substitutions(f, prefix="icon"): + """Write image substitutions for vendor icons into the RST file.""" + for vendor, (vendor_key, icon_rel_path) in VENDOR_MAP.items(): + sub_name = f"{prefix}_{vendor_key}" + f.write(f".. |{sub_name}| image:: /{icon_rel_path}\n") + f.write(" :width: 18px\n") + f.write(" :height: 18px\n") + f.write(" :align: middle\n") + f.write(" :class: vendor-icon\n\n") + +def get_vendor_cell(vendor_raw, prefix="icon"): + sub_info = VENDOR_MAP.get(vendor_raw) + if sub_info: + sub_name = f"{prefix}_{sub_info[0]}" + return f"|{sub_name}| {vendor_raw}" + return vendor_raw + +def generate_platforms_table(): + platforms_file = DATA_DIR / "platforms.yaml" + if not platforms_file.exists(): + print(f"Warning: {platforms_file} does not exist.") + return + + data = load_yaml(platforms_file) + platforms = data.get("platforms", []) + + out_file = DOCS_DIR / "platforms" / "_generated_platforms_table.rst" + out_file.parent.mkdir(parents=True, exist_ok=True) + + with open(out_file, "w", encoding="utf-8") as f: + write_vendor_substitutions(f, prefix="icon") + + f.write(".. csv-table:: Supported Hardware Platforms & Architectures\n") + f.write(' :header: "Vendor", "Platform / SoC", "Family", "DSP Core / Arch", "Cores / Clocks", "Audio Interfaces", "IPC", "Target", "Status"\n') + f.write(" :widths: 14, 18, 12, 16, 14, 22, 8, 10, 12\n\n") + + for p in platforms: + vendor_cell = get_vendor_cell(p.get("vendor", ""), prefix="icon") + name = p.get("name", "") + family = p.get("family", "") + arch = p.get("dsp_arch", "") + cores_clocks = f"{p.get('cores', 1)} @ {p.get('clock_range', 'N/A')}" + interfaces = "; ".join(p.get("audio_interfaces", [])) + ipcs = "/".join(p.get("ipc_versions", [])) + target = p.get("target_alias", "") + status = p.get("status", "") + + row = f' "{vendor_cell}", "{name}", "{family}", "{arch}", "{cores_clocks}", "{interfaces}", "{ipcs}", "{target}", "{status}"\n' + f.write(row) + + print(f"Generated {out_file} ({len(platforms)} platforms)") + +def generate_legacy_platforms_table(): + legacy_file = DATA_DIR / "legacy_platforms.yaml" + if not legacy_file.exists(): + print(f"Warning: {legacy_file} does not exist.") + return + + data = load_yaml(legacy_file) + platforms = data.get("legacy_platforms", []) + + out_file = DOCS_DIR / "platforms" / "_generated_legacy_platforms_table.rst" + out_file.parent.mkdir(parents=True, exist_ok=True) + + with open(out_file, "w", encoding="utf-8") as f: + write_vendor_substitutions(f, prefix="icon_leg") + + f.write(".. csv-table:: Platforms No Longer Supported in Mainline\n") + f.write(' :header: "Vendor", "Platform / SoC", "Last Release", "Branch", "Architecture", "Cores / Clocks", "Platform Clock", "Memory", "Audio Interfaces"\n') + f.write(" :widths: 14, 18, 10, 10, 15, 12, 10, 18, 20\n\n") + + for p in platforms: + vendor_cell = get_vendor_cell(p.get("vendor", ""), prefix="icon_leg") + name = p.get("name", "") + last_rel = p.get("last_release", "") + branch = p.get("branch", "") + arch = p.get("dsp_arch", "") + cores_clocks = p.get("cores_clocks", "") + platform_clock = p.get("platform_clock", "") + memory = p.get("memory", "") + interfaces = p.get("audio_interfaces", "") + + row = f' "{vendor_cell}", "{name}", "{last_rel}", "{branch}", "{arch}", "{cores_clocks}", "{platform_clock}", "{memory}", "{interfaces}"\n' + f.write(row) + + print(f"Generated {out_file} ({len(platforms)} legacy platforms)") + +def generate_modules_table(): + modules_file = DATA_DIR / "modules.yaml" + if not modules_file.exists(): + print(f"Warning: {modules_file} does not exist.") + return + + data = load_yaml(modules_file) + modules = data.get("modules", []) + + out_file = DOCS_DIR / "algos" / "_generated_modules_table.rst" + out_file.parent.mkdir(parents=True, exist_ok=True) + + with open(out_file, "w", encoding="utf-8") as f: + f.write(".. csv-table:: SOF Supported Audio Processing Modules & Algorithms\n") + f.write(' :header: "Algorithm", "Source", "Category", "SIMD", "Key Capabilities", "Status"\n') + f.write(" :widths: 17, 8, 14, 21, 28, 12\n\n") + + for m in modules: + name = m.get("name", "") + source = m.get("source", "SOF") + cat = m.get("category", "") + simd = ", ".join(m.get("simd", [])) if isinstance(m.get("simd"), list) else m.get("simd", "") + feats = "; ".join(m.get("key_features", [])) + status = m.get("status", "Upstream") + + row = f' "{name}", "{source}", "{cat}", "{simd}", "{feats}", "{status}"\n' + f.write(row) + + print(f"Generated {out_file} ({len(modules)} modules)") + +def generate_sof_bin_releases(): + cache_file = DATA_DIR / "sof_bin_releases.json" + releases = [] + + # Attempt to fetch live from GitHub API (timeout 5s) + try: + url = "https://api.github.com/repos/thesofproject/sof-bin/releases?per_page=12" + req = urllib.request.Request(url, headers={"User-Agent": "SOF-Docs-Builder"}) + with urllib.request.urlopen(req, timeout=5) as resp: + data = json.loads(resp.read().decode("utf-8")) + for r in data: + asset_name = "N/A" + asset_url = "#" + asset_size_mb = 0 + for a in r.get("assets", []): + if a["name"].endswith(".tar.gz"): + asset_name = a["name"] + asset_url = a["browser_download_url"] + asset_size_mb = round(a["size"] / (1024 * 1024), 1) + break + releases.append({ + "tag_name": r.get("tag_name"), + "name": r.get("name") or r.get("tag_name"), + "published_at": r.get("published_at", "")[:10], + "html_url": r.get("html_url"), + "asset_name": asset_name, + "asset_url": asset_url, + "asset_size_mb": asset_size_mb, + "prerelease": r.get("prerelease", False) + }) + # If successfully fetched, update local cache + if releases: + with open(cache_file, "w", encoding="utf-8") as f: + json.dump(releases, f, indent=2) + print(f"Fetched {len(releases)} live releases from GitHub API.") + except Exception as e: + print(f"Notice: Could not fetch live GitHub releases ({e}). Falling back to cached data.") + + # Fallback to cache if network fetch failed + if not releases and cache_file.exists(): + with open(cache_file, "r", encoding="utf-8") as f: + releases = json.load(f) + print(f"Loaded {len(releases)} cached releases from {cache_file}.") + + if not releases: + print("Warning: No release data available.") + return + + out_file = DOCS_DIR / "_generated_sof_bin_releases.rst" + latest = releases[0] + + with open(out_file, "w", encoding="utf-8") as f: + # Latest Release Hero Card + f.write(".. raw:: html\n\n") + f.write('
\n') + f.write('
\n') + f.write('
\n') + f.write(' Latest Binary Release: \n') + f.write(f' {latest["tag_name"]}\n') + f.write('
\n') + f.write(f'
Published on {latest["published_at"]}
\n') + f.write('
\n') + f.write('

Official pre-built and signed firmware binaries, compiled topologies, and install scripts for Intel, AMD, and NXP platforms.

\n') + f.write(' \n') + f.write('
\n\n') + + # Recent Releases Table + f.write("Recent Binary Releases\n") + f.write("**********************\n\n") + f.write(".. csv-table::\n") + f.write(' :header: "Release Tag", "Release Date", "Binary Archive", "Archive Size", "GitHub Notes"\n') + f.write(" :widths: 16, 15, 30, 14, 25\n\n") + + for r in releases: + tag = r["tag_name"] + date = r["published_at"] + asset_name = r["asset_name"] + asset_url = r["asset_url"] + size_str = f"{r['asset_size_mb']} MB" if r["asset_size_mb"] else "N/A" + notes_url = r["html_url"] + + download_cell = f'`{asset_name} <{asset_url}>`_' if asset_name != "N/A" else "N/A" + notes_cell = f'`Release Notes <{notes_url}>`_' + + f.write(f' "`{tag} <{notes_url}>`_", "{date}", "{download_cell}", "{size_str}", "{notes_cell}"\n') + + f.write("\n") + + print(f"Generated {out_file} with {len(releases)} releases.") + +if __name__ == "__main__": + generate_platforms_table() + generate_legacy_platforms_table() + generate_modules_table() + generate_sof_bin_releases() diff --git a/scripts/requirements-lax.txt b/scripts/requirements-lax.txt index ae8a4076..a0718d1a 100644 --- a/scripts/requirements-lax.txt +++ b/scripts/requirements-lax.txt @@ -14,6 +14,11 @@ sphinx>=4.5.0 docutils>=0.17.1 sphinx_rtd_theme>=0.2.4 sphinxcontrib-jquery +sphinx-copybutton +sphinx-tabs +pydata-sphinx-theme +myst-parser +pyyaml # - Version 0.11 is the first version that supports # `plantuml_output_format=none` which is required for instant builds. diff --git a/scripts/requirements.txt b/scripts/requirements.txt index 48d602f8..d33f888a 100644 --- a/scripts/requirements.txt +++ b/scripts/requirements.txt @@ -12,5 +12,11 @@ sphinx>=7 breathe docutils sphinx_rtd_theme +pydata-sphinx-theme +myst-parser +sphinx-copybutton +sphinx-tabs sphinxcontrib-plantuml sphinxcontrib-applehelp +sphinxcontrib-jquery +pyyaml diff --git a/static/sof-custom.css b/static/sof-custom.css index c822a6b9..a6c278a7 100644 --- a/static/sof-custom.css +++ b/static/sof-custom.css @@ -21,10 +21,13 @@ /* code block highlight color in rtd changed to lime green, no no no */ -.rst-content tt.literal, .rst-content code.literal, .highlight { +.wy-nav-content .rst-content tt.literal, +.wy-nav-content .rst-content code.literal, +.wy-nav-content .highlight { background: #f0f0f0; } -.rst-content tt.literal, .rst-content code.literal { +.wy-nav-content .rst-content tt.literal, +.wy-nav-content .rst-content code.literal { color: #000000; } @@ -40,7 +43,7 @@ div > p + ul, div > p + ol { /* add some space before the figure caption */ p.caption { -# border-top: 1px solid; + /* border-top: 1px solid; */ margin-top: 1em; } @@ -95,3 +98,258 @@ th,td { .rst-content div.breathe-sectiondef { padding-left: 0 !important; } + +/* -- PyData Theme Custom Layout Dimensions --------------------------------- */ + +:root { + --pst-sidebar-secondary: 11.5rem !important; +} + +/* Widen overall container on wide displays */ +.bd-page-width { + max-width: 98rem !important; +} + +/* Make left primary navigation sidebar slimmer */ +@media (min-width: 960px) { + .bd-sidebar-primary { + width: 13.5% !important; + min-width: 175px !important; + max-width: 210px !important; + padding: 1rem 0.45rem 1rem !important; + font-size: 0.86rem !important; + } + + /* Make right secondary TOC sidebar slimmer */ + .bd-sidebar-secondary { + width: 11.5rem !important; + min-width: 11.5rem !important; + max-width: 12.5rem !important; + padding: 1.25rem 0.35rem 1rem !important; + font-size: 0.80rem !important; + } +} + +/* Vendor icon styling for platform tables */ +img.vendor-icon { + display: inline-block !important; + vertical-align: middle !important; + margin-right: 6px !important; + width: 18px !important; + height: 18px !important; + border-radius: 4px !important; +} + +table.docutils td:first-child { + white-space: nowrap !important; + font-weight: 600 !important; +} + +/* Expand main article container */ +@media (min-width: 1200px) { + .bd-main .bd-content .bd-article-container { + max-width: 82em !important; + padding: 1rem 1.75rem !important; + } + + .bd-main .bd-content .bd-article-container .bd-article { + padding-left: 1rem !important; + padding-right: 1rem !important; + padding-top: 1.25rem !important; + } +} + +/* -- Sphinx-Tabs Modern Styling -------------------------------------------- */ + +.sphinx-tabs { + margin-top: 1.25rem; + margin-bottom: 1.75rem; + padding: 0; +} + +.sphinx-tabs [role="tablist"] { + display: flex; + flex-wrap: wrap; + border-bottom: 2px solid var(--pst-color-border, #d1d5da); + margin-bottom: 0; + padding-left: 0; + gap: 4px; +} + +/* Base tab button */ +.sphinx-tabs-tab { + font-family: inherit; + font-size: 0.95rem; + font-weight: 500; + line-height: 1.5; + padding: 0.6rem 1.25rem; + border: 1px solid transparent; + border-bottom: none; + border-radius: 6px 6px 0 0; + background-color: transparent; + color: var(--pst-color-text-muted, #677384); + cursor: pointer; + margin-bottom: -2px; + transition: all 0.15s ease-in-out; +} + +.sphinx-tabs-tab:hover { + color: var(--pst-color-primary, #0a7d91); + background-color: var(--pst-color-surface, rgba(0, 0, 0, 0.04)); +} + +.sphinx-tabs-tab:focus-visible { + outline: 2px solid var(--pst-color-accent, #0a7d91); + outline-offset: 2px; +} + +/* Active tab button (light mode default) */ +.sphinx-tabs-tab[aria-selected="true"] { + font-weight: 600; + color: var(--pst-color-primary, #0a7d91) !important; + background-color: var(--pst-color-on-background, #ffffff) !important; + border: 2px solid var(--pst-color-border, #d1d5da) !important; + border-top: 2px solid var(--pst-color-primary, #0a7d91) !important; + border-bottom: 2px solid var(--pst-color-on-background, #ffffff) !important; + margin-bottom: -2px; + z-index: 2; +} + +/* Tab content panel (light mode default) */ +.sphinx-tabs-panel { + border: 2px solid var(--pst-color-border, #d1d5da); + border-top: none; + border-radius: 0 0 6px 6px; + background-color: var(--pst-color-on-background, #ffffff); + color: var(--pst-color-text-base, #222832); + padding: 1.25rem; + margin: 0; + position: relative; + z-index: 1; +} + +.sphinx-tabs-panel[hidden] { + display: none !important; +} + +.sphinx-tabs-panel .highlight { + margin: 0 !important; + background-color: var(--pst-color-surface, #f8fafc) !important; + border: 1px solid var(--pst-color-border, #d1d5da) !important; + border-radius: 6px; +} + +.sphinx-tabs-panel .highlight pre { + margin: 0; + padding: 0.85rem 1rem; + background-color: transparent !important; + color: inherit; +} + +/* -- Dark Mode Overrides (PyData Theme data attributes) -- */ + +html[data-theme="dark"] .sphinx-tabs [role="tablist"], +html[data-mode="dark"] .sphinx-tabs [role="tablist"] { + border-bottom-color: var(--pst-color-border, #48566b) !important; +} + +html[data-theme="dark"] .sphinx-tabs-tab, +html[data-mode="dark"] .sphinx-tabs-tab { + color: var(--pst-color-text-muted, #9ca4af) !important; + background-color: transparent !important; +} + +html[data-theme="dark"] .sphinx-tabs-tab:hover, +html[data-mode="dark"] .sphinx-tabs-tab:hover { + color: var(--pst-color-text-base, #ffffff) !important; + background-color: var(--pst-color-surface, #29313d) !important; +} + +html[data-theme="dark"] .sphinx-tabs-tab[aria-selected="true"], +html[data-mode="dark"] .sphinx-tabs-tab[aria-selected="true"] { + color: var(--pst-color-text-base, #ffffff) !important; + background-color: #222832 !important; + border-color: var(--pst-color-border, #48566b) !important; + border-top: 2px solid var(--pst-color-primary, #0a7d91) !important; + border-bottom: 2px solid #222832 !important; +} + +html[data-theme="dark"] .sphinx-tabs-panel, +html[data-mode="dark"] .sphinx-tabs-panel { + background-color: #222832 !important; + border-color: var(--pst-color-border, #48566b) !important; + color: var(--pst-color-text-base, #ced6dd) !important; +} + +html[data-theme="dark"] .sphinx-tabs-panel .highlight, +html[data-mode="dark"] .sphinx-tabs-panel .highlight, +html[data-theme="dark"] .highlight, +html[data-mode="dark"] .highlight { + background-color: #14181e !important; + border-color: #364150 !important; + color: var(--pst-color-text-base, #ced6dd) !important; +} + +html[data-theme="dark"] .sphinx-tabs-panel .highlight pre, +html[data-mode="dark"] .sphinx-tabs-panel .highlight pre { + background-color: transparent !important; + color: #ced6dd !important; +} + +html[data-theme="dark"] button.copybtn, +html[data-mode="dark"] button.copybtn { + background-color: var(--pst-color-surface, #29313d) !important; + color: var(--pst-color-text-base, #ced6dd) !important; + border-color: var(--pst-color-border, #48566b) !important; +} + +/* -- System Dark Mode Fallback (@media prefers-color-scheme) -- */ + +@media (prefers-color-scheme: dark) { + html:not([data-theme="light"]):not([data-mode="light"]) .sphinx-tabs [role="tablist"] { + border-bottom-color: var(--pst-color-border, #48566b) !important; + } + + html:not([data-theme="light"]):not([data-mode="light"]) .sphinx-tabs-tab { + color: var(--pst-color-text-muted, #9ca4af) !important; + background-color: transparent !important; + } + + html:not([data-theme="light"]):not([data-mode="light"]) .sphinx-tabs-tab:hover { + color: var(--pst-color-text-base, #ffffff) !important; + background-color: var(--pst-color-surface, #29313d) !important; + } + + html:not([data-theme="light"]):not([data-mode="light"]) .sphinx-tabs-tab[aria-selected="true"] { + color: var(--pst-color-text-base, #ffffff) !important; + background-color: #222832 !important; + border-color: var(--pst-color-border, #48566b) !important; + border-top: 2px solid var(--pst-color-primary, #0a7d91) !important; + border-bottom: 2px solid #222832 !important; + } + + html:not([data-theme="light"]):not([data-mode="light"]) .sphinx-tabs-panel { + background-color: #222832 !important; + border-color: var(--pst-color-border, #48566b) !important; + color: var(--pst-color-text-base, #ced6dd) !important; + } + + html:not([data-theme="light"]):not([data-mode="light"]) .sphinx-tabs-panel .highlight, + html:not([data-theme="light"]):not([data-mode="light"]) .highlight { + background-color: #14181e !important; + border-color: #364150 !important; + color: var(--pst-color-text-base, #ced6dd) !important; + } + + html:not([data-theme="light"]):not([data-mode="light"]) .sphinx-tabs-panel .highlight pre { + background-color: transparent !important; + color: #ced6dd !important; + } + + html:not([data-theme="light"]):not([data-mode="light"]) button.copybtn { + background-color: var(--pst-color-surface, #29313d) !important; + color: var(--pst-color-text-base, #ced6dd) !important; + border-color: var(--pst-color-border, #48566b) !important; + } +} + diff --git a/static/sof-custom.js b/static/sof-custom.js new file mode 100644 index 00000000..9d86b9df --- /dev/null +++ b/static/sof-custom.js @@ -0,0 +1,46 @@ +// Dynamic Favicon switcher for SOF documentation +(function() { + function updateFavicon() { + var theme = document.documentElement.dataset.theme; + var prefersDark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches; + var isDark = theme === 'dark' || (theme === 'auto' && prefersDark) || (!theme && prefersDark); + + var links = document.querySelectorAll('link[rel="icon"], link[rel="shortcut icon"]'); + links.forEach(function(link) { + var href = link.getAttribute('href') || ''; + if (href.indexOf('sof-favicon') !== -1) { + var dir = href.substring(0, href.lastIndexOf('/') + 1); + if (theme === 'dark') { + link.href = dir + 'sof-favicon-dark.png'; + } else if (theme === 'light') { + link.href = dir + 'sof-favicon-light.png'; + } else { + link.href = dir + (isDark ? 'sof-favicon-dark.png' : 'sof-favicon.svg'); + } + } + }); + } + + if (document.readyState === 'loading') { + document.addEventListener('DOMContentLoaded', updateFavicon); + } else { + updateFavicon(); + } + + var observer = new MutationObserver(function(mutations) { + mutations.forEach(function(mutation) { + if (mutation.type === 'attributes' && mutation.attributeName === 'data-theme') { + updateFavicon(); + } + }); + }); + + observer.observe(document.documentElement, { + attributes: true, + attributeFilter: ['data-theme'] + }); + + if (window.matchMedia) { + window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', updateFavicon); + } +})(); diff --git a/static/sof-favicon-16x16.png b/static/sof-favicon-16x16.png new file mode 100644 index 00000000..93bc02aa Binary files /dev/null and b/static/sof-favicon-16x16.png differ diff --git a/static/sof-favicon-32x32.png b/static/sof-favicon-32x32.png new file mode 100644 index 00000000..f234f547 Binary files /dev/null and b/static/sof-favicon-32x32.png differ diff --git a/static/sof-favicon-dark-16x16.png b/static/sof-favicon-dark-16x16.png new file mode 100644 index 00000000..9dfca361 Binary files /dev/null and b/static/sof-favicon-dark-16x16.png differ diff --git a/static/sof-favicon-dark.png b/static/sof-favicon-dark.png new file mode 100644 index 00000000..1ab2ccdb Binary files /dev/null and b/static/sof-favicon-dark.png differ diff --git a/static/sof-favicon-light-16x16.png b/static/sof-favicon-light-16x16.png new file mode 100644 index 00000000..f9ee7456 Binary files /dev/null and b/static/sof-favicon-light-16x16.png differ diff --git a/static/sof-favicon-light.png b/static/sof-favicon-light.png new file mode 100644 index 00000000..94d8f932 Binary files /dev/null and b/static/sof-favicon-light.png differ diff --git a/static/sof-favicon.svg b/static/sof-favicon.svg new file mode 100644 index 00000000..aba644d1 --- /dev/null +++ b/static/sof-favicon.svg @@ -0,0 +1,17 @@ + + + + + + +