<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-95BD3650-08CB-407D-969E-DFDB39B2FEFC" xml:lang="en"><title>What is a Platform Service?</title><shortdesc>A platform service is an interface designed to make it

quick, easy and inexpensive to integrate hardware into a mobile device.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-F3ACE06A-E619-416A-BC4B-4AA4771404D2"><title>Platform

Service</title>       <p>A platform service is a set of defined functionality,

usually providing an abstraction or encapsulation for functionality

provided by hardware.</p><p>For example, a platform service may provide

a standard interface for using a serial bus to send commands and data

between integrated circuits on the base board. Another example would

be providing a standard interface for Direct Memory Access (DMA) hardware

for moving blocks of data from one block of memory locations to another

or from a block of memory to a hardware device.</p><p>The platform

service separates the functionality required by kernel, device driver

and application processes from the specific hardware implementation.

This means, for example, that a device driver can be written for a

platform service that uses the published APIs, without needing to

know the specifics of the actual hardware device/chipset.</p><fig id="GUID-D1D306BB-EFDD-4365-8259-39A4F4EB6AE3">

<title>Platform service</title>

<image href="GUID-99637158-DE86-4BB4-98D4-3A3E64AB768F_d0e87314_href.png" placement="inline"/>

</fig><p>The platform service is a consistent hardware interface at

the bottom of the operating system platform software stack. In the

past much of the logic and configuration required to enable a new

piece of hardware was higher up in the operating system stack and

that made it difficult to support new or variant hardware. The platform

service architecture separates out the hardware specific interfaces

and encapsulates them behind a standard set of platform service (client

interface) APIs. </p><p>The platform service consists of :</p><ul>

<li><p>Client Interface/Platform service APIs </p></li>

<li><p>Implementation of the APIs:</p><ul>

<li><p>Platform Independent Layer (PIL)/Framework/Generic implementation</p></li>

<li><p>SHAI interface</p></li>

<li><p>Platform Specific Layer (PSL)/SHAI Implementation/Hardware

implementation</p></li>

</ul></li>

</ul><p>The PIL contains all the common functionality code such as

maintaining a list of available channels for communication or holding

the pending list of memory transfers to be processed by DMA when the

hardware becomes available. Usually the PIL provides the implementation

of the Client Interface APIs. This is sometimes referred to as the

Framework.</p><p>The interface between the framework code and the

PSL code is known as the Symbian Hardware Adaptation Interface (SHAI).

The SHAI interface specifies how the PIL and PSL talk to each other

(APIs, shared memory areas etc.)</p><p>The PSL consists of the specific

code required to work with a particular piece of hardware. This means

that supporting a new or variant chipset only requires the PSL to

be amended or to have detection code to handle a particular piece

of hardware. </p><p>Some Platform Services, such as GPIO, provide

APIs that directly address the hardware, and so the PSL provides the

client interface API implementation directly. For example, there is

no GPIO PIL/framework.</p></section>

<section id="GUID-15BD58D5-12D7-4871-9A98-940F39B95182"><title>Variations

on platform service</title><p>Not all platform services are as simple

as the diagram above suggests. Some platform services do not talk

to hardware directly or at all, but provide a higher-level abstraction,

often with further low-level platform services below them in the OS

stack. For example, the Power Manager Policy platform service, provides

APIs to control power management policy, but does not interface with

any hardware directly. In these cases there is either no PSL, or the

PSL provides configuration specific responses to a generic PIL. For

example, if a handset can be built in two variants, one with a hardware

graphics accelerator and one without but with a software emulated

graphics accelerator, then the PSL would be responsible for directing

graphics requests either to the hardware, or to the software and returning

the results back through the PIL to the client.</p><p>Some plaftorm

services, for example TV-Out, may use additional platform services

to output sound as well as providing hardware support for the TV-Out

chipset.</p><p>Some platform services may share a piece of hardware,

such as a radio chip. The chip may provide cellular telephony, WiFi,

