The Architecture of the Symbian System Model

© 2009 Symbian Foundation1

System Definition PkO training

Part 1:

The architecture of the System Model


Overview

• What is the system model?

• System Model hierarchy• Layers

• Packages

• Collections

• Components

• Relation to the build

• System Models types• Device Model

• Tools Model

• Vendor-specific Models


System Model Structure

The system model reflects the organisation of a modular software stack

•Layers are the fundamental stacking of software• Each layer abstracts the ones below

• Levels within layers group packages by intended audience

•Packages are self-contained technologies• Levels within packages show their internal software stack

•Collections are logical groupings of related components

•Components are the atomic unit of software architecture


Layers

Layers

• Layers contain packages with no upward dependency between layers. • A package may depend on other packages in the same layer or in any lower layer

• A package must not depend on packages in a higher layer

• A package should avoid depending on a package in a higher level of the same layer

• A package in a lower level will have executables with a higher State Domain order

• Public and platform APIs are grouped by layer• Uses layer_LAYER_type_EXPORT_PATH macro

• OS• Public /epoc32/include OS_LAYER_PUBLIC_EXPORT_PATH

• Platform /epoc32/include/platform OS_LAYER_PLATFORM_EXPORT_PATH

• Middleware• Public /epoc32/include/mw MW_LAYER_PUBLIC_EXPORT_PATH

• Platform /epoc32/include/platform/mw MW_LAYER_PLATFORM_EXPORT_PATH

• Applications• Public /epoc32/include/app APP_LAYER_PUBLIC_EXPORT_PATH

• Platform /epoc32/include/platform/app APP_LAYER_PLATFORM_EXPORT_PATH


Layers

Evolution

• Technologies migrate between layers over time

• “Commoditised” technologies move downward as their use becomes more generic

Example: HTTP was a technology specific to web browsers (applications), but is now a widely-used generic protocol (middleware)

• Legacy technologies move upward as fewer types of applications use them

Example: Older Connectivity Transports (e.g. Psion Link Protocol) have been moving upwards over time as they are less used

• Packages should be introduced at the highest reasonable layer to perform their function

• This limits the dependencies on new technologies and reduces the overall risk to the system


Layers

Foundation Layers

• Three Symbian Foundation Device layers:OS, Middleware and Applications

• Additional layers may be added with Architecture Council approval

• Vendors may add their own layers if needed• Vendor’s layers can only contain non-contributed, vendor-specific packages

• Three Symbian Foundation Tools layers: Development, Analysis and Deployment

OS

Middleware

Applications

Analysis

Deployment

Development


LayersFoundation Device layers:OS

• Provides APIs that abstract the hardware platform• Allowing higher layers to be isolated from hardware

changes

• Contains lower-level APIs that are not hardware abstractions, but are used within the OS layer

• Sufficient to develop a test platform• Two levels:

• hw: The kernel, interfaces to the hardware and user-side services• This level is sufficient to be an operating system (filesystems, essential drivers,

program execution model)• Board Support package uses KSM2HALDomainn System State Domain• Other packages use KSM2KernelServicesDomainn System State Domain

• services: Essential services necessary for a phone• Contains communications, text and data handling, graphics, etc• Equivalent to KSM2OSServicesDomainn System State Domain


LayersFoundation Device layers:Middleware

• Provides higher-level generic APIs usableby programs in the application layer

• Includes native UI frameworks, application lifecycle, higher-level protocols and data handling, etc

• Middleware components are independent of the hardware platform• MW APIs are not used by the OS layer

• Two levels:• generic: Services intended for any class of application

Examples: Text entry, security and GUI widgets are expected to be used by most apps

• This level and below is a general purpose computer• Equivalent to KSM2GenMiddlewareDomainn System State Domain

• specific: Services intended for a specific class of applicationExamples: Presence is mainly used by instant messaging apps, the Phone Server

is expected to only be used by a Phone application• This level and below is sufficient for phone application development• Equivalent to KSM2AppServicesDomainn System State Domain


LayersFoundation Device layers: Applications

• Primarily contains interactive UI applications

• Includes non-interactive applications (daemons) thatrespond to events from other than the device user (e.g. from a PC).

• Two levels:• services: Non-interactive applications, services provided to other packages

• This level and below is sufficient to create applications which work together

