<?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 xml:lang="en" id="GUID-0A9C35DA-DF54-5885-AFE0-F4D5B3E49941"><title>Allocate Resources for Endpoints</title><shortdesc>This tutorial shows how to set up the required endpoint resources. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p> <b>Note</b>: This is an optional step when creating a class driver. </p> <section id="GUID-0FD43479-5CDC-5CF0-99F4-9A9B5DB82CDE"><title>Introduction</title> <p>Class drivers can allocate resources to endpoints. This allows the PDD PSL to manage DMA resources more efficiently and to enable and disable endpoint resources on particular interface settings. </p> <p> <b>Note</b>: The functions <codeph>AllocateEndpointResource()</codeph>, <codeph>QueryEndpointResourceUse()</codeph> and <codeph>DeAllocateEndpointResource()</codeph> always refer to the endpoints of the currently active alternate interface setting. Since after interface creation, and before configuration through the host, alternate setting 0 (default) is active, resources for endpoints on other settings of that interface can only be accessed after a successful <codeph>SetInterface()</codeph> request from the host that selects the respective alternate setting. See <xref href="GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834.dita#GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834/GUID-9D773343-8597-5A85-9511-32E176D06E8F">Set the interface</xref>. </p> </section> <section><title>PDD Support for endpoint resource allocation</title> <p>The USB Client PDD PSL must explicitly support the allocation of endpoint resources. The PDD will indicate if this is the case by setting the <codeph>iFeatureWord1</codeph> member in the <xref href="GUID-638DE142-E894-3EC9-9406-CAF67DB822A1.dita"><apiname>TUsbDeviceCapsV01</apiname></xref> structure to the constant <xref href="GUID-B9F2B6CB-E2D7-3794-B0E2-0F60DC24B8F0.dita"><apiname>KUsbDevCapsFeatureWord1_EndpointResourceAllocV2</apiname></xref>. </p> <codeblock id="GUID-2DF5FC9B-A742-5D2C-8AFE-F94F95908514" xml:space="preserve">TUsbDeviceCaps caps;
... 
caps().iFeatureWord1 | KUsbDevCapsFeatureWord1_EndpointResourceAllocV2;</codeblock> <p>This structure is passed to the LDD as part of <xref href="GUID-8133647A-13D8-38A5-B458-13AA58470F0B.dita"><apiname>TUsbcInterfaceInfo</apiname></xref> at interface (and thus logical endpoint) creation time in the call to <codeph>SetInterface()</codeph>. See <xref href="GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834.dita#GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834/GUID-8B403342-D4CC-5DB7-AD4E-402DFD75FA62">Define the interface data</xref>. </p> <p>The successful outcome of the <codeph>SetInterface()</codeph> call does not depend on the availability of requested resources as the driver does not try to allocate requested endpoint resources at this point. The Physical Device Driver (PDD) PIL passes the resource request information to the PSL only at endpoint configuration time (after a <codeph>SetInterface()</codeph> request has been received from the host). </p> <p>Check that the driver supports endpoint resource allocation for DMA and double buffering with by <xref href="GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834.dita#GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834/GUID-E816E6FE-BD6A-5FF6-B450-CA5304BC0175">Getting the Device capabilities</xref> for <codeph>iFeatureWord1</codeph>. </p> </section> <section><title>Allocate endpoint resources</title> <p>Allocate resources for endpoints with <xref href="GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA.dita#GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA/GUID-094CA4FC-E221-373F-BEB6-0D9382A8B0BC"><apiname>RDevUsbcScClient::AllocateEndpointResource()</apiname></xref>. Pass the function the endpoint number and a member of <xref href="GUID-98F7AB41-2C6F-38F9-951B-36659EE394F5.dita"><apiname>TUsbcEndpointResource</apiname></xref> to indicate the type of resource. The parameter that takes the resource type is not a bitmap and <codeph>TEndpointResource</codeph> values should not be combined in the same call to the function. </p> <p>If more than one resource is to be specified then multiple calls to the function have to be made, each one selecting a single resource. </p> <codeblock id="GUID-D04EE4DA-5E9A-5F55-88AF-51694D2BBCE6" xml:space="preserve">gPort.AllocateEndpointResource(aEndpoint, EUsbcEndpointResourceDoubleBuffering);</codeblock> <p> <codeph>KErrNone</codeph> is returned if the resource has been successfully allocated, in which case it will be used from when the current bus transfer has been completed. <codeph>KErrNotSupported</codeph> will be returned if the endpoint does not support the resource requested and <codeph>KErrInUse</codeph> will be returned if the resource is already consumed and cannot be allocated. </p> </section> <section><title>Query </title> <p>There is no direct and immediate feedback as to whether the resources were successfully allocated. The user can find out about the outcome by calling <xref href="GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA.dita#GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA/GUID-AF83C7D3-A914-3B5E-A505-50BD2D74A2BA"><apiname>RDevUsbcScClient::QueryEndpointResourceUse()</apiname></xref> after a configuration or interface alternate setting change notification. </p> <p> <codeph>QueryEndpointResourceUse()</codeph> returns <codeph>ETrue</codeph> if the specified resource is in use at the endpoint and <codeph>EFalse</codeph> if not. </p> <codeblock id="GUID-9D3E1AA9-73DF-5099-8877-B56224F68C09" xml:space="preserve">TBool res = gPort.QueryEndpointResourceUse(aEndpoint, EUsbcEndpointResourceDoubleBuffering);</codeblock> <p>A resource may be deallocated by the PDD if: </p> <ul><li id="GUID-7B6A5139-2FF9-5CF3-A9F6-6125E5883F83"><p>the host selects a different configuration (including zero) than the current one by sending a SET_CONFIGURATION request, </p> </li> <li id="GUID-3C5232C1-9E27-5752-B75C-4169150B3C4F"><p>the host selects a different alternate interface setting than the current one by sending a SET_INTERFACE request, </p> </li> <li id="GUID-2A853D94-7955-519C-82A0-DB544A6C3E9E"><p>the user calls <xref href="GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA.dita#GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA/GUID-37D64B03-5907-31F8-96C6-CD4E2313147D"><apiname>RDevUsbcScClient::ReleaseInterface()</apiname></xref> or <xref href="GUID-BE73CFE6-D48D-5B92-AF49-E2D967ADF0EC.dita">Unloads the USB Client LDD</xref>. </p> </li> </ul> </section> <section><title>Deallocate</title> <p> <xref href="GUID-9348DBF1-AAD2-3D56-819E-09EE51BE5820.dita"><apiname>DeAllocateEndpointResource()</apiname></xref> de-allocates the use of <codeph>aResource</codeph> from some endpoint or ends a specified endpoint behaviour. <codeph>aResource</codeph> is typically some rationed hardware resource or possibly specifies a type of endpoint behaviour. <codeph>aResource</codeph> is not a bitmap and <codeph>TEndpointResource</codeph> values should not be combined. <codeph>KErrNone</codeph> is returned if the resource has been successfully de-allocated, in which case it will be removed from when the current bus transfer has been completed. <codeph>KErrNotSupported</codeph> will be returned if the endpoint does not support the resource requested. </p> </section> <section><p>After you have allocated resources for the endpoints you should force a <xref href="GUID-9597DB22-D932-5A58-9C3C-4E5FCA244253.dita">Re-Enumeration</xref>. </p> </section> </conbody></concept>