mtd.h 12.1 KB
Newer Older
1
/*
D
David Woodhouse 已提交
2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
 * Copyright © 1999-2010 David Woodhouse <dwmw2@infradead.org> et al.
 *
 * 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
 * (at your option) 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.
 *
 * 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 St, Fifth Floor, Boston, MA  02110-1301  USA
L
Linus Torvalds 已提交
17 18 19 20 21 22 23 24 25
 *
 */

#ifndef __MTD_MTD_H__
#define __MTD_MTD_H__

#include <linux/types.h>
#include <linux/module.h>
#include <linux/uio.h>
26
#include <linux/notifier.h>
D
David Brownell 已提交
27
#include <linux/device.h>
L
Linus Torvalds 已提交
28 29 30

#include <mtd/mtd-abi.h>

31 32
#include <asm/div64.h>

L
Linus Torvalds 已提交
33 34 35 36 37 38 39 40 41
#define MTD_CHAR_MAJOR 90
#define MTD_BLOCK_MAJOR 31

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

42
#define MTD_FAIL_ADDR_UNKNOWN -1LL
43

L
Linus Torvalds 已提交
44
/* If the erase fails, fail_addr might indicate exactly which block failed.  If
45
   fail_addr = MTD_FAIL_ADDR_UNKNOWN, the failure was not at the device level or was not
L
Linus Torvalds 已提交
46 47 48
   specific to any particular block. */
struct erase_info {
	struct mtd_info *mtd;
49 50 51
	uint64_t addr;
	uint64_t len;
	uint64_t fail_addr;
L
Linus Torvalds 已提交
52 53
	u_long time;
	u_long retries;
54 55
	unsigned dev;
	unsigned cell;
L
Linus Torvalds 已提交
56 57 58 59 60 61 62
	void (*callback) (struct erase_info *self);
	u_long priv;
	u_char state;
	struct erase_info *next;
};

struct mtd_erase_region_info {
63
	uint64_t offset;			/* At which this region starts, from the beginning of the MTD */
64 65
	uint32_t erasesize;		/* For this region */
	uint32_t numblocks;		/* Number of blocks of erasesize in this region */
66
	unsigned long *lockmap;		/* If keeping bitmap of locks */
L
Linus Torvalds 已提交
67 68
};

69 70 71 72 73 74
/*
 * 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
75
 * MTD_OOB_RAW:		mode to read oob and data without doing ECC checking
76 77 78 79 80 81 82 83 84 85 86
 */
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
 *
87
 * @len:	number of data bytes to write/read
88
 *
89
 * @retlen:	number of data bytes written/read
90
 *
91 92
 * @ooblen:	number of oob bytes to write/read
 * @oobretlen:	number of oob bytes written/read
93 94 95 96
 * @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
97
 *
98
 * Note, it is allowed to read more than one OOB area at one go, but not write.
99 100
 * The interface assumes that the OOB write requests program only one page's
 * OOB area.
101 102 103 104 105 106
 */
struct mtd_oob_ops {
	mtd_oob_mode_t	mode;
	size_t		len;
	size_t		retlen;
	size_t		ooblen;
107
	size_t		oobretlen;
108 109 110 111 112
	uint32_t	ooboffs;
	uint8_t		*datbuf;
	uint8_t		*oobbuf;
};

113 114 115
#define MTD_MAX_OOBFREE_ENTRIES_LARGE	32
#define MTD_MAX_ECCPOS_ENTRIES_LARGE	448
/*
116 117 118 119
 * Internal ECC layout control structure. For historical reasons, there is a
 * similar, smaller struct nand_ecclayout_user (in mtd-abi.h) that is retained
 * for export to user-space via the ECCGETLAYOUT ioctl.
 * nand_ecclayout should be expandable in the future simply by the above macros.
120 121 122 123 124 125 126 127
 */
struct nand_ecclayout {
	__u32 eccbytes;
	__u32 eccpos[MTD_MAX_ECCPOS_ENTRIES_LARGE];
	__u32 oobavail;
	struct nand_oobfree oobfree[MTD_MAX_OOBFREE_ENTRIES_LARGE];
};

