.. include:: /keyword.rst

=========
Audio DSP
=========

.. contents:: Sections
    :local:
    :depth: 2

Build SOF Firmware
------------------

The SOF project aims to provide an open-source audio DSP firmware and software stack for audio devices.
This guide will explain how to use SOF docker image to build SOF firmware for the |G510-G700-G1200-EVK|.

Set up the SOF workspace
^^^^^^^^^^^^^^^^^^^^^^^^

1. Establish a directory to store all the SOF work.

.. prompt:: bash # auto

    # SOF_WORKSPACE=~/sof_work
    # mkdir -p "$SOF_WORKSPACE"

2. Clone the SOF repository.

.. prompt:: bash # auto

    # cd "$SOF_WORKSPACE"
    # git clone --recurse-submodules https://github.com/thesofproject/sof.git

Get the SOF Docker Image
^^^^^^^^^^^^^^^^^^^^^^^^

To build SOF binaries, a Docker image with the necessary platform-related cross-compiler and build 
environment dependencies are required. 
Building SOF binaries using Docker can save time compared to building them from source code, as building
the toolchains from the source code might take several hours.

For information on how to install Docker, please visit `Set up Docker <https://thesofproject.github.io/latest/getting_started/build-guide/build-with-docker.html#set-up-docker>`_.

1. Pull the Docker image from Docker Hub. Please make sure your platform has an internet connection.

.. prompt:: bash # auto

    # docker pull thesofproject/sof

Build Firmware Binaries
^^^^^^^^^^^^^^^^^^^^^^^

If you execute the ``xtensa-build-all.sh`` script without specifying the platforms, this script will 
build firmware binaries for all the platforms listed in the script.
This script allows specifying the platform binaries to be built by adding the platform alias suffixes
at the end of the command.

To build the SOF binaries for Genio platforms:

.. prompt:: bash # auto

    # cd "$SOF_WORKSPACE"/sof/
    
    Genio 510/700-EVK
    # ./scripts/docker-run.sh ./scripts/xtensa-build-all.sh mt8188

    Genio 1200-EVK
    # ./scripts/docker-run.sh ./scripts/xtensa-build-all.sh mt8195

    Genio 510/700-EVK, Genio 1200-EVK
    # ./scripts/docker-run.sh ./scripts/xtensa-build-all.sh mt8188 mt8195

The firmware binaries are located in the ``build_<platform>/src/arch/xtensa/`` directory.
Copy them to the ``/lib/firmware/mediatek/sof`` directory on the target machine.

Build SOF Topology
^^^^^^^^^^^^^^^^^^

.. prompt:: bash # auto

    # cd "$SOF_WORKSPACE"/sof/
    # ./scripts/docker-run.sh ./scripts/build-tools.sh


The topology files are located in the ``"$SOF_WORKSPACE"/sof/tools/build_tools/topology`` folder.
Copy the files to the ``/lib/firmware/mediatek/sof-tplg`` directory on the target machine.

Build SOF Tools
^^^^^^^^^^^^^^^

SOF tools are a collection of utilities and scripts designed to facilitate the development, debugging,
and deployment of audio firmware on various platforms.

The SOF topology and SOF tools are both compiled together using the same scripts -
``./scripts/build-tools.sh``. However, if you intend to use SOF tools on Genio platforms, please ensure
that they are compiled using the ARM architecture.

The application SDK can be used for building 3rd party software if IoT Yocto does not provide them. 
You can use the application SDK to build the SOF tools. For more details, please refer to the :ref:`Application SDK <sw/yocto/app-sdk:application sdk>`.

- `sof-logger`

    ``sof-logger`` is a specialized tool used within the SOF project to capture and display logs
    generated by the SOF firmware. These logs are crucial for debugging, performance analysis, and
    monitoring the behavior of the audio DSP firmware. ``sof-logger`` captures logs from the SOF
    firmware on the DSP, providing real-time insights into the firmware's operations.

    To use ``sof-logger``, please enable these configs at ``recipes-kernel/linux/linux-mtk/sof.cfg``
    while building the platform image.

    .. prompt:: bash $ auto

        - EXPERT
        - SND_SOC_SOF_DEVELOPER_SUPPORT
        - SND_SOC_SOF_DEBUG
        - SND_SOC_SOF_DEBUG_VERBOSE_IPC (optional)
        - SND_SOC_SOF_DEBUG_ENABLE_FIRMWARE_TRACE (optional)

    Ensure you have the logger configuration file (``sof-<platform>.ldc``) which contains the necessary
    metadata for decoding the logs. ``sof-<platform>.ldc`` is built with the SOF firmware binary. Copy 
    the file to the directory ``/lib/firmware/mediatek/sof`` on the target machine.

    Here is a basic example to run ``sof-logger``:

    .. prompt:: bash # auto

        # ./sof-logger -l sof-mt8188.ldc -t
    
    For more ``sof-logger`` usage, please refer to `here <https://thesofproject.github.io/latest/developer_guides/debugability/logger/index.html#logger-usage>`_.

