<?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-F20D5802-7B83-5B78-8753-A88E74E28398" xml:lang="en"><title>PSL Implementation</title><shortdesc>This topic describes how to implement the <codeph>DUsbClientController</codeph> interface to provide a platform-specific layer implementation for

the USB client controller.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The platform-specific layer only contains functionality that cannot

be abstracted and made generic because different USB device controller

designs operate differently. For example, the internal (and therefore

external) management of the endpoint FIFOs can be different. In some

USB device controller designs, the endpoints have hardwired FIFOs

of specific sizes, which may possibly be configured, whereas other

designs have a defined maximum amount of FIFO RAM available that has

to be shared by all endpoints in use in a given configuration. The

way that the chip is programmed can also differ. Some designs have

a single register into which all commands and their parameters are

written, whereas others are programmed via a number of special purpose

control registers. </p>

<p>Everything else that has to be common because it is defined in

the USB specification, is contained in the <i>platform-independent

layer</i>. </p>

<p>The operation of the USB device controller is hardware specific

and the implementers of the platform-specific layer is free to do

whatever is necessary to use the hardware. All of this is transparent

to the platform-independent layer, which uses only the fixed set of

pure virtual functions defined in <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita"><apiname>DUsbClientController</apiname></xref> to communicate with the platform-specific layer, and therefore with

the hardware. </p>

<p>The platform-specific layer is also responsible for managing the

transfer of data over the endpoints, and it is important that it can

provide the services expected by the platform-independent layer. Data

transfers are normally set up by the platform-independent layer by

calling one of the following member functions of <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita"><apiname>DUsbClientController</apiname></xref>: </p>

<codeblock id="GUID-34B3EEE2-F83F-5063-9885-5CC0092FB518" xml:space="preserve">TInt SetupEndpointRead(TInt aRealEndpoint, TUsbcRequestCallback&amp; aCallback) = 0;

TInt SetupEndpointWrite(TInt aRealEndpoint, TUsbcRequestCallback& aCallback) = 0;

TInt SetupEndpointZeroRead() = 0;

TInt SetupEndpointZeroWrite(const TUint8* aBuffer, TInt aLength, TBool aZlpReqd=EFalse) = 0;

TInt SendEp0ZeroByteStatusPacket() = 0;</codeblock>

<p>which the platform-specific layer implements. </p>

<p>These data transfer functions fall into two groups: one for handling

endpoint-0 and another for handling general endpoints. Endpoint-0

is handled differently from general endpoints throughout the USB stack.

The functions for handling general endpoints are used to transfer

user data. In addition to taking an endpoint number, these functions

also take a reference to a <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita"><apiname>TUsbcRequestCallback</apiname></xref> object. This is a request callback, it is key to the data transfer

mechanism. </p>

<section id="GUID-B9C7FD99-E5D9-5E08-A219-AD1FE89ED139"><title>Reading

data</title> <ul>

<li id="GUID-96C81B48-9C6A-5EDB-86B3-8F8EC9F94DF0"><p> <xref href="GUID-F20D5802-7B83-5B78-8753-A88E74E28398.dita#GUID-F20D5802-7B83-5B78-8753-A88E74E28398/GUID-4076097E-5FC3-594B-BA00-4A45B78E84CD">General endpoints</xref>  </p> </li>

<li id="GUID-260D22D3-5BA7-50A3-B382-D2E5F74CA5D5"><p> <xref href="GUID-F20D5802-7B83-5B78-8753-A88E74E28398.dita#GUID-F20D5802-7B83-5B78-8753-A88E74E28398/GUID-DD28FFFD-9433-57C9-A517-81BA8E001129">Endpoint-0</xref>  </p> </li>

</ul> <p id="GUID-4076097E-5FC3-594B-BA00-4A45B78E84CD"><b>General endpoints</b> </p> <p>The platform-independent layer issues a request to read

data by calling <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-907F6988-4336-3160-BD41-7FBECE9C6E88"><apiname>DUsbClientController::SetupEndpointRead()</apiname></xref>, which is implemented by the platform-specific layer, passing it

the endpoint and a <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita"><apiname>TUsbcRequestCallback</apiname></xref> object. </p> <p>Data is read into a large buffer, whose address and length are

passed as data members of the <codeph>TUsbcRequestCallback</codeph> object: <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita#GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F/GUID-B8507E01-B472-3FE6-82E7-281094A491C5"><apiname>TUsbcRequestCallback::iBufferStart</apiname></xref> and <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita#GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F/GUID-565F9CC5-15CE-3AF3-87DD-539737E0E628"><apiname>TUsbcRequestCallback::iLength</apiname></xref> respectively. For Bulk reads,