L
Linus Torvalds 已提交
128 129
struct mtd_info {
	u_char type;
130
	uint32_t flags;
131
	uint64_t size;	 // Total size of the MTD
L
Linus Torvalds 已提交
132

133
	/* "Major" erase size for the device. Naïve users may take this
L
Linus Torvalds 已提交
134 135 136
	 * to be the only erase size available, or may use the more detailed
	 * information below if they desire
	 */
137
	uint32_t erasesize;
138 139 140 141 142 143
	/* 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.
J
Joern Engel 已提交
144
	 */
145
	uint32_t writesize;
L
Linus Torvalds 已提交
146

147 148 149 150 151 152 153 154 155 156 157
	/*
	 * Size of the write buffer used by the MTD. MTD devices having a write
	 * buffer can write multiple writesize chunks at a time. E.g. while
	 * writing 4 * writesize bytes to a device with 2 * writesize bytes
	 * buffer the MTD driver can (but doesn't have to) do 2 writesize
	 * operations, but not 4. Currently, all NANDs have writebufsize
	 * equivalent to writesize (NAND page size). Some NOR flashes do have
	 * writebufsize greater than writesize.
	 */
	uint32_t writebufsize;

158 159
	uint32_t oobsize;   // Amount of OOB data per block (e.g. 16)
	uint32_t oobavail;  // Available OOB bytes per block
L
Linus Torvalds 已提交
160

161 162 163 164 165 166 167 168 169
	/*
	 * If erasesize is a power of 2 then the shift is stored in
	 * erasesize_shift otherwise erasesize_shift is zero. Ditto writesize.
	 */
	unsigned int erasesize_shift;
	unsigned int writesize_shift;
	/* Masks based on erasesize_shift and writesize_shift */
	unsigned int erasesize_mask;
	unsigned int writesize_mask;
170

L
Linus Torvalds 已提交
171
	// Kernel-only stuff starts here.
172
	const char *name;
L
Linus Torvalds 已提交
173 174
	int index;

175 176
	/* ecc layout structure pointer - read only ! */
	struct nand_ecclayout *ecclayout;
L
Linus Torvalds 已提交
177 178

	/* Data for variable erase regions. If numeraseregions is zero,
179
	 * it means that the whole device has erasesize as given above.
L
Linus Torvalds 已提交
180 181
	 */
	int numeraseregions;
182
	struct mtd_erase_region_info *eraseregions;
L
Linus Torvalds 已提交
183

J
Jörn Engel 已提交
184 185 186 187 188 189 190
	/*
	 * Erase is an asynchronous operation.  Device drivers are supposed
	 * to call instr->callback() whenever the operation completes, even
	 * if it completes with a failure.
	 * Callers are supposed to pass a callback function and wait for it
	 * to be called before writing to the block.
	 */
L
Linus Torvalds 已提交
191 192 193
	int (*erase) (struct mtd_info *mtd, struct erase_info *instr);

	/* This stuff for eXecute-In-Place */
194 195 196
	/* phys is optional and may be set to NULL */
	int (*point) (struct mtd_info *mtd, loff_t from, size_t len,
			size_t *retlen, void **virt, resource_size_t *phys);
L
Linus Torvalds 已提交
197 198

	/* We probably shouldn't allow XIP if the unpoint isn't a NULL */
199
	void (*unpoint) (struct mtd_info *mtd, loff_t from, size_t len);
L
Linus Torvalds 已提交
200

201 202 203 204 205 206 207 208 209 210 211 212 213 214
	/* Allow NOMMU mmap() to directly map the device (if not NULL)
	 * - return the address to which the offset maps
	 * - return -ENOSYS to indicate refusal to do the mapping
	 */
	unsigned long (*get_unmapped_area) (struct mtd_info *mtd,
					    unsigned long len,
					    unsigned long offset,
					    unsigned long flags);

	/* Backing device capabilities for this device
	 * - provides mmap capabilities
	 */
	struct backing_dev_info *backing_dev_info;

L
Linus Torvalds 已提交
215 216 217 218

	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);

219 220 221 222 223 224 225 226 227
	/* In blackbox flight recorder like scenarios we want to make successful
	   writes in interrupt context. panic_write() is only intended to be
	   called when its known the kernel is about to panic and we need the
	   write to succeed. Since the kernel is not going to be running for much
	   longer, this function can break locks and delay to ensure the write
	   succeeds (but not sleep). */

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

228 229 230 231
	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);
L
Linus Torvalds 已提交
232

233 234
	/*
	 * Methods to access the protection register area, present in some
L
Linus Torvalds 已提交
235
	 * flash devices. The user data is one time programmable but the
236
	 * factory data is read only.
L
Linus Torvalds 已提交
237
	 */
238
	int (*get_fact_prot_info) (struct mtd_info *mtd, struct otp_info *buf, size_t len);
L
Linus Torvalds 已提交
239
	int (*read_fact_prot_reg) (struct mtd_info *mtd, loff_t from, size_t len, size_t *retlen, u_char *buf);
240 241
	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);
L
Linus Torvalds 已提交
242
	int (*write_user_prot_reg) (struct mtd_info *mtd, loff_t from, size_t len, size_t *retlen, u_char *buf);
