PIXCI® Imaging Drivers Installation: Linux Driver on Head-less Systems

1. PIXCI® Imaging Drivers Installation: Linux Driver on Head-less Systems

Background.

The driver for PIXCI® frame grabbers is included with the XCAP GUI application’s distribution. The same driver is used with the XCLIB SDK; the XCLIB distribution doesn’t duplicate the driver’s file(s).

Typically, XCAP’s Driver Assistant is used to install the Linux driver for PIXCI® frame grabbers; XCAP should be run with super-user privileges while installing the driver. However, some Linux systems with tiny footprints do not support running of GUI applications. Or, some systems are ‘head-less’, without display, keyboard, or mouse. Or, restricts users with super-user privilege from running GUI applications[1].

The installation of Linux drivers is complicated by a Linux restriction: Linux requires that each driver be compiled ‘against the kernel’ on which the driver is to be used (i.e. the target): same version, subversion, sub-subversion, etc[2]. (Older kernels, 2.4.x, do not have the same requirement regarding driver compilation). Typically this is done by compiling the driver on the target system[3]. Further: The Linux kernel continues to evolve, drivers often require changes to meet/match the new kernel API[4]. Further: the compilation options required for the driver occasionally change[5].

As new Linux kernels are released daily (if not more often!), it is impractical to provide a pre-compiled driver for each kernel. Nor is source code for the PIXCI® driver provided. Provided is a ‘driver recompilation kit’:

a. A ‘binary blob’ in which most of the source code is pre-compiled,

b. A ‘wrapper’ (as source code) interface between the binary blob and the kernel, and

c. Support files to automate the compilation process on the target machine.

Different ‘driver recompilation kit’ are provided for different CPU architectures, such as Intel i386, Intel x86−64, ARM imx6, ARM aarch64, etc.

Because the ‘binary blob’ interfaces to the kernel via wrappers, it is partially shielded from kernel changes. But some changes, such as compile options, require a new ‘binary blob’. Other compile option changes, such as a local system’s enabling/disabling of kernel profiling, can be handled by compile time options within the ‘wrappers’.

Provided are one or more binary blobs that have proven sufficient to compile drivers on supported Linux systems. Additional binary blobs will be provided as the need arises. The binary blobs are labeled with the major and minor kernel version, not the full version, subversion, sub-subversion, etc. Typically, when compiling the driver, one uses the binary blob whose kernel version is nearest to, but younger than, the current kernel version.

Also provided are one or more pre-compiled drivers; they are labeled with the full ‘uname -r’ version of the kernel under which they were compiled. A customer may choose to install the corresponding version of Linux and use the pre-compiled driver.

Installation of Files

Driver files are in XCAP’s drivers subdirectory, typically:

    /usr/local/xcap/drivers/

    /usr/local/xcap32/drivers/

for 32 bit XCAP on an x86−64 platform. The XCAP installer can be run on the target machine, installing XCAP’s files, even though the XCAP GUI isn’t run; the XCAP installer is not a GUI application. Or, the files of XCAP installed on one machine can be copied to another; only the files in the drivers subdirectory are needed.

Typical contents, using x86−64 platform as an example, are:

    ~/drivers/pixci.sh          script to install PIXCI driver & pixci.rc
    ~/drivers/pixci.rc          runs at boot to install driver
    ~/drivers/pixcitty.rc       script to install PIXCI tty driver & pixci.rc
    ~/drivers/pixcitty.sh       runs at boot to install tty driver
    ~/drivers/pixcitty.df       default parameters for tty driver
    ~/drivers/pixciv4l.rc       script to install PIXCI v4l2 driver & pixci.rc
    ~/drivers/pixciv4l.sh       runs at boot to install v4l2 driver
    ~/drivers/pixciv4l.df       default parameters for v4l2 driver
    ~/drivers/x86_64/           subdirectory for x86-64 drivers
        ~/x86_64/3.8.0-26/      pre-compiled drivers under eponymous kernel
            ~/3.8.0-26/pixci_x86_64.ko      PIXCI driver for ... kernel
            ~/3.8.0-26/pixcitty_x86_64.ko   PIXCI tty  driver for ... kernel
            ~/3.8.0-26/pixciv4l_x86_64.ko   PIXCI v4l2 driver for ... kernel
        ~/x86_64/src_2.6/        driver recompilation kit w. 2.6 blob
            ~/src_2.6/Makefile                  makefile
            ~/src_2.6/pixcilnx_x86_64_2.6.a     blob
            ~/src_2.6/pixcipub.c                wrappers
            ~/src_2.6/pixcipub.h                wrappers
        ~/x86_64/src_3.0/       driver recompilation kit w. 3.0 blob
            ...                                 ditto
        ~/x86_64/src_3.8/       driver recompilation kit w. 3.8 blob
            ...                                 ditto
        ~/x86_64/ttysrc_2.6/    tty driver recompilation kit w. 2.6 blob
            ~/ttysrc_2.6/Makefile                makefile
            ~/ttysrc_2.6/pixcipub.h              wrappers
            ~/ttysrc_2.6/pixcitty.c              wrappers
        ~/x86_64/ttysrc_3.0     tty driver recompilation kit w. 3.0 blob
            ...                                 ditto
        ~/x86_64/ttysrc_3.8     tty driver recompilation kit w. 3.8 blob
            ...                                 ditto
        ~/x86_64/v4lsrc_2.6/    v4l2 driver recompilation kit w. 2.6 blob
            ~/v4lsrc_2.6/Makefile                makefile
            ~/v4lsrc_2.6/pixcipub.h              wrappers
            ~/v4lsrc_2.6/pixciv4l.c              wrappers
        ~/x86_64/v4lsrc_3.0     v4l2 driver recompilation kit w. 3.0 blob
            ...                                 ditto
        ~/x86_64/v4lsrc_3.8     v4l2 driver recompilation kit w. 3.8 blob
            ...                                 ditto

