// 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