/*

* Copyright (c) 2009 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:

*

* Description:

*

*/

// Ethernet.h

//

//

/** @file ethernet.h

Base classes for implementating ethernet support (Kernel-side only)

@internalComponent

*/

#ifndef __ETHERNET_H__

#define __ETHERNET_H__

#include <platform.h>

#include <d32ethernet.h>

#include <e32ver.h>

/** @addtogroup enet Ethernet Drivers

 *  Kernel Ethernet Support

 */

/** @addtogroup enet_ldd Driver LDD's

 * @ingroup enet

 */

const TInt KEthernetMajorVersionNumber = 1;

const TInt KEthernetMinorVersionNumber = 0;

const TInt KEthernetBuildVersionNumber = KE32BuildVersionNumber;

/**

	@publishedPartner

	@released

*/

const TInt KTxWorkBudgetLimit  = 10;

// Card Rx constants.

const TInt KNumRXBuffers       = 40;

/**

	@publishedPartner

	@released

*/

const TInt KIRQWorkBudgetLimit = 4;

/**

	@publishedPartner

	@released

*/

const TInt KRxWorkBudgetLimit  = 6;

/**

	@publishedPartner

	@released

*/

const TInt KMaxEthernetPacket = 1518;

/**

	@publishedPartner

	@released

*/

const TUint16 CRC_LEN = 4;

/** @addtogroup enet_pdd Driver PDD's

 * @ingroup enet

 * @{

 */

/**

    Different Stop Modes

	@publishedPartner

	@released

 */

enum TStopMode 

    {

    EStopNormal,    /**< Finish sending and then stop */

    EStopEmergency  /**< Just stop now */

    };

class DChannelEthernet;

/**

	Ethernet driver base class

	The base class for an ethernet driver that doesn't support power control

	@publishedPartner

	@released

*/

class DEthernet : public DBase

    {

    public:

    /**

     * Start receiving frames

     * @return KErrNone if driver started

     */

    virtual TInt Start() =0;

    /**

     * Stop receiving frames

     * @param aMode The stop mode

     */

    virtual void Stop(TStopMode aMode) =0;

    /**

     * Validate a new config

     * Validates a new configuration should be called before Configure

     * @param aConfig is the configuration to be validated

     * @return ETrue or EFalse if the Configuration is allowed

     * @see Configure()

     */

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

    /**

     * Configure the device

     * Reconfigure the device using the new configuration supplied.

     * This should not change the MAC address.

     * @param aConfig The new configuration

     * @see ValidateConfig()

     * @see MacConfigure()

     */

    virtual TInt Configure(TEthernetConfigV01 &aConfig) =0;

    /**

     * Change the MAC address

     * Attempt to change the MAC address of the device

     * @param aConfig A Configuration containing the new MAC

     * @see Configure()

     */

    virtual void MacConfigure(TEthernetConfigV01 &aConfig) =0;

    /**

     * Get the current config from the chip

     * This returns the current configuration of the chip with the folling fields

     * The Transmit Speed

     * The Duplex Setting

     * The MAC address

     * @param aConfig is a TEthernetConfigV01 referance that will be filled in

     */

    virtual void GetConfig(TEthernetConfigV01 &aConfig) const =0;

    /**

     * Check a configuration

     * @param aConfig	a reference to the structure TEthernetConfigV01 with configuration to check

     */

    virtual void CheckConfig(TEthernetConfigV01& aConfig)=0;

    /**

     * Querie the device's capibilitys

     * @param aCaps To be filled in with the capibilites

     */

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

    /**

     * Transmit data

     * @param aBuffer referance to the data to be sent

     * @return KErrNone if the data has been sent

     */

    virtual TInt Send(TBuf8<KMaxEthernetPacket+32> &aBuffer) =0;

    /**

     * Retrieve data from the device

     * Pull the received data out of the device and into the supplied buffer. 

     * Need to be told if the buffer is OK to use as if it not we could dump 

     * the waiting frame in order to clear the interrupt if necessory.

     * @param aBuffer Referance to the buffer to be used to store the data in

     * @param okToUse Bool to indicate if the buffer is usable

     * @return KErrNone if the buffer has been filled.

     */

    virtual TInt ReceiveFrame(TBuf8<KMaxEthernetPacket+32> &aBuffer, 

                              TBool okToUse) =0;

    /**

     * Disables all IRQ's

     * @return The IRQ level before it was changed

     * @see RestoreIrqs()

     */

    virtual TInt DisableIrqs()=0;

    /**

     * Restore the IRQ's to the supplied level

     * @param aIrq The level to set the irqs to.

     * @see DisableIrqs()

     */

    virtual void RestoreIrqs(TInt aIrq)=0;

    /**

     * Return the DFC Queue that this device should use

     * @param aUnit The Channel number

     * @return Then DFC Queue to use

     */

    virtual TDfcQue* DfcQ(TInt aUnit)=0;

    /**

     * The Receive Isr for the device

     */

    inline void ReceiveIsr();

#ifdef ETH_CHIP_IO_ENABLED

    virtual TInt BgeChipIOCtrl(TPckgBuf<TChipIOInfo> &aIOData)=0;

#endif

    /**

     * A pointer to the logical device drivers channel that owns this device

     */

    DChannelEthernet * iLdd ;

    };

