flash.h

Flash的驱动程序。包括市面上常见的Nor Flash和Nand Flash.基本上所有的Flash只需要简单修改就可以移植到其他应用。

#ifndef __FLASH_H__
#define __FLASH_H__

/**********************************************************************
 * flash.h
 *
 * File System Device interface.
 *
 * This module implements a device-independent view of the low-level flash
 * system devices.  This interface hides all of the implementation details
 * and device differences between the diverse device types.
 *
 * Copyright (C) 2004-2006, Qualcomm, Inc.
 *
 **********************************************************************/

/*===========================================================================

                        EDIT HISTORY FOR MODULE

  This section contains comments describing changes made to the module.
  Notice that changes are listed in reverse chronological order.

  $Header: //depot/asic/msmshared/drivers/flash/MSM_FLASH.01.04/flash.h#3 $ $DateTime: 2006/05/23 10:27:05 $ $Author: dhamimp $

when         who     what, where, why
--------     ---     ----------------------------------------------------------
2006-05-23   dp      Changed feature macro names to be consistent
2006-05-04   dp      Adding controller abstraction layer
2006-01-27   dp      Added Intel MLC support
2004-09-30   drh     Moved partition support from one file to another
2004-08-09   drh     Added support for ECC manipulation
2004-03-19   drh     Move partition definitions to separate header file
2004-02-23   drh     Added support for partition tables
2004-01-21   drh     Came from services/efs/fs_device.h

===========================================================================*/


#include "comdef.h"
#include "customer.h"

typedef uint32 page_id;
typedef uint32 block_id;
typedef uint32 cluster_id;

#define FS_NO_DEVICE                              ((fs_device_t) 0)
#define FS_DEVICE_OK                              0
#define FS_DEVICE_DONE                            0
#define FS_DEVICE_FAIL                            (-1)
#define FS_DEVICE_BAD_BLOCK                       (-2)
#define FS_DEVICE_BUSY                            (-3)
#define FS_DEVICE_PARTITION_NOT_FOUND             (-4)
#define FS_DEVICE_NO_PARTITION_TABLE              (-5)
#define FS_DEVICE_INVALID_DEVICE                  (-6)
#define FS_DEVICE_INVALID_PARTITION_NAME          (-7)
#define FS_DEVICE_INVALID_FLASH                   (-8)
#define FS_DEVICE_PARTITION_TABLE_FULL            (-9)
#define FS_DEVICE_PARTITION_INVALID_NAME          (-10)
#define FS_DEVICE_PARTITION_TABLE_EXISTS          (-11)
#define FS_DEVICE_DUPLICATE_PARTITION             (-12)
#define FS_DEVICE_INVALID_PARTITION_TABLE         (-13)
#define FS_DEVICE_PARTITION_TABLE_VERSION_SKEW    (-14)
#define FS_DEVICE_NOT_SUPPORTED                   (-15)

#define FLASH_UNLOCK_OP                           0x1
#define FLASH_LOCK_OP                             0x2
#define FLASH_LOCKTIGHT_OP                        0x3

/* This define is used for MLC support by EFS2 */
#define HAVE_FLASH_WRITE_STYLE
/* This define is used for copy page API support */
#define HAVE_FLASH_COPY_PAGE
/* This define is used for read multiple pages API support */
#define HAVE_FLASH_READ_MPAGES
/* This define is used for generic spare bytes API support */
#define HAVE_FLASH_READ_SPARE_BYTES

/* Description of how write grouping happens, and what is necessary to
 * recover from partial and failed writes. */
typedef enum {

  FS_DEVICE_WRITES_SIMPLE,
  /* NOR devices where arbitrary bits can be set to zero.  SLC NOR devices
   * generally fall in this category. */

  FS_DEVICE_WRITES_PAGED,
  /* NAND devices requiring entire pages to be written, and can only be
   * written to once.  These devices do not allow 'partial_write'. */

  FS_DEVICE_WRITES_PAIRED_BITS,
  /* NOR devices where adjacent pairs of bits are written together.  A pair
   * can be written from '11' to a value, and from a value to '00'.  If
   * recovery from failed writes is needed, the only two values that should
   * be used are '11' and '00'.  After a failed write, it may not be
   * possible to write the pair to any value other than '00'. */

  FS_DEVICE_WRITES_UNSUPPORTED = 0x1000,
  /* Indicates a NOR device with an unsupported write style.  No
   * assumptions can be made about how the data is written.  Pages must be
   * written in their entirety, and pages that have bad powerdowns cannot
   * be used. */

} fs_device_write_style_t;

