About Blackmagic Desktop Video Software
---------------------------------------

The Desktop Video packages provide capture and playback support for a large
range of Blackmagic Design PCIe and thunderbolt products including the
DeckLink, Intensity and UltraStudio product lines.


What's New in Desktop Video 12.9
----------------------------------

New features on UltraStudio 4K Mini:
* Adds 10-bit YUVA 422 up to 2160p30 for keying.
* Adds mute on fill and key output for replay use.
* General performance and stability improvements for all models.


Minimum System Requirements
---------------------------

 * x86-64 running Linux 3.10 or higher.
 * AArch64 running Linux 4.9.140 or higher.

A system with ample memory is strongly recommended.


Supported ARM Platforms
---------------------------

Desktop Video has been tested on the following platforms:

Nvidia Jetson AGX Xavier and Nvidia Clara AGX:

 * DeckLink 8K Pro
 * DeckLink Quad 2
 * DeckLink Duo 2
 * DeckLink Quad HDMI Recorder
 * DeckLink 4K Extreme 12G
 * DeckLink SDI Micro


Thunderbolt Hotplug Requirements
--------------------------------

Supported kernels older than 3.12 require an extra step after plugging the
device in. You must tell the kernel to rescan the PCI bus using the following
command:

# sudo sh -c 'echo 1 > /sys/bus/pci/rescan'

Kernel 3.12 and later support hotplug without the need for any extra steps.


Supported Distributions
-----------------------

x86-64:

 * Ubuntu: 22.04, 23.04
 * Debian: 11
 * Fedora: 38
 * CentOS: 7
 * Rocky Linux: 8.8

Nvidia Jetson AGX Xavier / Nvidia Clara AGX:

 * JetPack 5.1

Several different package formats are supplied:

 * Native package (.deb) for Ubuntu and Debian based distributions.
 * Native package (.rpm) for RedHat and Fedora based distributions.
 * Tarball and packaging files for custom installation.


Software Dependencies
---------------------

The Desktop Video packages require some additional libraries and packages:

 * dkms
 * Linux kernel headers/source (for currently running kernel version)

All packages above are included in most modern distributions. Consult your
distribution's documentation for more information.

CentOS distributions do not ship with dkms. This install can be completed
with the following commands:

# sudo yum install epel-release
# sudo yum install dkms

For more info please visit https://github.com/dell/dkms.


Secure Boot
-----------

To install the Desktop Video drivers on Linux with Secure Boot enabled, there
are several requirements that must be met.

 * Your system must be installed with an EFI bootloader
 * Your distribution must support a signed shim loader
 * You must have enrolled a Machine Owner Key (MOK)
 * You must sign the drivers with the MOK

The deb/rpm package will endeavor to take care of both the key enrollment and
the signing of the drivers if your system has secure boot enabled.

If MOK enrollment took place, you will be asked to reboot. When your system
next boots up, you will be presented with a blue screen with the text "Press
any key to perform MOK management". Press any key, and complete the following
steps to continue with the MOK enrollment.

 * Select "Enroll MOK" from the menu
 * Select "Continue" from the menu
 * Select "Yes" from the menu
 * Enter the password you provided earlier during the installation
 * Select "Reboot" from the menu

From this point the system should continue to boot normally.

On systems with the update-secureboot-policy script, that wil be used to
generate the MOK. Otherwise a MOK will be generated in /var/lib/blackmagic. If
you have your own key to be used, you can define the environment variable
BMD_NO_SECUREBOOT, and all signing and enrollment operations will be skipped by
the installer.


Installing Desktop Video Software
---------------------------------

There are packages provided which you can install:

 * desktopvideo: This package includes the driver and firmware
   utility. This package is required.

 * desktopvideo-gui: This package includes the graphical control panel used
   to configure the device and a firmware update available notification.

 * mediaexpress: This package includes Media Express, a simple capture and
   playback utility (x86_64 only).

