Orca PCIe Linux Kernel Driver Installation and Troubleshooting Guide

Documentation Installation
1

Linux Kernel Driver Installation

Hosts that have DeGirum Orca card installed need a driver to enable its functionality. The driver is distributed as a source package via a DeGirum APT software repository. It can be built automatically after download. To download, build, and install the driver please perform the following steps:

  1. Install prerequisites:
sudo apt install curl dkms mokutil
  1. Download DeGirum public key:
  • Ubuntu 20.04:
wget -O - -q http://docs.degirum.com/apt-repo/DeGirum.gpg.key | sudo apt-key add -
  • Ubuntu 22.04 and 24.04:
curl -fsSL http://docs.degirum.com/apt-repo/DeGirum.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/degirum.gpg
  1. Add DeGirum software repository to APT sources configuration file:
  • Ubuntu 20.04:
echo deb [arch=amd64,arm64] https://docs.degirum.com/apt-repo ORCA main | sudo tee -a /etc/apt/sources.list
  • Ubuntu 22.04 and 24.04:
echo deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/degirum.gpg] https://docs.degirum.com/apt-repo ORCA main | sudo tee -a /etc/apt/sources.list
  1. Update package information from configured sources:
sudo apt update
  1. Download and build DeGirum Linux driver package:
sudo -E apt install cdapci-dkms
  1. Either perform reboot or execute the following command to load the driver:
sudo modprobe cdapci
  1. If secure boot is enabled, it will prompt to add the certificate used to sign the driver to MOK:
  • Press Enter.
  • Enter some password, and confirm it.
  • When driver installation is complete, reboot the target.
  • Once the target reboots, the Shim UEFI Key Management screen is displayed. Select the Enroll MOK option from the menu.
  • Review the keys in the current enrollment list and confirm their enrollment. The MOK password from step 2 is required to confirm these operations.
  • Continue with the target boot.

Linux Kernel Driver Troubleshooting

  1. Verify that Orca PCIe device is recognized by the system. Run the following command:
sudo lspci | grep accelerators

If the PCIe device is recognized, you should see something like:

03:00.0 Processing accelerators: Device 1f0d:0100

If the PCIe device is not recognized, then you will see empty output.

  1. If the PCIe device is not recognized, check that the device is plugged in and green LED light is flashing. If the device is plugged, but green LED light is not flashing, then the device is not functioning and needs to be replaced.

  2. Verify that Orca Kernel Driver is installed. Run the following command:

sudo lsmod | grep cda

If the driver is installed, you should see something like:

cdapci                 28672  0

If the driver is not installed, then you will see empty output.

  1. If the driver is not installed, please reinstall the driver following the steps described in the Linux Kernel Driver Installation section.

  2. The driver requires permissions to be correct in order to access ORCA. Usually, these are set up automatically during the driver install process. Verify that a user group named dg_orca exists, and that the current user belongs to it:

cat /etc/group | grep dg_orca && groups | grep dg_orca

If the group does not exist, please reinstall the driver following the steps described in the Linux Kernel Driver Installation section. If the group does exist, but the user is not in it, add the user via

sudo -E usermod -a -G dg_orca <username>
  1. If you installed DeGirum AI Server then verify AI Server operation. Run the following command on any system in your local network, which has PySDK installed:
degirum sys-info --host <hostname or IP>

The <hostname or IP> is the hostname or IP address of the system running AI server. If you have PySDK installed on the same system where you run AI server, then run this command on that system and specify --host localhost. If AI server operates properly, you should see something like:

Devices:
...
ORCA:
- '@Index': 0
        Device Description: 'Orca[ #0, bus 3, dev 0 ]'
        Firmware Version: 0.1.40
        IC Frequency (MHz): 250
        IC Temperature (C): 51
        Memory DRAM (MB): 1024
Software Version: 0.5.1

Check for the ORCA section. It should be present in the output.

  1. If AI server does not operate properly, reinstall the server following the steps described in the DeGirum AI Server Installation and Configuration Guide.

The following command combines the above checks in one:

    sudo lspci | grep accelerators && sudo lsmod | grep cda && cat /etc/group | grep dg_orca && groups | grep dg_orca

Kernal Driver Installation for Other Operating Systems

The current version of DeGirum software package supports only Linux kernel driver. Kernel driver support for other operating systems is under development. This document will be updated when kernel drivers for other operating systems will be released.