feat(U-Boot): add QoS configuration section

bryanbrattlof · bryanbrattlof · commit a17be0cc0221 · 2025-12-15T17:47:56.000-06:00
Add basic documentation on how the CBASS QoS blocks function and how
Sysconfig can be used to generate the files for U-Boot to apply during
the SoC's bootup phase.

Signed-off-by: Bryan Brattlof &lt;bb@ti.com&gt;
diff --git a/configs/AM62AX/AM62AX_linux_toc.txt b/configs/AM62AX/AM62AX_linux_toc.txt
@@ -44,6 +44,7 @@ linux/Foundational_Components/U-Boot/UG-DDRSS
 #linux/Foundational_Components/U-Boot/UG-Network-K3
 linux/Foundational_Components/U-Boot/UG-RemoteProc
 linux/Foundational_Components/U-Boot/UG-Falcon-Mode
+linux/Foundational_Components/U-Boot/UG-QoS
 
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
diff --git a/configs/AM62DX/AM62DX_linux_toc.txt b/configs/AM62DX/AM62DX_linux_toc.txt
@@ -35,6 +35,7 @@ linux/Foundational_Components/U-Boot/UG-DFU
 linux/Foundational_Components/U-Boot/UG-Memory-K3
 linux/Foundational_Components/U-Boot/UG-QSPI
 linux/Foundational_Components/U-Boot/UG-UART
+linux/Foundational_Components/U-Boot/UG-QoS
 
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
diff --git a/configs/AM62LX/AM62LX_linux_toc.txt b/configs/AM62LX/AM62LX_linux_toc.txt
@@ -39,6 +39,7 @@ linux/Foundational_Components/U-Boot/UG-QSPI
 linux/Foundational_Components/U-Boot/UG-UART
 linux/Foundational_Components/U-Boot/UG-Key-Writer-Lite
 linux/Foundational_Components/U-Boot/UG-Programming-OTPs
+linux/Foundational_Components/U-Boot/UG-QoS
 
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
diff --git a/configs/AM62PX/AM62PX_linux_toc.txt b/configs/AM62PX/AM62PX_linux_toc.txt
@@ -44,6 +44,7 @@ linux/Foundational_Components/U-Boot/UG-Network-K3
 linux/Foundational_Components/U-Boot/UG-Splash-Screen
 linux/Foundational_Components/U-Boot/UG-RemoteProc
 linux/Foundational_Components/U-Boot/UG-Falcon-Mode
+linux/Foundational_Components/U-Boot/UG-QoS
 
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
diff --git a/configs/AM62X/AM62X_linux_toc.txt b/configs/AM62X/AM62X_linux_toc.txt
@@ -43,6 +43,7 @@ linux/Foundational_Components/U-Boot/UG-Network-K3
 linux/Foundational_Components/U-Boot/UG-Splash-Screen
 linux/Foundational_Components/U-Boot/UG-RemoteProc
 linux/Foundational_Components/U-Boot/UG-Falcon-Mode
+linux/Foundational_Components/U-Boot/UG-QoS
 
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
diff --git a/configs/AM64X/AM64X_linux_toc.txt b/configs/AM64X/AM64X_linux_toc.txt
@@ -41,6 +41,7 @@ linux/Foundational_Components/U-Boot/UG-NAND
 linux/Foundational_Components/U-Boot/UG-Network-K3
 linux/Foundational_Components/U-Boot/UG-RemoteProc
 linux/Foundational_Components/U-Boot/UG-PCIeBoot
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-TroubleShooting
diff --git a/configs/AM67/AM67_linux_toc.txt b/configs/AM67/AM67_linux_toc.txt
@@ -37,6 +37,7 @@ linux/Foundational_Components/U-Boot/UG-SATA
 linux/Foundational_Components/U-Boot/UG-DDR3
 linux/Foundational_Components/U-Boot/UG-HyperBus
 linux/Foundational_Components/U-Boot/UG-RemoteProc
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
diff --git a/configs/AM67A/AM67A_linux_toc.txt b/configs/AM67A/AM67A_linux_toc.txt
@@ -42,6 +42,7 @@ linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
 linux/Foundational_Components/U-Boot/Apps-TroubleShooting
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components_Kernel
 linux/Foundational_Components_Kernel_Drivers
 linux/Foundational_Components/Kernel/Kernel_Drivers/ADC
