Debian Package For KR260: A Step-by-Step Guide

by Alex Johnson 47 views

Introduction

Are you looking to create a Debian package for your KR260 with ZOCL DKMS? This comprehensive guide will walk you through the process step-by-step, ensuring you can successfully build and deploy your custom drivers. This article addresses the challenges encountered when trying to get the Ubuntu 24.04 image from Cannonical working on the KR260, specifically focusing on creating a Debian package for the ZOCL (Zynq® OpenCL™) driver with DKMS (Dynamic Kernel Module Support). The primary issue is the proper installation and building of the ZOCL driver to interface with the Xilinx Runtime (XRT) on the target system. We will explore the necessary steps to create a Debian package that correctly installs the ZOCL driver, resolves dependencies, and integrates with the kernel.

The initial problem reported was that after installing the Ubuntu 24.04 image, XRT was installed, but no devices were detected, even though /dev/fpga0 existed. The attempt to load the zocl module via modprobe failed, indicating a problem with the driver build. The user then tried to build the driver from source, compatible with version 2025.2, and successfully cross-compiled the code for the aarch64 architecture. However, they encountered difficulties in creating the Debian package using the build_edge_deb.sh script, which requires a debian/ folder. Manually copying files and running the postinst script resulted in a DKMS build failure due to missing references to XRT.

In this guide, we will cover the essential steps to create a Debian package, including setting up the debian/ folder, resolving dependencies, and ensuring the DKMS build process completes successfully. By following this guide, you will be able to create a robust and reliable Debian package for your KR260 with ZOCL DKMS.

Prerequisites

Before we dive into the process, let's ensure you have everything you need:

  • A working cross-compilation environment for the target architecture (aarch64 in this case).
  • The source code for the ZOCL driver, preferably cloned from a reliable repository.
  • Xilinx Runtime (XRT) installed on the target system.
  • Basic knowledge of Debian packaging.

Step 1: Setting Up the debian/ Folder

The debian/ folder is the heart of any Debian package. It contains all the necessary files and scripts to build, install, and manage your package. Here’s how to set it up:

  1. Create the debian/ folder: If it doesn't already exist, create a debian/ folder in the root of your driver source directory. This folder will house all the packaging-related files.

    mkdir debian
cd debian

  2. Essential Files: Inside the debian/ folder, you'll need several essential files:

    • control: Contains metadata about the package, such as name, version, dependencies, and description.
    • rules: A makefile that specifies how to build the package.
    • install: Specifies where to install the files.
    • changelog: Records changes made to the package over time.
    • copyright: Contains copyright information.
    • postinst: Script to be executed after package installation.
    • postrm: Script to be executed after package removal.
    • dkms.conf: Configuration file for DKMS.

Let's create these files and populate them with the necessary content.

1.1. The control File

The control file is crucial for defining your package’s metadata. Here’s an example of a control file for the ZOCL driver:

Source: zocl
Section: kernel
Priority: optional
Maintainer: Your Name <your.email@example.com>
Build-Depends: debhelper (>= 11), dkms, xrt
Standards-Version: 4.1.4

Package: zocl-dkms
Architecture: any
Depends: dkms, xrt
Description: ZOCL driver for Xilinx devices
 This package provides the ZOCL driver for Xilinx FPGAs,
 built using DKMS for easy kernel updates.

In this file:

  • Source: The name of the source package.
  • Section: The category of the package (kernel drivers in this case).
  • Priority: The priority of the package.
  • Maintainer: Your name and email address.
  • Build-Depends: Packages required to build the Debian package.
  • Standards-Version: Debian policy standards version.
  • Package: The name of the binary package.
  • Architecture: any for architecture-independent packages.
  • Depends: Packages required to install the Debian package.
  • Description: A brief description of the package.

1.2. The rules File

The rules file is a makefile that defines the build process. Here’s a typical rules file for a DKMS package:

#!/usr/bin/make -f

%:  
	dh $@

override_dh_auto_build:

override_dh_auto_install:
	dh_install

override_dh_dkms:
	dh_dkms --dkms_name=zocl

This file uses debhelper commands to automate the build process. The dh_dkms command is used to integrate with DKMS, specifying the DKMS module name as zocl.

1.3. The install File

The install file specifies which files to install and where. For a DKMS package, you typically need to install the driver source files. Here’s an example:

*.ko /usr/src/zocl-2.20.0/

This file instructs the package manager to install all .ko (kernel object) files into the /usr/src/zocl-2.20.0/ directory. You should replace 2.20.0 with the actual version of your driver.

1.4. The changelog File

The changelog file records changes to the package. You can create an initial entry using the dch command:

dch -i

