System Definition PkO

training

Part 3:
Using the system
definition
Overview of Using the system definition
Operations Lifecycle
• Validating • The root system definition
(for Integration + Chief Architects)
• Joining
• Package definitions
• Merging (for package owners and delegates)
• Configuring • Lifecycle operations
• Creating
• Building
• Changing
• Packaging • Deprecating
• Modelling • Removing

Copyright © 2009 Symbian Foundation

 System Model
Operations

Copyright © 2009 Symbian Foundation

 System Model Operations
Editing and Validating
• Edit in any text or XML editor • Validating syntax
validate-sysdef.xsl
• Your favourite plain text editor
• XML: Fatal error on invalid XML
• Any XML editor will do • Sysdef syntax: unrecognised/misplaced attributes and
elements + checks attribute values
• Eclipse WTP XML plugin works well
• Foundation conventions: Checks paths and tech domains
• Simple validation
• Load in any web browser • Validating presence of unit files
checklinks.pl
• Thorough validation
• Checks relative paths in all <unit> elements
• Run on system_definition.xml or
package_definition.xml files
• Follows and tests all linked
sysdef fragments
• Available in
/os/buildtools/bldsystemtools/sysdeftools/validate

Copyright © 2009 Symbian Foundation

 System Model Operations
Pre-build operations:
joining, merging and downgrading
1. Join sysdef fragments
Foundation Vendor 1 Vendor 2
2. Merge with vendor
sysdef(s) sys
def
pkg
defs
sys
def
pkg
defs
sys
def
pkg
defs

3. Downgrade for use by

older tools join join join

Vendor 2
SF Vendor 1

3.0.0 3.0.0 3.0.0

Sysdef Sysdef Sysdef
merge

Full Full SF + vnd1 merge

2.0.1 downgrade 3.0.0
Sysdef Sysdef SF+vnd1
merge
+vnd2
more…
(for older tools) (for newer tools)

Copyright © 2009 Symbian Foundation

 System Model Operations
Joining
• Joining embeds all linked system definition fragments into a single system definition
file
• All unit relative paths are translated into absolute paths
• All href attributes are replaced by the linked content
on ent
r a ge ct i
po n
e ck lle m
lay pa co co
• Requires /os/deviceplatformrelease/foundation_system/system_model/system_definition.xml
1. The root system definition file to be joined
2. The system model path for the root system definition
+
../../../ossrv/package_definition.xml
•
•
Needed to generate the units absolute paths
Allows sysdef file to be built regardless of where it’s
+
genericopenlibs/cstdlib/group
stored on the local filesystem
3. The filename to save the result in
=
/os/ossrv/genericopenlibs/cstdlib/group

• Joining a stand-alone system definition has no effect

• It’s an Identity transformation
Copyright © 2009 Symbian Foundation
 System Model Operations
Merging

s
cie
Vendor

en
nd
pe
downstream

de
• Merging combines two system
definitions into a single
Foundation

es
combined one

ci
en
upstream

nd
• Can also be used to identify

pe
de
changes between two sysdefs
• Requires
1. One upstream stand-alone system definition file (eg the Foundation sysdef)
2. One downstream stand-alone system definition file (eg a vendor sysdef)
3. The filename to save the result in
• An origin-model attribute is added to every component identifying which model it came from
• Components from the upstream model use the upstream system model name
• Components added to the upstream model use the downstream system model name
• Components in both use the upstream system model name
• If both models have the same name, “Upstream” and “Downstream” are used (can be overridden)
• Merging a sysdef with itself will only add origin-model attributes
• Cannot merge pkgdefs (yet)

Copyright © 2009 Symbian Foundation

 System Model Operations
Downgrading
• Most tools require 2.0.1 or older sysdef syntaxes
• Including raptor and genxml
• The 3.0.0 syntax can be automatically translated into the 2.0.1 syntax
• Downgrades the syntax and joins any linked fragments
• tech-domain attribute and meta elements are removed
• id attribute becomes name
• name attribute becomes long-name
• ID namespace prefixes from the root document are used
• Common uses
• Downgrade the root Foundation system definition
• Downgrade a single package definition
• Downgrade a previously-merged stand-alone Foundation + vendor system definition
• Requires
1. The system definition file to be downgraded (stand-alone, root or fragment)
2. The 2.0 style system model path for the system definition (ie does not begin with /)
• Needed to generate the units’ absolute paths
• Not needed when transforming a stand-alone sysdef
3. The filename to save the result in
• Optional
• Root variables (ie SRCROOT and others) can be set to generate 2.0 style absolute paths needed for cross-filesystem
building

