<?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-5F614B75-056D-5798-AE06-8DA6E9ED6834"><title>Set the Interface Descriptors </title><shortdesc>A short document that describes how to set the interface descriptors. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section id="GUID-078753F0-B95D-59F6-B820-8CB8E0C9E903"><title>Introduction</title> <p>Before setting the interface descriptors, get the device and endpoint capabilities of the USB Device Controller (UDC) hardware. </p> <ul><li id="GUID-A1822AA8-7D19-500B-86AB-F6020A6D5A6B"><p> <xref href="GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834.dita#GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834/GUID-E816E6FE-BD6A-5FF6-B450-CA5304BC0175">Get device capabilities,</xref>  </p> </li> <li id="GUID-692A31F3-F583-585B-9288-E40863145D8C"><p> <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> </li> <li id="GUID-A1AB1EB3-A95C-5E38-AE82-1DA7AB9BA807"><p> <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> </li> <li id="GUID-43CA2C0D-1B24-5D7B-A5C2-D158262EE44A"><p> <xref href="GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834.dita#GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834/GUID-44EC5C8F-C795-57C7-AB1A-C8918C187CDE">Finalise the interface.</xref>  </p> </li> </ul> </section> <section id="GUID-E816E6FE-BD6A-5FF6-B450-CA5304BC0175"><title>Get device capabilities</title> <p>Use <xref href="GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA.dita#GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA/GUID-990AB6D3-D659-33C9-BE33-117ACE95A106"><apiname>RDevUsbcScClient::DeviceCaps()</apiname></xref> to get the device capabilities and <xref href="GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA.dita#GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA/GUID-A16F2D62-FCBC-3E97-B058-F9D4ED68817C"><apiname>RDevUsbcScClient::EndpointCaps()</apiname></xref> to get the endpoint capabilities. </p> <p> <xref href="GUID-638DE142-E894-3EC9-9406-CAF67DB822A1.dita"><apiname>TUsbDeviceCapsV01</apiname></xref> is the structure used to return the device capabilities. </p> <codeblock id="GUID-EC77C1A0-510E-57B9-848E-5B58D51B3438" xml:space="preserve">TUsbDeviceCaps d_caps;

TInt r = gPort.DeviceCaps(d_caps);</codeblock> <p> <xref href="GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA.dita#GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA/GUID-A16F2D62-FCBC-3E97-B058-F9D4ED68817C"><apiname>RDevUsbcScClient::EndpointCaps()</apiname></xref> returns the object <xref href="GUID-70D18C87-249C-3E9C-895F-85FFB9B0139B.dita"><apiname>TUsbEndpointData</apiname></xref> which contains a <xref href="GUID-581F651B-9D13-3C26-908B-5A12259914CE.dita"><apiname>TUsbEndpointCaps</apiname></xref> object and a boolean variable that indicates whether the endpoint is in use. <codeph>TUsbEndpointCaps</codeph> contains the endpoint capabilities as reported by the driver. </p> <codeblock id="GUID-59FAB2C1-43B8-5549-A3CE-8E01E41858DB" xml:space="preserve">TUsbcEndpointData data[KUsbcMaxEndpoints];

TPtr8 dataptr(reinterpret_cast<TUint8*>(data), sizeof(data), sizeof(data));

r = gPort.EndpointCaps(dataptr);</codeblock> <p> <b>Note</b>: Endpoint zero is only supported as a control endpoint. The capabilities of endpoint zero are not included in the list of endpoint cababilities returned. </p> </section> <section id="GUID-8B403342-D4CC-5DB7-AD4E-402DFD75FA62"><title>Define the interface data</title> <p>Before calling <xref href="GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA.dita#GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA/GUID-8DD93FEC-4B48-3789-B850-41EEB867C25F"><apiname>RDevUsbcScClient::SetInterface()</apiname></xref>, the class, subclass and protocol must be defined in the <xref href="GUID-0A45BEF9-973E-3C73-8F23-4383AB694C1E.dita"><apiname>TUsbcScInterfaceInfo</apiname></xref> object. <codeph>TUsbcScInterfaceInfo</codeph> is in the <xref href="GUID-D93648BC-3702-34EC-8550-C038009C3FE6.dita"><apiname>TUsbcScInterfaceInfoBuf</apiname></xref> package buffer. </p> <p>In the example below we set the interface data in the <codeph>TUsbcScInterfaceInfo</codeph> object. </p> <codeblock id="GUID-E9DA752C-2200-5173-99BA-B446EE5595B0" xml:space="preserve">TUsbcScInterfaceInfoBuf ifc;

