<?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-2380FDDE-5489-5B1C-87BB-1FD882E385D2" xml:lang="en"><title>Migration

Tutorial: Direct Memory Addressing</title><shortdesc>To handle direct memory addressing, you must to make the following

changes to your code. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>If a media driver uses a data transfer mechanism like <xref href="GUID-E5576D91-BC5C-588E-BF90-5A1E3C445133.dita">DMA</xref>,

data transfer can be faster if the media driver knows that an address passed

in an I/O request is a physical address. This is known as direct memory addressing. </p>

<ul>

<li id="GUID-E2C6E9D0-0150-529C-953E-32DFDEA68E77"><p> <xref href="GUID-2380FDDE-5489-5B1C-87BB-1FD882E385D2.dita#GUID-2380FDDE-5489-5B1C-87BB-1FD882E385D2/GUID-621EB44F-25BB-5B71-BF74-ED0304B7B591">Changes to registration</xref>  </p> </li>

<li id="GUID-62701989-76A6-52D5-A713-226343BED4EE"><p> <xref href="GUID-2380FDDE-5489-5B1C-87BB-1FD882E385D2.dita#GUID-2380FDDE-5489-5B1C-87BB-1FD882E385D2/GUID-49992CF9-404A-585C-8770-E9034434A344">Changes to request handling</xref>  </p> </li>

<li id="GUID-79FF128E-98B3-5613-B02A-08A81FC5B82D"><p> <xref href="GUID-2380FDDE-5489-5B1C-87BB-1FD882E385D2.dita#GUID-2380FDDE-5489-5B1C-87BB-1FD882E385D2/GUID-5F4A392F-0EAF-5E69-B902-D987B8FFD610">Issues about physical addresses</xref>  </p> </li>

</ul>

<section id="GUID-621EB44F-25BB-5B71-BF74-ED0304B7B591"><title>Changes to

registration</title> <p>If the media driver code can handle physical addresses,

it must tell the local media subsystem. This process is called registration.

The media driver calls <xref href="GUID-9E60E8D9-619E-3A76-BAC8-93A60D62C7DF.dita#GUID-9E60E8D9-619E-3A76-BAC8-93A60D62C7DF/GUID-57B3380F-3CA6-3FF4-9D79-05B718E0743A"><apiname>LocDrv::RegisterDmaDevice()</apiname></xref> to register

as part of the <xref href="GUID-A70A01D2-467E-5BA8-A01D-6182558F3F52.dita">media

driver initialisation</xref> process. The media driver calls <codeph>RegisterDmaDevice()</codeph> after

the media driver has <xref href="GUID-A70A01D2-467E-5BA8-A01D-6182558F3F52.dita#GUID-A70A01D2-467E-5BA8-A01D-6182558F3F52/GUID-4A8DEEAB-32C4-5431-8226-5623E2BD9098">registered

with the local media subsystem</xref>. </p> <p>After the call to <xref href="GUID-9E60E8D9-619E-3A76-BAC8-93A60D62C7DF.dita#GUID-9E60E8D9-619E-3A76-BAC8-93A60D62C7DF/GUID-57B3380F-3CA6-3FF4-9D79-05B718E0743A"><apiname>LocDrv::RegisterDmaDevice()</apiname></xref>,

the local media subsystem will test if the address in an I/O request is a

physical address or a virtual address. The local media subsystem extracts

the information that the media driver requires. The media driver gets this

information through calls to the functions: </p> <ul>

<li id="GUID-93AEF5CB-CB70-5369-BC33-9F2B51903FFE"><p> <xref href="GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C.dita#GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C/GUID-DD6773B4-9EF5-322F-B53D-29174DF3B3BF"><apiname>TLocDrvRequest::IsPhysicalAddress()</apiname></xref>. </p> </li>

<li id="GUID-33328F10-BE3D-5ADA-8FFE-5E19764E43F1"><p> <xref href="GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C.dita#GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C/GUID-9879145B-D996-327E-87F6-3B8337A86A56"><apiname>TLocDrvRequest::GetNextPhysicalAddress()</apiname></xref>. </p> </li>

</ul> <p>A <xref href="GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C.dita"><apiname>TLocDrvRequest</apiname></xref> object represents an I/O request

and is passed to the media driver. </p> <p>There are three pieces of information

that the local media subsystem needs from the media driver when the media

driver registers: </p> <ul>

