feat(debian): AM62LX: Armbian-ize Debian docs for AM62L

jsuhaas22 · jsuhaas22 · commit 6ecb904f78f1 · 2025-06-12T11:02:34.000+05:30
Up until now, Debian images have been built using `ti-bdebstrap`. The
docs presently reflect this.

Starting with the 11.00.15.05 Linux SDK release, Debian images are built
with the Armbian Build Framework.

Therefore, edit AM62L-specific docs to remove references to
`ti-bdebstrap` and add information about Armbian.

Note: Only AM62L-specific changes have been made, using ifconfig's and a
new `Building_Debian_Image` file. This is because the other devices are
still going to use Debian until the 11.1 release.

Also add "Armbian" and "Debian" as recognized words for Vale.

Signed-off-by: Suhaas Joshi &lt;s-joshi@ti.com&gt;
diff --git a/.github/styles/config/vocabularies/PSDK/accept.txt b/.github/styles/config/vocabularies/PSDK/accept.txt
@@ -22,3 +22,5 @@ Zink
 [Ss]carthgap
 [Tt]oolchain
 balenaEtcher
+Armbian
+Debian
diff --git a/configs/AM62LX/AM62LX_debian_toc.txt b/configs/AM62LX/AM62LX_debian_toc.txt
@@ -2,7 +2,7 @@ devices/AM62LX/debian/index
 
 debian/Overview
 devices/AM62LX/debian/Getting_Started_Guide
-debian/Building_Debian_Image
+devices/AM62LX/debian/Building_Debian_Image
 debian/Building_Debian_Packages
 debian/How_to_Guides/index_How_to_Guides
 linux/How_to_Guides/Target/How_To_Enable_M2CC3301_in_linux
diff --git a/source/debian/Overview.rst b/source/debian/Overview.rst
@@ -2,19 +2,34 @@
 Overview
 ########
 
+.. ifconfig:: CONFIG_part_variant in ('AM62LX')
+
+   Armbian is a highly-optimized **base operating system** (i.e. an extensive build framework) for building Debian-based images for Single-Board Computers (SBCs).
+
+
 Debian, also known as Debian GNU/Linux, is a Linux distribution composed of free and open-source software, developed by the community-supported Debian Project.
 
-The Linux Debian distribution is enabled for TI's AM62Lx, AM62Px, AM62x and AM64x platforms. Few key highlights of this project are:
+.. ifconfig:: CONFIG_part_variant in ('AM62LX')
+
+   The Linux Debian distribution, built using Armbian, is enabled for TI's AM62Lx platform. Few key highlights of this project are:
+
+.. ifconfig:: CONFIG_part_variant not in ('AM62LX')
+
+   The Linux Debian distribution is enabled for TI's AM62Px, AM62x and AM64x platforms. Few key highlights of this project are:
 
 - The Debian filesystem image requires standard packages from debian.org and TI's customizations as .deb packages. The deb packages for the components owned by TI are built using the public sources hosted on respective git repositories and the deb packages are hosted on TI's official PPA repository maintained on `Github/TexasInstruments <https://github.com/TexasInstruments/ti-debpkgs>`__.
 
-- The entire Debian build process is made easy with a build script, the script "ti-bdebstrap" is hosted on `TI Debian Github <https://github.com/TexasInstruments/ti-bdebstrap>`__.
+.. ifconfig:: CONFIG_part_variant not in ('AM62LX')
+
+   - The entire Debian build process is made easy with a build script, the script "ti-bdebstrap" is hosted on `TI Debian Github <https://github.com/TexasInstruments/ti-bdebstrap>`__.
 
 - This document also provides the required steps and instructions to customize the TI's components for AM62Lx, AM62Px, AM62x and AM64x SOCs and create the corresponding deb packages.
 
 - The entire project is made public and we accept community contributions as pull requests to github repositories.
 
-- Github actions are enabled for the buildscripts workflow. So, any change in the config files, package additions or modifications in build scripts will result in auto generation of a new debian filesystem that reflects these changes. The new builds will store the filesystem image as an artifact hosted on the same repo, allowing other users to test the change without making a new build. These images are available via github for 90 days after which they may be purged to save disk space.
+.. ifconfig:: CONFIG_part_variant not in ('AM62LX')
+
+   - Github actions are enabled for the buildscripts workflow. So, any change in the config files, package additions or modifications in build scripts will result in auto generation of a new debian filesystem that reflects these changes. The new builds will store the filesystem image as an artifact hosted on the same repo, allowing other users to test the change without making a new build. These images are available via github for 90 days after which they may be purged to save disk space.
 
 
 Debian vs Yocto