/** @} */ // End of pdd group

/**

 * @addtogroup enet_ldd_nopm_nopccard Ethernet LDD Not PCMCIA and No Power Managment

 * @ingroup enet_ldd

 * @ingroup enet_misa

 * @ingroup enet_wins

 * @{

 */

/**

	Ethernet logical device

	The class representing the ethernet logical device

	@internalComponent

*/

class DDeviceEthernet : public DLogicalDevice

    {

    public:

    /**

     * The constructor

     */

    DDeviceEthernet();

    /**

     * Install the device

     */

    virtual TInt Install();

    /**

     * Get the Capabilites of the device

     * @param aDes descriptor that will contain the returned capibilites

     */

    virtual void GetCaps(TDes8 &aDes) const;

    /**

     * Create a logical channel to the device

     */

    virtual TInt Create(DLogicalChannelBase*& aChannel);

    };

/**

	Stores the Tx and RX buffers for use in a ethernet logical channel

	@internalComponent

 */

class DChannelEthernetFIFO 

    {

    public:

    /**

     * The TX Buffer

     */

    TBuf8<KMaxEthernetPacket+32> iTxBuf;

    /**

     * The constructor

     */

    DChannelEthernetFIFO();

    /**

     * The destructor

     */

    ~DChannelEthernetFIFO();

    /**

     * Get a empty receive buffer

     * @return NULL or a pointer to the free buffer

     */

    TBuf8<KMaxEthernetPacket+32> * GetFree();

    /**

     * Get the next full buffer

     * @return NULL or a pointer to the full buffer

     */ 

    TBuf8<KMaxEthernetPacket+32> * GetNext();

    /**

     * Move on to the next full buffer

     */

    void SetNext();

    private:

    /**

     * The array of receive buffers

     */

    TBuf8<KMaxEthernetPacket+32> iRxBuf[KNumRXBuffers];

    /**

     * Index into the array of the next full buffer

     */

    TInt iRxQueIterNext;

    /**

     * Index into the array of the next empty buffer

     */

    TInt iRxQueIterFree;

    /**

     * Count of the number of empty buffers

     */

    TInt iNumFree;

    };

/**

	The logical channel for ethernet devices

	The basic ethernet logical channel that doesn't support

	power control or PCCard ethernet devices

	@internalComponent

 */