<li id="GUID-7A889D6A-52E0-5FBB-BC2F-A1E10A0F0D4D"><p>The <i>minimum number

of bytes</i> that the media device can transfer. For example, the architecture

of some memory card types requires data transfer in blocks of 512 bytes. The

local media subsystem can not support I/O requests for physical addresses

where the length of the data is smaller than this minimum number. This limit

prevents accidental access of the data outside the limits of the request. </p> </li>

<li id="GUID-C778CC22-699B-5B01-B217-C6567CBE01E3"><p>The <i>maximum number

of bytes</i> that the media driver can transfer in one burst. This value depends

on the hardware. For eaxample,<xref href="GUID-0D2F811C-81C3-526F-8EA4-98E50261BF4B.dita">DMA

Framework</xref> has limits that depend on the DMA controller. </p> </li>

<li id="GUID-49B448A8-B8ED-5EF6-9AB2-BA43FD6ED34F"><p>The <i>alignment of

memory</i> that the DMA controller requires. For example: a DMA controller

might require 2 byte (word or 16 bit) alignment or 4 byte (double word or

32 bit) alignment. For 2 byte alignment, specify 2; for 4 byte alignment specify

4 etc. The local media subsystem can not support I/O requests for physical

addresses that are not aligned according to this value. </p> </li>

</ul> <p>You get all of this information from the documentation for the platform. </p> <p>This

example code extends the code shown in the section <xref href="GUID-A70A01D2-467E-5BA8-A01D-6182558F3F52.dita">Media

driver initialisation before the system is initialised</xref>. It adds a call

to <xref href="GUID-9E60E8D9-619E-3A76-BAC8-93A60D62C7DF.dita#GUID-9E60E8D9-619E-3A76-BAC8-93A60D62C7DF/GUID-57B3380F-3CA6-3FF4-9D79-05B718E0743A"><apiname>LocDrv::RegisterDmaDevice()</apiname></xref>. This call follows registration

of the media driver with the local media subsystem. </p> <codeblock id="GUID-A56AFE4C-729A-57DA-B232-60A29CE7F735" xml:space="preserve">DECLARE_STANDARD_EXTENSION()

    {

    TInt r=KErrNoMemory;

    DPrimaryMediaBase* pM=new DPrimaryMediaBase;

    if (pM)

        {//…Required here for Asynchronous creation (if supported)

        pM->iDfcQ = &MyDfcQ;

        // Perform registration here

        r = LocDrv::RegisterMediaDevice(MEDIA_DEVICE_TYPE,

                                        MEDIA_DRIVECOUNT,

                                        &IMediaDriveNumbers[0],

                                        pM,MEDIA_NUMMEDIA,KMediaDriveName

                                       );

        if ® != KErrNone)

            {

            return r;

            }

        // Register support for physical addressing.

        //

        // Note : in practice the values passed to RegisterDmaDevice() would be

        // either symbolic constants or functions that return values. If the 

        // media driver is split into platform independent and platform dependent

        // layers, and this code is in the independent layer, then you will need 

        // functions in the dependent layer to provide these values.

        r = LocDrv::RegisterDmaDevice(pM,

                                                    512,  // Block Addressing 512 Bytes

                                                    1024, // 1024 Byte address range

                                                    2 );  // 2 Byte alignment

        if ® != KErrNone)

            {

            return r;

            }

        ...

        }

    return®);

    }

      </codeblock> </section>

<section id="GUID-49992CF9-404A-585C-8770-E9034434A344"><title> Changes to

request handling</title> <p>To use physical addreses, you need to make changes

to the code that deals with <codeph>ERead</codeph> and <codeph>EWrite</codeph> requests

in your implementation of the <xref href="GUID-EBF025DB-1552-5E99-8C07-09932DB60552.dita#GUID-EBF025DB-1552-5E99-8C07-09932DB60552/GUID-EC193360-31C2-5012-8ED2-19F1C48C8FC5">DMediaDriver::Request()</xref> function. This section discusses the issues with <codeph>ERead</codeph> requests,

but the principles apply to <codeph>EWrite</codeph> requests. </p> <p>There

are a number of points to consider: </p> <p><b>Check if the address is physical </b> </p> <p>Call <xref href="GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C.dita#GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C/GUID-DD6773B4-9EF5-322F-B53D-29174DF3B3BF"><apiname>TLocDrvRequest::IsPhysicalAddress()</apiname></xref> to