This command will open an editor where you can enter the changelog information. A typical entry looks like this:

zocl (2.20.0-1) unstable; urgency=low

  * Initial release.

 -- Your Name <your.email@example.com>  Thu, 27 Jun 2024 10:00:00 +0000

1.5. The copyright File

The copyright file contains copyright information for your package. Include the copyright notice for the driver and any other relevant information.

1.6. The postinst Script

The postinst script is executed after the package is installed. For a DKMS package, it’s crucial to register the module with DKMS. Here’s an example:

#!/bin/sh

set -e

dkms add -m zocl -v 2.20.0 || exit 1
dkms autoinstall -m zocl -v 2.20.0 || exit 1

exit 0

This script adds the module to DKMS and attempts to build and install it for the currently running kernel. If you encounter issues related to DKMS failing to install XRT drivers, as mentioned in the original problem, it is crucial to ensure that the XRT development headers are installed. This often involves installing a package like xrt-dev or similar, which provides the necessary header files for DKMS to build the ZOCL module against the XRT libraries.

1.7. The postrm Script

The postrm script is executed after the package is removed. It should remove the module from DKMS. Here’s an example:

#!/bin/sh

set -e

dkms remove -m zocl -v 2.20.0 --all || exit 1

exit 0

This script removes the module from DKMS, ensuring it’s properly uninstalled.

1.8. The dkms.conf File

The dkms.conf file provides DKMS with the information it needs to build the module. Here’s an example:

PACKAGE_NAME="zocl"
PACKAGE_VERSION="2.20.0"
MAKE="make"
CLEAN="make clean"
BUILT_MODULE_NAME[0]="zocl"
BUILT_MODULE_LOCATION[0]="."
DEST_MODULE_LOCATION[0]="/updates"
AUTOINSTALL="yes"

In this file:

  • PACKAGE_NAME: The name of the package.
  • PACKAGE_VERSION: The version of the package.
  • MAKE: The command to build the module.
  • CLEAN: The command to clean the build directory.
  • BUILT_MODULE_NAME: The name of the kernel module.
  • BUILT_MODULE_LOCATION: The location of the module in the source tree.
  • DEST_MODULE_LOCATION: The destination directory for the module.
  • AUTOINSTALL: Automatically install the module when a new kernel is installed.

Step 2: Building the Debian Package

With the debian/ folder set up, you can now build the Debian package. Use the dpkg-buildpackage command:

dpkg-buildpackage -uc -b

This command will build the package. The -uc option skips signing the changelog, and the -b option builds a binary package.

If you encounter errors during the build process, carefully review the output and check your debian/ files for any mistakes. Common issues include incorrect dependencies, syntax errors in scripts, and missing files.

Step 3: Installing the Debian Package

Once the package is built, you can install it using dpkg:

sudo dpkg -i zocl-dkms_2.20.0-1_any.deb

Replace zocl-dkms_2.20.0-1_any.deb with the actual name of your package file.

After installation, the postinst script will run, adding the module to DKMS and attempting to build it. If the build fails, check the DKMS logs in /var/lib/dkms/zocl/2.20.0/build for more information.

Step 4: Troubleshooting Common Issues

4.1. DKMS Build Failures

One common issue is DKMS failing to build the module. This can be due to several reasons:

  • Missing Kernel Headers: Ensure the kernel headers for your running kernel are installed. You can install them using:

    sudo apt-get install linux-headers-$(uname -r)

  • Missing Dependencies: As noted in the initial problem, missing XRT development headers can cause build failures. Install the necessary development packages:

    sudo apt-get install xrt-dev

  • Build Errors: Check the DKMS logs in /var/lib/dkms/zocl/2.20.0/build for specific error messages. These logs can provide valuable clues about what went wrong.

4.2. Module Not Loading

If the module builds successfully but doesn’t load, try loading it manually using modprobe:

sudo modprobe zocl

If this fails, check the system logs for error messages:

dmesg | grep zocl

4.3. Device Not Detected

If /dev/fpga0 exists but no devices are detected, ensure that the XRT is properly configured and that the ZOCL driver is correctly interfacing with it. Check the XRT logs and configuration files for any issues.

Conclusion

Creating a Debian package for the KR260 with ZOCL DKMS involves several steps, from setting up the debian/ folder to building and installing the package. By following this guide, you should be able to create a robust and reliable package that integrates seamlessly with your system. Remember to pay close attention to dependencies, DKMS configuration, and potential build errors. By addressing these aspects, you can ensure the successful deployment of your custom drivers.

If you're looking for more information about Debian packaging, you can check the official Debian documentation on Debian Package Management. This resource provides in-depth details on the process and best practices for creating Debian packages.