Ultracam Software Installation Guide

Ultracam Linux RTAI version

1 Additional Requirements

Ultracam requires two kernel level systems to be installed prior to use, and several user mode software systems. Whilst you may find that Ultracam can compile and run on versions of software other than those listed here, we only attempt to support these explicit versions;

*Kernel extension*	*Version*	*Link*
RTAI real time extensions	24.1.13	​http://www.aero.polimi.it/~rtai/
Big Physical Memory Area	2.4.20	​http://www.polyware.nl/~middelin/En/hob-v4l.html#bigphysarea

*Software system*	*Version*	*Link*
ACE Toolkit	5.2.1	​http://www.cs.wustl.edu/~schmidt/ACE.html
libxml2	2.5.6	TBD
libxslt	1.0.31	TBD
cfitsio	TBD	TBD

2 Hardware support

Ultracam is usually installed on a dual (SMP) motherboard machine, since the availability of two CPUs allows the system to lock most of the real time processing onto one CPU and allow the other to run the user space programs. This can provide better performance of the non real time processes, particularly where large data frames are being processed, and allows users to run other programs without unduly affecting the real time performance. The downside to this is support for SMP motherboards - although Linux has very good support for SMP it appears that RTAI patched kernels have some problems, particularly with newer motherboards. The exact cause of this isn't known, although it apperas to be associated with how well the APIC on the motherbaord is supported. In any case, we have sucessfully run the system on two motherboard and processor combinations, and expect to update this list with newer motherboards when we have the time to try them. You are advised to use these hardware combinations, unless you have the time to trial RTAI on other combinations yourself. The two systems we current know to work are;

*Motherboard*	*CPU Type*
Gigabyte GA-6ETXDR (Socket 370 Dual Processors Motherboard)	2 x PIII MP
TYAN Thunder i7505 S2665 (BIOS rev 1.13.2665)	2 x P4 Xeon

It is possible to run Ultracam on single processor systems, as long as your throughput requirements aren't too high. In this case you should find that most CPUs and motherboards will work, although it is always a good idea to test the systems first. If you want to test a CPU and motherboard combination, you can obtain a copy of a LiveCD at ​http://issaris.org/rtai/; this system will boot from the CD and should allow you to test the system without installing anything.

3 Linux distribution

Ultracam has been successfully built on Redhat 7, 8 and 9 distributions and Debian Woody. In theory the distribution doesn't matter, since Ultracam needs a specific kernel from kernel.org to be built. But you might want to avoid newer distributions than those listed, since many have now moved to 2.6 kernels and may have dependencies on a 2.6 kernel being used. We hope to soon build and test Ultracam under a 2.6 kernel, which will allow newer distriubutions to be used. For now, a Redhat 9 system is the best known by the Ultracam team.

4 Compilers, make etc

Ultracam uses Autoconf/Automake, make and gcc (C and C++) throughout. At the very least you should have;

• GCC V2.95.3 (use *gcc -v* to check)
• Gnu make greater than 3.2 (use *make -v* to check)

It shouldn't be necessary to have Autoconf/Automake installed on the host machine.

5 Installing RTAI

The Real-Time Linux variant used for the Ultracam software is the DIAPM RTAI (see ​http://www.aero.polimi.it/~rtai/). Full installation instructions for RTAI are available, in the distribution and on the website, and you should check these and use them for install. However, below is a shortened summary for installing RTAI version 24.1.13 that you can use as a check list.

5.1 Download Linux kernel

We have based Ultracam on the RTAI patches for a stock 2.4.20 kernel. Whilst any of the kernels supported by RTAI version 24.1.13 can in theory be used, we would advise you to use the 2.4.20 kernel for compatability. We would advise against using any kernel sources that are not exactly the same as the base kerenls at ​http://www.kernel.org/.

1 Download the 2.4.20 kernel source 2 Un-tar the source to /usr/src (it will create a directory called linux-2.4.20) 3 Link /usr/src/linux-2.4.20) to /usr/src/linux

5.2 Download RTAI

1 Download the RTAI version 24.1.13 sourcecode 2 Un-tar the source to /usr/src (it will create a directory called rtai-24.1.13)

5.3 Patch the kernel

1 Chage to the kernel source directory (/usr/src/linux) 2 Patch the kernel source using patch patch-2.4.20-rthal5g from the RTAI directory;

<verbatim>patch -p1 < /usr/src/rtai-24.1.9/patches/patch-2.4.20-rthal5g</verbatim>

5.4 Configure the kernel

If you already have a working kernel, you may wish to copy the configuration files from that to ensure you get the correct drivers built. To do this, copy the configuration file (typically found in /boot) to .config, and then run <verbatim> make oldconfig</verbatim>.

1 build and run the kernel config, e.g.;

<verbatim>make menuconfig</verbatim>

2 enable *CONFIG_RTHAL*, the Real-Time Hardware Abstraction Layer, in the *Processor

type and features* menu.

3 disable *Set version information on all module symbols* under the *Loadable module support* menu 4 enable any other features that you want

