diff -r 000000000000 -r a41df078684a kernel/eka/include/drivers/flash_media.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kernel/eka/include/drivers/flash_media.h Mon Oct 19 15:55:17 2009 +0100 @@ -0,0 +1,295 @@ +// Copyright (c) 1996-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: +// e32\include\drivers\flash_media.h +// +// + +/** + @file + @internalComponent +*/ + +#ifndef __FLASH_MEDIA_H__ +#define __FLASH_MEDIA_H__ +#include +#include + +GLREF_C TDfcQue FlashDfcQ; + + + + +/** +@publishedPartner +@released + +Base class for the LFFS media driver. + +The class provides an implementation for the generic layer of +the LFFS media driver. +Code that is specifc to a flash device is implemented as a class +derived from this. +*/ +class DMediaDriverFlash : public DMediaDriver + { +public: + /** + Defines a set of values that are passed to Complete() + informing the generic layer about the type of request + that is being completed. + */ + enum TRequest { + /** + Indicates that a read request is being completed. + */ + EReqRead=0, + + /** + Indicates that a write request is being completed. + */ + EReqWrite=1, + + /** + Indicates that an erase request is being completed. + */ + EReqErase=2}; +public: + /** + Creates an instance of the LFFS media driver. + + Although declared in this class, this function is not implemented by + Symbian OS, but must be implemented by the port. + + It should return an instance of the class derived from DMediaDriverFlash. + The following is an example taken from the Lubbock reference platform: + @code + DMediaDriverFlash* DMediaDriverFlash::New(TInt aMediaId) + { + return new DMediaDriverFlashLA(aMediaId); + } + @endcode + + @param aMediaId The unique media ID specifed when the media driver was registered. + This value is just propagated through. + + @return An instance of a class derived from DMediaDriverFlash + */ + static DMediaDriverFlash* New(TInt aMediaId); + + DMediaDriverFlash(TInt aMediaId); +public: + // replacing pure virtual + + virtual TInt Request(TLocDrvRequest& aRequest); + + virtual TInt PartitionInfo(TPartitionInfo& anInfo); + + virtual void NotifyPowerDown(); + + virtual void NotifyEmergencyPowerDown(); + +public: + // pure virtual - FLASH device specific stuff + + /** + Called by the generic layer of the LFFS media driver, and implemented by + the specific layer to perform any initialisation required by + the specific layer. + + @return KErrNone, if successful; otherwise one of the other system + wide error codes. + */ + virtual TInt Initialise()=0; + + + + /** + Called by the generic layer of the LFFS media driver, and implemented by + the specific layer to get the size of the flash erase block. + + @return The size of the flash erase block, in bytes. + */ + virtual TUint32 EraseBlockSize()=0; + + + + /** + Called by the generic layer of the LFFS media driver, and implemented by + the specific layer to get the total size of the flash. + + @return The total size of the flash, in bytes. + */ + virtual TUint32 TotalSize()=0; + + + + /** + Called by the generic layer of the LFFS media driver, and implemented by + the specific layer to start a read request. + + The information for the request is in iReadReq. + + If the read operation cannot be started immediately, then this function + should return KMediaDriverDeferRequest; this asks the generic layer + to defer the request and re-start it later. A read request might be + deferred, for example, if there is a write or an erase operation + already in progress. + + Note that this an asynchronous request, i.e. it starts the operation; + the driver must call: + @code + Complete(EReqRead, result); + @endcode + when the operation is complete, where result is KErrNone if sucessful, or + one of the system-wide error codes, otherwise. + + @return KErrNone, if the request has been sucessfully initiated; + KErrNotSupported, if the request cannot be handled by the device; + KMediaDriverDeferRequest, if the request cannot be handled + immediately because of an outstanding request + + @see iReadReq + @see DMediaDriverFlash::Complete() + */ + virtual TInt DoRead()=0; + + + + /** + Called by the generic layer of the LFFS media driver, and implemented by + the specific layer to start a write request. + + The information for the request is in iWriteReq. + + If the write operation cannot be started immediately, then this function + should return KMediaDriverDeferRequest; this asks the generic layer + to defer the request and re-start it later. A write request might be + deferred, for example, if there is a read or an erase operation + already in progress. + + Note that this an asynchronous request, i.e. it starts the operation; + the driver must call: + @code + Complete(EReqWrite, result); + @endcode + when the operation is complete, where result is KErrNone if sucessful, or + one of the system-wide error codes, otherwise. + + @return KErrNone, if the request has been sucessfully initiated; + KErrNotSupported, if the request cannot be handled by the device; + KMediaDriverDeferRequest, if the request cannot be handled + immediately because of an outstanding request + + @see iWriteReq + @see DMediaDriverFlash::Complete() + */ + virtual TInt DoWrite()=0; + + + + /** + Called by the generic layer of the LFFS media driver, and implemented by + the specific layer to start a block erase request. + + The information for the request is in iEraseReq. + + If the erase operation cannot be started immediately, then this function + should return KMediaDriverDeferRequest; this asks the generic layer + to defer the request and re-start it later. An erase request might be + deferred, for example, if there is a read or a write operation + already in progress. + + Note that this an asynchronous request, i.e. it starts the operation; + the driver must call: + @code + Complete(EReqErase, result); + @endcode + when the operation is complete, where result is KErrNone if sucessful, or + one of the system-wide error codes, otherwise. + + @return KErrNone, if the request has been sucessfully initiated; + KErrNotSupported, if the request cannot be handled by the device; + KMediaDriverDeferRequest, if the request cannot be handled + immediately because of an outstanding request + + @see iEraseReq + @see DMediaDriverFlash::Complete() + */ + virtual TInt DoErase()=0; +public: + TInt DoCreate(TInt aMediaId); + + virtual TInt Caps(TLocalDriveCapsV2& aCaps); + + void Complete(TInt aRequest, TInt aResult); +public: + + + /** + Location for request information. + + An array of three entries to contain request information for read, + write and erase requests respectively. + + NB Do not access this array directly; instead use the macro definitions: + iReadReq, iWriteReq and iEraseReq. These ensure that you access the correct + TLocDrvRequest items within the array. + + @see iReadReq + @see iWriteReq + @see iEraseReq + @see TLocDrvRequest + */ + TLocDrvRequest* iRequests[3]; + }; + + + + +/** +Read request information for LFFS media drivers. + +@see TLocDrvRequest +@see DMediaDriverFlash +@see DMediaDriverFlash::iRequests +*/ +#define iReadReq iRequests[EReqRead] + + + + +/** +Write request information for LFFS media drivers. + +@see TLocDrvRequest +@see DMediaDriverFlash +@see DMediaDriverFlash::iRequests +*/ +#define iWriteReq iRequests[EReqWrite] + + + + +/** +Erase request information for LFFS media drivers. + +@see TLocDrvRequest +@see DMediaDriverFlash +@see DMediaDriverFlash::iRequests +*/ +#define iEraseReq iRequests[EReqErase] + + + +#endif