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

device suitable with one of the Mer architectures. See: OBS_architecture_naming
Platform_SDK installed and preferribly updated.
a bootloader for your device
a kernel capable of bringing the device to a framebuffer console
X drivers (optional)
for this simplified guide you will need an account on the Community OBS

Make a kernel package

First setup the osc. See Osc_Setup guide.

After the osc is setup properly, create a home project for the adaptation in the selected OBS. Check the OBS_architecture_naming for the repository naming. Below is an example of creating a project, note that you need to change some values to match your own case:

cat >> my_new_project.conf << EOF
<project name="home:user:subproject">
  <repository name="latest_ARCH">
    <path repository="Core_ARCH" project="Mer:fake:Core:ARCH"/>
    <arch>SCHEDULER_ARCH</arch>
  </repository>
</project>
EOF
osc meta prj home:user:subproject -F my_new_project.conf

After project is done we create a package for the kernel package to just created project

osc meta pkg home:user:subproject kernel-adaptation-sample -e

This command opens a text editor where you need to change something (remove one empty line for example) and the exit to create the package.

Then check out the package

osc co home:user:subproject kernel-adaptation-sample
cd home:user:subproject/kernel-adaptation-sample

Next thing is to get the adaptation template

git clone https://github.com/lbt/mer-kernel-adaptation.git
cp mer-kernel-adaptation/* .

After this we have the very basic structure and files for the kernel packaging.

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

Next you should select either git method (A) or tarball method (B) to for the sources.

A: 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.

B: Tarball method

In your package 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 directory with the other files and ensure that the first source filename format matches to the tarball. One can use macros like %{name} and %{version} that will match to the Name and Version fields. 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/*

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 latest_ARCH SCHEDULER_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 match to the architectures determined earlier when creating the project.

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 different to the Mer/OBS arch)
make menuconfig/bzImage/modules/...

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

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

When the kernel is satisfactory you MUST COPY THE CONFIG OUT OF THE CHROOT to the kernel-adaptation-sample.config file in the packging directory or as 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

Booting any random ARM device you typically have u-boot as boot-loader, some guidance on setting up u-boot for graceful boot experience in...

u-boot adaptation guide

Make graphics adaptation package (recommended)

For Mer there are certain binaries that are expected to be present when accelerated graphics are expected. For this there is a template packaging available at https://github.com/saukko/mer-graphics-adaptation that can be used as and base for graphics adaptation packaging.

Do note that usually the OpenGL ES applications should be built against the Mer core and not against Hardware Adaptation specific development packages. The graphics adaptation packages should provide /usr/lib/libGLESv2.so.2 and /usr/lib/libEGL.so.1 and all their dependency packages.

For video decoding Mer Core supports GStreamer and for the best compatibility with the existing applications the graphics adaption should provide hardware accelerated audio and video decoders and encoders for GStreamer.

X.Org

For video rendering in X.Org based environment the de-facto API is X.Org's XVideo extension and that should be implemented by the hardware vendor. GStreamer in Mer Core already provides an open source XV sink that can use hardware accelerated rendering, if X.Org XV is supported by the graphics adaptation.

For good graphical performance in X.Org based environment, the graphics adaption must provide X.Org graphics driver that enables hardware accelerated drawing operations (blitting, blending, etc).

Wayland

TODO: Requirements for Wayland based environment?

Peripherals

Most of the peripherals should work with out of the box if they are using the de-facto APIs and the Hardware Adaptation provides any needed firmware binaries. De-facto APIs and the Mer Core packages using them are listed below.

Battery

Kernel API: power supply
Mer Core packages: contextkit-plugin-upower

WiFi

Kernel API: 802.11 wireless
Mer Core packages: @Mer Connectivity
Configuration: Hardware specific firmware may be required in /lib/firmware/

Bluetooth

Kernel API: ?
Mer Core packages: ?

GPS

Kernel API: ?
Mer Core packages: ?

Display

Kernel API: Framebuffer
Mer Core packages: @Mer Xorg enablement (for X.Org)
Configuration: Hardware specific drivers for X.Org in /usr/lib/xorg/modules/drivers/ and corresponding X.Org configuration file in /etc/X11/xorg.conf.d/

Touchscreen

Kernel API: evdev
Mer Core packages: @Mer Xorg enablement (for X.Org)
Configuration: X.Org should detect evdev based touchscreen automatically

TODO: list other Kernel APIs and their corresponding X.Org drivers?

Audio

Kernel API: alsa
Mer Core packages: @Mer Base System, optionally alsa-utils
Configuration: Optionally provide asound.state and startup scripts to store/restore settings on shutdown/boot.

Hardware keys

Kernel API: evdev
Mer Core packages: ?
Configuration: ?

Power management

TODO

Sensors

Make sure /etc/board has the board name (boardname should return a correct name).
Provide sensorfw config for the board in /etc/sensorfw/

Make an image

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

The kickstart file for your device needs to prepare a rootfs and setup any needed bootloader.

First install the configs for creating the .ks files.

sudo zypper install mer-kickstarter-configs

Then create the example kickstarts. Ref: default Mer kickstart

mer-kickstarter -c /usr/share/kickstarter-configs/mer-reference-images/00reference.yaml -o reference-kickstarts/

Next thing is to take one of the reference kickstarts and add your own adaptation to it. This can be done by adding following lines repo that contains the path to the repository where packages are. All the packages for the adaptation are put under the %packages section, e.g., kernel-adaptation-<my_adaptation>, bootloader-xyz etc.

After you have modified the .ks for your needs, we can build the image. See Category:Mic for more detailed information.

mic cr raw reference-kickstarts/mer-core-i586-xorg-basic-qmlviewer.ks --arch=i586 --outdir=images

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/wiki/Image_Creation

Flashing your device

If your device uses SD or mmc or another block device then you can just create an image and write it.

If you use NAND flash / mtd then you'll need to make a rootfs and use a suitable tool to make a filesystem image.

Hack image

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

If you are missing a login prompt do the following inside the target rootfs from the / level.

ln -s  ../serial-getty@.service ./lib/systemd/system/getty.target.wants/serial-getty@tty<xx>.service.

Set <xx> to suit your device eg S0, mxc0 etc

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-tests package may be useful

Higher level features

something for video, sound, networking and similar

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.

Adaptation Guide/Step by step

Contents