Ubuntu and Debian based distributions

    The x86-64 deb packages are located in the deb/x86_64 directory.
    The AArch64 deb packages are located in the deb/aarch64 directory.

    Installation from Graphical User Interface

        Double click on the desktopvideo package. Click the install
        button and follow the prompts. This can then be repeated for
        the desktopvideo-gui and mediaexpress packages if desired. 
        The mediaexpress package is for x86_64 only.

    Installation from Command Line

        At the command prompt type:

         # sudo dpkg -i desktopvideo_*.deb

        To also install the control panel and Media Express, type:

         # sudo dpkg -i desktopvideo_*.deb desktopvideo-gui_*.deb \
           mediaexpress_*.deb

        Then fix up any missing dependencies with:

         # sudo apt-get install -f

RedHat or Fedora based distributions

    The rpm packages are located in the rpm/x86_64 directory.

    Please apply all system updates before installing the packages.

    Installation from Graphical User Interface

        Double click the desktopvideo package. Click the install
        button and follow the prompts. This can then be repeated for
        the desktopvideo-gui and mediaexpress packages if desired.
        The mediaexpress package is for x86_64 only.

    Installation from Command Line

        At the command prompt type:

         # sudo yum install --nogpgcheck desktopvideo-*.rpm

        Or, to also install the control panel and Media Express, type:

         # sudo yum install --nogpgcheck desktopvideo-*.rpm \
           mediaexpress-*.rpm

        If upgrading from an older version of the driver, you will need to
        reboot in order to load the new module.

Creating your own .deb or .rpm packages

    The packaging files used to build the .deb and .rpm packages can be
    found in the other/x86_64 and other/aarch64 (.deb only) directories along 
    with the binary tarballs they use as source. The examples below build 
    the x86_64 desktopvideo packages.

    Building a set of .deb packages

        To build these packages you need to have debhelper and
        devscripts installed.

         # mkdir desktopvideo-deb
         # tar zxf other/x86_64/desktopvideo_*_amd64.debian.tar.gz \
           -C desktopvideo-deb
         # cp other/x86_64/desktopvideo*-x86_64.tar.gz desktopvideo-deb
         # cd desktopvideo-deb
         # debuild -us -uc -b

    Building a set of .rpm packages

        To build these packages you need to have rpm-build and chrpath
        installed.

         # mkdir desktopvideo-rpm
         # ( cd desktopvideo-rpm && mkdir BUILD BUILDROOT RPMS SRPMS \
           SPECS SOURCES )
         # cp other/x86_64/desktopvideo*.x86_64.spec desktopvideo-rpm/SPECS
         # cp other/x86_64/desktopvideo*-x86_64.tar.gz desktopvideo-rpm/SOURCES
         # cd desktopvideo-rpm
         # rpmbuild --define "_topdir ${PWD}" -bb \
           SPECS/desktopvideo*.x86_64.spec

    The same process can be used to build the Media Express package.

Other Linux based distributions (Experts Only)

    No native package exist to support these distributions at the time of
    writing. It is however, possible to install the driver manually by
    downloading the tar.gz archive.

    Before you begin, ensure that your system satisfies external
    dependencies listed above in "Software dependencies".

    The files are structured in the binary tarball as they should be
    installed. It is suggested that you look at the provided rpm spec file
    or the debian rules file for any assistance required.

    Before getting started, you should take note of the following:

     * If your system places its 64-bit libraries in lib64, there
       are a number of additional changes required. You can find
       these in the install section of the provided x86_64 spec
       file.

     * If you want to install into a prefix other than /usr, you
       will have to make the same set of changes as above for
       lib64.


Frequently Asked Questions
--------------------------

* How do I check that the driver/device was loaded successfully?

    You can check that your computer find your device by entering the
    following from a terminal:

     # lspci | grep Blackmagic
     02:00.0 Multimedia video controller: Blackmagic Design Device a11b

    You should see entries like the above if the device was recognized by the
    system.

    To test if the driver is loaded properly, type:

     # lsmod | grep blackmagic
     blackmagic                   2082944  1

    If you get no output, that means that the driver is not loaded.

