_dochapi.h

H3 M-system NAND flash driver in Linux OS, M-DOC driver

/******************************************************************************
 *                                                                            *
 * Project: DOC Driver for Linux 2.4 Block device driver for mDOC H3  family  *
 * of devices under Linux kernel 2.4.                                         *
 *                                                                            *
 *   Version: 1.0                                                             *
 *   Email questions to: [e-mail]                               *
 *   Copyright (C) SanDisk IL Ltd. 1995 - 2007                                *
 *   SanDisk IL Ltd., 7 Atir Yeda Street, Kfar Saba 44425, Israel             *
 *                                                                            *
 ******************************************************************************
 *                                                                            *
 * This program is free software; you can redistribute it and/or modify it    *
 * under the terms of the GNU General Public License as published by the Free *
 * Software Foundation; either version 2 of the License, or any later version.*
 * This program is distributed in the hope that it will be useful, but WITHOUT*
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or      *
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for  *
 * more details, which is set forth in the readme.txt file.                   *
 * You should have received a copy of the GNU General Public License along    *
 * with this program; if not, write to the Free Software Foundation, Inc., 51 *
 * Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA                    *
 *                                                                            *
 * This License does not grant you any right to use the trademarks, service   *
 * marks or logos of SanDisk IL Ltd. or SanDisk Corporation.                  *
 * Subject to the foregoing, SanDisk IL Ltd., for itself and on behalf of its *
 * licensors, hereby reserves all intellectual property rights in the program,*
 * except for the rights expressly granted in this License.                   *
 *                                                                            *
 ******************************************************************************/

/***********************************************************************************/
/*																				   */
/*	Internal header file for doch_api module									   */ 
/*																				   */
/***********************************************************************************/

/*
 * $Log:   V:/PVCSDB/DiskOnChip/archives/version 7.0/TrueFFS FS/src/h3/_dochapi.h-arc  $
 * 
 *    Rev 1.16   Sep 11 2006 13:45:10   yaniv.iarovici
 * Legal header added
 * 
 *    Rev 1.15   Sep 10 2006 10:02:40   Yaniv.Iarovici
 * Change SA SDK sub-version to "1.51 Prelim2".
 * 
 *    Rev 1.14   Aug 24 2006 11:40:36   Yaniv.Iarovici
 * Added 'DOCH_ACCESS_ALL_PARTITIONS' to structure 'DOCH_Access_Op'.
 * 
 *    Rev 1.13   Aug 16 2006 08:43:02   Yaniv.Iarovici
 * change SA SDK sub-version to Fin4
 * Change DOCH_SECTOR_SIZE_BITS to bit-manipulation on DOCH_SECTOR_SIZE_BITS insead of value of 512
 * Add #define DOCH_MAX_DRQ_SUPPORTED to indicate max DRQ size supported by the SDK
 * Change description of flDOCHGetPowerMode() and flDOCHSetPowerMode() to fit SW Spec 0.84
 * 
 *    Rev 1.12   Aug 09 2006 17:27:42   Polina.Marimont
 * initial for DOC Driver 1.0
 * 
 *    Rev 1.10   Jul 03 2006 22:45:02   polina.marimont
 * version change
 * 
 *    Rev 1.9   Jul 03 2006 22:12:32   polina.marimont
 * version changed
 * 
 *    Rev 1.8   Jun 22 2006 16:56:32   Polina.Marimont
 * version changed
 * 
 *    Rev 1.7   Jun 21 2006 18:23:34   Polina.Marimont
 * 1. version update
 * 2. set power mode function description updated
 * 
 *    Rev 1.6   Jun 18 2006 13:01:58   Polina.Marimont
 * 1. version changed
 * 2. power mode save function chaged
 * 
 *    Rev 1.5   Jun 14 2006 17:31:52   Polina.Marimont
 * version updated
 * 
 *    Rev 1.4   May 30 2006 10:40:24   polina.marimont
 * version change to 1.42 Pre 3
 * 
 *    Rev 1.3   May 28 2006 12:48:26   polina.marimont
 * version 1.42 Pre1
 * 
 *    Rev 1.2   May 18 2006 14:40:46   polina.marimont
 * PVCS inside
 */