Copyright © 2009 Symbian Foundation

 System Model Operations
Configuring build_SFPhase4

Filters used in tools model

• Basic configuration is done via filters
• Divides the system into large sets of components
• Majority of the system has no filters build_SFPhase
• Controls inclusion in specific types of build 2
• By platform type (gt, techview) build_SFPhase3
• By production type (test, systemtest)
• Build order (build_SFPhase1, build_SFPhase2, etc)
Build_SFPhase1

techview
test

gt
systemtest

Filters used in device model

Copyright © 2009 Symbian Foundation

 System Model Operations
Building from the system definition
Building generates the “buildable” parts of the system from a subset or all bld.inf files in
the system definition file
• Three types of sysdef-based builds:
1. Full System build
• Build everything in the entire system from scratch
2. Part System build
• Build only a specific part of the system
• Foundation-only build
• Vendor-only build
• Requires Foundation build already in the environment
• Layer-only build
• Requires existing environment if not building the bottom layer
3. Package (sub-system) build
• Build just a single package on top of existing environment

Copyright © 2009 Symbian Foundation

 System Model Operations
Packaging
• Component Based Release (CBR) tools package-up and deliver individual components
• Component definition file (MRP) linked from unit’s mrp attribute

• MRP file used to package source code, exports and binaries into CBR packages

• Flat list of MRP files extracted from release’s System Definition using genxml

• CBR packages can then be downloaded to generate a build environment

• Vendors not using CBR do not need to link MRP files from the units

Copyright © 2009 Symbian Foundation

 System Model Operations
Modelling
• Modelling renders the system definition as a system model diagram
• SVG format = more detail than static images (Jpeg, PNG, etc)
• Viewable in most
web browsers

• Found in Tools packages:

• Command line System Model Generator in swconfigmdw
• Eclipse plugin System Model Manager in swconfigapps
• Command line use: Optional ini file
Location to save configuration Sysdef file
generated SVG to draw
sysmodelgen -o %OUT%\mymodel.svg -i config.ini
-sysdef os\deviceplatformrelease\foundation_system\system_model\system_definition.xml
… various other options …
Additional configuration
Copyright © 2009 Symbian Foundation (overrides ini file)
 System Model
Lifecycle

Copyright © 2009 Symbian Foundation

 System Model Lifecycle
The root system definition
The root system definition is a skeleton which describes the overall structure of the system,
but with none of the package content
• Contains:
Video File Convers Instant Image Video Video Music Voice Screen Home
Location Push to IP Email Utility Camera Gallery Video Radio Recorder

• Layers
Telephony Manager ation Msg. Editor Editor Player Photos Player Saver Screen Profiles
Apps Talk Telephony Apps Apps Apps Apps Center Apps

Applications
Apps Apps Apps Apps Apps Apps Apps Apps Apps Apps Apps
Phone Contacts Organizer Messa- Help Techview
Apps Apps App Suite ing Apps Apps
Multimedia Settings Content Device Image Graphic Speech Home Conn R&D
Sharing Control Control Printing Dictionary Viewer Recog- Screen Web UIs Java
UIs UIs Daemons Daemons UIs s UIs nition UIs Tools Tools tools

(3 layers) Location Wireless VPN IP App

Telepho Messa- Instant
ny & ing Msg. &
Legacy Open Remote DLNA Image Meta-
Legacy Meta- Multi-
media
Multi-
Video Camera media Home
Service
API Service
Presence Manage- data Screen Web UI Tools
Services Access Client Services SIM Middl- Presence Services Services ment Services Handling data Services UI Utils Services App Services Fram- API

• Packages
Services ware Srvs. Services Fmwk. Fmwk. work
Middleware

General
Generic IP High- Networ- Remote Service Multi- UI UI Settings App
Security Access Connec- level IP App ing De- Remote Bluetooth USB media Input Classic SVG Haptics Web Platform
App DRM Storage Connec-
Discovery Accelera Resourc Services & Installati Services Tools
Support Services Security ivity ice & Usage Services Services Middle- Methods UI Tiny
Internet Protocols
ivity ware tor es Profiles on
Mgmt. Protocols Mgmt.
(100+ packages) Srvs.