* How do I update the firmware on a device?

    The device's firmware can be updated with the BlackmagicFirmwareUpdater.
    See the man page for instructions and examples on how to use the utility.

* The driver crashed my system

    Look for kernel output messages in dmesg and /var/log/messages.

* The package installed, but the driver was not loaded

    Try the following command:

     # dkms status -m blackmagic-io -k `uname -r`
     
    If the status is 'installed', then the module is installed, but probably
    not loaded. It can be loaded with the following command:

     # sudo modprobe blackmagic-io

    If the status is 'added', then the module failed to build. You can issue
    the following command to manually run the build and use the output to
    determine the problem.

     # sudo dkms build -m blackmagic-io -v 12.9

    The full module version number is in the form 12.9aXX. This module number
    can be found by running dkms status.

    A common cause is a version mismatch between the installed kernel image,
    and the kernel source/headers. If they do not match, simply bring either
    the source/headers or the image version up to date, and reboot your system.
    Once the system is back up, the driver should be built for you at startup.
    The command to install matching headers for your currently running kernel
    on CentOS is:

     # sudo yum install "kernel-devel-uname-r == $(uname -r)"

    If the status is 'built', then the module has been built, but not
    installed. You can issue the following command to manually install and use
    the output to determine the problem.

     # sudo dkms install -m blackmagic-io -v 12.9 --all

    Legacy Desktop Video products on x86_64 platforms use an older driver.  
    Users should build and install this module with the dkms commands above, 
    replacing `-m blackmagic-io` option with `-m blackmagic`.


Known Issues
------------

* Performance of Nvidia embedded platforms

    Nvidia devices like Jetson may default to a mid-range power/performance
    mode, eg. 30W / "mode 2". When using higher-end video modes that require
    more processing, you may have to increase this setting. Refer to the
    nvpmodel command or other related method in NVidia's documentation.

* Incompatibility with small memory systems

    Sufficient memory must be available to the driver to support the number of
    devices installed and their frame buffering requirements. A 64 bit system
    with adequate memory is strongly recommended. In some configurations,
    reserving more memory at boot for vmalloc may be necessary. More memory
    can be allocated by adding 'vmalloc=<SIZE>' option to the kernel command
    line.

    e.g. vmalloc=256M

* Driver fails to build against certain version of linux-rt

    Some versions of the linux-rt patchset may be incompatible with the
    driver.

* ASPM with some PCI-e cards

    Some PCI-e cards (1x lane cards) do not function properly by default when
    ASPM is enabled. When in this state, the device will be listed in lspci
    and the BlackmagicFirmwareUpdater status will report version ff. To work
    around this please add kernel boot parameter "pcie_aspm=off" to your boot
    loader.

* Settings are not saved on some versions of Fedora

    This issue is caused by the SELinux policies being incorrect on the
    preferences file. To fix this issue, ensure the policycoreutils-python-utils
    package is installed and run the following commands:

     # sudo rm /etc/blackmagic/BlackmagicPreferences.xml
     # sudo semanage fcontext -a -t etc_runtime_t /etc/blackmagic
     # sudo restorecon /etc/blackmagic


Additional Information
----------------------

Please check www.blackmagicdesign.com for additional information on third
party software compatibility and minimum system requirements.

Some applications may use third party code under license. For details, please refer to the included "Third Party Licenses.rtf" document.

Copyright 2024 Blackmagic Design. All rights reserved. 'Blackmagic Design', 'Blackmagic', 'Blackmagic Cloud', 'DaVinci Resolve', 'Fusion', 'Fairlight', 'Ultimatte', 'HyperDeck', 'DeckLink', 'HDLink', 'Videohub', 'Intensity' and 'Leading the creative video revolution' are registered trademarks in the US and other countries. All other company and product names may be trademarks of their respective companies with which they are associated.

Updated April 10, 2024.