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 3 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
54 changes: 47 additions & 7 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> Firmware supplied by your Linux distribution</li>
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.

This isn't true for all distros and this is a common section. Please leave it as is.

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.

Reverted this shared Background item to the original generic wording (Version 1.1.0.0 or later) so it doesn’t imply a distro-specific packaging model

<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,32 @@ <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>.</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>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>
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.

for the purpose of running the flm validate command yous shouldn't need to export LD_LIBRARY_PATH or FLM_CONFIG_PATH to the environment for the whole shell (ie export). Just run the single application like that.

IE:

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

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.

Updated this to the single-command form so the env vars only apply to flm validate, rather than exporting them for the whole shell.

</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>
</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 +270,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 +285,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,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 have version <strong>1.1.0.0 or later</strong>.</p>
<p>If <code>flm validate</code> reports a firmware issue, update the firmware package from your Linux distribution and reboot.</p>
Copy link
Copy Markdown
Member

@superm1 superm1 Mar 9, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

Not true for all distros and this is in the generic FAQ. For example Ubuntu doesn't have updated firmware and you get it by running the DKMS package.
So I would just call it out as one way to potentially solve it.

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.

Softened this FAQ entry so it’s framed as one possible fix rather than a universal distro-independent answer, and pointed readers back to their distro’s recommended update path.

<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.


<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>
Expand All @@ -311,7 +338,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 +359,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