Add AM62D Audio AI documentation (OS=edgeai)

.github/styles/config/vocabularies/PSDK/accept.txt

@@ -33,9 +33,13 @@ Zink
 [Mm]ulticast
 [Rr]enderers?
 [Ss]carthgap
+[Ss]ubgraphs?
 [Tt]oolchain
 balenaEtcher
 bdebstrap
 fdisk
+logits?
 mmdebstrap
+perfsim
 umount
+venv

.rstcheck.cfg

@@ -3,5 +3,5 @@ ignore_directives = ifconfig,graphviz,grid,grid-item,grid-item-card,card,dropdow
 # ignore the following languages because they require external compilers and
 # snippets in this repo depend on external code
 ignore_languages = c,cpp,c++
-ignore_substitutions = __PART_FAMILY_NAME__,__PART_FAMILY_DEVICE_NAMES__,__PRODUCT_LINE_NAME__,__SDK_BUILD_MACHINE__,__SDK_FULL_NAME__,__SDK_SHORT_NAME__,__SDK_INSTALL_FILE__,__SDK_INSTALL_DIR__,__SDK_DOWNLOAD_URL__,__LINUX_UBUNTU_VERSION_LONG__,__LINUX_UBUNTU_VERSION_SHORT__,__OPTEE_PLATFORM_FLAVOR__,__RTOS_UBUNTU_VERSION_LONG__,__WINDOWS_SUPPORTED_LONG__,__FEATURINGMATRIX__,__SYSFW_CORE_NAME__,__PCIE_BASE_ADDRESS__,__PCIE_DEVICE_ID__,__IMAGE_TYPE__,__SDK_OS_NAME__
+ignore_substitutions = __PART_FAMILY_NAME__,__PART_FAMILY_DEVICE_NAMES__,__PRODUCT_LINE_NAME__,__SDK_BUILD_MACHINE__,__SDK_FULL_NAME__,__SDK_SHORT_NAME__,__SDK_INSTALL_FILE__,__SDK_INSTALL_DIR__,__SDK_DOWNLOAD_URL__,__LINUX_UBUNTU_VERSION_LONG__,__LINUX_UBUNTU_VERSION_SHORT__,__OPTEE_PLATFORM_FLAVOR__,__RTOS_UBUNTU_VERSION_LONG__,__WINDOWS_SUPPORTED_LONG__,__FEATURINGMATRIX__,__SYSFW_CORE_NAME__,__PCIE_BASE_ADDRESS__,__PCIE_DEVICE_ID__,__IMAGE_TYPE__,__SDK_OS_NAME__,__AUDIOAI_SDK_VERSION__,trade
 ignore_messages = (Hyperlink target.*is not referenced\.)

conf.py

@@ -261,6 +261,12 @@
 
 FAMILY = os.environ.get("DEVFAMILY", "")
 OS = os.environ.get("OS", "")
+
+# Audio AI docs prefix every shell command with a "$ " prompt symbol; strip it
+# from the copy-button output so copied text is directly runnable. 
+if OS == "edgeai" and FAMILY == "AM62DX":
+    copybutton_prompt_text = "$ "
+
 try:
     globals().update(importlib.import_module(f"configs.{FAMILY}.{FAMILY}_{OS}_tags").__dict__)
 except ModuleNotFoundError as exc:

configs/AM62DX/AM62DX_edgeai_config.txt

@@ -0,0 +1,30 @@
+# General family replacement variables and configuration values for AM62D Audio AI build
+
+# This file is processed by Python scripts to define both replacement
+# variable and configuration values for a device family build.
+# For replacement variables, all variables should be listed on a single
+# line, and all the variables should be listed on consecutive lines
+# (i.e. no additional blank lines between the replacement variables).
+# Similarly, all the configuration values should be listed on individual,
+# consecutive lines (with no blank lines between the configuration values).
+#
+# Note that neither replacement variables nor configuration values may contain
+# a colon (i.e. ":") in their name.  However, values may contain colons.
+
+Replacement Variables
+---------------------
+'__PART_FAMILY_NAME__'           : 'AM62Dx'
+'__PART_FAMILY_DEVICE_NAMES__'   : 'AM62Dx'
+'__PRODUCT_LINE_NAME__'          : 'Sitara MPU'
+'__SDK_FULL_NAME__'              : 'Processor SDK Linux Audio AI AM62Dx'
+'__SDK_SHORT_NAME__'             : 'PSDK Audio AI'
+'__SDK_DOWNLOAD_URL__'           : '`AM62D-SDK-Download-page <https://www.ti.com/drr/opn/AM62D-LINUX-RT-RESTRICTED-SDK>`__'
+'__AUDIOAI_SDK_VERSION__'        : '12.1'
+'__TIDL_VERSION__'               : '11_02_18_00'
+'__TIDL_TOOLS_VERSION__'         : '11.2.x'
+
+Configuration Values
+--------------------
+'CONFIG_part_family'      : 'AM62DX_family'
+'CONFIG_part_variant'     : 'AM62DX'
+'CONFIG_sdk'              : 'SITARA'

