1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/include/drivers/ethernet.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,568 @@
1.4 +/*
1.5 +* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of the License "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +// Ethernet.h
1.21 +//
1.22 +//
1.23 +/** @file ethernet.h
1.24 +Base classes for implementating ethernet support (Kernel-side only)
1.25 +@internalComponent
1.26 +*/
1.27 +
1.28 +#ifndef __ETHERNET_H__
1.29 +#define __ETHERNET_H__
1.30 +#include <platform.h>
1.31 +#include <d32ethernet.h>
1.32 +#include <e32ver.h>
1.33 +
1.34 +/** @addtogroup enet Ethernet Drivers
1.35 + * Kernel Ethernet Support
1.36 + */
1.37 +
1.38 +/** @addtogroup enet_ldd Driver LDD's
1.39 + * @ingroup enet
1.40 + */
1.41 +
1.42 +const TInt KEthernetMajorVersionNumber = 1;
1.43 +const TInt KEthernetMinorVersionNumber = 0;
1.44 +const TInt KEthernetBuildVersionNumber = KE32BuildVersionNumber;
1.45 +
1.46 +/**
1.47 + @publishedPartner
1.48 + @released
1.49 +*/
1.50 +const TInt KTxWorkBudgetLimit = 10;
1.51 +
1.52 +// Card Rx constants.
1.53 +const TInt KNumRXBuffers = 40;
1.54 +/**
1.55 + @publishedPartner
1.56 + @released
1.57 +*/
1.58 +const TInt KIRQWorkBudgetLimit = 4;
1.59 +/**
1.60 + @publishedPartner
1.61 + @released
1.62 +*/
1.63 +const TInt KRxWorkBudgetLimit = 6;
1.64 +
1.65 +/**
1.66 + @publishedPartner
1.67 + @released
1.68 +*/
1.69 +const TInt KMaxEthernetPacket = 1518;
1.70 +/**
1.71 + @publishedPartner
1.72 + @released
1.73 +*/
1.74 +const TUint16 CRC_LEN = 4;
1.75 +
1.76 +/** @addtogroup enet_pdd Driver PDD's
1.77 + * @ingroup enet
1.78 + * @{
1.79 + */
1.80 +
1.81 +/**
1.82 + Different Stop Modes
1.83 + @publishedPartner
1.84 + @released
1.85 + */
1.86 +enum TStopMode
1.87 + {
1.88 + EStopNormal, /**< Finish sending and then stop */
1.89 + EStopEmergency /**< Just stop now */
1.90 + };
1.91 +
1.92 +
1.93 +class DChannelEthernet;
1.94 +
1.95 +
1.96 +/**
1.97 + Ethernet driver base class
1.98 + The base class for an ethernet driver that doesn't support power control
1.99 + @publishedPartner
1.100 + @released
1.101 +*/
1.102 +class DEthernet : public DBase
1.103 + {
1.104 + public:
1.105 + /**
1.106 + * Start receiving frames
1.107 + * @return KErrNone if driver started
1.108 + */
1.109 + virtual TInt Start() =0;
1.110 + /**
1.111 + * Stop receiving frames
1.112 + * @param aMode The stop mode
1.113 + */
1.114 + virtual void Stop(TStopMode aMode) =0;
1.115 +
1.116 + /**
1.117 + * Validate a new config
1.118 + * Validates a new configuration should be called before Configure
1.119 + * @param aConfig is the configuration to be validated
1.120 + * @return ETrue or EFalse if the Configuration is allowed
1.121 + * @see Configure()
1.122 + */
1.123 + virtual TInt ValidateConfig(const TEthernetConfigV01 &aConfig) const =0;
1.124 + /**
1.125 + * Configure the device
1.126 + * Reconfigure the device using the new configuration supplied.
1.127 + * This should not change the MAC address.
1.128 + * @param aConfig The new configuration
1.129 + * @see ValidateConfig()
1.130 + * @see MacConfigure()
1.131 + */
1.132 + virtual TInt Configure(TEthernetConfigV01 &aConfig) =0;
1.133 + /**
1.134 + * Change the MAC address
1.135 + * Attempt to change the MAC address of the device
1.136 + * @param aConfig A Configuration containing the new MAC
1.137 + * @see Configure()
1.138 + */
1.139 + virtual void MacConfigure(TEthernetConfigV01 &aConfig) =0;
1.140 + /**
1.141 + * Get the current config from the chip
1.142 + * This returns the current configuration of the chip with the folling fields
1.143 + * The Transmit Speed
1.144 + * The Duplex Setting
1.145 + * The MAC address
1.146 + * @param aConfig is a TEthernetConfigV01 referance that will be filled in
1.147 + */
1.148 + virtual void GetConfig(TEthernetConfigV01 &aConfig) const =0;
1.149 + /**
1.150 + * Check a configuration
1.151 + * @param aConfig a reference to the structure TEthernetConfigV01 with configuration to check
1.152 + */
1.153 + virtual void CheckConfig(TEthernetConfigV01& aConfig)=0;
1.154 +
1.155 + /**
1.156 + * Querie the device's capibilitys
1.157 + * @param aCaps To be filled in with the capibilites
1.158 + */
1.159 + virtual void Caps(TDes8 &aCaps) const =0;
1.160 +
1.161 + /**
1.162 + * Transmit data
1.163 + * @param aBuffer referance to the data to be sent
1.164 + * @return KErrNone if the data has been sent
1.165 + */
1.166 + virtual TInt Send(TBuf8<KMaxEthernetPacket+32> &aBuffer) =0;
1.167 + /**
1.168 + * Retrieve data from the device
1.169 + * Pull the received data out of the device and into the supplied buffer.
1.170 + * Need to be told if the buffer is OK to use as if it not we could dump
1.171 + * the waiting frame in order to clear the interrupt if necessory.
1.172 + * @param aBuffer Referance to the buffer to be used to store the data in
1.173 + * @param okToUse Bool to indicate if the buffer is usable
1.174 + * @return KErrNone if the buffer has been filled.
1.175 + */
1.176 + virtual TInt ReceiveFrame(TBuf8<KMaxEthernetPacket+32> &aBuffer,
1.177 + TBool okToUse) =0;
1.178 +
1.179 + /**
1.180 + * Disables all IRQ's
1.181 + * @return The IRQ level before it was changed
1.182 + * @see RestoreIrqs()
1.183 + */
1.184 + virtual TInt DisableIrqs()=0;
1.185 + /**
1.186 + * Restore the IRQ's to the supplied level
1.187 + * @param aIrq The level to set the irqs to.
1.188 + * @see DisableIrqs()
1.189 + */
1.190 + virtual void RestoreIrqs(TInt aIrq)=0;
1.191 + /**
1.192 + * Return the DFC Queue that this device should use
1.193 + * @param aUnit The Channel number
1.194 + * @return Then DFC Queue to use
1.195 + */
1.196 + virtual TDfcQue* DfcQ(TInt aUnit)=0;
1.197 + /**
1.198 + * The Receive Isr for the device
1.199 + */
1.200 + inline void ReceiveIsr();
1.201 +
1.202 +#ifdef ETH_CHIP_IO_ENABLED
1.203 + virtual TInt BgeChipIOCtrl(TPckgBuf<TChipIOInfo> &aIOData)=0;
1.204 +#endif
1.205 + /**
1.206 + * A pointer to the logical device drivers channel that owns this device
1.207 + */
1.208 + DChannelEthernet * iLdd ;
1.209 + };
1.210 +
1.211 +/** @} */ // End of pdd group
1.212 +
1.213 +/**
1.214 + * @addtogroup enet_ldd_nopm_nopccard Ethernet LDD Not PCMCIA and No Power Managment
1.215 + * @ingroup enet_ldd
1.216 + * @ingroup enet_misa
1.217 + * @ingroup enet_wins
1.218 + * @{
1.219 + */
1.220 +
1.221 +/**
1.222 + Ethernet logical device
1.223 + The class representing the ethernet logical device
1.224 + @internalComponent
1.225 +*/
1.226 +class DDeviceEthernet : public DLogicalDevice
1.227 + {
1.228 + public:
1.229 + /**
1.230 + * The constructor
1.231 + */
1.232 + DDeviceEthernet();
1.233 + /**
1.234 + * Install the device
1.235 + */
1.236 + virtual TInt Install();
1.237 + /**
1.238 + * Get the Capabilites of the device
1.239 + * @param aDes descriptor that will contain the returned capibilites
1.240 + */
1.241 + virtual void GetCaps(TDes8 &aDes) const;
1.242 + /**
1.243 + * Create a logical channel to the device
1.244 + */
1.245 + virtual TInt Create(DLogicalChannelBase*& aChannel);
1.246 + };
1.247 +
1.248 +
1.249 +/**
1.250 + Stores the Tx and RX buffers for use in a ethernet logical channel
1.251 + @internalComponent
1.252 + */
1.253 +class DChannelEthernetFIFO
1.254 + {
1.255 + public:
1.256 + /**
1.257 + * The TX Buffer
1.258 + */
1.259 + TBuf8<KMaxEthernetPacket+32> iTxBuf;
1.260 +
1.261 + /**
1.262 + * The constructor
1.263 + */
1.264 + DChannelEthernetFIFO();
1.265 + /**
1.266 + * The destructor
1.267 + */
1.268 + ~DChannelEthernetFIFO();
1.269 + /**
1.270 + * Get a empty receive buffer
1.271 + * @return NULL or a pointer to the free buffer
1.272 + */
1.273 + TBuf8<KMaxEthernetPacket+32> * GetFree();
1.274 + /**
1.275 + * Get the next full buffer
1.276 + * @return NULL or a pointer to the full buffer
1.277 + */
1.278 + TBuf8<KMaxEthernetPacket+32> * GetNext();
1.279 + /**
1.280 + * Move on to the next full buffer
1.281 + */
1.282 + void SetNext();
1.283 +
1.284 + private:
1.285 + /**
1.286 + * The array of receive buffers
1.287 + */
1.288 + TBuf8<KMaxEthernetPacket+32> iRxBuf[KNumRXBuffers];
1.289 + /**
1.290 + * Index into the array of the next full buffer
1.291 + */
1.292 + TInt iRxQueIterNext;
1.293 + /**
1.294 + * Index into the array of the next empty buffer
1.295 + */
1.296 + TInt iRxQueIterFree;
1.297 + /**
1.298 + * Count of the number of empty buffers
1.299 + */
1.300 + TInt iNumFree;
1.301 + };
1.302 +
1.303 +/**
1.304 + The logical channel for ethernet devices
1.305 + The basic ethernet logical channel that doesn't support
1.306 + power control or PCCard ethernet devices
1.307 + @internalComponent
1.308 + */
1.309 +class DChannelEthernet : public DLogicalChannel
1.310 + {
1.311 + public:
1.312 + /**
1.313 + * The state of the logical channel
1.314 + */
1.315 + enum TState
1.316 + {
1.317 + EOpen, /**< The channel is open */
1.318 + EActive, /**< The channel is open and busy */
1.319 + EClosed /**< The channel is closed */
1.320 + };
1.321 +
1.322 + /**
1.323 + * Requests that can be made on the channel
1.324 + */
1.325 + enum TRequest
1.326 + {
1.327 + ERx=1, /**< Receive a frame */
1.328 + ETx=2, /**< Transmit a frame */
1.329 + EAll=0xff /**< Complete/cancel all outstanding requests */
1.330 + };
1.331 +
1.332 + /**
1.333 + * The constructor
1.334 + */
1.335 + DChannelEthernet();
1.336 + /**
1.337 + * The destructor
1.338 + */
1.339 + ~DChannelEthernet();
1.340 +
1.341 + /**
1.342 + * The ISR function for the channel
1.343 + * This is called by the pycical channels ISR when data is received
1.344 + * It passes a empty buffer to the PDD for it to store the frame in
1.345 + */
1.346 + virtual void ReceiveIsr();
1.347 +
1.348 + protected:
1.349 + /**
1.350 + * Create a logical ethernet channel
1.351 + * @param aUnit The channel number to create
1.352 + * @param anInfo not used, can be NULL
1.353 + * @param aVer The minimun driver version allowed
1.354 + * @return KErrNone if channel created
1.355 + */
1.356 + virtual TInt DoCreate(TInt aUnit, const TDesC8* anInfo, const TVersion& aVer);
1.357 + /**
1.358 + * Handle a message from the channels user
1.359 + * @param aMsg The message to handle
1.360 + */
1.361 + virtual void HandleMsg(TMessageBase* aMsg);
1.362 + /**
1.363 + * Cancel an outstanding request
1.364 + * @param aMask A mask containing the requests to be canceled
1.365 + */
1.366 + void DoCancel(TInt aMask);
1.367 + /**
1.368 + * Preform a control operation on the channel
1.369 + * Control operations are:
1.370 + * - Get the current configuration
1.371 + * - Configure the channel
1.372 + * - Set the MAC address for the channel
1.373 + * - Get the capibilities of the channel
1.374 + * @param aId The operation to preform
1.375 + * @param a1 The data to use with the operation
1.376 + * @param a2 can be NULL - not used
1.377 + * @return KErrNone if operation done
1.378 + */
1.379 + TInt DoControl(TInt aId, TAny* a1, TAny* a2);
1.380 + /**
1.381 + * Preform an asynchros operation on the channel
1.382 + * Operations are:
1.383 + * - Read data from the channel
1.384 + * - Write data to the channel
1.385 + * @param aId The operation to perform
1.386 + * @param aStatus The status object to use when complete
1.387 + * @param a1 The data to use
1.388 + * @param a2 The length of the data to use
1.389 + * @return KErrNone if operation started ok
1.390 + * @see Complete()
1.391 + */
1.392 + TInt DoRequest(TInt aId, TRequestStatus* aStatus, TAny* a1, TAny* a2);
1.393 +
1.394 + //Override sendMsg to copy clients memory in client context for WDP.
1.395 + virtual TInt SendMsg(TMessageBase* aMsg);
1.396 +
1.397 + TInt SendControl(TMessageBase* aMsg);
1.398 +
1.399 + TInt SendRequest(TMessageBase* aMsg);
1.400 +
1.401 + /**
1.402 + * Start the channel receiving
1.403 + */
1.404 + void Start();
1.405 + /**
1.406 + * Shutdown the channel
1.407 + */
1.408 + void Shutdown();
1.409 +
1.410 + /**
1.411 + * Complete an RX request
1.412 + * Is run as the RX DFC and reads a buffer from the receive FIFO into
1.413 + * the users buffer
1.414 + */
1.415 + void DoCompleteRx();
1.416 + /**
1.417 + * Completes an outstanding request
1.418 + * @param aMask Specifies what request to complete
1.419 + * @param aReason The reason the request is complete
1.420 + * @see DoRequest()
1.421 + */
1.422 + void Complete(TInt aMask, TInt aReason);
1.423 +
1.424 + /**
1.425 + * Disables all IRQ's
1.426 + * @return The IRQ level before it was changed
1.427 + * @see RestoreIrqs()
1.428 + */
1.429 + inline TInt DisableIrqs();
1.430 + /**
1.431 + * Restore the IRQ's to the supplied level
1.432 + * @param aIrq The level to set the irqs to.
1.433 + * @see DisableIrqs()
1.434 + */
1.435 + inline void RestoreIrqs(TInt aIrq);
1.436 +
1.437 + /**
1.438 + * Calls the PDD's start method
1.439 + * @return KErrNone if the PDD started ok
1.440 + */
1.441 + inline TInt PddStart();
1.442 + /**
1.443 + * Calls the PDD's Validate method
1.444 + * @param aConfig The configuration to be validated
1.445 + * @return KErrNone if config is valid
1.446 + */
1.447 + inline TInt ValidateConfig(const TEthernetConfigV01 &aConfig) const;
1.448 + /**
1.449 + * Calls the PDD's Configure method
1.450 + * Should call Validate first
1.451 + * Will not change the MAC address
1.452 + * @param aConfig The new configuration
1.453 + * @see ValidateConfig()
1.454 + */
1.455 + inline void PddConfigure(TEthernetConfigV01 &aConfig);
1.456 + /**
1.457 + * Calls the PDD's MacConfigure method
1.458 + * Will not change anything but the MAC address
1.459 + * @param aConfig A configuration containing the new MAC address
1.460 + */
1.461 + inline void MacConfigure(TEthernetConfigV01 &aConfig);
1.462 + /**
1.463 + * Calls the PDD's ChheckConfig Method
1.464 + * @param aConfig The config to check
1.465 + */
1.466 + inline void PddCheckConfig(TEthernetConfigV01 &aConfig);
1.467 +
1.468 + /**
1.469 + * Calls the PDD's get capibilities method
1.470 + * @param aCaps Filled in with the PDD capibilites on return
1.471 + */
1.472 + inline void PddCaps(TDes8 &aCaps) const;
1.473 +
1.474 + /**
1.475 + * Sends data using the PDD
1.476 + * @param aBuffer A referance to a buffer to be sent
1.477 + * @return KErrNone if buffer sent
1.478 + */
1.479 + inline TInt PddSend(TBuf8<KMaxEthernetPacket+32> &aBuffer);
1.480 + /**
1.481 + * Receive a frame from the PDD
1.482 + * @param aBuffer A referance to the buffer that the frame is to be put in
1.483 + * @param okToUse Flag to say if the buffer is valid
1.484 + * @return KErrNone if the buffer now contains a frame
1.485 + */
1.486 + inline TInt PddReceive(TBuf8<KMaxEthernetPacket+32> &aBuffer, TBool okToUse);
1.487 +
1.488 + private:
1.489 + /**
1.490 + * The DFC called by the kernel
1.491 + * @param aPtr A pointer to the channel object
1.492 + */
1.493 + static void CompleteRxDfc(TAny* aPtr);
1.494 +
1.495 + /**
1.496 + * Start a read request
1.497 + * @param aRxDes The buffer to be filled with data
1.498 + * @param aLength The max size frame that can fit in the buffer
1.499 + */
1.500 + void InitiateRead(TAny* aRxDes, TInt aLength);
1.501 + /**
1.502 + * Start a write request
1.503 + * @param aTxDes The buffer containing the frame to be sent
1.504 + * @param aLength The length of the frame to be sent
1.505 + */
1.506 + void InitiateWrite(TAny* aTxDes, TInt aLength);
1.507 + /**
1.508 + * Validates and set a new configuration
1.509 + * @param c The configuration to try
1.510 + * @return KErrNone if new configuration set
1.511 + */
1.512 + TInt SetConfig(TEthernetConfigV01& c);
1.513 + /**
1.514 + * Validates and sets a new MAC address
1.515 + * @param c The configuration containing the MAC to be set
1.516 + * @return KErrNone if the MAC is set ok
1.517 + */
1.518 + TInt SetMAC(TEthernetConfigV01& c);
1.519 +
1.520 + /**
1.521 + * The current channel configuration
1.522 + */
1.523 + TEthernetConfigV01 iConfig;
1.524 +
1.525 + /**
1.526 + * Pointer to the client thread
1.527 + */
1.528 + DThread* iClient;
1.529 +
1.530 + /**
1.531 + * Current state of the LDD
1.532 + */
1.533 + TState iStatus;
1.534 +
1.535 + /**
1.536 + * The receive complete DFC
1.537 + */
1.538 + TDfc iRxCompleteDfc;
1.539 +
1.540 + /**
1.541 + * Records if the channel is being shutdown
1.542 + */
1.543 + TBool iShutdown; // ETrue means device is being closed
1.544 +
1.545 + /**
1.546 + * The length of the clients buffer
1.547 + */
1.548 + TInt iRxLength;
1.549 +
1.550 + /**
1.551 + * The TX and RX buffers
1.552 + */
1.553 + DChannelEthernetFIFO iFIFO;
1.554 +
1.555 + //Read request to store user request status for WDP
1.556 + TClientBufferRequest* iReadRequest;
1.557 + //Read buffer to pin client buffer in client context for WDP
1.558 + TClientBuffer* iClientReadBuffer;
1.559 +
1.560 + //Write request to store user request status for WDP
1.561 + TClientRequest* iWriteRequest;
1.562 +
1.563 +#ifdef ETH_CHIP_IO_ENABLED
1.564 + TPckgBuf<TChipIOInfo> iChipInfo;
1.565 +#endif
1.566 + };
1.567 +/** @} */
1.568 +
1.569 +#include <drivers/ethernet.inl>
1.570 +
1.571 +#endif