Adaptation Guide/Step by step

The objective of this phase is to provide a minimal booting image for a device. Initially bring the device up with a kernel to a framebuffer/console (ideally with console or networking) and then to X.

Pre-requisites

• a suitable architecture build of Mer (ie armv7, MIPS, x86 etc)
• a bootloader
• a kernel capable of bringing the device to a framebuffer console
• X drivers (optionally)
• OBS access or platform SDK
• to package a kernel you need spectacle installed.
• to build it locally you need osc or the SDK.
• to make an image you'll need mic2 installed.
• for this simplified guide you will need an account on the Community OBS (see footnote)

Make a kernel package

The Community OBS project we will use is: Mer:Sample:HA (draft in home:lbt:Mer:Sample:HA)

When deciding which kernel version to use bear in mind that closed DRM modules may only be available for certain kernels versions.

• Checkout the sample kernel-adaptation:

 osc co Mer:Sample:HA:kernel-adaptation-sample
 cd Mer:Sample:HA/kernel-adaptation-sample

• Prepare a tarball and patches for your kernel

Note, we're using the name '-sample' here - you shouldn't change this just yet unless you know what you're doing.

Git method (preferred):

• Start with a clone of an upstream kernel
• You should have or create a branch with your patches applied onto a mainline tag location. Eg a branch based at v2.6.32.25 with local patches.

Now to create a tarball, a set of patches and produce a Patches: section for the yaml file.

In the root directory of your kernel git tree create a tarball and patchset using the git2tarball.sh script from the kernel-adaptation package. eg:

/path/to/Mer:Sample:HA/kernel-adaptation-sample/git2tarball.sh /path/to/Mer:Sample:HA/kernel-adaptation-sample 2.6.38.4

The 'version' must correspond to a 'v' kernel tag (eg in this case v2.6.38.4). Then every commit from that tag to HEAD is exported as a patch to the package directory and a Patches: section is printed.

In the Mer:Sample:HA/kernel-adaptation-sample directory, modify the yaml file to include suitable values for Version:, Release: etc. Also include the Patches: section generated by the script. The yaml and spec files contain comments explaining how values are used.

Tarball method:

In the Mer:Sample:HA/kernel-adaptation directory, modify the yaml file to include suitable values for Version:, Release: etc. Also include a Patches: section if you have any patches (see the spectacle page for links to more details).

Copy the kernel tarball to the /path/to/Mer:Sample:HA/kernel-adaptation-sample and ensure that the filename is of the format: kernel-v${VERSION}-src.tar.gz Note that this VERSION string must mach the yaml and the Makefile in the tarball. Also the tarball should unpack the source to a directory such as linux-XYZ/*

Additional patches must be handled manually but can be placed in the yaml file Patches: section.

Both methods; build and/or hack on code:

To update the .spec file you must run:

specify kernel-adaptation-sample.yaml

You can now do a local build by running:

osc build <arch> kernel-adaptation-sample.spec

This will send your .spec file (only) to the server to determine what packages need downloading. It will then create a minimal chroot environment and unpack your src locally. Finally it will run rpmbuild to make an rpm of your kernel.

The <arch> value should be i586, armv7el or armv8el (see the section about arch in Mer for more details).

The build environment is accessed using:

osc chroot <arch> kernel-adaptation-sample.spec

This will tell you where the chroot is located (hint, edit your ~/.oscrc to modify this and note that the build user is 'abuild' and the build happens in /home/abuild/rpmbuild/BUILD/ inside the chroot) - so you can edit files there using your desktop editor. You can then do :

cd rpmbuild/BUILD/kernel/
export ARCH=x86 (or whatever you need - note that this is the *KERNEL* arch specification and is differen to the Mer/OBS arch)
make menuconfig/bzImage/modules/...

It is frequently necessary to revisit this step to change the kernel. The steps are:

1. build an image (coming next)
2. image boots but fails to run properly (missing device driver etc)
3. enter kernel chroot
4. change the config
5. build the kernel
6. copy the kernel to the image built in step 1 to avoid rebuilds
7. go to step 2

When the kernel is satisfactory you MUST COPY THE CONFIG OUT OF THE CHROOT to the /path/to/Mer:Sample:HA/kernel-adaptation-sample or it will be lost because the chroot is modified (sources wiped) every time you do an 'osc build'. See the section about osc chroots for more information.

Having copied the config (and any patches) out of the chroot and put them in the package you can build a clean kernel package.

At this point in a full development deployment you would normally send your changes up to a private OBS/BOSS instance to be built and QA'ed. We'll move on to making an image locally to test the device.

Make a bootloader package (if needed for the image)

For devices that need a bootloader in the same image as the OS, a bootloader package is needed.

The Mer:Sample:HA has an example EFI grub bootloader. It simply contains a tar of the required configuration files and the bootloader binary. The Makefile copies these into the /boot partition created by mic (see the next step)

The bootloader should pass a kernel command line (or this can be set in the CONFIG_CMDLINE kernel configuration) that sets systemd.unit=start.getty

Make an image

This section provides a bare minimum of information to get going; see the mic2 section for more details.

To prepare the bootstrap use:

 mic-create-bootstrap -n trunk -k /var/cache/mic -r http://repo.meego.com/MeeGo/builds/trunk/latest/repos/oss/ia32/packages/ -o /var/cache/meego-bootstrap

The kickstart file for your device needs to prepare a rootfs and setup any needed bootloader. FIXME: Replace this with kickstarter oriented approach

Use the default Mer kickstart as a starting point

mic-image-creator -c mer-core-i586.ks --outdir=images

Typically you'll need to add your kernel HA package and possibly a bootloader package. For devices which need the kernel in a distinct file. mic has an option called --save-kernel which creates a rootfs/kernel pair.

[1]: http://wiki.merproject.org/Image_Creation

Hack image

Once the image boots you should try to login as root using the password "mer"

Boot device and debugging

Hints, tips and tricks:

• The kernel command line: systemd.unit=$SOME.target can be used to specify a specific systemd target. rescue.target should be useful.
• Consider using kernel option "rootwait" if your rootfs device may be slow to appear (eg on a usb stick)
• The evbug module is useful for debugging touch and other keylike events

Prepare X / Wayland and Qt

To install X on a device you'll need to package/install:

• A Rendering Manager (DRM) kernel module for your device
• An Xorg driver for your device
• GL libraries for your device
• Any devel files

The Intel EMGD drivers have been packaged as a sample adaptation. Note:

• The drm module must be built against or compatible with your kernel
• The xorg driver must have an ABI version match to the Mer X server
• The GL libraries should provide ???

When debugging X with this minimal Mer build note that:

• the X log is in /var/log/Xorg.0.log
• when X starts, the program specified in /usr/share/xsessions/default.desktop runs (usually qmlviewer)
• That application logs errors to /home/mer/.xsession-errors

eglinfo and egltest from the mer-gfx-test package may be useful

Extending the image

To extend your image properly you should use the kickstarter approach which allows you to generate kickstart files that inherit from the Mer base image definition (and from other definitions within your organisation).

A quicker but less maintainable approach is to just edit the kickstart file and add more repos and packages.

To make ad-hoc changes on a device use 'zypper ar' and add the url of a suitable .repo file.

Finally you can simply use 'scp' or 'curl -O' to pull in rpm files and then usr 'rpm -i' to install them.

---

Note: Although this method uses the public OBS you do not need to publish your source code or .config file and you won't need to use the C.OBS in a proper product development environment.