<?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-AB9175EB-1B61-5341-B6B9-5613A7862D74" xml:lang="en"><title>Channel

Implementation</title><shortdesc>Describes how to implement <codeph>DComm</codeph> to drive a serial

port hardware.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>A physical channel defines the interface between the logical device and

the physical device. The Serial Port Driver physical channel interface is

defined by the <codeph>DComm</codeph> class. </p>

<p>The <codeph>DComm</codeph> class is defined in: <filepath>...\e32\include\drivers\comm.h</filepath>,

which is exported to <filepath>epoc32\include\drivers</filepath>: </p>

<codeblock id="GUID-F9E58262-51AA-5A58-A113-3FA994F00156" xml:space="preserve">class DComm : public DBase

    {

public:

    virtual TInt Start() =0;

    virtual void Stop(TStopMode aMode) =0;

    virtual void Break(TBool aState) =0;

    virtual void EnableTransmit() =0;

    virtual TUint Signals() const =0;

    virtual void SetSignals(TUint aSetMask,TUint aClearMask) =0;

    virtual TInt ValidateConfig(const TCommConfigV01 &aConfig) const =0;

    virtual void Configure(TCommConfigV01 &aConfig) =0;

    virtual void Caps(TDes8 &aCaps) const =0;

    virtual void CheckConfig(TCommConfigV01& aConfig)=0;

    virtual TInt DisableIrqs()=0;

    virtual void RestoreIrqs(TInt aIrq)=0;

    virtual TDfcQue* DfcQ(TInt aUnit)=0;

    inline TBool PowerGood(); 

    inline void SetCurrent(TInt aCurrent);

    inline void ReceiveIsr(TUint* aChar, TInt aCount, TInt aXonXoff);

    inline TInt TransmitIsr();inline void CheckTxBuffer();

    inline void StateIsr(TUint aSignals);

    inline TBool Transmitting();

public:

    DChannelComm *iLdd;

    TBool iTransmitting;

    };

</codeblock>

<p>Note that <codeph>DComm</codeph> defines the minimum set of functions to

be used by the LDD. A real physical channel object, typically, requires the

addition of an interrupt handler, some DFC callback routines (if these are

not handled in the LDD itself) and various other state variables. </p>

<section id="GUID-B0D61B54-EDF3-4804-9B1E-370C36E01708"><title>DCommVariant constructor</title> <p>Implement the constructor

for the channel object. Since there is no unit number argument, the constructor

is limited to initialising only those members that are common across all possible

channels, with no access to any specific hardware. </p> </section>

<section id="GUID-550681C3-F1A6-4298-BAA5-C6F2D9D61624"><title>DCommVariant destructor</title> <p>Implement the destructor

for the channel object. It should release any hardware and Symbian platform

resources that have been allocated to the driver, typically unbinding the

UART interrupt ISR, and any private DFCs that are still in use. The destructor

merely unbinds the interrupt as no channel specific DFCs are active at destructor

invocation. </p> </section>

<section id="GUID-8254536B-E938-4B86-A735-798DD03E3456"><title>DoCreate()</title> <p>Implement the <codeph>DoCreate()</codeph> channel

initialisation function for the UART driver. In general, defining a <codeph>DoCreate()</codeph> function

is not mandated by the device driver framework but is useful for drivers that

make use of unit numbers. This is called by the factory object’s <xref href="GUID-6DE69F29-45B0-5E62-AA13-DA4041B1BC46.dita#GUID-6DE69F29-45B0-5E62-AA13-DA4041B1BC46/GUID-48EF94F9-ACBC-58DA-9F0E-4034E56C6C74">Create()</xref> function after the device object’s allocation has succeeded. </p> <p>Typical

operations performed by this function are to setup any channel specific hardware

states and bind the driver’s ISR to the (possibly channel specific) interrupt

channel, as well as enabling the UART hardware itself. However, since the <xref href="GUID-AB9175EB-1B61-5341-B6B9-5613A7862D74.dita#GUID-AB9175EB-1B61-5341-B6B9-5613A7862D74/GUID-0CAA6D27-FE2E-5569-8747-EB3D4976E7FD">Start()</xref> function

