<?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-4AEF7595-17C0-513E-9568-B212E6194388" xml:lang="en"><title>Record

operation</title><shortdesc>Describes the operation of the Sound Driver for sound recording.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-0722033C-4BC0-45D0-B980-C1FC680BBF70"><title>Client functions</title> <p>Many aspects regarding the way

that the Sound Driver recording operates are similar to the way it handles

playback. One difference is how the memory location in the <xref href="GUID-51514A4B-0220-557B-9F7A-FB110CEFEF10.dita">Shared

Chunks</xref> for the transfer is determined. In play requests, the client

specifies the source location in the chunk for the transfer having arranged

for the data to be loaded there prior to the request. For record requests,

the client just requests a buffers worth of record data and allows the driver

to decide which buffer to use for the request. </p> <p>The driver commences

recording when the client issues the first <xref href="GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3.dita#GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3/GUID-D96D7433-6CB5-3368-8B51-C19731C474AF"><apiname>RSoundSc::RecordData()</apiname></xref> request.

However, unlike playback operation, once recording has commenced, the driver

continues to record data into its available record buffers until it is told

to stop. To stop the driver capturing record data, the client must either

issue <xref href="GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3.dita#GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3/GUID-16C40CF6-C84D-3901-8527-EA66842E0AAC"><apiname>RSoundSc::Pause()</apiname></xref> to temporarily suspend recording, <xref href="GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3.dita#GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3/GUID-4B53ED55-EC95-35B3-B9D6-A24EF70D81F9"><apiname>RSoundSc::CancelRecordData()</apiname></xref> to

terminate record operation, or close the driver channel altogether. </p> <p>The

client specifies the number and size of the record buffers available to the

driver within the shared chunk by calling either <xref href="GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3.dita#GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3/GUID-1978D84C-6E2A-39C0-AF5F-17C85E5B25B4"><apiname>RSoundSc::SetBufferChunkCreate()</apiname></xref>,

to create a buffer, or <xref href="GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3.dita#GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3/GUID-46096E39-A530-3644-91F0-0B97AC3C6580"><apiname>RSoundSc::SetBufferChunkOpen()</apiname></xref> to

open an existing buffer. </p> <p>When the driver starts recording, all the

buffers in the shared chunk are empty, and the driver can use all of these

available buffers. They are filled one by one, and if the client is slow to

request the recorded data, then once the driver has filled all of the available

empty buffers, it is forced to discard the earliest one filled and re-use

this to continue recording data. </p> <p>Each time the client requests a buffers

worth of recorded data with <xref href="GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3.dita#GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3/GUID-D96D7433-6CB5-3368-8B51-C19731C474AF"><apiname>RSoundSc::RecordData()</apiname></xref>, it

is given the earliest one filled. This buffer is now said to be in-use and

unavailable to the driver for capturing. This buffer remains in-use until

it is freed by the client with a call of <xref href="GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3.dita#GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3/GUID-26F7C97B-D06A-32BE-90B3-2E6918BF3F4D"><apiname>RSoundSc::ReleaseBuffer()</apiname></xref>. </p> <p>When

buffers are in use by the client the number of buffers available to the driver

for capture is reduced. If the client is slow to release buffers and the number

of available buffers falls to two then further <xref href="GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3.dita#GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3/GUID-D96D7433-6CB5-3368-8B51-C19731C474AF"><apiname>RSoundSc::RecordData()</apiname></xref> requests

fail with <codeph>KErrInUse</codeph> until the client has freed some buffers.

The driver always needs a working set of at least two buffers in order to

achieve uninterrupted data capture. The driver always has a current buffer

which is actively being filled and another queued in advance. If the client

fails to take buffers at full speed then they are discarded by the driver. </p><p><note> The

driver does not slow down if it runs out of empty buffers. </note></p> <p><b>Buffers</b> </p> <p>The driver maintains three buffer lists: </p> <ul>

<li id="GUID-D0B884B5-3687-5CB9-B732-1B028F0008A8"><p>free list </p> </li>

