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 1 commit
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
64 changes: 58 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> 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>
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,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">
Expand Down Expand Up @@ -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 => {
Expand All @@ -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';
Expand All @@ -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>
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 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>
Expand Down Expand Up @@ -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">
Expand All @@ -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>
Expand Down