feat(am62dx-edgeai): Add AM62DX EdgeAI documentation

.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__,__EDGEAI_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", "")
+
+# EdgeAI 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 EdgeAI 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 EdgeAI AM62Dx'
+'__SDK_SHORT_NAME__'             : 'PSDK EdgeAI'
+'__SDK_DOWNLOAD_URL__'           : '`AM62D-SDK-Download-page <https://www.ti.com/drr/opn/AM62D-LINUX-RT-RESTRICTED-SDK>`__'
+'__EDGEAI_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'Processor SDK Linux Edge AI for AM62Dx'
+html_title = 'Processor SDK Linux Edge AI for AM62Dx Documentation'
+
+# The master toctree document.
+master_doc = 'devices/AM62DX/edgeai/index'

configs/AM62DX/AM62DX_edgeai_toc.txt

@@ -0,0 +1,13 @@
+devices/AM62DX/edgeai/index
+devices/AM62DX/edgeai/overview
+devices/AM62DX/edgeai/evm_hardware_setup
+devices/AM62DX/edgeai/out_of_box_demo
+devices/AM62DX/edgeai/models_artifacts_and_setup
+devices/AM62DX/edgeai/linux_audio_inference_app
+devices/AM62DX/edgeai/getting_started_gstreamer
+devices/AM62DX/edgeai/edgeai_model_workflow
+devices/AM62DX/edgeai/model_zoo
+devices/AM62DX/edgeai/model_compile_evaluate
+devices/AM62DX/edgeai/model_inspect
+devices/AM62DX/edgeai/integrating_new_model
+devices/AM62DX/edgeai/performance

configs/AM62DX/AM62DX_linux_toc.txt

@@ -125,5 +125,6 @@ linux/Demo_User_Guides/index_Demos
 linux/Demo_User_Guides/AM62D_Dsp_Offload_User_Guide
 linux/Demo_User_Guides/AM62D_2DFFT_User_Guide
 linux/Demo_User_Guides/AM62D_Cascade_Biquad_Parametric_EQ_User_Guide
+linux/Demo_User_Guides/AM62D_EdgeAI_User_Guide
 
 linux/Documentation_Tarball

source/devices/AM62DX/edgeai/edgeai_model_workflow.rst

@@ -0,0 +1,122 @@
+.. include:: <isonum.txt>
+
+.. _edgeai-introduction:
+
+#####################
+EdgeAI Model Workflow
+#####################
+
+This guide covers the workflow for audio deep-learning (DL) models on the
+|__PART_FAMILY_NAME__| platform, using |__SDK_FULL_NAME__|
+|__EDGEAI_SDK_VERSION__|. It targets embedded developers. You can run,
+compile, evaluate, and benchmark audio models on the AM62D. Run pre-compiled
+artifacts directly on the target. Or use the 64-bit x86 compile-and-evaluate
+workflow.
+
+Four **reference models** serve as worked examples throughout the guide. 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. The guide will add more reference models over time.
+
+The remaining sections cover:
+
+- :ref:`EdgeAI Model Zoo <edgeai_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 <edgeai_compile_evaluate>` - the
+  x86 BYOM workflow built on ``edgeai-tidlrunner``: compile a model for the AM62D
+  and evaluate accuracy on a data set.
+- :ref:`Model Inspect <edgeai_model_inspect>` - analyze the compiled subgraphs
+  and per-layer behavior with Model Inspector.
+- :ref:`Performance benchmark <edgeai_performance>` - latency and memory
+  method 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 EdgeAI ModelZoo,
+   or your own exported ONNX.
+#. **Compile** it for the C7\ |trade| Neural Processing Unit (NPU) on an x86 host
+   (:ref:`Model Compile and Evaluate <edgeai_compile_evaluate>`).
+#. **Evaluate** accuracy or audio-quality metrics on a data set.
+#. **Inspect** the compiled subgraphs and per-layer analysis (:ref:`Model
+   Inspect <edgeai_model_inspect>`).
+#. **Run** on the AM62D target using the compiled artifact
+   (:ref:`EdgeAI Model Zoo <edgeai_model_zoo>`).
+#. **Benchmark** latency and memory (:ref:`Performance <edgeai_performance>`).
+
+****************
+Reference models
+****************
+
+Four reference models cover two task families. Each is a worked example of the
+workflow, delivered as an `ONNX <https://onnx.ai/>`__ graph. Three of the four
+run on the C7\ |trade| NPU through the TVM runtime (TVM-RT).
+
+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 data set.
+
+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``).
+
+Both speech-enhancement models are evaluated on the VoiceBank-DEMAND-16k
+data set.
+
+.. _edgeai-tvm-tidl:
+
+********************
+TVM + TIDL framework
+********************
+
+The AM62D audio models compile and deploy with **TI TVM**. This is 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. It combines the **C7x DSP** with the **Matrix Multiplication
+Accelerator (MMA)**. Older documents call this combination *C7x+MMA*.
+
+TI TVM adds **TIDL** (TI Deep Learning) as an accelerator backend. TIDL
+offloads supported layers to the MMA. TVM generates **C7x DSP** code for any
+layers that are left. The MMA and the C7x DSP together form the C7\ |trade|
+NPU. The result is one deployable artifact. The **entire model runs on the
+C7**\ |trade| **NPU**.
+
+Compilation runs on an x86 host in three stages:
+
+#. **Model import** - TVM imports the ONNX graph.
+#. **Partitioning** - the TIDL import API splits the graph into TIDL-supported
+   subgraphs and the rest. The TIDL network compiler builds the subgraphs. TVM
+   generates C7x DSP code for the rest.
+#. **Artifact generation** - TVM packages both parts into one TVM-RT
+   deployable artifact (:file:`deploy_lib.so` + :file:`deploy_graph.json` +
+   :file:`deploy_param.params`).
+
+At run time, the AM62D TVM runtime loads this artifact. It then sends 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.