diff --git a/Makefile b/Makefile index d8381b1e..24b84eb2 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,13 @@ else Q = @ endif -SOF_DOC_BUILD = ../sof/build_doxygen/ +# Locate SOF firmware repository: check SOF_ROOT, or candidate directories +ifeq ($(SOF_ROOT),) + SOF_ROOT := $(firstword $(wildcard ../sof-dox-work ../sof ../sof-tgl/sof /home/lrg/work/sof-dox-work)) +endif +SOF_DOC_BUILD ?= $(if $(SOF_ROOT),$(SOF_ROOT)/build_doxygen,_build_doxygen) +SOF_HAS_DOC := $(wildcard $(SOF_ROOT)/doc/CMakeLists.txt) + SPHINXBUILD = sphinx-build SPHINXPROJ = "SOF Project" SOURCEDIR = . @@ -34,21 +40,19 @@ help: .PHONY: help apidocs html clean -# Generate the doxygen xml (for Sphinx) and copy the doxygen html to the -# api folder for publishing along with the Sphinx-generated API docs. -# Keep doxygen optional not to burden "drive-by" .rst contributors with -# extra dependencies. - -APIS_CMAKE := ${SOF_DOC_BUILD}/build.ninja +# Generate the doxygen xml (for Sphinx Breathe) and copy the doxygen html +# for publishing along with the Sphinx-generated API docs. apidocs: -ifeq (${APIS_CMAKE},$(wildcard ${APIS_CMAKE})) - ninja -C ${SOF_DOC_BUILD} $${VERBOSE:+-v} doc +ifneq ($(SOF_HAS_DOC),) + @if [ ! -f "$(SOF_DOC_BUILD)/build.ninja" ]; then \ + echo "Configuring Doxygen build with CMake in $(SOF_DOC_BUILD)..."; \ + cmake -GNinja -S "$(SOF_ROOT)/doc" -B "$(SOF_DOC_BUILD)"; \ + fi + @echo "Building Doxygen documentation in $(SOF_DOC_BUILD)..." + ninja -C "$(SOF_DOC_BUILD)" $${VERBOSE:+-v} doc else - # To include doxygen APIs run this first: - # cmake -GNinja -S ../sof/doc -B ${SOF_DOC_BUILD} - # Note this will make the build CONSIDERABLY LONGER! - # Conversely, you can have _instant builds from scratch_ - # by disabling UML diagrams in the conf.py file. + @echo "Note: SOF firmware source tree (doc/CMakeLists.txt) not found." + @echo " Specify SOF_ROOT=/path/to/sof to generate live C API documentation." endif PYTHON ?= python3 @@ -58,9 +62,14 @@ generate_data: html: generate_data apidocs $(SPHINXBUILD) -j auto -t $(DOC_TAG) -b html \ --d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) \ --D breathe_projects.'SOF Project'="${SOF_DOC_BUILD}"/doxygen/xml \ -$(ERROROPTS) $(O) + -d $(BUILDDIR)/doctrees $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) \ + $(if $(wildcard $(SOF_DOC_BUILD)/doxygen/xml),-D breathe_projects.'SOF Project'="$(abspath $(SOF_DOC_BUILD)/doxygen/xml)",) \ + $(ERROROPTS) $(O) + @if [ -d "$(SOF_DOC_BUILD)/doxygen/html" ]; then \ + echo "Copying raw Doxygen HTML to $(BUILDDIR)/html/doxygen..."; \ + mkdir -p $(BUILDDIR)/html/doxygen; \ + cp -r $(SOF_DOC_BUILD)/doxygen/html/* $(BUILDDIR)/html/doxygen/; \ + fi # Reminder: to see _all_ warnings you must "make clean" first. @@ -68,8 +77,10 @@ $(ERROROPTS) $(O) clean: rm -fr $(BUILDDIR) -ifeq (${APIS_CMAKE},$(wildcard ${APIS_CMAKE})) - ninja -C ${SOF_DOC_BUILD} $${VERBOSE:+-v} doc-clean clean +ifneq ($(SOF_HAS_DOC),) + @if [ -f "$(SOF_DOC_BUILD)/build.ninja" ]; then \ + ninja -C "$(SOF_DOC_BUILD)" $${VERBOSE:+-v} doc-clean clean; \ + fi endif # Copy material over to the GitHub pages staging repo diff --git a/README.md b/README.md index c6cb3164..ee886925 100644 --- a/README.md +++ b/README.md @@ -5,4 +5,4 @@ SOF Project documentation web site published to https://thesofproject.github.io Learn how to setup and generate documentation by reading -https://thesofproject.github.io/latest/contribute/process/docbuild.html +https://thesofproject.github.io/latest/contribute/index.html#building-publishing-documentation diff --git a/algos/index.rst b/algos/index.rst index db12fed6..db132e9e 100644 --- a/algos/index.rst +++ b/algos/index.rst @@ -6,9 +6,14 @@ Algorithms Supplied Processing Algorithms ****************************** -SOF contains several permissively-licensed and royalty-free audio processing -algorithms that can be used alongside proprietary processing components to -build pipelines. +SOF provides an extensive ecosystem of permissively-licensed and royalty-free audio processing +algorithms that can be used alongside proprietary processing components to build production audio pipelines. + +In addition to upstream native algorithms, license-compatible open-source algorithms from external projects +(such as FFmpeg, WebRTC, Valve Steam Audio, CMSIS-DSP, and vendor DSP libraries) can be compiled as dynamically +loadable modules (e.g. Zephyr LLEXT / ELF modules) and linked at runtime into active audio pipelines. This +modular architecture allows open-source, vendor, and proprietary intellectual property (IP) components to be safely +integrated into the same pipeline graph without license contamination or monolithic recompilation. .. include:: _generated_modules_table.rst diff --git a/api/audio-stream-api.rst b/api/audio-stream-api.rst deleted file mode 100644 index b95f86af..00000000 --- a/api/audio-stream-api.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _audio-stream-api: - -Audio Stream API -################ - -Location: *include/sof/audio/audio_stream.h* - -.. doxygengroup:: audio_stream_api - :project: SOF Project diff --git a/api/component-api.rst b/api/component-api.rst deleted file mode 100644 index 81802014..00000000 --- a/api/component-api.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. _component-api: - -Component API -############# - -This section is intended for all component developers. It documents the basic -component driver and component device API that must be implemented by every -component. It also documents functions that are commonly used by effects -components, or blocks inserted in the middle of the pipeline to process -enhance the audio signal. - -Another :ref:`component-ext-api` section documents macros and functions that -are used by the infrastructure and specialized components like host, dai, -and kpb. - -Location: *include/sof/audio/component.h* - -.. doxygengroup:: component_api - :project: SOF Project - -.. doxygengroup:: component_common_int - :project: SOF Project diff --git a/api/component-ext-api.rst b/api/component-ext-api.rst deleted file mode 100644 index 4b16b170..00000000 --- a/api/component-ext-api.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _component-ext-api: - -Component API Ext -################# - -Location: *include/sof/audio/component_ext.h* - -.. doxygengroup:: component_api_helpers - :project: SOF Project diff --git a/api/dai-drivers-api.rst b/api/dai-drivers-api.rst deleted file mode 100644 index 5b662000..00000000 --- a/api/dai-drivers-api.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _dai-drivers-api: - -DAI Drivers API -############### - -.. doxygengroup:: sof_dai_drivers - :project: SOF Project diff --git a/api/dma-drivers-api.rst b/api/dma-drivers-api.rst deleted file mode 100644 index af3ca063..00000000 --- a/api/dma-drivers-api.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _dma-drivers-api: - -DMA Drivers API -############### - -.. doxygengroup:: sof_dma_drivers - :project: SOF Project - -.. - Keep 'sof_dma_copy_func' after 'sof_dma_drivers' so most dma_copy - links (correctly) point to the struct and not to the func. This also - avoids the 'WARNING: Duplicate declaration, dma_copy' for some - unclear reason. - -.. doxygengroup:: sof_dma_copy_func - :project: SOF Project - -This function is listed separately to solve a name clash with the struct -dma_copy {} above. diff --git a/api/index.rst b/api/index.rst index ec11d4d7..b23c6ae8 100644 --- a/api/index.rst +++ b/api/index.rst @@ -1,18 +1,62 @@ .. _api: +.. _uuid-api: API Documentation ################# -.. toctree:: - :maxdepth: 1 - - uuid-api - dma-drivers-api - dai-drivers-api - pm-runtime-api - platform-api - memory-alloc-api - audio-stream-api - component-api - component-ext-api - uapi +The Sound Open Firmware (SOF) C application programming interface (API) documentation +is generated directly from the firmware source code comments and header files using +Doxygen. This ensures that the documentation is always synchronized with the actual +implementation across all supported audio components, pipeline infrastructure, +hardware abstraction layers, and IPC protocols. + +.. raw:: html + +
+

Sound Open Firmware Doxygen API Documentation

+

+ Browse the complete, interactive C API reference generated directly from the SOF firmware codebase, including data structures, function declarations, macros, enumerations, file hierarchies, and dependency call graphs. +

+ + Open Doxygen API Reference → + +
+ +Overview of Documented Modules +****************************** + +The Doxygen documentation covers the entire public firmware and host-shared interface: + +* **Audio Components & Pipelines**: + Core component driver lifecycle (``component.h``), component extensions and buffer helpers (``component_ext.h``), and PCM stream buffer utilities (``audio_stream.h``). + +* **Hardware Drivers & Interfaces**: + Direct Memory Access (``dma.h``), Digital Audio Interfaces for I2S/SSP, SoundWire/ALH, DMIC/PDM, and HDA (``dai.h``), Power Management runtime (``pm_runtime.h``), and platform hardware timers and interrupt controllers (``platform.h``). + +* **Core RTOS & System Services**: + Real-time task scheduling (EDF, LL-Timer, LL-DMA, Zephyr DataProcessing threads in ``schedule.h``), memory allocation heaps (``alloc.h``), and component/pipeline UUID declarations (``uuid.h``). + +* **IPC & Host Interfaces**: + User/Kernel IPC ABI protocols and messaging envelopes (``ipc/header.h``, ``ipc/control.h``), and SRAM Window 0 firmware status registers and telemetry offsets (``kernel/mailbox.h``). + +* **Source Code Graphs & File Browsing**: + Full source file tree, header include dependency graphs, and function call/caller graphs. + +Building API Documentation Locally +********************************** + +To build or refresh the Doxygen documentation alongside the Sphinx documentation: + +.. code-block:: bash + + # From the sof-docs repository root + make apidocs # Generates Doxygen XML and HTML + make html # Generates Sphinx site and stages Doxygen at _build/html/doxygen/ + +Alternatively, Doxygen can be built directly inside the SOF firmware repository: + +.. code-block:: bash + + # From the sof firmware repository root + cmake -GNinja -S doc -B build_doxygen + ninja -C build_doxygen doc diff --git a/api/memory-alloc-api.rst b/api/memory-alloc-api.rst deleted file mode 100644 index 05da3a6c..00000000 --- a/api/memory-alloc-api.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _memory-alloc-api: - -Memory Allocation API -##################### - -Location: *include/sof/lib/alloc.h* - -.. doxygengroup:: alloc_api - :project: SOF Project diff --git a/api/platform-api.rst b/api/platform-api.rst deleted file mode 100644 index e103df9d..00000000 --- a/api/platform-api.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _platform-api: - -Platform API -############### - -Location: *include/sof/platform.h* - -.. doxygengroup:: platform_api - :project: SOF Project diff --git a/api/pm-runtime-api.rst b/api/pm-runtime-api.rst deleted file mode 100644 index 7a4d7772..00000000 --- a/api/pm-runtime-api.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _pm-runtime-api: - -PM Runtime API -############## - -.. doxygengroup:: pm_runtime - :project: SOF Project diff --git a/api/uapi.rst b/api/uapi.rst deleted file mode 100644 index 00a8b304..00000000 --- a/api/uapi.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. _api-uapi: - -uAPI -#### - -.. doxygengroup:: sof_uapi - :project: SOF Project diff --git a/api/uuid-api.rst b/api/uuid-api.rst deleted file mode 100644 index eee5911c..00000000 --- a/api/uuid-api.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _uuid-api: - -UUID API -######## - -Location: *include/sof/lib/uuid.h* - -.. doxygengroup:: uuid_api - :project: SOF Project diff --git a/conf.py b/conf.py index 14652328..5022cfe4 100755 --- a/conf.py +++ b/conf.py @@ -78,7 +78,7 @@ templates_path = ['_templates'] # Fixes "WARNING: Error when parsing function declaration." -c_id_attributes = ["__sparse_cache", "__syscall"] +c_id_attributes = ["__sparse_cache", "__syscall", "__packed", "__aligned", "__kernel", "__user", "__section"] cpp_id_attributes = c_id_attributes # cpp_paren_attributes = ["_ALIAS_OF", "__printf_like"] breathe_domain_by_extension = {"h": "c"} @@ -294,8 +294,24 @@ def filter(self, record): """ +# Look for Doxygen XML path if not already provided or overridden +_breathe_xml_candidates = [ + os.path.join(os.environ['SOF_DOC_BUILD'], 'doxygen/xml') if os.environ.get('SOF_DOC_BUILD') else None, + os.path.join(os.environ['SOF_ROOT'], 'build_doxygen/doxygen/xml') if os.environ.get('SOF_ROOT') else None, + os.path.abspath('../sof-dox-work/build_doxygen/doxygen/xml'), + os.path.abspath('../sof/build_doxygen/doxygen/xml'), + os.path.abspath('../sof-tgl/sof/build_doxygen/doxygen/xml'), + os.path.abspath('../sof/doc/doxygen/xml'), +] + +_breathe_xml_path = None +for _cand in _breathe_xml_candidates: + if _cand and os.path.isdir(_cand): + _breathe_xml_path = _cand + break + breathe_projects = { - "SOF Project" : "../sof/doc/doxygen/xml", + "SOF Project" : _breathe_xml_path or "../sof/doc/doxygen/xml", } breathe_default_project = "SOF Project" breathe_default_members = ('members', 'undoc-members', 'content-only') diff --git a/contribute/contribute_guidelines.rst b/contribute/contribute_guidelines.rst deleted file mode 100644 index 6b3bdfa0..00000000 --- a/contribute/contribute_guidelines.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. _contribute_guidelines: - -Contribution Guidelines -####################### - -As an open-source project, we welcome and encourage the community to -submit patches directly to the SOF project. In our collaborative open -source environment, standards and methods for submitting changes help -reduce the chaos that can result from an active development community. - -This document explains how to participate in project conversations, log -and track bugs and enhancement requests, and submit patches to the -project so your patch will be accepted quickly in the codebase. - -Licensing -********* - -Licensing is very important to open source projects. It helps ensure the -software continues to be available under the terms that the author -desired. - -The SOF project uses a BSD-3-Clause license, as found in the -:git-sof-mainline:`LICENCE` file in the project's GitHub repo. - -A license tells you what rights you have as a developer, as provided by -the copyright holder. It is important that the contributor fully -understands the licensing rights and agrees to them. Sometimes the -copyright holder isn't the contributor, such as when the contributor is -doing work on behalf of a company. - -.. _DCO: - -Developer Certification of Origin (DCO) -*************************************** - -To make a good faith effort to ensure licensing criteria are met, -project SOF requires the Developer Certificate of Origin (DCO) process -to be followed. - -The DCO is an attestation attached to every contribution made by every -developer. In the commit message of the contribution, (described more -fully later in this document), the developer simply adds a -``Signed-off-by`` statement and thereby agrees to the DCO. - -When a developer submits a patch, it is a commitment that the -contributor has the right to submit the patch per the license. The DCO -agreement is shown below and at http://developercertificate.org/. - -.. code-block:: none - - Developer's Certificate of Origin 1.1 - - By making a contribution to this project, I certify that: - - (a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - - (b) The contribution is based upon previous work that, to the - best of my knowledge, is covered under an appropriate open - source license and I have the right under that license to - submit that work with modifications, whether created in whole - or in part by me, under the same open source license (unless - I am permitted to submit under a different license), as - Indicated in the file; or - - (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including - all personal information I submit with it, including my - sign-off) is maintained indefinitely and may be redistributed - consistent with this project or the open source license(s) - involved. - -DCO Sign-Off Methods -==================== - -The DCO requires that a sign-off message, in the following format, -appears on each commit in the pull request:: - - Signed-off-by: Sofforus Jones - -The DCO text can either be manually added to your commit body, or you can add -either ``-s`` or ``--signoff`` to your usual Git commit commands. If you forget -to add the sign-off, you can also amend a previous commit with the sign-off by -running ``git commit --amend -s``. If you have already pushed your changes to GitHub, you will need to force push your branch after this with ``git push -f``. - -.. note:: - The name and email address of the account you use to submit your PR must - match the name and email address on the ``Signed-off-by`` line in - your commit message. - -Prerequisites -************* - -.. _SOF project website: https://sofproject.org - -As a contributor, familiarize yourself with the SOF project, how to -configure, install, and use it as explained on the -`SOF project website`_, and how to set up your development environment -as introduced in the project's :ref:`getting_started`. - -You should be familiar with common developer tools such as Git and -platforms such as GitHub. - -If you have not already done so, create a (free) GitHub account -on https://github.com and have Git tools available on your development system. - - diff --git a/contribute/doc_guidelines.rst b/contribute/doc_guidelines.rst deleted file mode 100644 index caee341b..00000000 --- a/contribute/doc_guidelines.rst +++ /dev/null @@ -1,396 +0,0 @@ -.. _doc_guidelines: - -Documentation Guidelines -######################## - -The SOF project content is written using the `reStructuredText`_ markup -language (``.rst`` file extension) with Sphinx extensions, and processed -using Sphinx to create a formatted standalone website. Developers can -view this content either in its raw form as ``.rst`` markup files, or (with -Sphinx installed) they can build the documentation using the Makefile -(on Linux systems) to -generate the HTML content. The HTML content can then be viewed using a -web browser. This same ``.rst`` content is also fed into the -`SOF Project documentation`_ website. - -You can read details about `reStructuredText`_ -and about `Sphinx extensions`_ from their respective websites. - -.. _Sphinx extensions: http://www.sphinx-doc.org/en/stable/contents.html -.. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html -.. _Sphinx Inline Markup: http://sphinx-doc.org/markup/inline.html#inline-markup -.. _SOF Project documentation: http://thesofproject.github.io - -This document provides a quick reference for commonly used reST and -Sphinx-defined directives and roles used to create the documentation -you're reading. - -Headings -******** - -Document sections are identified through their heading titles, -indicated with an underline below the title text. (While reST allows -use of both and overline and matching underline to indicate a heading, -we only use an underline indicator for headings.) For consistency in -our documentation, we define the order of characters used to indicated -the nested table of contents levels: - -* Use ``#`` for the Document title underline character -* Use ``*`` for the First sub-section heading level -* Use ``=`` for the Second sub-section heading level -* Use ``-`` for the Third sub-section heading level - -Additional heading level depth is discouraged. - -The heading underline must be at least as long as the title it's under. - -Here's an example of nested heading levels and the appropriate -underlines to use: - -.. code-block:: rest - - Document Title heading - ###################### - - Section 1.0 heading - ******************* - - Section 2.0 heading - ******************* - - Section 2.1 heading - =================== - - Section 2.1.1 heading - --------------------- - - Section 2.2 heading - =================== - - Section 3.0 heading - ******************* - - - -Content Highlighting -******************** - -Some common reST inline markup samples: - -* one asterisk: ``*text*`` for emphasis (*italics*), -* two asterisks: ``**text**`` for strong emphasis (**boldface**), and -* two backquotes: ````text```` for ``inline code`` samples. - -ReST rules for inline markup try to be forgiving to account for common -cases of using these marks. For example using an asterisk to indicate -multiplication, such as ``2 * (x + y)`` will not be interpreted as an -unterminated italics section. For inline markup, the characters between -the beginning and ending characters must not start or end with a space, -so ``*this is italics*`` ( *this is italics*) while ``* this isn't*`` -(* this isn't*). - -If asterisks or backquotes appear in running text and could be confused with -inline markup delimiters, you can eliminate the confusion by adding a -backslash (``\``) before it. - -Lists -***** - -For bullet lists, place an asterisk (``*``) or hyphen (``-``) at -the start of a paragraph and indent continuation lines with two -spaces. - -The first item in a list (or sublist) must have a blank line before it -and should be indented at the same level as the preceding paragraph -(and not indented itself). - -For numbered lists -start with a ``1.`` or ``a)`` for example, and continue with autonumbering by -using a ``#`` sign and a ``.`` or ``)`` as used in the first list item. -Indent continuation lines with spaces to align with the text of first -list item: - -.. code-block:: rest - - * This is a bulleted list. - * It has two items, the second - item and has more than one line of reST text. Additional lines - are indented to the first character of the - text of the bullet list. - - 1. This is a new numbered list. If there wasn't a blank line before it, - it would be a continuation of the previous list (or paragraph). - #. It has two items too. - - a) This is a numbered list using alphabetic list headings - #) It has three items (and uses autonumbering for the rest of the list) - #) Here's the third item. Use consistent punctuation on the list - number. - - #. This is an autonumbered list (default is to use numbers starting - with 1). - - #. This is a second-level list under the first item (also - autonumbered). Notice the indenting. - #. And a second item in the nested list. - #. And a second item back in the containing list. No blank line - needed, but it wouldn't hurt for readability. - -Definition lists (with a term and its definition) are a convenient way -to document a word or phrase with an explanation. For example this reST -content: - -.. code-block:: rest - - The Makefile has targets that include: - - html - Build the HTML output for the project - - clean - Remove all generated output, restoring the folders to a - clean state. - -Would be rendered as: - - The Makefile has targets that include: - - html - Build the HTML output for the project - - clean - Remove all generated output, restoring the folders to a - clean state. - -Multi-column lists -****************** - -If you have a long bullet list of items, where each item is short, -you can indicate the list items should be rendered in multiple columns -with a special ``hlist`` directive: - -.. code-block:: rest - - .. hlist:: - :columns: 3 - - * A list of - * short items - * that should be - * displayed - * horizontally - * so it doesn't - * use up so much - * space on - * the page - -This would be rendered as: - -.. hlist:: - :columns: 3 - - * A list of - * short items - * that should be - * displayed - * horizontally - * so it doesn't - * use up so much - * space on - * the page - -Note the optional ``:columns:`` parameter (default is two columns), and -all the list items are indented by three spaces. - -File names and Commands -*********************** - -Sphinx extends reST by supporting additional inline markup elements (called -"roles") used to tag text with special -meanings and allow style output formatting. (You can refer to the `Sphinx Inline Markup`_ -documentation for the full list). - -For example, there are roles for marking :file:`filenames` -(``:file:`name```) and command names such as :command:`make` -(``:command:`make```). You can also use the \`\`inline code\`\` -markup (double backticks) to indicate a ``filename``. - -Don't use items within a single backtick, for example ```word```. - -.. _internal-linking: - -Internal Cross-Reference Linking -******************************** - -ReST links are only supported within the current file using the -notation: - -.. code-block:: rest - - refer to the `internal-linking`_ page - -which renders as, - - refer to the `internal-linking`_ page - -Note the use of a trailing -underscore to indicate an outbound link. In this example, the label was -added immediately before a heading, so the text that's displayed is the -heading text itself. - -With Sphinx however, we can create -link-references to any tagged text within the project documentation. - -Target locations within documents are defined with a label directive: - - .. code-block:: rst - - .. _my label name: - -Note the leading underscore indicating an inbound link. -The content immediately following -this label is the target for a ``:ref:`my label name``` -reference from anywhere within the documentation set. -The label should be added immediately before a heading so there's a -natural phrase to show when referencing this label (e.g., the heading -text). - -This is the same directive used to -define a label that's a reference to a URL: - -.. code-block:: rest - - .. _Hypervisor Wikipedia Page: - https://en.wikipedia.org/wiki/Hypervisor - -To enable easy cross-page linking within the site, each file should have -a reference label before its title so it can -be referenced from another file. These reference labels must be unique -across the whole site, so generic names such as "samples" should be -avoided. For example the top of this document's ``.rst`` file is: - - -.. code-block:: rst - - .. _doc_guidelines: - - Documentation Guidelines - ######################## - -Other ``.rst`` documents can link to this document using the -``:ref:`doc_guidelines``` tag and it will show up as -:ref:`doc_guidelines`. This type of internal cross reference works -across multiple files, and the link text is obtained from the document -source so if the title changes, the link text will update as well. - -There may be times where you'd like to change the link text that's shown -in the generated document. In this case, you can add specify alternate -text using ``:ref:`alternate text ``` (renders as -:ref:`alternate text `). - - -Non-ASCII Characters -******************** - -You can insert non-ASCII characters such as a Trademark symbol -(|trade|), by using the notation ``|trade|``. (It's also allowed to use -the UTF-8 characters directly.) Available replacement names are defined -in an include file used during the Sphinx processing of the reST files. -The names of these replacement characters are the same as used in HTML -entities used to insert characters in HTML, e.g., \™ and are -defined in the file ``sphinx_build/substitutions.txt`` as listed here: - -.. literalinclude:: ../substitutions.txt - :language: rst - -We've kept the substitutions list small but others can be added as -needed by submitting a change to the ``substitutions.txt`` file. - -Code and Command Examples -************************* - -Use the reST ``code-block`` directive to create a highlighted block of -fixed-width text, typically used for showing formatted code or console -commands and output. Smart syntax highlighting is also supported (using the -Pygments package). You can also directly specify the highlighting language. -For example: - -.. code-block:: rest - - .. code-block:: c - - struct _k_object { - char *name; - u8_t perms[CONFIG_MAX_THREAD_BYTES]; - u8_t type; - u8_t flags; - u32_t data; - } __packed; - -Note the blank line between the ``code-block`` directive and the first -line of the code-block body, and the body content is indented three -spaces (to the first non-white space of the directive name). - -This would be rendered as: - - .. code-block:: c - - struct _k_object { - char *name; - u8_t perms[CONFIG_MAX_THREAD_BYTES]; - u8_t type; - u8_t flags; - u32_t data; - } __packed; - - -You can specify other languages for the ``code-block`` directive, -including ``c``, ``python``, and ``rst``, and also ``console``, -``bash``, or ``shell``. If you want no syntax highlighting, use the -language ``none``, for example: - -.. code-block:: rest - - .. code-block:: none - - This would be a block of text styled with a background - and box, but with no syntax highlighting. - -Would display as: - - .. code-block:: none - - This would be a block of text styled with a background - and box, but with no syntax highlighting. - -There's a shorthand for writing code blocks too: end the introductory -paragraph with a double colon (``::``) and indent the code block content -by three spaces. On output, only one colon will be shown. The -highlighting package makes a best guess at the type of content in the -block and highlighting purposes. This can lead to some odd -highlighting in the generated output. - -Tabs, spaces, and indenting -*************************** - -Indenting is significant in reST file content, and using spaces is -preferred. Extra indenting can (unintentionally) change the way content -is rendered too. For lists and directives, indent the content text to -the first non-white space in the preceding line. For example: - -.. code-block:: rest - - * List item that spans multiple lines of text - showing where to indent the continuation line. - - 1. And for numbered list items, the continuation - line should align with the text of the line above. - - .. code-block:: none - - The text within a directive block should align with the - first character of the directive name. - -Keep the line length for documentation less than 80 characters to make -it easier for reviewing in GitHub. Long lines because of URL references -are an allowed exception. diff --git a/contribute/dox-source-code.rst b/contribute/dox-source-code.rst deleted file mode 100644 index 6692ec8e..00000000 --- a/contribute/dox-source-code.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. _dox-source-code: - -Documenting the Source Code -########################### - -All source code items such as functions, globals, and defines must be documented. Declarations that appear in the API headers must be documented. - -The source code documentation follows the Doxygen (dox) annotation format. It -enables generation of documentation in HTML/XML formats directly from the -annotated source files. Doxygen has many annotation flavors; the FW code -uses the one used by Alsa Project. - -Refer to :ref:`sof_doc` to learn how to generate the documentation. - -Basic Rules -*********** - -1. All dox comments begin with ``/**`` and end with ``*/``. - -#. Short comments appended to structure members begin with ``/**<``. - Keep them short while adding more details to the parent documentation if - needed. - -#. If a brief description is followed by a detailed description, the - first one begins with the ``\brief`` tag and the detailed section is separated - with an empty line. - -#. Use the ``\brief`` tag if you want to make sure the first line is inlined inside - the basic description in HTML output (see *#define* example below). - -Examples -******** - -.. code-block:: c - :caption: General Example - - /** - * \brief This is mandatory short description. - * - * This is detailed description. - */ - typedef ...; - -.. code-block:: c - :caption: Macro (simple one, with no parameters) - - /** \brief SOF ABI version number. */ - #define SOF_ABI_VERSION 1 - -.. code-block:: c - :caption: Structure / Union - - /** - * \brief Header for all non IPC ABI data. - * - * Identifies data type, size and ABI. - * Used by any bespoke component data structures or binary blobs. - */ - struct sof_abi_hdr { - uint32_t magic; /**< 'S', 'O', 'F', '\0' */ - uint32_t type; /**< component specific type */ - uint32_t size; /**< size in bytes of data excluding this struct */ - uint32_t abi; /**< SOF ABI version */ - uint32_t comp_abi; /**< component specific ABI version */ - char data[0]; - } __attribute__((packed)); - -.. code-block:: c - :caption: Enum - - /** \brief Types of DAI */ - enum sof_ipc_dai_type { - SOF_DAI_INTEL_NONE = 0, /**< None */ - SOF_DAI_INTEL_SSP, /**< Intel SSP */ - SOF_DAI_INTEL_DMIC, /**< Intel DMIC */ - SOF_DAI_INTEL_HDA, /**< Intel HDA */ - }; - -.. code-block:: c - :caption: Function / Macro (with parameters) - - /** - * \brief Utility to get module pointer from position. - * \param[in,out] desc FW descriptor in manifest. - * \param[in] index Index of the module. - * \return Pointer to module descriptor. - * - * Note that index is not verified. - */ - static inline struct sof_man_module *sof_man_get_module(struct sof_man_fw_desc *desc, - int index); diff --git a/contribute/process/images/abiprocess.pu b/contribute/images/abiprocess.pu similarity index 100% rename from contribute/process/images/abiprocess.pu rename to contribute/images/abiprocess.pu diff --git a/contribute/process/images/audacity-clean-sine-wave.png b/contribute/images/audacity-clean-sine-wave.png similarity index 100% rename from contribute/process/images/audacity-clean-sine-wave.png rename to contribute/images/audacity-clean-sine-wave.png diff --git a/contribute/process/images/audacity-end-of-glitch.png b/contribute/images/audacity-end-of-glitch.png similarity index 100% rename from contribute/process/images/audacity-end-of-glitch.png rename to contribute/images/audacity-end-of-glitch.png diff --git a/contribute/process/images/audacity-sine-wave-with-glitch.png b/contribute/images/audacity-sine-wave-with-glitch.png similarity index 100% rename from contribute/process/images/audacity-sine-wave-with-glitch.png rename to contribute/images/audacity-sine-wave-with-glitch.png diff --git a/contribute/process/images/audacity-start-of-glitch.png b/contribute/images/audacity-start-of-glitch.png similarity index 100% rename from contribute/process/images/audacity-start-of-glitch.png rename to contribute/images/audacity-start-of-glitch.png diff --git a/contribute/process/images/bug-life-cycle.png b/contribute/images/bug-life-cycle.png similarity index 100% rename from contribute/process/images/bug-life-cycle.png rename to contribute/images/bug-life-cycle.png diff --git a/contribute/process/images/example-trace-point.png b/contribute/images/example-trace-point.png similarity index 100% rename from contribute/process/images/example-trace-point.png rename to contribute/images/example-trace-point.png diff --git a/contribute/process/images/fork-sof-docs.png b/contribute/images/fork-sof-docs.png similarity index 100% rename from contribute/process/images/fork-sof-docs.png rename to contribute/images/fork-sof-docs.png diff --git a/contribute/process/images/label-blocked.png b/contribute/images/label-blocked.png similarity index 100% rename from contribute/process/images/label-blocked.png rename to contribute/images/label-blocked.png diff --git a/contribute/process/images/label-branch-glk.png b/contribute/images/label-branch-glk.png similarity index 100% rename from contribute/process/images/label-branch-glk.png rename to contribute/images/label-branch-glk.png diff --git a/contribute/process/images/label-branch-master.png b/contribute/images/label-branch-master.png similarity index 100% rename from contribute/process/images/label-branch-master.png rename to contribute/images/label-branch-master.png diff --git a/contribute/process/images/label-branch-v1-2.png b/contribute/images/label-branch-v1-2.png similarity index 100% rename from contribute/process/images/label-branch-v1-2.png rename to contribute/images/label-branch-v1-2.png diff --git a/contribute/process/images/label-bug.png b/contribute/images/label-bug.png similarity index 100% rename from contribute/process/images/label-bug.png rename to contribute/images/label-bug.png diff --git a/contribute/process/images/label-duplicate.png b/contribute/images/label-duplicate.png similarity index 100% rename from contribute/process/images/label-duplicate.png rename to contribute/images/label-duplicate.png diff --git a/contribute/process/images/label-invalid.png b/contribute/images/label-invalid.png similarity index 100% rename from contribute/process/images/label-invalid.png rename to contribute/images/label-invalid.png diff --git a/contribute/process/images/label-need-info.png b/contribute/images/label-need-info.png similarity index 100% rename from contribute/process/images/label-need-info.png rename to contribute/images/label-need-info.png diff --git a/contribute/process/images/label-platform-apl.png b/contribute/images/label-platform-apl.png similarity index 100% rename from contribute/process/images/label-platform-apl.png rename to contribute/images/label-platform-apl.png diff --git a/contribute/process/images/label-platform-byt.png b/contribute/images/label-platform-byt.png similarity index 100% rename from contribute/process/images/label-platform-byt.png rename to contribute/images/label-platform-byt.png diff --git a/contribute/process/images/label-platform-glk.png b/contribute/images/label-platform-glk.png similarity index 100% rename from contribute/process/images/label-platform-glk.png rename to contribute/images/label-platform-glk.png diff --git a/contribute/process/images/label-priorities.png b/contribute/images/label-priorities.png similarity index 100% rename from contribute/process/images/label-priorities.png rename to contribute/images/label-priorities.png diff --git a/contribute/process/images/label-verified.png b/contribute/images/label-verified.png similarity index 100% rename from contribute/process/images/label-verified.png rename to contribute/images/label-verified.png diff --git a/contribute/process/images/label-will-not-fix.png b/contribute/images/label-will-not-fix.png similarity index 100% rename from contribute/process/images/label-will-not-fix.png rename to contribute/images/label-will-not-fix.png diff --git a/contribute/index.rst b/contribute/index.rst index b03a15e1..2e9b941e 100644 --- a/contribute/index.rst +++ b/contribute/index.rst @@ -4,15 +4,906 @@ Contributing to the Project ########################### As an open-source project, we welcome and encourage the community to submit -patches for code, documentation, tests, and more, directly to the project. - -.. toctree:: - :maxdepth: 1 - - contribute_guidelines.rst - doc_guidelines.rst - dox-source-code.rst - process/bug-tracking - process/docbuild - process/abiprocess - linux/development_tree +patches for code, documentation, tests, and audio algorithms directly to the +Sound Open Firmware (SOF) project. In our collaborative open-source environment, +standards and methods for submitting changes help ensure high code quality, +architectural consistency, and smooth community collaboration. + +This document serves as the comprehensive single-page reference for all aspects +of contributing to SOF: + +* :ref:`contribute_guidelines`: Licensing (BSD-3-Clause), Developer Certificate of Origin (DCO), and prerequisites. +* :ref:`development_tree`: Linux SOF kernel drivers, git trees, upstream workflow, and maintainers. +* :ref:`SOF_ABI_changes`: Firmware-to-driver ABI change process, RFC reviews, and compatibility. +* :ref:`bug_tracking`: Bug life cycle, issue triage labels, reporting guidelines, and audio quality proof captures. +* :ref:`doc_guidelines`: Documentation formatting in reStructuredText and Sphinx. +* :ref:`dox-source-code`: Documenting source code headers with Doxygen annotations. +* :ref:`sof_doc`: Building, previewing, and publishing SOF documentation locally and with Docker. + +.. _contribute_guidelines: + +Contribution Guidelines +*********************** + +As an open-source project, we welcome and encourage the community to +submit patches directly to the SOF project. In our collaborative open +source environment, standards and methods for submitting changes help +reduce the chaos that can result from an active development community. + +This section explains how to participate in project conversations, log +and track bugs and enhancement requests, and submit patches to the +project so your patch will be accepted quickly in the codebase. + +Licensing +========= + +Licensing is very important to open source projects. It helps ensure the +software continues to be available under the terms that the author +desired. + +The SOF project uses a BSD-3-Clause license, as found in the +:git-sof-mainline:`LICENCE` file in the project's GitHub repo. + +A license tells you what rights you have as a developer, as provided by +the copyright holder. It is important that the contributor fully +understands the licensing rights and agrees to them. Sometimes the +copyright holder isn't the contributor, such as when the contributor is +doing work on behalf of a company. + +.. _DCO: + +Developer Certification of Origin (DCO) +======================================= + +To make a good faith effort to ensure licensing criteria are met, +project SOF requires the Developer Certificate of Origin (DCO) process +to be followed. + +The DCO is an attestation attached to every contribution made by every +developer. In the commit message of the contribution, the developer +adds a ``Signed-off-by`` statement and thereby agrees to the DCO. + +When a developer submits a patch, it is a commitment that the +contributor has the right to submit the patch per the license. The DCO +agreement is shown below and at http://developercertificate.org/. + +.. code-block:: none + + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the + best of my knowledge, is covered under an appropriate open + source license and I have the right under that license to + submit that work with modifications, whether created in whole + or in part by me, under the same open source license (unless + I am permitted to submit under a different license), as + Indicated in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including + all personal information I submit with it, including my + sign-off) is maintained indefinitely and may be redistributed + consistent with this project or the open source license(s) + involved. + +DCO Sign-Off Methods +-------------------- + +The DCO requires that a sign-off message, in the following format, +appears on each commit in the pull request:: + + Signed-off-by: Random J Developer + +The DCO text can either be manually added to your commit body, or you can add +either ``-s`` or ``--signoff`` to your usual Git commit commands. If you forget +to add the sign-off, you can also amend a previous commit with the sign-off by +running ``git commit --amend -s``. If you have already pushed your changes to GitHub, +you will need to force push your branch after this with ``git push -f``. + +.. note:: + The name and email address of the account you use to submit your PR must + match the name and email address on the ``Signed-off-by`` line in + your commit message. + +Prerequisites +============= + +.. _SOF project website: https://sofproject.org + +As a contributor, familiarize yourself with the SOF project, how to +configure, install, and use it as explained on the +`SOF project website`_, and how to set up your development environment +as introduced in the project's :ref:`getting_started`. + +You should be familiar with common developer tools such as Git and +platforms such as GitHub. + +If you have not already done so, create a (free) GitHub account +on https://github.com and have Git tools available on your development system. + +.. _development_tree: + +Linux SOF Driver Development +**************************** + +Background +========== + +Linux development is split by subsystems. All SOF contributions are +merged through the sound/system (maintained by Takashi Iwai) and the +sound/soc subsystem (maintained by Mark Brown). + +All SOF patches merged by the two maintainers will be used for +linux-next (as a first pass of integration to detect conflicts with +other subsystems or compilation issues) and eventually merged in the +mainline by Linus Torvalds. + +Instructions for SOF Developers +=============================== + +ABI Changes +----------- + +One fundamental and non-negotiable premise of Linux kernel development +is "we don't break the userspace." More specifically, users may update +their kernels at any time while keeping the SOF firmware binary and +topology files stored in the root filesystem unchanged. The +expectation is that the SOF Linux driver does not generate any errors +and that audio functionality remains unchanged. + +Conversely, when a capability is introduced in a new firmware release, the +expectation is that the kernel shall be updated as well. In other words, +a new firmware does not need to include any backwards-compatibility +code to interface with an older kernel. + +When the ABI changes, the developer or maintainer shall tag it in +GitHub, and the ABI level change will be recorded in the official ABI +change tracker: + +https://github.com/orgs/thesofproject/projects/2 + +The process for firmware ABI changes is documented in :ref:`SOF_ABI_changes`. + +When the ABI is not backwards-compatible, Pull Requests on the +kernel side shall include code that deals with older firmware and +topology files. + +Development Branch +------------------ + +All SOF development takes place on the ``topic/sof-dev`` branch in the SOF tree: + +``git@github.com:thesofproject/linux.git`` + +Developers are required to submit Pull Requests (PRs) against the +``topic/sof-dev`` branch. The Continuous Integration (CI) runs a set +of static analysis, builds, and on-device testing. + +Two approvers are required for each PR. SOF admins may in some +exceptions use their privileges to merge PRs, such as to restore +functionality and broken builds. + +When a PR is submitted by an SOF admin, another admin must approve that PR. +The PRs are integrated into the SOF tree using the 'rebase-and-merge' method +which keeps the integrated patches in a linear order. + +Rebasing Tree +------------- + +In addition to the ``topic/sof-dev`` branch, the SOF project maintains a +parallel ``topic/sof-dev-rebase`` branch. This branch is not intended for +development, but to make upstream contributions easier to manage. +As its name indicates, commit SHA1s in ``topic/sof-dev-rebase`` are volatile +and should not be relied on. SHA1s in ``topic/sof-dev`` are immutable. + +Upstream Merges +--------------- + +During Linux development, patches to the ALSA/ASoC cores, dependencies such +as audio codecs, or bug fixes may be contributed by the community. SOF Linux +maintainers will, on a regular basis (typically weekly), merge all upstream +contributions into the SOF tree. + +.. _sof_drv_maintainer_list: + +Development Flow +================ + +SOF Linux Maintainers +--------------------- + +.. list-table:: + :header-rows: 1 + :widths: 25 35 40 + + * - Organization + - Maintainer + - GitHub Handle + * - Consultant + - Pierre Bossart + - `@plbossart `_ + * - Intel + - Kai Vehmanen + - `@kv2019i `_ + * - NXP + - Daniel Baluta + - `@dbaluta `_ + +SOF Maintainers Process +----------------------- + +Mirror all SOF patches to topic/sof-dev-rebase: + This mirroring consists in doing a set of git "cherry-pick" operations + from ``topic/sof-dev`` to ``topic/sof-dev-rebase``. Once all development + patches are applied, SOF maintainers will add the relevant + Signed-off-by and Reviewed-by tags. + + In specific cases, incremental patches will be squashed to simplify + upstream reviews, commit messages will be made clearer, and the order of + patches will be changed, but in all cases the intent is that both + ``topic/sof-dev`` and ``topic/sof-dev-rebase`` provide the same code (as seen + with git diff or diff -r). + +Upstream merge/rebase: + When the two branches are integrated, the SOF maintainer will create + an upstream baseline. This baseline is then merged locally on top of + ``topic/sof-dev``, then pushed as a dedicated PR and run through the CI + tests. The merge may in some cases create conflicts that have to be + resolved locally by the maintainer. Once the PR is deemed suitable for + integration, the maintainer will use a 'Commit merge' operation (in + contrast to the 'rebase-and-merge' used for development). + + In parallel, the ``topic/sof-dev-rebase`` branch is rebased on top of the + same baseline, and again compared to the ``topic/sof-dev`` branch. After + the two separate operations of merge and rebase on the two branches, + these two branches should again be identical. The net effect of the + rebase is that all patches already integrated by ALSA/ASoC maintainers + 'disappear.' In other words, comparing sof-dev with sof-dev-rebase + shows all patches not currently merged upstream. This includes a limited + number of infrastructure changes that will never be merged upstream + such as github's CODEOWNERS file. + +Upstream contributions: + The SOF maintainer generates patch sets and sends them with a cover + to the alsa-devel mailing list, with the maintainers in Cc:. In most + cases the patches are approved without issues, but the ALSA/ASoC + maintainers or members of the community may provide feedback and + request some changes. In those cases, the changes are applied on + ``topic/sof-dev``, then mirrored and squashed on ``topic/sof-dev-rebase``, and + submitted again. Under no circumstances should the SOF maintainer handle + changes to the ``topic/sof-dev-rebase`` directly. + +Exceptions: + In very specific cases, such as for HDMI-related patches, it might be easier + for an SOF developer to submit the patches directly to alsa-devel. By + default, though, the process is that all patches are first submitted + to the SOF GitHub, CI-tested. Only when maintainers provide a written + agreement should developers submit SOF-related patches directly to the + alsa-devel mailing list. + + To avoid disrupting the development and rewriting its history, all + upstream patches are integrated using the "Merge commit" option. + +Development Summary +=================== + +:: + + +----reject-----------+ +--------merge----------------+ + | | | | + v | v | + +----+------+ +-----+-------+ +------+--------+ +--------+----------+ + | developer +------->+ SOF reviews +--ok-->+ topic/sof-dev | +-+ upstream baseline | + | PR | | CI tests | | | | | | + +-----------+ +-----+-------+ +------+--------+ | +---------+---------+ + | | | ^ + | +--rebase-+ | + | | | ALSA maintainers ok + | | v | + | +----------v--------+--+ +--------+----------+ + | | topic/sof-dev-rebase +-email-->+ alsa-devel | + | | | | mailing list | + | +----------------------+ +--------+----------+ + | ^ + | | + | | + +-----------------direct path (exceptions)------------+ + +.. _SOF_ABI_changes: + +Firmware ABI Change Process +*************************** + +SOF ABI Definitions +=================== + +The SOF ABI consists of public structs used in host-FW communication +defined in: + +- ``src/include/kernel/`` +- ``src/include/ipc/`` +- ``src/include/user/`` + +SOF ABI versioning is defined in firmware source code documentation: +:git-sof-mainline:`src/include/kernel/abi.h`. + +Change Process +============== + +When a firmware change requires extending or modifying the public +SOF ABI, the developer must go through the ABI change process as defined +in this section. The developer must drive this process, contact the +stakeholders, request reviews (and re-reviews when needed) and coordinate +with the driver maintainers. + +The main steps of the process are depicted in the following +state diagram: + +.. _ABI Change Tracker: https://github.com/orgs/thesofproject/projects/2 + +The pull requests are classified in GitHub using the official `ABI Change Tracker`_. + +.. uml:: images/abiprocess.pu + :caption: ABI process state diagram + +When the ABI change is not backwards-compatible, Pull Requests on the +kernel side shall include code that deals with older firmware and +topology files. See :ref:`development_tree` for kernel side +documentation. + +Document Modified Fields +======================== + +When the interface is extended with a backwards-compatible (MINOR) interface +change, each added or modified interface field must be documented +with a reference to the interface version where the change was +first implemented. + +Some code examples: + +.. code-block:: c + + struct foo { + uint8_t group_id; /**< group ID, 0 means no group (ABI3.17) */ + } __attribute__((packed)); + +.. code-block:: c + + enum bar { + EXT_MAN_ELEM_FOO_DATA = 7, /**< ABI3.18 */ + }; + +ABI Change Approvers +==================== + +TSC +--- + +Approval from an SOF :ref:`tsc` member is needed for all ABI changes. + +SOF Driver Maintainers +---------------------- + +Linux driver team approval for changes can be granted by any member of the +SOF Linux driver maintainer team. The current list of members is maintained +in :ref:`sof_drv_maintainer_list`. + +.. _bug_tracking: + +Bug Tracking & Reporting +************************ + +Bug-type issues have the label |label-bug|. + +.. |label-bug| image:: images/label-bug.png + :scale: 70 + +GitHub issues only have two states: open, closed. Dedicated *labels* are defined +to assist SOF bug tracking and triage. + +Life Cycle of a Bug +=================== + +The life cycle of a bug represents the end-to-end resolution workflow: + +.. image:: images/bug-life-cycle.png + :scale: 80 + +Issue Labels +============ + +Please find all labels at https://github.com/thesofproject/sof/labels. + +* *Solution*, *priority* and *platform* labels are common across SOF + firmware, Linux kernel driver, and tool repositories. +* *Branch* labels are repository-specific. + +Solution Labels +--------------- + +Usually a developer will fix a bug by submitting pull requests. This +is the default solution and doesn't require an extra solution label. + +Otherwise, **developers** add the label |label-invalid|, +|label-duplicate|, or |label-won't-fix| to indicate the solution with +justification: + +.. |label-invalid| image:: images/label-invalid.png + :scale: 70 + +.. |label-duplicate| image:: images/label-duplicate.png + :scale: 70 + +.. |label-won't-fix| image:: images/label-will-not-fix.png + :scale: 70 + +The label |label-verified| is added exclusively by the **bug scrub owner** after +reviewing the solution and confirmation from QA and the reporter: + +.. |label-verified| image:: images/label-verified.png + :scale: 70 + +Priority Labels +--------------- + +The **bug scrub owner** assigns priority to a bug according to its impact: + +.. image:: images/label-priorities.png + :scale: 50 + +Platform and Branch Labels +-------------------------- + +Used by **QA** and the **bug reporter**. + +*Platform* labels specify the platform or multiple platforms on +which a bug is observed, e.g. |label-byt|, |label-apl|, |label-glk| ... + +.. |label-byt| image:: images/label-platform-byt.png + :scale: 70 + +.. |label-apl| image:: images/label-platform-apl.png + :scale: 70 + +.. |label-glk| image:: images/label-platform-glk.png + :scale: 70 + +*Branch* labels specify the branch or branches on which a bug is observed, +e.g. |label-branch-v1.2|, |label-branch-glk| ... + +.. |label-branch-v1.2| image:: images/label-branch-v1-2.png + :scale: 70 + +.. |label-branch-glk| image:: images/label-branch-glk.png + :scale: 70 + +.. note:: + *Platform* labels should always be applied. + + *Branch* labels are usually only applied when the branch is not + the default branch for developing/release on the platform. + + **QA** should *update (add/remove)* platform and branch labels + according to the latest bug status. + +Dependency Labels +----------------- + +Two optional labels can be used to call for attention: + +* |label-blocked| - Blocked by an external dependency (feature implementation or bug reproduction). +* |label-need-info| - Further information is requested from the reporter. + +.. |label-blocked| image:: images/label-blocked.png + :scale: 70 + +.. |label-need-info| image:: images/label-need-info.png + :scale: 70 + +How to Report a Bug +=================== + +Please `create an issue `_ +and apply the label |label-bug|. + +Please provide the following information: + +* **Title**: + * Clear, unique, and descriptive summary of the bug. Avoid generic titles like "ipc timeout" or "topology failed to load". + * Include keywords from the kernel, firmware, or user space error message. + * Prefix indicating the area of failure, e.g. ``ipc:``, ``topology:``, ``pipeline:``. + +* **Environment**: + * Branch name and commit hash of three repositories: ``sof`` (firmware), ``linux`` (kernel driver), and ``sof-tools`` (tools & topology). + * Exact topology file name (e.g. ``sof-tgl-nocodec.tplg``). + * Target platform(s) on which the bug is observed. + * Reproducibility Rate (e.g. 5/5, or 2/10 intermittent). + +* **Steps to Reproduce**: + * Precise, numbered steps from beginning to end so developers can reproduce the exact scenario. + +* **Expected Result**: + * What the user expected to happen. + +* **Actual Result**: + * What actually occurred in contrast to expected behavior. + +* **Proof & Diagnostic Logs**: + * Paste relevant ``dmesg`` and firmware trace logs into the comment box (including 10 lines before the crash/error). + * For firmware boot failures, include the **trace point** indicating boot progress: + + |trace-point| + + * Attach full kernel message buffers and firmware trace output. + * If audio playback/capture is silent, attach current ``amixer`` settings. + * For audio quality anomalies (noise, glitch sound, distortion): + * Play/capture a reference sine wave and attach the captured WAV file. + * Specify frequency, sample rate, bit format, and channel count. + * Provide Audacity waveform screenshots showing the glitch/distortion (> 10ms): + + |sine-wav| + + Sine wave with audio glitch: + + |sine-with-glitch| + + Zoomed in at glitch start: + + |start-of-glitch| + + Zoomed in at glitch end: + + |end-of-glitch| + +.. |trace-point| image:: images/example-trace-point.png + :scale: 75 + +.. |sine-wav| image:: images/audacity-clean-sine-wave.png + :scale: 75 + +.. |sine-with-glitch| image:: images/audacity-sine-wave-with-glitch.png + :scale: 75 + +.. |start-of-glitch| image:: images/audacity-start-of-glitch.png + :scale: 60 + +.. |end-of-glitch| image:: images/audacity-end-of-glitch.png + :scale: 60 + +.. note:: + If you encounter multiple separate issues, please file them separately so they can + be tracked and resolved independently. + + Please use GitHub markdown code fences (`````) for formatting logs, diffs, and terminal commands. + +How to Close a Bug +================== + +* **Bugs fixed by pull requests**: + Developers can use GitHub keywords (e.g. ``Fixes #1234``) in commit messages to automatically close bugs when merged. + Developers can also leave the bug open for QA verification; QA closes the issue once verified. +* **Invalid or Won't Fix**: + For bugs labeled |label-invalid| or |label-won't-fix|, developers should close them with an explanation. +* **Duplicates**: + For bugs with label |label-duplicate|, keep the issue open until the primary duplicate issue is resolved and closed. + +.. note:: + After a pull request is merged, the developer should always mention (``@``) the bug reporter and QA engineer to verify the resolution. + +.. _doc_guidelines: + +Documentation Guidelines +************************ + +The SOF project documentation is authored using `reStructuredText`_ (``.rst``) +with Sphinx extensions, producing the static HTML website hosted at +https://thesofproject.github.io. + +Developers can inspect ``.rst`` source files directly or generate the HTML +output locally using ``make html``. + +.. _reStructuredText: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html +.. _Sphinx extensions: http://www.sphinx-doc.org/en/stable/contents.html +.. _Sphinx Inline Markup: http://sphinx-doc.org/markup/inline.html#inline-markup + +Headings +======== + +Document sections are identified by an underline beneath the title text. +For consistency across the SOF project documentation, use the following underline characters: + +* Use ``#`` for Document Title (top level) +* Use ``*`` for First sub-section heading level +* Use ``=`` for Second sub-section heading level +* Use ``-`` for Third sub-section heading level + +The heading underline must be at least as long as the title text. + +Content Highlighting +==================== + +Common reST inline markup: + +* Single asterisk: ``*text*`` for emphasis (*italics*) +* Double asterisks: ``**text**`` for strong emphasis (**boldface**) +* Double backticks: ````text```` for ``inline code`` and literals + +If asterisks or backquotes appear in running prose and could be confused with +inline markup delimiters, prefix them with a backslash (``\``). + +Lists +===== + +For bullet lists, place an asterisk (``*``) or hyphen (``-``) at +the start of a paragraph and indent continuation lines by two spaces. +Always insert a blank line before the first list item. + +For numbered lists, start with ``1.`` and continue with autonumbering using ``#.``: + +.. code-block:: rest + + 1. First ordered step + #. Second ordered step + #. Third ordered step + +Definition lists provide a clean term-and-description presentation: + +.. code-block:: rest + + make html + Generates Sphinx HTML documentation output. + + make clean + Cleans generated documentation build artifacts. + +Multi-Column Lists +================== + +For long bullet lists with short entries, render them in columns with ``.. hlist::``: + +.. code-block:: rest + + .. hlist:: + :columns: 3 + + * Item A + * Item B + * Item C + * Item D + * Item E + * Item F + +File Names and Commands +======================= + +Sphinx provides semantic inline roles: + +* Files: ``:file:`filename.c``` +* Commands: ``:command:`make``` +* Double backticks (````code````) can also be used for code symbols and paths. + +.. _internal-linking: + +Internal Cross-Reference Linking +================================ + +To create cross-page hyperlinks across the documentation site, define an anchor label +immediately above a section heading: + +.. code-block:: rst + + .. _my_unique_target: + + Section Title + ============= + +Reference the anchor from any file in the documentation using ``:ref:`my_unique_target``` +(renders as the section heading) or ``:ref:`Custom Link Text ```. + +Non-ASCII Characters +==================== + +Special character substitutions are defined in ``sphinx_build/substitutions.txt``: + +.. literalinclude:: ../substitutions.txt + :language: rst + +Code and Command Examples +========================= + +Use the ``code-block`` directive to display syntax-highlighted source code or shell sessions: + +.. code-block:: rest + + .. code-block:: c + + struct sof_ipc_cmd { + uint32_t size; + uint32_t cmd; + }; + +Supported languages include ``c``, ``python``, ``bash``, ``console``, ``rst``, and ``none``. + +Indentation & Formatting +======================== + +Indentation is syntactically significant in reST. Use spaces (not tabs). +Directives and list continuations must align with the first character of the parent directive name or list text. +Keep line lengths under 100 characters for optimal review in GitHub pull requests. + +.. _dox-source-code: + +Documenting Source Code (Doxygen) +********************************* + +All public firmware and driver source code items—including functions, structures, +enums, macros, and API declarations in header files—must be documented using +Doxygen (dox) annotations. + +Basic Rules +=========== + +1. All Doxygen comments begin with ``/**`` and end with ``*/``. +2. Short comments appended to structure members begin with ``/**<``. Keep them concise. +3. For multi-line documentation, start with a ``\brief`` summary followed by a blank line and the detailed description. +4. Function parameters are documented with ``\param[in]``, ``\param[out]``, or ``\param[in,out]``, followed by ``\return``. + +Examples +======== + +.. code-block:: c + :caption: Function Documentation + + /** + * \brief Allocates and initializes an audio stream buffer. + * \param[in,out] dev Pointer to the SOF core device structure. + * \param[in] size Requested buffer capacity in bytes. + * \param[in] flags Memory allocation flags (e.g. SOF_MEM_ZONE_SYS). + * \return Pointer to allocated sof_buffer, or NULL on allocation failure. + */ + struct sof_buffer *sof_buffer_alloc(struct sof_dev *dev, size_t size, uint32_t flags); + +.. code-block:: c + :caption: Structure Documentation + + /** + * \brief Header for non-IPC ABI component data structures. + */ + struct sof_abi_hdr { + uint32_t magic; /**< 'S', 'O', 'F', '\0' */ + uint32_t type; /**< Component specific type */ + uint32_t size; /**< Size in bytes of payload */ + uint32_t abi; /**< SOF ABI version */ + uint32_t comp_abi; /**< Component specific ABI version */ + char data[0]; + } __attribute__((packed)); + +.. code-block:: c + :caption: Macro Documentation + + /** \brief Current SOF ABI Major Version */ + #define SOF_ABI_VERSION 1 + +.. _sof_doc: + +Building & Publishing Documentation +*********************************** + +These instructions explain how to build, preview, and publish the SOF documentation +website locally or via Docker. + +Documentation Overview +====================== + +The SOF project documentation sources reside in the `sof-docs `_ +repository. Documentation is built using Sphinx with the PyData Sphinx theme, +the Breathe extension (integrating Doxygen XML generated from the `sof` firmware repository), +and custom data-generation scripts. + +Setting Up Working Repositories +=============================== + +The recommended directory structure stages `sof` and `sof-docs` side-by-side: + +.. code-block:: bash + + mkdir -p ~/thesofproject && cd ~/thesofproject + git clone https://github.com/thesofproject/sof-docs.git + git clone https://github.com/thesofproject/sof.git + cd sof-docs + git remote add upstream https://github.com/thesofproject/sof-docs.git + +Installing Documentation Tools +============================== + +Install system prerequisites for your operating system: + +* **Ubuntu / Debian**: + + .. code-block:: bash + + sudo apt-get install doxygen python3-pip python3-venv make \ + graphviz cmake ninja-build default-jre + +* **Fedora / RHEL**: + + .. code-block:: bash + + sudo dnf install doxygen python3-pip make graphviz cmake ninja-build java + +Create and activate a dedicated Python virtual environment: + +.. code-block:: bash + + cd ~/thesofproject/sof-docs + python3 -m venv .venv + source .venv/bin/activate + pip install -r scripts/requirements.txt -c scripts/constraints.txt + +.. _run_documentation_processors: + +Running Documentation Processors +================================ + +Local Build +----------- + +To generate the complete HTML documentation: + +.. code-block:: bash + + cd ~/thesofproject/sof-docs + source .venv/bin/activate + make clean html + +The generated static website is located at ``_build/html/index.html``. Open it in any browser: + +.. code-block:: bash + + python3 -m http.server 8085 -d _build/html + +Docker Build +------------ + +As an alternative to installing dependencies directly on your workstation, use the Docker builder: + +.. code-block:: bash + + cd ~/thesofproject + ./sof-docs/scripts/docker_build/docker-build.sh + +Publishing Content +================== + +If you have publishing rights to ``thesofproject.github.io``, you can update the public website: + +.. code-block:: bash + + cd ~/thesofproject + git clone git@github.com:thesofproject/thesofproject.github.io.git + cd ~/thesofproject/sof-docs + make publish + +Troubleshooting +=============== + +* **Missing Virtual Environment / Dependencies**: + Ensure your virtual environment is active (``source .venv/bin/activate``) and all packages from ``scripts/requirements.txt`` are installed. +* **Doxygen API XML Missing**: + When building without a local ``sof`` checkout, run ``make html LAX=1`` to compile documentation using lax mode. +* **PlantUML Version Incompatibility**: + Verify the PlantUML compiler version with: + + .. code-block:: bash + + java -jar ./scripts/plantuml.jar -version diff --git a/contribute/linux/development_tree.rst b/contribute/linux/development_tree.rst deleted file mode 100644 index 46ca8af0..00000000 --- a/contribute/linux/development_tree.rst +++ /dev/null @@ -1,192 +0,0 @@ -.. _development_tree: - -Linux SOF drivers -################# - -.. contents:: - :local: - :depth: 3 - -Background -********** - -Linux development is split by subsystems. All SOF contributions are -merged through the sound/system (maintained by Takashi Iwai) and the -sound/soc subsystem (maintained by Mark Brown). - -All SOF patches merged by the two maintainers will be used for -linux-next (as a first pass of integration to detect conflicts with -other subsystems or compilation issues) and eventually merged in the -mainline by Linus Torvalds. - -Instructions for SOF developers -******************************* - -ABI changes -=========== - -One fundamental and non-negotiable premise of Linux kernel development -is "we don't break the userspace." More specifically, users may update -their kernels at any time while keeping the SOF firmware binary and -topology files stored in the root filesystem unchanged. The -expectation is that the SOF Linux driver does not generate any errors -and that audio functionality remains unchanged. - -Conversely, when a capability is introduced in a new firmware release, the -expectation is that the kernel shall be updated as well. In other words, -a new firmware does not need to include any backwards-compatibility -code to interface with an older kernel. - -When the ABI changes, the developer or maintainer shall tag it in -GitHub, and the ABI level change will be recorded in the official ABI -change tracker: - -https://github.com/orgs/thesofproject/projects/2 - -The process for firmware ABI changes is documented in the :ref:`SOF_ABI_changes`. - -When the ABI is not backwards-compatible, Pull Requests on the -kernel side shall include code that deals with older firmware and -topology files. - -Development branch -================== - -All SOF development takes place on the topic/sof-dev branch in the SOF tree: - -``git@github.com:thesofproject/linux.git`` - -Developers are required to submit Pull Requests (PRs) against the -topic/sof-dev branch. The Continuous Integration (CI) runs a set -of static analysis, builds, and on-device testing. - -Two approvers are required for each PR. SOF admins may in some -exceptions use their privileges to merge PRs, such as to restore -functionality and broken builds. - -When a PR is submitted by an SOF admin, another admin must approve that PR. -The PRs are integrated into the SOF tree using the 'rebase-and-merge' method -which keeps the integrated patches in a linear order. - -Rebasing tree -============= - -In addition to the topic/sof-dev branch, the SOF project maintains a -parallel topic/sof-dev-rebase branch. This branch is not intended for -development, but to make upstream contributions easier to manage. -As its name indicates, commit SHA1s in topic/sof-dev-rebase are volatile -and should not be relied on. SHA1s in topic/sof-dev are immutable. - -Upstream merges -=============== - -During Linux development, patches to the ALSA/ASoC cores, dependencies such -as audio codecs, or bug fixes may be contributed by the community. SOF Linux -maintainers will, on a regular basis (typically weekly), merge all upstream -contributions into the SOF tree. - -.. _sof_drv_maintainer_list: - -Development flow -**************** - -SOF Linux maintainers -===================== - -+---------------+-------------------+---------------+ -| Intel | Pierre Bossart | @plbossart | -+---------------+-------------------+---------------+ -| Intel | Ranjani Sridharan | @ranj063 | -+---------------+-------------------+---------------+ -| Intel | Kai Vehmanen | @kv2019i | -+---------------+-------------------+---------------+ -| NXP | Daniel Baluta | @dbaluta | -+---------------+-------------------+---------------+ - -SOF maintainers process -======================= - -Mirror all SOF patches to topic/sof-dev-rebase ----------------------------------------------- - -This mirroring consists in doing a set of git "cherry-pick" operations -from topic/sof-dev to topic/sof-dev-rebase. Once all development -patches are applied, SOF maintainers will add the relevant -Signed-off-by and Reviewed-by tags. - -In specific cases, incremental patches will be squashed to simplify -upstream reviews, commit messages will be made clearer, and the order of -patches will be changed, but in all cases the intent is that both -topic/sof-dev and topic/sof-dev-rebase provide the same code (as seen -with git diff or diff -r). - -Upstream merge/rebase ---------------------- - -When the two branches are integrated, the SOF maintainer will create -an upstream baseline. This baseline is then merged locally on top of -topic/sof-dev, then pushed as a dedicated PR and run through the CI -tests. The merge may in some cases create conflicts that have to be -resolved locally by the maintainer. Once the PR is deemed suitable for -integration, the maintainer will use a 'Commit merge' operation (in -contrast to the 'rebase-and-merge' used for development). - -In parallel, the topic/sof-dev-rebase branch is rebased on top of the -same baseline, and again compared to the topic/sof-dev branch. After -the two separate operations of merge and rebase on the two branches, -these two branches should again be identical. The net effect of the -rebase is that all patches already integrated by ALSA/ASoC maintainers -'disappear.' In other words, comparing sof-dev with sof-dev-rebase -shows all patches not currently merged upstream. This includes a limited -number of infrastructure changes that will never be merged upstream -such as github's CODEOWNERS file. - -Upstream contributions ----------------------- - -The SOF maintainer generates patch sets and sends them with a cover -to the alsa-devel mailing list, with the maintainers in Cc:. In most -cases the patches are approved without issues, but the ALSA/ASoC -maintainers or members of the community may provide feedback and -request some changes. In those cases, the changes are applied on -topic/sof-dev, then mirrored and squashed on topic/sof-dev-rebase, and -submitted again. Under no circumstances should the SOF maintainer handle -changes to the topic/sof-dev-rebase directly. - -Exceptions ----------- - -In very specific cases, such as for HDMI-related patches, it might be easier -for an SOF developer to submit the patches directly to alsa-devel. By -default, though, the process is that all patches are first submitted -to the SOF GitHub, CI-tested. Only when maintainers provide a written -agreement should developers submit SOF-related patches directly to the -alsa-devel mailing list. - -To avoid disrupting the development and rewriting its history, all -upstream patches are integrated using the "Merge commit" option. - -Development summary -******************* - -:: - - +----reject-----------+ +--------merge----------------+ - | | | | - v | v | - +----+------+ +-----+-------+ +------+--------+ +--------+----------+ - | developer +------->+ SOF reviews +--ok-->+ topic/sof-dev | +-+ upstream baseline | - | PR | | CI tests | | | | | | - +-----------+ +-----+-------+ +------+--------+ | +---------+---------+ - | | | ^ - | +--rebase-+ | - | | | ALSA maintainers ok - | | v | - | +----------v--------+--+ +--------+----------+ - | | topic/sof-dev-rebase +-email-->+ alsa-devel | - | | | | mailing list | - | +----------------------+ +--------+----------+ - | ^ - | | - | | - +-----------------direct path (exceptions)------------+ diff --git a/contribute/process/abiprocess.rst b/contribute/process/abiprocess.rst deleted file mode 100644 index 91308bb1..00000000 --- a/contribute/process/abiprocess.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. _SOF_ABI_changes: - -SOF ABI Change Process -###################### - -SOF ABI definitions -******************* - -The SOF ABI consists of public structs used in host-FW communication -defined in: - -- src/include/kernel/ -- src/include/ipc/ -- src/include/user/ - -SOF ABI versioning is defined in firmware source code documentation: -:git-sof-mainline:`src/include/kernel/abi.h` - -Change process -************** - -When a firmware change requires extending or modifying the public -SOF ABI, the developer must go through the ABI change process as defined -in this section. The developer must drive this process, contact the -stakeholders, request reviews (and re-reviews when needed) and coordinate -with the driver maintainers. - -The main steps of the process are depicted in the following -state diagram: - -.. _ABI Change Tracker: https://github.com/orgs/thesofproject/projects/2 - -The pull requests are classified in GitHub using the following -official `ABI Change Tracker`_. - -.. uml:: images/abiprocess.pu - :caption: ABI process state diagram - -When the ABI change is not backwards-compatible, Pull Requests on the -kernel side shall include code that deals with older firmware and -topology files. See :ref:`development_tree` for kernel side -documentation. - -Document modified fields -************************ - -When the interface is extended with a backwards-compatible (MINOR) interface -change, each added or modified interface field must be documented -with a reference to the interface version where the change was -first implemented. - -Some code examples: - -.. code-block:: c - - struct foo { - uint8_t group_id; /**< group ID, 0 means no group (ABI3.17) */ - } __attribute__((packed)); - -.. code-block:: c - - enum bar { - EXT_MAN_ELEM_FOO_DATA = 7, /**< ABI3.18 */ - }; - -ABI change approvers -******************** - -TSC ---- - -Approval from an SOF :ref:`tsc` member is needed for all ABI changes. - -SOF driver ----------- - -Linux driver team approval for changes can be granted by any member of the -SOF Linux driver maintainer team. The current list of members is maintained -in :ref:`sof_drv_maintainer_list`. diff --git a/contribute/process/bug-tracking.rst b/contribute/process/bug-tracking.rst deleted file mode 100644 index 824d9d17..00000000 --- a/contribute/process/bug-tracking.rst +++ /dev/null @@ -1,262 +0,0 @@ -.. _bug_tracking: - -Bug Tracking -############################ -Bug type of issues have a label |label-bug|. - - -.. |label-bug| image:: images/label-bug.png - :scale: 70 - -GitHub issues only have 2 states: open, closed. So *labels* are defined -to assist SOF bug tracking. - -.. contents:: - :local: - :depth: 3 - -Life Cycle of a Bug -********************* -The life cycle of a bug is also the workflow for bugs. Here is a graphic -representation of this life cycle. - -.. image:: images/bug-life-cycle.png - :scale: 80 - -Labels -******** -Please find the labels from https://github.com/thesofproject/sof/labels. - -* *Solution*, *priority* and *platform* labels are common for SOF - firmware, linux kernel driver and tool repositories. - -* *Branch* labels are repository-specific. - -Solution Labels ----------------- -Usually a developer will fix a bug by submitting pull requests. This -is the default solution and so doesn't any solution label. - -Otherwise, **developers** need to add a label |label-invalid|, -|label-duplicate| or |label-won't-fix| to indicate the solution with -justication. - -.. |label-invalid| image:: images/label-invalid.png - :scale: 70 - -.. |label-duplicate| image:: images/label-duplicate.png - :scale: 70 - -.. |label-won't-fix| image:: images/label-will-not-fix.png - :scale: 70 - -Label |label-verified| is only added by the **bug scrub owner** after -reviewing the solution and feedback from QA and bug reporter. - -.. |label-verified| image:: images/label-verified.png - :scale: 70 - - -Priority Labels ------------------ -**Bug scrub owner** should use them to set priority to a bug according -to its impact. - -.. image:: images/label-priorities.png - :scale: 50 - - -Plaform and Branch Labels ----------------------------- -Used by **QA** and **bug reporter**. - -*Platform* labels are used to specify a platform or multiple platforms on -which a bug is observed, e.g. |label-byt|, |label-apl|, |label-glk| ... - -.. |label-byt| image:: images/label-platform-byt.png - :scale: 70 - -.. |label-apl| image:: images/label-platform-apl.png - :scale: 70 - -.. |label-glk| image:: images/label-platform-glk.png - :scale: 70 - -*Branch* labels are used specify a branch or multiple branches on which -a bug is observed, e.g. |label-branch-v1.2|, |label-branch-glk|, -|label-branch-master| ... - - -.. |label-branch-v1.2| image:: images/label-branch-v1-2.png - :scale: 70 - -.. |label-branch-glk| image:: images/label-branch-glk.png - :scale: 70 - -.. |label-branch-master| image:: images/label-branch-master.png - :scale: 70 - -.. note:: - *Platform* labels should always be applied. - - *Branch* labels are usually only applied when the branch is not - the default branch for developing/release on the platform. - - **QA** should *update (add/remove)* platform and branch labels - according to texample-trace-point.pnghe latest bug status. - -Other optional Labels ------------------------ - -Two optional labels can be used to call for attention. - -* |label-blocked| - Blocked by some dependency, whichh applies to either - feature implementation or bug reproduction. - -* |label-need-info| - Further information is requested. - -.. |label-blocked| image:: images/label-blocked.png - :scale: 70 - -.. |label-need-info| image:: images/label-need-info.png - :scale: 70 - -How to Report a Bug -******************** -Please -`create a issue `_ -and apply label |label-bug|. - -And please provide the following information: - -* Title - * The title should be a clear and concise summary of the bug. - - * The title must be unique and descriptive. Bad examples are - "ipc timeout" and "topology failed to load". Ideally the title - should contain keywords from the kernel, firmware, or user space - error message. - - * The title should also contain a prefix indicating the area of - failure e.g. "ipc:", "topology:", "pipeline:" - -* Environment - * Branch name and commit hash of 3 repositories: sof (firmware), - linux (kernel driver) and soft (tools & topology). - - * Name of the topology file - - * Name of the platform(s) on which the bug is observed. - - * Reproducibility Rate. If you can only reproduce it randomly, - it's useful to report how many times the bug has been reproduced - vs. the number of attempts it’s taken to reproduce the bug. - -* Steps to reproduce - * The steps must be precise. And please help to narrow down the steps. - - * Please number the steps from beginning to end so developers can - easily follow through by repeating the same process - -* Expected Result - * Describe what the user should expect. - -* Actual Result - * In contrast to the expected behavior, describe what currently happens. - -* Proof - * Please paste the relevant *dmesg* and *firmware logger data* to the - comment box. The pasted data should contain the actual crash or - error but also the conditions prior to the bug, i.e. also copy the - 10 lines before the crash. - - For firmare boot failure, the pasted dmesg must include the - *trace point* which indicates the progress of firmware boot process: - - |trace-point| - - * Entire kernel message and firmware logger text should also be - attached for reference. - - * If you cannot hear sound for playback or capture, please attach - your amixer settings. If there is a mixer setting seems wrong, - please paste the relevant amixer item in the comment box. - - * For audio quality issues (eg. noise, glitch sound and distortion - etc), it's helpful to - - * play/capture a sine wave, attach the captured wave file with - quality issue. - - *note:* You can - use `Audacity `_ - to `generate a sine wave `_. - Here is the screenshot of a sine wave: - |sine-wav| - - * share the parameters of the sine wave: frequency, sample rate, - format and number of channels. - - * share the waveform screenshot where the glitch/distortion happens - shown by Audacity (> 10ms). - - Here is an example of a sine wave with glitch sound: - |sine-with-glitch| - - Please also zoom in to show the start of the glitch sound, - |start-of-glitch| - - and the end of the glitch. - |end-of-glitch| - -.. |trace-point| image:: images/example-trace-point.png - :scale: 75 - -.. |sine-wav| image:: images/audacity-clean-sine-wave.png - :scale: 75 - -.. |sine-with-glitch| image:: images/audacity-sine-wave-with-glitch.png - :scale: 75 - -.. |start-of-glitch| image:: images/audacity-start-of-glitch.png - :scale: 60 - -.. |end-of-glitch| image:: images/audacity-end-of-glitch.png - :scale: 60 - -.. note:: - If you have multiple issues, please file them separately so they can - be tracked more easily. - - Please use `markdown `_ - for formatting example commands, code, diffs, patches etc. - -How to Close a Bug -******************** - -* For bugs fixed by pull requests - - *Developers* can use - `keywords `_ - to close one or multiple bugs via pull requests automatically. - - *Developers* can also leave the bug open, and *QA* should close the - bug if it cannot be reproduced after verification. - -* For bugs with label |label-invalid| or |label-won't-fix|, - *develpers* should close them with justification. - -* For bugs with label |label-duplicate|, - please keep the bug open until its duplicate is resolved and closed. - -.. note:: - After the pull request(s) is merged, *developer* should always - **@** *bug reporter* and **@** *QA engineer* who tracks this bug - to verify the solution. - - Usually the right QA engineer is the bug reporter or who updates the - bug status in the comment box. If you don't know who is the QA - engineer, please **@** *bug scrub owner*. - -.. _reStructuredText: http://sphinx-doc.org/rest.html -.. _Sphinx: http://sphinx-doc.org/ diff --git a/contribute/process/docbuild.rst b/contribute/process/docbuild.rst deleted file mode 100644 index 606375cd..00000000 --- a/contribute/process/docbuild.rst +++ /dev/null @@ -1,432 +0,0 @@ -.. _sof_doc: - -SOF Documentation Generation -############################ - -These instructions will walk you through generating the SOF Project's -documentation and publishing it to https://thesofproject.github.io. -You can also use these instructions to generate the SOF documentation -on your local system. - -Documentation overview -********************** - -The SOF Project content is written using the reStructuredText markup -language (``.rst`` file extension) with Sphinx extensions, and processed -using Sphinx to create a formatted standalone website. As a developer, you -can view this content either in its raw form as ``.rst`` markup files, or you -can generate the HTML content and view it with a web browser directly on -your workstation. - -Read details about `reStructuredText`_, and `Sphinx`_ from -their respective websites. - -The project's documentation contains reStructuredText source files used to -generate documentation found at the http://thesofproject.github.io website. -All of the reStructuredText sources are found in the thesofproject/sof-docs -`repo`_. - -The reStructuredText files are processed by the Sphinx documentation system, -and make use of the breathe extension for including the doxygen-generated API -material. - - -Set up documentation working folders -************************************ - -You must install git to set up the working folders: - -* For an Ubuntu development system use: - - .. code-block:: bash - - sudo apt-get install git - -* For a Fedora development system use: - - .. code-block:: bash - - sudo dnf install git - -* For a Windows development system, download and install Git manually from - the https://git-scm.com/download/win website. - -We use github.io for publishing the generated documentation. The recommended -folder setup for documentation contributions and generation is as follows: - -.. code-block:: console - - thesofproject/ - sof/ - sof-docs/ - -The parent ``thesofproject`` folder is present because we use the -publishing area (``thesofproject.github.io``) later in these steps. It's -best if the ``sof-docs`` folder is an ssh clone of your personal fork of the -upstream project repos (although https clones also work): - -#. Use your browser to visit https://github.com/thesofproject and do a - fork of the ``sof-docs`` repo to your personal GitHub account.) - - .. image:: images/fork-sof-docs.png - -#. At a command prompt, create the working folder and clone the sof-docs - repository to your local computer (and if you have publishing rights, the - thesofproject.github.io repo). If you don't have publishing rights, - can still generate the docs locally but not publish them: - - .. code-block:: bash - - cd ~ - mkdir thesofproject && cd thesofproject - git clone git@github.com:/thesofproject/sof-docs - -#. The documentation of the SOF source code generated by doxygen is referenced and included by the ``sof-docs``. Clone the ``sof`` repository, too: - - .. code-block:: bash - - git clone git@github.com:thesofproject/sof - -#. For the cloned local repos, tell git about the upstream repo: - - .. code-block:: bash - - cd sof-docs - git remote add upstream git@github.com:thesofproject/sof-docs - -#. If you haven't done so already, be sure to configure git with your name - and email address for the signed-off-by line in your commit messages: - - .. code-block:: bash - - git config --global user.name "David Developer" - git config --global user.email "david.developer@company.com" - -Install documentation tools -*************************** - -Our documentation processing has been tested to run with: - -* Python 3.6.3 -* Doxygen version 1.8.13 -* Sphinx version 1.7.5 -* Breathe version 4.9.1 -* docutils version 0.14 -* sphinx_rtd_theme version 0.4.0 - -The SOF documentation makes use of additional Sphinx extensions used for -creating drawings: - -* sphinxcontrib-plantuml -* sphinx.ext.graphviz (included with Sphinx) - -.. note:: The ``scripts/plantuml.jar`` extension uses Java to render the UML - drawing syntax into an image. You need to have a Java runtime environment - (JRE) installed when generating documentation. - -There is a sof-docs Docker image recipe that can be used as an alternative to -installing the documentation tools on local OS. If you choose to use Docker then -please skip the tools installation steps and go directly to -:ref:`run_documentation_processors` - -Depending on your Linux version, install the following tools: - -* For Ubuntu use: - - .. code-block:: bash - - sudo apt-get install doxygen python3-pip python3-wheel make \ - default-jre graphviz cmake ninja-build - -* For Fedora use: - - .. code-block:: bash - - sudo dnf install doxygen python3-pip python3-wheel make \ - java graphviz cmake ninja-build - -For either Linux environment, install the remaining python-based -tools: - -.. code-block:: bash - - cd ~/thesofproject/sof-docs - pip3 install --user -r scripts/requirements.txt -c scripts/constraints.txt - -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.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 - 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 - - PIP_IGNORE_INSTALLED=0 pip3 install --user -r scripts/requirements-lax.txt - - -For Windows, install the needed tools manually: - -* Python (3.7+) from https://www.python.org/downloads/ - -* Python package installer (pip) from https://pip.pypa.io/en/stable/installing/ - -* Doxygen from http://www.doxygen.nl/download.html - -* GraphViz from https://graphviz.gitlab.io/ - -* Ninja from https://github.com/ninja-build/ninja/releases - -* CMake (3.10+) from https://cmake.org/install/ - -* Make - if you do not already have make, install it using MSYS2 from https://www.msys2.org/. Use the following command: - - .. code-block:: bash - - pacman -S make - -.. note:: - Make sure that installed executable files are in your path. If not, - manually add the paths to the PATH variable. - -For Windows, install the remaining python-based tools as previously -described for Linux: - -.. code-block:: bash - - cd \thesofproject\sof-docs - pip3 install --user -r scripts\requirements.txt - - -You are ready to generate the documentation. - -Documentation presentation theme -******************************** - -Sphinx supports easy customization of the generated documentation -appearance through the use of themes. Replace the theme files and do -another ``make html`` and the output layout and style is changed. -The ``read-the-docs`` theme is installed as part of the -``requirements.txt`` list above. - -.. _run_documentation_processors: - -Run documentation processors -**************************** - -The sof-docs directory contains all the .rst source files, extra tools, and -Makefile for generating a local copy of the SOF technical documentation. - -You can generate the HTML documentation by using local build tools (1) or by -Docker image (2) - -1. Generate the HTML output by using the following commands (**local build**): - - .. code-block:: bash - - cd thesofproject - # API documentation (Doxygen) - 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 - -Depending on your system, the last command may need a few minutes to run - -but only the first time. Most of the time is spent generating UML -diagrams. When done, view the HTML output with your browser, starting at -``~/thesofproject/sof-docs/_build/html/index.html`` - -If your changes are not related to any UML diagram, you can build more -than 10 times faster from scratch by temporarily changing the -``plantuml_output_format`` line in :git-sof-docs-mainline:`conf.py`. - -2. Generate the HTML output by using the following commands (**Docker build**): - - .. code-block:: bash - - cd thesofproject - # Build both sof (Doxygen) and sof-docs UML and reStruredText - ./sof-docs/scripts/docker_build/docker-build.sh - -The docker build script will copy the sof and sof-docs source code from host -working directory to image, build the documentation and when completed copy back -output to the host (./sof-docs/_build) - -The first docker build run will take more time due to image creation and -installation of all the necessary build tools. Each next build is much faster -and can additionally be speed up by selecting only sof-docs to build: - - .. code-block:: bash - - cd thesofproject - # Re-build only sof-docs - ./sof-docs/scripts/docker_build/docker-build.sh docs - -Publish content -*************** - -If you have merge rights to the ``thesofproject repo`` called -``thesofproject.github.io``, you can update the public project documentation -found at https://thesofproject.github.io. - -You must perform a one-time clone of the upstream repo (we publish -directly to the upstream repo rather than to a personal forked copy): - -.. code-block:: bash - - cd ~/thesofproject - git clone git@github.com:thesofproject/thesofproject.github.io - -After you have verified that the generated HTML from ``make html`` looks -good, you can push directly to the publishing site using this command: - -.. code-block:: bash - - make publish - -This will delete everything in the publishing repo's **latest** folder (in -case the new version has deleted files) and push a copy of the -newly-generated HTML content directly to the GitHub pages publishing repo. -The public site at https://thesofproject.github.io will be updated within a -few minutes so it's best to verify the locally-generated html before -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 -C sof-docs clean`` command. - -Installation troubleshooting -**************************** - -In some cases, after you run ``make html``, the documentation processors might return the following errors: - -.. code-block:: console - - Warning: sphinx_rtd_theme missing. Use pip to install it. - Extension error: - Could not import extension breathe (exception: No module named breathe) - Makefile:36: recipe for target 'html' failed - make: *** [html] Error 1 - -The issue could be related to the default policy on Debian-based Linux -distributions (i.e. Ubuntu) that links Python commands to Python 2.7.x. You -can verify this by entering the following steps: - -.. code-block:: bash - - python --version - - Python 2.7.15rc1 - - ll /usr/bin/python - - lrwxrwxrwx 1 root root 9 sie 29 07:36 /usr/bin/python -> python2.7* - -The issue can be resolved by running a dedicated environment with the Python -3.x binary and include its own set of installed Python packages. -Virtualization of the Python environment is recommended as an alternative to: - -* adding an alias setup in ~/.bashrc -* changing the symbolic link (/usr/bin/python) -* modifying the default system behavior using update-alternatives - -Start with installing virtualization support. As a next step, activate the -virtualized environment: - -.. code-block:: bash - - apt-get install python3-venv - python3 -m venv my-sof-env - . ./my-sof-env/bin/activate - python --version - - - Python 3.6.7 - -Verify the Python version and proceed with installing all required -Python packages in the virtualized environment: - -.. code-block:: bash - - pip install sphinx - git clone https://github.com/thesofproject/sof - git clone https://github.com/thesofproject/sof-docs - cd sof-docs/ - pip install -r scripts/requirements.txt - -After the installation is finished, you should be able to generate -documentation by invoking commands listed in **Running the documentation -processors**. - -To deactivate the virtual environment and original Python environment, type: - -.. code-block:: bash - - deactivate - -Further information on how to use lightweight Python virtualization -environments can be found at https://docs.python.org/3/library/venv.html. - -Windows troubleshooting -*********************** - -It is possible that the ``cmake`` command may not be accessible from the MSYS2 shell: - -.. code-block:: console - - cmake -GNinja . - bash: cmake: command not found - -The problem may be due to the MSYS2 PATH missing the cmake installation -folder. If the cmake works correctly from the Win Command Prompt then edit -the msys2_shell.cmd and check if a PATH inherit option is enabled: - -.. code-block:: bash - - set MSYS2_PATH_TYPE=inherit - - -Another issue that may occur is the ``sphinx-build`` command not found: - -.. code-block:: bash - - make html - make: sphinx-build: Command not found - make: *** [Makefile:36: html] Error 127 - -If the above error occurs both in the Win Command Prompt and in the MSYS2 -shell then the python sphinx package needs to be updated: - -.. code-block:: bash - - pip install -U sphinx - -Diagram compilation troubleshooting -*********************************** - -If you are creating a diagram that is using the lastest features of -plantuml, you may encounter the following compilation error: - -.. code-block:: console - - WARNING: error while running plantuml - b'ERROR\n2\nSyntax Error?\nSome diagram description contains errors\n' - -If you excluded syntax errors in the diagram description, one of remaining -possibilities is lack of compatibility with the installed plantuml.jar -version. You can verify it using the following command: - -.. code-block:: bash - - java -jar ./scripts/plantuml.jar -version - -If the installed version of plantuml.jar is missing necessary features, -submit a pull request to the SOF documentation repository with a new one. - - -.. _reStructuredText: http://sphinx-doc.org/rest.html -.. _Sphinx: http://sphinx-doc.org/ -.. _repo: https://github.com/thesofproject/sof-docs diff --git a/data/sof_bin_releases.json b/data/sof_bin_releases.json index 2b48bc28..95d46b51 100644 --- a/data/sof_bin_releases.json +++ b/data/sof_bin_releases.json @@ -2,6 +2,7 @@ { "tag_name": "v2025.12.2", "name": "v2025.12.2", + "fw_version": "v2.14.3", "published_at": "2026-01-27", "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.12.2", "asset_name": "sof-bin-2025.12.2.tar.gz", @@ -12,6 +13,7 @@ { "tag_name": "v2025.12.1", "name": "v2025.12.1", + "fw_version": "v2.14.2", "published_at": "2026-01-22", "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.12.1", "asset_name": "sof-bin-2025.12.1.tar.gz", @@ -22,6 +24,7 @@ { "tag_name": "v2025.12", "name": "v2025.12", + "fw_version": "v2.14", "published_at": "2025-12-19", "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.12", "asset_name": "sof-bin-2025.12.tar.gz", @@ -32,6 +35,7 @@ { "tag_name": "v2025.05.1", "name": "v2025.05.1", + "fw_version": "v2.13.1", "published_at": "2025-08-19", "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.05.1", "asset_name": "sof-bin-2025.05.1.tar.gz", @@ -42,6 +46,7 @@ { "tag_name": "v2025.05", "name": "v2025.05", + "fw_version": "v2.13", "published_at": "2025-06-13", "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.05", "asset_name": "sof-bin-2025.05.tar.gz", @@ -52,6 +57,7 @@ { "tag_name": "v2025.01.1", "name": "v2025.01.1", + "fw_version": "v2.12.1", "published_at": "2025-03-31", "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.01.1", "asset_name": "sof-bin-2025.01.1.tar.gz", @@ -62,6 +68,7 @@ { "tag_name": "v2025.01", "name": "v2025.01", + "fw_version": "v2.12", "published_at": "2025-01-31", "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2025.01", "asset_name": "sof-bin-2025.01.tar.gz", @@ -72,6 +79,7 @@ { "tag_name": "v2024.09.2", "name": "v2024.09.2", + "fw_version": "v2.11.3", "published_at": "2024-12-05", "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2024.09.2", "asset_name": "sof-bin-2024.09.2.tar.gz", @@ -82,6 +90,7 @@ { "tag_name": "v2024.09.1", "name": "v2024.09.1", + "fw_version": "v2.11.1", "published_at": "2024-11-08", "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2024.09.1", "asset_name": "sof-bin-2024.09.1.tar.gz", @@ -92,6 +101,7 @@ { "tag_name": "v2024.09", "name": "v2024.09", + "fw_version": "v2.11.1", "published_at": "2024-09-27", "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2024.09", "asset_name": "sof-bin-2024.09.tar.gz", @@ -102,6 +112,7 @@ { "tag_name": "v2024.06", "name": "v2024.06", + "fw_version": "v2.10", "published_at": "2024-07-18", "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2024.06", "asset_name": "sof-bin-2024.06.tar.gz", @@ -112,6 +123,7 @@ { "tag_name": "v2024.03", "name": "v2024.03", + "fw_version": "v2.9", "published_at": "2024-04-02", "html_url": "https://github.com/thesofproject/sof-bin/releases/tag/v2024.03", "asset_name": "sof-bin-2024.03.tar.gz", diff --git a/developer_guides/add_new_arch.rst b/developer_guides/add_new_arch.rst deleted file mode 100644 index b0ba708c..00000000 --- a/developer_guides/add_new_arch.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _add_new_arch: - -Adding a new DSP architecture to SOF -==================================== - -This is not yet a guide for architecure porting, but in general, you can add -support for a new DSP architectures to SOF in the following two ways: - -- Write a new Hardware Abstraction Layer (HAL) for your DSP. -- Use an existing RTOS that supports your DSP architecture as a HAL for SOF. - -Both methods require a working compiler for the new DSP architecture and -preferrably an emulation environment or hardware debugger to help with the -bringup and debug. - -Method 1 - New HAL ------------------- - -The main work in adding the new architecture HAL is duplicating and porting the -src/arch directory to your new architecture. The code in the architecture -directory mainly deals with architecture abstraction and initialization of any -architecture IP like MMU, IRQs and caches alongside providing optimized -versions of some common C functions (memcpy, memset, etc) for that architecture. -Adding a new architecture also usually means adding a new host platform too. - -Method 2 - Use existing RTOS ----------------------------- - -This method involves creating a HAL by wrapping the RTOS functions used by SOF -as thinly as possible (i.e. to compile out). It also means removing unused code -from the SOF build in order to use the RTOS version if desireable i.e. -allocator, schedulers, messaging etc. The final stage is to link the SOF audio -code to the RTOS. diff --git a/developer_guides/debugability/index.rst b/developer_guides/debugability/index.rst index ed686043..cb81c3e2 100644 --- a/developer_guides/debugability/index.rst +++ b/developer_guides/debugability/index.rst @@ -7,7 +7,6 @@ Debugability :maxdepth: 1 traces/index - logger/index coredump-reader/index probes/index ri-info/index diff --git a/developer_guides/debugability/logger/index.rst b/developer_guides/debugability/logger/index.rst deleted file mode 100644 index 17e41d1c..00000000 --- a/developer_guides/debugability/logger/index.rst +++ /dev/null @@ -1,274 +0,0 @@ -.. _dbg-logger: - -Logger -###### - -The sof-logger is used to print logs delivered from the FW `dma_trace` -mechanism by searching log entries in the `ldc` file (logs dictionary) -that are generated by the *SMEX* (Sof Metadata Extractor) tool. Every entry -declared in the FW is placed in an elf output file (e.g. sof-apl) in the -`.static_log_entries` section in a struct form that is defined in `sof/src/include/sof/trace.h` in the `sof` fw repo. - -The `ldc` file contains `snd_sof_logs_header` and `snd_sof_uids_header` -(defined in smex/ldc.h). `snd_sof_logs_header` is followed by a -`.static_log_entries` section incorporated from the FW elf file (e.g. -sof-apl). `snd_sof_logs_header` contains basic information about the -`.static_log_entries` section such as `base_address` and `data_length`. The -sof-logger works by reading entry parameters values and entries addresses from the FW `dma_trace` mechanism and searching for suitable entries in the -`ldc` file by its address. The `snd_sof_uids_header` struct is followed by -the `.static_uuid_entries` section content from the FW elf file. A single -uuid entry is defined in `sof/src/include/sof/lib/uuid.h` in the `sof` fw -repo. - -Logger usage -************ - -Usage sof-logger - --h help --l ldc_file Specify the ldc file (debugging information and strings) --i in_file Get traces from the in_file instead of from the default "/sys/kernel/debug/sof/etrace" --o out_file Specify the output file instead of the default stdout --t Get traces from "/sys/kernel/debug/sof/trace" instead of from the default "/sys/kernel/debug/sof/etrace" --p Get traces from stdin instead of the default "/sys/kernel/debug/sof/etrace" --c clock Set the timestamp clock in MHz --n Disable checking the firmware version with the default verification file "/sys/kernel/debug/sof/fw_version" --v ver_file Enable checking the firmware version with the ver_file file instead of the default: "/sys/kernel/debug/sof/fw_version" --s Take a snapshot of state --r Less formatted output for chained log processors --L Hide log location in source code --f precision Set timestamp precision --g Hide timestamp --d Dump ldc information --F filter Update trace filtering - -Examples --------- - -- Gets traces from the "/sys/kernel/debug/sof/etrace" file; disable compatibility - check between given ldc_file with fw_version saved in default location - and prints logs to stdout - - .. code-block:: bash - - sof-logger -l ldc_file -n - -- Gets traces from the "/sys/kernel/debug/sof/etrace" file; verifies the - fw_version with the ver_file file and prints logs to stdout - - .. code-block:: bash - - sof-logger -l ldc_file -v ver_file - -- Get traces from the "/sys/kernel/debug/sof/etrace" file and prints logs to - stdout - - .. code-block:: bash - - sof-logger -l ldc_file - -- Get traces from the "/sys/kernel/debug/sof/etrace" file and prints logs to - the out_file file - - .. code-block:: bash - - sof-logger -l ldc_file -o out_file - -- Get traces from the "/sys/kernel/debug/sof/trace" file and prints logs to - stdout - - .. code-block:: bash - - sof-logger -l ldc_file -t - -- Get traces from the "/sys/kernel/debug/sof/trace" file and prints logs to - the out_file file - - .. code-block:: bash - - sof-logger -l ldc_file -t -o out_file - -- Get traces from stdin and prints logs to stdout - - .. code-block:: bash - - sof-logger -l ldc_file -p - -- Get traces from stdin and prints logs to the out_file file - - .. code-block:: bash - - sof-logger -l ldc_file -p -o out_file - -- Get traces from the trace_dump file and prints logs to stdout - - .. code-block:: bash - - sof-logger -l ldc_file -i trace_dump - -- Get traces from the trace_dump file and prints logs to the out_file file - - .. code-block:: bash - - sof-logger -l ldc_file -i trace_dump -o out_file - -- c flag defines the clock value (in MHz) used to format log timestamps. By - default, the clock value is set to 19.2 (MHz). The below example sets the - clock value to 19.9 (MHz). - - .. code-block:: bash - - sof-logger -l ldc_file -i trace_dump -o out_file -c 19.9 - -- Dump information from the ldc file (such as the ABI version and the uuid - dictionary) to stdout - - .. code-block:: bash - - sof-logger -l ldc_file -d - - -.. note:: - debugfs files used by sof-logger: - - - ``etrace``: direct access to the shared TRACE window of the SOF firmware - - ``trace``: using DMA to stream debug trace information from SOF firmware (on - distribution kernels ``sof_debug=1`` module option for ``snd_sof`` might be - needed if the /sys/kernel/debug/sof/trace file is not present) - -.. note:: - If sof-logger is started (or restarted) while firmware is active, the initial - trace messages might be incomplete. This can happen as current (as of SOF version - 1.9) trace is implemented with a ringbuffer between firmware and the kernel driver. - When sof-logger is started, kernel will always start to read the ringbuffer from - 0 position, independently of firmware state. If firmware write pointer just wrapped - around when sof-logger is started, sof-logger will only show the traces after - the wrap. Firmware write position is also reset whenever firmware is booted, - including runtime suspend and resume. To capture traces over runtime suspend - events, the kernel trace interface will signal end of file at runtime suspend. - When sof-logger notices the end of file marker, it will reopen the trace - file and start reading from position 0 and thus be in sync with the firmware - when it is resumed. - - Sometimes error messages about dropped logs are printed. If that is a problem, - increasing DMA_TRACE_LOCAL_SIZE in the relevant platform.h file can be helpful. - -Trace filtering -*************** - -Current log levels can be changed for any instance of a component at -runtime. To do so, use the `-F` option and the following argument format: - - ="[, ]" - -Where ** can be one of the following: - -- ``c`` / ``critical`` -- ``e`` / ``error`` -- ``w`` / ``warning`` -- ``i`` / ``info`` -- ``d`` / ``debug`` -- ``v`` / ``verbose`` - -After the **=** character, all components are listed in a comma-separated -format. Each component begins with *name* followed by an optional *instance* -description. - -The list of possible component names comes from the UUID declaration. -Refer to the :ref:`uuid-api` for more detailed information. Use the ``-d`` -flag in the logger to list component names from the ``ldc`` file content. - -Example output: - - .. code-block:: bash - - $./sof-logger -d log/sof-cnl.ldc - logger ABI Version is 5:2:0 - ldc_file ABI Version is 5:2:0 - - Components uuid dictionary size: 824 bytes - Components uuid base address: 0x1FFFA000 - Components uuid entries: - ADDRESS UUID NAME - 0x1FFFA000 <8b9d100c-6d78-418f-90a3-e0e805d0852b> host - 0x1FFFA01C pipe-task - 0x1FFFA03C <34dc0385-fc2f-4f7f-82d2-6cee444533e0> volume-task - 0x1FFFA05C volume - 0x1FFFA078 src - 0x1FFFA134 dai - -------------------------------------------------- cnt: 6 - -A special wildcard - ``*`` - can be used to apply a given trace level to -each component. - -Instance descriptions can have one of the following forms: - -- ``*`` - each component instance -- ``X.*`` - each component on selected pipeline *X* -- ``X.Y`` - component on pipeline *X* with id *Y* - -Trace level changes work in the same order as options given in a command line, and a new set overwrites old values. -It allows you to easily enable verbose logs only for selected components and keep the lowest possible log level (critical) for -others, as shown in the following example: - - sof-logger -l ldc_file -t -Fcritical=* -Fverbose="dai*, volume1.1" - -A similar example may be prepared for components on a particular pipeline: - - sof-logger -l ldc_file -t -Fc=* -Fv=*1.* - -Verbose and debug log levels ----------------------------- - -To enable verbose and debug trace messages, select the "Trace->Trace verbose" option in the firmware build -menuconfig (in addition to setting the proper log levels as described above). - -Disabling DSP power gating --------------------------- - -After a firmware reset (such as after power gating in suspend mode) custom filter settings will be lost. -Thus consider disabling power gating during your debug session. The way this is done is slightly different on every platform, -two examples follow: - -1. Intel PCI based: - -.. code-block:: bash - - sudo su - echo on >/sys/devices/pci0000\:00/0000\:$(lspci -nn | grep "audio contoller" | awk '{print $1;}')/power/control - -2. NXP imx8mp: - -.. code-block:: bash - - sudo su - echo on>/sys/class/devlink/platform:power-domains:audiomix-pd--platform:3b6e8000.dsp/consumer/power/control - -To re-enable automatic suspend use ``echo auto``, the current status can be read from the runtime_status file in these sysfs directories. - -Trace filtering details ------------------------ - -* The filtering mechanism occurs on the firmware side so, after changing the - log level to verbose for each component, the DSP can be overwhelmed by - tracing. - -* Core functionality is provided by the DSP, so filtering does not work in - offline mode - during conversion in a previously saved input file. - -* The trace filtering affects only traces sent after the filter setup, - so traces already stored on the kernel side are not affected. If a certain log level is needed before a filter has been setup the DECLARE_TR_CTX() - macro at the beginning of the respective component's source file can be adapted. - -* Filters are set up incrementally, so when loggers are run twice with - different settings, then filters from the first run will not be restored to - the default state but will be replaced by a new one. Active trace filters are stored in the firmware runtime memory. To reset the filters to the - default state, a firmware reset is needed. - -* Communication between the firmware and logger occurs through the kernel debugfs. The logger writes new trace settings to ``sys/kernel/debug/sof/filter``. - These will be used to create *IPC* messages with new trace levels. A simple text data format is used: - - ``log1_level uuid1_id pipe1_id comp1_id; [log2_level uuid2_id pipe2_id comp2_id;]\n`` - - Any unused uuid_id should be set here to 0; other unused fields should be - set to -1. ``log_level`` must always be set to a valid value that represents ``LOG_LEVEL_*`` defined values. diff --git a/developer_guides/firmware/async_messaging_best_practices.rst b/developer_guides/firmware/async_messaging_best_practices.rst deleted file mode 100644 index efc49c1b..00000000 --- a/developer_guides/firmware/async_messaging_best_practices.rst +++ /dev/null @@ -1,651 +0,0 @@ -.. _async_messaging_best_practices: - -Async Messaging Best Practices -############################## - -This section provides best practices and point out issues that developers should -be aware of when using asynchronous messages in their components. - -Message Type IDs -**************** - -The only unique value that is guaranteed to not change is UUID. The message type -IDs can change every time when a component is registering as a message -consumer/producer. In fact it depends on initialization order of components and -it may seem to be static. However it can change i.e. with addition of a new -component to pipeline and the entire mechanism will stop working. - -The components must not hardcode this value and they must use a runtime value of -component instance ID returned during producer/consumer registration. - -.. _message_handling: - -Message Handling -**************** - -The asynchronous messages consumers must be prepared to handle the messages -asynchronously. A message can be received while a component is processing data -and it can lead to undefined behavior when internal state is changed -immediately. The recommended way of handling asynchronous messages is to save a -message and apply the changes during a next processing time i.e. at the -beginning of processing. - -- When a processing of asynchronous message is done at the beginning of - component processing (Process Data), only then component processing is - deterministic. - -If an asynchronous message cannot be processed immediately by a consumer, it is -a good practice to implement a queue of incoming asynchronous messages in a -component or at least count asynchronous messages since last processing to -detect this kind of situation. - -A consumer component cannot assume that it can save a message pointer and -dereference is later. The message memory is released as soon as Asynchronous -Messaging Service will finish processing, so a consumer component must copy a -content of asynchronous message. - -Example - the pseudo code on a consumer side: - -.. code:: cpp - - queue_t request_queue; - - struct request_t { - uint8_t new_state; - }; - - struct message_context_t { - int32_t error; - queue_t *request_queue; - }; - - message_context_t message_context; - - void callback(const ams_message_payload_s * const ams_message_payload, void *ctx) { - if(ams_message_payload->message_length != sizeof(request_t)) { - ((message_context_t *)ctx)->error = 1; - return; - } - - queue_push(((message_context_t *)ctx)->request_queue, (request_t *)(ams_message_payload->message)); - } - - error_code componentA::Init(Pipeline* parent_ppl, const ModuleACfg* cfg) { - //getting Message Type ID - error = am_service_get_message_type_id(MESSAGE_A, &message_type_id); - if(error != 0) { - //error handling - } - - //registering consumer - message_context.error = 0; - message_context.request_queue = &request_queue; - error = am_service_register_consumer(message_type_id, GetcomponentID(), GetInstanceID(), callback, &message_context); - if(error != 0) { - //error handling - } - } - - error_code componentA::ProcessData(size_t max_output_data_size, uint32_t* custom_error_code) { - while(queue_size(message_context.request_queue) > 0) { - if(message_context.error != 0) { - //error handling - } - - request_t *r = queue_pop(message_context.request_queue); - //handling of async message - process_request(r); - } - - //regular processing - } - -.. _processing_in_a_consumer_callback: - -Processing in a consumer callback -********************************* - -The consumer callbacks must not do any heavy processing. Best if the callback -only saves information and a component will process it in the next processing -slot. - -- The asynchronous message callbacks are called in the context of a message - producer or in the context of IDC task. -- If a heavy processing is done in a message, then a producer MPCS or IDC task - budget needs to take into account this heavy processing. While it may be - possible to take into account additional budget for simple cases, it is - impossible to accommodate MCPS requirements in the general case (i.e. large - number of consumers with heavy processing). - -The example described in :ref:`message_handling` is also applicable for this issue. - -.. _message_filtering_mechanism: - -Message Filtering Mechanism -*************************** - -1. If a consumer is interested in async messages from one particular producer, - it needs to register for that particular producer using component ID and - instance ID. A component ID and instance ID of producer should be passed as - ``LARGE_CONFIG_SET`` parameter to the consumer. -2. If a producer wants to target a specific component instance, then it should - use send function that is parametrized with component ID and instance ID. - -Passing Pointers In Asynchronous Messages -***************************************** - -The asynchronous messages do not prevent to pass pointers between components. It -seems like a good idea at the beginning when a developer wants to return a -result. While it is simple solution, it may lead into the following issues: - -- there can be more than one consumer of a message and each of them needs to - have an allocated slot in the memory, -- the firmware framework cannot guarantee that component memory will be still - available when async message is processed i.e. a component can be subject of - firmware paging and the firmware infrastructure can decide to evict component - memory, - -The recommended method is to not pass pointers in the asynchronous messages. - -One-way Messages -**************** - -The asynchronous messages are one-way messages and there is no explicit feedback -whether a message was received or processed. The ``send`` functions return only -information whether the async messaging service return an error. - -Two-way Messages - Example #1 -***************************** - -The asynchronous messages are One-way Messages. Sometimes there is a need to -implement “function call” like functionality where a component instance wants -another component instance to take an action and return a result. This -functionality should be implemented with following issues in mind: - -- the result will not be returned immediately - :ref:`message_handling`, -- avoiding heavy processing in a consumer callback - :ref:`processing_in_a_consumer_callback`, -- 1:1 vs. M:N communication - :ref:`message_filtering_mechanism`, -- blocking vs. non-blocking execution: - - - If a producer depends on a result, it has to be handled as a blocking call - and the producer has to block its execution until result is received. To - do that, a blockade should be used when ``send`` functions return. - - - the task blockade must be removed when a result is received (in a - result callback), it will allow to continue a component execution, - - when the task blockade is set, the component execution is preempted and - the component with the highest priority is called, - -- one vs. two messages for handling action and result - - - the “function call” can be implemented as two separate messages: one for - triggering action from component A to component B and then second one for - passing result from component B to component A, it increases amount of - asynchronous messages, - - the recommended way is to implement it as one asynchronous message where - component A and B are both consumer and producer of the same asynchronous - message - - - it is important to note that filtering mechanism must be used to break - recursion - component A must discard a message from itself, - -Example - 1:1 function call: - -Consumer (component instance A) code: - -.. code:: cpp - - uint32_t message_type_id; - - queue_t request_queue; - - struct message_context_t { - int32_t error; - queue_t *request_queue; - }; - - message_context_t message_context; - - queue_t request_queue; - - struct request_t { - uint8_t message_type; //1 - request, 2 - response - uint8_t new_state; - }; - - void consumer_callback(const ams_message_payload_s * const payload, void *ctx) { - if(payload->message_length != sizeof(request_t)) { - ((message_context_t *)ctx)->error = 1; - return; - } - - //only requests are supported by a consumer - if((request_t *)(payload->message)->message_type != 1) { - ((message_context_t *)ctx)->error = 2; - return; - } - - queue_push(((message_context_t *)ctx)->request_queue, (request_t *)(payload->message)); - } - - error_code componentB::Init(Pipeline* parent_ppl, const ModuelCfg* cfg) { - //getting Message Type ID - error = am_service_get_message_type_id(MESSAGE_A, &message_type_id); - if(error != 0) { - //error handling - } - - //registering consumer - message_context.error = 0; - message_context.request_queue = &request_queue; - error = am_service_register_consumer_mi(message_type_id, GetcomponentID(), GetInstanceID(), component_A_id, component_A_instance_id, callback, &message_context); - if(error != 0) { - //error handling - } - } - - error_code componentB::ProcessData(size_t max_output_data_size, uint32_t* custom_error_code) { - while(queue_size(request_queue) > 0) { - if(message_context.error != 0) { - //error handling - } - - request_t *r = queue_pop(request_queue); - - //handling of async message - process_request(r); - - //message response - request_t response; - response.message_type = 2; - - error_code error = am_service_send_mi(message_type_id, GetcomponentID(), GetInstanceID(), component_A_id, component_A_instance_id, sizeof(request_t), &response); - if(e != 0) { - //error handling - } - } - - //regular processing - } - -Producer code: - -.. code:: cpp - - uint32_t message_type_id; - - queue_t request_queue; - - struct message_requestor_context_t { - int32_t error; - queue_t *request_queue; - uint32_t blockade; - }; - - message_requestor_context_t message_context; - - struct request_t { - uint8_t message_type; //1 - request, 2 - response - uint8_t new_state; - }; - - void consumer_callback(const ams_message_payload_s * const payload, void *ctx) { - if(payload->message_length != sizeof(request_t)) { - (message_requestor_context_t *)ctx->error = 1; - return; - } - - //only responses are supported by a producer - if((request_t *)(payload->message)->message_type != 2) { - (message_requestor_context_t *)ctx->error = 2; - return; - } - - queue_push(((message_context_t *)ctx)->request_queue, (request_t *)(payload->message)); - (message_requestor_context_t *)ctx->blockade = 0; //unblock a producer component execution - } - - error_code componentA::Init(Pipeline* parent_ppl, const ModuleACfg* cfg) { - //getting Message Type ID - error = am_service_get_message_type_id(MESSAGE_A, &message_type_id); - if(error != 0) { - //error handling - } - - //registering consumer - message_context.error = 0; - message_context.blockade = 0; - message_context.request_queue = &request_queue; - error = am_service_register_consumer_mi(message_type_id, GetcomponentID(), GetInstanceID(), component_B_id, component_B_instance_id, callback, &message_context); - if(error != 0) { - //error handling - } - - //registering as a producer - error = am_service_register_producer(message_type_id); - if(error != 0) { - //error handling - } - } - - error_code componentA::ProcessData(size_t max_output_data_size, uint32_t* custom_error_code) { - ... - SystemServiceInternal const* services = get_system_services(); - ... - //message request - request_t response; - response.message_type = 1; - - message_context.blockade = 1; //initialize blockade - error_code error = am_service_send_mi(message_type_id, GetcomponentID(), GetInstanceID(), component_B_id, component_B_instance_id, sizeof(request_t), &response); - if(e != 0) { - //error handling - } - - //block a component execution until a consumer will reply with a result - _AdspCurrentTaskBlockade blockade; - services->SetTaskRunCondition(&blockade, (uint32_t*)(&message_context.blockade), 0 /*unblocking value*/, 0xffffffff); - services->RemoveTaskRunCondition(&blockade); - - while(queue_size(request_queue) > 0) { - if(message_context.error != 0) { - //error handling - } - - request_t *r = queue_pop(request_queue); - - //handling of async message - process_request(r); - } - ... - //regular processing - } - -Two-way Messages - Example #2 -***************************** - -The below example shows a real use case where multiple control interfaces are -supported (IPC and I2C). Control application needs to produce an async message -and when async message response is received, it needs to respond to the correct -requestor IPC vs. I2C. To make it happen, the unique async message ID needs to -be introduced. The unique ID can be generated globally or locally when source -component is tracked. In the below pseudo-code, the ID is generated locally and -component B needs to respond to the correct component. - -Example - 1:1 function call: - -Consumer (component instance B) code: - -.. code:: cpp - - uint32_t message_request_id; - uint32_t message_response_id; - uint32_t current_state; - - queue_t request_queue; - queue_t requestor_info_queue; - - struct unique_message_id { - uint16_t component_id; - uint16_t instance_id; - uint32_t message_id; - }; - - struct message_context_t { - int32_t error; - queue_t *request_queue; - queue_t *requestor_info_queue; - }; - - message_context_t message_context; - - struct request_t { - unique_message_id uid; - uint32_t requested_state; - }; - - struct requestor_info_t { - unique_message_id uid; - uint16_t component_id; - uint16_t instance_id; - }; - - struct response_t { - unique_message_id uid; - uint32_t current_state; - }; - - void consumer_callback(const ams_message_payload_s * const payload, void *ctx) { - if(payload->message_length != sizeof(request_t)) { - ((message_context_t *)ctx)->error = 1; - return; - } - - queue_push(((message_context_t *)ctx)->request_queue, (request_t *)(payload->message)); - - requestor_info_t info; - info.uid = (request_t *)(payload->message)->uid; - info.component_id = payload->producer_component_id; - info.instance_id = payload->producer_instance_id; - queue_push(((message_context_t *)ctx)->requestor_info_queue, info); - } - - error_code componentB::Init(Pipeline* parent_ppl, const ModuelCfg* cfg) { - //getting Message Type ID for requests - error = am_service_get_message_type_id(MESSAGE_REQUEST, &message_request_id); - if(error != 0) { - //error handling - } - - //registering consumer - message_context.error = 0; - message_context.request_queue = &request_queue; - message_context.requestor_info_queue = &requestor_info_queue; - error = am_service_register_consumer(message_request_id, GetcomponentID(), GetInstanceID(), callback, &message_context); - if(error != 0) { - //error handling - } - - //getting Message Type ID for responses - error = am_service_get_message_type_id(MESSAGE_RESPONSE, &message_response_id); - if(error != 0) { - //error handling - } - - //registering producer - error = am_service_register_producer(message_response_id, GetcomponentID(), GetInstanceID()); - if(error != 0) { - //error handling - } - } - - void process_request(request_t *r) { - current_state = r->requested_state; - } - - uint32_t get_current_state() { - return current_state; - } - - error_code componentB::ProcessData(size_t max_output_data_size, uint32_t* custom_error_code) { - while(queue_size(request_queue) > 0) { - if(message_context.error != 0) { - //error handling - } - - request_t *r = queue_pop(request_queue); - - //handling of async message - process_request(r); - - //message response - response_t response; - response.uid = r->uid; - response.current_state = get_current_state(); - - //find requestor information - requestor_info_t *ri = find(requestor_info_queue, r->uid); - if(ri == NULL) { - //error handling - } - queue_pop(requestor_info_queue, ri); - - error_code error = am_service_send_mi(message_type_id, GetcomponentID(), GetInstanceID(), ri->component_id, ri->instance_id, sizeof(response_t), &response_t); - if(e != 0) { - //error handling - } - } - - //regular processing - ... - } - -Producer code: - -.. code:: cpp - - uint32_t message_request_id; - uint32_t message_response_id; - uint32_t message_id_counter; - - queue_t response_queue; - queue_t request_source_queue; - - struct unique_message_id { - uint16_t component_id; - uint16_t instance_id; - uint32_t message_id; - }; - - struct message_requestor_context_t { - int32_t error; - queue_t *response_queue; - uint32_t blockade; - }; - - message_requestor_context_t message_context; - - struct request_source_t { - unique_message_id uid; - uint32_t source; //0 - IPC, 1 - I2C - }; - - struct request_t { - unique_message_id uid; - uint32_t requested_state; - }; - - struct response_t { - unique_message_id uid; - uint32_t current_state; - }; - - void consumer_callback(const ams_message_payload_s * const payload, void *ctx) { - if(payload->message_length != sizeof(response_t)) { - (message_requestor_context_t *)ctx->error = 1; - return; - } - - queue_push(((message_context_t *)ctx)->response_queue, (request_t *)(payload->message)); - } - - error_code componentA::Init(Pipeline* parent_ppl, const ModuleACfg* cfg) { - message_id_counter = 0; - - //getting Message Type ID for response - error = am_service_get_message_type_id(MESSAGE_RESPONSE, &message_response_id); - if(error != 0) { - //error handling - } - - //registering consumer - message_context.error = 0; - message_context.blockade = 0; - message_context.response_queue = &response_queue; - error = am_service_register_consumer(message_response_id, GetcomponentID(), GetInstanceID(), callback, &message_context); - if(error != 0) { - //error handling - } - - //getting Message Type ID for request - error = am_service_get_message_type_id(MESSAGE_REQUEST, &message_request_id); - if(error != 0) { - //error handling - } - - //registering as a producer - error = am_service_register_producer(message_request_id, GetcomponentID(), GetInstanceID()); - if(error != 0) { - //error handling - } - } - - Message::IxcStatus componentA::LargeConfigSet(uint32_t large_param_id, - bool init_block, - bool final_block, - uint32_t data_off_size, - const ByteArray* data, - ByteArray* response) - { - ... - //message request - request_t request; - response.uid = {GetcomponentID(), GetInstanceID(), message_id_counter++}; - response.requested_state = state_from_request; - - request_source_t source; - source.uid = response.uid; - source.source = 0; //IPC - queue_push(request_source_queue, source); - - error_code error = am_service_send_mi(message_type_id, GetcomponentID(), GetInstanceID(), component_B_id, component_B_instance_id, sizeof(request_t), &response); - if(e != 0) { - //error handling - } - ... - } - - void process_request(response_t *r) { - ... - request_source_t *rs = find(request_source_queue, r->uid); - if(rs == NULL) { - //error handling - } - - if(rs->source == 0) { - //send response over IPC - } - - queue_pop(request_source_queue, rs); - ... - } - - error_code componentA::ProcessData(size_t max_output_data_size, uint32_t* custom_error_code) { - ... - while(queue_size(response_queue) > 0) { - if(message_context.error != 0) { - //error handling - } - - response_t *r = queue_pop(request_queue); - - //handling of async message - process_request(r); - } - ... - //regular processing - } - -Max message size -**************** - -The asynchronous message size is limited by size of an async message slot in the -AM queue, which is currently 4KB and should not be exceeded. - -Queue is Full -************* - -The queue of asynchronous messages is used when there are customers of messages -registered on other core than producer’s core. This queue has limited size and -it can happen that ``send`` function will fail. In such case, the best strategy -is to retry ``send`` function call in the next execution period. diff --git a/developer_guides/firmware/component-tutorial/tut-i-basic-fw-code.rst b/developer_guides/firmware/component-tutorial/tut-i-basic-fw-code.rst deleted file mode 100644 index 248814f4..00000000 --- a/developer_guides/firmware/component-tutorial/tut-i-basic-fw-code.rst +++ /dev/null @@ -1,404 +0,0 @@ -.. _developer_guides_tut-i: - -Part I - Adding a Component Code to FW -###################################### - -This lesson describes how to add a component code to the FW source tree, with -a minimal Component API implementation and a simple copying function inside. -It also demonstrates how to register the component driver in the FW -infrastructure so that the FW can respond to the *new component* request sent -by the driver and instantiate it. - -For this lesson, the new component is called "the amplifier." The amplifier -is based on a processing component class such as effect. - -Adding Basic Component Code -*************************** - -New Component Type -================== - -First, define a new component type in *src/include/ipc/topology.h*. It is a -unique identifier used while declaring instances of the component as parts of -the topology. More details on the required topology modifications will be -provided in the next part of the tutorial; for now, our focus is on the FW -source code. - -.. note:: - Simple component IDs currently used at the moment will be replaced by - UUIDs in the future to avoid conflict resolutions while integrating - independently developed components. The current implementation requires - you to assign an unoccupied number. The UUIDs assigned to the components - today are used for logging purposes only. - -.. code-block:: c - - enum sof_comp_type { - /* ... - */ - - SOF_COMP_AMP = 1000, - - /* ... - */ - }; - -Identifier for Logging -====================== - -Components use Universally Unique Identifiers (UUIDs) for logging. Refer to -the :ref:`uuid-api` documentation for basic information about UUIDs in FW and -how to generate one for your component. - -The example UUID generated for the amplifier component is -*1d501197-da27-4697-80c8-4e694d3600a0*. - -Add the following declaration at the beginning of the source file: - -.. code-block:: c - - DECLARE_SOF_RT_UUID("amp", amp_uuid, 0x1d501197, 0xda27, 0x4697, - 0x80, 0xc8, 0x4e, 0x69, 0x4d, 0x36, 0x00, 0xa0); - - DECLARE_TR_CTX(amp_tr, SOF_UUID(amp_uuid), LOG_LEVEL_INFO); - -where *"amp"* is the component name that will be printed by the logger tool. -Amplifier's UUID value and its name is stored in the ldc file deployed on the -target system and is used by the logger to resolve and print the name of the -component. The only thing required to "teach" the logger the new component's -name is to update the ldc file along with the FW binary on the target -system. No tool recompilation is required. - -Every component has to define its trace context. It groups UUID to be inserted -into the traces produced by the component for identification purposes, as well -as run-time trace settings like the tracing level, initialized to -``LOG_LEVEL_INFO`` in this example. The trace context is declared using -``DECLARE_TR_CTX()`` macro as ``amp_tr``. - -Basic Component API -=================== - -Create a folder for your component source code in *src/audio*, such as -*src/audio/amp*, and create a new *amp.c* file inside. - -Declare the basic required part of the API for your component using ``struct -comp_driver`` in *amp.c*. To learn more about component instances, or -devices, and their drivers, refer to :ref:`apps-component-overview` and -:ref:`component-api`. - -.. code-block:: c - - #include - - /* ... - */ - - struct comp_driver comp_amp = { - .type = SOF_COMP_AMP, - .uid = SOF_RT_UUID(amp_uuid), - .tctx = &_tr, - .ops = { - .create = amp_new, - .free = amp_free, - .params = NULL, - .cmd = NULL, - .trigger = amp_trigger, - .prepare = amp_prepare, - .reset = amp_reset, - .copy = amp_copy, - }, - }; - - static SHARED_DATA struct comp_driver_info comp_amp_info = { - .drv = &comp_amp, - }; - - static void sys_comp_amp_init(void) - { - comp_register(platform_shared_get(&comp_amp_info, - sizeof(comp_amp_info))); - } - - DECLARE_MODULE(sys_comp_amp_init); - -Note that the ``type`` used for the component driver is set to the -``SOF_COMP_AMP`` which is declared earlier. The ``uid`` used for logging is -initialized by the ``SOF_RT_UUID(amp_uuid)``, where ``amp_uuid`` is declared at -the beginning of the source file. The trace context ``amp_tr`` is associated -with the driver object as well. - -The API declaration is followed by a registration handler attached to the -initialization list by the ``DECLARE_MODULE()`` macro. This is all the -infrastructure needs to know in order to find and create an instance of the -``SOF_COMP_AMP`` component. - -The following operations are currently not implemented: - -* ``params`` - the amplifier will do all the preparations and setup inside - the ``prepare`` handler; this one will not be used. - -* ``cmd`` - a handler to report and receive our custom run-time parameters - will be implemented later in :ref:`amp-run-time-params`. - -Constructor ``amp_new()`` -========================= - -Add the following handler before your API declaration: - -.. code-block:: c - - static struct comp_dev *amp_new(const struct comp_driver *drv, - struct sof_ipc_comp *comp) - { - struct comp_dev *dev; - struct sof_ipc_comp_process *amp; - struct sof_ipc_comp_process *ipc_amp - = (struct sof_ipc_comp_process *)comp; - struct amp_comp_data *cd; - int ret; - - dev = comp_alloc(drv, COMP_SIZE(struct sof_ipc_comp_process)); - if (!dev) - return NULL; - - cd = rzalloc(SOF_MEM_ZONE_RUNTIME, 0, SOF_MEM_CAPS_RAM, sizeof(*cd)); - if (!cd) { - rfree(dev); - return NULL; - } - - amp = COMP_GET_IPC(dev, sof_ipc_comp_process); - ret = memcpy_s(amp, sizeof(*amp), ipc_amp, - sizeof(struct sof_ipc_comp_process))); - assert(!ret); - - comp_set_drvdata(dev, cd); - - dev->state = COMP_STATE_READY; - - comp_dbg(dev, "amplifier created"); - - return dev; - } - -The constructor: - -* Allocates the memory, usually in two steps. Both allocations are done from - the SOF_MEM_ZONE_RUNTIME heap that should be used by the application layer - which includes processing components. - - * First, a common context for the device is allocated including some - extensions specific for a component class. In this example, the component - device is based on the ``struct sof_ipc_comp_process``, which is used for - processing components. Component's parameters received from the IPC - request are copied to the allocated space. :cpp:func:`comp_alloc()` used - for the first allocation guarantees that all important parts of the ``dev`` are initialized as well. - - * The second allocation acquires memory for the private data of the - amplifier instance, ``struct amp_comp_data``. This structure contains a - placeholder at the moment. You will redefine it later to store run-time - parameters of the instance. Note how the private data is attached to the - device by calling ``comp_set_drvdata()``. You will use symmetric - ``comp_get_drvdata()`` to retrieve the private data object from the - device object later while implementing other handlers. - - .. code-block:: c - - struct amp_comp_data { - int placeholder; - }; - -* The device state is set to ``COMP_STATE_READY``. To learn more - about the component device state machine, refer to - :ref:`apps-component-overview`. - -Note the ``comp_dbg()`` macro used to log the creation event where ``dev`` is -the first argument that lets the logger resolve the name of the trace source -while processing the log entry. DEBUG level messages are not traced by -default; the trace subsystem has to be reconfigured. The trace system -outputs INFO, WARN, and ERROR messages by default. - -Destructor ``amp_free()`` -========================= - -The destructor frees the memory allocated previously in the ``amp_new()``. - -.. code-block:: c - - static void amp_free(struct comp_dev *dev) - { - struct comp_data *cd = comp_get_drvdata(dev); - - rfree(cd); - rfree(dev); - } - - -State Transition Handler ``amp_trigger()`` -========================================== - -The transition handler just invokes ``comp_set_state()``. No specific -actions are defined in this simple example. - -.. code-block:: c - - static int amp_trigger(struct comp_dev *dev, int cmd) - { - comp_dbg(dev, "amplifier got trigger cmd %d", cmd); - return comp_set_state(dev, cmd); - } - -Stream Parameters Handler ``amp_prepare()`` -=========================================== - -This is where your component can be reconfigured for the stream parameters. - -This example assumes that only one source buffer and one sink buffer are -connected; therefore, only the first item from ``dev->bsink_list`` is -verified. - -Note that in the event that another "prepare" call was previously issued, -the handler returns ``PPL_STATUS_PATH_STOP`` and exits to prevent -propagation of a likely configuration coming from another connected pipeline. - -Add the following handler code before your API declaration: - -.. code-block:: c - - static int amp_prepare(struct comp_dev *dev) - { - int ret; - struct comp_buffer *sink_buf; - struct sof_ipc_comp_config *config = dev_comp_config(dev); - uint32_t sink_per_bytes; - - ret = comp_set_state(dev, COMP_TRIGGER_PREPARE); - if (ret < 0) - return ret; - - if (ret == COMP_STATUS_STATE_ALREADY_SET) - return PPL_STATUS_PATH_STOP; - - sink_buf = list_first_item(&dev->bsink_list, - struct comp_buffer, source_list); - - sink_per_bytes = audio_stream_period_bytes(&sink_buf->stream, - dev->frames); - - if (sink_buf->stream.size < config->periods_sink * sink_per_bytes) { - comp_err(dev, "amp_prepare(): sink buffer size is insufficient"); - return -ENOMEM; - } - - comp_dbg(dev, "amplifier prepared"); - return 0; - } - -Reset Handler ``amp_reset()`` -============================= - -The *reset* handler toggles the device state. It is a good place to add any -instance reset code later. - -.. code-block:: c - - static int amp_reset(struct comp_dev *dev) - { - return comp_set_state(dev, COMP_TRIGGER_RESET); - } - - -Signal Processing Function ``amp_copy`` -======================================= - -This first version of the processing function simply copies input samples to -output and shows how to: - -* Use :cpp:class:`comp_copy_limits` and :cpp:func:`comp_get_copy_limits_with_lock()` - to retrieve information about the number of samples to be processed. - -* Refresh the local data cache with :cpp:func:`buffer_invalidate()` in case - the input data is being provided to the source buffer by a component - running on another core. - -* Iterate over the frames, channels, and samples using the - :cpp:class:`comp_copy_limits` descriptor. - -* Read/write from/to the circular buffers. This implementation assumes both - input and output are signed 16-bit samples; therefore, - :cpp:func:`audio_stream_read_frag_s16()` and - :cpp:func:`audio_stream_write_frag_s16()` are used. You may prepare more - alternatives and use the one suitable for the input/output format obtained - from the ``sink_buf->stream.frame_fmt`` in the ``amp_prepare()`` handler. - -* Update the shared memory containing produced samples with the local data - cache using :cpp:func:`buffer_writeback()` in the event that the output - data is being consumed from the sink buffer by a component running on - another core. - -* Update the buffers' pointers using :cpp:func:`comp_update_buffer_consume()` - and :cpp:func:`comp_update_buffer_produce()` to indicate the data consumed - and produced. - -The ``*dst = *src`` copy operation will be replaced later by amplification. - -Add the following handler code before your API declaration: - -.. code-block:: c - - static int amp_copy(struct comp_dev *dev) - { - struct comp_copy_limits cl; - struct comp_buffer *source; - struct comp_buffer *sink; - int frame; - int channel; - uint32_t buff_frag = 0; - int16_t *src; - int16_t *dst; - - source = list_first_item(&dev->bsource_list, struct comp_buffer, - sink_list); - sink = list_first_item(&dev->bsink_list, struct comp_buffer, - source_list); - - comp_get_copy_limits_with_lock(source, sink, &cl); - - buffer_invalidate(source, cl.source_bytes); - - for (frame = 0; frame < cl.frames; frame++) { - for (channel = 0; channel < sink->stream.channels; channel++) { - src = audio_stream_read_frag_s16(&source->stream, - buff_frag); - dst = audio_stream_write_frag_s16(&sink->stream, - buff_frag); - *dst = *src; - ++buff_frag; - } - } - - buffer_writeback(sink, cl.sink_bytes); - - comp_update_buffer_produce(sink, cl.sink_bytes); - comp_update_buffer_consume(source, cl.source_bytes); - - return 0; - } - -Build Scripts -************* - -Add the following line to *src/audio/CMakeLists.txt* inside the block where -other components' subfolders are specified: - -.. code-block:: cmake - - add_subdirectory(amp) - -Create a new file *src/audio/amp/CMakeLists.txt* and add this line inside: - -.. code-block:: cmake - - add_local_sources(sof amp.c) - -Rebuild the firmware. diff --git a/developer_guides/firmware/component-tutorial/tut-ii-topology.rst b/developer_guides/firmware/component-tutorial/tut-ii-topology.rst deleted file mode 100644 index 71252eff..00000000 --- a/developer_guides/firmware/component-tutorial/tut-ii-topology.rst +++ /dev/null @@ -1,247 +0,0 @@ -.. _developer_guides_tut-ii: - -Part II - Modifying the Topology & Driver -######################################### - -Topology -******** - -Create *tools/topology/m4/amp.m4* and add the following Amp widget definition. -Note the highlighted line containing the definition of the type of your new -processing component. The *Driver* section refers to it later. - -.. code-block:: text - :caption: tools/topology/m4/amp.m4 - :linenos: - :emphasize-lines: 32 - - divert(-1) - - dnl Define macro for example Amp widget - - dnl AMP(name) - define(`N_AMP', `AMP'PIPELINE_ID`.'$1) - - dnl W_AMP(name, format, periods_sink, periods_source, kcontrols_list) - define(`W_AMP', - `SectionVendorTuples."'N_AMP($1)`_tuples_w" {' - ` tokens "sof_comp_tokens"' - ` tuples."word" {' - ` SOF_TKN_COMP_PERIOD_SINK_COUNT' STR($3) - ` SOF_TKN_COMP_PERIOD_SOURCE_COUNT' STR($4) - ` SOF_TKN_COMP_CORE_ID' STR($5) - ` }' - `}' - `SectionData."'N_AMP($1)`_data_w" {' - ` tuples "'N_AMP($1)`_tuples_w"' - `}' - `SectionVendorTuples."'N_AMP($1)`_tuples_str" {' - ` tokens "sof_comp_tokens"' - ` tuples."string" {' - ` SOF_TKN_COMP_FORMAT' STR($2) - ` }' - `}' - `SectionData."'N_AMP($1)`_data_str" {' - ` tuples "'N_AMP($1)`_tuples_str"' - `}' - `SectionVendorTuples."'N_AMP($1)`_tuples_str_type" {' - ` tokens "sof_process_tokens"' - ` tuples."string" {' - ` SOF_TKN_PROCESS_TYPE' "AMP" - ` }' - `}' - `SectionData."'N_AMP($1)`_data_str_type" {' - ` tuples "'N_AMP($1)`_tuples_str_type"' - `}' - `SectionWidget."'N_AMP($1)`" {' - ` index "'PIPELINE_ID`"' - ` type "effect"' - ` no_pm "true"' - ` data [' - ` "'N_AMP($1)`_data_w"' - ` "'N_AMP($1)`_data_str"' - ` "'N_AMP($1)`_data_str_type"' - ` ]' - ` bytes [' - $6 - ` ]' - `}') - - divert(0)dnl - -Add a definition of parameters and specify default values for them (handling -parameters in the FW code is discussed in the next lesson but you prepare a -complete topology upfront). Create *tools/topology/amp_bytes.m4* and add the -following code. - -Note the size of the parameters data and the data highlighted (two 32-bit -number set to 1 to unmute both channels by default, little-endian byte -ordering). The data begins with `struct sof_abi_hdr` content, note the SOF -magic number in line 3 and the ABI version in line 6. The latter must be set -to a version compatible with the SOF stack. - -.. code-block:: text - :caption: tools/topology/amp_bytes.m4 - :linenos: - :emphasize-lines: 5, 11-12 - - # AMP Example - Parameters - CONTROLBYTES_PRIV(AMP_priv, - ` bytes "0x53,0x4f,0x46,0x00,' - ` 0x00,0x00,0x00,0x00,' - ` 0x08,0x00,0x00,0x00,' - ` 0x00,0x00,0x00,0x03,' - ` 0x00,0x00,0x00,0x00,'' - ` 0x00,0x00,0x00,0x00,' - ` 0x00,0x00,0x00,0x00,' - ` 0x00,0x00,0x00,0x00,' - ` 0x01,0x00,0x00,0x00,' - ` 0x01,0x00,0x00,0x00"' - ) - -Add the Amp widget to a playback pipeline. Create a copy of -*tools/topology/sof/pipe-volume-playback.m4* and save it as -*tools/topology/sof/pipe-amp-volume-playback.m4*. Add the definitions -in your copy as highlighted below. - -.. code-block:: text - :caption: tools/topology/sof/pipe-amp-volume-playback.m4 - :linenos: - :emphasize-lines: 14, 16, 43-58, 73-75, 81-86, 96-99, 104 - - # Low Latency Passthrough with volume Pipeline and PCM - # - # Pipeline Endpoints for connection are :- - # - # host PCM_P --> B0 --> Amp -> B1 -> Volume 0 --> B2 --> sink DAI0 - - # Include topology builder - include(`utils.m4') - include(`buffer.m4') - include(`pcm.m4') - include(`pga.m4') - include(`dai.m4') - include(`mixercontrol.m4') - include(`bytecontrol.m4') - include(`pipeline.m4') - include(`amp.m4') - - # - # Controls - # - # Volume Mixer control with max value of 32 - C_CONTROLMIXER(Master Playback Volume, PIPELINE_ID, - CONTROLMIXER_OPS(volsw, 256 binds the mixer control to volume get/put handlers, 256, 256), - CONTROLMIXER_MAX(, 32), - false, - CONTROLMIXER_TLV(TLV 32 steps from -64dB to 0dB for 2dB, vtlv_m64s2), - Channel register and shift for Front Left/Right, - LIST(` ', KCONTROL_CHANNEL(FL, 1, 0), KCONTROL_CHANNEL(FR, 1, 1))) - - # - # Volume configuration - # - - define(DEF_PGA_TOKENS, concat(`pga_tokens_', PIPELINE_ID)) - define(DEF_PGA_CONF, concat(`pga_conf_', PIPELINE_ID)) - - W_VENDORTUPLES(DEF_PGA_TOKENS, sof_volume_tokens, - LIST(` ', `SOF_TKN_VOLUME_RAMP_STEP_TYPE "0"' - ` ', `SOF_TKN_VOLUME_RAMP_STEP_MS "250"')) - - W_DATA(DEF_PGA_CONF, DEF_PGA_TOKENS) - - # Amp Parameters - include(`amp_bytes.m4') - - # Amp Bytes control with max value of 140 - # The max size needs to also take into account the space required to hold the control data IPC message - # struct sof_ipc_ctrl_data requires 92 bytes - # AMP priv in amp_bytes.m4 (ABI header (32 bytes) + 2 dwords) requires 40 bytes - # Therefore at least 132 bytes are required for this kcontrol - # Any value lower than that would end up in a topology load error - C_CONTROLBYTES(AMP, PIPELINE_ID, - CONTROLBYTES_OPS(bytes, 258 binds the control to bytes get/put handlers, 258, 258), - CONTROLBYTES_EXTOPS(258 binds the control to bytes get/put handlers, 258, 258), - , , , - CONTROLBYTES_MAX(, 140), - , - AMP_priv) - - # - # Components and Buffers - # - - # Host "Passthrough Playback" PCM - # with 2 sink and 0 source periods - W_PCM_PLAYBACK(PCM_ID, Passthrough Playback, 2, 0, SCHEDULE_CORE) - - - # "Volume" has 2 source and 2 sink periods - W_PGA(0, PIPELINE_FORMAT, DAI_PERIODS, 2, DEF_PGA_CONF, SCHEDULE_CORE, - LIST(` ', "PIPELINE_ID Master Playback Volume")) - - # "Amp" has 2 sink periods and 2 source periods - W_AMP(0, PIPELINE_FORMAT, 2, 2, SCHEDULE_CORE, - LIST(` ', "AMP")) - - # Playback Buffers - W_BUFFER(0, COMP_BUFFER_SIZE(2, - COMP_SAMPLE_SIZE(PIPELINE_FORMAT), PIPELINE_CHANNELS, COMP_PERIOD_FRAMES(PCM_MAX_RATE, SCHEDULE_PERIOD)), - PLATFORM_HOST_MEM_CAP) - W_BUFFER(1, COMP_BUFFER_SIZE(2, - COMP_SAMPLE_SIZE(PIPELINE_FORMAT), PIPELINE_CHANNELS, COMP_PERIOD_FRAMES(PCM_MAX_RATE, SCHEDULE_PERIOD)), - PLATFORM_HOST_MEM_CAP) - W_BUFFER(2, COMP_BUFFER_SIZE(DAI_PERIODS, - COMP_SAMPLE_SIZE(DAI_FORMAT), PIPELINE_CHANNELS, COMP_PERIOD_FRAMES(PCM_MAX_RATE, SCHEDULE_PERIOD)), - PLATFORM_DAI_MEM_CAP) - - # - # Pipeline Graph - # - # host PCM_P --> B0 --> Amp -> B1 --> Volume 0 --> B2 --> sink DAI0 - - P_GRAPH(pipe-amp-volume-playback-PIPELINE_ID, PIPELINE_ID, - LIST(` ', - `dapm(N_BUFFER(0), N_PCMP(PCM_ID))', - `dapm(N_AMP(0), N_BUFFER(0))', - `dapm(N_BUFFER(1), N_AMP(0))', - `dapm(N_PGA(0), N_BUFFER(1))', - `dapm(N_BUFFER(2), N_PGA(0))')) - - # - # Pipeline Source and Sinks - # - indir(`define', concat(`PIPELINE_SOURCE_', PIPELINE_ID), N_BUFFER(2)) - indir(`define', concat(`PIPELINE_PCM_', PIPELINE_ID), Passthrough Playback PCM_ID) - - - # - # PCM Configuration - - # - PCM_CAPABILITIES(Passthrough Playback PCM_ID, `S32_LE,S24_LE,S16_LE', PCM_MIN_RATE, PCM_MAX_RATE, 2, PIPELINE_CHANNELS, 2, 16, 192, 16384, 65536, 65536) - -Create a copy of your topology in *tools/topology* and replace the -definition of low latency playback pipeline with the one crated in the previous -step. - -.. code-block:: text - :caption: Main topology .m4 file - :linenos: - :emphasize-lines: 3 - - # Low Latency playback pipeline 1 on PCM 0 using max 2 channels of s24le. - # Schedule 48 frames per 1000us deadline on core 0 with priority 0 - PIPELINE_PCM_ADD(sof/pipe-amp-volume-playback.m4, - 1, 0, 2, s24le, - 1000, 0, 0, - 48000, 48000, 48000) - -Driver -****** - -Add a mapping between ``SOF_TKN_PROCESS_TYPE`` set to **"AMP"** -in your m4 topology definition and the ``SOF_COMP_AMP`` defined in the FW code -in lesson 1. Refer to the driver documentation for further details about the -topology mappings location and recompilation of the driver. diff --git a/developer_guides/firmware/component-tutorial/tut-iii-runtime-params.rst b/developer_guides/firmware/component-tutorial/tut-iii-runtime-params.rst deleted file mode 100644 index 76248653..00000000 --- a/developer_guides/firmware/component-tutorial/tut-iii-runtime-params.rst +++ /dev/null @@ -1,197 +0,0 @@ -.. _developer_guides_tut-iii: - -.. _amp-run-time-params: - -Part III - Adding Run-time Parameter Control -############################################ - -This lesson describes how to add startup and run-time parameters to your component. -You will add a command handler to the "amp" to mute/unmute individual channels. - -Changes in the topology definition are required as well. You will add binary -bytes kcontrol connected to your widget in order to enable parameter transfer -from a user space application, through the driver to the FW running your "amp" -component. - -This simple example defines the parameter blob as two 32-bit integer numbers, -one per channel, where non-zero value causes the channel samples to pass while -zero value "mutes" the channel. - -Changing the FW Code -******************** - -First, change the private data definition to store run-time parameters. - -.. code-block:: c - :emphasize-lines: 2 - - struct amp_comp_data { - int channel_volume[2]; - }; - -Add start-up parameter handling to ``amp_new()``. - -.. code-block:: c - :emphasize-lines: 10-16, 22-23 - - static struct comp_dev *amp_new(struct sof_ipc_comp *comp) - { - /* ... */ - - amp = COMP_GET_IPC(dev, sof_ipc_comp_process); - ret = memcpy_s(amp, sizeof(*amp), ipc_amp, - sizeof(struct sof_ipc_comp_process))); - assert(!ret); - - cd->channel_volume[0] = 1; - cd->channel_volume[1] = 1; - - if (ipc_amp->size == sizeof(cd->channel_volume)) { - memcpy_s(cd->channel_volume, sizeof(cd->channel_volume), - ipc_amp->data, ipc_amp->size); - } - - comp_set_drvdata(dev, cd); - - /* ... */ - - comp_dbg(dev, "amplifier created vol[0] %d vol[1] %d", - cd->channel_volume[0], cd->channel_volume[1]); - - } - -Modify ``amp_copy()`` to pass/mute channels based on your settings. - -.. code-block:: c - :emphasize-lines: 3, 14-17 - - static int amp_copy(struct comp_dev *dev) - { - struct amp_comp_data *cd = comp_get_drvdata(dev); - struct comp_copy_limits cl; - - /* ... */ - - for (frame = 0; frame < cl.frames; frame++) { - for (channel = 0; channel < sink->stream.channels; channel++) { - src = audio_stream_read_frag_s16(&source->stream, - buff_frag); - dst = audio_stream_write_frag_s16(&sink->stream, - buff_frag); - if (cd->channel_volume[channel]) - *dst = *src; - else - *dst = 0; - ++buff_frag; - } - } - -Add the command handlers to report parameters and receive updates. - -First, add the handler to receive parameters. - -.. code-block:: c - - static int amp_cmd_set_data(struct comp_dev *dev, - struct sof_ipc_ctrl_data *cdata) - { - struct amp_comp_data *cd = comp_get_drvdata(dev); - - if (cdata->cmd != SOF_CTRL_CMD_BINARY) { - comp_err(dev, "amp_cmd_set_data(): invalid cmd %d", - cdata->cmd); - return -EINVAL; - } - - if (cdata->data->size != sizeof(cd->channel_volume)) { - comp_err(dev, "amp_cmd_set_data(): invalid data size %d", - cdata->data->size); - return -EINVAL; - } - - memcpy_s(cd->channel_volume, sizeof(cd->channel_volume), - cdata->data->data, cdata->data->size); - comp_dbg(dev, "amplifier new settings vol[0] %d vol[1] %d", - cd->channel_volume[0], cd->channel_volume[1]); - return 0; - } - -Add another one to report parameters back to the host. Note how the -``cdata->data`` (``struct sof_abi_hdr``) is updated. - -.. code-block:: c - - static int amp_cmd_get_data(struct comp_dev *dev, - struct sof_ipc_ctrl_data *cdata, int max_size) - { - struct amp_comp_data *cd = comp_get_drvdata(dev); - - if (cdata->cmd != SOF_CTRL_CMD_BINARY) { - comp_err(dev, "amp_cmd_get_data(): invalid cmd %d", - cdata->cmd); - return -EINVAL; - } - - if (sizeof(cd->channel_volume) > max_size) - return -EINVAL; - - memcpy_s(cdata->data->data, - ((struct sof_abi_hdr *)(cdata->data))->size, - cd->channel_volume, - sizeof(cd->channel_volume)); - cdata->data->abi = SOF_ABI_VERSION; - cdata->data->size = sizeof(cd->channel_volume); - - return 0; - } - -Put everything together as a command handler. - -.. code-block:: c - - static int amp_cmd(struct comp_dev *dev, int cmd, void *data, int max_data_size) - { - struct sof_ipc_ctrl_data *cdata = data; - int ret = 0; - - switch (cmd) { - case COMP_CMD_SET_DATA: - ret = amp_cmd_set_data(dev, cdata); - break; - case COMP_CMD_GET_DATA: - ret = amp_cmd_get_data(dev, cdata, max_data_size); - break; - default: - comp_err(dev, "amp_cmd(): unhandled command %d", cmd); - ret = -EINVAL; - break; - } - return ret; - } - -Attach the handler to your component driver API. - -.. code-block:: c - :emphasize-lines: 7 - - struct comp_driver comp_amp = { - .type = SOF_COMP_AMP, - .ops = { - .new = amp_new, - .free = amp_free, - .params = NULL, - .cmd = amp_cmd, - .trigger = amp_trigger, - .prepare = amp_prepare, - .reset = amp_reset, - .copy = amp_copy, - .cache = NULL - }, - }; - - -Binary Bytes KControl in Topology -********************************* - -An example of data section for component parameters is presented as -*amp_bytes.m4* content in the previous part of the tutorial. diff --git a/developer_guides/firmware/component-tutorial/tut-intro.rst b/developer_guides/firmware/component-tutorial/tut-intro.rst deleted file mode 100644 index 8c0417ee..00000000 --- a/developer_guides/firmware/component-tutorial/tut-intro.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _developer_guides_hello_world: - -Hello World Tutorial -#################### - -This guide takes a step-by-step approach to creating a new audio component -and adding it to a simple audio pipeline. - -At the end of this tutorial, a very simple audio signal amplifier will be -running as a part of the playback pipeline implemented. You will be able to -control the amplification strength from the command line. - -The amplifier will log its basic activities to demonstrate use of the FW -logging capabilities. - -We will also inject a division by 0 instruction to the amplifier code to -demonstrate how to collect and analyze the FW exception reports. - -.. toctree:: - :maxdepth: 1 - - tut-i-basic-fw-code - tut-ii-topology - tut-iii-runtime-params - tut-iv-exceptions diff --git a/developer_guides/firmware/component-tutorial/tut-iv-exceptions.rst b/developer_guides/firmware/component-tutorial/tut-iv-exceptions.rst deleted file mode 100644 index b93df9e0..00000000 --- a/developer_guides/firmware/component-tutorial/tut-iv-exceptions.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _developer_guides_tut-iv: - -Part IV - Working with Exception Reports -######################################## - -This chapter is forthcoming. diff --git a/developer_guides/firmware/index.rst b/developer_guides/firmware/index.rst deleted file mode 100644 index ee2e75cd..00000000 --- a/developer_guides/firmware/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _firmware: - -Firmware -######## - -Developer guides and information for firmware development. - -.. toctree:: - :maxdepth: 1 - - component-tutorial/tut-intro - porting - cmake - async_messaging_best_practices - llext_modules diff --git a/developer_guides/firmware/llext_modules.rst b/developer_guides/firmware/llext_modules.rst index e4040d54..1385bc21 100644 --- a/developer_guides/firmware/llext_modules.rst +++ b/developer_guides/firmware/llext_modules.rst @@ -33,8 +33,7 @@ different from built-in ones. Implementing LLEXT modules ************************** -At the moment only modules, implementing the Module Adapter API -:ref:`apps-comp-world` are supported. +At the moment only modules implementing the `Module Adapter API `_ are supported. .. _multiple-adapter-modules: @@ -77,10 +76,9 @@ modules don't have to use "tristate" in their Kconfig entries. Installation ************ -As specified in -: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 +The |SOF| Linux kernel driver loads SOF dynamic modules by their UUIDs +(staging from ``/lib/firmware/intel/sof-ipc4/`` or platform module directories), +as 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 xtensa-build-zephyr.py script. It copies modules to the deployment tree as files with a "llext" extension and creates symbolic links to them named as @@ -99,7 +97,7 @@ will be created, e.g. 39656EB2-3B71-4049-8D3F-F92CD5C43C09.bin -> mixin_mixout.llext 3C56505A-24D7-418F-BDDC-C1F5A3AC2AE0.bin -> mixin_mixout.llext -See :ref:`apps-component-overview` for more information on UUID use by SOF +See :ref:`uuid` for more information on UUID use by SOF component and module adapter drivers. It is also possible to avoid using the script by running ``west build`` to build diff --git a/developer_guides/firmware/porting.rst b/developer_guides/firmware/porting.rst deleted file mode 100644 index b2cae769..00000000 --- a/developer_guides/firmware/porting.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _porting: - -Porting Guides -############## - -Details about porting SOF to other DSP architectures and platforms. This guide -is still work in progress. - -Architecture Porting Guide -************************** -|SOF| currently supports the Cadence xtensa DSP architecture but is designed to -support other DSP architectures via an architecture abstraction layer (AAL) in -the src/arch directory. The AAL provides an architecture agnostic API that -exports functioality for common architecure features. - -#. Boot -#. Interrupts -#. Exceptions -#. Timers -#. Spinlocks -#. Atomic Arithmetic -#. Cache -#. Wait -#. GDB debug - -The AAL API is exported via headers in 'src/arch//include/arch'. - -The AAL thinly wraps architecture specific HALs or RTOSes and is intended to -"compile out" so that there is no runtime performance penalty. i.e. on -Cadence xtensa architecture it wraps xtensa HAL and XTOS API calls. - -Platform Porting Guide -********************** - -The SOF infrastructure requires every platform to provide certain interfaces -and define certain macros with platform specific configuration. - -#. Platform capabilities -#. Memmory mapping -#. Device platform data -#. Interrupt mapping -#. Platform timers - -Refer to :ref:`platform-api` for documentation. - -.. TODO: reference to flows that illustrate calls to platform api. diff --git a/developer_guides/index.rst b/developer_guides/index.rst index 854e6716..b2a4af23 100644 --- a/developer_guides/index.rst +++ b/developer_guides/index.rst @@ -1,132 +1,122 @@ .. _developer_guides: +.. _subsystem-architecture-guides: Developer Guides ################ -New developers are best starting by reading the introduction which describes the -terminology before reading further. +Firmware Development (FW) +************************* + +Guides and specifications for developing, compiling, and debugging DSP firmware components, Zephyr RTOS integration, audio processing algorithms, dynamic modules, and firmware image signing. + +Upstream Firmware Feature Specifications +======================================== + +The SOF firmware repository maintains detailed, up-to-date specifications for each audio processing module, pipeline feature, and subsystem directly alongside the source code in `thesofproject/sof `_: + +Core Infrastructure & Pipeline +------------------------------ + +* `Pipeline Architecture `_ +* `Audio Buffer Management `_ +* `Scheduler `_ +* `Module Framework `_ +* `Module Adapter & IADK Integration `_ +* `IPC Infrastructure (IPC3 & IPC4) `_ +* `Firmware Initialization & Boot `_ + +Audio Processing Modules & Algorithms +------------------------------------- + +* `Volume Control `_ +* `Mixer & Mixin / Mixout `_ +* `Sample Rate Converter (SRC) `_ & `ASRC `_ +* `Parametric EQ (FIR) `_ & `EQ (IIR) `_ +* `Dynamic Range Compressor (DRC) `_ & `Multiband DRC `_ +* `Crossover `_ +* `DC Blocker `_ +* `Time-Domain Fixed Beamformer (TDFB) `_ +* `RTNR Noise Reduction `_ +* `TensorFlow Lite Micro (TFLM) `_ +* `MFCC Feature Extraction `_ +* `Smart Amp Protection `_ +* `Sound Dose Evaluator `_ +* `Copier `_, `Mux `_ & `Selector `_ +* `PCM Format Converter `_ -.. toctree:: - :maxdepth: 1 - - introduction - firmware/index - unit_tests - xtrun/index - topology/topology - topology2/topology2 - uuid/index.rst - debugability/index - tuning/sof-ctl - rimage/index.rst - linux_driver/index - virtualization/virtualization - virtualization/running - fuzzing/index - testbench/index - add_new_arch +.. _algorithm-specific-information: -Technical Notes -*************** +Algorithm Tuning & Implementation Guides +======================================== -Some how-to technical notes that help explain how you can use SOF capabilities. +Detailed filter design, coefficient generation, and tuning workflows: .. toctree:: :maxdepth: 1 - tech/build-cmocka - tech/compile_wsl - -Remote Deployment with ktest -**************************** + algorithms/demux/demux.rst + algorithms/eq/equalizers_tuning + algorithms/src/sample_rate_conversion + algorithms/tdfb/time_domain_fixed_beamformer -Set up a target device and environment to deploy and test kernels over SSH using ``ktest``. +Firmware Packaging & Dynamic Modules +==================================== .. toctree:: :maxdepth: 1 - ktest/setup_ktest_environment - -Set up SOF on a special device -****************************** + rimage/index.rst + firmware/llext_modules + loadable_modules/lmdk_user_guide -SOF also runs on the MinnowBoard Turbot and the Up Squared board with Hifiberry Dac+. +DSP Telemetry, Probes & Debugging +================================= .. toctree:: :maxdepth: 1 - setup_special_device/setup_minnowboard_turbot - setup_special_device/setup_up_2_board + debugability/index + uuid/index.rst -Debug Audio issues on Intel platforms -************************************* +Kernel & Host Driver Development (Kernel) +***************************************** -Intel platforms rely on different versions of DSP and audio hardware -interfaces. The following sections provide hints for integrators and -users when audio components are not working properly or are broken. +Guides for Linux ASoC kernel driver developers, topology authors, virtualization environments, and host tuning utilities. .. toctree:: :maxdepth: 1 - intel_debug/introduction - intel_debug/suggestions + linux_driver/index + topology2/topology2 + topology/topology + virtualization/virtualization + virtualization/running + tuning/sof-ctl + ktest/setup_ktest_environment -SOF on NXP platforms -******************** +Hardware & Platform-Specific Guides (HW) +**************************************** -This section provides guides for integrators and for users working with i.MX platforms. +Hardware integration, platform memory layouts, boot architectures, and bringup checklists across silicon vendors, legacy architectures, and embedded development boards. .. toctree:: :maxdepth: 1 nxp/sof_imx_user_guide + setup_special_device/setup_up_2_board -Building loadable modules using LMDK -************************************ - -This section describes the process of building loadable modules using LMDK. - -.. toctree:: - :maxdepth: 1 - - loadable_modules/lmdk_user_guide - -.. _subsystem-architecture-guides: - -Detailed Subsystem Architecture Guides -************************************** - -For in-depth implementation specifications, driver models, and platform-specific firmware layers, consult the dedicated architectural guides below: - -.. toctree:: - :maxdepth: 2 - - subsystem_architecture/host/index - subsystem_architecture/firmware/index - -Platform Specific Information -***************************** - -Further information on specific platforms can be found here. - -.. toctree:: - :maxdepth: 2 - - intel-legacy/index - intel-cavs/index - -.. _algorithm-specific-information: - -Algorithm Specific Information -****************************** +Simulation, Testing & Toolchain (SDK) +************************************* -Further information on specific algorithms, filter tuning, and design tools: +Verification frameworks, host audio simulation, fuzzing, and compiler toolchains. .. toctree:: :maxdepth: 1 - algorithms/demux/demux.rst - algorithms/eq/equalizers_tuning - algorithms/src/sample_rate_conversion - algorithms/tdfb/time_domain_fixed_beamformer + unit_tests + tech/cmake + testbench/index + xtrun/index + fuzzing/index + tech/compile_wsl diff --git a/developer_guides/intel-cavs/apollolake/apl-memory.rst b/developer_guides/intel-cavs/apollolake/apl-memory.rst deleted file mode 100644 index ce67b871..00000000 --- a/developer_guides/intel-cavs/apollolake/apl-memory.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _apl-memory: - -APL Memory -########## - -8000 0000h - Address aliasing to A000 0000h - BFFF FFFFh range (non L1 cacheable) - -9000 0000h - L2 cache alias address (non L1 cacheable). - HPSRAM alias 9E00 0000h. - LPSRAM alias 9E80 0000h - -A000 0000h - L2 cacheable memory (L1 cacheable). - Code/data in IMR accessed via L1 and L2 cache. - -B000 0000h - L2 uncacheable memory (L1 cacheable). - Code/data in IMR accessed via L1 cache. - -BE00 0000h - L2 local HPSRAM (L1 cacheable). 8 * 64KB - -BE80 0000h - L2 local LPSRAM (L1 cacheable). 2 * 64KB - -.. graphviz:: images/apl-memory.dot - :caption: APL Memory Map diff --git a/developer_guides/intel-cavs/apollolake/images/apl-memory.dot b/developer_guides/intel-cavs/apollolake/images/apl-memory.dot deleted file mode 100644 index d459d639..00000000 --- a/developer_guides/intel-cavs/apollolake/images/apl-memory.dot +++ /dev/null @@ -1,68 +0,0 @@ -digraph G { - node [fontsize=10, shape="record"] - edge [fontsize=10] - rankdir=LR - splines=ortho - - subgraph clusterDsp { fontsize=10 color=grey - dsp_1 [label="DSP" style=filled color="#f0f0f0"] - dsp_2 [label="DSP" style=filled color="#f0f0f0"] - dsp_3 [label="DSP" style=filled color="#f0f0f0"] - dsp_4 [label="DSP" style=filled color="#f0f0f0"] - dsp_5 [label="DSP" style=filled color="#f0f0f0"] - dsp_6 [label="DSP" style=filled color="#f0f0f0"] - dsp_7 [label="DSP" style=filled color="#f0f0f0"] - dsp_8 [label="DSP" style=filled color="#f0f0f0"] - } - - subgraph clusterL1 { fontsize=10 color=grey - l1_1 [label="L1" style=filled color="#e0e0e0"] - l1_2 [label="L1" style=filled color="#e0e0e0"] - l1_5 [label="L1" style=filled color="#e0e0e0"] - l1_7 [label="L1" style=filled color="#e0e0e0"] - } - - hpsram_l2_1 [label="HPSRAM L2" style=filled color="#d0d0d0"] - hpsram_l2_3 [label="HPSRAM L2" style=filled color="#d0d0d0"] - hpsram_local_5 [label="HPSRAM\nLocal mem" style=filled color="#d0d0d0"] - hpsram_local_6 [label="HPSRAM\nLocal mem" style=filled color="#d0d0d0"] - - lpsram_local_7 [label="LPSRAM\nLocal mem" style=filled color="#d0d0d0"] - lpsram_local_8 [label="LPSRAM\nLocal mem" style=filled color="#d0d0d0"] - - subgraph clusterImr { fontsize=10 color=grey - imr_1 [label="IMR" style=filled color="#c0c0c0"] - imr_2 [label="IMR" style=filled color="#c0c0c0"] - imr_4 [label="IMR" style=filled color="#c0c0c0"] - imr_3 [label="IMR" style=filled color="#c0c0c0"] - } - - /* L1 -> L2 -> IMR */ - dsp_1 -> l1_1 -> hpsram_l2_1 - hpsram_l2_1 -> imr_1 [label="@ A000 0000"] - - /* L1 -> IMR */ - dsp_2 -> l1_2 - l1_2 -> imr_2 [label="@ B000 0000"] - - /* L2 -> IMR */ - dsp_3 -> hpsram_l2_3 - hpsram_l2_3 -> imr_3 [label="@ 8000 0000"] - - /* -> IMR */ - dsp_4 -> imr_4 [label="@ 9000 0000"] - - /* DSP -> L1 -> HPSRAM */ - dsp_5 -> l1_5 - l1_5 -> hpsram_local_5 [label="@ BE00 0000"] - - /* DSP -> HPSRAM */ - dsp_6 -> hpsram_local_6 [label="@ 9E00 0000"] - - /* DSP -> L1 -> LPSRAM */ - dsp_7 -> l1_7 - l1_7 -> lpsram_local_7 [label = "@BE80 0000"] - - /* DSP -> LPSRAM */ - dsp_8 -> lpsram_local_8 [label = "@9E80 0000"] -} diff --git a/developer_guides/intel-cavs/apollolake/index.rst b/developer_guides/intel-cavs/apollolake/index.rst deleted file mode 100644 index 72c1bcf0..00000000 --- a/developer_guides/intel-cavs/apollolake/index.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _platform-apollolake: - -Intel Apollo Lake -################# - -Intel Apollo Lake (APL) platform is built on cAVS 1.5 HW and uses Xtensa DSP -architecture. - -The only Apollo Lake commercially-available platform is the Up Squared -board, which uses a BIOS compatible with SOF. Other platforms can be -supported but require a BIOS change. - -Chromebooks based on Gemini Lake support SOF directly in both the -official images and in developer mode. - -.. toctree:: - :maxdepth: 1 - - apl-memory diff --git a/developer_guides/intel-cavs/cannonlake/cnl-config.rst b/developer_guides/intel-cavs/cannonlake/cnl-config.rst deleted file mode 100644 index 5e4d9735..00000000 --- a/developer_guides/intel-cavs/cannonlake/cnl-config.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _cnl-config: - -CNL Configuration -################# - -Supported DAIs -************** - -- SSP: 3 instances exposed via ``dai_get()``. diff --git a/developer_guides/intel-cavs/cannonlake/cnl-memory.rst b/developer_guides/intel-cavs/cannonlake/cnl-memory.rst deleted file mode 100644 index c6577aa2..00000000 --- a/developer_guides/intel-cavs/cannonlake/cnl-memory.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _cnl-memory: - -CNL Memory -########## - -8000 0000h - Aliasing to A000 0000h - BFFF FFFFh range (non L1 cacheable). - -A000 0000h - L2 cacheable memory (L1 cacheable). - -B000 0000h - L2 uncacheable memory (L1 cacheable). - IMR (4MB size), see *IMR Allocation*. - -BE00 0000h - L2 local HPSRAM (L1 cacheable). - Seen as 8MB of virtual memory space (47 * 64KB). - -.. note:: By default, address virtualization is disabled. The Translation - Lookup Buffer (TLB) entries for populated HPSRAM banks have the - same values for virtual addresses and physical addresses. - -BE80 0000h - L2 local LPSRAM (L1 cacheable). - Accessed using physical addresses (1 * 64KB). - -BEFE 0000h - DSP ROM Code - - .. graphviz:: images/cnl-memory.dot - :caption: CNL Memory Map diff --git a/developer_guides/intel-cavs/cannonlake/images/cnl-memory.dot b/developer_guides/intel-cavs/cannonlake/images/cnl-memory.dot deleted file mode 100644 index 114384ed..00000000 --- a/developer_guides/intel-cavs/cannonlake/images/cnl-memory.dot +++ /dev/null @@ -1,20 +0,0 @@ -digraph G { - node [fontsize=10, shape="record"] - edge [fontsize=10] - rankdir=LR - splines=line - - dsp [label="DSP"] - mem_rom [label="ROM\nBEFE 00000\n(128K)"] - mem_alias [label="Alias\n8000 0000\n" group="memory"] - mem [label=" IMR\nB000 0000 - | HPSRAM\nBE00 0000 - | LPSRAM\nBE80 0000" group="memory"] - - dsp -> mem_alias:a [label="L1 uncached"] - - dsp -> mem:imr [label="L1 cached"] - dsp -> mem:hpsram [label="L1 cached"] - dsp -> mem:lpsram [label="L1 cached"] - -} diff --git a/developer_guides/intel-cavs/cannonlake/index.rst b/developer_guides/intel-cavs/cannonlake/index.rst deleted file mode 100644 index d01be7f8..00000000 --- a/developer_guides/intel-cavs/cannonlake/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _platform-cannonlake: - -Intel Cannon Lake -################# - -Intel Cannon Lake (CNL) platform is built on cAVS 1.8 HW and uses Xtensa DSP -architecture. - -.. toctree:: - :maxdepth: 1 - - cnl-memory - cnl-config diff --git a/developer_guides/intel-cavs/commons/images/core-enable.pu b/developer_guides/intel-cavs/commons/images/core-enable.pu deleted file mode 100644 index a30b09d7..00000000 --- a/developer_guides/intel-cavs/commons/images/core-enable.pu +++ /dev/null @@ -1,36 +0,0 @@ -participant core0 -participant core1 -participant ipc -participant cpu -participant alloc -participant idc -participant init - -core0 -> ipc : ipc_pm_core_enable(header) - activate ipc - - ipc -> cpu : cpu_enable_core(core_id) - activate cpu - - cpu -> alloc : alloc_core_context(core_id) - activate alloc - cpu <-- alloc - deactivate alloc - - cpu -> idc : idc_enable_interrupts(core_id) - activate idc - cpu <-- idc - cpu-> idc : arch_idc_send_msg(power_up, IDC_NON_BLOCKING) - cpu <-- idc - deactivate idc - - ipc <-- cpu - deactivate cpu - -core0 <-- ipc -deactivate ipc - -core1 -> init : slave_core_init() - activate init -init <-- core1 -deactivate init diff --git a/developer_guides/intel-cavs/commons/images/work-smp-cavs.pu b/developer_guides/intel-cavs/commons/images/work-smp-cavs.pu deleted file mode 100644 index 86f5b41f..00000000 --- a/developer_guides/intel-cavs/commons/images/work-smp-cavs.pu +++ /dev/null @@ -1,47 +0,0 @@ -participant ipc -participant "core 0" as core_0 -participant "core 1" as core_1 -participant wallclk - -ipc -> core_0 : new pipeline 0 (@core 0) - activate core_0 - core_0 -> wallclk : timer_register() - core_0 -> core_0 : work_schedule(ppl 0 dai, +1ms) - core_0 -> wallclk : work_set_timer(period = +1ms) -ipc <-- core_0 -deactivate core_0 - -wallclk -> core_0 : cb() @ next ms - activate core_0 - core_0 -> core_0 : ppl 0 dai cb() - activate core_0 - core_0 -> core_0 : ppl 0 copy - core_0 -> core_0 : work_schedule(ppl 0 dai, +1ms) - deactivate core_0 - core_0 -> wallclk : work_set_timer() - deactivate core_0 - -ipc -> core_0 : new pipeline 1 (@core 1) - core_0 -> core_1 - activate core_1 - core_1 -> wallclk : timer_register() - core_1 -> core_1 : work_schedule(ppl 1 dai) - core_0 <-- core_1 - deactivate core_1 - -wallclk -> core_0 : cb() @ next ms - activate core_0 - activate core_1 - core_0 -> core_0 : ppl 0 dai cb() - activate core_0 - core_0 -> core_0 : ppl 0 copy - core_0 -> core_0 : work_schedule(ppl 0 dai, +1ms) - deactivate core_0 - core_1 -> core_1 : ppl 1 dai cb() - activate core_1 - core_1 -> core_1 : ppl 1 copy - core_1 -> core_1 : work_schedule(ppl 1 dai, +1ms) - deactivate core_1 - deactivate core_1 - core_0 -> wallclk : work_set_timer() - deactivate core_0 diff --git a/developer_guides/intel-cavs/commons/images/work-st.pu b/developer_guides/intel-cavs/commons/images/work-st.pu deleted file mode 100644 index efefce6a..00000000 --- a/developer_guides/intel-cavs/commons/images/work-st.pu +++ /dev/null @@ -1,99 +0,0 @@ -scale max 800 height - -skinparam rectangle { - backgroundColor<> #6fccdd - backgroundColor<> #f6ed80 - backgroundColor<> #d6d6de - borderColor<> #d6d6de - borderColor<> #a1a1ca - - backgroundColor<> #f05772 - stereotypeFontColor<> #ffffff - fontColor<> #ffffff - - backgroundColor<> #f0f0f0 -} - -together { - ' ssp dais - rectangle "ssp-dai #0" as ssp_0 <> - rectangle "ssp-dai #1" as ssp_1 <> - ' hda dais - rectangle "hda-dai #0" as hda_0 <> -} - -rectangle "core #0" <> { - - together { - rectangle "hda-dma\nhost output #0" as hda_dma_ho_0 <> - rectangle "hda-dma\nhost input #0" as hda_dma_hi_0 <> - } - together { - rectangle "dw-dma #0" as dw_dma_0 <> - rectangle "dw-dma #1" as dw_dma_1 <> - } - - rectangle "playback #0" <> { - - rectangle "ppl #0" as ppl_0 <> { - rectangle "host comp" as host_0 - rectangle "vol" as vol_0 - rectangle "mix-in" as mix_in_0 - - host_0 --> vol_0 - vol_0 --> mix_in_0 - } - - rectangle "ppl #1" as ppl_1 <> { - rectangle "mix-out" as mix_out_1 - rectangle "dai comp" as dai_1 - - mix_out_1 --> dai_1 - } - mix_in_0 --> mix_out_1 - } - hda_dma_ho_0 --> host_0 - - dai_1 --> dw_dma_0 - dw_dma_0 --> ssp_0 - - rectangle "capture #0" <> { - rectangle "ppl #3" as ppl_3 <> { - rectangle "host comp" as host_3 - rectangle "dai comp" as dai_3 - host_3 <-- dai_3 - } - } - hda_dma_hi_0 <-- host_3 - dai_3 <-- dw_dma_1 - dw_dma_1 <-- ssp_1 - - ' now let's show who's driving - rectangle "work queue #0\n@core_0" as wq_0 <> - wq_0 .[#green]> mix_in_0 - wq_0 .[#green]> dw_dma_0 : new - wq_0 .[#green]> dw_dma_1 : new -} - -rectangle "core #1" <> { - - rectangle "hda-dma\nhost output #1" as hda_dma_ho_1 <> - rectangle "hda-dma\nlink input #0" as hda_dma_li_0 <> - - - rectangle "playback #1" <> { - rectangle "ppl #2" as ppl_2 <> { - - rectangle "host comp" as host_2 - rectangle "dai comp" as dai_2 - - host_2 --> dai_2 - } - } - hda_dma_ho_1 --> host_2 - dai_2 --> hda_dma_li_0 - hda_dma_li_0 --> hda_0 - - rectangle "work queue #1\n@core_1" as wq_1 <> - wq_1 .[#green]> hda_dma_li_0 -} diff --git a/developer_guides/intel-cavs/commons/index.rst b/developer_guides/intel-cavs/commons/index.rst deleted file mode 100644 index d853f6f1..00000000 --- a/developer_guides/intel-cavs/commons/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _platforms-cavs-commons: - -CAVS Commons -############ - -.. toctree:: - :maxdepth: 1 - - work-queue - multicore-processing diff --git a/developer_guides/intel-cavs/commons/multicore-processing.rst b/developer_guides/intel-cavs/commons/multicore-processing.rst deleted file mode 100644 index eaa0280f..00000000 --- a/developer_guides/intel-cavs/commons/multicore-processing.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. _platforms-intel-cavs-multicore: - -Multicore Processing -#################### - -Description -*********** - -|SOF| implements multicore processing so that the whole pipelines or single -components are executed on the selected core. The core selection is done by -the ``core`` field in ``struct sof_ipc_pipe_new`` or ``struct sof_ipc_comp`` -during creation. The core value cannot exceed the number of cores on the -current platform defined by ``CONFIG_MAX_CORE_COUNT``. - -.. code-block:: c - - struct sof_ipc_pipe_new { - struct sof_ipc_hdr hdr; - uint32_t comp_id; - uint32_t pipeline_id; - uint32_t sched_id; - uint32_t core; - uint32_t deadline; - uint32_t priority; - uint32_t mips; - uint32_t frames_per_sched; - uint32_t xrun_limit_usecs; - uint32_t timer; - } __attribute__((packed)); - - struct sof_ipc_comp { - struct sof_ipc_cmd_hdr hdr; - uint32_t id; - enum sof_comp_type type; - uint32_t pipeline_id; - uint32_t core; - - /** extended data length, 0 if no extended data (ABI3.17) */ - uint32_t ext_data_length; - } __attribute__((packed)); - -Core enablement -*************** - -Cores are enabled and disabled by sending the ``SOF_IPC_PM_CORE_ENABLE`` IPC -with the correct ``enable_mask``. The core must be enabled **before the -pipeline trigger start happens** and disabled **after the pipeline trigger -stop**. - -.. code-block:: c - - struct sof_ipc_pm_core_config { - struct sof_ipc_hdr hdr; - uint32_t enable_mask; - } - -.. uml:: images/core-enable.pu - -.. note:: The kernel also needs to enable cores on the host side, before - even sending the ``SOF_IPC_PM_CORE_ENABLE`` IPC to the FW. - For details on how to specify the DSP core in the topology file, refer to the topology documentation, :ref:`DSP Core Index `. - diff --git a/developer_guides/intel-cavs/commons/work-queue.rst b/developer_guides/intel-cavs/commons/work-queue.rst deleted file mode 100644 index 78953b9b..00000000 --- a/developer_guides/intel-cavs/commons/work-queue.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _platform-cavs-work-queue: - -Work Queues -########### - -On CAVS platforms, the wall clock is used as a time source for multiple work -queues (one work queue instance per active core). - -Since enough comparators are not available, all instances register to a shared -interrupt where one comparator is used to wake up all. The primary core -re-programs the wall clock to the next wake event. Its work queue operates in -*primary mode*. Work queues running on other cores are attached to the shared -time source on CAVS SMP platforms; these are configured to the *secondary mode*. On -other SMP platforms where multiple independent time sources are available, all -queues can be configured in *primary mode*. - -Synchronous SysTick on All Cores -******************************** - -The shared time source aligns work scheduling on all cores as all synchronously -wake up on the same periodic event via a system tick timer, or *SysTick*. - -SysTick periods are configurable. While no resolution is guaranteed, the -default value of 1ms is acceptable for works that are typically scheduled on -this system, specifically low latency works that are enabled and can be run on -multiple cores in sync. For ultra low latency configurations, the SysTick -period can be configured to a value of < 1ms. - -An HD/A DMA running in circular buffer mode (@ dai) is already registered in -the work queue with a specified timeout period of 1ms. Other DMAs can be -switched from their individual interrupt sources (buffer completion) to work -queues, thus making pipelines scheduling fully *systick aligned*. - -In the case of more complex topologies, pipelines that start/terminate with a -component other then dai can be also driven by work queues. - -.. note:: Work queue primary/secondary mode vs. independent mode configurable by - CONFIG @ compile time. The work queue min tick (1ms/0.33ms/1us) is - configurable @ run-time so that the current mode is still fully supported. - -.. uml:: images/work-st.pu - :caption: Work queue dependecies for CAVS SMP - -.. uml:: images/work-smp-cavs.pu - :caption: Work queue flow for CAVS SMP diff --git a/developer_guides/intel-cavs/icelake/icl-config.rst b/developer_guides/intel-cavs/icelake/icl-config.rst deleted file mode 100644 index f8e93dcf..00000000 --- a/developer_guides/intel-cavs/icelake/icl-config.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _icl-config: - -ICL Configuration -################# - -Supported DAIs -************** - -- SSP: 6 instances exposed via ``dai_get()``. diff --git a/developer_guides/intel-cavs/icelake/icl-memory.rst b/developer_guides/intel-cavs/icelake/icl-memory.rst deleted file mode 100644 index 19e3e313..00000000 --- a/developer_guides/intel-cavs/icelake/icl-memory.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _icl-memory: - -ICL Memory -########## - -Memory map is the same as on Cannon Lake. See :ref:`cnl-memory`. diff --git a/developer_guides/intel-cavs/icelake/index.rst b/developer_guides/intel-cavs/icelake/index.rst deleted file mode 100644 index cbcaeb3d..00000000 --- a/developer_guides/intel-cavs/icelake/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _platform-icelake: - -Intel Ice Lake -############## - -The Intel Ice Lake (ICL) platform is built on cAVS 2.0 HW and uses Xtensa DSP -architecture. - - -.. toctree:: - :maxdepth: 1 - - icl-memory - icl-config \ No newline at end of file diff --git a/developer_guides/intel-cavs/images/cavs-platform-deps.pu b/developer_guides/intel-cavs/images/cavs-platform-deps.pu deleted file mode 100644 index e1cc19f8..00000000 --- a/developer_guides/intel-cavs/images/cavs-platform-deps.pu +++ /dev/null @@ -1,29 +0,0 @@ -package cavs { - component 2.5 - component 2.0 - component 1.8 - component 1.5 -} - -package arch { - component host - component xtensa - component xtensa_smp -} - -1.5 ..> xtensa_smp -1.8 ..> xtensa_smp -2.0 ..> xtensa_smp -2.5 ..> xtensa_smp - -package platform { - component icelake - component cannonlake - component apollolake - component tigerlake -} - -apollolake ..> 1.5 -cannonlake ..> 1.8 -icelake ..> 2.0 -tigerlake ..> 2.5 diff --git a/developer_guides/intel-cavs/index.rst b/developer_guides/intel-cavs/index.rst deleted file mode 100644 index cc2b7bd1..00000000 --- a/developer_guides/intel-cavs/index.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _platforms-intel-cavs: - -Intel CAVS Platforms -#################### - -Intel CAVS platforms supported by the |SOF|. - -+---------+----------+-----------------------------------------+ -|cAVS |ver. 1.5 | Apollo Lake, Gemini Lake | -| +----------+-----------------------------------------+ -| |ver. 1.8 | Cannon Lake, Whiskey Lake, Comet Lake | -| +----------+-----------------------------------------+ -| |ver. 2.0 | Ice Lake | -| +----------+-----------------------------------------+ -| |ver. 2.5 | Tiger Lake | -+---------+----------+-----------------------------------------+ - -.. note:: While the Skylake and Kaby Lake platforms are also based on the - cAVS 1.5 architecture, they are not supported at this time due to - differences in boot flow and memory architecture. - -.. uml:: images/cavs-platform-deps.pu - :caption: CAVS Platforms - -.. toctree:: - :maxdepth: 1 - - commons/index - apollolake/index - cannonlake/index - icelake/index - tigerlake/index diff --git a/developer_guides/intel-cavs/tigerlake/images/tgl-memory.dot b/developer_guides/intel-cavs/tigerlake/images/tgl-memory.dot deleted file mode 100644 index 0bba71e5..00000000 --- a/developer_guides/intel-cavs/tigerlake/images/tgl-memory.dot +++ /dev/null @@ -1,24 +0,0 @@ -digraph G { - node [fontsize=10, shape="record"] - edge [fontsize=10] - rankdir=LR - splines=line - - dsp [label="DSP"] - mem_rom [label="ROM\n9F18 00000\n(512KB)"] - mem_alias [label="Alias\n8000 0000\n" group="memory"] - mem [label=" IMR\nB000 0000 - | HPSRAM\nBE00 0000 - | LPSRAM\nBE80 0000 - | L1DSRAM\n9F10 000 - | L1ISRAM\n9F18 0000" group="memory"] - - dsp -> mem_alias:a [label="L1 uncached"] - - dsp -> mem:imr [label="L1 cached"] - dsp -> mem:hpsram [label="L1 cached"] - dsp -> mem:lpsram [label="L1 cached"] - - dsp -> mem:l1dsram [label="L1 local"] - dsp -> mem:l1isram [label="L1 local"] -} diff --git a/developer_guides/intel-cavs/tigerlake/index.rst b/developer_guides/intel-cavs/tigerlake/index.rst deleted file mode 100644 index aa76c83e..00000000 --- a/developer_guides/intel-cavs/tigerlake/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _platform-tigerlake: - -Intel Tiger Lake -################# - -The Intel Tiger Lake (TGL) platform is built on cAVS 2.5 HW and uses Xtensa -DSP architecture. - -.. toctree:: - :maxdepth: 1 - - tgl-memory - tgl-config diff --git a/developer_guides/intel-cavs/tigerlake/tgl-config.rst b/developer_guides/intel-cavs/tigerlake/tgl-config.rst deleted file mode 100644 index 52b20041..00000000 --- a/developer_guides/intel-cavs/tigerlake/tgl-config.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _tgl-config: - -TGL Configuration -################# - -Supported DAIs -************** - -- SSP: 6 instances exposed via ``dai_get()``. diff --git a/developer_guides/intel-cavs/tigerlake/tgl-memory.rst b/developer_guides/intel-cavs/tigerlake/tgl-memory.rst deleted file mode 100644 index 58458625..00000000 --- a/developer_guides/intel-cavs/tigerlake/tgl-memory.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _tgl-memory: - -TGL Memory -########## - -8000 0000h - Aliasing to A000 0000h - BFFF FFFFh range (non L1 cacheable). - -A000 0000h - L2 cacheable memory (L1 cacheable). - -B000 0000h - L2 uncacheable memory (L1 cacheable). - IMR (4MB size), see *IMR Allocation*. - -BE00 0000h - L2 local HPSRAM (L1 cacheable). - Seen as 8MB of virtual memory space (46 * 64KB). - -.. note:: By default, address virtualization is disabled. The Translation - Lookup Buffer (TLB) entries for populated HPSRAM banks have the - same values for virtual addresses and physical addresses. - -BE80 0000h - L2 local LPSRAM (L1 cacheable). - Accessed using physical addresses (1 * 64KB). - -9F00 0000h - L1 local D-SRAM (512 KB) - Directly accessed from core #0 only. - -9F10 0000h - L1 local I-SRAM (512 KB) - Directly accessed from core #0 only. - -.. note:: The SOF version that will add Local L1 Data & Instruction SRAM - support is subject to future development. - -9F18 0000h - DSP ROM Code - Directly accessed from core #0 only. - - .. graphviz:: images/tgl-memory.dot - :caption: TGL Memory Map diff --git a/developer_guides/intel-legacy/baytrail/index.rst b/developer_guides/intel-legacy/baytrail/index.rst deleted file mode 100644 index 8b5040ca..00000000 --- a/developer_guides/intel-legacy/baytrail/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _platform-baytrail: - -Intel Bay Trail / Cherry Trail -############################## - -Intel Bay Trail platform is based on an Atom CPU and a Tensilica HiFi2 -EP DSP. It relies on both internal memory and caches to access DDR -memory. The Bay Trail processor relies on a 25 MHz oscillator. - -Supported commercially-available platforms include the MinnowBoard -Turbot, tablets and laptops built for Windows (SOF requires a Linux -installation). - -The Cherry Trail platform is similar to Bay Trail but it relies on a -19.2 MHz osciilator. Supported commercially-available platforms -include the Up board and devices built for Windows (SOF requires a -Linux installation). - -Bay Trail and Cherry Trail Chromebooks can support SOF but the official -images are still based on the closed-source firmware solution. diff --git a/developer_guides/intel-legacy/broadwell/index.rst b/developer_guides/intel-legacy/broadwell/index.rst deleted file mode 100644 index 1fd903b9..00000000 --- a/developer_guides/intel-legacy/broadwell/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _platform-broadwell: - -Intel Broadwell -############### - -Intel Broadwell platform is based on an core CPU and a Tensilica HiFi2 -EP DSP integrated in the PCH. It relies only on internal memory (no -caches). - -Supported commercially-available platforms are limited, but include: - -- Dell Latitude 13 7350 2-in-1 laptop -- Dell Venue 11 Pro 7140 tablet -- Dell XPS 13 9343 laptop -- Google Chromebook Pixel (2015) -- HP Spectre x360 (2015) 2-in-1 laptop - diff --git a/developer_guides/intel-legacy/index.rst b/developer_guides/intel-legacy/index.rst deleted file mode 100644 index ccc590e8..00000000 --- a/developer_guides/intel-legacy/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _platforms-intel-Hifi2-EP: - -Intel Hifi2-EP Platforms -######################## - -Intel platforms based on the Tensilica Hifi2-EP DSP supported by the |SOF|. - -+------------+--------------------------------------------------+ -| Atom/PCI | Merrifield (Edison) | -+------------+--------------------------------------------------+ -| Atom/ACPI | Bay Trail, Cherry Trail, Braswell | -+------------+--------------------------------------------------+ -| Core/ACPI | Broadwell (Chromebook Pixel 2015, Dell XPS) | -+------------+--------------------------------------------------+ - -.. toctree:: - :maxdepth: 1 - - merrifield/index - baytrail/index - broadwell/index diff --git a/developer_guides/intel-legacy/merrifield/index.rst b/developer_guides/intel-legacy/merrifield/index.rst deleted file mode 100644 index b6a7311d..00000000 --- a/developer_guides/intel-legacy/merrifield/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _platform-merrifield: - -Intel Merrifield -################ - -Intel Merrifield platform is based on an Atom CPU and a Tensilica HiFi2 -EP DSP. It is very similar to Bay Trail but uses a PCI-based -enumeration and has a clocking structure similar to Cherry Trail. - -This platform is no longer commercially available, but the Edison -platform is supported by the open-source community. diff --git a/developer_guides/intel_debug/introduction.rst b/developer_guides/intel_debug/introduction.rst deleted file mode 100644 index 11e8ca55..00000000 --- a/developer_guides/intel_debug/introduction.rst +++ /dev/null @@ -1,319 +0,0 @@ -.. _intel_debug_introduction: - -Overview of Intel hardware platforms -#################################### - -ACPI platforms (introduced before and up to 2015) -************************************************* - -On Bay Trail, Cherry Trail, Braswell, and Broadwell devices (also referred to -as `legacy` devices), the DSP enumeration is handled by the ACPI -subsystem. - -1. Local audio accessories (mics, speakers, headset) ----------------------------------------------------- - -On Bay Trail, Cherry Trail, Braswell, and Broadwell, the BIOS can either -enable or disable the DSP: - -* Enable the DSP. In this case, a DSP driver is required. This mode is - selected on platforms where the audio interface for 3rd-party codecs is based on the I2C/I2S/TDM interfaces. - -* Disable the DSP. In this case, an HDaudio controller is exposed and the - ``snd-intel-hda`` driver will take care of all audio usages. SOF cannot be used in this case. - - -2. HDMI/DP interfaces ---------------------- - -On Broadwell, HDMI/DP is handled by an HDaudio controller. - -On Bay Trail/Cherry Trail and Braswell, the BIOS can enable two modes: - -* HDAudio-based solution (similar to Broadwell). - -* LPE HDMI Audio. This mode is used by the majority of tablets and low-cost - devices. It provides functionality similar to HDaudio, but with a different interface. This mode is enabled in Linux via the ``CONFIG_HDMI_LPE_AUDIO`` option. - -The DSP cannot control any of these interfaces because SOF does not support -HDMI/DP on those devices. - -On all of these legacy platforms, HDMI support is exposed in Linux as a -separate card. - -PCI devices (introduced after 2016) -*********************************** - -In newer devices, the same HDAudio controller can handle both local -accessories and HDMI/DP interfaces. However, SOF is not always -supported on those platforms. - -When the Intel DSP is not enabled in the BIOS (OEM choice), audio -interfaces are handled by the ``snd-hda-intel`` driver. The platform only -exposes PCM devices and no audio processing capabilities. - -When OEM platforms integrate digital microphones attached directly -to the Intel chipset (aka DMIC), or they use I2C/I2S or SoundWire -interfaces, the DSP must be enabled by the BIOS. There is, however, one -more option. On Skylake and Kaby Lake platforms, the Intel DSP is handled by -the ``snd-soc-skl`` module which relies on closed-source firmware. - -SOF is available on Intel PCI devices starting with Gemini Lake, and -has since been the only solution provided by Intel for the following -platforms: Comet Lake, Ice Lake, and Tiger Lake. - -Since multiple drivers can register for the same PCI ID, it was (until -recently) common for users and distributions to use the wrong -driver, which could only be resolved by changing the Linux ``.config`` file -or deselecting drivers in the ``/etc/modprobe.d`` configuration files. - -The ``snd-intel-dspcfg`` module introduced in early 2020 exposes an API -used by all drivers, and the user can now override default choices by -setting the ``dsp_driver`` parameter. For example, setting - -.. code-block:: cfg - - options snd-intel-dspcfg dsp_driver=1 - -will allow for the HDaudio legacy driver to be used. This will typically -work for speakers and headphones/headsets, but will not allow DMIC -capture. - -Conversely, when a platform does not require a DSP-based platform, but -the DSP is still enabled by the OEM, the user or integration can -force the SOF Linux driver to be used. - -.. code-block:: cfg - - options snd-intel-dspcfg dsp_driver=3 - - -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 ------------ - -1.1. Base firmware ------------------- - -The firmware file, ``/lib/firmware/intel/sof/sof-tgl.ri`` (example -location for Intel Tiger Lake), contains all DSP code and tables. On -PCI devices, the firmware can only be signed by an Intel production -key which prevents community users from installing their own firmware. -Notable exceptions include Google Chromebooks and Up2/Up-Extreme -boards, where the *community key* is used. - -The Intel ME (Management Engine) is responsible for authentication of -the firmware, whether it is signed by an Intel production key (consumer -products), a community key (open development systems and Chromebooks -since Gemini Lake) or an OEM key. If the Intel ME is disabled by an -OEM, or disabled by user-accessible BIOS options, the firmware -authentication will fail and the firmware boot will not complete. If -the ME is disabled by the OEM, the only solution is to fall-back -to the legacy HDAudio driver. If the ME is disabled by the user, the user -must re-enable it. Unfortunately, no documented mechanism exists for the -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. Non-modular and modular firmware releases ----------------------------------------------- - -SOF project releases for Intel platforms are either a single firmware or modular firmware based. - -1.3.1. Non-modular firmware releases ------------------------------------- - -The release contains single a firmware image: **sof-PLAT.ri** - -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** : On demand loadable library identified by UUID. If the library contains multiple modules then a UUID symlink must be provided for each one. - -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. - -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. - - The firmware folder and filename can be overridden with "fw_path" and "fw_filename" SOF kernel parameters. - - The loadable module library path can be overridden with "lib_path" SOF kernel parameter. - -2. Topology file ----------------- - -The topology file, such as ``/lib/firmware/intel/sof-tplg/sof-hda-generic-2ch.tplg``, describes the processing graph and controls to -be instantiated by the SOF driver. The topology can be regenerated and -reconfigured with tools but requires expert knowledge of the ALSA/ASoC/topology frameworks. - -.. list-table:: Firmware topology file look-up paths per Intel platform - :widths: 50 5 50 25 - :header-rows: 1 - - * - Platform - - IPC type - - Topology load path - - Notes - * - Raptor Lake and older - - IPC3 - - /lib/firmware/intel/sof-tplg/sof-CONFIG.tplg - - CONFIG = topology variant needed for detected hardware configuration - * - Tiger Lake and newer - - IPC4 - - /lib/firmware/intel/sof-ipc4-tplg/sof-CONFIG.tplg - - CONFIG = topology variant needed for detected hardware configuration - -Important notices: - - For compatibility reasons with respect to **Meteor Lake** ``/lib/firmware/intel/sof-ace-tplg`` must be symlinked to ``/lib/firmware/intel/sof-ipc4-tplg`` - - 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. - - The topology folder and filename can be overridden with "tplg_path" and "tplg_filename" `snd_sof_pci` kernel parameters. - -3. UCM file ------------ - -The UCM file, such as ``/usr/share/alsa/ucm2/sof-hda-dsp/``, configures -the controls exposed by the topology file and the external audio -chips. UCM can be used in a terminal via the ``alsaucm`` command but -will typically be used by audio servers such as PulseAudio or -PipeWire. UCM files released by Intel are compatible with different -drivers and should work when changing the ``dsp_driver`` parameter. - -The selection of firmware, topology, and UCM files is based on platform -capabilities, codec names, and DMI options. While the SOF team and the -community try to cover all possible cases, errors will happen when the -wrong file is selected at any of the three layers. - -4. Chromebooks and SOF ----------------------- - -As stated above, starting from 2019/2020, Intel Chromeboooks have been -configured with the *community* key. It means that Chromebooks can run -audio firmware signed by anyone. The entire filesystem is locked by -default instead, but there are several options to disable security for -development purposes. In all cases the first step is to switch the -Chromebook to (non-secure) `Developer Mode -`_. -Developer Mode is the only required step if you only -want to install and run your own SOF firmware and are not interested in -changing anything else in Chrome OS. - -If you need the flexibility to make more changes, Chromebooks can run -Linux in several non-mutually exclusive ways. All the options listed -below let you run any SOF firmware. One of the biggest -differences between them is how to install and run your own Linux -kernel. - -- **Chrome OS** has direct hardware access, but Chrome OS development - cannot happen on Chrome OS itself. It requires a separate workstation - similar to how most embedded development typically does. For - information about setting up the ``cros_sdk``, see the `Chromium OS - Developer Guide - `_. - The ``cros_sdk`` is a complete environment that lets you modify - anything in Chrome OS and even build an entire system image. The - ``cros_sdk`` requires significant disk space and some learning - effort if you are not already familiar with Portage, a build system - in Gentoo, and especially with building the Linux kernel in Portage. - -- `Crostini - `_ - is a secure Linux Virtual Machine that does not have direct access - to the hardware and cannot be used for SOF. It does not require - Developer Mode. Crostini is listed here for completeness. You might - use Crostini as your pseudo-separate ``cros_sdk`` workstation, but a - different, more powerful system that you never have to reboot is a - much better ``cros_sdk`` option. - -- **Crouton** is a non-secure chroot that does allow direct hardware - access and can be used for SOF. It lets you install a choice of - popular Linux distributions, which you can use for development on the device - itself. Make regular backups! The Zephyr project has `very detailed - specific instructions - `_ - on how to use Crouton for SOF. Most of these instructions are not - Zephyr-specific. With Crouton, you can configure and compile a Linux - kernel as usual. However, the kernel *installation* process is similar - to the ``cros_sdk`` process with a couple of small twists. - -- Finally, it is possible to **dual-boot** or completely replace - Chrome OS with a regular Linux distribution on *some* Chromebooks and - forget it is a Chromebook entirely. However, this comes at a price: it - is the least secure option and the more likely to make your device - permanently unusable ("brick"). That level of risk is highly dependent - on your particular Chromebook model. If that does not scare you, then - https://chrx.org/ is a good starting point. Pay special attention to - the note on security. This is the only option that lets you manage - kernel installations as a typical Linux distribution does. diff --git a/developer_guides/intel_debug/suggestions.rst b/developer_guides/intel_debug/suggestions.rst deleted file mode 100644 index 5a01e805..00000000 --- a/developer_guides/intel_debug/suggestions.rst +++ /dev/null @@ -1,340 +0,0 @@ -.. _debug_suggestions: - -Suggestions before filing an SOF bug -#################################### - -Run alsa-info -************* - -The ``alsa-info`` script extracts a lot of information from the platform -(PCI ids, ACPI ids, DMI, controls, dmesg) that will help the SOF team -understand which hardware and OEM configuration is used. ``alsa-info`` -can upload the results to a server; providing the link is very useful -when filing a bug. - -Disable SOF on PCI/HDaudio devices to test audio playback -********************************************************* - -When audio issues occur, first see if the HDaudio legacy can generate sound -on speakers and headsets. Accomplish this by adding "options -snd-intel-dspcfg dsp_driver=1" to ``/etc/modprobe.d/alsa-base.conf``. - -If no sound can be heard and jack detection is not functional, an -HDaudio external codec configuration is likely. In some cases, the -Linux drivers are missing configuration information and may only -enable two of the four speakers present. - -All of these cases are orthogonal to SOF issues in that the SOF driver -cannot compensate for codec driver problems on its own. The HDaudio -codec configuration is handled by the legacy HDAudio driver -(snd-hda-intel), which is not maintained directly by SOF developers. - -Try booting into Windows first, then reboot into Linux -****************************************************** - -On some platforms, such as with an HDaudio codec connected to -amplifiers over an I2C/I2S link, the codec driver needs to perform a -set of amplifier configurations. This is often handled in Windows but -not in Linux codec drivers. A classic example of such issues is when -headphone playback works, but speaker playback does not (or not on all -speakers). Booting first in Windows then rebooting in Linux may help -setup the right configuration, but additional work is needed to patch -the Linux kernel. - -Reverse-engineer the Windows audio driver -***************************************** - -The HDaudio driver configures the codec with 'verb' commands to -e.g. setup the 'pins' or a coefficient. The exact values used are -device-specific, and in the absence of any documentation from the -codec vendor need to be reverse-engineered by snooping HDAudio -commands in a Windows environment. - -The following links provide additional information on snooping the -commands and determining what needs to be added to the Linux -kernel. These links are not maintained by SOF developers. - -* `ASUS Linux blog `_ - -* `How to sniff verbs from a Windows sound driver `_ - -Make sure the ME is enabled -*************************** - -If the ME is disabled by the OEM or the user, firmware authentication -will fail without any explicit feedback provided to the user. In case -of any authentication failure, verify that the ME is not disabled. More -information about the ME is available in the "Firmware binary" section of :ref:`intel_debug_introduction`. - -Test at the ALSA 'hw' device level -********************************** - -When the legacy HDaudio driver produces audible sound without -distortion and an SOF-based solution does not, user space configuration -issues are possible. - -Use the following commands to check if the SOF driver is functional at the hardware device level: - -.. code-block:: console - - speaker-test -Dhw:0,0 -c2 -r48000 -f S16_LE - arecord -Dhw:0,0 -c2 -r48000 -f S16_LE -d 10 test.wav - -The card and device indices may need to be adjusted on different -platforms: use ``aplay -l`` and ``arecord -l`` to see supported values on -your platform. - -If the playback or capture seems ok at the hardware device level, then the -following packages may need to be updated: - -- alsa-lib -- alsa-ucm-conf -- pulseaudio - -Verify mixer settings -********************* - -A classic issue with Linux audio is that a mixer control value remains -muted or with a volume set to zero. The ``alsamixer`` command can be -used to check if any paths are disabled (represented as "m") or if the -volume settings are not correct. - -Note that randomly playing with ALSA mixer settings can damage audio -accessories, speakers, or your hearing. Never change mixer -settings while listening to loud music on a headset! - -Enable dynamic debug -******************** - -To avoid spamming all Linux users with audio-specific information, -only critical errors are reported in the ``dmesg`` log. That information -may not be enough to debug a specific issue, and the recommendation is -to add the following options to the ``/etc/modprobe.d/sof-dyndbg.conf`` -file: - -.. code-block:: cfg - - # ACPI - options snd_sof_acpi dyndbg=+pmf - options snd_sof_acpi_intel_byt dyndbg=+pmf - options snd_sof_acpi_intel_bdw dyndbg=+pmf - options snd_sof_intel_byt dyndbg=+pmf - options snd_sof_intel_bdw dyndbg=+pmf - - # PCI - options snd_sof_pci dyndbg=+pmf - options snd_sof_pci_intel_apl dyndbg=+pmf - options snd_sof_pci_intel_cnl dyndbg=+pmf - options snd_sof_pci_intel_icl dyndbg=+pmf - options snd_sof_pci_intel_tgl dyndbg=+pmf - options snd_sof_pci_intel_mtl dyndbg=+pmf - options snd_sof_pci_intel_lnl dyndbg=+pmf - - # DSP selection - options snd_intel_dspcfg dyndbg=+pmf - options snd_intel_sdw_acpi dyndbg=+pmf - - # SOF internals - options snd_sof_intel_hda_common dyndbg=+pmf - options snd_sof_intel_hda_generic dyndbg=+pmf - options snd_sof_intel_hda_mlink dyndbg=+pmf - options snd_sof_intel_hda dyndbg=+pmf - options snd_sof dyndbg=+pmf - options snd_sof_nocodec dyndbg=+pmf - - # HDA - options snd_hda_intel dyndbg=+pmf - options snd-hda-codec-realtek dyndbg=+pmf - options snd-hda-codec-generic dyndbg=+pmf - options snd-hda-codec-hdmi dyndbg=+pmf - options snd-hda-codec dyndbg=+pmf - - # SoundWire core - options soundwire_bus dyndbg=+pmf - options soundwire_generic_allocation dyndbg=+pmf - options soundwire_cadence dyndbg=+pmf - options soundwire_intel_init dyndbg=+pmf - options soundwire_intel dyndbg=+pmf - -Note that this list is only an example. - -Dynamic debug is a Linux kernel feature. For detailed information, see the -official `kernel documentation `__. - -Install sof-logger -****************** - -If an issue with the SOF firmware is reported, such as IPC errors, SOF -developers will need DSP traces. This is typically done by installing -``/usr/local/bin/sof-logger`` as well as the ``.ldc`` file, and using the -following command to extract DSP traces: - - -.. code-block:: bash - - sof-logger -t -l sof-tgl.ldc - -Trace support might need to be enabled on distribution kernels in case the -``/sys/kernel/debug/sof/trace`` file is not present by adding sof_debug=1 option -to snd_sof module: - -.. code-block:: cfg - - options snd_sof sof_debug=1 - - -Digital mic issues -****************** - -The SOF driver and firmware have limited information related to the -number of digital microphones and their physical location. - -On devices designed for Windows, the presence of the microphone is -reported as an NHLT endpoint (ACPI table in the BIOS). The SOF Linux -driver will report this information with a 'dmesg' log such as - -.. code-block:: none - - [ 4.301490] sof-audio-pci-intel-tgl 0000:00:1f.3: DMICs detected in NHLT tables: 2 - -Recent versions of the ACPICA tools (acpica-tools package) can also be -used to visualize the ACPI tables. - -In some instances the number of DMICs reported by the NHLT does not -match the hardware layout. The SOF driver provides a means to alter -the value with a kernel parameter which can be added in -/etc/modprobe.d/alsa-base.conf (or any other configuration file with -this .conf extension). A reboot is necessary after changing the value - -.. code-block:: cfg - - options snd_sof_intel_hda_common dmic_num=4 - -The following command can then be used to check if the microphones are active at the lowest level - -.. code-block:: bash - - arecord -Dhw:0,6 -c4 -r48000 -fS32_LE -d 10 test.wav - -In 99% of the cases, hardware designers connect the two microphones on -the PDM0 controller. Some platforms use PDM1, which cannot really be -detected by the OS. By capturing in 4ch mode, it's possible that -channel3 and 4 capture data while channel0 and channel1 only show -signs of transitions and DC-removal. Simply talking or recording music -in this 10s test, then visualizing the recorded file with Audacity is -often enough to diagnose the presence of 2 microphones on the 'wrong' -PDM controller. - -In that case, a different topology file needs to be used, typically -sof-hda-generic-2ch-pdm1.tplg. On older distributions, it will be -necessary to override the file installed in -/lib/firmware/intel/sof-tplg/sof-hda-generic-2ch.tplg. On kernels -5.20+ a kernel parameter will be enough with no need to change and -override installed topology files, e.g. - -.. code-block:: cfg - - options snd-sof-pci tplg_filename=sof-hda-generic-2ch-pdm1.tplg - -These PDM1 issues are tracked in GitHub with the label 'DMIC-PDM1' in the -`firmware issues `_ -and in the `Linux issues `_. - -Users running Linux distributions on Chromebooks routinely experience -issues with digital microphones. In the Chrome environment, the -topology always exposes 4 channels, and UCM files for specific -platforms specify which of the 4 channels are valid. A plugin will -then drop the useless/non-populated channels. This capability does not -exist yet in upstream UCM/Linux. Capturing with the 'arecord; command -above will help understand which channels are valid and configure UCM -files. - -ES8336 support -************** - -Since 2021, a number of OEMs relied on the ES8336 codec from Everest -Audio on platforms as varied as AppoloLake, GeminiLake, JasperLake, -CometLake, AlderLake. - -End-users can verify if the hardware uses this configuration by -running the 'alsa-info' command and checking for the presence an ACPI -_HID, e.g. - -.. code-block:: none - - /sys/bus/acpi/devices/ESSX8336:00/status 15 - -.. code-block:: none - - /sys/bus/acpi/devices/ESSX8326:00/status 15 - -Support for this platform only stated upstream with the kernel -5.19-rc1. Any attempts with earlier kernels will require backports and -experimental patches to be added. In the case of the 8326, the codec -vendor submitted a driver to the ALSA/ASoC maintainers, which was not -merged as of July 2022. In this specific case end-users will be forced -to compile their own kernel. - -The SOF driver implemented an automatic detection of the SSP/I2S port -used by hardware and the presence of digital microphones based on -platform firmware/NHLT. - -There are however a number of hardware configurations that cannot be -detected from platform firmware. To work-around this limitation, the -'sof-es8336' machine driver exposes a 'quirk' kernel parameter which -can be used for modify GPIO and jack detection settings. Existing -quirks are listed in the sound/soc/intel/boards/sof_es8336.c machine -driver: - -.. code-block:: c - - #define SOF_ES8336_SPEAKERS_EN_GPIO1_QUIRK BIT(4) - #define SOF_ES8336_JD_INVERTED BIT(6) - #define SOF_ES8336_HEADPHONE_GPIO BIT(7) - #define SOC_ES8336_HEADSET_MIC1 BIT(8) - - -The default and actual quirk values for the platform can be obtained -from the kernel logs in the line as follows: - -.. code-block:: none - - ... - sof-essx8336 sof-essx8336: quirk mask 0x1a0 - ... - -for the unchanged mask, or: - -.. code-block:: none - - ... - sof-essx8336 sof-essx8336: Overriding quirk 0x1a0 => 0x120 - ... - -for the quirk overriding. - -The overridden quirk value can also be obtained from the -/sys/module/snd_soc_sof_es8336/parameters/quirk (the value is reported -as a plain integer, not hexadecimal). If the quirk is not overridden, -the `-1` value is returned. - -Changes to the default can be added with the following option in -e.g. /etc/modprobe.d/alsa-base.conf. Only the bits listed above can be -modified; others need to remain as is. - -.. code-block:: cfg - - options snd_soc_sof_es8336 quirk= - -Changing quirk values is an extremely experimental endeavor that -should only attempted by users with working knowledge of the Linux -audio subsystem and an understanding that playing with hardware -settings MAY DAMAGE HARDWARE or generate extremely loud sounds that -MAY DAMAGE YOUR HEARING. - -In rare cases, some platforms use the MCLK1 signal instead of -MCLK0. As of July 2022, there is no turn-key solution for those -platforms. - -These ES8336 issues are tracked in GitHub with the label 'codec -ES8336' in the `Linux ES8336 issues `_. diff --git a/developer_guides/introduction.rst b/developer_guides/introduction.rst deleted file mode 100644 index 33acd03e..00000000 --- a/developer_guides/introduction.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. _developer_guides_introduction: - -Introduction -============ - -|SOF| is mainly written in C with a small assembler for DSP initialization -and some DSP intrinsic values for media processing. The intended audience is -software developers familiar with C programming and media processing. - -Developers wishing to participate with upstream should also be familiar with -git and GitHub. - -Knowledge of hardware debugging (such as JTAG) and use of emulators is also -desirable if bringing up new hardware. - - -SOF Core Concepts ------------------ - -Following are core concepts and terms used by SOF developers. - -**Component** An audio or signal processing component that processes input -data into output data. Components can have one or more input source buffers -and one or more output sink buffers. Components can also send and receive -runtime configuration data that can be used to monitor or alter the data processing. - -**Buffer** A memory region that can be used to share audio processing data -between components. Buffers can have certain attributes depending on their -usage, such as a DMA'able buffer. - -**Pipeline** A collection of audio processing components and buffers that -are scheduled for processing together such as a schedA pipeline that can -have multiple source and sink endpoints. The endpoints may be other -pipelines or components. - -**DAI** Digital Audio Interface. A hardware audio serial interface used to -send audio data between hardware devices. Examples are I2S, Soundwire, PDM, HDA, and HDMI. - -**Topology** A high-level description of the network of all pipelines and -components enumerated on the DSP. This is initially described in text format -before being compiled into a binary that firmware can process. - -**Module** Another name for component. Implies that a component is linked at -runtime rather than at build time. - -**Driver** A device driver used by firmware to control hardware devices (such as DMA or I2S) or a |SOF| host OS device driver. - -**AAL** Architecture Abstraction Layer. A firmware abstraction layer used to -abstract architecture-specific code. - -**SRC** Sample Rate Converter. An audio component used to convert the sample -rate of a synchronous input stream to a synchronous output stream. diff --git a/developer_guides/linux_driver/third_party/keyword_detect/keyword_detect.rst b/developer_guides/linux_driver/third_party/keyword_detect/keyword_detect.rst index f33bdde4..4f5a8640 100644 --- a/developer_guides/linux_driver/third_party/keyword_detect/keyword_detect.rst +++ b/developer_guides/linux_driver/third_party/keyword_detect/keyword_detect.rst @@ -16,7 +16,7 @@ keyphrase (keyword) is successfully detected. Offloading the keyphrase detection algorithm to the embedded processing environment (i.e. dedicated DSP) reduces system power consumption while listening for an utterance. -To learn how to integrate a 3rd-party detection algorithm into the SOF firmware, refer to :ref:`KD-integration`. +To learn how to integrate a 3rd-party detection algorithm into the SOF firmware, refer to the upstream `Module Adapter Specification `_ and :ref:`llext_modules`. Keyword Detection pipelines *************************** diff --git a/developer_guides/nxp/sof_imx_user_guide.rst b/developer_guides/nxp/sof_imx_user_guide.rst index c7e2f6c7..84e31678 100644 --- a/developer_guides/nxp/sof_imx_user_guide.rst +++ b/developer_guides/nxp/sof_imx_user_guide.rst @@ -175,19 +175,7 @@ SOF firmware See Step 3 :ref:`build-from-scratch`. -Tools ------ -See Step 4 in :ref:`build-from-scratch`. - -The sof-logger must be cross-compiled in order to run on arm64: - -.. code-block:: bash - - $ cd "$SOF_WORKSPACE"/sof/tools/ - $ mkdir build_tools && cd build_tools - $ cmake .. -DCMAKE_TOOLCHAIN_FILE=../scripts/cross-arch64.cmake - $ make sof-logger Audio scenarios *************** diff --git a/developer_guides/setup_special_device/images/minnow_turbot.png b/developer_guides/setup_special_device/images/minnow_turbot.png deleted file mode 100644 index 94d3d048..00000000 Binary files a/developer_guides/setup_special_device/images/minnow_turbot.png and /dev/null differ diff --git a/developer_guides/setup_special_device/setup_minnowboard_turbot.rst b/developer_guides/setup_special_device/setup_minnowboard_turbot.rst deleted file mode 100644 index 9c1f4dbf..00000000 --- a/developer_guides/setup_special_device/setup_minnowboard_turbot.rst +++ /dev/null @@ -1,189 +0,0 @@ -.. _setup_minnowboard_turbot: - -Set up SOF on MinnowBoard Turbot -################################ - -.. contents:: - :local: - :depth: 3 - -MinnowBoard resources -********************* - -About Turbot -============ - -https://minnowboard.org/minnowboard-turbot/technical-specs - -Schematic -========= - -https://minnowboard.org/minnowboard-turbot/documentation - -BIOS -==== - -We recommend using the latest version. - -https://firmware.intel.com/projects/minnowboard-max - -Development -*********** - -Hardware Rework & Connect External Audio Codec -============================================== - -* Realtek ALC5651 -* Dialog DA7212 - -Update BIOS and Insert OEM Key -============================== - -MinnowBoard does not need key signing, so no OEM key is needed. - -Install Linux -============= - -Install Ubuntu: https://minnowboard.org/tutorials/installing-ubuntu-lts/ - -Set Up SOF -========== - -Please follow the build from scratch :ref:`instructions ` -for generic set up steps. - -Set up Xtensa config to build with xt-xcc: - -#. Install the RD-2012.5 version of Xtensa tools from Xplorer. -#. Download the Xtensa `core config `__ for BYT. -#. Save the core config tarball (Intel\_HiFiEP\_linux.tgz) in your - /XtDevTools/downloads directory. -#. Unzip and install the tarball. - - .. code-block:: bash - - tar xvzf Intel\_HiFiEP\_linux.tgz - cd Intel\_HiFiEP - ./install - -#. When prompted, enter the Xtensa tools directory. - - .. code-block:: console - - /XtDevTools/install/tools/RD-2012.5-linux/XtensaTools - -After you have built and setup SOF: - -#. Copy the*sof-byt.ri* to /lib/firmware/intel/ on Minnow Turbot FS -#. Clone the |SOF| firmware tools from git://git.alsa-project.org/sound-open-firmware-tools.git and select a topology file like one of the following: - - .. code-block:: console - - test-ssp2-passthrough-s16le-s16le-48k-codec.tplg - test-ssp2-passthrough-s24le-s24le-48k-codec.tplg - test-ssp2-volume-s16le-s16le-48k-codec.tplg - test-ssp2-volume-s24le-s24le-48k-codec.tplg - - .. note:: - - We only support pass-through topology in SOF 1.0. - -#. Copy the topology file to /lib/firmware/intel/ as - sof-byt-"codec name".tplg (e.g. sof-byt-rt5651.tplg) to the - Minnow Turbot FS. - -UCM ---- - -Pierre Bossart provides a `UCM repository `__ that supports both headset mode and line in/out mode. - -You can also use alsactl to restore a recommended asound.state file for -the amixer setting. - -asound.state files: -user@\ `bee:/git/audio/reef/board-int `__ - -Kernel build -============ - -Kernel update -------------- - -Repo: https://github.com/plbossart/sound.git - -Branch: heads/topic/sof-v4.14 - -#. Select the machine and codec driver in kernel config - - :: - - Device Drivers > Sound card support > Advanced Linux Sound Architecture > ALSA for SoC audio support - - Make sure ASoC SOF Baytrail and codec RT5651/DA7212 - are selected. - - |image1| - -#. Build deb package. - - .. code-block:: bash - - make -j8 && make -j8 deb-pkg - -#. Package all the \*.deb files for MinnowBoard, and install all deb files. - - .. code-block:: bash - - dpkg -i \*.deb - -#. Reboot your system. - -EFI API -------- - -Repo: https://github.com/plbossart/MinnowBoardMaxFirmware.git - -Clone the repo and build the source code. - -.. note:: - - AudioSsdtUpdate.efi and associated .aml files are avaible as - pre-compiled binaries under X64/ - -Steps: - -#. Create a startup.nsh file in /boot/efi/ - - .. code-block:: bash - - vim startup.nsh - - Add the following: - - .. code-block:: bash - - fs0: - cd EFI - AudioSsdtUpdate.efi "codecname".aml(like RT5651.aml or DA7212.aml) - cd ubuntu - grubx64.efi - -#. Move .aml and .efi files to EFI directory. - - .. code-block:: bash - - cp \*.aml /boot/efi/EFI - cp AudioSsdtUpdate.efi /boot/efi/EFI - -#. Configure the BIOS. - - * From the BIOS press F2. - * Select the EFI Internal Shell as primary boot option: Boot-Maintenance - Manager -> Boot Options -> Change Boot Order - * Press F10 to save and exit. - - EFI shell will automatically run the startup.nsh shell script. - -.. |image1| image:: images/minnow_turbot.png - :class: confluence-embedded-image - :height: 250px diff --git a/developer_guides/subsystem_architecture/firmware/index.rst b/developer_guides/subsystem_architecture/firmware/index.rst deleted file mode 100644 index 646d15fd..00000000 --- a/developer_guides/subsystem_architecture/firmware/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _architecture-firmware: - -Firmware Architecture -##################### - -For the high-level system, hostless, and audio pipeline architectures, see :ref:`architectures`. - -.. toctree:: - :maxdepth: 1 - - sof-common/index - sof-xtos/index - sof-zephyr/index - intel/index \ No newline at end of file diff --git a/developer_guides/subsystem_architecture/firmware/intel/ace/iadk_modules.rst b/developer_guides/subsystem_architecture/firmware/intel/ace/iadk_modules.rst deleted file mode 100644 index 2410faa7..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/ace/iadk_modules.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _iadk-modules: - -IADK Modules Adapter -#################### - -IADK Modules -============ - -An IADK module is a software component that can be represented by a processing -block with some input pins and output pins capable to transport a digital -signal into the block or out of the block. Processing is applied on an input -signal or a combination of input signals, some input signals may only be used -as reference signals that influence the processing on other input signals. -The result of the processing is written into the output signals. The behavior -of the block can be controlled using a configuration parameter interface. - -An IADK module communicates with base firmware and other modules through -ProcessingModuleInterface API and access base firmware services via -System Service API. - - -IADK Module Adapter -=================== - -The IADK Module Adapter is an extension to SOF component infrastructure that -allows to integrate modules developed under IADK (Intel Audio Development Kit) -Framework. -IADK modules uses uniform set of interfaces and are linked into separate -library. These modules are loaded in runtime through Library Manager and then -after registration into SOF component infrastructure are interfaced through -module adapter API. -Since IADK modules uses ProcessingModuleInterface API to control/data transfer -and SystemService API to use base FW services from internal module code, there -is a communication shim layer defined. - -The SOF IADK Module Adapter is designed to interact with IADK modules without -their code modification. Therefore C++ function, structures and variables -definition are here kept with original form from IADK Framework. -This provides binary compatibility with already developed 3rd party modules. - -There are three entities in IADK Module Adapter Package: - * System Agent - A mediator to allow the custom module to interact with the - base SOF FW. It calls IADK module entry point and provides all necessary - information to connect both sides of ProcessingModuleInterface and - System Service. - * System Service - exposes of SOF base FW services to the module. - * Processing Module Adapter - SOF base FW side of ProcessingModuleInterface - API diff --git a/developer_guides/subsystem_architecture/firmware/intel/ace/index.rst b/developer_guides/subsystem_architecture/firmware/intel/ace/index.rst deleted file mode 100644 index 8f2507bd..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/ace/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _ace-architecture-intel: - -Intel ACE Architecture -###################### - -The details below are specific to Intel products with an audio DSP ACE -architecture using SOF. Intel ACE is a next generation of Intel Audio DSP -solution that replaces Intel cAVS architecture. - -.. toctree:: - :maxdepth: 1 - - iadk_modules diff --git a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-ldr.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-ldr.rst deleted file mode 100644 index 04fd5d0e..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-ldr.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. _apl-boot-ldr: - -Apollo Lake Boot Loader -####################### - -* Additional HPSRAM memory initialization. -* L2 cache disabled in ``boot_entry`` (enabled by default by APL ROM). - -Example list of sections in the APL boot_ldr:: - - Idx Name Size VMA LMA File off Algn - 0 .boot_entry.text 00000036 b000a000 b000a000 000000d4 2**2 - CONTENTS, ALLOC, LOAD, READONLY, CODE - 1 .boot_entry.literal 0000000c b000a040 b000a040 0000010c 2**2 - CONTENTS, ALLOC, LOAD, READONLY, CODE - 2 .text 000007d2 b000a0b0 b000a0b0 00000120 2**4 - CONTENTS, ALLOC, LOAD, READONLY, CODE - 3 .rodata 00000008 b0002000 b0002000 000008f4 2**2 - CONTENTS, ALLOC, LOAD, DATA - ... more debug sections ... diff --git a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-rom.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-rom.rst deleted file mode 100644 index 5070e745..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/apl-boot-rom.rst +++ /dev/null @@ -1,163 +0,0 @@ -.. _apl-boot-rom: - -Apollo Lake Boot ROM -#################### - -Progress of the boot process is reflected by the status information updated by -the ROM in an SRAM area called *FW Registers*. It is available to the host -driver through a memory window. - -ROM FW Registers -**************** - -This SRAM area updated by the ROM during the boot process is available via -memory window #0, the limit is set to 4K. - -Offset 0x00 - FwStatus - Current ROM status - -Offset 0x04 - ErrorCode - Last ROM error code - -Offset 0x08 - FwPwrStatus - Current DSP clock status (ToBeVerified on APL/CNL) - -FwStatus -======== - -The FwStatus register contains current FW status, initialized to 0 on the DSP -startup. - -The ErrorCode register is updated by ROM when *FwStatus* ``running`` bit is -set to “halted on critical error”, initialized to 0 (`ADSP_SUCCESS`) on the -DSP startup. - -Once Base FW is being executed, *ErrorCode* is updated every time some error is -detected while calling internal API components. Some of the error codes might be -helpful for driver writers hence documented in this specification. - -.. code-block:: c - - union fw_status_reg - { - int32_t full; - struct Bits - { - uint32_t state : 24; - uint32_t wait_state : 4; - uint32_t module : 3; - uint32_t running : 1; - } bits; - }; - -running - This field is used to report current FW running state. - 0 – running, - 1 – halted. - When FW reports halted state, ErrorCode register contains error - code. - -module - This field is used to report FW module (that indicates boot phase - component/module in this context, not a processing module) that is being - executed. - -wait_state - This field is updated to non-zero code of operation when ROM is waiting - for completion of that operation. - -state - This field is used to report phase of the FW module that is being executed. - When FW switches to another module (reported by Module field) this value - may get started again from 0, so it is Module context sensitive. - -.. uml:: images/apl-rom-flow.pu - :caption: APL ROM Boot Sequence - -.. code-block:: c - :caption: APL ROM Wait States - - // Waiting for IPC busy bit to be set - #define WAIT_FOR_IPC_BUSY 0x1 - // Waiting for IPC done bit to be set - #define WAIT_FOR_IPC_DONE 0x2 - // Waiting for L2$ invalidation to be ack'ed - #define WAIT_FOR_CACHE_INVALIDATION 0x3 - // Waiting for DMA buffer to be filled - #define WAIT_FOR_DMA_BUFFER_FULL 0x5 - -.. code-block:: c - :caption: APL ROM Status Codes - - #define FSR_ROM_INIT 0x0 - #define FSR_ROM_INIT_DONE 0x1 - #define FSR_ROM_CSE_MANIFEST_LOADED 0x2 - #define FSR_ROM_FW_MANIFEST_LOADED 0x3 - #define FSR_ROM_FW_FW_LOADED 0x4 - #define FSR_ROM_FW_ENTERED 0x5 - #define FSR_ROM_VERIFY_FEATURE_MASK 0x6 - #define FSR_ROM_GET_LOAD_OFFSET 0x7 - #define FSR_ROM_BASEFW_CSE_IMR_REQUEST 0x10 - #define FSR_ROM_BASEFW_CSE_IMR_GRANTED 0x11 - #define FSR_ROM_BASEFW_CSE_VALIDATE_IMAGE_REQUEST 0x12 - #define FSR_ROM_BASEFW_CSE_IMAGE_VALIDATED 0x13 - -.. code-block:: c - :caption: APL ROM Error Codes - - #define ADSP_UNHANDLED_INTERRUPT 0xBEE00000 - - // Memory hole/ECC error - // Status bits are provided: - // [0] - L2 SRAM ECC error - // [1] - L2 memory hole error - #define ADSP_MEMORY_HOLE_ECC 0xECC00000 - #define ADSP_USER_EXCEPTION 0xBEEF0000 - #define ADSP_KERNEL_EXCEPTION 0xCAFE0000 - - // Other critical error - #define ADSP_FAILURE 6 - // FW image does not match the feature mask read from HW register. - #define ADSP_INVALID_FEAT_MASK 20 - // Invalid parameter - #define ADSP_INVALID_PARAM 21 - // CSE responded with error on an IPC request - #define ADSP_CSE_ERROR 40 - // Invalid IPC response sent back by CSE. - #define ADSP_CSE_WRONG_RESPONSE 41 - // Size of IMR assigned by CSE is too small to load FW Image. - #define ADSP_IMR_TOO_SMALL 42 - // Base FW module not found in FW Image. - #define ADSP_BASE_FW_NOT_FOUND 43 - // CSE responded with error on FW image validation request. - #define ADSP_CSE_VALIDATION_FAILED 44 - // IPC communication failed with fatal error. - #define ADSP_IPC_FATAL_ERROR 45 - // L2 cache command failed. - #define ADSP_L2_CACHE_ERROR 46 - // Load offset set in FW Image Manifest is too small. - #define ADSP_LOAD_OFFSET_TOO_SMALL 47 - -ROM -> FW Transition -==================== - -Once APL ROM jumps to the entry point of the first module in the main binary, -the memory and caches are in the following state: - -* L2$ is turned on, so the FW boot procedure may either execute via L2 - cacheable address space or directly via L2 uncacheable alias. - -* HPSRAM areas allocated by the ROM listed in the next table. - -APL ROM HPSRAM Allocation -========================= - -+---------------------+------------+--------------+ -| Area | Base Addr | Size | -+=====================+============+==============+ -| Code load buffer | 0xBE008000 | 0x8000 (32K) | -+---------------------+------------+--------------+ -| BSS (inc. stack) | 0xBE010000 | 0x8000 (32K) | -+---------------------+------------+--------------+ -| FW Registers | 0xBE01E000 | 0x800 (2K) | -+---------------------+------------+--------------+ diff --git a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/images/apl-rom-flow.pu b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/images/apl-rom-flow.pu deleted file mode 100644 index 4624b4d1..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/images/apl-rom-flow.pu +++ /dev/null @@ -1,59 +0,0 @@ -participant "State" as st -participant "Error" as err -participant "Host\nDriver" as host -participant "APL\nROM" as rom -participant "CSE" as cse - -host -> rom : <> RomControl (purge=1, dma_id) - -== Initialization == -rom -> rom : Boot - err <[#red]- rom : ADSP_UNHANDLED_INTERRUPT [anytime unhandled int reported] - err <[#red]- rom : ADSP_MEMORY_HOLE_ECC [anytime memory hole int reported] - err <[#red]- rom : ADSP_USER_EXCEPTION [anytime unhandled user mode exception happens] - err <[#red]- rom : ADSP_KERNEL_EXCEPTION [anytime unhandled kernel mode exception happens] - -rom -> rom : L2Cache Initialization - err <[#red]- rom : ADSP_L2_CACHE_ERROR [Failed to init L2$] - -rom -> rom : Requesting IMR - st <[#green]- rom : FSR_ROM_BASEFW_CSE_IMR_REQUEST - rom -> cse : <> IPC_ADSP2CSE_REQUEST_IMR - rom <- cse : <> IPC_CSE2ADSP_REQUEST_IMR_RESPONSE - st <[#green]- rom : FSR_ROM_BASEFW_CSE_IMR_GRANTED - -rom -> rom : Initializing Code Load DMA - err <[#red]- rom : ADSP_INVALID_PARAM [dma_id out of range] - -st <[#green]- rom : FSR_ROM_INIT_DONE - -== Loading Image == - rom -> rom : Loading Firmware - ' First fw image block is loaded and feature mask is verified - st <[#green]- rom : FSR_ROM_VERIFY_FEATURE_MASK - err <[#red]- rom : ADSP_INVALID_FEAT_MASK [mft mask does not match SKUID] - ' Load offset is verified - st <[#green]- rom : FSR_ROM_GET_LOAD_OFFSET - err <[#red]- rom : ADSP_LOAD_OFFSET_TOO_SMALL [load offset less then Rsvd space] - err <[#red]- rom : ADSP_IMR_TOO_SMALL [load offset greater than assigned IMR size] - ' CSE Manifest if loaded - rom -> rom : Loading CSE Manifest - err <[#red]- rom : ADSP_IMR_TOO_SMALL [CSE manifest > IMR size] - st <[#green]- rom : FSR_ROM_CSE_MANIFEST_LOADED - ' FW Manifest is loaded - rom -> rom : Loading ADSP FW Manifest - err <[#red]- rom : ADSP_IMR_TOO_SMALL [ADSP FW manifest > IMR size] - st <[#green]- rom : FSR_ROM_FW_MANIFEST_LOADED - err <[#red]- rom : ADSP_BASE_FW_NOT_FOUND [module entry not found in manifest] - ' Loading rest of FW - rom -> rom : Loading FW - st <[#green]- rom : FSR_ROM_FW_FW_LOADED - -== Authenticating Image == - st <[#green]- rom : FSR_ROM_BASEFW_CSE_VALIDATE_IMAGE_REQUEST - rom -> cse : <> IPC_CSE2ADSP_START_FW_AUTH - rom <- cse : <> IPC_CSE2ADSP_START_FW_AUTH_RESPONSE - err <[#red]- rom : ADSP_CSE_VALIDATION_FAILED [invalid image signature] - st <[#green]- rom : FSR_ROM_BASEFW_CSE_IMAGE_VALIDATED -== Booting FW == - st <[#green]- rom : FSR_ROM_FW_ENTERED diff --git a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/index.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/index.rst deleted file mode 100644 index 21ee69cb..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/apollolake/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _cavs-boot-apl: - -Apollo Lake Boot Process -######################## - -.. toctree:: - :maxdepth: 1 - - apl-boot-rom - apl-boot-ldr diff --git a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/cavs-dsp-boot-overview.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/cavs-dsp-boot-overview.rst deleted file mode 100644 index 24fde842..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/cavs-dsp-boot-overview.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. _cavs-dsp-boot-overview: - -Overview -######## - -There are two main DSP boot flows: - -* **Cold boot** performed when the host CPU exits an Sx state. FW binaries are - loaded into DSP memory and full state re-initialization is required. This - flow is also referred as *Purge Flow* in the figures below. - -* **RTD3 boot** when the DSP state is restored from the DSP internal memory. - This flow is available on platforms with access to Isolated Memory Region - (IMR) allocated for the DSP. - -IPC Communication with DSP ROM -****************************** - -Once the primary DSP core (#0) is powered up and reset by the host driver, an -IPC communication with the DSP ROM is required in order to set the boot -options (see Boot Path Control Messages for details and list of platforms that -require this step). It is a one-way message that does not require a response -from the DSP. - -There may be some specific requirements about the order of the DSP core reset, -sending IPC message, and the DSP core unstall operations. It is assumed that -the following order is required unless specified otherwise by Boot Path -Control Message in case of a specific platform: - -1. Power up and reset the DSP Core 0, -#. Send ROM Control IPC, -#. Unstall DSP Core 0. - -The ROM Control IPC message includes “purge” parameter that should be set to 1 -in case of the cold boot. Otherwise it may be set to 0 after coming out of -RTD3 to attempt quicker state restore flow. In the latter case, the driver -just waits for FW Ready notification (no library loading is needed). - -The flow is illustrated in the next figure. - -.. uml:: images/boot-dsp.pu - -Loading Binaries to ADSP Memory -******************************* - -The ADSP FW binary code may be divided into: - -* The Base FW binary file, which contains FW infrastructure code (Base FW - module) required by all the platforms, optionally followed by other modules, - -* Set of libraries (modules) containing additional processing modules code - that may be optionally loaded into ADSP FW memory based on the platform’s - requirements and configuration. - -.. note:: This section contains general information about the structure of - binaries necessary to understand the loading process. For a complete - documentation refer to FW Binaries documentation. - -There are two main parts of the main binary: - -* Manifest, -* Modules binary code. - -Determining Part of Binary to be Loaded -======================================= - -The binary begins with the Manifest that is loaded into the DSP memory. The -Manifest contains ``preload_page_count`` parameter that determines part of the -binary to be loaded by the driver during the boot process. The preload size is -expressed in pages, where size of the page is 4096 bytes for all platforms. If -IMR is available and allocated for the DSP on the platform, the preload size -includes the entire binary. Otherwise it includes only the critical part of -the binary while other parts (so called loadable modules) may be loaded on -demand when needed (see Load Multiple Modules IPC) to limit SRAM usage and -save the power. - -For example, the Base FW binary file may be setup in a way that -``preload_page_count`` includes size of the Manifest as well as size of the -following Base FW module (it is always module 0 in the Base FW binary) since -its presence in the DSP memory is absolutely necessary for the boot to -complete. If the Base FW module is followed by other modules code, they may be -either included in the preload or not, depending on the platform memory -availability. - -The ``preload_page_count`` is one of the ``AdspFwBinaryHeader`` parameters. -The header starts with “$AM1” tag (0x314D4124) and is located at offset 0x2000 -of the binary file. - -.. note:: All the binary file offsets specified by the Manifest are computed - relatively to the beginning of the Manifest. - -Preparing DMA to Transfer Binaries -================================== - -The driver programs the DMA engine that is used to transfer the binaries into -the DSP memory. It is either dedicated Code Load DMA if available, or one of -the HD/A host output DMAs otherwise. In the latter case the ROM Control IPC is -required since the DMA identifier must be passed to the DSP ROM in order to -program the DMA on the DSP side. - -Note that the DMA buffers are managed independently on the host side and the -DSP side. - -Loading Binaries -================ - -Once the DMA is ready, the driver loads the Base FW binary, waits for the FW -Ready IPC notification and then loads additional binaries (libraries/modules). - -.. note:: Loading additional modules must be finished before any stream is - opened for the first time and the DMA is reclaimed for HD/A streaming. - -The complete flow is illustrated in the next figure. - -.. uml:: images/loading-bins.pu - :caption: Loading FW Binaries to ADSP Memory - -The details of *_write(....binary)* step are illustrated in the next figure. - -.. uml:: images/write-bin.pu - :caption: Writing a Binary - -Booting with Boot Loader -************************ - -.. uml:: images/boot-ldr-flow.pu - :caption: SOF Boot Loader Flow diff --git a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/boot-dsp.pu b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/boot-dsp.pu deleted file mode 100644 index 59acf2df..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/boot-dsp.pu +++ /dev/null @@ -1,21 +0,0 @@ -actor Host -participant mw0 as "MemWnd0" -participant core0 as "DSP Core0" -participant rom as "DSP ROM" - -Host -> core0 : power up and reset - -Host -> rom : <> ROM Control(set_boot_config) -Host -> core0 : unstall - core0 -> rom : ResetVector() - activate rom - -Host -> mw0 : wait for(FSR_ROM_INIT_DONE) - - rom -> rom : Process ROM Control - - mw0 <- rom : FwRegsSetState(FSR_ROM_INIT_DONE) - -Host <-- mw0 - -Host -> Host : binaries loading diff --git a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/boot-ldr-flow.pu b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/boot-ldr-flow.pu deleted file mode 100644 index 643cca70..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/boot-ldr-flow.pu +++ /dev/null @@ -1,28 +0,0 @@ -actor "ROM" as rom -box "boot_ldr @IMR" #6fccdd - participant ".boot_entry.text" as bup_be - participant ".text" as bup -end box -participant "sof" as fw - -rom -> bup_be : boot_entry() @boot_ldr.ep (boot_entry.S) - activate bup_be - bup_be -> bup_be : j boot_init: - note right: Platform specific actions (compilation flags)\n\ -- reset MHE\n\ -- disable L2$ - bup_be -> bup : call8 boot_pri_core() (boot_loader.c) - activate bup - bup -> bup : hp_sram_init() - opt defined(CONFIG_BOOT_LOADER) - bup -> bup : parse_manifest() - note right: copying of FW IMR -> SRAM done here - end - - bup -> bup : _ResetVector() - activate bup - bup -> fw : _MainEntry() @SOF_TEXT_START - fw -> fw : call0 _start - activate fw - fw -> fw : call main - activate fw diff --git a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/loading-bins.pu b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/loading-bins.pu deleted file mode 100644 index 0c0dedb6..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/loading-bins.pu +++ /dev/null @@ -1,41 +0,0 @@ -actor host as "Host" -participant cldma as "CodeLoadDMA" -participant mw0 as "MemWnd0" -participant core0 as "DSP Core0" -participant rom as "DSP ROM" -participant fw as "DSP FW" - -activate rom -activate host -host -> cldma : init_host_side() - -rom -> cldma : init_dsp_side() -note right: Unified cAVS1.5+ flow - -host -> mw0 : wait for (FSR_ROM_INIT_DONE) - mw0 <- rom : FSR_ROM_INIT_DONE -host <-- mw0 - -host -> cldma : write(base fw binary) - cldma <- rom : read() : base fw manifest - rom -> rom : veirfy(base fw manifest) - cldma <- rom : read() : base fw code - mw0 <- rom : FSR_ROM_FW_ENTERED - - create fw - rom -> fw : start() - activate fw - fw -> fw : initialization() - host <- fw : <> FW Ready - deactivate fw - -loop libraries loading - host -> cldma : write(library binary) - host -> fw : <> Load Library - activate fw - cldma <- fw : read() : library manifest - fw -> fw : verify(library manifest) - cldma <- fw : read() : library code - host <-- fw - deactivate fw -end loop diff --git a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/write-bin.pu b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/write-bin.pu deleted file mode 100644 index 451ca627..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/images/write-bin.pu +++ /dev/null @@ -1,10 +0,0 @@ -actor host as "Host" -participant cldma as "CodeLoadDMA" - -activate host -host -> host : read(): binary -host -> host : detect and strip Extended Manifest : binary_mft_code -host -> host : retrieve preload size (binary_mft_code) : preload_size - -host -> cldma : write (binary_mft_code, mft_size) -host -> cldma : write (binary_mft_code+mft_size, preload_size-mft_size) diff --git a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/index.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/index.rst deleted file mode 100644 index 54ba2ef6..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/cavs/cavs-boot/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _architecture-intel-cavs-boot: - -Booting up CAVS ADSP -#################### - -Intel has several generations of audio DSP. "CAVS" versions relate to the audio -DSP in Skylake Core and Apollo Lake Atom platforms onwards. - -Bay Trail, Cherry Trail, Braswell, Haswell, and Broadwell audio DSPs have a simpler -boot flow using memory copy and not authentication. - - -.. toctree:: - :maxdepth: 2 - - cavs-dsp-boot-overview - apollolake/index diff --git a/developer_guides/subsystem_architecture/firmware/intel/cavs/images/idc-send-message.pu b/developer_guides/subsystem_architecture/firmware/intel/cavs/images/idc-send-message.pu deleted file mode 100644 index f19d027e..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/cavs/images/idc-send-message.pu +++ /dev/null @@ -1,30 +0,0 @@ -participant core0 -participant core1 -participant idc -participant platform - -core0 -> idc : idc_init() - activate idc - - idc -> platform : interrupt_register(irq, auto_unmask, irq_handler, idc) - activate platform - idc <-- platform - deactivate platform - -core0 <-- idc -deactivate idc - -core0 -> idc : idc_send_msg(idc_msg, mode) - activate idc - - idc -> core1 : irq_handler() - activate core1 - idc <-- core1 - deactivate core1 -core0 <-- idc -deactivate idc - -core1 -> idc : idc_do_cmd(data) - activate idc -idc <-- core1 -deactivate idc diff --git a/developer_guides/subsystem_architecture/firmware/intel/cavs/index.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/index.rst deleted file mode 100644 index 4f3ac9a7..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/cavs/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _cavs-architecture-intel: - -Intel cAVS Architecture -####################### - -The details below are specific to Intel products with an audio DSP cAVS -architecture using SOF. - -.. toctree:: - :maxdepth: 1 - - cavs-boot/index - smp/index \ No newline at end of file diff --git a/developer_guides/subsystem_architecture/firmware/intel/cavs/smp/index.rst b/developer_guides/subsystem_architecture/firmware/intel/cavs/smp/index.rst deleted file mode 100644 index 5aff7fc0..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/cavs/smp/index.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _architecture-intel-smp: - -Intel SMP Architecture -###################### - -Description -*********** - -SMP architecture is used in the environment, where multiple processors are -connected to a single shared memory, have access to all input and output -interfaces, and are controlled by a single operating system. In our case, -we have multiple Xtensa DSP cores, which use the same Firmware binary loaded -to the shared L2 SRAM, and are controlled by the same instance of the XTOS. - -Using SMP architecture -********************** - -|SOF| implementation of SMP architecture involves separate and modified XTOS, -which can be chosen by selecting appropriate arch flag during configuration -step of building FW binary. - -.. code-block:: bash - - ./configure --with-arch=xtensa-smp --with-platform= --with-dsp-core= --with-root-dir= --host= - -Implementation details -********************** - -The data structures critical to core execution need to be instantiated -per core, instead of being accessed using static pointers. -SMP implementation creates ``struct core_context`` to meet those demands. -This structure contains pointers to the XTOS data along with -``struct irq_task``, ``struct schedule_data``, ``struct work_queue`` etc. - -.. code-block:: c - - struct core_context { - struct thread_data td; - struct irq_task *irq_low_task; - struct irq_task *irq_med_task; - struct irq_task *irq_high_task; - struct schedule_data *sch; - struct work_queue *queue; - struct idc *idc; - }; - -``struct core_context`` is allocated by primary core for secondary cores before -secondary core boot. Address of the ``struct core_context`` is written into -``THREADPTR`` processor register, which can later be retrieved by the secondary core -after boot. Every core has its own instance of ``THREADPTR``, -so ``struct core_context`` address can be read anytime at any place of the code. - -Communication between cores -*************************** - -Primary core can communicate with secondary cores by sending messages using -the IDC mechanism. This mechanism is pretty much the same as IPC. -Important data can be sent in two 32-bit IDC registers. Cores use interrupts -to register for the incoming messages. - -.. uml:: ../images/idc-send-message.pu - -.. comment "master" has been replaced with "primary" -.. comment "slave" has been replaced with "secondary" \ No newline at end of file diff --git a/developer_guides/subsystem_architecture/firmware/intel/index.rst b/developer_guides/subsystem_architecture/firmware/intel/index.rst deleted file mode 100644 index c7a5c4ea..00000000 --- a/developer_guides/subsystem_architecture/firmware/intel/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _vendor-specific: - -Vendor-Specific Architecture Information -######################################## - -Architecture details of any vendor specific code and flows. This is architecture -specific to a single vendor that falls outside the scope of the high level -generic SOF architecture. - -.. toctree:: - :maxdepth: 1 - - cavs/index - ace/index \ No newline at end of file diff --git a/developer_guides/subsystem_architecture/firmware/sof-common/components/component-mgmt-api.rst b/developer_guides/subsystem_architecture/firmware/sof-common/components/component-mgmt-api.rst deleted file mode 100644 index 3d9562d2..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-common/components/component-mgmt-api.rst +++ /dev/null @@ -1,19 +0,0 @@ -.. _apps-component-mgmt-api: - -Managing the Components -####################### - -The components management functionality is declared in *audio/component.h* and -implemented in *audio/component.c*. - -It provides APIs for component drivers and component clients. - -.. uml:: images/component-mgmt-api.pu - :caption: Component Management API - -Initialization -************** - -Audio unit initialization routine calls ``sys_comp_init()`` to perform -allocation of the ``comp_data`` which maintains the list of registered -component drivers. diff --git a/developer_guides/subsystem_architecture/firmware/sof-common/components/component-module-api.rst b/developer_guides/subsystem_architecture/firmware/sof-common/components/component-module-api.rst deleted file mode 100644 index 15560b87..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-common/components/component-module-api.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. _apps-comp-world: - -Component & Module Interfaces -############################# - -Introduction of the Module Adapter, an intermediate layer which provides common -code for different module API adapters, created multi-level sequences of calls -to functions and this mechanism is very expensive during run-time processing -with regards to additional cycles consumed for parameter translation and copying -as well as the additional memory for extra buffers, contexts, and the call -stack. The `module_adapter` translates the `comp_ops` interface required by the -existing infrastructure (pipelines etc.) into the `module_interface`. Then -appropriate adapter translates the `module_interface` into the final module -interface like `Cadence Codec API` or `IADK ProcessingModuleInterface`. These -dependencies are illustrated in the next figure. - -.. uml:: images/comp-module-api.pu - :caption: Component & Module API - -Maintenance of two base component (alias module) interfaces is expensive and -also confusing for the developers who wants to create a module that provides SOF -native module API. It is unclear whether this should be the `comp_ops` or the -`module_interface`. The latter is much more convenient since it is tailored for -the audio processing modules while the `comp_ops` is a multipurpose interface -cluttered with many optional operations required for *dai-comp* modules only. - -Therefore the `module_interface` should become the only SOF native module -interface that the rest of underlying infrastructure would interact with -directly. The `comp_ops` would become obsolete and eventually would be removed -from the SOF. - -The cost of extra memory required at the moment for intermediate audio data -buffers allocated inside the `module_adapter` layer (see the *Preparation Flow* -figure below) as well as cost of extra cycles required to copy the data to/from -the intermediate buffers (see the *Processing Flow* figure below) could be -avoided by removing the `comp_ops` as well. - -.. uml:: images/comp-prepare-flow.pu - :caption: Preparation Flow - -.. uml:: images/comp-copy-flow.pu - :caption: Processing Flow diff --git a/developer_guides/subsystem_architecture/firmware/sof-common/components/component-overview.rst b/developer_guides/subsystem_architecture/firmware/sof-common/components/component-overview.rst deleted file mode 100644 index edfd4a50..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-common/components/component-overview.rst +++ /dev/null @@ -1,105 +0,0 @@ -.. _apps-component-overview: - -Overview -######## - -A component adds audio signal processing to a pipeline that's running on the -DSP. An instance of the component, called a component device (components are -implemented in the driver-device model), is chained with other component -devices and builds an audio processing path organized as a pipeline. - -Component driver -**************** - -Every component must implement a driver (see the ``comp_driver``) which -creates instances by handling *new* component requests coming from the -command handlers. - -The driver must be registered on the system component driver list by calling -``comp_register(comp_driver *)`` and providing a unique component id in -order to receive the requests. - -Each component driver declares its unique ``type`` that is later used by the -uAPI to create a component of that ``type``. It also provides an entry point -to the component ops implementation. - -UUIDs (Universally Unique Identifiers) provide a more scalable and -collision-free way of component identification. UUIDs are currently used as -the standard interface by all users of the SOF firmware, including the -tracing subsystem, the topology .m4 files, and the Linux topology driver. -Using the ``type`` to define topology and create components is still -supported today; however, the ``type`` will be moved out of the IPC struct -in the future. Therefore, **be sure to allocate UUIDs for all newly-added component drivers.** - -The UUID entry declared in the FW code contains the identifier value as well -as the object which is the component name in this case. Both are -provided as the arguments to the ``DECLARE_SOF_RT_UUID()`` macro. For -example, the **volume** component provides the following declaration: - -.. code-block:: c - - /* b77e677e-5ff4-4188-af14-fba8bdbf8682 */ - DECLARE_SOF_RT_UUID("volume", volume_uuid, 0xb77e677e, 0x5ff4, 0x4188, - 0xaf, 0x14, 0xfb, 0xa8, 0xbd, 0xbf, 0x86, 0x82); - -Note how the ``af14`` 16bit segment is split into two bytes at the beginning -of the second line. - -``volume`` is the component name used by the sof-logger while printing the -trace source name. ``volume_uuid`` is the symbol used later to associate the -declared UUID with the volume of the component driver: - -.. code-block:: c - :emphasize-lines: 3 - - static const struct comp_driver comp_volume = { - .type = SOF_COMP_VOLUME, - .uid = SOF_RT_UUID(volume_uuid), - ... - }; - -See the :ref:`uuid-api` for more details on UUID generation and declaration. - -.. uml:: images/comp-driver.pu - :caption: Component Driver - -Create a component device -************************* - -When a new component device is requested, the system ``comp_new()`` function -finds the driver that's registered with the requested unique component type -and calls the ``new()`` function pointed by the registered driver's data in -order to instantiate the device. - -Following is the entry called to create a new component device:: - - struct comp_dev* comp_new(sof_ipc_comp *comp); - -.. uml:: images/comp-new-flow.pu - -Handle the component device state -********************************* - -.. uml:: images/comp-dev-states.pu - :caption: Component Device States - -.. note:: - - COMP_STATE_SUSPEND is not used currently. - -Refer to :c:func:`comp_set_state` in :ref:`component-api` for details. - -Implement the component API (comp_ops) -************************************** - -Every component driver implements the ``comp_ops`` API. - -.. note:: - - Some API functions are mandatory for specific component types since - the infrastructure code calls them selectively based on the target - component type. For instance, ``dai_config()`` is only called for - ``SOF_COMP_DAI`` and ``SOF_COMP_SG_DAI`` and cannot be called for other - component types. - -See ``struct comp_ops`` documentation in :ref:`component-api` for details. diff --git a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-copy-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-copy-flow.pu deleted file mode 100644 index 0f015622..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-copy-flow.pu +++ /dev/null @@ -1,42 +0,0 @@ -actor pipeline -box "Module Adapter\no-- comp_ops" - participant "module_adapter" as module_adapter -end box -box "IADK Module Adapter\no-- module_interface" - participant "iadk_adapter" as iadk_adapter -end box -box "IADK Module\no-- ProcessingModuleInterface" - participant iadk_module -end box - -pipeline -> module_adapter : (1) ops->module_adapter_copy() - activate module_adapter - - module_adapter -> module_adapter : find min bytes\nto process - - note left of module_adapter - This logic is WRONG for some modules!! - end note - - module_adapter -> module_adapter : copy input from sources\nto internal buffers - - module_adapter -> module_adapter : module_process() - activate module_adapter -note left of module_adapter -Why all those extra internal calls -used only once?? -end note - - module_adapter -> iadk_adapter : (2) ops->process() - activate iadk_adapter - iadk_adapter -> iadk_module : (3) processing - module_adapter <-- iadk_adapter - deactivate iadk_adapter - - deactivate module_adapter - - module_adapter -> module_adapter : module_adapter_process_output() - activate module_adapter - module_adapter -> module_adapter : copy output from internal buffers\ntosinks - deactivate module_adapter -pipeline <-- module_adapter diff --git a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-dev-states.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-dev-states.pu deleted file mode 100644 index 85d91941..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-dev-states.pu +++ /dev/null @@ -1,17 +0,0 @@ -hide empty description -[*] -right-> COMP_STATE_INIT : start of comp_ops.new() - -COMP_STATE_INIT --> COMP_STATE_READY : end of comp_ops.new() - -COMP_STATE_READY ---> COMP_STATE_PREPARE : COMP_TRIGGER_PREPARE - -COMP_STATE_PREPARE --> COMP_STATE_ACTIVE : COMP_TRIGGER_START - -COMP_STATE_ACTIVE --> COMP_STATE_PREPARE : COMP_TRIGGER_STOP -COMP_STATE_PAUSED --> COMP_STATE_PREPARE : COMP_TRIGGER_STOP - -COMP_STATE_ACTIVE -> COMP_STATE_PAUSED : COMP_TRIGGER_PAUSE - -COMP_STATE_PAUSED --> COMP_STATE_ACTIVE : COMP_TRIGGER_RELEASE - -COMP_STATE_PREPARE --> COMP_STATE_READY : COMP_TRIGGER_RESET diff --git a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-driver.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-driver.pu deleted file mode 100644 index a96e9e1a..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-driver.pu +++ /dev/null @@ -1,32 +0,0 @@ -package component { - - class comp_driver { - type : uint32_t - uid : uint32_t - module_id : uint32_t - ops : comp_ops - } - hide comp_driver methods - - class comp_ops - hide comp_ops methods - hide comp_ops attributes - - class comp_dev { - drv : comp_driver* - - more params goes here ... - - params : sof_ipc_stream_params - - bsource_list - bsink_list - private: void* - comp : sof_ipc_comp - } - hide comp_dev methods - - comp_driver --> "ops" comp_ops : provides - - comp_driver -> comp_dev : creates in comp_new() -} diff --git a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-module-api.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-module-api.pu deleted file mode 100644 index 5f7ef971..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-module-api.pu +++ /dev/null @@ -1,160 +0,0 @@ -scale 1024 width - -component "pipelines" { - class pipeline - hide pipeline methods - hide pipeline attributes -} -component "component" { - - class comp_driver <> { - } - hide comp_driver methods - hide comp_driver attributes - - class comp_dev <> { - state - position - frames - pipeline - min_sink_bytes - min_source_bytes - task - size - period - ... - } - hide comp_dev methods - - interface buffer - hide buffer methods - hide buffer attributes - - interface comp_ops { - create() : comp_dev* - free(comp_dev*) - params(params) - dai_get_hw_params(params, dir) - dai_config(dai_config, dai_spec_config) - cmd(int cmd, void *data) - trigger(int cmd) - prepare() - reset() - copy() - position() - get_attribute() - set_attribute() - dai_ts_config() - dai_ts_start() - dai_ts_stop() - unbind() - get_large_config() - set_large_config() - } - hide comp_ops attributes - - - comp_driver -> comp_dev : creates - comp_dev *-right- comp_ops -} -pipeline -> comp_ops : calls - -component "module_adapter" { - - class module_adapter <> { - ops : comp_ops = - .create = adapter_shim_new - .prepare = module_adapter_prepare - .params = module_adapter_params - .copy = module_adapter_copy - - adapter_shim_new() - module_adapter_prepare() - module_adapter_params() - module_adapter_copy() - } - - interface module_interface { - init(processing_module*) - prepare(processing_module*) - process(processing_module*) - set_configuration() - get_configuration() - set_processing_mode() - get_processing_mode() - reset() - free() - } - hide module_interface attributes - - class processing_module <> { - stream_params - sink_buffer_list - period_bytes - deep_buff_bytes - output_buffer_size - input_buffers[] - output_buffers[] - } - hide processing_module methods - - module_adapter -left-> processing_module : creates - module_adapter -> module_interface : calls - -} -module_adapter -up-|> comp_ops - -component "cadence adapter" { - class cadence_codec { - cadence_codec_init() - cadence_codec_prepare() - cadence_codec_process() - cadence_codec_set_configuration() - cadence_codec_reset() - cadence_codec_free() - } - hide cadence_codec attributes - - interface "Cadence Codec API" as cadence_codec_api - hide cadence_codec_api methods - hide cadence_codec_api attributes - - cadence_codec -> cadence_codec_api : calls -} -cadence_codec -up-|> module_interface - -component "custom extensions" { - class "mp3 codec" as mp3_codec - hide mp3_codec methods - hide mp3_codec attributes - - class "aac codec" as aac_codec - hide aac_codec methods - hide aac_codec attributes -} -mp3_codec -up-|> cadence_codec_api -aac_codec -up-|> cadence_codec_api - -component "IADK adapter" { - class adp_interface { - intel_modules_init() - intel_modules_prepare() - intel_modules_process() - } - hide adp_interface attributes - - interface ProcessingModuleInterface <> { - Init() - Delete() - Process() - Reset() - SetProcessingMode() - GetProcessingMode() - SetConfiguration(config_id, fragment_pos, data_in, data_out) - GetConfiguration(config_id, fragment_pos, data_out) - } - hide ProcessingModuleInterface attributes - - adp_interface -> ProcessingModuleInterface : calls -} -adp_interface -up-|> module_interface diff --git a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-new-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-new-flow.pu deleted file mode 100644 index b96b4a0a..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-new-flow.pu +++ /dev/null @@ -1,18 +0,0 @@ -actor "ipc/ipc_comp_new()" as c -participant "audio/component" as comp -participant "comp_driver" as drv -participant "lib/heap" as heap - -c -> comp : comp_new(comp : sof_ipc_comp) - activate comp - comp -> comp : get_drv(comp->type) : drv - comp -> drv : drv->ops.new(comp) - activate drv - drv -> heap : rzalloc(Runtime) - drv <-- heap - comp <-- drv : comp_dev* - deactivate drv - - comp -> comp : init component -c <-- comp : comp_dev* -deactivate comp diff --git a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-prepare-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-prepare-flow.pu deleted file mode 100644 index 960b8623..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/comp-prepare-flow.pu +++ /dev/null @@ -1,22 +0,0 @@ -actor pipeline -box "Module Adapter\no-- comp_ops" - participant "module_adapter" as module_adapter -end box -box "IADK Module Adapter\no-- module_interface" - participant "iadk_adapter" as iadk_adapter -end box -box "IADK Module\no-- ProcessingModuleInterface" - participant iadk_module -end box - -pipeline -> module_adapter : (1) ops->module_adapter_prepare() - activate module_adapter - module_adapter -> module_adapter : module_prepare() - activate module_adapter - module_adapter -> iadk_adapter : (2) ops->prepare() - activate iadk_adapter - iadk_adapter -> iadk_module : (3) preparation - module_adapter <-- iadk_adapter - deactivate iadk_adapter - module_adapter -> module_adapter : alloc buf descriptors - module_adapter -> module_adapter : alloc buffers diff --git a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/component-mgmt-api.pu b/developer_guides/subsystem_architecture/firmware/sof-common/components/images/component-mgmt-api.pu deleted file mode 100644 index f4869f5a..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-common/components/images/component-mgmt-api.pu +++ /dev/null @@ -1,29 +0,0 @@ -package component-mgmt { - class "component API" <> { - comp_new(sof_ipc_comp*) - comp_register(comp_driver*) - comp_unregister(comp_driver*) - comp_set_state(comp_dev*, cmd) - ... - sys_comp_init(void) - } - - class comp_data { - list - } - hide comp_data methods - - "component API" -right-> comp_data : drv_get() - -} -note right of comp_data - Singleton allocated in RZONE_SYS - by sys_comp_init() -end note - -"component API" <-up- comp_driver : registers in comp_register() - -comp_driver -o comp_data - -hide comp_driver members -hide comp_driver methods diff --git a/developer_guides/subsystem_architecture/firmware/sof-common/components/index.rst b/developer_guides/subsystem_architecture/firmware/sof-common/components/index.rst deleted file mode 100644 index 76db7fdd..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-common/components/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _apps-components: - -Components -########## - -.. toctree:: - :maxdepth: 2 - - component-overview - component-mgmt-api - component-module-api diff --git a/developer_guides/subsystem_architecture/firmware/sof-common/index.rst b/developer_guides/subsystem_architecture/firmware/sof-common/index.rst deleted file mode 100644 index 6e093246..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-common/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _sof-common: - -SOF Common Architecture -####################### - -Architecture chapters and details that are common both for SOF Legacy and SOF -with Zephyr. - -.. toctree:: - :maxdepth: 1 - - components/index diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/images/dai-ops.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/images/dai-ops.pu deleted file mode 100644 index 9f71f620..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/images/dai-ops.pu +++ /dev/null @@ -1,47 +0,0 @@ -class lib { - struct dai *dai_get(uint32_t type, uint32_t index) - dai_put(struct dai*) -} -hide lib attributes - -class dai_ops { - set_config() - trigger() - pm_context_restore() - pm_context_store() - probe() - remove() - set_loopback_mode() -} -hide dai_ops attributes - -class "struct dai" as s_dai { - type : uint32_t - index : uint32_t - plat_data : dai_plat_data - ops : const dai_ops * - private : void * -} -hide s_dai methods - -class "struct dai_plat_data" as s_dai_plat_data { - base : uint32_t - irq : uint32_t - flags : uint32_t - fifo : struct dai_plat_fifo_data[2] -} -hide s_dai_plat_data methods - -class "struct dai_plat_fifo_data" as s_dai_plat_fifo_data { - offset : uint32_t - width : uint32_t - depth : uint32_t - watermark : uint32_t - handshake : uint32_t -} -hide s_dai_plat_fifo_data methods - -dai_ops - s_dai -s_dai -- s_dai_plat_data -s_dai_plat_data -- s_dai_plat_fifo_data -s_dai <- lib : provides diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/images/dai-set-config.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/images/dai-set-config.pu deleted file mode 100644 index aae163c4..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/images/dai-set-config.pu +++ /dev/null @@ -1,33 +0,0 @@ -participant host as "Host" -participant ipc -participant platform -participant dai_comp as "audio/dai" -participant dai -participant dai_hw - -host -> ipc : ipc_dai_config(config) - activate ipc - - ipc -> platform : dai_get(config->type, config->id) - activate platform - ipc <-- platform : dai ptr - deactivate platform - - ipc -> dai : dai_set_config(config) - activate dai - dai -> dai_hw : setup - activate dai_hw - ipc <-- dai - deactivate dai - -host <-- ipc -deactivate ipc - -host -> dai_comp : dai_comp_trigger(cmd) - note right: Full call path includes parent pipeline - activate dai_comp - dai_comp -> dai : dai_trigger(cmd) - activate dai - dai -> dai_hw : update - dai_comp <-- dai -host <-- dai_comp diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/index.rst deleted file mode 100644 index b9441dc8..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dai/index.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. _dai-drivers: - -DAI Drivers -########### - -For the documentation of support devices refer to -:ref:`dai-drivers-supported-devices`. - -Intro -***** - -DAI drivers provide access to the Digital Audio Interfaces supported by -the platform. - -.. uml:: images/dai-ops.pu - :caption: DAI Driver API - -Programming Flows -***************** - -DAI Initialization -================== - -When ADSP enters D0, the dai instances are registered in the list maintained -by the *lib*. - -Configuration & Commands -======================== - -Before the dai client starts the device, it is configured with parameters -from the IPC command. - -.. uml:: images/dai-set-config.pu - -Using DAI Driver API -******************** - -See :ref:`dai-drivers-api` - -.. note:: - - The API is accessed through a common structure; however, an - implementation may keep some specific private data attached to the - ``dai.private`` pointer. - -.. _dai-drivers-supported-devices: - -Supported Devices -***************** - - -.. note:: - - Throughout this tutorial, we reference your website name as . diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/images/dma-ops.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/images/dma-ops.pu deleted file mode 100644 index f42c115e..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/images/dma-ops.pu +++ /dev/null @@ -1,42 +0,0 @@ -class lib { - dma_get(dmac_id) : struct dma* - dma_put(struct dma*) -} -hide lib attributes - -class dma_ops { - channel_get() - channel_put() - start() - stop() - pause() - release() - status() - set_config() - set_cb() - pm_context_restore() - probe() - remove() -} -hide dma_ops attributes - -class dma_plat_data { - id : uint32_t - base : uint32_t - channels : uint32_t - irq : uint32_t - drv_plat_data : void * -} -hide dma_plat_data methods - -class "struct dma" as s_dma { - plat_data : dma_plat_data - lock : spinlock_t - ops : const dma_ops * - private : void * -} -hide s_dma methods - -dma_ops - s_dma -s_dma -- dma_plat_data -s_dma <- lib : provides diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/images/dma-transfer.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/images/dma-transfer.pu deleted file mode 100644 index e5594acd..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/images/dma-transfer.pu +++ /dev/null @@ -1,22 +0,0 @@ -participant client -participant lib -participant dma - -== Obtaining Reference to DMAC == -client -> lib : dma_get(capabilities) -client <-- lib : dma - -== Start == -client -> dma : dma_channel_get( stream tag ) -client <-- dma : ch# - -client -> dma : dma_set_cb( ch#, client.cb() ) -client -> dma : dma_set_config( ch#, config ) -client -> dma : dma_start( ch# ) - -== Transmission == -... - -== Stop == -client -> dma : dma_stop( ch# ) -client -> dma : dma_channel_put( ch# ) diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/index.rst deleted file mode 100644 index de9d0d72..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/index.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. _dma-drivers: - -DMA Drivers -########### - -For documentation of support devices, refer to -:ref:`dma-drivers-supported-devices`. - -Intro -***** - -Access to the DMA Controllers (DMAC) available on the platform is provided by -the ``dma_get()`` function implemented by the *library* code. Reference to a -DMAC instance obtained from ``dma_get()`` is represented by a pointer to -``struct dma``. Each ``struct dma`` instance provides the ``dma_ops`` API used -by the DMA clients to set up and run the DMA transmission. - -.. uml:: images/dma-ops.pu - :caption: DMA Driver API - -Programming Flows -***************** - -DMAC Initialization -=================== - -In a one-time initialization phase, the ADSP goes to the D0 device power state. -In this fully functional state, the platform registers its DMA drivers in the -list maintained by the *lib* at startup. - -.. note:: - - A static array of ``dma`` instances declared in the platform's code - may be replaced with a dynamic discovery of the DMA resources available - on the platform, using capability registers if provided by the HW. - -Any component from the *audio* package may use a DMA engine by obtaining a -reference to the ``dma_ops`` interface from the *lib*'s list. This flow may -happen an unlimited number of times during ADSP D0. - -Channel Initialization & Data Transfer -====================================== - -.. uml:: images/dma-transfer.pu - :caption: Channel Initialization & Data Transfer - -In case the host co-manages the DMA HW and the channel is "allocated" by the -host side, the FW component must wait until its ``params()`` API is called -in order to learn the channel ID and pass it to the ``channel_get()`` request. - -Using DMA Driver API -******************** - -See :ref:`dma-drivers-api` - -.. note:: - - The API is accessed through a common structure; however, an - implementation may keep some specific private data, attached to the - ``dma.private`` pointer. - -.. _dma-drivers-supported-devices: - -Supported Devices -***************** - -.. toctree:: - :maxdepth: 2 - - intel/index diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/hda-dma.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/hda-dma.rst deleted file mode 100644 index 048bbf8e..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/hda-dma.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. _intel-cavs-hda-dma-driver: - -cAVS HD/A DMA Driver -#################### - -Probing -******* - -A basic initialization of basic data structures is performed. No piece of -HD/A HW is touched at this point. - -Configuration -************* - -HD/A DMA works with a single continuous circular buffer only. Therefore, the -SGLs are verified if they are of the same size and point to a continuous -memory space. - -The total buffer size (period size x number of periods) must be a multiple of -HD/A DMA burst size (32 bytes). - -The initial DMA HW buffer setup takes place. - -Setting up Callback -******************* - -A client (a host/dai component for instance) registers a callback by calling -``dma_set_cb()`` which is notified upon completion of the transfer of each period of -data. - -The size of the period is specified by SGL elements passed to ``dma_set_config()``. - -Starting the Device -******************* - -The device is registered in the PM platform driver to ensure that the DMI L1 is -handled properly. - -.. note:: It is not required when the PM call is made by the device - driver, but when the call is moved to the systick handler, the PM - platform driver must know if any active DMA devices are registered. - -.. uml:: images/hda-start-flow.pu - :caption: HD/A DMA Device Start Flow - -Stopping the Device -******************* - -HW reset is programmed by setting ``GEN`` to 0. DSP confirms ``GBUSY`` is 0; -otherwise, an exception is reported to the host. - -.. uml:: images/hda-stop-flow.pu - :caption: HD/A DMA Device Stop Flow - -Transferring Data -***************** - -Transmission is started on the DSP side after the ``dma_start()`` is -called as ``GEN`` is set to 1 there. - -Interrupts -========== - -Segment completion interrupts are unavailable; therefore, the DSP has to -calculate the amount of space/data available in the buffer manually by reading HD/A -register values. - -Any blocking polling must be done for as short a time as possible to release the -CPU for other tasks. The HD/A driver uses the system work queue API to check for IO -completion in the context of timer callbacks deferred to a point in time when -the IO operation is expected to finish. - -Power Management -================ - -The driver prevents the DMI from entering L1 at the end of each data copy -request for a host HD/A DMA to secure the transfer operation. - -Cyclic vs. Non-cyclic Mode of Work -================================== - -Four types of HD/A DMAs exist: - -* Host Output DMA - host memory to DSP memory -* Host Input DMA - DSP memory to host memory -* Link Output DMA - DSP memory to peripheral device memory -* Link Input DMA - peripheral device memory to DSP memory - -Host DMAs work in a non-cyclic mode in SOF, i.e. the transfer of a full period is -scheduled on demand each time and completes very quickly. - -Link DMAs work in cyclic mode. In the case of HD/A DMA, DMA pointers -are updated in real-time with a small step. - -Host Output DMA (On Demand Mode) --------------------------------- - -Host Output DMA provides input data for the DSP on a playback path. In the -beginning, once the DMA is started, the host fills up the entire buffer with data -(the buffer size is typically set to two periods of data). Subsequent transfers -are requested by the DSP by advancing its read pointer, making space for the next -transfer available to the host side. It takes some time for the initial -transfer to complete (buffer full is signaled), so the DSP should not expect -the data to be available "instantly" after the DMA is started. It should not wait -in blocking mode for "buffer full" either. However, the second copy operation -run by the pre-loader task presents a good opportunity to eventually "complete" the first transfer and reliably commit the data for further processing by the -pipeline. - -.. uml:: images/hda-host-output.pu - :caption: Host output startup sequence - -Link Input/Output DMA (Cyclic Mode) ------------------------------------ - -In order to enable cyclic mode, with no interrupt available, the DMA driver -schedules work every 1ms. - -.. uml:: images/hda-link.pu - :caption: Callback notification for link playback and capture - -Limitations -*********** - -Passthrough pipelines (host-dai) with a period size unaligned to HD/A DMA -burst size (32 bytes) cannot work with 2-periods shared buffer configured. If -the DSP moves the read pointer by unaligned size of the period, the tail -(period % burst size) is not transferred until the next pointer move. diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-host-output.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-host-output.pu deleted file mode 100644 index e56ff18e..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-host-output.pu +++ /dev/null @@ -1,67 +0,0 @@ -actor drv as "Host\nDriver" -participant ppl as "pipeline" -participant host as "host\ncomponent" -participant hda_dma -participant hda_hw as "HD/A HW" - -== Start Trigger == - -drv -> ppl : <> trigger (START) - activate ppl - - ppl -> host : trigger (START) - activate host - - host -> hda_dma : dma_start() - activate hda_dma - host <-- hda_dma - deactivate hda_dma - - host -> hda_dma : copy(flags = PRELOAD) - activate hda_dma - note right: Do not expect Buffer Full yet. - hda_dma -> hda_dma : state += PRELOAD - hda_dma -> hda_dma : preload() - activate hda_dma - note right : First non-blocking BF test - deactivate hda_dma - hda_dma -> hda_dma : state += BF_WAIT - host <-- hda_dma - deactivate hda_dma - ppl <-- host - deactivate host - - ppl -> ppl : schedule_copy_idle() - activate ppl - note right: Scheduler got a ppl task (pre-loader)\n to run in idle - deactivate ppl -drv <-- ppl -deactivate ppl - -== Pre-load == - --> ppl : pipeline_task - activate ppl - ppl -> ppl : pipeline_copy - activate ppl - ppl -> host : copy() - activate host - host -> hda_dma : copy() - activate hda_dma - hda_dma -> hda_dma : preload() - activate hda_dma - note right : Blocking BF wait this time - host <- hda_dma : callback() /for each period/ - activate host - host -> host : comp_update_buffer_produce() - host --> hda_dma - deactivate host - hda_dma -> hda_dma : clear state flags -note right: Switching to normal on demand mode.\n\ -Rptr (FPI) advanced on the next copy()\n\ -Once the first period is processed. - deactivate hda_dma - host <-- hda_dma - deactivate hda_dma - ppl <-- host - deactivate host diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-link.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-link.pu deleted file mode 100644 index 7d394d85..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-link.pu +++ /dev/null @@ -1,31 +0,0 @@ -actor client as "dai\ncomponent" -participant hda_dma -participant work_queue - -client -> hda_dma : dma_start() - activate hda_dma - note right: GEN := 1 -> transfer starts - - hda_dma -> work_queue : work_schedule_default(&hda_work, HDA_LINK_1MS_US) - hda_dma <-- work_queue -client <-- hda_dma -deactivate hda_dma - -... 1 ms elapsed ... - -work_queue -> hda_dma : hda_work->cb() - activate hda_dma - - hda_dma -> hda_dma : update FPI by 'bytes' - note right: 'commit' is always true in this scenario - - hda_dma -> hda_dma : wait for next period to be available (w/ short t/o) - - hda_dma -> client : callback() - activate client - client -> client : comp_update_buffer_produce/consume() - hda_dma <-- client - deactivate client - -work_queue <-- hda_dma : 1MS_TIMEOUT (to re-arm the timer) -deactivate hda_dma diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-start-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-start-flow.pu deleted file mode 100644 index f9929685..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-start-flow.pu +++ /dev/null @@ -1,51 +0,0 @@ -box "Host" #ffffff - participant "Host\nDriver" as drv -end box -box "HD/A HW" - participant hda_sw - participant hda_fw -end box -box "DSP" #ffffff - participant host - participant hda_dma -end box - -note over hda_sw, hda_fw: "DMA in RESET state" - --> drv : Create Stream - drv -> host : new() - host -> hda_dma : dma_get(dmac_id) - host <-- hda_dma : dmac - - drv <-- host - <-- drv - --> drv : Stream Params - drv -> hda_sw : setup DMA (format & BDL) - - drv -> host : params() - host -> hda_dma : dma_channel_get(dmac, params.stream_tag) - host <-- hda_dma : chan - - host -> hda_dma : dma_set_config(dmac, chan, config) - hda_fw <- hda_dma : DGBBA, DGBS - hda_fw <- hda_dma : DGMBS := buffer size [host dma] - hda_fw <- hda_dma : GEN := 0 - hda_fw <- hda_dma : SCS := 1 [bit_depth != 32] - hda_fw <- hda_dma : FWCB : = 1 - hda_fw <- hda_dma : FIFORDY := 0 - host <-- hda_dma - - drv <-- host - <-- drv - --> drv : RUN - drv -> hda_sw : RUN := 1 - - drv -> host : trigger(COMP_TRIGGER_START) - host -> hda_dma : dma_start() - hda_fw <- hda_dma : GEN := 1 - hda_fw <- hda_dma : FIFORDY := 1 - host <-- hda_dma - drv <-- host - <-- drv diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-stop-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-stop-flow.pu deleted file mode 100644 index b72b892a..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/images/hda-stop-flow.pu +++ /dev/null @@ -1,30 +0,0 @@ -box "Host" #ffffff - participant "Host\nDriver" as drv -end box -box "HD/A HW" - participant hda_sw - participant hda_fw -end box -box "DSP" #ffffff - participant host - participant hda_dma -end box - -note over hda_sw, hda_fw: "DMA in RUNNING state" - --> drv : Stop? - - drv -> host : COMP_TRIGGER_PAUSE ? - note right : No more FPI touching at this point - drv <-- host - - drv -> hda_sw : RUN := 0 - - drv -> host : COMP_TRIGGER_STOP - host -> hda_dma : dma_stop() - hda_fw <- hda_dma : GEN := 0 - hda_fw <- hda_dma : FIFORDY := 0 - host <-- hda_dma - drv <-- host - - drv -> hda_sw : Flush DMA,\nset SRST (stream reset) diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/index.rst deleted file mode 100644 index 5cd2bd06..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/dma/intel/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _intel-dma-drivers: - -Intel Platforms -############### - -.. toctree:: - :maxdepth: 1 - - hda-dma diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-disco.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-disco.pu deleted file mode 100644 index 9698238e..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-disco.pu +++ /dev/null @@ -1,18 +0,0 @@ -participant "platform" as plat -participant lib - --> plat : platform_init() - activate plat - - == DAI == - - plat -> plat : dai_disco() : dai_desc_list - plat -> lib : dai_install(dai_desc_list) - - == DMA == - - plat -> plat : dma_disco() : dma_desc_list - plat -> lib : dma_install(dma_desc_list) - -<-- plat -deactivate plat diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-probe.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-probe.pu deleted file mode 100644 index 0ef96326..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-probe.pu +++ /dev/null @@ -1,24 +0,0 @@ -participant "component" as comp -participant lib -participant ukernel -participant "driver" as drv -participant hw - --> comp : new() - -comp -> lib : dai_get(type, ...) - activate lib - - lib -> lib : lookup(dai_desc_list) : dai_desc - opt dai_desc->sref == 0 - lib -> drv : dai_desc->ops->probe(dai_desc) - activate drv - drv -> hw : ungate power - drv -> ukernel : alloc mem - lib <-- drv : Success - deactivate drv - end opt - lib -> lib : dai_desc->sref++ - -comp <-- lib : dev* -deactivate lib diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-remove.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-remove.pu deleted file mode 100644 index 32e40b2b..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/images/device-remove.pu +++ /dev/null @@ -1,22 +0,0 @@ -participant "component" as comp -participant lib -participant ukernel -participant "driver" as drv -participant hw - --> comp : free() - -comp -> lib : dai_put(dev*) - activate lib - - opt --dai_desc->sref == 0 - lib -> drv : dai_desc->ops->remove(dev) - activate drv - drv -> ukernel : free mem - drv -> hw : gate power - lib <-- drv : Success - deactivate drv - end opt - -comp <-- lib -deactivate lib diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/index.rst deleted file mode 100644 index d0a2b4f2..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/drivers/index.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. _drivers: - -Drivers -####### - -The drivers controls the devices attached to the platform. The following type -of devices are typically available: - -* DMA (Direct Memory Access) devices -* DAI (Digital Audio Interface) devices - -Registering the Devices -*********************** - -The devices are connected to other topology elements when the topology is being -created. The infrastructure (lib) needs to know what devices are available and -how to connect to their drivers' APIs. The platform initialization routine is -responsible for the device discovery and API registration. The discovery -mechanism depends on the platform. It may be either very simple statically -compiled list of the devices or a dynamic one based on capability information -provided by the underlying HW at run-time. - -.. uml:: images/device-disco.pu - :caption: Device discovery and registration - -Probing on Demand -***************** - -Creation of the particular device may result in a significant resource -allocation and increased power demand. Therefore the infrastructure does not -create (probe) the devices immediately upon startup. A simple reference -counting mechanism implemented inside the lib allows to probe the devices -on demand and free (remove) them when no longer in use. - -The device driver implementation of ``remove()`` API is required to free all -the resources allocated in ``probe()`` and power-gate unused HW blocks. - -.. uml:: images/device-probe.pu - :caption: Creating the device on the first use - -.. uml:: images/device-remove.pu - :caption: Removing the device when no longer in use - -API -*** - -The drivers are located at: *src/drivers* - -.. toctree:: - :maxdepth: 1 - - dma/index - dai/index diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/edf-scheduler-deps.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/edf-scheduler-deps.pu deleted file mode 100644 index 89bd4137..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/edf-scheduler-deps.pu +++ /dev/null @@ -1,6 +0,0 @@ -class "edf_schedule_data" as edf { - - list : list - - clock - - irq -} -hide edf methods diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/edf-scheduler-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/edf-scheduler-flow.pu deleted file mode 100644 index db1b44db..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/edf-scheduler-flow.pu +++ /dev/null @@ -1,21 +0,0 @@ -actor client as c - -participant edf_scheduler as edf -participant interrupt_driver as int - --> edf : scheduler_init() - activate edf - edf -> int : interrupt_register(edf_scheduler_run) - deactivate edf -<-- edf -... -c -> edf : schedule_task(&task) - activate edf - edf -> int : interrupt_set() - deactivate edf -c <-- edf - -edf <- int : edf_scheduler_run() - activate edf - edf -> edf : schedule_task_running() - edf -> edf : schedule_task_complete() diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/fw-arch-diag.png b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/fw-arch-diag.png deleted file mode 100644 index 52c5b66d..00000000 Binary files a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/fw-arch-diag.png and /dev/null differ diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/ll-scheduler-deps.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/ll-scheduler-deps.pu deleted file mode 100644 index 5ff8f402..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/ll-scheduler-deps.pu +++ /dev/null @@ -1,30 +0,0 @@ -class "ll_schedule_data" as lsd { - - tasks : list - - num_tasks - - pcd - - domain -} -hide lsd methods - -class "ll_schedule_domain" as lsdom { - - last_tick - - lock - - total_num_tasks - - num_clients - - ticks_per_ms - - type - - clk - - synchronous - - priv_data - - registered : array - - enabled : array - + domain_register() - + domain_unregister() - + domain_enable() - + domain_disable() - + domain_set() - + domain_clear() - + domain_is_pending() -} - -lsd *-- lsdom : contains diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/ll-scheduler-flow.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/ll-scheduler-flow.pu deleted file mode 100644 index fafdd382..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/ll-scheduler-flow.pu +++ /dev/null @@ -1,26 +0,0 @@ -actor client as c - -participant ll_scheduler as ls -participant ll_schedule_domain as lsd - --> lsd : domain_init -<-- lsd : domain - --> ls : scheduler_init(&domain) -<-- ls -... -c -> ls : schedule_task(&task) - activate ls - ls -> lsd : domain_register(schedule_ll_tasks_run) - ls -> lsd : domain_enable() - deactivate ls -c <-- ls -... -ls <- lsd : schedule_ll_tasks_run() - activate ls - ls -> lsd : domain_disable() - loop schedule_ll_is_pending() - ls -> ls : schedule_ll_tasks_execute() - end loop - ls -> lsd : domain_enable() - deactivate ls diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/memory-zones.dot b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/memory-zones.dot deleted file mode 100644 index e4541abf..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/memory-zones.dot +++ /dev/null @@ -1,19 +0,0 @@ -digraph memory_zones { - compound = true; - node [shape = record]; - rankdir = LR; - size=5; - - clients [label = "applications - |kernel - |drivers"]; - - zones [label = "runtime zone - |buffer zone - |{system zone |sys rt?}"]; - - clients:apps -> zones:rt; - clients:apps -> zones:buf; - clients:kernel -> zones:sys; - clients:drv -> zones:sys_rt [style = dotted]; -} diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/runtime-zone.dot b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/runtime-zone.dot deleted file mode 100644 index e2824216..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/runtime-zone.dot +++ /dev/null @@ -1,33 +0,0 @@ -digraph runtime_zone { - compound = true; - node [shape = record]; - rankdir = LR; - size=4; - - subgraph cluster_rt_0 { - label = "RUNTIME HEAP #0"; - - map0 [label = "map"]; - - rt0 [label = "{<1>64B|<2>64B|...} - |{<10>128B|<11>128B|...} - |{<20>256B|<22>256B|...} - |{....}"]; - } - - subgraph cluster_core_0 { - style = filled; - color = "#f0f0f0"; - label = ""; - - comp_0; - comp_1; - comp_2; - } - - comp_0 -> rt0:2:nw; - comp_0 -> rt0:10:nw; - comp_1 -> rt0:22:nw; - comp_2 -> rt0:1:nw; - -} diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/scheduler-ops.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/scheduler-ops.pu deleted file mode 100644 index 80bf07b1..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/scheduler-ops.pu +++ /dev/null @@ -1,19 +0,0 @@ -class "scheduler_ops" { - .. Mandatory .. - + schedule_task() - + schedule_task_cancel() - + schedule_task_free() - .. Optional .. - + schedule_task_running() - + schedule_task_complete() - + reschedule_task() - + scheduler_free() - + scheduler_run() -} - -enum schedule_types { - SOF_SCHEDULE_EDF - SOF_SCHEDULE_LL_TIMER - SOF_SCHEDULE_LL_DMA -} -hide schedule_types methods diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/system-zone.dot b/developer_guides/subsystem_architecture/firmware/sof-xtos/images/system-zone.dot deleted file mode 100644 index 06768cb9..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/images/system-zone.dot +++ /dev/null @@ -1,49 +0,0 @@ -digraph system_zone { - compound = true; - node [shape = record]; - rankdir = LR; - size=7; - - subgraph cluster_sys_0 { - label = "SYS HEAP #0"; - - s0 [label = "block\n\n\n - |block - |block\n\n - |free space...\n\n\n\n\n"]; - } - - subgraph cluster_sys_1 { - label = "SYS HEAP #1"; - - s1 [label = "block - |block\n\n - |free space...\n\n"]; - } - - subgraph cluster_core_0 { - style = filled; - color = "#f0f0f0"; - label = "core #0"; - - ipc; - scheduler_0; - work_0; - } - - subgraph cluster_core_1 { - style = filled; - color = "#f0f0f0"; - label = "core #1"; - - scheduler_1; - work_1; - } - - ipc -> s0:b0:nw; - scheduler_0 -> s0:b1:nw; - work_0 -> s0:b2:nw; - - scheduler_1 -> s1:b0:nw; - work_1 -> s1:b1:nw; -} diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/index.rst deleted file mode 100644 index 1063889e..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _sof-xtos: - -SOF with XTOS Architecture -########################## - -.. toctree:: - :maxdepth: 1 - - overview - mem-mgmt - pm-runtime/index - schedulers - drivers/index - pipelines/index - kd_integration/index diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-component-diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-component-diagram.pu deleted file mode 100644 index 252d347f..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-component-diagram.pu +++ /dev/null @@ -1,48 +0,0 @@ -@startuml - -scale max 1024 width - -skinparam rectangle { - backgroundColor<> #6fccdd - backgroundColor<> #f6ed80 - backgroundColor<> #d6d6de - borderColor<> #d6d6de - borderColor<> #a1a1ca - - backgroundColor<> #f05772 - stereotypeFontColor<> #ffffff - fontColor<> #ffffff - - backgroundColor<> #f0f0f0 -} - - -together { -rectangle "MIC HW" as dmic #DDDDDD - -rectangle "Speech Capture Pipeline" as ppl_1 <>{ - rectangle "MIC DAI" as dai_1 <> - rectangle "Keyphrase Buffer Manager" as kpb - dai_1 -> kpb : 2ch/16kHz/16bit - rectangle "Host" as host - } - -} - -rectangle "Keyphrase Detector Pipeline" as ppl_2 <>{ - rectangle "Channel selector" as sel - rectangle "Keyphrase detection algorithm" as wov - sel -> wov : 1ch/16kHz/16bit -} - -rectangle "Host System" as hsys { - rectangle "Host Memory" as hmem #DDDDDD -} - -dmic -> dai_1 -kpb -> host -kpb -> sel : 2ch/16kHz/16bit -host -> hmem : 2ch/16kHz/16bit -wov ..> kpb : FW events -wov ..> hsys : FW notifications -@enduml \ No newline at end of file diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-e2e-sequence-diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-e2e-sequence-diagram.pu deleted file mode 100644 index 344e56bb..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-e2e-sequence-diagram.pu +++ /dev/null @@ -1,123 +0,0 @@ -@startuml - -scale max 1024 width - -participant "Userspace component" as usr -participant "Audio driver" as drv -participant "FW infrastructure" as fw -participant "Data transfer to Host" as dma -participant "Keyword detection algorithm" as kda -participant "Data transfer to DSP" as gpdma - -box "Linux User/Kernel space" #LavenderBlush - participant usr - participant drv -end box - -box "DSP" #LightBlue - participant fw - participant dma - participant kda - participant gpdma -end box - -activate fw - -drv -> fw : Setup audio topology \n (Speech Capture & Keyword Detection pipes) -usr -> drv : Prepare & Open PCM capture \n(snd_pcm_open/snd_pcm_hw_params) -drv -> fw : Stream Open & Preparation -drv -> fw : HW Params -group optional (depends on keyword detection algorithm implementation) - usr -> drv : Send keyword detection algorithm parameters \n (snd_ctl_elem_tlv_write) - drv -> fw : Send keyword detection algorithm parameters - fw -> kda : Send keyword detection algorithm parameters -end - -drv ->drv : DAPM power up event -drv -> fw : HW Params for Keyphrase Detection Pipeline -usr -> drv : Trigger start (alsamixer) -drv -> fw : Keyword detection algorithm & buffer manager triggered - -fw -> fw : Keyphrase Buffer Manager \nin acquisition mode -fw -> gpdma - -activate gpdma - -fw -> kda : keypharse detection enabled - -activate kda - -usr -> drv : Trigger start (snd_pcm_read) - -note over usr -Speech application indefinitely -waits for data. -end note - -ref over usr, drv, fw , gpdma, kda, dma -Speech Capture pipeline is not transmitting data to Host system -Host system may enter the low power state -end ref - -loop keyword detection algorithm \nexecuted on DSP - kda <- gpdma -end - -hnote over kda : keyword is detected - -fw <-- kda : FW event on keyword detection -fw -> kda : keyword detection disabled - -deactivate kda - -fw -> fw : Keyphrase Buffer Manager \nin drain mode -drv <-- fw : notification on keyword detection -'drv -> fw : enable data transission to Host \n(Capture[Speech] pipeline to Host is running) -usr <-- drv : notification on keyword detection (optional) -gpdma -> dma - -activate dma - -ref over dma -Sending a burst of historic data (approx.2s) -with detected keyword for -second stage verification on host. -end ref - -gpdma <-- dma - -deactivate dma - -usr <-- drv : snd_pcm_read completed - -fw -> fw : Keyphrase Buffer Manager \nin passthrough mode - -loop Realtime capture - usr -> drv : snd_pcm_read - gpdma -> dma - activate dma - gpdma <-- dma - - deactivate dma - usr <-- drv : snd_pcm_read completed -end - -ref over usr -User space optionally performs second stage keyword verification. -end ref - -usr -> drv : Trigger stop (alsamixer) -drv ->drv : DAPM power down event -drv -> fw : Stop Keyphrase Detection algorithm pipeline -usr -> drv : Trigger stop (snd_pcm_drop / snd_pcm_free) -drv -> fw : Close Speech capture stream -fw -> gpdma - -deactivate gpdma - -ref over usr, drv, fw , gpdma, kda, dma -The flow can be repeated for next user command starting from snd_pcm_open() -end ref - -deactivate fw -@enduml \ No newline at end of file diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-state-diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-state-diagram.pu deleted file mode 100644 index ab0a9c74..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-state-diagram.pu +++ /dev/null @@ -1,44 +0,0 @@ -@startuml -[*] --> KPB_DISABLED: Start \nor\n [IPC] free \nmessage \nfrom either state -KPB_DISABLED: Starting state of KPB - \nNo action has been taken yet -KPB_DISABLED--> KPB_CREATED: [IPC] \nnew component -KPB_DISABLED-[#0000FF]-> KPB_DISABLED: [IPC] \nreset - -KPB_CREATED : New KPB component has been created -KPB_CREATED --> KPB_PREPARING: [IPC] \npcm params -KPB_CREATED -[#0000FF]-> KPB_CREATED : [IPC] \nreset - -KPB_PREPARING: Prepare Key Phrase Buffer component. -KPB_PREPARING-> KPB_STATE_RUN: Success -KPB_PREPARING-> KPB_PREPARING: Failure -KPB_PREPARING-[#0000FF]-> KPB_PREPARING: [IPC] \nreset - -KPB_STATE_RUN: KPB is prepared and ready. -KPB_STATE_RUN-[#0000FF]-> KPB_PREPARING: [IPC] \nreset -KPB_STATE_RUN---> KPB_STATE_INIT_DRAINING: [EVENT] \nkey phrase detected -KPB_STATE_RUN-> KPB_STATE_BUFFERING: Start \nbuffering - -KPB_STATE_BUFFERING: Buffer incoming samples in the \ninternal history buffer -KPB_STATE_BUFFERING-> KPB_STATE_RUN: Done -KPB_STATE_BUFFERING-> KPB_STATE_INIT_DRAINING: Done -KPB_STATE_BUFFERING-> KPB_STATE_DRAINING: Done -KPB_STATE_BUFFERING-[#0000FF]-> KPB_STATE_RESETTING: [IPC] \nreset - -KPB_STATE_INIT_DRAINING: KPB received detection event -KPB_STATE_INIT_DRAINING-[#0000FF]-> KPB_PREPARING: [IPC] \nreset -KPB_STATE_INIT_DRAINING--> KPB_STATE_DRAINING: Draining task starts -KPB_STATE_INIT_DRAINING--> KPB_STATE_BUFFERING: Start \nbuffering - -KPB_STATE_DRAINING: KPB is draining internal history buffer \nto the client's buffer -KPB_STATE_DRAINING-->KPB_STATE_HOST_COPY: Draining done -KPB_STATE_DRAINING-[#0000FF]-> KPB_STATE_RESETTING: [IPC] \nreset -KPB_STATE_DRAINING--> KPB_STATE_BUFFERING: Start \nbuffering - -KPB_STATE_RESETTING: KPB is preparing itself for the reset -KPB_STATE_RESETTING-->KPB_STATE_RESET_FINISHING - -KPB_STATE_RESET_FINISHING: KPB is finishing reset sequence -KPB_STATE_RESET_FINISHING->KPB_PREPARING: Reset done - -KPB_STATE_HOST_COPY: KPB is copying real time \nstream into client's buffer -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-timing-diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-timing-diagram.pu deleted file mode 100644 index f6f4b3bb..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/images/kd-timing-diagram.pu +++ /dev/null @@ -1,25 +0,0 @@ -@startuml - -scale max 1024 width - -footer: timeline not to scale -robust "Speech application" as App -concise "Audio Stream" as Audio - -App is idle -Audio is "Preceeding" - -@App -0 is idle -+180 is Processing - -@Audio -0 is Keyphrase -@0 <-> @100 : keyphrase length - L1 -@100 <-> @+80 : detection\ntime - L2 -@180 <-> @+80 : burst \ntransmission time - L3 -Audio@180 -> App@180 : notification -@260 <-> @+60 : safety \nmargin - L4 -100 is Command -+200 is Following -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/index.rst deleted file mode 100644 index 7aaa8c00..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _apps-kd-integration: - -Keyword detection -################# - -.. toctree:: - :maxdepth: 2 - - kd-integration - diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/kd-integration.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/kd-integration.rst deleted file mode 100644 index 021639ef..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/kd_integration/kd-integration.rst +++ /dev/null @@ -1,176 +0,0 @@ -.. _KD-integration: - -Keyword Detection integration -############################# - -Keyword Detection (KD), also known as Voice Activation or Sound Trigger, is -a feature that triggers a speech recognition engine when a predefined -keyphrase (keyword) is successfully detected. Offloading the keyphrase -detection algorithm to the embedded processing environment (i.e. dedicated -DSP) reduces system power consumption while listening for an utterance. - -The terms Voice Activation and Keyphrase Detection are often used -interchangeably to describe end-to-end system-level use cases that include: - -* Keyphrase detection algorithm -* Keyphrase enrollment (parametrization of keyphrase detection algorithm) -* Management of an audio stream that is used to transport utterances -* Steps made to reduce system-level power consumption -* System wakeup on keyphrase detection - -The Keyphrase Detector component typically is used to identify a -firmware processing component that implements an algorithm for keyphrase -detection in an audio stream. - -The speech audio stream is used to indicate that the stream is primarily used -to deliver data to the automatic speech recognition (ASR) algorithm. The -voice audio stream typically indicates that the recipient of audio data is a -human. - -Depending on system-level requirements for the keyphrase detection algorithm -and the speech recognition engine, different policies for keyphrase buffering -and voice data streaming may be applied. This document covers the reference -implementation available in SOF. The following sections cover the functional -scope. - -.. note:: - Currently, SOF implements the Keyphrase Detector component with a - reference trigger function that allows testing of E2E flow by detecting - a rapid volume change. - - -Timing sequence -*************** - -.. _timing-sequence: - -.. uml:: images/kd-timing-diagram.pu - :caption: Basic diagram for a timing sequence - -A keyphrase is preceded by a period of silence and is followed by a user -command. In order to balance power savings and user experience, the host -system (CPU) is activated only if a keyphrase is detected. To reduce the -number of false triggers for user commands, the keyphrase can be sent to the -host for additional (2nd stage) verification. This requires the FW to buffer -the keyphrase in a memory. Keyphrase transmission to the host is as fast as -possible (faster than real-time) to reduce latency for a system response. - -End-2-End flows -*************** - -.. uml:: images/kd-e2e-sequence-diagram.pu - :caption: E2E flow for SW/FW components - -The fundamental assumption for the flow is that the keyphrase detection -sequence is controlled by the user space component (application) that opens -and closes the speech audio stream. The audio topology must be set up -before the speech stream is opened. There is an optional sequence to -customize the keyword detection algorithm by behavior by sending run-time -parameters. - -During the Stream Open and Preparation phase, HW parameters are sent to the -DAI and configuration parameters are passed from the topology to the FW -components. The DAPM events handlers are used to control a Keyphrase -Detector node of the FW topology graph by the audio driver. Once the -keyphrase is detected, a notification is sent to the driver. At the same -time, an internal event in the FW triggers, draining buffered audio data in -burst mode to the host. Once the buffer is drained, the speech capture -pipeline starts to work as a passthrough capture until it is closed by the -user space application. - -FW topology -*********** - -.. uml:: images/kd-component-diagram.pu - :caption: Basic diagram for FW components topology - -The diagram above provides an overview of FW and HW components that play a -role in keyphrase detection flows. The components are organized in pipelines: - -1. Speech capture pipeline - - a) DMIC DAI configures the HW interface to capture data from microphones. - - b) The Keyphrase Buffer Manager is responsible for managing the data - captured by microphones. This includes control of an internal buffer - for incoming data and routing of incoming audio samples. The - audio buffer with historic audio data is implemented as a cyclic - buffer. While listening to a keyphrase, the component stores incoming - data in an internal buffer and copies it to a sink that leads toward - the keyword detector component. On successful detection of a - keyphrase, the buffer is drained during a burst transmission to a - host. Once the buffer is drained, it starts to work as a passthrough - component on a capture pipeline. - - c) The host component configures transport (over DMA) to the host system. - The component is responsible for transmitting from local memory - (FW accessible) to remote (host CPU accessible) memory. - - -2. Keyphrase detector pipeline - - a) The channel selector is responsible for providing a single channel on - input to the keyphrase detection algorithm. The decision of which - channel to select is made by the platform integrator. The component - can accept parameters from a topology file. - - b) The keyphrase detection algorithm accepts audio frames and returns - information if a keyphrase is detected. Note that the FW infrastructure - can allow a FW event to be sent to the Keyphrase Buffer Manager - component if a keyphrase is detected. The component also sends a - notification to the audio driver and implements large parameters - support. - -KPBM state diagram -****************** - -The state diagram below presents all possible keyphrase buffer manager states -as well as the valid relationships between them. - -.. uml:: images/kd-state-diagram.pu - :caption: Keyphrase buffer manager state diagram - -Latency & buffering -******************* - -This section covers calculations needed to be done to properly configure -the keyphrase buffer size. The symbols used in a formula below are depicted -above; see :ref:`timing-sequence`. - -.. note:: - - The formula for size of a keyphrase buffer: - ( L1 + L2 + L3 + L4 ) * number of channels * bitdepth = Size [Kb] - - -Specifically: - -1. L1 is defined as length of a keyphrase with preceding or trailing silence. - The value depends highly on the keyphrase itself and detection algorithm - requirements. - -2. L2 is a sum of the algorithmic (processing) latency of a detection - algorithm and the additional time needed to execute additional components - in pipelines as well as prepare and send notifications. - -3. L3 is the time required to send already-buffered data to the host. - Typically, a Write Pointer (WP) is used to indicate where data that's - coming from microphones is written to a keyphrase buffer. The keyphrase - buffer is organized as a cyclic buffer and the WP moves if data is coming - from mics at a regular rate. The Read Pointer (RP) indicates from which - offset in the buffer data is fetched to host. To start burst - transmission, the RP is set to the WP - "history depth" position. The - history depth is defined at FW or is passed from topology. The RP moves - faster than the WP due to draining that is executed as a background task. - The draining phase lasts until the RP again reaches the WP, which - moves at a regular (slower) rate. This signals the end of the L3 period - and the RP follows the WP at a rate that the data is available in the DAI - DMA buffer. Implementation note: "history depth" may be updated - on-the-fly during the draining phase if new data is captured in the - meantime. - -4. L4 is a safety margin that can be accommodated in any period of time - defined above. It is explicitly defined to make sure it is included in - the calculation. L4 length depends on: an audio frame size that is - processed by a detector; the amount of detector compute time; the output - audio format; the keyphrase buffer size; etc. diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/mem-mgmt.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/mem-mgmt.rst deleted file mode 100644 index e96b955a..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/mem-mgmt.rst +++ /dev/null @@ -1,102 +0,0 @@ -.. _kernel-mem-mgmt: - -Memory Management -################# - -Heap Memory Zones -***************** - -The heap has three different zones from where memory can be allocated: - -System Zone - Fixed size heap where allocation always succeeds and is never freed. Used - by any initialization code that will never give up the memory. - -Runtime Zone - Main and larger heap zone where allocations are not guaranteed to succeed. - Memory can be freed here. - -Buffer Zone - Largest heap zone intended for audio buffers. See platform/memory.h for - heap size configuration and mappings. - -.. graphviz:: images/memory-zones.dot - :caption: Memory Zones - -System Zone -*********** -The system zone receives a series of allocations during the system -initialization phase. Since no memory is freed until the system (core) goes -down, the allocation mechanism might be simple, ensuring that a sufficient -offset to the beginning of free space left is maintained. - -.. graphviz:: images/system-zone.dot - :caption: System Zone - -All system-level components (schedulers, work queues, etc.) allocate their -memory blocks from the system heap. Separation between the system heap and -runtime heap(s) might be further hardened in case an access control for user -mode vs. kernel mode is supported by the architecture/platform. - -Extensions for SMP Architectures -================================ - -Each CPU (core) might own a dedicated system heap. The memory assigned for -system heaps is distributed asymmetrically on CAVS platforms: a large heap -for the primary core (#0) and smaller ones for other cores (#1+). - -When a core goes down, the entire heap can be freed by moving back the free -space offset to the beginning of the heap. - -The heap can be aligned with memory bank(s) to provide better control over -power consumption. Once a core goes down, memory banks allocated for -its system heap can be powered off as well. - -Runtime Zone -************ - -* Provides flexible ``malloc``/``free`` operations. - -* Since the runtime zone is separated from the system zone, adjustment - and complex usage scenarios do not interface with system allocations. - -.. graphviz:: images/runtime-zone.dot - :caption: Runtime Zone - -Buffer Zone -*********** - -Information is forthcoming. - -Shared Data -************* - -Shared data refers to a piece of memory that can be accessed by different -DSP cores. Data can be declared as shared in one of two ways, depending on -its type: - -* Static global variables are marked with the ``SHARED_DATA`` definition. - -* Heap data is allocated with the ``SOF_MEM_FLAG_SHARED`` flag. - -To keep data synchronized, commit very read and write access to the shared -data by using the dedicated ``platform_shared_commit`` function. Note that -read-only access does not exist and that shared data must be synchronized -even after just reading. - -Both the ``SHARED_DATA`` macro and the ``platform_shared_commit`` function -are platform-specific and can be implemented differently on different -platforms. Two general approaches can be used, based on available hardware -support: - -1. Platform uses L1 cache, but also supports uncached memory regions: - - * ``SHARED_DATA`` puts data into a dedicated firmware section that is accessed using uncache. - - * ``platform_shared_commit`` does nothing. - -2. Platform uses L1 cache and doesn't support uncached memory regions: - - * ``SHARED_DATA`` does nothing. - - * ``platform_shared_commit`` writebacks and invalidates cache. diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/overview.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/overview.rst deleted file mode 100644 index 94b44a8a..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/overview.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _sof-legacy-overview: - -Overview -########## - -Currently SOF has support for the Cadence Xtensa DSP architecture in UP and SMP -modes in the upstream code base. - -The diagram below shows the high-level firmware architecture with the -Bay Trail platform integration as an example. The firmware is divided into four -main sections: - -#. **Generic microkernel.** The microkernel manages and abstracts the - DSP hardware for the rest of the system. It also exports C APIs for - memory allocation, scheduling work, event notifications, and power - management. - -#. **Audio components.** The audio components can be used to form an - audio processing pipeline from the host DMA buffer to the DSP digital - audio interface. Audio components will have a source and sink buffer - where they will usually transform or route audio data as part of their - processing. - -#. **Audio task.** The audio task manages the audio pipelines at run - time; it manages the transportation of data from source to sink - component within the pipeline. The pipelines are currently statically - defined in the firmware, but infrastructure is now in place to allow the - dynamic creation of pipelines from Linux userspace. - -#. **Platform drivers.** The platform drivers are used to control any - external IP to the DSP IP. This will usually be things like DMA engines - or DAI (Digital Audio Interface) controllers. These drivers are used by - the audio components and pipelines to send/receive data to/from the host - and external codecs. - - .. figure:: ./images/fw-arch-diag.png - :align: center - :alt: SOF Architecture - :width: 800px - - `Sound Open Firmware Architecture using Intel Bay Trail Platform` - - -Each section above is well insulated from the other sections by partitioning -code into separate directories and by using DSP and platform agnostic generic -APIs for orchestration between the sections. diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-new.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-new.pu deleted file mode 100644 index fe7cd7bc..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-new.pu +++ /dev/null @@ -1,7 +0,0 @@ -participant "pipeline" as ppl - --> ppl : pipeline_new(pipe_desc, cd) - ppl -> heap : rzalloc(RZONE_RUNTIME, ...) - ppl -> ppl : sched_comp = cd - note right: sched_comp is used as root comp for pipeline scheduling -<-- ppl diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-op-downstream.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-op-downstream.pu deleted file mode 100644 index 83eccfdc..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-op-downstream.pu +++ /dev/null @@ -1,22 +0,0 @@ -participant "pipeline" as ppl -participant "component" as comp --> ppl : comp_op_downstream(op_data,\nstart, current, previous) - note right: start, current, and previous are struct *comp_dev - alt op_data->op == COMP_OPS_PARAMS - ppl -> comp : comp_install_params(current) - ppl -> comp : comp_params(current) - else COMP_OPS_CMD - ppl -> comp : comp_cmd(current) - ppl -> ppl : pipeline_cmd_update(current) - else COMP_OPS_PREPARE - ppl -> comp : comp_prepare(current) - else COMP_OPS_RESET - ppl -> comp : comp_reset(current) - else COMP_OPS_BUFFER - note right: error, handled by other API calls - end - loop for each current's sink - ppl -> ppl : component_op_downstream(..., current = consumer @ sink/source) - note right: recursive call - end -<-- ppl diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-operations.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-operations.pu deleted file mode 100644 index 03a2de39..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-operations.pu +++ /dev/null @@ -1,9 +0,0 @@ -participant "pipeline" as ppl - --> ppl : (op = COMP_OPS_...) - alt SOF_IPC_STREAM_PLAYBACK - ppl -> ppl : comp_op_downstream(op) - else - ppl -> ppl : comp_op_upstream(op) - end -<-- ppl diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-params.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-params.pu deleted file mode 100644 index 87911f52..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-params.pu +++ /dev/null @@ -1,20 +0,0 @@ -actor driver as drv -participant ipc -participant "pipeline" as ppl - -drv -> ipc : ipc_stream_pcm_params() - activate ipc - ipc -> ppl : pipeline_params() - activate ppl - ppl -> ppl : (COMP_OPS_PARAMS, first = pcm_dev, params) - ipc <-- ppl - deactivate ppl - - ipc -> ppl : pipeline_prepare() - activate ppl - ppl -> ppl : (COMP_OPS_PREPARE) - ppl -> ppl : component_prepare_buffers_downstream/upstream() - ipc <-- ppl - deactivate ppl -drv <-- ipc -deactivate ipc diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-reset.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-reset.pu deleted file mode 100644 index 53e97dde..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-reset.pu +++ /dev/null @@ -1,5 +0,0 @@ -participant "pipeline" as ppl - --> ppl : pipeline_reset() - ppl -> ppl : (COMP_OPS_RESET) -<-- ppl diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-struct.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-struct.pu deleted file mode 100644 index dca9eed3..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-struct.pu +++ /dev/null @@ -1,26 +0,0 @@ -class "pipeline" { - ipc_pipe - comp_list : list of components - buffer_list : list of buffers - pipe_task - sched_comp : comp_dev * - status : uint32_t -} -hide pipeline methods - -class sof_ipc_pipe_new { - comp_id - pipeline_id - sched_id - ... -} -hide sof_ipc_pipe_new methods -note right: attributes provided\nthrough ipc - -class task -hide task members -hide task attributes -note right: task registered\nin scheduler - -pipeline -- sof_ipc_pipe_new : ipc_pipe -pipeline - task : "pipe_task" diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-task.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-task.pu deleted file mode 100644 index 5382067c..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/images/ppl-task.pu +++ /dev/null @@ -1,15 +0,0 @@ -participant "pipeline" as ppl - --> ppl : pipeline_task() - activate ppl - ppl -> ppl : pipeline_copy() - activate ppl - ppl -> ppl : pipeline_copy_from_upstream() - activate ppl - deactivate ppl - ppl -> ppl : pipeline_copy_to_downstream() - activate ppl - deactivate ppl - deactivate ppl -<-- ppl -deactivate ppl diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/index.rst deleted file mode 100644 index b8e69614..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pipelines/index.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _apps-pipelines: - -Pipelines -######### - -.. uml:: images/ppl-struct.pu - :caption: Pipeline structure - -Creating a Pipeline -******************* - -.. uml:: images/ppl-new.pu - :caption: Creating a pipeline - -The scheduling component (``sched_comp``) is configured by the driver inside -the IPC request. It is usually set to the dai component id for pipelines that -are attached to a dai instance and are driven by that dai's IO events. - -Executing an Operation -********************** - -Most of the pipeline functions sets the operation id and executes a common -routine, either ``component_op_downstream()`` in case of a playback path or -``component_op_upstream()`` otherwise. - -.. uml:: images/ppl-operations.pu - :caption: Pipeline Operation - -Propagating the Operation Downstream -==================================== - -.. uml:: images/ppl-op-downstream.pu - :caption: Going downstream - -Propagating the Operation Upstream -================================== - -The ``comp_op_upstream()`` algorithm is identical except for the loop at the end that runs over the sources and calls itself recursively for producers. - -Resetting Pipeline -****************** - -.. uml:: images/ppl-reset.pu - :caption: Resetting a pipeline - -Configuring Audio Parameters & Preparing for Use -************************************************ - -.. uml:: images/ppl-params.pu - :caption: Configuring audio parameters - -Scheduling -********** - -A pipeline's task (see _Processing_) may be scheduled at a certain point in time using ``pipeline_schedule_copy(start)``. In order to schedule the next stream copy operation in idle (see pre-loader), ``pipeline_schedule_copy_idle()`` should be used. - -Processing -********** - -.. uml:: images/ppl-task.pu - :caption: Pipeline task routine called by the scheduler diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-idle.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-idle.pu deleted file mode 100644 index 96eb713f..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-idle.pu +++ /dev/null @@ -1,28 +0,0 @@ -scale max 800 width - -participant drv as "Driver" -participant ipc -participant mct as "master-core-task" -participant platform -participant pm_rt as "pm-runtime" - -drv -> ipc : PM_GATE (PPG = 0) -note left: Entering idle... - activate ipc - ipc -> pm_rt : pm_runtime_enable(PM_RUNTIME_DSP, 0) - activate pm_rt - pm_rt -> pm_rt : ref_cnt-- - note right: 1 -> 0 (if there was no other disable calls) - ipc <-- pm_rt - deactivate pm_rt -drv <-- ipc -deactivate ipc - -mct -> platform : platform_wait_for_interrupt() - activate platform - platform -> pm_rt : pm_runtime_is_active(PM_RUNTIME_DSP, 0) - activate pm_rt - platform <-- pm_rt : false - deactivate pm_rt - platform -> platform : d?-idle state if available - deactivate platform diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-init.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-init.pu deleted file mode 100644 index ddab1e0a..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/images/pm-dsp-core-init.pu +++ /dev/null @@ -1,34 +0,0 @@ -scale max 800 width - -participant drv as "Driver" -participant ipc -participant mct as "master-core-task" -participant platform -participant pm_rt as "pm-runtime" - -mct -> platform : platform_init() - activate platform - - platform -> pm_rt : pm_runtime_disable(PM_RUNTIME_DSP, 0) - activate pm_rt - note right: Make latency of dsp core 0 int handler minimal - pm_rt -> pm_rt : ref_cnt++ - note right: 0 -> 1 - platform <-- pm_rt - deactivate pm_rt - -mct <-- platform -deactivate platform - -drv -> ipc : building topology - ipc -> mct - mct -> platform : platform_wait_for_interrupt() - activate platform - platform -> pm_rt : pm_runtime_is_active(PM_RUNTIME_DSP, 0) - activate pm_rt - platform <-- pm_rt : true - deactivate pm_rt - platform -> platform : d0-idle state - deactivate platform - ipc <-- mct -drv <-- ipc diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/index.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/index.rst deleted file mode 100644 index 3b59c40d..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _kernel-pm-runtime: - -Power Management -################ - -.. toctree:: - :maxdepth: 1 - - pm-dsp-core - intel/pm-dsp-core-cavs - -API -*** - -:ref:`pm-runtime-api` diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/intel/images/dsp-core-lps-cavs-d0-d0i3-d0.pu b/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/intel/images/dsp-core-lps-cavs-d0-d0i3-d0.pu deleted file mode 100644 index 4f4c2369..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/intel/images/dsp-core-lps-cavs-d0-d0i3-d0.pu +++ /dev/null @@ -1,37 +0,0 @@ -scale max 800 width - -participant platform -participant lps as "cavs/lps_wait" -participant lps_pg as "cavs/lps\npg thread" -participant pm_rt as "pm-runtime" - -participant lpsram_boot as "Lpsram\nBoot" -participant dsp_rom as "Dsp\nRom" - --> platform : platform_wait_for_interrupt() - activate platform - platform -> lps : lps_wait_for_interrupt() - activate lps - lps -> lps : platform_pg\nint_handler(D0i3/D0) [SW INT] - activate lps - lps -> pm_rt : pm_runtime_put(DSP, 0) - note right: DSP core PG\nenabled - lps -> lps_pg : platform_pg_task - deactivate lps - activate lps_pg - lps_pg -> lps_pg : configure lpsram boot - lps_pg -> lps_pg : waiti - note right: DSP core is PG-ed - deactivate lps_pg -... - -dsp_rom <- : INT -lpsram_boot <- dsp_rom -lps <- lpsram_boot : platform_pg\nint_handler(D0i3/D0) [SW INT] - activate lps - lps -> pm_rt : pm_runtime_get(DSP, 0) - note right: DSP core PG\ndisabled - lps <-- lps - deactivate lps -platform <-- lps -<-- platform diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/intel/pm-dsp-core-cavs.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/intel/pm-dsp-core-cavs.rst deleted file mode 100644 index 50c61a11..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/intel/pm-dsp-core-cavs.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _pm-dsp-core-cavs: - -cAVS pm-runtime for DSP core 0 -############################## - -cAVS provides two levels of power savings for DSP cores: - -- clock gating, - -- power gating in idle, important part of *D0i3* state. - -The clock gating is enabled by default. When a DSP core enters idle (calls -``waiti``), the clock signal is gated (note that ``CCOUNT`` is not incremented -in this state, so the only reliable always running clock is the Wall Clock). - -The power gating mechanism is enabled if the *CAVS_LPS* config option is set. -The ``waiti`` entry/exit transitions are driven by the Low Power Sequencer -(LPS). The platform is able to shut the DSP core down on ``waiti`` and power -it up on interrupt. - -The LPS mechanism is used only if ``pm_runtime_is_active()`` returns *false* -meaning that DPS core 0 does not have to be locked in D0 state. - -Implementation note: cAVS simply uses ``pm_runtime_get()`` -/``pm_runtime_put()`` operations to program the power gating control registers -in D0i3 to indicate that DSP core should be powered down/up while -entering/exiting ``waiti``. - -.. uml:: images/dsp-core-lps-cavs-d0-d0i3-d0.pu - :caption: DSP Core 0 idle in D0i3 on cAVS with LPS diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/pm-dsp-core.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/pm-dsp-core.rst deleted file mode 100644 index 0f4597d7..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/pm-runtime/pm-dsp-core.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. _pm-dsp-core: - -Power Management for DSP Cores -############################## - -DSP cores are managed by using ``PM_RUNTIME_DSP`` context id and core index to -the pm-runtime functions. - -Some platforms may provide advanced power management of the DSP cores, -including clock gating in idle, full power gating in idle, etc. depending on -how the cores are integrated on that platform. - -An implementation of platform API may provide customized idle entry function -``platform_wait_for_interrupt()`` which might simply call -``arch_wait_for_interrupt()`` or perform more sophisticated power transition to -lower the power consumed when a DSP core is in idle. - -An advanced power transitions may take more time to complete since the DSP core -/ platform has to return from a deeper power state. This additional latency is -not always acceptable, for instance it might be better to complete the initial -platform setup faster, with a quicker IPC request handling. Therefore the -platform initialization code (``platform_init()``) may disable the advanced -pm-runtime of the DSP core by calling ``pm_runtime_disable(PM_RUNTIME_DSP, 0)`` -and wait for the driver to enable it once the initialization is complete by -sending ``PM_GATE (PreventPowerGating=0)`` IPC. The ``PM_GATE`` handler calls -either ``pm_runtime_enable(PM_RUNTIME_DSP, 0)`` or -``pm_runtime_disable(PM_RUNTIME_DSP, 0)`` depending on the value of the ``PPG`` -flag. Note that enable/disable calls are ref-counted as there might be other -internal clients interested in locking the DSP core in the highest state in -order to keep the ``waiti`` entry/exit latency minimal and get better -performance. - -``pm_runtime_is_active(PM_RUNTIME_DSP, 0)`` may be used to query the state of -ref-counter and decide whether transitions to deeper power states are allowed -inside the ``platform_wait_for_interrupt()``. - -.. uml:: images/pm-dsp-core-init.pu - :caption: Pm-runtime: DSP Core 0 initial setup - -.. uml:: images/pm-dsp-core-idle.pu - :caption: Pm-runtime: DSP Core 0 enters idle diff --git a/developer_guides/subsystem_architecture/firmware/sof-xtos/schedulers.rst b/developer_guides/subsystem_architecture/firmware/sof-xtos/schedulers.rst deleted file mode 100644 index 17d751d2..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-xtos/schedulers.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. _schedulers_xtos: - -Schedulers -########## - -Scheduler Registration -********************** - -The Schedule API is an abstract layer that allows for scheduler -registration, task creation, and scheduling. New schedulers can be added by -extending a list of pre-defined schedule types. Currently supported types -are: ``SOF_SCHEDULE_EDF``, ``SOF_SCHEDULE_LL_TIMER`` and ``SOF_SCHEDULE_LL_DMA``. Every newly-added scheduler should implement at least -a mandatory subset of ``scheduler_ops``. - -.. uml:: images/scheduler-ops.pu - :caption: Scheduler operations - -The ``scheduler_init`` function must called in order to register the -scheduler with a given ``type``, ``scheduler_ops``, and the custom -scheduler's data. Scheduling is as simple as initializing a task with ``schedule_task_init`` and passing such an object later on to scheduler -operations. - -Low Latency Scheduler -********************* - -The low latency scheduler executes all registered tasks concurrently based -on their initial priorities and periods of execution. This task chain is a *critical section* which removes any possibility of a system interrupt -preemption. Thus, every client of the scheduler should be aware of the -task's expected DSP utilization and try not to register long-running -processings which can lead to system instability. - -The low latency scheduler requires a low latency schedule domain in order to -be initialized. Each domain includes a different type of interrupt source -that runs the scheduler. Three domains are supported: timer, DMA multiple -channels, and DMA single channel. The timer domain is a simple timer-based -interrupt that occurs after a specified number of cycles. Schedulers for the -DMA multiple channels domain run after every channel interrupt. DMA single -channels run only on interrupts coming from one of the channels. The -appropriate DMA channel is selected based on the order of task registration -and also the task's period. - -Note that even though the domains are shared among all DSP cores, the low -latency schedulers are instantiated per core. - -.. uml:: images/ll-scheduler-deps.pu - :caption: Low latency scheduler dependencies - -.. uml:: images/ll-scheduler-flow.pu - :caption: Basic low latency scheduler flow - -EDF Scheduler -************* - -The EDF scheduler executes all registered tasks based on their deadlines. -Every EDF task has its own private stack which allows for full preemption -support. The task with an earlier deadline can easily pause the execution of -the task with a higher deadline, execute first, and return to the preempted -task after that. Since EDF tasks run on a passive irq level, they can be -preempted by every interrupt. - -The EDF scheduler is instantiated per core. - -.. uml:: images/edf-scheduler-deps.pu - :caption: EDF scheduler structure - -.. uml:: images/edf-scheduler-flow.pu - :caption: Basic EDF scheduler flow - - diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/app_layer/images/app_layer_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/app_layer/images/app_layer_diagram.pu deleted file mode 100644 index dea00068..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/app_layer/images/app_layer_diagram.pu +++ /dev/null @@ -1,68 +0,0 @@ -@startuml -allowmixing - -scale max 1280 width - -package "SOF" { - - package "Application layer" as APP_CUSTOMIZATION { - - package "Example Loadable Module" as LOADABLE_MODULE { - component "3rd Party Post-Processing" as PROCESSING_3RD_PARTY - component "WoV" as WOV_MODULE - component "ACA" as ACA_MODULE - component "Other modules" as OTHER_MODULES - - PROCESSING_3RD_PARTY -[hidden]right- WOV_MODULE - WOV_MODULE -[hidden]right- ACA_MODULE - ACA_MODULE -[hidden]right- OTHER_MODULES - } - - package "Built-in Module" as BUILTIN_MODULE { - component "Copier" as COPIER - component "SRC" as SRC - component "Mixers" as MIXERS - component "History Buffer/KPB" as HISTORY_BUFFER - component "Probe" as PROBE - - COPIER -[hidden]right- SRC - SRC -[hidden]right- MIXERS - MIXERS -[hidden]right- HISTORY_BUFFER - HISTORY_BUFFER -[hidden]right- PROBE - } - - BUILTIN_MODULE -[hidden]down- LOADABLE_MODULE - } - - package "System Services" as SYS_SERVICES { - - interface "System Services" as SS - - package "Media Processing Pipelines Services extension" as KERNEL_EXTENSION { - component "Communication" as COMMUNICATION - component "Pipelines and Component Infrastructure" as PIPELINE_COMPONENT_INFRASTRUCTURE - component "AVS Scheduling" as AVS_SCHEDULERS - - COMMUNICATION -[hidden]right- PIPELINE_COMPONENT_INFRASTRUCTURE - PIPELINE_COMPONENT_INFRASTRUCTURE -[hidden]right- AVS_SCHEDULERS - } - - package "Zephyr" as ZEPHYR { - component "Services" as SERVICES - } - - SS -[hidden]down- KERNEL_EXTENSION - SS -[hidden]down- ZEPHYR - - KERNEL_EXTENSION -[hidden]right- ZEPHYR - } - - APP_CUSTOMIZATION -[hidden]down- SYS_SERVICES - BUILTIN_MODULE .down. SS - PROCESSING_3RD_PARTY .down. SS - WOV_MODULE .down. SS - ACA_MODULE .down. SS - OTHER_MODULES .down. SS -} - -@enduml \ No newline at end of file diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/app_layer/index.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/app_layer/index.rst deleted file mode 100644 index fba32384..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/app_layer/index.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. _app_layer: - -Application Layer -################# - -Application Layer represents the built-in FW modules (processing components), loadable FW -modules and example templates with application libraries required for -modules integration. Application layer content is assumed to be open source -and only proprietary 3rd party components should remain private. - -.. uml:: images/app_layer_diagram.pu - :caption: Application Layer - -Modules in Application Layer -**************************** - -The built-in modules are built together with base firmware and they have -direct access to all firmware drivers and service APIs. When built-in module -is enabled in configuration, it is guaranteed to exist in firmware binary. - -The loadable modules are built separately from base firmware and they are -loaded dynamically as a separate binary, depending on the host audio -configuration. To build, use LMDK(Loadable Module Development Kit) -which is standalone kit containing all required files. - -All the application layer module access base firmware services are via the System -Services ABI. - -**NOTE:** The built-in modules are utility components provided by the base -firmware/kernel. - -Examples of built-in modules: - -* Audio built-in components: Copiers, Mixers, Volume, SRC, etc. - -Example how to build a loadable module: - -* Example Up-Down-Mixer build using :ref:`lmdk_user_guide` - -Probe -===== - -The probe module is special module in FW infrastructure that allows to inject -or extract data from a specified probe point. The traditional client -platforms use HDA DMAs to transfer data in and out of such module. - -Loadable Modules -================ - -The loadable modules are build into separate binaries from the main SOF build. To communicate with them -is used native system agent and to control is used module api :ref:`apps-comp-world`. diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/images/overview_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/images/overview_diagram.pu deleted file mode 100644 index 8ee7f089..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/images/overview_diagram.pu +++ /dev/null @@ -1,42 +0,0 @@ -@startuml -allowmixing - -scale max 1280 width - -package "SOF" { - - package "Application layer - user space" as APPLICATION_LAYER { - component "3rd party algorithms" - private" as 3RD_PARTY_ALGOS - component "Loadable libraries" as LOADABLE_COMPONENTS - component "Built-in Processing components" as BUILTIN_COMPONENTS - - BUILTIN_COMPONENTS -[hidden]right- LOADABLE_COMPONENTS - LOADABLE_COMPONENTS -[hidden]right- 3RD_PARTY_ALGOS - } - - package "Kernel space" { - - package "Media Processing Pipelines layer - kernel extension" as KERNEL_EXTENSION { - component "Communication" as COMMUNICATION - component "Pipelines and Component Infrastructure" as PIPELINE_COMPONENT_INFRASTRUCTURE - component "AVS Scheduling" as AVS_SCHEDULERS - - COMMUNICATION -[hidden]right- PIPELINE_COMPONENT_INFRASTRUCTURE - PIPELINE_COMPONENT_INFRASTRUCTURE -[hidden]right- AVS_SCHEDULERS - } - - package "Zephyr RTOS layer" as RTOS { - component "Services" as SERVICES - component "SoC HAL" as SOC - component "Drivers" as DRIVERS - - SERVICES --[hidden]right-- SOC - SOC --[hidden]right-- DRIVERS - } - - APPLICATION_LAYER -[hidden]down- KERNEL_EXTENSION - KERNEL_EXTENSION -[hidden]down- RTOS - } -} - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/images/sof_lib.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/images/sof_lib.pu deleted file mode 100644 index b819e2e4..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/images/sof_lib.pu +++ /dev/null @@ -1,39 +0,0 @@ -component "app/mpp" as app - -component lib <> { - interface cpu - interface dai - interface dma - interface pm_runtime - - component dai_mng - dai_mng -up- dai - component dma_mng - dma_mng -up- dma - component pm_runtime_impl - pm_runtime_impl -up- pm_runtime -} - -app .down.> dai : uses -app .down.> dma : uses -app .down.> pm_runtime : uses -app .down.> cpu : uses - -component "arch/xtensa/lib" as arch_xtensa { - component arch_cpu -} -arch_cpu -up- cpu - -component vendor { - component platform { - component dai_init - dai_init .up.> dai_mng : initialize - component dma_init - dma_init .up.> dma_mng : initialize - component platform_pm_runtime - } - component drivers - drivers .up.> dma : uses -} -arch_cpu .down.> platform -pm_runtime_impl .down.> platform_pm_runtime diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/images/sof_lib_zephyr.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/images/sof_lib_zephyr.pu deleted file mode 100644 index d39e6c48..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/images/sof_lib_zephyr.pu +++ /dev/null @@ -1,53 +0,0 @@ -component "app/mpp" as app - -component lib <> { - interface cpu - interface dai - interface dma - interface pm_runtime - - ' component dai_mng - ' dai_mng -up- dai - ' component dma_mng - ' dma_mng -up- dma - ' component pm_runtime_impl - ' pm_runtime_impl -up- pm_runtime -} - -app .down.> dai : uses -app .down.> dma : uses -app .down.> pm_runtime : uses -app .down.> cpu : uses - -component "lib-zephyr" as lib_zephyr { - component "cpu-flows" as cpu_flows - cpu_flows -up- cpu -} - -component "zephyr" as zephyr { - component "api" as zephyr_api -} - -cpu_flows .down.> zephyr_api : uses -zephyr_api -up- dai -zephyr_api -up- dma -zephyr_api -up- pm_runtime - -' component "arch/xtensa/lib" as arch_xtensa { -' component arch_cpu -' } -' arch_cpu -up- cpu - -' component vendor { -' component platform { -' component dai_init -' dai_init .up.> dai_mng : initialize -' component dma_init -' dma_init .up.> dma_mng : initialize -' component platform_pm_runtime -' } -' component drivers -' drivers .up.> dma : uses -' } -' arch_cpu .down.> platform -' pm_runtime_impl .down.> platform_pm_runtime diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/index.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/index.rst deleted file mode 100644 index e89e5913..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _sof-zephyr: - -SOF with Zephyr Architecture -############################ - -.. toctree:: - :maxdepth: 1 - - overview - app_layer/index - mpp_layer/index - rtos_layer/index - zephyr_api_integration diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/async_messaging.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/async_messaging.rst deleted file mode 100644 index 77813193..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/async_messaging.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _async_msg: - -Asynchronous Messaging Service -############################## - -Asynchronous Messaging Service (AMS) is designed to exchange sporadic / -asynchronous events between firmware components, such as key phrase detection. -It can also be optionally selected in the firmware build configuration. The -service exposes an external interface to the host and is API accessible from -firmware components. - -**NOTE:** The AMS integration is currently a work in progress; it might not be -fully functional in SOF main branch. - -Asynchronous messages are one-way from producer to all consumers and allows to: - - - direct asynchronous communication between components (1:1) - - sending one asynchronous message to many components (1:N) - - producing asynchronous messages by many modules where 1 is receiving (M:1) - - producing asynchronous messages by many modules where many are receiving (M:N) - -Messages are exchanged over IDC protocol and shared memory with multi-core -support. Message producers and consumers can be run on different cores. - -Development guide: :ref:`async_messaging_best_practices` - -.. TODO: Add link to AMS interface generated from code - -Asynchronous Messaging Flows -**************************** - -Producer and consumer on the same core -====================================== - -.. uml:: images/async_messaging/flow_prod_cons_same_core.pu - :caption: Asynchronous Messaging example with WoV producer and custom module consumer running on single core - -Producer on primary core, consumer on secondary core -==================================================== - -.. uml:: images/async_messaging/flow_prod_primary_cons_secondary_core.pu - :caption: Asynchronous Messaging example with WoV producer on primary core and custom module consumer running on secondary core - -.. TODO: Port additional async messaging uml flows from internal FAS documentation diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/dp_scheduling.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/dp_scheduling.rst deleted file mode 100644 index c6adf7ff..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/dp_scheduling.rst +++ /dev/null @@ -1,614 +0,0 @@ -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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_cons_same_core.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_cons_same_core.pu deleted file mode 100644 index 876bea23..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_cons_same_core.pu +++ /dev/null @@ -1,83 +0,0 @@ -@startuml - -box "DSP #0 (primary)" #LightBlue - participant "DSP #0: AMS" as ams - participant "DSP #0: KR" as kr - participant "DSP #0: Custom module" as custom_module -end box - -box "Shared SRAM" - participant "AMS database" as ams_db -end box - -... - -group Register KEY_PHRASE_DETECTED producer - group Get Message ID - kr -> ams: am_service_get_message_type_id(KEY_PHRASE_DETECTED UUID) - activate ams - ams -> ams_db: Find ID for KEY_PHRASE_DETECTED message - activate ams_db - alt If no KEY_PHRASE_DETECTED is found - ams -> ams_db: Assign ID to KEY_PHRASE_DETECTED message - return - end - return - end - - kr -> ams: am_service_register_producer(message_id) - activate ams - return -end - -... - -group Register KEY_PHRASE_DETECTED consumer - group Get Message ID - custom_module-> custom_module - end - - custom_module -> ams: am_service_register_consumer(message_id, callback) - activate ams - ams -> ams_db: Add KEY_PHRASE_DETECTED message consumer - return -end - -... - -group Send Async Message - kr -> ams: am_service_send_message(lp_kpd_id, message) - activate ams - - ams -> ams_db: Get KEY_PHRASE_DETECTED consumers - loop Until all consumer are called - ams -> ams_db: Get AMS consumer Processor ID - - alt AMS Consumer Processor ID != Current Processor ID - ams -> ams: Forward AMS message to the consumer's core - else AMS Consumer Processor ID == Current Processor ID - ams -> ams_db: Get AMS consumer callback - ams -> ams: Call consumer AMS callback - end - end - return -end - -... - -group Unregister KEY_PHRASE_DETECTED consumer - custom_module -> ams: am_service_unregister_consumer(message_id, callback) - activate ams - ams -> ams_db: Remove KEY_PHRASE_DETECTED message consumer - return -end - -... - -group Unregister KEY_PHRASE_DETECTED producer - kr -> ams: am_service_unregister_producer(message_id) - activate ams - return -end - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_primary_cons_secondary_core.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_primary_cons_secondary_core.pu deleted file mode 100644 index 60b9a7db..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/async_messaging/flow_prod_primary_cons_secondary_core.pu +++ /dev/null @@ -1,153 +0,0 @@ -@startuml - -scale max 1280 width - -box "DSP #0 (primary)" #LightBlue - participant "DSP #0: IXC Service" as ixc_service_dsp_0 - participant "DSP #0: IDC" as idc_dsp_0 - participant "DSP #0: AMS" as ams_dsp_0 - participant "DSP #0: KR" as kr_dsp_0 -end box - -box "DSP #1 (secondary)" #LightGreen - participant "DSP #1: IDC" as idc_dsp_1 - participant "DSP #1: Scheduler" as scheduler_dsp_1 - participant "DSP #1: IDC Task" as idc_dsp_1 - participant "DSP #1: IXC Service" as ixc_service_dsp_1 - participant "DSP #1: AMS" as ams_dsp_1 - participant "DSP #1: Custom module" as custom_module_dsp_1 -end box - -box "Shared SRAM" - participant "AMS database" as ams_db -end box - -... - -group Register KEY_PHRASE_DETECTED producer - group Get Message ID - kr_dsp_0 -> ams_dsp_0: am_service_get_message_type_id(KEY_PHRASE_DETECTED UUID) - activate ams_dsp_0 - ams_dsp_0 -> ams_db: Find ID for KEY_PHRASE_DETECTED message - activate ams_db - alt If no KEY_PHRASE_DETECTED is found - ams_dsp_0 -> ams_db: Assign ID to KEY_PHRASE_DETECTED message - end - return - return - end - - kr_dsp_0 -> ams_dsp_0: am_service_register_producer(message_id) - activate ams_dsp_0 - return -end - -... - -group Register KEY_PHRASE_DETECTED consumer - group Get Message ID - custom_module_dsp_1 -> ams_dsp_1: am_service_get_message_type_id(KEY_PHRASE_DETECTED UUID) - activate ams_dsp_1 - - ams_dsp_0 -> ams_db: Find ID for KEY_PHRASE_DETECTED message - activate ams_db - alt If no KEY_PHRASE_DETECTED is found - ams_dsp_0 -> ams_db: Assign ID to KEY_PHRASE_DETECTED message - end - return - end - - custom_module_dsp_1 -> ams_dsp_1: am_service_register_consumer(message_id) - activate ams_dsp_1 - ams_dsp_1 -> ams_db: Add KEY_PHRASE_DETECTED message consumer - return -end - -... - -group Send Async Message - kr_dsp_0 -> ams_dsp_0: am_service_send_message(message_id, message) - activate ams_dsp_0 - ams_dsp_0 -> ams_db: Get KEY_PHRASE_DETECTED consumers - - note left of ams_db - "External" means the consumers located on the other DSP cores. - "Internal" means the consumers located on the same DSP core. - end note - - loop Until all consumer are called - ams_dsp_0 -> ams_db: Get AMS consumer Processor ID - - alt AMS Consumer Processor ID != Current Processor ID - alt If a first time AMS consumer on this DSP core - alt If it is a first external AMS consumer - loop Until AMS message slot is reserved or limit of tries is reached - ams_dsp_0 -> ams_db: Reserve AMS message slot - end - - ams_dsp_0 -> ams_db: Increment a 'core use count' for AMS slot - ams_dsp_0 -> ams_db: Set MOVEMENT_REPORT message - ams_dsp_0 -> ams_dsp_0: Flush/Invalidate L1 cache - end - - ams_dsp_0 -> ixc_service_dsp_0: Send FORWARD_AMS_MESSAGE(ams_message_slot_id) IDC to the consumer's core - activate ixc_service_dsp_0 - ixc_service_dsp_0 -> idc_dsp_0: IDC Interrupt - activate idc_dsp_0 - idc_dsp_1 -> scheduler_dsp_1: Add/unblock IDC task - return - return - end - else AMS Consumer Processor ID == Current Processor ID - ams_dsp_0 -> ams_db: Get AMS consumer callback - ams_dsp_0 -> ams_dsp_0: Call consumer AMS callback - end - end - return - - ... - - scheduler_dsp_1 -> idc_dsp_1: Execute task - activate idc_dsp_1 - idc_dsp_1 -> ixc_service_dsp_1: Process IDC message - activate ixc_service_dsp_1 - ixc_service_dsp_1 -> ams_dsp_1: FORWARD_AMS_MESSAGE(ams_message_slot_id) - activate ams_dsp_1 - ams_dsp_1 -> ams_db: Get KEY_PHRASE_DETECTED consumers - loop Until all consumer are called - ams_dsp_1 -> ams_db: Get AMS consumer Processor ID - - alt AMS Consumer Processor ID == Current Processor ID - ams_dsp_1 -> ams_db: Get AMS consumer callback - alt If Custom module consumer - ams_dsp_1 -> custom_module_dsp_1: Call AMS Custom module callback - activate custom_module_dsp_1 - return - else - ams_dsp_1 -> ams_dsp_0: Call consumer AMS callback - end - end - end - return - return - return -end - -... - -group Unregister KEY_PHRASE_DETECTED produce - kr_dsp_0 -> ams_dsp_0: am_service_unregister_producer(message_id) - activate ams_dsp_0 - return -end - -... - -group Unregister KEY_PHRASE_DETECTED consumer - custom_module_dsp_1 -> ams_dsp_1: am_service_unregister_consumer(message_id) - activate ams_dsp_1 - ams_dsp_1 -> ams_db: Remove KEY_PHRASE_DETECTED message consumer - return -end - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1.pu deleted file mode 100644 index 969188bb..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_1.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_1.pu deleted file mode 100644 index b8f65e24..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_1.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_2.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_2.pu deleted file mode 100644 index 9b8798ba..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_2.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_3.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_3.pu deleted file mode 100644 index 5dd8d956..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_3.pu +++ /dev/null @@ -1,40 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_4.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_4.pu deleted file mode 100644 index 03ed3355..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_4.pu +++ /dev/null @@ -1,42 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_5.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_5.pu deleted file mode 100644 index 098fb792..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example1_5.pu +++ /dev/null @@ -1,41 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2.pu deleted file mode 100644 index 7677f06d..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1.pu deleted file mode 100644 index 83dfc838..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1.pu +++ /dev/null @@ -1,40 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1a.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1a.pu deleted file mode 100644 index 8e1c2874..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_1a.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2.pu deleted file mode 100644 index 0e7440cf..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2a.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2a.pu deleted file mode 100644 index 20f6e42e..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_2a.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_3.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_3.pu deleted file mode 100644 index a976be4f..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_3.pu +++ /dev/null @@ -1,40 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_4.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_4.pu deleted file mode 100644 index 4e06b3e5..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_4.pu +++ /dev/null @@ -1,40 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_5.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_5.pu deleted file mode 100644 index c1efc9c0..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_5.pu +++ /dev/null @@ -1,40 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_6.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_6.pu deleted file mode 100644 index 7677f06d..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_6.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_7.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_7.pu deleted file mode 100644 index b2a6ca71..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example2_7.pu +++ /dev/null @@ -1,39 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3.pu deleted file mode 100644 index 92dbf045..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_1.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_1.pu deleted file mode 100644 index 0c83890a..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_1.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_2.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_2.pu deleted file mode 100644 index c5e7faba..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_2.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_3.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_3.pu deleted file mode 100644 index 64b7accb..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_3.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_4.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_4.pu deleted file mode 100644 index 858ff446..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_4.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_5.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_5.pu deleted file mode 100644 index d9ccd7e6..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_5.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_6.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_6.pu deleted file mode 100644 index f43be350..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_6.pu +++ /dev/null @@ -1,34 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_7.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_7.pu deleted file mode 100644 index 5591eaae..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example3_7.pu +++ /dev/null @@ -1,40 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4.pu deleted file mode 100644 index dfb6cd24..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4.pu +++ /dev/null @@ -1,38 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_1.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_1.pu deleted file mode 100644 index 627e730b..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_1.pu +++ /dev/null @@ -1,38 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_2.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_2.pu deleted file mode 100644 index 9e5a49b0..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/example4_2.pu +++ /dev/null @@ -1,38 +0,0 @@ -@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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/pic1_chains.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/pic1_chains.pu deleted file mode 100644 index 0dc0256b..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/dp_scheduling/pic1_chains.pu +++ /dev/null @@ -1,16 +0,0 @@ -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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_delete_instance.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_delete_instance.pu deleted file mode 100644 index 6a827e38..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_delete_instance.pu +++ /dev/null @@ -1,56 +0,0 @@ -@startuml - -box "Host" #LightGreen - participant "Driver" as host_driver -end box - -box "SOF" #LightSkyBlue - participant "IPC4 Handler" as ipc4_handler - participant "Component Manager" as component_manager - participant "Library Manager" as library_manager -end box - -box "Zephyr RTOS" #LightBlue - participant "Memory Management Driver" as memory_management_driver -end box - -host_driver -> ipc4_handler: SOF_IPC4_MOD_DELETE_INSTANCE - activate ipc4_handler - ipc4_handler -> component_manager: Free comp_driver - activate component_manager - alt IADK module - component_manager -> library_manager: Deinitialize comp_driver \nwith Processing Module Adapter - activate library_manager - library_manager -> component_manager: return status - deactivate library_manager - else SOF module - component_manager -> library_manager: Deinitialize comp_driver - activate library_manager - library_manager -> component_manager: return status - deactivate library_manager - end alt - component_manager -> library_manager: Free comp_driver resources - activate library_manager - library_manager -> memory_management_driver: Free/Unmap L2 memory for code and rodata - activate memory_management_driver - memory_management_driver -> library_manager - deactivate memory_management_driver - library_manager -> memory_management_driver: Free/Unmap L2 memory for bss - activate memory_management_driver - memory_management_driver -> library_manager - deactivate memory_management_driver - loop Search library for shared module - library_manager -> library_manager: Check if shared module exists and is loaded - library_manager -> memory_management_driver: Free/Unmap L2 memory for shared module - activate memory_management_driver - memory_management_driver -> library_manager - deactivate memory_management_driver - end loop - library_manager -> component_manager: return status - deactivate library_manager - component_manager -> ipc4_handler: return status - deactivate component_manager -ipc4_handler -> host_driver: Complete IPC request -deactivate ipc4_handler - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_init_instance.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_init_instance.pu deleted file mode 100644 index 9b16f5fd..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_init_instance.pu +++ /dev/null @@ -1,65 +0,0 @@ -@startuml - -box "Host" #LightGreen - participant "Driver" as host_driver -end box - -box "SOF" #LightSkyBlue - participant "IPC4 Handler" as ipc4_handler - participant "Component Manager" as component_manager - participant "Library Manager" as library_manager -end box - -box "Zephyr RTOS" #LightBlue - participant "Memory Management Driver" as memory_management_driver -end box - -host_driver -> ipc4_handler: SOF_IPC4_MOD_INIT_INSTANCE - activate ipc4_handler - ipc4_handler -> library_manager: lib_manager_register_module() - activate library_manager - library_manager -> ipc4_handler: return status - deactivate library_manager - ipc4_handler -> component_manager: Create comp_driver - activate component_manager - component_manager -> library_manager: Allocate L2 memory for module - activate library_manager - library_manager -> memory_management_driver: Map L2 memory - deactivate library_manager - activate memory_management_driver - memory_management_driver -> library_manager - deactivate memory_management_driver - activate library_manager - library_manager -> memory_management_driver: Load module code and rodata \nfrom L3 to L2 memory - activate memory_management_driver - memory_management_driver -> library_manager - deactivate memory_management_driver - library_manager -> memory_management_driver: Initialize L2 memory for bss - activate memory_management_driver - memory_management_driver -> library_manager - deactivate memory_management_driver - loop Search library for shared module - library_manager -> library_manager: Check if shared module exists and is not loaded - library_manager -> memory_management_driver: Allocate/Map L2 memory for shared module - activate memory_management_driver - memory_management_driver -> library_manager - deactivate memory_management_driver - library_manager -> memory_management_driver: Load shared module code and rodata \nfrom L3 to L2 memory - activate memory_management_driver - memory_management_driver -> library_manager - deactivate memory_management_driver - end loop - alt IADK module - component_manager -> library_manager: Create/Initialize comp_driver \nwith IADK Module Adapter - library_manager -> component_manager: return status - else SOF module - component_manager -> library_manager: Create/Initialize comp_driver - library_manager -> component_manager: return status - deactivate library_manager - end alt - component_manager -> ipc4_handler: return status - deactivate component_manager -ipc4_handler -> host_driver: Complete IPC request -deactivate ipc4_handler - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_load.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_load.pu deleted file mode 100644 index 714a5de5..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/lib_manager/library_manager_load.pu +++ /dev/null @@ -1,49 +0,0 @@ -@startuml - -box "Host" #LightGreen - participant "Driver" as host_driver -end box - -box "SOF" #LightBlue - participant "IPC4 Handler" as ipc4_handler - participant "Library Manager" as library_manager - participant "MPP Memory Manager" as mpp_memory_manager -end box - -box "ACE Platform" #LightYellow - participant "ROM EXT" as rom_ext -end box - - -host_driver -> ipc4_handler: SOF_IPC4_GLB_LOAD_LIBRARY - activate ipc4_handler - ipc4_handler -> library_manager: lib_manager_load_library() - activate library_manager - library_manager -> library_manager: Parse Manifest \nPrepare Storage Memory - library_manager -> mpp_memory_manager: Allocate L3 memory for library - activate mpp_memory_manager - mpp_memory_manager -> library_manager - deactivate mpp_memory_manager - library_manager -> library_manager: Prepare HDA DMA transfer - host_driver -> library_manager: Transfer library manifest over DMA\nto L3 memory - note right: if SoC does not support L3 memory\nthen L2 memory has to be used - opt if AUTH_API_ENABLED - library_manager -> rom_ext: Verify Manifest - activate rom_ext - rom_ext -> library_manager: result - deactivate rom_ext - end opt - host_driver -> library_manager: Transfer library code over DMA\nto L3 memory - opt if AUTH_API_ENABLED - library_manager -> rom_ext: Verify whole Library - activate rom_ext - rom_ext -> library_manager: result - deactivate rom_ext - end opt - library_manager -> library_manager: Update Library \ndescriptors table - library_manager -> ipc4_handler: return status - deactivate library_manager -ipc4_handler -> host_driver: Complete IPC request -deactivate ipc4_handler - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_layer_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_layer_diagram.pu deleted file mode 100644 index 24f8c175..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_layer_diagram.pu +++ /dev/null @@ -1,55 +0,0 @@ -@startuml - -allowmixing - -scale max 1024 width - -package "SOF" { - - package "Media Processing Pipelines layer" as MEDIA_PROCESSING_PIPELINES { - package "MPP Scheduling" as MPP_SCHEDULING { - component "LL Tasks" as LL_TASKS - component "DP Tasks" as DP_TASKS - - DP_TASKS -[hidden]down- LL_TASKS - } - - package "Communication" as COMMUNICATION { - component "IPC Message Processing and common command definitions" as IPC_MESSAGE_PROCESSING - component "Async Messaging" as ASYNC_MESSAGING - - IPC_MESSAGE_PROCESSING -[hidden]right- ASYNC_MESSAGING - } - - package "Pipeline/Component Infrastructure" as PIPELINE_COMPONENT_INFRASTRUCTURE { - component "Pipeline Management" as PIPELINE_MANAGEMENT - component "Host/DAI Gateways" as HOST_DAI_GATEWAYS - component "Processing Component Management" as PROCESSING_COMPONENT_MANAGEMENT - - PIPELINE_MANAGEMENT -[hidden]right- HOST_DAI_GATEWAYS - HOST_DAI_GATEWAYS -[hidden]right- PROCESSING_COMPONENT_MANAGEMENT - } - - COMMUNICATION -[hidden]down- PIPELINE_COMPONENT_INFRASTRUCTURE - COMMUNICATION -[hidden]right- MPP_SCHEDULING - } - - package "Zephyr" as ZEPHYR { - interface "Zephyr Services, SoC HAL and Driver Interfaces" as SS - - component "SoC HAL" as SOC - component "Drivers" as DRIVERS - component "XTHAL" as XTHAL - component "Services" as SERVICES - - SS -[hidden]down- SERVICES - SERVICES -[hidden]right- SOC - SOC -[hidden]right- DRIVERS - DRIVERS -[hidden]right- XTHAL - } - - MEDIA_PROCESSING_PIPELINES -[hidden]down- ZEPHYR - PIPELINE_COMPONENT_INFRASTRUCTURE -[hidden]down- ZEPHYR -} - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot deleted file mode 100644 index 91447f91..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/edf_scheduling.dot +++ /dev/null @@ -1,23 +0,0 @@ -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/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_DP_secondary_core_timeline.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_DP_secondary_core_timeline.pu deleted file mode 100644 index 2d3e35c9..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_DP_secondary_core_timeline.pu +++ /dev/null @@ -1,136 +0,0 @@ -@startuml - -Title DP tasks scheduling on secondary DSP core - -legend -Assumptions: -1) 1ms scheduling -2) No LL tasks assigned to example secondary DSP core -3) DP Task B do not depend on Task A completion -(otherwise, Task B would start on next timer interrupt after A -completion) -end legend - -scale 1 as 150 pixels - -concise "Task B" as Task_B -concise "Task A" as Task_A - -concise "DP task processing" as DP_Processing -robust "DSP" as DSP -concise "Timer interrupt" as Interrupt - - -@Task_A -0 is Busy -1.5 is {-} - -4 is Busy -5.5 is {-} - -8 is Busy -9.5 is {-} - -@0 <-> @4: Task A schedule period (4ms) -@4 <-> @5.5: Task A execution time (1.5ms) - -DP_Processing@0 -[#Orange]> Task_A@0 -DP_Processing@1 -[#Orange]> Task_A@1 -DP_Processing@1.5 -[#Orange]> Task_A@1.5 - - -@Task_B -0 is Busy -2 is {-} - -6 is Busy -8 is {-} - -@0 <-> @6: Task B schedule period (6ms) -@6 <-> @8: Task B execution time (2ms) - -DP_Processing@1.5 -[#Brown]> Task_B@0 -DP_Processing@2 -[#Brown]> Task_B@0.5 -DP_Processing@3 -[#Brown]> Task_B@1.5 -DP_Processing@3.5 -[#Brown]> Task_B@2 - -DSP is Idle -DP_Processing is {-} - -@0 -DP_Processing is "A" - -@0 -Interrupt -[#DarkViolet]> DSP -DSP -> DP_Processing -DSP is "Scheduling" -DP_Processing is "A" - -@1 -Interrupt -[#DarkViolet]> DSP -DSP -> DP_Processing -DP_Processing is "A" - -@1.5 -DP_Processing -> DSP -DSP -> DP_Processing -DP_Processing is "B" - -@2 -Interrupt -[#DarkViolet]> DSP -DSP -> DP_Processing -DP_Processing is "B" - -@3 -Interrupt -[#DarkViolet]> DSP -DSP -> DP_Processing -DP_Processing is "B" - -@3.5 -DP_Processing -> DSP -DSP is Idle -DP_Processing is {-} - -@4 -Interrupt -[#DarkViolet]> DSP -DSP is "Scheduling" -DSP -> DP_Processing -DP_Processing is "A" - -@5 -Interrupt -[#DarkViolet]> DSP -DSP -> DP_Processing -DP_Processing is "A" - -@5.5 -DP_Processing -> DSP -DSP is Idle -DP_Processing is {-} - -@6.001 -Interrupt -[#DarkViolet]> DSP -DSP -> DP_Processing -DSP is "Scheduling" -DP_Processing is "B" - -@7.001 -Interrupt -[#DarkViolet]> DSP -DSP -> DP_Processing -DP_Processing is "B" - -@8.001 -Interrupt -[#DarkViolet]> DSP -DSP -> DP_Processing -DP_Processing is "A" - -@9.001 -Interrupt -[#DarkViolet]> DSP -DSP -> DP_Processing -DP_Processing is "A" - -@9.5 -DP_Processing -> DSP -DSP is Idle -DP_Processing is {-} - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_LL_DP_timeline.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_LL_DP_timeline.pu deleted file mode 100644 index 74a91cce..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_LL_DP_timeline.pu +++ /dev/null @@ -1,95 +0,0 @@ -@startuml - -Title Task scheduling on DSP core - -legend -Assumptions: -1) 1ms scheduling -2) 0.1ms takes LL task execution -3) 0.5ms takes execution of all DP tasks -end legend - -scale 1 as 200 pixels - -concise "DP Tasks Processing" as DP_Processing -concise "LL Tasks Processing" as LL_Processing -robust "DSP" as DSP -concise "Timer Interrupt" as Interrupt - -DSP is Idle - -@DSP -@1.2 <-> @2: Time available for\nDP tasks execution -@2.2 <-> @2.7: Actual execution time\nof DP tasks -@3 <-> @3.2: Actual execution time\nof LL tasks - -@Interrupt -@0 <-> @1 : Schedule period - -@0 -Interrupt -> DSP -DSP -> LL_Processing -DSP is "Scheduling tasks" -LL_Processing is Busy -DP_Processing is {-} - -@+0.2 -DSP -> DP_Processing -LL_Processing is {-} -DP_Processing is Busy - -@+0.5 -DP_Processing -> DSP -DP_Processing is {-} -DSP is Idle - -@1 -Interrupt -> DSP -DSP -> LL_Processing -DSP is "Scheduling tasks" -LL_Processing is Busy - -@+0.2 -DSP -> DP_Processing -LL_Processing is {-} -DP_Processing is Busy - -@+0.5 -DP_Processing -> DSP -DP_Processing is {-} -DSP is Idle - -@2 -Interrupt -> DSP -DSP -> LL_Processing -DSP is "Scheduling tasks" -LL_Processing is Busy - -@+0.2 -DSP -> DP_Processing -LL_Processing is {-} -DP_Processing is Busy - -@+0.5 -DP_Processing -> DSP -DP_Processing is {-} -DSP is Idle - -@3 -Interrupt -> DSP -DSP -> LL_Processing -DSP is "Scheduling tasks" -LL_Processing is Busy - -@+0.2 -DSP -> DP_Processing - -LL_Processing is {-} -DP_Processing is Busy - -@+0.5 -DP_Processing -> DSP -DP_Processing is {-} -DSP is Idle - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_multiple_cores_timeline.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_multiple_cores_timeline.pu deleted file mode 100644 index 1aa419e7..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_multiple_cores_timeline.pu +++ /dev/null @@ -1,108 +0,0 @@ -@startuml - -Title Tasks scheduling on multiple DSP cores - -legend -Assumptions: -1) 1ms system tick - -Notes: -2) Core #0 has only LL tasks assigned schedule in 1ms period -3) Core #1 has one DP task assigned that is dependent on Core #0 LL tasks data, scheduled in 1ms period -(e.g. multicore pipeline with DP module scheduled on separate core) -4) Core #2 has LL tasks scheduled in 1ms period and DP task scheduled in 2ms period -(e.g. pipeline processing with LL and DP components components where DP component has 2ms scheduling period) -end legend - -scale 1 as 300 pixels - -concise "DSP #2" as DSP_2 -concise "DSP #1" as DSP_1 -concise "DSP #0" as DSP_0 - -concise "Timer interrupt" as Interrupt - -@DSP_0 -0 is "LL proc." -0.5 is {-} - -1 is "LL proc." -1.5 is {-} - -2 is "LL proc." -2.5 is {-} - -3 is "LL proc." -3.5 is {-} - -4 is "LL proc." -4.5 is {-} - -@0 <-> @1: DSP#0 LL schedule period (1ms) - -@DSP_1 -0 is {-} - -1 is "DP proc." -1.6 is {-} - -2 is "DP proc." -2.6 is {-} - -3 is "DP proc." -3.6 is {-} - -4 is "DP proc." -4.6 is {-} -5 is {-} - -@0 <-> @1: delay one period (waiting for first DSP#0 LL data) -@1 <-> @2: DSP#1 DP schedule period (1ms) - -@DSP_2 - -0 is "LL proc." -0.3 is {-} - -1 is "LL proc." -1.3 is {-} - -2 is "LL proc." -2.3 is "DP proc." - -3 is "LL proc." -3.3 is "DP proc." -3.7 is {-} - -4 is "LL proc." -4.3 is "DP proc." - -@0 <-> @1: DSP#2 LL schedule period (1ms) -@2.3 <-> @4.3: DSP#2 DP schedule period (2ms) - -@0 -Interrupt -[#DarkViolet]> DSP_0 -Interrupt -[#DarkViolet]> DSP_1 -Interrupt -[#DarkViolet]> DSP_2 - -@1 -Interrupt -[#DarkViolet]> DSP_0 -Interrupt -[#DarkViolet]> DSP_1 -Interrupt -[#DarkViolet]> DSP_2 - -@2 -Interrupt -[#DarkViolet]> DSP_0 -Interrupt -[#DarkViolet]> DSP_1 -Interrupt -[#DarkViolet]> DSP_2 - -@3 -Interrupt -[#DarkViolet]> DSP_0 -Interrupt -[#DarkViolet]> DSP_1 -Interrupt -[#DarkViolet]> DSP_2 - -@4 -Interrupt -[#DarkViolet]> DSP_0 -Interrupt -[#DarkViolet]> DSP_1 -Interrupt -[#DarkViolet]> DSP_2 - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_task_with_budget.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_task_with_budget.pu deleted file mode 100644 index c4b27de9..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/example_task_with_budget.pu +++ /dev/null @@ -1,50 +0,0 @@ -@startuml - -skinparam maxMessageSize 400 -skinparam BoxPadding 4 - -box "SOF Firmware" #LightBlue - participant "Firmware Manager" - participant "MPP Scheduling" - participant "Zephyr Scheduler" - participant "Zephyr Thread" -end box - -activate "Zephyr Scheduler" - -"Zephyr Scheduler"-> "Zephyr Thread": schedule IPC Task with Budget (TWB) thread\n(MEDIUM_PRIO) -activate "Zephyr Thread" - - "Zephyr Thread"-> "Zephyr Thread": run - "Zephyr Thread"-> "MPP Scheduling": on processing complete - activate "MPP Scheduling" - "MPP Scheduling"-> "Zephyr Thread": k_thread_runtime_stats_get - activate "Zephyr Thread" - return - "MPP Scheduling"-> "MPP Scheduling": update IPC Task with budget\ncycles_consumed_in_sys_tick - return - "Zephyr Thread"-> "Zephyr Thread": suspend TWB Zephyr Thread\n(k_sem_take) -return - -"Zephyr Scheduler"-> "Zephyr Thread": schedule EDF thread\n(LOW_PRIO) -activate "Zephyr Thread" - "Zephyr Thread"-> "Zephyr Thread": run - - activate "Firmware Manager" - "Firmware Manager"-> "Firmware Manager": Host IPC message received - "Firmware Manager"-> "MPP Scheduling": request IPC processing - activate "MPP Scheduling" - "MPP Scheduling"-> "Zephyr Thread": resume IPC TWB Zephyr Thread\n(k_sem_give) - "MPP Scheduling" --> "Firmware Manager" - deactivate "MPP Scheduling" - deactivate "Firmware Manager" - -"Zephyr Thread" --> "Zephyr Scheduler": EDF thread gets preempted -deactivate "Zephyr Thread" - -"Zephyr Scheduler"-> "Zephyr Thread": schedule IPC task with budget thread\n(MEDIUM_PRIO) - activate "Zephyr Thread" - "Zephyr Thread"-> "Zephyr Thread": run - return - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_diagram.pu deleted file mode 100644 index b7e6895a..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_diagram.pu +++ /dev/null @@ -1,60 +0,0 @@ -@startuml -allowmixing - -scale max 1280 width - -package “RTOS layer” { - - package "SOF kernel extension" as KERNEL_EXTENSION { - package "MPP Scheduling" as MPP_SCHEDULING { - component "LL Tasks" as LL_TASKS - component "DP Tasks" as DP_TASKS - component "Tasks with Budget" as TWB - component "Idle Tasks" as IDLE_TASKS - - LL_TASKS -[hidden]right- DP_TASKS - DP_TASKS -[hidden]right- TWB - TWB -[hidden]right- IDLE_TASKS - } - } - - package "Zephyr" as ZEPHYR_LAYER { - package "Services" as SERVICES { - component "Timing" as TIMING - component "Interrupts" as INTERRUPTS - } - - package "Scheduling" as SCHEDULING { - component "Threads" as THREADS - component "EDF Scheduler" as EDF - component "Time-Slice Scheduler" as TIME_SLICE_SCHEDULING - - THREADS -[hidden]right- EDF - EDF -[hidden]right- TIME_SLICE_SCHEDULING - } - - package "Drivers" as DRIVERS { - component "Timer" as TIMER_DRV - component "Watchdog" as WATCHDOG_DRV - } - - package “SoC HAL” as SOC_HAL { - component "OEM SoC 1" as OEM_SOC_1 - component "OEM SoC 2" as OEM_SOC_2 - component "Other SoCs" as OTHER_SOCS - } - - component "XTHAL" as XTHAL - - SERVICES -[hidden]right- SCHEDULING - SERVICES -[hidden]down- XTHAL - SCHEDULING -[hidden]down- SOC_HAL - SCHEDULING -[hidden]down- DRIVERS - DRIVERS -[hidden]right- SOC_HAL - DRIVERS -[hidden]right- XTHAL - } - - KERNEL_EXTENSION -[hidden]down- ZEPHYR_LAYER -} - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_threads_periodic_update.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_threads_periodic_update.pu deleted file mode 100644 index 5eee1041..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_threads_periodic_update.pu +++ /dev/null @@ -1,38 +0,0 @@ -@startuml - -scale max 1280 width - -skinparam maxMessageSize 400 -skinparam BoxPadding 4 - -box "SOF Firmware" #LightBlue - participant "MPP Scheduling" - participant "Zephyr Thread" - participant "Timer" -end box - -"Timer" -> "MPP Scheduling": sys_tick callback -activate "MPP Scheduling" - -loop for each Task with Budget - "MPP Scheduling"-> "MPP Scheduling": reset task with budget\ncycles_consumed_in_sys_tick - "MPP Scheduling" -> "Zephyr Thread": k_thread_priority_set(thread, MEDIUM_PRIO) - "MPP Scheduling" -> "Zephyr Thread": k_thread_time_slice_set(thread, slice_ticks = budget) - note right: Reset priority and budget\nto default value - "MPP Scheduling"-> "Zephyr Thread": k_thread_runtime_stats_get(thread) - activate "Zephyr Thread" - return return thread_cycles - absolute number of cycles consumed - "MPP Scheduling"-> "MPP Scheduling": save thread_ref_cycles = thread_cycles as a reference -end - -loop for each DP task - opt if DP task is ready for processing - "MPP Scheduling"-> "MPP Scheduling": re-calculate task deadline - "MPP Scheduling" -> "Zephyr Thread": k_thread_deadline_set(thread, deadline) - "MPP Scheduling" -> "Zephyr Thread": resume thread - end -end - -deactivate "MPP Scheduling" - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_zephyr.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_zephyr.pu deleted file mode 100644 index 834b28c4..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/images/mpp_scheduling/schedulers_zephyr.pu +++ /dev/null @@ -1,88 +0,0 @@ -@startuml - -scale max 1280 width - -skinparam maxMessageSize 400 -skinparam BoxPadding 4 - -box "SOF" #LightBlue - participant "MPP Scheduling" - participant "Zephyr Scheduler" - participant "Zephyr Thread" - participant "Timer" -end box - -"Timer" -> "MPP Scheduling": sys_tick callback -activate "MPP Scheduling" - loop for each core - "MPP Scheduling"-> "Zephyr Scheduler": resume LL Zephyr Thread\n(k_sem_give) - activate "Zephyr Scheduler" - end - - "MPP Scheduling"-> "MPP Scheduling": DP and Task with Budget\nZephyr Threads update - -"Zephyr Scheduler"-> "Zephyr Thread": schedule LL Zephyr Thread\n(context switch) - deactivate "MPP Scheduling" - activate "Zephyr Thread" - "Zephyr Thread"-> "Zephyr Thread": zephyr_ll_run - activate "Zephyr Thread" - - loop for each LL pending task - note left: LL pending tasks are scheduled operations\nthat are waiting for certain circumstances\n(like data arrival) to start processing - opt if task is ready for processing - "Zephyr Thread"-> "Zephyr Thread": move task \nto LL run queue - end - end - - loop for each task in LL queues - "Zephyr Thread"-> "Zephyr Thread": run LL task callback - end - return - - "Zephyr Thread"-> "Zephyr Thread": suspend LL Zephyr Thread\n(k_sem_take) - return - -loop for each Task With Budget (TwB) Zephyr Thread - "Zephyr Scheduler"-> "Zephyr Thread": schedule TwB Zephyr Thread\n(context switch) - activate "Zephyr Thread" - "Zephyr Thread"-> "Zephyr Thread": run - - alt if time_slice (budget) timeout - "Zephyr Thread"-> "Zephyr Scheduler": time_slice timeout - "Zephyr Scheduler"-> "MPP Scheduling": time_slice callback(thread) - activate "MPP Scheduling" - "MPP Scheduling"-> "Zephyr Thread": k_thread_priority_set(thread, LOW_PRIO) - note right: when budget is consumed\nreset time_slice to default\nand lower priority - "MPP Scheduling"-> "Zephyr Thread": k_thread_time_slice_set(thread, slice_ticks = budget) - deactivate "MPP Scheduling" - - else if processing complete (no time_slice timeout) - "Zephyr Thread"-> "MPP Scheduling": on processing complete (thread) - activate "MPP Scheduling" - "MPP Scheduling"-> "Zephyr Thread": k_thread_runtime_stats_get(thread) - activate "Zephyr Thread" - return return thread_cycles - absolute number of cycles consumed by thread - "MPP Scheduling"->"MPP Scheduling": update thread\ncycles_consumed_in_sys_tick += (thread_cycles - thread_ref_cycles) - note right: thread_ref_cycles is a reference number of cycles consumed by thread\nupdated on each sys_tick start and processing complete - "MPP Scheduling"->"MPP Scheduling": update thread_ref_cycles = thread_cycles - return - deactivate "MPP Scheduling" - - "Zephyr Thread" -> "Zephyr Thread": suspend TwB Zephyr Thread\n(k_sem_take) - note left: TwB Threads are expected to be resumed when there is new data for processing\nfor example IPC TwB Thread will be resumed on IPC interrupt - "Zephyr Thread" --> "Zephyr Scheduler" - deactivate "Zephyr Thread" - end -end - -loop for each DP Zephyr Thread - "Zephyr Scheduler"-> "Zephyr Thread": schedule DP Zephyr Thread with earlieast deadline\n(context switch) - note right: TwB Threads with low priority are treated\nas threads with max deadline and will be\nscheduled after DP threads complete processing - activate "Zephyr Thread" - "Zephyr Thread"-> "Zephyr Thread": run - note right: DP thread runs till completion\nor till earlier deadline or\nhigher priority thread is available - return - deactivate "Zephyr Thread" -end - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/index.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/index.rst deleted file mode 100644 index b8542887..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/index.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. _mpp_layer: - -Media Processing Pipelines Layer -################################ - -The Media Processing Pipelines (MPP) is a FW infrastructure layer independent to -the HW. The MPP components serve as kernel services extension that is available -to the Application layer. - -.. toctree:: - :maxdepth: 1 - - mpp_overview - mpp_scheduling - async_messaging - lib_manager - dp_scheduling \ No newline at end of file diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/lib_manager.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/lib_manager.rst deleted file mode 100644 index 0bb4bccf..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/lib_manager.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. _lib_manager: - -Loadable Library Manager -######################## - -The Loadable Library Manager is a MPP Layer component responsible for loading -and running loadable components provided in external libraries. It supports SOF -native components as well as IADK cAVS/ACE developed modules through -:doc:`../../intel/ace/iadk_modules`. - -Loading an external library is a feature available only for IPC4 protocol with -command: `SOF_IPC4_GLB_LOAD_LIBRARY`. - -.. uml:: images/lib_manager/library_manager_load.pu - :caption: Library Manager: Load library flow - -In the `SOF_IPC4_GLB_LOAD_LIBRARY` IPC flow the ``lib_manager_load_library()`` api -function loads binary from host driver to DSP memory and updates its internal -structure with library descriptor data. If ``AUTH_API`` Kconfig option is -selected, library manager communicates with platform ROM Extension library to -perform library image verification. In that case only trusted libraries will be -successfully loaded. - -**NOTE:** ``AUTH_API`` Kconfig option is available only for Intel platforms. - -During the `SOF_IPC4_MOD_INIT_INSTANCE` IPC4 protocol call, handler searches -for specific module among build-in components and if not found, verifies -manifests of all already loaded external libraries. When module is found in -external library, it is registered in SOF Firmware ``struct comp_driver_list`` -with ``lib_manager_register_module()`` api function and loaded from L3 memory to -L2 memory. Afterwards module is created with standard component device -operation. - -**NOTE:** If L3 memory is not available, the L2 memory has to be used and there -is no memory load operation required. - -.. uml:: images/lib_manager/library_manager_init_instance.pu - :caption: Init instance flow for loadable module - -External libraries could contain not only processing modules but also shared -library code that could be reused across several external modules. The library -manager searches external library manifest for such entities and loads them -together with first processing module loaded. - -When an external processing module is no longer needed, it could be unloaded -with the IPC4 call `SOF_IPC4_MOD_DELETE_INSTANCE`. The command performs reverse -flow to the previous one. It frees L2 SRAM memory allocated for the processing -module and if it is last one unloaded from given library, it frees also -resources used for all shared libraries loaded previously. - -.. uml:: images/lib_manager/library_manager_delete_instance.pu - :caption: Delete instance flow for loadable module - -In `SOF_IPC4_MOD_INIT_INSTANCE` and `SOF_IPC4_MOD_DELETE_INSTANCE` flows, -particular module could be loaded in more than one instance. Its `.text` and -`.rodata` memory sections are allocated only for the first instance and shared -for all other instances. Also the `.text` and `.rodata` resources are released -only for the last instance of given processing module. diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/mpp_overview.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/mpp_overview.rst deleted file mode 100644 index 955a3781..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/mpp_overview.rst +++ /dev/null @@ -1,94 +0,0 @@ -.. _mpp_layer_overview: - -Media Processing Pipelines Overview -################################### - -The Media Processing Pipelines (MPP) layer role is to enable SOF specific use -cases that are not supported directly by Zephyr. The MPP is responsible for host -communication, tasks scheduling, pipeline and component management. - -.. uml:: images/mpp_layer_diagram.pu - :caption: Media Processing Pipelines Layer diagram - -Services in Media Processing Pipelines Layer -******************************************** - -Gateways -======== - -The gateways are a key element in SOF data exchange with host, external audio -peripherals and internally between firmware components. They serve as an -abstraction layer for multiple data protocols. - -The typical audio stream (chain of pipelines) starts and ends with I/O gateway. -I/O gateway represents a sink or a source interface that can be read or written -via DMA operations on I/O FIFO (i.e. DMIC, SNDW, etc.) or directly via memory -operations (i.e. memory buffers of IPC Gateway). Host Gateway is unique as it -exposes interface endpoint to the Host driver. - -The stream audio gateways are created as a part of Copier component -configuration. - -.. TODO: Add link to Copier detailed description - -Examples of gateways: - -- DMIC Gateway, -- SoundWire Gateway, -- I2S Gateway, -- HD/A Gateway, -- IPC Gateway, - -.. TODO: Add link to Gateways detailed specification. - -*NOTE:* Not all I/O gateways must be available in all configurations. - -Pipeline Management -=================== - -The Pipeline Management is a host IPC driven service that is used to: - -- create / delete pipeline -- switch pipeline state -- create pipeline processing tasks -- allocate pipeline buffers memory - -.. TODO: Add link to Pipeline Management IPC interface. - -Processing Component Management -=============================== - -Processing Component Management is driven by host IPC requests. It is used to: - -- instantiate / delete components -- configure components -- bind / unbind components into processing paths -- load components into ADSP memory - -.. TODO: Add link to Component Management IPC interface. - -Asynchronous Messaging -====================== - -Asynchronous Messaging Service (AMS) provides functionality to: - -- send asynchronous messages to firmware components or host, -- broadcast messages to multiple consumers, -- asynchronous message exchange between components running on different cores - -.. TODO: Add link to Asynchronous Messaging Service detailed description - -MPP Scheduling -============== - -MPP Scheduling is dedicated to support Media Processing Pipelines services tasks -scheduling. It exposes SOF specific interface that is implemented on top of -Zephyr scheduling API. - -MPP Scheduling features: - -- Low Latency tasks scheduling, -- Data Processing tasks scheduling, -- Tasks with budget scheduling - -.. TODO: Add link to MPP Scheduling detailed description diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst deleted file mode 100644 index 20b3df84..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/mpp_layer/mpp_scheduling.rst +++ /dev/null @@ -1,302 +0,0 @@ -.. _sof-zephyr_mpp_scheduling: - -MPP Scheduling -############## - -This section describes MPP scheduling flows, task types and their usage in SOF -based on Zephyr API. - -MPP Scheduling defines four task categories: - -- Low Latency audio data processing tasks (LL) - high priority, -- Tasks with Budget (TwB) - medium priority, -- audio Data Processing tasks (DP) - low priority, -- background (idle) priority tasks - -**NOTE:** As of today, only LL tasks has been integrated with Zephyr. TwB, DP -and idle tasks are work in progress (WIP). - -The role of MPP Scheduling is limited to task threads definition, configuration -and state management. The thread scheduling itself is handled by Zephyr. - -MPP Scheduling is designed to: - -- address strict real-time requirements, - - - i.e. to avoid under/overflows on isochronous interfaces such as - I2S, - -- provide predictable latency, -- reduce amount of buffering needed, - -MPP Scheduling defines two tasks categories: - -Task categories characteristic: - -- LL tasks for latency sensitive audio data processing, - - - LL tasks are organized in queues shared between component instances, - - there is one non-preemptive high priority LL Thread assigned to exactly - one core. For example, for HW configuration with 4 cores there will be 4 - LL Threads, - - each queue is statically linked to one LL Thread and all queue tasks will - be processed on a core that LL Thread is assigned to, - - there are multiple queues per LL Thread which represent a priority and - guarantee tasks execution order, - -.. TODO: Add LL tasks, Threads and queues relation diagram, - -- TwB for medium priority processing (e.g., IPC/IDC message handling), - - - each TwB is scheduled as a separate preemptive thread, - - TwB has assigned budget for processing that is refreshed in each sys tick - (`Zephyr Thread time slicing - `__), - - TwB priority is dropped to low when budget is consumed, - -- DP tasks for low priority audio processing, - - - DP tasks are scheduled based on earliest deadline first (EDF) algorithm, - - each DP task is scheduled as a separate preemptive thread, - - DP tasks can be assigned to one of the available cores, - -- idle tasks for background processing, - - - idle tasks are scheduled as separate preemptive threads, - - they have the lowest priority and are scheduled when all other tasks - completed their processing, - - they are used in Fast Mode. For example, in data draining from firmware to - host. - -**NOTE:** Each task is assigned by MPP Scheduling to one core. Tasks are -executed by the assigned core till termination. - -**NOTE:** For Earliest Deadline First (EDF) algorithm description, please refer -to link: -`Wikipedia `__. - -**NOTE:** For Zephyr Scheduling description, please refer to link: -`Zephyr -Scheduling `__. - -.. uml:: images/mpp_scheduling/schedulers_diagram.pu - :caption: SOF MPP Scheduling based on Zephyr - -LL Tasks -******** - -Low Latency Tasks are executed within one of the non-preemptive high priority LL -Threads that runs all ready-to-run tasks till completion during a single cycle. -There is one LL Thread scheduled per core with its own queues and LL tasks to -execute. - -MPP Scheduling adds ready tasks to LL queues at the beginning of each scheduling -period. There are a number of queues to add tasks to. LL Thread iterates over -the queues, and runs all tasks from one queue before moving to the next queue. -Therefore, it is possible to guarantee that some tasks are always run before -others during a cycle. - -There are also two special queues: pre-run queue and post-run queue. Tasks from -pre-run queue are run at the beginning of each cycle (may consider them to have -the highest priority). - -Tasks from post-run queue are run at the end of each cycle (may consider them to -have the lowest priority). - -Example of a pre-run task may be a task registered by the sink driver that -starts the sink at the very beginning of the cycle if data was supplied during -the previous cycles and link has been stopped. - -.. TODO: Evaluate option to add time slice limit for LL thread (set limit it to - 90% to not starve potential IPC communication tasks) - -DP Tasks -******** - -The data processing components are represented as a DP tasks that are scheduled as -separate preemptive threads. DP threads scheduling is done according to EDF -(Earliest Deadline First) algorithm that is part of Zephyr. - -To meet real-time processing criteria algorithm operates by choosing component task -that is closest to its deadline (time when output data is required). - -For playback case algorithm starts from sink and going backward calculates -deadline for data delivery: - - * Time required by component to process data depend on processing period and compute. - * Goal is to process data through chain before real-time sink deadline - -EDF scheduling example - -.. graphviz:: images/mpp_scheduling/edf_scheduling.dot - -The capture pipelines operate in the same way. - -It is important to consider that EDF assumes preemptive scheduling of the DP -Tasks and lack of dependency between them. - -Task With Budget -**************** - -This is a specialized version of DP task that has pre-allocated MCPS budget -renewed with every system tick. When the task is ready to run, then depending on -the budget left in the current system tick, either MEDIUM_PRIORITY or -LOW_PRIORITY is assigned to task thread. The latter allows for opportunistic -execution if there is no other ready task with a higher priority while the -budget is already spent. - -Examples of tasks with budget: Ipc Task, Idc Task. - -Task with Budget (TWB) has two key parameters assigned: - -- *cycles granted*: the budget per system tick, -- *cycles consumed*: number of cycles consumed in a given system_tick - for task execution - -The number of cycles consumed is being reset to 0 at the beginning of each -system_tick, renewing TWB budget. When the number of cycles consumed exceed -cycles granted, the task is switched from MEDIUM to LOW priority. When the task -with budget thread is created the MPP Scheduling is responsible to set thread -time slice equal to task budget along with setting callback on time slice -timeout. Thread time slicing guarantee that Zephyr scheduler will interrupt -execution when the budget is spent, so MPP Scheduling timeout callback can -re-evaluate task priority. - -If there is a budget left in some system tick (task spent less time or started -executing close to the system tick that preempts execution), it is reset and not -carried over to the next tick. - -**NOTE** The Zephyr Scheduler track time slice budget of the TWB when preempted -and log warning if the budget is significantly exceeded (some long critical -section inside the task’s code might be responsible for this). - -**NOTE** The MPP Scheduling must be notified by TWB on processing complete and -update cycles consumed in the current system tick. This allows to schedule TWB -more than once (if necessary) in the single system tick with MEDIUM_PRIORITY. -The second TWB schedule should be done with modified time slice value, equal to -delta between budget and cycles consumed. - -Scheduling flows -**************** - -Zephyr scheduling -================= - -The presented Zephyr scheduling flow takes place on each core that has -MPP tasks scheduled. - -.. uml:: images/mpp_scheduling/schedulers_zephyr.pu - :caption: Zephyr scheduling of MPP threads flow - - -MPP Data Processing and Task with Budget threads periodic update -================================================================ - -Zoom in to Data Processing (Earliest Deadline First) and Task with Budget -Threads periodic update operations on each system tick start. - -.. uml:: images/mpp_scheduling/schedulers_threads_periodic_update.pu - :caption: DP and TWB threads sys tick update flow - - -Task with budget scheduling -=========================== - -.. uml:: images/mpp_scheduling/example_task_with_budget.pu - :caption: Task with budget example scheduling flow - - -Example timeline of MPP Scheduling on a DSP core -================================================= - -The below diagram shows how scheduling looks like on a DSP core. At the timer -interrupt, LL scheduler runs as the first one and then DP scheduler is executed. - -.. uml:: images/mpp_scheduling/example_LL_DP_timeline.pu - :caption: Example timeline of MPP Scheduling on DSP core with LL and DP tasks scheduling - - -Example timeline of DP tasks scheduling on secondary DSP core -============================================================== - -The below diagram shows a detailed example of how DP tasks are scheduled -on the secondary DSP core. - -.. uml:: images/mpp_scheduling/example_DP_secondary_core_timeline.pu - :caption: Example of DP tasks scheduling on secondary DSP core - - -Example timeline of MPP scheduling on multiple DSP cores -======================================================== - -The below diagram shows how scheduling looks like on many DSP cores. The DP task -deadlines are reevaluated on each core in Timer sys tick callback. - -.. uml:: images/mpp_scheduling/example_multiple_cores_timeline.pu - :caption: Example of MPP Scheduling on many cores - LL and DP tasks scheduling - -Fast Mode -********* - -The Fast Mode is used to process data faster than real time. The processing -faster than real time is only needed for a short time period and it happens i.e. -when firmware performs low power Wake on Voice. In such case SOF firmware is -working in low power mode, performing i.e. key phrase detection algorithm, -accumulating last few seconds of audio samples in history buffer. When a key -phrase detection happens, there is a need to stream the accumulated history to -Host as quickly as possible with optional additional processing on DSP. It is -only possible when a sink interface to Host transfer burst of data from DSP. - -The Fast Mode is an idle low priority task. The task is only executed when other -DP tasks with deadlines has completed their processing and there is still enough -DSP cycles before a next system tick. - -When the Fast Mode task is created by i.e. History Buffer, the component -instance (i.e. History Buffer) needs to provide a list of LL component instances -that will be executed within a Fast Mode thread, similar as it is done with LL -tasks queues and LL Thread. When the Fast Mode thread is executed it will -trigger processing of LL components in similar way as LL Thread does. The Fast -Mode task is executed in the critical section. It will check if there is data -available in an input queue and there is enough space in an output queue. Only -then it will execute a LL component. What is important to note is that the Fast -Mode task does not call processing on the DP components directly. - -As described in the previous sections, the processing on DP components is called -according to EDF algorithm. A periodicity of a component processing is -determined by time needed to fill an input queue using real time source of data. -When an input queue has sufficient amount of data, the processing on DP -component can be called. The input queues for DP components that are on the Fast -Mode task path will be filling much faster than real time as the side effect of -the Fast Mode task execution - LL components will move data to DP component -input queue and out of DP component output queue. As the result, DP component -can be executed much earlier than real time - a DSP task reports “ready to run” -as soon as it has sufficient amount of data in input queue and output queue has -enough space for produced frame. That can lead to starvation of other tasks and -to prevent it a Fast Mode tasks must be scheduled as idle tasks in background. - -Watchdog timer -************** - -Depending on HW configuration there can be a single watchdog timer, watchdog -available for each DSP core or none. - -All DSP cores shall enable watchdog when they are active to monitor health of -subsystem. When one of watchdogs will expire, the entire subsystem will be reset -by Host. - -Watchdog shall be enabled when: - -- DSP core is enabled, -- tasks are assigned to DSP core, - -Watchdog shall be disabled when: - -- DSP core is disabled, -- no tasks are assigned to DSP core, -- DSP core goes to low power state, - -Watchdog timer shall be programmed to value of a few scheduling periods. - -Watchdog timer when enabled shall be updated at every system tick. In case of -primary DSP core, it should be after running LL tasks. In case of secondary HP -DSP cores, it should be on system tick end. \ No newline at end of file diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/overview.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/overview.rst deleted file mode 100644 index e9969e29..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/overview.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _sof-zephyr-overview: - -Overview -######## - -New SOF firmware architecture is based on Zephyr RTOS and introduce new IPC4 -Host protocol ABI. In result FW has been re-organized into layers. The -interaction between the components across the layers is limited to the -internally defined interfaces. - -.. uml:: images/overview_diagram.pu - :caption: SOF with Zephyr Architecture overview diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/kernel_services.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/kernel_services.pu deleted file mode 100644 index f1d19987..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/kernel_services.pu +++ /dev/null @@ -1,57 +0,0 @@ -@startuml -allowmixing - -scale max 1280 width - -package "SOF" { - package "Kernel Infrastructure" { - interface "Zephyr System Services" as SS - - package "Services" { - component "Memory Manager" as MEMORY_MANAGER - component "Power Manager" as POWER_MANAGER - component "IPC/IDC" as IXC - component "Logging" as LOGGING - component "Debug" as DEBUG - component "Interrupt Handler" as INTERRUPT_HANDLER - } - - SS .down. MEMORY_MANAGER - SS .down. POWER_MANAGER - SS .down. IXC - SS .down. LOGGING - SS .down. DEBUG - SS .down. INTERRUPT_HANDLER - } - - package "Kernel Extension" { - interface "Extended System Services" as ESS - - component "AVS Scheduling" as AVS_Scheduling - - package "Extended Services" as EXTENDED_SERVICES { - component "Firmware Manager" as FIRMWARE_MANAGEMENT - component "Pipeline Management" as PIPELINE_MANAGEMENT - component "Async Messaging" as ASYNC_MESSAGING - component "Processing Component Management" as COMPONENT_MANAGEMENT - component "IPC Message Processing" as IPC_MESSAGE_PROCESSING - } - - ESS .down. FIRMWARE_MANAGEMENT - ESS .down. PIPELINE_MANAGEMENT - ESS .down. ASYNC_MESSAGING - ESS .down. IPC_MESSAGE_PROCESSING - ESS .down. COMPONENT_MANAGEMENT - - AVS_Scheduling -[hidden]down- EXTENDED_SERVICES - } - - package "Loadable modules" { - component "WoV" as WOV - - WOV .down. SS - WOV .down. ESS - } -} - -@enduml \ No newline at end of file diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/dsp_fw_power_states.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/dsp_fw_power_states.pu deleted file mode 100644 index c864c743..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/dsp_fw_power_states.pu +++ /dev/null @@ -1,14 +0,0 @@ -@startuml -hide empty description - -state "D0 / D0ix" as D0 { - [*] --> PM_STATE_ACTIVE: Initialization - PM_STATE_ACTIVE -> PM_STATE_RUNTIME_IDLE - PM_STATE_RUNTIME_IDLE -> PM_STATE_ACTIVE - PM_STATE_ACTIVE --> [*] -} - -[*] --> D0: Go to D0 / Power DSP on -D0 --> [*]: Go to D3 / Power DSP Off - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/dx_state_transitions.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/dx_state_transitions.pu deleted file mode 100644 index 1a1870b2..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/dx_state_transitions.pu +++ /dev/null @@ -1,10 +0,0 @@ -@startuml - -[*] --> D3 -D3 --> D0 -D0 --> D0ix: SET_D0ix(wake = 0) -D0ix --> D0: SET_D0ix(wake = 1) -D0ix --> D3: ENTER_DX_STATE -D0 --> D3: ENTER_DX_STATE - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_disable_d0i3.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_disable_d0i3.pu deleted file mode 100644 index 9279b09d..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_disable_d0i3.pu +++ /dev/null @@ -1,19 +0,0 @@ -@startuml - -box "Host" #LightSkyBlue - participant "Driver" as DRIVER -end box - -box "SOF" #LightBlue - participant "Core #0: Zephyr lib" as sof_zephyr_lib - participant "Zephyr Power Manager" as zephyr_power_manager -end box - -DRIVER -> sof_zephyr_lib: SET_D0ix(prevent_power_gating = 1) IPC request -activate sof_zephyr_lib - sof_zephyr_lib -> zephyr_power_manager: pm_policy_state_lock_get\n(PM_STATE_RUNTIME_IDLE) - activate zephyr_power_manager - return -return SET_D0ix IPC response - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_dsp_idle.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_dsp_idle.pu deleted file mode 100644 index 123751e5..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_dsp_idle.pu +++ /dev/null @@ -1,41 +0,0 @@ -@startuml - -box "SOF" #LightBlue - participant "Core #N: Zephyr lib" as sof_zephyr_lib - participant "Zephyr Power Manager" as zephyr_power_manager - participant "Zephyr SoC HAL" as soc_hal -end box - -box "Hardware" #LightGreen - participant "Core #N: Control" as core_hw_control -end box - -opt When Core is Idle - - zephyr_power_manager -> sof_zephyr_lib: pm_policy_next_state (PID: Core #N, ticks) - activate sof_zephyr_lib - activate zephyr_power_manager - sof_zephyr_lib -> zephyr_power_manager: pm_policy_state_lock_get\n(PM_STATE_RUNTIME_IDLE) - activate zephyr_power_manager - return - alt if no lock on D0ix state - return PM_STATE_RUNTIME_IDLE - else if there is lock on D0ix state - return PM_STATE_ACTIVE - end - - zephyr_power_manager -> soc_hal: pm_power_state_set\n(power_state, PID: Core #N) - activate soc_hal - alt If power_state is PM_STATE_IDLE - soc_hal -> soc_hal: arch_clear_power_gating_prevent (Core #N) - soc_hal -> core_hw_control: Clear power gating prevent - else if PM_STATE_RUNTIME_ACTIVE - soc_hal -> soc_hal: arch_set_power_gating_prevent (Core #N) - soc_hal -> core_hw_control: Set power gating prevent - end - return - - deactivate zephyr_power_manager -end - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_enable_d0i3.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_enable_d0i3.pu deleted file mode 100644 index 70b3ea8b..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_enable_d0i3.pu +++ /dev/null @@ -1,29 +0,0 @@ -@startuml - -box "Host" #LightSkyBlue - participant "driver" as driver -end box - -box "SOF" #LightBlue - participant "Core #0: Zephyr lib" as sof_zephyr_lib - participant "Zephyr Power Manager" as zephyr_power_manager -end box - -driver -> sof_zephyr_lib: SET_D0ix(prevent_power_gating = 0) IPC request -activate sof_zephyr_lib - sof_zephyr_lib -> zephyr_power_manager: pm_policy_state_lock_put\n(PM_STATE_RUNTIME_IDLE) - activate zephyr_power_manager - return - sof_zephyr_lib -> zephyr_power_manager: pm_policy_state_lock_is_active\n(PM_STATE_RUNTIME_IDLE) - activate zephyr_power_manager - return - - alt if D0ix is still locked - sof_zephyr_lib --> driver: return ERROR - note right: Zephyr PM Policy can be used concurrently\nand there can be more then one lock\non D0ix state - else - sof_zephyr_lib --> driver: return SUCCESS - end - - deactivate sof_zephyr_lib -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_primary_core_power_down.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_primary_core_power_down.pu deleted file mode 100644 index c904de25..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_primary_core_power_down.pu +++ /dev/null @@ -1,56 +0,0 @@ -@startuml - -scale max 1280 width - -box "Host" #LightSkyBlue - participant "driver" as driver -end box - -box "SOF" #LightBlue - participant "Core #0: Zephyr lib" as sof_zephyr_lib_0 - participant "Zephyr Power Manager" as zephyr_power_manager - participant "Zephyr SoC HAL" as soc_hal -end box - -box "Hardware" #LightGreen - participant "Core #0: Control" as core_hw_control -end box - -opt If D0ix is enabled - driver -> sof_zephyr_lib_0: SET_D0ix(prevent D0ix) IPC request - activate sof_zephyr_lib_0 - sof_zephyr_lib_0 -> zephyr_power_manager: pm_policy_state_lock_get\n(PM_STATE_RUNTIME_IDLE) - activate zephyr_power_manager - return - return -end - -== DSP FW in PM_STATE_ACTIVE == - -driver -> sof_zephyr_lib_0: SET_DX(PID: Core #0, D3) IPC request -activate sof_zephyr_lib_0 - sof_zephyr_lib_0 -> zephyr_power_manager: Read status of secondary cores - activate zephyr_power_manager - return - - alt If any secondary core is powered up - sof_zephyr_lib_0 --> driver: SET_DX(ERROR) IPC response - else else - sof_zephyr_lib_0 -> zephyr_power_manager: pm_power_state_force\n(PM_STATE_SOFT_OFF, PID: Core #0) - activate zephyr_power_manager - zephyr_power_manager -> soc_hal: pm_power_state_set\n(PM_STATE_SOFT_OFF, PID: Core #0) - activate soc_hal - soc_hal -> soc_hal: Save context - soc_hal -> soc_hal: Prepare restore vector - return - return - -return SET_DX(SUCCESS) IPC response -end - -driver -> core_hw_control: clear power register -loop Until Core #0 power is down - driver -> core_hw_control: Read Core #0 power bit -end - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_boot.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_boot.pu deleted file mode 100644 index dc8704e9..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_boot.pu +++ /dev/null @@ -1,48 +0,0 @@ -@startuml - -box "Host" #LightSkyBlue - participant "driver" as driver -end box - -box "SOF" #LightBlue - participant "Core #0: Zephyr lib" as sof_zephyr_lib_0 - participant "Core #1: FW Init" as fw_init_1 - participant "Zephyr Power Manager" as zephyr_power_manager - participant "Zephyr SoC HAL" as soc_hal -end box - -box "Hardware" #LightGreen - participant "Core #1: Control" as core_control_1 -end box - -opt If D0ix is enabled - driver -> sof_zephyr_lib_0: SET_D0ix(prevent D0/D0ix) IPC request - activate sof_zephyr_lib_0 - sof_zephyr_lib_0 -> zephyr_power_manager: pm_policy_state_lock_get\n(PM_STATE_RUNTIME_IDLE) - activate zephyr_power_manager - return - return -end - -== DSP FW in PM_STATE_ACTIVE == - -driver -> sof_zephyr_lib_0: SET_DX(PID: Core #1, D0) IPC request -activate sof_zephyr_lib_0 - sof_zephyr_lib_0 -> soc_hal: arch_start_cpu(PID: Core #1) - activate soc_hal - soc_hal -> core_control_1: Set alternate boot vector to FW Init - note right: Cores share the \nsame FW binary\nand the firmware must be\npresent in SRAM. - soc_hal -> core_control_1: Set SPA bit - - core_control_1 -> fw_init_1: Start and jump to alternate boot vector - activate fw_init_1 - fw_init_1 -> fw_init_1: Restore context\nif any saved - - loop Until Core #1 is enabled - soc_hal -> core_control_1: read power register - end - deactivate fw_init_1 - return -return - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_power_down.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_power_down.pu deleted file mode 100644 index 05d6c6c8..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/flow_secondary_core_power_down.pu +++ /dev/null @@ -1,56 +0,0 @@ -@startuml - -scale max 1280 width - -box "Host" #LightSkyBlue - participant "driver" as driver -end box - -box "SOF" #LightBlue - participant "Core #0: Zephyr lib" as sof_zephyr_lib_0 - participant "Zephyr Power Manager" as zephyr_power_manager - participant "Zephyr SoC HAL" as soc_hal -end box - -box "Hardware" #LightGreen - participant "Core #1: Control" as core_1_control -end box - -opt If D0ix is enabled - driver -> sof_zephyr_lib_0: SET_D0ix(prevent D0ix) IPC request - activate sof_zephyr_lib_0 - sof_zephyr_lib_0 -> zephyr_power_manager: pm_policy_state_lock_get\n(PM_STATE_RUNTIME_IDLE) - activate zephyr_power_manager - return - return -end - -== DSP FW in PM_STATE_ACTIVE == - -driver -> sof_zephyr_lib_0: SET_DX(PID: Core #1, D3) IPC request -activate sof_zephyr_lib_0 - sof_zephyr_lib_0 -> zephyr_power_manager: pm_power_state_force\n(PM_STATE_SOFT_OFF, PID: Core #1) - activate zephyr_power_manager - zephyr_power_manager -> soc_hal: pm_power_state_set\n(PM_STATE_SOFT_OFF, PID: Core #1) - activate soc_hal - soc_hal -> soc_hal: Save context to IMR - return - deactivate zephyr_power_manager - - loop Until Core #1 transition to PM_STATE_SOFT_OFF - sof_zephyr_lib_0 -> zephyr_power_manager: pm_power_state_get(PID: Core #1) - activate zephyr_power_manager - return - end - - sof_zephyr_lib_0 -> soc_hal: arch_stop_cpu(PID: Core #1) - activate soc_hal - soc_hal -> core_1_control: clear power bit - loop Until Core #1 is disabled - soc_hal -> core_1_control: read power register - end - return - -return SET_DX(SUCCESS) IPC response - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/power_components.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/power_components.pu deleted file mode 100644 index f111ae24..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/power/power_components.pu +++ /dev/null @@ -1,30 +0,0 @@ -node sw_driver [ - SW Driver - * DSP power control over IPC protocol -] - -node fw [ - SOF Zephyr Library - - * Exposes interface of SOF with XTOS for Host Power IPC handling - * Executes requested sequence of Zephyr power operations - * Waits and verifies power request completion - - --- - Zephyr Power Management - Generic RTOS Power Management service - - * Manages System Power States - * Manages Power Policies - * Manages Device Runtime Power - - --- - SoC HAL - Hardware specific power control - - * Moves SoC and its resources to power state requested by Zephyr - * Interacts directly with hardware and power registers - * Suppors different power states depending on the target SoC -] - -sw_driver -down-> fw : <> Set Dx - power state transition D0/D3\n<> Set D0ix - power gating override (on/off) diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/zephyr_kernel_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/zephyr_kernel_diagram.pu deleted file mode 100644 index f7bf622a..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/images/zephyr_kernel_diagram.pu +++ /dev/null @@ -1,124 +0,0 @@ -@startuml -allowmixing - -scale max 1280 width - -package "Kernel space" { - - package "Media Processing Pipelines - kernel extension" as MPP_KERNEL_EXTENSION { - interface "Extended System Services" as ESS - - component "Firmware Manager" as FIRMWARE_MANAGER - - package "Communication" as COMMUNICATION { - component "IPC Message Processing" as IPC_MESSAGE_PROCESSING - component "Async Messaging" as ASYNC_MESSAGING - - IPC_MESSAGE_PROCESSING -[hidden]right- ASYNC_MESSAGING - } - - package "Pipeline/Component Infrastructure" as PIPELINE_COMPONENT_INFRASTRUCTURE { - component "Pipeline Management" as PIPELINE_MANAGEMENT - component "Host/DAI Gateways" as HOST_DAI_GATEWAYS - component "Processing Component Management" as PROCESSING_COMPONENT_MANAGEMENT - - PIPELINE_MANAGEMENT -[hidden]right- HOST_DAI_GATEWAYS - HOST_DAI_GATEWAYS -[hidden]right- PROCESSING_COMPONENT_MANAGEMENT - } - - package "AVS Scheduling" as AVS_SCHEDULING { - component "Data Processing (DP) Tasks (EDF based)" as DP_TASKS - component "Low Latency (LL) Tasks" as LL_TASKS - - DP_TASKS -[hidden]right- LL_TASKS - } - - FIRMWARE_MANAGER -[hidden]right- PIPELINE_COMPONENT_INFRASTRUCTURE - FIRMWARE_MANAGER -[hidden]down- COMMUNICATION - COMMUNICATION -[hidden]right- AVS_SCHEDULING - - ESS -[hidden]down- FIRMWARE_MANAGER - ESS -[hidden]down- PIPELINE_COMPONENT_INFRASTRUCTURE - } - - package "Zephyr" as Zephyr_RTOS { - interface "Zephyr System Services" as SS - - package "Schedulers" as SCHEDULERS { - component "RTOS Scheduling" as RTOS_SCHEDULER - } - - package "Services" as SERVICES { - component "Memory Manager" as MEMORY_MANAGER - component "Power Manager" as POWER_MANAGER - component "IPC/IDC" as IXC - component "Logging" as LOGGING - component "Debug" as DEBUG - component "Timer Manager" as TIMER_MANAGER - component "Interrupt Handler" as INTERRUPT_HANDLER - - MEMORY_MANAGER -[hidden]right- POWER_MANAGER - POWER_MANAGER -[hidden]right- IXC - IXC -[hidden]down- LOGGING - LOGGING -[hidden]right- TIMER_MANAGER - TIMER_MANAGER -[hidden]right- INTERRUPT_HANDLER - } - - package "SoC HAL" as SOC { - component "OEM SoC 1" as SOC_1 - component "OEM SoC 2" as SOC_2 - component "Other SoCs" as OTHER_SOCS - - SOC_1 -[hidden]right- SOC_2 - SOC_2 -[hidden]right- OTHER_SOCS - } - - package "Drivers" as DRIVERS { - package "Common Drivers" as COMMON_DRIVERS { - component "GPDMA" as GPDMA - component "Timer" as TIMER - component "SHA-384" as SHA384 - component "Watchdog" as WATCHDOG - component "IPC" as IPC - component "IDC" as IDC - } - - package "Audio Drivers" as AUDIO_DRIVERS{ - component "DMIC" as DMIC - component "I2S" as I2S - component "SDW" as SDW - component "HDA" as HDA - - DMIC -[hidden]right- I2S - I2S -[hidden]right- SDW - SDW -[hidden]right- HDA - } - - package "Sensing Drivers" as SENSING_DRIVERS { - component "I2C" as I2C - component "GPIO" as GPIO - component "I3C" as I3C - component "SPI" as SPI - component "UART" as UART - - I2C -[hidden]right- GPIO - GPIO -[hidden]right- I3C - I3C -[hidden]right- SPI - SPI -[hidden]right- UART - } - } - - component "XTHAL" as XTHAL - - SS -[hidden]down- SCHEDULERS - SS -[hidden]down- SERVICES - SCHEDULERS -[hidden]right- SERVICES - SERVICES -[hidden]right- SOC - SERVICES --[hidden]down-- DRIVERS - DRIVERS -[hidden]down- XTHAL - } - - MPP_KERNEL_EXTENSION --[hidden]down-- Zephyr_RTOS -} - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/index.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/index.rst deleted file mode 100644 index 204b057a..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _rtos_layer: - -RTOS Layer Infrastructure -######################### - -The RTOS layer is based on Zephyr that provide generic and scalable open source -solution with options for SW partitioning of product subsystems to run audio -workloads. - -.. toctree:: - :maxdepth: 1 - - zephyr_kernel_overview - memory_management/index - power_management - io_drivers/index diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/dmic_driver.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/dmic_driver.rst deleted file mode 100644 index 6da57691..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/dmic_driver.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _dmic_driver: - -DMIC IO Driver -############## - -.. uml:: images/dmic_diagram.pu - :caption: DMIC IO Driver overview - -Gateway Initialization -********************** - -.. uml:: images/dmic_gateway_init.pu - :caption: DMIC Input Gateway Initialization - -DMIC HW is initialized as follows: - - 1. Mute microphones. - 2. Enable clock on microphones (also enable CIC and FIRs). - 3. Wait for clock stabilization (SoC defined delay). - 4. Unmute microphones using a curved ramp until the DC offset is gone and - replaced with the live stream. - -Configuration BLOB -****************** - -DMIC IO Driver is prepared for the configuration BLOB to come in context of any -instance of the DmicInput at any time. The configuration may be rejected if the -current state of PDM controllers and FIFOs is inappropriate. Accepting the -configuration does not always mean that it is immediately programmed to the HW. -The configuration is global, so when sent by an instance of DmicInput while -another instance is already running it is just compared with already programmed -data for the sake of consistency. - -Gateway Release -*************** - -.. uml:: images/dmic_gateway_release.pu - :caption: DMIC Input Gateway Release - -State Transitions -***************** - -.. uml:: images/dmic_gateway_state_transitions.pu - :caption: DMIC Input Gateway State Transition diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_diagram.pu deleted file mode 100644 index 6dc94a0c..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_diagram.pu +++ /dev/null @@ -1,30 +0,0 @@ -@startuml - -hide methods -hide attributes - -component Zephyr { - class DmicDriver - interface dai_dmic_ops - interface dai_driver_api -} - -component MPP { - interface Gateway - - interface IoDriver - class DmicManager - class DmicInput -} - -DmicDriver -up- dai_dmic_ops - -dai_dmic_ops -left-|> dai_driver_api : implements - -DmicManager -up- IoDriver -DmicManager -left-> DmicInput : manages -DmicInput -up- Gateway -DmicInput -down-> dai_dmic_ops : calls -DmicDriver --* DmicInput - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_init.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_init.pu deleted file mode 100644 index f8a938f4..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_init.pu +++ /dev/null @@ -1,23 +0,0 @@ -@startuml - -participant "DMIC Manager" as dmic_manager -participant "Zephyr PM Subsystem" as zephyr_pm -participant "DMIC Driver" as dmic_driver - --> dmic_manager : gateway_allocate() - activate dmic_manager - dmic_manager -> zephyr_pm : pm_runtime_device_get (dmic) - - activate zephyr_pm - zephyr_pm -> zephyr_pm : increase usage count - opt if usage == 1 - zephyr_pm -> dmic_driver : pm_device_resume - activate dmic_driver - return - end - return - - deactivate dmic_manager -<-- dmic_manager - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_release.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_release.pu deleted file mode 100644 index 9afebab9..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_release.pu +++ /dev/null @@ -1,23 +0,0 @@ -@startuml - -participant "DMIC Manager" as dmic_manager -participant "Zephyr PM Subsystem" as zephyr_pm -participant "DMIC Driver" as dmic_driver - --> dmic_manager : gateway_release() - activate dmic_manager - dmic_manager -> zephyr_pm : pm_runtime_device_put (dmic) - - activate zephyr_pm - zephyr_pm -> zephyr_pm : decrease usage count - opt if usage == 0 - zephyr_pm -> dmic_driver : pm_device_suspend - activate dmic_driver - return - end - return - - deactivate dmic_manager -<-- dmic_manager - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_state_transitions.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_state_transitions.pu deleted file mode 100644 index ee592ed6..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/dmic/images/dmic_gateway_state_transitions.pu +++ /dev/null @@ -1,19 +0,0 @@ - -participant "Dmic Input\nGateway" as dmic_input -participant "DMA" as dma - -== Dmic Input : STOPPED == - --> dmic_input : STOPPED - dmic_input -> dma : stop() - -== Dmic Input : PAUSED == - --> dmic_input : PAUSED - dmic_input -> dma : init_transfer() - dmic_input -> dma : pause() - -== Dmic Input : RUNNING == - --> dmic_input : RUNNING - dmic_input -> dma : start() diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/hda_driver.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/hda_driver.rst deleted file mode 100644 index 3165775c..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/hda_driver.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. _hda_driver: - -HD-A IO Driver -############## - -.. uml:: images/hda_io_driver_deps.pu - :caption: HD-A IO Driver overview - -HD-A Gateways -************* - -Gateway Node Addressing -======================= - -There are four types of HD-A gateways. Note that the naming convention -(inherited from c-spec) names the data flow direction based on the external -entity's perspective. Therefore, "output" means that data comes to FW from the -external source and "input" means that data is sent from FW to the external -sink. - -.. uml:: images/hda_playback.pu - :caption: HD-A Playback - -.. uml:: images/hda_capture.pu - :caption: HD-A Capture - -HD-A Gateway types: - - HDA-A DMA Source, - - - DMA Host Output, - - DMA Link Input, - - - HDA-A DMA Sink, - - - DMA Host Input, - - DMA Link Output - -HD-A to HDMI -============ - -There following options are available: - - 1. Legacy HD/A (not recommended), - 2. HW chaining in the DSP (depends on HW support), - 3. SW chaining in the DSP (recommended), - 4. Full Copier-...-Copier pipeline (more resources required). - -The most resource-efficient way to do a simple HD/A to HD/A playback via the DSP -is to use the "DMA Chaining" feature. FW provides an IPC command to connect two -HD/A gateways with a simple data copier task running in the LL domain. diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_capture.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_capture.pu deleted file mode 100644 index 37e6a371..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_capture.pu +++ /dev/null @@ -1,15 +0,0 @@ -@startuml - -component "host capture" as hc - -package FW { - component "Host Input" as hi - component "Link Output" as lo -} - -component "link capture" as lc -hc <- hi -hi <- lo -lo <- lc - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_io_driver_deps.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_io_driver_deps.pu deleted file mode 100644 index 8cfdd590..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_io_driver_deps.pu +++ /dev/null @@ -1,12 +0,0 @@ - -@startuml -allowmixing - -component "hd-a io driver" as io_drv -component "hd-a gateway" as gateway -component "hd-a dma" as dma - -io_drv -right-> gateway : provides -gateway -down-> dma : use - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_playback.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_playback.pu deleted file mode 100644 index 7988d2b3..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/hda/images/hda_playback.pu +++ /dev/null @@ -1,15 +0,0 @@ -@startuml - -component "host playback" as hp - -package FW { - component "Host Output" as ho - component "Link Input" as li -} - -component "link playback" as lp -hp -> ho -ho -> li -li -> lp - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst deleted file mode 100644 index ef17ecae..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/i2s_driver.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. _i2s_driver: - -I2S IO Driver -############# - -.. uml:: images/i2s_diagram.pu - :caption: I2S IO Driver overview - -Configuration BLOB -****************** - -The Configuration Blob is a build of block structures: - - TDM slot Map, - - I2S base registers, - - MCLK configuration that allows for specifying the ratio for multiple - dividers, - - Aggregation configuration - -The ``I2sConfigurationBlobHeader`` begins with a signature followed by the BLOB -version and size. - -.. code-block:: text - - I2sConfigurationBlobHeader - { - signature and version { 0xEE, BLOB version } - size in bytes - } - -Blob Configuration structure that follows the header depends on the BLOB version. -Currently, only v2.5 is supported with the structure as follows: - -.. code-block:: text - - I2sConfigurationBlob2 - { - I2sConfigurationBlobHeader - TDM slot map ver.2 [I2S_TDM_MAX_SLOT_MAP_COUNT] - I2S base registers - MCLK configuration ver.2 - { - 2.5: Aggregation configuration - } - } - -TDM Time Slots -============== - -TDM time slots are statically assigned to streams by definition coming from -ACPI. A single stream transmits data through time slots of a single time slot -group. For example, 8 TDM time slots may be grouped by the following definition -from ACPI: - -.. code-block:: text - - tsd[0] = 0xFFFFFF43, tsd[1] = 0xFFFFFF01, ... - -where: - - Stream 0 specifies time_slot_group_index = 1, - - Stream 1 uses time_slot_group_index = 0 - -that would mean that the 1st TDM slot is mapped to S0 Ch0; the 0th TDM slot is -mapped to S0 Ch1; the 3rd TDM slot is mapped to S1 Ch0, and 4th TDM slot is -mapped to S1 Ch1. - -.. graphviz:: images/i2s_tdm.dot - :caption: I2S TDM - -Configuring BCLK Clock Input Source -=================================== - -The I2S Link BCLK may be configured to use on the SoC available clock sources. - -Example BCLK clock sources: - - - XTAL Oscillator clock, - - Audio Cardinal clock, - - Audio PLL fixed clock, - - MCLK - -Clock selection is programmed using values provided in the I2S Configuration -BLOB for the MCDSS and MNDSS fields of the MDIVCTRL register. - -Link Synchronization (and Aggregation) -====================================== - -Applies to sync of the streams started together as well as to synchronizing new -stream with already running ones. - -.. note:: The same configuration must be set to all involved I2S ports. Specifically, - all the ports must be driven by the same clock source. Moreover, there might - be clock source SoC limitations. For example, in the TGL the M/N divider has - to be selected for aggregation case. - -.. list-table:: - :widths: 25 25 50 - :header-rows: 1 - - * - Synchronized - - Provider Mode - - Consumer Mode - * - Stream start - - Yes - - Yes - * - BCLK, SFRM - - Yes - - By hooking up to the same I2S provider - -"Single" I2S links may be synchronized and aggregated by sending I2sSyncData to -the I2S IO Driver. - -Loopback mode -====================================== - -The I2S transmitter and receiver share data pins at the IP level. The Tx pin of the transmitter -is connected to the Rx pin of the receiver. This may be used for easy creation of digital -loopbacks (LBM, loopback mode) - the receiver always does see what the sender is sending. - -Please note the following: - - - all the parameters of transmitter and receiver, like number of channels, data rates, and format must match each other - - the lines are connected internally, so LBM mode may be used even if the I2S pins are not physically available - diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_diagram.pu deleted file mode 100644 index d49b4d50..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_diagram.pu +++ /dev/null @@ -1,18 +0,0 @@ -@startuml - -hide methods -hide attributes - -class I2sSink --() Gateway -class I2sSource --() Gateway -class I2sDriver --() IoDriver -class I2sChannel -class I2sInputChannel - -I2sChannel --* I2sDriver -I2sInputChannel --|> I2sChannel -I2sOutputChannel --|> I2sChannel -I2sSink --o I2sOutputChannel -I2sSource --o I2sInputChannel - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_tdm.dot b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_tdm.dot deleted file mode 100644 index db699bbd..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/i2s/images/i2s_tdm.dot +++ /dev/null @@ -1,38 +0,0 @@ -digraph G { - node [fontsize=10,shape=record,height=.1]; - splines=false - - subgraph clusterAcpi { - label="tdm_ts_group[8]"; fontsize=10; - tdm_acpi [label="FFFFFF43 |FFFFFF01 |..."]; - } - - subgraph clusterStr0 { - label="Stream 0"; fontsize=10; color="#C4D600"; - - str0_cfg [label="\{ time_slot_group_index=1\}"]; - str0_cfg -> tdm_acpi:acpi1 [style=dotted]; - - str0 [label="L |R |... |
\n') f.write('
\n') - f.write('
\n') + f.write('
\n') f.write(' Latest Binary Release: \n') f.write(f' {latest["tag_name"]}\n') + if fw_badge: + f.write(f' {fw_badge}\n') f.write('
\n') f.write(f'
Published on {latest["published_at"]}
\n') f.write('
\n') - f.write('

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

\n') + if latest_fw != "N/A": + f.write(f'

Official pre-built and signed firmware binaries (bundled with SOF Firmware {latest_fw}), compiled topologies, and install scripts for Intel, AMD, and NXP platforms.

\n') + else: + f.write('

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

\n') f.write(' \n') f.write('
\n\n') @@ -236,21 +275,24 @@ def generate_sof_bin_releases(): f.write("Recent Binary Releases\n") f.write("**********************\n\n") f.write(".. csv-table::\n") - f.write(' :header: "Release Tag", "Release Date", "Binary Archive", "Archive Size", "GitHub Notes"\n') - f.write(" :widths: 16, 15, 30, 14, 25\n\n") + f.write(' :header: "Release Tag", "Firmware Version", "Release Date", "Binary Archive", "Archive Size", "GitHub Notes"\n') + f.write(" :widths: 15, 15, 14, 28, 13, 20\n\n") for r in releases: tag = r["tag_name"] + fw_ver = r.get("fw_version", "N/A") date = r["published_at"] asset_name = r["asset_name"] asset_url = r["asset_url"] size_str = f"{r['asset_size_mb']} MB" if r["asset_size_mb"] else "N/A" notes_url = r["html_url"] + tag_cell = f'`{tag} <{notes_url}>`_' + fw_cell = f'`{fw_ver} `_' if fw_ver != "N/A" else "N/A" download_cell = f'`{asset_name} <{asset_url}>`_' if asset_name != "N/A" else "N/A" notes_cell = f'`Release Notes <{notes_url}>`_' - f.write(f' "`{tag} <{notes_url}>`_", "{date}", "{download_cell}", "{size_str}", "{notes_cell}"\n') + f.write(f' "{tag_cell}", "{fw_cell}", "{date}", "{download_cell}", "{size_str}", "{notes_cell}"\n') f.write("\n") diff --git a/static/sof-custom.css b/static/sof-custom.css index a6c278a7..027010b0 100644 --- a/static/sof-custom.css +++ b/static/sof-custom.css @@ -353,3 +353,60 @@ html[data-mode="dark"] button.copybtn { } } +/* -- Breathe C API middle content pane styling (PyData theme) ------------- */ + +.bd-article p.breathe-sectiondef-title { + font-size: 1.25rem; + font-weight: 700; + margin-top: 1.8rem; + margin-bottom: 0.8rem; + padding-bottom: 0.3rem; + border-bottom: 1px solid var(--pst-color-border, #e5e7eb); + color: var(--pst-color-text-base); +} + +.bd-article dl.c.function, +.bd-article dl.c.struct, +.bd-article dl.c.enum, +.bd-article dl.c.macro, +.bd-article dl.c.type { + margin: 1.25rem 0; + padding: 0.75rem 1rem; + border: 1px solid var(--pst-color-border, #e5e7eb); + border-radius: 6px; + background-color: var(--pst-color-surface, #f8f9fa); +} + +.bd-article dl.c > dt.sig { + font-family: var(--pst-font-family-monospace, monospace); + font-size: 0.92rem; + font-weight: 600; + padding: 0.4rem 0.6rem; + margin: -0.75rem -1rem 0.75rem -1rem; + border-bottom: 1px solid var(--pst-color-border, #e5e7eb); + background-color: rgba(0, 0, 0, 0.03); + border-top-left-radius: 5px; + border-top-right-radius: 5px; + overflow-x: auto; +} + +html[data-theme="dark"] .bd-article dl.c > dt.sig, +html[data-mode="dark"] .bd-article dl.c > dt.sig { + background-color: rgba(255, 255, 255, 0.04); +} + +.bd-article dl.c > dd { + margin-left: 0.5rem; + margin-bottom: 0; +} + +.bd-article dl.c .field-list { + margin-top: 0.75rem; + margin-bottom: 0.5rem; +} + +.bd-article dl.c .field-list dt { + font-weight: 600; + color: var(--pst-color-text-muted, #6c757d); +} + diff --git a/tsc/index.rst b/tsc/index.rst index 477adfe8..a636b3ef 100644 --- a/tsc/index.rst +++ b/tsc/index.rst @@ -3,13 +3,32 @@ Technical Steering Committee (TSC) ################################## -The TSC serves as the highest technical decision body for the project, -with members chosen from involved project maintainers. This committee -sets the technical direction for the project, defines milestone -release features, and coordinates cross-community collaboration. +The Technical Steering Committee (TSC) serves as the highest technical decision-making +body for the Sound Open Firmware (SOF) project. The committee sets the technical +direction for the project, defines roadmap priorities and milestone release features, +evaluates architectural proposals (including :ref:`SOF_ABI_changes`), and coordinates +cross-community collaboration. -.. toctree:: - :maxdepth: 1 +.. _representatives: - representatives.rst - meetings.rst +TSC Representation +****************** + +Member companies active in the Sound Open Firmware project appoint technical +representatives to serve on the TSC. + +**Intel**, **NXP**, **AMD**, **MediaTek (MTK)**, and **Google** each hold **2 seats** +on the committee, ensuring balanced technical governance and multi-vendor alignment +across the open-source audio ecosystem. + +.. _meetings: + +TSC Meetings +************ + +TSC meetings are held periodically, usually following each major firmware release, +or on an ad-hoc basis as needed to address architectural, roadmap, or governance topics. + +Meeting agendas and notices are circulated ahead of time on the SOF development +channels and mailing list. Notes and decisions agreed upon by the TSC are made +publicly accessible and published in the project's GitHub repositories. diff --git a/tsc/meetings.rst b/tsc/meetings.rst deleted file mode 100644 index 2516ed52..00000000 --- a/tsc/meetings.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. _meetings: - -TSC Meetings -############ - -TSC meetings take place every month, typically the first Monday of -each month, with a agenda circulated ahead of time on the SOF mailing -list. - -The notes and decisions made by the TSC will be made public, stored on -GitHub and a link provided on the SOF mailing list. - diff --git a/tsc/representatives.rst b/tsc/representatives.rst deleted file mode 100644 index 66b7ff4d..00000000 --- a/tsc/representatives.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _representatives: - - -TSC Representatives -################### - -The TSC is currently made of the following contributors - -+---------------+----------------------+------------------+ -| Company | Name | Username | -+===============+======================+==================+ -| Intel | Michal Wasko | @mwasko | -+---------------+----------------------+------------------+ -| Intel | Liam Girdwood | @lgirdwood | -+---------------+----------------------+------------------+ -| Intel | Pierre Bossart | @plbossart | -+---------------+----------------------+------------------+ -| Intel | Beata Baranowska | @beatabaranowska | -+---------------+----------------------+------------------+ -| NXP | Daniel Baluta | @dbaluta | -+---------------+----------------------+------------------+ -| Google | Johny Lin | @johnylin76 | -+---------------+----------------------+------------------+ -| Google | Unseated | | -+---------------+----------------------+------------------+ -| Google | Unseated | | -+---------------+----------------------+------------------+ -| AMD | Carl Wakeland | @cwakeland | -+---------------+----------------------+------------------+ -| AMD | Virendra Pratap Arya | @vp-arya | -+---------------+----------------------+------------------+ -| AMD | Basavaraj Hiregoudar | @bhiregou | -+---------------+----------------------+------------------+

" color="#C4D600"]; - } - - subgraph clusterStr1 { - label="Stream 1"; fontsize=10; color="#FFA300" - - str1_cfg [label="\{ time_slot_group_index=0\}"] - str1_cfg -> tdm_acpi:acpi0 [style=dotted] - - str1 [label="L |R |..." color="#FFA300"] - } - - str [label="<0>R |<1>L |<2> |<3>L |<4>R |<5> |<6> |<7> "] - - str0:l -> str:1 - str0:r -> str:0 - - str1:l -> str:3 - str1:r -> str:4 - - {rank=min; tdm_acpi} - {rank=max; str} -} diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/images/io_drivers_diagram.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/images/io_drivers_diagram.pu deleted file mode 100644 index 37ce38ce..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/images/io_drivers_diagram.pu +++ /dev/null @@ -1,16 +0,0 @@ -frame "SOF" { - component Gateway - component GatewayExtension <> -} - -frame "Zephyr" { - component IoDriver <> - component DMA -} - -Gateway *-right- GatewayExtension - -Gateway -down- IoDriver -Gateway -down- DMA - -GatewayExtension ..> IoDriver diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/index.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/index.rst deleted file mode 100644 index 52562049..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/io_drivers/index.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _io_drivers: - -IO Drivers -########## - -The IO Drivers provide access to an IO HW Interfaces connected to the DSP, e.g. -I2S, DMIC, etc. and are managed as a part of the Zephyr RTOS. The Audio IO -Drivers share generic `Zephyr DAI interface `__. -For a full list of IO drivers available on the specific platform, refer to -:ref:`platforms`. HW IO is accessed via the `Gateway` interface inside the FW. -The actual implementation of that interface depends on the underlying HW IO -mechanism. Gateways use the Zephyr DMA interface to transmit the data to/from -the represented HW IO. DMA interface implementation depends on the underlying -DMA method (HDA-DMA, GPDMA, etc.). - -**NOTE:** The introduction of Gateways concept to SOF with Zephyr is a work in -progress. In existing implementation the SOF Host and DAI implementation is -still in use as a substitute of Gateways. - -.. uml:: images/io_drivers_diagram.pu - :caption: IO Drivers diagram - -Drivers -******* - -.. toctree:: - :maxdepth: 1 - - hda/hda_driver - i2s/i2s_driver - dmic/dmic_driver diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/heap_sharing.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/heap_sharing.rst deleted file mode 100644 index 1b7d0347..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/heap_sharing.rst +++ /dev/null @@ -1,58 +0,0 @@ -Heap sharing -############ - -The memory heap can be: - -- local - used exclusively by a single DSP core, -- shared - higher level memory shared across all DSP cores - -.. uml:: images/heaps.pu - :caption: Memory Heaps - -.. note:: Introduction of MMU will require a separate local application heap per - isolated domain. - -L1 Cache Coherency -****************** - -NOTE: This section applies to Intel systems without L1 cache coherency - -A local heap is used exclusively by a single DSP core. Therefore operations on -the allocated memory buffers do not require explicit L1 cache operations nor -data cache alignment. - -All operations performed on a local heap can be executed by the associated DSP -core only. The *move-to-another-core* operation is not permitted for allocated -buffers. - -A shared heap can be configured in two ways: - -1. To provide uncache aliases of buffer addresses to the clients, -2. To provide cacheable addresses to the clients. - -Option #1 is preferred, since does not require explicit L1 cache operations -when memory is accessed by a DSP core. However, all operations directly access -L2+ memory therefore it is not suitable for a low latency high performance data -processing case. - -Option #2 provides better performance but requires explicit L1 cache operations, -which are difficult to maintain and validate, as well as data cache alignment -for both client buffers and their descriptors, which creates an overhead. This -configuration should be avoided if possible unless a coherent API is available -to share the data. - -However, a one important exception to the shared memory accessed through uncached -alias is a data buffer connected between processing components running on -different cores. Locking and cache operations price could be payed to get much -better performance of accessing the data in the buffer which may be a -significant part of light weight LL processing modules DSP cycle budget. - -Accessing Shared Memory Pool -**************************** - -The data structures needed to manage shared memories are initialized by the -primary core, structure location in memory map is known at the build time and -API is protected by the mutex. - -The mutex uses atomic operation behind and all processors co-managing this -memory heap must support atomics. diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/dynamic_module_load.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/dynamic_module_load.pu deleted file mode 100644 index 02c386d0..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/dynamic_module_load.pu +++ /dev/null @@ -1,77 +0,0 @@ -@startuml - -box "Host" #LightGreen - participant "Driver" as host_driver -end box - -box "Media Processing Pipelines Layer" #LightSkyBlue - participant "Component Manager" as component_manager - participant "Library Manager" as lib_manager - participant "MPP Memory Manager" as mpp_memory_manager -end box - -box "Zephyr RTOS" #LightBlue - participant "Memory Management Driver" as memory_management_driver -end box - -box "Hardware" #LightGrey - participant "Memory" as hw_memory -end box - -host_driver -> lib_manager: Load Library - activate lib_manager - lib_manager -> mpp_memory_manager: rmalloc(MEM_ZONE_RUNTIME, flags=NULL, MEM_CAPS_LOADABLE_LIBRARY, size) - activate mpp_memory_manager - return address to store library - lib_manager --> host_driver - deactivate lib_manager - -host_driver -> lib_manager: Transfer library over DMA\nto given address - -host_driver -> component_manager: Instantiate Component - activate component_manager - - opt if Component is Loadable and it is first instance - component_manager -> lib_manager: Load component - activate lib_manager - - loop repeat for Component TEXT, RODATA - lib_manager -> lib_manager: read Component virtual address and size from manifest - - lib_manager -> memory_management_driver: sys_mm_drv_map_region(virt*, phys=NULL, size, flags=NULL) - activate memory_management_driver - memory_management_driver -> memory_management_driver: allocate free phys pages - opt power up memory banks for allocated phys pages - memory_management_driver -> hw_memory: power up memory banks - end - memory_management_driver --> lib_manager - deactivate memory_management_driver - - lib_manager -> lib_manager: read Component address offset from library manifest - lib_manager -> lib_manager: mem_copy(virt*, library_store_addr + offset, size) - lib_manager -> memory_management_driver: sys_mm_drv_update_region(virt*, size, flags= CODE / RODATA) - activate memory_management_driver - note right: update region flags to prevent overwrite - return - - end - - opt if Component has BSS - lib_manager -> memory_management_driver: sys_mm_drv_map_region(virt*, phys=NULL, bss_size, flags) - activate memory_management_driver - memory_management_driver -> memory_management_driver: allocate free phys pages - opt power up memory banks for allocated phys pages - memory_management_driver -> hw_memory: power up memory banks - end - memory_management_driver --> lib_manager - deactivate memory_management_driver - end - - lib_manager --> component_manager - deactivate lib_manager - end - - component_manager -> component_manager: Instantiate Component - component_manager --> host_driver - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/heaps.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/heaps.pu deleted file mode 100644 index 582b21bd..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/heaps.pu +++ /dev/null @@ -1,31 +0,0 @@ -scale max 1024 width - -node "DSP Core #0 Memory Block" as core_0 { - node "Application Heap (local)" as app_0 #lightgreen { - component "Pipelines @Core #0" as ppl_0 - component "LL Modules & Tasks @Core #0" as ll_0 - component "DP Modules & Tasks @Core #0" as dp_0 - } - - node "Application Heap (shared)" as app_shared_0 #lightyellow { - component "Shared buffers" - } - - node "System Heap (shared)" as sys_0 #lightblue { - component "Devices" - } -} - -ppl_0 -[hidden]down-> ll_0 -ll_0 -[hidden]down-> dp_0 - -node "DSP Core #1 Memory Block" as core_1 { - node "Application Heap (local)" as app_1 #lightgreen { - component "Pipelines @Core #1" as ppl_1 - component "LL Modules & Tasks @Core #1" as ll_1 - component "DP Modules & Tasks @Core #1" as dp_1 - } -} - -ppl_1 -[hidden]down-> ll_1 -ll_1 -[hidden]down-> dp_1 diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation.pu deleted file mode 100644 index 82d84bf0..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation.pu +++ /dev/null @@ -1,21 +0,0 @@ -@startuml - -box "SOF" #LightBlue - participant "Component Management" as component_management - participant "MPP Memory Manager" as mpp_memory_manager -end box - -box "Zephyr" #LightGreen - participant "Zephyr Memory Manager" as zephyr_memory_manager -end box - -activate component_management -component_management -> mpp_memory_manager: rmalloc(mem_zone, flags, caps, size) - activate mpp_memory_manager - - mpp_memory_manager -> mpp_memory_manager: find memory heap that\nmatch zone and caps - mpp_memory_manager -> zephyr_memory_manager: k_heap_alloc (heap, size) - activate zephyr_memory_manager - return - mpp_memory_manager --> component_management -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation_from_memory_driver.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation_from_memory_driver.pu deleted file mode 100644 index a9d10fd7..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_allocation_from_memory_driver.pu +++ /dev/null @@ -1,26 +0,0 @@ -@startuml - -box "SOF" #LightBlue - participant "Library Manager" as library_manager -end box - -box "Zephyr" #LightGreen - participant "Memory Management Driver" as memory_management_driver -end box - -box "Hardware" #LightGrey - participant "Memory" as hw_memory -end box - -activate library_manager - -library_manager -> memory_management_driver: sys_mm_drv_map_region\n(virt*, phys=NULL, size, flags) - activate memory_management_driver - memory_management_driver -> memory_management_driver: allocate memory phys pages - opt if phys memory pages require power up - memory_management_driver -> hw_memory: power up memory banks - end - - return - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_initialization.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_initialization.pu deleted file mode 100644 index 666e68b1..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_initialization.pu +++ /dev/null @@ -1,42 +0,0 @@ -@startuml - -box "SOF" #LightBlue - participant "MPP Memory Manager" as mpp_memory_manager -end box - -box "Zephyr" #LightGreen - participant "Memory Manager" as zephyr_memory_manager - participant "Memory Management Driver" as memory_management_driver -end box - -box "Hardware" #LightGrey - participant "Memory" as hw_memory -end box - - --> memory_management_driver: sys_mm_drv_mm_init - activate memory_management_driver - memory_management_driver -> memory_management_driver: read unused_main_mem_start_marker\nfrom linker - note right: The marker is used to\n identify where base firmware\n ends in memory (text, data, bss) - - memory_management_driver -> memory_management_driver: sys_mm_drv_unmap_region(unused_main_mem_start, unused_size) - activate memory_management_driver - opt If architecture support granular memory banks power control - memory_management_driver -> hw_memory: power down unused memory banks - deactivate memory_management_driver - end - - deactivate memory_management_driver - --> mpp_memory_manager: mpp_mem_init - activate mpp_memory_manager - mpp_memory_manager -> mpp_memory_manager: read memory zones\nbase address and size - loop for each memory region create heap - mpp_memory_manager -> zephyr_memory_manager: k_heap_init\n(heap, mem*, size) - activate zephyr_memory_manager - return - end - - deactivate mpp_memory_manager - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_management_layers.pu b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_management_layers.pu deleted file mode 100644 index a2218c96..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/images/memory_management_layers.pu +++ /dev/null @@ -1,60 +0,0 @@ -@startuml - -allowmixing - -scale max 1024 width - -component SOF { - - package "Zephyr" as ZEPHYR_RTOS { - interface "Zephyr Memory Service interface" as ZMSI - hide ZMSI methods - hide ZMSI attributes - - package "Drivers" as DRIVERS { - component "Memory Management Driver" as MEMORY_MGMT_DRIVER - } - - package "Memory Manager" as ZEPHYR_MEM_MANAGER { - component "Multi Heap" as MULTI_HEAP - component "Memory Heaps" as MEM_HEAPS - component "Memory Blocks Allocator" as MEM_BLOCK_ALLOCATOR - component "Demand Paging" as DEMAND_PAGING - - MULTI_HEAP .[hidden]right. MEM_HEAPS - MEM_HEAPS .[hidden]right. MEM_BLOCK_ALLOCATOR - MEM_BLOCK_ALLOCATOR .[hidden]right. DEMAND_PAGING - } - - component "Device Tree" as DEV_TREE - - ZMSI -[hidden]down- MEM_BLOCK_ALLOCATOR - ZEPHYR_MEM_MANAGER -[hidden]down- DRIVERS - DRIVERS -[hidden]right- DEV_TREE - } - - package "Media Processing Pipelines layer" as MPP_LAYER { - component "Pipeline Manager" as PIPELINE_MANAGER - component "Communication" as COMMUNICATION - component "Component Manager" as COMPONENT_MANAGER - component "MPP Memory Manager" as MPP_MEM_MANAGER - - PIPELINE_MANAGER -[hidden]right- COMMUNICATION - COMMUNICATION -[hidden]right- MPP_MEM_MANAGER - MPP_MEM_MANAGER -[hidden]right- COMPONENT_MANAGER - - } - - package "Application layer" as APP_LAYER { - component "Loadable Components" as LOADABLE_COMPONENTS - component "Built-in Components" as BUILT_IN_COMPONENTS - - BUILT_IN_COMPONENTS -[hidden]right- LOADABLE_COMPONENTS - } - - APP_LAYER -[hidden]down- MPP_LAYER - MPP_LAYER -[hidden]down- ZEPHYR_RTOS - -} - -@enduml diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/index.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/index.rst deleted file mode 100644 index fbaddd30..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/index.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. _memory_mgmt: - -Memory Management -################# - -Memory Management role is to provide service API for dynamic memory mapping and -allocation from available memory zones. - -Overview -******** - -The memory support functionality is delivered at two levels: - - - Zephyr Memory Management Service, which provides memory drivers, demand - paging, allocators, and heap management, - - - MPP Memory Management - SOF extension, which provides heaps for virtual - memory mapped to physical memory on demand, and declaration of SOF specific - heaps instantiated for various memory zones, - -.. uml:: images/memory_management_layers.pu - :caption: Example of Memory Management layers and interfaces - -Memory Hierarchy & Dynamic Paging -********************************* - -SOF manages heterogeneous memory spaces across DSP and host domains: - -* **Tightly Coupled Memories (IRAM/DRAM)**: Low-latency memory dedicated to performance-critical DSP interrupt service routines and real-time audio threads. -* **High-Power / Low-Power SRAM Pools**: Dynamically power-gated SRAM banks utilized to minimize power draw during active playback and low-power idle. -* **Isolated Memory Regions (IMR) & Dynamic Paging**: For platforms with constrained on-chip SRAM, SOF dynamically pages code and data between host DRAM (IMR) and DSP SRAM, enabling large features (like complex neural networks or large codec libraries) to execute without requiring oversized on-chip SRAM. - -Read More -********* - -.. toctree:: - :maxdepth: 1 - - memory_zones - mpp_memory_management - heap_sharing - memory_management_driver - memory_management_flows - -External Links -============== - -- `Zephyr Memory Management Service `__ -- `Memory Blocks Allocator `__ -- `Memory Management driver `__ -- `Heaps Management `__ -- `Demand Paging `__ diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_driver.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_driver.rst deleted file mode 100644 index 097c450f..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_driver.rst +++ /dev/null @@ -1,21 +0,0 @@ -Memory Management Driver -######################## - -The Memory Management Driver (MMD) is part of the Zephyr distributed drivers. -Each SoC may require unique Memory Management driver implementation. The MMD -shall implement common MMD interface that is exposed to kernel services. This -allows for explicit allocation and mapping of individual memory hardware pages -within the physical environment. - -All operations within Memory Management Driver are explicit. Hardware page IDs -represent real physical blocks of hardware memory. - -The MMD is responsible for identification what part of the SoC memory is used by -the base firmware (code, data, bss) and unmap the unused blocks. The unused -memory will be available for dynamic allocation. Base firmware code, read only -data and BSS are mapped in the TLB automatically with corresponding flags (CODE, -RODATA) to prevent incidental modification. - -Memory Management Driver can maintain memory power at a granular level if the -architecture support it. It has possibility to power up selected memory banks on -map requests and power down on unmap, which is a recommended flow. diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_flows.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_flows.rst deleted file mode 100644 index aa90ebb2..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_management_flows.rst +++ /dev/null @@ -1,41 +0,0 @@ -Flows -##### - -Memory initialization -********************* - -Main goal of Memory initialization is to unmap unused memory after firmware load -and create heaps for supported memory zones. - -.. uml:: images/memory_initialization.pu - :caption: Memory initialization flow - -Memory allocation -***************** - -The common memory allocation is expected to use one of the available memory -zones via Zephyr Heap that was created during initialization. - -.. uml:: images/memory_allocation.pu - :caption: Memory allocation example flow - -Memory allocation directly using Memory Management Driver -********************************************************* - -In specific use cases (e.g. Dynamic Component Load) it may be required to -allocate memory directly using Memory Management Driver to control what virtual -address will be mapped to physical memory. - -.. uml:: images/memory_allocation_from_memory_driver.pu - :caption: Example memory allocation using Memory Management Driver - -Dynamic Component Load -********************** - -The loadable components are stored in Loadable Library memory zone and can be -loaded on instantiate request to System memory. The components load to System -memory is optional and integrator can indicate if the components can be executed -directly from the Loadable Library memory zone. - -.. uml:: images/dynamic_module_load.pu - :caption: Dynamic component load and instantiation flow diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_zones.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_zones.rst deleted file mode 100644 index 5be17be8..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/memory_zones.rst +++ /dev/null @@ -1,11 +0,0 @@ -Memory Zones -############ - -Depending on the memory use case a different memory zone can be used for -allocation. Application and MPP layer components are using memory zones and -capabilities to identify a target memory. The memory zones mapping on physical -addresses is SoC specific. If the SoC support multiple memory types with -different characteristics, then it is up to SoC integrator to decide which -memory will be most suitable for zone mapping. For example, if SoC has access to -slow but large capacity memory then it can map it for Loadable Library memory -zone. diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/mpp_memory_management.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/mpp_memory_management.rst deleted file mode 100644 index 2f079186..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/memory_management/mpp_memory_management.rst +++ /dev/null @@ -1,19 +0,0 @@ -MPP Memory Management -##################### - -MPP Memory Management (MPP MM) is a SOF extension running on top of Zephyr -Memory Manager. The reason to create MPP MM was to add support for memory zones, -which are not natively supported by Zephyr. Zephyr by default initialize single -System Heap. - -The MPP MM roles: - - - initialization of Memory Heaps for supported memory zones, - - provide allocator API for memory allocation from different memory zones, - -Memory Heaps initialization is done based on SoC Memory Map that identify start -and end addresses of memory zones. - -.. note:: - Memory zones are expected to be defined as memory sections in a SoC linker script. - diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/power_management.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/power_management.rst deleted file mode 100644 index c394f52c..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/power_management.rst +++ /dev/null @@ -1,158 +0,0 @@ -.. _power_mgmt: - -Power Management -################ - -The Power Manager is responsible for system and device power management. The -power management behavior can be customized by power policy configuration and -direct power API requests which allows you to adjust system power savings to the -current firmware activity. - -.. uml:: images/power/power_components.pu - :caption: Participants of the Firmware power management. - -`Zephyr Power Management -documentation `__ - -DSP Cores -********* - -Each DSP core can be separately powered up and down. - -The assumption is that DSP #0 is a primary core and is responsible for powering -up all secondary cores. The primary core powers up the secondary cores on Set Dx -IPC request. - -The secondary core shall be powered up prior to any task allocated to it by the SW -driver. - -Power Transitions -***************** - -There are three DSP core power states: - -.. list-table:: - :widths: 5 10 20 - :header-rows: 1 - - * - DSP Power State - - Zephyr Power State - - Notes - * - D0 - - PM_STATE_ACTIVE - - built-in state, no extra mapping required - * - D0i3 - - PM_STATE_RUNTIME_IDLE - - custom mapping in the Device Tree - *d0i3: idle { power-state-name = "runtime-idle" }* - * - D3 - - PM_STATE_SOFT_OFF - - custom mapping in the Device Tree - *d3: off { power-state-name = "soft-off" }* - -A major consumer of power related to the main part of the DSP subsystem -is a source of the clock that is wired to the DSP core and the DSP core itself. -Transitions to lower power states focus on this part. Another power consumer, -a bit less significant, is the L2 SRAM memory embedded in the DSP subsystem. - -The clock source and clock gating is managed by the Power Manager according to -Power Policy configuration settings. - -Memory power is controlled by the Memory Management Driver that is responsible -for memory setup on power state transitions and memory banks power gating on -map/unmap requests (if it is supported by the SoC). - -Other power-related settings are clock gating and power gating of I/Os (I2C, -I3C, GPIO, SPI, UART, DMIC, etc.) and external DSP accelerators (if supported by -the hardware). - -The low power state transition can be triggered either by Zephyr (on CPU idle) -or on the Host IPC request through the Zephyr force power state set request. The -entrance to D0i3 power state can be dynamically locked on SetD0ix IPC request -that configures the Zephyr Power Policy to prevent a selected power state transition. - -More details are in the `Zephyr Power Management -documentation `__ - -.. uml:: images/power/dsp_fw_power_states.pu - :caption: DSP and FW Power States - -.. uml:: images/power/dx_state_transitions.pu - :caption: D3, D0 and D0ix state transitions - -Power Up of Secondary Core (D3 to D0 transition) -================================================ - -The below diagram shows secondary core boot flow: - -.. uml:: images/power/flow_secondary_core_boot.pu - :caption: DSP Secondary Core Boot flow - -Power down of DSP core (D0 to D3 transition) -============================================ - -The below diagram shows a primary core power down flow: - -.. uml:: images/power/flow_primary_core_power_down.pu - :caption: DSP Primary Core Power Down flow - -Power down of Secondary Core (D0 to D3 transition) -================================================== - -The below diagram shows a secondary core power down flow: - -.. uml:: images/power/flow_secondary_core_power_down.pu - :caption: DSP Secondary Core Power Down flow - -Enable D0ix (D0 to D0ix) -======================== - -D0ix is enabled on explicit `SET_D0ix` IPC message with prevent_power_gating bit -set to 0. - -.. uml:: images/power/flow_enable_d0i3.pu - :caption: Enable D0i3 flow - -Disable D0ix (D0ix to D0) -========================= - -D0ix is disabled on explicit `SET_D0ix` IPC message with prevent_power_gating -bit set to 1. - -.. uml:: images/power/flow_disable_d0i3.pu - :caption: Disable D0i3 flow - -DSP idle state -============== - -.. uml:: images/power/flow_dsp_idle.pu - :caption: DSP idle state flow - -DSP Cores Clock Gating -====================== - -DSP clocks, similar to DSP cores, can be separately gated as well. Clock gating -shall be enabled by default for all DSP cores unless there is request to prevent -it. - -.. TODO: Create diagram with DSP power state transitions when either DSP clock - is gate or DSP power is gate. - -**NOTE:** Power and clock gating is controlled via `Set D0ix` IPC message. - -I/O Power and Clock Gating Management -************************************* - -Zephyr is responsible for I/O devices power and clock management. - -The I/O device power is controlled based on usage count. More details can be -found in `Zephyr Device Runtime Power Management -documentation `__ - -The I/O clock gating is configurable in driver power policy. Each driver shall -request the desired clock and clock power gating if it is necessary for I/O, -accelerator, etc. to work correctly. - -For instance, audio I/Os such as I2S associated with audio domain require a high -accuracy XTAL clock and may request it. This clock shall be used for as long as -audio I/Os are active. diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/zephyr_kernel_overview.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/zephyr_kernel_overview.rst deleted file mode 100644 index e8e9ada2..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/rtos_layer/zephyr_kernel_overview.rst +++ /dev/null @@ -1,372 +0,0 @@ -.. _kernel_overview: - -Zephyr based kernel -################### - -Zephyr has been introduced as an IP agnostic solution that replaced existing SOF -audio specific kernel. The Zephyr base kernel has been complemented with SOF Low -Level Drivers, SoC HAL and kernel extensions. The new solution continues -scalable kernel concept and it serves as a generic part of infrastructure that -can be statically and dynamically customized based on usage, compute, and memory -constrains, HW configuration etc. - -As a result of the kernel customization, a firmware infrastructure is produced. -This firmware infrastructure can run on a given processor type and it is tuned -for specified usage. - -For more Zephyr kernel details, see `Zephyr Introduction -documentation `__ - -The Zephyr based kernel consists of the following components: - -- Hardware integration layer: XTHAL, -- Low Level Drivers, - - - DMIC, - - I2S, - - SNDW, - - GPIO, - - I2C, - - I3C, - - timers, - - GPDMA, - - IDC, - - IPC, - - watchdog, - - etc. - -- SoC HAL, - - - OEM SoC specific code, - -- Services: shared resource services, communication services, memory manager, - power manager, interrupt manager, system service, etc. -- Kernel extensions: - - - AVS schedulers, - - Firmware Manager, - - Media Processing Pipeline Components, - -The Zephyr base kernel expectations: - -- it can scale down to meet all KPIs via static and dynamic scaling options, -- Zephyr itself is IP agnostic and shared across other SW and FW projects, -- it is available and maintain under open source license, - -.. uml:: images/zephyr_kernel_diagram.pu - :caption: Zephyr Kernel diagram - -Scaling Options -''''''''''''''' - -Zephyr kernel offers scaling options to adjust to selected HW configuration, -scale down to meet aggressive KPIs on a given platform, scale up to meet -functional requirements. - -The scaling is achieved in two ways: - -- static, kernel components can be selectively enabled in the build process - - - Drivers selected depending on SoC Configuration - - Services and execution frameworks chosen in Zephyr - -- dynamic, not used parts can be unloaded and saved in "backup storage" memory, - that typically has large capacity and high access latency. They will be - loaded again once a specific event will happen - - - It is only applicable to SoCs that support it. - - It is achieved via one of the following mechanisms: - - - Firmware Paging (if present) - Only currently executing modules are in - SRAM. - - Split Firmware into modules - Modules are loaded from "backup storage" - or unloaded on explicit request. No runtime dynamism. - -Handling Project Configuration -'''''''''''''''''''''''''''''' - -Zephyr is prepared to be configured via device tree that describe given SoC -board audio hardware configuration. - -A SoC board device tree allows configuring: - -* HW configuration - - * number of HP DSP cores, - * types of memories available per cores, - * supported clocks, - * number of I/Os, - * number of IPC and IDC interfaces for DSP cores, - * etc. - - * DSP memory space, - * IPC mailbox address, - * etc. - -Low Level Drivers -''''''''''''''''' - -SOF is capable to support hardware with several audio I/Os, sensor I/Os, DSP -accelerators and DMAs which count can be customized per architcture. - -HW resources with low level drivers: - -* Audio I/Os: I2S, DMIC, SNDW, HD/A, -* Sensor I/Os: I2C, I3C, GPIO, UART, SPI, ADC, PWM, -* Common resources: HP GPDMA, IPC, IDC, Timers, SHA-384, Watchdog - -**NOTE:** Not all I/Os are supported in each SoC board. - -.. TODO: add link to supported audio architectures - -Zephyr based firmware provides low level drivers for all these resources. A -specific driver can be enabled during build process. - -SoC HAL -''''''' - -The SoC HAL include implementation and configuration details specific for -selected SoC architecture. The SoC HAL abstraction allow to seamlesly switch -between target SoC configuration builds. - -More details can be found in Zephyr documentation: - -* `Zephyr Board Porting Guide `__ -* `Zephyr Architecture Porting Guide `__ - -Services -'''''''' - -.. uml:: images/kernel_services.pu - :caption: Example of kernel services - -The base Zephyr services provide generic system management functionality for -memory, interrupts, autonomous power control (clock and power gating, clock -management). - -The SOF specific functionality is exposed in a form of an extended kernel -services. The extended services utilize Zephyr base services infrastructure and -low level drivers to supply user space interface for the firmware application -layer components. The user space separation from hardware and low level drivers -significantly increase the firmware security and stability. - -Firmware Management -------------------- - -The firmware manager is a core service that is responsible for: - -- reading HW capabilities (number of cores, memory available, etc.), -- firmware initialization, -- instantiation and initialization of Low Level drivers for the existing HW - components, - - - memory type drivers initialization with size read form capability - registers - - audio drivers for supported interfaces - -- instantiate and initialize Extended Kernel Services - - - component manager - - pipeline manager - - IPC/IDC communication service - - async messaging service - - debug service - -.. TODO: add other components that require initialization by the firmware manager - -Interrupt Management --------------------- - -The interrupt handler service allows to: - -- enable and disable an interrupt for DSP core, -- register a callback that will be called once a specified interrupt occur, - -For more details, see `Zephyr Interrupts -documentation `__ - -Memory Management ------------------ - -The Memory Manager provides a service to other FW components to allocate a block -out of available memory pools, it provides high level API, scans for unused -memory areas, handles physical memory defragmentation, prefetch and cache -policies. Most of the memory is expected to be paged. - -All allocation requests refer to virtual memory address space, which shall be -continuous. This also applies to DMA buffer allocations, where continuous memory -is guaranteed by either continuous physical memory or VA/PA translation. - -The map of available memory resources is passed to the Memory Manager during -initialization of Memory Manager via firmware infrastructure. - -For more details, see `Zephyr Memory Management -documentation `__. - -Power Management ----------------- - -The power management behavior highly depends on platform that firmware runs on, -and it can be configured during build time. There are platforms that only allow -clock gating and power gating is not applicable. - -The power management interface provides the following functionality: - -- allow and prevent power gating, -- allow and prevent clock gating, -- allow and prevent slower clock, -- allow and prevent XTAL shutdown, - -In all cases, the implementation relies on atomic counter which is incremented -every time when prevent function is called and decremented when allow function -is called. - -.. TODO: Add link to SOF Power Management detailed description with flows - -`Zephyr Power Management documentation -`__. - -IPC and IDC Service -------------------- - -The IPC and IDC Service provides communication channel over IPC or IDC. IPCs are -used for the external communication with Host, other processors within SoC or -other subsystems within PCH. IDCs are used for the internal communication -between processors within SOF subsystem. - -The introduction of SOF with Zephyr is followed with new IPC4 interface and -message formats that replaced IPC3. - -The following types of sequences are supported: - -- request-response initiated by Host, - - - it is synchronous sequence, - - long-running operations shall queue request and send response immediately. - The actual completion information should be sent via one-way asynchronous - notification, - -- one-way asynchronous notification, - -.. TODO: Add link to Communication section (when ready) - -Debugging ---------- - -The Zephyr based kernel provides a few services that helps with debugging FW. - -Logging -~~~~~~~ - -The Logger Service provides a lightweight mechanism to push log entries to all -firmware modules that are based on Zephyr logging infrastructure. - -It is a very useful mechanism to do a first level of debugging. - -.. TODO: Add link to Logger Service section (when ready) -.. TODO: Add link to SOF Enable Logs interface -.. TODO: Add link to SOF status and error codes registers - -Zephyr related documentation: - -- `Zephyr - Logging `__ - -Probes -~~~~~~ - -SOF supports injection and extraction probes. The probes are mainly used to -extract audio data from queues between components. - -The other probe use cases include: - -- injection of audio data to a component input queue - useful during testing - and debugging, -- injection of data to internal probes, -- extraction of data from internal probes i.e. internal component states, - intermediate data, debug information, -- logging - probes can be used as transport for firmware logs, - -.. TODO: Add link to Probe configuration interface (when ready) - -Performance Measurements -~~~~~~~~~~~~~~~~~~~~~~~~ - -The firmware infrastructures support performance measurements to collect -information about DSP cycles or amount of data moved via interfaces. - -.. TODO: Add link to Performance Measurements State firmware interface -.. TODO: Add link to firmware Global Performance Data description - - -Telemetry -~~~~~~~~~ - -Firmware infrastructure supports collection of telemetry events which then can -be read by the Host Software. The modules running in FW infrastructure can push -telemetry events via System Services. - -If the telemetry collection is started, the telemetry events will be written to -a common circular buffer. - -If the telemetry collection is stopped/disabled, the telemetry events will be -dropped at telemetry service level and they will not be written to the telemetry -circular buffer. During transition from started to stopped state, the telemetry -events that are already in the circular buffer will be dropped. - -.. TODO: Add link to SOF Telemetry interface documentation - -.. _schedulers_zephyr: - -Schedulers ----------- - -The scheduling method depends on compute and memory available for firmware -running on processor as well as type of workloads executed on given domain. - -There are following types of schedulers supported in SOF - -- AVS scheduling, - -.. TODO: Add link to Scheduling detailed section - -Async Messaging Service ------------------------ - -Asynchronous Messaging Service (AMS) is mechanism to exchange asynchronous -events between components running in the same firmware infrastructure or running -on the another processor (e.g. between HiFi and Fusion cores). - -The Async Messages can be also injected and extracted via Host Async Message -Gateway module by Host SW. - -.. TODO: Add link to Asynchronous Messaging detailed section - -System Services ---------------- - -The FW components do not know location of driver and service functions in base -firmware library, so they need to access base firmware services via System -Services. - -In SOF with Zephyr the `Zephyr interfaces for -drivers `__ -were adopted. All newly developed drivers must be compliant to this standard and -the legacy ones must be ported to it. - -In Zephyr based firmware, a driver instance is obtained via -``device_get_binding`` function call with a name of a driver instance. There is -no explicit driver initialization call as a driver instance is initialized with -the first call. - -A driver implementation must be ready for using the same hardware instance from -many modules and from many cores (it must be thread-safe implementation). There -can be more than one device instance if there is more than 1 instance of a -hardware (i.e. 2 I2C owner controllers). - -The example functionalities that should be exposed via system services: - -- IPC and IDC, -- Logger Service, -- RTOS scheduler functionalities, like yield, -- Async Messaging Service, diff --git a/developer_guides/subsystem_architecture/firmware/sof-zephyr/zephyr_api_integration.rst b/developer_guides/subsystem_architecture/firmware/sof-zephyr/zephyr_api_integration.rst deleted file mode 100644 index fe351051..00000000 --- a/developer_guides/subsystem_architecture/firmware/sof-zephyr/zephyr_api_integration.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. _zephyr-api-integration: - -Zephyr API Integration -###################### - -Most of the interfaces between the application (audio) layer and the kernel are -aggregated inside the part of the legacy SOF architecture called "lib". The -interfaces are exposed by the *lib*, declared in header files in -*src/include/sof/lib* directory. Implementation is located in the *src/lib* -except for platform and architecture specific functions that are delegated to -*platform* and *arch* parts respectively. - -.. uml:: images/sof_lib.pu - :caption: Legacy SOF Lib - -Zephyr replaces *lib* and other architecture and platform specific code, -everything below the *app* & *mpp* layers. - -In order to unify the access to the lower parts from the *app* and *mpp*, the -library header files provides now a definition of unified interface but some -changes are introduced to the original set of APIs and/or the implementation. - -Let's have a look at possible cases. - -**Case #1: New Zephyr API replaces 1:1 legacy SOF lib API** - -If there is a Zephyr version of a SOF legacy API which provides exactly the same -functionality as the original function but has a different name, the Zephyr -function name is used as a replacement in the SOF *app* and *mpp* code. It -causes direct linking and call into the Zephyr code optimizing FW size and -performance when SOF is built with Zephyr. Building with legacy SOF *lib* -requires an implementation or just a simple adapter for the new Zephyr API. It -may or may not slightly increase the size and decrease the performance of the -legacy SOF. - -.. code-block:: c - - // src/include/sof/lib.cpu.h - #ifdef __ZEPHYR__ - #include - #else - // was: static inline int cpu_is_core_enabled(int id) - static inline bool arch_cpu_active(int id) - { - arch_cpu_is_core_enabled(id); - } - #endif /* __ZEPHYR__ */ - -**Case #2: Legacy SOF lib API requires multi-step implementation for Zephyr -configuration** - -There may be a case when SOF legacy API is implemented by a single function -provided by the *arch* or another package and there is no 1:1 API available in -Zephyr to replace that. In this case, the API is implemented in the *lib-zephyr* -part based on the native Zephyr APIs. - -.. code-block:: c - - // src/include/sof/lib/cpu.h - #ifdef __ZEPHYR__ - void cpu_disable_core(int id); - #else - static inline void cpu_disable_core(int id) - { - arch_cpu_disable_core(id); - } - #endif /* __ZEPHYR__ */ - - // src/lib-zephyr/cpu.c - void cpu_disable_core(int id) - { - // ... calls to Zephyr APIs - } - -**Case #3: Legacy SOF lib API is implemented completely inside the lib and does -not have any replacement in Zephyr** - -The agent code might be an example of the library functions that are common and -must be compiled and linked together with either legacy SOF *lib* or -*lib-zephyr*. - -The dependencies between the SOF *lib*, *lib-zephyr*, and *zephyr* are -illustrated in the below figure. - -.. uml:: images/sof_lib_zephyr.pu - :caption: SOF Lib + Zephyr diff --git a/developer_guides/subsystem_architecture/host/index.rst b/developer_guides/subsystem_architecture/host/index.rst deleted file mode 100644 index 170d0654..00000000 --- a/developer_guides/subsystem_architecture/host/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. _architecture-host: - -Host Architecture -################# - -For the high-level system and software stack architecture, see :ref:`architectures`. - -.. toctree:: - :maxdepth: 1 - - linux_driver/architecture/sof_driver_arch.rst diff --git a/developer_guides/subsystem_architecture/host/linux_driver/architecture/images/sof-driver-arch-1.png b/developer_guides/subsystem_architecture/host/linux_driver/architecture/images/sof-driver-arch-1.png deleted file mode 100644 index 4c5ebe9c..00000000 Binary files a/developer_guides/subsystem_architecture/host/linux_driver/architecture/images/sof-driver-arch-1.png and /dev/null differ diff --git a/developer_guides/subsystem_architecture/host/linux_driver/architecture/images/sof-driver-arch-2.png b/developer_guides/subsystem_architecture/host/linux_driver/architecture/images/sof-driver-arch-2.png deleted file mode 100644 index bf2246ca..00000000 Binary files a/developer_guides/subsystem_architecture/host/linux_driver/architecture/images/sof-driver-arch-2.png and /dev/null differ diff --git a/developer_guides/subsystem_architecture/host/linux_driver/architecture/sof_driver_arch.rst b/developer_guides/subsystem_architecture/host/linux_driver/architecture/sof_driver_arch.rst deleted file mode 100644 index 61f774f9..00000000 --- a/developer_guides/subsystem_architecture/host/linux_driver/architecture/sof_driver_arch.rst +++ /dev/null @@ -1,364 +0,0 @@ -.. _sof_driver_arch: - -SOF Linux Driver Architecture -############################# - -|SOF| can either operate as a standalone firmware or alongside a host OS -driver for configuration and control. The |SOF| OS driver is responsible for -loading firmware, loading configuration and managing firmware use cases. -Currently |SOF| has a driver for the Linux OS. - -The |SOF| driver code is dual licensed GPLv2 and BSD and this means the user -can choose which licence they want to use (either BSD or GPLv2). The driver -stack is designed with maximum resuse so that large portions of it can be -taken and integrated into other OSs or RTOSs. - -.. contents:: - :local: - :depth: 1 - -Overview -******** - -Audio Driver Architecture -========================= - -The Sound Open Firmware (SOF)-based audio driver stack consists of an architecture-independent SOF driver core, an SOF DSP driver for Intel High Definition Audio (HD-Audio) platforms, an ALSA System-on-Chip (ASoC)-compliant audio codec driver, and a hardware-specific machine driver. - -.. image:: images/sof-driver-arch-1.png - -Sound Open Firmware -=================== - -Sound Open Firmware (SOF) is an open source audio Digital Signal Processing (DSP) firmware infrastructure and SDK. SOF provides infrastructure, real-time control pieces, and audio drivers. A generic SOF subsystem is implemented in Linux as a subsystem of ALSA ASoC. - -.. image:: images/sof-driver-arch-2.png - -ALSA and ASoC -============= - -The Advanced Linux Sound Architecture `(ALSA) `_ provides audio and MIDI functionality to the Linux operating system. The ALSA System-on-Chip `(ASoC) `_ is a subsystem of ALSA. ASoC provides a modular architecture to share audio codec drivers across different SoC implementations, unify the controls provided to applications, and provide a common infrastructure to manage SoC audio component power and clocks. - -Related ALSA Drivers -==================== - -The upstream Linux kernel has a few drivers that are related to the SOF-based audio driver stack described in this document. These drivers include the Intel AZX HD Audio driver (``linux/sound/pci/hda``) and the Intel SST Audio driver (``linux/sound/soc/intel/``). - -The AZX driver is intended to be used with Intel HD Audio PCI hardware when the Audio DSP is disabled (e.g. BIOS configuration). The AZX driver should be used instead of SOF when the DSP is not used. - -The SST Audio implements an ASoC-compliant driver for Intel HD Audio hardware, utilizing the Intel SST firmware. SST is primarily used with older generations of Intel processors for which SOF firmware support is not available. The SST driver and firmware should be used when the DSP is enabled and SOF firmware is not available for the platform. - -Driver Probe -************ - -The probe callback in the SOF PCI/APCI driver is responsible for allocating the platform data that is used to store the machine information including the PCI device ID, name, and the ACPI mach description. For Intel platforms, it uses the ACPI matching tables to determine the correct machine driver to load. The probe callback also sets up the SOF platform driver, initializes the Inter-Process Communication (IPC) to communicate with the DSP, and registers the SOF PCM component driver and the machine driver. Upon completion, it enables the runtime power management for the platform, if supported. - -SOF Platform Driver -******************* - -The SOF platform driver is a platform-specific driver that abstracts the low-level platform DSP hardware into a common generic API that is used by the upper layers. This includes code that will initialize the DSP and boot the firmware. The platform driver is responsible for setting up platform-specific ops for the device. The mandatory and optional platform ops are defined in ``struct snd_sof_dsp_ops``. It also describes the chip info the DUT by populating the ``struct sof_intel_dsp_desc`` fields necessary for DSP initialization. - -Platform Driver Probe -===================== - -The SOF platform driver detects the presence of a DSP in the platform by checking the PCI ``class/sub-class/prog-id`` information. It sets up the platform devices (ex: HDA device, dmic device), the DSP Base Address Registers, and initializes the streams and the interrupt vectors. Finally, it initializes the DSP capabilities and enables the DSP processing pipe capability interrupts. - -Firmware Loading and Booting -============================ - -On SKL+ platforms, firmware loading is performed using a dedicated DMA for code loading which is responsible for copying the FW into DSP memory. The DSP cores are powered up in a predetermined sequence and the host driver waits for the appropriate ROM init status to be written into the ROM status register to indicate initialization. This step is attempted a few times until the ROM status registers returns the successful ROM init status. Upon successful completion, the host driver triggers the code loader DMA to start copying the FW into DSP memory and boot it while waiting for the notification from the DSP. When the FW has successfully booted, the DSP sends the firmware-ready IPC message to notify the host. Further details are provided in **IPC Processing**, below. - -IPC Processing -************** - -Introduction -============ - -The SOF Audio DSP firmware uses IPC to communicate with the host. IPC is also used by the preinstalled DSP ROM, so it is used at least to load and start an SOF image. During that phase, the host communicates with the DSP ROM. Once ROM initialization is complete and the SOF FW has booted, the consequent IPC is performed with the firmware. - -IPC is bi-directional; messages can be initiated by the host and then acknowledged by the DSP. Similarly, they can be initiated by the DSP and acknowledged by the host. To indicate the direction of the communication, terms **initiator** and **target** are used. - -After SOF completes its boot process, it informs the host that it is ready for operation. Prior to receiving this message from the DSP, the mailbox offsets are not configured. Therefore, the message is read out from the DSP-to-host mailbox configured in the PCI mailbox BAR. Once read out, the message is parsed to determine the exact layout of all the IPC mailbox buffers. After that, the host sends further IPC messages to perform DSP configuration and initialization. - -At run-time, IPC is used for streaming control and buffer management, as well as for firmware traces. - -IPC Hardware Implementation -=========================== - -On most systems, the DSP and the host CPUs can access the same memory, such as where the DSP is implemented as a PCI device on the host system. On other systems, the DSP is implemented as a stand-alone device, connected to the host by a serial bus such as SPI. - -Intel IPC -========= - -At the hardware level, IPC support is implemented using a set of doorbell -registers and mailbox buffers. Details of the implementation can vary between -architectures. In general, sending an IPC message and replying to it involves -the following steps: - -#. If the IPC message is supposed to contain a payload, which is almost always the case with SOF, the initiator first copies the payload to the respective mailbox buffer. -#. The initiator sets a BUSY bit in an initiator-side IPC register, which then sets a BUSY bit on the target side. -#. If configured, this can also generate an interrupt on the target side. -#. When the target completes processing the received message, it clears the BUSY bit on its own side. This is then reflected to the initiator side, where as a result the BUSY bit is cleared and the DONE bit is set. -#. Setting the DONE bit can also generate an interrupt on the initiator side. -#. The initiator processes the reply from the target and clears the DONE bit. - -SOF on both the host and the DSP serializes the sending of their IPC messages. Therefore, a new message cannot be initiated before the target has finished processing the previous one. However, both the host and the DSP can initiate their messages simultaneously. This cannot lead to a race because both the host and the DSP have separate target and initiator IPC registers. - -.. note:: The IPCCTL register is common for target and initiator operations - and is used to mask and unmask BUSY and DONE interrupts. Therefore, in - theory, a race is possible where one context would try to mask or unmask - one of the bits (e.g. BUSY) while a different context, running on a - different core, would try to mask or unmask the other bit (DONE). This - can lead to inconsistent register contents. To avoid this, the software - has to make sure to lock the read-modify-write operations on the IPCCTL. - -SPI -=== - -IPC messages have the same structure as in the PCI case, but they are sent and received over an SPI bus. The SPI transfer is always initiated by the SPI provider, which is the host. Therefore, the DSP cannot send asynchronous messages to the host using only the SPI bus. To overcome this limitation, an additional GPIO line is used by the DSP to trigger an interrupt on the host to request it to read out an IPC message. Support for such devices is still experimental in SOF. Details will be added later. - -iMX IPC -======= - -Information on this subject matter is forthcoming. - -IPC Messages -============ - -IPC messages are divided into several groups: global reply, topology, power management, component, stream, DAI, trace, and a separate "firmware ready" message. Multiple messages can also be grouped into a message that belong to a compound group. For all IPC message definitions, see ``include/sound/sof/header.h``. Most messages are sent by the host to the DSP; only the following messages are sent by the DSP to the host: - -- firmware ready: sent only once during initialization -- trace: optional, contains firmware trace data -- position update: only used if position data cannot be transferred in a memory window or if forced by the kernel configuration - -PCM Driver -********** - -The SOF PCM driver creates ALSA PCMs, DAPM, and kcontrols based on the -:ref:`topology` data loaded at runtime. The PCM driver also allocates -buffers for DMA and registers with runtime PM. It contains architecture- -and platform-generic code. The PCM driver implements the low-level -functions defined by the ALSA PCM middle layer in ``struct -snd_pcm_ops``. These functions implement the platform-generic parts and -invoke platform-specific ops to access the hardware. - -When the machine driver is probed and the sound card is registered, the SOF PCM component driver gets probed when the dai links in the sound card are bound to the card. The SOF PCM component probe callback loads the topology file for the DUT. The SOF topology defines the audio processing pipelines, FE DAIs, and the BE DAI configuration for the BE dai links defined in the machine driver. Therefore, it is important to make sure that the DAI link IDs for the BE DAIs are identical in the topology and the machine driver. A mismatch in the DAI links ID will cause the sound card registration to fail. - -Topology Loading -================ - -The SOF PCM component probe invokes ``snd_sof_load_topology()`` to load the topology binary and triggers the parsing and loading of all the defined components. The topology operations pertinent to the loading/unloading of the various topology components are defined in ``struct snd_soc_tplg_ops`` in ``topology.c``. The topology parser invokes these callbacks to perform driver-specific loading operations for each component/widget. The load callback for each type of component in topology performs two main functions: - -#. Parse the component specific tokens associated with the component and populate the IPC structure. -#. Send the IPC to the DSP to set up, configure, and link the components. - -The unload callback is responsible for freeing the memory associated with the component and remove it from the list of components. Currently, the SOF driver supports loading only one topology file during boot up. This might be extended in the future to support multiple topologies that can be dynamically loaded/unloaded at runtime. - -The topology file also defines the IO callbacks for the kcontrols supported by the SOF topology, namely mixer, enum, and byte controls. - -Kcontrol IO ------------ - -The kcontrol IO callbacks are all defined in ``control.c``. The three types of kcontrol supported by SOF are: - -#. Volume: The volume kcontrol put callback is responsible for translating the user setting for volume level to the appropriate dB value and sending the IPC to the DSP. The get callback reads the volume dB value set in the DSP and determines the appropriate user space setting. -#. Enum: The enum put callback reads the user set value of the enum kcontrol and sends the IPC to the DSP to set the corresponding value in the FW. The get callback reads the enum value from the DSP and updates the user space setting. -#. Bytes: The byte control put callback is used for passing binary data from the user to the DSP FW. Depending on the size of the binary data being sent, the driver splits the data across multiple IPC messages. The FW is responsible for consolidating the data at the other end when the last segment of the data has been received from the host. The get callback gets the binary data from the DSP and passes it to the user space. As with the put callback, this is accomplished either in a single IPC or multiple IPCs, depending on the size of the binary data being read. - -Stream Management -================= - -The SOF PCM driver handles all stream control operations initiated by ALSA such as pcm open, close, hw_params, and trigger start/stop. It includes the code for the generic PCM operations while invoking the platform-specific callbacks to access the hardware. - -PCM open/close --------------- - -When a pcm is opened, the SOF pcm open ``ioctl`` assigns the stream for the host DMA and the stream is released when the pcm is closed. - -PCM HW Params/Free ------------------- - -During the hw_params step, the SOF PCM driver performs the following operations: - -#. Allocates audio buffer pages. -#. Invokes the platform-specific stream hw_params op. For SKL+ platforms, this involves decoupling host and link DMA engines, resetting the streams, setting up and programming the BDLs, and enabling the DMA interrupts. -#. Sends IPC to the FW to set up the stream params in the DSP. - -The PCM free ``ioctl`` undoes the operations performed during hw_params. - -PCM Trigger ------------ - -When the trigger ``ioctl`` is invoked, the SOF PCM driver invokes the platform-specific stream trigger operation and then sends the corresponding stream trigger IPC message to the DSP. The platform-specific stream trigger operation is responsible for starting/stopping the stream DMA, depending on the trigger command being invoked. - -PCM Prepare ------------ - -The SOF PCM driver does not advertise ``SNDRV_PCM_INFO_RESUME`` in the runtime configuration for pcm streams. This means that upon resuming from system suspend, the streams that were active prior to suspend will be restarted instead of being resumed. Therefore, when restarting the suspended streams, the hw_params needs to set up again before triggering them. The SOF driver utilizes the prepare ``ioctl`` that is invoked upon resuming to determine if the hw_params needs to set up again or not. - -Power Management -**************** - -Overview -======== - -The SOF framework implements the standard Linux kernel power management interface for devices. The SOF core exports the following standard methods: - -- snd_sof_runtime_suspend() -- snd_sof_runtime_resume() -- snd_sof_suspend() -- snd_sof_resume() - -On Intel HDA platforms, the PCI device registered in ``linux/sound/soc/sof/sof-pci-dev.c`` uses the above exported symbols to fill the Linux PM struct ``dev_pm_ops``. - -SOF is configured to support both system sleep and runtime power management. In a typical configuration, the SOF device is runtime-suspended if no ALSA PCM streams are active and no ALSA mixer controls (kcontrols) are used by user space applications. Currently for Intel platforms, the only two power states supported for the DSP are D0 (DSP is on) and D3 (DSP is powered off). - -Suspend Flow -============ - -- Firmware trace is released (if enabled). -- Debugfs state is cached (if enabled, affects debugfs nodes linked to DSP memory that will lose its state in suspend). -- Context-save IPC (SAVE_CTX) message is sent to firmware to notify the DSP of upcoming D3 entry. -- DSP-specific suspend flow is run. - - - On the Intel HDA; this involves logic to reset the HDA controller, disable IRQs, and power down the DSP cores. - - Runtime and system suspend flows have their own code paths. - -Resume Flow -=========== - -- DSP specific resume flow. - - - On Intel HDA, this involves logic to take the HDA controller out of reset, power up the DSP cores, and enable IRQs. - - Runtime and system resume flows have their own code paths. - -- Firmware boot -- Firmware trace is re-enabled (if configured). -- Existing PCM pipelines are restored to the firmware, using cached data maintained in the SOF driver (see sof_restore_pipelines()). -- Kcontrol values are restored from the cached data. -- Resume is completed by notifying the firmware with the Context Restored (CTX_RESTORE) IPC message. - - -Interaction with Codec Drivers -============================== - -The audio codec drivers (compliant with the ALSA ASoC framework) are created as children of the SOF platform device in the Linux device hierarchy. While the codec drivers (located typically under ``linux/sound/soc/codecs/``) manage their power flows independently, the parent-child relationship guarantees ordering between SOF platform device and the codecs. For suspend, the codecs are suspended before the SOF platform device and, similarly for resume, the platform driver is resumed first and then the codec driver. - -Intel Drivers -************* - -Intel HDA SOF DSP Platform Driver -================================= - -SOF implementation for Intel platforms is performed by the DSP Platform drivers. A platform driver implements the generic SOF ``struct snd_sof_dsp_ops`` interface, including functions such as doorbell, IPC messages send and receive, firmware load, and power up/down. The platform implements these methods for a given hardware target. The Intel platform drivers are located in the ``linux/sound/soc/sof/intel/`` folder of the Linux kernel tree. - -Intel HDA DSP Driver for CNL/CML/WHL -==================================== - -The hardware interface for the Cannon Lake, Comet Lake, and Whiskey Lake platforms are defined in the ``linux/sound/soc/sof/intel/cnl.c`` file. For simplicity, all three platforms will be addressed with the CNL acronym in this section. This file defines the DSP ops required for initializing the SOF driver. Most of the DSP ops for the CNL are shared with the other Intel HDA platforms such as APL. The key changes in the CNL DSP driver are the doorbell registers and the corresponding IPC IRQ implementation. - -Intel Machine Drivers -===================== - -The ALSA SoC Layer (ASoC) includes machine drivers. A machine driver glues together various software components (e.g. drivers for codecs, platforms, and digital audio interfaces), describes the relationships between the components, and registers the result as an ALSA sound card to the kernel. A machine driver can be generic, handling a family of similar systems, or can be very specific, targeting a single product. - -A set of machine drivers is included in the Linux kernel and provides support for a variety of systems with the Intel Audio DSP. These drivers are located in ``linux/soc/intel/boards``. The generic SOF HD-Audio machine driver (``skl_hda_dsp_generic.c``) can handle any system that meets the following criteria: - -- HDMI/DP codec in Intel Graphics -- Optional: 1 external HDA codec -- Optional: 1 to 4 digital microphones directly connected to PCH (not via codec) - -If the system has any I2S audio codecs or MIPI SoundWire codecs, the generic HD-Audio machine driver cannot be used and a dedicated machine driver is required instead. - -.. note:: Some existing machine drivers were previously developed for Intel closed source audio firmware (SST firmware, Intel® Smart Sound Technology). The SOF platform driver works with the existing machine drivers and requires no changes. The one big difference, though, is that the SOF PCM driver ignores the FE DAI links defined in the machine driver and overrides them with the ones defined in the SOF topology. - -Support for High Definition Audio (HD-Audio) -******************************************** - -Generic HD-Audio Support -======================== - -The Intel HD Audio controller is the standard audio host controller widely adopted in the PC platform; the industry standard Intel HD Audio driver software is available for Linux-based OSs. This driver is often referred to as the legacy HD-Audio driver. HDA DMA is used to transmit data between the host memory and the HD-A bus, and then to the external HDA codecs. - -On Intel’s platforms after Skylake (SKL+ platforms), the HDA controller is converged with the Audio DSP, and the HDA DMA is split into two parts, the host DMA and the link DMA. The host DMA is used to transmit data between the host memory and DSP memory so data can be processed by DSP firmware. The link DMA is used to transmit data between the DSP memory and the ``HDA/iDisp/I2S/SoundWire`` bus (and then to the ``HDA/HDMI/I2S/SoundWire`` codecs). The SOF driver plus firmware can support this HDA DSP-converged architecture. - -In the Linux ALSA framework, use of the audio DSP is optional. The common HDA library (hdac library, in ``sound/hda/``) is designed for both legacy HDA and HDA via Audio DSP support. It implements the HDA framework-level support, including the HDA bus, the HDA controller, and the HDA stream management. - -In SOF, the HDA driver (``sound/soc/sof/intel/hda*.c``) uses the hdac library to initialize the HDA bus and controller, probe codecs, and add SOF-specific stream management. Please note that HDA controller initialization and stream management are mandatory for Intel SKL+ platforms even if no HDA/HDMI-codec support is required, because the host DMA and stream control registers are part of HDA controller. - -The Legacy HD-Audio driver and SOF driver can coexist in one Linux distribution. The ``snd-intel-dspcfg`` kernel driver implements logic to select the correct driver based on ACPI table contents and platform capabilities detected at runtime. For example, if no specific configuration is defined in ACPI tables and digital microphones are directly attached to the PCH (Intel Platform Control Hub), an audio DSP is required and thus the SOF driver is chosen automatically. - -HD-Audio Codec Support -====================== - -In ASoC, the HD-Audio codec is implemented in ``hdac_hda.c`` in the ``soc/codec`` directory. It reuses the legacy HD-Audio codec driver and implements the features required by ASoC, such as registering the audio codec component driver, dapm routes, and codec dai operators. Three dai links are supported: Analog, Digital, and Alt Analog codec dai. Since power management is implemented in the legacy hda codec driver, there is no PM function in this codec driver. - -Display Audio Support -===================== - -SOF also supports the Intel i915 audio codec driver. The Intel HDMI audio codec driver supports HDMI audio, Single Stream Transport (SST) Display Port (DP) audio, and Multi Stream Transport (MST) DP audio. It fully supports 3+ PCM playback streams; it does not support capture streams. - -When an HDMI/DP display with audio support is connected, it is attached to a free ALSA PCM node from the pool of nodes reserved for HDMI. The status of HDMI/DP PCM connections is exposed via the ALSA mixer card controls **HDMI/DP,pcm=X Jack**, where X is the PCM device number. When a connection is detected, another ALSA mixer PCM control, **name='ELD',device=X**, describes the connected monitor. This data is formatted as ELD data (**EDID Like Data**, where EDID is Extended Display Identification Data), as defined in the `HDA `_ specification. - -Starting with Linux kernel version 5.5, HDMI/DP audio is implemented with an architecture that is similar to other HDA codecs. Implementation of the HDMI/DP codec is in ``snd-hda-codec-hdmi`` (``sound/pci/hda/patch_hdmi.c``). - -In older versions of Linux, a dedicated codec driver was used (``sound/soc/codec/hdac_hdmi.c``) but is now deprecated. - -Dependency on Intel Graphics Driver (i915) ------------------------------------------- - -The HDMI/DP audio codec is integrated in the graphics card. This means the SOF HDMI/DP audio codec driver directly depends on the Intel i915 graphic driver. - -The graphics driver and the HDMI/DP audio codec driver use the “component” model to handle the upper communication between the graphics driver and the audio driver. The graphics driver is bound to the audio driver as a component. This interface is used to request power, clocks, get notifications of monitor connection changes, and to get access to auxiliary information about the monitor. The main structure that is used in the graphic and audio communication is ``struct drm_audio_component``. Refer to ``drm_audio_component.h`` for more information on the structure. - -The graphics card includes an Audio Power Domain which is dedicated to the audio power setting. Any audio operation on the HDMI/DP audio codec requires the Audio Power Domain to be turned on. After an operation, the audio driver should turn off the Audio Power Domain. The HDMI/DP audio codec clock domain is located in the graphic card. Whenever the audio sample rate/bit rate is changed, the audio driver requires the graphic driver to modify the clock setting correspondingly. - -Audio for DisplayPort Multi-Stream Transport (DP-MST) ------------------------------------------------------ - -The Multi-Stream Transport (DP-MST) feature was first introduced in the DP 1.2 specification. It allows graphics to transfer multiple streams on a single connection. In a typical implementation, the multiplexed stream is terminated at a DP-MST hub which routes the individual streams into separate displays. - -The SOF HDMI/DP audio codec driver handles DP-MST audio streams transparently, and a DP-MST is treated in a similar way as any HDMI or DP-SST stream. - -.. note:: With Linux kernel versions 5.4 and older, the HDMI/DP implementation is using another codec driver and DP-MST interface to user-space is difference. With the old codec implementation, user-space software can determine the connection matrix between the monitors and the DP-MST port though **Pin#n-Port#m Mux** kcontrols in the alsamixer tool. - -Kernel Configuration/Kconfig -**************************** - -Refer to the `README `_ file of the SOF kconfig repository. - -Debug Options -************* - -SOF provides multiple options to enable developers to quickly bring up new platforms and debug errors/crashes that occur during audio test cases. The most notable ones are as below: - -Nocodec Mode -============ - -The no-codec mode is specifically meant for speeding up the process of bringing up SOF on new platforms. This mode enables developers to quickly verify basic audio functionality on the available Digital Audio Interfaces (DAI) on the platform. This is also useful to rule out issues due to potential errors in the codec drivers. - -Debugfs -======= - -SOF exposes several memory windows to the user space through the kernel debugfs filesystem. Developers can read or dump out the contents of these debugfs entries to infer the state of the DSP in case of a panic or a crash. Some of the most useful debugfs entries SOF exposes are mailbox, exception, and trace. - -Firmware Tracing -================ - -The tracing feature in the SOF firmware allows the DSP to send trace messages to the host. This tracing feature fills in for the lack of a printf feature while executing firmware code on the DSP. The host configures and sets up the DMA buffer for receiving the trace messages from the DSP. Once the trace DMA triggers, the DSP periodically initiates a DMA transfer to copy over the trace messages to the host. These messages can then be parsed using the sof-logger utility which prints out the messages in chronological order. - -More information is available in the firmware debuggability sections for :ref:`dbg-traces` and :ref:`dbg-logger`. - -IPC Flooding -============ - -The IPC flooding feature is useful to determine the throughput when sending IPCs from the host to the DSP at a very high rate. It is also useful for exposing race conditions which might cause IPC timeouts to occur. Two available options allow the user to either flood the DSP with a specified number of IPCs or flood the DSP with IPCs for the specified duration. - -Force IPC Position -================== - -Sending position update IPC from the firmware to the host is a generic method to generate period interrupts to meet the requirement from the ALSA IRQ mode (e.g. ``snd_pcm_period_elapsed()``). On some HDA-integrated platforms (e.g. Intel SKL+ ones), this interrupt can be generated using the `HDA `_ period IOC (interrupt on complete) and the real-time buffer pointers can be read back from the DPIB (DMA Pointer In Buffer). On these platforms, the position update IPC is only the fallback choice and is not used by default. - -In order to debug issues with IOC/DPIB, the force IPC position kernel -debug config can be selected. On Intel SKL- platforms, the stream -position update IPC is used whether or not this option is selected. diff --git a/developer_guides/tech/build-cmocka.rst b/developer_guides/tech/build-cmocka.rst deleted file mode 100644 index 03fee6a2..00000000 --- a/developer_guides/tech/build-cmocka.rst +++ /dev/null @@ -1,142 +0,0 @@ -.. _build-cmocka: - -Build Cmocka for Xtensa -####################### - -Cmocka for SOF is built automatically by default, however you may need a prebuilt version that can be used with :ref:`CMOCKA_DIRECTORY `. - -This article exaplains how to build Cmocka manually. -Please note that it currently works only for Xtensa xt-* toolchain. -Xtensa GCC toolchain is not supported yet. - -Cmocka fork -*********** - -We use our Cmocka fork that adds some options for embedded compilers: - -WITH_POSITION_INDEPENDENT_CODE - Some compilers cannot compile CMake's test program with PIC, - so you can disable it with this option. - -WITH_TINY_CONFIG - Usually compiler checks are cheap, so configuration is quick. - However many compilers are expensive to call, - so this option can be used to minimize checks count. - -WITH_SHARED_LIB - For compilers that cannot build shared libs and still want to - use make / make install for making prebuilt libs - -All changes made to Cmocka are enabled with these options, without them it works just like vanilla Cmocka. - -Clone repo and enter its directory, because all examples will be executed there: - -.. code-block:: bash - - git clone https://github.com/thesofproject/cmocka - cd cmocka - -Simple build on Linux -********************* - -On any system that CMake identifies as `UNIX `_, you can just call following -commands and it should work: - -.. code-block:: bash - - mkdir build && cd build - cmake \ - -DCMAKE_C_COMPILER=xt-xcc \ - -DWITH_STATIC_LIB=ON \ - -DWITH_SHARED_LIB=OFF \ - -DWITH_EXAMPLES=OFF \ - -DWITH_POSITION_INDEPENDENT_CODE=OFF \ - -DCMAKE_INSTALL_PREFIX=install \ - .. - make install - -Arguments used: - -CMAKE_C_COMPILER - We specify "xt-xcc" as compiler that CMake should use - to compile C files. -WITH_STATIC_LIB - By default static lib for Cmocka is not built, - so we enable it. -WITH_SHARED_LIB - By default Cmocka builds shared lib, but we don't want that. -WITH_EXAMPLES - Examples don't work without shared lib, so we disable them. -WITH_POSITION_INDEPENDENT_CODE - PIC will make CMake's testing programs - to fail, so disable it. -CMAKE_INSTALL_PREFIX - By default, it will go to host system binary files - (for example /usr/bin), we change it to "install", so **make install**, will - place output to **build/install** directory. This is the directory that you - can use as input for :ref:`CMOCKA_DIRECTORY ` in SOF build system. - -Cross-platform build -******************** - -In order to build Cmocka for generic system, you need to use -`CMAKE_TOOLCHAIN_FILE `_. - -Create **xt-toolchain-for-cmocka.cmake** file with following contents: - -.. code-block:: cmake - - # Generic because we build for embedded system - set(CMAKE_SYSTEM_NAME Generic) - # It should be always set when CMAKE_SYSTEM_NAME is changed - set(CMAKE_SYSTEM_VERSION 1) - - # Make CMake use "xt-xcc" for compiling C files - set(CMAKE_C_COMPILER xt-xcc) - # Override ar and ranlib tools that CMake should use for linking lib - set(CMAKE_AR xt-ar CACHE STRING "") - set(CMAKE_RANLIB xt-ranlib CACHE STRING "") - - # Cmocka is written in C99, but for some reason it sets this flag, only on Posix - # We set up it here, because our system is Generic - add_definitions("-std=gnu99") - -Now you can build Cmocka using file above (use correct path to your toolchain file): - -.. code-block:: bash - - mkdir build && cd build - cmake \ - -DCMAKE_TOOLCHAIN_FILE=/path/to/xt-toolchain-for-cmocka.cmake \ - -DWITH_STATIC_LIB=ON \ - -DWITH_SHARED_LIB=OFF \ - -DWITH_EXAMPLES=OFF \ - -DWITH_POSITION_INDEPENDENT_CODE=OFF \ - -DCMAKE_INSTALL_PREFIX=install \ - .. - make install - -After these commands are successfully completed, the Cmocka's static lib and -headers should be in **build/install**. - -Please note that commands above were for CMake's Make generator. -If you are using Windows and want to use Ninja, your commands will -look more like: - -.. code-block:: bash - - mkdir build && cd build - cmake \ - -DCMAKE_TOOLCHAIN_FILE=/path/to/xt-toolchain-for-cmocka.cmake \ - -DWITH_STATIC_LIB=ON \ - -DWITH_SHARED_LIB=OFF \ - -DWITH_EXAMPLES=OFF \ - -DWITH_POSITION_INDEPENDENT_CODE=OFF \ - -DCMAKE_INSTALL_PREFIX=install \ - -GNinja \ - .. - ninja install - -.. note:: - - You can use -DWITH_TINY_CONFIG=ON, if configuration step takes too much time. diff --git a/developer_guides/firmware/cmake.rst b/developer_guides/tech/cmake.rst similarity index 100% rename from developer_guides/firmware/cmake.rst rename to developer_guides/tech/cmake.rst diff --git a/faq/index.rst b/faq/index.rst index 9a134303..5073c3d0 100644 --- a/faq/index.rst +++ b/faq/index.rst @@ -9,40 +9,6 @@ This page addresses common architectural, algorithmic, development, and licensin :local: :depth: 2 -General & Architecture -********************** - -What is Sound Open Firmware (SOF)? -================================== -Sound Open Firmware (SOF) is an open-source, vendor-neutral audio Digital Signal Processing (DSP) firmware infrastructure, SDK, and host driver framework governed under the Linux Foundation. It enables deterministic, ultra-low-latency, power-efficient audio signal processing across personal computers, smartphones, smart speakers, automotive infotainment, and embedded microcontrollers. - -How does SOF differ from traditional audio DSP firmware? -======================================================== -Traditional audio DSP solutions rely on proprietary, closed-source binary blobs supplied by silicon vendors, offering little transparency, rigid pipeline configurations, and high friction for custom audio algorithms. SOF is: - -* **Open and Permissive**: Built with transparent BSD 3-Clause and MIT code, allowing developers to inspect, modify, debug, and optimize every line of firmware code. -* **Architecture-Independent**: Operates seamlessly across Tensilica Xtensa, ARM Cortex-M, and RISC-V DSPs. -* **Decoupled from Firmware**: Uses dynamic ALSA Topology (Topology 2) rather than hardcoded C pipelines, enabling dynamic runtime graph instantiation. -* **Upstream First**: Supported natively in upstream Linux kernel releases (``sound/soc/sof/``). - -What deployment models does SOF support? -======================================== -SOF supports two foundational architectures: - -* **Host-Based Architecture**: Coupled to a host application processor running **Linux**, **Android**, or **ChromeOS**. The host OS driver stack controls power states (D0ix/D3) and streams PCM audio over DMA windows via IPC (IPC3/IPC4). -* **Hostless (Standalone / Embedded) Architecture**: Runs autonomously on microcontrollers and embedded DSPs (such as **ESP32-P4** or **Teensy 4.1 / i.MX RT1062**) atop the Zephyr RTOS, streaming audio directly between physical peripherals (I2S, PDM, Bluetooth) using static ROM topologies without requiring a host PC. - -Which Real-Time Operating System (RTOS) does SOF use? -===================================================== -Modern SOF releases run natively on the **Zephyr RTOS**, providing robust hardware abstraction layers (HAL), POSIX thread synchronization primitives, dynamic device drivers, and real-time scheduling. Legacy deployments also support Cadence Xtensa XTOS. - -Which IPC protocols are supported? -================================== -SOF supports two Inter-Processor Communication (IPC) protocols: - -* **IPC4**: A structured, multi-part messaging protocol designed for modern Intel (cAVS 2.5+, ACE 1.x, ACE 3.x) and AMD platforms. It supports granular pipeline gating, modular dynamic loading, and multi-core scheduling. -* **IPC3**: A lightweight, mailbox-based message protocol used across earlier Intel CAVS architectures and legacy embedded DSP targets. - Audio Processing & Module Development ************************************* @@ -59,16 +25,9 @@ Yes. Because the SOF firmware core is licensed under the permissive **BSD 3-Clau What audio processing components are available out-of-the-box? ============================================================== -SOF includes a rich catalog of production-grade audio processing components: - -* **Core Mixing & Routing**: Volume control with smooth volume ramping, multi-channel Mixers, Matrix Mixers, Demux, and Multiplexers. -* **Sample Rate Conversion**: High-order polyphase fractional and synchronous Sample Rate Converters (SRC). -* **Acoustic Tuning**: Parametric IIR/FIR Equalizers (EQ) and multi-band Dynamic Range Control (DRC). -* **Voice & Spatial Processing**: Directional Microphone Beamforming (TDFB), Acoustic Echo Cancellation (AEC), and Wake-on-Voice (WoV). -* **Hardware-Accelerated Codecs**: MP3 and AAC decoders optimized for Tensilica Vector Floating-Point Units (VFPU). -* **Spatial Audio**: Valve Steam Audio HRTF 3D binaural spatial rendering. - -Refer to the :ref:`Audio Algorithms & Features Catalog ` for technical specifications and testbench instructions. +For the complete catalog of production-grade audio processing components, +codecs, filters, and dynamic modules available out-of-the-box in SOF, +refer to the :ref:`Audio Processing Modules Catalog `. How are audio signal pipelines defined? ======================================= @@ -79,13 +38,235 @@ Hardware & Platform Support Where can I review hardware compatibility? ========================================== -The living :ref:`Supported Platforms Matrix ` details all supported silicon architectures, core frequencies, memory tiers, audio interfaces, and IPC protocols across: - -* **Intel Platforms**: Tiger Lake (TGL / CAVS 2.5), Meteor Lake (MTL / ACE 1.5), Arrow Lake (ARL-S / ACE 1.5), Lunar Lake (LNL / ACE 2.0), and Panther Lake (PTL / ACE 3.0). -* **AMD Platforms**: Renoir, Rembrandt, Phoenix, and Strix. -* **NXP Platforms**: i.MX8, i.MX8M, and i.MX9. -* **MediaTek Platforms**: MT8195 and MT8186. -* **Embedded Microcontrollers**: NXP i.MX RT1062 (**Teensy 4.1**) and Espressif **ESP32-P4** RISC-V audio bridges. +Hardware compatibility for SOF is documented across two primary references: + +* **SOF Supported Platforms Matrix**: Refer to the :ref:`platforms` page for + detailed specifications of all silicon targets, DSP architectures, memory + tiers, audio interfaces (SoundWire, I2S, PDM, HDA), and IPC protocols. +* **Zephyr Project Supported Boards & Platforms**: Because modern SOF firmware + is built upon the Zephyr RTOS, it can be ported and executed across any + architecture, SoC, or board supported by upstream Zephyr. Refer to the + `Zephyr Supported Boards Catalog `_ + for the complete upstream hardware list. + +Why does my audio work on Windows, but not on Linux? +==================================================== +A frequent point of confusion for users installing Linux on a consumer PC or laptop +is finding that the internal speakers, headphone jack detection, or microphone array +do not function out-of-the-box, even though the device worked perfectly on Windows. + +To understand why this happens, it is important to recognize that modern PC and laptop +audio is not a single standardized, plug-and-play device (unlike USB audio devices +or NVMe drives). Instead, it is an embedded-style subsystem with massive hardware +differentiation and complex physical interconnects customized by the original equipment +manufacturer (OEM) for every specific motherboard model: + +* **Diverse Audio Codecs**: + Laptops incorporate diverse codecs from various vendors—such as Realtek + (ALC287, ALC5682, ALC295), Cirrus Logic (CS42L42), Everest Semiconductor + (ES8336), Conexant, or ESS. +* **Smart Speaker Amplifiers**: + Internal laptop speakers typically require discrete smart amplifiers—such as + Texas Instruments (TAS2781), Cirrus Logic (CS35L41), or Maxim Integrated (MAX98373). + These amps communicate over I2C, SPI, or SoundWire and require customized firmware + calibration blobs, speaker protection parameters, and real-time voltage/current + (Vmon/Imon) feedback monitoring. +* **Complex Audio Interfaces**: + A single laptop design often routes audio across multiple distinct buses: + MIPI SoundWire for smart amplifiers, I2S/TDM for the audio codec, PDM for 2-channel + or 4-channel digital microphone arrays, and Intel HD-Audio (HDA) for display/HDMI audio. +* **Multi-Point Clock Trees**: + Buses require intricate clock distribution across Main Clocks (MCLK), Bit Clocks (BCLK), + Word Clocks (WCLK/FS), and internal PLLs, where either the SoC or the peripheral can act + as the clock provider. +* **SoC and Codec/Amp GPIO Control Lines**: + Discrete GPIO pins must be toggled in precise power-up sequences to enable external + speaker amplifier power rails, reset smart amplifier ICs, switch speaker mute gates, + power microphone bias voltages, and control camera/mic privacy LEDs. +* **Jack Detection & Impedance Sensing**: + The 3.5mm combo audio jack relies on dedicated interrupt lines (GPIOs) and internal + comparator circuits to detect jack insertion, differentiate 3-pole TRS headphones + from 4-pole TRRS headsets with microphones, and sense multi-button in-line remote + presses (volume up/down, hook switch). + +.. graphviz:: + :caption: Figure: Hardware Complexity and the Critical OEM Board Integration Layer + + digraph oem_audio_complexity { + rankdir=TB; + nodesep=0.35; + ranksep=0.45; + + node [fontname="Verdana", fontsize=9, shape=box, style="filled,rounded", height=0.38]; + edge [fontname="Verdana", fontsize=8]; + + // SoC + subgraph cluster_soc { + label = "Host SoC (Intel / AMD)"; + style = "filled,rounded"; + color = "#1f618d"; + fillcolor = "#ebf5fb"; + fontname = "Verdana-Bold"; + fontsize = 10; + fontcolor = "#154360"; + + soc_dsp [label="Audio DSP Engine\n(SOF / Generic Driver)", fillcolor="#d4e6f1"]; + soc_buses [label="Audio Buses\n(SoundWire, I2S, PDM, HDA)", fillcolor="#d4e6f1"]; + soc_clocks [label="Clock Generators\n(MCLK, BCLK, WCLK, PLLs)", fillcolor="#d4e6f1"]; + soc_gpios [label="SoC GPIO Controller\n(Reset, Enable, IRQs)", fillcolor="#d4e6f1"]; + + { rank=same; soc_dsp; soc_buses; soc_clocks; soc_gpios; } + } + + // OEM Integration Layer + subgraph cluster_integration { + label = "The OEM Board Integration Layer (Motherboard Wiring & Mappings)"; + style = "filled,rounded,dashed"; + color = "#c0392b"; + fillcolor = "#fdf2e9"; + fontname = "Verdana-Bold"; + fontsize = 10; + fontcolor = "#78281f"; + + acpi_dsd [label="ACPI _DSD / Platform Mappings\n(Audio Interface Routing, Endpoints)", fillcolor="#fadbd8"]; + gpio_routing [label="GPIO & Power Routing\n(Amp Power, Reset, Jack IRQ)", fillcolor="#fadbd8"]; + clock_tree [label="Clock Tree Configuration\n(Provider/Consumer, Frequencies)", fillcolor="#fadbd8"]; + ucm_quirks [label="ALSA Machine Driver & UCM\n(Channel Maps, Controls, Mixers)", fillcolor="#fadbd8"]; + + { rank=same; acpi_dsd; gpio_routing; clock_tree; ucm_quirks; } + } + + // Peripherals + subgraph cluster_hw { + label = "Differentiated Motherboard Hardware"; + style = "filled,rounded"; + color = "#27ae60"; + fillcolor = "#eafaf1"; + fontname = "Verdana-Bold"; + fontsize = 10; + fontcolor = "#145a32"; + + codecs [label="Audio Codecs\n(Realtek, Cirrus, Everest)", fillcolor="#d5f5e3"]; + smart_amps [label="Smart Amplifiers\n(TI, Maxim, Cirrus + Vmon/Imon)", fillcolor="#d5f5e3"]; + jack_hw [label="3.5mm Combo Jack\n(Impedance Sense, Mic Bias)", fillcolor="#d5f5e3"]; + mic_array [label="Digital Mic Array\n(2-ch / 4-ch PDM)", fillcolor="#d5f5e3"]; + speakers [label="Internal Speakers\n(Woofer / Tweeter Array)", fillcolor="#d5f5e3"]; + + { rank=same; codecs; smart_amps; jack_hw; mic_array; speakers; } + } + + soc_buses -> acpi_dsd [color="#2980b9", penwidth=1.5]; + soc_clocks -> clock_tree [color="#2980b9", penwidth=1.5]; + soc_gpios -> gpio_routing [color="#2980b9", penwidth=1.5]; + soc_dsp -> ucm_quirks [color="#2980b9", penwidth=1.5]; + + acpi_dsd -> codecs [color="#e74c3c", penwidth=1.5]; + acpi_dsd -> smart_amps [color="#e74c3c", penwidth=1.5]; + clock_tree -> codecs [color="#e74c3c", penwidth=1.5]; + clock_tree -> smart_amps [color="#e74c3c", penwidth=1.5]; + gpio_routing -> smart_amps [color="#e74c3c", penwidth=1.5]; + gpio_routing -> jack_hw [color="#e74c3c", penwidth=1.5]; + acpi_dsd -> mic_array [color="#e74c3c", penwidth=1.5]; + smart_amps -> speakers [color="#27ae60", penwidth=1.5]; + codecs -> jack_hw [color="#27ae60", penwidth=1.5]; + } + +The Upstream Driver Reality vs. OEM Integration +----------------------------------------------- +The CPU vendors (Intel, AMD) and codec/amplifier vendors (Realtek, Cirrus Logic, +Texas Instruments, etc.) **do provide good quality, battle-tested generic drivers +upstream in the Linux kernel** (such as ``sound/soc/sof/`` and ``sound/soc/codecs/``). + +However, these generic drivers cannot predict how an OEM has physically wired a +specific laptop. They lack the crucial **OEM board-level integration** that maps: + +1. Which specific GPIO lines on the SoC or codec correspond to amplifier resets, power + enables, or headset jack interrupts. +2. Which I2C/SPI bus or SoundWire link ID the smart amplifiers reside on. +3. Which clock rates and provider/consumer clock modes are wired between the SoC and codec. +4. How audio channels, speaker volumes, and mixer controls should be configured in + the ALSA Use Case Manager (UCM). + +OEM vs. User-Installed Operating Systems +---------------------------------------- +* **Windows & Devices That Ship With Linux**: + On Windows, and on commercial laptops that **ship with Linux pre-installed from + the factory** (such as Chromebooks, Dell Developer Editions, or certified Lenovo + ThinkPads), this hardware integration is performed directly by the OEM/ODM. + The manufacturer provides custom ACPI tables (including ``_DSD`` Device-Specific + Data properties), firmware calibration tables, and driver mapping configurations + designed specifically for that platform. + +* **Devices Where Linux Is Installed by the User as a Second OS**: + When a user purchases a standard Windows laptop and installs Linux as a dual-boot + or secondary OS, **no OEM integration has been done for Linux**. The device's + ACPI firmware typically only contains Windows-proprietary AML methods and expects + proprietary Windows INF files and registry configurations. + +Consequently, when booting generic Linux on an arbitrary consumer laptop, **it is +purely by luck that driver features work with unknown board configurations**—unless +the manufacturer happened to follow a standard silicon reference schematic, or +upstream kernel community developers have manually reverse-engineered the board's +ACPI tables, submitted DMI machine quirks, or crafted custom ALSA UCM profiles. + +Why does ACPI audio data not match my audio hardware? +===================================================== +A frequent problem when running Linux as a secondary operating system on consumer +PCs and laptops is encountering BIOS/ACPI tables whose audio descriptions (such as +**NHLT**, **DISCO**, and ``_DSD`` tables) contradict the actual motherboard hardware. +For instance, the ACPI tables might describe four digital microphones when only two are +physically wired, declare the wrong I2S link format, or list SoundWire endpoints on +incorrect link IDs. + +The Root Cause: The Fast ODM/OEM Development Flow +------------------------------------------------- +Original Design Manufacturers (ODMs) and Original Equipment Manufacturers (OEMs) +operate under extremely aggressive product delivery schedules. When bringing up audio +on a new laptop model: + +1. **BIOS Tables Are Often Stale or Copied**: + Motherboard BIOS engineers frequently copy ACPI tables (including Intel/AMD + **NHLT** – *Non-HD Audio Link Table*, MIPI **SoundWire DISCO** – *Discovery and + Configuration* tables, and device-specific ``_DSD`` properties) from an earlier + reference design or older laptop model. +2. **Hardcoded Windows Driver Workarounds**: + Fixing mistakes in the motherboard BIOS requires cross-team firmware engineering + cycles, BIOS rebuilding, and extensive validation passes. To meet tight shipping + deadlines, **it is significantly faster and easier for the audio integration engineer + to simply hardcode the correct hardware parameters into the proprietary Windows driver, + INF installation script, or registry settings**. +3. **Windows Ignores the ACPI Bugs**: + Because the customized Windows driver explicitly overrides or bypasses the BIOS + tables using its hardcoded model profiles, audio works flawlessly on Windows despite + the inaccurate or corrupt ACPI tables underneath. + +The Impact on Linux-Based Devices +--------------------------------- +Unlike proprietary monolithic drivers, **Linux relies strictly on standards-based +hardware discovery**: + +* The upstream Linux kernel audio subsystem (``sound/soc/sof/``, ``sound/soc/intel/``, + and ``sound/soc/sdw/``) directly parses the BIOS ACPI data—including **NHLT** + endpoints and formats, **SoundWire DISCO** properties, and ``_DSD`` device parameters—to + dynamically instantiate the audio machine driver, configure clock dividers, discover + peripheral codecs, select matching topologies, and construct a working sound card. +* When the ACPI, NHLT, or DISCO data is incomplete, outdated, or wrong, Linux creates + audio interfaces with wrong bit depths, binds non-existent microphone channels, + or fails to enumerate codecs altogether, leading to silence, audio distortion, or + failed DSP probing. + +How Linux Developers Work Around Broken ACPI Data +------------------------------------------------- +Because end-users cannot easily rewrite their motherboard BIOS, upstream Linux audio +engineers and community contributors must reverse-engineer the actual hardware wiring +and implement software quirks: + +* **DMI Machine Quirks**: The Linux kernel maintains extensive quirk tables + (``dmi_system_id``) that match a laptop's manufacturer, product name, and BIOS version + to force the correct channel counts, GPIO pin assignments, or SoundWire link mappings. +* **NHLT & DSD Overrides**: When BIOS tables are irrecoverably broken, Linux audio + drivers implement fallback heuristics or load external ACPI DSD/SSDT overlays to + substitute correct hardware descriptors. Can SOF run without a host computer? ==================================== @@ -113,7 +294,7 @@ SOF provides two simulation options: How do I capture DSP firmware logs and trace data? ================================================== -SOF uses an efficient string dictionary extraction system (**smex**). Format strings are extracted from firmware ELF binaries during compilation into a dictionary file (``.ldc``), allowing the DSP to transmit compact numeric trace IDs over DMA without CPU overhead. On the host, tools such as **sof-logger** and the **TCP Probe Server** (port 9999) decode these trace packets in real time. +SOF uses an efficient string dictionary extraction system (**smex**). Format strings are extracted from firmware ELF binaries during compilation into a dictionary file (``.ldc``), allowing the DSP to transmit compact numeric trace IDs over DMA without CPU overhead. On the host, tools such as the **TCP Probe Server** (port 9999), DMA trace probes, and Zephyr log decoders decode these trace packets in real time. Licensing & Community Governance ******************************** diff --git a/getting_started/index.rst b/getting_started/index.rst index 65ba0480..49314374 100644 --- a/getting_started/index.rst +++ b/getting_started/index.rst @@ -91,7 +91,7 @@ The SOF SDK provides a complete toolkit connecting source code authoring to comp fontsize = 10; fontcolor = "#4a235a"; - runtime_diag [label="Live Probing & Telemetry\n(TCP Probe Server 9999, sof-logger)", width=3.3, fixedsize=shape, fillcolor="#d2b4de"]; + runtime_diag [label="Live Probing & Telemetry\n(TCP Probe Server 9999, DMA Probes)", width=3.3, fixedsize=shape, fillcolor="#d2b4de"]; sim_qemu [label="QEMU DSP Simulators\n(ptl-sim, tgl-sim in CI)", fillcolor="#d7bde2"]; dut_boards [label="Target DUTs & Hardware Boards\n(Spider TGL, Dragon Fly ARL, Aphid PTL, Teensy 4.1)", width=3.3, fixedsize=shape, fillcolor="#d2b4de"]; @@ -137,7 +137,7 @@ Core SDK Ingredients * **Firmware Packaging & Signing (`rimage`)**: Converts compiled ELF binaries into platform-specific signed manifests with optional security headers. -* **Trace & Log Decoding (`smex` & `sof-logger`)**: Extracts format strings from ELF binaries into a dictionary file (``.ldc``), allowing the DSP to transmit compressed numeric trace IDs decoded in real time on the host. SOF also integrates natively with **Zephyr logging and tracing capabilities** (including Zephyr log backends and dictionary-based logging) for unified system and driver diagnostics. +* **Trace & Log Decoding (`smex` & DMA Probes)**: Extracts format strings from ELF binaries into a dictionary file (``.ldc``), allowing the DSP to transmit compressed numeric trace IDs decoded in real time on the host. SOF also integrates natively with **Zephyr logging and tracing capabilities** (including Zephyr log backends and dictionary-based logging) for unified system and driver diagnostics. * **Real-Time Telemetry & Probing**: The TCP probe server captures raw, multi-channel DMA audio stream taps at runtime over TCP port 9999 without interrupting pipeline execution. diff --git a/index.rst b/index.rst index cd3aebe7..6d0a285a 100644 --- a/index.rst +++ b/index.rst @@ -29,7 +29,6 @@ Sound Open Firmware Documentation release.rst contribute/index.rst tsc/index.rst - maintainers/index.rst api/index.rst presentations/index.rst faq/index.rst diff --git a/maintainers/admin.rst b/maintainers/admin.rst deleted file mode 100644 index 450bc783..00000000 --- a/maintainers/admin.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _admin: - -SOF admin -######### - -Given the size of the project, maintainer rights are granted -to multiple contributors: - -+---------------+-------------------+---------------+ -| Intel | Lech Betlej | @lbetlej | -+---------------+-------------------+---------------+ -| Intel | Liam Girdwood | @lgirdwood | -+---------------+-------------------+---------------+ -| Intel | Marcin Maka | @mmaka1 | -+---------------+-------------------+---------------+ -| Intel | Ranjani Sridharan | @ranj063 | -+---------------+-------------------+---------------+ -| NXP | Daniel Baluta | @dbaluta | -+---------------+-------------------+---------------+ -| Google | Johny Lin | @johnylin76 | -+---------------+-------------------+---------------+ - -Administrators may override specific merge rules, for example merge a -PR even if it does not meet all criteria defined by a repository, but -will only do so for exceptional cases. - -Administrators can add new contributors to the project, define their -contributor levels and assign them to specific teams. diff --git a/maintainers/code_owners.rst b/maintainers/code_owners.rst deleted file mode 100644 index 13305699..00000000 --- a/maintainers/code_owners.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _code_owners: - - -SOF code owners -############### - -Each repository defines its own CODE_OWNER file, which identifies key -contributors and experts in each area of the SOF project. - -Code owners will be notified of each change to their respective -domains, and are encouraged to approve or provide feedback on -contributions being reviewed. - -Each repository in the SOF project may define their own rules, but the -general expectation is that Pull Requests are approved by 2 or more -code owners, maintainers or admin. diff --git a/maintainers/index.rst b/maintainers/index.rst deleted file mode 100644 index 0a7ed6bb..00000000 --- a/maintainers/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _maintainers: - - -SOF admin, maintainers and code owners -###################################### - -The SOF project defines administrators, grants key contributors merge -rights and defines code owners for each subsystem and technical area. - -.. toctree:: - :maxdepth: 1 - - admin.rst - merge_rights.rst - code_owners.rst diff --git a/maintainers/merge_rights.rst b/maintainers/merge_rights.rst deleted file mode 100644 index 72a2c105..00000000 --- a/maintainers/merge_rights.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _merge_rights: - -Merge rights -############ - -For the firmware tree, additional key contributors have merge rights -into the master branch: - -+---------------+-------------------+---------------+ -| Intel | Tomasz Lauda | @tlauda | -+---------------+-------------------+---------------+ -| Intel | Janusz Jankowski | @jajanusz | -+---------------+-------------------+---------------+ diff --git a/release.rst b/release.rst index 1b52522d..0305c88f 100644 --- a/release.rst +++ b/release.rst @@ -72,6 +72,7 @@ SOF binary releases follow a **Calendar Versioning (CalVer)** scheme: ``vYYYY.MM * **Major Releases** (``vYYYY.MM``): Published periodically (aligned with upstream Linux kernel and Zephyr LTS releases). * **Maintenance & Patch Releases** (``vYYYY.MM.patch``): Critical bug fixes, hardware workarounds, and topology updates published from dedicated stable branches (e.g. ``stable-v2025.12``). +* **Binary vs. Firmware Versioning**: Binary packages use CalVer (e.g. ``v2025.12.2``) and package specific upstream SOF firmware releases (e.g. ``v2.14.3``) along with matching topologies and kernel compatibility scripts. * **Daily CI Builds**: In addition to tagged releases, the `sof-bin main branch `_ is updated daily with verified builds from the firmware development tree. .. seealso:: diff --git a/scripts/generate_matrices.py b/scripts/generate_matrices.py index 5c5da31d..16a698c5 100644 --- a/scripts/generate_matrices.py +++ b/scripts/generate_matrices.py @@ -17,6 +17,7 @@ """ import json +import re import sys import urllib.request from pathlib import Path @@ -157,6 +158,21 @@ def generate_modules_table(): print(f"Generated {out_file} ({len(modules)} modules)") +def parse_fw_version(body): + if not body: + return "N/A" + matches = re.findall(r'SOF\s*(v?\d+\.\d+(?:\.\d+)?)', body, re.IGNORECASE) + matches += re.findall(r'https://github.com/thesofproject/sof/releases/tag/(v\d+\.\d+(?:\.\d+)?)', body) + normalized = [] + for m in matches: + norm = m if m.startswith('v') else 'v' + m + if norm not in normalized: + normalized.append(norm) + if normalized: + normalized.sort(key=lambda v: [int(x) for x in v.lstrip('v').split('.')], reverse=True) + return normalized[0] + return "N/A" + def generate_sof_bin_releases(): cache_file = DATA_DIR / "sof_bin_releases.json" releases = [] @@ -177,9 +193,11 @@ def generate_sof_bin_releases(): asset_url = a["browser_download_url"] asset_size_mb = round(a["size"] / (1024 * 1024), 1) break + fw_ver = parse_fw_version(r.get("body", "")) releases.append({ "tag_name": r.get("tag_name"), "name": r.get("name") or r.get("tag_name"), + "fw_version": fw_ver, "published_at": r.get("published_at", "")[:10], "html_url": r.get("html_url"), "asset_name": asset_name, @@ -207,27 +225,48 @@ def generate_sof_bin_releases(): out_file = DOCS_DIR / "_generated_sof_bin_releases.rst" latest = releases[0] + latest_fw = latest.get("fw_version", "N/A") with open(out_file, "w", encoding="utf-8") as f: # Latest Release Hero Card + fw_badge = "" + if latest_fw != "N/A": + fw_link = f"https://github.com/thesofproject/sof/releases/tag/{latest_fw}" + fw_badge = ( + f'' + f'Firmware {latest_fw} ↗' + ) + f.write(".. raw:: html\n\n") f.write('