• Equivalent to KSM2UiServicesDomainn System State Domain

• apps: Applications which interact with the user• This level and below is the full set of software on the device

• Equivalent to KSM2UiApplicationDomainn System State Domain

• Packages which span both levels provide user-facing applications and services to other applications.

Example: Contacts Apps provides the user-facing Phonebook application, plus the Contact Model which has an API for programmatically accessing contacts.


Layers

Foundation Tools Layers

• Development• Tools for editing, building, running and debugging• Contains supporting run-time environments

• Analysis• Tools required to perform static and run-time validation

of the platform and performance optimisation

• Deployment• Tools and data files supporting the creation of

deliverables and distributions of Symbian OS and its associated tools

• All Tools layers have the same three levels:• Device Tools (dev): Device based tools providing a direct

interface onto platform or public interfaces to support tools use-cases

• Host Middleware Tools (mdw): Non-Eclipse based host tools providing a programmatic or command line interface to higher level tools within the same or upper levels or generic non Eclipse based middleware

• Host Eclipse Tools (ecl): Eclipse based tools providing an IDE-integrated UI component, a command line interface or generic Eclipse based middleware

Dev

elo

pm

ent

device

middleware

eclipse

An

alys

is

device

middleware

eclipse

Dep

loym

ent

middleware

eclipse


Packages

Packages

• A modular group of component collections that is sufficient to develop, build, and test a technology

• A high-level application or application suite, e.g. Phone Apps, Messaging Apps• Services with a common or interrelated code base, e.g. Security Services, Input

Methods• A core technology, e.g. Graphics, Networking Services

• Packages are the basic unit of Symbian Foundation organisational control• Package scope and model location is agreed with the Foundation Architecture council

• Packages are owned and maintained by a package owner (PkO)• PkO has overall responsibility for the package and its contents• Contributions also come from the wider Symbian Foundation community

• A package belongs to a single technology domain – a vertical grouping of related packages

gene

ric

gene

ric

gene

ric

gene

ric

com

ms

com

ms

com

ms

com

ms

UIUI

UIUI


Packages

Evolution

Packages split or combine over time

• Generic technologies split when they gain sufficient “mass” over time to warrant their own package.

• New technologies tend to start development in the generic packages: Generic App Support, Generic OS Services.

• This avoids the overhead of creating a package for a technology with an unclear future

Example: Device Services split out of Generic OS Services

• Subtechnologies split when large or sufficientlyself-contained enough to be developed separately

Example: Shortlink Services split into Bluetooth and USB

Generic OS

Services

Persistent Data Services

OS Security

Device Service

s

Blue-tooth

USB

Short Link

Services


Packages

Package Levels (Device Model)

• Package’s internal software stack described with levels• Lowest provides interface to hardware or layers below• Highest provides, UIs, APIs, metadata and documentation• Mid-levels tend to be frameworks, engines, servers, plugins, internal tools, etc

• Meaning differs between layersBy convention, packages in the same layer and level have roughly the same

number of internal levels• OS Layer, hw level: ≤5 levels. Bottom level reserved for development boards.• OS Layer, services level: ≤6 levels. Bottom level reserved for device drivers• Middleware Layer, generic level: ≤6 levels• Middleware Layer, specific level: ≤5 levels. UI, if any, on top level• App Layer, services level: ≤4 levels• App Layer, apps level: ≤4 levels.

• Spanning packages ≤8 levels• Applications and UIs on top level, frameworks and engines below, plugins and other

support on bottom (guidelines, not binding)


Packages

Package Levels (Tools Model)

• All Tools packages have the same sets of levels:

• UI - UI centric (e.g. editors, viewers, etc.)

• Framework - provides an extensible development infrastructure

• Middleware - provides standard functionality to be used by a number of higher level components

• Lowlevel-libs – provides low level functionality such as device drivers or generic support libraries such as mathlib.


Collections

Collections

• A coherent set of collaborating components which together deliver a complete, discrete, and identifiable part of the system functionality

• Components in a collection will generally be strongly coupled or implement the same interface (e.g. a family of plugins)

• A component with no strong ties in the package can live alone in itscollection

• Collections can group components to reflect ……the software or communication stack

…a sub-technology of functionality

