Skip to content

Add document that explains how to extend scope of npu-umd-test #101

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

Merged
merged 1 commit into from
Sep 23, 2025
Merged

Add document that explains how to extend scope of npu-umd-test #101

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
110 changes: 81 additions & 29 deletions docs/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ SPDX-License-Identifier: MIT
│ User Mode Driver │ │ NPU compiler │
│ │ │ │
│ intel-level-zero-npu ◀═══▶ intel-driver-compiler-npu │
│ (libze_intel_vpu.so) │ │ (libnpu_driver_compiler.so) │
│ (libze_intel_npu.so) │ │ (libnpu_driver_compiler.so) │
│ │ │ │
└──────────────────▲──────────────────┘ └────────────────────────────────────────┘
╚════════════════════╗
Expand All @@ -51,6 +51,15 @@ SPDX-License-Identifier: MIT

## Changelog

<details>
<summary>Driver library name change from libze_intel_vpu.so to libze_intel_npu.so (from v1.16.0)</summary>

Starting from v1.16.0 release the driver library name has been changed from `libze_intel_vpu.so` to
`libze_intel_npu.so`. The old library name is still supported for backward compatibility in Level
Zero loader, but it is recommended to use the new library name. Using an older version of Level Zero
than v1.17.17 requires to keep the old library name.

</details>

