From 748a829be30ef55c4fdaed0672d8e6dc4a616b37 Mon Sep 17 00:00:00 2001
From: Omer Faruk Oruc <omerfarukoruc35@gmail.com>
Date: Sat, 7 Mar 2026 14:22:03 +0300
Subject: [PATCH 1/4] docs: add Fedora FLM setup guidance

---
 docs/dev-getting-started.md |  8 +++++
 docs/flm_npu_linux.html     | 64 +++++++++++++++++++++++++++++++++----
 2 files changed, 66 insertions(+), 6 deletions(-)

diff --git a/docs/dev-getting-started.md b/docs/dev-getting-started.md
index 1fb79c41c..f9552fe99 100644
--- a/docs/dev-getting-started.md
+++ b/docs/dev-getting-started.md
@@ -164,6 +164,8 @@ chmod +x build/app-appimage/Lemonade-*.AppImage
 - This avoids LGPL dependencies (GTK3, libappindicator3, libnotify)
 - Run server using: `lemonade-server serve` (headless mode is automatic)
 - Fully functional for server operations and model management
+- `./setup.sh` supports Fedora via `dnf` and installs the common build dependencies automatically
+- Local RPM packaging also requires `rpmbuild` (`sudo dnf install rpm-build`)
 - Uses permissively licensed dependencies only (MIT, Apache 2.0, BSD, curl license)
 - Clean .deb package with only runtime files (no development headers)
 - PID file system for reliable process management
@@ -275,6 +277,10 @@ lemonade-server serve
 
 Very similar to the Debian instructions above with minor changes
 