<li id="GUID-3A3FAAA7-72C2-5A35-9F4D-3824966D3D52"><p>completed list </p> </li>

<li id="GUID-E571D299-99C5-51D1-832E-55A88533B365"><p>in-use list. </p> </li>

</ul> <p>A record buffer can only exist in one of these lists at any time.

The free list contains buffers that are empty and not in use by the client.

Once a buffer has been filled with record data it is moved into the completed

buffer list. Here the buffer remains until it is passed back to the client

in response to a record request. When a client is using the buffer it is deemed

as in-use and is moved to the <i>in-use</i> list. Each time the client successfully

calls <xref href="GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3.dita#GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3/GUID-26F7C97B-D06A-32BE-90B3-2E6918BF3F4D"><apiname>RSoundSc::ReleaseBuffer()</apiname></xref> to free up a buffer then

the driver moves this from the in-use list to the free list. </p> <p>The driver

also maintains two record buffers which are excluded from any of the three

lists. </p> <ul>

<li id="GUID-3EB509DB-F35F-51E7-AAD9-8A25EEDAE604"><p>the current buffer,

the one actively being filled with record data </p> </li>

<li id="GUID-E109F4E5-998D-5B19-AE82-A913BBF4CED3"><p>the next buffer which

becomes the active buffer once the current buffer is filled </p> </li>

</ul> <p>During recording there may be DMA requests pending for both the current

buffer and the next buffers. </p> <fig id="GUID-FBF47E94-8334-55D3-9AC0-FDAF1F9960B1">

<title>                 The record buffer cycle               </title>

<desc><p>The numbers one to five show the buffer cycle under normal operation,

while the letters A to C show error induced operation. </p> </desc>

<image href="GUID-1A92047A-3C1D-5B4C-949B-98D770F5F530_d0e420445_href.png" placement="inline"/>

</fig> <p>When recording commences, the driver removes two buffers from the

free list making one the current buffer and the other the next buffer (4 and

5). </p> <p>When the current buffer is set as filled, the LDD normally adds

this to the completed list (1). If a record error has occurred while recording

to this buffer and it is only partially filled, or even empty then the buffer

is still added to the completed list, as the client needs to be informed of

the error (1). The only exception is in handling record pause, where a record

buffer ends up being completed with no error and with no data added. In this

case the buffer is added straight into the free list (A). </p> <p>Having added

the current buffer to one of these lists, the driver moves the next buffer

to the current buffer (5) and then obtains a new next buffer (4). In normal

operation this comes from the free list but if the client is slow, this list

may be empty and the buffer is taken from the completed list (B). This is

a buffer overflow situation which is reported to the client as a response

to its next <xref href="GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3.dita#GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3/GUID-D96D7433-6CB5-3368-8B51-C19731C474AF"><apiname>RSoundSc::RecordData()</apiname></xref> request as <codeph>KErrOverFlow</codeph>. </p> <p>Whenever

a buffer is filled, the driver checks if there is a record request pending

(1). Similarly, when the driver processes a new record request it checks if

a filled buffer is already available. In either case, if a request can be

completed to the client then the earliest buffer completed is returned. If

this buffer was filled successfully then it added to the in-use list (2).

However, if an error occurred whilst filling the buffer then it is returned

straight to the free list instead (C). </p> <p>Each time the client successfully

calls <xref href="GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3.dita#GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3/GUID-26F7C97B-D06A-32BE-90B3-2E6918BF3F4D"><apiname>RSoundSc::ReleaseBuffer()</apiname></xref> to free up a buffer then

the driver moves this from the in-use list to the free list (3). </p> </section>

<section id="GUID-548515F6-403D-4C99-AAA3-027C7D303C73"><title>Audio recording</title> <p><b>RecordData()</b> </p> <p>If

the driver is not already recording data then the first <xref href="GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3.dita#GUID-B0118EDD-2B08-353E-BE92-2DC75E5622B3/GUID-D96D7433-6CB5-3368-8B51-C19731C474AF"><apiname>RSoundSc::RecordData()</apiname></xref> request

