This step by step guide explains on how to download, install and configure various tools required to build, run and debug Codezero.

a. Give the following commands on shell:

% mkdir /opt
% mkdir /opt/archives
% mkdir /opt/tools

This will respectively create the directories where Codezero source code and required build tools will be saved and installed in reference to this guide.

Git SCM tool is needed for downloading and managing Codezero sources.

For Ubuntu users, give the following shell command:

% sudo aptitude install git-core

To install git or any other package from the Ubuntu repository, sudo password is required. On Ubuntu, git installation is done by the above step. For non-Ubuntu users, please refer to Installing from Source guide for installation of git from scratch.

Codezero uses SCons as its build software. SCons is a python-based build tool where builds can be manipulated using Python scripts and functions.

For Ubuntu users, give the following shell command:

% sudo aptitude install scons

Sudo password is required for this step. SConstruct installation is done. For non-Ubuntu users, please refer to Installing SCons section in the Installing from Source guide.

Codezero project uses the Codesourcery ARM cross-compilers for compiling the sources. Other cross-compilers such as crosstools may work, but testing is done using this toolchain.

• Note, Codesourcery toolchain comes in two types for ARM, namely EABI and GNUEABI. The former is used for building barebones embedded software (such as OS kernels), the latter is for building applications for Linux. In Codezero a similar choice is made; the microkernel is built using the eabi toolchain, and the userland is built using the gnueabi toolchain. The respective compiler is already referred to in the relevant build files.

For installing the cross compiler tool chain, follow the steps below.

a. Create a directory for cross compiler tool chain.

% mkdir /opt/archives/cc

b. Download latest gcc arm cross compiler tool chain(IA32 GNU/Linux Installer) for ARM EABI from http://www.codesourcery.com/sgpp/lite/arm/portal/subscription3053.

• A file named “arm-2009q3-68-arm-none-eabi.bin” will be downloaded.

Download latest gcc arm cross compiler tool chain(IA32 GNU/Linux Installer) for GNU-LINUX from http://www.codesourcery.com/sgpp/lite/arm/portal/subscription3057.

• A file named “arm-2009q3-67-arm-none-linux-gnueabi.bin” will be downloaded.

We have tested 2009q1 and 2009q3 tool chains, so preferably download any of these.

c. Save both files to /opt/archives/cc.

d. Give the following shell commands to configure and install tool chain:

% cd /opt/archives/cc
% chmod 777 arm-2009q3-68-arm-none-eabi.bin

The last command would give execution right to run the binary, and root permission may be needed for this.

% . arm-2009q3-68-arm-none-eabi.bin -i console

This will start installing tool chain choose appropriate options when asked during installation of the tool chain. Default options can be chosen.

• Give installation path as ”/opt/tools/cc” when asked.
• Please read the “Getting Started Guide” present at http://www.codesourcery.com/sgpp/lite/arm/portal/release1033 for more help in installation of the toolchain.

e. Repeat step (d) above for installing arm-2009q3-67-arm-none-linux-gnueabi.bin binary.

f. Add the following lines in the end of .bashrc file present in the home directory of current user (for example /home/amit for the fictional user named amit):

% PATH=$PATH:/opt/tools/cc/bin
% export PATH

This will add path of installed tool chain binaries to PATH environment variable. Please note for new .bashrc to be effective new console should be started, for making changes in .bashrc to be effective in currently running console, give the following command in console:

% source /home/amit/.bashrc

Here again, amit is the fictional current user, replace it appropriately.

• To test if the toolchain is installed properly and paths are updated suitably, give following command on shell:

% arm-none-eabi-gcc –help

This should display the help section of gcc cross compiler.

To download/clone Codezero git repository give following shell commands:

% cd /opt
% git clone git://www.git.l4dev.org/codezero.git

This will start cloning the repository and will create the Codezero source tree under the directory /opt/codezero. master branch on this repository contains the stable version of the sources. The devel branch includes the latest development sources.

Provided here are the minimal instructions needed to build Codezero. Please refer to the Codezero Overview guide for general information about the Codezero directory layout and generated images during a Codezero build.

