<?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-E7C55048-5B7A-5BF2-B7F4-4D731659B88C-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1" xml:lang="en"><title>Device+
−
Driver Writing and Migration Technology Tutorial</title><shortdesc>Explains techniques for writing device drivers on data paged systems+
−
and migrating device drivers to data paged systems. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>+
−
<section id="GUID-8629C08B-C1C8-4435-962A-A57F11EB25CF-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1"><title>Impact of data+
−
paging on kernel APIs</title> <p>The use of data paging impacts on the task+
−
of writing and migrating device drivers in two main ways: the preconditions+
−
for kernel API calls and the performance of the kernel APIs. </p> <p>Firstly,+
−
kernel APIs which access user memory may only be called subject to preconditions.+
−
The preconditions are that </p> <ul>+
−
<li id="GUID-81B56316-97C6-5EE8-BD88-D0741F9301F9-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-4-1"><p>no fast mutex may be+
−
held while calling them, and </p> </li>+
−
<li id="GUID-507412E1-1CA8-5590-B974-809B51C3D79D-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-4-2"><p>no kernel mutex may+
−
be held while calling them. </p> </li>+
−
</ul> <p>The APIs are these: </p> <ul>+
−
<li id="GUID-7A4E9152-8BFA-515E-A115-265436C843F4-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-1"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-C154A151-0DF7-345D-9A10-E9B1CF3400D9"><apiname>Kern::KUDesInfo</apiname></xref>  </p> </li>+
−
<li id="GUID-3C31D5D3-48E9-5D6D-8489-8259D98BF117-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-2"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-FAFAA120-AA28-32FD-9202-1534C3148026"><apiname>Kern::InfoCopy</apiname></xref>  </p> </li>+
−
<li id="GUID-FCE0C3D6-EE49-5AC9-856E-9833D22D541A-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-3"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-B79007D0-FF1F-30E7-986D-7CEBC5E45102"><apiname>Kern::KUDesGet</apiname></xref>  </p> </li>+
−
<li id="GUID-72D4E609-B189-570A-B4D6-D2F4F1289EC1-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-4"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-CDEA7B22-9520-3DB1-AA04-1289C2287936"><apiname>Kern::KUDesPut</apiname></xref>  </p> </li>+
−
<li id="GUID-EE2D8F45-5B12-5D69-A9FD-7ED47A0B5EAD-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-5"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-94F2DF65-87A5-32C6-9695-9557E5832ACF"><apiname>Kern::KUDesSetLength</apiname></xref>  </p> </li>+
−
<li id="GUID-46805316-D1D5-5477-8287-FBF43DD8D3C4-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-6"><p> <xref href="GUID-EE4CB2B4-EAFC-3721-BF0D-ECDF96C29FBF.dita"><apiname>umemget</apiname></xref>, <xref href="GUID-E569834D-8960-3D4E-8980-64902200D4F8.dita"><apiname>kumemget</apiname></xref>, <xref href="GUID-388FF557-3092-3EA0-BF4A-D73504521CD0.dita"><apiname>umemget32</apiname></xref>, <xref href="GUID-874BB607-F0CA-3123-AB2D-D04F4763B16A.dita"><apiname>kumemget32</apiname></xref>  </p> </li>+
−
<li id="GUID-DB8BF5C7-2444-5B8F-8F66-12383ECB6A81-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-7"><p> <xref href="GUID-71B53E34-1F41-3B53-8133-D76D8847D143.dita"><apiname>umemput</apiname></xref>, <xref href="GUID-7B0CC157-0EF6-3CF5-BAF2-D8227F7734A5.dita"><apiname>kumemput</apiname></xref>, <xref href="GUID-A6303814-456F-3583-86B0-A99EA5C3E5A4.dita"><apiname>umemput32</apiname></xref>, <xref href="GUID-B00A6392-9A90-357E-B6A2-D2762800C2C5.dita"><apiname>kumemput32</apiname></xref>  </p> </li>+
−
<li id="GUID-9E6B180A-B360-58A6-B60E-8605E22F2C2E-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-8"><p> <xref href="GUID-BBF5941C-3369-3B56-A560-6E80A7CFFE0F.dita"><apiname>umemset</apiname></xref>, <xref href="GUID-08C2BCA6-6842-3D10-AB56-835B618317F9.dita"><apiname>kumemset</apiname></xref>, <xref href="GUID-B48B5214-ACDD-3E9B-AE07-1B40F645D959.dita"><apiname>umemset32</apiname></xref>, <xref href="GUID-5C1EB135-F9A7-37A5-B256-299CB9598DA9.dita"><apiname>kumemset32</apiname></xref>  </p> </li>+
−
<li id="GUID-F307081B-7672-5C3F-869C-9B4B4F55CE62-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-9"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-D0FCFD5B-2814-3D81-A54A-9E2FA226019B"><apiname>Kern::RequestComplete</apiname></xref>  </p> </li>+
−
<li id="GUID-647B36DF-2124-5252-824E-E100695624C2-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-10"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-589188FC-48E8-3973-B88B-D9E47CFE4403"><apiname>Kern::ThreadRawRead</apiname></xref>  </p> </li>+
−
<li id="GUID-9776CFD1-B061-5FC1-B100-0A55D7E8BFA5-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-11"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-68BFCE22-E05E-3710-9014-6E72FDE7891F"><apiname>Kern::ThreadRawWrite</apiname></xref>  </p> </li>+
−
<li id="GUID-21F695FF-8933-5FF4-84DC-1F09056E36A6-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-12"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-451FD979-14A8-3301-A389-7B509C969FE9"><apiname>Kern::ThreadDesRead</apiname></xref>  </p> </li>+
−
<li id="GUID-B477D969-B73E-514B-8E40-565EE6C4490E-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-13"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-B4A7AF78-179A-378B-9184-CCC2E31830F5"><apiname>Kern::ThreadDesWrite</apiname></xref>  </p> </li>+
−
<li id="GUID-C8080F75-2F3B-5DBE-B0DE-D8518ED49516-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-14"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-6668EA8F-AA55-3CB4-ADEA-879579E94729"><apiname>Kern::ThreadGetDesLength</apiname></xref>  </p> </li>+
−
<li id="GUID-8D644BB0-9A01-5248-8DD2-95CDAE058B09-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-15"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-53813A59-7CED-39E2-818A-D9E0374D2BFD"><apiname>Kern::ThreadGetDesMaxLength</apiname></xref>  </p> </li>+
−
<li id="GUID-746E54A0-C6D0-5B90-89F3-D197DD04470C-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-1-6-16"><p> <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-60E5E01D-2965-3E33-BC05-052A575303F8"><apiname>Kern::ThreadGetDesInfo</apiname></xref>  </p> </li>+
−
</ul> </section>+
−
<section id="GUID-8C767668-D568-40E4-82F7-DD6FC6EA8132-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-2"><title>Impact of data+
−
paging on execution</title> <p>Device drivers use kernel side APIs to access+
−
user memory, and even when they are called in accordance with their preconditions+
−
they are no longer guaranteed to execute in a short and bounded time. This+
−
is because they may access paged memory and incur page faults which propagate+
−
from one thread to another. This document discusses how to mitigate the impact+
−
of data paging on device drivers. </p> </section>+
−
<section id="GUID-3903425C-EA48-44D6-B65E-253F583465BF-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-3"><title>Mitigating+
−
data paging: general principles</title> <p>Three general principles are involved+
−
in mitigating the impact of data paging on device drivers. </p> <ul>+
−
<li id="GUID-955ACDFA-CA71-5489-920F-B2F74039EA37-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-3-3-1"><p>Device drivers should+
−
not use shared DFC queues. </p> </li>+
−
<li id="GUID-3FD4823A-C1A0-53B2-8987-45313BC984C3-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-3-3-2"><p>Device drivers should,+
−
as far as possible, not access paged memory. </p> </li>+
−
<li id="GUID-3557B245-D479-5FA3-B039-092A8F1B7E06-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-3-3-3"><p>If a device driver needs+
−
to access paged memory, it should do so in the context of the client thread. </p> </li>+
−
</ul> </section>+
−
<section id="GUID-BE00235A-D227-4290-B3FA-93B20966073F-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-4"><title>Driver frameworks</title> <p>There+
−
are three main categories of device driver: </p> <ul>+
−
<li id="GUID-EAD164EF-A615-5AFE-A512-032C1C0CC0AC-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-4-3-1"><p><b>Boot-Loaded Non-Channel+
−
Drivers</b></p><p>Boot loaded drivers are built as kernel extensions. They+
−
are typically simple device drivers such as keyboard drivers with limited+
−
or no client side interface and are not much impacted by data paging. It is+
−
generally safe for them to pass data structures using the HAL in the context+
−
of a kernel thread and for them to execute in the context of a kernel thread:+
−
however, this assumption must always be verified for individual cases. </p></li>+
−
<li id="GUID-B82465B7-6306-5AAC-B6B4-FB5A4D07EBB2-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-4-3-2"><p><b>Media Drivers</b> </p><p>Media+
−
drivers are both channel based drivers and kernel extensions. When written+
−
according to the recommended model they either execute wholly in the context+
−
of their clients or use a unique DFC queue and associated kernel thread. If+
−
these recommendations are followed, no additional measures to mitigate the+
−
impact of data paging are required. </p> </li>+
−
<li id="GUID-86AB0CC9-B147-5019-837C-B2A6B32A9F6B-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-4-3-3"><p><b>Dynamically loaded+
−
channel based IO device drivers</b> </p><p>Channel based IO device drivers+
−
are based on various models: all are dynamically loaded. They are derived+
−
either from <xref href="GUID-E7550422-5121-3393-A85E-BB797969CD2A.dita"><apiname>DLogicalChannelBase</apiname></xref> or <xref href="GUID-A3CC1D95-4681-3349-A67C-F113A614041D.dita"><apiname>DLogicalChannel</apiname></xref>.+
−
  </p><p>Channel based drivers derived from <xref href="GUID-E7550422-5121-3393-A85E-BB797969CD2A.dita"><apiname>DLogicalChannelBase</apiname></xref> usually+