is handled in the context of the driver DFC thread, as access to the audio

hardware is required to enable record operation. However, for efficiency,

subsequent record requests from the client are handled entirely in the context

of the calling thread, as access to the audio hardware is not required to

handle the request. The driver only has to check whether there is a filled

record buffer already available. If there is then the driver completes the

request straight away. If not, the driver saves the details of the request

until a filled buffer does become available. </p> <p>Returning to the case

of a record request where the driver is not already in the process of recording

data, the LDD first checks whether the client has specified or supplied a

shared chunk to the driver channel and has set the audio configuration and

record level. If the buffer configuration has not been specified then the

driver cannot proceed and returns <codeph>KErrNotReady</codeph>. If the audio

configuration or record level has not been specified then the LDD applies

default settings to the audio hardware device for each instead by calling

the functions <xref href="GUID-E1C67F8D-1A83-36B3-A451-22F496A659C6.dita#GUID-E1C67F8D-1A83-36B3-A451-22F496A659C6/GUID-23CEDA72-E161-30C4-B8D7-DBDCBC5B9C63"><apiname>DSoundSc::SetConfig()</apiname></xref> and <xref href="GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424.dita#GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424/GUID-D893A29B-1A4B-35AF-876B-84D74B7E783C"><apiname>DSoundScPdd::SetVolume()</apiname></xref> on

the PDD. </p> <p><b>StartTransfer()</b> </p> <p>Depending

on the mapping attributes of the shared chunk, the LDD may now need to purge

the region of the record chunk concerned. Next the LDD calls <xref href="GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424.dita#GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424/GUID-54D3CC19-0C00-3FFA-BD1A-62618D36EB20"><apiname>DSoundScPdd::StartTransfer()</apiname></xref> on

the PDD to allow it to prepare the audio hardware device for record data transfer. </p> <p><b>TransferData()</b> </p> <p>The LDD may need to break down the record buffer

into memory fragments. These specify a physically contiguous region and are

manageable by the PDD as a single transfer. The LDD queues as many transfer

fragments of the current buffer on the PDD as it can accept with a call to <xref href="GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424.dita#GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424/GUID-8C79D09B-317A-3D8E-B9C2-474812F17529"><apiname>DSoundScPdd::TransferData()</apiname></xref> for

each fragment. If all fragments from the current buffer are accepted by the

PDD then the LDD tries to queue fragments from the next buffer. As with playback,

to support uninterrupted transfer of audio data the PDD must be able to accept

multiple fragments simultaneously. As long as the LDD has transfer fragments

still to queue, it continues to call <xref href="GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424.dita#GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424/GUID-8C79D09B-317A-3D8E-B9C2-474812F17529"><apiname>DSoundScPdd::TransferData()</apiname></xref> until

the PDD signals that it has temporarily reached its capacity by returning <codeph>KErrNotReady</codeph>. </p> <p><b>RecordCallBack()</b> </p> <p>Each time the PDD completes the transfer

of a fragment from a record buffer, it must signal this event back to the

LDD by calling the function <xref href="GUID-5807543D-A30F-3EB9-8F28-91A623B0D484.dita#GUID-5807543D-A30F-3EB9-8F28-91A623B0D484/GUID-9112E399-DC3C-334F-BE16-B5F42216F903"><apiname>DSoundScLdd::RecordCallBack()</apiname></xref>.

This must always be called in the context of the driver DFC thread. In executing <xref href="GUID-5807543D-A30F-3EB9-8F28-91A623B0D484.dita#GUID-5807543D-A30F-3EB9-8F28-91A623B0D484/GUID-434E378F-0C48-39D9-8FB8-9831A1F704C0"><apiname>DSoundScLdd::RecordCallback()</apiname></xref>,

the LDD checks whether the entire transfer for the current buffer is now complete.

If so, depending on the mapping attributes of the shared chunk, the LDD may

need to purge the region of the record client. The LDD attempts to queue further

fragments on the PDD, by calling <xref href="GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424.dita#GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424/GUID-8C79D09B-317A-3D8E-B9C2-474812F17529"><apiname>DSoundScPdd::TransferData()</apiname></xref>,