configs/AM62DX/AM62DX_edgeai_tags.py

@@ -0,0 +1,6 @@
+# Project name and HTML title
+project = u'Audio AI for AM62D'
+html_title = 'Audio AI for AM62D Documentation'
+
+# The master toctree document.
+master_doc = 'devices/AM62DX/edgeai/index'

configs/AM62DX/AM62DX_edgeai_toc.txt

@@ -0,0 +1,6 @@
+devices/AM62DX/edgeai/index
+devices/AM62DX/edgeai/introduction
+devices/AM62DX/edgeai/model_zoo
+devices/AM62DX/edgeai/model_compile_evaluate
+devices/AM62DX/edgeai/model_inspect
+devices/AM62DX/edgeai/performance

source/devices/AM62DX/edgeai/index.rst

@@ -0,0 +1,21 @@
+.. _audioai-index:
+
+#########################################
+AM62D Audio AI Software Developer's Guide
+#########################################
+
+.. rubric:: Welcome to the AM62D Audio AI/DL Software Developer's Guide
+
+.. toctree::
+   :maxdepth: 5
+   :numbered:
+
+   introduction
+   model_zoo
+   model_compile_evaluate
+   model_inspect
+   performance
+
++--------------------------------+--------------------------------------------------------------------------------------------------+
+| .. Image:: /images/E2e.jpg     | For technical support please post your questions at `http://e2e.ti.com <http://e2e.ti.com/>`__.  |
++--------------------------------+--------------------------------------------------------------------------------------------------+

source/devices/AM62DX/edgeai/introduction.rst

