<?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-B97BAC2E-04E3-4979-BACE-9C46BADE912E" xml:lang="en"><title>Deferred Function Calls</title><shortdesc>This document describes how Deferred Function Calls are

used to implement asynchronous requests.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-1F20014A-5F1E-48B3-AEB8-ED1922452A84"><title>Deferred

function calls</title> <p>Asynchronous request processing is normally

done in a Deferred Function Call (DFC). The second stage of interrupt

handling is deferred to run as a DFC, which runs in a non-critical

context. </p> <p>Different asynchronous requests can be handled using

a single or multiple DFCs. The number of DFCs to be created must be

decided when the driver is designed. For example, a driver that handles

at the same time an asynchronous receive request and a transmit request

would create two DFCs, one each for receive and transmit. </p><p>There

are two main types of deferred function call:<ul>

<li><p>standard Deferred Function Call (DFC)</p></li>

<li><p>Immediate Deferred Function Call (IDFC).</p></li>

</ul></p><p>A DFC is a kernel object that specifies a function to

be run in a thread, which is processing a DFC queue. A DFC is added

to a DFC queue that is associated with a given thread, where it is

cooperatively scheduled with other DFCs on that queue.  Queued DFCs

are run in order of their priority, followed by the order they where

queued.  When the DFC gets to run, the function is run kernel side,

and no other DFC in this queue will get to run until it completes.

A DFC can be queued from any context.</p><p>An IDFC is run as soon

as the scheduler is next run, which is:</p><table id="GUID-CCA45A6C-BB16-41D1-B16C-E3491BEF8B7B">

<tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry align="center" valign="top">Scheduler</entry>

<entry align="center" valign="top">IDFC runs</entry>

</row>

</thead>

<tbody>

<row>

<entry>queued from an Interrupt Service Routine (ISR)</entry>

<entry>during the IRQ postamble.</entry>

</row>

<row>

<entry>queued from an IDFC</entry>

<entry>when the currently-running IDFC completes.</entry>

</row>

<row>

<entry>queued from thread context</entry>

<entry>when the kernel is next unlocked.</entry>

</row>

</tbody>

</tgroup>

</table><p>Unlike a DFC, the IDFC is not run from a thread context,

and its execution time must be much smaller.  For these reasons, IDFCs

are rarely used directly, but are used for implementation of the kernel

and RTOS personality layers.  An important use of IDFCs is in the

implementation of queuing DFCs from an ISR context.  IDFCs are run

with interrupts enabled but the kernel locked.</p></section>

<section id="GUID-5439E26D-754A-46F3-B607-D229BF5B8A8C"><title>Creation</title> <p>DFCs are created using <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita"><apiname>TDfc</apiname></xref> objects. </p> <p>The DFC is initialized with a DFC callback function, a pointer to

an object to be passed to the callback function, and a priority. It

can also provide the DFC queue to be used by this DFC at the time

of construction. </p> <codeblock id="GUID-B3918CAB-F168-5992-BFA9-868648D07083" xml:space="preserve">TDfc iRxDfc;

/* RxDataDfc is a function pointer to a static function, "this" is passed as a parameter */

iRxDfc(RxDataDfc,this,1); // This implements an DFC using the standard queue and priority 1.

iRxDfc(RxDataDfc,this,iDfcQ,1); // This implements an DFC on a user-specified queue with a priority of 1.

iRxDfc(RxDataDfc,this); // This implements an IDFC.</codeblock><note>DFCs are created with a priority which is 0 to (<xref href="GUID-483DF06F-0236-36C0-8F59-475BB38344E5.dita"><apiname>KNumDfcPriorities</apiname></xref>—1), which is typically 0..7. Using a higher priority value is an

error. IDFCs are created by not specifying a priority. </note></section>

<section id="GUID-886457DF-0DB5-4447-BC9B-EB43060A5C6B"><title>Queuing</title> <p>To initiate the process of DFC functionality, the DFC object

must be queued to the DFC queue associated with the Kernel thread. </p> <p>Before adding the DFC to a DFC queue of the thread, it must be

associated with the queue (<xref href="GUID-24B2FEDB-9273-351F-A1C6-6F5F91BF83B7.dita"><apiname>TDfcQue</apiname></xref>) object. This

can be either done at the time of construction, or can be set later,

by calling <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita#GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB/GUID-E3458CD4-7A1C-3FBD-A7FB-488A9C92AE42"><apiname>TDfc::SetDfcQ()</apiname></xref>. </p> <codeblock id="GUID-B57B1C37-A1A5-5C85-AED8-FDD8DBE84280" xml:space="preserve">...

// Associate the Tx and Rx DFCs with the same queue set to receive 

// the client messages for this driver. SetDfcQ() sets up the DFC 

// queue for the DFCs constructed for Tx and Rx

//

iRxDfc.SetDfcQ(iDfcQ);

...</codeblock> <p> <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita#GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB/GUID-18073EBB-D91B-3AC8-87A2-424AEDD4D7A4"><apiname> TDfc::Add()</apiname></xref> or <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita#GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB/GUID-F6F0C858-8EB2-387B-AE1A-F04B51CE4CED"><apiname>TDfc::Enque()</apiname></xref> is used to add the DFC object to the DFC queue. From an ISR, <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita#GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB/GUID-18073EBB-D91B-3AC8-87A2-424AEDD4D7A4"><apiname>TDfc::Add()</apiname></xref> is used. From a thread, <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita#GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB/GUID-F6F0C858-8EB2-387B-AE1A-F04B51CE4CED"><apiname>TDfc::Enque()</apiname></xref> is used. If preemption is disabled, <codeph>TDfc::Add()</codeph> could also be used. </p> <codeblock id="GUID-9FBB6881-4BA9-534E-86C7-3A0167E9159C" xml:space="preserve">// TDfc::Add() will queue an IDFC or a DFC from an ISR. This function 

// is the only way to queue an IDFC and is the only way to queue a 

// DFC from an ISR. To queue a DFC from an IDFC or a thread either 

// TDfc::Enque() or TDfc::DoEnque() should be used. This function 

// does nothing if the IDFC/DFC is already queued.

//

iRxDfc.Add();

</codeblock></section>

<section id="GUID-E0B9073A-1554-4085-BE24-E27633B7EDF2"><title>Callback

function</title> <p>The DFC callback function is a static function

called when a DFC is executed. A pointer to this function is provided

at the time of DFC object creation. This function implements the deferred

functionality of an asynchronous request, such as reading or writing

data from or to an I/O peripheral. It would then either complete the

request or start another operation. </p> <codeblock id="GUID-5682EDE1-8397-592D-82CE-78DF11487512" xml:space="preserve">static void RxDataDfc(TAny* aPtr);</codeblock></section>

<section id="GUID-A57C3C99-3032-48CD-A800-E9EE7DCDF4E3"><title>Cancellation</title> <p>A DFC function must be cancelled while cleaning up resources,

for example, when closing the channel. The function <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita#GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB/GUID-9851B90B-8D05-3C86-B083-44C4564AC140"><apiname>TDfc::Cancel()</apiname></xref> cancels the DFC if it is already queued. It does nothing if a DFC

is not queued. It must be called to avoid orphaned DFCs. </p> <codeblock id="GUID-CD926E3D-13E8-51C4-B224-8150FD4D70DB" xml:space="preserve">...

// If it is a Transmit request, cancel the Transmit DFC. 

// TDfc::Cancel() cancels the DFC if it is already queued. It 

// does nothing if DFC is not queued.

//

iTxDfc.Cancel();

...</codeblock></section>

</conbody></concept>