<?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-FBE6E61F-5A2E-5A7A-BC59-51F072EBED7D" xml:lang="en"><title>Media

Driver Migration Guide</title><shortdesc>Describes the issues that need to be considered, when migrating

media drivers to a writable data demand paging environment. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-AB10DA2D-B7CC-47FD-B68A-1610B6BEAAE6"><title>Purpose</title> <p>This

document explains the points that have to be considered when migrating existing

media drivers to a writable data paging environment. </p>  </section>

<section id="GUID-EB26A48A-3A34-44E8-9651-C7ED658CED51"><title>Issues Involved</title> <p>The

two main issues that have to be addressed when migrating existing media drivers

are: </p> <ul>

<li id="GUID-68A44C67-6D4E-5D7E-A13B-0A82154073B2"><p>A deadlock condition

can occur between the driver and the client process, where both are trying

to access the same page of paged memory</p> </li>

<li><p>A deadlock condition can occur between the driver and the client process,

where the client is allocating on the kernel heap, the paging system tries

to page out some data and the media driver also tries to allocate on the kernel

heap while servicing the resulting request.</p></li>

<li id="GUID-56A3815D-E07B-5195-85C3-0B93C08745C3"><p>Unpredictable delays

in servicing a DFC can occur, since memory might need to be paged in.</p> </li>

</ul> <p>To address the above issues, the following points will have to be

considered/undertaken: </p> <ul>

<li id="GUID-A15DB387-AB22-51BB-A4AD-0353932B788C"><p>Pass data by value to

DoRequest/DoControl </p> </li>

<li id="GUID-0FB5B141-94FE-54E4-9915-2DD50F840879"><p>Return results by using

a return code </p> </li>

<li id="GUID-9B3D3D25-010E-58C3-9C48-13AF494C3E62"><p>Use of a dedicated DFC

queue </p> </li>

<li id="GUID-AADA0BD7-75E7-5A11-98EB-F7EF3E1B5139"><p>Determine if unpredictable

delays in servicing DFCs are acceptable </p> </li>

<li id="GUID-E5B45EC9-DF21-51A9-814C-17CF3C13DFAE"><p>Validate the arguments

in the client context as far as possible </p> </li>

<li id="GUID-E6E4F7E2-1BE4-5590-AB05-777637C9B32B"><p>Move user memory accesses

to client context where possible </p> </li>

<li id="GUID-F4B44B27-9AE6-5A8C-B88C-C1809DAF6B89"><p>Replace the use of small

fixed-size structures with the use of the TClientDataRequest object </p> </li>

<li id="GUID-990D43F2-21C3-5C55-AC13-89C7153EA83B"><p>Pin user memory accessed

from DFCs </p><p>Do not allocate on the kernel heap while handling page out

requests.</p> <p>The paging algorithm can be over ridden and pages of memory

can be kept in memory (pinned). This situation can be reversed by 'unpinning'

the page. The TClientBufferRequest API provides this functionality. </p> </li>

<li id="GUID-67DB522A-DEB2-5FEA-ACA4-D80D09D80926"><p>Re-write the driver

to use shared chunks </p> </li>

<li id="GUID-A298C045-2260-55B5-89B9-595E3AF5472F"><p>No fast mutex may be

held when calling APIs that access user memory </p> </li>

<li id="GUID-F9F79078-0CBC-5E8F-899F-117D148C605A"><p>No kernel mutex may

be held </p> </li>

<li id="GUID-D378D276-CAF0-5B8B-BDA2-4D18EB87F96A"><p>Use the new APIs, (See

the <xref href="GUID-592B6D20-4ABA-5C79-9734-D18E2CE4A86C.dita">Writable Data Paging

Overview</xref> ). </p> </li>

</ul> </section>

<section id="GUID-796DBAE0-EE59-4C1D-8D4A-BC5ACC899085"><title>Device Driver

Tutorials</title> <p>The link given below is a guide that is relevant to this

topic: </p> <p> <xref href="GUID-91C11D80-7A62-5135-8EE0-6EC5576D1118.dita">Demand

Paged Device Drivers Writing Guide</xref>  </p> <p>This guide describes changes

to device drivers that have to be undertaken in order for them to work on

a device that uses writable data paging. </p> </section>

<section id="GUID-32E564F3-D66A-472B-A3C1-D2D61807A5F2"><title>See also</title> <ul>

<li id="GUID-77417650-C1F4-5ABC-9E75-54D274556FCD"><p> <xref href="GUID-E7C55048-5B7A-5BF2-B7F4-4D731659B88C-GENID-1-7-1-14-1-1-7-1-7-1-11-1-7-1-4-1-9-1.dita">Device

Driver Writing and Migration Guide</xref>  </p> <p>This document explains

techniques for writing device drivers on data paged systems and migrating

device drivers to data paged systems. </p> </li>

</ul> </section>

</conbody></concept>