diff --git a/source/devices/AM62LX/debian/Building_Debian_Image.rst b/source/devices/AM62LX/debian/Building_Debian_Image.rst
@@ -0,0 +1,73 @@
+======================
+Building Debian Images
+======================
+
+Introduction
+============
+
+Texas Instruments uses the **Armbian** build framework to generate Debian images for its platforms. *Armbian* describes itself to be a "base operating system"; that is, a build framework used to build Linux images optimized for Single-Board Computers.
+
+|__SDK_DOWNLOAD_URL__| provides Debain images for AM62L, but users can also build these, especially if users require something custom (such as different kernel configurations or default desktop environments).
+
+Armbian Usage
+=============
+
+This document provides high-level information about how to build Debian images for AM62LX, using Armbian. For a full list of options available for users to configure these images at build time, see `Armbian Documentation <https://docs.armbian.com/>`__.
+
+Get Armbian
+-----------
+
+For the time being, TI's fork of Armbian maintains AM62L support. Therefore, the first step is to fetch TI's fork:
+
+.. code-block:: console
+
+   git clone https://github.com/TexasInstruments/armbian-build.git
+
+Repository Structure
+--------------------
+
+There are 4 files and directories of relevance to this high-level overview:
+
+- ``configs/``: This directory has configurations for boards, families, kernel configurations, desktop or CLI environments and so on. To find configuration files relevant to TI, see:
+   - ``configs/sources/families/k3.conf``
+   - ``configs/kernel/linux-k3-current.conf``
+   - ``configs/kernel/linux-k3-rt-current.conf``
+
+- ``compile.sh``: This is the script that the user should run for building Armbian images.
+
+- ``lib/``: This directory stores the scripts that do most of the work in building Armbian images.
+
+- ``extensions/``: This directory has files that define **extension hooks**. In Armbian, *extension hooks* are function signatures, which the build framework calls in the process of building an image. However, the build framework does not define these in ``lib/``. Users can define these functions and integrate custom steps in the build process. TI has ``extensions/ti-debpkgs.sh`` extension file for AM62L. To customize the build process, create a new file in this directory, and define your extension hooks there. Once the file is created, be sure to add the following line to board/family config file:
+
+   .. code-block:: console
+
+      enable_extension <extension_name>
+
+- ``userpatches/``: This directory stores files that define build parameters, user patches and so on.
+
+Building Images
+---------------
+
+Armbian supports an interactive build process. To build interactively, go to TI's Armbian fork you cloned, and use the following command:
+
+.. code-block:: console
+
+   ./compile.sh
+
+The build framework will then display dialog boxes, through which the user can select the board, CLI or desktop environment, kernel configurations and so on.
+
+To build the image non-interactively, specify all required **Build Switches** in the command:
+
+.. code-block:: console
+
+   ./compile.sh [command] [switch...] [command...]
+
+A full list of build switches is available at `Build Switches <https://docs.armbian.com/Developer-Guide_Build-Switches/>`__.
+
+For example, the following command builds the image at |__SDK_DOWNLOAD_URL__|:
+
+.. code-block:: console
+
+   ./compile.sh build BOARD=am62l-evm BRANCH=current BUILD_MINIMAL=yes KERNEL_CONFIGURE=no RELEASE=trixie SKIP_ARMBIAN_REPO=yes
+
+``output/images/`` stores the built images. These images have a ``.img`` extension.
diff --git a/source/devices/AM62LX/debian/Getting_Started_Guide.rst b/source/devices/AM62LX/debian/Getting_Started_Guide.rst
@@ -4,7 +4,7 @@
 Getting Started with Debian
 ***************************
 
-The SD card Image tisdk-debian-trixie-<machine>-<version>.wic.xz provided on the |__SDK_DOWNLOAD_URL__| is all you need to get started and explore Debian on TI microprocessors.
+The SD card Image ti_debian_trixie_<machine>-<armbian-version>.img provided on the |__SDK_DOWNLOAD_URL__| is all you need to get started and explore Debian on TI microprocessors.
 
 The Debian Image provided has all the basic packages required to boot with weston as default window manager. The user can install any new package using inbuilt 'apt' utility
 and customize the filesystem as required.
diff --git a/source/devices/AM62LX/debian/index.rst b/source/devices/AM62LX/debian/index.rst
@@ -16,7 +16,7 @@ Debian Developer's Guide
 
    /debian/Overview
    Getting_Started_Guide
-   /debian/Building_Debian_Image
+   Building_Debian_Image
    /debian/Building_Debian_Packages
    /debian/How_to_Guides/index_How_to_Guides
    /debian/Demo_User_Guides/index_Demos
