PIXCI® Imaging Software and Drivers Installation: Boundary Devices/ARM NITROGEN6/imx6

1. PIXCI® Imaging Software and Drivers Installation: Boundary Devices/ARM NITROGEN6/imx6

This application note outlines the installation of XCAP software and drivers for PIXCI® frame grabbers on the Boundary Devices NITROGEN6 with ARM imx6 processor running Linux. Changes to the NITROGEN6 and its Linux can be expected; this application note was written for use with the NITROGEN6 and Ubuntu Linux released circa November 2017.

1. Update Linux. As distributed, the NITROGEN6 has insufficient ‘disk’ space (actually a 4 GiB SD memory card) to install and run XCAP. Use ‘gparted’ to grow the 4 GiB disk image to size of new SD card:

    apt install gparted
    gparted-pkexec (will prompt for su password)

Update the distribution image:

    sudo apt update
    sudo apt upgrade
    sync
    sudo reboot

See Boundary Devices documentation for more details on use of these commands.

Note: If intending to only use XCLIB based applications, installation of XCAP and expansion of ‘disk’ space is not required. Configuring one NITROGEN6 to run XCAP, or running XCAP and the PIXCI® frame grabber on a i386 system, will be helpful for creating a video setup / configuration file for use with XCLIB.

2. Install JRE. Unlike XCAP for x86 and x86−64 platforms, XCAP for NITROGEN6 does not include a Java Runtime Environment. If the Java JRE for Linux is not already installed, install the default Java JRE from the Linux distribution and repository:

    apt-get update
    apt-get -y install default-jre

Note: If the Java JRE for Linux is not already installed, newer releases of the XCAP installer (below) will offer to install the Java JRE from the Linux distribution and repository.

3. Install XCAP. XCAP for NITROGEN6 is not provided on the PIXCI® CD/DVD, and only available via download. Download xcaplnx_armv7l.bin from www.epixinc.com/support/files.php. Do:

    chmod a+x xcaplnx_armv7l.bin
    ./xcaplnx_armv7l.bin

Only XCAP-Lite is supported for the NITROGEN6 - intended as a testing and configuration tool to assist in for developing application programs using the XCLIB C/C++ library. XCAP-Ltd and XCAP-Std are currently not supported for the NITROGEN6.

Some versions of the JRE do not accept a ‘-client’ option. It may be necessary to edit /usr/local/xcap/xcaplnx and /usr/local/xcap/program/xcaplnx and remove the ‘-client’ option. Or with:

    sed -i -e s/-client//g /usr/local/xcap/xcaplnx
    sed -i -e s/-client//g /usr/local/xcap/program/xcaplnx

Problems have been reported with OpenJDK V1.7, resulting in:

    Internal Error (os_linux_zero.cpp:285)
    fatal error: caught unhandled signal 11

Adding the ‘-jamvm’ option has been suggested by the Java community to remedy the problem; edit /usr/local/xcap/xcaplnx and /usr/local/xcap/program/xcaplnx and add the ‘-jamvm’ option (after the ‘java’ command). However, some distributions of the default JRE do not include the ‘-jamvm’.

Alternately, install and use the Oracle JVM.

4. XCAP’s installer will offer to start XCAP. Or, use the XCAP shortcut, above. Or, use

    xcap

from a terminal prompt.

5. Install PIXCI® driver. One or more precompiled PIXCI® drivers are provided with XCAP. If one of these drivers match the current kernel, use XCAP’s:

    PIXCI®
    PIXCI® Open/Close
    Close (if open)
    Driver Assistant
    Install PIXCI® Driver
    Install Precompiled Driver
    Apply

Alternately, the PIXCI® driver can be compiled so as to match the current kernel. Use XCAP’s:

    PIXCI®
    PIXCI® Open/Close
    Close (if open)
    Driver Assistant
    Install PIXCI® Driver
    Compile & Install Driver
    Apply

