[deliverable/linux.git] / include / linux / mtd / mtd.h

/*
 * $Id: mtd.h,v 1.61 2005/11/07 11:14:54 gleixner Exp $
 *
 * Copyright (C) 1999-2003 David Woodhouse <dwmw2@infradead.org> et al.
 *
 * Released under GPL
 */

#ifndef __MTD_MTD_H__
#define __MTD_MTD_H__

#ifndef __KERNEL__
#error This is a kernel header. Perhaps include mtd-user.h instead?
#endif

#include <linux/types.h>
#include <linux/module.h>
#include <linux/uio.h>
#include <linux/notifier.h>

#include <linux/mtd/compatmac.h>
#include <mtd/mtd-abi.h>

#define MTD_CHAR_MAJOR 90
#define MTD_BLOCK_MAJOR 31
#define MAX_MTD_DEVICES 32

#define MTD_ERASE_PENDING      	0x01
#define MTD_ERASING		0x02
#define MTD_ERASE_SUSPEND	0x04
#define MTD_ERASE_DONE          0x08
#define MTD_ERASE_FAILED        0x10

/* If the erase fails, fail_addr might indicate exactly which block failed.  If
   fail_addr = 0xffffffff, the failure was not at the device level or was not
   specific to any particular block. */
struct erase_info {
	struct mtd_info *mtd;
	u_int32_t addr;
	u_int32_t len;
	u_int32_t fail_addr;
	u_long time;
	u_long retries;
	u_int dev;
	u_int cell;
	void (*callback) (struct erase_info *self);
	u_long priv;
	u_char state;
	struct erase_info *next;
};

struct mtd_erase_region_info {
	u_int32_t offset;			/* At which this region starts, from the beginning of the MTD */
	u_int32_t erasesize;		/* For this region */
	u_int32_t numblocks;		/* Number of blocks of erasesize in this region */
};

/*
 * oob operation modes
 *
 * MTD_OOB_PLACE:	oob data are placed at the given offset
 * MTD_OOB_AUTO:	oob data are automatically placed at the free areas
 *			which are defined by the ecclayout
 * MTD_OOB_RAW:		mode to read raw data+oob in one chunk. The oob data
 *			is inserted into the data. Thats a raw image of the
 *			flash contents.
 */
typedef enum {
	MTD_OOB_PLACE,
	MTD_OOB_AUTO,
	MTD_OOB_RAW,
} mtd_oob_mode_t;

/**
 * struct mtd_oob_ops - oob operation operands
 * @mode:	operation mode
 *
 * @len:	number of data bytes to write/read
 *
 * @retlen:	number of data bytes written/read
 *
 * @ooblen:	number of oob bytes to write/read
 * @oobretlen:	number of oob bytes written/read
 * @ooboffs:	offset of oob data in the oob area (only relevant when
 *		mode = MTD_OOB_PLACE)
 * @datbuf:	data buffer - if NULL only oob data are read/written
 * @oobbuf:	oob data buffer
 */
struct mtd_oob_ops {
	mtd_oob_mode_t	mode;
	size_t		len;
	size_t		retlen;
	size_t		ooblen;
	size_t		oobretlen;
	uint32_t	ooboffs;
	uint8_t		*datbuf;
	uint8_t		*oobbuf;
};

struct mtd_info {
	u_char type;
	u_int32_t flags;
	u_int32_t size;	 // Total size of the MTD

	/* "Major" erase size for the device. Naïve users may take this
	 * to be the only erase size available, or may use the more detailed
	 * information below if they desire
	 */
	u_int32_t erasesize;
	/* Minimal writable flash unit size. In case of NOR flash it is 1 (even
	 * though individual bits can be cleared), in case of NAND flash it is
	 * one NAND page (or half, or one-fourths of it), in case of ECC-ed NOR
	 * it is of ECC block size, etc. It is illegal to have writesize = 0.
	 * Any driver registering a struct mtd_info must ensure a writesize of
	 * 1 or larger.
	 */
	u_int32_t writesize;

	u_int32_t oobsize;   // Amount of OOB data per block (e.g. 16)
	u_int32_t ecctype;
	u_int32_t eccsize;

	/*
	 * Reuse some of the above unused fields in the case of NOR flash
	 * with configurable programming regions to avoid modifying the
	 * user visible structure layout/size.  Only valid when the
	 * MTD_PROGRAM_REGIONS flag is set.
	 * (Maybe we should have an union for those?)
	 */
#define MTD_PROGREGION_CTRLMODE_VALID(mtd)  (mtd)->oobsize
#define MTD_PROGREGION_CTRLMODE_INVALID(mtd)  (mtd)->ecctype