#ifndef _DOCHAPI
#define _DOCHAPI

#include "_common.h"

/***********************/
/*	SDK Version Number */
/***********************/
#define DochSDKVersion     "0151"
#define DochSDKSubVersion  "Pre2"

/********************/
/*	Partitions		*/
/********************/

/*	Pattern to indicate a boolean global variable was set
	(to deal with "naughty" compilers...)*/
#define DOCH_GLOBAL_BOOL_PATTERN 0xCAFE

/*	Max number of paritions	*/
#define DOCH_MAX_PARTITIONS 16

/*IPL partition*/
#define DOCH_IPL_PARTITION				0
#define IPL_PARTITION_SIZE_SECTORS		0x200	/*256KB in sectors*/
#define IPL_PARTITION_SIZE_V_SECTORS	0x10   /* 8K KB sectors*/


/********************/
/*	Various Defines	*/
/********************/

/* On/Off definitions */
#define DOCH_OFF	0
#define DOCH_ON		1

/* size of DOCH data block in FLBytes */
#define	DOCH_SECTOR_SIZE_BITS	9
#define DOCH_SECTOR_SIZE		(1<<DOCH_SECTOR_SIZE_BITS)

/* Operations on IOreq structure */
#define DOCH_GET_SOCKET_FROM_IOREQ_HANDLE(ioreq)			(FLByte)((ioreq)->irHandle & 0x0f)
#define DOCH_SET_SOCKET_TO_IOREQ_HANDLE(ioreq, socket)		((ioreq)->irHandle |= (socket))

#define DOCH_GET_PARTITION_FROM_IOREQ_HANDLE(ioreq)			(FLByte)(((ioreq)->irHandle & 0xf0) >> 4)
#define DOCH_SET_PARTITION_TO_IOREQ_HANDLE(ioreq, part)		((ioreq)->irHandle = \
															( ((part & 0xF) << 4) | ((ioreq)->irHandle & 0xFFFFFF0F)) )

/*	Operation type (for long operations)	*/
#define DOCH_NORMAL_OPERATION		0x00
#define DOCH_IMMEDIATE_OPERATION	0x80

/*	Data transfer modes	*/
typedef enum { DOCH_DATA_XFER_MODE_SINGLE		= 0x00,
			   DOCH_DATA_XFER_MODE_MULT			= 0x01
} DOCH_DataTransferMode;
/*Max supported DRQ*/
#define DOCH_MAX_DRQ_SUPPORTED	4

/*ETFFS Alert Levels*/
typedef enum {
	DOCH_ALERT_LEVEL_CRASH		= 0,	/*Prints only errors that H3 can not recover from*/
	DOCH_ALERT_LEVEL_EMERGENCY	= 1,	/*Prints only important, but not lethal errors*/
	DOCH_ALERT_LEVEL_REPORT		= 2,	/*Prints basic report on H3 operations*/
	DOCH_ALERT_LEVEL_DEBUG		= 3,	/*Prints full report on H3 progress*/
	DOCH_ALERT_LEVEL_BORING		= 4		/*Prints every operation done by H3*/
} DOCH_AlertLevel;

/*	Power mode constants */
typedef enum {
	DOCH_PM_SET_NONE			= 0x00,
	DOCH_PM_SET_WORK_MODE		= 0x01,
	DOCH_PM_SET_INACTIVE_MODE	= 0x02,
	DOCH_PM_SET_BOTH_MODES		= 0x03
} DOCH_SetPowerMode;

typedef enum {
	DOCH_PM_WORK_MODE		= 0x00,
	DOCH_PM_INACTIVE_MODE	= 0x04
} DOCH_SelectedPowerMode;