To build Codezero, build.py script is provided in the project root directory /opt/codezero.

a. Give the following shell commands to run build.py:

% cd /opt/codezero
% ./build.py -c

This command will do both, configure and build for codezero.

Note: In case you want to use old configuration/last used configuration only, give ”./build.py” command.

• This will start building the Codezero project, a configuration screen like “make menuconfig” as in Linux will pop up asking the user to choose various configuration options for building Codezero.
• You can either choose the default configuration or decide your own configuration. Please refer to Codezero Configuration Symbols section for more help on configuration symbols and their meanings. Press the “x” key to save configuration, arrow keys to move up, down and in and out of menu and submenu.
• This will build the Codezero microkernel and various containers selected, producing an elf image in the respective build folders: e.g. cont0.elf in /opt/codezero/build/cont0/, in case we compile codezero with one or more container selected.
• Next step, the build system will combine all produced elf images to produce a final elf image “final.elf” under /opt/codezero/build folder. This final executable contains the external loader with all necessary images embedded inside.

Note: There is a complete set of options available that can be used with build.py script. Some important options are described here:

• ./build.py -f <config_file>: Build codezero using pre existing configuration file as given by <config_file>.
• ./build.py -r: Reset the configuration to default.
• ./build.py -c: Configure before building.

For more details please check ”./build.py -h”. In case you just want to configure codezero without building it, you can use configure.py script, as follows:

• ./configure.py: This will just configure codezero, without building it.

QEMU is a freely available virtual platform emulator.

• Codezero uses QEMU/ARM Versatile platform as the reference platform for development.
• Latest version of QEMU needs a small patch in order to work correctly with GDB/Insight. Particularly -s switch behaviour needs to be modified so that QEMU waits for gdb connection before proceeding.

You may use the patched and prebuilt qemu-system-arm binary provided on this link. If you have any difficulty running this binary, please let us know

Alternatively, if you prefer to build and install QEMU from the sources, please refer to the QEMU section in Installing from Source guide.

Insight is a GUI front-end for GDB with a focus on cross-debugging of embedded targets. Insight is not necessary to be able to run Codezero, but it greatly simplifies development by providing step-by-step debugging and inspection opportunities for both Codezero Microkernel and its userland applications.

• Insight 6.8 is known to work well with QEMU and it is highly recommended to use 6.8 version of insight with QEMU. Other versions may not work properly.
• Insight needs to be built from the sources, as it needs to be configured for arm architecture at the time of compiling insight.

a. Create a directory for insight.

% mkdir /opt/archives/insight

b. Download insight tarball(for example insight-6.8.tar.bz2) from ftp://sourceware.org/pub/insight/releases.

c. Save it to /opt/archives/insight.

d. Use the following shell commands to untar the tarball:

% cd /opt/archives/insight
% tar -xjvf insight-6.8-1.tar.bz2

This will generate insight-6.8-1 directory under /opt/archives/insight.

• Insight depends on “X11 Development Libraries” and “termcap library”. Both of these should be installed before installing Insight. Termcap is available at http://linux.softpedia.com/get/Terminals/GNU-termcap-23867.shtml.

As an example, in Ubuntu you may do:

% sudo aptitude search libncurses5
% sudo aptitude install libncurses-dev libncurses5-dev
% sudo aptitude search libx11
% sudo aptitude install libx11-dev

In Ubuntu libncurses package has termcap library.

Other dependencies that must be installed:

% sudo aptitude search makeinfo
% sudo aptitude install texi2html
% sudo aptitude install texinfo
% sudo aptitude search expat
% sudo aptitude install libexpat-dev libexpat1-dev

