Surface Manager Overview

Variant: ScreenPlay. Target audience: Device creators.

Summary

The Surface Manager creates and manages graphics composition surfaces:

The Surface Manager allocates memory to which it controls access and that it can safely permit hardware to access.
The Surface Manager maintains size and format information.
The Surface Manager keeps track of the clients using each surface.

The Surface Manager provides an API that allows clients to create, open, access (map to) and close surfaces. A client can also simply request a surface's attributes. Clients cannot change a surface's attributes which, once the surface has been created, are generally immutable.

Surfaces are uniquely identified by a 128 bit surface ID. This comprises eight bits that identify the surface type and 120 bits that identify the surface itself.

A client that creates a surface can pass its ID to another process. That process can then become a client of the Surface Manager and use the ID to access the surface. Access to a surface is strictly limited to clients that know the ID.

Architecture

The Surface Manager creates and manages surfaces that are used as input to the composition engine.

Surface Manager and related components -

The Surface Manager is an adaptation component, which means that it can be modified or replaced to suit the exact hardware that is available on a specific device.

The Symbian Surface Manager consists of:

A generic DLL that provides the user-side API. This provides features to create and delete surfaces, to access surface pixel data and to query surface attributes. It routes the calls through to the device driver.
A reference implementation, which consists of a Logical Device Driver (LDD) and a kernel extension. This implements surfaces as shared chunks, which allow memory to be mapped into the address space of multiple applications and to be available to hardware such as the MBX GPU. This allows instant access and avoids copying or moving large amounts of data.

Shared chunks are memory regions that can be safely shared between user-side and kernel-side processes. The implementation is a kernel extension because shared chunks can only be created by the kernel. As a kernel extension it is controlled using an LDD. It performs shared chunk allocation and allows the client to specify caching attributes.

The Surface Manager is an adaptation component, which means that it can be modified or replaced to suit the exact hardware that is available on a specific device.

The Symbian Surface Manager consists of:

A generic DLL that provides the user-side API. This provides features to create and delete surfaces, to access surface pixel data and to query surface attributes. It routes the calls through to the device driver.
A reference implementation, which consists of a Logical Device Driver (LDD) and a kernel extension. This implements surfaces as shared chunks, which allow memory to be mapped into the address space of multiple applications and to be available to hardware such as the MBX GPU. This allows instant access and avoids copying or moving large amounts of data.

Shared chunks are memory regions that can be safely shared between user-side and kernel-side processes. The implementation is a kernel extension because shared chunks can only be created by the kernel. As a kernel extension it is controlled using an LDD. It performs shared chunk allocation and allows the client to specify caching attributes.

The Surface Manager reference implementation -

Device creators can replace the reference implementation and retain the user-side API. Alternatively, it is possible to replace both the implementation and the user-side API or to replace the implementation and to extend the user-side API.

It is generally necessary to create a custom Surface Manager implementation if hardware-accelerated surfaces (surfaces stored in memory managed by the GPU) are to be used. Device creators can also provide their own APIs on top of the Surface Manager. The following diagram shows the default configuration and two possible adaptation configurations.

Some possible Surface Manager configurations -

Description

Features of the Surface Manager API and reference implementation include:

Cache control

Surface Manager allows cached or uncached operation. If the Memory Management Unit (MMU) supports caching, the client can specify the caching attributes that the Surface Manager is to use for the shared chunk allocation. This enables the Surface Manager to create surfaces in shared chunks that are suitable for both hardware and software renderers. If the MMU does not support the requested caching attribute, a lesser one is used. The client can subsequently query the supported cache behavior.
Chunk adoption

Clients can specify a pre-existing shared chunk when creating surfaces. The shared chunk can originate from an existing surface allocated through the Surface Manager or from another driver. The Surface Manager adopts the chunk passed in instead of allocating new memory. This means that pixel data that has already been written to a shared chunk by, for example, the camera driver, can be used as input to the composition engine.

This functionality also allows memory to be saved because one chunk can be used for both landscape and portrait orientations of a surface when both orientations are not required at the same time.
Hinting support

Like metadata, surface hints contain information about surface content. Hints are defined by the device creator and consist of key-value pairs, each of which has a flag that determines whether the value can be changed. Other processes that have access to the surface can read this data and change it if the hint is mutable. They can also add hints after creation of the surface.
Surface states

The Surface Manager determines the relationship between each client process and each Surface ID. Each process sees each surface ID as being in one of the following states:
- Invalid. No surface exists with that ID.
- Closed. The surface exists, but is not open in the process.
- Open. The process has opened the surface.
- Mapped. The process has mapped the surface into its address space. This implies that the surface is open in that process.
Multiple processes that refer to the same surface may have different relationships with that surface. For example, the surface may be mapped in one process but simply open in another process. Most Surface Manager operations require the surface to be in a particular state relative to the calling process. If the surface is not in the required state an error is returned.
Reference Counting

The Surface Manager maintains a reference count for each surface. The count is started when the surface is created, gets incremented each time a client calls OpenSurface() and gets decremented each time CloseSurface() is called. When the count drops to zero the Surface Manager deletes the surface and releases the memory.

When a process exits or closes its session with the Surface Manager, the Surface Manager closes all of the surfaces that the process has open.

Executables

The Surface Manager component contains the following executable files:

Name Description

Surfacemanager.dll

The Surface Manager user-side API, which provides features to create and delete surfaces, to access surface pixel data and to query surface attributes. This routes the calls through to the device driver.

surfacemanagerdriver.ldd

A system memory logical device driver and kernel extension. It performs shared chunk allocation and allows the client to specify caching attributes.

Typical uses

Typical use involves creating a surface, querying its properties and passing the surface ID to another process. A second process can then open the surface.

Clients of the Surface Manager simply create an instance of the client side class RSurfaceManager and use its API. The complexities of device driver communication, memory management and thread safety are completely encapsulated.

RSurfaceManager surfaceManager; +