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.

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.

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.

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.

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.

• Note: The 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 relevant compiler prefix options are already referred to in the configuration system and may be changed for different toolchains.

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

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

Download latest GCC ARM cross-compiler toolchain (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 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.

• Please use an installation path as ”/opt/tools/cc” when prompted.
• Please read the “Getting Started Guide” presently at http://www.codesourcery.com/sgpp/lite/arm/portal/release1033 for more help in 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

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

% arm-none-eabi-gcc –help

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

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.

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.

• This will start building the Codezero project; a configuration screen (like “make menuconfig” in Linux) will pop up, prompting the user to choose various configuration options for building Codezero.
• The user can either choose the default configuration or decide to use a custom configuration. Please refer to the Codezero Configuration Symbols section for more help on configuration symbols and their meanings. Press the 'x' key to save the configuration and use the arrow keys to move up, down, in, and out of the menu and submenu. The 'h' key will display help for the individually selected symbol, and the 'c' key will provide help on general usage of the configuration system.
• This will build the Codezero microkernel and various containers selected, producing an elf image in the respective build folders: e.g., container0.elf under /opt/codezero/build/cont0/, in case we compile Codezero with one container selected.
• During the next step, the build system will combine all the generated elf images to produce a final image called “final.elf” under the /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 the build.py script. Some important options are described below:

• ./build.py -f <config_file>: Build Codezero using an existing configuration file as given by the <config_file> path.
• ./build.py -r: Reset the configuration to its default.
• ./build.py -C: Configure before building.

For more details please check:

• ./build.py -h

QEMU is a freely available virtual platform emulator.

• Codezero uses the QEMU/ARM Versatile platform as the reference platform for development. For SMP/Cortex-A9, B Labs also provides a version that emulates this setup over the Versatile Express platform.
• The latest version of QEMU needs a patch in order to work correctly with GDB/Insight. Particularly, the -s switch behavior needs to be modified so that QEMU waits for a 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 its 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 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.

• Insight 6.8 is known to work well with QEMU, and it is highly recommended to use version 6.8 of Insight with QEMU. Other versions have not been tested when creating this guide.
• Insight needs to be built from its sources, as it needs to be configured for the ARM architecture at the time of compiling Insight.

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.

• Note: Insight depends on the X11 Development Libraries and the termcap library. Both of these should be installed before installing 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

• Before running make, a -Werror flag may need to be removed from gdb/Makefile and the WERROR_CFLAGS variable left as empty.

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

• ”–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 cross-compiler gGDB that exists on the host.
• ”–with-expat” is required for GDB parsing the target XML definition file during connection to QEMU.

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

% ./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

followed by:

% make install

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

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

• 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 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.

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.

• Please refer to the Codezero Overview guide to get an understanding 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 container images embedded inside.

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.

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.

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:

• Configuration files present under codezero/config/cml/posix, may be used to run various examples of POSIX projects/containers.
• Configuration files present under codezero/config/cml/linux may be used to invoke the virtualized Linux kernel container.

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.

• The Hello World and Empty containers automatically create new project directories, ready to be built for integration with the Codezero runttime. New projects would typically reside within the codezero/conts/<project_name> directory, where the <project_name> value may be selected during configuration. Application development would take place inside these directories, and builds may be invoked via the build.py script at the Codezero root. Application testing may then take place on real or emulation hardware by loading and running the final.elf image resulting from these builds.
• Once the project is developed to completion, it may be desirable to integrate the project as one of the standard bare-metal builds provided during the configuration phase. For this purpose, codezero/scripts/baremetal/baremetal_add_container.py script should be run on the ready container project as follows:

% 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

• Apart from the Hello world and empty project types, all other bare-metal containers may be directly built from sources that are already resident under codezero/conts/baremetal/<project_name> directories for demonstration purposes.

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.

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.