• Collections are stacked in levels• The primary package exposed interfaces are on the top

• The interface to lower layers or hardware are on bottom

• Middle levels tend to reflect dependencies and technology-specific relationships


Collections

Conventions (1/2)

•Documentation which describes ……a single component should be contained within the component

…multiple components in a collection should live in that collection

…an entire package should live in the “package_info” collection

•Tests which cover……a single component should be contained as PRJ_TESTMMPFILES in

that component

…multiple components in a collection should live in that collection

…API tests for a package should live in a “packageapitest” collection which appears at the top level in the package

…integration, validation or other test suites can live in a collection with the components they test, or live in a test collection at the same level (or higher) as the highest level collection they test


Collections

Conventions (2/2)

• A family of plugin components can live in……the same collection as their framework to emphasise their

relationship

…a separate collection if the framework is in another package

…a separate collection below the framework if callers need to know about the framework, but not what plugin is used (i.e. the framework selects and loads the plugins)

…a separate collection above the framework if callers need to know about the plugins, (i.e. caller selects and loads the plugins )

• Configuration components should live……in the same collection as the component(s) they configure

• Interface components can live……with their components in the same collection (Symbian-style)

They are separate from the implementation mainly for licensing / legal reasons

…in package_plat or package_pub components in the package_info collection (S60-style)


Components

Components

• The smallest architectural entity of the system. A component is an implementation unit that provides a discrete, re-usable piece of the

system. In concrete terms, a component is identified with a single MRP or bld.inf file that packages binaries, data, tests, documentation and source code.

• Build and packaging data• Information provided to build or configuration tools to allow a system-wide, package-

wide or subsystem build• Bld.inf location (building)• MRP file location (CBR packaging)• Filters (configuration)

• Informative dataInformation provided for documentation or analysis purposes• Age• What devices this can should or must appear it• Intended target (ie device or desktop)• Class of contents (ie, what is in it)


Components

Release data

• Introduced• The release number when the component was first produced

• Older are Symbian-release based (ER5, 6.0, 7.0s, 8.1b, 9.5, etc)• Newer use Foundation release (^2, ^3, etc)

• “Future” indicates a component ready for system-wide testing, but not in any official release

• If not identified, the age of the component is unknown• Why do we need it?

• To give an idea of the maturity of the component and to easily identify what is new• Non-trivial to determined by codeline analysis, especially for older components

• Deprecated• The release number when the component was first deprecated (like “introduced” above)

• Deprecated components are ones that are provided for backwards compatibility or developer convenience

• All deprecated components should be documented with an alternative for developers

• Why do we need it?• To identify components that are on their way out and should be avoided• Not all cases can be determined by scanning Doxygen comments


Components

Purpose

The “purpose” identifies where and how a component can be used • Used to communicate usage with Foundation developers• Cannot be deduced from the source code

• Mandatory • Provides core functionality for a package• Strongly recommended for all

commercial devices• Mandatory cannot depend on optional• Components not contributed or made

available to Foundation can’t be mandatory• Why is this needed?

• Indicates to developers which DLLs their code can statically link against

• Optional • Production quality and can be used on commercial devices or end-user's desktop• Includes development tools for third party developers which can appear on a

commercial device• DLLs should be dynamically linked against• Why is this needed?

• Indicates to developers which DLLs need runtime or installation-time testing for presence

• Development • For development (R&D) use only• Must not appear on a commercial device

• Generally either not production quality or may have significant security risks

• Most tests fall into this category• Also tools necessary for building, but not

shipping, a device. • Why is this needed?

• To avoid having devices ship with substandard or dangerous software


Components

Target

The target identifies where the component's deliverables are intended to be used• Device

• At least some deliverables are used on a device • Can be test or production

• A component with both device and desktop deliverables should be classed as “device”Example: a component with scripts used for building device binaries

• Why is this needed?• The target gives an idea of how much “mass” in the system is oriented for device vs desktop• “device” is the default for components, so it does not need to be explicitly stated

• Desktop • The deliverables are intended to be installed or run on a desktop/host-side• Usually build tools used on a developer's desktop• Also includes deliverables intended for an end-user's desktop

Example: end-user documentation or a desktop suite• Why is this needed?

• At this point, this cannot be trivially determined from source, but may be able to in the future