−
execute in the context of their client, mitigating the impact of data paging.+
−
Where they are multi-threaded, they typically create separate and unique kernel+
−
threads and do not use shared DFC queues, mitigating the impact of data paging:+
−
if they use a shared DFC queue and associated kernel thread, they are impacted+
−
by data paging and must be written so as to mitigate the effects.  Channel+
−
based drivers derived from <xref href="GUID-A3CC1D95-4681-3349-A67C-F113A614041D.dita"><apiname>DLogicalChannel</apiname></xref> may communicate+
−
with the hardware directly (LDD to hardware) or indirectly (LDD to PDD to+
−
hardware). If a PDD is involved, mitigation of data paging should take place+
−
at that level and not the LDD.   Channel based drivers may have single or+
−
multiple clients, channels and hardware. It is these drivers which require+
−
most work to mitigate the impact of data paging. </p> </li>+
−
</ul> </section>+
−
<section id="GUID-6CD39776-B448-4F7D-8EC2-727AF13B575B-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5"><title>Mitigation+
−
techniques</title> <p>The impact of data paging on device drivers is mitigated+
−
by the use of various different techniques which are the subject of the rest+
−
of this document. </p> <p><b>Passing+
−
data by value</b> </p> <p>Clients should pass data by value not as pointers.+
−
Return values of calls should be return codes not data. </p> <p><b>Using dedicated DFC queues</b> </p> <p>All drivers which use DFCs should+
−
use a dedicated DFC queue to service them. You should not use the kernel queues <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-96588DB1-6884-300F-A85B-EA14A8A1BFAD"><apiname>Kern::DfcQue0</apiname></xref> and <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-7B1F53D8-7EC2-3A05-9F1B-240550A7283B"><apiname>Kern::DfcQue1</apiname></xref> for this purpose. How you create a dedicated DFC queue depends on the nature+
−
of the driver. </p> <p>To service boot loaded drivers and media drivers, you+
−
create a DFC queue by calling <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-F8D26F25-FBFB-3D89-9A80-95719D165C8E"><apiname>Kern::DfcQueueCreate()</apiname></xref>. </p> <p>To+
−
service dynamically loaded drivers derived from DLogicalChannelBase you call <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-ED1B8C3D-ABFB-37BD-A6E9-4080FCCE115C"><apiname>Kern::DynamicDfcQCreate()</apiname></xref> with+
−
a <xref href="GUID-D9111A26-FAA3-3D8E-AB41-5B1263FABB6A.dita"><apiname>TDynamicDfcQue</apiname></xref> as argument: </p> <codeblock id="GUID-73C0C08A-6BAC-5526-A987-57079ED762E7-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-9" xml:space="preserve">TInt Kern::DynamicDfcQCreate(TDynamicDfcQue*&amp; aDfcQ, TInt aPriority, const TDesC&amp; aBaseName);</codeblock> <p>To service a dynamically loaded driver derived from <xref href="GUID-A3CC1D95-4681-3349-A67C-F113A614041D.dita"><apiname>DLogicalChannel</apiname></xref>,+
−
you use the DFC queue supplied with it (the member <xref href="GUID-954F5891-8BF3-33B2-9F40-9D80A6D2A17C.dita"><apiname>iDfc</apiname></xref>,+
−
accessed by pointer). To use the queue you call the <xref href="GUID-2FC8CE8F-102C-3025-86B6-C903D26CD002.dita"><apiname>SetDfcQ()</apiname></xref> function+
−
during the second phase construction of the LDD. </p> <p>You destroy queues+
−
by calling their function <xref href="GUID-38F49D2C-2798-37DB-82CC-A49EAB22B829.dita"><apiname>Destroy()</apiname></xref> which also terminates+
−
the associated thread. </p> <p><b>Setting+
−
realtime state</b> </p> <p>The realtime state of a thread determines whether+
−
it is enabled to access paged memory. If a thread is realtime (its realtime+
−
state is on) it is guaranteed not to access paged memory, so avoiding unpredictable+
−
delays. The realtime state of a thread may be set to <xref href="GUID-0AD1C6D1-591E-3ED2-A4AA-2486A37AE5CE.dita"><apiname>ERealtimeStateOn</apiname></xref>, <xref href="GUID-19425C4A-0B5F-3D89-B5C9-C5DB7E984D7F.dita"><apiname>ERealtimeStateOff</apiname></xref> and <xref href="GUID-2AB828E6-39A5-377C-87B1-FA0CB886E2D7.dita"><apiname>ERealtimeStateWarn</apiname></xref> as defined in the enumeration <xref href="GUID-C9606015-7E55-338D-BE81-42AF50980F59.dita"><apiname>TThreadRealtimeState</apiname></xref> and+
−
set by the kernel function <xref href="GUID-802BE082-128E-3F1E-A8D5-304DCDABFCC8.dita"><apiname>SetRealtimeState</apiname></xref>. </p> <p>If+
−
a driver uses DFC threads and is subject to performance guarantees, their+
−
realtime state should be set to on (this is the default when data paging is+
−
enabled). Otherwise the state should be set to off: the warning state is used+
−
for debugging. </p> <p><b>Validating+
−
arguments in client context</b> </p> <p>It is often necessary to validate+
−
the arguments of a request function. This should be done in the context of+
−
the client thread as far as possible. </p> <p>When a driver derived from the+
−
class <xref href="GUID-E7550422-5121-3393-A85E-BB797969CD2A.dita"><apiname>DLogicalChannelBase</apiname></xref> makes a request this happens+
−
automatically as a call to the <xref href="GUID-92AA62BB-14F1-325D-9A22-9C87AAE0535C.dita"><apiname>Request()</apiname></xref> function takes+
−
place in the client thread. When the driver is derived from the class <xref href="GUID-A3CC1D95-4681-3349-A67C-F113A614041D.dita"><apiname>DLogicalChannel</apiname></xref> the+
−
request involves a call to the <xref href="GUID-E31B440A-A98E-30DA-B222-C8BA59A81A0E.dita"><apiname>SendMsg()</apiname></xref> function inherited+
−
from the base class and it is necessary to override the base implementation+
−
to force evaluation of the arguments within the client thread. </p> <p><b>Accessing user memory from client context</b> </p> <p>The DFC should access+
−
user memory as little as possible. Whenever there is a need to access user+
−
memory and it can be accessed in the context of the client thread, it should+
−
be. </p> <p>When the driver is derived from the class <xref href="GUID-E7550422-5121-3393-A85E-BB797969CD2A.dita"><apiname>DLogicalChannelBase</apiname></xref>,+
−
read and write operations on user memory can be performed with calls to the <xref href="GUID-92AA62BB-14F1-325D-9A22-9C87AAE0535C.dita"><apiname>Request()</apiname></xref> function+
−
and these take place in the context of the client thread. </p> <p>When the+
−
driver is derived from the class <xref href="GUID-A3CC1D95-4681-3349-A67C-F113A614041D.dita"><apiname>DLogicalChannel</apiname></xref> it is+
−
possible to read from and write to user memory by overriding the <xref href="GUID-E31B440A-A98E-30DA-B222-C8BA59A81A0E.dita"><apiname>SendMsg()</apiname></xref> function+
−
before passing the message on to be processed by the DFC thread if necessary.+
−
If the message is passed on, data must be stored kernel side either on the+
−
client thread's kernel stack or in the channel object. </p> <p>Message data+
−
can only be stored on the client thread's kernel stack if the message is synchronous+
−
and the size of the data is less than 4Kb. Since the stack is local to the+
−
client it can be used by more than one thread. One way of doing this is to+
−
implement <xref href="GUID-E31B440A-A98E-30DA-B222-C8BA59A81A0E.dita"><apiname>SendMsg()</apiname></xref> with a call to <xref href="GUID-4DF8919A-CAA2-36D5-B91B-E26D2A32F5F5.dita"><apiname>SendControl()</apiname></xref> which+
−
is itself implemented to perform the copying in the client thread context+
−
and independently call the <xref href="GUID-E31B440A-A98E-30DA-B222-C8BA59A81A0E.dita"><apiname>SendMsg()</apiname></xref> function of the parent+
−
class. </p> <p>Where the message is asynchronous you can use a similar strategy+
−
for overriding the <xref href="GUID-E31B440A-A98E-30DA-B222-C8BA59A81A0E.dita"><apiname>SendMsg()</apiname></xref> function but this time perform+
−
the copying to a buffer owned by the channel independently of a call to the <xref href="GUID-E31B440A-A98E-30DA-B222-C8BA59A81A0E.dita"><apiname>SendMsg()</apiname></xref> function+
−
of the parent class. In this case the size of the data must be small (in the+
−
region of 4Kb), there must be only one client using the buffer, and data cannot+
−
be written back to the client. </p> <p><b>Using+
−
TClientDataRequest</b> </p> <p>An asynchronous request often needs to copy+
−
a structure of fixed size to its client to complete a request. The <xref href="GUID-918410AB-63D3-3672-82BE-73289F88C03E.dita"><apiname>TClientDataRequest</apiname></xref> object+
−
exists for this purpose: it writes a fixed size structure to user memory and+
−
completes the request in the following steps. </p> <ol id="GUID-100FA302-3292-565D-A0BC-A7314C2E2499-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-26">+
−
<li id="GUID-41BF301F-9FC7-55F8-9346-42262F49B5EE-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-26-1"><p>The driver creates a <xref href="GUID-918410AB-63D3-3672-82BE-73289F88C03E.dita"><apiname>TClientDataRequest</apiname></xref> object+
−
for each asynchronous client which may be outstanding concurrently: either+
−
one per client or one per request as appropriate. </p> </li>+
−
<li id="GUID-D4322A3D-C2F7-52D2-B600-35A65EF460CD-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-26-2"><p>When the client makes+
−
a request the <xref href="GUID-918410AB-63D3-3672-82BE-73289F88C03E.dita"><apiname>TClientDataRequest</apiname></xref> object is set to contain+
−
the address of the client's buffer or descriptor and the address of the client's <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref>.+
−
This takes place in the client context. </p> </li>+
−
<li id="GUID-6FBED29F-E54D-5C5C-A6E5-8DBA41625338-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-26-3"><p>The data to be written+
−
is copied into the buffer of the <xref href="GUID-918410AB-63D3-3672-82BE-73289F88C03E.dita"><apiname>TClientDataRequest</apiname></xref> object. </p> </li>+
−
<li id="GUID-3316EB6E-804D-5CBC-8930-68D8E226C955-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-26-4"><p>A call to <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-DE0CF5BD-B166-3C5B-9E27-F95710322F21"><apiname>Kern::QueueRequestComplete()</apiname></xref> passes+
−
the address of the <xref href="GUID-918410AB-63D3-3672-82BE-73289F88C03E.dita"><apiname>TClientDataRequest</apiname></xref> object. </p> </li>+
−
<li id="GUID-39DE78F0-D6E0-582B-B3F1-3AEC6D0E12CE-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-26-5"><p>The client is signalled+
−
immediately. </p> </li>+
−
<li id="GUID-5FF0CD64-F05D-5DF2-BD96-6B5966119CA8-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-26-6"><p>When the client thread+
−
next runs, the buffer contents and completion value are written to the client. </p> </li>+
−
</ol> <p><b>Using+
−
TClientBufferRequest</b> </p> <p>When it is necessary to access user memory+
−
from a DFC thread context, that memory must be pinned for the duration of+
−
the request and unpinned when the request is completed. The pinning must be+
−
performed in the context of the client thread. The <xref href="GUID-5CD6D111-213B-31A2-AA46-C5598DDB7249.dita"><apiname>TClientBufferRequest</apiname></xref> object+
−
exists for this purpose.It is used in the following way. </p> <ol id="GUID-3FEB8983-0BF6-578D-856A-09433AD7182E-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-29">+
−
<li id="GUID-4C3FB914-624A-50FE-94E0-EFF85D6169F8-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-29-1"><p>The driver creates a <xref href="GUID-5CD6D111-213B-31A2-AA46-C5598DDB7249.dita"><apiname>TClientBufferRequest</apiname></xref> object+
−
for each client request which may be outstanding concurrently: either one+
−
per client or one per request as appropriate. </p> </li>+
−
<li id="GUID-CAD03D3A-19E6-5C3D-A203-1726917A50B2-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-29-2"><p>Whe a client makes a+
−
request, the <xref href="GUID-5CD6D111-213B-31A2-AA46-C5598DDB7249.dita"><apiname>TClientBufferRequest</apiname></xref> object is set to contain+
−
the address of any buffers used and the address of the client's <xref href="GUID-E0B34F3E-D4C4-3232-B8B1-7DB35B454646.dita"><apiname>TRequestStatus</apiname></xref>.+
−
Doing so pins the contents of the buffers: they can be specified as descriptors+
−
or by start address and length. This takes place in the client context. </p> </li>+
−
<li id="GUID-8493130F-9E96-580F-B509-5EB5B69852A0-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-29-3"><p>The driver calls <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-A33C039B-981C-3234-A414-95487D4103A9"><apiname>Kern::ThreadBufRead()</apiname></xref> and <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-0C62AA11-87B4-307A-B63E-08A6842C7283"><apiname>Kern::ThreadBufWrite()</apiname></xref> to access the client's buffers. This takes place in the context of the DFC. </p> </li>+
−
<li id="GUID-5C63E867-025B-5F67-90CE-CE960DC254BB-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-29-4"><p>When the request is+
−
complete, the driver calls <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-ECE11E29-0831-3271-AFAA-88DAE4131BE1"><apiname>Kern::QueueBufferRequestComplete()</apiname></xref> passing+
−
the <xref href="GUID-5CD6D111-213B-31A2-AA46-C5598DDB7249.dita"><apiname>TClientBufferRequest</apiname></xref> object. This signals the client+
−
immediately and unpins the buffers. </p> </li>+
−
<li id="GUID-474B2BBE-F24E-5DB3-B83F-CDA95DDE0C3E-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-29-5"><p>When the client thread+
−
next runs, the completion value is written back to the client along with the+
−
updated length of any descriptors. </p> </li>+
−
</ol> <p><b>Using+
−
Kern::RequestComplete()</b> </p> <p>The function <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-D720BB4C-5E31-3213-BB16-859AA325FE98"><apiname>Kern::RequestComplete()</apiname></xref> exists+
−
in two versions: </p> <codeblock id="GUID-11FEEAC7-3223-5B27-9FA2-0C71F5F55E8C-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-32" xml:space="preserve">static void Kern::RequestComplete(DThread* aThread, TRequestStatus*&amp; aStatus, TInt aReason);</codeblock> <p>which is now deprecated, and its overloaded replacement </p> <codeblock id="GUID-AAAAF661-3C0F-5048-8AD2-16C085A65387-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-34" xml:space="preserve">static void Kern::RequestComplete(TRequestStatus*&amp; aStatus, TInt aReason);</codeblock> <p>The+
−
overloaded version should always be used, as it does not take a thread pointer+
−
argument. </p> <p><b>Using+
−
shared chunks</b> </p> <p>Shared chunks are a mechanism by which kernel side+
−
code shares buffers with user side code. As an alternative to pinning memory+
−
they have the following advantages: </p> <ul>+
−
<li id="GUID-65C6ECA6-A89B-5303-B674-E90AA805841A-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-38-1"><p>Shared chunks cannot+
−
be paged and therefore paging faults never arise. </p> </li>+
−
<li id="GUID-D7B96CD0-725F-5FCB-A30A-6FFF55ADC439-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-5-38-2"><p>Shared chunks transfer+
−
data with a minimum number of copying operations and are useful where high+
−
speeds and large volumes are required. </p> </li>+
−
</ul> <p>Shared chunks present disadvantages when a driver is being migrated+
−
rather than written from scratch, as the client API must be rewritten as well+
−
as the driver code. </p> </section>+
−
<section id="GUID-143D7A45-D119-4AEF-8941-116C2567514F-GENID-1-10-1-15-1-1-7-1-1-5-1-8-1-11-1-7-1-5-1-9-1-3-6"><title>See Also</title> <p> <xref href="GUID-85C18DAF-DB76-51C6-B38D-A802E314F4D1.dita">Performance Guarantee Tutorial</xref>  </p> </section>+
−
</conbody></concept>+
−