Back to home page

OSCL-LXR

 
 

    


0001 /* SPDX-License-Identifier: GPL-2.0 */
0002 /*
0003  * Copyright (c) 2016-2017 Micron Technology, Inc.
0004  *
0005  *  Authors:
0006  *  Peter Pan <peterpandong@micron.com>
0007  */
0008 #ifndef __LINUX_MTD_SPINAND_H
0009 #define __LINUX_MTD_SPINAND_H
0010 
0011 #include <linux/mutex.h>
0012 #include <linux/bitops.h>
0013 #include <linux/device.h>
0014 #include <linux/mtd/mtd.h>
0015 #include <linux/mtd/nand.h>
0016 #include <linux/spi/spi.h>
0017 #include <linux/spi/spi-mem.h>
0018 
0019 /**
0020  * Standard SPI NAND flash operations
0021  */
0022 
0023 #define SPINAND_RESET_OP                        \
0024     SPI_MEM_OP(SPI_MEM_OP_CMD(0xff, 1),             \
0025            SPI_MEM_OP_NO_ADDR,                  \
0026            SPI_MEM_OP_NO_DUMMY,                 \
0027            SPI_MEM_OP_NO_DATA)
0028 
0029 #define SPINAND_WR_EN_DIS_OP(enable)                    \
0030     SPI_MEM_OP(SPI_MEM_OP_CMD((enable) ? 0x06 : 0x04, 1),       \
0031            SPI_MEM_OP_NO_ADDR,                  \
0032            SPI_MEM_OP_NO_DUMMY,                 \
0033            SPI_MEM_OP_NO_DATA)
0034 
0035 #define SPINAND_READID_OP(naddr, ndummy, buf, len)          \
0036     SPI_MEM_OP(SPI_MEM_OP_CMD(0x9f, 1),             \
0037            SPI_MEM_OP_ADDR(naddr, 0, 1),            \
0038            SPI_MEM_OP_DUMMY(ndummy, 1),             \
0039            SPI_MEM_OP_DATA_IN(len, buf, 1))
0040 
0041 #define SPINAND_SET_FEATURE_OP(reg, valptr)             \
0042     SPI_MEM_OP(SPI_MEM_OP_CMD(0x1f, 1),             \
0043            SPI_MEM_OP_ADDR(1, reg, 1),              \
0044            SPI_MEM_OP_NO_DUMMY,                 \
0045            SPI_MEM_OP_DATA_OUT(1, valptr, 1))
0046 
0047 #define SPINAND_GET_FEATURE_OP(reg, valptr)             \
0048     SPI_MEM_OP(SPI_MEM_OP_CMD(0x0f, 1),             \
0049            SPI_MEM_OP_ADDR(1, reg, 1),              \
0050            SPI_MEM_OP_NO_DUMMY,                 \
0051            SPI_MEM_OP_DATA_IN(1, valptr, 1))
0052 
0053 #define SPINAND_BLK_ERASE_OP(addr)                  \
0054     SPI_MEM_OP(SPI_MEM_OP_CMD(0xd8, 1),             \
0055            SPI_MEM_OP_ADDR(3, addr, 1),             \
0056            SPI_MEM_OP_NO_DUMMY,                 \
0057            SPI_MEM_OP_NO_DATA)
0058 
0059 #define SPINAND_PAGE_READ_OP(addr)                  \
0060     SPI_MEM_OP(SPI_MEM_OP_CMD(0x13, 1),             \
0061            SPI_MEM_OP_ADDR(3, addr, 1),             \
0062            SPI_MEM_OP_NO_DUMMY,                 \
0063            SPI_MEM_OP_NO_DATA)
0064 
0065 #define SPINAND_PAGE_READ_FROM_CACHE_OP(fast, addr, ndummy, buf, len)   \
0066     SPI_MEM_OP(SPI_MEM_OP_CMD(fast ? 0x0b : 0x03, 1),       \
0067            SPI_MEM_OP_ADDR(2, addr, 1),             \
0068            SPI_MEM_OP_DUMMY(ndummy, 1),             \
0069            SPI_MEM_OP_DATA_IN(len, buf, 1))
0070 
0071 #define SPINAND_PAGE_READ_FROM_CACHE_OP_3A(fast, addr, ndummy, buf, len) \
0072     SPI_MEM_OP(SPI_MEM_OP_CMD(fast ? 0x0b : 0x03, 1),       \
0073            SPI_MEM_OP_ADDR(3, addr, 1),             \
0074            SPI_MEM_OP_DUMMY(ndummy, 1),             \
0075            SPI_MEM_OP_DATA_IN(len, buf, 1))
0076 
0077 #define SPINAND_PAGE_READ_FROM_CACHE_X2_OP(addr, ndummy, buf, len)  \
0078     SPI_MEM_OP(SPI_MEM_OP_CMD(0x3b, 1),             \
0079            SPI_MEM_OP_ADDR(2, addr, 1),             \
0080            SPI_MEM_OP_DUMMY(ndummy, 1),             \
0081            SPI_MEM_OP_DATA_IN(len, buf, 2))
0082 
0083 #define SPINAND_PAGE_READ_FROM_CACHE_X2_OP_3A(addr, ndummy, buf, len)   \
0084     SPI_MEM_OP(SPI_MEM_OP_CMD(0x3b, 1),             \
0085            SPI_MEM_OP_ADDR(3, addr, 1),             \
0086            SPI_MEM_OP_DUMMY(ndummy, 1),             \
0087            SPI_MEM_OP_DATA_IN(len, buf, 2))
0088 
0089 #define SPINAND_PAGE_READ_FROM_CACHE_X4_OP(addr, ndummy, buf, len)  \
0090     SPI_MEM_OP(SPI_MEM_OP_CMD(0x6b, 1),             \
0091            SPI_MEM_OP_ADDR(2, addr, 1),             \
0092            SPI_MEM_OP_DUMMY(ndummy, 1),             \
0093            SPI_MEM_OP_DATA_IN(len, buf, 4))
0094 
0095 #define SPINAND_PAGE_READ_FROM_CACHE_X4_OP_3A(addr, ndummy, buf, len)   \
0096     SPI_MEM_OP(SPI_MEM_OP_CMD(0x6b, 1),             \
0097            SPI_MEM_OP_ADDR(3, addr, 1),             \
0098            SPI_MEM_OP_DUMMY(ndummy, 1),             \
0099            SPI_MEM_OP_DATA_IN(len, buf, 4))
0100 
0101 #define SPINAND_PAGE_READ_FROM_CACHE_DUALIO_OP(addr, ndummy, buf, len)  \
0102     SPI_MEM_OP(SPI_MEM_OP_CMD(0xbb, 1),             \
0103            SPI_MEM_OP_ADDR(2, addr, 2),             \
0104            SPI_MEM_OP_DUMMY(ndummy, 2),             \
0105            SPI_MEM_OP_DATA_IN(len, buf, 2))
0106 
0107 #define SPINAND_PAGE_READ_FROM_CACHE_DUALIO_OP_3A(addr, ndummy, buf, len) \
0108     SPI_MEM_OP(SPI_MEM_OP_CMD(0xbb, 1),             \
0109            SPI_MEM_OP_ADDR(3, addr, 2),             \
0110            SPI_MEM_OP_DUMMY(ndummy, 2),             \
0111            SPI_MEM_OP_DATA_IN(len, buf, 2))
0112 
0113 #define SPINAND_PAGE_READ_FROM_CACHE_QUADIO_OP(addr, ndummy, buf, len)  \
0114     SPI_MEM_OP(SPI_MEM_OP_CMD(0xeb, 1),             \
0115            SPI_MEM_OP_ADDR(2, addr, 4),             \
0116            SPI_MEM_OP_DUMMY(ndummy, 4),             \
0117            SPI_MEM_OP_DATA_IN(len, buf, 4))
0118 
0119 #define SPINAND_PAGE_READ_FROM_CACHE_QUADIO_OP_3A(addr, ndummy, buf, len) \
0120     SPI_MEM_OP(SPI_MEM_OP_CMD(0xeb, 1),             \
0121            SPI_MEM_OP_ADDR(3, addr, 4),             \
0122            SPI_MEM_OP_DUMMY(ndummy, 4),             \
0123            SPI_MEM_OP_DATA_IN(len, buf, 4))
0124 
0125 #define SPINAND_PROG_EXEC_OP(addr)                  \
0126     SPI_MEM_OP(SPI_MEM_OP_CMD(0x10, 1),             \
0127            SPI_MEM_OP_ADDR(3, addr, 1),             \
0128            SPI_MEM_OP_NO_DUMMY,                 \
0129            SPI_MEM_OP_NO_DATA)
0130 
0131 #define SPINAND_PROG_LOAD(reset, addr, buf, len)            \
0132     SPI_MEM_OP(SPI_MEM_OP_CMD(reset ? 0x02 : 0x84, 1),      \
0133            SPI_MEM_OP_ADDR(2, addr, 1),             \
0134            SPI_MEM_OP_NO_DUMMY,                 \
0135            SPI_MEM_OP_DATA_OUT(len, buf, 1))
0136 
0137 #define SPINAND_PROG_LOAD_X4(reset, addr, buf, len)         \
0138     SPI_MEM_OP(SPI_MEM_OP_CMD(reset ? 0x32 : 0x34, 1),      \
0139            SPI_MEM_OP_ADDR(2, addr, 1),             \
0140            SPI_MEM_OP_NO_DUMMY,                 \
0141            SPI_MEM_OP_DATA_OUT(len, buf, 4))
0142 
0143 /**
0144  * Standard SPI NAND flash commands
0145  */
0146 #define SPINAND_CMD_PROG_LOAD_X4        0x32
0147 #define SPINAND_CMD_PROG_LOAD_RDM_DATA_X4   0x34
0148 
0149 /* feature register */
0150 #define REG_BLOCK_LOCK      0xa0
0151 #define BL_ALL_UNLOCKED     0x00
0152 
0153 /* configuration register */
0154 #define REG_CFG         0xb0
0155 #define CFG_OTP_ENABLE      BIT(6)
0156 #define CFG_ECC_ENABLE      BIT(4)
0157 #define CFG_QUAD_ENABLE     BIT(0)
0158 
0159 /* status register */
0160 #define REG_STATUS      0xc0
0161 #define STATUS_BUSY     BIT(0)
0162 #define STATUS_ERASE_FAILED BIT(2)
0163 #define STATUS_PROG_FAILED  BIT(3)
0164 #define STATUS_ECC_MASK     GENMASK(5, 4)
0165 #define STATUS_ECC_NO_BITFLIPS  (0 << 4)
0166 #define STATUS_ECC_HAS_BITFLIPS (1 << 4)
0167 #define STATUS_ECC_UNCOR_ERROR  (2 << 4)
0168 
0169 struct spinand_op;
0170 struct spinand_device;
0171 
0172 #define SPINAND_MAX_ID_LEN  4
0173 /*
0174  * For erase, write and read operation, we got the following timings :
0175  * tBERS (erase) 1ms to 4ms
0176  * tPROG 300us to 400us
0177  * tREAD 25us to 100us
0178  * In order to minimize latency, the min value is divided by 4 for the
0179  * initial delay, and dividing by 20 for the poll delay.
0180  * For reset, 5us/10us/500us if the device is respectively
0181  * reading/programming/erasing when the RESET occurs. Since we always
0182  * issue a RESET when the device is IDLE, 5us is selected for both initial
0183  * and poll delay.
0184  */
0185 #define SPINAND_READ_INITIAL_DELAY_US   6
0186 #define SPINAND_READ_POLL_DELAY_US  5
0187 #define SPINAND_RESET_INITIAL_DELAY_US  5
0188 #define SPINAND_RESET_POLL_DELAY_US 5
0189 #define SPINAND_WRITE_INITIAL_DELAY_US  75
0190 #define SPINAND_WRITE_POLL_DELAY_US 15
0191 #define SPINAND_ERASE_INITIAL_DELAY_US  250
0192 #define SPINAND_ERASE_POLL_DELAY_US 50
0193 
0194 #define SPINAND_WAITRDY_TIMEOUT_MS  400
0195 
0196 /**
0197  * struct spinand_id - SPI NAND id structure
0198  * @data: buffer containing the id bytes. Currently 4 bytes large, but can
0199  *    be extended if required
0200  * @len: ID length
0201  */
0202 struct spinand_id {
0203     u8 data[SPINAND_MAX_ID_LEN];
0204     int len;
0205 };
0206 
0207 enum spinand_readid_method {
0208     SPINAND_READID_METHOD_OPCODE,
0209     SPINAND_READID_METHOD_OPCODE_ADDR,
0210     SPINAND_READID_METHOD_OPCODE_DUMMY,
0211 };
0212 
0213 /**
0214  * struct spinand_devid - SPI NAND device id structure
0215  * @id: device id of current chip
0216  * @len: number of bytes in device id
0217  * @method: method to read chip id
0218  *      There are 3 possible variants:
0219  *      SPINAND_READID_METHOD_OPCODE: chip id is returned immediately
0220  *      after read_id opcode.
0221  *      SPINAND_READID_METHOD_OPCODE_ADDR: chip id is returned after
0222  *      read_id opcode + 1-byte address.
0223  *      SPINAND_READID_METHOD_OPCODE_DUMMY: chip id is returned after
0224  *      read_id opcode + 1 dummy byte.
0225  */
0226 struct spinand_devid {
0227     const u8 *id;
0228     const u8 len;
0229     const enum spinand_readid_method method;
0230 };
0231 
0232 /**
0233  * struct manufacurer_ops - SPI NAND manufacturer specific operations
0234  * @init: initialize a SPI NAND device
0235  * @cleanup: cleanup a SPI NAND device
0236  *
0237  * Each SPI NAND manufacturer driver should implement this interface so that
0238  * NAND chips coming from this vendor can be initialized properly.
0239  */
0240 struct spinand_manufacturer_ops {
0241     int (*init)(struct spinand_device *spinand);
0242     void (*cleanup)(struct spinand_device *spinand);
0243 };
0244 
0245 /**
0246  * struct spinand_manufacturer - SPI NAND manufacturer instance
0247  * @id: manufacturer ID
0248  * @name: manufacturer name
0249  * @devid_len: number of bytes in device ID
0250  * @chips: supported SPI NANDs under current manufacturer
0251  * @nchips: number of SPI NANDs available in chips array
0252  * @ops: manufacturer operations
0253  */
0254 struct spinand_manufacturer {
0255     u8 id;
0256     char *name;
0257     const struct spinand_info *chips;
0258     const size_t nchips;
0259     const struct spinand_manufacturer_ops *ops;
0260 };
0261 
0262 /* SPI NAND manufacturers */
0263 extern const struct spinand_manufacturer ato_spinand_manufacturer;
0264 extern const struct spinand_manufacturer gigadevice_spinand_manufacturer;
0265 extern const struct spinand_manufacturer macronix_spinand_manufacturer;
0266 extern const struct spinand_manufacturer micron_spinand_manufacturer;
0267 extern const struct spinand_manufacturer paragon_spinand_manufacturer;
0268 extern const struct spinand_manufacturer toshiba_spinand_manufacturer;
0269 extern const struct spinand_manufacturer winbond_spinand_manufacturer;
0270 extern const struct spinand_manufacturer xtx_spinand_manufacturer;
0271 
0272 /**
0273  * struct spinand_op_variants - SPI NAND operation variants
0274  * @ops: the list of variants for a given operation
0275  * @nops: the number of variants
0276  *
0277  * Some operations like read-from-cache/write-to-cache have several variants
0278  * depending on the number of IO lines you use to transfer data or address
0279  * cycles. This structure is a way to describe the different variants supported
0280  * by a chip and let the core pick the best one based on the SPI mem controller
0281  * capabilities.
0282  */
0283 struct spinand_op_variants {
0284     const struct spi_mem_op *ops;
0285     unsigned int nops;
0286 };
0287 
0288 #define SPINAND_OP_VARIANTS(name, ...)                  \
0289     const struct spinand_op_variants name = {           \
0290         .ops = (struct spi_mem_op[]) { __VA_ARGS__ },       \
0291         .nops = sizeof((struct spi_mem_op[]){ __VA_ARGS__ }) /  \
0292             sizeof(struct spi_mem_op),          \
0293     }
0294 
0295 /**
0296  * spinand_ecc_info - description of the on-die ECC implemented by a SPI NAND
0297  *            chip
0298  * @get_status: get the ECC status. Should return a positive number encoding
0299  *      the number of corrected bitflips if correction was possible or
0300  *      -EBADMSG if there are uncorrectable errors. I can also return
0301  *      other negative error codes if the error is not caused by
0302  *      uncorrectable bitflips
0303  * @ooblayout: the OOB layout used by the on-die ECC implementation
0304  */
0305 struct spinand_ecc_info {
0306     int (*get_status)(struct spinand_device *spinand, u8 status);
0307     const struct mtd_ooblayout_ops *ooblayout;
0308 };
0309 
0310 #define SPINAND_HAS_QE_BIT      BIT(0)
0311 #define SPINAND_HAS_CR_FEAT_BIT     BIT(1)
0312 
0313 /**
0314  * struct spinand_ondie_ecc_conf - private SPI-NAND on-die ECC engine structure
0315  * @status: status of the last wait operation that will be used in case
0316  *          ->get_status() is not populated by the spinand device.
0317  */
0318 struct spinand_ondie_ecc_conf {
0319     u8 status;
0320 };
0321 
0322 /**
0323  * struct spinand_info - Structure used to describe SPI NAND chips
0324  * @model: model name
0325  * @devid: device ID
0326  * @flags: OR-ing of the SPINAND_XXX flags
0327  * @memorg: memory organization
0328  * @eccreq: ECC requirements
0329  * @eccinfo: on-die ECC info
0330  * @op_variants: operations variants
0331  * @op_variants.read_cache: variants of the read-cache operation
0332  * @op_variants.write_cache: variants of the write-cache operation
0333  * @op_variants.update_cache: variants of the update-cache operation
0334  * @select_target: function used to select a target/die. Required only for
0335  *         multi-die chips
0336  *
0337  * Each SPI NAND manufacturer driver should have a spinand_info table
0338  * describing all the chips supported by the driver.
0339  */
0340 struct spinand_info {
0341     const char *model;
0342     struct spinand_devid devid;
0343     u32 flags;
0344     struct nand_memory_organization memorg;
0345     struct nand_ecc_props eccreq;
0346     struct spinand_ecc_info eccinfo;
0347     struct {
0348         const struct spinand_op_variants *read_cache;
0349         const struct spinand_op_variants *write_cache;
0350         const struct spinand_op_variants *update_cache;
0351     } op_variants;
0352     int (*select_target)(struct spinand_device *spinand,
0353                  unsigned int target);
0354 };
0355 
0356 #define SPINAND_ID(__method, ...)                   \
0357     {                               \
0358         .id = (const u8[]){ __VA_ARGS__ },          \
0359         .len = sizeof((u8[]){ __VA_ARGS__ }),           \
0360         .method = __method,                 \
0361     }
0362 
0363 #define SPINAND_INFO_OP_VARIANTS(__read, __write, __update)     \
0364     {                               \
0365         .read_cache = __read,                   \
0366         .write_cache = __write,                 \
0367         .update_cache = __update,               \
0368     }
0369 
0370 #define SPINAND_ECCINFO(__ooblayout, __get_status)          \
0371     .eccinfo = {                            \
0372         .ooblayout = __ooblayout,               \
0373         .get_status = __get_status,             \
0374     }
0375 
0376 #define SPINAND_SELECT_TARGET(__func)                   \
0377     .select_target = __func,
0378 
0379 #define SPINAND_INFO(__model, __id, __memorg, __eccreq, __op_variants,  \
0380              __flags, ...)                  \
0381     {                               \
0382         .model = __model,                   \
0383         .devid = __id,                      \
0384         .memorg = __memorg,                 \
0385         .eccreq = __eccreq,                 \
0386         .op_variants = __op_variants,               \
0387         .flags = __flags,                   \
0388         __VA_ARGS__                     \
0389     }
0390 
0391 struct spinand_dirmap {
0392     struct spi_mem_dirmap_desc *wdesc;
0393     struct spi_mem_dirmap_desc *rdesc;
0394     struct spi_mem_dirmap_desc *wdesc_ecc;
0395     struct spi_mem_dirmap_desc *rdesc_ecc;
0396 };
0397 
0398 /**
0399  * struct spinand_device - SPI NAND device instance
0400  * @base: NAND device instance
0401  * @spimem: pointer to the SPI mem object
0402  * @lock: lock used to serialize accesses to the NAND
0403  * @id: NAND ID as returned by READ_ID
0404  * @flags: NAND flags
0405  * @op_templates: various SPI mem op templates
0406  * @op_templates.read_cache: read cache op template
0407  * @op_templates.write_cache: write cache op template
0408  * @op_templates.update_cache: update cache op template
0409  * @select_target: select a specific target/die. Usually called before sending
0410  *         a command addressing a page or an eraseblock embedded in
0411  *         this die. Only required if your chip exposes several dies
0412  * @cur_target: currently selected target/die
0413  * @eccinfo: on-die ECC information
0414  * @cfg_cache: config register cache. One entry per die
0415  * @databuf: bounce buffer for data
0416  * @oobbuf: bounce buffer for OOB data
0417  * @scratchbuf: buffer used for everything but page accesses. This is needed
0418  *      because the spi-mem interface explicitly requests that buffers
0419  *      passed in spi_mem_op be DMA-able, so we can't based the bufs on
0420  *      the stack
0421  * @manufacturer: SPI NAND manufacturer information
0422  * @priv: manufacturer private data
0423  */
0424 struct spinand_device {
0425     struct nand_device base;
0426     struct spi_mem *spimem;
0427     struct mutex lock;
0428     struct spinand_id id;
0429     u32 flags;
0430 
0431     struct {
0432         const struct spi_mem_op *read_cache;
0433         const struct spi_mem_op *write_cache;
0434         const struct spi_mem_op *update_cache;
0435     } op_templates;
0436 
0437     struct spinand_dirmap *dirmaps;
0438 
0439     int (*select_target)(struct spinand_device *spinand,
0440                  unsigned int target);
0441     unsigned int cur_target;
0442 
0443     struct spinand_ecc_info eccinfo;
0444 
0445     u8 *cfg_cache;
0446     u8 *databuf;
0447     u8 *oobbuf;
0448     u8 *scratchbuf;
0449     const struct spinand_manufacturer *manufacturer;
0450     void *priv;
0451 };
0452 
0453 /**
0454  * mtd_to_spinand() - Get the SPI NAND device attached to an MTD instance
0455  * @mtd: MTD instance
0456  *
0457  * Return: the SPI NAND device attached to @mtd.
0458  */
0459 static inline struct spinand_device *mtd_to_spinand(struct mtd_info *mtd)
0460 {
0461     return container_of(mtd_to_nanddev(mtd), struct spinand_device, base);
0462 }
0463 
0464 /**
0465  * spinand_to_mtd() - Get the MTD device embedded in a SPI NAND device
0466  * @spinand: SPI NAND device
0467  *
0468  * Return: the MTD device embedded in @spinand.
0469  */
0470 static inline struct mtd_info *spinand_to_mtd(struct spinand_device *spinand)
0471 {
0472     return nanddev_to_mtd(&spinand->base);
0473 }
0474 
0475 /**
0476  * nand_to_spinand() - Get the SPI NAND device embedding an NAND object
0477  * @nand: NAND object
0478  *
0479  * Return: the SPI NAND device embedding @nand.
0480  */
0481 static inline struct spinand_device *nand_to_spinand(struct nand_device *nand)
0482 {
0483     return container_of(nand, struct spinand_device, base);
0484 }
0485 
0486 /**
0487  * spinand_to_nand() - Get the NAND device embedded in a SPI NAND object
0488  * @spinand: SPI NAND device
0489  *
0490  * Return: the NAND device embedded in @spinand.
0491  */
0492 static inline struct nand_device *
0493 spinand_to_nand(struct spinand_device *spinand)
0494 {
0495     return &spinand->base;
0496 }
0497 
0498 /**
0499  * spinand_set_of_node - Attach a DT node to a SPI NAND device
0500  * @spinand: SPI NAND device
0501  * @np: DT node
0502  *
0503  * Attach a DT node to a SPI NAND device.
0504  */
0505 static inline void spinand_set_of_node(struct spinand_device *spinand,
0506                        struct device_node *np)
0507 {
0508     nanddev_set_of_node(&spinand->base, np);
0509 }
0510 
0511 int spinand_match_and_init(struct spinand_device *spinand,
0512                const struct spinand_info *table,
0513                unsigned int table_size,
0514                enum spinand_readid_method rdid_method);
0515 
0516 int spinand_upd_cfg(struct spinand_device *spinand, u8 mask, u8 val);
0517 int spinand_select_target(struct spinand_device *spinand, unsigned int target);
0518 
0519 #endif /* __LINUX_MTD_SPINAND_H */