diff --git a/configs/AM68/AM68_linux_toc.txt b/configs/AM68/AM68_linux_toc.txt
@@ -40,6 +40,7 @@ linux/Foundational_Components/U-Boot/UG-Network-K3
 linux/Foundational_Components/U-Boot/UG-HyperBus
 linux/Foundational_Components/U-Boot/UG-RemoteProc
 linux/Foundational_Components/U-Boot/UG-HSM
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
diff --git a/configs/AM68A/AM68A_linux_toc.txt b/configs/AM68A/AM68A_linux_toc.txt
@@ -40,6 +40,7 @@ linux/Foundational_Components/U-Boot/UG-DDRSS-J7
 linux/Foundational_Components/U-Boot/UG-HyperBus
 linux/Foundational_Components/U-Boot/UG-RemoteProc
 linux/Foundational_Components/U-Boot/UG-HSM
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
diff --git a/configs/AM69/AM69_linux_toc.txt b/configs/AM69/AM69_linux_toc.txt
@@ -40,6 +40,7 @@ linux/Foundational_Components/U-Boot/UG-Network-K3
 linux/Foundational_Components/U-Boot/UG-HyperBus
 linux/Foundational_Components/U-Boot/UG-RemoteProc
 linux/Foundational_Components/U-Boot/UG-HSM
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
diff --git a/configs/AM69A/AM69A_linux_toc.txt b/configs/AM69A/AM69A_linux_toc.txt
@@ -40,6 +40,7 @@ linux/Foundational_Components/U-Boot/UG-DDRSS-J7
 linux/Foundational_Components/U-Boot/UG-HyperBus
 linux/Foundational_Components/U-Boot/UG-RemoteProc
 linux/Foundational_Components/U-Boot/UG-HSM
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
diff --git a/configs/J7200/J7200_linux_toc.txt b/configs/J7200/J7200_linux_toc.txt
@@ -41,6 +41,7 @@ linux/Foundational_Components/U-Boot/UG-HyperBus
 linux/Foundational_Components/U-Boot/UG-RemoteProc
 linux/Foundational_Components/U-Boot/UG-AVS
 linux/Foundational_Components/U-Boot/UG-Thermal
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
diff --git a/configs/J721E/J721E_linux_toc.txt b/configs/J721E/J721E_linux_toc.txt
@@ -45,6 +45,7 @@ linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
 linux/Foundational_Components/U-Boot/Apps-TroubleShooting
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components_Kernel
 linux/Foundational_Components_Kernel_Drivers
 linux/Foundational_Components/Kernel/Kernel_Drivers/ADC
diff --git a/configs/J721S2/J721S2_linux_toc.txt b/configs/J721S2/J721S2_linux_toc.txt
@@ -42,6 +42,7 @@ linux/Foundational_Components/U-Boot/UG-HyperBus
 linux/Foundational_Components/U-Boot/UG-RemoteProc
 linux/Foundational_Components/U-Boot/UG-HSM
 linux/Foundational_Components/U-Boot/UG-AVS
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
diff --git a/configs/J722S/J722S_linux_toc.txt b/configs/J722S/J722S_linux_toc.txt
@@ -40,6 +40,7 @@ linux/Foundational_Components/U-Boot/UG-DDRSS-J7
 linux/Foundational_Components/U-Boot/UG-Network-K3
 linux/Foundational_Components/U-Boot/UG-HyperBus
 linux/Foundational_Components/U-Boot/UG-RemoteProc
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
diff --git a/configs/J742S2/J742S2_linux_toc.txt b/configs/J742S2/J742S2_linux_toc.txt
@@ -40,6 +40,7 @@ linux/Foundational_Components/U-Boot/UG-UFS
 linux/Foundational_Components/U-Boot/UG-DDRSS-J7
 linux/Foundational_Components/U-Boot/UG-HyperBus
 linux/Foundational_Components/U-Boot/UG-RemoteProc
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
diff --git a/configs/J784S4/J784S4_linux_toc.txt b/configs/J784S4/J784S4_linux_toc.txt
@@ -41,6 +41,7 @@ linux/Foundational_Components/U-Boot/UG-DDRSS-J7
 linux/Foundational_Components/U-Boot/UG-HyperBus
 linux/Foundational_Components/U-Boot/UG-RemoteProc
 linux/Foundational_Components/U-Boot/UG-HSM
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
diff --git a/configs/TDA4VM/TDA4VM_linux_toc.txt b/configs/TDA4VM/TDA4VM_linux_toc.txt
@@ -41,6 +41,7 @@ linux/Foundational_Components/U-Boot/UG-DDR3
 linux/Foundational_Components/U-Boot/UG-HyperBus
 linux/Foundational_Components/U-Boot/UG-RemoteProc
 linux/Foundational_Components/U-Boot/UG-AVS
