feat: security: Add docs explaining Firewall Exceptions

jsuhaas22 · jsuhaas22 · commit 8325a08cb65a · 2026-01-20T13:52:35.000+05:30
Add a document to explain when a firewall exception occurs and how to
trigger it on purpose, and how to interpret it.

Signed-off-by: Suhaas Joshi &lt;s-joshi@ti.com&gt;
diff --git a/configs/AM62AX/AM62AX_linux_toc.txt b/configs/AM62AX/AM62AX_linux_toc.txt
@@ -97,6 +97,7 @@ linux/Foundational_Components/Power_Management/pm_debug
 linux/Foundational_Components/System_Security/Security_overview
 linux/Foundational_Components/System_Security/SELinux
 linux/Foundational_Components/System_Security/Auth_boot
+linux/Foundational_Components/System_Security/Firewall_Exception
 
 linux/Foundational_Components_Kernel_Users_Guide
 linux/Foundational_Components_Kernel_LTP-DDT_Validation
diff --git a/configs/AM62LX/AM62LX_linux_toc.txt b/configs/AM62LX/AM62LX_linux_toc.txt
@@ -83,6 +83,7 @@ linux/Foundational_Components/Power_Management/pm_am62lx_debug
 linux/Foundational_Components/System_Security/Security_overview
 #linux/Foundational_Components/System_Security/SELinux
 linux/Foundational_Components/System_Security/Auth_boot
+linux/Foundational_Components/System_Security/Firewall_Exception
 
 linux/Foundational_Components_Kernel_Users_Guide
 linux/Foundational_Components_Kernel_LTP-DDT_Validation
diff --git a/configs/AM62PX/AM62PX_linux_toc.txt b/configs/AM62PX/AM62PX_linux_toc.txt
@@ -102,6 +102,7 @@ linux/Foundational_Components/Power_Management/pm_debug
 linux/Foundational_Components/System_Security/Security_overview
 linux/Foundational_Components/System_Security/SELinux
 linux/Foundational_Components/System_Security/Auth_boot
+linux/Foundational_Components/System_Security/Firewall_Exception
 
 linux/Foundational_Components_Kernel_Users_Guide
 linux/Foundational_Components_Kernel_LTP-DDT_Validation
diff --git a/configs/AM62X/AM62X_linux_toc.txt b/configs/AM62X/AM62X_linux_toc.txt
@@ -99,6 +99,7 @@ linux/Foundational_Components/Power_Management/pm_debug
 linux/Foundational_Components/System_Security/Security_overview
 linux/Foundational_Components/System_Security/SELinux
 linux/Foundational_Components/System_Security/Auth_boot
+linux/Foundational_Components/System_Security/Firewall_Exception
 
 linux/Foundational_Components_PRU_Subsystem
 linux/Foundational_Components/PRU-ICSS-Linux-Drivers
diff --git a/configs/AM64X/AM64X_linux_toc.txt b/configs/AM64X/AM64X_linux_toc.txt
@@ -84,6 +84,7 @@ linux/Foundational_Components_Kernel_LTP-DDT_Validation
 linux/Foundational_Components_Kernel_FAQs
 linux/Foundational_Components_Security
 linux/Foundational_Components/System_Security/Security_overview
+linux/Foundational_Components/System_Security/Firewall_Exception
 linux/Foundational_Components_Machine_Learning
 linux/Foundational_Components/Machine_Learning/arm_compute_library
 linux/Foundational_Components/Machine_Learning/armnn
