This Version Adapted for JAC Use by Maren Purves. Additional

This version adapted for JAC use by Maren Purves.

Additional Requirements Hardware support Linux distribution Compilers, make etc Installing RTAI Download Linux kernel Download RTAI Patch the kernel Configure the kernel Build and install the kernel Configure your loader Reboot Configure and build RTAI Test RTAI Installing the bigphysarea kernel patch Download and build bigphysarea Re-build and install the kernel. Configure your loader Reboot Check bigphysarea Installing third party software Download and unpack ACE Configure ACE Build and test ACE Install cfitsio Finishing up Installing Ultracam. Un-pack the ultracam distribution Configure Ultracam Build the Ultracam software Building additional software Installing the Java ucam interface (UClient) Testing Ultracam

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

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.

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.

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.

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.

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 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)

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; patch -p1 < /usr/src/rtai-24.1.9/patches /patch-2.4.20-rthal5g

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 make oldconfig.

1. build and run the kernel config, e.g.; make menuconfig 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

Build and install the kernel

1. run make deps 2. run make modules 3. run make modules_install 4. run make bzImage 5. run make install

Configure your loader

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

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.

Configure and build RTAI

1. Change to the RTAI source directory (/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

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; patch -p1 < /usr/src/bigphysarea-2.4.20/bigphysarea.diff

Re-build and install the kernel.

1. run make deps 2. run make modules 3. run make modules_install 4. run make bzImage 5. run make install

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; append="bigphysarea=1024" 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 cat /proc/bigphysarea

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; setenv ACE_ROOT /usr/src/Ultracam/ACE_wrappers setenv ACE_ROOT /jac_sw/itsroot/src/ucam/src/ACE_wrappers

change to the ace sub-directory; cd $ACE_ROOT/ace

link a suitable configuration file to config.h; ln -s config-linux.h config.h

change to the include/makeinclude sub-directory; cd $ACE_ROOT/include/makeinclude

link a suitable configuration file to platform_macros.GNU; ln -s platform_linux.GNU platform_macros.GNU

Set the variable LD_LIBRARY_PATH to include the directory $ACE_ROOT/ace setenv LD_LIBRARY_PATH $ACE_ROOT/ace:$LD_LIBRARY_PATH setenv LD_LIBRARY_PATH $ACE_ROOT/ace

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 cd $ACE_ROOT

type make go away and have several cups of coffee, take a book with you. This takes a long time to build (or build overnight, during your lunch break or over a doctor's appointment). As an alternative, you can cd to $ACE_ROOT/ace and run make there - although this will not build 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

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

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.

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;

./configure --prefix=/usr/src/Ultracam --with-kerneldir=/usr/src/linux-2.4.20 --with-rtai=/usr/src/rtai-2 --with-xml=/usr/src/Ultracam --with-cfitsio=/usr/src/Ultracam --with-ace=/usr/src/Ultracam/ACE_wrappers

Rather than typing this each time, you can use Stewart McLay's myconfig, customizing it where necessary (e.g. the build version).

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.

If you have just gotten this out of CVS, likely some timestamps are off and 'make' will fail with rather cryptic errors. If this happens, use the 'bootstrap' command (also by Stewart McLay, I believe), 'configure' again, and then 'make'

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

cd UClient build/bin/uclient 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

set JAVA = /usr/java/j2sdk1.4.2/bin/java 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.

-- Andy Vick - 17 Mar 2005