1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/include/drivers/crashflash.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,183 @@
1.4 +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// e32/include/drivers/crashflash.h
1.18 +//
1.19 +// WARNING: This file contains some APIs which are internal and are subject
1.20 +// to change without notice. Such APIs should therefore not be used
1.21 +// outside the Kernel and Hardware Services package.
1.22 +//
1.23 +
1.24 +#ifndef __CRASH_FLASH_H__
1.25 +#define __CRASH_FLASH_H__
1.26 +
1.27 +#include <e32def.h>
1.28 +#include <e32ver.h>
1.29 +#include <e32cmn.h>
1.30 +
1.31 +///////////////////////////////////////////////////////////////////////////////
1.32 +// Crash log is stored in flash in the format:
1.33 +// Crash log size (TUint), i.e. bytes stored in crash log crash sector
1.34 +// Crash log signature (string KCrashLogSignature)
1.35 +// Uncompressed log size (TUint), if log is compressed
1.36 +// Flags (TUint8) - bits 0-3 indicate log data format, bit 4 set when log
1.37 +// had to be truncated.
1.38 +// If nand implementation, some white space is inserted to fill up
1.39 +// the whole of the signature block/sector
1.40 +// Actual log data in specified format
1.41 +//*******WARNING*******: Crash log header each field must start/end on 4 byte
1.42 +// boundary, otherwise NOR flash implementations will hang
1.43 +///////////////////////////////////////////////////////////////////////////////
1.44 +
1.45 +/** Maximum size of a crash log.
1.46 + * @internalTechnology
1.47 + */
1.48 +const TUint KMaxCrashLogSize = 0x00100000;// 1Meg of crashflash
1.49 +
1.50 +/** The size in bytes of the Crash Log Signature
1.51 + * @internalTechnology
1.52 + */
1.53 +const TUint KCrashLogSignatureBytes = 20;
1.54 +
1.55 +/** The size in bytes of the total size of the crash log (including itself and
1.56 + * the crash log signature)
1.57 + * @internalTechnology
1.58 + */
1.59 +const TUint KCrashLogSizeFieldBytes = 4;
1.60 +
1.61 +/* The crash log signature.
1.62 + * @internalTechnology
1.63 + */
1.64 +_LIT8(KCrashLogSignature, "Symbian Crash Logger");
1.65 +
1.66 +/** The size in bytes of the total size of the crash log once it has been uncompressed
1.67 + * @internalTechnology
1.68 + */
1.69 +const TUint KCrashLogUncompSizeFieldBytes = 4;
1.70 +
1.71 +/** The flags to indicate to the crash reader the data format of the log and if
1.72 + * it was truncated or not. 16 MSBs used to indicate the offset of the start of the
1.73 + * log data from the signature, required for NAND flash implementations where signarture
1.74 + * occupyies a whole flash sector/page filling unused space with white space
1.75 + * @internalTechnology
1.76 + */
1.77 +const TUint KCrashLogFlagsFieldBytes = 4;
1.78 +
1.79 +const TUint8 KCrashLogFlagUncompr = 0x0;/** No compression performed on log */
1.80 +const TUint8 KCrashLogFlagGzip = 0x1; /** Log compressed using Gzip compatible output*/
1.81 +const TUint8 KCrashLogFlagTypeBits = 4; /** No. of bits for the type*/
1.82 +
1.83 +const TUint8 KCrashLogFlagTruncated = 0x10; /** The log had to be truncated*/
1.84 +
1.85 +const TUint32 KCrashLogFlagOffShift = 16; /**place offset in 16 MSBs of flags field*/
1.86 +
1.87 +/** Total size of the crash log header in bytes. Must be less than the size of a
1.88 + * single NAND flash sector/page for current crashflashnand implementations
1.89 + * @internalTechnology
1.90 + */
1.91 +#ifndef _CRASHLOG_COMPR
1.92 +const TUint KCrashLogHeaderSize = KCrashLogSignatureBytes + KCrashLogSizeFieldBytes;
1.93 +#else
1.94 +const TUint KCrashLogHeaderSize = KCrashLogSignatureBytes + KCrashLogSizeFieldBytes +
1.95 + KCrashLogUncompSizeFieldBytes + KCrashLogFlagsFieldBytes;
1.96 +#endif //_CRASHLOG_COMPR
1.97 +
1.98 +
1.99 +/** The string to output when the log had to be truncated
1.100 + * @internalTechnology
1.101 + */
1.102 +_LIT8(KCrashLogTruncated,"\r\nLog truncated due to end of crash log partition");
1.103 +
1.104 +/** Abstract class defining interface to all CrashFlash classes. This is used
1.105 + * by the CrashLogger to log to a specific type of flash.
1.106 + *@internalTechnology
1.107 + */
1.108 +class CrashFlash
1.109 + {
1.110 +public:
1.111 + /** Called first. Should initialise underlying crash flash device to the
1.112 + * state that it can read, write, and erase.
1.113 + * @return KErrNone if successful. Else, a system wide error code.
1.114 + */
1.115 + virtual TInt Initialise()=0;
1.116 +
1.117 + /** Called second. Allows underlying implementation to set any flags
1.118 + * required to indicate that a transaction has started.
1.119 + */
1.120 + virtual void StartTransaction()=0;
1.121 +
1.122 + /** Called third. Performs the operations necessary to erase a block of
1.123 + * flash large enough to store a log of KMaxCrashLogSize.
1.124 + */
1.125 + virtual void EraseLogArea()=0;
1.126 +
1.127 + /** Called last. Commits any buffered data and sets the flag for the
1.128 + * underlying crash flash device indicating that the transaction finished
1.129 + * succesfully.
1.130 + */
1.131 + virtual void EndTransaction()=0;
1.132 +
1.133 + /** Writes aDes to the underlying crash flash device. The underlying
1.134 + * implementation may buffer as required.
1.135 + */
1.136 + virtual void Write(const TDesC8& aDes)=0;
1.137 +
1.138 + /** Writes aDes to the signature section of the underlying cras flash device.
1.139 + * The descriptor should include both the signature and the length written.
1.140 + */
1.141 + virtual void WriteSignature(const TDesC8& aDes)=0;
1.142 +
1.143 + /** Reads the next aDes.Length() characters and places them in aDes starting
1.144 + * from aDes[0]. The read position is modifiable using SetReadPos(). The
1.145 + * underlying implementation may buffer as required.
1.146 + */
1.147 + virtual void Read(TDes8& aDes)=0;
1.148 +
1.149 + /** Sets the internal state such that the next read will take place at
1.150 + * aPos bytes from the base address.
1.151 + */
1.152 + virtual void SetReadPos(TUint aPos) = 0;
1.153 +
1.154 + /** Sets the internal state of the write position
1.155 + * aPos bytes from the base address.
1.156 + */
1.157 + virtual void SetWritePos(const TUint aPos) = 0;
1.158 +
1.159 + /** Returns the number of bytes written to the flash. This is used by
1.160 + * reading programs to figure out how much to read back.
1.161 + * @return The current total number of bytes written to flash.
1.162 + */
1.163 + virtual TUint BytesWritten()=0;
1.164 +
1.165 + /**
1.166 + * Erases the data in a given flash block
1.167 + * @param aBlock The block to be erased
1.168 + */
1.169 + virtual void EraseFlashBlock(const TUint aBlock) = 0;
1.170 +
1.171 +#ifdef _CRASHLOG_COMPR
1.172 + /** Get the amount of space availiable for crash log data only.
1.173 + Not including the space required to output the signature message
1.174 + @return The number of bytes allocated to the crash log data
1.175 + */
1.176 + virtual TUint GetOutputLimit(void)=0;
1.177 +
1.178 + /** Get the offset from the end of the signature to the log data, if any.
1.179 + @return The number of bytes after the signature that the log data starts
1.180 + */
1.181 + virtual TUint GetLogOffset(void)=0;
1.182 +#endif
1.183 +
1.184 + };
1.185 +
1.186 +#endif