Skip to content

docs: add Fedora FLM setup guidance #1320

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
OmerFarukOruc wants to merge 4 commits into
base: main
Choose a base branch
from
+55 −6
Open

docs: add Fedora FLM setup guidance #1320

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
748a829
docs: add Fedora FLM setup guidance
OmerFarukOruc Mar 7, 2026
ed1eb75
docs: narrow Fedora FLM setup guidance
OmerFarukOruc Mar 8, 2026
6d9758f
docs: simplify Fedora FLM setup guidance
OmerFarukOruc Mar 9, 2026
1bc40ac
docs: address maintainer review on FLM Linux guide
OmerFarukOruc Mar 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/dev-getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
67 changes: 61 additions & 6 deletions docs/flm_npu_linux.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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> 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>
Expand All @@ -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>
Expand All @@ -73,6 +74,45 @@ <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 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>
<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>
<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>
</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">
Expand Down Expand Up @@ -243,7 +283,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 => {
Expand All @@ -258,7 +298,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';
Expand All @@ -278,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 version <strong>1.1.0.0 or later</strong>.</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>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>
Copy link
Copy Markdown
Member

@superm1 superm1 Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Considering my above comments I guess with this text maybe it should be more wishy washy than assertive.

Copy link
Copy Markdown
Contributor Author

@OmerFarukOruc OmerFarukOruc Mar 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Made the firmware troubleshooting text less assertive and more distro-agnostic to match the generic FAQ context.

<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>
Expand Down Expand Up @@ -311,7 +353,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>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>
</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">
Expand All @@ -320,6 +374,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>
Expand Down