Getting Started with Codezero development

The hypervisor toolkit releases contain prebuilt versions of the hypervisor image, tools and documentation. The toolkit releases are specifically tailored for application development on top of Codezero.

This is a quick getting started guide that explains how to download, install, build and develop on Codezero Embedded Hypervisor Toolkit releases.

• Please download Codezero Hypervisor Toolkit from the downloads page. The installer provides support for Ubuntu/Debian hosts, and the tarballs provide the same environment although bin paths to tool directories must be updated manually.

• Please read README file and documentation, if available.

• Please make sure to install Codezero manpages on your Ubuntu/Debian machine. This is by far the simplest way to quickly read API documentation while programming. For instance, typing:

% man utcb
% man l4_map
% man l4_ipc
% man capability

on the terminal should give quick and detailed reference on these API elements, without need to scroll on the website and reference manual.

• Please refer to Codezero_Reference_Manual.pdf file for complete documentation. This file contains all documentation available on the website and includes notes on manual installation, Codezero architecture, API reference and programming examples.

• To build your project, execute ./build.py script at the root of codezero directory
• Source code is immediately available to be edited under the container project directory, i.e. conts/project0/
• To build-test your container execute conts/project0/scons under this directory.

• To run, please run qemu and insight by executing ./tools/run-qemu-insight script. Inspecting this script should indicate ways to run qemu and insight individually.

Building and running the default installation container should print 'Hello World!' on the terminal screen.

Once the toolkit is installed, Codezero can be build for Pandaboard issuing following command in toolkit's codezero directory:

% ./build.py -f prebuilt/config.cml -b

If everything goes fine, an elf binary, 'final.elf', will be built under 'build/'.

To run Codezero on Pandaboard using a MMC/SDHC card use the following procedure:

• Format the SDHC card using the procedure mentioned here.

• Copy the following files to the fat32 partition of MMC/SDHC card:

% codezero/prebuilt/MLO
% codezero/prebuilt/u-boot.bin
% codezero/build/final.elf

• Plug the MMC/SDHC card into the PandaBoard.
• Connect the UART port of Pandaboard to the host machine.
• Run 'Minicom' on the host machine and connect it to the port where Pandaboard's UART is connected.
• Power ON the Pandaboard.

This will start booting Codezero on Pandaboard and run 'Hello World' container printing 'Hello World'.

PS: QEMU doesnot support OMAP4/Pandaboard as of now.

Codezero developer toolkit provides a complete development environment for baremetal and multithreaded applications.

• One may choose to develop an application from scratch on top of the available Codezero API. This is encouraged for initial understanding of the software.

• conts/examples directory contains example source code projects that are available for reference. These files may be copied under the active project directory, e.g. conts/project0 to make use of example API elements.

• Users are strongly encouraged to port existing 3rd party software to realize maximum potential from Codezero. For example, porting of an existing baremetal GUI stack, driver or RTOS may be ideal ways to build upon Codezero and invest developer time.

Let's consider a scenario where a software stack that acts as an interactive shell is to be ported to Codezero. Let's assume that the shell uses a certain amount of physical memory, requires 3 threads, a synchronization mechanism between threads, and access to UART for input/output. Below are the basic steps that would be required for porting:

1. Read provided container documentation under conts/project0/BUILD.README
2. Read container configuration under conts/project0/configuration
3. Copy software stack sources under conts/project0/
4. Decide on whether to use SCons or Make build tool and either replace or glue to 3rd party build tool from conts/project0/scons
5. Use linker script provided, see readme file listed in (1)
6. Start modifying source code by inserting calls to Codezero API, for example:
   • For thread creation, use man l4_thread_control
   • For synchronization use man l4_mutex_control
   • For mapping physical memory to virtual space, use man l4_map
   • For mapping UART for I/O, use man l4_map, also look for UART device documentation for underlying platform, e.g. QEMU emulated UART device.
   • Check conts/examples directory for example usage of API calls.
7. Build, run and test.

If you plan to develop a userspace software layer or port a baremetal stack on top of Codezero embedded hypervisor, 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.

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.

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.

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.