[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/config.h>
#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 16

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