243
	int (*lock_user_prot_reg) (struct mtd_info *mtd, loff_t from, size_t len);
L
Linus Torvalds 已提交
244

T
Thomas Gleixner 已提交
245
	/* kvec-based read/write methods.
246
	   NB: The 'count' parameter is the number of _vectors_, each of
L
Linus Torvalds 已提交
247 248 249 250 251 252 253 254
	   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 */
255 256
	int (*lock) (struct mtd_info *mtd, loff_t ofs, uint64_t len);
	int (*unlock) (struct mtd_info *mtd, loff_t ofs, uint64_t len);
257
	int (*is_locked) (struct mtd_info *mtd, loff_t ofs, uint64_t len);
L
Linus Torvalds 已提交
258 259 260 261 262 263 264 265 266

	/* 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);

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

269 270
	/* ECC status information */
	struct mtd_ecc_stats ecc_stats;
271 272
	/* Subpage shift (NAND) */
	int subpage_sft;
273

L
Linus Torvalds 已提交
274 275 276
	void *priv;

	struct module *owner;
D
David Brownell 已提交
277
	struct device dev;
L
Linus Torvalds 已提交
278
	int usecount;
A
Artem Bityutskiy 已提交
279 280 281 282 283 284 285

	/* If the driver is something smart, like UBI, it may need to maintain
	 * its own reference counting. The below functions are only for driver.
	 * The driver may register its callbacks. These callbacks are not
	 * supposed to be called by MTD users */
	int (*get_device) (struct mtd_info *mtd);
	void (*put_device) (struct mtd_info *mtd);
L
Linus Torvalds 已提交
286 287
};

D
David Brownell 已提交
288 289
static inline struct mtd_info *dev_to_mtd(struct device *dev)
{
290
	return dev ? dev_get_drvdata(dev) : NULL;
D
David Brownell 已提交
291 292
}

293
static inline uint32_t mtd_div_by_eb(uint64_t sz, struct mtd_info *mtd)
294 295 296 297 298 299 300
{
	if (mtd->erasesize_shift)
		return sz >> mtd->erasesize_shift;
	do_div(sz, mtd->erasesize);
	return sz;
}

301
static inline uint32_t mtd_mod_by_eb(uint64_t sz, struct mtd_info *mtd)
302 303 304 305 306 307
{
	if (mtd->erasesize_shift)
		return sz & mtd->erasesize_mask;
	return do_div(sz, mtd->erasesize);
}

308
static inline uint32_t mtd_div_by_ws(uint64_t sz, struct mtd_info *mtd)
309 310 311 312 313 314 315
{
	if (mtd->writesize_shift)
		return sz >> mtd->writesize_shift;
	do_div(sz, mtd->writesize);
	return sz;
}

316
static inline uint32_t mtd_mod_by_ws(uint64_t sz, struct mtd_info *mtd)
317 318 319 320 321
{
	if (mtd->writesize_shift)
		return sz & mtd->writesize_mask;
	return do_div(sz, mtd->writesize);
}
L
Linus Torvalds 已提交
322 323 324

	/* Kernel-side ioctl definitions */

325 326 327 328 329 330
struct mtd_partition;

extern int mtd_device_register(struct mtd_info *master,
			       const struct mtd_partition *parts,
			       int nr_parts);
extern int mtd_device_unregister(struct mtd_info *master);
L
Linus Torvalds 已提交
331
extern struct mtd_info *get_mtd_device(struct mtd_info *mtd, int num);
332 333
extern int __get_mtd_device(struct mtd_info *mtd);
extern void __put_mtd_device(struct mtd_info *mtd);
334
extern struct mtd_info *get_mtd_device_nm(const char *name);
L
Linus Torvalds 已提交
335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353
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);

354 355
void *mtd_kmalloc_up_to(const struct mtd_info *mtd, size_t *size);

L
Linus Torvalds 已提交
356 357 358 359 360 361 362 363 364 365 366 367
void mtd_erase_callback(struct erase_info *instr);

/*
 * 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...)				\
368
	do {						\
L
Linus Torvalds 已提交
369 370 371 372
		if (n <= CONFIG_MTD_DEBUG_VERBOSE)	\
			printk(KERN_INFO args);		\
	} while(0)
#else /* CONFIG_MTD_DEBUG */
373 374 375 376 377
#define DEBUG(n, args...)				\
	do {						\
		if (0)					\
			printk(KERN_INFO args);		\
	} while(0)
L
Linus Torvalds 已提交
378 379 380 381

#endif /* CONFIG_MTD_DEBUG */

#endif /* __MTD_MTD_H__ */