Generic OS Persistent Device Locating Comms Networ- Cellular Multime Imaging Graphics Text & XML Device OS R&D

• Layer levels
OS Data Fram- ing WLAN Baseband Bluetooth USB Localisat Platform
Services Security Services Services Services work Services Srvs. dia Ext. ion Srvs. Services Release tools
OS

Kernel & Board Build

(2 levels per layer)

Hardware
Services Support Tools

• package technology domains (package colour)

• Maintained centrally between Architecture and Integration

• Architecture Council responsible for content
• Integration responsible for ensuring the build-ability of the
system_defintion.xml file

Copyright © 2009 Symbian Foundation

 System Model Lifecycle
Authority for decisions
• Layers and packages
• All changes to the layers and packages must go through the Foundation Architecture
Council
• Introduction of new vendor-only layers or packages should be approved by the impacted chief architects
(or local equivalent) within the organisation
• Package internals
• The Package Owner (PkO) is ultimately responsible for their package
• All changes entirely within a package must have PkO approval
• Introduction of new components should be reviewed for system-wide impact by other architects in the
PkO’s organisation or the Foundation community
• Ensures consistency of component concept between packages
• Avoids duplication of existing functionality
• Between packages
• Movement of components between packages must have agreement of both package
owners
• Foundation Architecture Council must be informed via Architectural Change Request
• AC must be aware of package dependency changes due to move

Copyright © 2009 Symbian Foundation

 System Model Lifecycle
Root system definition changes
• System definition changes that need to be approved by the
Foundation Architecture Council:
• Changing a layer (new layer, removing a layer, changing layer levels)
• Creating, removing, significantly altering a package
• Deprecating, combining or splitting packages
• These changes are done by an Architectural Change Request

• Package changes must also be agreed with all impacted Package Owners
• Changing a package’s technology domain must be agreed with the Package Owner and
Technology Manager
• The Architecture Council has final authority on technology domain changes
• Internal changes only require Foundation approval when there is external impact

Copyright © 2009 Symbian Foundation

 System Model Lifecycle
Package creation
• Packages require effort to approve, create and ongoing work to maintain
• Avoid creating packages unless there is actual need

• Is there an existing place for it?

• Is it tightly coupled to existing technology?
• Consider living in that package
• Is this just the first piece of work for a new technology?
• Consider adding to a generic package (e.g. ossrv, appsupport) and moving later
• Depends on how specialised the development knowledge is and how much effort it is to maintain

• It this a technology’s first foray into a new layer?

• Is it based on a low-layer technology but requires use of a high-layer
package?
• Consider adding to that high-layer package

Copyright © 2009 Symbian Foundation

 System Model Lifecycle
Package creation checklist
• What is the intent of the package? • What does it depend upon?
• Without a solid definition, it’s unclear what will • The dependencies identify the lowest layer the
go in the package and how much effort it will be package can be in
to maintain • What layer is it in?
• What technology domain it is? • The layer limits the functionality available to
• This tells what other packages this is related to the package. If too low, future features may
and who is responsible for the future roadmap require a new package. If too high, features
• What is its name? might not be available to other technologies
• The name provides a first order approximation of • What level in the layer?
its function and advertises its existence to your • The layer’s level indicates the intended
organisation and the Foundation community audience of the package and as well as its
• Package names must make sense when taken out System State Domain
of context • Who is the package owner?
• What is its ID? • The owner must be in a Foundation member
• The ID is a globally-unique abbreviated form of organisation
the name. It’s used for its base directory name • When will it be first delivered?
and for tools to reference the package
• The Foundation needs to be aware of the
contents of its releases

Copyright © 2009 Symbian Foundation

 System Model Lifecycle
Splitting and combining packages
Short
Bluetooth BT Link

• Packages split or combine over time API Tests Comms Services

Profiles
Info

Host USB

• Split when parts gain sufficient “mass” over time to

Contrllr. Manage
Interface ment

warrant their own roadmap Bluetooth

BT
Comms Bluetooth
API Tests
Bluetooth
Info
USB Info
Profiles

• Equivalent to removing one package and creating two Bluetooth

Manage
ment
IrDA
Host USB

new packages
Contrllr. Manage
Short Link Interface ment

Services Bluetooth
Core

• Combine when separate packages prove easier to Bluetooth

Manage
ment
IrDA

maintain together
Bluetooth USB
• Less common than splitting
• Equivalent to removing one package and moving code
between packages