	// Kernel-only stuff starts here.
	char *name;
	int index;

	/* ecc layout structure pointer - read only ! */
	struct nand_ecclayout *ecclayout;

	/* Data for variable erase regions. If numeraseregions is zero,
	 * it means that the whole device has erasesize as given above.
	 */
	int numeraseregions;
	struct mtd_erase_region_info *eraseregions;

	/* This really shouldn't be here. It can go away in 2.5 */
	u_int32_t bank_size;

	int (*erase) (struct mtd_info *mtd, struct erase_info *instr);

	/* This stuff for eXecute-In-Place */
	int (*point) (struct mtd_info *mtd, loff_t from, size_t len, size_t *retlen, u_char **mtdbuf);

	/* We probably shouldn't allow XIP if the unpoint isn't a NULL */
	void (*unpoint) (struct mtd_info *mtd, u_char * addr, loff_t from, size_t len);


	int (*read) (struct mtd_info *mtd, loff_t from, size_t len, size_t *retlen, u_char *buf);
	int (*write) (struct mtd_info *mtd, loff_t to, size_t len, size_t *retlen, const u_char *buf);

	int (*read_oob) (struct mtd_info *mtd, loff_t from,
			 struct mtd_oob_ops *ops);
	int (*write_oob) (struct mtd_info *mtd, loff_t to,
			 struct mtd_oob_ops *ops);

	/*
	 * Methods to access the protection register area, present in some
	 * flash devices. The user data is one time programmable but the
	 * factory data is read only.
	 */
	int (*get_fact_prot_info) (struct mtd_info *mtd, struct otp_info *buf, size_t len);
	int (*read_fact_prot_reg) (struct mtd_info *mtd, loff_t from, size_t len, size_t *retlen, u_char *buf);
	int (*get_user_prot_info) (struct mtd_info *mtd, struct otp_info *buf, size_t len);
	int (*read_user_prot_reg) (struct mtd_info *mtd, loff_t from, size_t len, size_t *retlen, u_char *buf);
	int (*write_user_prot_reg) (struct mtd_info *mtd, loff_t from, size_t len, size_t *retlen, u_char *buf);
	int (*lock_user_prot_reg) (struct mtd_info *mtd, loff_t from, size_t len);

	/* kvec-based read/write methods.
	   NB: The 'count' parameter is the number of _vectors_, each of
	   which contains an (ofs, len) tuple.
	*/
	int (*writev) (struct mtd_info *mtd, const struct kvec *vecs, unsigned long count, loff_t to, size_t *retlen);

	/* Sync */
	void (*sync) (struct mtd_info *mtd);

	/* Chip-supported device locking */
	int (*lock) (struct mtd_info *mtd, loff_t ofs, size_t len);
	int (*unlock) (struct mtd_info *mtd, loff_t ofs, size_t len);

	/* Power Management functions */
	int (*suspend) (struct mtd_info *mtd);
	void (*resume) (struct mtd_info *mtd);

	/* Bad block management functions */
	int (*block_isbad) (struct mtd_info *mtd, loff_t ofs);
	int (*block_markbad) (struct mtd_info *mtd, loff_t ofs);

	struct notifier_block reboot_notifier;  /* default mode before reboot */

	/* ECC status information */
	struct mtd_ecc_stats ecc_stats;

	void *priv;

	struct module *owner;
	int usecount;
};


	/* Kernel-side ioctl definitions */

extern int add_mtd_device(struct mtd_info *mtd);
extern int del_mtd_device (struct mtd_info *mtd);

extern struct mtd_info *get_mtd_device(struct mtd_info *mtd, int num);

extern void put_mtd_device(struct mtd_info *mtd);


struct mtd_notifier {
	void (*add)(struct mtd_info *mtd);
	void (*remove)(struct mtd_info *mtd);
	struct list_head list;
};


extern void register_mtd_user (struct mtd_notifier *new);
extern int unregister_mtd_user (struct mtd_notifier *old);

int default_mtd_writev(struct mtd_info *mtd, const struct kvec *vecs,
		       unsigned long count, loff_t to, size_t *retlen);

int default_mtd_readv(struct mtd_info *mtd, struct kvec *vecs,
		      unsigned long count, loff_t from, size_t *retlen);

