1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
2 // All rights reserved.
3 // This component and the accompanying materials are made available
4 // under the terms of the License "Eclipse Public License v1.0"
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // e32/include/drivers/crashflash.h
16 // WARNING: This file contains some APIs which are internal and are subject
17 // to change without notice. Such APIs should therefore not be used
18 // outside the Kernel and Hardware Services package.
21 #ifndef __CRASH_FLASH_H__
22 #define __CRASH_FLASH_H__
28 ///////////////////////////////////////////////////////////////////////////////
29 // Crash log is stored in flash in the format:
30 // Crash log size (TUint), i.e. bytes stored in crash log crash sector
31 // Crash log signature (string KCrashLogSignature)
32 // Uncompressed log size (TUint), if log is compressed
33 // Flags (TUint8) - bits 0-3 indicate log data format, bit 4 set when log
34 // had to be truncated.
35 // If nand implementation, some white space is inserted to fill up
36 // the whole of the signature block/sector
37 // Actual log data in specified format
38 //*******WARNING*******: Crash log header each field must start/end on 4 byte
39 // boundary, otherwise NOR flash implementations will hang
40 ///////////////////////////////////////////////////////////////////////////////
42 /** Maximum size of a crash log.
45 const TUint KMaxCrashLogSize = 0x00100000;// 1Meg of crashflash
47 /** The size in bytes of the Crash Log Signature
50 const TUint KCrashLogSignatureBytes = 20;
52 /** The size in bytes of the total size of the crash log (including itself and
53 * the crash log signature)
56 const TUint KCrashLogSizeFieldBytes = 4;
58 /* The crash log signature.
61 _LIT8(KCrashLogSignature, "Symbian Crash Logger");
63 /** The size in bytes of the total size of the crash log once it has been uncompressed
66 const TUint KCrashLogUncompSizeFieldBytes = 4;
68 /** The flags to indicate to the crash reader the data format of the log and if
69 * it was truncated or not. 16 MSBs used to indicate the offset of the start of the
70 * log data from the signature, required for NAND flash implementations where signarture
71 * occupyies a whole flash sector/page filling unused space with white space
74 const TUint KCrashLogFlagsFieldBytes = 4;
76 const TUint8 KCrashLogFlagUncompr = 0x0;/** No compression performed on log */
77 const TUint8 KCrashLogFlagGzip = 0x1; /** Log compressed using Gzip compatible output*/
78 const TUint8 KCrashLogFlagTypeBits = 4; /** No. of bits for the type*/
80 const TUint8 KCrashLogFlagTruncated = 0x10; /** The log had to be truncated*/
82 const TUint32 KCrashLogFlagOffShift = 16; /**place offset in 16 MSBs of flags field*/
84 /** Total size of the crash log header in bytes. Must be less than the size of a
85 * single NAND flash sector/page for current crashflashnand implementations
88 #ifndef _CRASHLOG_COMPR
89 const TUint KCrashLogHeaderSize = KCrashLogSignatureBytes + KCrashLogSizeFieldBytes;
91 const TUint KCrashLogHeaderSize = KCrashLogSignatureBytes + KCrashLogSizeFieldBytes +
92 KCrashLogUncompSizeFieldBytes + KCrashLogFlagsFieldBytes;
93 #endif //_CRASHLOG_COMPR
96 /** The string to output when the log had to be truncated
99 _LIT8(KCrashLogTruncated,"\r\nLog truncated due to end of crash log partition");
101 /** Abstract class defining interface to all CrashFlash classes. This is used
102 * by the CrashLogger to log to a specific type of flash.
108 /** Called first. Should initialise underlying crash flash device to the
109 * state that it can read, write, and erase.
110 * @return KErrNone if successful. Else, a system wide error code.
112 virtual TInt Initialise()=0;
114 /** Called second. Allows underlying implementation to set any flags
115 * required to indicate that a transaction has started.
117 virtual void StartTransaction()=0;
119 /** Called third. Performs the operations necessary to erase a block of
120 * flash large enough to store a log of KMaxCrashLogSize.
122 virtual void EraseLogArea()=0;
124 /** Called last. Commits any buffered data and sets the flag for the
125 * underlying crash flash device indicating that the transaction finished
128 virtual void EndTransaction()=0;
130 /** Writes aDes to the underlying crash flash device. The underlying
131 * implementation may buffer as required.
133 virtual void Write(const TDesC8& aDes)=0;
135 /** Writes aDes to the signature section of the underlying cras flash device.
136 * The descriptor should include both the signature and the length written.
138 virtual void WriteSignature(const TDesC8& aDes)=0;
140 /** Reads the next aDes.Length() characters and places them in aDes starting
141 * from aDes[0]. The read position is modifiable using SetReadPos(). The
142 * underlying implementation may buffer as required.
144 virtual void Read(TDes8& aDes)=0;
146 /** Sets the internal state such that the next read will take place at
147 * aPos bytes from the base address.
149 virtual void SetReadPos(TUint aPos) = 0;
151 /** Sets the internal state of the write position
152 * aPos bytes from the base address.
154 virtual void SetWritePos(const TUint aPos) = 0;
156 /** Returns the number of bytes written to the flash. This is used by
157 * reading programs to figure out how much to read back.
158 * @return The current total number of bytes written to flash.
160 virtual TUint BytesWritten()=0;
163 * Erases the data in a given flash block
164 * @param aBlock The block to be erased
166 virtual void EraseFlashBlock(const TUint aBlock) = 0;
168 #ifdef _CRASHLOG_COMPR
169 /** Get the amount of space availiable for crash log data only.
170 Not including the space required to output the signature message
171 @return The number of bytes allocated to the crash log data
173 virtual TUint GetOutputLimit(void)=0;
175 /** Get the offset from the end of the signature to the log data, if any.
176 @return The number of bytes after the signature that the log data starts
178 virtual TUint GetLogOffset(void)=0;