/*------------------------------------------------------------
 *
 *  Flash Device Definitions
 *
 * ---------------------------------------------------------*/

/* Public interface to the flash device drivers */
struct fs_device_data;

typedef struct fs_device_data *fs_device_t;

struct fs_device_data {

  /* Query operations. */

  /* These will no longer be one each for each device, but
   * will be generic functions that extract data from the
   * private portions of the device structure and return
   * that data.  They will operate the same for all devices. */
  char * (*device_name) (fs_device_t self);
  int (*device_maker_id) (fs_device_t self);
  int (*device_id) (fs_device_t self);
  uint32 (*block_count) (fs_device_t self);
  uint32 (*block_size) (fs_device_t self);
  uint32 (*page_size) (fs_device_t self);
  uint32 (*total_page_size) (fs_device_t self);

  /* Initial bad block check for Nand device */
  int (*bad_block_check) (fs_device_t self, block_id block);

  /* Mark a block as bad for Nand device */
  int (*mark_block_bad) (fs_device_t self, block_id block);

  /* Write operations. */
  int (*write_page) (fs_device_t self,
    page_id page,
    void *data);

  /* A full erase.  Eventually, will implement NOR-style partial erasing. */
  int (*erase_block) (fs_device_t self,
    block_id block);

  /* Get the address of read data.  Returns NULL if this device doesn't
   * support direct mapping of read data. */
  void *(*read_pointer) (fs_device_t self,
    page_id page);

  /* Read the data into a buffer.  Can be used if the above returns NULL. */
  int (*read_page) (fs_device_t self,
    page_id page,
    void *data);

  /* Determine erase status of page */
  int (*is_erased) (fs_device_t self, page_id page);  

  /* If this function pointer is non-null, then can be called to perform a
   * partial page write.  It is only valid to change FF's in flash into
   * values, and then to change values into 00's.  The write must be
   * contained entirely within a page, and is only guaranteed to work
   * on 32 bit boundaries. */
  int (*partial_write) (fs_device_t self, page_id page,
    void *data, int offset, int length);

  /* A full erase that returns and leaves the erase pending */
  int (*begin_erase_block) (fs_device_t self,
    block_id block);

  /* Suspend the current erase */
  int (*suspend_erase) (fs_device_t self);

  /* Resume suspended erase */
  int (*resume_erase) (fs_device_t self);

  /* Check if the erase block operation begun with begin_erase_block has 
   * completed. */
  int (*erase_status) (fs_device_t self);

  /* Check if given block is erased */
  int (*is_block_erased) (fs_device_t self, block_id block);  

  /* Read len bytes from spare_offset in the spare area in given page
   * and copy into given data buffer */
  int (*read_spare_bytes) (fs_device_t self, page_id page, uint32 spare_offset, 
    uint32 len, void *data);

  /* Read num_pages from start_page and copy them into given data location/
   * address */
  int (*read_mpages) (fs_device_t self, page_id start_page, page_id num_pages, 
    void *data, void (*wdog_kick_fn_ptr)(void));

  /* Copy data from source page and write it into dest_page */
  int (*copy_page) (fs_device_t self, page_id src_page, page_id dest_page);

  /* Support lock/unlock/locktight of blocks from start_page to end_page */
  int (*lock_ops) (fs_device_t self, page_id start_page, page_id end_page,
    uint32 opcode);

  /* Open a particular partition.
   *     Caller passes device structure filled in during probe,
   *     this function call may modify it if successful. */
  int (*open_partition) (fs_device_t self, char *partition_name);

  /* Add a new partition.
   *     Will create a new partition table in RAM if none exists.
   *     Will update an existing partition table if one exists.
   *     Will fail if entry already exists.
   *  Offset and length quantities are in blocks. */
  int (*add_partition) (fs_device_t self, char *partition_name,
    uint32 which_flash, uint32 offset, uint32 length );
  
  /* Commit partition table.
   *     Will write the current RAM version of the partition table to flash.
   *     Will fail if a table already exists. */
  int (*commit_partition_table) (fs_device_t self);

  /* Change the default state of ECC calculation
   *     This is used mainly when reading back a raw file system
   *     using flash tools. */
  void (*set_ecc_state) (fs_device_t self, int state);
  
  /* Get the device write style. */
  fs_device_write_style_t
    (*get_write_style) (fs_device_t self);
};

#endif /* __FLASH_H__ */