#ifdef CONFIG_MTD_PARTITIONS
void mtd_erase_callback(struct erase_info *instr);
#else
static inline void mtd_erase_callback(struct erase_info *instr)
{
	if (instr->callback)
		instr->callback(instr);
}
#endif

/*
 * Debugging macro and defines
 */
#define MTD_DEBUG_LEVEL0	(0)	/* Quiet   */
#define MTD_DEBUG_LEVEL1	(1)	/* Audible */
#define MTD_DEBUG_LEVEL2	(2)	/* Loud    */
#define MTD_DEBUG_LEVEL3	(3)	/* Noisy   */

#ifdef CONFIG_MTD_DEBUG
#define DEBUG(n, args...)				\
	do {						\
		if (n <= CONFIG_MTD_DEBUG_VERBOSE)	\
			printk(KERN_INFO args);		\
	} while(0)
#else /* CONFIG_MTD_DEBUG */
#define DEBUG(n, args...) do { } while(0)

#endif /* CONFIG_MTD_DEBUG */

#endif /* __MTD_MTD_H__ */
Commit	Line	Data
61ecfa87 TG	1	/*
61ecfa87 TG	2	* $Id: mtd.h,v 1.61 2005/11/07 11:14:54 gleixner Exp $
1da177e4 LT	3	*
	4	* Copyright (C) 1999-2003 David Woodhouse <dwmw2@infradead.org> et al.
	5	*
	6	* Released under GPL
	7	*/
	8
	9	#ifndef __MTD_MTD_H__
	10	#define __MTD_MTD_H__
	11
	12	#ifndef __KERNEL__
	13	#error This is a kernel header. Perhaps include mtd-user.h instead?
	14	#endif
	15
1da177e4 LT	16	#include <linux/types.h>
	17	#include <linux/module.h>
	18	#include <linux/uio.h>
963a6fb0	19	#include <linux/notifier.h>
1da177e4 LT	20
	21	#include <linux/mtd/compatmac.h>
	22	#include <mtd/mtd-abi.h>
	23
	24	#define MTD_CHAR_MAJOR 90
	25	#define MTD_BLOCK_MAJOR 31
c0fe10ae	26	#define MAX_MTD_DEVICES 32
1da177e4 LT	27
	28	#define MTD_ERASE_PENDING 0x01
	29	#define MTD_ERASING 0x02
	30	#define MTD_ERASE_SUSPEND 0x04
	31	#define MTD_ERASE_DONE 0x08
	32	#define MTD_ERASE_FAILED 0x10
	33
	34	/* If the erase fails, fail_addr might indicate exactly which block failed. If
	35	fail_addr = 0xffffffff, the failure was not at the device level or was not
	36	specific to any particular block. */
	37	struct erase_info {
	38	struct mtd_info *mtd;
	39	u_int32_t addr;
	40	u_int32_t len;
	41	u_int32_t fail_addr;
	42	u_long time;
	43	u_long retries;
	44	u_int dev;
	45	u_int cell;
	46	void (callback) (struct erase_info self);
	47	u_long priv;
	48	u_char state;
	49	struct erase_info *next;
	50	};
	51
	52	struct mtd_erase_region_info {
	53	u_int32_t offset; /* At which this region starts, from the beginning of the MTD */
	54	u_int32_t erasesize; /* For this region */
	55	u_int32_t numblocks; /* Number of blocks of erasesize in this region */
	56	};
	57
8593fbc6 TG	58	/*
	59	* oob operation modes
	60	*
	61	* MTD_OOB_PLACE: oob data are placed at the given offset
	62	* MTD_OOB_AUTO: oob data are automatically placed at the free areas
	63	* which are defined by the ecclayout
	64	* MTD_OOB_RAW: mode to read raw data+oob in one chunk. The oob data
	65	* is inserted into the data. Thats a raw image of the
	66	* flash contents.
	67	*/
	68	typedef enum {
	69	MTD_OOB_PLACE,
	70	MTD_OOB_AUTO,
	71	MTD_OOB_RAW,
	72	} mtd_oob_mode_t;
	73
	74	/**
	75	* struct mtd_oob_ops - oob operation operands
	76	* @mode: operation mode
	77	*
7014568b	78	* @len: number of data bytes to write/read
8593fbc6	79	*
7014568b	80	* @retlen: number of data bytes written/read
8593fbc6	81	*
7014568b VW	82	* @ooblen: number of oob bytes to write/read
7014568b VW	83	* @oobretlen: number of oob bytes written/read
8593fbc6 TG	84	* @ooboffs: offset of oob data in the oob area (only relevant when
	85	* mode = MTD_OOB_PLACE)
	86	* @datbuf: data buffer - if NULL only oob data are read/written
	87	* @oobbuf: oob data buffer
	88	*/
	89	struct mtd_oob_ops {
	90	mtd_oob_mode_t mode;
	91	size_t len;
	92	size_t retlen;
	93	size_t ooblen;
7014568b	94	size_t oobretlen;
8593fbc6 TG	95	uint32_t ooboffs;
	96	uint8_t *datbuf;
	97	uint8_t *oobbuf;
	98	};
	99
