MeeGo wiki - User contributions [en]

UMMS Architecture

2012-04-23T01:07:23Z

Noel: /* How to develop a backend */

= UMMS Architecture =

== Introduction ==
This page describes the architecture of umms-0.1. You can get the code from: git://gitorious.org:meego-middleware/umms.git 
The UMMS general description can found on the '''[[Umms|main page]]'''

== Class Diagram ==
[[File:ClassDiagramUmms-0.1.png]]

*'''UmmsAudioManager'''
Class to implement '''''com.UMMS.AudioManager''''' interface which provide client with audio output control service.

*'''UmmsVideoOutput'''
Class to implement '''''com.UMMS.VideoOutput''''' interface which provide client with video output control service.

*'''UmmsPlayingContentMetadataViewer'''
Class to implement '''''com.UMMS.PlayingContentMetadataViewer''''' interface which allow the client to query the current playing content on server side.

*'''UmmsObjectManager'''
Class to manage MediaPlayer objects, including create/destory, register/unregister MediaPlayer objects.

*'''UmmsMediaPlayer'''
Class to implement the '''''com.UMMS.MediaPlayer''''' interface which provide media playback service for client.

*'''UmmsPlayerBackend'''
A base class which defined internal interface for media playback. UmmsMediaPlayer uses this class to handle the service request. Backend developer need to subclass it.

*'''UmmsAudioManagerBackend'''
A base class which defined internal interface for controlling audio output. UmmsAudioManager uses this class to handle the service request. Backend developer need to subclass it.

*'''UmmsVideoOutputBackend'''
A base class which defined internal interface for controlling video output. UmmsVideoOutput uses this class to handle the service request. Backend developer need to subclass it.

*'''UmmsPlugin'''
A class which defined the plugin mechanism. All backend should be implemented as a UmmsPlugin.

*'''Player'''
An implementation of UmmsPlayerBackend.

*'''AudioManger'''
An implementation of UmmsAudioBackend.

*'''VideoOutput'''
An implementation of UmmsVideoOutput.

Note that, '''Player''','''AudioManger''','''VideoOutput''' are plugins and will not provide by umms-1.0.

== How to develop a backend ==
Suppose you are going to develop a player backend.
*'''Step 1: Subclass UmmsPlayerBackend'''
The UmmsPlayerBackend is an internal interface to abstract all the media playback control. The backend developer should subclass this class and implement its vmethods. Of course, you can just implement a subset of the virtual methods defined in UmmsPlayerBackendClass struct, for example. For the dvb player backend, it is optional to implement the "pause" method. If you want to add the time-shifting feature for DVB playback, implementing "pause" method is a choice.

*'''Step 2: Fill the UmmsPlugin struct in your PlayerBackend.c file and export it'''
The definition of struct UmmsPlugin:
<pre>
typedef struct _UmmsPlugin {
gint major_version;//the major version number of umms core that plugin was compiled for
gint minor_version;//the minor version number of core that plugin was compiled for
UmmsPluginType type;
const gchar *filename;//set by "plugin loader" when this plugin loaded.
const gchar *name;
const gchar *description;

/*
* Used for plugins of UMMS_PLUGIN_TYPE_PLAYER_BACKEND type.
* If supported_uri_protocols is empty, unsupported_uri_protocols is respected
* as a "black list" of uri. If supported_uri_protocols is not empty, ignore
* unsupported_uri_protocols.
* For example, the implementor can create a black list for its plugin like this:
* supported_uri_protocols = {NULL};
* unsupported_uri_protocols = {"dvb"};
* that means the plugin can handle all uri protocols unless "dvb".
*/
const gchar **supported_uri_protocols;
const gchar **unsupported_uri_protocols;

/*vmethod to create the instance of backend.*/
gpointer (*backend_new_func) (void);
}UmmsPlugin;
</pre>
The most important fields are supported_uri_protocols, unsupported_uri_protocols, and backend_new_func. The following is code snapshot to fill the struct:
<pre>
static gchar *supported_prots[] = {
NULL
};

static gchar *unsupported_prots[] = {
"dvb", NULL
};

MyPlayerBackend *my_player_backend_new (void)
{
return g_object_new (MY_TYPE_PLAYER_BACKEND, NULL);
}

