1. Obtaining CapROS

If you just want to have a look at the code, you can simply go to the Project page on GitHub, where you can browse through folders and files, or clone the repository.

2. Building CapROS

The host system is the system on which you build CapROS and do any development. The target system is the system on which you run CapROS.

These instructions apply when the host and target are both the Intel IA32 (x86) architecture. The target system could be the same computer as the host system (rebooted to run CapROS), or it could be a separate computer (possibly a virtual machine).

A port also exists for the ARM architecture target; see below.

2.1. Package Requirements

CapROS is built using Linux. If your system doesn't have the following packages, you may need to obtain and install them.

2.1.1. For Fedora

• Some versions need transfig.

2.1.2. For Debian Sarge

• libgmp3-dev -- Multiprecision arithmetic library
• binutils-dev -- for libbfd
• gawk

2.2. Obtaining the Cross Compilation Tools

Even though the host and target machines both have the Intel IA32 architecture, cross tools are necessary because most tools have dependencies on the underlying operating system. CapROS uses its own cross-compilation tools for stability. We acknowledge and thank the Coyotos project for hosting these tools.

Tools are available for Fedora Core 10 (and earlier systems). We hope to have tools for later systems soon. Some have had success building CapROS on Fedora Core 11.

2.2.1 Setting up on Linux/YUM Systems

If you are running Fedora Core 11 or greater, you can add the YUM repository to your yum and up2date configurations by executing:

su -c 'rpm -Uvh http://dev.eros-os.com/YUM/coyotos/Fedora/11/Coyotos-Repository.noarch.rpm'

Older versions of Fedora Core would use:

su -c 'rpm -ivh http://www.coyotos.org/YUM/coyotos/6/i386/Coyotos-Repository-3.2-2.fc6.noarch.rpm'

You can then install the cross compilation tools by running:

su -c 'yum install capros-i386-xenv'

And you can later update the cross compilation tools by running:

su -c 'yum update capros-i386-xenv'

(If the above fails, see email of 5/16/06.)

The capros-i386-xenv package is a "virtual" package - it simply supplies the necessary dependencies so that YUM will find all of the pieces you need. All of the CapROS cross environment tools install into the top-level directory /capros/.

For more information, refer to the Coyotos build instructions, substituting "capros" where appropriate.

2.2.2 Setting up on Fedora Core 8 using the GUI

If you are running on Fedora Core 8, you can add the build tools to your automatic software update list with the following procedure.