1da177e4 LT	100	struct mtd_info {
	101	u_char type;
	102	u_int32_t flags;
	103	u_int32_t size; // Total size of the MTD
	104
151e7659	105	/* "Major" erase size for the device. Naïve users may take this
1da177e4 LT	106	* to be the only erase size available, or may use the more detailed
	107	* information below if they desire
	108	*/
	109	u_int32_t erasesize;
783ed81f AB	110	/* Minimal writable flash unit size. In case of NOR flash it is 1 (even
	111	* though individual bits can be cleared), in case of NAND flash it is
	112	* one NAND page (or half, or one-fourths of it), in case of ECC-ed NOR
	113	* it is of ECC block size, etc. It is illegal to have writesize = 0.
	114	* Any driver registering a struct mtd_info must ensure a writesize of
	115	* 1 or larger.
28318776 JE	116	*/
28318776 JE	117	u_int32_t writesize;
1da177e4	118
1da177e4	119	u_int32_t oobsize; // Amount of OOB data per block (e.g. 16)
1da177e4 LT	120	u_int32_t ecctype;
1da177e4 LT	121	u_int32_t eccsize;
638d9838 NP	122
	123	/*
	124	* Reuse some of the above unused fields in the case of NOR flash
	125	* with configurable programming regions to avoid modifying the
	126	* user visible structure layout/size. Only valid when the
	127	* MTD_PROGRAM_REGIONS flag is set.
	128	* (Maybe we should have an union for those?)
	129	*/
638d9838 NP	130	#define MTD_PROGREGION_CTRLMODE_VALID(mtd) (mtd)->oobsize
638d9838 NP	131	#define MTD_PROGREGION_CTRLMODE_INVALID(mtd) (mtd)->ecctype
1da177e4 LT	132
	133	// Kernel-only stuff starts here.
	134	char *name;
	135	int index;
	136
5bd34c09 TG	137	/* ecc layout structure pointer - read only ! */
5bd34c09 TG	138	struct nand_ecclayout *ecclayout;
1da177e4 LT	139
1da177e4 LT	140	/* Data for variable erase regions. If numeraseregions is zero,
61ecfa87	141	* it means that the whole device has erasesize as given above.
1da177e4 LT	142	*/
1da177e4 LT	143	int numeraseregions;
61ecfa87	144	struct mtd_erase_region_info *eraseregions;
1da177e4 LT	145
	146	/* This really shouldn't be here. It can go away in 2.5 */
	147	u_int32_t bank_size;
	148
	149	int (erase) (struct mtd_info mtd, struct erase_info *instr);
	150
	151	/* This stuff for eXecute-In-Place */
	152	int (point) (struct mtd_info mtd, loff_t from, size_t len, size_t retlen, u_char *mtdbuf);
	153
	154	/* We probably shouldn't allow XIP if the unpoint isn't a NULL */
	155	void (unpoint) (struct mtd_info mtd, u_char * addr, loff_t from, size_t len);
	156
	157
	158	int (read) (struct mtd_info mtd, loff_t from, size_t len, size_t retlen, u_char buf);
	159	int (write) (struct mtd_info mtd, loff_t to, size_t len, size_t retlen, const u_char buf);
	160
8593fbc6 TG	161	int (read_oob) (struct mtd_info mtd, loff_t from,
	162	struct mtd_oob_ops *ops);
	163	int (write_oob) (struct mtd_info mtd, loff_t to,
	164	struct mtd_oob_ops *ops);
1da177e4	165
61ecfa87 TG	166	/*
61ecfa87 TG	167	* Methods to access the protection register area, present in some
1da177e4	168	* flash devices. The user data is one time programmable but the
61ecfa87	169	* factory data is read only.
1da177e4	170	*/
f77814dd	171	int (get_fact_prot_info) (struct mtd_info mtd, struct otp_info *buf, size_t len);
1da177e4	172	int (read_fact_prot_reg) (struct mtd_info mtd, loff_t from, size_t len, size_t retlen, u_char buf);
f77814dd NP	173	int (get_user_prot_info) (struct mtd_info mtd, struct otp_info *buf, size_t len);
f77814dd NP	174	int (read_user_prot_reg) (struct mtd_info mtd, loff_t from, size_t len, size_t retlen, u_char buf);
1da177e4	175	int (write_user_prot_reg) (struct mtd_info mtd, loff_t from, size_t len, size_t retlen, u_char buf);
f77814dd	176	int (lock_user_prot_reg) (struct mtd_info mtd, loff_t from, size_t len);
1da177e4	177
2528e8cd	178	/* kvec-based read/write methods.
61ecfa87	179	NB: The 'count' parameter is the number of _vectors_, each of
1da177e4 LT	180	which contains an (ofs, len) tuple.
1da177e4 LT	181	*/
1da177e4	182	int (writev) (struct mtd_info mtd, const struct kvec vecs, unsigned long count, loff_t to, size_t retlen);
1da177e4 LT	183
	184	/* Sync */
	185	void (sync) (struct mtd_info mtd);
	186
	187	/* Chip-supported device locking */
	188	int (lock) (struct mtd_info mtd, loff_t ofs, size_t len);
	189	int (unlock) (struct mtd_info mtd, loff_t ofs, size_t len);
	190
	191	/* Power Management functions */
	192	int (suspend) (struct mtd_info mtd);
	193	void (resume) (struct mtd_info mtd);
	194
	195	/* Bad block management functions */
	196	int (block_isbad) (struct mtd_info mtd, loff_t ofs);
	197	int (block_markbad) (struct mtd_info mtd, loff_t ofs);
	198
963a6fb0 NP	199	struct notifier_block reboot_notifier; /* default mode before reboot */
963a6fb0 NP	200
7fac4648 TG	201	/* ECC status information */
	202	struct mtd_ecc_stats ecc_stats;
	203
1da177e4 LT	204	void *priv;
	205
	206	struct module *owner;
	207	int usecount;
	208	};
	209
	210
	211	/* Kernel-side ioctl definitions */
	212
	213	extern int add_mtd_device(struct mtd_info *mtd);
	214	extern int del_mtd_device (struct mtd_info *mtd);
	215
	216	extern struct mtd_info get_mtd_device(struct mtd_info mtd, int num);
	217
	218	extern void put_mtd_device(struct mtd_info *mtd);
	219
	220
	221	struct mtd_notifier {
	222	void (add)(struct mtd_info mtd);
	223	void (remove)(struct mtd_info mtd);
	224	struct list_head list;
	225	};
	226
	227
	228	extern void register_mtd_user (struct mtd_notifier *new);
	229	extern int unregister_mtd_user (struct mtd_notifier *old);
	230
	231	int default_mtd_writev(struct mtd_info mtd, const struct kvec vecs,
	232	unsigned long count, loff_t to, size_t *retlen);
	233
	234	int default_mtd_readv(struct mtd_info mtd, struct kvec vecs,
	235	unsigned long count, loff_t from, size_t *retlen);
	236