this buffer is intended to catch a burst of data transmitted from

the host rather than just a single packet. </p> <p>For all other transfer

types (Control, Interrupt, Isochronous) it is usual to return only

single packets to the LDD. The amount of data returned is controlled

– and limited - by the USB client driver (the LDD) through the <codeph>iLength</codeph> value. </p> <p>The <codeph>TUsbcRequestCallback</codeph> object also supplies a pair of arrays: </p> <ul>

<li id="GUID-D1993F45-0E58-5ECA-A845-3B300558759B"><p> <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita#GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F/GUID-843E57D1-4703-3127-B1BE-4C93F1AD54FC"><apiname>TUsbcRequestCallback::iPacketIndex</apiname></xref> containing the offset(s) into the data buffer of the single packet

or burst data. </p> </li>

<li id="GUID-6A2DDA06-DCB4-5675-AF62-6A9A5226AA2B"><p> <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita#GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F/GUID-2C7B48F0-5A57-3D72-91ED-9FABC99D25EE"><apiname>TUsbcRequestCallback::iPacketSize</apiname></xref> containing the size(s) of the packet or burst data. </p> </li>

</ul> <p>These arrays are logically linked; both are the same size

and can hold information for two entries each. </p> <p>Therefore,

received single packets have to be merged into one 'superpacket' in

the read buffer. It is assumed that these merged packets consist of

maximum packet sized packets, possibly terminated by a short packet.

A zero length packet or ZLP must appear separately; this would be

the optional second packet in the respective array. </p> <p>For example,

for a Bulk endpoint with a maximum packet size of 64 bytes: </p> <ul>

<li id="GUID-65A91C14-FD6C-5FDD-9DDF-9E9A5F11271A"><p>If 10 x 64 byte

packets and one 10 byte packet arrive, then these are marked as a

single large 650 byte packet. </p> </li>

<li id="GUID-AEA01430-333D-5A6E-B32D-017FEF9B93F7"><p>If 10 x 64 byte

packets and one ZLP arrive, then these should be entered as two packets

in the arrays; one of size 640 bytes and one of size zero. </p> </li>

</ul> <p>The general aim when servicing a Bulk read request from the

platform-independent layer is to capture as much data as possible

whilst not holding onto data too long before returning the data to

the LDD and receiving another buffer. There is considerable flexibility

in how this is achieved and the design does not mandate any particular

method; it also depends to a certain extent on the USB device controller

hardware used. </p> <p>The platform implementation can use a re-startable

timer to see whether data has been received in the time (usually milliseconds)

since the last data was received. If data has been received, then

the timer is restarted. If data has not been received, then the timer

is not restarted, and the buffer is marked as complete for the platform-independent

layer by calling <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-30D6B783-B27B-3ECD-AF34-D22ADF34A12D"><apiname>DUsbClientController::EndpointRequestComplete()</apiname></xref>. </p> <p>Note the following: </p> <ul>

<li id="GUID-60992745-5A02-5177-9707-B9DD6F087AE0"><p>In the interrupt

service routine (ISR), the flag <codeph>iRxMoreDataRcvd</codeph> is

used to indicate that data has been received. </p> </li>

<li id="GUID-2B15F54F-66A6-5788-89E9-68D12D3EB8AF"><p>The timer is

not restarted in the ISR - the timer is allowed to expire and then

a test is made for received data. </p> </li>

<li id="GUID-F5FEF7D6-8DD1-5B12-9AF3-2EBBB18F75A4"><p>Typical values

for the timer range from 1—5 ms. </p> </li>

<li id="GUID-D46B9ABA-5719-5FC3-89F0-3745779F5900"><p>Each OUT endpoint

requires a separate timer. </p> </li>

<li id="GUID-585E00C0-FE41-5176-8DEF-54C0AD8F55E2"><p>The read is

not flagged as complete to the platform-independent layer if no data

has been received. The timer is only started once the first packet/transfer

has been received. </p> </li>

<li id="GUID-62CCCC78-AD45-5570-BC15-050BD4509BC7"><p>The bare minimum

of work is done in the ISR. After draining the FIFO, update the <codeph>iPacketSize</codeph> and <codeph>iPacketIndex</codeph> arrays and

recalculate the buffer address ready for the next packet, taking into