diff --git a/source/linux/Foundational_Components/System_Security/Firewall_Exception.rst b/source/linux/Foundational_Components/System_Security/Firewall_Exception.rst
@@ -0,0 +1,112 @@
+.. _firewall-exception:
+
+******************
+Firewall Exception
+******************
+
+Overview
+========
+
+TI MPUs use hardware-backed firewalls to enforce access control. TIFS
+configures these firewalls to restrict which components can access
+specific regions of device-mapped memory. Other components such as
+OP-TEE, ATF, Linux, U-Boot, and userspace programs can request TIFS to
+configure firewalls on their behalf.
+
+Firewalls can restrict access based on:
+
+*  **Core**: A53, R5, M4, etc.
+*  **Privilege level**: privileged or non-privileged
+*  **Security state**: secure or non-secure
+
+For example, TIFS might configure a firewall to prevent Linux (running
+on A53) from accessing a memory region reserved for the secure world.
+
+For more information about firewalls, see the Technical Reference
+Manual (TRM) for the specific SoC, the
+`TISCI Firewall API <https://software-dl.ti.com/tisci/esd/latest/2_tisci_msgs/security/firewall_api.html>`__,
+and the
+`TIFS Firewall FAQ <https://software-dl.ti.com/tisci/esd/latest/6_topic_user_guides/firewall_faq.html>`__.
+
+What Happens During a Firewall Violation
+========================================
+
+When software attempts an unauthorized access to a memory region that
+a firewall protects, the firewall blocks the access and triggers an
+exception. The outcome depends on the type of access:
+
+*  **Read access**: The firewall blocks the read. The system continues
+   running.
+*  **Write access**: The firewall blocks the write and crashes the
+   Linux kernel. The system halts.
+
+The kernel crash on write violations stops the offending software
+immediately, preventing further unauthorized access attempts.
+
+TIFS logs information about every firewall exception. The rest of this
+document explains how to trigger exceptions, enable TIFS logs, access
+them, and interpret them.
+
+Triggering a Firewall Exception
+===============================
+
+To test firewall behavior, use ``k3conf`` to read from or write to a
+protected memory region.
+
+Triggering a read exception:
+
+.. code-block:: console
+
+   k3conf read <addr> [<size>]
+
+Triggering a write exception (this will crash the kernel):
+
+.. code-block:: console
+
+   k3conf write <addr> <value>
+
+Replace ``<addr>`` with the address of a firewall-protected region,
+``<size>`` with the number of bytes to read, and ``<value>`` with the
+value to write.
+
+Enabling TIFS Logs
+==================
+
+TIFS does not output logs by default. Enabling TIFS logging requires
+modifying U-Boot source code, recompiling it, and transferring the new
+binaries to the boot partition.
+
+Modify U-Boot Configuration
+---------------------------
+
+Open :file:`board/ti/<soc_name>/board-cfg.yaml` in the U-Boot source
+tree. Locate ``trace_dst_enables`` and ``trace_src_enables``, which
+U-Boot sets to ``0x0`` by default. Change these values as follows:
+
+*  ``trace_dst_enables``: change from ``0x0`` to ``0xD``
+*  ``trace_src_enables``: change from ``0x0`` to ``0x3F``
+
+Build and Deploy U-Boot
+-----------------------
+
+After making these changes, compile U-Boot and transfer the resulting
+binaries to the board's boot partition. See
+:ref:`u-boot-build-guide-build-k3` for build instructions.
+
+Accessing TIFS Logs
+===================
+
+TIFS outputs logs to a separate serial port from the Linux console.
+If the Linux command line appears on :file:`/dev/ttyUSB0`, TIFS logs
+typically appear on :file:`/dev/ttyUSB1`. However, the exact device
+assignment depends on the hardware setup and the order in which the
+host enumerates USB devices.
+
+Open the TIFS serial port with a terminal program such as minicom or
+PuTTY to view the logs.
+
+Interpreting TIFS Logs
+======================
+
+For information on interpreting firewall exception logs, see the
+`TIFS Firewall FAQ <https://software-dl.ti.com/tisci/esd/latest/6_topic_user_guides/firewall_faq.html#how-do-i-debug-firewall-issues>`__.
diff --git a/source/linux/Foundational_Components/System_Security/Security_overview.rst b/source/linux/Foundational_Components/System_Security/Security_overview.rst
@@ -61,6 +61,8 @@ The following table lists some of the key Security Features:
   |                         | Trusted Execution Environment that enables isolated       | :ref:`foundational-components-optee` |
   |                         | execution of security-sensitive applications and services |                                      |
   +-------------------------+-----------------------------------------------------------+--------------------------------------+
+  | **Firewall Exception**  | Debugging hardware firewall violations                    | :ref:`firewall-exception`            |
+  +-------------------------+-----------------------------------------------------------+--------------------------------------+
 
 .. ifconfig:: CONFIG_part_variant in ('AM62X', 'AM62PX', 'AM62AX')
 
@@ -83,6 +85,8 @@ The following table lists some of the key Security Features:
   |                         | Trusted Execution Environment that enables isolated       | :ref:`foundational-components-optee` |
   |                         | execution of security-sensitive applications and services |                                      |
   +-------------------------+-----------------------------------------------------------+--------------------------------------+
+  | **Firewall Exception**  | Debugging hardware firewall violations                    | :ref:`firewall-exception`            |
+  +-------------------------+-----------------------------------------------------------+--------------------------------------+
 
 .. ifconfig:: CONFIG_part_variant not in ('AM62X', 'AM62PX', 'AM62AX', 'AM62LX')
 
@@ -99,4 +103,6 @@ The following table lists some of the key Security Features:
   |                         | Trusted Execution Environment that enables isolated       | :ref:`foundational-components-optee` |
   |                         | execution of security-sensitive applications and services |                                      |
   +-------------------------+-----------------------------------------------------------+--------------------------------------+
+  | **Firewall Exception**  | Debugging hardware firewall violations                    | :ref:`firewall-exception`            |
+  +-------------------------+-----------------------------------------------------------+--------------------------------------+
 
diff --git a/source/linux/Foundational_Components_Security.rst b/source/linux/Foundational_Components_Security.rst
@@ -12,3 +12,4 @@ Security
    Foundational_Components_Secure_Boot
    Foundational_Components/System_Security/SELinux
    Foundational_Components/System_Security/Auth_boot
+   Foundational_Components/System_Security/Firewall_Exception
