/*
* 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