has not yet been called, it should not enable the UART interrupts/poll routines

which would actively buffer incoming data; any data I/O requests should be

discarded until the driver’s <xref href="GUID-AB9175EB-1B61-5341-B6B9-5613A7862D74.dita#GUID-AB9175EB-1B61-5341-B6B9-5613A7862D74/GUID-0CAA6D27-FE2E-5569-8747-EB3D4976E7FD">Start()</xref> routine

has been called. </p> </section>

<section id="GUID-0CAA6D27-FE2E-5569-8747-EB3D4976E7FD"><title>Start()</title> <p> Implement

the <codeph>Start()</codeph> function. This should enable the driver’s receive

path.</p><p> Received characters are placed in the LDD upstream buffer, either

by the interrupt handler routine, or by a polling routine that tests for the

existence of received characters (and their associated error state). This

is done by calling the LDD’s <codeph>ReceiveIsr()</codeph> routine, with a

pointer to the buffered characters, a count and a flag indicating whether

the XON or XOFF flow control characters have been received.</p><p>The function

is called by the LDD when the owning thread opens the device channel. It should

complete any UART data I/O enabling that has not already been performed in

the <codeph>DoCreate()</codeph> function, i.e. the enabling of UART receive

interrupt processing as a minimum. After this function returns, it is expected

that incoming data will be placed in a (local) buffer and passed upstream

to the LDD, until <xref href="GUID-AB9175EB-1B61-5341-B6B9-5613A7862D74.dita#GUID-AB9175EB-1B61-5341-B6B9-5613A7862D74/GUID-9428082D-581D-530B-8838-1DBF6D0EB8E7">Stop()</xref> is

invoked. Note that since there may have been line activity prior to this call,

it may be necessary to reset the UART state, as we do not want to report errors/states

that may have occurred before the UART was (logically) enabled.</p></section>

<section id="GUID-9428082D-581D-530B-8838-1DBF6D0EB8E7"><title>Stop()</title><p>Implement

the <codeph>Stop()</codeph> function. This should disable the driver’s transmit

and receive paths. </p><p>Depending on the type of stop requested, i.e. emergency

power down, or otherwise, <codeph>Stop()</codeph> may not wait for the UART

to finish transmitting any characters stored in the transmit FIFO queue. All

receive paths are stopped instantly and any characters that may be in the

receive FIFO queue are ignored. </p><p>The function is called by the LDD when

the owning thread closes the device channel. At this point, the UART device

should revert to the state in which all data I/O requests are ignored or failed.

To save OS resources the natural method to accomplish this is to disable the

UART interrupt processing or disable the UART itself. It may also be necessary

to cancel any DFCs queued, so that event notifications are not sent to the

LDD after it has requested an end to I/O. </p></section>

<section id="GUID-5E4B6533-75F5-47FB-A4DF-55FAA1E1B973"><title>DfcQ()</title><p>Implement the <codeph>DfcQ()</codeph> function.

This should return the DFC queue on which the LDD will install its DFCs. Usually

the standard low priority kernel DFC queue 0 is returned. </p></section>

<section id="GUID-ADC89B5B-0E29-4723-92E6-A6F1A5604710"><title>Break()</title><p>Implement the <codeph>Break()</codeph> function.

This starts or ends a BREAK condition on the wire. </p><p>This operation is

explicitly requested by the owning thread through the LDD. A break state requires

the forcing of the line into an abnormal state, which violates standard data

format timings (a form of out of band signalling), and is detected by the

remote device and is usually used to force it to cycle through its baud rate

detection modes. Forcing a break state requires that the PDD explicitly set

some state in the UART hardware. </p></section>

<section id="GUID-82A259A7-54F7-536A-B829-31C0AF3C5C81"><title>Signals()</title><p>Implement

the <codeph>Signals()</codeph> function. This returns the state of the flow

