The goal of MeeGo Porting Guide (MPG) is to provide valuable information and instructions to people who want to run MeeGo OS on their (new) HW and eventually create products based on the MeeGo OS. The MPG starts with an overview of the porting process, tools and other related background information and then moves on to describing what the porting actually means in individual technical/functional areas.
The porting guide is not strictly tied to any particular MeeGo OS version or device category. Instead it tries to be general enough to cover the different device categories as well as follow changes introduced in new MeeGo OS versions.
Detailed porting information in the different technical areas is dependent on the respective MeeGo architecture. In some cases, this architecture may still be open and this is noted in the applicable sections.
Contribution to these pages is open. Any MeeGo community member is free to improve these pages at any time. You can also leave feedback in the MeeGo porting mailing list.
Perhaps the most important piece of background information related to the MPG are the MeeGo compliance requirements. A device that is meant to be MeeGo compliant will need to fulfill the requirements listed in the MeeGo compliance specification for the applicable device category (the first version of the specification is supposed to be available in October 2010). In short, a MeeGo compliant device will need to:
The compliance rules will also specify CPU architecture specific requirements concerning how MeeGo OS itself and MeeGo applications are to be compiled to different environments (instruction set used, compiler version, compiler options etc.).
A device vendor may include additional functionality, HW components and SW components in their devices as long as they don't break MeeGo compliance. The vendor can also patch MeeGo OS components if the patches don't break MeeGo compliance. A device vendor's own SW components can be either open source or closed source components as long as they adhere to the rules set by the applicable SW licenses.
From the MeeGo Porting Guide perspective, the compliance requirements - by defining the SW components and HW components that need to be present - effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.
As long as some vendor's device is MeeGo compliant as defined above, it is basically up to the vendor to decide how they build the SW that ends up in the device. The vendor may use their own build machinery or setup an OBS build system that is used also in MeeGo. Regardless of what the vendor's build system is, it needs to integrate with the MeeGo build infrastructure at least to fetch the MeeGo source packages for the builds as well as build each MeeGo component in the same way as it would be built in the MeeGo build system (e.g. with the same compiler and compiler options). Whatever the case, the intention in MeeGo is to use and offer an open toolset that any HW or SW vendor can use for efficient SW creation. It is likely that using the same toolset as MeeGo will offer the easiest way to integrate vendor's own build system with the the MeeGo build infrastructure.
The key ingredients of the MeeGo build infrastructure and toolset are:
For additional information, see Build Infrastructure, Release Infrastructure and Release Engineering.
For another overview of the MeeGo porting process, see Hardware Enabling Process.
So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. An own OBS system may also be beneficial in earlier HW/product development phases as it offers a flexible way to modify and build MeeGo OS to test it on the new HW. The vendor's own OBS system can link to the MeeGo OBS for handling packages that come directly from MeeGo and it an link to other sources for handling e.g. closed source packages that are specific to the vendor. An overview picture of this setup can be found from here.
In this setup, the vendor:
Another way of porting MeeGo to some new HW is to get the new HW accepted as one MeeGo reference HW and have the MeeGo build machinery create builds for the reference HW as a part of the normal MeeGo release building cycle (see Release Timeline and Release Process). This setup can also include QA support for the reference HW on the MeeGo side (see Quality). At the time of this writing, the actual process of getting new reference HW to MeeGo is still somewhat unclear. In any case, this model requires active participation from the vendor in MeeGo work in general and especially in supporting their reference HW in MeeGo.
In this setup, the vendor:
A lightweight but also more limited "try it out" alternative to the above processes is discussed below.
The second step to a proper hardware adaptation is making sure you can build your own image. Since we based our work before on a reference device image, it makes sense to try to build this image first. MeeGo images are constructed on the basis of so called 'kickstart files' which describe the intended contents of a image.
A detailed description of a variation of this model can be found from here (Better description needed).
See How-to: getting new chipset support to the MeeGo kernel for more detailed information about how to work with the MeeGo kernel and make it support new HW.
When building a product based on MeeGo, the product vendor will typically augment the MeeGo OS with their own SW components as well as make fixes and adjustments to the MeeGo OS code (in the limits set by the compliance rules). While vendors can manage their own SW components as they wish, the strong preference is that any changes made to the MeeGo OS SW components are delivered as patches primarily to the respective upstream projects or secondarily to MeeGo.com. In this way vendors can relieve themselves from the burden of managing a potentially big patch set on top of MeeGo OS and also verify the quality and safety of their patches. Having the patches in upstream projects again lessens the patch set management load at MeeGo.com.
For information about pushing patches to MeeGo, see Contribution Guidelines and Hardware Enabling Process (especially section How Do Patches Get Integrated and Accepted?) and Kernel workflow.
In the MeeGo architecture model (see e.g. MeeGo Architecture Domain View), adaptation is represented as adaptation subsystems. SW components in the adaptation subsystem realizations do things that are expected by the OS and communicate with the OS through interfaces defined by the OS.
The key goal in the sections below is to identify the interface(s) that the adaptation SW needs to implement/use in order to communicate with the OS in the required manner. Behind these interfaces the adaptation SW can basically handle the required functionality as it sees best. In some cases, however, there may also be some preferred way of implementing the adaptation.
In some areas, the adaptation work may consist of just writing a suitable Linux device driver for the HW in question. In some other areas, the adaptation work may consist of writing one or more device drivers as well as one or more user space components (e.g. plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.
MeeGo places no restrictions as to what SW components are used to handle the pre-OS boot phases in a MeeGo compliant device. Thus, vendors are free to choose e.g. the boot loader as they see fit. Note however that full utilization of the MeeGo platform security requires that the pre-OS boot phases form a trusted boot chain that ultimately builds on chipset-level security support.
At the time of this writing, MeeGo does not define anything special with regard to what information the boot loader is expected to pass to the Linux kernel e.g. via the kernel command line.
The kernel-level boot phases can be tailored as necessary to the specific CPU, chipset or device in a standard Linux manner.
The post-kernel boot phases (startup scripts) can be tailored by device vendors as necessary for their devices in the limits set by MeeGo compliance requirements (certain SW components need to be present in the system).
Regarding the Linux kernel, each MeeGo release defines the kernel version to be used and a set of patches on top of that. In addition, the Linux kernel used in MeeGo compliant devices is assumed to have been built with a set of fixed build-time configuration values that are not allowed to be changed. In addition to the fixed values, device vendors can define other kernel configuration values as required by their devices.
MeeGo does not place any special requirements concerning how the boot loader passes information to the kernel or how the HW configuration and initialization of the system is handled.
CPU, chipset (SoC) and device vendors are assumed to implement the elementary CPU architecture/chipset/device support for the Linux kernel used in MeeGo in a standard Linux manner. This includes:
At the time of this writing, the understanding is that MeeGo in general relies on established Linux kernel frameworks and APIs for power management. Some of these frameworks and APIs may be applicable only in certain CPU architectures. In addition, the HW capabilities related to power management may vary between different HW platforms potentially meaning that the SW is assumed perform somewhat different tasks in different environments.
The Linux power management frameworks and APIs include:
Whether MeeGo will have some user space SW components or framework related to power management is under discussion at the time of this writing.
In the thermal management area, the Device State Management Entity (DSME) component in the Device Health subsystem is supposed to make thermal state management decisions in the system. The DSME has a thermal manager module that again uses other DSME modules (thermal objects) to access the actual thermal sensor information in the HW. To port this functionality to new HW, one or more DSME thermal object modules need to be implemented.
The APIs that the thermal object modules use to access the thermal sensor information are not strictly defined by MeeGo. At device driver level, however, the preferred approach is to utilize standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.
At the time of this writing, basically the only thing that MeeGo requires from HW adaptation in the energy management area (battery charging and monitoring) is support for the Linux power supply sysfs class. Additional energy management related functionality can be handled in a vendor specific manner.
The DSME component participates in device state management e.g. by managing device run level, reboot and shutdown, by monitoring the device thermal state and shutting down the device in fatal thermal conditions, and by handling HW watchdog kicking activity.
In a new HW environment, the DSME needs to be adapted to handle the watchdog kicking through the right device driver interfaces and at the right intervals. In addition, to port the DSME thermal management functionality to new HW, one or more DSME thermal object modules need to be implemented as described above in the Power and thermal management section.
Work is ongoing in bringing platform security functionality to the MeeGo OS based on the Mandatory Access Control (MAC), Integrity Measurement Architecture (IMA) and Extended Verification Module (EVM) technologies in the Linux kernel. Maximum security can be reached if the MeeGo platform security functionality can rely on trusted platform support "below" the Linux kernel, effectively in the HW and the boot loader(s). MeeGo, however, places no strict requirements as to how the trusted platform support is implemented in MeeGo based devices.
MeeGo also includes the OpenSSL open source toolkit implementing general purpose cryptography functionality. Algorithms and operations supported by the OpenSSL toolkit can be accelerated in HW by using the OpenSSL engine architecture. OpenSSL also supports a cryptodev engine that uses crypto algorithms implemented in the Linux kernel.
Some devices may have a security watchdog in the HW that needs "kicking" at regular intervals to keep the device up and running. In MeeGo, watchdog kicking functionality is implemented in the Device State Management Entity (DSME) component. If security watchdog kicking is needed, the DSME needs to be adapted to handle that through the right device driver interface and at the right intervals.
The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
The Resource Manager can be used e.g. to change the audio routing in the device when the user attaches a wired headset to the device.
Event listening and change enforcement in the Resource Manager happens through plugin modules. Using the MeeGo OS in some new device effectively involves creating suitable Resource Manager policies and writing the necessary plugins for listening device/application events and changing device behavior accordingly. Though not pure HW adaptation, this can be considered as a form of MeeGo OS "device adaptation".
The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (e.g. touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used e.g. for:
The MCE has its own plugin architecture that can be used to adapt it to different HW environments.
For an overview of the MeeGo visual services architecture, see the MeeGo architecture domain view.
The key ingredients of the display and graphics architecture in MeeGo are the X Window System (X Server with its extensions) and the Khronos graphics APIs (OpenGL ES, OpenVG and EGL with their extensions).
The display and graphics HW adaptation SW needs to enable the X Window System and the Khronos APIs to function on the device HW. In practice, the adaptation SW needs to have an X display/video driver (hosted inside the X Server) and libraries that implement the Khronos graphics APIs, both supporting the features and functionality required by MeeGo. Also some configuration file changes may be needed. Any additional user space and kernel space components needed for the HW adaptation are implementation dependent.
If the device supports delivering display content to external displays, the Resource Manager component may be used to coordinate the display routing related behavior of the device.
The audio architecture in MeeGo is centered around the GStreamer and PulseAudio frameworks. In addition, the Resource Manager plays a role in coordinating the audio related behavior of the device (audio routings). The audio HW adaptation SW needs to provide GStreamer elements and PulseAudio plugins that enable the GStreamer and PulseAudio client interfaces used for e.g. for audio playback, recording and volume control to work on the device. Typical required components include e.g. codec elements for GStreamer and sink/source plugins for PulseAudio.
Behind the GStreamer and PulseAudio plugins, the audio HW adaptation SW can be implemented with different technologies and APIs, including ALSA and OpenMAX. In case OpenMAX components are used, the gst-omx package must be used to offer those to the GStreamer framework as needed. Use of the ALSA framework and APIs is encouraged, however, as they allow significant reuse of components and functionality on the PulseAudio level and are already a part of the upstream Linux kernel. If ALSA is not used to implement the kernel side parts of the audio adaptation, the solution that is used instead should still be aligned with the upstream Linux kernel.
For an overview of the MeeGo media services architecture, see the MeeGo architecture domain view.
The central pieces of the MeeGo still imaging architecture are the GStreamer multimedia framework and the CameraBin GStreamer element. The still imaging HW adaptation SW is required to contain a GStreamer camera source element to be used "inside" the CameraBin element. Thus, the required HW adaptation interfaces are the relevant GStreamer plugin interfaces and especially the interfaces expected by the CameraBin element, in particular the GstPhotography interface.
If HW accelerated encoders are supported, they should be also offered to the system as GStreamer elements.
Behind the GStreamer elements, the HW adaptation SW can be implemented with different technologies and APIs, including V4L2 and OpenMAX. In case OpenMAX components are used, the gst-omx package must be used to offer those to the GStreamer framework.
The central pieces of the MeeGo video imaging architecture are the GStreamer multimedia framework, the CameraBin GStreamer element (video recording) and the Playbin2 GStreamer element (video playback). The video imaging HW adaptation SW is required to contain:
Behind the GStreamer elements, the video imaging HW adaptation SW can be implemented with different technologies and APIs, including V4L2 and OpenMAX. In case OpenMAX components are used, the gst-omx package must be used to offer those to the GStreamer framework.
If the device supports delivering video content to external displays, the Resource Manager component may be used to coordinate the video/display routing related behavior of the device.
For an overview of the MeeGo communications services architecture, see Comms Services.
The cellular telephony architecture in MeeGo is centered on the oFono, PulseAudio and Telepathy frameworks. In addition, the Resource Manager plays a role in coordinating the device behavior during voice calls.
The cellular modem HW adaptation SW must implement the following interfaces towards the MeeGo OS:
For more detailed information about the oFono APIs, see the documentation and source code available at oFono git.
The foundation of the the MeeGo USB functionality is the standard Linux USB subsystem. The Linux USB subsystem defines the USB related HW adaptation interfaces that need to be supported in MeeGo. In practice, these are kernel side interfaces between the generic USB functionality and a HW dependent USB host controller driver.
The MeeGo WLAN architecture is centered on the Linux wireless (IEEE-802.11) subsystem. The Linux wireless SW stack defines the WLAN HW adaptation SW interfaces that need to be used in MeeGo. In practice, the required interfaces are defined by cfg80211 for FullMAC WLAN devices and by mac80211 for SoftMAC WLAN devices. In addition, a Linux network interface needs to be supported towards the Linux TCP/IP stack.
The MeeGo Bluetooth architecture is centered on the BlueZ SW stack. The BlueZ SW stack defines the Bluetooth HW adaptation SW interfaces that need to be used in MeeGo. In practice, these are Linux kernel side interfaces between the generic HCI (Host Controller Interface) core and a HW specific HCI driver.
The MeeGo location architecture is based on QtMobility Location API. The QtMobility 1.0 Location API provides geographic coordinates only. The QtMobility 1.1 Location API provides geocoding and reverse geocoding, POI search, navigation, and mapping. The 1.0 Location API is available in MeeGo 1.1. The 1.1 or later Location API will be available in MeeGo 1.2. The Location API uses a plugin system for implementations of the underlying backend. MeeGo compliance requirements require support for the QtMobility Location API and thus require one or more plugins to support these APIs. MeeGo places no restrictions as to how the plugins are implemented, however. Adaptation to location related HW may be done by manufacturers or service providers and the way how it's done is not defined by the API.
MeeGo will use GeoClue as the reference location framework and the reference implementation of the Qt Mobility location API backend will be written on top of GeoClue. GeoClue defines a set of (D-Bus) APIs for accessing location services provided by service providers implemented as D-Bus services. In addition, GeoClue includes a set of service provider implementations and (at the time of this writing) an experimental master service provider that can act as a proxy between clients and the actual service providers. If a device vendor wants to take advantage of this existing functionality, the vendor can implement their location services "behind" the GeoClue APIs as GeoClue service providers. In such a case, adaptation to the location related HW would happen inside the service providers as defined by the service provider designs.
The key component in the MeeGo sensor handling architecture is the Sensor Framework. The Sensor Framework uses both HW independent logical sensor plugins and HW dependent sensor adaptor plugins in its operation. The required sensor HW adaptation interfaces in MeeGo are the interfaces that the Sensor Framework and the logical sensor plugins define for the sensor adaptor plugins to implement. The sensor adaptor plugins typically communicate directly with sensor HW drivers in the Linux kernel. The interfaces that the sensor HW drivers expose to the user space are not defined by MeeGo. Sensor HW adaptation in MeeGo thus consists of adaptor plugins in the Sensor Framework and sensor HW drivers in the Linux kernel.
Note that thermal sensors are handled in a different manner as described in the Power and thermal management section above.
The key SW components on the touch input handling path in MeeGo are the touch HW device driver, Linux kernel input subsystem, X server, X input driver, Qt and finally the MeeGo Touch Framework. Enabling touch support for some new HW requires at least the implementation of the corresponding touch HW device driver in the Linux kernel. If this driver communicates touch events to the user space in a "standard" manner via the Linux kernel input subsystem, basically the existing functionality in X server (e.g. evdev input driver) and above can be used as such. In case the kernel-to-user-space interface is non-standard, it is also possible to implement a new X input driver as a part of the touch HW adaptation.
Multi-touch support in X requires a new version, 2.1, of the X Input Extension and this also requires support from the client side, in this case Qt's multi-touch support. Once this support has been implemented throughout the SW stack, including X evdev input driver, supporting multi-touch for some new HW should require only the implementation of a touch HW device driver that implements the standard Linux multi-touch interface. This should be the case in MeeGo 1.2.
Before 1.2, multi-touch support in MeeGo uses a special X input driver (mtev), X server multi-pointer support (MPX) and Qt multi-touch support written on top of MPX. This solution requires the touch HW device driver to expose a user-space interface that is compatible with mtev.
The key SW components on the HW keyboard input handling path in MeeGo are the keyboard HW device driver, Linux kernel input subsystem, X server, X input driver and Qt. Enabling keyboard support for some new HW requires typically only the implementation of the corresponding keyboard HW device driver in the Linux kernel. If this driver communicates key events to the user space in a "standard" manner via the Linux kernel input subsystem, the existing functionality in X server (e.g. evdev input driver) and above should work as such. In case the kernel-to-user space interface is non-standard, it is also possible to implement a new X input driver as a part of the keyboard HW adaptation.
Starting from version 1.2, MeeGo includes the MCE and System SW Qt API (QmSystem) components. The MCE can be used to control the device mode and it listens to power button events and e.g. device open/close switch events via the respective device driver interfaces. The System SW Qt API on the other hand provides a Qt API to various system information, including events from various physical buttons in the device (e.g. volume button, camera button). The System SW Qt API gets the button events either by listening to the relevant device driver interfaces or through the MCE component.
Both the MCE and the System SW Qt API components can be adapted to new devices by device vendors.
The MeeGo Touch Framework present (at least) in the MeeGo handset device category contains a component called Feedback Framework (meegotouch-feedback) that handles the creation of auditory and/or haptic feedback to touch events. The haptic feedback can be created e.g. with vibra motors or piezo elements. In the Feedback Framework, the different types of feedback are created by backend libraries implemented as plugins.
The haptics related HW adaptation interface from MeeGo OS perspective is the backend plugin interface defined by the Feedback Framework. The plugins can then communicate with the HW either through some device driver interface or some intermediate SW layers (MeeGo places no restrictions as to how the plugins are implemented).
Starting from version 1.2, MeeGo (at least the handset category) will include a component called Non-Graphical Feedback Framework (NGF). This component offers the capability of playing e.g. audio, vibra or led as an indication of events such as incoming call/message, clock and calendar alarms, missed calls, unread messages etc. The NGF also integrates with the Resource Policy to decide about the available playback resources based on policy rules and the current system state.
The actual playback of the different types of notifications is handled by NGF plugins that can be created by device vendors. The plugins communicate with the relevant HW as they see best, e.g. directly through some device driver interface or via some intermediate user space SW components. The plugin interfaces defined by NGF thus form the notification/alert vibra adaptation interface in MeeGo.
Production deals with areas such as flashing, testing, tuning and certification. The current understanding is that these areas are handled in a vendor specific manner, including the adaptation.