Table of Contents

Getting Started with Codezero development

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

1.) Creating the directory structure for Codezero sources and tools

a. Make the following commands on the shell:

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

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

2.) Installing Git

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

For Ubuntu, please use the command below for the Git installation:

% sudo aptitude install git-core

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

3.) Installing SCons

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, please use the command below for installation:

% sudo aptitude install scons

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

4.) Installing the GCC cross-compiler

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

For installing the cross-compiler toolchain, please follow the steps below.

a. Create a directory for the cross-compiler toolchain:

% mkdir /opt/archives/cc

b. Download the latest GCC ARM cross-compiler toolchain (IA32 GNU/Linux Installer) for ARM EABI from: http://www.codesourcery.com/sgpp/lite/arm/portal/subscription3053

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

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

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

d. Use the following shell commands to configure and install the toolchain:

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

The last command would grant execution rights to run the binary, but root permission may be needed to achieve this.

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

The command above will start installing the toolchain. Choose appropriate options when prompted during the 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 at the end of the .bashrc file presently in the home directory of the current user (for example /home/amit for a fictional user named amit):

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

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

% source /home/user/.bashrc

% arm-none-eabi-gcc –help

This should display the help section of the installed GCC cross-compiler.

5.) Downloading Codezero sources

To download/clone the Codezero Git repository, please use the 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. The master branch on this repository contains the stable version of the sources. The devel branch includes the latest development sources.

6.) Building Codezero 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, a build.py script is provided in the project root directory /opt/codezero.

a. Please issue the following shell commands to run build.py:

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

which will first configure Codezero for the build and then start building it.

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

For more details please check:

7.) Installing QEMU

QEMU is a freely available virtual platform emulator.

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 its sources, please refer to the QEMU section in Installing from Source guide.

8.) Installing Insight

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

Using Insight and QEMU together, a complete ICE/HW debugging environment can be emulated that is faster than most real ICE debugger/HW platform solutions. Linux kernel debugging is also possible for precision in stepping through assembler files and symbols.

a. Create a directory for Insight.

% mkdir /opt/archives/insight

b. Download the 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 an insight-6.8-1 directory under /opt/archives/insight.

As an example, in Ubuntu you may install these libraries by:

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

The Ubuntu libncurses package contains the termcap library.

Other dependencies that must be installed are as follows:

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

e. Please 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

For more help on configuring Insight please run configure program by:

% ./configure --help
% make

followed by:

% make install

will build and install all the binaries in the system at the prefixed directory given during the configuration stage.

.gdbinit file

Insight is a GUI front end for GDB. GDB takes its configuration from the ”.gdbinit” file, which should be present under the home directory of the 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

tells GDB to connect to QEMU.

	load final.elf

loads the following image every time gGDB connects to QEMU.

	sym final.elf

tells GDB to use the following filename for symbol information.

	break break_virtual

A break_virtual symbol is defined as standard in Codezero builds, to mark the execution right after virtual memory is enabled. From this point onwards, it becomes possible to step through the code as desired. 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 the kernel.elf file for symbol information that includes Codezero symbol information after virtual memory is enabled.

Please copy this file over to your home directory:

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

Add the following lines in the end of the .bashrc file present in the home directory of the current user (For example: /home/amit for a 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 the new .bashrc file to be effective, a 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, run the following command on the shell:

% cd codezero/build
% arm-none-insight

which should start the Insight debugger with its GUI window.

9.) Running Codezero

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

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 container images embedded inside.

/opt/codezero/tools/run-qemu-insight script

The script above 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 the breakpoint during an 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
% gedit run-qemu-insight

opens up the 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 the /opt/codezero/build directory.
  2. In the second line, QEMU's ARM emulation binary is called using “qemu-system-arm”.
    • The ”-kernel” option tells QEMU to use the final.elf image, present in the current working directory as the kernel image.
    • The ”-m 128” option provides emulation of 128MB of available RAM.
    • ”-M” tells qemu to emulate processor/platform type; as specified here, the “ARM Versatile PB” platform is used. Currently, ARM/Versatile PB926 is the reference platform for running Codezero.
    • The ”-s” option tells QEMU to wait for a 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 the shell only after the debugger is terminated. This enables termination of QEMU as soon as the debugger is shut down.
  5. Finally, at the last line, the shell goes one directory level up to, i.e., /opt/codezero and finishes.
How it looks

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 breakpoints, and generally do everything possible with the Insight/GDB debugger. In order to debug userspace applications, please refer to the Codezero Application Development tutorial.

10.) Running Codezero-provided examples and templates

Codezero comes with a set of well-designed examples and templates called Bare-metal Projects, which a user can instantiate to see how the Codezero system works. Also, these examples can be used as templates to develop and generate new projects.

Within the codezero/config/cml/baremetal directory, various configuration files are present that can be used to build bare-metal projects provided by Codezero.

Any of the example scripts may be invoked for a build by issuing the following commands in the shell:

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

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

Note:

11.) Developing new projects for Codezero

Developers can follow the processes described here to build and integrate new projects to the Codezero build system. During the configuration phase, bare-metal projects provide two paths of development; either existing sources can be instantiated on their own or new projects may be created.

% cd codezero

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

Here, <description> would be a short, one-line description for the new project to be added, and <source_path> would be a directory containing the source files for new container to be added.

This is to be done only once, and after running the script, the container should appear as one of the bare-metal options during configuration.

To delete a recently added container project, the following commands may be used:

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

where <source_path> denotes the path where the project resides. For more help on using this script, use:

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

If you feel you are missing information or a concept is not described clearly enough, please notify us by direct email or ask on our mailing list.

12.) The next step

If you plan to develop and help 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 steps above.

For further information, please consult the Codezero Overview document, API Reference and join our codezero-devel mailing list, where technical issues about the Codezero microkernel are discussed.