1da177e4 LT	237	#ifdef CONFIG_MTD_PARTITIONS
	238	void mtd_erase_callback(struct erase_info *instr);
	239	#else
	240	static inline void mtd_erase_callback(struct erase_info *instr)
	241	{
	242	if (instr->callback)
	243	instr->callback(instr);
	244	}
	245	#endif
	246
	247	/*
	248	* Debugging macro and defines
	249	*/
	250	#define MTD_DEBUG_LEVEL0 (0) /* Quiet */
	251	#define MTD_DEBUG_LEVEL1 (1) /* Audible */
	252	#define MTD_DEBUG_LEVEL2 (2) /* Loud */
	253	#define MTD_DEBUG_LEVEL3 (3) /* Noisy */
	254
	255	#ifdef CONFIG_MTD_DEBUG
	256	#define DEBUG(n, args...) \
f4a43cfc	257	do { \
1da177e4 LT	258	if (n <= CONFIG_MTD_DEBUG_VERBOSE) \
	259	printk(KERN_INFO args); \
	260	} while(0)
	261	#else /* CONFIG_MTD_DEBUG */
	262	#define DEBUG(n, args...) do { } while(0)
	263
	264	#endif /* CONFIG_MTD_DEBUG */
	265
	266	#endif /* __MTD_MTD_H__ */