account any alignment restrictions. </p> </li>

</ul> <p>The platform-specific layer completes a non endpoint-0 read

request by calling the platform-independent layer function <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-30D6B783-B27B-3ECD-AF34-D22ADF34A12D"><apiname>DUsbClientController::EndpointRequestComplete()</apiname></xref>. This function

takes as its sole argument a pointer to the updated request callback

structure that was initially passed to the platform-specific layer

for that read. Members that need to be updated, in addition to the

packet arrays <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita#GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F/GUID-843E57D1-4703-3127-B1BE-4C93F1AD54FC"><apiname>TUsbcRequestCallback::iPacketIndex</apiname></xref> and <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita#GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F/GUID-2C7B48F0-5A57-3D72-91ED-9FABC99D25EE"><apiname>TUsbcRequestCallback::iPacketSize</apiname></xref>, are: </p> <ul>

<li id="GUID-7EF9E9C2-DE14-5290-B3FE-B91918669AE2"><p> <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita#GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F/GUID-8B2D125B-9943-386F-9A27-11CC1A25A0C2"><apiname>TUsbcRequestCallback::iRxPackets</apiname></xref>, with possible values: 1 or 2. </p> </li>

<li id="GUID-9E1800A9-8D39-5D5D-92D0-13AF9CD3EF2A"><p> <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita#GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F/GUID-A00F6B27-655A-3182-96E2-8B3D2404CB7C"><apiname>TUsbcRequestCallback::iError</apiname></xref>  </p> </li>

</ul> <p><b>Summary of Completion Criteria for general Endpoints</b> </p> <p>The platform-specific layer completes a read request by calling <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-30D6B783-B27B-3ECD-AF34-D22ADF34A12D"><apiname>DUsbClientController::EndpointRequestComplete()</apiname></xref> when any

of the following conditions are met: </p> <ul>

<li id="GUID-F66AF5EC-56D4-5133-A930-2BB793478B31"><p>The requested

number of bytes has been received. </p> </li>

<li id="GUID-91D9D4E4-2196-55C9-9595-1BA6AE2C2848"><p>A short packet,

including a ZLP, is received. In the case of a ZLP being received,

it must be represented separately in the <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-E5FD5F91-B22B-31A9-8482-635B2F1EB0B4"><apiname>DUsbClientController::iPacketIndex</apiname></xref> and <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-BFB565F1-C8F9-3E44-88FB-E81E88D2DF3A"><apiname>DUsbClientController::iPacketSize</apiname></xref> arrays. </p> </li>

<li id="GUID-42124450-1AC8-59F3-9C30-8C74EC425CAE"><p>If the number

of bytes in the current packet (still in the FIFO) were to cause the

total number of bytes to exceed the buffer length <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-A0A7399A-A51E-3544-A181-5C45B69AB121"><apiname>DUsbClientController::iLength</apiname></xref>. </p> </li>

<li id="GUID-09281AB5-7240-5B29-B0C1-C5A4A8289B7F"><p>The timer has

expired, data is available, but no further packets have been received. </p> </li>

</ul> <p id="GUID-DD28FFFD-9433-57C9-A517-81BA8E001129"><b>Endpoint-0</b> </p> <p>The handling of endpoint-0 read requests is similar to general

endpoints except for the following: </p> <ul>

<li id="GUID-D9361990-1591-522E-9F9E-7E38A6EB0B08"><p>The platform-independent

layer issues the request by calling <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-B3B4793E-7B75-3C40-A6FA-CD17B460CC73"><apiname>DUsbClientController::SetupEndpointZeroRead()</apiname></xref>. This function does not take any parameters because: </p> <ul>

<li id="GUID-4AED5324-65B5-5BD3-AACA-5EA9FB7CB90A"><p>The endpoint

number is known, this is zero. </p> </li>

<li id="GUID-9CEAFC92-DF2D-5B07-B623-5BA562EC61BE"><p>The request

is completed after every received packet, and a <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita"><apiname>TUsbcRequestCallback</apiname></xref> object is not needed. </p> </li>

</ul> </li>

</ul> <p>All the platform-specific layer needs to know is where to

place the received data, and its size. Both are fixed values: <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-BC2DF410-292B-354A-BCEF-2C9E520024B8"><apiname>DUsbClientController::iEp0_RxBuf</apiname></xref> and <xref href="GUID-D0DFABCF-15B4-347E-BAE5-0F050E137949.dita"><apiname>KUsbcBufSzControl</apiname></xref> respectively. </p> <p>An endpoint-0 read request is completed by