<details>
<summary>zeMutableCommandList extension implementation (from v1.6.0)</summary>
Expand Down Expand Up @@ -111,7 +120,7 @@ set, the `ZE_INTEL_NPU_LOGMASK` allows to target specific log group. The log
group are listed in
[umd/vpu_driver/source/utilities/log.hpp](../umd/vpu_driver/source/utilities/log.hpp#L19)

```
```bash
# Set log level to INFO
export ZE_INTEL_NPU_LOGLEVEL=INFO

Expand Down Expand Up @@ -147,7 +156,7 @@ and set "modularize" for `Intel NPU (Neural Processing Unit)`.
<details>
<summary>Finding the intel_vpu kernel module in the system</summary>

```
```bash
# check if the intel_vpu exists is in the system
modinfo intel_vpu

Expand All @@ -165,16 +174,24 @@ ls /dev/accel/accel0
```
</details>

## Driver package installation

The driver binary package and installation process can be found in the [release
page](https://github.com/intel/linux-npu-driver/releases). The list of disbributed packages:
* intel-fw-npu: firmware binaries
* intel-level-zero-npu: user space driver library with name libze_intel_npu.so
* intel-driver-compiler-npu: NPU compiler library with name libnpu_driver_compiler.so

## Building a standalone driver

Install the required dependencies in Ubuntu:
```
```bash
sudo apt update
sudo apt install -y build-essential git git-lfs cmake python3
```

Commands to build the driver:
```
```bash
cd linux-npu-driver
git submodule update --init --recursive

Expand All @@ -197,8 +214,8 @@ Compiler-in-Driver component from [NPU compiler repository](https://github.com/o
OpenVINO runtime is required by compiler. About the dependencies for building OpenVINO,
please check the [OpenVINO build document](https://github.com/openvinotoolkit/openvino/blob/master/docs/dev/build.md).

To build a compiler from the driver repository the `ENABLE_NPU_COMPILER_BUILD` flag has to be set:
```
To build a compiler the `ENABLE_NPU_COMPILER_BUILD` flag has to be set:
```bash
cd linux-npu-driver
git submodule update --init --recursive

Expand Down Expand Up @@ -226,7 +243,7 @@ The binary `npu-umd-test` is located in the build folder, ex. `build/bin/`.

Command line to run functional tests (after driver installation):

```
```bash
npu-umd-test
```

Expand All @@ -236,7 +253,7 @@ control the inference test content. Those tests require compiler in system.

Config file requires to download any OpenVINO model. Command line to setup a
`basic.yaml`:
```
```bash
# Prepare the add_abc model in path pointed by basic.yaml
mkdir -p models/add_abc
curl -o models/add_abc/add_abc.xml https://raw.githubusercontent.com/openvinotoolkit/openvino/master/src/core/tests/models/ir/add_abc.xml
Expand All @@ -250,12 +267,54 @@ More information about config can be found in [validation/umd-test/configs](/val

## Troubleshooting

<details>
<summary>Device is not detectable</summary>

To check if device is available the user can use `npu-umd-test` or `hello_query_device` from the OpenVINO sample applications.
To debug missing NPU device, the `strace` allows to trace system calls that initalize the device. Run test command with `strace`:

```bash
# Record system calls using strace and npu-umd-test
strace -o strace.log --trace=file ./build/bin/npu-umd-test
...
# Or using OpenVINO python API
strace -o strace.log --trace=file python -c "from openvino import Core; print(Core().available_devices)"
...
```
> [!WARNING]
> After v1.16.0 release the driver library has a libze_intel_npu.so.1 name. If you are using
> libze_intel_vpu.so.1 by mistake, please remove it from system

Analyze the `strace.log` file for system calls that open NPU libraries and device:

```bash
grep -E "(accel|libnpu_|libze_)" strace.log
# Below output from command
...
# Check if the Level Zero loader is found in system
openat(AT_FDCWD, "/lib/x86_64-linux-gnu/libze_loader.so.1", O_RDONLY|O_CLOEXEC) = 3
....
# libze_intel_vpu.so.1 should not be used after v1.16.0 release, consider to remove it if it is in the system
openat(AT_FDCWD, "/usr/lib/x86_64-linux-gnu/libze_intel_vpu.so.1", O_RDONLY|O_CLOEXEC) = -1 ENOENT (No such file or directory)
...
# Check if driver library is found
openat(AT_FDCWD, "/lib/x86_64-linux-gnu/libze_intel_npu.so.1", O_RDONLY|O_CLOEXEC) = 3
...
# Check if driver successfully opened accel0. If unsuccessful, check next section
openat(AT_FDCWD, "/dev/accel/accel0", O_RDWR|O_NOFOLLOW|O_CLOEXEC) = 3
...
# Check if compiler was found
openat(AT_FDCWD, "/lib/x86_64-linux-gnu/libnpu_driver_compiler.so", O_RDONLY|O_CLOEXEC) = 3
...
```
</details>

<details>
<summary>Non-root access to the NPU device</summary>

To access the NPU device, the user must be in the "render" or "video" group.
A group depends on system configuration:
```
```bash
# check user groups
groups

Expand All @@ -271,7 +330,7 @@ but might not be available in your Linux distribution. See

If setting the "render" group does not resolve the non-root access issue,
this must be done by an administrator manually:
```
```bash
# check device permissions
ls -l /dev/accel/

Expand All @@ -286,50 +345,44 @@ $ ls -lah /dev/accel/accel0
crw-rw---- 1 root render 261, 0 Jan 31 15:58 /dev/accel/accel0
```
</details>

<details>
<summary>Compilation problem due to lack of memory</summary>

The compilation may fail due to memory shortage. The recommendation is to
use the Ninja generator instead of Unix Makefiles. If it does not help, please
The compilation may fail due to memory shortage. The recommendation is to use the Ninja generator
instead of Unix Makefiles and extending swap memory. If it does not help, please
[file a new issue](https://github.com/intel/linux-npu-driver/issues/new).

```
# install Ninja
sudo apt update
sudo apt install -y ninja-build

# remove the old build and create a new one
rm build -rf
cmake -B build -S . -G Ninja
```
</details>

<details>
<summary>Enable driver log using an environment variable</summary>

Valid logging levels are `ERROR`, `WARNING`, `INFO` (and `VERBOSE` for driver
older than v1.5.0 release)

Seting the logging level using the `ZE_INTEL_NPU_LOGLEVEL` environment variable:
```
```bash
export ZE_INTEL_NPU_LOGLEVEL=<logging_level>
```

Command to clear an exported value:
```
```bash
unset ZE_INTEL_NPU_LOGLEVEL
```

Setting `ZE_INTEL_NPU_LOGMASK` allows to print specific log groups in driver.
The log group are listed in
[umd/vpu_driver/source/utilities/log.hpp](../umd/vpu_driver/source/utilities/log.hpp#L19)

```
```bash
# Set log level to INFO to enable LOGMASK
export ZE_INTEL_NPU_LOGLEVEL=INFO

# Set log mask to only print from DEVICE, DRIVER and CACHE groups
export ZE_INTEL_NPU_LOGMASK=$((1<<4|1<<3|1<<17))
```

</details>

<details>
Expand All @@ -338,17 +391,16 @@ export ZE_INTEL_NPU_LOGMASK=$((1<<4|1<<3|1<<17))
The user can use different kernel and firmware combination for NPU device. The
user might receive the following error message:

```
```bash
ERROR! MAPPED_INFERENCE_VERSION is NOT compatible with the ELF Expected: 6.1.0 vs received: 7.0.0
```

It means that NPU compiler mismatches the NPU firmware. To fix this issue the
user needs to upgrade the firmware. Firmware update should be done from
driver repository using release tag that matches the NPU compiler:

```
```bash
cmake -B build -S .
cmake --install build/ --component fw-npu --prefix /
```

</details>
</details>
Loading