ADM-XRC LTS Driver for Linux ============================ 1. Overview ----------- This package can be considered to be the runtime that is required to run an application developed using the ADM-XRC SDK. The following hardware is supported: o ADM-XRC o ADM-XRC-P o ADM-XRC-II-Lite o ADM-XRC-II o ADP-WRCII o ADP-DRCII o ADM-XPL o ADM-XP o ADP-XPI o ADM-XRC-4LX o ADM-XRC-4SX o ADCP-XRC-4LX o ADM-XMC-4FX / ADM-XRC-4FX o ADPE-XRC-4FX o ADM-XRC-5LX o ADM-XRC-5T1 o ADM-XRC-5T2 o ADM-XRC-5T2-ADV / ADM-XRC-5T2-ADV6 o ADM-AMC-5A2 o ADM-XRC-5TZ o ADM-XRC-5T-DA1 o ADM-XRC-5T2-ADV-CC1 o ADC-BBP o ADM-PCIE-6S1 2. Building the driver ---------------------- NOTE: this section is applicable only to a driver that is built natively, i.e. the development machine and the target machine are the same. First, as an unprivileged user, run the "configure" script in the same directory as this README file: $ ./configure This will detect certain features of the Linux distribution and kernel, and writes configuration information to two files: .kernel_path and .build_defs. Next, build the driver and shared libraries: $ make clean all At this point, the driver is ready to be installed on the target filesystem. Refer to section 3 for instructions. 3. Installing the driver ------------------------ NOTE: this section is applicable only to a driver that is built natively, i.e. the development machine and the target machine are the same. Installing the driver must be done as a privileged user such as root: $ make install This will install the kernel module (admxrc2.ko) in the system modules directory, which is normally /lib/modules/<kernel version>/kernel/drivers/addon/admxrc2 It also copies the shared libraries to the system library directories, which are normally /usr/lib/ /usr/lib64/ (in bi-architecture systems) If installation is successful, the following files and symbolic links are created: /lib/modules/<kernel version>/kernel/drivers/addon/admxrc2/admxrc2.ko /usr/lib/libadmxrc2.so /usr/lib/libadmxrc2.so.2 /usr/lib/libadmxrc2.so.2.X.Y.Z /usr/lib32/libadmxrc2.so /usr/lib32/libadmxrc2.so.2 /usr/lib32/libadmxrc2.so.2.X.Y.Z /usr/lib64/libadmxrc2.so /usr/lib64/libadmxrc2.so.2 /usr/lib64/libadmxrc2.so.2.X.Y.Z /etc/udev/rules.d/51-admxrc2.rules where X.Y.Z is the release number of this package, e.g. 4.0.0. NOTE: Depending on the architecture of your machine, and whether or not you have built the runtime as bi-architecture (32-bit & 64-bit), some of the directories /usr/lib, /usr/lib32 and/or /usr/lib64 may not exist in your system. 4. Cross-building the driver ---------------------------- NOTE: this section is applicable only to a driver that is cross-built, i.e. the development machine and the target machine are different. This procedure asssumes that the environment variables ARCH and CROSS_COMPILE are correctly defined for cross-compilation. For example, ARCH=powerpc CROSS_COMPILE=powerpc-e600-linux-gnualtivec- and that the GNU cross-compiler toolchain binaries are in the PATH. First, as an unprivileged user, run the "configure" script in the same directory as this README file: $ ./configure -sysroot /path/to/target_filesystem -kernel /path/to/target_kernel_sources This will detect certain features of the target system's Linux kernel, and write out configuration information. Next, build the driver and shared libraries: $ make clean all At this point, the driver is ready to be installed on the target filesystem. Refer to section 5 and/or 6 for instructions. 5. Installing the cross-built driver ------------------------------------ Assuming the instructions in section 4 above have been followed, installing the driver and associated files on the target filesystem is a matter of using the 'install' target like so: $ make install It may be necessary to reboot the target system or run 'depmod' as root on the target system before the newly installed 'admxrc2.ko' module can be found by the system. 6. Manually installing a cross-built driver on the target system ---------------------------------------------------------------- NOTE: this section is applicable only to a driver that is cross-built, i.e. the development machine and the target machine are different. If the procedure in section 5 above does not work for some reason, this section offers guidelines on how to manually install the cross-compiled driver and associated files on the target filesystem. We cannot offer instructions guaranteed to work on all systems, since Linux distributions can vary greatly in the root filesystem layout. The general procedure is: a) Copy driver/monolithic/linux/admxrc2.ko to the appropriate kernel modules directory on the target filesystem, i.e. to /lib/modules/<kernel version>/kernel/drivers/addon/admxrc2/ Some directories in this path may need to manually created when installing for the first time. b) Copy the udev rules files to the target filesystem's /etc/udev/rules.d/ directory. The rules files are: driver/monolithic/linux/51-admxrc2.rules c) Copy api/modules/admxrc2/linux/obj/libadmxrc2.so.2.X.Y.Z to the target filesystem's /usr/lib/ directory. d) Create the usual symbolic links in the target filesystem's /usr/lib/ directory; for example: /usr/lib/libadmxrc2.so -> /usr/lib/libadmxrc2.so.2.X.Y.Z /usr/lib/libadmxrc2.so.2 -> libadmxrc2.so.2.X.Y.Z 7. Starting the driver on the target system ------------------------------------------- Practically every modern Linux distrubtuion uses the "udev" device manager to manage device nodes in the /dev directory. This driver interacts with udev so that when the driver is started, device nodes in /dev are automatically created. The command to start the driver on the target system is modprobe admxrc2 which must be executed as root. If desired, this command can be added to the /etc/rc.d/rc.local script. To stop the driver, issue the command rmmod admxrc2 which must also be executed as root. Any device nodes that were created in /dev when the driver was started will be automatically deleted. Note that attempting to stop the driver whilst at least one program has an open handle to a device (that is controlled by the driver) will fail, and the driver will not be stopped.