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 struct mtd_info {
 100         u_char type;
 101         u_int32_t flags;
 102         uint64_t size;   /* Total size of the MTD */
 103
 104         /* "Major" erase size for the device. Naïve users may take this
 105          * to be the only erase size available, or may use the more detailed
 106          * information below if they desire
 107          */
 108         u_int32_t erasesize;
 109         /* Minimal writable flash unit size. In case of NOR flash it is 1 (even
 110          * though individual bits can be cleared), in case of NAND flash it is
 111          * one NAND page (or half, or one-fourths of it), in case of ECC-ed NOR
 112          * it is of ECC block size, etc. It is illegal to have writesize = 0.
 113          * Any driver registering a struct mtd_info must ensure a writesize of
 114          * 1 or larger.
 115          */
 116         u_int32_t writesize;
 117
 118         u_int32_t oobsize;   /* Amount of OOB data per block (e.g. 16) */
 119         u_int32_t oobavail;  /* Available OOB bytes per block */
 120
 121         /*
 122          * read ops return -EUCLEAN if max number of bitflips corrected on any
 123          * one region comprising an ecc step equals or exceeds this value.
 124          * Settable by driver, else defaults to ecc_strength.  User can override
 125          * in sysfs.  N.B. The meaning of the -EUCLEAN return code has changed;
 126          * see Documentation/ABI/testing/sysfs-class-mtd for more detail.
 127          */
 128         unsigned int bitflip_threshold;
 129
 130         /* Kernel-only stuff starts here. */
 131         const char *name;
 132         int index;
 133
 134         /* ECC layout structure pointer - read only! */
 135         struct nand_ecclayout *ecclayout;
 136
 137         /* max number of correctible bit errors per ecc step */
 138         unsigned int ecc_strength;
 139
 140         /* Data for variable erase regions. If numeraseregions is zero,
 141          * it means that the whole device has erasesize as given above.
 142          */
 143         int numeraseregions;
 144         struct mtd_erase_region_info *eraseregions;
 145
 146         /*
 147          * Do not call via these pointers, use corresponding mtd_*()
 148          * wrappers instead.
 149          */
 150         int (*_erase) (struct mtd_info *mtd, struct erase_info *instr);
 151         int (*_point) (struct mtd_info *mtd, loff_t from, size_t len,
 152                         size_t *retlen, void **virt, phys_addr_t *phys);
 153         void (*_unpoint) (struct mtd_info *mtd, loff_t from, size_t len);
 154         int (*_read) (struct mtd_info *mtd, loff_t from, size_t len,
 155                      size_t *retlen, u_char *buf);
 156         int (*_write) (struct mtd_info *mtd, loff_t to, size_t len,
 157                       size_t *retlen, const u_char *buf);
 158
 159         /* In blackbox flight recorder like scenarios we want to make successful
 160            writes in interrupt context. panic_write() is only intended to be
 161            called when its known the kernel is about to panic and we need the
 162            write to succeed. Since the kernel is not going to be running for much
 163            longer, this function can break locks and delay to ensure the write
 164            succeeds (but not sleep). */
 165
 166         int (*_panic_write) (struct mtd_info *mtd, loff_t to, size_t len, size_t *retlen, const u_char *buf);
 167
 168         int (*_read_oob) (struct mtd_info *mtd, loff_t from,
 169                          struct mtd_oob_ops *ops);
 170         int (*_write_oob) (struct mtd_info *mtd, loff_t to,
 171                          struct mtd_oob_ops *ops);
 172         int (*_get_fact_prot_info) (struct mtd_info *mtd, struct otp_info *buf,
 173                                    size_t len);
 174         int (*_read_fact_prot_reg) (struct mtd_info *mtd, loff_t from,
 175                                    size_t len, size_t *retlen, u_char *buf);
 176         int (*_get_user_prot_info) (struct mtd_info *mtd, struct otp_info *buf,
 177                                    size_t len);
 178         int (*_read_user_prot_reg) (struct mtd_info *mtd, loff_t from,
 179                                    size_t len, size_t *retlen, u_char *buf);
 180         int (*_write_user_prot_reg) (struct mtd_info *mtd, loff_t to, size_t len,
 181                                     size_t *retlen, u_char *buf);
 182         int (*_lock_user_prot_reg) (struct mtd_info *mtd, loff_t from,
 183                                    size_t len);
 184         void (*_sync) (struct mtd_info *mtd);
 185         int (*_lock) (struct mtd_info *mtd, loff_t ofs, uint64_t len);
 186         int (*_unlock) (struct mtd_info *mtd, loff_t ofs, uint64_t len);
 187         int (*_block_isbad) (struct mtd_info *mtd, loff_t ofs);
 188         int (*_block_markbad) (struct mtd_info *mtd, loff_t ofs);
 189         /*
 190          * If the driver is something smart, like UBI, it may need to maintain
 191          * its own reference counting. The below functions are only for driver.
 192          */
 193         int (*_get_device) (struct mtd_info *mtd);
 194         void (*_put_device) (struct mtd_info *mtd);
 195
 196 /* XXX U-BOOT XXX */
 197 #if 0
 198         /* kvec-based read/write methods.
 199            NB: The 'count' parameter is the number of _vectors_, each of
 200            which contains an (ofs, len) tuple.
 201         */
 202         int (*writev) (struct mtd_info *mtd, const struct kvec *vecs, unsigned long count, loff_t to, size_t *retlen);
 203 #endif
 204 /* XXX U-BOOT XXX */
 205 #if 0
 206         struct notifier_block reboot_notifier;  /* default mode before reboot */
 207 #endif
 208
 209         /* ECC status information */
 210         struct mtd_ecc_stats ecc_stats;
 211         /* Subpage shift (NAND) */
 212         int subpage_sft;
 213
 214         void *priv;
 215
 216         struct module *owner;
 217         int usecount;
 218 };
 219
 220 int mtd_erase(struct mtd_info *mtd, struct erase_info *instr);
 221 int mtd_read(struct mtd_info *mtd, loff_t from, size_t len, size_t *retlen,
 222              u_char *buf);
 223 int mtd_write(struct mtd_info *mtd, loff_t to, size_t len, size_t *retlen,
 224               const u_char *buf);
 225 int mtd_panic_write(struct mtd_info *mtd, loff_t to, size_t len, size_t *retlen,
 226                     const u_char *buf);
 227
 228 int mtd_read_oob(struct mtd_info *mtd, loff_t from, struct mtd_oob_ops *ops);
 229
 230 static inline int mtd_write_oob(struct mtd_info *mtd, loff_t to,
 231                                 struct mtd_oob_ops *ops)
 232 {
 233         ops->retlen = ops->oobretlen = 0;
 234         if (!mtd->_write_oob)
 235                 return -EOPNOTSUPP;
 236         if (!(mtd->flags & MTD_WRITEABLE))
 237                 return -EROFS;
 238         return mtd->_write_oob(mtd, to, ops);
 239 }
 240
 241 int mtd_get_fact_prot_info(struct mtd_info *mtd, struct otp_info *buf,
 242                            size_t len);
 243 int mtd_read_fact_prot_reg(struct mtd_info *mtd, loff_t from, size_t len,
 244                            size_t *retlen, u_char *buf);
 245 int mtd_get_user_prot_info(struct mtd_info *mtd, struct otp_info *buf,
 246                            size_t len);
 247 int mtd_read_user_prot_reg(struct mtd_info *mtd, loff_t from, size_t len,
 248                            size_t *retlen, u_char *buf);
 249 int mtd_write_user_prot_reg(struct mtd_info *mtd, loff_t to, size_t len,
 250                             size_t *retlen, u_char *buf);
 251 int mtd_lock_user_prot_reg(struct mtd_info *mtd, loff_t from, size_t len);
 252
 253 /* XXX U-BOOT XXX */
 254 #if 0
 255 int mtd_writev(struct mtd_info *mtd, const struct kvec *vecs,
 256                unsigned long count, loff_t to, size_t *retlen);
 257 #endif
 258
 259 static inline void mtd_sync(struct mtd_info *mtd)
 260 {
 261         if (mtd->_sync)
 262                 mtd->_sync(mtd);
 263 }
 264
 265 int mtd_lock(struct mtd_info *mtd, loff_t ofs, uint64_t len);
 266 int mtd_unlock(struct mtd_info *mtd, loff_t ofs, uint64_t len);
 267 int mtd_is_locked(struct mtd_info *mtd, loff_t ofs, uint64_t len);
 268 int mtd_block_isbad(struct mtd_info *mtd, loff_t ofs);
 269 int mtd_block_markbad(struct mtd_info *mtd, loff_t ofs);
 270
 271 static inline uint32_t mtd_div_by_eb(uint64_t sz, struct mtd_info *mtd)
 272 {
 273         do_div(sz, mtd->erasesize);
 274         return sz;
 275 }
 276
 277 static inline uint32_t mtd_mod_by_eb(uint64_t sz, struct mtd_info *mtd)
 278 {
 279         return do_div(sz, mtd->erasesize);
 280 }
 281
 282 static inline int mtd_has_oob(const struct mtd_info *mtd)
 283 {
 284         return mtd->_read_oob && mtd->_write_oob;
 285 }
 286
 287 static inline int mtd_can_have_bb(const struct mtd_info *mtd)
 288 {
 289         return !!mtd->_block_isbad;
 290 }
 291
 292         /* Kernel-side ioctl definitions */
 293
 294 extern int add_mtd_device(struct mtd_info *mtd);
 295 extern int del_mtd_device (struct mtd_info *mtd);
 296
 297 extern struct mtd_info *get_mtd_device(struct mtd_info *mtd, int num);
 298 extern struct mtd_info *get_mtd_device_nm(const char *name);
 299
 300 extern void put_mtd_device(struct mtd_info *mtd);
 301 extern void mtd_get_len_incl_bad(struct mtd_info *mtd, uint64_t offset,
 302                                  const uint64_t length, uint64_t *len_incl_bad,
 303                                  int *truncated);
 304 /* XXX U-BOOT XXX */
 305 #if 0
 306 struct mtd_notifier {
 307         void (*add)(struct mtd_info *mtd);
 308         void (*remove)(struct mtd_info *mtd);
 309         struct list_head list;
 310 };
 311
 312 extern void register_mtd_user (struct mtd_notifier *new);
 313 extern int unregister_mtd_user (struct mtd_notifier *old);
 314 #endif
 315
 316 #ifdef CONFIG_MTD_PARTITIONS
 317 void mtd_erase_callback(struct erase_info *instr);
 318 #else
 319 static inline void mtd_erase_callback(struct erase_info *instr)
 320 {
 321         if (instr->callback)
 322                 instr->callback(instr);
 323 }
 324 #endif
 325
 326 /*
 327  * Debugging macro and defines
 328  */
 329 #define MTD_DEBUG_LEVEL0        (0)     /* Quiet   */
 330 #define MTD_DEBUG_LEVEL1        (1)     /* Audible */
 331 #define MTD_DEBUG_LEVEL2        (2)     /* Loud    */
 332 #define MTD_DEBUG_LEVEL3        (3)     /* Noisy   */
 333
 334 #ifdef CONFIG_MTD_DEBUG
 335 #define pr_debug(args...)       MTDDEBUG(MTD_DEBUG_LEVEL0, args)
 336 #define MTDDEBUG(n, args...)                            \
 337         do {                                            \
 338                 if (n <= CONFIG_MTD_DEBUG_VERBOSE)      \
 339                         printk(KERN_INFO args);         \
 340         } while(0)
 341 #else /* CONFIG_MTD_DEBUG */
 342 #define pr_debug(args...)
 343 #define MTDDEBUG(n, args...)                            \
 344         do {                                            \
 345                 if (0)                                  \
 346                         printk(KERN_INFO args);         \
 347         } while(0)
 348 #endif /* CONFIG_MTD_DEBUG */
 349 #define pr_info(args...)        MTDDEBUG(MTD_DEBUG_LEVEL0, args)
 350 #define pr_warn(args...)        MTDDEBUG(MTD_DEBUG_LEVEL0, args)
 351 #define pr_err(args...)         MTDDEBUG(MTD_DEBUG_LEVEL0, args)
 352
 353 static inline int mtd_is_bitflip(int err) {
 354         return err == -EUCLEAN;
 355 }
 356
 357 static inline int mtd_is_eccerr(int err) {
 358         return err == -EBADMSG;
 359 }
 360
 361 static inline int mtd_is_bitflip_or_eccerr(int err) {
 362         return mtd_is_bitflip(err) || mtd_is_eccerr(err);
 363 }
 364
 365 #endif /* __MTD_MTD_H__ */