// Endpoint zero

ifc().iEndpointData[0].iType = KUsbEpTypeBulk;

ifc().iEndpointData[0].iDir = KUsbEpDirIn;

ifc().iEndpointData[0].iSize = KUsbEpSize64;    

//Endpoint 1

ifc().iEndpointData[1].iType = KUsbEpTypeBulk;

ifc().iEndpointData[1].iDir = KUsbEpDirOut;

ifc().iEndpointData[1].iSize = KUsbEpSize64;

_LIT16(string, "T_USBCSC Interface");

ifc().iString = const_cast<TDesC16*>(&string);

ifc().iTotalEndpointsUsed = 2;

ifc().iClass.iClassNum      = 0xff;

ifc().iClass.iSubClassNum = 0xff;

ifc().iClass.iProtocolNum = 0xff;

// Tell the driver that this setting is interested in Ep0 requests:

ifc().iFeatureWord |= 0;</codeblock> <p> <codeph>TUsbcScInterfaceInfo</codeph> contains the following data members: </p> <ul><li id="GUID-EC42ACC1-2390-5038-BBB2-ECD9BED00095"><p> <codeph>iEndpointData</codeph> is is an array of n <xref href="GUID-D59AC3E3-2F3D-3D85-BBA4-271A78515993.dita"><apiname>TUsbcScEndpointInfo</apiname></xref> elements where n = <codeph>iTotalEndpointsUsed</codeph>, </p> <p>For each endpoint the <codeph>TUsbcScEndpointInfo</codeph> object must, at the very least, contain: </p> <ul><li id="GUID-13CC90A8-B9BE-52D4-9B8D-DC436E8B7D2C"><p>The endpoint type (<codeph>iType</codeph>), direction (<codeph>iDir</codeph>) and maximum packet size (<codeph>iSize</codeph>) must be specified to claim each endpoint. </p> </li> <li id="GUID-01B1592E-3680-5815-A192-8EC181BF549A"><p>The members <codeph>iBufferSize</codeph> and <codeph>iReadSize</codeph> help with performance tuning and memory optimisation. For example, a capture of 64KB may be an optimal size to pull off the bus without incurring timeout penalties in the PSL. Some classes may benefit from having multiple captures in the endpoint buffer, so <codeph>iBufferSize</codeph> would be some multiple of <codeph>iReadSize</codeph>. </p> </li> <li id="GUID-23779A3C-783F-56BE-AABF-CA035021552F"><p> <codeph>iExtra</codeph> and <codeph>iPairing</codeph> allow for possible future support of classes that require pairing of endpoints by physical address and function. <b>Note</b>: This is not yet supported and any attempt to pair endpoints will result in failure to create the interface. </p> </li> </ul> </li> <li id="GUID-59C914DF-E81E-5ECD-A957-20505BE84EAF"><p> <codeph>iString</codeph> is a <xref href="GUID-440FF2B4-353B-3097-A2BA-5887D10B8B23.dita"><apiname>TDesC16</apiname></xref>, </p> <p>A description string for the interface. </p> </li> <li id="GUID-17D47697-E796-59B5-8BF7-87D62848757A"><p> <codeph>iTotalEndpointsUsed</codeph> is a <xref href="GUID-F9432D7B-41C9-3048-AC50-B5BCF8BE11D0.dita"><apiname>TUint</apiname></xref>, </p> <p>This number is all the endpoints you wish to use excluding endpoint zero. For example, if you wish to use 4 endpoints and the control endpoint, this value is should be four. </p> <p> <b>Note</b>: If you wish to implement a control-only interface then this value should be zero. </p> </li> <li id="GUID-A244CB5A-D7E5-562E-9BEA-55E891106E8E"><p> <codeph>iClass</codeph> is of type <xref href="GUID-4BA5287B-69D8-3714-BA3A-D4DBA4DD6AE8.dita"><apiname>TUsbcClassInfo</apiname></xref>, </p> <p>Sets the class type for this interface. </p> </li> <li id="GUID-5514EA9C-2B41-545A-9249-84DB03A0A5B3"><p> <codeph>iFeatureWord</codeph> is 32 flag bits used for specifying miscellaneous interface features. </p> <p>See <xref href="GUID-0A9C35DA-DF54-5885-AFE0-F4D5B3E49941.dita">Allocate Resources for Endpoints</xref>. </p> </li> </ul> </section> <section id="GUID-9D773343-8597-5A85-9511-32E176D06E8F"><title>Set the interface</title> <p>To set the interface pass the initialised <xref href="GUID-D93648BC-3702-34EC-8550-C038009C3FE6.dita"><apiname>TUsbcScInterfaceInfoBuf</apiname></xref> to <xref href="GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA.dita#GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA/GUID-8DD93FEC-4B48-3789-B850-41EEB867C25F"><apiname>RDevUsbcScClient::SetInterface()</apiname></xref>. </p> <codeblock id="GUID-E96684EB-8012-59D1-9ECF-4C0AA19F3B9B" xml:space="preserve">// Set up the interface.