Alternately, as some Linux releases discourage running graphic programs as root, compile and install the driver with:

    cd /usr/local/xcap/drivers/armv7l/src_$(uname -r)
    sudo make
    cd ../..
    sudo ./pixci.sh install . armv7l/src_$(uname -r)

where ‘$(uname -r)’ is replaced with the current kernel version. If:

    /usr/local/xcap/drivers/armv7l/src_$(uname -r)

does not exist, pick the:

    /usr/local/xcap/drivers/armv7l/src_*

subdirectory whose suffix is closest to the current kernel version. (The various subdirectories represent the driver’s precompiled ‘binary blob’ having been pre-compiled under various kernels. Typically, the ‘binary blob’ only needs to be close to the current kernel version, with the final compilation performed under the current kernel).

6. Configure NITROGEN6 memory and interrupts. Unlike Linux for x86 and x86−64 systems providing a single, large, pool of memory, the Linux for NITROGEN6 partitions memory into various pools each with a designated purpose. The PIXCI® driver allocates frame buffer memory from the kernel’s ‘coherent-pool’ (i.e. DMA pool). The default NITROGEN6 coherent-pool is ?? KB and allows, approximately, 256(?) KB of frame buffer memory. Also, the NITROGEN6 must be configured to accept use of non-MSI PCI interrupts.

Edit /6x_bootscript.txt and add, for example:

    coherent-pool=8M

to the kernel command line so as to allow additional frame buffer memory. Also add:

    pci=nomsi

to the same kernel command line to allow non-MSI PCI interrupts. Note: The proper line of /6x_bootscript.txt might be found by searching for ‘vmalloc=’. Note: The long kernel command line may be displayed by the editor as split into several lines; but it must be edited as a single line without line break.

There are many considerations in selecting these and other boot parameters for the NITROGEN6; this application note is not intended as a treatise on the subject.

Compile the /6x_bootscript.txt by browsing git.boundarydevices.com/bootscript.php, copy and paste the /6x_bootscript.txt as the ‘u-boot commands’, click ‘Compile’, and copy result to /6x_bootscript. Or, for newer systems, run:

    sudo apt-get install u-boot-tools
    mkimage -A arm -O linux -T script -C none -n "boot script" \
        -a 0 -e 0 -d 6x_bootscript.txt 6x_bootscript

Some systems have both /6x_bootscript.txt and /boot/boot.txt. Edit the /boot/boot.txt as described above, compile as:

    mkimage -A arm -O linux -T script -C none -n "boot script" \
        -a 0 -e 0 -d /boot/boot.txt  /boot/boot.scr

See https://boundarydevices.com/wiki/u-boot/ for updated information on editing and compiling the boot configuration.

7. Configure frame buffer memory.

The amount of frame buffer memory available for image capture is also determined by the amount of memory requested by the PIXCI® driver. This is set in the same manner as for x86 or x86−64 systems; typically using XCAP (run as root):

    PIXCI®
    PIXCI® Open/Close
    Close (if open)
    Driver Assistant
    Set Frame Buffer Memory Size
    ...

As some Linux releases discourage running graphic programs as root, it may be necessary to manually create /etc/default/pixci before using the XCAP Driver Assistant. Do:

    sudo echo ""  >> /etc/default/pixci
    sudo chown 777   /etc/default/pixci

and then run XCAP as non-root, letting it edit the /etc/default/pixci as non-root.

XCAP’s ‘Forceful Memory Allocation’ option, used with the memory architecture of x86 and x86−64 systems, is not applicable to the NITROGEN6.

8. Reboot NITROGEN6.

9. If using the XCLIB or XCLIB+PXIPL C/C++ library, download: xclib_armv7l.bin or xclip_armv7l.bin from www.epixinc.com/support/files.php. Install with:

    chmod a+x xclib_armv7l.bin
    ./xclib_armv7l.bin

    chmod a+x xclip_armv7l.bin
    ./xclip_armv7l.bin

Updated: 27 March 2023