diff -r 000000000000 -r a41df078684a kernel/eka/include/drivers/crashflash.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kernel/eka/include/drivers/crashflash.h Mon Oct 19 15:55:17 2009 +0100 @@ -0,0 +1,183 @@ +// Copyright (c) 2006-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/crashflash.h +// +// WARNING: This file contains some APIs which are internal and are subject +// to change without notice. Such APIs should therefore not be used +// outside the Kernel and Hardware Services package. +// + +#ifndef __CRASH_FLASH_H__ +#define __CRASH_FLASH_H__ + +#include +#include +#include + +/////////////////////////////////////////////////////////////////////////////// +// Crash log is stored in flash in the format: +// Crash log size (TUint), i.e. bytes stored in crash log crash sector +// Crash log signature (string KCrashLogSignature) +// Uncompressed log size (TUint), if log is compressed +// Flags (TUint8) - bits 0-3 indicate log data format, bit 4 set when log +// had to be truncated. +// If nand implementation, some white space is inserted to fill up +// the whole of the signature block/sector +// Actual log data in specified format +//*******WARNING*******: Crash log header each field must start/end on 4 byte +// boundary, otherwise NOR flash implementations will hang +/////////////////////////////////////////////////////////////////////////////// + +/** Maximum size of a crash log. + * @internalTechnology + */ +const TUint KMaxCrashLogSize = 0x00100000;// 1Meg of crashflash + +/** The size in bytes of the Crash Log Signature + * @internalTechnology + */ +const TUint KCrashLogSignatureBytes = 20; + +/** The size in bytes of the total size of the crash log (including itself and + * the crash log signature) + * @internalTechnology + */ +const TUint KCrashLogSizeFieldBytes = 4; + +/* The crash log signature. + * @internalTechnology + */ +_LIT8(KCrashLogSignature, "Symbian Crash Logger"); + +/** The size in bytes of the total size of the crash log once it has been uncompressed + * @internalTechnology + */ +const TUint KCrashLogUncompSizeFieldBytes = 4; + +/** The flags to indicate to the crash reader the data format of the log and if + * it was truncated or not. 16 MSBs used to indicate the offset of the start of the + * log data from the signature, required for NAND flash implementations where signarture + * occupyies a whole flash sector/page filling unused space with white space + * @internalTechnology + */ +const TUint KCrashLogFlagsFieldBytes = 4; + +const TUint8 KCrashLogFlagUncompr = 0x0;/** No compression performed on log */ +const TUint8 KCrashLogFlagGzip = 0x1; /** Log compressed using Gzip compatible output*/ +const TUint8 KCrashLogFlagTypeBits = 4; /** No. of bits for the type*/ + +const TUint8 KCrashLogFlagTruncated = 0x10; /** The log had to be truncated*/ + +const TUint32 KCrashLogFlagOffShift = 16; /**place offset in 16 MSBs of flags field*/ + +/** Total size of the crash log header in bytes. Must be less than the size of a + * single NAND flash sector/page for current crashflashnand implementations + * @internalTechnology + */ +#ifndef _CRASHLOG_COMPR +const TUint KCrashLogHeaderSize = KCrashLogSignatureBytes + KCrashLogSizeFieldBytes; +#else +const TUint KCrashLogHeaderSize = KCrashLogSignatureBytes + KCrashLogSizeFieldBytes + + KCrashLogUncompSizeFieldBytes + KCrashLogFlagsFieldBytes; +#endif //_CRASHLOG_COMPR + + +/** The string to output when the log had to be truncated + * @internalTechnology + */ +_LIT8(KCrashLogTruncated,"\r\nLog truncated due to end of crash log partition"); + +/** Abstract class defining interface to all CrashFlash classes. This is used + * by the CrashLogger to log to a specific type of flash. + *@internalTechnology + */ +class CrashFlash + { +public: + /** Called first. Should initialise underlying crash flash device to the + * state that it can read, write, and erase. + * @return KErrNone if successful. Else, a system wide error code. + */ + virtual TInt Initialise()=0; + + /** Called second. Allows underlying implementation to set any flags + * required to indicate that a transaction has started. + */ + virtual void StartTransaction()=0; + + /** Called third. Performs the operations necessary to erase a block of + * flash large enough to store a log of KMaxCrashLogSize. + */ + virtual void EraseLogArea()=0; + + /** Called last. Commits any buffered data and sets the flag for the + * underlying crash flash device indicating that the transaction finished + * succesfully. + */ + virtual void EndTransaction()=0; + + /** Writes aDes to the underlying crash flash device. The underlying + * implementation may buffer as required. + */ + virtual void Write(const TDesC8& aDes)=0; + + /** Writes aDes to the signature section of the underlying cras flash device. + * The descriptor should include both the signature and the length written. + */ + virtual void WriteSignature(const TDesC8& aDes)=0; + + /** Reads the next aDes.Length() characters and places them in aDes starting + * from aDes[0]. The read position is modifiable using SetReadPos(). The + * underlying implementation may buffer as required. + */ + virtual void Read(TDes8& aDes)=0; + + /** Sets the internal state such that the next read will take place at + * aPos bytes from the base address. + */ + virtual void SetReadPos(TUint aPos) = 0; + + /** Sets the internal state of the write position + * aPos bytes from the base address. + */ + virtual void SetWritePos(const TUint aPos) = 0; + + /** Returns the number of bytes written to the flash. This is used by + * reading programs to figure out how much to read back. + * @return The current total number of bytes written to flash. + */ + virtual TUint BytesWritten()=0; + + /** + * Erases the data in a given flash block + * @param aBlock The block to be erased + */ + virtual void EraseFlashBlock(const TUint aBlock) = 0; + +#ifdef _CRASHLOG_COMPR + /** Get the amount of space availiable for crash log data only. + Not including the space required to output the signature message + @return The number of bytes allocated to the crash log data + */ + virtual TUint GetOutputLimit(void)=0; + + /** Get the offset from the end of the signature to the log data, if any. + @return The number of bytes after the signature that the log data starts + */ + virtual TUint GetLogOffset(void)=0; +#endif + + }; + +#endif