/*

 * 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