Skip to main content

Drivers

The BOS AI SDK requires kernel-mode and user-mode drivers to communicate with Eagle-N hardware. This section documents both the kernel-mode driver (KMD) and user-mode driver (UMD) components, along with installation and configuration instructions.

BOS-UMD​

This page introduces the BOS User-Mode Driver (UMD) and how to build it for supported Tenstorrent architectures. It provides core setup requirements, including Ubuntu dependencies and recommended compiler tooling. The guide explains system prerequisites such as IOMMU and hugepage behavior, with architecture-specific notes. It also outlines standard build and test flows, including optional GCC-based builds. Finally, it summarizes integration patterns and Eagle-N1-specific implementation structure for downstream use.

BOS AI User-Mode Driver​

Repository​

https://github.com/bos-semi-release/BOS_UMD

Software Dependencies​

BOS's UMD requires BOS's kernel-mode driver

Required Ubuntu dependencies:

sudo apt install -y libhwloc-dev cmake ninja-build zlib1g-dev ninja-build libyaml-cpp-dev libfmt-dev libboost-all-dev

Suggested third-party dependency is Clang 17:

wget https://apt.llvm.org/llvm.sh
chmod u+x llvm.sh
sudo ./llvm.sh 17

IOMMU and Hugepage requirements​

To determine whether your system requires hugepage configuration, run the provided script:

./scripts/iommu_detect.sh
Blackhole​

If your system IOMMU is enabled, no hugepage setup is required. You can enable hugepage with following command.

  • sudo -E env PATH=$PATH python3 ./scripts/setup_hugepages.py enable

After the command completes, reboot your PC and run the command again.

Build flow​

To build libdevice.so:

cmake -B build -G Ninja
cmake --build build

Tests are build separately for each architecture. Specify the ARCH_NAME environment variable as grayskull, wormhole_b0 or blackhole before building. You also need to configure cmake to enable tests, hence the need to run cmake configuration step again. To build tests:

cmake -B build -G Ninja -DTT_UMD_BUILD_TESTS=ON
cmake --build build

To build with GCC, set these environment variables before invoking cmake:

export CMAKE_C_COMPILER=/usr/bin/gcc
export CMAKE_CXX_COMPILER=/usr/bin/g++

Add Unit Tests​

in tests/blackholeplus/CMakeLists.txt :

# Example: Add new unit tests here
# Uncomment and modify these lines to add new test files:
# add_unit_test(unit_test_example "unit_test_example.cpp")
# add_unit_test(unit_test_feature "unit_test_feature.cpp" "helper_file.cpp")
# add_unit_test(unit_test_integration "unit_test_integration.cpp")

Integration​

UMD can be consumed by downstream projects in multiple ways.

From Source (CMake)​

You can link libdevice.so by linking against the umd::device target.

As a submodule/external project​

add_subdirectory(<path to umd>)

BOS-KMD​

The BOS Kernel-Mode Driver (KMD) provides low-level hardware access and device management for Eagle-N NPU. This section covers KMD installation, configuration, device file registration, and building with DKMS for streamlined driver management.

Repository​

[http://gitlab/bos_kmd]

Supported hardware:​

  • BOS NN Accelerator

The driver registers device files named /dev/bos/%d, one for each enumerated device.

How to Build and Install the BOS KMD Module Using DKMS​

  • You must have dkms installed
sudo apt-get install dkms
  • You have to set version of kmd module (For now, I'll set as 2.3.0)
export VERSION=2.3.0
  • Build & Install BOS KMD Module with DKMS
sudo dkms add .
sudo dkms build -m bos -v 2.3.0
sudo dkms install -m bos -v 2.3.0

sudo modprobe bos
  • Remove the module from DKMS
sudo dkms remove bos_kmd/2.3.0 --all
  • Insert Module
sudo insmod /path/dkms/bos.ko
  • Remove Module
sudo rmmod bos
  • Verify if the module is successfully inserted
lspci -v
  • You can use the .sh file to work at once (You have to create folder /usr/src/bos_kmd-2.3.0)
./set_dkms.sh
  • If you want to change the version of KMD, edit below the files
dkms.conf
module.c
set_dkms.h