+linux/Foundational_Components/U-Boot/UG-QoS
 linux/Foundational_Components/U-Boot/Applications
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
diff --git a/source/linux/Foundational_Components/U-Boot/UG-QoS.rst b/source/linux/Foundational_Components/U-Boot/UG-QoS.rst
@@ -0,0 +1,50 @@
+Quality of Service (QoS)
+########################
+
+The Common Bus Architecture (CBASS) module includes Quality of Service
+(QoS) blocks which can change attributes such as the priority, Address
+Selection (ASEL), and Order ID (orderID) values of the transactions
+created by blocks in the System on a Chip (SoC) to route and prioritize
+the traffic on the bus in a particular way.
+
+For example changing the Order ID can route traffic through a particular port
+when more than port exists for that block on the bus. Most External
+Memory Interface (EMIF) controllers for K3 SoCs will have two ports to
+the CBASS so setting an Order ID value of 8 to 15 will route traffic
+through the high priority port and serviced by the EMIF before standard
+traffic. Setting an Order ID of 8 or higher for the display subsystem
+will allow its traffic to use the EMIF's high priority port and will
+help minimize stuttering or jitter on the display that can be more
+noticeable to end users.
+
+Consult the Technical Reference Manual (TRM) for you processor for more
+information about these QoS settings.
+
+Modifying QoS Defaults
+======================
+
+By default, the majority of transactions will default to the lowest
+priority level (ASEL is 0 and Order ID is 0). During boot-up `U-Boot can
+change`_  the QoS settings for your board early on during boot-up using
+the data generated from the `Sysconfig Tool`_ which you can download or
+launch online `here`_.
+
+.. _U-Boot can change: https://source.denx.de/u-boot/u-boot/-/blob/v2025.10/arch/arm/mach-k3/am62px/am62p5_init.c?ref_type=tags#L253
+.. _Sysconfig Tool: https://www.ti.com/tool/SYSCONFIG
+.. _here: https://www.ti.com/tool/SYSCONFIG
+
+The MCU+ SDK documentation has `an excellent guide`_ on how to to use the
+Sysconfig Tool to generate the needed configuration file. Once generated, copy
+the file into the :file:`arch/arm/mach-k3/r5/${SOC}/${SOC}_qos_uboot.c` and
+rebuild U-Boot to apply your changes.
+
+.. _an excellent guide: https://software-dl.ti.com/mcu-plus-sdk/esd/AM62X/latest/exports/docs/api_guide_am62x/DRIVERS_QOS_PAGE.html
+
+.. note::
+
+   Configuring the QoS blocks after the system is running is undefined
+   behaviour anc can cause issues. Modifying these settings can only
+   happen during bootup by the boot-loaders when many of the blocks in
+   the SoC are idle
+
+
diff --git a/source/linux/Foundational_Components/U-Boot/Users-Guide.rst b/source/linux/Foundational_Components/U-Boot/Users-Guide.rst
@@ -34,3 +34,4 @@ User's Guide
    UG-Key-Writer-Lite
    UG-Programming-OTPs
    UG-Falcon-Mode
+   UG-QoS