5.5 Build and install the kernel

   > make deps
   > make modules   
   > make modules_install   
   > make bzImage  
   > make install 

5.6 Configure your loader

For&nbsp;lilo: edit /etc/lilo.conf and add a line for your new kernel and then run lilo to install it. For&nbsp;grub: edit /boot/grub.conf and add a line for your new kernel (this gets picked up automatically).

5.7 Reboot

Reboot the machine using the new kernel. If the new kernel doesn't work, boot under the old kernel and check the kernel and RTAI installation notes to fix it before preoceeding any further.

5.8 Configure and build RTAI

   # 1 Change to the RTAI source directory 
   cd /usr/src/rtai-24.1.13
   # 2 Configure RTAI (use the default selections unless you know better);
   make menuconfig
   # 3 Build the RTAI utilities
   make
   # 4 Install the RTAI utilities. Note that you need to check where the modules are installed (by default somewhere
   #   under /lib/modules) when you run the install command.
   make install
   make dev
   # 5 Install the SMP scheduler
   ./setsched smp

5.9 Test RTAI

Build and run the tests under the following directories (there are README files that explain each one);

• examples
• lxrt/examples
• mups_examples

Dont procede until you have convinced yourself that RTAI is running correctly.

Installing the bigphysarea kernel patch

The bigphysarea patch provides a convenient way of using a block of high physical memory as a kernel and user program accessible buffer area. The patch is available for numerous kernel versions.

Download and build bigphysarea

1 Download bigphysarea-2.4.20.tar.gz from ​http://www.polyware.nl/~middelin/En/hob-v4l.html#bigphysarea 2 change directory to /usr/src 3 Un-tar bigphysarea-2.4.20.tar.gz (it will create a directory bigphysarea-2.4.20) 4 Change directory to the linux kernel source (/usr/src/linux) 5 Patch the kernel from the bigphysarea-2.4.20 patch;

<verbatim> patch -p1 < /usr/src/bigphysarea-2.4.20/bigphysarea.diff </verbatim>

Re-build and install the kernel.

1 run <verbatim>make deps</verbatim> 2 run <verbatim>make modules</verbatim> 3 run <verbatim>make modules_install</verbatim> 4 run <verbatim>make bzImage</verbatim> 5 run <verbatim>make install</verbatim>

Configure your loader

In either /etc/lilo.conf or /boot/grub.conf (as appropriate) add a kernel parameter to reserve big physcial space at boot time. This is normally an "append command". Assuming that you want to reserve ~50MByte, you should add the following line; <verbatim> append="bigphysarea=1024"</verbatim> The size is in pages, which are by default 512KBytes on a linux system.

Reboot

Reboot the machine using the new kernel. If the new kernel doesn't work, boot under the old kernel and check the kernel and bigphysarea installation notes to fix it before preoceeding any further.

Check bigphysarea

You can check the bigphysarea (at any time) by looking in /proc, just do <verbatim>cat /proc/bigphysarea</verbatim>

Installing third party software

The ultracam system uses libxml2, libxslt and the ACE toolkit. Libxml2 and libxslt are probably already available with your chosen linux distribution, if not they can be installed using the normal *configure, make, make install* sequence. Since you supply the path to the installation directory of these packages, you don't have to install them under /usr, /usr/local etc. A good system might be to install libxml2, libxslt and ACE under a single root directory (where you also install the Ultracam software).

The ACE toolkit doesn't use configure at this time, use the following section to install it. Note that ACE doesn't have a normal install, you need to use it where you build it and add one of it's sub-directories to your LD_LIBRARY_PATH.

Download and unpack ACE

• Download ACE-5.2.1.tar.gz from ​http://www.cs.wustl.edu/~schmidt/ACE.html
• Un-tar ACE-5.2.1.tar.gz to a suitable build location, it will create a directory called _ACE_wrappers_
• cd to _ACE_wrappers_

Configure ACE

Read the file ACE-INSTALL or ACE-INSTALL.html for more information on setting up ACE.