• Other • Any other categories do not adequately describe the component's intended target• Why is this needed?

• In case this does not cover a future situation


Components

Classes

The Class is a set of standard informational tags which indicate functional properties

• A component can have any number of classes• Informative, as opposed to build-related properties which are captured by filters

• Tool (“tool” in the system definition)• Component contains only tools

• A component which happens to have tools to help build or test it does not count• It must be a component which contains TOOLS or TOOLS2 as the targets in the bld.inf

• Why is this needed?• This makes it easy to differentiate between tools and tests• Currently manually specified, this may be automatable in the future

• API (“api” in the system definition)• Component contains only header files or other interface specifications

• Used throughout ex-S60 code to enforce control of APIs • Also used when the interface and implementation have different licenses

• An API component will not contain any binaries• Binaries are provided by one or more other components• …or not at all, if it is expected that a downstream vendor will provide them

• Why is this needed?• Identifies where the component’s implementation is physically separate from the

exposed interface• Currently manually specified, this may be automatable in the future


Components

Documentation class

• Contains only documentation• Documentation for a single component should live in that component• Documentation that describes how sets of components interact can live in the same

collection as a separate component• Package-wide documentation should live in a component in the “Package-name Info”

collection• Component should be called “Package-name Documentation”

• Uses the “doc” class in the system definition• The “target” identifies where the documentation is used

• i.e. on the device or on a desktop

• The “purpose” should match the purpose of what is being documentedExample: If it’s documenting mandatory components, purpose should be mandatoryExample: If it’s documenting tests, the purpose should be development

• Why is this needed?• While it is easy to detect if a component contains only data files, it is not always

clear what the files are for• Makes it easier to identify and collect documentation for developers


Components

Configuration class

• Contains configuration files used by another component

• Configuration components are used……to facilitate customisation by downstream vendors or developers

…if the binaries are mandatory but the configuration is not

…if the configuration files are encumbered by 3rd party IP

• Non-production configuration files can also live in the component as test exports

• Uses the “config” class in the system definition

• Why is this needed?• This highlights the configurable parts of the system


Components

Plugin ClassAn atomic set of binaries exposing a standard interface defined outside the component

• The component’s main purpose is to implement the interface• Components which happen to contains plugins to do a larger task are not considered plugins

• The plugin’s framework must be in a separate component

• Plugins should only be separate from the framework when there is a logical reason• The plugin is expected to be removed, extended or replaced outside of the component• If the framework is mandatory but the plugins are not• If the plugins are encumbered by 3rd party IP

• A framework should not expose internal plugins• The fact that plugins are used inside the component is invisible to the rest of the system• Exposing the plugin constrains the design and will do more harm than good

• Plugins must be atomic (like all components)• Plugin components can contain binaries that are used solely or primarily by the plugin

Example: A set of plugins plus a set of DLLs that provide utilities for itExample: A client/server plus a plugin the requires them to work

• Consider creating a single component for multiple plugins with the same interface…or group into components based on usage or functionality

• A plugin must contain a binary• A configuration component is not a plugin

• Uses the “plugin” class in the system definition• Why is this needed?

• This highlights parts of the system which may need additions / alterations when creating a device


Components

Build and packaging data

• The unit describes how to find and build a component• Units are not architectural entities

• <unit> is the XML element which describes how to build the component

• A component can have only a single unit for a specific build• Components with multiple units must be filtered or otherwise processed

to only use one of them at build time

• Configuration of builds is still being defined

• For the time being stick to the one unit per component rule

• Units serve four purposes• Configuration

• Building

• Defining content

• Importing external components


Components

Configuration

• Simple configuration can turn on or off units (and components) in a build• Usage likely to change in the future as Foundation configuration tools mature• Two mechanisms are provided in the system definition:• Filters are global identifiers that are used to remove anything that contains that filter

• Used on only components and units• Intended to allow filtering based on device/product/build phase/etc

Example: Components / units with filter="techview" are ignored unless techview filter is explicitly requested

• Requires filter-aware tools to do the processing (e.g. genxml, filtering.xsl)• Why is this needed?

• Filters provide a way to easily turn on or off large numbers of components when building

• Version numbers are provided for external tools to select one of a set of units• Versions are used when a component undergoes major change that cannot be easily configured