and MODEM control inputs, ie. DCD, DSR, CTS and RI (if implemented on the

device itself). This function is called by the LDD to return the state of

all the handshaking lines so that it can decide whether further data I/O operations

are allowed. </p></section>

<section id="GUID-492D86E5-BEEF-4408-B6E0-6DDA1244CA74"><title>SetSignals()</title><p>Implement the <codeph>SetSignals()</codeph> function.

This controls the state of the flow and MODEM control outputs. It is used

by the LDD to control MODEM handshaking and line failure detection, and can

be invoked in response to a specific user request to change the handshake

signal’s state, or when the LDD itself decides that the output lines states

should be changed in response to some transfer state (e.g. requesting no further

transmissions if buffer availability runs low). </p></section>

<section id="GUID-CB1FA26C-5D29-50ED-AF40-8CC579AF776F"><title>Caps()</title><p>Implement

the <codeph>Caps()</codeph> function. This returns the driver supported configurations:

speed, format, and handshaking. </p><p>It is called by the LDD in response

to a user request for the device's capabilities. The PDD must fill a <xref href="GUID-98A18771-CA6D-3B68-8784-449CDBEC3D88.dita"><apiname>TCommCapsV02</apiname></xref> object,

with the capabilities for that port. </p><p>The object is defined in <filepath>d32comm.h</filepath>: </p><codeblock id="GUID-A95D8753-E574-5C86-85DC-6AA10F635612" xml:space="preserve">class TCommCapsV01

    {

public:

    TUint iRate;

    TUint iDataBits;

    TUint iStopBits;

    TUint iParity;

    TUint iHandshake;

    TUint iSignals;

    TUint iFifo;

    TUint iSIR;

    };

class TCommCapsV02 : public TCommCapsV01

    {

public:

    TUint iNotificationCaps;

    TUint iRoleCaps;

    TUint iFlowControlCaps;

    };</codeblock> <p>The base object, <xref href="GUID-BDBB61A7-18BC-3C85-A258-77D8B16621AD.dita"><apiname>TCommCapsV01</apiname></xref>, defines

capabilities in terms of: </p> <ul>

<li id="GUID-7AE03D23-1013-5522-B219-23153E1B7798"><p>data rate </p> </li>

<li id="GUID-E2FBD4C1-B704-592A-B3A2-1BCFFC7E5451"><p>word format (i.e. parity,

data bits, stop bits) </p> </li>

<li id="GUID-525050DD-8ACE-5580-BDF7-3717295D704E"><p>flow control lines </p> </li>

<li id="GUID-B5DBE4E6-8184-522A-856A-9BD17E76FF33"><p>MODEM control lines </p> </li>

<li id="GUID-62ACC296-4B9B-59D3-8531-480E04264FE0"><p>IrDA support. </p> </li>

</ul> <p>Each attribute range is passed as a bitfield of possible settings,

all assumed to be orthogonal, i.e. each attribute can assume all the values

independently of the other attributes. </p> <p>The attribute bitfields are

defined in <filepath>d32comm.h</filepath>. </p> <p>The <codeph>iSIR</codeph> attribute

in <xref href="GUID-BDBB61A7-18BC-3C85-A258-77D8B16621AD.dita"><apiname>TCommCapsV01</apiname></xref> indicates whether the port can support

slow infrared protocol. </p> <p>The <codeph>iNotificationCaps</codeph> attribute

in <xref href="GUID-98A18771-CA6D-3B68-8784-449CDBEC3D88.dita"><apiname>TCommCapsV02</apiname></xref> allows the driver to describe its ability

to report asynchronous events, if requested to do so by the client thread.

The only useful applications seem to be to report data arrival and handshake

line status change, although fields exist for other capabilities. </p> <p>The <codeph>iRoleCaps</codeph> attribute

in <xref href="GUID-98A18771-CA6D-3B68-8784-449CDBEC3D88.dita"><apiname>TCommCapsV02</apiname></xref> is intended to indicate that the device

