include/linux/mtd/mtd.h

   1 /*
   2  * Copyright (C) 1999-2003 David Woodhouse <dwmw2@infradead.org> et al.
   3  *
   4  * Released under GPL
   5  */
   6
   7 #ifndef __MTD_MTD_H__
   8 #define __MTD_MTD_H__
   9
  10 #include <linux/types.h>
  11 #include <div64.h>
  12 #include <mtd/mtd-abi.h>
  13 #include <asm/errno.h>
  14
  15 #define MTD_CHAR_MAJOR 90
  16 #define MTD_BLOCK_MAJOR 31
  17 #define MAX_MTD_DEVICES 32
  18
  19 #define MTD_ERASE_PENDING       0x01
  20 #define MTD_ERASING             0x02
  21 #define MTD_ERASE_SUSPEND       0x04
  22 #define MTD_ERASE_DONE          0x08
  23 #define MTD_ERASE_FAILED        0x10
  24
  25 #define MTD_FAIL_ADDR_UNKNOWN   -1LL
  26
  27 /*
  28  * Enumeration for NAND/OneNAND flash chip state
  29  */
  30 enum {
  31         FL_READY,
  32         FL_READING,
  33         FL_WRITING,
  34         FL_ERASING,
  35         FL_SYNCING,
  36         FL_CACHEDPRG,
  37         FL_RESETING,
  38         FL_UNLOCKING,
  39         FL_LOCKING,
  40         FL_PM_SUSPENDED,
  41 };
  42
  43 /* If the erase fails, fail_addr might indicate exactly which block failed.  If
  44    fail_addr = MTD_FAIL_ADDR_UNKNOWN, the failure was not at the device level or was not
  45    specific to any particular block. */
  46 struct erase_info {
  47         struct mtd_info *mtd;
  48         uint64_t addr;
  49         uint64_t len;
  50         uint64_t fail_addr;
  51         u_long time;
  52         u_long retries;
  53         u_int dev;
  54         u_int cell;
  55         void (*callback) (struct erase_info *self);
  56         u_long priv;
  57         u_char state;
  58         struct erase_info *next;
  59         int scrub;
  60 };
  61
  62 struct mtd_erase_region_info {
  63         uint64_t offset;                        /* At which this region starts, from the beginning of the MTD */
  64         u_int32_t erasesize;            /* For this region */
  65         u_int32_t numblocks;            /* Number of blocks of erasesize in this region */
  66         unsigned long *lockmap;         /* If keeping bitmap of locks */
  67 };
  68
  69 /**
  70  * struct mtd_oob_ops - oob operation operands
  71  * @mode:       operation mode
  72  *
  73  * @len:        number of data bytes to write/read
  74  *
  75  * @retlen:     number of data bytes written/read
  76  *
  77  * @ooblen:     number of oob bytes to write/read
  78  * @oobretlen:  number of oob bytes written/read
  79  * @ooboffs:    offset of oob data in the oob area (only relevant when
  80  *              mode = MTD_OPS_PLACE_OOB or MTD_OPS_RAW)
  81  * @datbuf:     data buffer - if NULL only oob data are read/written
  82  * @oobbuf:     oob data buffer
  83  *
  84  * Note, it is allowed to read more then one OOB area at one go, but not write.
  85  * The interface assumes that the OOB write requests program only one page's
  86  * OOB area.
  87  */
  88 struct mtd_oob_ops {
  89         unsigned int    mode;
  90         size_t          len;
  91         size_t          retlen;
  92         size_t          ooblen;
  93         size_t          oobretlen;
  94         uint32_t        ooboffs;
  95         uint8_t         *datbuf;
  96         uint8_t         *oobbuf;
  97 };
  98
  99 #ifdef CONFIG_SYS_NAND_MAX_OOBFREE
 100 #define MTD_MAX_OOBFREE_ENTRIES_LARGE   CONFIG_SYS_NAND_MAX_OOBFREE
 101 #else
 102 #define MTD_MAX_OOBFREE_ENTRIES_LARGE   32
 103 #endif
 104
 105 #ifdef CONFIG_SYS_NAND_MAX_ECCPOS
 106 #define MTD_MAX_ECCPOS_ENTRIES_LARGE    CONFIG_SYS_NAND_MAX_ECCPOS
 107 #else
 108 #define MTD_MAX_ECCPOS_ENTRIES_LARGE    640
 109 #endif
 110
 111 /*
 112  * ECC layout control structure. Exported to userspace for
 113  * diagnosis and to allow creation of raw images
 114  */
 115 struct nand_ecclayout {
 116         uint32_t eccbytes;
 117         uint32_t eccpos[MTD_MAX_ECCPOS_ENTRIES_LARGE];
 118         uint32_t oobavail;
 119         struct nand_oobfree oobfree[MTD_MAX_OOBFREE_ENTRIES_LARGE];
 120 };
 121
 122 struct mtd_info {
 123         u_char type;
 124         u_int32_t flags;
 125         uint64_t size;   /* Total size of the MTD */
 126
 127         /* "Major" erase size for the device. Naïve users may take this
 128          * to be the only erase size available, or may use the more detailed
 129          * information below if they desire
 130          */
 131         u_int32_t erasesize;
 132         /* Minimal writable flash unit size. In case of NOR flash it is 1 (even
 133          * though individual bits can be cleared), in case of NAND flash it is
 134          * one NAND page (or half, or one-fourths of it), in case of ECC-ed NOR
 135          * it is of ECC block size, etc. It is illegal to have writesize = 0.
 136          * Any driver registering a struct mtd_info must ensure a writesize of
 137          * 1 or larger.
 138          */
 139         u_int32_t writesize;
 140
 141         u_int32_t oobsize;   /* Amount of OOB data per block (e.g. 16) */
 142         u_int32_t oobavail;  /* Available OOB bytes per block */
 143
 144         /*
 145          * read ops return -EUCLEAN if max number of bitflips corrected on any
 146          * one region comprising an ecc step equals or exceeds this value.
 147          * Settable by driver, else defaults to ecc_strength.  User can override
 148          * in sysfs.  N.B. The meaning of the -EUCLEAN return code has changed;
 149          * see Documentation/ABI/testing/sysfs-class-mtd for more detail.
 150          */
 151         unsigned int bitflip_threshold;
 152
 153         /* Kernel-only stuff starts here. */
 154         const char *name;
 155         int index;
 156
 157         /* ECC layout structure pointer - read only! */
 158         struct nand_ecclayout *ecclayout;
 159
 160         /* max number of correctible bit errors per ecc step */
 161         unsigned int ecc_strength;
 162
 163         /* Data for variable erase regions. If numeraseregions is zero,
 164          * it means that the whole device has erasesize as given above.
 165          */
 166         int numeraseregions;
 167         struct mtd_erase_region_info *eraseregions;
 168
 169         /*
 170          * Do not call via these pointers, use corresponding mtd_*()
 171          * wrappers instead.
 172          */
 173         int (*_erase) (struct mtd_info *mtd, struct erase_info *instr);
 174         int (*_point) (struct mtd_info *mtd, loff_t from, size_t len,
 175                         size_t *retlen, void **virt, phys_addr_t *phys);
 176         void (*_unpoint) (struct mtd_info *mtd, loff_t from, size_t len);
 177         int (*_read) (struct mtd_info *mtd, loff_t from, size_t len,
 178                      size_t *retlen, u_char *buf);
 179         int (*_write) (struct mtd_info *mtd, loff_t to, size_t len,
 180                       size_t *retlen, const u_char *buf);
 181
 182         /* In blackbox flight recorder like scenarios we want to make successful
 183            writes in interrupt context. panic_write() is only intended to be
 184            called when its known the kernel is about to panic and we need the
 185            write to succeed. Since the kernel is not going to be running for much
 186            longer, this function can break locks and delay to ensure the write
 187            succeeds (but not sleep). */
 188
 189         int (*_panic_write) (struct mtd_info *mtd, loff_t to, size_t len, size_t *retlen, const u_char *buf);
 190
 191         int (*_read_oob) (struct mtd_info *mtd, loff_t from,
 192                          struct mtd_oob_ops *ops);
 193         int (*_write_oob) (struct mtd_info *mtd, loff_t to,
 194                          struct mtd_oob_ops *ops);
 195         int (*_get_fact_prot_info) (struct mtd_info *mtd, struct otp_info *buf,
 196                                    size_t len);
 197         int (*_read_fact_prot_reg) (struct mtd_info *mtd, loff_t from,
 198                                    size_t len, size_t *retlen, u_char *buf);
 199         int (*_get_user_prot_info) (struct mtd_info *mtd, struct otp_info *buf,
 200                                    size_t len);
 201         int (*_read_user_prot_reg) (struct mtd_info *mtd, loff_t from,
 202                                    size_t len, size_t *retlen, u_char *buf);
 203         int (*_write_user_prot_reg) (struct mtd_info *mtd, loff_t to, size_t len,
 204                                     size_t *retlen, u_char *buf);
 205         int (*_lock_user_prot_reg) (struct mtd_info *mtd, loff_t from,
 206                                    size_t len);
 207         void (*_sync) (struct mtd_info *mtd);
 208         int (*_lock) (struct mtd_info *mtd, loff_t ofs, uint64_t len);
 209         int (*_unlock) (struct mtd_info *mtd, loff_t ofs, uint64_t len);
 210         int (*_block_isbad) (struct mtd_info *mtd, loff_t ofs);
 211         int (*_block_markbad) (struct mtd_info *mtd, loff_t ofs);
 212         /*
 213          * If the driver is something smart, like UBI, it may need to maintain
 214          * its own reference counting. The below functions are only for driver.
 215          */
 216         int (*_get_device) (struct mtd_info *mtd);
 217         void (*_put_device) (struct mtd_info *mtd);
 218
 219 /* XXX U-BOOT XXX */
 220 #if 0
 221         /* kvec-based read/write methods.
 222            NB: The 'count' parameter is the number of _vectors_, each of
 223            which contains an (ofs, len) tuple.
 224         */
 225         int (*writev) (struct mtd_info *mtd, const struct kvec *vecs, unsigned long count, loff_t to, size_t *retlen);
 226 #endif
 227 /* XXX U-BOOT XXX */
 228 #if 0
 229         struct notifier_block reboot_notifier;  /* default mode before reboot */
 230 #endif
 231
 232         /* ECC status information */
 233         struct mtd_ecc_stats ecc_stats;
 234         /* Subpage shift (NAND) */
 235         int subpage_sft;
 236
 237         void *priv;
 238
 239         struct module *owner;
 240         int usecount;
 241 };
 242
 243 int mtd_erase(struct mtd_info *mtd, struct erase_info *instr);
 244 int mtd_read(struct mtd_info *mtd, loff_t from, size_t len, size_t *retlen,
 245              u_char *buf);
 246 int mtd_write(struct mtd_info *mtd, loff_t to, size_t len, size_t *retlen,
 247               const u_char *buf);
 248 int mtd_panic_write(struct mtd_info *mtd, loff_t to, size_t len, size_t *retlen,
 249                     const u_char *buf);
 250
 251 int mtd_read_oob(struct mtd_info *mtd, loff_t from, struct mtd_oob_ops *ops);
 252
 253 static inline int mtd_write_oob(struct mtd_info *mtd, loff_t to,
 254                                 struct mtd_oob_ops *ops)
 255 {
 256         ops->retlen = ops->oobretlen = 0;
 257         if (!mtd->_write_oob)
 258                 return -EOPNOTSUPP;
 259         if (!(mtd->flags & MTD_WRITEABLE))
 260                 return -EROFS;
 261         return mtd->_write_oob(mtd, to, ops);
 262 }
 263
 264 int mtd_get_fact_prot_info(struct mtd_info *mtd, struct otp_info *buf,
 265                            size_t len);
 266 int mtd_read_fact_prot_reg(struct mtd_info *mtd, loff_t from, size_t len,
 267                            size_t *retlen, u_char *buf);
 268 int mtd_get_user_prot_info(struct mtd_info *mtd, struct otp_info *buf,
 269                            size_t len);
 270 int mtd_read_user_prot_reg(struct mtd_info *mtd, loff_t from, size_t len,
 271                            size_t *retlen, u_char *buf);
 272 int mtd_write_user_prot_reg(struct mtd_info *mtd, loff_t to, size_t len,
 273                             size_t *retlen, u_char *buf);
 274 int mtd_lock_user_prot_reg(struct mtd_info *mtd, loff_t from, size_t len);
 275
 276 /* XXX U-BOOT XXX */
 277 #if 0
 278 int mtd_writev(struct mtd_info *mtd, const struct kvec *vecs,
 279                unsigned long count, loff_t to, size_t *retlen);
 280 #endif
 281
 282 static inline void mtd_sync(struct mtd_info *mtd)
 283 {
 284         if (mtd->_sync)
 285                 mtd->_sync(mtd);
 286 }
 287
 288 int mtd_lock(struct mtd_info *mtd, loff_t ofs, uint64_t len);
 289 int mtd_unlock(struct mtd_info *mtd, loff_t ofs, uint64_t len);
 290 int mtd_is_locked(struct mtd_info *mtd, loff_t ofs, uint64_t len);
 291 int mtd_block_isbad(struct mtd_info *mtd, loff_t ofs);
 292 int mtd_block_markbad(struct mtd_info *mtd, loff_t ofs);
 293
 294 static inline uint32_t mtd_div_by_eb(uint64_t sz, struct mtd_info *mtd)
 295 {
 296         do_div(sz, mtd->erasesize);
 297         return sz;
 298 }
 299
 300 static inline uint32_t mtd_mod_by_eb(uint64_t sz, struct mtd_info *mtd)
 301 {
 302         return do_div(sz, mtd->erasesize);
 303 }
 304
 305 static inline int mtd_has_oob(const struct mtd_info *mtd)
 306 {
 307         return mtd->_read_oob && mtd->_write_oob;
 308 }
 309
 310 static inline int mtd_can_have_bb(const struct mtd_info *mtd)
 311 {
 312         return !!mtd->_block_isbad;
 313 }
 314
 315         /* Kernel-side ioctl definitions */
 316
 317 extern int add_mtd_device(struct mtd_info *mtd);
 318 extern int del_mtd_device (struct mtd_info *mtd);
 319
 320 extern struct mtd_info *get_mtd_device(struct mtd_info *mtd, int num);
 321 extern struct mtd_info *get_mtd_device_nm(const char *name);
 322
 323 extern void put_mtd_device(struct mtd_info *mtd);
 324 extern void mtd_get_len_incl_bad(struct mtd_info *mtd, uint64_t offset,
 325                                  const uint64_t length, uint64_t *len_incl_bad,
 326                                  int *truncated);
 327 /* XXX U-BOOT XXX */
 328 #if 0
 329 struct mtd_notifier {
 330         void (*add)(struct mtd_info *mtd);
 331         void (*remove)(struct mtd_info *mtd);
 332         struct list_head list;
 333 };
 334
 335 extern void register_mtd_user (struct mtd_notifier *new);
 336 extern int unregister_mtd_user (struct mtd_notifier *old);
 337 #endif
 338
 339 #ifdef CONFIG_MTD_PARTITIONS
 340 void mtd_erase_callback(struct erase_info *instr);
 341 #else
 342 static inline void mtd_erase_callback(struct erase_info *instr)
 343 {
 344         if (instr->callback)
 345                 instr->callback(instr);
 346 }
 347 #endif
 348
 349 /*
 350  * Debugging macro and defines
 351  */
 352 #define MTD_DEBUG_LEVEL0        (0)     /* Quiet   */
 353 #define MTD_DEBUG_LEVEL1        (1)     /* Audible */
 354 #define MTD_DEBUG_LEVEL2        (2)     /* Loud    */
 355 #define MTD_DEBUG_LEVEL3        (3)     /* Noisy   */
 356
 357 #ifdef CONFIG_MTD_DEBUG
 358 #define pr_debug(args...)       MTDDEBUG(MTD_DEBUG_LEVEL0, args)
 359 #define MTDDEBUG(n, args...)                            \
 360         do {                                            \
 361                 if (n <= CONFIG_MTD_DEBUG_VERBOSE)      \
 362                         printk(KERN_INFO args);         \
 363         } while(0)
 364 #else /* CONFIG_MTD_DEBUG */
 365 #define pr_debug(args...)
 366 #define MTDDEBUG(n, args...)                            \
 367         do {                                            \
 368                 if (0)                                  \
 369                         printk(KERN_INFO args);         \
 370         } while(0)
 371 #endif /* CONFIG_MTD_DEBUG */
 372 #define pr_info(args...)        MTDDEBUG(MTD_DEBUG_LEVEL0, args)
 373 #define pr_warn(args...)        MTDDEBUG(MTD_DEBUG_LEVEL0, args)
 374 #define pr_err(args...)         MTDDEBUG(MTD_DEBUG_LEVEL0, args)
 375
 376 static inline int mtd_is_bitflip(int err) {
 377         return err == -EUCLEAN;
 378 }
 379
 380 static inline int mtd_is_eccerr(int err) {
 381         return err == -EBADMSG;
 382 }
 383
 384 static inline int mtd_is_bitflip_or_eccerr(int err) {
 385         return mtd_is_bitflip(err) || mtd_is_eccerr(err);
 386 }
 387
 388 #endif /* __MTD_MTD_H__ */