• Both require Architecture Council approval and

Package Owner agreement

Copyright © 2009 Symbian Foundation

 System Model Lifecycle
Package definitions
• Package definition describes internal content and structure of a package
• Specifies how that package is built
• Owned and maintained by the Package owner or their delegates
• Contains: Flash Lite Open Env. Generic App Support

specific
API 3.1 Utilities Info

• Components Flash
Viewer
Fmwk.
Com-
mand
Shell
Telnet
Server
Generic
App
Support
Platform
Generic
App
Support
Public
Interfaces Interfaces
Generic
App
Support
Metadata

HW Rsc. Printing App. Launch

generic
Adaptation Support Services
HW Printing After
Resource Market App

• Collections
Manager UI App Launch
UI Plugin Support Starter Plugins

Core App UIs File Handling

server
Sensor
NSPS Restore Restore Acces- Key Advance Power General GS GS
Data Core File HTML to RichText
Factory Factory System Variated sory FW Event Server
Database
Recovery WS d TSP Save Settings Server Compen- App UIs Cnvrter. RichText to HTML
Plugin Settings Settings App Settings UI Frame- Contrllr. Utilities Server Engine Engine sator Test Fmwk. Cnvrter. Cnvrter.
Plugins Notifier work Stub Plugin

• Internal package levels

plugin framework
Context Framework Common App Services App Framework

Context Context Context Alarm Core App Backup App

Alarm
Frame- Fmwk. Fmwk. Server Server Apps Services Restore
Notific-
App. View
Server
UIF Test
Fmwk.
work Plugins Build Test Test Docs Arch.
ation

Media Keys Time Zone Services Content Time Zone

• Package’s name Key
Publi- MM Key Media Time Time
Zone
Time
Zone Time
Zone
Handling
Web
PC Side
Time
Zone
Zone Localiz- Recog-
sher Bearer Keys Localiz- ation Databas Compile
Build Server Resource nisers
Plugin ation e r
Factory

System Rsc. Startup Services System

system
Monitoring Settings

OOD Startup Startup GS GS

OOM Splash Sensor
Monitor Monitor App Screen Anim- Accessory
ation Plugin Plugin

Generic Application Support

Copyright © 2009 Symbian Foundation

 System Model Lifecycle
Checklist for creating new items
• What is the name?
• All names must make sense to
someone not familiar with
Symbian OS, but familiar with mobile technology
• Does the ID need a namespace?
• The ID namespace must match the owner
• Is the name unique?
• Use Foundation namespace (the default) for all
• The name should be unique –
Foundation items
duplicate names risk confusion
• Use own namespace for vendor-only, non-
• What is the ID? contributed items
• The ID must be an obvious abbreviation
• Where will the item go?
of the human-readable name
• When there is more than one potential location
• The ID should be as brief as possible to
for a new item, use the option that will make
avoid path-length-related build problems
the structure easier to understand
• Is the ID unique? • ie, when all technical options are equal, always
• The ID must be unique – duplicate IDs will break a place to show the most clarity
build

Copyright © 2009 Symbian Foundation

 System Model Lifecycle
Collection creation checklist
• What is the collection’s name?
• Collection names should make sense to someone familiar with the
technology
• What is the intent of the collection?
• Does the collection contain tightly coupled interacting components?
• Does it contain a family of plugins to the same framework?
• Is it a grab bag of tests or configurations?
• All collections define the scope of what belong in them
• What level is the collection on?
• The level indicates the collection’s position in the package’s stack.
The ordered list of available levels are specified in <package levels="…">
• Identifying the levels may help break down the package into sensible collections

Copyright © 2009 Symbian Foundation

 System Model Lifecycle
Component creation checklist
• What is the component’s name? • What class of component is it?
• Internal acronyms and jargon are • Does it provide a plugin?
acceptable if it makes sense in the • Does it configure another component?
context of the collection name
• Does it only contain APIs and no
• Where should the component be used? implementation?
• Developers can rely on mandatory components • Does it contain only documentation?
being present on all Foundation-based devices
• The class helps identify the intended use of
• Developers must test for the presence of optional component at a high level
components if they wish to use them
• Does it have any special build requirements?
• OEMs must not ship a device with any
development components • The filter controls the type of build the
component is included in
• Which (Foundation or internal) release is this to be
introduced in?
• Identifying when a component is first available
makes it easier to track the difference between
releases