+**Prerequisites:**
+- Completed C++ build (see above)
+- `rpmbuild` available (Fedora: `sudo dnf install rpm-build`)
+
 **Building:**
 
 ```bash
@@ -304,6 +310,8 @@ sudo dnf remove lemonade-server
 
 Same as .deb above
 
+For Fedora-specific FLM / XDNA setup notes, see the [Linux FLM / NPU guide](./flm_npu_linux.html).
+
 **macOS:**
 
 ### Building from Source on MacOS for M-Series / arm64 Family
diff --git a/docs/flm_npu_linux.html b/docs/flm_npu_linux.html
index bad8fedac..115ef04fb 100644
--- a/docs/flm_npu_linux.html
+++ b/docs/flm_npu_linux.html
@@ -47,7 +47,7 @@ <h2>Background</h2>
           <strong>Requirements:</strong>
         </p>
         <ul>
-          <li><strong>NPU Firmware:</strong> Version 1.1.0.0 or later</li>
+          <li><strong>NPU Firmware:</strong> A compatible XDNA2 firmware version from your distro or XRT package (older examples may show <code>1.1.x.x</code>, while newer Fedora setups may report values such as <code>255.x.x.x</code>)</li>
           <li><strong>Kernel:</strong> Must have the <strong>amdxdna</strong> driver (from kernel 7.0 or later, or via DKMS package as provided in instructions below)</li>
           <li><strong>Runtime:</strong> FLM (FastFlowLM) installed</li>
           <li><strong>System limits:</strong> Sufficient memlock limits (handled by Lemonade's systemd service)</li>
@@ -65,6 +65,7 @@ <h2>Setup</h2>
           <label for="distro-select" class="distro-label"><strong>Select your Linux distribution:</strong></label>
           <select id="distro-select" class="distro-selector">
             <option value="" selected disabled>Select your distro…</option>
+            <option value="fedora-43">Fedora 43</option>
             <option value="ubuntu-24">Ubuntu 24.04</option>
             <option value="ubuntu-25">Ubuntu 25.10</option>
             <option value="ubuntu-26">Ubuntu 26.04</option>
@@ -73,6 +74,42 @@ <h2>Setup</h2>
           </select>
         </div>
 
+        <div class="distro-instructions" id="distro-fedora-43" style="display:none;">
+          <div class="option-box option-primary">
+            <div class="option-header">
+              <span class="option-label">For Fedora 43</span>
+            </div>
+            <ol>
+              <li>Install the standard Lemonade build prerequisites from <a href="https://github.com/lemonade-sdk/lemonade/blob/main/docs/dev-getting-started.md" target="_blank">dev-getting-started.md</a>, then install the extra XRT / FLM build dependencies and the matching kernel development package for your running kernel:<br>
+                <div class="code-block"><code>sudo dnf install boost-devel boost-static json-glib-devel libcurl-devel libuuid-devel rapidjson-devel opencl-headers ocl-icd-devel pybind11-devel python3-pybind11<br># Also install the matching kernel-devel / kernel-headers package for your running kernel</code></div>
+              </li>
+              <li>Raise the shell memlock limit for FLM validation outside of the Lemonade service:<br>
+                <div class="code-block"><code>printf '* soft memlock unlimited\n* hard memlock unlimited\n' | sudo tee /etc/security/limits.d/99-amdxdna.conf<br>sudo reboot</code></div>
+                <span style="font-size:0.95em; color:#666;">A fresh login or reboot is required before an existing shell will see the new limit. The packaged Lemonade service already sets <code>LimitMEMLOCK=infinity</code>.</span>
+              </li>
+              <li>Build and install AMD XRT and the AMD XDNA plugin from source:<br>
+                <div class="code-block"><code>git clone --recursive https://github.com/amd/xdna-driver.git ~/src/xdna-driver<br>cd ~/src/xdna-driver/xrt/build<br>./build.sh -npu -opt -noctest -j $(nproc)<br>cd Release<br>make package -j $(nproc)<br>cd ~/src/xdna-driver/build<br>./build.sh -release -j $(nproc)<br>sudo dnf install -y ~/src/xdna-driver/xrt/build/Release/*.rpm ~/src/xdna-driver/build/Release/*.rpm</code></div>
+              </li>
+              <li>Build and install FastFlowLM:<br>
+                <div class="code-block"><code>git clone https://github.com/FastFlowLM/FastFlowLM.git ~/src/FastFlowLM<br>git -C ~/src/FastFlowLM submodule update --init --recursive<br>cd ~/src/FastFlowLM<br>cmake -S src --preset linux-default<br>ninja -C src/build -j $(nproc)<br>sudo cmake --install src/build</code></div>
+              </li>
+              <li>Export the FLM runtime environment and validate the NPU stack:<br>
+                <div class="code-block"><code>export LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}<br>export FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json<br>/opt/fastflowlm/bin/flm validate</code></div>
+                On recent Fedora / XDNA2 systems the firmware may be reported in a newer format such as <code>255.0.11.69</code> rather than older <code>1.1.x.x</code> examples.<br>
+                <div class="code-block" style="margin-top:0.5rem; background:#222; color:#fff;">
+❮ /opt/fastflowlm/bin/flm validate<br>[FLM]  Using custom model list path: /opt/fastflowlm/share/flm/model_list.json<br>[Linux]  Kernel: 6.19.3-cachyos3.fc43.x86_64<br>[Linux]  NPU: /dev/accel/accel0 with 8 columns<br>[Linux]  NPU FW Version: 255.0.11.69<br>[Linux]  amdxdna version: 1.0<br>[Linux]  Memlock Limit: infinity
+                </div>
+              </li>
+              <li>If you installed <code>lemonade-server</code> as a systemd service, add a drop-in with the beta flag and FLM runtime paths:<br>
+                <div class="code-block"><code>sudo install -d /etc/systemd/system/lemonade-server.service.d<br>printf '[Service]\nEnvironment=LEMONADE_FLM_LINUX_BETA=1\nEnvironment=LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib\nEnvironment=FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json\n' | sudo tee /etc/systemd/system/lemonade-server.service.d/10-flm-beta.conf<br>sudo systemctl daemon-reload<br>sudo systemctl enable --now lemonade-server.service</code></div>
+              </li>
+              <li>Verify the service and local API:<br>
+                <div class="code-block"><code>systemctl status lemonade-server.service --no-pager<br>curl -i http://127.0.0.1:8000/api/v1/models</code></div>
+              </li>
+            </ol>
+          </div>
+        </div>
+
         <!-- Ubuntu 24.04 and 25.10 Instructions -->
         <div class="distro-instructions" id="distro-ubuntu-24" style="display:none;">
           <div class="option-box option-primary">
@@ -243,7 +280,7 @@ <h2>Setup</h2>
           // Distro selector logic
           document.addEventListener('DOMContentLoaded', function() {
             const select = document.getElementById('distro-select');
-            const ids = ['ubuntu-24', 'ubuntu-25', 'ubuntu-26', 'arch', 'other'];
+            const ids = ['fedora-43', 'ubuntu-24', 'ubuntu-25', 'ubuntu-26', 'arch', 'other'];
             const faq = document.getElementById('flm-faq-section');
             // Hide all by default
             ids.forEach(id => {
@@ -258,7 +295,9 @@ <h2>Setup</h2>
               });
               if (faq) faq.style.display = 'block';
               const val = select.value;
-              if (val === 'ubuntu-24') {
+              if (val === 'fedora-43') {
+                document.getElementById('distro-fedora-43').style.display = 'block';
+              } else if (val === 'ubuntu-24') {
                 document.getElementById('distro-ubuntu-24').style.display = 'block';
               } else if (val === 'ubuntu-25') {
                 document.getElementById('distro-ubuntu-25').style.display = 'block';
@@ -278,12 +317,12 @@ <h2>Setup</h2>
         <h2>Common flm validate issues</h2>
 
         <h3>1. Outdated NPU Firmware</h3>
-        <p>If <code>flm validate</code> reports a firmware issue, ensure you have version <strong>1.1.0.0 or later</strong>.</p>
+        <p>If <code>flm validate</code> reports a firmware issue, ensure you have the firmware version line recommended by your distribution or XRT package.</p>
         <p>You can check your version manually with:</p>
         <div class="code-block">
           <code>cat /sys/bus/pci/drivers/amdxdna/*/fw_version</code>
         </div>
-        <p>If the firmware is older than 1.1.0.0, you'll need to update it through your Linux distribution (typically by updating the <code>linux-firmware</code> package).</p>
+        <p>Older examples may show version numbers like <code>1.1.x.x</code>. Recent Fedora / XDNA2 setups may report newer values such as <code>255.0.11.69</code>. If your distro packages the firmware separately, update that package; if you built from <code>amd/xdna-driver</code>, verify the installed XRT / XDNA packages match your running kernel.</p>
 
         <h3>2. Missing or Outdated amdxdna Driver</h3>
         <p>The NPU requires the <strong>amdxdna</strong> driver, which is included in Linux kernel 7.0 and later, or can be installed via the <code>amdxdna-dkms</code> package as described in the instructions above.</p>
@@ -311,7 +350,19 @@ <h3>3. Memlock limit too low</h3>
           <pre><code>*    soft    memlock    unlimited
 *    hard    memlock    unlimited</code></pre>
         </div>
-        <p>Then <strong>log out and log back in</strong> for changes to take effect.</p>
+        <p>Then <strong>log out and log back in</strong> (or reboot) for changes to take effect. Existing shells can keep the old limit even after the file is correct.</p>
+
+        <h3>4. FLM is on PATH, but Lemonade or FLM cannot find XRT libraries or the model list</h3>
+        <p>On some Linux distributions, finding <code>flm</code> on your <code>PATH</code> is not enough. If you see errors about <code>libxrt_coreutil.so.2</code> or a missing <code>model_list.json</code>, set:</p>
+        <div class="code-block">
+          <pre><code>LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib
+FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json</code></pre>
+        </div>
+        <p>Export these in your shell before running <code>/opt/fastflowlm/bin/flm</code>, or add them to a Lemonade systemd drop-in if you are running the service.</p>
+
+        <h3>5. <code>lemonade-server recipes</code> still says FLM requires Windows</h3>
+        <p>During the current Linux beta, <code>lemonade-server recipes</code> can still show <code>flm  npu  unsupported  Requires Windows</code> even when the Linux FLM stack is working.</p>
+        <p>Treat <code>flm validate</code>, <code>systemctl status lemonade-server.service</code>, and a successful local API probe as the authoritative checks instead.</p>
       </div>
 
       <div class="install-section">
@@ -320,6 +371,7 @@ <h2>Additional Resources</h2>
           For detailed NPU setup instructions and troubleshooting:
         </p>
         <ul>
+          <li><a href="https://github.com/lemonade-sdk/lemonade/blob/main/docs/dev-getting-started.md" target="_blank">Lemonade development and packaging guide</a></li>
           <li><a href="https://github.com/FastFlowLM/FastFlowLM" target="_blank">FastFlowLM GitHub Repository</a></li>
         </ul>
       </div>

From ed1eb753de55688cef9050acbb0948d6c77ffb71 Mon Sep 17 00:00:00 2001
From: Omer Faruk Oruc <omerfarukoruc35@gmail.com>
Date: Sun, 8 Mar 2026 16:29:39 +0300
Subject: [PATCH 2/4] docs: narrow Fedora FLM setup guidance

---
 docs/flm_npu_linux.html | 37 ++++++++++++++++++++-----------------
 1 file changed, 20 insertions(+), 17 deletions(-)

diff --git a/docs/flm_npu_linux.html b/docs/flm_npu_linux.html
index 115ef04fb..aa26e59a2 100644
--- a/docs/flm_npu_linux.html
+++ b/docs/flm_npu_linux.html
@@ -47,7 +47,7 @@ <h2>Background</h2>
           <strong>Requirements:</strong>
         </p>
         <ul>
-          <li><strong>NPU Firmware:</strong> A compatible XDNA2 firmware version from your distro or XRT package (older examples may show <code>1.1.x.x</code>, while newer Fedora setups may report values such as <code>255.x.x.x</code>)</li>
+          <li><strong>NPU Firmware:</strong> Production XDNA2 firmware from your Linux distribution (older working examples commonly show <code>1.1.x.x</code>; avoid using development <code>255.x.x.x</code> firmware as the default setup)</li>
           <li><strong>Kernel:</strong> Must have the <strong>amdxdna</strong> driver (from kernel 7.0 or later, or via DKMS package as provided in instructions below)</li>
           <li><strong>Runtime:</strong> FLM (FastFlowLM) installed</li>
           <li><strong>System limits:</strong> Sufficient memlock limits (handled by Lemonade's systemd service)</li>
@@ -80,28 +80,31 @@ <h2>Setup</h2>
               <span class="option-label">For Fedora 43</span>
             </div>
             <ol>
-              <li>Install the standard Lemonade build prerequisites from <a href="https://github.com/lemonade-sdk/lemonade/blob/main/docs/dev-getting-started.md" target="_blank">dev-getting-started.md</a>, then install the extra XRT / FLM build dependencies and the matching kernel development package for your running kernel:<br>
-                <div class="code-block"><code>sudo dnf install boost-devel boost-static json-glib-devel libcurl-devel libuuid-devel rapidjson-devel opencl-headers ocl-icd-devel pybind11-devel python3-pybind11<br># Also install the matching kernel-devel / kernel-headers package for your running kernel</code></div>
+              <li>Install the standard Lemonade build prerequisites from <a href="https://github.com/lemonade-sdk/lemonade/blob/main/docs/dev-getting-started.md" target="_blank">dev-getting-started.md</a>, then update Fedora's production firmware and reboot into the refreshed image:<br>
+                <div class="code-block"><code>sudo dnf upgrade linux-firmware<br>sudo reboot</code></div>
+                <span style="font-size:0.95em; color:#666;">Use the production firmware shipped by Fedora. Do not treat development <code>255.x.x.x</code> firmware as the default setup path.</span>
               </li>
-              <li>Raise the shell memlock limit for FLM validation outside of the Lemonade service:<br>
-                <div class="code-block"><code>printf '* soft memlock unlimited\n* hard memlock unlimited\n' | sudo tee /etc/security/limits.d/99-amdxdna.conf<br>sudo reboot</code></div>
-                <span style="font-size:0.95em; color:#666;">A fresh login or reboot is required before an existing shell will see the new limit. The packaged Lemonade service already sets <code>LimitMEMLOCK=infinity</code>.</span>
-              </li>
-              <li>Build and install AMD XRT and the AMD XDNA plugin from source:<br>
-                <div class="code-block"><code>git clone --recursive https://github.com/amd/xdna-driver.git ~/src/xdna-driver<br>cd ~/src/xdna-driver/xrt/build<br>./build.sh -npu -opt -noctest -j $(nproc)<br>cd Release<br>make package -j $(nproc)<br>cd ~/src/xdna-driver/build<br>./build.sh -release -j $(nproc)<br>sudo dnf install -y ~/src/xdna-driver/xrt/build/Release/*.rpm ~/src/xdna-driver/build/Release/*.rpm</code></div>
+              <li>If you need a manual XRT setup today, use the stable <a href="https://github.com/Xilinx/XRT/releases/tag/2.21.75" target="_blank">XRT 2.21.75 release</a> instead of the <code>amd/xdna-driver</code> git branch:<br>
+                <div class="code-block"><code>curl -L -o ~/Downloads/xrt-2.21.75.tar.gz https://github.com/Xilinx/XRT/releases/download/2.21.75/2.21.75.tar.gz<br>mkdir -p ~/src/xrt-2.21.75<br>tar -C ~/src/xrt-2.21.75 --strip-components=1 -xzf ~/Downloads/xrt-2.21.75.tar.gz<br>cd ~/src/xrt-2.21.75/xrt/XRT<br>sudo ./src/runtime_src/tools/scripts/xrtdeps.sh<br>cd build<br>./build.sh -npu -opt -noctest -j $(nproc)<br>cd Release<br>make package -j $(nproc)<br>sudo dnf install -y ./*.rpm</code></div>
+                <span style="font-size:0.95em; color:#666;">A Fedora COPR is the preferred long-term packaging path, but until that exists this keeps the instructions on the stable 2.21.75 release instead of a moving git checkout.</span>
               </li>
               <li>Build and install FastFlowLM:<br>
                 <div class="code-block"><code>git clone https://github.com/FastFlowLM/FastFlowLM.git ~/src/FastFlowLM<br>git -C ~/src/FastFlowLM submodule update --init --recursive<br>cd ~/src/FastFlowLM<br>cmake -S src --preset linux-default<br>ninja -C src/build -j $(nproc)<br>sudo cmake --install src/build</code></div>
               </li>
-              <li>Export the FLM runtime environment and validate the NPU stack:<br>
+              <li>If you run <code>flm validate</code> manually and it reports a low memlock limit, raise the shell memlock limit and re-login:<br>
+                <div class="code-block"><code>printf '* soft memlock unlimited\n* hard memlock unlimited\n' | sudo tee /etc/security/limits.d/99-amdxdna.conf<br>sudo reboot</code></div>
+                <span style="font-size:0.95em; color:#666;">A fresh login or reboot is required before an existing shell will see the new limit. The packaged Lemonade service already sets <code>LimitMEMLOCK=infinity</code>.</span>
+              </li>
+              <li>If you are using the current manual <code>/opt</code> install layout, export the FLM runtime environment and validate the NPU stack:<br>
                 <div class="code-block"><code>export LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}<br>export FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json<br>/opt/fastflowlm/bin/flm validate</code></div>
-                On recent Fedora / XDNA2 systems the firmware may be reported in a newer format such as <code>255.0.11.69</code> rather than older <code>1.1.x.x</code> examples.<br>
+                <span style="font-size:0.95em; color:#666;">If future Fedora packages install these files into <code>/usr</code>, you can skip these manual exports.</span><br>
                 <div class="code-block" style="margin-top:0.5rem; background:#222; color:#fff;">
-❮ /opt/fastflowlm/bin/flm validate<br>[FLM]  Using custom model list path: /opt/fastflowlm/share/flm/model_list.json<br>[Linux]  Kernel: 6.19.3-cachyos3.fc43.x86_64<br>[Linux]  NPU: /dev/accel/accel0 with 8 columns<br>[Linux]  NPU FW Version: 255.0.11.69<br>[Linux]  amdxdna version: 1.0<br>[Linux]  Memlock Limit: infinity
+❮ /opt/fastflowlm/bin/flm validate<br>[FLM]  Using custom model list path: /opt/fastflowlm/share/flm/model_list.json<br>[Linux]  Kernel: 6.19.3-cachyos3.fc43.x86_64<br>[Linux]  NPU: /dev/accel/accel0 with 8 columns<br>[Linux]  NPU FW Version: 1.1.2.64<br>[Linux]  amdxdna version: 1.0<br>[Linux]  Memlock Limit: infinity
                 </div>
               </li>
-              <li>If you installed <code>lemonade-server</code> as a systemd service, add a drop-in with the beta flag and FLM runtime paths:<br>
-                <div class="code-block"><code>sudo install -d /etc/systemd/system/lemonade-server.service.d<br>printf '[Service]\nEnvironment=LEMONADE_FLM_LINUX_BETA=1\nEnvironment=LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib\nEnvironment=FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json\n' | sudo tee /etc/systemd/system/lemonade-server.service.d/10-flm-beta.conf<br>sudo systemctl daemon-reload<br>sudo systemctl enable --now lemonade-server.service</code></div>
+              <li>If you installed <code>lemonade-server</code> as a systemd service, add a drop-in with the beta flag. If you are using the current manual <code>/opt</code> installs, also add the FLM / XRT runtime paths:<br>
+                <div class="code-block"><code>sudo install -d /etc/systemd/system/lemonade-server.service.d<br>printf '[Service]\nEnvironment=LEMONADE_FLM_LINUX_BETA=1\n' | sudo tee /etc/systemd/system/lemonade-server.service.d/10-flm-beta.conf<br>sudo systemctl daemon-reload<br>sudo systemctl enable --now lemonade-server.service</code></div>
+                <span style="font-size:0.95em; color:#666;">For the current manual <code>/opt</code> layout, add <code>Environment=LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib</code> and <code>Environment=FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json</code> to the same drop-in.</span>
               </li>
               <li>Verify the service and local API:<br>
                 <div class="code-block"><code>systemctl status lemonade-server.service --no-pager<br>curl -i http://127.0.0.1:8000/api/v1/models</code></div>
@@ -317,12 +320,12 @@ <h2>Setup</h2>
         <h2>Common flm validate issues</h2>
 
         <h3>1. Outdated NPU Firmware</h3>
-        <p>If <code>flm validate</code> reports a firmware issue, ensure you have the firmware version line recommended by your distribution or XRT package.</p>
+        <p>If <code>flm validate</code> reports a firmware issue, ensure you are using the production firmware line recommended by your distribution.</p>
         <p>You can check your version manually with:</p>
         <div class="code-block">
           <code>cat /sys/bus/pci/drivers/amdxdna/*/fw_version</code>
         </div>
-        <p>Older examples may show version numbers like <code>1.1.x.x</code>. Recent Fedora / XDNA2 setups may report newer values such as <code>255.0.11.69</code>. If your distro packages the firmware separately, update that package; if you built from <code>amd/xdna-driver</code>, verify the installed XRT / XDNA packages match your running kernel.</p>
+        <p>Older working examples commonly show version numbers like <code>1.1.x.x</code>. If you instead see a development value such as <code>255.x.x.x</code>, switch back to the production firmware shipped by your distribution unless you are explicitly testing unstable bits. On Fedora, update the <code>linux-firmware</code> package and reboot.</p>
 
         <h3>2. Missing or Outdated amdxdna Driver</h3>
         <p>The NPU requires the <strong>amdxdna</strong> driver, which is included in Linux kernel 7.0 and later, or can be installed via the <code>amdxdna-dkms</code> package as described in the instructions above.</p>
@@ -353,7 +356,7 @@ <h3>3. Memlock limit too low</h3>
         <p>Then <strong>log out and log back in</strong> (or reboot) for changes to take effect. Existing shells can keep the old limit even after the file is correct.</p>
 
         <h3>4. FLM is on PATH, but Lemonade or FLM cannot find XRT libraries or the model list</h3>
-        <p>On some Linux distributions, finding <code>flm</code> on your <code>PATH</code> is not enough. If you see errors about <code>libxrt_coreutil.so.2</code> or a missing <code>model_list.json</code>, set:</p>
+        <p>This usually only applies to manual installs that place FLM under <code>/opt/fastflowlm</code> and XRT under <code>/opt/xilinx/xrt</code>. If you see errors about <code>libxrt_coreutil.so.2</code> or a missing <code>model_list.json</code>, set:</p>
         <div class="code-block">
           <pre><code>LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib
 FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json</code></pre>

From 6d9758f4947f9719c5a8b476fd375d432f76389d Mon Sep 17 00:00:00 2001
From: Omer Faruk Oruc <omerfarukoruc35@gmail.com>
Date: Mon, 9 Mar 2026 12:21:18 +0300
Subject: [PATCH 3/4] docs: simplify Fedora FLM setup guidance

---
 docs/flm_npu_linux.html | 33 +++++++++------------------------
 1 file changed, 9 insertions(+), 24 deletions(-)

diff --git a/docs/flm_npu_linux.html b/docs/flm_npu_linux.html
index aa26e59a2..5c269580e 100644
--- a/docs/flm_npu_linux.html
+++ b/docs/flm_npu_linux.html
@@ -47,7 +47,7 @@ <h2>Background</h2>
           <strong>Requirements:</strong>
         </p>
         <ul>
-          <li><strong>NPU Firmware:</strong> Production XDNA2 firmware from your Linux distribution (older working examples commonly show <code>1.1.x.x</code>; avoid using development <code>255.x.x.x</code> firmware as the default setup)</li>
+          <li><strong>NPU Firmware:</strong> Firmware supplied by your Linux distribution</li>
           <li><strong>Kernel:</strong> Must have the <strong>amdxdna</strong> driver (from kernel 7.0 or later, or via DKMS package as provided in instructions below)</li>
           <li><strong>Runtime:</strong> FLM (FastFlowLM) installed</li>
           <li><strong>System limits:</strong> Sufficient memlock limits (handled by Lemonade's systemd service)</li>
@@ -80,31 +80,18 @@ <h2>Setup</h2>
               <span class="option-label">For Fedora 43</span>
             </div>
             <ol>
-              <li>Install the standard Lemonade build prerequisites from <a href="https://github.com/lemonade-sdk/lemonade/blob/main/docs/dev-getting-started.md" target="_blank">dev-getting-started.md</a>, then update Fedora's production firmware and reboot into the refreshed image:<br>
-                <div class="code-block"><code>sudo dnf upgrade linux-firmware<br>sudo reboot</code></div>
-                <span style="font-size:0.95em; color:#666;">Use the production firmware shipped by Fedora. Do not treat development <code>255.x.x.x</code> firmware as the default setup path.</span>
-              </li>
-              <li>If you need a manual XRT setup today, use the stable <a href="https://github.com/Xilinx/XRT/releases/tag/2.21.75" target="_blank">XRT 2.21.75 release</a> instead of the <code>amd/xdna-driver</code> git branch:<br>
-                <div class="code-block"><code>curl -L -o ~/Downloads/xrt-2.21.75.tar.gz https://github.com/Xilinx/XRT/releases/download/2.21.75/2.21.75.tar.gz<br>mkdir -p ~/src/xrt-2.21.75<br>tar -C ~/src/xrt-2.21.75 --strip-components=1 -xzf ~/Downloads/xrt-2.21.75.tar.gz<br>cd ~/src/xrt-2.21.75/xrt/XRT<br>sudo ./src/runtime_src/tools/scripts/xrtdeps.sh<br>cd build<br>./build.sh -npu -opt -noctest -j $(nproc)<br>cd Release<br>make package -j $(nproc)<br>sudo dnf install -y ./*.rpm</code></div>
-                <span style="font-size:0.95em; color:#666;">A Fedora COPR is the preferred long-term packaging path, but until that exists this keeps the instructions on the stable 2.21.75 release instead of a moving git checkout.</span>
+              <li>Install the standard Lemonade build prerequisites from <a href="https://github.com/lemonade-sdk/lemonade/blob/main/docs/dev-getting-started.md" target="_blank">dev-getting-started.md</a>.</li>
+              <li>Install XRT from the stable <a href="https://github.com/Xilinx/XRT/releases/tag/2.21.75" target="_blank">2.21.75 release</a>:<br>
+                <div class="code-block"><code>curl -L -o ~/Downloads/xrt-2.21.75.tar.gz https://github.com/Xilinx/XRT/releases/download/2.21.75/2.21.75.tar.gz<br>mkdir -p ~/src/xrt-2.21.75<br>tar -C ~/src/xrt-2.21.75 --strip-components=1 -xzf ~/Downloads/xrt-2.21.75.tar.gz<br>cd ~/src/xrt-2.21.75/xrt/XRT<br>sudo ./src/runtime_src/tools/scripts/xrtdeps.sh<br>cd build<br>./build.sh -npu -opt -noctest -j $(nproc)<br>cd Release<br>sudo dnf install -y ./*.rpm</code></div>
               </li>
               <li>Build and install FastFlowLM:<br>
                 <div class="code-block"><code>git clone https://github.com/FastFlowLM/FastFlowLM.git ~/src/FastFlowLM<br>git -C ~/src/FastFlowLM submodule update --init --recursive<br>cd ~/src/FastFlowLM<br>cmake -S src --preset linux-default<br>ninja -C src/build -j $(nproc)<br>sudo cmake --install src/build</code></div>
               </li>
-              <li>If you run <code>flm validate</code> manually and it reports a low memlock limit, raise the shell memlock limit and re-login:<br>
-                <div class="code-block"><code>printf '* soft memlock unlimited\n* hard memlock unlimited\n' | sudo tee /etc/security/limits.d/99-amdxdna.conf<br>sudo reboot</code></div>
-                <span style="font-size:0.95em; color:#666;">A fresh login or reboot is required before an existing shell will see the new limit. The packaged Lemonade service already sets <code>LimitMEMLOCK=infinity</code>.</span>
-              </li>
-              <li>If you are using the current manual <code>/opt</code> install layout, export the FLM runtime environment and validate the NPU stack:<br>
-                <div class="code-block"><code>export LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}<br>export FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json<br>/opt/fastflowlm/bin/flm validate</code></div>
-                <span style="font-size:0.95em; color:#666;">If future Fedora packages install these files into <code>/usr</code>, you can skip these manual exports.</span><br>
-                <div class="code-block" style="margin-top:0.5rem; background:#222; color:#fff;">
-❮ /opt/fastflowlm/bin/flm validate<br>[FLM]  Using custom model list path: /opt/fastflowlm/share/flm/model_list.json<br>[Linux]  Kernel: 6.19.3-cachyos3.fc43.x86_64<br>[Linux]  NPU: /dev/accel/accel0 with 8 columns<br>[Linux]  NPU FW Version: 1.1.2.64<br>[Linux]  amdxdna version: 1.0<br>[Linux]  Memlock Limit: infinity
-                </div>
+              <li>Run validation:<br>
+                <div class="code-block"><code>export LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}<br>export FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json<br>/opt/fastflowlm/bin/flm validate</code></div>
               </li>
-              <li>If you installed <code>lemonade-server</code> as a systemd service, add a drop-in with the beta flag. If you are using the current manual <code>/opt</code> installs, also add the FLM / XRT runtime paths:<br>
-                <div class="code-block"><code>sudo install -d /etc/systemd/system/lemonade-server.service.d<br>printf '[Service]\nEnvironment=LEMONADE_FLM_LINUX_BETA=1\n' | sudo tee /etc/systemd/system/lemonade-server.service.d/10-flm-beta.conf<br>sudo systemctl daemon-reload<br>sudo systemctl enable --now lemonade-server.service</code></div>
-                <span style="font-size:0.95em; color:#666;">For the current manual <code>/opt</code> layout, add <code>Environment=LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib</code> and <code>Environment=FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json</code> to the same drop-in.</span>
+              <li>If you run <code>lemonade-server</code> as a systemd service, add the Linux beta flag and FLM paths:<br>
+                <div class="code-block"><code>sudo install -d /etc/systemd/system/lemonade-server.service.d<br>printf '[Service]\nEnvironment=LEMONADE_FLM_LINUX_BETA=1\nEnvironment=LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib64\nEnvironment=FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json\n' | sudo tee /etc/systemd/system/lemonade-server.service.d/10-flm-beta.conf<br>sudo systemctl daemon-reload<br>sudo systemctl enable --now lemonade-server.service</code></div>
               </li>
               <li>Verify the service and local API:<br>
                 <div class="code-block"><code>systemctl status lemonade-server.service --no-pager<br>curl -i http://127.0.0.1:8000/api/v1/models</code></div>
@@ -320,13 +307,11 @@ <h2>Setup</h2>
         <h2>Common flm validate issues</h2>
 
         <h3>1. Outdated NPU Firmware</h3>
-        <p>If <code>flm validate</code> reports a firmware issue, ensure you are using the production firmware line recommended by your distribution.</p>
+        <p>If <code>flm validate</code> reports a firmware issue, update the firmware package from your Linux distribution and reboot.</p>
         <p>You can check your version manually with:</p>
         <div class="code-block">
           <code>cat /sys/bus/pci/drivers/amdxdna/*/fw_version</code>
         </div>
-        <p>Older working examples commonly show version numbers like <code>1.1.x.x</code>. If you instead see a development value such as <code>255.x.x.x</code>, switch back to the production firmware shipped by your distribution unless you are explicitly testing unstable bits. On Fedora, update the <code>linux-firmware</code> package and reboot.</p>
-
         <h3>2. Missing or Outdated amdxdna Driver</h3>
         <p>The NPU requires the <strong>amdxdna</strong> driver, which is included in Linux kernel 7.0 and later, or can be installed via the <code>amdxdna-dkms</code> package as described in the instructions above.</p>
         <p>To check if the driver is loaded, run:</p>

From 1bc40acd1abc5c4004c25cbaa6f125f220634f1f Mon Sep 17 00:00:00 2001
From: Omer Faruk Oruc <omerfarukoruc35@gmail.com>
Date: Tue, 10 Mar 2026 22:30:54 +0300
Subject: [PATCH 4/4] docs: address maintainer review on FLM Linux guide

---
 docs/flm_npu_linux.html | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/docs/flm_npu_linux.html b/docs/flm_npu_linux.html
index 5c269580e..4caacb1a1 100644
--- a/docs/flm_npu_linux.html
+++ b/docs/flm_npu_linux.html
@@ -47,7 +47,7 @@ <h2>Background</h2>
           <strong>Requirements:</strong>
         </p>
         <ul>
-          <li><strong>NPU Firmware:</strong> Firmware supplied by your Linux distribution</li>
+          <li><strong>NPU Firmware:</strong> Version 1.1.0.0 or later</li>
           <li><strong>Kernel:</strong> Must have the <strong>amdxdna</strong> driver (from kernel 7.0 or later, or via DKMS package as provided in instructions below)</li>
           <li><strong>Runtime:</strong> FLM (FastFlowLM) installed</li>
           <li><strong>System limits:</strong> Sufficient memlock limits (handled by Lemonade's systemd service)</li>
@@ -88,13 +88,13 @@ <h2>Setup</h2>
                 <div class="code-block"><code>git clone https://github.com/FastFlowLM/FastFlowLM.git ~/src/FastFlowLM<br>git -C ~/src/FastFlowLM submodule update --init --recursive<br>cd ~/src/FastFlowLM<br>cmake -S src --preset linux-default<br>ninja -C src/build -j $(nproc)<br>sudo cmake --install src/build</code></div>
               </li>
               <li>Run validation:<br>
-                <div class="code-block"><code>export LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}<br>export FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json<br>/opt/fastflowlm/bin/flm validate</code></div>
+                <div class="code-block"><code>LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}} FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json /opt/fastflowlm/bin/flm validate</code></div>
               </li>
               <li>If you run <code>lemonade-server</code> as a systemd service, add the Linux beta flag and FLM paths:<br>
                 <div class="code-block"><code>sudo install -d /etc/systemd/system/lemonade-server.service.d<br>printf '[Service]\nEnvironment=LEMONADE_FLM_LINUX_BETA=1\nEnvironment=LD_LIBRARY_PATH=/opt/fastflowlm/lib:/opt/xilinx/xrt/lib64\nEnvironment=FLM_CONFIG_PATH=/opt/fastflowlm/share/flm/model_list.json\n' | sudo tee /etc/systemd/system/lemonade-server.service.d/10-flm-beta.conf<br>sudo systemctl daemon-reload<br>sudo systemctl enable --now lemonade-server.service</code></div>
               </li>
               <li>Verify the service and local API:<br>
-                <div class="code-block"><code>systemctl status lemonade-server.service --no-pager<br>curl -i http://127.0.0.1:8000/api/v1/models</code></div>
+                <div class="code-block"><code>systemctl status lemonade-server.service --no-pager<br>curl -i http://localhost:8000/api/v1/models</code></div>
               </li>
             </ol>
           </div>
@@ -307,11 +307,12 @@ <h2>Setup</h2>
         <h2>Common flm validate issues</h2>
 
         <h3>1. Outdated NPU Firmware</h3>
-        <p>If <code>flm validate</code> reports a firmware issue, update the firmware package from your Linux distribution and reboot.</p>
+        <p>If <code>flm validate</code> reports a firmware issue, one possible fix is to follow your distribution's recommended update path for the firmware or related packages, then reboot.</p>
         <p>You can check your version manually with:</p>
         <div class="code-block">
           <code>cat /sys/bus/pci/drivers/amdxdna/*/fw_version</code>
         </div>
+        <p>If the firmware is older than 1.1.0.0, check your distribution's documentation for the recommended update path, since it varies by distro.</p>
         <h3>2. Missing or Outdated amdxdna Driver</h3>
         <p>The NPU requires the <strong>amdxdna</strong> driver, which is included in Linux kernel 7.0 and later, or can be installed via the <code>amdxdna-dkms</code> package as described in the instructions above.</p>
         <p>To check if the driver is loaded, run:</p>