calling <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-71E33976-C185-34FA-A8BF-7DB3404DDA78"><apiname>DUsbClientController::Ep0RequestComplete()</apiname></xref>, passing the endpoint number (0, or symbolically, <codeph>KEp0_Out</codeph>), the number of bytes received, and the resulting error code for

this request. </p> </section>

<section id="GUID-2617EDBD-6792-53B9-9CE0-6B0CC729728C"><title>Writing

data</title> <ul>

<li id="GUID-97BDD391-F5BE-509C-AF67-51AD4822FD11"><p> <xref href="GUID-F20D5802-7B83-5B78-8753-A88E74E28398.dita#GUID-F20D5802-7B83-5B78-8753-A88E74E28398/GUID-69839EA3-9DC0-5A3C-BE62-AC91708477BA">General endpoints</xref>  </p> </li>

<li id="GUID-8E0F6F8F-D3DA-5E67-8E8C-E4BE983DBF1A"><p> <xref href="GUID-F20D5802-7B83-5B78-8753-A88E74E28398.dita#GUID-F20D5802-7B83-5B78-8753-A88E74E28398/GUID-C674608C-393B-5397-A1E4-3C8368E2144C">Endpoint-0</xref>  </p> </li>

</ul> <p id="GUID-69839EA3-9DC0-5A3C-BE62-AC91708477BA"><b>General endpoints</b> </p> <p>The platform-independent layer issues a request to write

data by calling <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-F7880D1C-7E7D-3214-BF84-8811DA935B0C"><apiname>DUsbClientController::SetupEndpointWrite()</apiname></xref>, which is implemented by the platform-specific layer, passing the

function an endpoint and a <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita"><apiname>TUsbcRequestCallback</apiname></xref> object. </p> <p>The address of the buffer, containing the data to

be written, is passed into the data member <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita#GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F/GUID-B8507E01-B472-3FE6-82E7-281094A491C5"><apiname>TUsbcRequestCallback::iBufferStart</apiname></xref>. The length of this buffer is passed into <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita#GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F/GUID-565F9CC5-15CE-3AF3-87DD-539737E0E628"><apiname>TUsbcRequestCallback::iLength</apiname></xref>. The buffer is a single contiguous piece of memory. </p> <p>The

platform-specific layer's implementation needs to set up the transfer,

either using DMA or a conventional interrupt driven mechanism, and

then wait for the host to collect, by sending an IN token, the data

from the respective endpoint’s primed FIFO. This continues until all

data from the buffer has been transmitted to the host. </p> <p>If

the ZLP request flag <codeph>iZlpReqd</codeph> in the <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita"><apiname>TUsbcRequestCallback</apiname></xref> structure is set (=<xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref>), then the platform

specific layer must determine, after all data has been sent, whether

to send a ZLP or not. The decision is based on the size of the last

packet sent and the current maximum packet size of the endpoint. </p> <p>To summarize, a ZLP should be sent at the end of a write request

if: </p> <ul>

<li id="GUID-B3AFEC6D-EB74-57FE-9618-E44C6AE10460"><p>The ZLP flag

is set. </p> </li>

<li id="GUID-970EE707-24D1-53B8-A830-3824562F2AA8"><p>The last packet

of the write request was not a short packet (i.e. it was a max-packet-sized

packet). </p> </li>

</ul> <p>The platform-specific layer completes a non endpoint-0 write

request by calling the platform-independent layer function <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-30D6B783-B27B-3ECD-AF34-D22ADF34A12D"><apiname>DUsbClientController::EndpointRequestComplete()</apiname></xref>. This function

takes only one argument, a pointer to the updated request callback

structure passed to the platform-specific layer for this write. Members

that need to be updated are: </p> <ul>

<li id="GUID-F02F662E-ABAE-5519-A80C-DA4D66F7A51A"><p> <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita#GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F/GUID-31AF87D2-C1F3-3367-93AA-52924612A7D0"><apiname>TUsbcRequestCallback::iTxBytes</apiname></xref>  </p> </li>

<li id="GUID-D8416C51-7A46-560F-9F6F-2565DA445004"><p> <xref href="GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F.dita#GUID-D395BF82-65B3-3A98-800B-E6EF43150E8F/GUID-A00F6B27-655A-3182-96E2-8B3D2404CB7C"><apiname>TUsbcRequestCallback::iError</apiname></xref>  </p> </li>