FM radio transmission and other features all on one chip, but there

may be several separate platform services, each exposing an API for

one particular technology.</p><p>Both the PIL and PSL may make calls

to other OS components, including other platform services, for information

such as Hardware Configuration, power status, and the availability

of other services.</p></section>

<section id="GUID-1D50AC84-89A3-4BA3-BB7F-032FF499E56D"><title>Why

have a platform service</title><p>Platform services

benefit both device creators and third party hardware/chipset developers

since they specify a standard software interface between the operating

system and standard functionality provided by hardware.</p><p>This

means that it is possible for a device creator to easily integrate

the best hardware for their device, and allows hardware creators to

work to a standard interface that can be used across multiple devices

and multiple customers.</p><p>As the platform service interface provides

a consistent interface to functionality, it allows the device creator

to concentrate on the core functionality and not worry about how the

hardware will provide it. And since the interface is standard for

each type of hardware component, each manufacturer can provide the

information or code for the PSL comparatively easily for each additional

variant they produce. So this means less code required from hardware

manufacturers per hardware component, and a larger market as each

new mobile device, from any device creator, can use that compliant

hardware.</p><p>The platform services abstraction for hardware adaptation

also means more common code that can be shared across the Symbian

Foundation member community. This includes sharing PSL code with other

hardware providers, and sharing code for device drivers and other

higher-level components that need to use the platform services APIs.

For example, if a device driver for a particular piece of hardware

also needs to use a serial inter-IC bus (IIC) to send commands to

that hardware, then it can use the IIC platform service APIs and re-use

code that other components have already tested for using the IIC client

interface APIs.</p><p>Platform services also allow the use of standardized

test tools and test suites. Each new piece of hardware in a particular

category (for example, camera, Bluetooth radio) has to comply with

the SHAI interface (PIL/PSL interface). This means that an existing

test suite that works with another camera module can be used to test

that this new piece of hardware works. This reduces the time taken

for testing and increases speed to market.</p></section>

<section id="GUID-173DF644-98BC-415C-8DA5-5428FF560622"><title>Who

uses the Platform Service?</title><ul>

<li><p>Application developers, who need to use the functionality of

a hardware device, but do not need to know the specific details of

the hardware/hardware implementation. They use the client interface

and need to know what the APIs are, and what order they must be called

in and so on.</p></li>

<li><p>Framework developers, who need to know how to implement each

of the client interface APIs , and a description of the functionality

required within the framework.</p></li>

<li><p>Hardware Developers, who need to understand the hardware interface,

and have to write or update the hardware implementation (PSL) to support

their particular chipset/hardware.</p></li>

</ul></section>

<section id="GUID-84DAC762-23F9-4756-8D3A-EB03280E93CA"><title>Platform

service client interface APIs</title><p>In general these are function

calls, and associated enumerations. There are two main types of function

call:<ul>

<li><p>Synchronous</p></li>

<li><p>Asynchronous</p></li>

</ul></p><p>A synchronous function call from the client/device-driver

waits for the platform service to process it and make any return value.

The client thread waits for the synchronous call to complete.</p><p>An asynchronous function call asks the platform service to do something,

but then execution of the client continues immediately. For example,

this would be the case of any function that starts a long data transmission

or receive process, such as streaming video. One of the standard components

of an asynchronous function call is a way for the result to be communicated

back to the client. Often this is done by a “callback function” where

the client specifies a pointer to a function (and parameters) during

the original call, and the platform service puts the callback on the

Delayed Function Call (DFC) queue for the client when the platform

service has completed the request. This may indicate “transfer completed”

or “transfer failed, error code 123”, it may release a lock or other

functionality defined by the author of the client.</p></section>

</conbody><related-links>

<link href="http://developer.symbian.org/wiki/index.php/Prop/SHAI.dita">

<linktext>Symbian Foundation SHAI page</linktext></link>

</related-links></concept>