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

jsuhaas22 · jsuhaas22 · commit f87bb6a5c511 · 2025-06-11T11:12:36.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.

Signed-off-by: Suhaas Joshi &lt;s-joshi@ti.com&gt;
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
+============
+
+Debian images for AM62L are built using the **Armbian** build framework. *Armbian* describes itself to be a "base operating system", i.e. a build framework used to build Linux images optimized for Single-Board Computers.
+
+The Debian images are provided at |__SDK_DOWNLOAD_URL__|, but can also be built by users, especially if something custom (such as a particular desktop environment, or different kernel configs) is required.
+
+Armbian Usage
+=============
+
+This document provides high-level information on how to build Armbian images for AM62LX. For a full list of options on how these images may be configured, please see the.
+
+Get Armbian
+-----------
+
+For the time being, AM62L support is maintained in TI's fork of Armbian. Therefore, the first step would be to fetch TI's fork:
+
+.. code-block:: console
+
+   git clone https://github.com/TexasInstruments/armbian-build.git
+
+Repository Structure
+--------------------
+
+There are 4 files/directories of relevance to this high-level overview:
+
+- ``configs/``: This directory contains configurations for boards, families, kernel configs, desktop/CLI environments etc. To find config 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 should be invoked for building Armbian images.
+
+- ``lib/``: This directory stores the scripts that do most of the work in building Armbian images. Most likely, this directory would not have to be touched if you just want to create a custom AM62L image.
+
+- ``extensions``: This directory contains files in which **extension hooks** can be defined. In Armbian, *extension hooks* are functions that are not called in the process of building an image, but are un-defined in ``lib/``. TI has defined the ``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 can be used to store files that define build parameters, user patches etc.
+
+Building Images
+---------------
+
+Armbian supports an interactive building process. To build, go to the cloned Armbian repository, and use the following command:
+
+.. code-block:: console
+
+   ./compile.sh
+
+The build framework will then display dialog boxes to allow the user to select the board, CLI/desktop environment, kernel configs etc.
+
+To build the image non-interactively, specify all required **Build Switches** in the command:
+
+.. code-block:: console
+
+   ./compile.sh [command] [switch...] [command...]
+
+For example, the following command builds the image at |__SDK_DOWNLOAD_URL__|:
+
+.. code-block:: console
+
+   ./compile.sh build BOARD=sk-am62b BRANCH=current BUILD_MINIMAL=yes KERNEL_CONFIGURE=no RELEASE=trixie SKIP_ARMBIAN_REPO=yes
+
+The built image will then be stored at ``output/images/`` with 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