typedef enum {
	DOCH_WM_NORMAL					= 0x00,	/*Same as ATA ACTIVE Mode*/
	DOCH_WM_LOW_FREQ				= 0x01,	/*Same as ATA IDLE Mode*/
	DOCH_WM_NORMAL_AND_AUTO_STBY	= 0x02,
	DOCH_WM_LOW_FREQ_AND_AUTO_STBY	= 0x03
} DOCH_WorkMode;

typedef enum {
	DOCH_IM_IDLE			= 0x00,			/*Same as ATA STANDBY Mode*/
	DOCH_IM_DPD				= 0x10,			/*Same as ATA SLEEP Mode*/
	DOCH_IM_IDLE_2_DPD      = 0x20			/*No timeout IDLE ==> DPD */
} DOCH_InactiveMode;

#define DOCH_PM_SAVE_DEFAULT	0x10		/*Save power mode settings as device default*/

/*	Custom Parameters Table	*/
typedef enum { 
	DOCH_CP_BOOT_MODE		= 0x00,	/*Boot Mode (See DOCH_IPLModes)*/
	DOCH_CP_XIP_TEST_MODE	= 0x01,	/*XIP Test Modes (See DOCH_XIPTestModes)*/
	DOCH_CP_XIP_MAX_SIZE	= 0x02,	/*Max XIP Size*/
	DOCH_CP_XIP_ETFFS_SIZE	= 0x03,	/*Returns the size of the currently saved ETFFS (required for uploading the ETFFS)*/
	DOCH_CP_WORK_MODES		= 0x04,	/*Work Modes (Bit Field, see enum DOCH_CPWorkModes)*/
	DOCH_CP_SLOCK_CTRL		= 0x05,	/*Sticky Lock control (See DOCH_SlockCtrl)*/
	DOCH_CP_BYTE_SWAP_CTRL	= 0x06,	/*Byte Swap control (See DOCH_ByteSwapCtrl)*/
	DOCH_CP_FLASH_TEST_MODE	= 0x07	/*Enable/Disable flash test mode (See DOCH_FlashTestModeCtrl)*/
} DOCH_CustomParams;

#define DOCH_CUSTOM_PARAM_TEMP		1
#define DOCH_CUSTOM_PARAM_DEFAULT	0

/* IPL Modes */
typedef enum {
	DOCH_IPL_MODE_NORMAL_RAM				= 0x0000,
	DOCH_IPL_MODE_PAGED_RAM					= 0x0001,
	DOCH_IPL_MODE_VIRTUAL_RAM				= 0x0002,
	DOCH_IPL_MODE_CS_DELAY					= 0x1000,	/*Should be Or`ed with 0x0XX0, where bits 4-11 indicating delay*/
	DOCH_IPL_MODE_ADDRESS_SHIFT_IN_AFFECT	= 0x2000,
	DOCH_IPL_MODE_ACTIVE_SWAP_BYTES			= 0x4000,
	DOCH_IPL_MODE_8KB_WINDOW				= 0x8000
} DOCH_IPLModes;

#define	DOCH_IPL_WRITE_FIRST_CHUNK			0x80000000 /*Defines first chunk when writing IPL in chunks*/

/* XIP Test Modes */ /*No default value, will be cleared upon reset*/
typedef enum {
	DOCH_XIP_NORMAL			= 0x0000,
	DOCH_XIP_WRITEABLE		= 0x0001,
	DOCH_XIP_FILL_PATTERN	= 0x0002,	/*"M-Systems" and the rest with consecutive 16bit numbers*/
	DOCH_XIP_PIPELINE		= 0x0003	/*Places the device in pipeline access mode*/
} DOCH_XIPTestModes;

typedef enum {
	DOCH_WORK_MODES_BLOCK_SPI = 0x0002	/*Block SPI*/
} DOCH_CPWorkModes;