is capable of acting as a DCE as well as a DTE, i.e. that the port can be

configured to act like a MODEM port. This essentially reverses the normal

I/O of the status lines, and could add functionality such as ring indication.

Normal UART devices will never need to change this field from the default,

i.e. DTE device personality. </p> <p>The <codeph>iFlowControlCaps</codeph> field

in <xref href="GUID-98A18771-CA6D-3B68-8784-449CDBEC3D88.dita"><apiname>TCommCapsV02</apiname></xref> is unused and should be set to 0. </p> <p>The <codeph>iHandshake</codeph> field

in <xref href="GUID-BDBB61A7-18BC-3C85-A258-77D8B16621AD.dita"><apiname>TCommCapsV01</apiname></xref> describes the flow control signal support

on the device. Input signals have attributes “Obey” and “Fail” e.g. ObeyCts,

FailCts. Output signals have only the “Free” attribute, which indicates they

can be driven (via a call to <xref href="GUID-AB9175EB-1B61-5341-B6B9-5613A7862D74.dita#GUID-AB9175EB-1B61-5341-B6B9-5613A7862D74/GUID-82A259A7-54F7-536A-B829-31C0AF3C5C81">Signals()</xref>)

to any state, independent of the internal state of the UART, i.e. they are

entirely under LDD control. The Fail attribute implies that the LDD will deem

operations to have failed if an input line thus labelled becomes disasserted.

This means that the PDD can report these signal states asynchronously. If,

for example, a change in CTS state can generate an interrupt, then the PDD

should report it as possessing both Obey and Fail attributes, whereas if the

DCD line cannot generate an asynchronous event, it should merely present itself

as “Obey”. If the line is unimplemented then neither attribute should be reported. </p> </section>

<section id="GUID-DA860E4A-4240-4C16-B1C0-5E9B7C96F9E8"><title>Configure()</title> <p>Implement the <codeph>Configure()</codeph> function.

This configures the UART device according to the configuration data passed

into the function. </p> <p>Configuration data is encapsulated by a <xref href="GUID-0CBAE946-AB8E-3114-89FC-9591125C4BDC.dita"><apiname>TCommConfigV02</apiname></xref> object: </p> <codeblock id="GUID-275DAD25-9EF9-5084-A82B-8E2392CB14E8" xml:space="preserve">class TCommConfigV01

    {

public:

    TBps iRate;

    TDataBits iDataBits;

    TStopBits iStopBits;

    TParity iParity;

    TUint iHandshake;

    TUint iParityError;

    TUint iFifo;

    TInt iSpecialRate;

    TInt iTerminatorCount;

    TText8 iTerminator[KConfigMaxTerminators];

    TText8 iXonChar;

    TText8 iXoffChar;

    TText8 iParityErrorChar;

    TSir iSIREnable;

    TUint iSIRSettings;

    };

class TCommConfigV02: public TCommConfigV01

    {

public:

    TInt iTxShutdownTimeout;

    };

</codeblock> <p>This function is called by the LDD when the physical channel

is opened. The default configuration is set by the LDD when the <codeph>Dcomm</codeph> object

is constructed, but the user can override the configuration with a <codeph>SetConfig</codeph> request

on the opened channel. The configuration is described by specifying a set

of individual capability attributes from the supported ranges returned in

the <xref href="GUID-AB9175EB-1B61-5341-B6B9-5613A7862D74.dita#GUID-AB9175EB-1B61-5341-B6B9-5613A7862D74/GUID-CB1FA26C-5D29-50ED-AF40-8CC579AF776F">Caps()</xref> call. </p> <p>Note

that the <codeph>iTerminatorCount</codeph>, the <codeph>iTerminatorArray</codeph> and<codeph> iSpecialRate</codeph> are

currently unused. The <codeph>iParityErrorChar</codeph> replaces the character

that the UART determined had a parity violation. This can be used to send

a prearranged escape character to the upstream LDD. </p> </section>