within the component• Alternative bld.inf (and MRP) files are selected by associating each with a version number

• Requires version-aware tools to do the processing (e.g. variability tools)• Versions are not actively currently used• Why is this needed?

• Version numbers allow each unit to have a unique way to identify it without requiring a globally unique ID• Versioning units allows the component to remain invariant to major changes in its content


Components

Building

•The unit provides the location of the bld.inf, which describes how to build a component

•Not every component needs a bld.inf• Data-only components

• ie, anything which does not build or export anything

•Why is this needed?• The build system uses the system definition to generate a set of

bld.infs to process


Components

Defining contents

• Units provide mechanisms for identifying what files are owned by a component• Used to analyse metrics on data/code/etc to whole components (and higher rank items)• Used to tell packaging tool how to wrap up a component for self-contained delivery

• The Symbian CBR tools use the sysdef to determine the contents of the OS• Anything not owned by a component is not part of the system• All unowned files are removed before building

• Three mechanisms for defining content:• MRP files: Explicitly describes all content and deliverables

• Classifies content by type: source, binaries, exports, test binaries and test exports• Identifies source by IPR code• Legacy mechanism used by CBR tools.

• Implicit: All files in a component’s “ID path” are owned by that component• ID path = directory made up from layer/package/collection/component • Not valid in a large number of cases

• Base: specifies component’s root directory • Everything under component’s base is owned by the component

• Why is this needed?• Analysing architectural entities requires knowing what component all files in the OS

belong to• This provides a back-up for components that don’t map to their ID path


Components

Importing

•A pre-built component is one that is not in the codeline, but is needed for a build

• Binaries and exports are imported before the OS is built

…or after, so binaries can be put in a ROM

•Currently only works for importing CBR components

•Used in Device codeline to import Tools codeline components

•Why is this needed?• Dependencies on other codelines can be included without needing

to rebuild the code


Relationship between models

• Device and Tools models• Device Tools

• Device cannot statically link or #include Tools

• Device can be built using Tools

• Tools Device• Tools can statically link and

#include public/platform Device components

• Foundation and Vendor models• Foundation model cannot depend

on vendor-specific components

• Vendor components can only depend on upstream models

• A vendor’s components can depend on Foundation components

• A vendor should control their dependency on components from other vendors

OS

Middleware

Applications

Analysis

Deployment

Development

Valid deps

Invalid deps

Device model Tools model

Vendor Models

Valid

deps

Invalid

deps

Valid

deps

Invalid

deps


Why?

• Why do we need a system definition?• So we have a definitive list of what the contents of the system are. Since the same

data is used for building, architecture, documentation and analysis we can ensure consistency and accuracy

• Why do we need layers and packages?• Layers and packages keep the system clean and modular. The rules are testable and

guidelines make development more straightforward.• Why do we need collections? Why 4 hierarchical entities?

• To ensure the system is understandable by humans. Each rank of entity is expected to contain on the order of 10 entities, meaning that a person can comprehend a system of over 2000 components.

• Collections also provide a way of organising and describing a package’s internal structure, making the package appear as more than just a black box to outsiders

• Why does the system need to be understandable?• Mainly to keep track of what we have and avoid losing or duplicating code and

functionality that already exists• It’s also a very useful “big picture” introduction to the system, and a good way to

represent analyses• Why XML?

• It’s a widely supported standard that’s both human and machine readable


System Model Resources

• About the System Model

http://developer.symbian.org/wiki/index.php/Symbian_System_Model

• System Definition specification

http://developer.symbian.org/wiki/index.php/System_Definition

• Foundation software organisation

http://developer.symbian.org/wiki/index.php/Software_Structuring_Principles

• Foundation Packages

http://developer.symbian.org/main/source/packages/index.php

• Foundation Technology Domains

http://developer.symbian.org/main/source/technology_domains/index.php

• PkO Training Material

Part 2: System Definition XML syntax

Part 3: Using the System Definition



http://developer.symbian.org/wiki/index.php/System_Definition

http://developer.symbian.org/wiki/index.php/Software_Structuring_Principles



http://developer.symbian.org/main/source/technology_domains/index.php

The Architecture of the Symbian System Model

Documents

file system

root system definition

master system definition

single system definition

tools system definition

downstream system definition

terms system definition

system definition xml