@@ -0,0 +1,131 @@
+.. include:: <isonum.txt>
+
+.. _audioai-introduction:
+
+#######################
+Introduction & Overview
+#######################
+
+This guide walks through the workflow for developing and deploying audio
+deep-learning (Audio AI/DL) models on the |__PART_FAMILY_NAME__| platform, using
+|__SDK_FULL_NAME__| |__AUDIOAI_SDK_VERSION__|. It is written for embedded
+developers who want to run, compile, evaluate, and benchmark audio models on the
+AM62D - either out of the box on the target with pre-compiled artifacts, or
+through the x86 compile/evaluate workflow.
+
+Four **reference models** serve as worked examples throughout the guide, but the
+workflow is not limited to them: the same compile/evaluate/inspect flow is a
+bring-your-own-model (BYOM) flow that accepts any supported `ONNX
+<https://onnx.ai/>`__ model. More reference models will be added over time.
+
+The remaining sections cover:
+
+- :ref:`Audio AI Model Zoo <audioai-model-zoo>` - out-of-box demos on the AM62D
+  target (inference scripts and Jupyter notebooks) using pre-trained models and
+  pre-compiled artifacts.
+- :ref:`Model Compile and Evaluate <audioai-compile-evaluate>` - the
+  x86 BYOM workflow built on ``edgeai-tidlrunner``: compile a model for the AM62D
+  and evaluate accuracy on a dataset.
+- :ref:`Model Inspect <audioai-model-inspect>` - analyze the compiled subgraphs
+  and per-layer behavior with Model Inspector.
+- :ref:`Performance benchmark <audioai-performance>` - latency and memory
+  methodology with per-model tables.
+
+********************
+Development workflow
+********************
+
+The end-to-end path is the same for a reference model or your own model:
+
+#. **Obtain an ONNX model** - a reference graph shipped with the AudioAI ModelZoo,
+   or your own exported ONNX.
+#. **Compile** it for the C7\ |trade| NPU on an x86 host (:ref:`Model Compile and
+   Evaluate <audioai-compile-evaluate>`).
+#. **Evaluate** accuracy or audio-quality metrics on a dataset.
+#. **Inspect** the compiled subgraphs and per-layer analysis (:ref:`Model
+   Inspect <audioai-model-inspect>`).
+#. **Run** on the AM62D target using the compiled artifact
+   (:ref:`Audio AI Model Zoo <audioai-model-zoo>`).
+#. **Benchmark** latency and memory (:ref:`Performance <audioai-performance>`).
+
+****************
+Reference models
+****************
+
+Four reference models are provided across two task families, as worked examples
+of the workflow. Each is delivered as an `ONNX <https://onnx.ai/>`__ graph and,
+except for GTCRN, is offloaded to the C7\ |trade| NPU through the TVM runtime
+(TVM-RT); GTCRN is the one that runs ARM-only. See :ref:`the framework overview
+<audioai-tvm-tidl>` below for what that means. The same flow accepts your own
+ONNX model, and more reference models will be added over time.
+
+Audio analysis and classification
+=================================
+
+**VGGish11** (model ID ``ac-0101``)
+   Audio-clip classification. Input is a log-mel patch of shape ``(1, 1, 64, 126)``;
+   output is ``(1, 10)`` class logits plus a ``(1, 512)`` embedding. Runs at 8-bit,
+   fully offloaded to the C7\ |trade| NPU via TVM-RT (a single TIDL subgraph).
+
+**YAMNet** (model ID ``ac-0201``)
+   Audio-event classification. Input is a log-mel patch of shape ``(1, 1, 96, 64)``;
+   output is ``(1, 521)`` class scores. Runs at 8-bit, fully offloaded to the
+   C7\ |trade| NPU via TVM-RT (a single TIDL subgraph).
+
+Both classification models are evaluated on the UrbanSound8K dataset.
+
+Speech enhancement
+==================
+
+**GCRN** (model ID ``ase-0201``)
+   Convolutional-recurrent speech enhancement (noise suppression) over a fixed 4-second
+   window. Input and output are complex spectrograms of shape ``(1, 2, 401, 161)``.
+   Runs at 16-bit and is offloaded to the C7\ |trade| NPU via TVM-RT
+   (``tidl_offload: true``).
+
+**GTCRN** (model ID ``ase-0100``)
+   Grouped temporal convolutional-recurrent speech enhancement. Input and output
+   are complex spectrograms of shape ``(1, 257, T, 2)`` with a dynamic time
+   dimension ``T``. Runs FP32 on the Arm core through the ONNX runtime
+   (``tidl_offload: false``) - it is the only supported model that is **not**
+   offloaded to the C7\ |trade| NPU.
+
+Both speech-enhancement models are evaluated on the VoiceBank-DEMAND-16k
+dataset.
+
+.. _audioai-tvm-tidl:
+
+********************
+TVM + TIDL framework
+********************
+
+The AM62D audio models are compiled and deployed with **TI TVM**, TI's fork of
+the `Apache TVM <https://tvm.apache.org/>`__ deep-learning compiler. The target
+accelerator is the **C7**\ |trade| **NPU** - TI's Neural Processing Unit, which
+combines the **C7x DSP** with the **Matrix Multiplication Accelerator (MMA)**
+(referred to as *C7x+MMA* in older documentation).
+
+TI TVM integrates **TIDL** (TI Deep Learning) as an accelerator backend:
+TIDL-supported layers are offloaded to the MMA, while TVM generates **C7x DSP**
+code for any remaining layers. Because the MMA and the C7x DSP together make up
+the C7\ |trade| NPU, the result is a single deployable artifact in which the
+**entire model runs on the C7**\ |trade| **NPU**.
+
+Compilation runs on an x86 host and proceeds in stages:
+
+#. **Model import** - the ONNX graph is imported into TVM.
+#. **Partitioning** - using the TIDL import API, the graph is split into
+   TIDL-supported subgraphs (compiled by the TIDL network compiler) and the
+   remaining operators (handled by TVM C7x DSP code generation).
+#. **Artifact generation** - both parts are packaged into one TVM-RT deployable
+   artifact (``deploy_lib.so`` + ``deploy_graph.json`` + ``deploy_param.params``).
+
+At run time on the AM62D, the TVM runtime loads the artifact and dispatches the
+offloaded subgraphs to TIDL-RT on the C7\ |trade| NPU.
+
+.. figure:: ../../../images/audioai/tvm_tidl_flow.svg
+   :width: 80 %
+   :align: center
+
+   TVM + TIDL compile-and-deploy flow for the AM62D audio models. Green blocks
+   are handled by TIDL; white blocks are handled by TVM.