Under "Applications", open the "Add/Remove Software" and enter your root password when prompted. (Fedora 10 has an tool under System->Administration->Add/Remove Software, but it isn't capable of adding repositories.)

Open up the "Edit" menu and select "Repositories".

Fill in the fields:

Name:         Coyotos RPMs
Description:  Development tools for Coyotos/CapROS
Location:     http://www.coyotos.org/YUM/coyotos/6/i386/
	  

and click "OK".

Close the Repository Manager.

Select the "Search" tab, and enter "Coyotos-Repository" in the search. When the search completes, check the check box for:

Coyotos-Repository-3.2-2.fc6.noarch
	  

Click "Apply". Click "Continue" on the popup.

Select the "Search" tab, and enter "capros-i386-xenv" in the search. When the search completes, check the check box for:

capros-i386-xenv - 0.1.6.4fc6.i386
	  

Click "Apply". Click "Continue" on the popup.

2.2.3 Setting up on Other UNIX's

If you are building on some other UNIX derivative that does not support YUM, you may find that nothing will do but to build the cross environment for yourself. For instructions, go to the Coyotos build instructions for guidance. You may need to set COYOTOS_XENV to /capros/host and substitute "capros" where appropriate elsewhere.

2.3. Building CapROS

Follow the instructions on SourceForge for accessing and downloading the CapROS CVS repository. The projectname is capros, and the module name is eros (we haven't yet changed the name of the module). After setting CVSROOT appropriately, use the commands:

cd somewhere
cvs checkout -P eros

At the moment there is no tarball for the CapROS sources. We will add this when the system becomes stable enough for non-developers.

Now you can build CapROS by

cd somewhere/eros/src
make

Some make targets that may be useful:

• clean - remove all generated files
• distclean - clean, and also remove install directories under eros/
• update - get the latest version

3. Running CapROS

3.1. Supported Hardware

IA32 CapROS supports the following hardware (all trademarks belong to their respective owners):

3.2. Target System Setup

3.2.1. GRUB configuration

The target system must have GRUB installed, because CapROS is loaded by GRUB using the Multiboot specification.

The target system must have a boot partition with a file system where GRUB will find the file to load. Define CAPROS_BOOT_PARTITION as the name of this partition. For example, if the target system is the same as the host system:

export CAPROS_BOOT_PARTITION=/boot

The CapROS file is copied to the target system using scp. If the target system is a separate computer, you'll need to boot Linux (or any system that responds to scp) on that computer, and you'll need to configure it to allow ssh from the host computer. CAPROS_BOOT_PARTITION can be any path acceptable to scp. If the target system's host name is "target", you would define:

export CAPROS_BOOT_PARTITION=target:/boot

To boot CapROS, boot the target computer, stopping the boot when it comes to running GRUB. Type the following commands to GRUB:

root (hd0,1)     # or the appropriate value for your boot partition
kernel --type=multiboot /CapROS-kernimg

You will probably want to add an item to your GRUB menu.lst file with these commands.

3.2.2. Console configuration

Console output can go to the display console and/or to the target system's serial port. The default configuration is to send console output to the display only.

The display has the disadvantage that information you want can scroll off the top of the screen. (Also, in the future when CapROS supports a windowing GUI on the display, console output can't go there.) If you want you can change the configuration so console output is always sent to the serial port, and also to the display during kernel boot only. Also, in this configuration, the kernel debugger takes input from the serial port instead of the target system's keyboard. To do this, define the following in your environment:

export EROS_CONFIG=DEVEL

To use the output on the serial port, you'll need to connect it to the serial port of another computer, using a "null modem" cable. A program such as minicom can then capture and display the output. The serial configuration is 57,600 baud, 8-N-1.

3.2.3. Network Configuration

Network configuration means defining the IP address, mask, gateway, and security certificate for your target CapROS system. You only need to do this if you are using the IP network. Because this information is specific to each system, you should keep it in a place outside of the CapROS source tree. The CapROS source tree includes only a sample configuration which you should copy and modify.

Copy the sample configuration directory and files:

cp -r somewhere/eros/src/tutorials/config myconfig

You need to define the environment variable EROS_ROOT:

export EROS_ROOT=somewhere/eros

or you may simply define it in myconfig/Makefile.

Edit the file myconfig/eth.map to specify your IP address, mask, and gateway address.

To use HTTPS, you need a security certificate and private key. You can generate a self-signed certificate by typing the following and answering a few questions:

cd myconfig
make genkeys

Then install the files by typing:

cd myconfig
make install

3.3. Running a non-persistent test program

Make sure you rebuild CapROS after making any configuration changes.

To compile and load the test program into the target system:

cd somewhere/eros/src/tutorials/hello-large
make np

To run the test program, boot CapROS as described above. You will see some messages as the kernel boots, followed by the output of the test program.

Other test programs you can run can be found in other directories under eros/src/tutorials and eros/src/base/tests.

3.4. Running a persistent test program

3.4.1. Disk setup

CapROS supports USB disks. You must have a USB disk with a partition formatted for CapROS. Use a disk utility such as fdisk to create a partition, and give it type 0x95.

We suggest that the partition size be several times the size of your RAM (for the checkpoint log) plus however much space you expect to need for application data.

Before using the CapROS partition for the first time, you must format it. You do this on the host system by defining the shell variable EROS_HD as the device name for this partition. For example:

export EROS_HD=/dev/sdb1

You can create your own volmap file to allocate the log and other space. Use tutorials/volmap as a starting point. Note that only the amount of space specified in the volmap file will be used. Any additional space in the partition will be ignored.

Then format the partition. You only need to do this to the partition once. This may take a while.

cd somewhere/eros/src/tutorials/https/main
make init.hd

3.4.2. Running the Test Program

Test programs that you can run can be found under eros/src/tutorials and eros/src/base/tests. If the directory has a pimgmap file, it is meant to be run in a persistent system, otherwise it is to be run in a non-persistent system. To build and load the test, type for example:

cd somewhere/eros/src/base/tests/func/http
make p

There is a web-key demonstration in eros/src/tutorials/https. Be sure to read and follow the README file in that directory.

4. Building for ARM

CapROS can run on the ARMv4 architecture. First, get the ARM cross-tools:

su -c 'yum install capros-arm-xenv'

To build for ARM, you need to:

export EROS_TARGET=arm

You also need to set CAPROS_MACH to the board you are using. edb9315 and edb9315a are currently supported.

The system has been tested on a Cirrus EDB9315 development board, which uses the Cirrus EP9315, which is based on the ARM920T microprocessor.

To run on the EDB9315:

1. Build the system for ARM.
2. Go to the directory containing the test case you want to run, for example src/base/tests/perf/nc. The kernel text, kernel data, and initial system state are loaded into the system's memory from three separate files in /tftpboot (kerneltext, kerneldata, and imgdata respectively). Build them:

   make np
   

3. Set up Redboot according to the instructions that came with the EDB9315. To install tftp, you will need to:

   su -c 'yum install tftp-server'
   

   and then use the application at System->Administration->Services to enable tftp and restart xinetd. I also had to enable UDP port 69 in my firewall, and change the SELinux setting to Permissive.
4. Boot the EDB9315 to execute Redboot. Give Redboot the commands:

   load -v -r -b 0x00300000 imgdata
   load -v -r -b 0x00100000 kerneldata
   load -v -r -b 0x00200000 kerneltext
   go
   

   kerneltext is loaded last because that sets the default start address for the go command. Consider using Redboot aliases for these commands.

Copyright 2005-2011 by Strawberry Development Group. Copyright 2022 by Charles Landau. All rights reserved. For terms of redistribution, see the GNU General Public License This material is based upon work supported by the US Defense Advanced Research Projects Agency under Contract No. W31P4Q-07-C-0070. Approved for public release, distribution unlimited.