• Set the variable ACE_ROOT to the path to the _ACE_wrappers_ directory, e.g. (if it was un-tar'd under /usr/src/Ultracam, and your shell is a csh derrivative) use;

<verbatim>setenv ACE_ROOT /usr/src/Ultracam/ACE_wrappers</verbatim>

• change to the _ace_ sub-directory;

<verbatim> cd $ACE_ROOT/ace</verbatim>

• link a suitable configuration file to config.h;

<verbatim> ln -s config-linux.h config.h </verbatim>

• change to the _include/makeinclude_ sub-directory;

<verbatim> cd $ACE_ROOT/include/makeinclude</verbatim>

• link a suitable configuration file to platform_macros.GNU;

<verbatim> ln -s platform_linux.GNU platform_macros.GNU </verbatim>

• Set the variable LD_LIBRARY_PATH to include the directory $ACE_ROOT/ace

<verbatim>setenv LD_LIBRARY_PATH $ACE_ROOT/ace:$LD_LIBRARY_PATH</verbatim>

You should probably consider setting the ACE_ROOT and LD_LIBRARY_PATH environmental variables in you shell profile (or similar).

Build and test ACE

• cd to the ACE root directory

<verbatim> cd $ACE_ROOT</verbatim>

• type *make*
• go away and have several cups of coffee, take a book with you. This takes a long time to build. As an alternative, you can cd to $ACE_ROOT/ace and run make there - although this will not buidl the tests
• cd to the $ACE_ROOT/tests directory, and run some of the test applications to check that ACE has built correctly.

It is possible to install the ACE libraries and includes to another location, but this isn't provided for in any makefile and isn't supported (yet) by this installation.

Install cfitsio

%RED% TODO: This section of the document needs to be written. %ENDCOLOR%

Finishing up =

At this point you should have;

1 A Linux 2.4.20 kernel with RTAI and bigphysarea available 2 libxml2, libxslt and ACE installed

You can now procede to un-tar, configure, build and then test Ultracam.

Installing Ultracam.

The Ultracam software can be installed anywhere, since (most of) it uses the Autoconf/Automake system for configuration. It is advisable to explicitly state the locations of libraries (etc) to be linked against, especially if you have had to install a different version of (e.g.) libxml2 than that supplied by your distribution.

Un-pack the ultracam distribution

• cd to a suitable directory, e.g. _/usr/src/Ultracam_
• un-tar UCam-0.9.tar.gz (this creates a directory _UCam-0.9_)
• cd to _UCam-0.9_

Configure Ultracam

You can configure ultracam using the supplied *configure* script. This is a normal Autoconf/Automake generated script, and takes the normal arguments such as *--prefix* (and all the arguments should work correctly).

As stated before, it is advisable to supply paths to all the required third party libraries and kernel locations;

*configure scipt option*	*use*
--with-kerneldir=dir	specify directory containing kernel sources
--with-rtai=PATH	specify location of RTAI modules
--with-xml=PATH	specify location of libxml2 library
--with-cfitsio=PATH	specify location of libcfitsio library
--with-ace=PATH	specify location of libACE library

Note: the RTAI modules will have been installed under /lib/modules/ when you ran make install in RTAI, see _Configure and build RTAI_.

So, assuming a 2.4.20 kernel in /usr/src/linux-2.4.20, RTAI in /usr/src/rtai-24.1.13 etc, your command might look like; <verbatim> ./configure --prefix=/usr/src/Ultracam --with-kerneldir=/usr/src/linux-2.4.20 --with-rtai=/usr/src/rtai-24.1.13 --with-xml=/usr/src/Ultracam --with-cfitsio=/usr/src/Ultracam --with-ace=/usr/src/Ultracam/ACE_wrappers </verbatim>

Build the Ultracam software

Just type *make* and then (if all goes well) *make install*. If you used the configure command given above, you should have the ultracam commands in _/usr/src/Ultracam/bin_, the libraries in _/usr/src/Ultracam/lib_ etc.

Building additional software

There are utilities for Ultracam available, such as the Java user interface. At the present time these should have there own README files to guide you through installation which should really be used. but since the Java interface is used for testing, a limited installation can be performed by following the folling section;

Installing the Java ucam interface (UClient)

In order to run the UClient interface you will need a Java2 1.4.2 runtime (or SDK).

1 cd to a suitable install location, say _/usr/src/ultracam_ 2 Un-tar the Java interface distribution (UClient.tgz), this should create a directory _UClient_ 3 cd to the UClient directory, and try running the build/bin/uclient script

<verbatim> cd UClient build/bin/uclient </verbatim>

The following notes might help you to get the application running, although they aren't the _correct_ method of installing the software they are quick and relatively easy.

• If the script isn't picking up your Java executable, edit the file build/bin/uclient and replace the path on the line

<verbatim> set JAVA = /usr/java/j2sdk1.4.2/bin/java </verbatim> with a path to your java executable

• If you have changed the port numbers for any of the camera servers (so the client can't connect) alter the file *build/bin/uclient.conf* to reflect these changes.

Testing Ultracam

At this point you really need to have an SDSU PCI board installed in the computer, and an SDSU camera controller attached to the PCI board by fibre. The Ultracam system does have a limited test capability without the controller attached, but this facility doesn't provide any usefull diagnostics.

Once you have the PCI board and controller hooked up, go through the following test procedure (assumes the ultracam executables are in the path).

1 Switch on the SDSU controller. 2 Check the LED just above the fibre connectors on the PCI board. If it is lit (red) then the connection is not properly

made. If all the connectors are seated correctly, try swapping the cables at *either* the controller *OR* the PCI card. If you can't make the red LED go out then you can't communicate.

3 Once the communications are working, start the camera server using the *startup_camera* script. 4 Now start the filesave using the *startup_filesave* script 5 Now start the client interface using *cd /usr/src/Ultracam/UClient && build/bin/uclient* 6 Hit the menu command "Initialise servers" 7 Hit the menu command "RCO" (reset controller) 8 Hit the menu command "RST" (reset PCI board) 9 hit the menu command "List applications"

You should now have a list of the available applications. Try loading and running any of them *EXCEPT* power on.