include/linux/mtd/rawnand.h

   1 /*
   2  *  Copyright © 2000-2010 David Woodhouse <dwmw2@infradead.org>
   3  *                        Steven J. Hill <sjhill@realitydiluted.com>
   4  *                        Thomas Gleixner <tglx@linutronix.de>
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License version 2 as
   8  * published by the Free Software Foundation.
   9  *
  10  * Info:
  11  *      Contains standard defines and IDs for NAND flash devices
  12  *
  13  * Changelog:
  14  *      See git changelog.
  15  */
  16 #ifndef __LINUX_MTD_RAWNAND_H
  17 #define __LINUX_MTD_RAWNAND_H
  18
  19 #include <linux/wait.h>
  20 #include <linux/spinlock.h>
  21 #include <linux/mtd/mtd.h>
  22 #include <linux/mtd/flashchip.h>
  23 #include <linux/mtd/bbm.h>
  24 #include <linux/mtd/jedec.h>
  25 #include <linux/mtd/onfi.h>
  26 #include <linux/of.h>
  27 #include <linux/types.h>
  28
  29 struct nand_chip;
  30
  31 /* The maximum number of NAND chips in an array */
  32 #define NAND_MAX_CHIPS          8
  33
  34 /*
  35  * Constants for hardware specific CLE/ALE/NCE function
  36  *
  37  * These are bits which can be or'ed to set/clear multiple
  38  * bits in one go.
  39  */
  40 /* Select the chip by setting nCE to low */
  41 #define NAND_NCE                0x01
  42 /* Select the command latch by setting CLE to high */
  43 #define NAND_CLE                0x02
  44 /* Select the address latch by setting ALE to high */
  45 #define NAND_ALE                0x04
  46
  47 #define NAND_CTRL_CLE           (NAND_NCE | NAND_CLE)
  48 #define NAND_CTRL_ALE           (NAND_NCE | NAND_ALE)
  49 #define NAND_CTRL_CHANGE        0x80
  50
  51 /*
  52  * Standard NAND flash commands
  53  */
  54 #define NAND_CMD_READ0          0
  55 #define NAND_CMD_READ1          1
  56 #define NAND_CMD_RNDOUT         5
  57 #define NAND_CMD_PAGEPROG       0x10
  58 #define NAND_CMD_READOOB        0x50
  59 #define NAND_CMD_ERASE1         0x60
  60 #define NAND_CMD_STATUS         0x70
  61 #define NAND_CMD_SEQIN          0x80
  62 #define NAND_CMD_RNDIN          0x85
  63 #define NAND_CMD_READID         0x90
  64 #define NAND_CMD_ERASE2         0xd0
  65 #define NAND_CMD_PARAM          0xec
  66 #define NAND_CMD_GET_FEATURES   0xee
  67 #define NAND_CMD_SET_FEATURES   0xef
  68 #define NAND_CMD_RESET          0xff
  69
  70 /* Extended commands for large page devices */
  71 #define NAND_CMD_READSTART      0x30
  72 #define NAND_CMD_RNDOUTSTART    0xE0
  73 #define NAND_CMD_CACHEDPROG     0x15
  74
  75 #define NAND_CMD_NONE           -1
  76
  77 /* Status bits */
  78 #define NAND_STATUS_FAIL        0x01
  79 #define NAND_STATUS_FAIL_N1     0x02
  80 #define NAND_STATUS_TRUE_READY  0x20
  81 #define NAND_STATUS_READY       0x40
  82 #define NAND_STATUS_WP          0x80
  83
  84 #define NAND_DATA_IFACE_CHECK_ONLY      -1
  85
  86 /*
  87  * Constants for ECC_MODES
  88  */
  89 typedef enum {
  90         NAND_ECC_NONE,
  91         NAND_ECC_SOFT,
  92         NAND_ECC_HW,
  93         NAND_ECC_HW_SYNDROME,
  94         NAND_ECC_HW_OOB_FIRST,
  95         NAND_ECC_ON_DIE,
  96 } nand_ecc_modes_t;
  97
  98 enum nand_ecc_algo {
  99         NAND_ECC_UNKNOWN,
 100         NAND_ECC_HAMMING,
 101         NAND_ECC_BCH,
 102         NAND_ECC_RS,
 103 };
 104
 105 /*
 106  * Constants for Hardware ECC
 107  */
 108 /* Reset Hardware ECC for read */
 109 #define NAND_ECC_READ           0
 110 /* Reset Hardware ECC for write */
 111 #define NAND_ECC_WRITE          1
 112 /* Enable Hardware ECC before syndrome is read back from flash */
 113 #define NAND_ECC_READSYN        2
 114
 115 /*
 116  * Enable generic NAND 'page erased' check. This check is only done when
 117  * ecc.correct() returns -EBADMSG.
 118  * Set this flag if your implementation does not fix bitflips in erased
 119  * pages and you want to rely on the default implementation.
 120  */
 121 #define NAND_ECC_GENERIC_ERASED_CHECK   BIT(0)
 122 #define NAND_ECC_MAXIMIZE               BIT(1)
 123
 124 /*
 125  * When using software implementation of Hamming, we can specify which byte
 126  * ordering should be used.
 127  */
 128 #define NAND_ECC_SOFT_HAMMING_SM_ORDER  BIT(2)
 129
 130 /*
 131  * Option constants for bizarre disfunctionality and real
 132  * features.
 133  */
 134 /* Buswidth is 16 bit */
 135 #define NAND_BUSWIDTH_16        0x00000002
 136 /* Chip has cache program function */
 137 #define NAND_CACHEPRG           0x00000008
 138 /*
 139  * Chip requires ready check on read (for auto-incremented sequential read).
 140  * True only for small page devices; large page devices do not support
 141  * autoincrement.
 142  */
 143 #define NAND_NEED_READRDY       0x00000100
 144
 145 /* Chip does not allow subpage writes */
 146 #define NAND_NO_SUBPAGE_WRITE   0x00000200
 147
 148 /* Device is one of 'new' xD cards that expose fake nand command set */
 149 #define NAND_BROKEN_XD          0x00000400
 150
 151 /* Device behaves just like nand, but is readonly */
 152 #define NAND_ROM                0x00000800
 153
 154 /* Device supports subpage reads */
 155 #define NAND_SUBPAGE_READ       0x00001000
 156
 157 /*
 158  * Some MLC NANDs need data scrambling to limit bitflips caused by repeated
 159  * patterns.
 160  */
 161 #define NAND_NEED_SCRAMBLING    0x00002000
 162
 163 /* Device needs 3rd row address cycle */
 164 #define NAND_ROW_ADDR_3         0x00004000
 165
 166 /* Options valid for Samsung large page devices */
 167 #define NAND_SAMSUNG_LP_OPTIONS NAND_CACHEPRG
 168
 169 /* Macros to identify the above */
 170 #define NAND_HAS_SUBPAGE_READ(chip) ((chip->options & NAND_SUBPAGE_READ))
 171
 172 /* Non chip related options */
 173 /* This option skips the bbt scan during initialization. */
 174 #define NAND_SKIP_BBTSCAN       0x00010000
 175 /* Chip may not exist, so silence any errors in scan */
 176 #define NAND_SCAN_SILENT_NODEV  0x00040000
 177 /*
 178  * Autodetect nand buswidth with readid/onfi.
 179  * This suppose the driver will configure the hardware in 8 bits mode
 180  * when calling nand_scan_ident, and update its configuration
 181  * before calling nand_scan_tail.
 182  */
 183 #define NAND_BUSWIDTH_AUTO      0x00080000
 184 /*
 185  * This option could be defined by controller drivers to protect against
 186  * kmap'ed, vmalloc'ed highmem buffers being passed from upper layers
 187  */
 188 #define NAND_USE_BOUNCE_BUFFER  0x00100000
 189
 190 /*
 191  * In case your controller is implementing ->legacy.cmd_ctrl() and is relying
 192  * on the default ->cmdfunc() implementation, you may want to let the core
 193  * handle the tCCS delay which is required when a column change (RNDIN or
 194  * RNDOUT) is requested.
 195  * If your controller already takes care of this delay, you don't need to set
 196  * this flag.
 197  */
 198 #define NAND_WAIT_TCCS          0x00200000
 199
 200 /*
 201  * Whether the NAND chip is a boot medium. Drivers might use this information
 202  * to select ECC algorithms supported by the boot ROM or similar restrictions.
 203  */
 204 #define NAND_IS_BOOT_MEDIUM     0x00400000
 205
 206 /*
 207  * Do not try to tweak the timings at runtime. This is needed when the
 208  * controller initializes the timings on itself or when it relies on
 209  * configuration done by the bootloader.
 210  */
 211 #define NAND_KEEP_TIMINGS       0x00800000
 212
 213 /* Cell info constants */
 214 #define NAND_CI_CHIPNR_MSK      0x03
 215 #define NAND_CI_CELLTYPE_MSK    0x0C
 216 #define NAND_CI_CELLTYPE_SHIFT  2
 217
 218 /**
 219  * struct nand_parameters - NAND generic parameters from the parameter page
 220  * @model: Model name
 221  * @supports_set_get_features: The NAND chip supports setting/getting features
 222  * @set_feature_list: Bitmap of features that can be set
 223  * @get_feature_list: Bitmap of features that can be get
 224  * @onfi: ONFI specific parameters
 225  */
 226 struct nand_parameters {
 227         /* Generic parameters */
 228         const char *model;
 229         bool supports_set_get_features;
 230         DECLARE_BITMAP(set_feature_list, ONFI_FEATURE_NUMBER);
 231         DECLARE_BITMAP(get_feature_list, ONFI_FEATURE_NUMBER);
 232
 233         /* ONFI parameters */
 234         struct onfi_params *onfi;
 235 };
 236
 237 /* The maximum expected count of bytes in the NAND ID sequence */
 238 #define NAND_MAX_ID_LEN 8
 239
 240 /**
 241  * struct nand_id - NAND id structure
 242  * @data: buffer containing the id bytes.
 243  * @len: ID length.
 244  */
 245 struct nand_id {
 246         u8 data[NAND_MAX_ID_LEN];
 247         int len;
 248 };
 249
 250 /**
 251  * struct nand_ecc_step_info - ECC step information of ECC engine
 252  * @stepsize: data bytes per ECC step
 253  * @strengths: array of supported strengths
 254  * @nstrengths: number of supported strengths
 255  */
 256 struct nand_ecc_step_info {
 257         int stepsize;
 258         const int *strengths;
 259         int nstrengths;
 260 };
 261
 262 /**
 263  * struct nand_ecc_caps - capability of ECC engine
 264  * @stepinfos: array of ECC step information
 265  * @nstepinfos: number of ECC step information
 266  * @calc_ecc_bytes: driver's hook to calculate ECC bytes per step
 267  */
 268 struct nand_ecc_caps {
 269         const struct nand_ecc_step_info *stepinfos;
 270         int nstepinfos;
 271         int (*calc_ecc_bytes)(int step_size, int strength);
 272 };
 273
 274 /* a shorthand to generate struct nand_ecc_caps with only one ECC stepsize */
 275 #define NAND_ECC_CAPS_SINGLE(__name, __calc, __step, ...)       \
 276 static const int __name##_strengths[] = { __VA_ARGS__ };        \
 277 static const struct nand_ecc_step_info __name##_stepinfo = {    \
 278         .stepsize = __step,                                     \
 279         .strengths = __name##_strengths,                        \
 280         .nstrengths = ARRAY_SIZE(__name##_strengths),           \
 281 };                                                              \
 282 static const struct nand_ecc_caps __name = {                    \
 283         .stepinfos = &__name##_stepinfo,                        \
 284         .nstepinfos = 1,                                        \
 285         .calc_ecc_bytes = __calc,                               \
 286 }
 287
 288 /**
 289  * struct nand_ecc_ctrl - Control structure for ECC
 290  * @mode:       ECC mode
 291  * @algo:       ECC algorithm
 292  * @steps:      number of ECC steps per page
 293  * @size:       data bytes per ECC step
 294  * @bytes:      ECC bytes per step
 295  * @strength:   max number of correctible bits per ECC step
 296  * @total:      total number of ECC bytes per page
 297  * @prepad:     padding information for syndrome based ECC generators
 298  * @postpad:    padding information for syndrome based ECC generators
 299  * @options:    ECC specific options (see NAND_ECC_XXX flags defined above)
 300  * @priv:       pointer to private ECC control data
 301  * @calc_buf:   buffer for calculated ECC, size is oobsize.
 302  * @code_buf:   buffer for ECC read from flash, size is oobsize.
 303  * @hwctl:      function to control hardware ECC generator. Must only
 304  *              be provided if an hardware ECC is available
 305  * @calculate:  function for ECC calculation or readback from ECC hardware
 306  * @correct:    function for ECC correction, matching to ECC generator (sw/hw).
 307  *              Should return a positive number representing the number of
 308  *              corrected bitflips, -EBADMSG if the number of bitflips exceed
 309  *              ECC strength, or any other error code if the error is not
 310  *              directly related to correction.
 311  *              If -EBADMSG is returned the input buffers should be left
 312  *              untouched.
 313  * @read_page_raw:      function to read a raw page without ECC. This function
 314  *                      should hide the specific layout used by the ECC
 315  *                      controller and always return contiguous in-band and
 316  *                      out-of-band data even if they're not stored
 317  *                      contiguously on the NAND chip (e.g.
 318  *                      NAND_ECC_HW_SYNDROME interleaves in-band and
 319  *                      out-of-band data).
 320  * @write_page_raw:     function to write a raw page without ECC. This function
 321  *                      should hide the specific layout used by the ECC
 322  *                      controller and consider the passed data as contiguous
 323  *                      in-band and out-of-band data. ECC controller is
 324  *                      responsible for doing the appropriate transformations
 325  *                      to adapt to its specific layout (e.g.
 326  *                      NAND_ECC_HW_SYNDROME interleaves in-band and
 327  *                      out-of-band data).
 328  * @read_page:  function to read a page according to the ECC generator
 329  *              requirements; returns maximum number of bitflips corrected in
 330  *              any single ECC step, -EIO hw error
 331  * @read_subpage:       function to read parts of the page covered by ECC;
 332  *                      returns same as read_page()
 333  * @write_subpage:      function to write parts of the page covered by ECC.
 334  * @write_page: function to write a page according to the ECC generator
 335  *              requirements.
 336  * @write_oob_raw:      function to write chip OOB data without ECC
 337  * @read_oob_raw:       function to read chip OOB data without ECC
 338  * @read_oob:   function to read chip OOB data
 339  * @write_oob:  function to write chip OOB data
 340  */
 341 struct nand_ecc_ctrl {
 342         nand_ecc_modes_t mode;
 343         enum nand_ecc_algo algo;
 344         int steps;
 345         int size;
 346         int bytes;
 347         int total;
 348         int strength;
 349         int prepad;
 350         int postpad;
 351         unsigned int options;
 352         void *priv;
 353         u8 *calc_buf;
 354         u8 *code_buf;
 355         void (*hwctl)(struct nand_chip *chip, int mode);
 356         int (*calculate)(struct nand_chip *chip, const uint8_t *dat,
 357                          uint8_t *ecc_code);
 358         int (*correct)(struct nand_chip *chip, uint8_t *dat, uint8_t *read_ecc,
 359                        uint8_t *calc_ecc);
 360         int (*read_page_raw)(struct nand_chip *chip, uint8_t *buf,
 361                              int oob_required, int page);
 362         int (*write_page_raw)(struct nand_chip *chip, const uint8_t *buf,
 363                               int oob_required, int page);
 364         int (*read_page)(struct nand_chip *chip, uint8_t *buf,
 365                          int oob_required, int page);
 366         int (*read_subpage)(struct nand_chip *chip, uint32_t offs,
 367                             uint32_t len, uint8_t *buf, int page);
 368         int (*write_subpage)(struct nand_chip *chip, uint32_t offset,
 369                              uint32_t data_len, const uint8_t *data_buf,
 370                              int oob_required, int page);
 371         int (*write_page)(struct nand_chip *chip, const uint8_t *buf,
 372                           int oob_required, int page);
 373         int (*write_oob_raw)(struct nand_chip *chip, int page);
 374         int (*read_oob_raw)(struct nand_chip *chip, int page);
 375         int (*read_oob)(struct nand_chip *chip, int page);
 376         int (*write_oob)(struct nand_chip *chip, int page);
 377 };
 378
 379 /**
 380  * struct nand_sdr_timings - SDR NAND chip timings
 381  *
 382  * This struct defines the timing requirements of a SDR NAND chip.
 383  * These information can be found in every NAND datasheets and the timings
 384  * meaning are described in the ONFI specifications:
 385  * www.onfi.org/~/media/ONFI/specs/onfi_3_1_spec.pdf (chapter 4.15 Timing
 386  * Parameters)
 387  *
 388  * All these timings are expressed in picoseconds.
 389  *
 390  * @tBERS_max: Block erase time
 391  * @tCCS_min: Change column setup time
 392  * @tPROG_max: Page program time
 393  * @tR_max: Page read time
 394  * @tALH_min: ALE hold time
 395  * @tADL_min: ALE to data loading time
 396  * @tALS_min: ALE setup time
 397  * @tAR_min: ALE to RE# delay
 398  * @tCEA_max: CE# access time
 399  * @tCEH_min: CE# high hold time
 400  * @tCH_min:  CE# hold time
 401  * @tCHZ_max: CE# high to output hi-Z
 402  * @tCLH_min: CLE hold time
 403  * @tCLR_min: CLE to RE# delay
 404  * @tCLS_min: CLE setup time
 405  * @tCOH_min: CE# high to output hold
 406  * @tCS_min: CE# setup time
 407  * @tDH_min: Data hold time
 408  * @tDS_min: Data setup time
 409  * @tFEAT_max: Busy time for Set Features and Get Features
 410  * @tIR_min: Output hi-Z to RE# low
 411  * @tITC_max: Interface and Timing Mode Change time
 412  * @tRC_min: RE# cycle time
 413  * @tREA_max: RE# access time
 414  * @tREH_min: RE# high hold time
 415  * @tRHOH_min: RE# high to output hold
 416  * @tRHW_min: RE# high to WE# low
 417  * @tRHZ_max: RE# high to output hi-Z
 418  * @tRLOH_min: RE# low to output hold
 419  * @tRP_min: RE# pulse width
 420  * @tRR_min: Ready to RE# low (data only)
 421  * @tRST_max: Device reset time, measured from the falling edge of R/B# to the
 422  *            rising edge of R/B#.
 423  * @tWB_max: WE# high to SR[6] low
 424  * @tWC_min: WE# cycle time
 425  * @tWH_min: WE# high hold time
 426  * @tWHR_min: WE# high to RE# low
 427  * @tWP_min: WE# pulse width
 428  * @tWW_min: WP# transition to WE# low
 429  */
 430 struct nand_sdr_timings {
 431         u64 tBERS_max;
 432         u32 tCCS_min;
 433         u64 tPROG_max;
 434         u64 tR_max;
 435         u32 tALH_min;
 436         u32 tADL_min;
 437         u32 tALS_min;
 438         u32 tAR_min;
 439         u32 tCEA_max;
 440         u32 tCEH_min;
 441         u32 tCH_min;
 442         u32 tCHZ_max;
 443         u32 tCLH_min;
 444         u32 tCLR_min;
 445         u32 tCLS_min;
 446         u32 tCOH_min;
 447         u32 tCS_min;
 448         u32 tDH_min;
 449         u32 tDS_min;
 450         u32 tFEAT_max;
 451         u32 tIR_min;
 452         u32 tITC_max;
 453         u32 tRC_min;
 454         u32 tREA_max;
 455         u32 tREH_min;
 456         u32 tRHOH_min;
 457         u32 tRHW_min;
 458         u32 tRHZ_max;
 459         u32 tRLOH_min;
 460         u32 tRP_min;
 461         u32 tRR_min;
 462         u64 tRST_max;
 463         u32 tWB_max;
 464         u32 tWC_min;
 465         u32 tWH_min;
 466         u32 tWHR_min;
 467         u32 tWP_min;
 468         u32 tWW_min;
 469 };
 470
 471 /**
 472  * enum nand_data_interface_type - NAND interface timing type
 473  * @NAND_SDR_IFACE:     Single Data Rate interface
 474  */
 475 enum nand_data_interface_type {
 476         NAND_SDR_IFACE,
 477 };
 478
 479 /**
 480  * struct nand_data_interface - NAND interface timing
 481  * @type:        type of the timing
 482  * @timings:     The timing, type according to @type
 483  * @timings.sdr: Use it when @type is %NAND_SDR_IFACE.
 484  */
 485 struct nand_data_interface {
 486         enum nand_data_interface_type type;
 487         union {
 488                 struct nand_sdr_timings sdr;
 489         } timings;
 490 };
 491
 492 /**
 493  * nand_get_sdr_timings - get SDR timing from data interface
 494  * @conf:       The data interface
 495  */
 496 static inline const struct nand_sdr_timings *
 497 nand_get_sdr_timings(const struct nand_data_interface *conf)
 498 {
 499         if (conf->type != NAND_SDR_IFACE)
 500                 return ERR_PTR(-EINVAL);
 501
 502         return &conf->timings.sdr;
 503 }
 504
 505 /**
 506  * struct nand_op_cmd_instr - Definition of a command instruction
 507  * @opcode: the command to issue in one cycle
 508  */
 509 struct nand_op_cmd_instr {
 510         u8 opcode;
 511 };
 512
 513 /**
 514  * struct nand_op_addr_instr - Definition of an address instruction
 515  * @naddrs: length of the @addrs array
 516  * @addrs: array containing the address cycles to issue
 517  */
 518 struct nand_op_addr_instr {
 519         unsigned int naddrs;
 520         const u8 *addrs;
 521 };
 522
 523 /**
 524  * struct nand_op_data_instr - Definition of a data instruction
 525  * @len: number of data bytes to move
 526  * @buf: buffer to fill
 527  * @buf.in: buffer to fill when reading from the NAND chip
 528  * @buf.out: buffer to read from when writing to the NAND chip
 529  * @force_8bit: force 8-bit access
 530  *
 531  * Please note that "in" and "out" are inverted from the ONFI specification
 532  * and are from the controller perspective, so a "in" is a read from the NAND
 533  * chip while a "out" is a write to the NAND chip.
 534  */
 535 struct nand_op_data_instr {
 536         unsigned int len;
 537         union {
 538                 void *in;
 539                 const void *out;
 540         } buf;
 541         bool force_8bit;
 542 };
 543
 544 /**
 545  * struct nand_op_waitrdy_instr - Definition of a wait ready instruction
 546  * @timeout_ms: maximum delay while waiting for the ready/busy pin in ms
 547  */
 548 struct nand_op_waitrdy_instr {
 549         unsigned int timeout_ms;
 550 };
 551
 552 /**
 553  * enum nand_op_instr_type - Definition of all instruction types
 554  * @NAND_OP_CMD_INSTR: command instruction
 555  * @NAND_OP_ADDR_INSTR: address instruction
 556  * @NAND_OP_DATA_IN_INSTR: data in instruction
 557  * @NAND_OP_DATA_OUT_INSTR: data out instruction
 558  * @NAND_OP_WAITRDY_INSTR: wait ready instruction
 559  */
 560 enum nand_op_instr_type {
 561         NAND_OP_CMD_INSTR,
 562         NAND_OP_ADDR_INSTR,
 563         NAND_OP_DATA_IN_INSTR,
 564         NAND_OP_DATA_OUT_INSTR,
 565         NAND_OP_WAITRDY_INSTR,
 566 };
 567
 568 /**
 569  * struct nand_op_instr - Instruction object
 570  * @type: the instruction type
 571  * @ctx:  extra data associated to the instruction. You'll have to use the
 572  *        appropriate element depending on @type
 573  * @ctx.cmd: use it if @type is %NAND_OP_CMD_INSTR
 574  * @ctx.addr: use it if @type is %NAND_OP_ADDR_INSTR
 575  * @ctx.data: use it if @type is %NAND_OP_DATA_IN_INSTR
 576  *            or %NAND_OP_DATA_OUT_INSTR
 577  * @ctx.waitrdy: use it if @type is %NAND_OP_WAITRDY_INSTR
 578  * @delay_ns: delay the controller should apply after the instruction has been
 579  *            issued on the bus. Most modern controllers have internal timings
 580  *            control logic, and in this case, the controller driver can ignore
 581  *            this field.
 582  */
 583 struct nand_op_instr {
 584         enum nand_op_instr_type type;
 585         union {
 586                 struct nand_op_cmd_instr cmd;
 587                 struct nand_op_addr_instr addr;
 588                 struct nand_op_data_instr data;
 589                 struct nand_op_waitrdy_instr waitrdy;
 590         } ctx;
 591         unsigned int delay_ns;
 592 };
 593
 594 /*
 595  * Special handling must be done for the WAITRDY timeout parameter as it usually
 596  * is either tPROG (after a prog), tR (before a read), tRST (during a reset) or
 597  * tBERS (during an erase) which all of them are u64 values that cannot be
 598  * divided by usual kernel macros and must be handled with the special
 599  * DIV_ROUND_UP_ULL() macro.
 600  *
 601  * Cast to type of dividend is needed here to guarantee that the result won't
 602  * be an unsigned long long when the dividend is an unsigned long (or smaller),
 603  * which is what the compiler does when it sees ternary operator with 2
 604  * different return types (picks the largest type to make sure there's no
 605  * loss).
 606  */
 607 #define __DIVIDE(dividend, divisor) ({                                          \
 608         (__typeof__(dividend))(sizeof(dividend) <= sizeof(unsigned long) ?      \
 609                                DIV_ROUND_UP(dividend, divisor) :                \
 610                                DIV_ROUND_UP_ULL(dividend, divisor));            \
 611         })
 612 #define PSEC_TO_NSEC(x) __DIVIDE(x, 1000)
 613 #define PSEC_TO_MSEC(x) __DIVIDE(x, 1000000000)
 614
 615 #define NAND_OP_CMD(id, ns)                                             \
 616         {                                                               \
 617                 .type = NAND_OP_CMD_INSTR,                              \
 618                 .ctx.cmd.opcode = id,                                   \
 619                 .delay_ns = ns,                                         \
 620         }
 621
 622 #define NAND_OP_ADDR(ncycles, cycles, ns)                               \
 623         {                                                               \
 624                 .type = NAND_OP_ADDR_INSTR,                             \
 625                 .ctx.addr = {                                           \
 626                         .naddrs = ncycles,                              \
 627                         .addrs = cycles,                                \
 628                 },                                                      \
 629                 .delay_ns = ns,                                         \
 630         }
 631
 632 #define NAND_OP_DATA_IN(l, b, ns)                                       \
 633         {                                                               \
 634                 .type = NAND_OP_DATA_IN_INSTR,                          \
 635                 .ctx.data = {                                           \
 636                         .len = l,                                       \
 637                         .buf.in = b,                                    \
 638                         .force_8bit = false,                            \
 639                 },                                                      \
 640                 .delay_ns = ns,                                         \
 641         }
 642
 643 #define NAND_OP_DATA_OUT(l, b, ns)                                      \
 644         {                                                               \
 645                 .type = NAND_OP_DATA_OUT_INSTR,                         \
 646                 .ctx.data = {                                           \
 647                         .len = l,                                       \
 648                         .buf.out = b,                                   \
 649                         .force_8bit = false,                            \
 650                 },                                                      \
 651                 .delay_ns = ns,                                         \
 652         }
 653
 654 #define NAND_OP_8BIT_DATA_IN(l, b, ns)                                  \
 655         {                                                               \
 656                 .type = NAND_OP_DATA_IN_INSTR,                          \
 657                 .ctx.data = {                                           \
 658                         .len = l,                                       \
 659                         .buf.in = b,                                    \
 660                         .force_8bit = true,                             \
 661                 },                                                      \
 662                 .delay_ns = ns,                                         \
 663         }
 664
 665 #define NAND_OP_8BIT_DATA_OUT(l, b, ns)                                 \
 666         {                                                               \
 667                 .type = NAND_OP_DATA_OUT_INSTR,                         \
 668                 .ctx.data = {                                           \
 669                         .len = l,                                       \
 670                         .buf.out = b,                                   \
 671                         .force_8bit = true,                             \
 672                 },                                                      \
 673                 .delay_ns = ns,                                         \
 674         }
 675
 676 #define NAND_OP_WAIT_RDY(tout_ms, ns)                                   \
 677         {                                                               \
 678                 .type = NAND_OP_WAITRDY_INSTR,                          \
 679                 .ctx.waitrdy.timeout_ms = tout_ms,                      \
 680                 .delay_ns = ns,                                         \
 681         }
 682
 683 /**
 684  * struct nand_subop - a sub operation
 685  * @instrs: array of instructions
 686  * @ninstrs: length of the @instrs array
 687  * @first_instr_start_off: offset to start from for the first instruction
 688  *                         of the sub-operation
 689  * @last_instr_end_off: offset to end at (excluded) for the last instruction
 690  *                      of the sub-operation
 691  *
 692  * Both @first_instr_start_off and @last_instr_end_off only apply to data or
 693  * address instructions.
 694  *
 695  * When an operation cannot be handled as is by the NAND controller, it will
 696  * be split by the parser into sub-operations which will be passed to the
 697  * controller driver.
 698  */
 699 struct nand_subop {
 700         const struct nand_op_instr *instrs;
 701         unsigned int ninstrs;
 702         unsigned int first_instr_start_off;
 703         unsigned int last_instr_end_off;
 704 };
 705
 706 unsigned int nand_subop_get_addr_start_off(const struct nand_subop *subop,
 707                                            unsigned int op_id);
 708 unsigned int nand_subop_get_num_addr_cyc(const struct nand_subop *subop,
 709                                          unsigned int op_id);
 710 unsigned int nand_subop_get_data_start_off(const struct nand_subop *subop,
 711                                            unsigned int op_id);
 712 unsigned int nand_subop_get_data_len(const struct nand_subop *subop,
 713                                      unsigned int op_id);
 714
 715 /**
 716  * struct nand_op_parser_addr_constraints - Constraints for address instructions
 717  * @maxcycles: maximum number of address cycles the controller can issue in a
 718  *             single step
 719  */
 720 struct nand_op_parser_addr_constraints {
 721         unsigned int maxcycles;
 722 };
 723
 724 /**
 725  * struct nand_op_parser_data_constraints - Constraints for data instructions
 726  * @maxlen: maximum data length that the controller can handle in a single step
 727  */
 728 struct nand_op_parser_data_constraints {
 729         unsigned int maxlen;
 730 };
 731
 732 /**
 733  * struct nand_op_parser_pattern_elem - One element of a pattern
 734  * @type: the instructuction type
 735  * @optional: whether this element of the pattern is optional or mandatory
 736  * @ctx: address or data constraint
 737  * @ctx.addr: address constraint (number of cycles)
 738  * @ctx.data: data constraint (data length)
 739  */
 740 struct nand_op_parser_pattern_elem {
 741         enum nand_op_instr_type type;
 742         bool optional;
 743         union {
 744                 struct nand_op_parser_addr_constraints addr;
 745                 struct nand_op_parser_data_constraints data;
 746         } ctx;
 747 };
 748
 749 #define NAND_OP_PARSER_PAT_CMD_ELEM(_opt)                       \
 750         {                                                       \
 751                 .type = NAND_OP_CMD_INSTR,                      \
 752                 .optional = _opt,                               \
 753         }
 754
 755 #define NAND_OP_PARSER_PAT_ADDR_ELEM(_opt, _maxcycles)          \
 756         {                                                       \
 757                 .type = NAND_OP_ADDR_INSTR,                     \
 758                 .optional = _opt,                               \
 759                 .ctx.addr.maxcycles = _maxcycles,               \
 760         }
 761
 762 #define NAND_OP_PARSER_PAT_DATA_IN_ELEM(_opt, _maxlen)          \
 763         {                                                       \
 764                 .type = NAND_OP_DATA_IN_INSTR,                  \
 765                 .optional = _opt,                               \
 766                 .ctx.data.maxlen = _maxlen,                     \
 767         }
 768
 769 #define NAND_OP_PARSER_PAT_DATA_OUT_ELEM(_opt, _maxlen)         \
 770         {                                                       \
 771                 .type = NAND_OP_DATA_OUT_INSTR,                 \
 772                 .optional = _opt,                               \
 773                 .ctx.data.maxlen = _maxlen,                     \
 774         }
 775
 776 #define NAND_OP_PARSER_PAT_WAITRDY_ELEM(_opt)                   \
 777         {                                                       \
 778                 .type = NAND_OP_WAITRDY_INSTR,                  \
 779                 .optional = _opt,                               \
 780         }
 781
 782 /**
 783  * struct nand_op_parser_pattern - NAND sub-operation pattern descriptor
 784  * @elems: array of pattern elements
 785  * @nelems: number of pattern elements in @elems array
 786  * @exec: the function that will issue a sub-operation
 787  *
 788  * A pattern is a list of elements, each element reprensenting one instruction
 789  * with its constraints. The pattern itself is used by the core to match NAND
 790  * chip operation with NAND controller operations.
 791  * Once a match between a NAND controller operation pattern and a NAND chip
 792  * operation (or a sub-set of a NAND operation) is found, the pattern ->exec()
 793  * hook is called so that the controller driver can issue the operation on the
 794  * bus.
 795  *
 796  * Controller drivers should declare as many patterns as they support and pass
 797  * this list of patterns (created with the help of the following macro) to
 798  * the nand_op_parser_exec_op() helper.
 799  */
 800 struct nand_op_parser_pattern {
 801         const struct nand_op_parser_pattern_elem *elems;
 802         unsigned int nelems;
 803         int (*exec)(struct nand_chip *chip, const struct nand_subop *subop);
 804 };
 805
 806 #define NAND_OP_PARSER_PATTERN(_exec, ...)                                                      \
 807         {                                                                                       \
 808                 .exec = _exec,                                                                  \
 809                 .elems = (struct nand_op_parser_pattern_elem[]) { __VA_ARGS__ },                \
 810                 .nelems = sizeof((struct nand_op_parser_pattern_elem[]) { __VA_ARGS__ }) /      \
 811                           sizeof(struct nand_op_parser_pattern_elem),                           \
 812         }
 813
 814 /**
 815  * struct nand_op_parser - NAND controller operation parser descriptor
 816  * @patterns: array of supported patterns
 817  * @npatterns: length of the @patterns array
 818  *
 819  * The parser descriptor is just an array of supported patterns which will be
 820  * iterated by nand_op_parser_exec_op() everytime it tries to execute an
 821  * NAND operation (or tries to determine if a specific operation is supported).
 822  *
 823  * It is worth mentioning that patterns will be tested in their declaration
 824  * order, and the first match will be taken, so it's important to order patterns
 825  * appropriately so that simple/inefficient patterns are placed at the end of
 826  * the list. Usually, this is where you put single instruction patterns.
 827  */
 828 struct nand_op_parser {
 829         const struct nand_op_parser_pattern *patterns;
 830         unsigned int npatterns;
 831 };
 832
 833 #define NAND_OP_PARSER(...)                                                                     \
 834         {                                                                                       \
 835                 .patterns = (struct nand_op_parser_pattern[]) { __VA_ARGS__ },                  \
 836                 .npatterns = sizeof((struct nand_op_parser_pattern[]) { __VA_ARGS__ }) /        \
 837                              sizeof(struct nand_op_parser_pattern),                             \
 838         }
 839
 840 /**
 841  * struct nand_operation - NAND operation descriptor
 842  * @cs: the CS line to select for this NAND operation
 843  * @instrs: array of instructions to execute
 844  * @ninstrs: length of the @instrs array
 845  *
 846  * The actual operation structure that will be passed to chip->exec_op().
 847  */
 848 struct nand_operation {
 849         unsigned int cs;
 850         const struct nand_op_instr *instrs;
 851         unsigned int ninstrs;
 852 };
 853
 854 #define NAND_OPERATION(_cs, _instrs)                            \
 855         {                                                       \
 856                 .cs = _cs,                                      \
 857                 .instrs = _instrs,                              \
 858                 .ninstrs = ARRAY_SIZE(_instrs),                 \
 859         }
 860
 861 int nand_op_parser_exec_op(struct nand_chip *chip,
 862                            const struct nand_op_parser *parser,
 863                            const struct nand_operation *op, bool check_only);
 864 /**
 865  * struct nand_controller_ops - Controller operations
 866  *
 867  * @attach_chip: this method is called after the NAND detection phase after
 868  *               flash ID and MTD fields such as erase size, page size and OOB
 869  *               size have been set up. ECC requirements are available if
 870  *               provided by the NAND chip or device tree. Typically used to
 871  *               choose the appropriate ECC configuration and allocate
 872  *               associated resources.
 873  *               This hook is optional.
 874  * @detach_chip: free all resources allocated/claimed in
 875  *               nand_controller_ops->attach_chip().
 876  *               This hook is optional.
 877  * @exec_op:     controller specific method to execute NAND operations.
 878  *               This method replaces chip->legacy.cmdfunc(),
 879  *               chip->legacy.{read,write}_{buf,byte,word}(),
 880  *               chip->legacy.dev_ready() and chip->legacy.waifunc().
 881  * @setup_data_interface: setup the data interface and timing. If
 882  *                        chipnr is set to %NAND_DATA_IFACE_CHECK_ONLY this
 883  *                        means the configuration should not be applied but
 884  *                        only checked.
 885  *                        This hook is optional.
 886  */
 887 struct nand_controller_ops {
 888         int (*attach_chip)(struct nand_chip *chip);
 889         void (*detach_chip)(struct nand_chip *chip);
 890         int (*exec_op)(struct nand_chip *chip,
 891                        const struct nand_operation *op,
 892                        bool check_only);
 893         int (*setup_data_interface)(struct nand_chip *chip, int chipnr,
 894                                     const struct nand_data_interface *conf);
 895 };
 896
 897 /**
 898  * struct nand_controller - Structure used to describe a NAND controller
 899  *
 900  * @lock:               protection lock
 901  * @active:             the mtd device which holds the controller currently
 902  * @wq:                 wait queue to sleep on if a NAND operation is in
 903  *                      progress used instead of the per chip wait queue
 904  *                      when a hw controller is available.
 905  * @ops:                NAND controller operations.
 906  */
 907 struct nand_controller {
 908         spinlock_t lock;
 909         struct nand_chip *active;
 910         wait_queue_head_t wq;
 911         const struct nand_controller_ops *ops;
 912 };
 913
 914 static inline void nand_controller_init(struct nand_controller *nfc)
 915 {
 916         nfc->active = NULL;
 917         spin_lock_init(&nfc->lock);
 918         init_waitqueue_head(&nfc->wq);
 919 }
 920
 921 /**
 922  * struct nand_legacy - NAND chip legacy fields/hooks
 923  * @IO_ADDR_R: address to read the 8 I/O lines of the flash device
 924  * @IO_ADDR_W: address to write the 8 I/O lines of the flash device
 925  * @select_chip: select/deselect a specific target/die
 926  * @read_byte: read one byte from the chip
 927  * @write_byte: write a single byte to the chip on the low 8 I/O lines
 928  * @write_buf: write data from the buffer to the chip
 929  * @read_buf: read data from the chip into the buffer
 930  * @cmd_ctrl: hardware specific function for controlling ALE/CLE/nCE. Also used
 931  *            to write command and address
 932  * @cmdfunc: hardware specific function for writing commands to the chip.
 933  * @dev_ready: hardware specific function for accessing device ready/busy line.
 934  *             If set to NULL no access to ready/busy is available and the
 935  *             ready/busy information is read from the chip status register.
 936  * @waitfunc: hardware specific function for wait on ready.
 937  * @block_bad: check if a block is bad, using OOB markers
 938  * @block_markbad: mark a block bad
 939  * @erase: erase function
 940  * @set_features: set the NAND chip features
 941  * @get_features: get the NAND chip features
 942  * @chip_delay: chip dependent delay for transferring data from array to read
 943  *              regs (tR).
 944  * @dummy_controller: dummy controller implementation for drivers that can
 945  *                    only control a single chip
 946  *
 947  * If you look at this structure you're already wrong. These fields/hooks are
 948  * all deprecated.
 949  */
 950 struct nand_legacy {
 951         void __iomem *IO_ADDR_R;
 952         void __iomem *IO_ADDR_W;
 953         void (*select_chip)(struct nand_chip *chip, int cs);
 954         u8 (*read_byte)(struct nand_chip *chip);
 955         void (*write_byte)(struct nand_chip *chip, u8 byte);
 956         void (*write_buf)(struct nand_chip *chip, const u8 *buf, int len);
 957         void (*read_buf)(struct nand_chip *chip, u8 *buf, int len);
 958         void (*cmd_ctrl)(struct nand_chip *chip, int dat, unsigned int ctrl);
 959         void (*cmdfunc)(struct nand_chip *chip, unsigned command, int column,
 960                         int page_addr);
 961         int (*dev_ready)(struct nand_chip *chip);
 962         int (*waitfunc)(struct nand_chip *chip);
 963         int (*block_bad)(struct nand_chip *chip, loff_t ofs);
 964         int (*block_markbad)(struct nand_chip *chip, loff_t ofs);
 965         int (*erase)(struct nand_chip *chip, int page);
 966         int (*set_features)(struct nand_chip *chip, int feature_addr,
 967                             u8 *subfeature_para);
 968         int (*get_features)(struct nand_chip *chip, int feature_addr,
 969                             u8 *subfeature_para);
 970         int chip_delay;
 971         struct nand_controller dummy_controller;
 972 };
 973
 974 /**
 975  * struct nand_chip - NAND Private Flash Chip Data
 976  * @mtd:                MTD device registered to the MTD framework
 977  * @legacy:             All legacy fields/hooks. If you develop a new driver,
 978  *                      don't even try to use any of these fields/hooks, and if
 979  *                      you're modifying an existing driver that is using those
 980  *                      fields/hooks, you should consider reworking the driver
 981  *                      avoid using them.
 982  * @setup_read_retry:   [FLASHSPECIFIC] flash (vendor) specific function for
 983  *                      setting the read-retry mode. Mostly needed for MLC NAND.
 984  * @ecc:                [BOARDSPECIFIC] ECC control structure
 985  * @buf_align:          minimum buffer alignment required by a platform
 986  * @state:              [INTERN] the current state of the NAND device
 987  * @oob_poi:            "poison value buffer," used for laying out OOB data
 988  *                      before writing
 989  * @page_shift:         [INTERN] number of address bits in a page (column
 990  *                      address bits).
 991  * @phys_erase_shift:   [INTERN] number of address bits in a physical eraseblock
 992  * @bbt_erase_shift:    [INTERN] number of address bits in a bbt entry
 993  * @chip_shift:         [INTERN] number of address bits in one chip
 994  * @options:            [BOARDSPECIFIC] various chip options. They can partly
 995  *                      be set to inform nand_scan about special functionality.
 996  *                      See the defines for further explanation.
 997  * @bbt_options:        [INTERN] bad block specific options. All options used
 998  *                      here must come from bbm.h. By default, these options
 999  *                      will be copied to the appropriate nand_bbt_descr's.
1000  * @badblockpos:        [INTERN] position of the bad block marker in the oob
1001  *                      area.
1002  * @badblockbits:       [INTERN] minimum number of set bits in a good block's
1003  *                      bad block marker position; i.e., BBM == 11110111b is
1004  *                      not bad when badblockbits == 7
1005  * @bits_per_cell:      [INTERN] number of bits per cell. i.e., 1 means SLC.
1006  * @ecc_strength_ds:    [INTERN] ECC correctability from the datasheet.
1007  *                      Minimum amount of bit errors per @ecc_step_ds guaranteed
1008  *                      to be correctable. If unknown, set to zero.
1009  * @ecc_step_ds:        [INTERN] ECC step required by the @ecc_strength_ds,
1010  *                      also from the datasheet. It is the recommended ECC step
1011  *                      size, if known; if unknown, set to zero.
1012  * @onfi_timing_mode_default: [INTERN] default ONFI timing mode. This field is
1013  *                            set to the actually used ONFI mode if the chip is
1014  *                            ONFI compliant or deduced from the datasheet if
1015  *                            the NAND chip is not ONFI compliant.
1016  * @numchips:           [INTERN] number of physical chips
1017  * @chipsize:           [INTERN] the size of one chip for multichip arrays
1018  * @pagemask:           [INTERN] page number mask = number of (pages / chip) - 1
1019  * @data_buf:           [INTERN] buffer for data, size is (page size + oobsize).
1020  * @pagebuf:            [INTERN] holds the pagenumber which is currently in
1021  *                      data_buf.
1022  * @pagebuf_bitflips:   [INTERN] holds the bitflip count for the page which is
1023  *                      currently in data_buf.
1024  * @subpagesize:        [INTERN] holds the subpagesize
1025  * @id:                 [INTERN] holds NAND ID
1026  * @parameters:         [INTERN] holds generic parameters under an easily
1027  *                      readable form.
1028  * @max_bb_per_die:     [INTERN] the max number of bad blocks each die of a
1029  *                      this nand device will encounter their life times.
1030  * @blocks_per_die:     [INTERN] The number of PEBs in a die
1031  * @data_interface:     [INTERN] NAND interface timing information
1032  * @cur_cs:             currently selected target. -1 means no target selected,
1033  *                      otherwise we should always have cur_cs >= 0 &&
1034  *                      cur_cs < numchips. NAND Controller drivers should not
1035  *                      modify this value, but they're allowed to read it.
1036  * @read_retries:       [INTERN] the number of read retry modes supported
1037  * @bbt:                [INTERN] bad block table pointer
1038  * @bbt_td:             [REPLACEABLE] bad block table descriptor for flash
1039  *                      lookup.
1040  * @bbt_md:             [REPLACEABLE] bad block table mirror descriptor
1041  * @badblock_pattern:   [REPLACEABLE] bad block scan pattern used for initial
1042  *                      bad block scan.
1043  * @controller:         [REPLACEABLE] a pointer to a hardware controller
1044  *                      structure which is shared among multiple independent
1045  *                      devices.
1046  * @priv:               [OPTIONAL] pointer to private chip data
1047  * @manufacturer:       [INTERN] Contains manufacturer information
1048  * @manufacturer.desc:  [INTERN] Contains manufacturer's description
1049  * @manufacturer.priv:  [INTERN] Contains manufacturer private information
1050  */
1051
1052 struct nand_chip {
1053         struct mtd_info mtd;
1054
1055         struct nand_legacy legacy;
1056
1057         int (*setup_read_retry)(struct nand_chip *chip, int retry_mode);
1058
1059         unsigned int options;
1060         unsigned int bbt_options;
1061
1062         int page_shift;
1063         int phys_erase_shift;
1064         int bbt_erase_shift;
1065         int chip_shift;
1066         int numchips;
1067         uint64_t chipsize;
1068         int pagemask;
1069         u8 *data_buf;
1070         int pagebuf;
1071         unsigned int pagebuf_bitflips;
1072         int subpagesize;
1073         uint8_t bits_per_cell;
1074         uint16_t ecc_strength_ds;
1075         uint16_t ecc_step_ds;
1076         int onfi_timing_mode_default;
1077         int badblockpos;
1078         int badblockbits;
1079
1080         struct nand_id id;
1081         struct nand_parameters parameters;
1082         u16 max_bb_per_die;
1083         u32 blocks_per_die;
1084
1085         struct nand_data_interface data_interface;
1086
1087         int cur_cs;
1088
1089         int read_retries;
1090
1091         flstate_t state;
1092
1093         uint8_t *oob_poi;
1094         struct nand_controller *controller;
1095
1096         struct nand_ecc_ctrl ecc;
1097         unsigned long buf_align;
1098
1099         uint8_t *bbt;
1100         struct nand_bbt_descr *bbt_td;
1101         struct nand_bbt_descr *bbt_md;
1102
1103         struct nand_bbt_descr *badblock_pattern;
1104
1105         void *priv;
1106
1107         struct {
1108                 const struct nand_manufacturer *desc;
1109                 void *priv;
1110         } manufacturer;
1111 };
1112
1113 extern const struct mtd_ooblayout_ops nand_ooblayout_sp_ops;
1114 extern const struct mtd_ooblayout_ops nand_ooblayout_lp_ops;
1115
1116 static inline void nand_set_flash_node(struct nand_chip *chip,
1117                                        struct device_node *np)
1118 {
1119         mtd_set_of_node(&chip->mtd, np);
1120 }
1121
1122 static inline struct device_node *nand_get_flash_node(struct nand_chip *chip)
1123 {
1124         return mtd_get_of_node(&chip->mtd);
1125 }
1126
1127 static inline struct nand_chip *mtd_to_nand(struct mtd_info *mtd)
1128 {
1129         return container_of(mtd, struct nand_chip, mtd);
1130 }
1131
1132 static inline struct mtd_info *nand_to_mtd(struct nand_chip *chip)
1133 {
1134         return &chip->mtd;
1135 }
1136
1137 static inline void *nand_get_controller_data(struct nand_chip *chip)
1138 {
1139         return chip->priv;
1140 }
1141
1142 static inline void nand_set_controller_data(struct nand_chip *chip, void *priv)
1143 {
1144         chip->priv = priv;
1145 }
1146
1147 static inline void nand_set_manufacturer_data(struct nand_chip *chip,
1148                                               void *priv)
1149 {
1150         chip->manufacturer.priv = priv;
1151 }
1152
1153 static inline void *nand_get_manufacturer_data(struct nand_chip *chip)
1154 {
1155         return chip->manufacturer.priv;
1156 }
1157
1158 /*
1159  * A helper for defining older NAND chips where the second ID byte fully
1160  * defined the chip, including the geometry (chip size, eraseblock size, page
1161  * size). All these chips have 512 bytes NAND page size.
1162  */
1163 #define LEGACY_ID_NAND(nm, devid, chipsz, erasesz, opts)          \
1164         { .name = (nm), {{ .dev_id = (devid) }}, .pagesize = 512, \
1165           .chipsize = (chipsz), .erasesize = (erasesz), .options = (opts) }
1166
1167 /*
1168  * A helper for defining newer chips which report their page size and
1169  * eraseblock size via the extended ID bytes.
1170  *
1171  * The real difference between LEGACY_ID_NAND and EXTENDED_ID_NAND is that with
1172  * EXTENDED_ID_NAND, manufacturers overloaded the same device ID so that the
1173  * device ID now only represented a particular total chip size (and voltage,
1174  * buswidth), and the page size, eraseblock size, and OOB size could vary while
1175  * using the same device ID.
1176  */
1177 #define EXTENDED_ID_NAND(nm, devid, chipsz, opts)                      \
1178         { .name = (nm), {{ .dev_id = (devid) }}, .chipsize = (chipsz), \
1179           .options = (opts) }
1180
1181 #define NAND_ECC_INFO(_strength, _step) \
1182                         { .strength_ds = (_strength), .step_ds = (_step) }
1183 #define NAND_ECC_STRENGTH(type)         ((type)->ecc.strength_ds)
1184 #define NAND_ECC_STEP(type)             ((type)->ecc.step_ds)
1185
1186 /**
1187  * struct nand_flash_dev - NAND Flash Device ID Structure
1188  * @name: a human-readable name of the NAND chip
1189  * @dev_id: the device ID (the second byte of the full chip ID array)
1190  * @mfr_id: manufecturer ID part of the full chip ID array (refers the same
1191  *          memory address as @id[0])
1192  * @dev_id: device ID part of the full chip ID array (refers the same memory
1193  *          address as @id[1])
1194  * @id: full device ID array
1195  * @pagesize: size of the NAND page in bytes; if 0, then the real page size (as
1196  *            well as the eraseblock size) is determined from the extended NAND
1197  *            chip ID array)
1198  * @chipsize: total chip size in MiB
1199  * @erasesize: eraseblock size in bytes (determined from the extended ID if 0)
1200  * @options: stores various chip bit options
1201  * @id_len: The valid length of the @id.
1202  * @oobsize: OOB size
1203  * @ecc: ECC correctability and step information from the datasheet.
1204  * @ecc.strength_ds: The ECC correctability from the datasheet, same as the
1205  *                   @ecc_strength_ds in nand_chip{}.
1206  * @ecc.step_ds: The ECC step required by the @ecc.strength_ds, same as the
1207  *               @ecc_step_ds in nand_chip{}, also from the datasheet.
1208  *               For example, the "4bit ECC for each 512Byte" can be set with
1209  *               NAND_ECC_INFO(4, 512).
1210  * @onfi_timing_mode_default: the default ONFI timing mode entered after a NAND
1211  *                            reset. Should be deduced from timings described
1212  *                            in the datasheet.
1213  *
1214  */
1215 struct nand_flash_dev {
1216         char *name;
1217         union {
1218                 struct {
1219                         uint8_t mfr_id;
1220                         uint8_t dev_id;
1221                 };
1222                 uint8_t id[NAND_MAX_ID_LEN];
1223         };
1224         unsigned int pagesize;
1225         unsigned int chipsize;
1226         unsigned int erasesize;
1227         unsigned int options;
1228         uint16_t id_len;
1229         uint16_t oobsize;
1230         struct {
1231                 uint16_t strength_ds;
1232                 uint16_t step_ds;
1233         } ecc;
1234         int onfi_timing_mode_default;
1235 };
1236
1237 int nand_create_bbt(struct nand_chip *chip);
1238
1239 /*
1240  * Check if it is a SLC nand.
1241  * The !nand_is_slc() can be used to check the MLC/TLC nand chips.
1242  * We do not distinguish the MLC and TLC now.
1243  */
1244 static inline bool nand_is_slc(struct nand_chip *chip)
1245 {
1246         WARN(chip->bits_per_cell == 0,
1247              "chip->bits_per_cell is used uninitialized\n");
1248         return chip->bits_per_cell == 1;
1249 }
1250
1251 /**
1252  * Check if the opcode's address should be sent only on the lower 8 bits
1253  * @command: opcode to check
1254  */
1255 static inline int nand_opcode_8bits(unsigned int command)
1256 {
1257         switch (command) {
1258         case NAND_CMD_READID:
1259         case NAND_CMD_PARAM:
1260         case NAND_CMD_GET_FEATURES:
1261         case NAND_CMD_SET_FEATURES:
1262                 return 1;
1263         default:
1264                 break;
1265         }
1266         return 0;
1267 }
1268
1269 int nand_check_erased_ecc_chunk(void *data, int datalen,
1270                                 void *ecc, int ecclen,
1271                                 void *extraoob, int extraooblen,
1272                                 int threshold);
1273
1274 int nand_ecc_choose_conf(struct nand_chip *chip,
1275                          const struct nand_ecc_caps *caps, int oobavail);
1276
1277 /* Default write_oob implementation */
1278 int nand_write_oob_std(struct nand_chip *chip, int page);
1279
1280 /* Default read_oob implementation */
1281 int nand_read_oob_std(struct nand_chip *chip, int page);
1282
1283 /* Stub used by drivers that do not support GET/SET FEATURES operations */
1284 int nand_get_set_features_notsupp(struct nand_chip *chip, int addr,
1285                                   u8 *subfeature_param);
1286
1287 /* Default read_page_raw implementation */
1288 int nand_read_page_raw(struct nand_chip *chip, uint8_t *buf, int oob_required,
1289                        int page);
1290
1291 /* Default write_page_raw implementation */
1292 int nand_write_page_raw(struct nand_chip *chip, const uint8_t *buf,
1293                         int oob_required, int page);
1294
1295 /* Reset and initialize a NAND device */
1296 int nand_reset(struct nand_chip *chip, int chipnr);
1297
1298 /* NAND operation helpers */
1299 int nand_reset_op(struct nand_chip *chip);
1300 int nand_readid_op(struct nand_chip *chip, u8 addr, void *buf,
1301                    unsigned int len);
1302 int nand_status_op(struct nand_chip *chip, u8 *status);
1303 int nand_erase_op(struct nand_chip *chip, unsigned int eraseblock);
1304 int nand_read_page_op(struct nand_chip *chip, unsigned int page,
1305                       unsigned int offset_in_page, void *buf, unsigned int len);
1306 int nand_change_read_column_op(struct nand_chip *chip,
1307                                unsigned int offset_in_page, void *buf,
1308                                unsigned int len, bool force_8bit);
1309 int nand_read_oob_op(struct nand_chip *chip, unsigned int page,
1310                      unsigned int offset_in_page, void *buf, unsigned int len);
1311 int nand_prog_page_begin_op(struct nand_chip *chip, unsigned int page,
1312                             unsigned int offset_in_page, const void *buf,
1313                             unsigned int len);
1314 int nand_prog_page_end_op(struct nand_chip *chip);
1315 int nand_prog_page_op(struct nand_chip *chip, unsigned int page,
1316                       unsigned int offset_in_page, const void *buf,
1317                       unsigned int len);
1318 int nand_change_write_column_op(struct nand_chip *chip,
1319                                 unsigned int offset_in_page, const void *buf,
1320                                 unsigned int len, bool force_8bit);
1321 int nand_read_data_op(struct nand_chip *chip, void *buf, unsigned int len,
1322                       bool force_8bit);
1323 int nand_write_data_op(struct nand_chip *chip, const void *buf,
1324                        unsigned int len, bool force_8bit);
1325
1326 /* Scan and identify a NAND device */
1327 int nand_scan_with_ids(struct nand_chip *chip, unsigned int max_chips,
1328                        struct nand_flash_dev *ids);
1329
1330 static inline int nand_scan(struct nand_chip *chip, unsigned int max_chips)
1331 {
1332         return nand_scan_with_ids(chip, max_chips, NULL);
1333 }
1334
1335 /* Internal helper for board drivers which need to override command function */
1336 void nand_wait_ready(struct nand_chip *chip);
1337
1338 /*
1339  * Free resources held by the NAND device, must be called on error after a
1340  * sucessful nand_scan().
1341  */
1342 void nand_cleanup(struct nand_chip *chip);
1343 /* Unregister the MTD device and calls nand_cleanup() */
1344 void nand_release(struct nand_chip *chip);
1345
1346 /*
1347  * External helper for controller drivers that have to implement the WAITRDY
1348  * instruction and have no physical pin to check it.
1349  */
1350 int nand_soft_waitrdy(struct nand_chip *chip, unsigned long timeout_ms);
1351 struct gpio_desc;
1352 int nand_gpio_waitrdy(struct nand_chip *chip, struct gpio_desc *gpiod,
1353                       unsigned long timeout_ms);
1354
1355 /* Select/deselect a NAND target. */
1356 void nand_select_target(struct nand_chip *chip, unsigned int cs);
1357 void nand_deselect_target(struct nand_chip *chip);
1358
1359 #endif /* __LINUX_MTD_RAWNAND_H */