Foresight Imaging, LLC May 02, 2017 Important information regarding the this release of IDEA software for the LINUX operating system. This is a full library release. We are trying to support as many distributions as possible, but there are likely to be incompatibilities among various ports. Please contact us immediately (support@fi-llc.com) if you have any difficulties installing or using this software. Please note that there are separate release files for Red Hat Enterprise 5 ( 32 and 64 bit versions ) and other distributions. Each release was built and tested on the targeted distribution. At the time of the release, the kernels were at the following versions: Ubuntu 10.4 (64 bit) - 2.6.32-28 Ubuntu 10.10 (64 bit) - 2.6.35-25 Red Hat EL5 (64 bit) - 2.6.18-238 Red Hat EL5 (32 bit) - 2.6.18-238 Red Hat EL4 (32 bit) - 2.6.9-78 SUSE Enterprise Server 10 (64 bit) - 2.6.16-60 SUSE Enterprise Desktop 11.2 (64 bit) - 2.6.32.27 OpenSUSE 11.2 (32 bit) - 2.6.31.14 Fedora 13 (32 bit) - 2.6.34.7 Red Hat Enterprise Linux Server 7.1 - 3.10.0-229.el7.x86_64 The basis for this software port is the IDEA 3.3 release for the Windows operating systems. All currently supported frame grabbers from Foresight Imaging are supported by this release. This includes all AccuStream models supported by the IDEA v3.3 Windows release. The AccuStream Express HD+C H.264 compression capabilities is not currently supported. Please check with technical support for updates. This release supports both static capture and streaming capture. The streaming demo application captures to memory and then writes each frame out as a bitmap. The device driver is capable of supporting multiple boards. Selecting a particular board in a mult-board installation is a function of the application. This is shown in the "sgrab" demo. This release also includes the first, preliminary release of the VideoForLinux(2) driver. This can be found in the fsiv4l directory. To use this driver, it must be built on your current kernel sources. It can be installed using either the fsiv4l.sh or the startup.sh found in the scripts directory. Prior to using the driver, you must build and execute the fsiconfig utility found in the fsiconfig directory. This will load the specified chp file to configure the board for your signal. The fsiv4l driver has only been tested using the xawtv application. The Video for Linux driver is not supported under Red Hat Enterprise 5 because it requires a kernel of at least 2.6.24 and RHEL is at 2.6.18. Installation ====================== This tar file will unpack to /home/foresight. After unpacking you may have to reset the owner and group via chown and chgrp to the non-root user. After unpacking the the tar file, you will have the following directory structure: ./archive The binary linkable versions of the libraries ./aslite A command line based Auto-SYNC. ./driver The device driver module ./docs Documentation, including the library API manual from the Windows release. ./include Include files for creating applications ./iseries JBC files (firmware for the on-board FPGA), that get copied to /etc. ./linxgrab Command line based demo applications. ./scripts Shell scripts. fsght_load.sh is necessary for the driver. ./chp Template CHP files for common video signals. ./fsiconfig Application to configure the board for use with the VideoForLinux driver. ./fsiv4l The source code for the VideoForLinux driver. ./fsicap A Glade-based GUI application to snap and display images ./dviconfig A command line utility to program the board's DVI personality prom At the time of this release, there is no install make file. You will have to copy the contents of the iseries directory (*.jbc) to /etc. To build everything (driver, aslite, linxgrab) run the following from the foresight directory: make all Otherwise you can build / run each component individually. First you should rebuild the device driver by the following commands: cd driver make This should result in a new foresight.ko. The driver must be installed by running: sh fsght_load.sh from the scripts directory. If your distribution will support the V4L driver then you must build it for your kernel version using the following command: cd fsiv4l make To install the driver you must run the script fsiv4l.sh found in the scripts directory. sh fsiv4l.sh Note that you must have root access to run either one of these scripts, and that they need to be run each time the system restarts. Building Software ====================== In each directory there is a makefile named "makefile.xxx" where the xxx is a suffix specific to the project. To build software in place use the makefile named "makefile.xxx", i.e. make -f makefile.asl ; to build the aslite application. IMPORTANT NOTE ABOUT SYSTEMS WITH AT LEAST 4GB OF MEMORY ======================================================== It has been found that systems with 4GB of system memory experience problems with the IOMMU. Under some of these systems, our device driver is unable to lock down and map transfer buffers necessary for streaming capture. The solution is to increase the amount of memory used by the IOMMU. To do this, you must alter the boot command to increase this memory by adding "iommu=memaper=4" to the linux command. This will increase the size of the iommu memory to 512MB, which seems to be sufficient in our testing. Refer to your distribution's documentation for how to do this for your particular system and boot loader. IMPORTANT NOTE ABOUT THE EXPRESS and EXPRESSHD FRAME GRABBERS ============================================================= When using the Accustream Express and the Accustream Express HD frame grabbers, it is important that you invoke aslite with the "-r" option the first time you use it. This will force the board into a hard reset, which will then check the FPGA versions found on the board against the file installed into the "/etc" directory. If they dont match, you will be asked to update the on-board flash memory from the file. This process will take a few minutes to complete, but only needs to be done once. After you have completed this process, you should not have to do it again, unless Foresight Imaging issues an update to the FPGA firmware. About the Device Driver ======================= The device driver is a loadable module that will detect the presence of Foresight Imaging frame grabbers on the PCI bus. This has only been tested in an Intel/AMD type systems. The driver is responsible for mapping in the device registers, servicing interrupts, arbitrating between multiple boards, and performing the memory operations to support scatter-gather DMA. The driver is loaded via a shell script, fsght_load.sh in the ./scripts directory. You must have root privileges in order to execute this script. The script will load the driver and then created up to 4 entries in the /dev directory for the frame grabber devices. The driver must be loaded before any applications. To remove the device driver, execute "rmmod foresight" from the command line. Again, you must have root privileges to use the rmmod command. The device driver allocates 4mb of contiguous memory necessary for writing transfer descriptors. It is possible that this will not be sufficient if you are using a large number of buffers and large capture formats. For example, running the streamtest application using a 1080p input format and specifying 80 buffers. If you experience failures under these circumstances, then increase the size of the descriptor space by increasing the variable: iOrderPagesInCommonBuffer as found in the file "foresight.c". Then rebuild and re-install the device driver. About the Libraries =================== To create an application that accesses a Foresight frame grabber, you must link with the appropriate libraries found in the ./archive directory. libhdlib.a - This is the main library. The interface to the API's in this library is found in ./include/hdp_lib.h. Every application must link with this library. libhdlin.a - This library contains interfaces specific to the port to LINUX. All applications must link with this library. libhdcmn.a - This library contains interfaces that are common to the non Win32 ports of the IDEA library. All applications must link with this library. libhdtl.a - This library contains interfaces for the TOOLS library used for Auto-SYNC. Interfaces to this library are found in ./include/ideatools.h. An application only needs to link with this library if it needs to perform Auto-SYNC functionality. The aslite application will link to this library to Auto-Sync a signal. About the Applications ====================== All applications included in this release are demonstration applications meant to show how to use the libraries to access the various frame grabbers. They are not meant to be used as commercial grade applications. As such they contain a minimum of features and error checking. You as the developer may use these applications as a starting point for your own applications. You may customize them and add error checking and validation necessary for a commercial grade application. Note that some of the software may refer to the original development directory structure, which would be /home/apps32. You may need to change such paths before building and executing the software in your particular setup. aslite - This is a command line version of Auto-SYNC. It will scan the incoming video signal and generate a valid CHP file that can be loaded by another application. It does not allow for any interactive tuning of the video parameters. It is important to specify the proper cable type on the command line when using this application. You may want to just hard code the cable type if you know that you will always be using a VGA style cable or a BNC type cable. In this directory is the autosync.c file which actually performs the autosync function. If you need to tweak how this operates, recompile this file and replace the object in the libhdtl.a archive. This application now takes a number of command line arguments so the source should be inspected prior to use. Supported command line arguments are: -v ; specify a path to the vesa template files, usually this will be /home/foresight/chp/vesachp -c[y,m] ; specify a colorspace of: y = YPbPr for HDTV signals m = single channel monochrome input -g ; do a test grab and save the image in File -d2 ; Use the HDMI input of the ExpressHD board -r ; issue a reset to the board. sgrab - This is a command line applications that initializes the board and perform a single snap and save the image to a bitmap file. You will need to edit and rebuild this application before using it. This will save images to a sub directory called "images". streamtest - This is a command line application to demonstrate the streaming capabilities of the library. This application will stream a specified number of frames to be written as bitmaps. This application will also save captured frames to a sub directory called "images". stream_ad - This application will also test streaming, but does not need to have a chp file specified because it will auto-detect the incoming video signal. This application will continually perform streaming capture to a specified number of files until control-c is pressed. fsiconfig - This application will initialize the board with a specified chp file and optionally grab a test image. After using this, the board is prepared for use by the VideoForLinux driver. Supported command line arguments are: -dN ; select device N in a multiboard installation -r ; reset the board's FPGA -f ; Initialize the board with chp file in Path. If no file is specified, the application will do an autosync operation to determine the signal. -c[y,m] ; specify colorspace to pass to autosync if necessary. -g ; do a test grab and save the image to File. fsicap - This application is a Glade-base GUI application that demonstrates snapping and displaying a static image. There is much work left to be done on this application and it will be more complete in future releases. Note that you will need the GTK2.0 development package installed in order to build this application. This application takes the chp file as a command line argument, i.e.: ./fsicap rs170.chp About the DVI Configuration utility ==================================================================== This utility will allow you to program the board's DVI personality prom. You may need to use this if the video source is interrogating the DVI dimensions from the board and fails to match. In this case you program the board with one of the included "DAT" files to force the board to respond with a certain format. Usage: ./dviconfig [-r] [-dn] [-p2] -f -r : force the board to reset -dn : use device n in a multi-board installation -p2 : use the HDMI port of the ExpressHD board -f : load the file specified by For example: ./dviconfig -r -f./datfiles/foresight_1280x1024.dat