class DChannelEthernet : public DLogicalChannel

    {

    public:

    /**

     * The state of the logical channel

     */

    enum TState 

        {

        EOpen,    /**< The channel is open */

        EActive,  /**< The channel is open and busy */

        EClosed   /**< The channel is closed */

        };

    /**

     * Requests that can be made on the channel

     */

    enum TRequest 

        {

        ERx=1,      /**< Receive a frame */

        ETx=2,      /**< Transmit a frame */

        EAll=0xff   /**< Complete/cancel all outstanding requests */

        };

    /**

     * The constructor 

     */

    DChannelEthernet();

    /**

     * The destructor

     */

    ~DChannelEthernet();

    /**

     * The ISR function for the channel

     * This is called by the pycical channels ISR when data is received

     * It passes a empty buffer to the PDD for it to store the frame in

     */

    virtual void ReceiveIsr();

    protected:

    /**

     * Create a logical ethernet channel

     * @param aUnit The channel number to create

     * @param anInfo not used, can be NULL

     * @param aVer The minimun driver version allowed

     * @return KErrNone if channel created

     */

    virtual TInt DoCreate(TInt aUnit, const TDesC8* anInfo, const TVersion& aVer);

    /**

     * Handle a message from the channels user

     * @param aMsg The message to handle

     */

    virtual void HandleMsg(TMessageBase* aMsg);

    /**

     * Cancel an outstanding request

     * @param aMask A mask containing the requests to be canceled

     */

    void DoCancel(TInt aMask);

    /**

     * Preform a control operation on the channel

     * Control operations are:

     * - Get the current configuration

     * - Configure the channel

     * - Set the MAC address for the channel

     * - Get the capibilities of the channel

     * @param aId The operation to preform

     * @param a1 The data to use with the operation

     * @param a2 can be NULL - not used

     * @return KErrNone if operation done

     */

    TInt DoControl(TInt aId, TAny* a1, TAny* a2);

    /**

     * Preform an asynchros operation on the channel

     * Operations are:

     * - Read data from the channel

     * - Write data to the channel

     * @param aId The operation to perform

     * @param aStatus The status object to use when complete

     * @param a1 The data to use

     * @param a2 The length of the data to use

     * @return KErrNone if operation started ok

     * @see Complete()

     */

    TInt DoRequest(TInt aId, TRequestStatus* aStatus, TAny* a1, TAny* a2);

	//Override sendMsg to copy clients memory in client context for WDP.

	virtual TInt SendMsg(TMessageBase* aMsg);

	TInt SendControl(TMessageBase* aMsg);

	TInt SendRequest(TMessageBase* aMsg);

    /**

     * Start the channel receiving

     */

    void Start();

    /**

     * Shutdown the channel

     */

    void Shutdown();

    /**

     * Complete an RX request

     * Is run as the RX DFC and reads a buffer from the receive FIFO into

     * the users buffer

     */

    void DoCompleteRx();

    /** 

     * Completes an outstanding request

     * @param aMask Specifies what request to complete

     * @param aReason The reason the request is complete

     * @see DoRequest()

     */

    void Complete(TInt aMask, TInt aReason);

    /**

     * Disables all IRQ's

     * @return The IRQ level before it was changed

     * @see RestoreIrqs()

     */

    inline TInt DisableIrqs();

    /**

     * Restore the IRQ's to the supplied level

     * @param aIrq The level to set the irqs to.

     * @see DisableIrqs()

     */

    inline void RestoreIrqs(TInt aIrq);

    /**

     * Calls the PDD's start method

     * @return KErrNone if the PDD started ok

     */

    inline TInt PddStart();

    /**

     * Calls the PDD's Validate method

     * @param aConfig The configuration to be validated

     * @return KErrNone if config is valid

     */

    inline TInt ValidateConfig(const TEthernetConfigV01 &aConfig) const;

    /**

     * Calls the PDD's Configure method

     * Should call Validate first

     * Will not change the MAC address

     * @param aConfig The new configuration

     * @see ValidateConfig()

     */

    inline void PddConfigure(TEthernetConfigV01 &aConfig);

    /**

     * Calls the PDD's MacConfigure method

     * Will not change anything but the MAC address

     * @param aConfig A configuration containing the new MAC address

     */

    inline void MacConfigure(TEthernetConfigV01 &aConfig);

    /**

     * Calls the PDD's ChheckConfig Method

     * @param aConfig The config to check

     */

    inline void PddCheckConfig(TEthernetConfigV01 &aConfig);

    /**

     * Calls the PDD's get capibilities method

     * @param aCaps Filled in with the PDD capibilites on return

     */

    inline void PddCaps(TDes8 &aCaps) const;

    /**

     * Sends data using the PDD

     * @param aBuffer A referance to a buffer to be sent

     * @return KErrNone if buffer sent

     */

    inline TInt PddSend(TBuf8<KMaxEthernetPacket+32> &aBuffer);

    /**

     * Receive a frame from the PDD

     * @param aBuffer A referance to the buffer that the frame is to be put in

     * @param okToUse Flag to say if the buffer is valid

     * @return KErrNone if the buffer now contains a frame

     */

    inline TInt PddReceive(TBuf8<KMaxEthernetPacket+32> &aBuffer, TBool okToUse);

    private:

    /**

     * The DFC called by the kernel

     * @param aPtr A pointer to the channel object

     */

    static void CompleteRxDfc(TAny* aPtr);

    /**

     * Start a read request

     * @param aRxDes The buffer to be filled with data

     * @param aLength The max size frame that can fit in the buffer

     */

    void InitiateRead(TAny* aRxDes, TInt aLength);

    /**

     * Start a write request

     * @param aTxDes The buffer containing the frame to be sent

     * @param aLength The length of the frame to be sent

     */

    void InitiateWrite(TAny* aTxDes, TInt aLength);

    /**

     * Validates and set a new configuration

     * @param c The configuration to try

     * @return KErrNone if new configuration set

     */

    TInt SetConfig(TEthernetConfigV01& c);

    /**

     * Validates and sets a new MAC address

     * @param c The configuration containing the MAC to be set

     * @return KErrNone if the MAC is set ok

     */

    TInt SetMAC(TEthernetConfigV01& c);

    /**

     * The current channel configuration

     */

    TEthernetConfigV01 iConfig;

    /**

     * Pointer to the client thread

     */

    DThread* iClient;

    /**

     * Current state of the LDD

     */

    TState iStatus;

    /**

     * The receive complete DFC

     */

    TDfc iRxCompleteDfc;

    /**

     * Records if the channel is being shutdown

     */

    TBool iShutdown;			// ETrue means device is being closed

    /**

     * The length of the clients buffer

     */

    TInt iRxLength;

    /**

     * The TX and RX buffers

     */

    DChannelEthernetFIFO iFIFO;

	//Read request to store user request status for WDP

	TClientBufferRequest* iReadRequest;

	//Read buffer to pin client buffer in client context for WDP

	TClientBuffer* iClientReadBuffer;

	//Write request to store user request status for WDP

	TClientRequest* iWriteRequest;

#ifdef ETH_CHIP_IO_ENABLED

	TPckgBuf<TChipIOInfo> iChipInfo;

#endif

    };

/** @} */

#include <drivers/ethernet.inl>

#endif