From f0e9bc88657e299ae5352c60941c5ab60ad1db3f Mon Sep 17 00:00:00 2001
From: Donato Capitella <donato.capitella@reversec.com>
Date: Thu, 8 Jan 2026 14:47:14 +0000
Subject: [PATCH] adding warning

---
 README.md                        |  7 +++
 docs/troubleshooting-firmware.md | 80 ++++++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 docs/troubleshooting-firmware.md

diff --git a/README.md b/README.md
index 2667dba..80ce59b 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,13 @@
 
 This project provides pre-built containers (“toolboxes”) for running LLMs on **AMD Ryzen AI Max “Strix Halo”** integrated GPUs. Toolbx is the standard developer container system in Fedora (and now works on Ubuntu, openSUSE, Arch, etc).
 
+## 🚨 CRITICAL WARNING — 2026-01-08
+
+**Do NOT use `linux-firmware-20251125`.** It breaks ROCm support on Strix Halo (instability/crashes).
+AMD has recalled this update, but if you have already installed it, you must downgrade for now, until Fedora pushes a fix.
+
+👉 **[Click here for Downgrade Instructions & Fix Guide](docs/troubleshooting-firmware.md)**
+
 ## 🚨 Updates — 2025-11-18
 
 - Released new toolboxes for ROCm 7 that track the nightly builds, these are now called `alpha`. 
diff --git a/docs/troubleshooting-firmware.md b/docs/troubleshooting-firmware.md
new file mode 100644
index 0000000..01f2ed5
--- /dev/null
+++ b/docs/troubleshooting-firmware.md
@@ -0,0 +1,80 @@
+# Troubleshooting: Linux Firmware & ROCm
+
+## 🚨 CRITICAL WARNING: linux-firmware-20251125
+
+**Date:** 2026-01-08
+
+AMD pushed an update to `linux-firmware` (included in version `20251125`) that critically breaks ROCm functionality on Strix Halo systems. While this update has been recalled, many distributions (including Fedora) have not picked it up.
+
+If you are on this firmware version, you will likely experience **instability, crashes, or arbitrary failures** with ROCm workloads.
+
+### How to check your version
+
+```bash
+rpm -qa | grep linux-firmware
+```
+
+If you see `linux-firmware-20251125` or similar, you **must downgrade**.
+
+---
+
+## Downgrade Instructions (Fedora)
+
+The recommended stable version is `20251111`.
+
+### Fedora 43
+
+```bash
+# 1. Download the stable firmware packages
+wget -m https://kojipkgs.fedoraproject.org/packages/linux-firmware/20251111/1.fc43/noarch/ -I /packages/linux-firmware/20251111/1.fc43/noarch/
+
+# 2. Navigate to the download directory
+cd kojipkgs.fedoraproject.org/packages/linux-firmware/20251111/1.fc43/noarch/
+
+# 3. Downgrade
+sudo dnf downgrade *.rpm
+```
+
+### Fedora 42
+
+```bash
+# 1. Download the stable firmware packages
+wget -m https://kojipkgs.fedoraproject.org/packages/linux-firmware/20251111/1.fc42/noarch/ -I /packages/linux-firmware/20251111/1.fc42/noarch/
+
+# 2. Navigate to the download directory
+cd kojipkgs.fedoraproject.org/packages/linux-firmware/20251111/1.fc42/noarch/
+
+# 3. Downgrade
+sudo dnf downgrade *.rpm
+```
+
+---
+
+## Kernel & Modules Check
+
+After downgrading firmware, ensure your kernel and modules are consistent. You may want to reinstall/upgrade the kernel to ensure initramfs is rebuilt correctly or simply to match the tested configuration.
+
+```bash
+sudo dnf install kernel-6.18.3-200.fc43.x86_64 kernel-modules-extra-6.18.3-200.fc43.x86_64 kernel-tools-6.18.3-200.fc43.x86_64 --enablerepo=updates-testing
+```
+*(Adjust kernel version numbers as appropriate for your specific distribution state)*
+
+Finally, **reboot** your system:
+
+```bash
+shutdown -r now
+```
+
+---
+
+## Credits & References
+
+Huge thanks to the **Strix Halo Home Lab** Discord community for identifying this regression and testing the fixes.
+
+Specific thanks to:
+- **lorphos**
+- **kazak**
+
+Relevant discussion threads:
+- [Discord Thread 1](https://discord.com/channels/1384139280020148365/1455307501472976979/threads/1458579104315080779)
+- [Discord Thread 2](https://discord.com/channels/1384139280020148365/1458512705093763387)