If copying files from an existing XCAP installation, in addition to one or more subdirectories with pre-compiled drivers (with the directory name matching a kernel’s ‘uname -r’), there may be a subdirectory (under ‘x86_64’ in the example above) containing drivers compiled by XCAP with directory name matching the kernel under which it was compiled, i.e.:

        ~/x86_64/4.3.0-10/      locally compiled drivers under eponymous kernel
            ~/4.3.0-10/pixci_x86_64.ko      PIXCI driver for ... kernel
            ~/4.3.0-10/pixcitty_x86_64.ko   PIXCI tty  driver for ... kernel
            ~/4.3.0-10/pixciv4l_x86_64.ko   PIXCI v4l2 driver for ... kernel

Installing Pre-compiled Driver

Using file names from the typical contents shown above:

    cd /usr/local/xcap/drivers
    ./pixci.sh install . ./x86_64/3.8.0-26

Compiling & Installing Driver

Using file names from the typical contents shown above:

    cd /usr/local/xcap/drivers/x86_64/src_3.0
    make    # creates pixci_x86_64.ko in current directory
    cd /usr/local/xcap/drivers
    ./pixci.sh install . ./x86_64/src_3.0

choosing a different binary blob, i.e. src_, as needed.

Successful compilation of the driver requires that the ‘gcc’ compiler and the ‘kernel build files’ have been installed from the Linux distribution and repository.

Driver Configuration Parameters

Running XCAP with super-user privilege is also useful for configuring the PIXCI® driver by setting the default ‘Driver Configuration Parameters’.

To set the ‘Driver Configuration Parameters’ without XCAP, edit or create file /etc/default/pixci. One line should start with:

    driver.pixci.parm=

followed by the desired parameters, such as:

    driver.pixci.parm= -IM 2048 -DM 3

See the XCAP Reference Manual or the XCLIB Reference Manual for a description of the ‘Driver Configuration Parameters’.

The ‘Forceful Memory Allocation’ option, available only for i386 and x86−64 platforms, requires XCAP to modify both the ‘Driver Configuration Parameters’ in /etc/default/pixci and to modify Linux’ boot configuration. Modification of the boot configuration, so as to reduce the amount of memory ‘owned’ by Linux, is not covered in this application note.

TTY Drivers.

The optional ‘tty’ drivers provides /dev/tty style access to the serial port of Camera Link frame grabbers. Access to the serial port via the XCLIB SDK does not require the ‘tty’ drivers.

Compilation and installation of the ‘tty’ driver follows the same procedure as for the PIXCI® driver, using subdirectories and files names incorporating tty. The ‘tty’ driver can be installed only after the PIXCI® driver is installed.

To set the ‘tty’ configuration parameters without XCAP, edit or create file /etc/default/pixcitty. Or copy the provided ~/drivers/pixcitty.df to /etc/default/pixcitty. See pixcitty.df (it is text) for a description of the ‘tty’ parameters.

V4L2 Drivers.

The optional Video for Linux Driver (V4L2) a Linux standard V4L2 API to control PIXCI® frame grabbers and retrieve image data.

Compilation and installation of the ‘V4L2’ driver follows the same procedure as for the PIXCI® driver, using subdirectories and files names incorporating v4l. The ‘V4L2’ driver can be installed only after the PIXCI® driver is installed. See the PIXCI® Video for Linux Driver (V4L2) specific application note for information regarding its options and use.

To set the ‘V4L2’ configuration parameters without XCAP, edit or create file /etc/default/pixciv4l. Or copy the provided ~/drivers/pixciv4l.df to /etc/default/pixciv4l. See pixciv4l.df (it is text) for a description of the ‘V4L2’ parameters.

Cleanup.

The successful installation of the PIXCI® driver will copy all required files - for reloading the driver upon reboot - elsewhere into the file system; i.e. the pixci.rc, pixci*.ko, pixcitty.rc, pixcitty*.ko, pixciv4l.rc, and pixciv4l*.ko files. The

    ~/drivers

subdirectory can be removed.

Updated: 27 March 2023

Footnotes __________

1. The subject of how to reconfigure such a system to allow running XCAP
with super-user privilege is discussed elsewhere; this application
note discusses how to install the driver w/out running XCAP — for the
sake of running XCLIB-based applications.

The larger question of whether a GUI application should be re-
stricted from running as super-user, and whether it is appropriate to
defeat such restrictions, is certainly beyond the remit of this appli-
cation note.

Newer releases of XCAP, in conjunction with many Linux distribu-
tions using the ‘gnome terminal’ or ‘xterm’, allow using XCAP’s Driver
Assistant GUI without super-user status. Instead, the Driver Assis-
tant will create a shell script, open a terminal, and invite the user
to respond and authorize ‘sudo script’.

2. Attempting to install a driver of incorrect version typically results
in an ‘Invalid Module Format’ error while loading the driver.

3. It is also possible to cross-compile (compiling under kernel X for
target Y, where X≠Y, which is why the phrase ‘against the kernel’ is
used, above. While possible, cross-compilation does not require
knowledge specific to the PIXCI® frame grabber driver and won’t be
discussed further in this application note.

4. Typically resulting in errors while compiling the driver.

5. Typically resulting in an ‘Unresolved Symbol’ error while loading the
driver.