--- /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 <e32def.h>
+#include <e32ver.h>
+#include <e32cmn.h>
+
+///////////////////////////////////////////////////////////////////////////////
+// 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