</ul> <p id="GUID-C674608C-393B-5397-A1E4-3C8368E2144C"><b>Endpoint-0</b> </p> <p>The handling of endpoint-0 write requests is similar to general

endpoints except for the following: </p> <p>The platform-independent

layer issues the request by calling <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-DBE7AC29-8B85-3D98-BAF9-8EF059B33331"><apiname>DUsbClientController::SetupEndpointZeroWrite()</apiname></xref>. Unlike the equivalent read function, this function takes a number

of parameters: </p> <ul>

<li id="GUID-9831D5A3-2032-5C6C-B2AF-C78D9E00D09C"><p>the address

of the location containing the data to be written </p> </li>

<li id="GUID-C7F55C63-4AD4-5A37-B25B-1249850C5A92"><p>the length of

the data to be written </p> </li>

<li id="GUID-C2D21E5A-6FB9-5170-80F2-6B6351E5B11A"><p>a <xref href="GUID-4B942C06-1BAC-3A21-B3B1-89FB5C51ADA0.dita"><apiname>TBool</apiname></xref> parameter that indicates whether a zero length packet (ZLP) is to

be sent immediately after the data has been sent. </p> </li>

</ul> <p>An endpoint-0 write request is completed by calling <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-71E33976-C185-34FA-A8BF-7DB3404DDA78"><apiname>DUsbClientController::Ep0RequestComplete()</apiname></xref>, in the platform-independent

layer, passing the function the endpoint number (0, or symbolically <codeph>KEp0_In</codeph>), the number of bytes written, and the error code

for this write request. </p> <p>There is another endpoint-0 write

function, <xref href="GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941.dita#GUID-82FA9C04-0B7E-3FAD-9AAD-3A68E1E6A941/GUID-95CCCE69-C8AA-39B1-8152-37AA0A7B9CEB"><apiname>DUsbClientController::SendEp0ZeroByteStatusPacket()</apiname></xref>, which is used for sending a zero length packet (ZLP) on its own.

This separate function is provided because the USB device controller

mechanism for transmitting a ZLP on its own can be different to the

mechanism for transmitting the ZLP at the end of a data transmission. </p> </section>

<section id="GUID-0805DDC6-2C17-50A2-97B6-F51C77DF3E4F"><title>Using

DMA</title> <p>When planning to use DMA for transferring data from

and to the endpoints’ FIFOs, there are two things that must be considered: </p> <ul>

<li id="GUID-0E6B3A5B-CA84-5BB1-9447-70C7E493D8D2"><p> <xref href="GUID-F20D5802-7B83-5B78-8753-A88E74E28398.dita#GUID-F20D5802-7B83-5B78-8753-A88E74E28398/GUID-838483AC-BDDD-5A6A-AB8A-F26587851D9E">Flushing cached information for the data buffers</xref>  </p> </li>

<li id="GUID-B9545262-93E4-5AA9-837F-D909B278B19F"><p> <xref href="GUID-F20D5802-7B83-5B78-8753-A88E74E28398.dita#GUID-F20D5802-7B83-5B78-8753-A88E74E28398/GUID-840EB8C0-8C29-5FDE-9505-D6D7131E61A4">Implementing DMA mode for OUT transfers (DMA reads)</xref>  </p> </li>

</ul> <p id="GUID-838483AC-BDDD-5A6A-AB8A-F26587851D9E"><b>Flushing cached

information for the data buffers</b> </p> <p>The cached information

for the data buffers must be flushed before a DMA write operation,

(i.e. transfer memory to a FIFO), and both before and after a DMA

read operation, (i.e. transfer a FIFO to memory). </p> <p>The kernel

provides three functions for that purpose. These are static functions

in the class <xref href="GUID-4425E698-EE8A-369B-92CD-09B1CBD2911F.dita"><apiname>Cache</apiname></xref>, declared in <filepath>...\e32\include\kernel\cache.h</filepath>: </p> <ul>

<li id="GUID-4402C336-1638-5830-90A8-0A9746BC3CC7"><p> <xref href="GUID-4425E698-EE8A-369B-92CD-09B1CBD2911F.dita#GUID-4425E698-EE8A-369B-92CD-09B1CBD2911F/GUID-5F08DEAA-1237-32DE-AE41-CE7B18230972"><apiname>Cache::SyncMemoryBeforeDmaWrite()</apiname></xref>  </p> </li>

