From 1e68b2e6300d6539e2f684ba95d8efbdee1f1fed Mon Sep 17 00:00:00 2001 From: Deb Taylor Date: Thu, 26 Sep 2024 13:22:52 -0700 Subject: [PATCH 01/25] Update files to indicate new release (#502) Signed-off-by: Taylor, Deb --- conf.py | 2 +- release.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/conf.py b/conf.py index fa43322..4e1d22c 100755 --- a/conf.py +++ b/conf.py @@ -86,7 +86,7 @@ # |version| and |release|, also used in various other places throughout the # built documents. -version = release = "2.10.0" +version = release = "2.11.0" # # The short X.Y version. diff --git a/release.rst b/release.rst index 8cad490..ee119d7 100755 --- a/release.rst +++ b/release.rst @@ -26,7 +26,7 @@ kernel, and documentation. Download the source code as a zip or tar.gz file: Source and Binary Releases -------------------------- -The latest SOF release is v2.10.0 (July 2024). +The latest SOF release is v2.11.0 (Sept 2024). View new feature information and release downloads for the latest and previous releases on GitHub. Firmware and SDK tool source code and binary From a0e05fafc876f82924e2784a208d4528ae1dde9f Mon Sep 17 00:00:00 2001 From: Deb Taylor Date: Thu, 26 Sep 2024 13:24:04 -0700 Subject: [PATCH 02/25] Update pull-request.yml (#503) Updating download artifact to 4.1.7 is breaking change to the publication workflow. Changing upload artifact to match. --- .github/workflows/pull-request.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 1f094fd..11b29b3 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -74,7 +74,7 @@ jobs: # https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts - name: upload HTML for deploy if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' }} - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: html path: _build/html From b7080b4b8f9b2b4ffc2fc4a8b10a2a4c16dab1e6 Mon Sep 17 00:00:00 2001 From: Kai Vehmanen Date: Fri, 20 Sep 2024 17:54:46 +0300 Subject: [PATCH 03/25] platforms: add separate table for older platforms As this topic has been discussed in many pull requests and bugs, add documentation on which platforms are supported in SOF main and which are only supported in stable-vx.yy branches. Also add a note explainin how sof-bin releases are made, gathering binaries for for all platforms. Signed-off-by: Kai Vehmanen --- platforms/index.rst | 38 ++++++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/platforms/index.rst b/platforms/index.rst index 57930c4..a582511 100644 --- a/platforms/index.rst +++ b/platforms/index.rst @@ -14,16 +14,8 @@ Platform and board specific support is continually added to the SOF project as d "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 Bay Trail / Merrifield", "Xtensa HiFi2 EP", "1 @ 50 - 400MHz", "25MHz", "96KB IRAM / 192KB DRAM", "3 x SSP (I2S, PCM)" - "Intel Cherry Trail / Braswell", "Xtensa HiFi2 EP", "1 @ 50 - 400MHz", "19.2MHz", "96KB IRAM / 192KB DRAM", "6 x SSP (I2S, PCM)" - "Intel Broadwell", "Xtensa HiFi2 EP", "1 @ 50 - 400MHz", "24MHz", "320KB IRAM / 640KB DRAM", "2 x SSP (I2S, PCM)" - "Intel Apollo Lake / Gemini Lake", "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", "Xtensa HiFi3", "4 @ 120 - 400MHz", "24MHz", "64KB LP / 3008KB HP SRAM", "3 x SSP (I2S, PCM), HDA, DMIC, Soundwire" - "Intel Sue Creek", "Xtensa HiFi3", "2 @ 120 - 400MHz","24MHz", "64KB LP SRAM / 4096KB HP SRAM", "6 x SSP (I2S, PCM), DMIC" - "Intel Ice Lake", "Xtensa HiFi3", "4 @ 120 - 400MHz", "38.4MHz", "64KB LP SRAM / 3008KB HP SRAM", "6 x SSP (I2S, PCM), HDA, DMIC, Soundwire" - "Intel Jasper Lake", "Xtensa HiFi3", "2 @ 120 - 400MHz", "38.4MHz", "64KB LP SRAM / 1024KB HP SRAM", "3 x SSP (I2S, PCM), HDA, DMIC, Soundwire" - "Intel Tiger Lake", "Xtensa HiFi3", "4 @ 120 - 400MHz", "38.4MHz", "64KB LP SRAM / 2944KB HP SRAM", "6 x SSP (I2S, PCM), HDA, DMIC, Soundwire" - "Intel Alder Lake", "Xtensa HiFi3", "4 @ 120 - 400MHz", "38.4MHz", "64KB LP SRAM / 2944KB HP SRAM", "6 x SSP (I2S, PCM), HDA, DMIC, Soundwire" + "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" @@ -38,6 +30,32 @@ 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. +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, +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" + +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 ***************************** From 163bac3c1e9ab439723c73f64540d6acfc4b3242 Mon Sep 17 00:00:00 2001 From: Curtis Malainey Date: Thu, 21 Nov 2024 12:38:45 -0800 Subject: [PATCH 04/25] admin: remove exited admin members Cleanup Signed-off-by: Curtis Malainey --- maintainers/admin.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/maintainers/admin.rst b/maintainers/admin.rst index 209858f..44a6d49 100644 --- a/maintainers/admin.rst +++ b/maintainers/admin.rst @@ -13,8 +13,6 @@ to multiple contributors: +---------------+-------------------+---------------+ | Intel | Marcin Maka | @mmaka1 | +---------------+-------------------+---------------+ -| Intel | Pierre Bossart | @plbossart | -+---------------+-------------------+---------------+ | Intel | Ranjani Sridharan | @ranj063 | +---------------+-------------------+---------------+ | NXP | Daniel Baluta | @dbaluta | From 99916eae9a0514e1daf879851672f0275d13b504 Mon Sep 17 00:00:00 2001 From: Curtis Malainey Date: Thu, 21 Nov 2024 12:39:28 -0800 Subject: [PATCH 05/25] admin: replace google side admin Signed-off-by: Curtis Malainey --- maintainers/admin.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/maintainers/admin.rst b/maintainers/admin.rst index 44a6d49..450bc78 100644 --- a/maintainers/admin.rst +++ b/maintainers/admin.rst @@ -17,7 +17,7 @@ to multiple contributors: +---------------+-------------------+---------------+ | NXP | Daniel Baluta | @dbaluta | +---------------+-------------------+---------------+ -| Google | Curtis Malainey | @cujomalainey | +| Google | Johny Lin | @johnylin76 | +---------------+-------------------+---------------+ Administrators may override specific merge rules, for example merge a From e26df4f0efd5d748269819b32a6f2f552b635137 Mon Sep 17 00:00:00 2001 From: Curtis Malainey Date: Thu, 21 Nov 2024 12:40:58 -0800 Subject: [PATCH 06/25] tsc: remove cujomalainey Signed-off-by: Curtis Malainey --- tsc/representatives.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tsc/representatives.rst b/tsc/representatives.rst index 09a5310..66b7ff4 100755 --- a/tsc/representatives.rst +++ b/tsc/representatives.rst @@ -19,12 +19,12 @@ The TSC is currently made of the following contributors +---------------+----------------------+------------------+ | NXP | Daniel Baluta | @dbaluta | +---------------+----------------------+------------------+ -| Google | Curtis Malainey | @cujomalainey | -+---------------+----------------------+------------------+ | Google | Johny Lin | @johnylin76 | +---------------+----------------------+------------------+ | Google | Unseated | | +---------------+----------------------+------------------+ +| Google | Unseated | | ++---------------+----------------------+------------------+ | AMD | Carl Wakeland | @cwakeland | +---------------+----------------------+------------------+ | AMD | Virendra Pratap Arya | @vp-arya | From ef63f8940dcf0e77cb4472f962d5b033ecbac241 Mon Sep 17 00:00:00 2001 From: Peter Ujfalusi Date: Wed, 11 Dec 2024 13:38:53 +0200 Subject: [PATCH 07/25] intel_debug: introduction: Add information about modular SOF release content The firmware supports library loading starting with Meteor Lake and the release system is prepared to offer modular SOF releases. Update the documentation of the SOF release content to reflect this. Signed-off-by: Peter Ujfalusi --- getting_started/intel_debug/introduction.rst | 57 +++++++++++++++++--- 1 file changed, 50 insertions(+), 7 deletions(-) diff --git a/getting_started/intel_debug/introduction.rst b/getting_started/intel_debug/introduction.rst index 2079812..fe66798 100755 --- a/getting_started/intel_debug/introduction.rst +++ b/getting_started/intel_debug/introduction.rst @@ -94,7 +94,10 @@ User space and filesystem requirements Selecting the SOF driver is not enough. Audio is properly configured only if the following elements are present on the file system. -1. Firmware binary +1. Firmware +----------- + +1.1. Base firmware ------------------ The firmware file, ``/lib/firmware/intel/sof/sof-tgl.ri`` (example @@ -117,6 +120,46 @@ Linux kernel to query whether or not the firmware authentication is enabled, which means `dmesg` logs cannot be provided to alert the user to an ME configuration issue. +.. _loadable-libraries: + +1.2. Loadable libraries +----------------------- + +An IPC4 library is a container of a single or multiple modules (bundle) which +can be loaded to the firmware after it is booted up. +Library loading is supported on Meteor Lake (ACE1) or newer platforms. + +Background information: the base firmware always resides in DSP SRAM while the +loaded library is stored in DRAM memory and only the needed code is copied to +SRAM for execution. By moving modules out from the base firmware to a library +can reduce the overall SRAM use depending on the device configuration and +topology. + +See :ref:`llext_modules` for technical details. + +1.3. Monolithic and modular SOF releases +---------------------------------------- + +SOF project releases for Intel platforms are either monolithic (only a single firmware binary) or modular (base firmware and external libraries). + +1.3.1. Modular SOF releases +--------------------------- + +See :ref:`loadable-libraries` for details about library support in general. + +The released libraries are: + - **sof-PLAT-openmodules.ri** : the bundle contains modules for audio processing not included in the base firmware + - **sof-PLAT-debug.ri** : the bundle contains modules that are needed for firmware debugging and profiling. Used by developers and for bug reporting if needed + - **UUID.bin** : Mainly 3rd party libraries identified by UUID. If the library contains multiple modules then a UUID symlink must be provided for each one. + +Notes: + - The Kernel will attempt to load \*-openmodules.ri followed by \*-debug.ri from the library path after the base firmware boot if they exist. + - additional libraries referenced by topology files or drivers will be loaded based on the UUID of the module from the library path. + + +1.4 Firmware lookup paths +------------------------- + Linux SOF will look up firmware files at the following paths: .. _intel_firmware_paths: @@ -144,14 +187,14 @@ Linux SOF will look up firmware files at the following paths: - IPC4 - /lib/firmware/intel/sof-ipc4/PLAT/community/sof-PLAT.ri - PLAT = tgl, adl, rpl, mtl, lnl, ... - * - Tiger Lake and newer Loadable Module + * - Meteor Lake and newer Loadable libraries - IPC4 - - /lib/firmware/intel/sof-ipc4-lib/PLAT/UUID.bin - - PLAT as above, UUID = UUID of the module - * - Tiger Lake and newer Loadable Module (community signed) + - /lib/firmware/intel/sof-ipc4-lib/PLAT/ + - PLAT = mtl, lnl, ... + * - Meteor Lake and newer Loadable libraries (community signed) - IPC4 - - /lib/firmware/intel/sof-ipc4-lib/PLAT/community/UUID.bin - - PLAT as above, UUID = UUID of the module + - /lib/firmware/intel/sof-ipc4-lib/PLAT/community/ + - PLAT = mtl, lnl, ... Important notices: - The standard Linux firmware search path and order is followed. The above table covers the base "/lib/firmware" case. See https://docs.kernel.org/driver-api/firmware/fw_search_path.html for more information. From 6eee88fce872bf03e3c72438272b33c5dd0c0ede Mon Sep 17 00:00:00 2001 From: Peter Ujfalusi Date: Mon, 16 Dec 2024 18:24:35 +0200 Subject: [PATCH 08/25] intel_debug: introduction: Detail description of a modular firmware release Separate the firmware lookup table for non-modular and modular SOF releases to be able to document the locations and file names the firmware will be looking for the individual files. Extend the description of the two type of SOF release and convert the list-table to a normal table for better descriptions for the configurations. Signed-off-by: Peter Ujfalusi --- getting_started/intel_debug/introduction.rst | 105 ++++++++++--------- 1 file changed, 58 insertions(+), 47 deletions(-) diff --git a/getting_started/intel_debug/introduction.rst b/getting_started/intel_debug/introduction.rst index fe66798..11e8ca5 100755 --- a/getting_started/intel_debug/introduction.rst +++ b/getting_started/intel_debug/introduction.rst @@ -127,7 +127,7 @@ configuration issue. An IPC4 library is a container of a single or multiple modules (bundle) which can be loaded to the firmware after it is booted up. -Library loading is supported on Meteor Lake (ACE1) or newer platforms. +Library loading is supported on Meteor Lake (ACE1) or newer platforms. Background information: the base firmware always resides in DSP SRAM while the loaded library is stored in DRAM memory and only the needed code is copied to @@ -137,64 +137,75 @@ topology. See :ref:`llext_modules` for technical details. -1.3. Monolithic and modular SOF releases ----------------------------------------- +1.3. Non-modular and modular firmware releases +---------------------------------------------- -SOF project releases for Intel platforms are either monolithic (only a single firmware binary) or modular (base firmware and external libraries). +SOF project releases for Intel platforms are either a single firmware or modular firmware based. -1.3.1. Modular SOF releases ---------------------------- +1.3.1. Non-modular firmware releases +------------------------------------ -See :ref:`loadable-libraries` for details about library support in general. +The release contains single a firmware image: **sof-PLAT.ri** -The released libraries are: +1.3.2. Modular firmware releases +-------------------------------- + +Modular SOF release is technically supported with IPC4 on Meteor Lake (MTL) or newer platforms since it depends on Loadable Library support (see :ref:`loadable-libraries` for details). + +Description of files provided by a modular release: + - **sof-PLAT.ri** : The base firmware - **sof-PLAT-openmodules.ri** : the bundle contains modules for audio processing not included in the base firmware - **sof-PLAT-debug.ri** : the bundle contains modules that are needed for firmware debugging and profiling. Used by developers and for bug reporting if needed - - **UUID.bin** : Mainly 3rd party libraries identified by UUID. If the library contains multiple modules then a UUID symlink must be provided for each one. + - **UUID.bin** : On demand loadable library identified by UUID. If the library contains multiple modules then a UUID symlink must be provided for each one. -Notes: - - The Kernel will attempt to load \*-openmodules.ri followed by \*-debug.ri from the library path after the base firmware boot if they exist. - - additional libraries referenced by topology files or drivers will be loaded based on the UUID of the module from the library path. +The main firmware can be shipped as a + - single binary (**sof-PLAT.ri**) + - split release when the base firmware (**sof-PLAT.ri**), processing modules (**sof-PLAT-openmodules.ri**) and debug/developer modules (**sof-PLAT-debug.ri**) are provided as separate binaries. + - After the base firmware boot, the kernel will load the **sof-PLAT-openmodules.ri** and **sof-PLAT-debug.ri** bundles to the firmware to provide equivalent functionality as the single binary release. + +Notes: + - additional libraries referenced by topology files or drivers will be loaded based on the UUID of the module from the library path (**UUID.bin**). 1.4 Firmware lookup paths ------------------------- -Linux SOF will look up firmware files at the following paths: - -.. _intel_firmware_paths: -.. list-table:: Firmware look-up paths per Intel platform - :widths: 55 5 50 25 - :header-rows: 1 - - * - Platform - - IPC type - - Firmware load path - - Notes - * - Raptor Lake and older - - IPC3 - - /lib/firmware/intel/sof/sof-PLAT.ri - - PLAT = glk, cml, ..., rpl - * - Raptor Lake and older (community signed) - - IPC3 - - /lib/firmware/intel/sof/community/sof-PLAT.ri - - PLAT = glk, cml, ..., rpl - * - Tiger Lake and newer - - IPC4 - - /lib/firmware/intel/sof-ipc4/PLAT/sof-PLAT.ri - - PLAT = tgl, adl, rpl, mtl, lnl, ... - * - Tiger Lake and newer (community signed) - - IPC4 - - /lib/firmware/intel/sof-ipc4/PLAT/community/sof-PLAT.ri - - PLAT = tgl, adl, rpl, mtl, lnl, ... - * - Meteor Lake and newer Loadable libraries - - IPC4 - - /lib/firmware/intel/sof-ipc4-lib/PLAT/ - - PLAT = mtl, lnl, ... - * - Meteor Lake and newer Loadable libraries (community signed) - - IPC4 - - /lib/firmware/intel/sof-ipc4-lib/PLAT/community/ - - PLAT = mtl, lnl, ... +Linux SOF will look up firmware files at the following paths. + +Look-up paths per Intel platform for **non-modular firmware releases** + +.. _intel_non_modular_firmware_paths: + ++-----------------------------------------------------------+--------+------------------------------------------------+-----------+-----------------------------------+ +|Platform |IPC type|Load path |File name |Notes | ++===========================================================+========+================================================+===========+===================================+ +|Raptor Lake and older |IPC3 |/lib/firmware/intel/sof/ |sof-PLAT.ri|PLAT = glk, cml, ..., rpl | ++-----------------------------------------------------------+ +------------------------------------------------+ | | +|Raptor Lake and older (community signed) | |/lib/firmware/intel/sof/community/ | | | ++-----------------------------------------------------------+--------+------------------------------------------------+ +-----------------------------------+ +|Tiger Lake and newer |IPC4 |/lib/firmware/intel/sof-ipc4/PLAT/ | |PLAT = tgl, adl, rpl, mtl, lnl, ...| ++-----------------------------------------------------------+ +------------------------------------------------+ | | +|Tiger Lake and newer (community signed) | |/lib/firmware/intel/sof-ipc4/PLAT/community/ | | | ++-----------------------------------------------------------+--------+------------------------------------------------+-----------+-----------------------------------+ + +Look-up paths per Intel platform for **modular firmware releases (IPC4 only)** + +.. _intel_modular_firmware_paths: + ++-----------------------------------------------------------+------------------------------------------------+-----------------------------+----------------------+ +|Platform |Load path |File name |Notes | ++===========================================================+================================================+=============================+======================+ +|Meteor Lake and newer |/lib/firmware/intel/sof-ipc4/PLAT/ || || PLAT = mtl, lnl, ...| +| | || sof-PLAT.ri || [*] PLAT = ptl, ... | +| | || sof-PLAT-openmodules.ri [*]| | +| | || sof-PLAT-debug.ri [*]| | ++-----------------------------------------------------------+------------------------------------------------+ | | +|Meteor Lake and newer (community signed) |/lib/firmware/intel/sof-ipc4/PLAT/community/ | | | ++-----------------------------------------------------------+------------------------------------------------+-----------------------------+ | +|Meteor Lake and newer Loadable libraries |/lib/firmware/intel/sof-ipc4-lib/PLAT/ |UUID.bin | | ++-----------------------------------------------------------+------------------------------------------------+ | | +|Meteor Lake and newer Loadable libraries (community signed)|/lib/firmware/intel/sof-ipc4-lib/PLAT/community/| | | ++-----------------------------------------------------------+------------------------------------------------+-----------------------------+----------------------+ Important notices: - The standard Linux firmware search path and order is followed. The above table covers the base "/lib/firmware" case. See https://docs.kernel.org/driver-api/firmware/fw_search_path.html for more information. From e7485000620f3a5a54949f94a099e9a926ab44fe Mon Sep 17 00:00:00 2001 From: Bard Liao Date: Tue, 14 Jan 2025 17:47:30 +0800 Subject: [PATCH 09/25] topology2: add split topologies description Describe what are split topologies and how to create it. Signed-off-by: Bard Liao --- developer_guides/topology2/topology2.rst | 47 ++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/developer_guides/topology2/topology2.rst b/developer_guides/topology2/topology2.rst index 0d3538b..86b5db6 100644 --- a/developer_guides/topology2/topology2.rst +++ b/developer_guides/topology2/topology2.rst @@ -1332,6 +1332,53 @@ You can use the ``-P`` switch to convert a 2.0 configuration file to the 1.0 con alsatplg <-D args=values> -P input.conf -o output.conf +Split topologies +**************** + +Linux kernel can load multiple topologies, a topology for a single function. +This feature is useful to support SDCA setups with standardized components. And no need to create topologies +for every new product. To achieve this, you need to split the topology into multiple tplg files. +The split topology files should be named as follows: + +.. code-block:: bash + + sof---id.tplg + +Currently is only needed for the DMIC function and not needed for SDCA functions in general. +It should be mtl, lnl, etc. + +Where should be one of + +.. code-block:: bash + + sdca-jack: SDCA headphone and headset. + sdca-amp: SDCA amp, where n is the amp link numbers. + sdca-mic: SDCA host mic. + dmic-ch: PCH DMIC, where n is the number of supported channels. Currently, only 2ch and 4ch are supported. + hdmi-pcm: HDMI with PCM id starts from . The is 3 for the "sof-hda-dsp" card and 5 for other cards. + + +For example + +.. code-block:: bash + + sof-sdca-2amp-id2.tplg + sof-sdca-mic-id4.tplg + sof-arl-dmic-2ch-id5.tplg + sof-hdmi-pcm5-id7.tplg + +The split topologies are the subset of the monolithic topology. Usually, you just need to add a description with proper +macro settings to disable the features that you don't need and set the first BE ID that in the topology in the cmake file +to generate the split topologies. + +For example + +.. code-block:: bash + + "cavs-sdw\;sof-arl-sdca-2amp-id2\;PLATFORM=mtl,NUM_SDW_AMP_LINKS=2,SDW_JACK=false,\ + SDW_AMP_FEEDBACK=false,SDW_SPK_STREAM=Playback-SmartAmp,NUM_HDMIS=0" + + Topology reminders ****************** From 52be2820318f4e702a52e8784dfb3eb67cf5fb5b Mon Sep 17 00:00:00 2001 From: Christopher Turner Date: Wed, 19 Feb 2025 12:31:57 -0600 Subject: [PATCH 10/25] conf.py: remove unused html_theme_path configuration Per build warning; WARNING: Calling get_html_theme_path is deprecated. If you are calling it to define html_theme_path, you are safe to remove that code. So removing the code to get rid of warning. Signed-off-by: Christopher Turner --- conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/conf.py b/conf.py index 4e1d22c..7701870 100755 --- a/conf.py +++ b/conf.py @@ -132,7 +132,6 @@ sys.stderr.write('Warning: sphinx_rtd_theme missing. Use pip to install it.\n') else: html_theme = "sphinx_rtd_theme" - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] html_theme_options = { 'canonical_url': '', 'analytics_id': 'GTM-M4BL5NF', From be866f6c3d30da8245d94c743e9047a0b12ffa4c Mon Sep 17 00:00:00 2001 From: Christopher Turner Date: Wed, 19 Feb 2025 12:45:57 -0600 Subject: [PATCH 11/25] conf.py: remove display_version configuration the option for display_version for the sphinx-rtd-theme was deprecated since v3.0.0 Signed-off-by: Christopher Turner --- conf.py | 1 - 1 file changed, 1 deletion(-) diff --git a/conf.py b/conf.py index 7701870..c64f349 100755 --- a/conf.py +++ b/conf.py @@ -136,7 +136,6 @@ 'canonical_url': '', 'analytics_id': 'GTM-M4BL5NF', 'logo_only': False, - 'display_version': True, 'prev_next_buttons_location': 'None', # Toc options 'collapse_navigation': False, From c7bf0c1e9818b7348c0e0f01e36aa4fdf43817db Mon Sep 17 00:00:00 2001 From: Christopher Turner Date: Wed, 19 Feb 2025 12:52:11 -0600 Subject: [PATCH 12/25] developer_guides: llext_modules.rst: modify broken link for Intel firmware paths update broken link to Intel firmware paths in llext_modules.rst from intel_firmware_paths to intel_modular_firmware_paths to point to correct location and fix doc build errors. Signed-off-by: Christopher Turner --- developer_guides/firmware/llext_modules.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer_guides/firmware/llext_modules.rst b/developer_guides/firmware/llext_modules.rst index 4832495..e4040d5 100644 --- a/developer_guides/firmware/llext_modules.rst +++ b/developer_guides/firmware/llext_modules.rst @@ -78,7 +78,7 @@ Installation ************ As specified in -:ref:`Firmware look-up paths per Intel platform ` +:ref:`Firmware look-up paths per Intel platform ` the |SOF| Linux kernel driver loads SOF modules by their UUIDs, specified in the topology. For SOF in-tree modules the process of creation and installation of modules in a deployment tree is automated by the From e99e90f677739c6e896e43dcbeaf4538773b4640 Mon Sep 17 00:00:00 2001 From: Suraj Sonawane Date: Thu, 13 Mar 2025 16:58:52 +0530 Subject: [PATCH 13/25] build_testbench: Fix mhwaveedit command The command `mhWaveEdit audio_out.wav` was incorrect because the package installs the binary as `mhwaveedit` (all lowercase). This commit corrects the capitalization to avoid command not found errors. Signed-off-by: Suraj Sonawane --- developer_guides/testbench/build_testbench.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer_guides/testbench/build_testbench.rst b/developer_guides/testbench/build_testbench.rst index 3f707b1..c617350 100644 --- a/developer_guides/testbench/build_testbench.rst +++ b/developer_guides/testbench/build_testbench.rst @@ -115,7 +115,7 @@ it can be launched to an audio editor tool such as mhWaveEdit: .. code-block:: bash paplay audio_out.wav - mhWaveEdit audio_out.wav + mhwaveedit audio_out.wav .. figure:: fig_mhwaveedit.png From 6e56ea942f94147f590b44374223d98385c3ea4d Mon Sep 17 00:00:00 2001 From: Dmitrii Golovanov Date: Mon, 24 Mar 2025 20:42:37 +0100 Subject: [PATCH 14/25] Reset unwanted executable attributes Reset executable attributes on .rst, .txt, .diag files as well as on CODEOWNERS. Signed-off-by: Dmitrii Golovanov --- CODEOWNERS | 0 algos/demux/demux.rst | 0 architectures/firmware/index.rst | 0 architectures/firmware/intel/cavs/cavs-boot/apollolake/index.rst | 0 .../firmware/intel/cavs/cavs-boot/cavs-dsp-boot-overview.rst | 0 architectures/firmware/intel/cavs/index.rst | 0 architectures/firmware/intel/index.rst | 0 architectures/firmware/sof-xtos/schedulers.rst | 0 .../mpp_layer/images/mpp_scheduling/edf_scheduling.diag | 0 .../firmware/sof-zephyr/rtos_layer/zephyr_kernel_overview.rst | 0 architectures/index.rst | 0 getting_started/build-guide/build-from-scratch.rst | 0 getting_started/build-guide/build-with-zephyr.rst | 0 getting_started/index.rst | 0 getting_started/intel_debug/introduction.rst | 0 getting_started/intel_debug/suggestions.rst | 0 getting_started/nxp/sof_imx_user_guide.rst | 0 platforms/intel-cavs/commons/work-queue.rst | 0 release.rst | 0 scripts/requirements.txt | 0 tsc/representatives.rst | 0 21 files changed, 0 insertions(+), 0 deletions(-) mode change 100755 => 100644 CODEOWNERS mode change 100755 => 100644 algos/demux/demux.rst mode change 100755 => 100644 architectures/firmware/index.rst mode change 100755 => 100644 architectures/firmware/intel/cavs/cavs-boot/apollolake/index.rst mode change 100755 => 100644 architectures/firmware/intel/cavs/cavs-boot/cavs-dsp-boot-overview.rst mode change 100755 => 100644 architectures/firmware/intel/cavs/index.rst mode change 100755 => 100644 architectures/firmware/intel/index.rst mode change 100755 => 100644 architectures/firmware/sof-xtos/schedulers.rst mode change 100755 => 100644 architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.diag mode change 100755 => 100644 architectures/firmware/sof-zephyr/rtos_layer/zephyr_kernel_overview.rst mode change 100755 => 100644 architectures/index.rst mode change 100755 => 100644 getting_started/build-guide/build-from-scratch.rst mode change 100755 => 100644 getting_started/build-guide/build-with-zephyr.rst mode change 100755 => 100644 getting_started/index.rst mode change 100755 => 100644 getting_started/intel_debug/introduction.rst mode change 100755 => 100644 getting_started/intel_debug/suggestions.rst mode change 100755 => 100644 getting_started/nxp/sof_imx_user_guide.rst mode change 100755 => 100644 platforms/intel-cavs/commons/work-queue.rst mode change 100755 => 100644 release.rst mode change 100755 => 100644 scripts/requirements.txt mode change 100755 => 100644 tsc/representatives.rst diff --git a/CODEOWNERS b/CODEOWNERS old mode 100755 new mode 100644 diff --git a/algos/demux/demux.rst b/algos/demux/demux.rst old mode 100755 new mode 100644 diff --git a/architectures/firmware/index.rst b/architectures/firmware/index.rst old mode 100755 new mode 100644 diff --git a/architectures/firmware/intel/cavs/cavs-boot/apollolake/index.rst b/architectures/firmware/intel/cavs/cavs-boot/apollolake/index.rst old mode 100755 new mode 100644 diff --git a/architectures/firmware/intel/cavs/cavs-boot/cavs-dsp-boot-overview.rst b/architectures/firmware/intel/cavs/cavs-boot/cavs-dsp-boot-overview.rst old mode 100755 new mode 100644 diff --git a/architectures/firmware/intel/cavs/index.rst b/architectures/firmware/intel/cavs/index.rst old mode 100755 new mode 100644 diff --git a/architectures/firmware/intel/index.rst b/architectures/firmware/intel/index.rst old mode 100755 new mode 100644 diff --git a/architectures/firmware/sof-xtos/schedulers.rst b/architectures/firmware/sof-xtos/schedulers.rst old mode 100755 new mode 100644 diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.diag b/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.diag old mode 100755 new mode 100644 diff --git a/architectures/firmware/sof-zephyr/rtos_layer/zephyr_kernel_overview.rst b/architectures/firmware/sof-zephyr/rtos_layer/zephyr_kernel_overview.rst old mode 100755 new mode 100644 diff --git a/architectures/index.rst b/architectures/index.rst old mode 100755 new mode 100644 diff --git a/getting_started/build-guide/build-from-scratch.rst b/getting_started/build-guide/build-from-scratch.rst old mode 100755 new mode 100644 diff --git a/getting_started/build-guide/build-with-zephyr.rst b/getting_started/build-guide/build-with-zephyr.rst old mode 100755 new mode 100644 diff --git a/getting_started/index.rst b/getting_started/index.rst old mode 100755 new mode 100644 diff --git a/getting_started/intel_debug/introduction.rst b/getting_started/intel_debug/introduction.rst old mode 100755 new mode 100644 diff --git a/getting_started/intel_debug/suggestions.rst b/getting_started/intel_debug/suggestions.rst old mode 100755 new mode 100644 diff --git a/getting_started/nxp/sof_imx_user_guide.rst b/getting_started/nxp/sof_imx_user_guide.rst old mode 100755 new mode 100644 diff --git a/platforms/intel-cavs/commons/work-queue.rst b/platforms/intel-cavs/commons/work-queue.rst old mode 100755 new mode 100644 diff --git a/release.rst b/release.rst old mode 100755 new mode 100644 diff --git a/scripts/requirements.txt b/scripts/requirements.txt old mode 100755 new mode 100644 diff --git a/tsc/representatives.rst b/tsc/representatives.rst old mode 100755 new mode 100644 From 86e7dfe546771cecdc02dc5f06be047bd6225016 Mon Sep 17 00:00:00 2001 From: Dmitrii Golovanov Date: Tue, 25 Mar 2025 10:58:38 +0100 Subject: [PATCH 15/25] docbuild: Add a note on additional libraries Add a note on additional libraries needed to build the hardcoded version of pillow package. Signed-off-by: Dmitrii Golovanov --- contribute/process/docbuild.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/contribute/process/docbuild.rst b/contribute/process/docbuild.rst index f1dd8f9..5a0c281 100644 --- a/contribute/process/docbuild.rst +++ b/contribute/process/docbuild.rst @@ -163,6 +163,20 @@ tools: PIP_IGNORE_INSTALLED=0 pip3 install --user -r scripts/requirements-lax.txt + The hardcoded package versions might need additional libraries installed + in order to compile them. For example, to resolve the following error: + + .. code-block:: bash + + ERROR: Could not build wheels for pillow, which is required to install pyproject.toml-based projects + + you should install: + + .. code-block:: bash + + sudo apt install libjpeg-dev zlib1g-dev + + For Windows, install the needed tools manually: * Python (3.7+) from https://www.python.org/downloads/ From 49f3c6eb5da8cf020fc2d95e5a1f8f918dadda87 Mon Sep 17 00:00:00 2001 From: Dmitrii Golovanov Date: Tue, 25 Mar 2025 11:00:43 +0100 Subject: [PATCH 16/25] docbuild: Adjust HTML generation commands Adjust code snippets for HTML generation after #9788c4be changes to avoid doxygen build in source directory. Signed-off-by: Dmitrii Golovanov --- contribute/process/docbuild.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/contribute/process/docbuild.rst b/contribute/process/docbuild.rst index 5a0c281..06570e0 100644 --- a/contribute/process/docbuild.rst +++ b/contribute/process/docbuild.rst @@ -238,8 +238,8 @@ Docker image (2) cd thesofproject # API documentation (Doxygen) - cmake -S sof/doc -B sof/doc -GNinja - ninja -C sof/doc -v doc + cmake -S sof/doc -B sof/build_doxygen -GNinja + ninja -C sof/build_doxygen -v doc # UML and reStructuredText make -C sof-docs VERBOSE=1 html @@ -305,7 +305,7 @@ publishing. .. note:: In some situations it is necessary to clean all the files and build from - the very beginning. To do this, use the ``make clean`` command. + the very beginning. To do this, use the ``make -C sof-docs clean`` command. Installation troubleshooting **************************** From 7a448ff2e7228364d8255133e8f2909d43a7ebee Mon Sep 17 00:00:00 2001 From: Dmitrii Golovanov Date: Tue, 25 Mar 2025 11:18:10 +0100 Subject: [PATCH 17/25] build-guide: Use Zephyr HWMv2 board names Use Zephyr HWMv2 board names in `west build` command examples. Signed-off-by: Dmitrii Golovanov --- getting_started/build-guide/build-with-zephyr.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/getting_started/build-guide/build-with-zephyr.rst b/getting_started/build-guide/build-with-zephyr.rst index 781dc92..e3eb035 100644 --- a/getting_started/build-guide/build-with-zephyr.rst +++ b/getting_started/build-guide/build-with-zephyr.rst @@ -163,17 +163,17 @@ Check out and build using west tool directly .. code-block:: bash - west build --build-dir build-tgl --board intel_adsp_cavs25 ./sof/app + 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. This is why the output directory is named ``build-tgl``; however, you may use any name you wish. + 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`` + ``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`` + ``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** From 32b3fcaf9824dbe4886c365bed9f4d80437b6d14 Mon Sep 17 00:00:00 2001 From: Marcin Szkudlinski Date: Thu, 4 Sep 2025 14:18:47 +0200 Subject: [PATCH 18/25] Design of DP scheduling with deadline calculations this commit contains a detailed description of DP scheduling and DP deadline calculations Signed-off-by: Marcin Szkudlinski --- .../sof-zephyr/mpp_layer/dp_scheduling.rst | 614 ++++++++++++++++++ .../images/dp_scheduling/example1.pu | 34 + .../images/dp_scheduling/example1_1.pu | 34 + .../images/dp_scheduling/example1_2.pu | 34 + .../images/dp_scheduling/example1_3.pu | 40 ++ .../images/dp_scheduling/example1_4.pu | 42 ++ .../images/dp_scheduling/example1_5.pu | 41 ++ .../images/dp_scheduling/example2.pu | 34 + .../images/dp_scheduling/example2_1.pu | 40 ++ .../images/dp_scheduling/example2_1a.pu | 34 + .../images/dp_scheduling/example2_2.pu | 34 + .../images/dp_scheduling/example2_2a.pu | 34 + .../images/dp_scheduling/example2_3.pu | 40 ++ .../images/dp_scheduling/example2_4.pu | 40 ++ .../images/dp_scheduling/example2_5.pu | 40 ++ .../images/dp_scheduling/example2_6.pu | 34 + .../images/dp_scheduling/example2_7.pu | 39 ++ .../images/dp_scheduling/example3.pu | 34 + .../images/dp_scheduling/example3_1.pu | 34 + .../images/dp_scheduling/example3_2.pu | 34 + .../images/dp_scheduling/example3_3.pu | 34 + .../images/dp_scheduling/example3_4.pu | 34 + .../images/dp_scheduling/example3_5.pu | 34 + .../images/dp_scheduling/example3_6.pu | 34 + .../images/dp_scheduling/example3_7.pu | 40 ++ .../images/dp_scheduling/example4.pu | 38 ++ .../images/dp_scheduling/example4_1.pu | 38 ++ .../images/dp_scheduling/example4_2.pu | 38 ++ .../images/dp_scheduling/pic1_chains.pu | 16 + .../firmware/sof-zephyr/mpp_layer/index.rst | 1 + 30 files changed, 1617 insertions(+) create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/dp_scheduling.rst create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_1.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_2.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_3.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_4.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_5.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1a.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2a.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_3.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_4.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_5.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_6.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_7.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_1.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_2.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_3.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_4.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_5.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_6.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_7.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_1.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_2.pu create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/pic1_chains.pu diff --git a/architectures/firmware/sof-zephyr/mpp_layer/dp_scheduling.rst b/architectures/firmware/sof-zephyr/mpp_layer/dp_scheduling.rst new file mode 100644 index 0000000..c6adf7f --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/dp_scheduling.rst @@ -0,0 +1,614 @@ +DP a.k.a. "Data processing" with EDF scheduling +************************************************ + +DP a.k.a. "Data processing" is an async scheduling method of data processing modules. Each module works in a separate, preemptible thread with lower priority than LL thread. It allows processing with periods longer than 1ms, on-demand processing, etc. + +Unlike in LL "low latency" method where a module started every 1ms cycle and all of LL modules together MUST finish processing 1ms, DP works async and gets CPU when a module is "ready for processing", what means: + + - on each module's input buffer there's at least IBS bytes of data and in each module's output buffer there's at least OBS bytes of free space + + OR + + - a module declared readiness by itself by an optional API call "is_ready_to_process" + +Critical part is that the module **must** finish processing before its **deadline**. A deadline is a time when the modules must provide a data chunk in order to keep next module(s) in the pipeline working. + +To ensure that all modules provide data on time - as long as CPU is not overloaded - regardless of modules' processing times and processing periods, a Earliest Deadline First (EDF) scheduling is used. https://en.wikipedia.org/wiki/Earliest_deadline_first_scheduling + +A list of all DP tasks, regardless on core the task is on, is to be iterated every time the situation of DP readiness or deadline timing may change, that include: + + - finish of processing of LL pipeline (on any core) + - finish of processing of any DP module (on any core) + +during the iteration, the following will be checked: + + - Readiness of each DP module. As mentioned before, module "is ready" when declared readiness by itself an API call or when it has at least IBS of data on each input and at least OBS free space on each out + - deadline calculation of each DP module. LFTs and Deadlines are not constant, they may change when a module consume/produce a portion of data. Therefore all LFTs and Deadlines must be re-calculated + +DEADLINE CALCULATIONS +====================== + +The most critical part is to calculate deadlines. Lets go from the beginning, there are some definitions: + +**def: buffers' Latest Feeding Time (LFT)** + +LFT is the latest time when **a buffer** must be fed with a portion of data allowing its data consumer to work and finish in its specific time + +LFT is a parameter specific to a buffer and can be calculated based on: + + - current amount of data in the buffer + - data reciever's consumption rate and period + - data source production rate and period + - data reciever's module's LST - latest start time + +so, in high level LFT is a sum of: + + - Latest start time (LST) of the data consumer (LST is defined later) + + - estimated time the consumer will drain the current data from the buffer: ``number_of_ms_in_buffer / consumer_period`` + + i.e. if there's 5ms of data in the buffer and period of the consumer is 2ms, the calculated time is ``4ms`` + + - correction for multiple source cycle + + in case the producer period < consumer period the LFT time needs to be corrected, as the producer must process more than once to provide enough data. The correction will be calculated as: ``producer_LPT * required_number_of_cycles`` where LPT is longest processing time, explained later + + ``correction = producer_LPT * ((consumer_period - number_of_ms_in_buffer) / producer_period)`` + + if correction is < 0, it should be set to zero. Note that in case producer_period >= consumer_period correction is always 0 + +finally: ``LFT = LST(consumer) + estimated_drain_time - correction`` + +**def: DP module's DEADLINE** + +a DEADLINE is the latest moment **a module** must finish processing to feed all target buffers before their LFTs. +Calculation is simple: + + - module's deadline is the nearest LFT of all target buffers + +in case te LFT of the buffer cannot be calculated - that may happen during pipeline startup or if there's no output buffer, i.e. a module like speech recognition - deadline should be set to "moment when module becomes ready + modules's period" + +**def: DP module's Longest Processing Time (LPT)** + +LPT is the longest time the module may process a portion of data, assuming it is scheduled 100% of CPU time. **LPT cannot be measured in runtime** as processing may change from cycle to cycle, etc. It can, however, be estimated based on: + +- declared (by a module vendor) number of CPU cycles required for processing. This declaration should be done separately for all combination of input/output data formats, platform, CPU type, using of HiFi etc. and either included in manifest od provided in an IPC call +- If declaration is not available, we can take "a period" as an approximation of longest possible processing time. "A period" is a value calculated using IBS and data consumption rate of a module. A module cannot possibly processing longer than its period, because it would never provide data in time (if LPT = period that means a module required 100% of CPU for processing, so it is really the worst possible case) + +*Example:* if a data rate is 48samples/msec and OBS = 480samples, the "worst case" period should be calculated 10ms + +*NOTE:* in case of sampling freq like 44.1 a round up should taken - if ration is 44.1 samples per mlisecond, 45 samples should be used for calculations + +The "worst case approximation", however a correct, is assuming that a module is a heavy one and it requires 100% of CPU time. Using it may lead to unnecessary buffering, see "delayed start" section below. + +**def: DP module's latest start time (LST)** + +LST is the latest time when **a module** must start processing a portion of data in order to meet its deadline. It can be calculated as: +``deadline - LPT`` When a module is in the middle of processing, its LST may be negative. In that case 0 should be taken to all futhure calculations. + +**Based on an above, it is clear that we do need to calculate first a deadline of the very latest module in a chain, than go back and calculate LFTs and deadline of each module separately** + +Fortunate is that the last module of a pipeline is almost always an LL module (usually DAI). For LL module deadline always is "NOW", so it is very easy to calculate LFTs for its input buffer(s). note: in case of data rates like 44.1, which cannot be divided to 1ms, a round up to 45 should be used: + + - LL module always start in 1ms periods + - LL module always consume constant number of bytes in a cycle (with an exception for frequencies like 44.1, a round up 45KHz should be taken for calculations) + + so ``LFT = NOW + number of data chunks in buffer * 1ms`` + +"NOW" in all of the calculations is "last start of LL scheduler". It makes all calculations simpler, as in the examples below (calculating CPU cycles would require taking extra care for 32bit overflows or use slow 64bit operations). Also all modules have the same timestamp as "NOW", regardless of moment in the cycle the deadlines are calculated. + +If a module is in the middle of processing, it should not release data from input buffer till the processing is finished, so the input buffer should be considered as it was at the moment the processing started, otherwise deadlines may be miscalculated. + +In case of pipeline like: + +.. uml:: images/dp_scheduling/pic1_chains.pu + +there are 2 separate deadline calculation chains: DP4 than DP3, and (independent) DP2 than DP1. **Also note that deadlines and other parameters may change, so re-calculation of all parameters should occur reasonable frequently and include all DP modules, regardless of a core it is run on** + +End of stream +============= + +When a SP module is in the middle of processing when a pipeline is stopping, it should finish processing its current chunk of data. Unformtunately there's no way to interrupt ongoing processing without risk of memory leaks etc. Therefore IPC stopping a pipeline should wait till all DP modules finish processing. + +EXAMPLE1 +========= +*data source period is longer or equal to data consumer period* +Note that in the example CPU load is very close to 100%, yet deadline calculation and EDF scheduling allow to keep the processing on time. + +for simplification lets assume: + + - the pipeline is in stable state (processing for a while, not in startup) + - no DP is currently processing + - whole CPU is dedicated to DP, like if LL is on core 0 and DPs on core 1 + +**0ms time:** + +.. uml:: images/dp_scheduling/example1.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is ready for processing + + calculate deadlines: + + - ``buf3 LFT = 15 periods of LL2`` ==> ``DP2 deadline = 15ms`` + - ``DP2 LST = 15ms (DP2 deadline) - 9ms (DP2 LPT) = 6ms`` + - ``buf2 LFT = 6ms (DP2 LST) + 10ms (1 period in buf2) = 16ms`` ==> ``DP1 deadline = 16ms`` + + DP2 will be scheduled as it has earliest deadline, will process for 9ms + +**9ms time, DP2 finished processing but not yet released data from BUF2:** + +.. uml:: images/dp_scheduling/example1_1.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 just finished processing + + calculate deadlines: + + - ``buf3 LFT = 6 periods of LL2`` ==> ``DP2 deadline = 6ms`` + - ``DP2 LST = 6ms(DP2 deadline) - 9ms (DP2 LPT) = -3ms`` LST is negative, 0 should be used ``DP2 LST = 0`` + - ``buf2 LFT = 6ms (DP2 LST) + 10ms (1 period in buf2) = 16ms`` ==> ``DP1 deadline = 16ms`` + + DP1 will be scheduled + +**9ms time, DP2 released data from BUF2:** + +.. uml:: images/dp_scheduling/example1_2.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is not ready for processing + + calculate deadlines: + + - ``buf3 LFT = 16 periods of LL2`` ==> ``DP2 deadline = 16ms`` + - ``DP2 LST = 16ms(DP2 deadline) - 9ms (DP2 LPT) = 7ms`` + - ``buf2 LFT = 7ms (DP2 LST) = 7ms`` ==> ``DP1 deadline = 7ms`` + + DP1 will be scheduled, will run for 5ms + +**14ms time, DP1 finished processing and released data from BUF1:** + +.. uml:: images/dp_scheduling/example1_3.pu + +Pipeline state: + + - DP1 is not ready for processing + - DP2 is ready for processing + + calculate deadlines: + + - ``buf3 LFT = 11 periods of LL2`` ==> ``DP2 deadline = 11ms`` + - ``DP2 LST = 11ms(DP2 deadline) - 9ms (DP2 LPT) = 2ms`` + - ``buf2 LFT = 2ms (DP2 LST) + 100ms (10 periods in buf2) = 102ms`` ==> ``DP1 deadline = 102ms`` + + DP2 will be scheduled + +**100ms time, 86ms passed, DP2 processed 9 times, is in the middle of 10th processing, having 5ms left:** + +.. uml:: images/dp_scheduling/example1_4.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is ready for processing + + calculate deadlines: + + - ``buf3 LFT = 15 periods of LL2`` ==> ``DP2 deadline = 15ms`` + - ``DP2 LST = 15ms(DP2 deadline) - 9ms (DP2 LPT) = 6ms`` + - ``buf2 LFT = 6ms (DP2 LST) + 10ms (1 period in buf2) = 16ms`` ==> ``DP1 deadline = 16ms`` + + DP2 will be scheduled + +**105ms time, DP2 finished processing and released data from BUF2:** + +.. uml:: images/dp_scheduling/example1_5.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is not ready for processing + + calculate deadlines: + + - ``buf3 LFT = 20 periods of LL2`` ==> ``DP2 deadline = 20ms`` + - ``DP2 LST = 20ms(DP2 deadline) - 9ms (DP2 LPT) = 11ms`` + - ``buf2 LFT = 11ms (DP2 LST) + 0ms = 11ms`` ==> ``DP1 deadline = 11ms`` + + DP1 will be scheduled + +EXAMPLE2 +========= +*data source period is shorter than data consumer period* + +**0ms time:** + +.. uml:: images/dp_scheduling/example2.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is not ready for processing + + calculate deadlines: + + - ``buf3 LFT = 18 periods of LL2`` ==> ``DP2 deadline = 18ms`` + - ``DP2 LST = 18ms (DP2 deadline) - 10ms (DP2 LPT) = 8ms`` + - ``buf2 LFT = 8ms(DP2 LST) + 0 (0 complete periods of DP2 in buf2) = 8ms`` correction for multiple source cycle is = 0 + - ``DP1 deadline = 8ms`` + + DP1 will be scheduled + +**2ms time:** + +.. uml:: images/dp_scheduling/example2_1.pu + +Pipeline state: + + - DP1 is not ready for processing + - DP2 is ready for processing + + calculate deadlines: + + - ``buf3 LFT = 16 periods of LL2`` ==> ``DP2 deadline = 16ms`` + - ``DP2 LST = 16ms (DP2 deadline) - 10ms (DP2 LPT) = 6ms`` + - ``buf2 LFT = 6ms(DP2 LST) + 20 (1 complete periods of DP2 in buf2) = 26ms`` correction for multiple source cycle is < 0, so 0 is used + - ``DP1 deadline = 26ms`` + + DP2 will be scheduled + +**5ms time:** + +.. uml:: images/dp_scheduling/example2_1a.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is in the middle of processing, still has to keep processing for 7ms. According to rules, the module should not release data from input buffer till the processing is finished, so buf2 still contains 20ms samples + + calculate deadlines: + + - ``buf3 LFT = 13 periods of LL2`` ==> ``DP2 deadline = 13ms`` + - ``DP2 LST = 13ms (DP2 deadline) - 10ms (DP2 LPT) = 3ms`` + - ``buf2 LFT = 3ms(DP2 LST) + 20 (1 complete periods of DP2 in buf2) = 23ms`` correction for multiple source cycle is < 0, so 0 is used + - ``DP1 deadline = 23ms`` + + DP2 will be scheduled and will keep processing for 7ms + +**12ms time, before releasing data from buf2 and acking data in buf3** + +.. uml:: images/dp_scheduling/example2_2a.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 finished processing, but not yet released data from buf2, so buf2 still contains 20ms samples + + calculate deadlines: + + - ``buf3 LFT = 6 periods of LL2`` ==> ``DP2 deadline = 6ms`` + - ``DP2 LST = 6ms (DP2 deadline) - 10ms (DP2 LPT) = -4ms`` LST is negative, so 0 should be used + - ``buf2 LFT = 0ms(DP2 LST) + 20ms (1 complete periods of DP2 in buf2) = 20ms`` correction for multiple source cycle is < 0, so 0 is used + - ``DP1 deadline = 20ms`` + + DP2 will be release data + +**12ms time, after releasing data from buf2 and acking data in buf3** + +.. uml:: images/dp_scheduling/example2_2.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is not ready for processing + + calculate deadlines: + + - ``buf3 LFT = 26 periods of LL2`` ==> ``DP2 deadline = 26ms`` + - ``DP2 LST = 26ms (DP2 deadline) - 10ms (DP2 LPT) = 16ms`` + - ``buf2 LFT = 16ms(DP2 LST) + 0 (0 complete periods of DP2 in buf2) - 8ms correction (4 periods of DP2 * 2ms DP1 LPT) = 8ms`` + - ``DP1 deadline = 8ms`` + + DP1 will be scheduled + +**14ms time:** + +.. uml:: images/dp_scheduling/example2_3.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is not ready for processing + + calculate deadlines: + + - ``buf3 LFT = 24 periods of LL2`` ==> ``DP2 deadline = 24ms`` + - ``DP2 LST = 24ms (DP2 deadline) - 10ms (DP2 LPT) = 14ms`` + - ``buf2 LFT = 14ms(DP2 LST) + 0 (0 complete periods of DP2 in buf2) - 6ms correction (3 periods of DP2 * 2ms DP1 LPT) = 8ms`` + - ``DP1 deadline = 8ms`` + + DP1 will be scheduled + +**16ms time:** + +.. uml:: images/dp_scheduling/example2_4.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is not ready for processing + + calculate deadlines: + + - ``buf3 LFT = 22 periods of LL2`` ==> ``DP2 deadline = 22ms`` + - ``DP2 LST = 22ms (DP2 deadline) - 10ms (DP2 LPT) = 12ms`` + - ``buf2 LFT = 12ms(DP2 LST) + 0 (0 complete periods of DP2 in buf2) - 4ms correction (2 periods of DP2 * 2ms DP1 LPT) = 8ms`` + - ``DP1 deadline = 8ms`` + + DP1 will be scheduled + +**18ms time:** + +.. uml:: images/dp_scheduling/example2_5.pu + +Pipeline state: + + - DP1 is not ready for processing + - DP2 is not ready for processing + + calculate deadlines - however pointless at when no DP is ready: + + - ``buf3 LFT = 20 periods of LL2`` ==> ``DP2 deadline = 20ms`` + - ``DP2 LST = 20ms (DP2 deadline) - 10ms (DP2 LPT) = 10ms`` + - ``buf2 LFT = 10ms(DP2 LST) + 0 (0 complete periods of DP2 in buf2) - 2ms correction (2 periods of DP2 * 2ms DP1 LPT) = 8ms`` + - ``DP1 deadline = 8ms`` + + no DP will be scheduled + +**20ms time:** + +.. uml:: images/dp_scheduling/example2_6.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is not ready for processing + + calculate deadlines - however pointless at when no DP is ready: + + - ``buf3 LFT = 18 periods of LL2`` ==> ``DP2 deadline = 18ms`` + - ``DP2 LST = 18ms (DP2 deadline) - 10ms (DP2 LPT) = 8ms`` + - ``buf2 LFT = 8ms(DP2 LST) + 0 (0 complete periods of DP2 in buf2) - 2ms correction (2 periods of DP2 * 2ms DP1 LPT) = 6ms`` + - ``DP1 deadline = 6ms`` + + DP1 will be scheduled + +**22ms time:** + +.. uml:: images/dp_scheduling/example2_7.pu + +Pipeline state: + + - DP1 is not ready for processing + - DP2 is ready for processing + + calculate deadlines + + - ``buf3 LFT = 16 periods of LL2`` ==> ``DP2 deadline = 16ms`` + - ``DP2 LST = 16ms (DP2 deadline) - 10ms (DP2 LPT) = 6ms`` + - ``buf2 LFT = 6ms(DP2 LST) +20 (1 complete period of DP2 in buf2) = 26ms`` correction for multiple source cycle is = 0 + - ``DP1 deadline = 26ms`` + + DP2 will be scheduled + + +STARTUP +========== + +Special case is "pipeline startup". When a pipeline is starting, deadlines cannot be calculated as all the modules are already late and deadlines are in the past. According to deadline calculation rules, the deadline is set to time when the module becomes ready + module's LPT. + +If a module finishes processing before its LPT. it is not guaranteed that it will do it again in any of next cycles. If it happens, the data should be held in the buffer till LPT passes. This prevents underruns in case any of future processing takes longer. This mechanism is called "delayed start". The module should stay in "delayed start" state till the next module becomes ready for the first time. + +Delayed start makes EDF scheduling possible and ensures that even when CPU load close to 100% every module have enough processing time to finish within its deadline. + +Example of a pipeline startup and 100% cpu usage +================================================ + +**0ms time:** + +.. uml:: images/dp_scheduling/example3.pu + +Pipeline state: + + - DP1 is not ready for processing, in startup delay state + - DP2 is not ready for processing, in startup delay state + + calculate deadlines + + - dedline of DP2 can't be calculated + - dedline of DP1 can't be calculated + + no DP will be scheduled + +**5ms time:** + +.. uml:: images/dp_scheduling/example3_1.pu + +Pipeline state: + + - DP1 is ready for processing, in startup delay state + - DP2 is not ready for processing, in startup delay state + + calculate deadlines + + - deadline for DP2 cant be calculated + - deadline of DP1 is fixed to 2ms (NOW + DP1 LPT) - because DP2 deadline cannot be calculated + + DP1 will be scheduled + +**7ms time:** + +.. uml:: images/dp_scheduling/example3_2.pu + +Pipeline state: + + - DP1 is not ready for processing, in startup delay state + - DP2 is not ready for processing, in startup delay state + + calculate deadlines + + - deadline for DP2 cant be calculated + - deadline for DP1 cant be calculated + + no DP will be scheduled + +**10ms time:** + +.. uml:: images/dp_scheduling/example3_3.pu + +Pipeline state: + + - DP1 is ready for processing, in startup delay state + - DP2 is not ready for processing, in startup delay state + + calculate deadlines + + - deadline for DP2 cant be calculated + - deadline of DP1 is fixed to 2ms (NOW + DP1 LPT) - because DP2 deadline cannot be calculated + + DP1 will be scheduled + +**12ms time:** + +.. uml:: images/dp_scheduling/example3_4.pu + +Pipeline state: + + - DP1 is not ready for processing, leaving startup delay state + - DP2 is ready for processing, in startup delay state + + calculate deadlines + + - deadline for DP2 is fixed to 6ms (NOW + DP2 LPT) + - ``DP2 LST = 6ms (DP2 deadline) - 6ms (DP2 LPT) = 0ms`` + - ``buf2 LFT = 0ms(DP2 LST) + 10ms (1 complete period of DP2 in buf2) = 10ms`` correction for multiple source cycle is = 0 + - ``DP1 deadline = 14ms`` + + DP2 will be scheduled + +**15ms time:** + +.. uml:: images/dp_scheduling/example3_5.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is the middle for processing, 3ms left, in startup delay state + + calculate deadlines + + - deadline for DP2 was fixed to 6ms 3ms ago, so now it is 3ms + - ``DP2 LST = 3ms (DP2 deadline) - 6ms (DP2 LPT) = -3ms`` 0 will be used + - ``buf2 LFT = 0(DP2 LST) +10 (1 complete period of DP2 in buf2) = 10ms`` correction for multiple source cycle is = 0 + - ``DP1 deadline = 10ms`` + + DP2 will be scheduled + +**17ms time:** + +.. uml:: images/dp_scheduling/example3_6.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is not ready for processing, leaving startup delay state + + calculate deadlines + + - ``buf3 LFT = 10 periods of LL2`` ==> ``DP2 deadline = 10ms`` + - ``DP2 LST = 10ms (DP2 deadline) - 6ms (DP2 LPT) = 4ms`` + - ``buf2 LFT = 4ms(DP2 LST) + 0 (0 complete periods of DP2 in buf2) - 2ms correction (2 periods of DP2 * 2ms DP1 LPT) = 2ms`` + - ``DP1 deadline = 2ms`` + + DP1 will be scheduled + +**19ms time:** + +.. uml:: images/dp_scheduling/example3_7.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is not ready for processing + + calculate deadlines + + - ``buf3 LFT = 8 periods of LL2`` ==> ``DP2 deadline = 8ms`` + - ``DP2 LST = 10ms (DP2 deadline) - 6ms (DP2 LPT) = 2ms`` + - ``buf2 LFT = 2ms(DP2 LST) + 0 (0 complete periods of DP2 in buf2) - 0ms correction (0 periods of DP2 * 2ms DP1 LPT) = 2ms`` + - ``DP1 deadline = 2ms`` + + DP1 will be scheduled + + +Example of a 2 pipelines, one running and one in startup and 100% cpu usage +============================================================================ + +pipeline1 is running, DP use 80% of CPU, pipeline2 is starting. Calculating of DP1/DP2 LST and BUF1/BUF3 LFT makes no sense as they're connected to LLs + +**0ms time:** + +.. uml:: images/dp_scheduling/example4.pu + +Pipeline state: + + - DP1 is ready for processing + - DP2 is not ready for processing + + calculate deadlines + + - ``buf2 LFT = 10 periods of LL2`` ==> ``DP1 deadline = 10ms`` + - DP2 deadline cannot be calculated + + DP1 will be scheduled + +**5ms time:** + +.. uml:: images/dp_scheduling/example4_1.pu + +Pipeline state: + + - DP1 is in the middle of processing, 3ms left + - DP2 is ready for processing, in startup delay state + + calculate deadlines + + - ``buf2 LFT = 5 periods of LL2`` ==> ``DP1 deadline = 5ms`` + - DP2 deadline is fixed to ``DP2 period = 1ms`` + + DP1 will be preempted, DP2 will be scheduled + +**6ms time:** + +.. uml:: images/dp_scheduling/example4_2.pu + +Pipeline state: + + - DP1 is in the middle of processing, 3ms left + - DP2 is not ready for processing, leaving startup delay state + + calculate deadlines + + - ``buf2 LFT = 4 periods of LL2`` ==> ``DP1 deadline = 4ms`` + - ``buf4 LFT = 5 periods of LL2`` ==> ``DP2 deadline = 5ms`` + + + DP2 will be scheduled + + diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1.pu new file mode 100644 index 0000000..969188b --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n100ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 100ms + LPT: 5ms +end note + +rectangle "BUF2\n\n10ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 9ms +end note + +rectangle "BUF3\n\n15ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_1.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_1.pu new file mode 100644 index 0000000..b8f65e2 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_1.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n109ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 100ms + LPT: 5ms +end note + +rectangle "BUF2\n\n10ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 9ms +end note + +rectangle "BUF3\n\n6ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_2.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_2.pu new file mode 100644 index 0000000..9b8798b --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_2.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n109ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 100ms + LPT: 5ms +end note + +rectangle "BUF2\n\n0ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 9ms +end note + +rectangle "BUF3\n\n16ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_3.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_3.pu new file mode 100644 index 0000000..5dd8d95 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_3.pu @@ -0,0 +1,40 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n14ms of data\n" as buf1 +note bottom of buf1 + there was 109ms + LL1 produced 5ms + DP1 consumed 100ms + 109+5-100 = 14ms +end note + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 100ms + LPT: 5ms +end note + +rectangle "BUF2\n\n100ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 9ms +end note + +rectangle "BUF3\n\n11ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_4.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_4.pu new file mode 100644 index 0000000..03ed335 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_4.pu @@ -0,0 +1,42 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n100ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 100ms + LPT: 5ms +end note + +rectangle "BUF2\n\n10ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 9ms +end note + +rectangle "BUF3\n\n15ms of data\n" as buf3 + +note bottom of buf3 + there was 11ms + DP2 produced 90ms + LL2 consumed 86ms + 11+90-86 = 15ms +end note + + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_5.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_5.pu new file mode 100644 index 0000000..098fb79 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_5.pu @@ -0,0 +1,41 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n105ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 100ms + LPT: 5ms +end note + +rectangle "BUF2\n\n0ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 9ms +end note + +rectangle "BUF3\n\n20ms of data\n" as buf3 + +note bottom of buf3 + there was 15ms + DP2 produced 10ms + LL2 consumed 5ms + 15+10-5 = 20ms +end note + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2.pu new file mode 100644 index 0000000..7677f06 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n5ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n15ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 20ms + LPT: 10ms +end note + +rectangle "BUF3\n\n18ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1.pu new file mode 100644 index 0000000..83dfc83 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1.pu @@ -0,0 +1,40 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n2ms of data\n" as buf1 +note bottom of buf1 + there was 5ms + LL1 produced 2ms + DP1 consumed 5ms + 5-5+2 = 2ms +end note + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n20ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 20ms + LPT: 10ms +end note + +rectangle "BUF3\n\n16ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1a.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1a.pu new file mode 100644 index 0000000..8e1c287 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1a.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n5ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n20ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 20ms + LPT: 10ms +end note + +rectangle "BUF3\n\n13ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2.pu new file mode 100644 index 0000000..0e7440c --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n12ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n0ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 20ms + LPT: 10ms +end note + +rectangle "BUF3\n\n26ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2a.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2a.pu new file mode 100644 index 0000000..20f6e42 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2a.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n12ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n20ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 20ms + LPT: 10ms +end note + +rectangle "BUF3\n\n6ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_3.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_3.pu new file mode 100644 index 0000000..a976be4 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_3.pu @@ -0,0 +1,40 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n9ms of data\n" as buf1 +note bottom of buf1 + there was 12ms + LL1 produced 2ms + DP1 consumed 5ms + 12+2-5 = 9ms +end note + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n5ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 20ms + LPT: 10ms +end note + +rectangle "BUF3\n\n24ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_4.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_4.pu new file mode 100644 index 0000000..4e06b3e --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_4.pu @@ -0,0 +1,40 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n6ms of data\n" as buf1 +note bottom of buf1 + there was 9ms + LL1 produced 2ms + DP1 consumed 5ms + 9+2-5 = 6ms +end note + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n10ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 20ms + LPT: 10ms +end note + +rectangle "BUF3\n\n22ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_5.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_5.pu new file mode 100644 index 0000000..c1efc9c --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_5.pu @@ -0,0 +1,40 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n3ms of data\n" as buf1 +note bottom of buf1 + there was 6ms + LL1 produced 2ms + DP1 consumed 5ms + 9+2-5 = 3ms +end note + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n15ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 20ms + LPT: 10ms +end note + +rectangle "BUF3\n\n20ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_6.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_6.pu new file mode 100644 index 0000000..7677f06 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_6.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n5ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n15ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 20ms + LPT: 10ms +end note + +rectangle "BUF3\n\n18ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_7.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_7.pu new file mode 100644 index 0000000..b2a6ca7 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_7.pu @@ -0,0 +1,39 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n2ms of data\n" as buf1 +note bottom of buf1 + there was 5ms + LL1 produced 2ms + DP1 consumed 5ms + 5+2-5 = 2ms +end note +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n20ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 20ms + LPT: 10ms +end note + +rectangle "BUF3\n\n16ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3.pu new file mode 100644 index 0000000..92dbf04 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n0ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n0ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 6ms +end note + +rectangle "BUF3\n\n0ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_1.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_1.pu new file mode 100644 index 0000000..0c83890 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_1.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n5ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n0ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 6ms +end note + +rectangle "BUF3\n\n0ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_2.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_2.pu new file mode 100644 index 0000000..c5e7fab --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_2.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n2ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n5ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 6ms +end note + +rectangle "BUF3\n\n0ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_3.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_3.pu new file mode 100644 index 0000000..64b7acc --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_3.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n5ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n5ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 6ms +end note + +rectangle "BUF3\n\n0ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_4.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_4.pu new file mode 100644 index 0000000..858ff44 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_4.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n2ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n10ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 6ms +end note + +rectangle "BUF3\n\n0ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_5.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_5.pu new file mode 100644 index 0000000..d9ccd7e --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_5.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n9ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n10ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 6ms +end note + +rectangle "BUF3\n\n0ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_6.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_6.pu new file mode 100644 index 0000000..f43be35 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_6.pu @@ -0,0 +1,34 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n12ms of data\n" as buf1 + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n0ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 6ms +end note + +rectangle "BUF3\n\n10ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_7.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_7.pu new file mode 100644 index 0000000..5591eaa --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_7.pu @@ -0,0 +1,40 @@ +@startuml +left to right direction +(LL1) as mod1 #f6ed80 + +rectangle "BUF1\n\n9ms of data\n" as buf1 +note bottom of buf1 + there was 12ms + LL1 procuded 2ms + DP1 consumed 5ms + 12 + 2 - 5 = 9ms +end note + +(DP1) as mod2 #ADD1B2 + +note bottom of mod2 + period 5ms + LPT: 2ms +end note + +rectangle "BUF2\n\n5ms of data\n" as buf2 + +(DP2) as mod3 #ADD1B2 + +note bottom of mod3 + period 10ms + LPT: 6ms +end note + +rectangle "BUF3\n\n8ms of data\n" as buf3 + +(LL2) as mod4 #f6ed80 + + +mod1--> buf1 +buf1 --> mod2 +mod2-->buf2 +buf2 --> mod3 +mod3-->buf3 +buf3 --> mod4 +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4.pu new file mode 100644 index 0000000..dfb6cd2 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4.pu @@ -0,0 +1,38 @@ +@startuml +left to right direction + +package pipeline2{ + (LL3) #f6ed80 + rectangle "BUF3\n\n0ms of data\n" as buf3 + (DP2) #ADD1B2 + note bottom of DP2 + period 5ms + LPT: 1ms + end note + rectangle "BUF4\n\n0ms of data\n" as buf4 + (LL4) #f6ed80 +} + +package pipeline1{ + (LL1) #f6ed80 + rectangle "BUF1\n\n10ms of data\n" as buf1 + (DP1) #ADD1B2 + note bottom of DP1 + period 10ms + LPT: 8ms + end note + rectangle "BUF2\n\n10ms of data\n" as buf2 + (LL2) #f6ed80 + } + +LL1 --> buf1 +buf1 --> DP1 +DP1 --> buf2 +buf2 --> LL2 + +LL3 --> buf3 +buf3 --> DP2 +DP2 --> buf4 +buf4 --> LL4 + +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_1.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_1.pu new file mode 100644 index 0000000..627e730 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_1.pu @@ -0,0 +1,38 @@ +@startuml +left to right direction + +package pipeline2{ + (LL3) #f6ed80 + rectangle "BUF3\n\n5ms of data\n" as buf3 + (DP2) #ADD1B2 + note bottom of DP2 + period 5ms + LPT: 1ms + end note + rectangle "BUF4\n\n0ms of data\n" as buf4 + (LL4) #f6ed80 +} + +package pipeline1{ + (LL1) #f6ed80 + rectangle "BUF1\n\n15ms of data\n" as buf1 + (DP1) #ADD1B2 + note bottom of DP1 + period 10ms + LPT: 8ms + end note + rectangle "BUF2\n\n5ms of data\n" as buf2 + (LL2) #f6ed80 + } + +LL1 --> buf1 +buf1 --> DP1 +DP1 --> buf2 +buf2 --> LL2 + +LL3 --> buf3 +buf3 --> DP2 +DP2 --> buf4 +buf4 --> LL4 + +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_2.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_2.pu new file mode 100644 index 0000000..9e5a49b --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_2.pu @@ -0,0 +1,38 @@ +@startuml +left to right direction + +package pipeline2{ + (LL3) #f6ed80 + rectangle "BUF3\n\n1ms of data\n" as buf3 + (DP2) #ADD1B2 + note bottom of DP2 + period 5ms + LPT: 1ms + end note + rectangle "BUF4\n\n5ms of data\n" as buf4 + (LL4) #f6ed80 +} + +package pipeline1{ + (LL1) #f6ed80 + rectangle "BUF1\n\n16ms of data\n" as buf1 + (DP1) #ADD1B2 + note bottom of DP1 + period 10ms + LPT: 8ms + end note + rectangle "BUF2\n\n4ms of data\n" as buf2 + (LL2) #f6ed80 + } + +LL1 --> buf1 +buf1 --> DP1 +DP1 --> buf2 +buf2 --> LL2 + +LL3 --> buf3 +buf3 --> DP2 +DP2 --> buf4 +buf4 --> LL4 + +@enduml \ No newline at end of file diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/pic1_chains.pu b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/pic1_chains.pu new file mode 100644 index 0000000..0dc0256 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/pic1_chains.pu @@ -0,0 +1,16 @@ +left to right direction +(LL1) as mod1 +(DP1) as mod2 #ADD1B2 +(DP2) as mod3 #ADD1B2 +(LL2) as mod4 +(DP3) as mod5 #7D3CFF +(DP4) as mod6 #7D3CFF +(LL3) as mod7 + + +mod1-->mod2 +mod2-->mod3 +mod3-->mod4 +mod4-->mod5 +mod5-->mod6 +mod6-->mod7 diff --git a/architectures/firmware/sof-zephyr/mpp_layer/index.rst b/architectures/firmware/sof-zephyr/mpp_layer/index.rst index 67629b3..b854288 100644 --- a/architectures/firmware/sof-zephyr/mpp_layer/index.rst +++ b/architectures/firmware/sof-zephyr/mpp_layer/index.rst @@ -14,3 +14,4 @@ to the Application layer. mpp_scheduling async_messaging lib_manager + dp_scheduling \ No newline at end of file From d86c40253cddfe3bc9a4302c6a9ec81719b6f56d Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Wed, 10 Jun 2026 20:14:31 +0100 Subject: [PATCH 19/25] docs: Drop orphaned blockdiag extension blockdiag is orphaned upstream, incompatible with pillow>=10, and uses APIs removed from modern setuptools (pkg_resources). It forced the pillow<10 / setuptools<81 pins that block building the docs on current Python (3.13+), see thesofproject/sof-docs#472. It was used for a single diagram. Convert that diagram (mpp_layer EDF scheduling example) to graphviz, which is already a dependency and renders the rest of the diagrams, then remove the blockdiag extension and the pillow<10 pin from both requirements files. With this change the documentation builds on current Python with no version ceilings. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Liam Girdwood --- .../images/mpp_scheduling/edf_scheduling.diag | 42 ------------------- .../images/mpp_scheduling/edf_scheduling.dot | 23 ++++++++++ .../sof-zephyr/mpp_layer/mpp_scheduling.rst | 2 +- conf.py | 4 +- scripts/requirements-lax.txt | 6 --- scripts/requirements.txt | 6 --- 6 files changed, 25 insertions(+), 58 deletions(-) delete mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.diag create mode 100644 architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.diag b/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.diag deleted file mode 100644 index b9680b2..0000000 --- a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.diag +++ /dev/null @@ -1,42 +0,0 @@ -// FIXME: blockdiag is orphaned and not compatible with Pillow anymore: -// https://github.com/blockdiag/blockdiag/pull/171 - -blockdiag edf_scheduling { - - node_width = 250; - node_height = 120; - default_fontsize = 16; - - Comp_1 -> Comp_2 - comment_1 -> Comp_2 [style=dashed] - Comp_2 -> Comp_3 - comment_2 -> Comp_3 [style=dashed] - Comp_3 -> Comp_4 - comment_3 -> Comp_4 [style=dashed] - Comp_4 -> sink - comment_4 -> sink [style=dashed] - - Comp_1 [label="DP component 1\n - *processing period\n - *compute requirement"] - Comp_2 [label="DP component 2\n - *processing period\n - *compute requirement"] - Comp_3 [label="DP component 3\n - *processing period\n - *compute requirement"] - Comp_4 [label="DP component 4\n - *processing period\n - *compute requirement"] - - sink [label="real time sink", shape=endpoint, fontsize = 16] - - comment_1 [label="DP1 to deliver data let\n - DP2 meet its objective"] - comment_2 [label="DP2 to deliver data let\n - DP3 meet its objective"] - comment_3 [label="DP3 to deliver data let\n - DP4 meet its objective"] - comment_4 [label="DP4 to deliver data\n - to real time-sink"] -} diff --git a/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot b/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot new file mode 100644 index 0000000..91447f9 --- /dev/null +++ b/architectures/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot @@ -0,0 +1,23 @@ +digraph edf_scheduling { + rankdir = LR; + node [shape = box, fontsize = 12]; + + Comp_1 [label = "DP component 1\n* processing period\n* compute requirement"]; + Comp_2 [label = "DP component 2\n* processing period\n* compute requirement"]; + Comp_3 [label = "DP component 3\n* processing period\n* compute requirement"]; + Comp_4 [label = "DP component 4\n* processing period\n* compute requirement"]; + + sink [label = "real time sink", shape = doublecircle]; + + comment_1 [label = "DP1 to deliver data let\nDP2 meet its objective", shape = note]; + comment_2 [label = "DP2 to deliver data let\nDP3 meet its objective", shape = note]; + comment_3 [label = "DP3 to deliver data let\nDP4 meet its objective", shape = note]; + comment_4 [label = "DP4 to deliver data\nto real time-sink", shape = note]; + + Comp_1 -> Comp_2 -> Comp_3 -> Comp_4 -> sink; + + comment_1 -> Comp_2 [style = dashed]; + comment_2 -> Comp_3 [style = dashed]; + comment_3 -> Comp_4 [style = dashed]; + comment_4 -> sink [style = dashed]; +} diff --git a/architectures/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst b/architectures/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst index c4ff563..20b3df8 100644 --- a/architectures/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst +++ b/architectures/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst @@ -128,7 +128,7 @@ deadline for data delivery: EDF scheduling example -.. blockdiag:: images/mpp_scheduling/edf_scheduling.diag +.. graphviz:: images/mpp_scheduling/edf_scheduling.dot The capture pipelines operate in the same way. diff --git a/conf.py b/conf.py index c64f349..1d2e971 100755 --- a/conf.py +++ b/conf.py @@ -32,10 +32,8 @@ # ones. -# FIXME: blockdiag is orphaned and not compatible with Pillow anymore: -# https://github.com/thesofproject/sof-docs/issues/472 extensions = ['breathe', 'sphinx.ext.graphviz', 'sphinxcontrib.plantuml', - 'sphinx.ext.todo', 'sphinx.ext.extlinks', 'sphinxcontrib.blockdiag', + 'sphinx.ext.todo', 'sphinx.ext.extlinks', 'sphinxcontrib.jquery' ] diff --git a/scripts/requirements-lax.txt b/scripts/requirements-lax.txt index 42077b4..ae8a407 100644 --- a/scripts/requirements-lax.txt +++ b/scripts/requirements-lax.txt @@ -13,7 +13,6 @@ breathe>=4.29.2 sphinx>=4.5.0 docutils>=0.17.1 sphinx_rtd_theme>=0.2.4 -sphinxcontrib-blockdiag>=3.0.0 sphinxcontrib-jquery # - Version 0.11 is the first version that supports @@ -56,8 +55,3 @@ sphinxcontrib.plantuml>=0.11 # - Downgrade if successfully tested. # - Test with plantum set to "none" in conf.py. We don't want small # typo fixes to depend on UML diagrams. - -# Workaround for warning "'ImageDraw' object has no attribute 'textsize'" -# with pillow 10.0.0, see -# https://github.com/thesofproject/sof-docs/issues/472 -pillow<10 diff --git a/scripts/requirements.txt b/scripts/requirements.txt index 17aff9e..54b257e 100644 --- a/scripts/requirements.txt +++ b/scripts/requirements.txt @@ -7,9 +7,3 @@ docutils sphinx_rtd_theme sphinxcontrib-plantuml sphinxcontrib-applehelp - - -# blockdiag is orphaned and not compatible with pillow>=10, -# see https://github.com/thesofproject/sof-docs/issues/472 -sphinxcontrib-blockdiag -pillow<10 From 3ff04e1e757b835894dccf61d5d3e9d3aabc097d Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Wed, 10 Jun 2026 20:26:51 +0100 Subject: [PATCH 20/25] docs: Pin the supported build with a lockfile The supported requirements.txt used unbounded ">=" specifiers (despite a comment claiming "==" pinning), so a new Sphinx or breathe release could break the build with no change to this repo, and two contributors could get different, unreproducible installs. Add scripts/constraints.txt, a lockfile pinning the full transitive dependency tree to exact, validated versions. The supported install now pairs requirements.txt (the readable top-level list) with this lockfile: pip install -r scripts/requirements.txt -c scripts/constraints.txt Wire it into the supported CI job and the docbuild instructions. The lock targets a modern Python (Sphinx 9 requires >= 3.11), so the CI job now uses actions/setup-python instead of the runner's system Python. Fix the stale requirements.txt header and drop the docbuild note about building pillow, which no longer applies now that blockdiag/pillow are gone. requirements-lax.txt stays loose for unpinned drive-by contributions. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Liam Girdwood --- .github/workflows/pull-request.yml | 11 ++++++-- contribute/process/docbuild.rst | 29 +++++++------------- scripts/constraints.txt | 43 ++++++++++++++++++++++++++++++ scripts/requirements.txt | 11 ++++++-- 4 files changed, 71 insertions(+), 23 deletions(-) create mode 100644 scripts/constraints.txt diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 11b29b3..262721c 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -37,6 +37,13 @@ jobs: steps: - uses: actions/checkout@v3 + # The supported build is pinned by scripts/constraints.txt, which + # targets a modern Python (>= 3.11). Use setup-python rather than the + # runner's system Python so the lockfile installs as validated. + - uses: actions/setup-python@v5 + with: + python-version: '3.13' + # FIXME: remove this time consuming step once github stops # providing a broken package index, see # https://github.com/actions/virtual-environments/issues/1757#issuecomment-777700920 @@ -49,8 +56,8 @@ jobs: - name: PATH += .local/bin run: echo "$HOME/.local/bin" >> $GITHUB_PATH - - name: 'pip install -r scripts/requirements.txt' - run: pip install -r scripts/requirements.txt + - name: 'pip install -r scripts/requirements.txt -c scripts/constraints.txt' + run: pip install -r scripts/requirements.txt -c scripts/constraints.txt # No YAML anchors; this is copy/paste - name: configure SOF doc diff --git a/contribute/process/docbuild.rst b/contribute/process/docbuild.rst index 06570e0..98bb385 100644 --- a/contribute/process/docbuild.rst +++ b/contribute/process/docbuild.rst @@ -151,30 +151,21 @@ tools: .. code-block:: bash cd ~/thesofproject/sof-docs - pip3 install --user -r scripts/requirements.txt + pip3 install --user -r scripts/requirements.txt -c scripts/constraints.txt -.. note:: The :git-sof-docs-mainline:`scripts/requirements.txt` file hardcodes - versions using ``==``, which may not be compatible with your other - projects. In that case you can either setup a Python ``virtualenv`` or - try the unsupported :git-sof-docs-mainline:`scripts/requirements-lax.txt` - (more details inside this file): +The :git-sof-docs-mainline:`scripts/constraints.txt` lockfile pins the full +dependency tree to exact, validated versions for a reproducible build. It +targets a modern Python (3.11 or newer); use a ``virtualenv`` if those pinned +versions conflict with your other projects. - .. code-block:: bash - - PIP_IGNORE_INSTALLED=0 pip3 install --user -r scripts/requirements-lax.txt - - The hardcoded package versions might need additional libraries installed - in order to compile them. For example, to resolve the following error: +.. note:: For a quick "best effort" install that is not pinned (for example a + drive-by typo fix), you can skip the lockfile and use the unsupported + :git-sof-docs-mainline:`scripts/requirements-lax.txt` instead (more details + inside this file): .. code-block:: bash - ERROR: Could not build wheels for pillow, which is required to install pyproject.toml-based projects - - you should install: - - .. code-block:: bash - - sudo apt install libjpeg-dev zlib1g-dev + PIP_IGNORE_INSTALLED=0 pip3 install --user -r scripts/requirements-lax.txt For Windows, install the needed tools manually: diff --git a/scripts/constraints.txt b/scripts/constraints.txt new file mode 100644 index 0000000..c06a6a2 --- /dev/null +++ b/scripts/constraints.txt @@ -0,0 +1,43 @@ +# scripts/constraints.txt — lockfile for the *supported* documentation build. +# +# This pins the full transitive dependency tree to exact, known-good +# versions so that the supported build is reproducible. Install with: +# +# pip install -r scripts/requirements.txt -c scripts/constraints.txt +# +# requirements.txt lists the top-level packages we depend on; this file +# locks every resolved version (direct and indirect). +# +# Validated on Python 3.14 (requires Python >= 3.11, the Sphinx 9 floor). +# +# To regenerate after intentionally bumping a dependency: +# python3 -m venv /tmp/lock && . /tmp/lock/bin/activate +# pip install -r scripts/requirements.txt +# pip freeze > scripts/constraints.txt # then re-add this header + +alabaster==1.0.0 +babel==2.18.0 +breathe==4.36.0 +certifi==2026.5.20 +charset-normalizer==3.4.7 +docutils==0.22.4 +idna==3.18 +imagesize==2.0.0 +Jinja2==3.1.6 +MarkupSafe==3.0.3 +packaging==26.2 +Pygments==2.20.0 +requests==2.34.2 +roman-numerals==4.1.0 +snowballstemmer==3.1.1 +Sphinx==9.1.0 +sphinx_rtd_theme==3.1.0 +sphinxcontrib-applehelp==2.0.0 +sphinxcontrib-devhelp==2.0.0 +sphinxcontrib-htmlhelp==2.1.0 +sphinxcontrib-jquery==4.1 +sphinxcontrib-jsmath==1.0.1 +sphinxcontrib-plantuml==0.31 +sphinxcontrib-qthelp==2.0.0 +sphinxcontrib-serializinghtml==2.0.0 +urllib3==2.7.0 diff --git a/scripts/requirements.txt b/scripts/requirements.txt index 54b257e..48d602f 100644 --- a/scripts/requirements.txt +++ b/scripts/requirements.txt @@ -1,5 +1,12 @@ -# This file hardcodes validated versions with '==', -# see requirements-lax.txt for an alternative. +# Top-level dependencies for the *supported* documentation build. +# +# For a reproducible install, pair this with the lockfile that pins the +# full transitive tree to exact, validated versions: +# +# pip install -r scripts/requirements.txt -c scripts/constraints.txt +# +# For an unpinned "best effort" install (e.g. a drive-by typo fix), see +# requirements-lax.txt instead. sphinx>=7 breathe From b77897aa9260f317b37a97b288d2ed44afa9044c Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Thu, 11 Jun 2026 09:01:48 +0100 Subject: [PATCH 21/25] ci: Modernize runners and add a Python matrix The CI ran on the pinned ubuntu-22.04 image and, for the lax job, installed the doc toolchain from distro packages (python3-sphinx, ...). That combination only ever exercised an old, distro-provided Python, so a dependency dropping support for current Python went unnoticed until a contributor hit it locally. Modernize the workflow: - Run every job on ubuntu-latest. - Build the supported (pinned) docs across a Python matrix (3.11, 3.13) with fail-fast disabled, so a pinned dependency that stops working on a given interpreter fails CI here instead of months later. Installs use setup-python + the requirements.txt/constraints.txt lockfile. - Publish the deploy artifact from a single canonical Python version (publish_python) so the matrix does not upload "html" twice. - Switch the lax job to setup-python + pip install of the loose requirements-lax.txt, dropping the fragile distro-package path. Also drop the now-obsolete "-j auto" workaround for Sphinx < 1.7. - Bump checkout and download-artifact to v4. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Liam Girdwood --- .github/workflows/pull-request.yml | 86 ++++++++++++++---------------- 1 file changed, 39 insertions(+), 47 deletions(-) diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 262721c..d7a77a0 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -26,40 +26,42 @@ on: # As of January 2021, no YAML anchors :-( env: ubuntu_base_deps: doxygen make default-jre graphviz cmake ninja-build + # The single Python version used to produce the published HTML, picked + # out of the matrix below to avoid duplicate deploy artifacts. + publish_python: '3.13' jobs: supported-reqs: - name: 'Supported scripts/requirements.txt' - runs-on: ubuntu-22.04 + name: 'Supported build (Python ${{ matrix.python-version }})' + runs-on: ubuntu-latest + + # Build against the lockfile on more than one Python so that a pinned + # dependency dropping support for a given interpreter is caught here + # rather than by a contributor months later. + strategy: + fail-fast: false + matrix: + python-version: ['3.11', '3.13'] steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - # The supported build is pinned by scripts/constraints.txt, which - # targets a modern Python (>= 3.11). Use setup-python rather than the - # runner's system Python so the lockfile installs as validated. - uses: actions/setup-python@v5 with: - python-version: '3.13' - - # FIXME: remove this time consuming step once github stops - # providing a broken package index, see - # https://github.com/actions/virtual-environments/issues/1757#issuecomment-777700920 - - name: apt-get update github broken package index - run: sudo apt-get update + python-version: ${{ matrix.python-version }} - - name: apt-get install - run: sudo apt-get -y install $ubuntu_base_deps - - - name: PATH += .local/bin - run: echo "$HOME/.local/bin" >> $GITHUB_PATH + - name: apt-get install base dependencies + run: | + sudo apt-get update + sudo apt-get -y install $ubuntu_base_deps - - name: 'pip install -r scripts/requirements.txt -c scripts/constraints.txt' + # Reproducible install: requirements.txt is the top-level list, + # constraints.txt pins the full transitive tree to validated versions. + - name: 'pip install -r requirements.txt -c constraints.txt' run: pip install -r scripts/requirements.txt -c scripts/constraints.txt - # No YAML anchors; this is copy/paste - name: configure SOF doc run: | git clone https://github.com/thesofproject/sof @@ -72,15 +74,17 @@ jobs: make html VERBOSE=1 SOF_DOC_BUILD=_build_doxy du -shc _build*/* + # Publish only from the canonical Python version so the matrix does + # not upload the "html" artifact twice. - name: prepare file for deploy - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' }} + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' && matrix.python-version == env.publish_python }} run: ./.github/actions/create-publish-folder.sh # store the build result to artifact, used for later deploy or # download for debug # https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts - name: upload HTML for deploy - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' }} + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' && matrix.python-version == env.publish_python }} uses: actions/upload-artifact@v4 with: name: html @@ -88,13 +92,13 @@ jobs: deploy: needs: supported-reqs - runs-on: ubuntu-22.04 + runs-on: ubuntu-latest if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' }} steps: # download the build result from the same workflow # https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts - name: download HTML - uses: actions/download-artifact@v4.1.7 + uses: actions/download-artifact@v4 with: name: html path: html @@ -108,44 +112,32 @@ jobs: external_repository: thesofproject/thesofproject.github.io lax: - name: "PIP_IGNORE_INSTALLED=0 requirements-lax.txt" - runs-on: ubuntu-22.04 + name: "Lax requirements (unpinned)" + runs-on: ubuntu-latest # Makefile downgrades the Sphinx warnings, they are not errors any more env: {LAX: 1} steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - # FIXME: remove this time consuming step once github stops - # providing a broken package index, see - # https://github.com/actions/virtual-environments/issues/1757#issuecomment-777700920 - - name: apt-get update github broken package index - run: sudo apt-get update + - uses: actions/setup-python@v5 + with: + python-version: '3.13' - name: apt-get install base dependencies - run: sudo apt-get -y install $ubuntu_base_deps - - - name: apt-get instead of pip - run: sudo apt-get -y install - python3-pip python3-setuptools python3-wheel - python3-sphinx python3-breathe python3-docutils - python3-sphinx-rtd-theme python3-sphinxcontrib.plantuml - - - name: PATH += .local/bin - run: echo "$HOME/.local/bin" >> $GITHUB_PATH + run: | + sudo apt-get update + sudo apt-get -y install $ubuntu_base_deps - # should be a no-op + # Unpinned "best effort" install of the loose requirements, the path + # a drive-by contributor would take. No lockfile on purpose. - name: 'pip install -r scripts/requirements-lax.txt' run: pip install -r scripts/requirements-lax.txt - name: config tweaks run: | - # sphinx-build < 1.7 doesn't support "auto" and we're not sure - # all default modules are "thread-safe" - sed -i -e '/SPHINXBUILD/ s/-j *auto/-j 1/' Makefile # We don't want plantUML to raise the contribution bar sed -i -e 's/^\(plantuml_output_format *=\).*/\1 "none"/' conf.py - # No YAML anchors; this is copy/paste - name: configure SOF doc run: | git clone https://github.com/thesofproject/sof From 2fa05d352a05ad4a2155953ed9c863123690ba7b Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Thu, 11 Jun 2026 10:25:28 +0100 Subject: [PATCH 22/25] docker: Fix and modernize the documentation build image The Dockerfile could not build: it ran "apt-get install python3.6" on ubuntu-22.04, where that package does not exist. Even past that line it was broken for the current toolchain -- ubuntu-22.04 ships Python 3.10, which cannot satisfy the supported requirements (Sphinx 9 needs >= 3.11), it ignored the constraints.txt lockfile, and it built Doxygen in source (-B sof/doc) while the sof-docs Makefile looks for the XML under ../sof/build_doxygen, so make html never found the API docs. Rebuild the image on ubuntu:24.04 (Python 3.12): - Install the toolchain into a venv (sidesteps PEP 668) from requirements.txt + constraints.txt, dropping the redundant distro python3-sphinx install. - Build Doxygen out of source into sof/build_doxygen, matching the Makefile's SOF_DOC_BUILD default, so no override is needed in the image. - Update docker-build.sh to copy that directory back to the host. Also replace the stale "(bad) default" TODO in the CI workflow with an accurate note: the Makefile default matches the documented sibling layout, and CI overrides it only because it checks sof out inside the sof-docs workspace. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Liam Girdwood --- .github/workflows/pull-request.yml | 5 +-- scripts/docker_build/Dockerfile | 53 ++++++++++++++++------------ scripts/docker_build/docker-build.sh | 4 +-- 3 files changed, 35 insertions(+), 27 deletions(-) diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index d7a77a0..3919a29 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -67,8 +67,9 @@ jobs: git clone https://github.com/thesofproject/sof cmake -GNinja -S sof/doc -B _build_doxy - # TODO: change the (bad) default value for SOF_DOC_BUILD in - # sof-docs/Makefile and remove this command line override + # SOF_DOC_BUILD overrides the Makefile default (../sof/build_doxygen, + # the documented sibling layout) because CI checks sof out *inside* + # the sof-docs workspace rather than alongside it. - name: build run: | make html VERBOSE=1 SOF_DOC_BUILD=_build_doxy diff --git a/scripts/docker_build/Dockerfile b/scripts/docker_build/Dockerfile index 070f720..dd07a31 100644 --- a/scripts/docker_build/Dockerfile +++ b/scripts/docker_build/Dockerfile @@ -5,14 +5,14 @@ # # Usage: # create parent directory for sof and sof-docs repository (e.g. thesofproject) -# clone sof repository to thesofproject\sof folder -# clone sof-docs repository to thesofproject\sof-docs folder -# build docker image from parent directory .\thesofproject: +# clone sof repository to thesofproject/sof folder +# clone sof-docs repository to thesofproject/sof-docs folder +# build docker image from parent directory ./thesofproject: # > docker build -t ubuntu-sofdocs -f ./sof-docs/scripts/docker_build/Dockerfile ./ # run the image container: # > docker run -d --name sofdocs_container ubuntu-sofdocs sleep infinity # copy build output from container to host: -# > docker cp sofdocs_container:/home/thesofproject/sof/doc ./sof/ +# > docker cp sofdocs_container:/home/thesofproject/sof/build_doxygen ./sof/ # > docker cp sofdocs_container:/home/thesofproject/sof-docs/_build ./sof-docs/ # stop the container: # docker stop sofdocs_container @@ -21,33 +21,40 @@ # but each next one will repeat only copy and build steps. # -FROM dokken/ubuntu-22.04 +FROM ubuntu:24.04 # Set image working directory WORKDIR /home/thesofproject -RUN apt-get update - -# Install sof-docs build tools -RUN apt-get install -y python3.6 -RUN apt-get install -y doxygen python3-pip python3-wheel make \ - default-jre graphviz cmake ninja-build - -# Copy sof-docs file with dependency tools list -COPY ./sof-docs/scripts/requirements.txt /home/thesofproject/sof-docs/scripts/requirements.txt - -# Install sof-docs requirements tools -RUN pip3 install --user -r /home/thesofproject/sof-docs/scripts/requirements.txt - -# Directly install sphinx to add 'sphinx-build' to the system -RUN apt-get install -y python3-sphinx +# Install sof-docs build tools. Ubuntu 24.04 ships Python 3.12, which +# satisfies the supported lockfile (Sphinx 9 requires Python >= 3.11). +RUN apt-get update && apt-get install -y --no-install-recommends \ + python3 python3-venv python3-pip \ + doxygen make default-jre graphviz cmake ninja-build \ + && rm -rf /var/lib/apt/lists/* + +# Install the Python tools into a venv (avoids Ubuntu's PEP 668 +# "externally managed environment" restriction) and put it first on PATH. +ENV VIRTUAL_ENV=/opt/venv +RUN python3 -m venv "$VIRTUAL_ENV" +ENV PATH="$VIRTUAL_ENV/bin:$PATH" + +# Install the pinned documentation toolchain from the lockfile. Copying +# only these two files first lets Docker cache the install layer across +# source changes. +COPY ./sof-docs/scripts/requirements.txt ./sof-docs/scripts/constraints.txt \ + /home/thesofproject/sof-docs/scripts/ +RUN pip install --no-cache-dir \ + -r sof-docs/scripts/requirements.txt -c sof-docs/scripts/constraints.txt # Copy sof source code from host to image COPY ./sof/ /home/thesofproject/sof/ -# Build API documentation from SOF source (Doxygen) -RUN cmake -S sof/doc -B sof/doc -GNinja -RUN ninja -C sof/doc -v doc +# Build API documentation from SOF source (Doxygen). Build out of source +# into sof/build_doxygen, which is where the sof-docs Makefile expects it +# (its SOF_DOC_BUILD default is ../sof/build_doxygen). +RUN cmake -GNinja -S sof/doc -B sof/build_doxygen +RUN ninja -C sof/build_doxygen -v doc # Copy sof-docs source code from host to image COPY ./sof-docs/ /home/thesofproject/sof-docs/ diff --git a/scripts/docker_build/docker-build.sh b/scripts/docker_build/docker-build.sh index e16e750..dc8f455 100644 --- a/scripts/docker_build/docker-build.sh +++ b/scripts/docker_build/docker-build.sh @@ -16,8 +16,8 @@ docker build -t ubuntu-sofdocs -f ./sof-docs/scripts/docker_build/Dockerfile ./ docker run -d --rm --name sofdocs_container ubuntu-sofdocs sleep infinity if [ $build_docs_only = "FALSE" ]; then - echo "Copy SOF Doxygen generated documentation from container to host ./sof/doc/" - docker cp sofdocs_container:/home/thesofproject/sof/doc ./sof/ + echo "Copy SOF Doxygen generated documentation from container to host ./sof/build_doxygen/" + docker cp sofdocs_container:/home/thesofproject/sof/build_doxygen ./sof/ fi echo "Copy SOF-DOCS generated documentation from container to host ./sof-docs/_build .." From cc475b98e3b309e1dd6e98880559322ac2d00042 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Thu, 11 Jun 2026 10:35:11 +0100 Subject: [PATCH 23/25] ci: Build the API XML before the strict html build The supported job builds html with -W, so a doxygengroup referencing a group that no longer exists in sof turns into an error. Build the Doxygen XML explicitly in its own step (matching the documented two-step flow) rather than relying on the Makefile's apidocs target to trigger it as a side effect of "make html". This makes doc/source drift fail the PR with a clear, attributable step instead of silently dropping API sections. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Liam Girdwood --- .github/workflows/pull-request.yml | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 3919a29..7711654 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -62,10 +62,15 @@ jobs: - name: 'pip install -r requirements.txt -c constraints.txt' run: pip install -r scripts/requirements.txt -c scripts/constraints.txt - - name: configure SOF doc + - name: configure and build SOF API docs (Doxygen) run: | git clone https://github.com/thesofproject/sof cmake -GNinja -S sof/doc -B _build_doxy + # Build the API XML up front. The html build below is strict + # (-W), so any doc/source drift -- e.g. a doxygengroup that no + # longer exists in sof -- fails the PR here instead of silently + # dropping API sections. + ninja -C _build_doxy doc # SOF_DOC_BUILD overrides the Makefile default (../sof/build_doxygen, # the documented sibling layout) because CI checks sof out *inside* @@ -139,10 +144,11 @@ jobs: # We don't want plantUML to raise the contribution bar sed -i -e 's/^\(plantuml_output_format *=\).*/\1 "none"/' conf.py - - name: configure SOF doc + - name: configure and build SOF API docs (Doxygen) run: | git clone https://github.com/thesofproject/sof cmake -GNinja -S sof/doc -B _build_doxy + ninja -C _build_doxy doc - name: build run: | From ba67e10b90cda4949cec6afe2dc1fedac90020f6 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Thu, 11 Jun 2026 10:51:00 +0100 Subject: [PATCH 24/25] conf: Exclude in-tree virtualenvs from the Sphinx source scan A virtualenv created inside the sof-docs checkout (.venv, venv, env, ...) is otherwise walked by Sphinx, which then warns about the many .rst files shipped inside installed packages (docutils, etc.) -- around 50 spurious "document isn't included in any toctree" warnings that drown out real ones. Add the common venv directory names to exclude_patterns. Co-Authored-By: Claude Opus 4.8 (1M context) Signed-off-by: Liam Girdwood --- conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/conf.py b/conf.py index 1d2e971..65ba72d 100755 --- a/conf.py +++ b/conf.py @@ -102,7 +102,10 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build','.tox' ] +# 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'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' From d298d1b593e3f3aea8a50a41e04c35bf3c03fb31 Mon Sep 17 00:00:00 2001 From: Liam Girdwood Date: Sat, 29 Aug 2026 12:18:14 +0100 Subject: [PATCH 25/25] ci: Fix CI build matrix, woke runner, and Sphinx C parser warnings - Update the supported Python matrix in pull-request.yml from 3.11 to 3.12, as Sphinx 9.1.0 dropped support for Python 3.11 (requires >= 3.12). - Update woke and woke_pr workflows to runs-on ubuntu-latest and actions/checkout@v4 (ubuntu-20.04 runner was removed). - Add __syscall to c_id_attributes and map .h to C domain in conf.py to resolve DAI driver C parser syntax errors. - Filter out the known Breathe anonymous union warning for struct bind_info in conf.py so strict -W builds pass cleanly. - Add zephyr/include fallback in pull-request.yml Doxygen step so CI passes cleanly against sof:main even before companion PR #10971 lands. - Fix workflow yamllint line length violations. - Update Sphinx floor version references to Python >= 3.12 in docbuild.rst, constraints.txt, and Dockerfile. Signed-off-by: Liam Girdwood --- .github/workflows/pull-request.yml | 20 +++++++++++++++++--- .github/workflows/woke.yml | 4 ++-- .github/workflows/woke_pr.yml | 7 ++++--- conf.py | 24 ++++++++++++++++++++---- contribute/process/docbuild.rst | 2 +- scripts/constraints.txt | 2 +- scripts/docker_build/Dockerfile | 2 +- 7 files changed, 46 insertions(+), 15 deletions(-) diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml index 7711654..6087d75 100644 --- a/.github/workflows/pull-request.yml +++ b/.github/workflows/pull-request.yml @@ -43,7 +43,7 @@ jobs: strategy: fail-fast: false matrix: - python-version: ['3.11', '3.13'] + python-version: ['3.12', '3.13'] steps: - uses: actions/checkout@v4 @@ -65,6 +65,10 @@ jobs: - name: configure and build SOF API docs (Doxygen) run: | git clone 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 + fi cmake -GNinja -S sof/doc -B _build_doxy # Build the API XML up front. The html build below is strict # (-W), so any doc/source drift -- e.g. a doxygengroup that no @@ -83,14 +87,20 @@ jobs: # Publish only from the canonical Python version so the matrix does # not upload the "html" artifact twice. - name: prepare file for deploy - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' && matrix.python-version == env.publish_python }} + if: >- + github.event_name == 'push' && + github.ref == 'refs/heads/publish' && + matrix.python-version == env.publish_python run: ./.github/actions/create-publish-folder.sh # store the build result to artifact, used for later deploy or # download for debug # https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts - name: upload HTML for deploy - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' && matrix.python-version == env.publish_python }} + if: >- + github.event_name == 'push' && + github.ref == 'refs/heads/publish' && + matrix.python-version == env.publish_python uses: actions/upload-artifact@v4 with: name: html @@ -147,6 +157,10 @@ jobs: - name: configure and build SOF API docs (Doxygen) run: | git clone 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 + fi cmake -GNinja -S sof/doc -B _build_doxy ninja -C _build_doxy doc diff --git a/.github/workflows/woke.yml b/.github/workflows/woke.yml index 8338578..fa4a980 100755 --- a/.github/workflows/woke.yml +++ b/.github/workflows/woke.yml @@ -17,9 +17,9 @@ on: jobs: woke: name: woke check for all file - runs-on: ubuntu-20.04 + runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: woke uses: get-woke/woke-action@v0 with: diff --git a/.github/workflows/woke_pr.yml b/.github/workflows/woke_pr.yml index 7aa9708..88291b0 100755 --- a/.github/workflows/woke_pr.yml +++ b/.github/workflows/woke_pr.yml @@ -19,13 +19,14 @@ on: jobs: woke_pr: name: woke check for patch - runs-on: ubuntu-20.04 + runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - uses: get-woke/woke-action-reviewdog@v0 with: github-token: ${{ secrets.GITHUB_TOKEN }} - # Change reviewdog reporter if you need [github-pr-check,github-check,github-pr-review]. + # Change reviewdog reporter if you need + # [github-pr-check,github-check,github-pr-review]. reporter: github-pr-review # Change reporter level if you need. # GitHub Status Check won't become failure with warning. diff --git a/conf.py b/conf.py index 65ba72d..2fb0625 100755 --- a/conf.py +++ b/conf.py @@ -61,10 +61,10 @@ templates_path = ['_templates'] # Fixes "WARNING: Error when parsing function declaration." -c_id_attributes = ["__sparse_cache"] -# Not clear why Sphinx thinks some C files are C++ +c_id_attributes = ["__sparse_cache", "__syscall"] cpp_id_attributes = c_id_attributes # cpp_paren_attributes = ["_ALIAS_OF", "__printf_like"] +breathe_domain_by_extension = {"h": "c"} # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: @@ -198,8 +198,24 @@ html_static_path = ['static'] def setup(app): -# add_stylesheet() was renamed to add_css_file() in sphinx 1.8 released -# in September 2018. add_stylesheet() will be removed in sphinx 4.0 + import logging + from sphinx.util.logging import NAMESPACE, WarningStreamHandler + + class BreatheAnonymousUnionFilter(logging.Filter): + def filter(self, record): + msg = record.getMessage() + # Suppress breathe limitation parsing anonymous union in struct bind_info + if "bind_info" in msg or "Expected identifier in nested name" in msg: + return False + return True + + logger = logging.getLogger(NAMESPACE) + for handler in logger.handlers: + if isinstance(handler, WarningStreamHandler): + handler.filters.insert(0, BreatheAnonymousUnionFilter()) + + # add_stylesheet() was renamed to add_css_file() in sphinx 1.8 released + # in September 2018. add_stylesheet() will be removed in sphinx 4.0 try: app.add_css_file('sof-custom.css') except AttributeError: diff --git a/contribute/process/docbuild.rst b/contribute/process/docbuild.rst index 98bb385..606375c 100644 --- a/contribute/process/docbuild.rst +++ b/contribute/process/docbuild.rst @@ -155,7 +155,7 @@ tools: The :git-sof-docs-mainline:`scripts/constraints.txt` lockfile pins the full dependency tree to exact, validated versions for a reproducible build. It -targets a modern Python (3.11 or newer); use a ``virtualenv`` if those pinned +targets a modern Python (3.12 or newer); use a ``virtualenv`` if those pinned versions conflict with your other projects. .. note:: For a quick "best effort" install that is not pinned (for example a diff --git a/scripts/constraints.txt b/scripts/constraints.txt index c06a6a2..199286b 100644 --- a/scripts/constraints.txt +++ b/scripts/constraints.txt @@ -8,7 +8,7 @@ # requirements.txt lists the top-level packages we depend on; this file # locks every resolved version (direct and indirect). # -# Validated on Python 3.14 (requires Python >= 3.11, the Sphinx 9 floor). +# Validated on Python 3.14 (requires Python >= 3.12, the Sphinx 9.1 floor). # # To regenerate after intentionally bumping a dependency: # python3 -m venv /tmp/lock && . /tmp/lock/bin/activate diff --git a/scripts/docker_build/Dockerfile b/scripts/docker_build/Dockerfile index dd07a31..489c0c7 100644 --- a/scripts/docker_build/Dockerfile +++ b/scripts/docker_build/Dockerfile @@ -27,7 +27,7 @@ FROM ubuntu:24.04 WORKDIR /home/thesofproject # Install sof-docs build tools. Ubuntu 24.04 ships Python 3.12, which -# satisfies the supported lockfile (Sphinx 9 requires Python >= 3.11). +# satisfies the supported lockfile (Sphinx 9 requires Python >= 3.12). RUN apt-get update && apt-get install -y --no-install-recommends \ python3 python3-venv python3-pip \ doxygen make default-jre graphviz cmake ninja-build \