include/linux/mtd/rawnand.h

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