which should now have the capability to accept more transfers. So, the PDD

should be written to handle calls to <xref href="GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424.dita#GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424/GUID-8C79D09B-317A-3D8E-B9C2-474812F17529"><apiname>DSoundScPdd::TransferData()</apiname></xref> within

its call back to <xref href="GUID-5807543D-A30F-3EB9-8F28-91A623B0D484.dita#GUID-5807543D-A30F-3EB9-8F28-91A623B0D484/GUID-434E378F-0C48-39D9-8FB8-9831A1F704C0"><apiname>DSoundScLdd::RecordCallback()</apiname></xref>. </p> </section>

<section id="GUID-7B5CF9A4-8527-4C76-96CD-C03F861AF3BF"><title>Pause and resume audio recording</title> <p>The client can

temporarily halt the progress of audio record at any time by issuing <xref href="GUID-5807543D-A30F-3EB9-8F28-91A623B0D484.dita#GUID-5807543D-A30F-3EB9-8F28-91A623B0D484/GUID-D912620F-9C51-3AFC-8A59-31AF9455AC4A"><apiname>DSoundScLdd::Pause()</apiname></xref>.

To configure the audio hardware device to halt recording, the LDD calls <xref href="GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424.dita#GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424/GUID-0608766F-2645-3E28-B804-BD4B953DB5FF"><apiname>DSoundScPdd::PauseTransfer()</apiname></xref> on

the PDD. This time, any active transfer should be aborted by the PDD. If a

recording is halted the PDD must signal this event with a single call of the

LDD function <xref href="GUID-3731902C-9C34-3FAE-8F82-9F9493C2C2E7.dita#GUID-3731902C-9C34-3FAE-8F82-9F9493C2C2E7/GUID-73F74080-6219-3D9A-BA56-735A17A9ABA0"><apiname>DSOundScLdd::RecordCallback()</apiname></xref>, which reports

back any partial data already received. In this case, if transfer is resumed

later, the LDD issues a new <xref href="GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424.dita#GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424/GUID-8C79D09B-317A-3D8E-B9C2-474812F17529"><apiname>DSoundScPdd::TransferData()</apiname></xref> request

to commence data transfer after calling <xref href="GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424.dita#GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424/GUID-C692BF61-FA3D-3B85-BCC6-1248C9C7D9BF"><apiname>DSoundScPdd::ResumeTransfer()</apiname></xref>.

As access to the hardware is required in both cases, pause and resume are

handled in the context of the driver DFC thread. </p> </section>

<section id="GUID-BA951968-290F-4DA5-842A-2004664B1139"><title>Error handling during recording</title> <p>If the PDD reports

an error when setting up the audio hardware device for recording then the

LDD immediately completes the first record request back to the client returning

the error value as the result. It will not restart record data transfer unless

it receives a further record request from the client. </p> <p>If the PDD reports

an error when commencing the transfer of a record fragment or as the result

of the transfer of a record fragment, then the LDD ceases transfer to that

record buffer and instead reports the error back to the client. The error

is returned in response to the record request which corresponds with that

buffer. </p> <p>Unexpected errors from the PDD are returned to the LDD via

the functions <xref href="GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424.dita#GUID-61CC68CB-A01D-3CA0-93D9-F3717ABD6424/GUID-8C79D09B-317A-3D8E-B9C2-474812F17529"><apiname>DSoundScPdd::TransferData()</apiname></xref> and <xref href="GUID-5807543D-A30F-3EB9-8F28-91A623B0D484.dita#GUID-5807543D-A30F-3EB9-8F28-91A623B0D484/GUID-434E378F-0C48-39D9-8FB8-9831A1F704C0"><apiname>DSoundScLdd::RecordCallback()</apiname></xref>. </p> <p>The

LDD does not try to cancel the transfer of other fragments for the same buffer

that are already queued on the PDD, but it ignores their outcome. However,

the LDD does try to carry on with the transfer to other available record buffers. </p> </section>