Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

intel_debug: introduction: Add information about modular SOF release … #505

Merged
merged 1 commit into from
Dec 13, 2024
Merged

intel_debug: introduction: Add information about modular SOF release … #505

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 50 additions & 7 deletions getting_started/intel_debug/introduction.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,10 @@ User space and filesystem requirements
Selecting the SOF driver is not enough. Audio is properly configured only if
the following elements are present on the file system.

1. Firmware binary
1. Firmware
-----------

1.1. Base firmware
------------------

The firmware file, ``/lib/firmware/intel/sof/sof-tgl.ri`` (example
Expand All @@ -117,6 +120,46 @@ Linux kernel to query whether or not the firmware authentication is enabled,
which means `dmesg` logs cannot be provided to alert the user to an ME
configuration issue.

.. _loadable-libraries:

1.2. Loadable libraries
-----------------------

An IPC4 library is a container of a single or multiple modules (bundle) which
can be loaded to the firmware after it is booted up.
Library loading is supported on Meteor Lake (ACE1) or newer platforms.

Background information: the base firmware always resides in DSP SRAM while the
loaded library is stored in DRAM memory and only the needed code is copied to
SRAM for execution. By moving modules out from the base firmware to a library
can reduce the overall SRAM use depending on the device configuration and
topology.

See :ref:`llext_modules` for technical details.

1.3. Monolithic and modular SOF releases
----------------------------------------

SOF project releases for Intel platforms are either monolithic (only a single firmware binary) or modular (base firmware and external libraries).

1.3.1. Modular SOF releases
---------------------------

See :ref:`loadable-libraries` for details about library support in general.

The released libraries are:
- **sof-PLAT-openmodules.ri** : the bundle contains modules for audio processing not included in the base firmware
- **sof-PLAT-debug.ri** : the bundle contains modules that are needed for firmware debugging and profiling. Used by developers and for bug reporting if needed
- **UUID.bin** : Mainly 3rd party libraries identified by UUID. If the library contains multiple modules then a UUID symlink must be provided for each one.

Notes:
- The Kernel will attempt to load \*-openmodules.ri followed by \*-debug.ri from the library path after the base firmware boot if they exist.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So these are just libraries with symbols in them, and the fw core will load the symbols as needed? No UUID based loading, symlink or otherwise, required?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In case of modular SOF release the basefw and modules are in different libraries (note that the basefw itself is a library file).
The full SOF is basefw+openmodules+debug, this is what we have now as monolithic single basefw, it includes all modules.
Iow, to get the full SOF you need to boot the basefw and then load the modules from the external libraries.

The UUID based loading is still supported, but the full SOF is defined in case of modular release as basefw+openmodules+debug.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok. And all those three base-release libraries are loaded to SRAM at boot time, like the the older monolithic FW binary, no?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The basefw loaded (to SRAM) and booted, then we load the openmodules followed by the debug library, these will be loaded to DRAM. The modules that are needed for the audio stream will be loaded (by the firmware) from DRAM to SRAM for execution.
The monolithic firmware with all the modules are stored in SRAM.

The basefw is still special, it is the one that can boot and have all the needed infra (like the kernel in Linux). Instead of individual modules we can have module bundles.

At the end these form the SOF package either way: monolithic or modular.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I finally read the long mail thread about the subject from just before my vacation, and it answered some of my questions. But still, the modules in the open-modules-bundle are loaded as needed based on uuid's even if they are not needed for getting access to the library file itself, don't they?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, sof-bin release is not planned to have UUID symlinks to the openmodules.ri, it is going to be loaded unconditionally if it exists in filesystem.
We can only load library into firmware, the library can contain one or more modules (bundle). One can freely move modules between basefw and openmodules between releases, the whole package will contain all the needed modules.

I want to define this as simple as possible:
If sof-bin is monolithic for a platform then only the basefw will be on filesystem.
If sof-bin is modular for a platform then basefw+openmodules(+debug) will be on the filesystem.

The kernel shall load these unconditionally, which means that the kernel will treat the base libraries as optional, if they don't exist it is not an error since it is the monolithic release.

The kernel change will come after the agreement on the documentation and how the sof-bin is going to be released.

The kernel will still going to look based on UUID for missing modules but for a complete sof-bin release it is not really going to happen (apart from LNL which have one module outside as library).

- additional libraries referenced by topology files or drivers will be loaded based on the UUID of the module from the library path.


1.4 Firmware lookup paths
-------------------------

Linux SOF will look up firmware files at the following paths:

.. _intel_firmware_paths:
Expand Down Expand Up @@ -144,14 +187,14 @@ Linux SOF will look up firmware files at the following paths:
- IPC4
- /lib/firmware/intel/sof-ipc4/PLAT/community/sof-PLAT.ri
- PLAT = tgl, adl, rpl, mtl, lnl, ...
* - Tiger Lake and newer Loadable Module
* - Meteor Lake and newer Loadable libraries
- IPC4
- /lib/firmware/intel/sof-ipc4-lib/PLAT/UUID.bin
- PLAT as above, UUID = UUID of the module
* - Tiger Lake and newer Loadable Module (community signed)
- /lib/firmware/intel/sof-ipc4-lib/PLAT/
- PLAT = mtl, lnl, ...
* - Meteor Lake and newer Loadable libraries (community signed)
- IPC4
- /lib/firmware/intel/sof-ipc4-lib/PLAT/community/UUID.bin
- PLAT as above, UUID = UUID of the module
- /lib/firmware/intel/sof-ipc4-lib/PLAT/community/
- PLAT = mtl, lnl, ...

Important notices:
- The standard Linux firmware search path and order is followed. The above table covers the base "/lib/firmware" case. See https://docs.kernel.org/driver-api/firmware/fw_search_path.html for more information.
Expand Down
Loading