flformat.h

M-System DOC(Disk on a Chip) Flash芯片的诊断工具, 可以从Flash芯片中获取特定的数据信息, 用于判断芯片当前的状态.

/***********************************************************************************/
/*                        M-Systems Confidential                                   */
/*           Copyright (C) M-Systems Flash Disk Pioneers Ltd. 1995-2003            */
/*                         All Rights Reserved                                     */
/***********************************************************************************/
/*                            NOTICE OF M-SYSTEMS OEM                              */
/*                           SOFTWARE LICENSE AGREEMENT                            */
/*                                                                                 */
/*      THE USE OF THIS SOFTWARE IS GOVERNED BY A SEPARATE LICENSE                 */
/*      AGREEMENT BETWEEN THE OEM AND M-SYSTEMS. REFER TO THAT AGREEMENT           */
/*      FOR THE SPECIFIC TERMS AND CONDITIONS OF USE,                              */
/*      OR CONTACT M-SYSTEMS FOR LICENSE ASSISTANCE:                               */
/*      E-MAIL = [e-mail]                                                    */
/***********************************************************************************/

/*
 * $Log:   V:/PVCSDB/DiskOnChip/archives/general storage/TrueFFS/src/include/flformat.h-arc  $
 * 
 *    Rev 1.8   Jan 27 2004 08:14:02   oris
 * Changed comments
 * 
 *    Rev 1.7   Oct 26 2003 19:06:24   oris
 * Added TL_DO_NOT_PERFORM_DOWNLOAD formatting flag
 * 
 *    Rev 1.6   Sep 30 2003 17:58:22   oris
 * Added TL_SINGLE_FLOOR definition for the format routine
 * 
 *    Rev 1.5   Sep 01 2003 19:07:46   oris
 * - Changed explanation of the various fields.
 * 
 *    Rev 1.4   Jun 01 2003 17:05:04   oris
 * Added paranthesis for TL_SPL_FORMAT and TL_FAST_PARTITION definition to simplefy the code.
 *  
 * 
 * 
 *    Rev 1.3   May 11 2003 08:26:32   OriS
 * Moved irFlags bits definition from blockdev.h.
 * Changed signOffset field to a more appropriate name (flags).
 * 
 *    Rev 1.2   May 08 2003 23:16:18   OriS
 * Changed TL_SIMPLE_MATCHING and TL_RUGGESIZED flags.
 * 
 *    Rev 1.1   May 06 2003 11:54:50   OriS
 * Changed Sdword variable type to FLSDword
 * 
 *    Rev 1.0   Apr 09 2003 12:16:00   OriS
 * Initial revision.
 * 
 */

/*****************************************************************************
* File Header                                                                *
* -----------                                                                *
* Name : flformat.h                                                          *
*                                                                            *
* Description : This file contains data strucutres passed to the format      *
*               routines.                                                    *
*                                                                            *
* Note : If dos format is also needed include dosformt.h instead             *
*                                                                            *
*****************************************************************************/

#ifndef FORMAT_H
#define FORMAT_H

#include "flbase.h"

/* IOreq->irFlags values for flFormatVolume routine:
 *
 * FAT_ONLY_FORMAT / TL_FORMAT / TL_FORMAT_IF_NEEDED / TL_FORMAT_ONLY 
 */

#define FAT_ONLY_FORMAT           0
#define TL_FORMAT                 1
#define TL_FORMAT_IF_NEEDED       2
#define TL_FORMAT_ONLY            8

/* IOreq->irFlags values for flFormatPhysicalDrive routine:
 *
 * TL_NORMAL_FORMAT / TL_LEAVE_BINARY_AREA / TL_LEAVE_SOME_BINARY_AREA 
 */

#define TL_LEAVE_BINARY_AREA       8  /* Is assumed to be a single bit */
#define TL_LEAVE_SOME_BINARY_AREA  9  /* Must include TL_LEAVE_BINARY_AREA bits */
#define TL_SINGLE_FLOOR            16 /* Format only a selection of the floors  */
#define TL_DO_NOT_PERFORM_DOWNLOAD 32 /* Do not issue a download operation at   */
                                      /* end of the format routine.             */

/* Internal Partition flags - N O T   F O R   U S E */

#define TL_SIMPLE_MATCHING     16 /* Internal flag - Use simple matching for partition */
#define TL_FORCE_REL           32  /* Internal flag - Use RELIABLE mode                */
#define TL_FAST_MODE           64  /* Use FAST mode                                    */
#define TL_NO_PLANES           128 /* Internal flag - Do not match blocks for planes   */

/* External Partition Flags - Not currently supported */
#define TL_FORMAT_COMPRESSION  1        /* Add ZIP format on the media       */
#define TL_RUGGEDIZED          8        /* Format ruggedized volume          */
#define TL_FAST_PARTITION      (TL_FORCE_REL | TL_FAST_MODE) /* Fast partition */

/* External Disk Partition Flags:
 *
 * TL_NORMAL_FORMAT / TL_FORMAT_FAT / TL_OLD_FORMAT
 */

#define TL_NORMAL_FORMAT       0
#define TL_FORMAT_FAT          2  /* Add FAT format on the media       */
#define TL_OLD_FORMAT          4  /* Format with 1 sector per cluster  */

/* External Binary Partition Flags 
 *
 * TL_NORMAL_FORMAT / TL_SPL_FORMAT 
 */

