/*

* Copyright (c) 2007-2008 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "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:

*

* Description:  spia interface declaration

*

*/

/*

* %version: 7 %

*/

#ifndef WLANSPIA_H

#define WLANSPIA_H

class MWlanSpiaClient;

class MWlanOsaExt;

#include <wlanspiatypes.h>

/**

 *  spia interface declaration

 *

 *

 *  @lib wlanpdd.pdd

 *  @since S60 v3.2

 */

class WlanSpia 

    {

public:

    typedef TInt TRequestId;

    /* SPI transfer clock speed. The closest one is selected if the 

     * exact clock frequency cannot be achieved. 

     * The closest is always less than the requested frequency.*/

    enum TClockSpeed

        {

        EClk1_5MHz = 0,

        EClk3MHz,

        EClk6MHz,

        EClk12MHz,

        EClk24MHz,

        EClk48MHz,

        EClk96MHz

        };

    /* SPI clock modes used for transfer. 

       Next picture shows what different configuration values means.

                               ,--> Sampling

                               | ,> Shift out

                               | |

            high/rising  ______|¯|_|¯|_|¯|_ (mode 0)

            high/falling ____|¯|_|¯|_|¯|_|¯ (mode 1)

            low/falling  ¯¯¯¯¯¯|_|¯|_|¯|_|¯ (mode 2)

            low/rising   ¯¯¯¯|_|¯|_|¯|_|¯|_ (mode 3)

    */

    enum TClockMode

        {

        /* SPI clock active high, sampling occurs on the rising edge */

        EPolarityHighRisingEdge = 0,

        /* SPI clock active high, sampling occurs on the falling edge */

        EPolarityHighFallingEdge,

        /* SPI clock active low, sampling occurs on the falling edge */

        EPolarityLowFallingEdge,

        /* SPI clock active low, sampling occurs on the rising edge */

        EPolarityLowRisingEdge

        };

    /* SPI slave select signal polarity used for transfer */

    enum TSsPolarity

        {

        /** SS is held \e high during the active state */

        ESsPolarityHigh = 0,

        /** SS is held \e low during the active state */

        ESsPolarityLow

        };

    /* SPI read mode, used when reading is done */

    enum TReadMode

        {

        /* normal read from SPI slave device 

         * (i.e no write involved for this call) */

        ENormalRead = 0,

        /* write buffer is written completely 

         * before the read operation is done */

        EWriteB4Read,

        /* full duplex mode 

         * Tx and Rx are done at same time

         * NOTE: Tx and Rx buffers must not overlap and must be of equal size  */        

        ECombinedWriteRead

        };

    struct TConfig

        {

        /* SPI clock mode */

        TClockMode iSpiaClockMode;

        /* SPI slave select signal polarity */

        TSsPolarity iSpiaSsPolarity;

        /* number of bytes per frame in tx */

        TUint8 iTxBytesPerFrame;

        /* number of bytes per frame in rx */

        TUint8 iRxBytsPerFrame;

        };

    /* SPI slave select mode */    

    enum TSsMode    

    {

        /* slave select is active during the whole SPI request operation */

        EForcedActive = 0,

        /* slave select is toggled on SPI frame basis during the whole SPI request */        

        EFrameControlled                

    };

    struct TCapabilities

    {

    /* bit 0 - memory config support: 

     * bit clear non cached memory supported, bit set cached memory supported

     * default value is cleared 

     * bit 1 - ENormalRead support in TReadMode: bit set when supported          

     * bit 2 - EWriteB4Read support in TReadMode: bit set when supported               

     * bit 3 - ECombinedWriteRead support in TReadMode: bit set when supported          

     * bit 4 - EForcedActive support in TSsMode: bit set when supported                       

     * bit 5 - EFrameControlled in TSsMode: bit set when supported */        

    TUint32 iCapability;

    /* Length of the memory cache line in bytes (needed for buffer alignment) */

    TUint32 iCacheLineLength;

    /* DMA threshold for SPI operations */

    TUint32 iDMAThreshold;

    };

    /* SPIA request structure */

    struct TRequest

        {

        /* tx buffer. Buffer length must be multiple of sizeof(TInt) */

        const TUint8* iTxBuffer;

        /* amount of data to transmit in the tx buffer in bytes */

        TUint   iTxBufferSize;

        /* rx buffer. Buffer length must be multiple of sizeof(TInt) */

        TUint8* iRxBuffer;

        /* amount of data to read to the rx buffer in bytes */

        TUint   iRxBufferSize;

        /* read operation type */

        TReadMode   iReadMode;

        /* complete callback method client to be called after 

         * the request has completed */

        MWlanSpiaClient* iRequestClient;

        /* unique request ID passed back to client as 

         * is in SPIA request callback */

        TRequestId iRequestId;

        /* SPI transfer clock speed. 

         * The closest one is selected if exact clock frequency 

         * can not be achieved. The closest is always less 

         * than the requested frequency. */

        TClockSpeed iSpiaClockSpeed;

        /* last request or not for a while, a hint for power management 

         * ETrue upon last request, any other not */

        TBool iLastRequest;

        /* SPI slave select mode used */        

        TSsMode iSsMode;

        };

	/**

	 * Destructor.

	 *

	 * @since S60 v3.2

	 */

    virtual ~WlanSpia() {};

    /**

     * Create spia layer object

     *

     * @since S60 v3.2

     * @param aOsaExt osa extension object

     * @return spia layer object, NULL upon failure

     * @deprecated Create() and Attach( MWlanOsaExt& ) should be used instead

     */

    static WlanSpia* Create( MWlanOsaExt& aOsaExt );

    /**

     * Create spia layer object

     *

     * @since S60 v3.2

     * @return spia layer object, NULL upon failure

     */

    static WlanSpia* Create();

    /**

     * Attach the OSA extension object

     *

     * @since S60 v3.2

     * @param aOsaExt osa extension object

     */

    void Attach( MWlanOsaExt& aOsaExt );

    /**

     * Destroy spia layer object

     *

     * @since S60 v3.2

     * @param aWlanSpia spia layer object

     */

    static void Destroy( WlanSpia* aWlanSpia );

    /**

     * Extract module capabilities

     *

     * @since S60 v3.2

     * @param aCapabilities capabilities of the module

     */    

    virtual void Capability( TCapabilities& aCapabilities ) { aCapabilities.iCapability = 0; }

    /**

     * Configures the SPI HW block

     *

     * @since S60 v3.2

     * @param aConfig SPI configuration data

     */

    virtual void Configure( const TConfig& aConfig ) = 0;

    /**

     * Issues SPIA request

     *

     * NOTE: the request must remain valid until operation completes 

     * (either synchronously or asynchronously by completion callback).

     * It is guaranteed by the system that no SPIA request complete callback 

     * gets called during this call

     *

     * @since S60 v3.2

     * @param aRequest request to execute

     * @return status of the operation

     *         ESuccess -       request was accepted for asynchronous 

     *                          excecution and will complete at a later time.

     *                          Request completion is notified by 

     *                          SPIA request complete callback.

     *                          SPIA user is allowed to issue additional 

     *                          requests

     *

     *         EFailure -       request was not accepted as it failed due 

     *                          unspecified reason.

     *                          SPIA request complete callback is not called 

     *

     *         ESuccessXfer -   request was accepted and completed 

     *                          synchronously inside the SPIA. 

     *                          SPIA request complete callback is not called. 

     *                          SPIA user is allowed to issue additional 

     *                          requests

     *

     *         EPending -       request was accepted for asynchronous 

     *                          excecution and will complete at later time. 

     *                          Request completion is notified by 

     *                          SPIA request complete callback.

     *                          SPIA user is NOT allowed to issue additional 

     *                          requests until SPIA request complete callback is called

     */

    virtual SPIA::TStatus Request( const TRequest& aRequest ) = 0; 

    /**

     * Cancels a pending SPIA request. Either succeeds or has no effect

     *

     * NOTE: it is guaranteed by the system that no SPIA request complete callback 

     * gets called during this call

     *

     * @since S60 v3.2

     * @param aRequestId request ID that identifies the SPIA request to cancel

     * @return status of the operation

     *         ESuccess -       operation success. 

     *                          SPIA request was cancelled and no SPIA request

     *                          complete callback gets executed for the request 

     *                          that was cancelled

     * 

     *

     *         EFailure -       the request is in use and can not be cancelled. 

     */

    virtual SPIA::TStatus Cancel( TRequestId aRequestId ) = 0;

protected:

    /**

     * Constructor 

     *

     * @since S60 v3.2

     */

    explicit WlanSpia() : iOsaExt( NULL ) {}

    /**

     * Constructor 

     *

     * @since S60 v3.2

     * @param aOsaExt osa extension object

     */

    explicit WlanSpia( MWlanOsaExt& aOsaExt ) : iOsaExt( &aOsaExt ) {}

    /**

     * Extract osa extension

     *

     * @since S60 v3.2

     * @return osa extension

     */

    inline MWlanOsaExt& OsaExtCb();

private:

    /**

     * osa extension

     */

    MWlanOsaExt*    iOsaExt;

    };

#include <wlanspia.inl>

#endif // WLANSPIA_H