/*Plugin description*/
G_MODULE_EXPORT
UmmsPlugin umms_plugin = {
UMMS_VERSION_MAJOR;
UMMS_VERSION_MINOR;
UMMS_PLUGIN_TYPE_PLAYER_BACKEND,
NULL,//should set by loader
"Player",
"Player to handle non-dvb URI",
(const gchar **)&supported_prots,
(const gchar **)&unsupported_prots,
(gpointer (*) (void)) my_player_backend_new
};
</pre>
Here is a sample player backend: [http://wiki.meego.com/images/Sample-player-backend-0.0.1.tar.gz]

UMMS Architecture

2012-04-23T01:03:16Z

Noel: /* Introduction */

= UMMS Architecture =

== Introduction ==
This page describes the architecture of umms-0.1. You can get the code from: git://gitorious.org:meego-middleware/umms.git 
The UMMS general description can found on the '''[[Umms|main page]]'''

== Class Diagram ==
[[File:ClassDiagramUmms-0.1.png]]

*'''UmmsAudioManager'''
Class to implement '''''com.UMMS.AudioManager''''' interface which provide client with audio output control service.

*'''UmmsVideoOutput'''
Class to implement '''''com.UMMS.VideoOutput''''' interface which provide client with video output control service.

*'''UmmsPlayingContentMetadataViewer'''
Class to implement '''''com.UMMS.PlayingContentMetadataViewer''''' interface which allow the client to query the current playing content on server side.

*'''UmmsObjectManager'''
Class to manage MediaPlayer objects, including create/destory, register/unregister MediaPlayer objects.

*'''UmmsMediaPlayer'''
Class to implement the '''''com.UMMS.MediaPlayer''''' interface which provide media playback service for client.

*'''UmmsPlayerBackend'''
A base class which defined internal interface for media playback. UmmsMediaPlayer uses this class to handle the service request. Backend developer need to subclass it.

*'''UmmsAudioManagerBackend'''
A base class which defined internal interface for controlling audio output. UmmsAudioManager uses this class to handle the service request. Backend developer need to subclass it.

*'''UmmsVideoOutputBackend'''
A base class which defined internal interface for controlling video output. UmmsVideoOutput uses this class to handle the service request. Backend developer need to subclass it.

*'''UmmsPlugin'''
A class which defined the plugin mechanism. All backend should be implemented as a UmmsPlugin.

*'''Player'''
An implementation of UmmsPlayerBackend.

*'''AudioManger'''
An implementation of UmmsAudioBackend.

*'''VideoOutput'''
An implementation of UmmsVideoOutput.

Note that, '''Player''','''AudioManger''','''VideoOutput''' are plugins and will not provide by umms-1.0.

== How to develop a backend ==
Suppose you are going to develop a player backend.
*'''Step 1: Subclass UmmsPlayerBackend'''
The UmmsPlayerBackend is internal interface to abstract all the media playback control. Backend developer should subclass this class and implement its vmethods. Of cause, you can just implement a subset of the virtual methods defined in UmmsPlayerBackendClass struct, e.g. For dvb player backend, it is optional to implement the "pause" method. If you want to add time-shifting feature for DVB playback, implementing "pause" method is a choice.

*'''Step 2: Fill the UmmsPlugin struct in your PlayerBackend.c file and export it'''
The definition of struct UmmsPlugin:
<pre>
typedef struct _UmmsPlugin {
gint major_version;//the major version number of umms core that plugin was compiled for
gint minor_version;//the minor version number of core that plugin was compiled for
UmmsPluginType type;
const gchar *filename;//set by "plugin loader" when this plugin loaded.
const gchar *name;
const gchar *description;

/*
* Used for plugins of UMMS_PLUGIN_TYPE_PLAYER_BACKEND type.
* If supported_uri_protocols is empty, unsupported_uri_protocols is respected
* as a "black list" of uri. If supported_uri_protocols is not empty, ignore
* unsupported_uri_protocols.
* e.g. The implementor can create a black list for its plugin like this:
* supported_uri_protocols = {NULL};
* unsupported_uri_protocols = {"dvb"};
* that means the plugin can handle all uri protocols unless "dvb".
*/
const gchar **supported_uri_protocols;
const gchar **unsupported_uri_protocols;

/*vmethod to create the instance of backend.*/
gpointer (*backend_new_func) (void);
}UmmsPlugin;
</pre>
The most important fields are supported_uri_protocols, unsupported_uri_protocols and backend_new_func. The following is code snapshot to fill the struct:
<pre>
static gchar *supported_prots[] = {
NULL
};

static gchar *unsupported_prots[] = {
"dvb", NULL
};

MyPlayerBackend *my_player_backend_new (void)
{
return g_object_new (MY_TYPE_PLAYER_BACKEND, NULL);
}

/*Plugin description*/
G_MODULE_EXPORT
UmmsPlugin umms_plugin = {
UMMS_VERSION_MAJOR;
UMMS_VERSION_MINOR;
UMMS_PLUGIN_TYPE_PLAYER_BACKEND,
NULL,//should set by loader
"Player",
"Player to handle non-dvb URI",
(const gchar **)&supported_prots,
(const gchar **)&unsupported_prots,
(gpointer (*) (void)) my_player_backend_new
};
</pre>
A sample player backend is here: [http://wiki.meego.com/images/Sample-player-backend-0.0.1.tar.gz]

UMMS User Manual

2012-04-23T01:00:16Z

Noel: /* Introduction */

= UMMS User Manual and Sample code =

== Introduction ==
This page is the user manual and some sample code for the Universal Multi Media Service (UMMS). 
The UMMS general description is on the '''[[Umms|main page]]'''.
You can get the code from:
git://gitorious.org/meego-middleware/umms.git

== Service Name ==
com.UMMS

== Objects and Interfaces ==
''ObjectManager'': Object to create and remove ''MediaPlayer'' object.
Path: /com/UMMS/ObjectManager
Interface: com.UMMS.ObjectManager.iface

''MediaPlayer'': Player object to control the playback of media assets.
Path: Returned by ''ObjectManager''
Interface: com.UMMS.MediaPlayer

''AudioManager'': Object to manage the system audio output.
Path: /com/UMMS/AudioManager
Interface: com.UMMS.AudioManger

''VideoOutput'': Object to control the display.
Path: /com/UMMS/VideoOutput
Interface: com.UMMS.VideoOutput

''PlayingContentMetadataViewer'': Object to provide the metadata of all current playing content.
Path: /com/UMMS/PlayingContentMetadataViewer
Interface: com.UMMS.PlayingContentMetadataViewer

== API Reference ==
* '''''Interface com.UMMS.ObjectManager.iface'''''

Methods:

RequestMediaPlayer(s(out): object_path)
Request a ''MediaPlayer'' object operate in attended-execution mode. The ''ObjectManager'' will creat a new ''MediaPlayer'' object,
register the object on the bus and return the object path to client.
Parameters:
object_path(out): The object path belongs to the newly created ''MediaPlayer'' object.

RequestMediaPlayerUnattended(d: time_to_execution, s(out): token, s(out): object_path)
Request a ''MediaPlayer'' object operate in unattended-execution mode. The ''ObjectManager'' will creat a new ''MediaPlayer'' object,
register it on the bus and return the object path to client.
Parameters:
time_to_execution: Times in seconds for which this ''MediaPlayer'' object keep alive.
token(out): The unique token belongs to this execution. Application can use it to identify the execution log file which
named by the token.
object_path(out): The object path belongs to the newly created ''MediaPlayer'' object.

RequestScheduledRecorder(d: start_time, d: duration, s: uri, s: location, s(out): token, s(out): object_path)
Request a ''MediaPlayer'' object operate in unattended-execution mode and schedule it to record the media pointed by "uri". The ''ObjectManager'' will creat a
new ''MediaPlayer'' object, register it on the bus and return the object path to client.
Parameters:
start_time: The delay to start recording in seconds.
duration: How long to record, in seconds.
uri: Specify the media to record.
location: Location to store the recorded media.
token(out): The unique token belongs to this execution. Application can use it to identify the execution log file which
named by the token.
object_path(out): The object path belongs to the newly created ''MediaPlayer'' object.

RemoveMediaPlayer(s: object_path)
Remove the ''MediaPlayer'' object which was exposed on the object_path.
Parameters:
object_path: The path on which this object was exposed.

* '''''Interface com.UMMS.MediaPlayer'''''

Methods:

SetUri(s: uri)
Set URI to UMMS.
Parameters:
uri: URI to set.

SetSubtitleUri(s: sub_uri)
Set subtitle URI to UMMS.
Parameters:
sub_uri: URI to identify the subtitle file.

GetCurrentUri(s(out): current_uri)
Get current URI.
Parameters:
current_uri(out): current URI.

SetTarget(i: type, a{sv}: param)
Set video target and pass all target parameters to UMMS. The video target is where your decoded video data should be rendered.
Parameters:
type: The type of video target.
0:XWindow, the video data will be rendered on the X Window.
1:DataCopy, the video data will be copied to a memory instead of directly rendering. E.g. copied to a GL Texture.
2:Socket, the video data will sent to a socket.
3:ReservedType0, reserved for custom target.
4:ReservedType1, reserved for custom target.
5:ReservedType2, reserved for custom target.
6:ReservedType3, reserved for custom target.
param: The list of key-value pair to specify the attributes of the target. The definition of attribute structure is
target-specific and up to the implementor. The UMMS framwork just defined the XWindow target attribute:
Key Value
"window-id" value of "i" type indicates the window id.

Play()

Pause()

Stop()

SetPosition(x: pos)
Seek to position.
Parameters:
pos: Stream position in millisecond.

GetPosition(x(out): pos)
Get the current position of stream in millisecond.
Parameters:
pos(out): The current stream position.

SetPlaybackRate(d: rate）
Set the playback rate.
Parameters:
rate: rate to playback the media asset.

GetPlaybackRate(d(out): rate）
Get current playback rate.
Parameters:
rate(out): The current playback rate.

SetVolume(i: volume)

GetVolume(i(out): volume)

SetVideoSize(u: x, u: y, u: w, u: h)
Set video dimension.
Paramters:
x: X coordinate of top-left.
y: Y coordinate of top-left.
w: Width of video rectangle.
h: Height of video rectangle.

GetVideoSize(u(out): w, u(out): h)
Get current width and height of video rectangle.
Parameters:
w(out): Width of current video rectangle.
h(out): Height of current video rectangle.

GetBufferedTime(x(out): length_time)
Get the approximate duration of playable data downloaded so far in millisecond.
Parameters:
length_time(out): amount of playable data downloaded so far in millisecond.

GetBufferedBytes(x(out): length_byte)
Get the approximate amount of playable data downloaded so far in bytes.
Parameters:
length_byte(out): amount of playable data downloaded so far in byte.

GetMediaSizeTime(x(out): duration)
Get the duration of the media.
Parameters:
duration(out): duration in millisecond.

GetMediaSizeBytes(x(out): size)
Get the total size of the media file.
Parameters:
size(out): total size of the media file.

HasVideo(b(out): has_video)
Indicates the existance of video stream in the media asset.
Parameters:
has_video(out): True if media asset has video. False otherwise.

HasAudio(b(out): has_audio)
Indicates the existance of audio stream in the media asset.
Parameters:
has_audio(out): True if media asset has audio. False otherwise.

IsStreaming(b(out): is_stream)
Indicates whether the URI represents a stream media.
Parameters:
is_stream(out): True for stream media. False otherwise.

IsSeekable(b(out): is_seekable)
Indicates whether this media asset is seekable.
Parameters:
is_seekable(out): True for seekable. False otherwise.

SupportFullScreen(b(out): support_fullscreen)
Indicates whether the backend supports a fullscreen mode.
Parameters:
support_fullscreen(out): True if backend supports fullscreen. False otherwise.

GetPlayerState(i(out): current_state)
Get current state of ''MediaPlayer'' object.
Parameters:
current_state(out):
0:Null,
1:Stopped,
2:Paused,
3:Playing

Reply()
Response the UMMS server’s heartbeat check. In the attended-execution mode, client should connect to NeedReply
signal with a callback in which Reply() method should be called.

SetProxy(a{sv}: param)
Set proxy stuffs.
Parameters:
param: A list of key-value pair to sepcify the proxy attributes.
The attribute structure is defined as:
Key Value
"proxy-uri" value of "s" type indicates HTTP proxy server URIl
"proxy-id" value of "s" type indicates HTTP proxy user id for authentication.
"proxy-pw" value of "s" type indicates HTTP proxy user password for authentication

Suspend()
Suspend current execution of player. After this invoking, all the resources ocuppied by this session will be released.

Restore()
Play the media asset from the position at where it suspended.

GetCurrentVideo(i(out): current_video)
Get current playing video stream.
Parameters:
current_video(out): stream number of current playing video.

GetCurrentAudio(i(out): current_audio)
Get current playing audio stream.
Parameters:
current_audio(out): stream number of current playing audio.

GetCurrentSubtitle(i(out): current_sub)
Get current playing subtitle stream.
Parameters:
current_sub(out): stream number of current playing subtitle.

SetCurrentVideo(i: current_video)
Choose the video stream to play.
Parameters:
current_video: stream number of video stream choosed to play.

SetCurrentAudio(i: current_audio)
Choose the audio stream to play.
Parameters:
current_audio: stream number of audio stream choosed to play.

SetCurrentSubtitle(i: current_sub)
Choose the subtitle stream to play. This method is for the media asset with embedded subtitle.
Parameters:
current_sub: stream number of subtitle stream choosed to play.

GetVideoNum(i(out): video_num)
Get total number of video streams.
Parameters:
video_num(out): Total number of video streams.

GetAudioNum(i(out): audio_num)
Get total number of audio streams.
Parameters:
audio_num(out): Total number of audio streams.

SetBufferDepth(i: format, x: buf_depth)
Set buffer depth when buffering network streams.
Parameters:
format: 0 for Time, 1 for Btye.
buf_depth: The depth to buffer data.

GetBufferDepth(i: format, x(out): buf_depth)
Get buffer depth.
Parameters:
format: 0 for Time, 1 for Btye.
buf_depth(out): The depth to buffer data.

SetMute(i: is_mute)
Mute the audio.
Parameters:
is_mute: 0 for unmute, 1 for mute.

IsMute(i(out): is_mute)
Get the mute state.
Parameters:
is_mute(out): 0 for unmute, 1 for mute.

SetScaleMode(i: mode)
Set the scale mode.
Parameters:
mode:
0: do not scale.
1: fill entire target, regardless of original video aspect ratio.
2: scale the video with respect to original video aspect ratio.
3: fill the whole screen but keep the ratio, some part of video may out of screen.

GetScaleMode(i(out): mode)
Get the scale mode.
Parameters:
mode(out):
0: do not scale.
1: fill entire target, regardless of original video aspect ratio.
2: scale the video with respect to original video aspect ratio.
3: fill the whole screen but keep the ratio, some part of video may out of screen.

GetVideoCodec(i: num, s(out): video_codec)
Get the codec of video stream specified by the "num".
Parameters:
num: video stream number.
video_codec(out): codec string.

GetAudioCodec(i: num, s(out): audio_codec)
Get the codec of audio stream specified by the "num".
Parameters:
num: audio stream number.
audio_codec(out): codec string.

GetVideoBitrate(i: num, i(out): video_bitrate)
Get the bitrate of video stream specified by the "num".
Parameters:
num: video stream number.
video_bitrate(out): bitrate of the video stream.

GetAudioBitrate(i: channel, i(out): audio_bitrate)
Get the bitrate of audio stream specified by the "num".
Parameters:
num: audio stream number.
audio_bitrate(out): bitrate of the audio stream.

GetEncapsulation(s(out): encapsulation)
Get the container format.
Parameters:
encapsulation(out): the container format.

GetAudioSampleRate(i: num, i(out): sample_rate)
Get the sample rate of audio stream specified by the "num".
Parameters:
num: audio stream number.
sample_rate(out): sample rate of the audio stream.

GetVideoFrameRate(i: num, i(out): frame_rate_num, i(out): frame_rate_denum)
Get the frame rate of video stream specified by the "num".
Parameters:
num: video stream number.
frame_rate_num(out): numerator of frame rate.
frame_rate_denum(out): denumerator of frame rate.

GetVideoResolution(i: num, i(out): width, i(out): height)
Get the original resolution of the video stream specified by the "num".
Parameters:
num: video stream number.
width(out): width of video.
height(out): height of video.

GetVideoAspectRatio(i: num, i(out): ratio_num, i(out): ratio_denum)
Get the original aspect ratio of the video stream specified by the "num".
Parameters:
num: video stream number.
ratio_num(out): numerator of the aspect ratio.
ratio_denum(out): denumerator of the aspect ratio.

GetProtocolName(s(out): protocol_name)
Get the tranport protocol name.
Parameters:
protocol_name(out): name of the protocol.

Record(b: to_record, s: location)
Start or stop the recording of current playing DVB stream.
Parameters:
to_record: True to start recording, False to stop recording.
location: path to store the record file.

GetPat(aa{sv}(out): pat)
Get the "Program Association Table".
Parameters:
pat(out): the "Program Association Table".
The structure of pat is a list of mapping table. Each mapping table has two key-value pairs:
Key Value
"program-number" value of "u" type which indicates the program number.
"pid": value of "u" type which indicates the pid of the pat.

GetPmt(u(out): program_number, u(out): pcr_pid, aa{sv}(out): stream_info)
Get the "Program Map Table" of current playing DVB program.
Parameters:
program_number(out): the number of current playing program.
pcr_pid(out): the pcr pid.
stream_info(out): the information of all elementary streams multiplexed in this program.
The structure of stream_info is a list of mapping table. Each mapping table has two key-value pairs:
Key Value
"stream-type" value of "u" type indicates the stream type.
"pid" value of "u" type indicates the pid of the elementary stream.

GetAssociatedDataChannel(s(out): ip, i(out): port)
Get the ip and port from which the client can retrive DVB associated data(ts packets).
Parameters:
ip(out): ip string
port(out): port string

Signals:
Initialized
Pipeline engine initialized.

Eof
End of file or stream.

Error(u: id, s: message)
Error happened.
Parameters:
id: error id.
message: error message.

Buffering(i: percent)
Buffering percent, from 0 to 100.

Seeked
Seeking done.

Stopped
Player stopped.

PlayerStateChanged(i: old_state, i: new_state)
Player state changed.
Parameters:
old_state: previous state of player, value definition is the same as state parameter of GetPlayerState.
new_state: current state of player, value definition is the same as state parameter of GetPlayerState.

NeedReply
Singal to request the client to reply. This is for client existence checking. The client should call the Reply() method to response this
signal.

Suspended
The player has been suspended. That means all the resources ocuppied by this player has been released.

Restored
The player restored from suspened.

NoResource
Resource unavailable.

VideoTagChanged(i: video_number)
The metadata of video stream changed.
Parameters:
video_number: video stream number.

AudioTagChanged(i: audio_number)
The metadata of audio stream changed.
Parameters:
audio_number: audio stream number.

TextTagChanged(i: text_number)
The metadata of text stream changed.
Parameters:
text_number: text stream number.

RecordStart
The recording started.

RecordStop
The recording stopped.

* '''''Interface: com.UMMS.AudioManger'''''

Methods:
SetVolume(i: output_type, i: volume)
Set the global audio volume on audio output specified by "output_type".
Parameters:
output_type: output type id.
0, hdmi
1, spidf
2, i2s0
3, i2s1
volume: volume to set, range [0, 100]

GetVolume(i: output_type, i(out): volume)
Set the global audio volume on audio output specified by "output_type".
Parameters:
output_type: output type id.
volume(out): current volume.

SetState(i: output_type, i: state)
Mute/Unmute the audio output.
Parameters:
output_type: output type id.
state: 0 to unmute, 1 to mute.

GetState(i: output_type, i(out): state)
Get the mute state of audio output.
Parameters:
output_type: output type id.
state(out): 0 for unmute, 1 for mute.

* '''''Interface: com.UMMS.VideoOutput'''''

Methods:
GetValidVideoOutput(as(out): outputs)
Get name of all the outputs.
Parameters:
outputs(out): output names.

GetValidMode(s:output_name, as(out): modes)
Get valid display modes of a output specified by output_name
Parameters:
output_name：output name.
modes(out): valid display modes.

SetMode(s:output_name, s: mode)
Set display mode of the output.
Parameters:
output_name：output name.
mode: mode to set.

GetMode(s:output_name, s(out): mode)
Get current display mode of the output.
Parameters:
output_name：output name.
mode(out): current display mode.

* '''''Interface: com.UMMS.PlayingContentMetadataViewer'''''

Methods:
GetPlayingContentMetadata(aa{sv}(out): playing_content_metadata)
Get the current playing content metadata.
Parameters:
playing_content_metadata(out): media content metadata
The structure of playing_content_metadata is a list of mapping table. Each mapping table has 3 key-value pairs:
Key Value
"URI" Value of "s" type indicates the current playing URI.
"Title" Value of "s" type indicates the title of the playing media content
"Artist" Value of "s" type indicates the artist of the playing media content

Signals:
MetadataUpdated(aa{sv}: metadata)
Emitted when a metadata changed. e.g. A new player is requested to play a video.
Parameters:
metadata: The same as playing_content_metadata

== Sample Code ==
This is a sample in python to play a URI by requesting a attended-execution. You can get the latest code from: git://gitorious.org:meego-middleware/umms.git
<pre>
import dbus
import dbus.mainloop.glib
import dbus.glib

player_iface = None
loop = None

def need_reply_cb ():
player_iface.Reply()

def eof_cb ():
print "EOF...."
loop.quit()

#event loop
dbus.mainloop.glib.DBusGMainLoop(set_as_default=True)

#get the system message deamon
bus=dbus.SystemBus()

#get the 'com.UMMS.ObjectManager.iface'
bus_obj=bus.get_object('com.UMMS', '/com/UMMS/ObjectManager')
obj_mngr=dbus.Interface(bus_obj, 'com.UMMS.ObjectManager.iface')

#request a media player for attended-execution
player_obj_path = obj_mngr.RequestMediaPlayer()
player_obj = bus.get_object("com.UMMS", player_obj_path)
player_iface = dbus.Interface(player_obj, 'com.UMMS.MediaPlayer')

#for the attended-execution, we must connect to the "NeedReply" signal
player_iface.connect_to_signal("NeedReply", need_reply_cb)

#connect other signals you want
player_iface.connect_to_signal("Eof", eof_cb)

#play a URI
player_iface.SetUri("/tmp/sample.mp4")
player_iface.Play()

#event loop
loop = gobject.MainLoop()
loop.run()
</pre>

Umms

2012-04-23T00:57:23Z

Noel: /* Universal Multimedia Service (UMMS) */

= Universal Multimedia Service (UMMS) =

1 Short description of the need
---------------------------------
Linux in general, including MeeGo in particular, lacks a unified solution for playing multimedia content. Almost every application has its own solution, limiting the opportunity to benefit from new hardware capabilities provided by modern chipsets on non-PC platforms, and reducing the scope of usability of high value multimedia content, which is often protected using a proprietary codec.
It isn't the first time that Linux has had to break boundaries and change established solutions to drastically improve its support for new services. In the recent past, we've seen the adoption of CUPS (1999-2002) for printing and Sane (2000-2005) for scanning, enabling the use of Linux in the office environment, which, before these two, seemed only possible for the geek in search of a long night enjoying troubleshooting fun.
The current proposition has no less of an outrageous ambition than creating a Unified Multi Media Service (UMMS), which will enable playing audio and video (AV) from an application on any Linux platform (starting from MeeGo), without having to worry about anything more than its position on the screen and its possible initial transparency over the User Interface graphics.
2 Purpose/audience
--------------------
The purpose of this document is to provide an understanding of a solution which could be used to deliver a unified service. This would enable a large community of developers to benefit from the best possible audio and video capabilities provided by various Linux implementations, without having to worry about the supporting HW.
It addresses the managers who wish to understand the requirements and the constraints required for such a solution, as well as the developers who will have to deliver a working implementation.
It focuses on an initial application for MeeGo TV, but it has been designed with the vision to expand, in a second phase, to all MeeGo verticals, starting with tablets. It is intended to go beyond TV and tablets and further, and experience a general adoption by the larger Linux community. Only MeeGo needs are described in this initial document.
3 Overview
------------
MeeGo is an open source version of Linux which targets Netbooks, Tablets, Mobiles, Connected TV, and Automotive domains. MeeGo has the goals of delivering an optimized user experience and also enabling a community of developers to service applications across domains.
Unfortunately, not only does Linux not have a standard set of APIs to play audio and video (AV), but the existing main Linux AV Player APIs (Mplayer and Totem) do not cater to TV's needs:
<ul>
<li>Programming language independence</li>
<li>Management of protected high value content (Pay TV)</li>
<li>GPL license isolation</li>
<li>Support of TV features (broadcast, sub-title, language selection, aspect ratio, trick play, …)</li>
<li>Sophisticated transport independence (smooth streaming, forward error correction, ...)</li>
<li>Multiple back-end video pipe support</li>
<li>Support of new generation HW feature (for example, video as an OpenGL texture)</li>
</ul>

This document explains the constraints introduced by these requirements and provides possible solutions and recommendations.

4 Documentation
----------------------------

Specifications [[File:Meego_Unified_MultiMedia_Service_V0.4.odt]] 
* [[UMMS_Architecture | General Architecture]] 
* [[UMMS_User_Manual | User Manual and Sample code]] 
* [[media:LinuxCon_2011_umms_introduction.pdf|Slides from Linux Conference Oct11 and Nov 11]]

Javascript API
* [[TV Browser]]

5 Where is the code
-----------------
Visit MeeGo OBS and search for UMMS
https://build.meego.com

or directly the GIT repo
git://gitorious.org/meego-middleware/umms.git

Umms

2012-04-23T00:54:42Z

Noel:

= Universal Multimedia Service (UMMS) =

1 Short description of the need
---------------------------------
Linux in general, including MeeGo in particular, lacks a unified solution for playing multimedia content. Almost every application has its own solution, limiting the opportunity to benefit from new hardware capabilities provided by modern chipsets on non-PC platforms, and reducing the scope of usability of high value multimedia content, which is often protected using a proprietary codec.
It isn't the first time that Linux has had to break boundaries and change established solutions to drastically improve its support for new services. In the recent past, we've seen the adoption of CUPS (1999-2002) for printing and Sane (2000-2005) for scanning, enabling the use of Linux in the office environment, which, before these two, seemed only possible for the geek in search of a long night enjoying troubleshooting fun.
The current proposition has no less of an outrageous ambition than creating a Unified Multi Media Service (UMMS), which will enable playing audio and video (AV) from an application on any Linux platform (starting from MeeGo), without having to worry about anything more than its position on the screen and its possible initial transparency over the User Interface graphics.
2 Purpose/audience
--------------------
The purpose of this document is to provide an understanding of a solution which could be used to deliver a unified service. This would enable a large community of developers to benefit from the best possible audio and video capabilities provided by various Linux implementations, without having to worry about the supporting HW.
It addresses the managers who wish to understand the requirements and the constraints required for such a solution, as well as the developers who will have to deliver a working implementation.
It focuses on an initial application for MeeGo TV, but it has been designed with the vision to expand, in a second phase, to all MeeGo verticals, starting with tablets. It is intended to go beyond TV and tablets and further, and experience a general adoption by the larger Linux community. Only MeeGo needs are described in this initial document.
3 Overview
------------
MeeGo is an open source version of Linux which targets Netbooks, Tablets, Mobiles, Connected TV, and Automotive domains. MeeGo has the goals of delivering an optimized user experience and also enabling a community of developers to service applications across domains.
Unfortunately, not only does Linux not have a standard set of APIs to play audio and video (AV), but the existing main Linux AV Player APIs (Mplayer and Totem) do not cater to TV's needs:
Programming language independence
Management of protected high value content (Pay TV)
GPL license isolation
Support of TV features (broadcast, sub-title, language selection, aspect ratio, trick play, …)
Sophisticated transport independence (smooth streaming, forward error correction, ...)
Multiple back-end video pipe support
Support of new generation HW feature (for example, video as an OpenGL texture)
This document explains the constraints introduced by these requirements and provides possible solutions and recommendations.

4 Documentation
----------------------------

Specifications [[File:Meego_Unified_MultiMedia_Service_V0.4.odt]] 
* [[UMMS_Architecture | General Architecture]] 
* [[UMMS_User_Manual | User Manual and Sample code]] 
* [[media:LinuxCon_2011_umms_introduction.pdf|Slides from Linux Conference Oct11 and Nov 11]]

Javascript API
* [[TV Browser]]

5 Where is the code
-----------------
Visit MeeGo OBS and search for UMMS
https://build.meego.com

or directly the GIT repo
git://gitorious.org/meego-middleware/umms.git

TV Browser

2012-04-23T00:30:56Z

Noel: /* 4, Documentation */

= MeeGo TV Browser =

== 1, Short expression of the need ==

The TV industry, and in particular IPTV, has used browsers for years to create TV portals. In IPTV, specialized companies, such as ANT (Cambridge, UK), Opera (Oslo, Norway), or Access (Tokyo, Japan) have created specialized browsers for these use cases.
These specialized browsers were optimized for TV, at the detriment of their potential to surf the open internet.
Today, the requirement to browse the open internet are imposed on TV, so there is a need to provide an “open internet” capable browser, which can be integrated in a TV and can be used to create TV portals.
These portals are commonly used to provide the business logic which runs locally on the device and is written in AJAX. To enable the control of the TV and Media Center, an API accessible from JavaScript must be added to the browser.

== 2, Purpose/audience ==
The purpose of this document is to provide an understanding of the solution which has been developed by the MeeGo TV project. It addresses the developers who will deliver a working implementation.

== 3, Overview ==
The internet world has created browsers for the PC. Assuming not only a mouse and a keyboard, but also 50 cm viewing with a multiple window presentation layer and a skilled human driving the beast.
Unfortunately, a TV has neither a keyboard or a mouse, the vision is done from 3m, there is no windowing concept, and the Live TV presentation remains in control of the UI all the time. The TV needs a browser which address some critical issues.
Controllable by an external application.
* Instant start
* Accept alternative input method
* Support HW accelerated Video
* Asset browsing
* Web API for TV (conform to [http://www.oipf.tv/docs/Release2/V2.1/OIPF-T1-R2-Specification-Volume-5-Declarative-Application-Environment-v2_1-2011-06-21.pdf OpenIPTV Forum DAE specification])
** Open IPTV Forum DAE configuration API (section 7.3)
** Open IPTV Forum DAE broadcasting API (section 7.13)
** Open IPTV video DAE playback control (section 7.14)
* [[TV Browser Control API]]
* [[TV Browser Javascript API]]
* [[TV Browser Video HW acceleration]]
* [[TV Browser Transparency Management]]

== 4, Documentation ==

Requirements
* [[File:Meego TV JavaScriptAPI requirement.pdf | Requirement for a TV Javascript API]] 
* [[File:Meego TV Browser V0.2.odt | Requirement for TV Browser]] 
* [http://www.oipf.tv/docs/Release2/V2.1/OIPF-T1-R2-Specification-Volume-5-Declarative-Application-Environment-v2_1-2011-06-21.pdf Declarative Application Environment V2.1]

User Manual
* [[TV Browser Control API]]
* [[TV Browser Javascript API]]
* [[TV Browser Video HW acceleration]]
* [[TV Browser Transparency Management]]

Related Topics
* Universal Multi Media Service [[umms | UMMS]]

== 5, Where is the code ==
Visit MeeGo OBS and search for meego-tv-browser
https://build.meego.com

or directly in the GIT repo 
http://meego.gitorious.org/meego-middleware/meego-tv-browser git branch 874-base-webkit 
http://meego.gitorious.org/meego-middleware/mutter-meego-tv 

== 6, How to Build the MeeGo TV browser with UMMS support ==
Visit the "How to build" wiki page to build the browser
http://wiki.meego.com/TV_Browser_How_to_Build

TV Browser

2012-04-23T00:30:15Z

Noel: /* MeeGo TV Browser */

= MeeGo TV Browser =

== 1, Short expression of the need ==

The TV industry, and in particular IPTV, has used browsers for years to create TV portals. In IPTV, specialized companies, such as ANT (Cambridge, UK), Opera (Oslo, Norway), or Access (Tokyo, Japan) have created specialized browsers for these use cases.
These specialized browsers were optimized for TV, at the detriment of their potential to surf the open internet.
Today, the requirement to browse the open internet are imposed on TV, so there is a need to provide an “open internet” capable browser, which can be integrated in a TV and can be used to create TV portals.
These portals are commonly used to provide the business logic which runs locally on the device and is written in AJAX. To enable the control of the TV and Media Center, an API accessible from JavaScript must be added to the browser.

== 2, Purpose/audience ==
The purpose of this document is to provide an understanding of the solution which has been developed by the MeeGo TV project. It addresses the developers who will deliver a working implementation.

== 3, Overview ==
The internet world has created browsers for the PC. Assuming not only a mouse and a keyboard, but also 50 cm viewing with a multiple window presentation layer and a skilled human driving the beast.
Unfortunately, a TV has neither a keyboard or a mouse, the vision is done from 3m, there is no windowing concept, and the Live TV presentation remains in control of the UI all the time. The TV needs a browser which address some critical issues.
Controllable by an external application.
* Instant start
* Accept alternative input method
* Support HW accelerated Video
* Asset browsing
* Web API for TV (conform to [http://www.oipf.tv/docs/Release2/V2.1/OIPF-T1-R2-Specification-Volume-5-Declarative-Application-Environment-v2_1-2011-06-21.pdf OpenIPTV Forum DAE specification])
** Open IPTV Forum DAE configuration API (section 7.3)
** Open IPTV Forum DAE broadcasting API (section 7.13)
** Open IPTV video DAE playback control (section 7.14)
* [[TV Browser Control API]]
* [[TV Browser Javascript API]]
* [[TV Browser Video HW acceleration]]
* [[TV Browser Transparency Management]]

== 4, Documentation ==

Requirements
* [[File:Meego TV JavaScriptAPI requirement.pdf | Requirement for a TV Javascript API]] 
* [[File:Meego TV Browser V0.2.odt | Requirement for TV Browser]] 
* [http://www.oipf.tv/docs/Release2/V2.1/OIPF-T1-R2-Specification-Volume-5-Declarative-Application-Environment-v2_1-2011-06-21.pdf Declarative Application Environment V2.1]

User Manual
* [[TV Browser Control API]]
* [[TV Browser Javascript API]]
* [[TV Browser Video HW Acceleration]]
* [[TV Browser Transparency Management]]

Related Topics
* Universal Multi Media Service [[umms | UMMS]]

== 5, Where is the code ==
Visit MeeGo OBS and search for meego-tv-browser
https://build.meego.com

or directly in the GIT repo 
http://meego.gitorious.org/meego-middleware/meego-tv-browser git branch 874-base-webkit 
http://meego.gitorious.org/meego-middleware/mutter-meego-tv 

== 6, How to Build the MeeGo TV browser with UMMS support ==
Visit the "How to build" wiki page to build the browser
http://wiki.meego.com/TV_Browser_How_to_Build

Image Creation For Beginners

2011-06-24T23:30:41Z

Noel: /* Creating a MeeGo Image */

__TOC__

== Creating a MeeGo Image ==

Here are the simple steps on how to create a MeeGo image.

For more in-depth information, go to the main Image Creator developer's guide: [[Image Creation]]

'''STEP 1 - Download Meego Image Creator (MIC)'''

MeeGo Image Creator is the tool we use to create MeeGo images.

To get it, you can:

* Download MIC source from Gitorious:
http://meego.gitorious.org/meego-developer-tools/image-creator
* Or, for Debian Squeeze, add the following line to /etc/apt/sources.list and install (using apt-get) ''mic2'':
deb <nowiki>http://repo.meego.com/tools/repos/debian/5.0/</nowiki> /

More on installation dependencies and options on downloading MIC, go to the 'Installation' section here: [[Image_Creation#Requirements]]

'''STEP 2 - Get MeeGo .ks File'''

KickStart (.ks) configuration files are passed to MIC to create images. KickStart files specify what repos to pull from, what packages to include, what post-scripts to run and what type of images to create.

*The official MeeGo .ks files for ARM based Nokia N900 are here: http://repo.meego.com/MeeGo/builds/trunk/ <version>/handset/images/meego-handset-armv7l-n900/
*The official MeeGo .ks files for Intel Atom based netbook and handset (Moorestown) are here: http://repo.meego.com/MeeGo/builds/trunk/ <version>/{netbook,handset,ivi}/images

You can download and use them as a base for the MeeGo images you create. Modify these .ks files as you wish to create tailored images.

We will use the netbook kickstart file to create a MeeGo netbook image: http://repo.meego.com/MeeGo/builds/trunk/1.1.80.7.20101119.1/netbook/images/meego-netbook-ia32/meego-netbook-ia32-1.1.80.7.20101119.1.ks (This is the latest file on November 19, 2010. Please adjust the URL to get the latest version!)

It seems that the "@Core" and "@Base" have been renamed "@Meego Core" and "@Meego Base", so I suggest you to edit the .ks file to rename the package with the good name.

'''STEP 3 - Create MeeGo Livecd Image'''

MIC has to be run with root privileges using 'sudo'.

Here is the command to create a MeeGo livecd image you can burn onto a CD.

<pre>
sudo mic-image-creator --config=default.ks --format=livecd --cache=mycache
</pre>

A file named meego-1.0-default-XX.iso is created. This ISO image is a hybrid image and can be either written to a disk device or burned onto a cd.

'''STEP 4 - Create MeeGo LiveUSB Image'''

To create a MeeGo liveusb image that you can transfer to a USB stick.

<pre>
sudo mic-image-creator --config=default.ks --format=liveusb --cache=mycache
</pre>

A file named meego-1.0-default-XX.usbimg will be created. To burn it onto a USB stick, run the following command:

<pre>
sudo mic-image-writer meego-1.0-default-XX.usbimg
</pre>

This image has a FAT file system and can be mounted easily on Windows and other OSes.

'''---FOR ADDITIONAL INFORMATION ON MIC, PLEASE VISIT THE MIC DEVELOPER'S GUIDE HERE: [[Image Creation]]---'''

== Configure Proxy and Other Variables ==

~/.mic2.conf is a configuration file that can make your life easier by specifying proxy settings, cache directories, and other variables that you normally would have to re-type in your command-line.

Copy and paste this into a file called: ~/.mic2.conf

Replace with your own relevant values.

<pre>
[main]
cachedir=/home/user1/mycache
tmpdir=/home/user1/mystorage/tmp
outdir=/home/user1/mystorage
proxy=http://my.proxy.com:911/
no_proxy=localhost,127.0.0.0/8,.mysite.com,172.16.0.0/16
</pre>

''cachedir'' = directory where the cached repo(s) will reside. With this variable set, you do not need to pass the --cache flag in the command-line.

''tmpdir'' = temporary directory used by mic2 when creating images. With this variable set, you do not need to pass the --tmpdir flag in the command-line.

''outdir'' = where your images will reside once they are created. With this variable set, you do not need to pass the --outdir flag in the command-line.

''proxy'' = specify your proxy if you're behind a behind a firewall.

''no_proxy'' = specify what domains should not sure the proxy setting.

'''Note:''' When specifying proxy and no_proxy, you do not need to use the --proxy flag in your .ks files when referring to repos.

'''---FOR ADDITIONAL INFORMATION ON MIC, PLEASE VISIT THE MIC DEVELOPER'S GUIDE HERE: [[Image_Creation]]---'''

== Another language version of this page ==

* [[适合新手的镜像制作-_-简体中文]]

Image Creation For Beginners

2011-06-24T23:28:58Z

Noel: /* Creating a MeeGo Image */

__TOC__

== Creating a MeeGo Image ==

Here are the simple steps on how to create a MeeGo image.

For more in-depth information, go to the main Image Creator developer's guide: [[Image Creation]]

'''STEP 1 - Download Meego Image Creator (MIC)'''

MeeGo Image Creator is the tool we use to create MeeGo images.

To get it, you can:

* Download MIC source from Gitorious:
http://meego.gitorious.org/meego-developer-tools/image-creator
* Or, for Debian Squeeze, add the following line to /etc/apt/sources.list and install (using apt-get) ''mic2'':
deb <nowiki>http://repo.meego.com/tools/repos/debian/5.0/</nowiki> /

More on installation dependencies and options on downloading MIC, go to the 'Installation' section here: [[Image_Creation#Requirements]]

'''STEP 2 - Get MeeGo .ks File'''

KickStart (.ks) configuration files are passed to MIC to create images. KickStart files specify what repos to pull from, what packages to include, what post-scripts to run and what type of images to create.

*The official MeeGo .ks files for ARM based Nokia N900 are here: http://repo.meego.com/MeeGo/builds/trunk/ <version>/handset/images/meego-handset-armv7l-n900/
*The official MeeGo .ks files for Intel Atom based netbook and handset (Moorestown) are here: http://repo.meego.com/MeeGo/builds/trunk/ <version>/{netbook,handset,ivi}/images

You can download and use them as a base for the MeeGo images you create. Modify these .ks files as you wish to create tailored images.

We will use the netbook kickstart file to create a MeeGo netbook image: http://repo.meego.com/MeeGo/builds/trunk/1.1.80.7.20101119.1/netbook/images/meego-netbook-ia32/meego-netbook-ia32-1.1.80.7.20101119.1.ks (This is the latest file on November 19, 2010 hence please adjust the URL to get the latest version!)

It seems that the "@Core" and "@Base" have been renamed to "@Meego Core" and "@Meego Base" so i suggest you to edit the .ks file to rename the package with the good name.

'''STEP 3 - Create MeeGo Livecd Image'''

MIC has to be run with root privileges using 'sudo'.

Here is the command to create a MeeGo livecd image you can burn onto a CD.

<pre>
sudo mic-image-creator --config=default.ks --format=livecd --cache=mycache
</pre>

A file named meego-1.0-default-XX.iso is created. This ISO image is a hybrid image and can be either written to a disk device or burned onto a cd.

'''STEP 4 - Create MeeGo LiveUSB Image'''

To create a MeeGo liveusb image that you can transfer to a USB stick.

<pre>
sudo mic-image-creator --config=default.ks --format=liveusb --cache=mycache
</pre>

A file named meego-1.0-default-XX.usbimg will be created. To burn it onto a USB stick, run the following command:

<pre>
sudo mic-image-writer meego-1.0-default-XX.usbimg
</pre>

This image has a FAT file system and can be mounted easily on Windows and other OSes.

'''---FOR ADDITIONAL INFORMATION ON MIC, PLEASE VISIT THE MIC DEVELOPER'S GUIDE HERE: [[Image Creation]]---'''

== Configure Proxy and Other Variables ==

~/.mic2.conf is a configuration file that can make your life easier by specifying proxy settings, cache directories, and other variables that you normally would have to re-type in your command-line.

Copy and paste this into a file called: ~/.mic2.conf

Replace with your own relevant values.

<pre>
[main]
cachedir=/home/user1/mycache
tmpdir=/home/user1/mystorage/tmp
outdir=/home/user1/mystorage
proxy=http://my.proxy.com:911/
no_proxy=localhost,127.0.0.0/8,.mysite.com,172.16.0.0/16
</pre>

''cachedir'' = directory where the cached repo(s) will reside. With this variable set, you do not need to pass the --cache flag in the command-line.

''tmpdir'' = temporary directory used by mic2 when creating images. With this variable set, you do not need to pass the --tmpdir flag in the command-line.

''outdir'' = where your images will reside once they are created. With this variable set, you do not need to pass the --outdir flag in the command-line.

''proxy'' = specify your proxy if you're behind a behind a firewall.

''no_proxy'' = specify what domains should not sure the proxy setting.

'''Note:''' When specifying proxy and no_proxy, you do not need to use the --proxy flag in your .ks files when referring to repos.

'''---FOR ADDITIONAL INFORMATION ON MIC, PLEASE VISIT THE MIC DEVELOPER'S GUIDE HERE: [[Image_Creation]]---'''

== Another language version of this page ==

* [[适合新手的镜像制作-_-简体中文]]

MeeGo Porting Guide

2011-06-24T23:27:01Z

Noel: /* Production Adaptation */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (such as touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used, for example, to:
* Listen to various keys and switches in the device (such as power key, volume key, camera button, slider switch)
* Control LEDs
* Enabling/disabling touch screen or HW keyboard, depending on device state
* Control keyboard backlight
* Control display state (on/off) and brightness

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 example, for audio playback, recording, and volume control to work on the device. Typical required components include, for example, 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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (such as video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

The foundation of 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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 (such as 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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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 (such as 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.

==== Buttons and switches ====

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, for example, 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 (such as 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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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 with, for example, 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 the 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).

==== Vibra (notifications/alerts) ====

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, for example, 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, such as 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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T23:26:44Z

Noel: /* Vibra (notifications/alerts) */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (such as touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used, for example, to:
* Listen to various keys and switches in the device (such as power key, volume key, camera button, slider switch)
* Control LEDs
* Enabling/disabling touch screen or HW keyboard, depending on device state
* Control keyboard backlight
* Control display state (on/off) and brightness

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 example, for audio playback, recording, and volume control to work on the device. Typical required components include, for example, 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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (such as video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

The foundation of 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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 (such as 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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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 (such as 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.

==== Buttons and switches ====

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, for example, 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 (such as 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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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 with, for example, 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 the 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).

==== Vibra (notifications/alerts) ====

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, for example, 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, such as 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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T23:25:20Z

Noel: /* Vibra (notifications/alerts) */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (such as touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used, for example, to:
* Listen to various keys and switches in the device (such as power key, volume key, camera button, slider switch)
* Control LEDs
* Enabling/disabling touch screen or HW keyboard, depending on device state
* Control keyboard backlight
* Control display state (on/off) and brightness

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 example, for audio playback, recording, and volume control to work on the device. Typical required components include, for example, 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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (such as video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

The foundation of 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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 (such as 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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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 (such as 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.

==== Buttons and switches ====

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, for example, 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 (such as 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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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 with, for example, 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 the 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).

==== Vibra (notifications/alerts) ====

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, for exmaple, 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, such as 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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T23:24:31Z

Noel: /* Haptics */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (such as touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used, for example, to:
* Listen to various keys and switches in the device (such as power key, volume key, camera button, slider switch)
* Control LEDs
* Enabling/disabling touch screen or HW keyboard, depending on device state
* Control keyboard backlight
* Control display state (on/off) and brightness

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 example, for audio playback, recording, and volume control to work on the device. Typical required components include, for example, 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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (such as video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

The foundation of 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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 (such as 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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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 (such as 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.

==== Buttons and switches ====

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, for example, 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 (such as 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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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 with, for example, 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 the 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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T23:23:00Z

Noel: /* Buttons and switches */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (such as touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used, for example, to:
* Listen to various keys and switches in the device (such as power key, volume key, camera button, slider switch)
* Control LEDs
* Enabling/disabling touch screen or HW keyboard, depending on device state
* Control keyboard backlight
* Control display state (on/off) and brightness

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 example, for audio playback, recording, and volume control to work on the device. Typical required components include, for example, 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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (such as video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

The foundation of 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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 (such as 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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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 (such as 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.

==== Buttons and switches ====

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, for example, 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 (such as 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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T23:22:07Z

Noel: /* HW keyboard */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (such as touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used, for example, to:
* Listen to various keys and switches in the device (such as power key, volume key, camera button, slider switch)
* Control LEDs
* Enabling/disabling touch screen or HW keyboard, depending on device state
* Control keyboard backlight
* Control display state (on/off) and brightness

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 example, for audio playback, recording, and volume control to work on the device. Typical required components include, for example, 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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (such as video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

The foundation of 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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 (such as 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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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 (such as 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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T23:20:17Z

Noel: /* Touch */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (such as touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used, for example, to:
* Listen to various keys and switches in the device (such as power key, volume key, camera button, slider switch)
* Control LEDs
* Enabling/disabling touch screen or HW keyboard, depending on device state
* Control keyboard backlight
* Control display state (on/off) and brightness

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 example, for audio playback, recording, and volume control to work on the device. Typical required components include, for example, 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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (such as video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

The foundation of 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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 (such as 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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T23:16:28Z

Noel: /* USB */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (such as touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used, for example, to:
* Listen to various keys and switches in the device (such as power key, volume key, camera button, slider switch)
* Control LEDs
* Enabling/disabling touch screen or HW keyboard, depending on device state
* Control keyboard backlight
* Control display state (on/off) and brightness

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 example, for audio playback, recording, and volume control to work on the device. Typical required components include, for example, 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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (such as video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

The foundation of 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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T23:15:20Z

Noel: /* Cellular */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (such as touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used, for example, to:
* Listen to various keys and switches in the device (such as power key, volume key, camera button, slider switch)
* Control LEDs
* Enabling/disabling touch screen or HW keyboard, depending on device state
* Control keyboard backlight
* Control display state (on/off) and brightness

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 example, for audio playback, recording, and volume control to work on the device. Typical required components include, for example, 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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (such as video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T23:14:16Z

Noel: /* Video and Imaging Adaptation */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (such as touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used, for example, to:
* Listen to various keys and switches in the device (such as power key, volume key, camera button, slider switch)
* Control LEDs
* Enabling/disabling touch screen or HW keyboard, depending on device state
* Control keyboard backlight
* Control display state (on/off) and brightness

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 example, for audio playback, recording, and volume control to work on the device. Typical required components include, for example, 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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (such as video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T23:12:24Z

Noel: /* Audio Adaptation */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (such as touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used, for example, to:
* Listen to various keys and switches in the device (such as power key, volume key, camera button, slider switch)
* Control LEDs
* Enabling/disabling touch screen or HW keyboard, depending on device state
* Control keyboard backlight
* Control display state (on/off) and brightness

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 example, for audio playback, recording, and volume control to work on the device. Typical required components include, for example, 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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T23:10:12Z

Noel: /* Display and Graphics Adaptation */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (such as touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used, for example, to:
* Listen to various keys and switches in the device (such as power key, volume key, camera button, slider switch)
* Control LEDs
* Enabling/disabling touch screen or HW keyboard, depending on device state
* Control keyboard backlight
* Control display state (on/off) and brightness

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T23:09:04Z

Noel: /* Mode Control Entity (MCE) */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

The MCE component (starting from MeeGo 1.2) can be used to listen to events that have an impact to the device mode (such as touch screen locked vs. unlocked) and change the device mode accordingly. The MCE is used, for example, to:
* Listen to various keys and switches in the device (such as power key, volume key, camera button, slider switch)
* Control LEDs
* Enabling/disabling touch screen or HW keyboard, depending on device state
* Control keyboard backlight
* Control display state (on/off) and brightness

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T23:06:32Z

Noel: /* Resource Policy */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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 a form of MeeGo OS "device adaptation".

==== Mode Control Entity (MCE) ====

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:
* Listening to various keys and switches in the device (e.g. power key, volume key, camera button, slider switch)
* Controlling LEDs
* Touch screen or HW keyboard enabling/disabling depending on device state
* Keyboard backlight control
* Display state (on/off) and brightness control

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T22:59:06Z

Noel: /* Resource Policy */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

The Resource Manager can be used, for example, 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".

==== Mode Control Entity (MCE) ====

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:
* Listening to various keys and switches in the device (e.g. power key, volume key, camera button, slider switch)
* Controlling LEDs
* Touch screen or HW keyboard enabling/disabling depending on device state
* Keyboard backlight control
* Display state (on/off) and brightness control

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T22:55:15Z

Noel: /* Device state */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

The DSME component participates in device state management, such as 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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

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".

==== Mode Control Entity (MCE) ====

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:
* Listening to various keys and switches in the device (e.g. power key, volume key, camera button, slider switch)
* Controlling LEDs
* Touch screen or HW keyboard enabling/disabling depending on device state
* Keyboard backlight control
* Display state (on/off) and brightness control

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T22:53:50Z

Noel: /* Power and thermal management */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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 use standard Linux interfaces such as the generic thermal sysfs API or the hwmon sysfs API.

==== Energy management ====

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.

==== Device state ====

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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

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".

==== Mode Control Entity (MCE) ====

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:
* Listening to various keys and switches in the device (e.g. power key, volume key, camera button, slider switch)
* Controlling LEDs
* Touch screen or HW keyboard enabling/disabling depending on device state
* Keyboard backlight control
* Display state (on/off) and brightness control

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T22:48:27Z

Noel: /* Kernel fundamentals */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (such as IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (such as I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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.

==== Energy management ====

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.

==== Device state ====

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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

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".

==== Mode Control Entity (MCE) ====

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:
* Listening to various keys and switches in the device (e.g. power key, volume key, camera button, slider switch)
* Controlling LEDs
* Touch screen or HW keyboard enabling/disabling depending on device state
* Keyboard backlight control
* Display state (on/off) and brightness control

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T22:46:42Z

Noel: /* Boot */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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, for example, the boot loader, as they see fit. Note, however, that full use 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, such as 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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (e.g. IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (e.g. I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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.

==== Energy management ====

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.

==== Device state ====

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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

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".

==== Mode Control Entity (MCE) ====

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:
* Listening to various keys and switches in the device (e.g. power key, volume key, camera button, slider switch)
* Controlling LEDs
* Touch screen or HW keyboard enabling/disabling depending on device state
* Keyboard backlight control
* Display state (on/off) and brightness control

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T22:44:58Z

Noel: /* Adaptation subsystems and interfaces */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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 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 (such as plugins to some user space SW frameworks). Various configuration file changes may also be required as a part of the adaptation work.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (e.g. IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (e.g. I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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.

==== Energy management ====

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.

==== Device state ====

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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

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".

==== Mode Control Entity (MCE) ====

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:
* Listening to various keys and switches in the device (e.g. power key, volume key, camera button, slider switch)
* Controlling LEDs
* Touch screen or HW keyboard enabling/disabling depending on device state
* Keyboard backlight control
* Display state (on/off) and brightness control

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T22:42:54Z

Noel: /* Upstream projects, MeeGo, products and patches */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products, and patches ===

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 of 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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see e.g. [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (e.g. IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (e.g. I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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.

==== Energy management ====

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.

==== Device state ====

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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

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".

==== Mode Control Entity (MCE) ====

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:
* Listening to various keys and switches in the device (e.g. power key, volume key, camera button, slider switch)
* Controlling LEDs
* Touch screen or HW keyboard enabling/disabling depending on device state
* Keyboard backlight control
* Display state (on/off) and brightness control

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T22:41:03Z

Noel: /* Building your first image */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

The second step to a proper hardware adaptation is making sure you can build your own image. Because 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 an image.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in the previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products and patches ===

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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see e.g. [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (e.g. IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (e.g. I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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.

==== Energy management ====

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.

==== Device state ====

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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

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".

==== Mode Control Entity (MCE) ====

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:
* Listening to various keys and switches in the device (e.g. power key, volume key, camera button, slider switch)
* Controlling LEDs
* Touch screen or HW keyboard enabling/disabling depending on device state
* Keyboard backlight control
* Display state (on/off) and brightness control

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T22:39:16Z

Noel: /* Initial bring-up attempt */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab the already built root filesystem / image for a MeeGo reference device that's the closest to your target. For ARMv7, this is typically the Nokia N900 handset image. For Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add, as this will be input for your porting work.

===== Building your first image =====

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.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products and patches ===

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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see e.g. [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (e.g. IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (e.g. I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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.

==== Energy management ====

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.

==== Device state ====

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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

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".

==== Mode Control Entity (MCE) ====

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:
* Listening to various keys and switches in the device (e.g. power key, volume key, camera button, slider switch)
* Controlling LEDs
* Touch screen or HW keyboard enabling/disabling depending on device state
* Keyboard backlight control
* Display state (on/off) and brightness control

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]

MeeGo Porting Guide

2011-06-24T22:37:54Z

Noel: /* Working under MeeGo.com */

== Introduction ==

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 [http://meego.com/developers/meego-architecture MeeGo architecture]. In some cases, this architecture may still be open and this is noted in the applicable sections.

=== Feedback ===

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 [http://lists.meego.com/listinfo/meego-porting MeeGo porting mailing list].

== General porting information/guidelines ==

=== MeeGo compliance ===

Perhaps the most important piece of background information related to the MPG are the [[Quality/Compliance|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:
* Meet the minimum HW performance and component requirements for the applicable device category
* Include all SW components that form the MeeGo core OS
* Include the additional SW components required to be present in devices in the applicable device category
* Not break the API/ABI of any of the components coming from MeeGo
* Follow the MeeGo SW packaging conventions

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, by defining the SW components and HW components that need to be present, the compliance requirements effectively define the minimum set of porting tasks required from a device vendor and what SW components are involved from MeeGo OS side.

=== Porting process and tools ===

==== Overview ====

As long as a 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 set up an OBS build system that is also used 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 (such as 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:
* [http://meego.gitorious.org MeeGo Gitorious]
** A version control system for the source files of various MeeGo specific SW components and tools
* [http://build.meego.com MeeGo OBS]
** The build system that is used to build MeeGo packages (RPMs) from their sources
* [http://repo.meego.com MeeGo Repository]
** The place where the built MeeGo releases, that is where MeeGo packages and images are stored
* [http://wiki.meego.com/Image_Creation MeeGo Image Creator]
** The tool used to build MeeGo images that can be installed/flashed on HW
* MeeGo release tools
** Tools such as BOSS and REVS that are used in the creation of the MeeGo releases under repo.meego.com

For additional information, see [[Build Infrastructure]], [[Release Infrastructure]] and [[Release Engineering]].

For another overview of the MeeGo porting process, see [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process].

==== Vendor's own OBS ====

So, ultimately, when creating actual products running the MeeGo OS, the vendor may end up setting up their own OBS build system. Setting up your 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 can link to other sources for handling, such as closed source packages that are specific to the vendor. See [[Release_Engineering/Process#Making a product out of MeeGo Release|an overview picture of this setup]].

In this setup, the vendor:
* Sets up their own OBS system
** [[User:Stskeeps/10_easy_steps_to_a_local_OBS|Instructions related to setting up an OBS system]], [[Build_Infrastructure/Sysadmin_Distro/OBS_setup_openSUSE112|OBS Applicances]] [http://en.opensuse.org/openSUSE:Build_Service_private_instance Open Suse OBS Wiki].
* Creates projects under the their own OBS for their own components
* Links their own OBS to the MeeGo OBS for MeeGo components
* May have trial patches to MeeGo components in their own OBS
** NOTE. Eventually all patches to MeeGo components required in a final MeeGo based product ''should'' be pushed to MeeGo.com. However, this is not an absolute must requirement, as long as the MeeGo compliance requirements and applicable SW license rules are fulfilled.
** See [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below
* Needs to set up the necessary machinery to create releases and images from the packages built with OBS
** This machinery can be based on the toolset used in MeeGo (see above)

==== Working under MeeGo.com ====

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 Engineering/Release Timeline|Release Timeline]] and [[Release Engineering/Process|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:
* Creates a device/platform development project under the MeeGo OBS for their components. The open source components would then get submitted to MeeGo Trunk:Testing and get reviewed like any other MeeGo component for inclusion.
** Note that it is also possible to have closed source binary components in the MeeGo OBS to be included in the MeeGo builds for some reference HW. These are submitted to the Trunk:non-oss repository. Licensing is usually required to at least include redistributability, as the components cannot be mirrored from or hosted at repo.meego.com otherwise. It is not possible to have components within Trunk:Testing require closed source dependencies.
* Pushes patches to other MeeGo components at MeeGo.com as necessary (see [[#Upstream_projects,_MeeGo,_products_and_patches|''Upstream projects, MeeGo, products and patches'']] below)
* Creates (or supports the creation of) a MIC kickstart file for building images for their reference HW
* As necessary, supports adding support for their reference HW and SW components in the MeeGo build and release infrastructure tools

==== Trials ====

A lightweight but also more limited "try it out" alternative to the above processes is discussed below.

===== Initial bring-up attempt =====

* Grab an already built root filesystem / image for a MeeGo reference device that's the most closest to your target. For ARMv7 this is typically the Nokia N900 handset image, for Atom, this could be netbook image or handset image.
* Build a Linux kernel for your device and install the modules into /lib/modules.
* Boot the root filesystem and modify the configuration and drop in components to bring up the device to UX. Note down the things you had to modify or add as this will be input for your porting work.

===== Building your first image =====

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.

* Install the MeeGo Image Creator tool (MIC)
* Download the kickstart file (.ks) from the same directory you found your reference device image.
* Create a image using mic-image-creator (should be elaborated).
* Test out your freshly baked image as in previous step.

===== Building your port's first reproduciable image =====

* Download the MeeGo kernel, possibly modifying the kernel with additional patches (including new device drivers) and building the kernel (see [[#Getting_new_chipset_support_to_the_MeeGo_kernel|''Getting new chipset support to the MeeGo kernel'']] below).
* Add the repository containing your kernel package to the kickstart file (to be elaborated)
* Remove parts of the kickstart file specific to the reference device.
* Add a mention of your kernel package in the %packages section.
* Build packages or include shell scripts in %post section of kickstart file that adds/modifies configuration fitting your device.

A detailed description of a variation of this model can be found from [[ARM/Meego on Beagleboard from scratch|here]] (Better description needed).

==== Getting new chipset support to the MeeGo kernel ====

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.

=== Upstream projects, MeeGo, products and patches ===

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 [http://meego.com/about/contribution-guidelines Contribution Guidelines] and [http://meego.com/developers/hardware-enabling-process Hardware Enabling Process] (especially section ''How Do Patches Get Integrated and Accepted?'') and [http://meego.gitorious.org/meego-os-base/kernel-source/blobs/master/README.workflow Kernel workflow].

=== Adaptation subsystems and interfaces ===

In the MeeGo architecture model (see e.g. [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

== Porting by adaptation subsystems ==

=== System Core Adaptation ===

==== Boot ====

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).

==== Kernel fundamentals ====

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:
* HW (board) configuration
* Mapping the fundamental Linux kernel functionality (e.g. IRQ, DMA, GPIO, RTC and memory handling) to the HW in question
* Creation/modification of the necessary device drivers to support the core SoC interfaces (e.g. I2C, SPI, SDIO)
* Permanent memory support
* Debugging and tracing support

==== Power and thermal management ====

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:
* CPU frequency control (support for the different voltage and frequency operating points) via the cpufreq infrastructure
* CPU idle state management (different levels of sleep) through the cpuidle infrastructure
* Clock management through the clock framework
* Suspend/resume
* Runtime power management
* HW voltage/current regulator control via the regulator framework
* PM_QOS (power management quality of service) framework for making and listening to PM QoS requests

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.

==== Energy management ====

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.

==== Device state ====

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|''Power and thermal management'']] section.

=== Security Adaptation ===

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.

=== Device Mode Adaptation ===

==== Resource Policy ====

The Resource (Policy) Manager component in the Device Health subsystem offers a generic framework for:
* Monitoring device and application events
* Managing policies that specify rules about what should happen in the device when certain events occur
* Making policy decisions when events occur (determining the needed changes in the device)
* Enforcing changes in the system through policy enforcement points

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".

==== Mode Control Entity (MCE) ====

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:
* Listening to various keys and switches in the device (e.g. power key, volume key, camera button, slider switch)
* Controlling LEDs
* Touch screen or HW keyboard enabling/disabling depending on device state
* Keyboard backlight control
* Display state (on/off) and brightness control

The MCE has its own plugin architecture that can be used to adapt it to different HW environments.

=== Display and Graphics Adaptation ===

For an overview of the MeeGo visual services architecture, see [http://meego.com/developers/meego-architecture/meego-architecture-domain-view 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.

=== Audio Adaptation ===

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 [http://meego.com/developers/meego-architecture/meego-architecture-domain-view the MeeGo architecture domain view].

=== Camera Adaptation ===

The central pieces of the MeeGo still imaging architecture are the [http://gstreamer.freedesktop.org/ 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.

=== Video and Imaging Adaptation ===

The central pieces of the MeeGo video imaging architecture are the [http://gstreamer.freedesktop.org/ 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:
:* A GStreamer camera source element to be used "inside" the CameraBin element (this is common with still imaging)
:* If HW accelerated codecs are supported, GStreamer elements that wrap the codecs
:* If HW accelerated filters are supported (e.g. video scaler, rotation engines, color conversion engines), GStreamer elements that wrap the filters
:* A GStreamer video sink element that offers the GStreamer X Overlay Interface. Note that if the XVideo extension is supported on the X Server side, the xvimagesink element can be used as the video sink element and no new elements are needed.

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.

=== Communications Adaptation ===

For an overview of the MeeGo communications services architecture, see [http://meego.com/developers/meego-architecture/comms-services Comms Services].

==== Cellular ====

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:
:* oFono modem plugin/driver API
:* Linux network interface for the Linux TCP/IP stack (for data communications)
:* Relevant PulseAudio plugin interfaces for cellular voice call audio handling

For more detailed information about the oFono APIs, see the documentation and source code available at [http://git.kernel.org/?p=network/ofono/ofono.git;a=summary oFono git].

==== USB ====

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.

==== WLAN ====

The MeeGo WLAN architecture is centered on the [http://linuxwireless.org/ 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.

==== Bluetooth ====

The MeeGo Bluetooth architecture is centered on the [http://www.bluez.org/ 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.

=== Location Adaptation ===

The MeeGo location architecture is based on [http://http://labs.trolltech.com/page/Projects/QtMobility| 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 [http://www.freedesktop.org/wiki/Software/GeoClue 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.

=== Sensor Adaptation ===

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|''Power and thermal management'']] section above.

=== Input Adaptation ===

==== Touch ====

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 [http://cgit.freedesktop.org/~whot/inputproto/tree/XI2proto.txt?h=multitouch 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.

==== HW keyboard ====

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.

==== Buttons and switches ====

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.

=== Haptics and Vibra Adaptation ===

==== Haptics ====

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).

==== Vibra (notifications/alerts) ====

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 Adaptation ===

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.

[[Category:Tutorial]]