Example
-------

This section provides a detailed example and instructions on how to modify the topology in Sound Open Firmware (SOF),
specifically by adding a new audio processing component such as a volume control (PGA) to an existing pipeline.

1. **Locate the Topology File:**

   Find the `.m4` file corresponding to the topology you want to modify, typically located in the `/tools/topology/topology1/` directory of the SOF source.

   The snippet shows the MT8188 topology (``sof-mt8188-mt6359.m4``) for capture devices:

    .. code-block:: bash

      # Low Latency capture pipeline 3 on PCM 18 using max 2 channels of s16le
      # Set 2000us deadline with priority 0 on core 0
      PIPELINE_PCM_ADD(sof/pipe-passthrough-capture.m4,
          3, 18, 2, s16le,
          2000, 0, 0,
          48000, 48000, 48000)

      # Low Latency capture pipeline 4 on PCM 19 using max 2 channels of s16le
      # Set 2000us deadline with priority 0 on core 0
      PIPELINE_PCM_ADD(sof/pipe-passthrough-capture.m4,
          4, 19, 2, s16le,
          2000, 0, 0,
          48000, 48000, 48000)


2. **Modify the Topology:**

   Add a new volume capture component (PGA) to the pipeline, replacing the passthrough filter, as shown in the snippet:

    .. code-block:: bash

      # Low Latency capture pipeline 3 on PCM 18 using max 2 channels of s16le
      # Set 2000us deadline with priority 0 on core 0
      PIPELINE_PCM_ADD(sof/pipe-volume-capture.m4,
          3, 18, 2, s16le,
          2000, 0, 0,
          48000, 48000, 48000)

      # Low Latency capture pipeline 4 on PCM 19 using max 2 channels of s16le
      # Set 2000us deadline with priority 0 on core 0
      PIPELINE_PCM_ADD(sof/pipe-passthrough-capture.m4,
          4, 19, 2, s16le,
          2000, 0, 0,
          48000, 48000, 48000)


3. **Rebuild the Topology:**

   After modifying the `.m4` file, rebuild the topology to generate the `.tplg` file.

   .. code-block:: bash

    cd "$SOF_WORKSPACE"/sof/
    ./scripts/docker-run.sh ./scripts/build-tools.sh


4. **Deploy the Topology:**

   The topology file is located in the ``"$SOF_WORKSPACE"/sof/tools/build_tools/topology`` folder.

   Copy the file to the ``/lib/firmware/mediatek/sof-tplg`` directory on the target machine (replacing the existing topology file) and restart the device for the changes to take effect.


5. **Verify the New Topology:**

   Check logs to ensure there are no errors related to SOF or the audio pipeline:

   .. code-block:: bash

      dmesg | grep sof

   Check the ``amixer`` settings to find the newly added component:

   .. code-block:: bash

    root@genio-510-evk:~# amixer -c0 | grep -A5 PGA3.0
    Simple mixer control 'PGA3.0 3 Master',0
        Capabilities: cvolume
        Capture channels: Front Left - Front Right
        Limits: Capture 0 - 80
        Front Left: Capture 50 [62%] [0.00dB]
        Front Right: Capture 50 [62%] [0.00dB]

   Tweak the component parameters:

   .. code-block:: bash

     root@genio-510-evk:~# amixer -c0 cset numid=366 80,80
     numid=366,iface=MIXER,name='PGA3.0 3 Master Capture Volume'
       ; type=INTEGER,access=rw---R--,values=2,min=0,max=80,step=0
       : values=80,80
       | dBscale-min=-50.00dB,step=1.00dB,mute=1

   Validate the changes:

   .. code-block:: bash

     root@genio-510-evk:~# amixer -c0 sget 'PGA3.0 3 Master'
     Simple mixer control 'PGA3.0 3 Master',0
        Capabilities: cvolume
        Capture channels: Front Left - Front Right
        Limits: Capture 0 - 80
        Front Left: Capture 80 [100%] [30.00dB]
        Front Right: Capture 80 [100%] [30.00dB]

   Test the audio capture to verify component functionality:

   .. code-block:: bash

     arecord -Dhw:0,18 -c2 -fS16_LE -d30 -r48000 test.wav

For more information on SOF topology, please refer to this: https://thesofproject.github.io/latest/developer_guides/topology/topology