r = gPort.SetInterface(0, ifc);</codeblock> <p>The interface number passed to <codeph>SetInterface()</codeph> along with <xref href="GUID-D93648BC-3702-34EC-8550-C038009C3FE6.dita"><apiname>TUsbcScInterfaceInfoBuf</apiname></xref> distinguishes between <i>alternate interfaces</i>. If alternate interfaces are not used then this value is always zero. When used, the value must be one greater than that of the proceeding alternate interface. </p> <p> <b>Note</b>: The whole <xref href="GUID-5F614B75-056D-5798-AE06-8DA6E9ED6834.dita">Setting interface descriptors</xref> section up to this point should be repeated for the number of alternative settings required. </p> </section> <section id="GUID-44EC5C8F-C795-57C7-AB1A-C8918C187CDE"><title>Finalise the interface</title> <p> <xref href="GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA.dita#GUID-4D1AE286-41EE-3361-948A-3E8634D81DBA/GUID-B0818D26-B205-3BF9-863B-6F67162BE06F"><apiname>RDevUsbcScClient::RealizeInterface()</apiname></xref> is called after <codeph>SetInterface()</codeph> has been called for all alternative settings. </p> <p>On success, a chunk handle is created and passed back through <codeph>aChunk</codeph>. </p> <codeblock id="GUID-B0376164-FF6A-53E2-98CE-FF3BB48F7C4A" xml:space="preserve">RChunk gChunk;

r = gPort.RealizeInterface(gChunk);</codeblock> <p>If you are using the <xref href="GUID-6E89E787-749D-5AC5-957D-967B4B9ACD74.dita">Buffer Interface Layer (BIL)</xref> then use <codeph>FinalizeInterface()</codeph> instead of <codeph>RealizeInterface()</codeph>. <codeph>FinalizeInterface()</codeph> has the same effect a calling <codeph>RealizeInterface()</codeph>, except that the BIL owns the <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> handle. This function must be used if you want to use any other BIL method. </p> <codeblock id="GUID-CD5C8BCC-7F55-5D95-A244-7999C1A0FAF4" xml:space="preserve">RChunk *tChunk = &amp;gChunk;

gPort.FinalizeInterface(tChunk);</codeblock> <p> <b>Note</b>: Calling <codeph>RealizeInterface()</codeph> or <codeph>FinalizeInterface()</codeph> invalidates all further calls to <codeph>SetInterface()</codeph>. All alternative settings must have been initialised before calling these functions. </p> </section> <section><p>After you have set the interface descriptors you could optionally <xref href="GUID-0A9C35DA-DF54-5885-AFE0-F4D5B3E49941.dita">Allocate Resources for Endpoints</xref> or go straight to <xref href="GUID-9597DB22-D932-5A58-9C3C-4E5FCA244253.dita">Re-Enumerate</xref>. </p> </section> </conbody></concept>