<li id="GUID-BD880077-FF37-5604-BECF-EB4D86803EB4"><p> <xref href="GUID-4425E698-EE8A-369B-92CD-09B1CBD2911F.dita#GUID-4425E698-EE8A-369B-92CD-09B1CBD2911F/GUID-3FF3C567-C1BD-3D4E-97E1-B036456A374E"><apiname>Cache::SyncMemoryBeforeDmaRead()</apiname></xref>  </p> </li>

<li id="GUID-49E1143C-2B5C-5E92-8ED8-66F75EB41D69"><p> <xref href="GUID-4425E698-EE8A-369B-92CD-09B1CBD2911F.dita#GUID-4425E698-EE8A-369B-92CD-09B1CBD2911F/GUID-78E6DE46-61F0-3840-B555-6926D21141BF"><apiname>Cache::SyncMemoryAfterDmaRead()</apiname></xref>  </p> </li>

</ul> <p id="GUID-840EB8C0-8C29-5FDE-9505-D6D7131E61A4"><b>Implementing DMA

mode for OUT transfers (DMA reads)</b> </p> <p>The implementation

of DMA mode for IN transfers is normally relatively straightforward,

however complications can occur with OUT transfers (DMA reads), depending

on the DMA controller, the USB device controller and the way the two

are connected. </p> <p>There are two issues: </p> <ol id="GUID-324F21A0-F3EB-5994-B23C-B0AD18973C2B">

<li id="GUID-7513B814-D305-50A0-B18D-779D8F5B741E"><p>If we set up

a DMA read for 4kB, for example, and this request returns after a

short packet, we must be able to tell how much data has been received

and is now in our buffer. In other words, the DMA controller must

provide a way of finding out how many bytes have been received, otherwise

we cannot complete the read request to the LDD. </p> <p>Here is a

theoretical solution for a Scatter/Gather controller that doesn’t

provide information about the number of bytes transferred directly. <b>Note: </b> This proposal has not been tested in practice! </p> <p>Instead of using one large DMA descriptor for 4kB, we could set up

a chain of descriptors for max-packet-size bytes each. When the DMA

completes, it will be: </p> <ul>

<li id="GUID-B088943E-BEC6-568B-8E0E-7AA177566599"><p>for the whole

transfer, in which case we know the number of bytes received. </p> </li>

<li id="GUID-33974049-2069-57A3-A784-4A312BA846D8"><p>because it is

a short packet. In this case we can try and find out which descriptor

was being served at the time. The number of bytes received is then </p> <codeblock id="GUID-56C3A794-4077-5A83-BA17-E6BE58A675D4" xml:space="preserve">number of completed descriptors * max-packet-size + number of bytes in short packet.</codeblock> </li>

</ul> </li>

<li id="GUID-E7406164-A6C4-5508-AD5D-A8DA4F2E4AAC"><p>Another potential

problem is posed by the restartable OUT endpoint timer described in

the section <xref href="GUID-F20D5802-7B83-5B78-8753-A88E74E28398.dita#GUID-F20D5802-7B83-5B78-8753-A88E74E28398/GUID-B9C7FD99-E5D9-5E08-A219-AD1FE89ED139">Reading data</xref>. The situation in the timer callback DFC, when

the LDD read request is about to complete, has to be handled with

care in order to avoid data loss. If at this point the pending DMA

request has already started transferring data from the endpoint FIFO

into our data buffer, then we cannot complete the LDD request anymore

(this data would be lost because the LDD would not know about it as

the variables in the request structure do not take account of it).

The buffer cannot be removed while it is receiving data from a DMA

transfer. A possible solution would be as follows: (again, this is

just an idea and therefore untested). In the timer DFC, before we

complete to the LDD, we cancel the pending DMA request. If a DMA transfer

was already happening, then this will somehow complete and the DMA

complete DFC will be queued. What we need to find out in that situation

is whether or not that DFC is pending: </p> <ul>

<li id="GUID-EA31A9E0-5783-5E3C-BFAF-AE041FBC61F1"><p>if not, then

there was no DMA transfer ongoing, and we can just complete our read

request to the LDD. </p> </li>

<li id="GUID-E971CEC8-B0EA-5924-83A6-6FF4E4EB8C9E"><p>otherwise we

have to abandon, at this point, the plan to complete and return from

the timer callback (without doing any damage). In this case, the DMA

complete DFC will run next, the LDD read request structure will be

updated, the RX timer will be set again, and we can proceed as normal. </p> </li>

</ul> </li>

</ol> </section>

</conbody></concept>