<section id="GUID-509C63E0-09D9-48F1-8ECB-F18377B73E8A"><title>CheckConfig()</title> <p>Implement the <codeph>CheckConfig()</codeph> function.

This is used by autosensing UARTs to pass detected configuration upstream

to the LDD. This is called by the LDD when it creates the initial channel

to allow the autosensed state to override any default it has set. If the UART

device cannot perform autosensing, and most cannot, then the <codeph>CheckConfig()</codeph> function

should leave the parameter buffer unchanged. </p> </section>

<section id="GUID-6F26F95A-7115-4E07-BA72-7AEF75DC2912"><title>ValidateConfig()</title> <p>Implement the <codeph>ValidateConfig()</codeph> function.

This returns true if the specified configuration is supported by the driver.

This should never return false if the correct capabilities have been setup,

but may be used to check for cases where, for example, a specific set of attributes

cannot be applied together. As an example, a data format word size may not

be generated for some specific baud rate. </p> </section>

<section id="GUID-10FB213C-47B3-4CFF-AB2B-5868AE4531E0"><title>DisableIrqs()</title> <p>Implement the <codeph>DisableIrqs()</codeph> function.

This is called by the LDD to disable (all) interrupts during critical sections,

for example, during LDD buffer manipulation. It calls the kernel utility to

perform the task. </p> </section>

<section id="GUID-BFE0DF32-3D2A-4D86-8BEE-6EB5AF32C3BB"><title>RestoreIrqs()</title> <p>Implement the <codeph>RestoreIrqs()</codeph> function,

called by the LDD to enable (all) interrupts after critical sections have

completed. Calls the kernel utility to perform the task. </p> </section>

<section id="GUID-96B9D6FE-1E2C-45C0-B7F4-E5CF9B5BD802"><title>EnableTransmit()</title> <p>Implement the <codeph>EnableTransmit()</codeph> function.

This initialises the UART transmit hardware, and the transmit ISR code path.

This function can be called from the ISR (on receipt of an unblocking XON

character), or to start a transmission of a LDD originated data buffer. It

causes the UART to generate Tx service interrupts as it finishes transmitting

a FIFOs worth of data, so that the entire buffer (passed by the LDD) can be

sent under interrupt control. </p> </section>

<section id="GUID-593C5E94-A188-48C4-BB02-07268735270A"><title>Data handling routines</title> <p>Implement the main data

handling routines. These are entirely dependent on the UART hardware interface

and cannot therefore be described generally. They are typically driven by

the interrupt service routine as asynchronous events from the UART (eg. data

received, finished transmission of data, change in handshaking/flow control

inputs) occur. </p> <p>The main ISR is typically driven by an interrupt multiplexed

from all the sources in the UART. The ISR, therefore, needs to determine which

of the interrupt sources requires attention. Since the most critical source

is the data received state, as this requires that the data is processed before

following data overwrites earlier data, then this is usually the signal to

be checked first. To avoid wasting time, the error state of the data is also

checked – data that has bad parity or framing must be noted as such. Typically

the receive path will save the currently available data into a temporary buffer,

and queue a DFC to process the data further at a later time, when more client

thread context is available (though this is a function of the LDD). The receive

ISRr just passes the location of the ISR buffer into an LDD function which

queues a DFC to process it. </p> <p>The transmit path, called when the transmit

FIFO contents drop below a programmable number, merely requests more data

from the LDD. If there is none available it disables the transmit interrupt

so as to prevent further requests when there is no data to be sent. Further

data to transmit will cause the transmit FIFO empty interrupt to be re-enabled.

Hence the start of any transmission is always performed on an explicit start

request from the LDD and then continues under PDD interrupt control until

the source data is exhausted. </p> <p>The status notification path is present

to inform the upstream LDD of changes in the input status signals (MODEM and

flow control status). The UART can generate interrupts when any input handshake

line changes state – the ISR merely reads the current state and queues a handler

DFC so that the LDD can be informed. The LDD is responsible for determining

what status change has occurred and dealing with it. </p> </section>