1 /* SPDX-License-Identifier: GPL-2.0 */
3 * Copyright 2017 - Free Electrons
6 * Boris Brezillon <boris.brezillon@free-electrons.com>
7 * Peter Pan <peterpandong@micron.com>
10 #ifndef __LINUX_MTD_NAND_H
11 #define __LINUX_MTD_NAND_H
13 #include <linux/mtd/mtd.h>
14 #include <linux/bitops.h>
17 * struct nand_memory_organization - Memory organization structure
18 * @bits_per_cell: number of bits per NAND cell
19 * @pagesize: page size
20 * @oobsize: OOB area size
21 * @pages_per_eraseblock: number of pages per eraseblock
22 * @eraseblocks_per_lun: number of eraseblocks per LUN (Logical Unit Number)
23 * @planes_per_lun: number of planes per LUN
24 * @luns_per_target: number of LUN per target (target is a synonym for die)
25 * @ntargets: total number of targets exposed by the NAND device
27 struct nand_memory_organization
{
28 unsigned int bits_per_cell
;
29 unsigned int pagesize
;
31 unsigned int pages_per_eraseblock
;
32 unsigned int eraseblocks_per_lun
;
33 unsigned int planes_per_lun
;
34 unsigned int luns_per_target
;
35 unsigned int ntargets
;
38 #define NAND_MEMORG(bpc, ps, os, ppe, epl, ppl, lpt, nt) \
40 .bits_per_cell = (bpc), \
43 .pages_per_eraseblock = (ppe), \
44 .eraseblocks_per_lun = (epl), \
45 .planes_per_lun = (ppl), \
46 .luns_per_target = (lpt), \
51 * struct nand_row_converter - Information needed to convert an absolute offset
53 * @lun_addr_shift: position of the LUN identifier in the row address
54 * @eraseblock_addr_shift: position of the eraseblock identifier in the row
57 struct nand_row_converter
{
58 unsigned int lun_addr_shift
;
59 unsigned int eraseblock_addr_shift
;
63 * struct nand_pos - NAND position object
64 * @target: the NAND target/die
65 * @lun: the LUN identifier
66 * @plane: the plane within the LUN
67 * @eraseblock: the eraseblock within the LUN
68 * @page: the page within the LUN
70 * These information are usually used by specific sub-layers to select the
71 * appropriate target/die and generate a row address to pass to the device.
77 unsigned int eraseblock
;
82 * struct nand_page_io_req - NAND I/O request object
83 * @pos: the position this I/O request is targeting
84 * @dataoffs: the offset within the page
85 * @datalen: number of data bytes to read from/write to this page
86 * @databuf: buffer to store data in or get data from
87 * @ooboffs: the OOB offset within the page
88 * @ooblen: the number of OOB bytes to read from/write to this page
89 * @oobbuf: buffer to store OOB data in or get OOB data from
90 * @mode: one of the %MTD_OPS_XXX mode
92 * This object is used to pass per-page I/O requests to NAND sub-layers. This
93 * way all useful information are already formatted in a useful way and
94 * specific NAND layers can focus on translating these information into
95 * specific commands/operations.
97 struct nand_page_io_req
{
99 unsigned int dataoffs
;
100 unsigned int datalen
;
105 unsigned int ooboffs
;
115 * struct nand_ecc_req - NAND ECC requirements
116 * @strength: ECC strength
117 * @step_size: ECC step/block size
119 struct nand_ecc_req
{
120 unsigned int strength
;
121 unsigned int step_size
;
124 #define NAND_ECCREQ(str, stp) { .strength = (str), .step_size = (stp) }
127 * struct nand_bbt - bad block table object
128 * @cache: in memory BBT cache
131 unsigned long *cache
;
137 * struct nand_ops - NAND operations
138 * @erase: erase a specific block. No need to check if the block is bad before
139 * erasing, this has been taken care of by the generic NAND layer
140 * @markbad: mark a specific block bad. No need to check if the block is
141 * already marked bad, this has been taken care of by the generic
142 * NAND layer. This method should just write the BBM (Bad Block
143 * Marker) so that future call to struct_nand_ops->isbad() return
145 * @isbad: check whether a block is bad or not. This method should just read
146 * the BBM and return whether the block is bad or not based on what it
149 * These are all low level operations that should be implemented by specialized
150 * NAND layers (SPI NAND, raw NAND, ...).
153 int (*erase
)(struct nand_device
*nand
, const struct nand_pos
*pos
);
154 int (*markbad
)(struct nand_device
*nand
, const struct nand_pos
*pos
);
155 bool (*isbad
)(struct nand_device
*nand
, const struct nand_pos
*pos
);
159 * struct nand_device - NAND device
160 * @mtd: MTD instance attached to the NAND device
161 * @memorg: memory layout
162 * @eccreq: ECC requirements
163 * @rowconv: position to row address converter
164 * @bbt: bad block table info
165 * @ops: NAND operations attached to the NAND device
167 * Generic NAND object. Specialized NAND layers (raw NAND, SPI NAND, OneNAND)
168 * should declare their own NAND object embedding a nand_device struct (that's
169 * how inheritance is done).
170 * struct_nand_device->memorg and struct_nand_device->eccreq should be filled
171 * at device detection time to reflect the NAND device
172 * capabilities/requirements. Once this is done nanddev_init() can be called.
173 * It will take care of converting NAND information into MTD ones, which means
174 * the specialized NAND layers should never manually tweak
175 * struct_nand_device->mtd except for the ->_read/write() hooks.
178 struct mtd_info
*mtd
;
179 struct nand_memory_organization memorg
;
180 struct nand_ecc_req eccreq
;
181 struct nand_row_converter rowconv
;
183 const struct nand_ops
*ops
;
187 * struct nand_io_iter - NAND I/O iterator
188 * @req: current I/O request
189 * @oobbytes_per_page: maximum number of OOB bytes per page
190 * @dataleft: remaining number of data bytes to read/write
191 * @oobleft: remaining number of OOB bytes to read/write
193 * Can be used by specialized NAND layers to iterate over all pages covered
194 * by an MTD I/O request, which should greatly simplifies the boiler-plate
195 * code needed to read/write data from/to a NAND device.
197 struct nand_io_iter
{
198 struct nand_page_io_req req
;
199 unsigned int oobbytes_per_page
;
200 unsigned int dataleft
;
201 unsigned int oobleft
;
205 * mtd_to_nanddev() - Get the NAND device attached to the MTD instance
208 * Return: the NAND device embedding @mtd.
210 static inline struct nand_device
*mtd_to_nanddev(struct mtd_info
*mtd
)
216 * nanddev_to_mtd() - Get the MTD device attached to a NAND device
219 * Return: the MTD device embedded in @nand.
221 static inline struct mtd_info
*nanddev_to_mtd(struct nand_device
*nand
)
227 * nanddev_bits_per_cell() - Get the number of bits per cell
230 * Return: the number of bits per cell.
232 static inline unsigned int nanddev_bits_per_cell(const struct nand_device
*nand
)
234 return nand
->memorg
.bits_per_cell
;
238 * nanddev_page_size() - Get NAND page size
241 * Return: the page size.
243 static inline size_t nanddev_page_size(const struct nand_device
*nand
)
245 return nand
->memorg
.pagesize
;
249 * nanddev_per_page_oobsize() - Get NAND OOB size
252 * Return: the OOB size.
254 static inline unsigned int
255 nanddev_per_page_oobsize(const struct nand_device
*nand
)
257 return nand
->memorg
.oobsize
;
261 * nanddev_pages_per_eraseblock() - Get the number of pages per eraseblock
264 * Return: the number of pages per eraseblock.
266 static inline unsigned int
267 nanddev_pages_per_eraseblock(const struct nand_device
*nand
)
269 return nand
->memorg
.pages_per_eraseblock
;
273 * nanddev_per_page_oobsize() - Get NAND erase block size
276 * Return: the eraseblock size.
278 static inline size_t nanddev_eraseblock_size(const struct nand_device
*nand
)
280 return nand
->memorg
.pagesize
* nand
->memorg
.pages_per_eraseblock
;
284 * nanddev_eraseblocks_per_lun() - Get the number of eraseblocks per LUN
287 * Return: the number of eraseblocks per LUN.
289 static inline unsigned int
290 nanddev_eraseblocks_per_lun(const struct nand_device
*nand
)
292 return nand
->memorg
.eraseblocks_per_lun
;
296 * nanddev_target_size() - Get the total size provided by a single target/die
299 * Return: the total size exposed by a single target/die in bytes.
301 static inline u64
nanddev_target_size(const struct nand_device
*nand
)
303 return (u64
)nand
->memorg
.luns_per_target
*
304 nand
->memorg
.eraseblocks_per_lun
*
305 nand
->memorg
.pages_per_eraseblock
*
306 nand
->memorg
.pagesize
;
310 * nanddev_ntarget() - Get the total of targets
313 * Return: the number of targets/dies exposed by @nand.
315 static inline unsigned int nanddev_ntargets(const struct nand_device
*nand
)
317 return nand
->memorg
.ntargets
;
321 * nanddev_neraseblocks() - Get the total number of erasablocks
324 * Return: the total number of eraseblocks exposed by @nand.
326 static inline unsigned int nanddev_neraseblocks(const struct nand_device
*nand
)
328 return (u64
)nand
->memorg
.luns_per_target
*
329 nand
->memorg
.eraseblocks_per_lun
*
330 nand
->memorg
.pages_per_eraseblock
;
334 * nanddev_size() - Get NAND size
337 * Return: the total size (in bytes) exposed by @nand.
339 static inline u64
nanddev_size(const struct nand_device
*nand
)
341 return nanddev_target_size(nand
) * nanddev_ntargets(nand
);
345 * nanddev_get_memorg() - Extract memory organization info from a NAND device
348 * This can be used by the upper layer to fill the memorg info before calling
351 * Return: the memorg object embedded in the NAND device.
353 static inline struct nand_memory_organization
*
354 nanddev_get_memorg(struct nand_device
*nand
)
356 return &nand
->memorg
;
359 int nanddev_init(struct nand_device
*nand
, const struct nand_ops
*ops
,
360 struct module
*owner
);
361 void nanddev_cleanup(struct nand_device
*nand
);
364 * nanddev_register() - Register a NAND device
367 * Register a NAND device.
368 * This function is just a wrapper around mtd_device_register()
369 * registering the MTD device embedded in @nand.
371 * Return: 0 in case of success, a negative error code otherwise.
373 static inline int nanddev_register(struct nand_device
*nand
)
375 return mtd_device_register(nand
->mtd
, NULL
, 0);
379 * nanddev_unregister() - Unregister a NAND device
382 * Unregister a NAND device.
383 * This function is just a wrapper around mtd_device_unregister()
384 * unregistering the MTD device embedded in @nand.
386 * Return: 0 in case of success, a negative error code otherwise.
388 static inline int nanddev_unregister(struct nand_device
*nand
)
390 return mtd_device_unregister(nand
->mtd
);
394 * nanddev_set_of_node() - Attach a DT node to a NAND device
398 * Attach a DT node to a NAND device.
400 static inline void nanddev_set_of_node(struct nand_device
*nand
,
401 const struct device_node
*np
)
403 mtd_set_of_node(nand
->mtd
, np
);
407 * nanddev_get_of_node() - Retrieve the DT node attached to a NAND device
410 * Return: the DT node attached to @nand.
412 static inline const struct device_node
*nanddev_get_of_node(struct nand_device
*nand
)
414 return mtd_get_of_node(nand
->mtd
);
418 * nanddev_offs_to_pos() - Convert an absolute NAND offset into a NAND position
420 * @offs: absolute NAND offset (usually passed by the MTD layer)
421 * @pos: a NAND position object to fill in
423 * Converts @offs into a nand_pos representation.
425 * Return: the offset within the NAND page pointed by @pos.
427 static inline unsigned int nanddev_offs_to_pos(struct nand_device
*nand
,
429 struct nand_pos
*pos
)
431 unsigned int pageoffs
;
434 pageoffs
= do_div(tmp
, nand
->memorg
.pagesize
);
435 pos
->page
= do_div(tmp
, nand
->memorg
.pages_per_eraseblock
);
436 pos
->eraseblock
= do_div(tmp
, nand
->memorg
.eraseblocks_per_lun
);
437 pos
->plane
= pos
->eraseblock
% nand
->memorg
.planes_per_lun
;
438 pos
->lun
= do_div(tmp
, nand
->memorg
.luns_per_target
);
445 * nanddev_pos_cmp() - Compare two NAND positions
446 * @a: First NAND position
447 * @b: Second NAND position
449 * Compares two NAND positions.
451 * Return: -1 if @a < @b, 0 if @a == @b and 1 if @a > @b.
453 static inline int nanddev_pos_cmp(const struct nand_pos
*a
,
454 const struct nand_pos
*b
)
456 if (a
->target
!= b
->target
)
457 return a
->target
< b
->target
? -1 : 1;
459 if (a
->lun
!= b
->lun
)
460 return a
->lun
< b
->lun
? -1 : 1;
462 if (a
->eraseblock
!= b
->eraseblock
)
463 return a
->eraseblock
< b
->eraseblock
? -1 : 1;
465 if (a
->page
!= b
->page
)
466 return a
->page
< b
->page
? -1 : 1;
472 * nanddev_pos_to_offs() - Convert a NAND position into an absolute offset
474 * @pos: the NAND position to convert
476 * Converts @pos NAND position into an absolute offset.
478 * Return: the absolute offset. Note that @pos points to the beginning of a
479 * page, if one wants to point to a specific offset within this page
480 * the returned offset has to be adjusted manually.
482 static inline loff_t
nanddev_pos_to_offs(struct nand_device
*nand
,
483 const struct nand_pos
*pos
)
490 (pos
->target
* nand
->memorg
.luns_per_target
)) *
491 nand
->memorg
.eraseblocks_per_lun
) *
492 nand
->memorg
.pages_per_eraseblock
);
494 return (loff_t
)npages
* nand
->memorg
.pagesize
;
498 * nanddev_pos_to_row() - Extract a row address from a NAND position
500 * @pos: the position to convert
502 * Converts a NAND position into a row address that can then be passed to the
505 * Return: the row address extracted from @pos.
507 static inline unsigned int nanddev_pos_to_row(struct nand_device
*nand
,
508 const struct nand_pos
*pos
)
510 return (pos
->lun
<< nand
->rowconv
.lun_addr_shift
) |
511 (pos
->eraseblock
<< nand
->rowconv
.eraseblock_addr_shift
) |
516 * nanddev_pos_next_target() - Move a position to the next target/die
518 * @pos: the position to update
520 * Updates @pos to point to the start of the next target/die. Useful when you
521 * want to iterate over all targets/dies of a NAND device.
523 static inline void nanddev_pos_next_target(struct nand_device
*nand
,
524 struct nand_pos
*pos
)
534 * nanddev_pos_next_lun() - Move a position to the next LUN
536 * @pos: the position to update
538 * Updates @pos to point to the start of the next LUN. Useful when you want to
539 * iterate over all LUNs of a NAND device.
541 static inline void nanddev_pos_next_lun(struct nand_device
*nand
,
542 struct nand_pos
*pos
)
544 if (pos
->lun
>= nand
->memorg
.luns_per_target
- 1)
545 return nanddev_pos_next_target(nand
, pos
);
554 * nanddev_pos_next_eraseblock() - Move a position to the next eraseblock
556 * @pos: the position to update
558 * Updates @pos to point to the start of the next eraseblock. Useful when you
559 * want to iterate over all eraseblocks of a NAND device.
561 static inline void nanddev_pos_next_eraseblock(struct nand_device
*nand
,
562 struct nand_pos
*pos
)
564 if (pos
->eraseblock
>= nand
->memorg
.eraseblocks_per_lun
- 1)
565 return nanddev_pos_next_lun(nand
, pos
);
569 pos
->plane
= pos
->eraseblock
% nand
->memorg
.planes_per_lun
;
573 * nanddev_pos_next_eraseblock() - Move a position to the next page
575 * @pos: the position to update
577 * Updates @pos to point to the start of the next page. Useful when you want to
578 * iterate over all pages of a NAND device.
580 static inline void nanddev_pos_next_page(struct nand_device
*nand
,
581 struct nand_pos
*pos
)
583 if (pos
->page
>= nand
->memorg
.pages_per_eraseblock
- 1)
584 return nanddev_pos_next_eraseblock(nand
, pos
);
590 * nand_io_iter_init - Initialize a NAND I/O iterator
592 * @offs: absolute offset
594 * @iter: NAND I/O iterator
596 * Initializes a NAND iterator based on the information passed by the MTD
599 static inline void nanddev_io_iter_init(struct nand_device
*nand
,
600 loff_t offs
, struct mtd_oob_ops
*req
,
601 struct nand_io_iter
*iter
)
603 struct mtd_info
*mtd
= nanddev_to_mtd(nand
);
605 iter
->req
.mode
= req
->mode
;
606 iter
->req
.dataoffs
= nanddev_offs_to_pos(nand
, offs
, &iter
->req
.pos
);
607 iter
->req
.ooboffs
= req
->ooboffs
;
608 iter
->oobbytes_per_page
= mtd_oobavail(mtd
, req
);
609 iter
->dataleft
= req
->len
;
610 iter
->oobleft
= req
->ooblen
;
611 iter
->req
.databuf
.in
= req
->datbuf
;
612 iter
->req
.datalen
= min_t(unsigned int,
613 nand
->memorg
.pagesize
- iter
->req
.dataoffs
,
615 iter
->req
.oobbuf
.in
= req
->oobbuf
;
616 iter
->req
.ooblen
= min_t(unsigned int,
617 iter
->oobbytes_per_page
- iter
->req
.ooboffs
,
622 * nand_io_iter_next_page - Move to the next page
624 * @iter: NAND I/O iterator
626 * Updates the @iter to point to the next page.
628 static inline void nanddev_io_iter_next_page(struct nand_device
*nand
,
629 struct nand_io_iter
*iter
)
631 nanddev_pos_next_page(nand
, &iter
->req
.pos
);
632 iter
->dataleft
-= iter
->req
.datalen
;
633 iter
->req
.databuf
.in
+= iter
->req
.datalen
;
634 iter
->oobleft
-= iter
->req
.ooblen
;
635 iter
->req
.oobbuf
.in
+= iter
->req
.ooblen
;
636 iter
->req
.dataoffs
= 0;
637 iter
->req
.ooboffs
= 0;
638 iter
->req
.datalen
= min_t(unsigned int, nand
->memorg
.pagesize
,
640 iter
->req
.ooblen
= min_t(unsigned int, iter
->oobbytes_per_page
,
645 * nand_io_iter_end - Should end iteration or not
647 * @iter: NAND I/O iterator
649 * Check whether @iter has reached the end of the NAND portion it was asked to
652 * Return: true if @iter has reached the end of the iteration request, false
655 static inline bool nanddev_io_iter_end(struct nand_device
*nand
,
656 const struct nand_io_iter
*iter
)
658 if (iter
->dataleft
|| iter
->oobleft
)
665 * nand_io_for_each_page - Iterate over all NAND pages contained in an MTD I/O
668 * @start: start address to read/write from
669 * @req: MTD I/O request
670 * @iter: NAND I/O iterator
672 * Should be used for iterate over pages that are contained in an MTD request.
674 #define nanddev_io_for_each_page(nand, start, req, iter) \
675 for (nanddev_io_iter_init(nand, start, req, iter); \
676 !nanddev_io_iter_end(nand, iter); \
677 nanddev_io_iter_next_page(nand, iter))
679 bool nanddev_isbad(struct nand_device
*nand
, const struct nand_pos
*pos
);
680 bool nanddev_isreserved(struct nand_device
*nand
, const struct nand_pos
*pos
);
681 int nanddev_erase(struct nand_device
*nand
, const struct nand_pos
*pos
);
682 int nanddev_markbad(struct nand_device
*nand
, const struct nand_pos
*pos
);
684 /* BBT related functions */
685 enum nand_bbt_block_status
{
686 NAND_BBT_BLOCK_STATUS_UNKNOWN
,
689 NAND_BBT_BLOCK_RESERVED
,
690 NAND_BBT_BLOCK_FACTORY_BAD
,
691 NAND_BBT_BLOCK_NUM_STATUS
,
694 int nanddev_bbt_init(struct nand_device
*nand
);
695 void nanddev_bbt_cleanup(struct nand_device
*nand
);
696 int nanddev_bbt_update(struct nand_device
*nand
);
697 int nanddev_bbt_get_block_status(const struct nand_device
*nand
,
699 int nanddev_bbt_set_block_status(struct nand_device
*nand
, unsigned int entry
,
700 enum nand_bbt_block_status status
);
701 int nanddev_bbt_markbad(struct nand_device
*nand
, unsigned int block
);
704 * nanddev_bbt_pos_to_entry() - Convert a NAND position into a BBT entry
706 * @pos: the NAND position we want to get BBT entry for
708 * Return the BBT entry used to store information about the eraseblock pointed
711 * Return: the BBT entry storing information about eraseblock pointed by @pos.
713 static inline unsigned int nanddev_bbt_pos_to_entry(struct nand_device
*nand
,
714 const struct nand_pos
*pos
)
716 return pos
->eraseblock
+
717 ((pos
->lun
+ (pos
->target
* nand
->memorg
.luns_per_target
)) *
718 nand
->memorg
.eraseblocks_per_lun
);
722 * nanddev_bbt_is_initialized() - Check if the BBT has been initialized
725 * Return: true if the BBT has been initialized, false otherwise.
727 static inline bool nanddev_bbt_is_initialized(struct nand_device
*nand
)
729 return !!nand
->bbt
.cache
;
732 /* MTD -> NAND helper functions. */
733 int nanddev_mtd_erase(struct mtd_info
*mtd
, struct erase_info
*einfo
);
735 #endif /* __LINUX_MTD_NAND_H */