test if the address passed is a physical address. For example, for a <codeph>ERead</codeph> request: </p> <codeblock id="GUID-90F1EE30-DAE5-5DE5-B42E-9EF48EB12509" xml:space="preserve">...

   // iReadReq points to a TLocDrvRequest object

   ...

   iMediaStartPos = iReadReq->Pos();

   iTotalLength   = I64LOW(iReadReq->Length()); 

   iDoPhysicalAddress = iReadReq->IsPhysicalAddress();

   if(iDoPhysicalAddress)

      {

      ..< Physical address memory code >..

      }

   else

      {

      ...&lt; Virtual address memory code &gt;...</codeblock> <p><b>Physical address code </b> </p> <p>If you want to use the physical address,

you need to get the physical address and the length of contiguous memory at

this location. Call <xref href="GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C.dita#GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C/GUID-9879145B-D996-327E-87F6-3B8337A86A56"><apiname>TLocDrvRequest::GetNextPhysicalAddress()</apiname></xref> to

get the physical address and the length of physically contiguous memory. The

length of physically contiguous memory can be smaller than the length supplied

in the read request, because physical memory can be fragmented into a number

of small blocks. If the length is smaller than the length supplied in the

read or write request, you call <xref href="GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C.dita#GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C/GUID-9879145B-D996-327E-87F6-3B8337A86A56"><apiname>TLocDrvRequest::GetNextPhysicalAddress()</apiname></xref> again

to get the address of the next physically contiguous block of memory. You

repeat this operation until the read request is complete. For example, for

a <codeph>ERead</codeph> request: </p> <codeblock id="GUID-2311A626-38BF-582F-B310-8E30D73AA1A7" xml:space="preserve">...

   // iReadReq points to a TLocDrvRequest object

   ...

   TPhysAddr physAddr; 

   TInt physLength;

   TInt err = KErrNone;                

   err = iReadReq->GetNextPhysicalAddress(physAddr, physLength);

   if(err == KErrNone)

      {                       

      if (physLength < iTotalLength)

         {

         // Memory is fragmented, note remainder. You will need 

         // to use this code again using the remainder value.

         iRemaining    = iTotalLength – physLength;

         iTotalLength -= physLength;

         }

      // Start data transfer into the current physically

      // contiguous block of physical memory.

      DoDataTransfer(iMediaStartPos, physLength, physAddr);

      ...

      }

</codeblock> <p>If you do not want to deal with fragmented physical memory,

you can use your original code. </p> <p><b>Virtual to physical address translation </b> </p> <p>Your code must not

perform a virtual to physical address translation when it deals with physical

memory. For example: </p> <codeblock id="GUID-4377A0D5-8E41-59AF-B26E-C468ABAFCF47" xml:space="preserve">void DMMCRxDmaHelp::ChannelTransfer(const SDmaPseudoDes&amp; aDes)

      {

      …

      TPhysAddr dest;

      if (iCurrentReq->IsPhysicalAddress())

         dest = (TPhysAddr) aDes.iDest;

      else

         dest = Epoc::LinearToPhysical(aDes.iDest);

      TPlatDma::SetDMARegister(KHoDMA_CDSA(iChno), dest);

      …

      }</codeblock> <p><b>Eliminate inter-process copy </b> </p> <p>You must change your code to

remove calls to <xref href="GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C.dita#GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C/GUID-842F91FF-C780-3E2A-8860-8F34815452FC"><apiname>TLocDrvRequest::WriteRemote()</apiname></xref>. For <codeph>ERead</codeph> requests,

data for transfer is already at the physical address. For example: </p> <codeblock id="GUID-1B14C66A-476C-5E3F-B0D7-502B54324D74" xml:space="preserve">if (!iCurrentReq-&gt;IsPhysicalAddress())

      {

      if( (id == DMediaPagingDevice::ERomPageInRequest)||

          (id == DMediaPagingDevice::ECodePageInRequest) )

         {

         r = iCurrentReq->WriteToPageHandler((TUint8 *)(& iBufPtr [0]), len, usrOfst);

         }

      else if(id==DLocalDrive::ERead)

         {

         r = iCurrentReq->WriteRemote(&iBufPtr,usrOfst);

         }

      }</codeblock> <p>The same logic applies to <codeph>EWrite</codeph> requests.

You need to remove calls to <xref href="GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C.dita#GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C/GUID-96B80631-AD1C-35E8-8613-0A630BD7D9E9"><apiname>TLocDrvRequest::ReadRemote()</apiname></xref>. </p> <p><b>Test your changes </b> </p> <p>You are recommended to run regression tests

on your changed code to makes sure that the media driver operates correctly. </p> </section>

<section id="GUID-5F4A392F-0EAF-5E69-B902-D987B8FFD610"><title>Issues about

physical addresses</title> <p>If the media driver can use physical addresses,

you need to be aware of a number of issues. </p> <p><b>The address scheme used by the hardware </b> </p> <p>All media devices

have a minimum number of bytes that they can transfer. For example, the architecture

of some memory card types requires data transfer in blocks of 512 bytes. To

read one byte from this type of media device, the media driver must read a

block of 512 bytes and extract the byte from the block. To write one byte

to a media device, the media driver must read a block of 512 bytes, change

the content of the byte, and write the block to the media device. </p> <p><b>Data transfer smaller than the minimum size </b> </p> <p>If the local

media subsystem receives a request to transfer data with a length smaller

than the minimum transfer size, the local media subsystem does not make a

physical address available to the media driver. A call to <xref href="GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C.dita#GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C/GUID-DD6773B4-9EF5-322F-B53D-29174DF3B3BF"><apiname>TLocDrvRequest::IsPhysicalAddress()</apiname></xref> returns

false. It is considered unsafe to give access to the physical data surrounding

the requested memory location. </p> <p><b>Data transfer not aligned to the media device block boundary </b> </p> <p>If

the local media subsystem receives a request to transfer data, and the address

on the media device is <i>not aligned</i> to the media device block boundary,

you need to adopt the technique suggested below. The local media subsystem

will make the physical address available to the media driver. A call to <xref href="GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C.dita#GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C/GUID-DD6773B4-9EF5-322F-B53D-29174DF3B3BF"><apiname>TLocDrvRequest::IsPhysicalAddress()</apiname></xref> returns

true. </p> <p>Consider the following case. A request has been made to read

1024 bytes from a media device that has a block size of 512 bytes. The 1024

bytes start at offset +256 on the media device. </p> <fig id="GUID-2689C022-180B-51EF-A02D-E63ACA832EB2">

</fig> <p>To get the first 256 bytes, you must read the first block of 512

bytes from the media device. This can corrupt the physical memory passed in

the I/O request. The solution is to read the first block from the media device

into an intermediate buffer. Copy the 256 bytes from that buffer into the

physical memory passed in the I/O request. </p> <p>To get the last 256 bytes,

you must read the third block of 512 bytes from the media device into the

intermediate buffer. Copy the 256 bytes from that buffer into the correct

position in the physical memory passed in the I/O request. </p> <p>The middle

512 bytes are aligned on the media device block boundary. The media driver

can read this data into the correct position in the physical memory passed

in the I/O request. </p> <p><b>Scatter/Gather DMA controllers </b> </p> <p>DMA controllers can support

the Scatter/Gather mode of operation. Each request in this mode of operation

consists of a set of smaller requests chained together. This chain of requests

is called the Scatter/Gather list. Each item in the list consists of a physical

address and a length. </p> <p>Use <xref href="GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C.dita#GUID-D84A9903-AE0F-3F54-8833-E8956A88E26C/GUID-9879145B-D996-327E-87F6-3B8337A86A56"><apiname>TLocDrvRequest::GetNextPhysicalAddress()</apiname></xref> to

help you populate the Scatter/Gather list. </p> <p>The following code fragment

shows how you do this. The example assumes that the DMA controller supports

a Scatter/Gather list with an unlimited number of entries. In practice, the

number of entries in the list is finite. </p> <codeblock id="GUID-EC3A441C-080F-5EB8-B0E8-E658F80687D4" xml:space="preserve">TPhysAddr physAddr; 

   TInt physLength;

   TInt err = KErrNone;

   while (iRemaining > 0)

      {

      err = iCurrentReq->GetNextPhysicalAddress(physAddr, physLength);

      if(err != KErrNone)

         return err;

      iRemaining -= physLength;

      PopulateScatterGatherList(physAddr, physLength);

      }                            

   return DoDataTransfer(pos, length);</codeblock> </section>

</conbody><related-links>

<link href="GUID-86082C0C-B0EE-5E7C-85B4-4A509066012F.dita"><linktext>MMC Porting

Implementation Tutorial</linktext></link>

</related-links></concept>