Copyright © 2009 Symbian Foundation

 System Model Lifecycle
Deprecating Components
• Deprecation advertises that users should switch to an alternative implementation
• Should document the alternatives:
• In component documentation
• Via Doxygen comments in source code
Version
• Via comment in package_definition.xml
number
• How to deprecate a component
• Use deprecated="…" in package_definition.xml
• Example: <component id="featureregistry" name="Feature Registry" deprecated="^3"…>
• Use @deprecated Doxygen tag in source code
• Example:
/**
* ...
* @deprecated
*/
EXPORT_C TInt RFeatureRegistry::Open()

• Note: packages and collections can be deprecated by deprecating all their contained components

Copyright © 2009 Symbian Foundation

 System Model Lifecycle
Removing items
• Saves development effort
• Should deprecate first
• Requires Architecture Council approval
• May require a compatibility break approval

Remote Backup & Remote Backup & Remote Backup &

Connectivity Info Connectivity Info Connectivity Info
Restore Restore Restore
Remote Remote Remote
Connectiv Remote Connectiv Remote Backup
Connectiv Remote
Backup
Connectiv Backup Backup ity Connectiv Backup ity Connectiv Backup
ity Engine ity Engine Test
Platform ity Engine Test Platform ity Test Platform
Interfaces Metadata Interfaces Metadata Interfaces Metadata

MTP Data Connectivity OBEX MTP Data Connectivity OBEX MTP Data OBEX
Providers PC Side Providers PC Side Providers
MTP File OBEX MTP File OBEX MTP File OBEX
Chat OBEX Chat OBEX OBEX
& Folder Extension & Folder Extension & Folder Protocol Extension
Provider Scripts Protocol Provider Scripts Protocol Provider API
API API

USB Function USB Function

Drivers Drivers

Mass
Storage
Manager
deprecate Mass
Storage
Manager
remove Remote
Connectivity
Connectivity MTP Connectivity Connectivity MTP Connectivity Connectivity MTP
Modules Frameworks Device FW Modules Frameworks Device FW Modules Frameworks
Service Connect- Connect- Service Connect- Connect- Service
MTP MTP Integ MTP MTP Integ Control- MTP MTP Integ
Control- ivity ivity Control- ivity ivity Fmwks
Fmwrks Test Fmwks Test lers Test
lers Fmwk. Services lers Fmwk. Services

Connectivity MTP Transports Connectivity MTP Transports MTP Transports

Transports Transports
PLP
Remote PLP MTP USB MTP PTP- MTP PLP
PLP MTP USB MTP PTP- MTP MTP USB MTP PTP- MTP
Variant Transport IP Tran- Controller Remote
Variant Transport IP Tran- Controller Transport IP Tran- Controller
Link port Link port port

Remote Connectivity Remote Connectivity

Copyright © 2009 Symbian Foundation

 System Model Lifecycle
Checking, reviewing
and approving changes Pk
Int

O’
egr

sO
ati
on

RACI chart
Pa rg
cka Ar
ge chi
Ow tec
n er ts
Ar
chi
Co tectu
un re
cil
.

System changes: A R C I
Layers and Packages: Create, Remove
Packages: Move, Split, Combine, Rename, Change tech domain
Package Internals: R A
Package: Change levels
Collections: Create, Move, Remove
Package Internals: C R A
Components: Create, Deprecate, Remove, make mandatory

Package Internals: A
Components: Move, change metadata

Component internals: A
Non-compatibility changes

Component internals: A R
Compatibility / dependency changes

Copyright © 2009 Symbian Foundation

System Definition Resources
• Processing and validation tools
/sf/os/buildtools/bldsystemtools/sysdeftools/
• Modelling tools
/sftools/depl/swconfigmdw/sysmodellibs/sysmodelgen/
/sftools/depl/swconfigapps/sysmodeltools/sysmodelmgr/
• Root System Definition locations
/sf/os/deviceplatformrelease/foundation_system/system_model/system_definition.xml
/sftools/depl/toolsplatformrelease/tools_system/tools_model/system_definition.xml
• System Definition specification
http://developer.symbian.org/wiki/index.php/System_Definition
• Package Owner processes
http://developer.symbian.org/wiki/index.php/Package_Owner_Admin_Tasks
• PkO Training Material
Part 1: The architecture of the System Model
Part 2: System Definition XML syntax
Copyright © 2009 Symbian Foundation