• You may need to remove -Werror flag from gdb/Makefile and leave the WERROR_CFLAGS variable as empty. You should do this before running `make'.

e. Use the following shell commands to configure and install insight:

% mkdir /opt/archives/insight-build
% cd /opt/archives/insight-build
% ../insight-6.8-1/configure --prefix=/opt/tools/insight --target=arm-none-eabi
    --program-prefix=arm-none- --with-expat

• ”–target=” tells configure that the target to debug using insight is “arm-none-eabi”. The –program-prefix” is the prefix to be added to all generated executables. For instance, arm-none-gdb and arm-none-insight. This avoids confusion with Insight/gdb and the the cross-compiler gdb that exists on the host.
• ”–with-expat” seems to be required for GDB parsing the target xml definition file during connection to QEMU.

For more help type:

% ./configure --help

• Please note insight is tested to work with GCC 4.4.1 or higher. It is recommended to use this version of gcc. If not, a 3.x series GCC compiler may give better results. Command line option “CC” can be used to specify the compiler to be used for compiling Insight.

% make

This will build insight binaries.

% make install

This will install all the binaries in the system at the prefixed directory given during configure.

Insight is a gui frontend for GDB. GDB takes its configuration from ”.gdbinit” file which should be present under the home directory of current user. (For example /home/amit for the fictional user named amit). To connect gdb to QEMU that is running Codezero and load its symbols, the following commands should be written to the .gdbinit file, line-by-line. Note the file is broken up below to explain each step.

	target remote localhost:1234

This command tells gdb to connect to qemu.

	load final.elf

Loads the following image everytime gdb connects to qemu.

	sym final.elf

This command tells gdb to use following file name for symbol information.

	break break_virtual

A break_virtual symbol is defined in Codezero right after virtual memory is enabled. From this point onwards, it becomes possible to step through the code as pleased. This command makes gdb stop right after virtual memory is enabled.

	continue
	stepi

These commands tell gdb to start from beginning, step over one instruction after the break_virtual breakpoint is hit. This will allow insight to refresh its screen with the new symbol table.

	sym kernel.elf

This command tells gdb to use kernel.elf file for symbol information which includes Codezero symbol information after virtual memory is enabled.

Copy this file over to your home directory:

% cd codezero
% cp ./tools/gdbinit ~/.gdbinit

• For more help on these commands, please check the gdb manual available at http://www.gnu.org/software/gdb/documentation.

Add the following lines in the end of .bashrc file present in the home directory of current user (For example /home/amit for fictional user named amit):

% PATH=$PATH:/opt/tools/insight/bin
% export PATH

This will add the path of Insight binaries to PATH environment variable. Please note for new .bashrc to be effective new console should be started. For making changes in .bashrc to be effective in the currently running console, the following command should be used:

% source /home/username/.bashrc

To test if insight is installed properly and paths are updated correctly, give the following command on shell:

% cd codezero/build
% arm-none-insight

This should start the Insight debugger with its GUI window.

After all tools have been installed as described in the previous sections and Codezero sources have been successfully built, it is time to put everything together and run Codezero.

• Please refer to the Codezero Overview guide to get a brief idea about what is included in the standard build, the executables created, and the directory layout of the project.

After Codezero has been successfully built, a final.elf executable should be present under the /opt/codezero/build directory. This image is the external loader executable that has the microkernel and all userspace tasks embedded inside.

The script run-qemu-insight contains all the necessary commands to start QEMU, load final.elf, start Insight and initiate execution until the point where virtual memory is enabled inside the Codezero Microkernel. Here, some logic is provided by the .gdbinit file under the home directory for loading the symbols, and setting breakpoint during Insight/GDB startup.

Running the script simply starts everthing and executes Codezero until virtual memory is enabled:

% cd /opt/codezero
% ./tools/run-qemu-insight

Taking a closer look at the run-qemu-insight script:

% cd /opt/codezero/tools
% vim run-qemu-insight

Opens up the l4-qemu script file, which contains the lines:

cd build
qemu-system-arm -s -kernel final.elf -m 128 -M versatilepb -nographic &
arm-none-insight ; pkill qemu-system-arm
cd ..

1. As this script is run from /opt/codezero directory, the shell enters /opt/codezero/build directory.
2. In the second line, QEMU's ARM emulation binary is called using “qemu-system-arm”.
   • ”-kernel” option tells QEMU to use final.elf image, present in the current working directory as ther kernel image,
   • ”-m 128” option provides emulation of 128MB of available RAM,
   • ”-M” tells qemu to emulate processor/platform type, as specified here “ARM Versatile PB” platform is used. Currently, ARM/Versatile PB926 is the reference platform for running Codezero.
   • ”-s” option tells QEMU to wait for debugger connection before executing anything. This option is particularly broken on newer versions of QEMU.
   • The ”-nographic” option redirects PL011 UART output directly to the console.
3. “arm-none-insight” in the third line starts the insight debugger.
4. The next command i.e “pkill qemu-system-arm” is executed by shell only after the debugger is terminated. This enables termination of QEMU as soon as the debugger is shut down.
5. Finally by the last line the shell goes one directory level up i.e /opt/codezero and finishes.

The following is a typical screenshot after Codezero is up and running in control of the Insight debugger. If you have come to this stage, it means you have successfully built and run Codezero for the first time.

From this point onwards, you may step through the Codezero initialization code, place break points and generally do everything possible with the Insight/GDB debugger. In order to debug userspace applications, please refer to the Codezero Application Development tutorial.

Codezero comes with a set of well designed examples and templates called Baremetal Projects, that a user can run to see how codezero system works, and also these examples can be used as templates to develop and generate new Projects.

If you check folder: codezero/config/cml/baremetal, we have a complete set of various configuration files present that can be used to build baremetal projects provided by codezero.

You can chose any any of the example script and run it simply by issuing the following commands in shell:

% cd codezero
% ./build.py -f </path/to/config_file>

Sources for various baremetal projects are present at: codezero/conts/baremetal/

Note:

• You can also use example configuration files, present at codezero/config/cml/posix, to run various examples of posix projects/containers.
• You can also use example configuration files, present at codezero/config/cml/linux, to run various examples of linux projects/containers (Not yet ready).

Developers can follow the following process/cycle to build and integrate new containers/projects in Codezero build system:

• Go to the following directory, codezero/conts/baremetal/empty. This directory contains an “Empty Projects” that do nothing but just act as a template for developers, from where on they can do their development work and develop new containers/projects/applications/drivers.
• Do the development work here in this container, test it (while building you will see that the build directory for this container is present at codezero/conts/empty0, also all the source files are copied from codezero/conts/baremetal/empty to codezero/conts/empty0).
• Now rename codezero/conts/empty0 to the name of your choice, say codezero/conts/developers_project. The renaming stuff is important as, the name of the base directory will be used as the name of new container to be added in codezero build system.
• Once you are ready with your work, you can integrate this container in codezero build system, so that next time when you configure codezero, you can see this container in menu and select it to run it. For integrating newly developed containers/projects, we have provided a script at:

codezero/scripts/baremetal/baremetal_add_container.py. Use this script as follows:

% cd codezero
% ./scripts/baremetal/baremetal_add_container.py -a -i <description> -s <source_path>

Here, <description> : short description for the new project to be added, and <source_path>: directory containing the source files for new container to be added.

In above mentioned development scenario <source_path> should be codezero/conts/empty0

And we are done, next time when you build codezero, you can see new project under “Baremetal Projects” menu.

In case you want to delete some earlier added project, use the following commands:

% cd codezero
% ./scripts/baremetal/baremetal_add_container.py -d -s <source_path>

<source_path> gives the path where the project resides. For above mentioned empty project case, <source_path> should be codezero/conts/baremetal/developer_project. For more help on using this script, use:

% ./scripts/baremetal/baremetal_add_container.py -h

Note:

• In case you think, your development work matches any of the pre existing Baremetal Projects, or you can take advantage of source of any other Baremetal Project, you can do the development work in that container too instead of “Empty Project”, as mentioned above. For eg:

If you are doing some work related to UARTS, you can consider working in UART Service Baremetal Project. Same process/cycle is applicable here also.

If you are aiming to develop and help on improving the Codezero software, the current setup would be sufficient.

The development cycle would be such that new changes would be made, recompiled and tested on QEMU/Insight as described in the above steps.

You should take a look at the Codezero Overview document, Codezero Application Development tutorial, API Reference and finally you may also join our codezero-devel mailing list, where we publicly discuss technical issues about the Codezero Microkernel.