typedef enum {
	DOCH_STICKY_LOCK_UNSET = 0x00,
	DOCH_STICKY_LOCK_SET   = 0x01
} DOCH_SlockCtrl;

typedef enum {
	DOCH_BYTE_SWAP_UNSET = 0x00,
	DOCH_BYTE_SWAP_SET   = 0x01
} DOCH_ByteSwapCtrl;

typedef enum {
	DOCH_DISABLE_FLASH_TEST_MODE	= 0x00,
	DOCH_ENABLE_FLASH_TEST_MODE		= 0x01
} DOCH_FlashTestModeCtrl;


typedef enum {
	DOCH_DLMCODE_DOWNLOAD						= 0x01,	/*Download is for immediate, temporary use*/
	DOCH_DLMCODE_DOWNLOAD_AND_SAVE				= 0x07,	/*Save downloaded code for immediate & future use*/
	DOCH_DLMCODE_DOWNLOAD_AND_LAST_SAVE			= 0x87,	/*Same as code 0x07, but marking this as the last permanent
														  download accepted by the device*/
	DOCH_DLMCODE_UPLOAD							= 0xFF
} DOCH_DLMcodeModes;

/* Set of access options for DOCH_EN_ACCESS_WPWD	*/
typedef enum { DOCH_ACCESS_USER_PASSWORD	= 0x00,
			   DOCH_ACCESS_MASTER_PASSWORD	= 0x01,
			   DOCH_ACCESS_GATE_KEEPER		= 0x02,

			   DOCH_ACCESS_ALL_PARTITIONS	= 0xFF
} DOCH_Access_Op;

/*Defines for DOCHConfigHW*/
/*------------------------*/
typedef enum {
	DOCH_BURST_WRITE_MODE_CTRL	= 0x0,
	DOCH_BURST_READ_MODE_CTRL	= 0x1,
	DOCH_IPL_CTRL				= 0x2,
	DOCH_WARM_BOOT_CTRL			= 0x3,
	DOCH_POWER_DOWN				= 0x4,
	DOCH_DMA_CTRL				= 0x5,
	DOCH_DMA_ENABLE				= 0x6,
	DOCH_DMA_NEGATION_CTRL		= 0x7,
	DOCH_SLOCK					= 0x8,
	DOCH_ENDIAN_CTRL			= 0x9,
	DOCH_OPERATION_MODE_CTRL	= 0xA,
	DOCH_POWER_MODE_CTRL		= 0xB
} DOCH_HwConfigType;

/* DOCH_NUM_OF_DCONFIGHW_ITEMS should be set to number of items in DOCH_HwConfigType*/
#define DOCH_NUM_OF_DCONFIGHW_ITEMS 0xC

/*IPL Control Register*/
#define DOCH_IPL_WRITE_DISABLE       0x0000
#define DOCH_IPL_WRITE_READY         0x0001
#define DOCH_IPL_WRITE_ENABLE        0x0002

#define DOCH_IPL_ALL_CS_ENABLED		 0x0000
#define DOCH_IPL_CLOSE_2LOW_IPLS	 0x0010
#define DOCH_IPL_CLOSE_2HIGH_IPLS	 0x0020
#define DOCH_IPL_CLOSE_ALL_IPLS		 0x0030

/*Warm Boot Register*/
#define DOCH_WARM_RST_POLARITY_LOW   0x0000
#define DOCH_WARM_RST_POLARITY_HIGH  0x0001

#define DOCH_WARM_RST_BURST_ON       0x0000
#define DOCH_WARM_RST_BURST_NO_CHNG  0x0002

/*Deep Power Down Mode Register*/
#define DOCH_DPD_PIN_POL_LOW		 0x0000
#define DOCH_DPD_PIN_POL_HIGH		 0x0001

#define DOCH_DPD_PIN_DISABLED		 0x0000
#define DOCH_DPD_PIN_ENABLED		 0x0002