Kernel:Kernel & Hardware Services Quick Start

From Symdev

{{#ifeq:{{{visible}}}|true|Get the Symbian kernel building and running on a supported platform.|}}

	Get Started with Symbian Kernel {{#if:Introduction| > Introduction|}}{{#if:Kernel Quick Start| > Kernel Quick Start|}}{{#if:Things to try| > Things to try|}}{{#if:KernelHwSrv Package| > KernelHwSrv Package|}}{{#if:Next steps| > Next steps|}}{{#if:| > {{{6}}}|}}{{#if:| > {{{7}}}|}}{{#if:| >' {{{8}}}|}}{{#if:| > {{{9}}}|}}{{#if:| > {{{10}}}|}}

---

The Kernel & Hardware Services package is the foundation upon which the rest of the platform is built. However, to run the Symbian kernel you need a baseport. That is, a port of the "base" parts of the Symbian platform for the hardware that you want to run it on. For other systems this is more typically known as a Board Support Package (BSP). This term is used in Symbian, but the "Board Support Packages" package is currently rather empty, containing only a soon-to-be-deprecated Windows emulator and some hardware abstraction interface tests.

At the time of releasing the kernel under the EPL we have two open source baseports available to enable wider use and experimentation, and hopefully to facilitate the creation of further baseports. One of the baseports is known as Syborg: It allows you to run ARM binaries for the Symbian platform on the popular QEMU emulator. The other baseport is for the low-cost BeagleBoard development platform with its OMAP3530 processor from Texas Instruments.

In addition to the open source baseports there is also a binary baseport for the Zoom II. It should be available for download from omapzoom.org.

Contents 1 Getting Started 1.1 Get the Tools 1.2 Installing the Kernel Taster Kit 1.3 Set Up the Kernel Taster Environment 1.4 Loading a ROM Image on a Target Platform 2 What Next? 2.1 Building Syborg 2.2 Building BeagleBoard 3 What Next Now? 4 Troubleshooting 5 Summary 6 Build Tool Arguments 6.1 Raptor - sbs 6.2 ROM Builder - rom 7 References & Further Reading

[edit] Getting Started

To get the Symbian kernel building and running on a supported platform, you must follow a common set of steps:

1. Get the tools.
2. Set up the environment.
3. Get the kernel source code.
4. Get the baseport source code.
5. Build the baseport.
6. Create a ROM image.
7. Load the ROM image on the target platform.

To help you get started faster we have created a Kernel Taster Kit, which has most of step 2 and steps 3-6 already done for you. It includes source, pre-built binaries and ROM images for both QEMU/Syborg and BeagleBoard baseports.

The instructions below assume that you are using Microsoft Windows (XP or Vista - possibly even Windows 7). It is possible to build and run Symbian code on Linux, but that requires a little more effort - see these forum posts.

[edit] Get the Tools

To build Symbian platform code and baseports you must install:

• A supported compiler:
  • ARM RVCT 2.2. The officially supported compiler for use with the platform.
  • ARM RVCT 4.0. A free version is available for use with Symbian (installation instructions here).
  • Note: GCCE support is work in progress.

• A Product Development Toolkit (PDT) and its Perl and Python dependencies (installation instructions here).
  • Note: If using RVCT 4.0 you'll need PDT 1.3 or later.

• A 7-zip compatible zip utility. We use a release from http://www.7-zip.org/, although a recent of Winzip (http://www.winzip.com/) will also work.

[edit] Installing the Kernel Taster Kit

The latest Kernel Taster Kit (KTK) is a preview to Symbian^4 (S^4) ahead of full Product Development Kits (PDK’s) to be released in Q3 2010. The aim of this kit is to allow the community early access to S^4 allowing them to get started, experiment and integrate with hardware.

The S^4 Kernel Taster Kit includes the source for a product quality SMP kernel which OEMs and silicon vendors can begin to use with their SMP enabled hardware to port or develop drivers and adaptation software. It can be downloaded from here.

After downloading the KTK, open a command prompt, create a new folder (in the example below I call it Symbian_Kernel_Taster) and subst(itute) it with a drive letter (X: in the example): C:\>mkdir Symbian_Kernel_Taster C:\>subst X: Symbian_Kernel_Taster

Leave the command box open. (In Windows Explorer) Unzip the Kernel Taster Kit into the root of the subst'ed drive. You can use a tool like WinZip or 7-zip to extract the .7z file.

[edit] Set Up the Kernel Taster Environment

In your command prompt, set the following environment variables: C:\>set EPOCROOT=\ C:\>set path=\epoc32\tools;\epoc32\gcc\bin;%path% These let the tools know where find the code and other tools. We use paths without a drive letter; this means that we have to run all commands that access Symbian tools from the subst'ed drive.

[edit] Loading a ROM Image on a Target Platform

The Kernel Taster Kit comes with debug and release ROM images for Syborg and the BeagleBoard. They can be found in \epoc32\rom. It also includes pre-built Windows binaries for the QEMU simulator.

To run the Syborg ROM image on QEMU, enter the following in your command prompt (changing the drive letter as necessary): C:\>X: X:\>cd \qemu\bin x:\qemu\bin>qemu-system-arm -M \sf\adaptation\qemu\baseport\syborg\syborg.dtb -kernel \epoc32\rom\syborg_tshell_ARMV5_udeb.img If everything is set up correctly, a QEMU window with a Symbian text shell should pop-up - looking something like this:

For more details about using QEMU and Syborg with Symbian, try this wiki page and for debugging instructions this one.

If you've got a BeagleBoard (or are willing to buy one) and want to run the BeagleBoard ROM image then follow the instructions in this article.

[edit] What Next?

Before going any further, you should validate your environment by rebuilding the Syborg baseport, re-creating the ROM and making sure you can still run it. Optionally, if you have a BeagleBoard, you may also want to rebuild the BeagleBoard baseport and ROM.

[edit] Building Syborg

Close your current QEMU window (if it's still running) and issue these commands from your command prompt:

<toggledisplay status="show" showtext="[Show RVCT4.0 instructions (debug)]" hidetext="[Hide RVCT4.0 instructions (debug)]"> X:\qemu\bin>cd \sf\adaptation\qemu X:\sf\adaptation\qemu>sbs -s package_definition_2.0.1.xml -c arm.v5.udeb.rvct4_0 -k -j 4 </toggledisplay> <toggledisplay showtext="[Show RVCT4.0 instructions (release)]" hidetext="[Hide RVCT4.0 instructions (release)]"> X:\qemu\bin>cd \sf\adaptation\qemu X:\sf\adaptation\qemu>sbs -s package_definition_2.0.1.xml -c arm.v5.urel.rvct4_0 -k -j 4 </toggledisplay> <toggledisplay showtext="[Show RVCT2.2 instructions (debug)]" hidetext="[Hide RVCT2.2 instructions (debug)]"> X:\qemu\bin>cd \sf\adaptation\qemu X:\sf\adaptation\qemu>sbs -s package_definition_2.0.1.xml -c arm.v5.udeb.rvct2_2 -k -j 4 </toggledisplay> <toggledisplay showtext="[Show RVCT2.2 instructions (release)]" hidetext="[Hide RVCT2.2 instructions (release)]"> X:\qemu\bin>cd \sf\adaptation\qemu X:\sf\adaptation\qemu>sbs -s package_definition_2.0.1.xml -c arm.v5.urel.rvct2_2 -k -j 4 </toggledisplay>

This changes to the root directory of the QEMU package, which contains the Syborg baseport, and builds either a debug or release version of it with SBSv2 (aka Raptor) using the specified compiler. Depending on your PC it should take a little over three minutes to complete with zero errors and 34 warnings. For more information on the sbs command and it's parameters please see the sbs tool reference.

The above command/s will generate a debug or release ROM image in \epoc32\rom as either syborg_tshell_ARMV5_udeb.img or syborg_tshell_ARMV5_urel.img respectively and assuming the ROM is generated without errors you can now repeat the steps from the previous section to run the image on QEMU. <toggledisplay showtext="[Show Syborg ROM generation details]" hidetext="[Hide Syborg ROM generation details]"> To build the Syborg ROM image manually use these commands: X:\sf\adaptation\qemu>cd \sf\os\kernelhwsrv\kernel\eka\rombuild X:\sf\os\kernelhwsrv\kernel\eka\rombuild>rom --variant=syborg --inst=armv5 --build=udeb --type=tshell --name=\epoc32\rom\syborg_tshell_ARMV5_udeb.img This changes to the directory where the rom building tools are located and then creates a Syborg ROM. For information on the parameters please see the ROM argument reference. </toggledisplay>

[edit] Building BeagleBoard

To rebuild the BeagleBoard baseport and generate a ROM, use these commands:

<toggledisplay status="show" showtext="[Show RVCT4.0 instructions (debug)]" hidetext="[Hide RVCT4.0 instructions (debug)]"> X:\qemu\bin>cd \sf\adaptation\beagleboard X:\sf\adaptation\beagleboard>sbs -s package_definition_2.0.1.xml -c arm.v5.udeb.rvct4_0 -k -j 4 </toggledisplay> <toggledisplay showtext="[Show RVCT4.0 instructions (release)]" hidetext="[Hide RVCT4.0 instructions (release)]"> X:\qemu\bin>cd \sf\adaptation\beagleboard X:\sf\adaptation\beagleboard>sbs -s package_definition_2.0.1.xml -c arm.v5.urel.rvct4_0 -k -j 4 </toggledisplay> <toggledisplay showtext="[Show RVCT2.2 instructions (debug)]" hidetext="[Hide RVCT2.2 instructions (debug)]"> X:\qemu\bin>cd \sf\adaptation\beagleboard X:\sf\adaptation\beagleboard>sbs -s package_definition_2.0.1.xml -c arm.v5.udeb.rvct2_2 -k -j 4 </toggledisplay> <toggledisplay showtext="[Show RVCT2.2 instructions (release)]" hidetext="[Hide RVCT2.2 instructions (release)]"> X:\qemu\bin>cd \sf\adaptation\beagleboard X:\sf\adaptation\beagleboard>sbs -s package_definition_2.0.1.xml -c arm.v5.urel.rvct2_2 -k -j 4 </toggledisplay> This changes to the root directory of the Beagleboard package, which contains the Beagleboard baseport, and builds either a debug or release version of it with SBSv2 (aka Raptor) using the specified compiler. For more information on the sbs command and it's parameters please see the sbs tool reference.

The above command/s will generate a debug or release ROM image in \epoc32\rom as either beagleboard_tshell_ARMV5_udeb.img or beagleboard_tshell_ARMV5_urel.img respectively. <toggledisplay showtext="[Show Beagleboard ROM generation details]" hidetext="[Hide Beagleboard ROM generation details]"> To build the Beagleboard ROM image manually use these commands: X:\sf\adaptation\beagleboard>cd \sf\os\kernelhwsrv\kernel\eka\rombuild X:\sf\os\kernelhwsrv\kernel\eka\rombuild>rom --variant=beagle --inst=armv5 --build=udeb --name=\epoc32\rom\beagle_tshell_ARMV5_udeb.img This changes to the directory where the rom building tools are located and then creates a Beagleboard ROM. For information on the parameters please see the ROM argument reference. </toggledisplay>

[edit] What Next Now?

Now that you have proven that you can rebuild and run your ROM you can begin exploring and modifying source on your own. Here is a simple starting point: Kernel & Hardware Services - Things To Try.

[edit] Troubleshooting

Having problems getting started? Common problems and their solutions can be found on this page, please leave comments about your specific problems (rather than errors in the instructions) there.

[edit] Summary

If you've worked through this article and the linked instructions you should have a working environment for experimenting with the Symbian kernel and the supplied baseports. You should be able to build the open source baseports and generate ROM images.

What next? Well, here are some things to try.

[edit] Build Tool Arguments

There are two main tools mentioned previously that are used to build a ROM from the KTK, sbs and rom. With the intention of keeping the quick start guide lightweight and concise we've collected the command arguments that are shared between the Syborg and Beagleboard ROMs and their described use down here so we can keep their associated sections short, so you can get up and running quickly.

[edit] Raptor - sbs

Example: sbs -s package_definition_2.0.1.xml -c arm.v5.udeb.rvct4_0 -k -j 4

This starts a Symbian build. In the above example the parameters are:

• -s specifies the package definition to use. The package definition file tells Raptor what needs building.
• -c specifies the build configuration to use. In this case, build a debug release (udeb) for arm v5 architecture (arm.v5) using the RVCT4.0 compiler (rvct4_0). Multiple -c options can be specified.
• -k tells Raptor to keep going if it encounters any errors.
• -j specifies how many compilations to perform in parallel. The number 4 was selected to ensure maximum utilisation of a typical dual-core system. It should work fine if you only have a single core.

For help on the other options use: sbs --help.

[edit] ROM Builder - rom

Example: rom --variant=syborg --inst=armv5 --build=udeb --type=tshell --name=\epoc32\rom\syborg_tshell_ARMV5_udeb.img

This command needs to be run from the \sf\os\kernelhwsrv\kernel\eka\rombuild directory. The above example creates a Syborg ROM. The parameters used are:

• --variant identifies a folder in \epoc32\rom which contains IBY files specifying the target-specific binaries to be included in the ROM
• --inst identifies the target architecture
• --build determines whether debug or release binaries are to be used
• --type=tshell selects the tshell.oby file from the current directory which then specifies the names of the IBY files to get from the variant directory and the remaining IBY files required to define a standard text shell ROM
• --name specifies the output image file name

For more help on the commands see the output of rom --help, the Guide to using ROM.bat or the ROM Building Guide.

[edit] References & Further Reading

• Kernel & Hardware Services package landing page
• Kernel & Hardware Services Guide in the Symbian Developer Library for Product Developers
• Complete version of the Symbian OS Internals book
• Base Porting Quick Start
• BeagleBoard Quick Start
• Guide to using ROM.bat - for creating text shell ROMs, as in this article.
• ROM Building Guide - for creating more complex ROMs than a text shell!
• More information on Syborg & QEMU
• Debugging Symbian code on QEMU