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