#define TL_SPL_FORMAT          (TL_SIMPLE_MATCHING | TL_NO_PLANES | TL_FORCE_REL) /* SPL partition */

/*********************************************/
/* Formatting parameter structure definition */
/*********************************************/

/*----------------------------------------------*/
/* User BDTL Partition Format Parameters record */
/*----------------------------------------------*/

typedef struct {
FLDword   length;
        /* The size of the usable storage space. The size will be
           rounded upwards to a multiplication of a block size.
           The size of the last partition will calculated automatically,
           but if the requested size is greater then the remaining space
           an error code will be returned,. Requesting zero size for any
      partition but the last will generate an flBadParameters status. */

unsigned        noOfSpareUnits;
        /* BDTL needs at least one spare erase unit in order to function
           as a read/write media. It is possible to specify more than one
           spare unit, which takes more media space. The advantage of
           specifying more than one spare unit is that if one of the flash
           erase units becomes bad and inerasable in the future, then one
           of the spare units can replace it. In that case, a second spare
           unit enables TrueFFS to continue its read/write functionality,
           whereas if no second spare unit is available the media goes into
           read-only mode. The standard value used is 1 */

FLByte   flags;                 /* A combination of the flags bellow:  */

/* TL_NORMAL_FORMAT / TL_FORMAT_FAT / TL_OLD_FORMAT */

FLByte         volumeId[4];  /* DOS partition identification number */

FLByte FAR1 *  volumeLabel;  /*DOS partition label string. If NULL, no label */

FLByte         noOfFATcopies;
        /* It is customary to format DOS media with two FAT copies. The
           first copy is always used, but more copies make it possible
           to recover if the FAT becomes corrupted (a rare occurrence).
           On the other hand, this slows down performance and uses media
           space. The standard value used is 2. */
#ifdef HW_PROTECTION
FLByte         protectionKey[8];   /* The key for the protection*/
FLByte         protectionType;
       /* PROTECTABLE          - Can recieve protection           */
       /* READ_PROTECTED       - Protect against read operations  */
       /* WRITE_PROTECTED      - Protect against write operations */
       /* LOCK_ENABLED         - Enables the hardware lock signal */
       /* PROTECTABLE          - This partition can be protected  */
       /* CHANGEABLE_PROTECTION - protection type can be changed */
#endif /* HW_PROTECTION */
#ifdef COMPRESSION
  FLWord       ratioDenominator;
  FLWord       ratioNominator;
#endif /* COMPRESSION */
       /* The ratio between the real media size and the virtual size
          reported to the file system when compression is active. */
} BDTLPartitionFormatParams;

/*------------------------------------------------*/
/* User binary Partition Format Parameters record */
/*------------------------------------------------*/

typedef struct {
FLDword length;   /* Required number of good blocks in the  partition.*/

FLByte sign[4];   /* signature of the binary  partition to format. 
                   The signature 0xFFFF FFFF is not a valid signature */

/* NOTE : the flags field used to be called signOffset */
FLByte flags; /* This field indicates one of the following modes : */

/* TL_NORMAL_FORMAT / TL_SPL_FORMAT */

#ifdef HW_PROTECTION
FLByte   protectionKey[8];   /* The key for the protection*/
FLByte   protectionType;
       /* PROTECTABLE          - Can recieve protection           */
       /* READ_PROTECTED       - Protect against read operations  */
       /* WRITE_PROTECTED      - Protect against write operations */
       /* LOCK_ENABLED         - Enables the hardware lock signal */
       /* PROTECTABLE          - This partition can be protected  */
       /* CHANGEABLE_PROTECTION - protection type can be changed */
#endif /* HW_PROTECTION */
} BinaryPartitionFormatParams;


/*-----------------------------------------------------------------*/
/* User Format Parameters record for flFormatPhysicalDrive routine */
/*-----------------------------------------------------------------*/

typedef FLStatus (*FLProgressCallback)(FLWord totalUnitsToFormat, FLWord totalUnitsFormattedSoFar);

typedef struct {

/*****************************/
/* Device formatting section */
/*****************************/

FLByte        percentUse;
       /* NAND flash inherently contains some bad blocks. TrueFFS handles 
	    * those blocks by managing a pool of spare blocks also called transfer
		* units. This format parameter specifies the percentage of the media 
		* to use. According to the flash specifications, SLC flashes should use
		* 98% while MLC flashes should use 95%. You can let TrueFFS 
		* automatically choose the percentage according to the flash spec by 
		* using the TL_DEFAULT_PERCENTAGE definition.
		*/

FLByte             noOfBDTLPartitions;
      /* Indicates the number of Disk partition (1 to 4). 0 will
       * format the media with a single disk partition 
       */

FLByte             noOfBinaryPartitions;
       /* Indicates the number of binary partitions (up to 3). 0 will
        * cause formatting with no binary partition. This value is ignored
        * if TL_LEAVE_BINARY_AREA flag is set in the irFlags field the ioreq 
		*/

BDTLPartitionFormatParams   FAR2* BDTLPartitionInfo;
       /* BDTL partition information array  */

BinaryPartitionFormatParams FAR2* binaryPartitionInfo;
       /* Binary partition information array*/

/***********************************/
/* Special format features section */
/***********************************/

#ifdef WRITE_EXB_IMAGE

void FAR1 *     exbBuffer;
   /* A buffer containing the EXB file. Optionaly this file can
      contain only the first 512 bytes of the file while the rest
      will be sent using consequitive calls to flPlaceExbByBuffer */