1 // SPDX-License-Identifier: GPL-2.0+
3 * Generic Error-Correcting Code (ECC) engine
5 * Copyright (C) 2019 Macronix
7 * Miquèl RAYNAL <miquel.raynal@bootlin.com>
10 * This file describes the abstraction of any NAND ECC engine. It has been
11 * designed to fit most cases, including parallel NANDs and SPI-NANDs.
13 * There are three main situations where instantiating this ECC engine makes
15 * - external: The ECC engine is outside the NAND pipeline, typically this
16 * is a software ECC engine, or an hardware engine that is
17 * outside the NAND controller pipeline.
18 * - pipelined: The ECC engine is inside the NAND pipeline, ie. on the
19 * controller's side. This is the case of most of the raw NAND
20 * controllers. In the pipeline case, the ECC bytes are
21 * generated/data corrected on the fly when a page is
23 * - ondie: The ECC engine is inside the NAND pipeline, on the chip's side.
24 * Some NAND chips can correct themselves the data.
26 * Besides the initial setup and final cleanups, the interfaces are rather
28 * - prepare: Prepare an I/O request. Enable/disable the ECC engine based on
29 * the I/O request type. In case of software correction or external
30 * engine, this step may involve to derive the ECC bytes and place
31 * them in the OOB area before a write.
32 * - finish: Finish an I/O request. Correct the data in case of a read
33 * request and report the number of corrected bits/uncorrectable
34 * errors. Most likely empty for write operations, unless you have
35 * hardware specific stuff to do, like shutting down the engine to
38 * The I/O request should be enclosed in a prepare()/finish() pair of calls
39 * and will behave differently depending on the requested I/O type:
40 * - raw: Correction disabled
41 * - ecc: Correction enabled
43 * The request direction is impacting the logic as well:
44 * - read: Load data from the NAND chip
45 * - write: Store data in the NAND chip
47 * Mixing all this combinations together gives the following behavior.
48 * Those are just examples, drivers are free to add custom steps in their
49 * prepare/finish hook.
51 * [external ECC engine]
52 * - external + prepare + raw + read: do nothing
53 * - external + finish + raw + read: do nothing
54 * - external + prepare + raw + write: do nothing
55 * - external + finish + raw + write: do nothing
56 * - external + prepare + ecc + read: do nothing
57 * - external + finish + ecc + read: calculate expected ECC bytes, extract
58 * ECC bytes from OOB buffer, correct
59 * and report any bitflip/error
60 * - external + prepare + ecc + write: calculate ECC bytes and store them at
61 * the right place in the OOB buffer based
63 * - external + finish + ecc + write: do nothing
65 * [pipelined ECC engine]
66 * - pipelined + prepare + raw + read: disable the controller's ECC engine if
68 * - pipelined + finish + raw + read: do nothing
69 * - pipelined + prepare + raw + write: disable the controller's ECC engine if
71 * - pipelined + finish + raw + write: do nothing
72 * - pipelined + prepare + ecc + read: enable the controller's ECC engine if
74 * - pipelined + finish + ecc + read: check the status, report any
76 * - pipelined + prepare + ecc + write: enable the controller's ECC engine if
78 * - pipelined + finish + ecc + write: do nothing
81 * - ondie + prepare + raw + read: send commands to disable the on-chip ECC
83 * - ondie + finish + raw + read: do nothing
84 * - ondie + prepare + raw + write: send commands to disable the on-chip ECC
86 * - ondie + finish + raw + write: do nothing
87 * - ondie + prepare + ecc + read: send commands to enable the on-chip ECC
88 * engine if deactivated
89 * - ondie + finish + ecc + read: send commands to check the status, report
91 * - ondie + prepare + ecc + write: send commands to enable the on-chip ECC
92 * engine if deactivated
93 * - ondie + finish + ecc + write: do nothing
96 #include <linux/module.h>
97 #include <linux/mtd/nand.h>
100 * nand_ecc_init_ctx - Init the ECC engine context
101 * @nand: the NAND device
103 * On success, the caller is responsible of calling @nand_ecc_cleanup_ctx().
105 int nand_ecc_init_ctx(struct nand_device *nand)
107 if (!nand->ecc.engine->ops->init_ctx)
110 return nand->ecc.engine->ops->init_ctx(nand);
112 EXPORT_SYMBOL(nand_ecc_init_ctx);
115 * nand_ecc_cleanup_ctx - Cleanup the ECC engine context
116 * @nand: the NAND device
118 void nand_ecc_cleanup_ctx(struct nand_device *nand)
120 if (nand->ecc.engine->ops->cleanup_ctx)
121 nand->ecc.engine->ops->cleanup_ctx(nand);
123 EXPORT_SYMBOL(nand_ecc_cleanup_ctx);
126 * nand_ecc_prepare_io_req - Prepare an I/O request
127 * @nand: the NAND device
128 * @req: the I/O request
130 int nand_ecc_prepare_io_req(struct nand_device *nand,
131 struct nand_page_io_req *req)
133 if (!nand->ecc.engine->ops->prepare_io_req)
136 return nand->ecc.engine->ops->prepare_io_req(nand, req);
138 EXPORT_SYMBOL(nand_ecc_prepare_io_req);
141 * nand_ecc_finish_io_req - Finish an I/O request
142 * @nand: the NAND device
143 * @req: the I/O request
145 int nand_ecc_finish_io_req(struct nand_device *nand,
146 struct nand_page_io_req *req)
148 if (!nand->ecc.engine->ops->finish_io_req)
151 return nand->ecc.engine->ops->finish_io_req(nand, req);
153 EXPORT_SYMBOL(nand_ecc_finish_io_req);
155 /* Define default OOB placement schemes for large and small page devices */
156 static int nand_ooblayout_ecc_sp(struct mtd_info *mtd, int section,
157 struct mtd_oob_region *oobregion)
159 struct nand_device *nand = mtd_to_nanddev(mtd);
160 unsigned int total_ecc_bytes = nand->ecc.ctx.total;
166 oobregion->offset = 0;
167 if (mtd->oobsize == 16)
168 oobregion->length = 4;
170 oobregion->length = 3;
172 if (mtd->oobsize == 8)
175 oobregion->offset = 6;
176 oobregion->length = total_ecc_bytes - 4;
182 static int nand_ooblayout_free_sp(struct mtd_info *mtd, int section,
183 struct mtd_oob_region *oobregion)
188 if (mtd->oobsize == 16) {
192 oobregion->length = 8;
193 oobregion->offset = 8;
195 oobregion->length = 2;
197 oobregion->offset = 3;
199 oobregion->offset = 6;
205 static const struct mtd_ooblayout_ops nand_ooblayout_sp_ops = {
206 .ecc = nand_ooblayout_ecc_sp,
207 .free = nand_ooblayout_free_sp,
210 const struct mtd_ooblayout_ops *nand_get_small_page_ooblayout(void)
212 return &nand_ooblayout_sp_ops;
214 EXPORT_SYMBOL_GPL(nand_get_small_page_ooblayout);
216 static int nand_ooblayout_ecc_lp(struct mtd_info *mtd, int section,
217 struct mtd_oob_region *oobregion)
219 struct nand_device *nand = mtd_to_nanddev(mtd);
220 unsigned int total_ecc_bytes = nand->ecc.ctx.total;
222 if (section || !total_ecc_bytes)
225 oobregion->length = total_ecc_bytes;
226 oobregion->offset = mtd->oobsize - oobregion->length;
231 static int nand_ooblayout_free_lp(struct mtd_info *mtd, int section,
232 struct mtd_oob_region *oobregion)
234 struct nand_device *nand = mtd_to_nanddev(mtd);
235 unsigned int total_ecc_bytes = nand->ecc.ctx.total;
240 oobregion->length = mtd->oobsize - total_ecc_bytes - 2;
241 oobregion->offset = 2;
246 static const struct mtd_ooblayout_ops nand_ooblayout_lp_ops = {
247 .ecc = nand_ooblayout_ecc_lp,
248 .free = nand_ooblayout_free_lp,
251 const struct mtd_ooblayout_ops *nand_get_large_page_ooblayout(void)
253 return &nand_ooblayout_lp_ops;
255 EXPORT_SYMBOL_GPL(nand_get_large_page_ooblayout);
258 * Support the old "large page" layout used for 1-bit Hamming ECC where ECC
259 * are placed at a fixed offset.
261 static int nand_ooblayout_ecc_lp_hamming(struct mtd_info *mtd, int section,
262 struct mtd_oob_region *oobregion)
264 struct nand_device *nand = mtd_to_nanddev(mtd);
265 unsigned int total_ecc_bytes = nand->ecc.ctx.total;
270 switch (mtd->oobsize) {
272 oobregion->offset = 40;
275 oobregion->offset = 80;
281 oobregion->length = total_ecc_bytes;
282 if (oobregion->offset + oobregion->length > mtd->oobsize)
288 static int nand_ooblayout_free_lp_hamming(struct mtd_info *mtd, int section,
289 struct mtd_oob_region *oobregion)
291 struct nand_device *nand = mtd_to_nanddev(mtd);
292 unsigned int total_ecc_bytes = nand->ecc.ctx.total;
295 if (section < 0 || section > 1)
298 switch (mtd->oobsize) {
310 oobregion->offset = 2;
311 oobregion->length = ecc_offset - 2;
313 oobregion->offset = ecc_offset + total_ecc_bytes;
314 oobregion->length = mtd->oobsize - oobregion->offset;
320 static const struct mtd_ooblayout_ops nand_ooblayout_lp_hamming_ops = {
321 .ecc = nand_ooblayout_ecc_lp_hamming,
322 .free = nand_ooblayout_free_lp_hamming,
325 const struct mtd_ooblayout_ops *nand_get_large_page_hamming_ooblayout(void)
327 return &nand_ooblayout_lp_hamming_ops;
329 EXPORT_SYMBOL_GPL(nand_get_large_page_hamming_ooblayout);
331 static enum nand_ecc_engine_type
332 of_get_nand_ecc_engine_type(struct device_node *np)
334 struct device_node *eng_np;
336 if (of_property_read_bool(np, "nand-no-ecc-engine"))
337 return NAND_ECC_ENGINE_TYPE_NONE;
339 if (of_property_read_bool(np, "nand-use-soft-ecc-engine"))
340 return NAND_ECC_ENGINE_TYPE_SOFT;
342 eng_np = of_parse_phandle(np, "nand-ecc-engine", 0);
347 return NAND_ECC_ENGINE_TYPE_ON_DIE;
349 return NAND_ECC_ENGINE_TYPE_ON_HOST;
352 return NAND_ECC_ENGINE_TYPE_INVALID;
355 static const char * const nand_ecc_placement[] = {
356 [NAND_ECC_PLACEMENT_OOB] = "oob",
357 [NAND_ECC_PLACEMENT_INTERLEAVED] = "interleaved",
360 static enum nand_ecc_placement of_get_nand_ecc_placement(struct device_node *np)
362 enum nand_ecc_placement placement;
366 err = of_property_read_string(np, "nand-ecc-placement", &pm);
368 for (placement = NAND_ECC_PLACEMENT_OOB;
369 placement < ARRAY_SIZE(nand_ecc_placement); placement++) {
370 if (!strcasecmp(pm, nand_ecc_placement[placement]))
375 return NAND_ECC_PLACEMENT_UNKNOWN;
378 static const char * const nand_ecc_algos[] = {
379 [NAND_ECC_ALGO_HAMMING] = "hamming",
380 [NAND_ECC_ALGO_BCH] = "bch",
381 [NAND_ECC_ALGO_RS] = "rs",
384 static enum nand_ecc_algo of_get_nand_ecc_algo(struct device_node *np)
386 enum nand_ecc_algo ecc_algo;
390 err = of_property_read_string(np, "nand-ecc-algo", &pm);
392 for (ecc_algo = NAND_ECC_ALGO_HAMMING;
393 ecc_algo < ARRAY_SIZE(nand_ecc_algos);
395 if (!strcasecmp(pm, nand_ecc_algos[ecc_algo]))
400 return NAND_ECC_ALGO_UNKNOWN;
403 static int of_get_nand_ecc_step_size(struct device_node *np)
408 ret = of_property_read_u32(np, "nand-ecc-step-size", &val);
409 return ret ? ret : val;
412 static int of_get_nand_ecc_strength(struct device_node *np)
417 ret = of_property_read_u32(np, "nand-ecc-strength", &val);
418 return ret ? ret : val;
421 void of_get_nand_ecc_user_config(struct nand_device *nand)
423 struct device_node *dn = nanddev_get_of_node(nand);
426 nand->ecc.user_conf.engine_type = of_get_nand_ecc_engine_type(dn);
427 nand->ecc.user_conf.algo = of_get_nand_ecc_algo(dn);
428 nand->ecc.user_conf.placement = of_get_nand_ecc_placement(dn);
430 strength = of_get_nand_ecc_strength(dn);
432 nand->ecc.user_conf.strength = strength;
434 size = of_get_nand_ecc_step_size(dn);
436 nand->ecc.user_conf.step_size = size;
438 if (of_property_read_bool(dn, "nand-ecc-maximize"))
439 nand->ecc.user_conf.flags |= NAND_ECC_MAXIMIZE_STRENGTH;
441 EXPORT_SYMBOL(of_get_nand_ecc_user_config);
444 * nand_ecc_is_strong_enough - Check if the chip configuration meets the
445 * datasheet requirements.
447 * @nand: Device to check
449 * If our configuration corrects A bits per B bytes and the minimum
450 * required correction level is X bits per Y bytes, then we must ensure
451 * both of the following are true:
456 * Requirement (1) ensures we can correct for the required bitflip density.
457 * Requirement (2) ensures we can correct even when all bitflips are clumped
458 * in the same sector.
460 bool nand_ecc_is_strong_enough(struct nand_device *nand)
462 const struct nand_ecc_props *reqs = nanddev_get_ecc_requirements(nand);
463 const struct nand_ecc_props *conf = nanddev_get_ecc_conf(nand);
464 struct mtd_info *mtd = nanddev_to_mtd(nand);
467 if (conf->step_size == 0 || reqs->step_size == 0)
468 /* Not enough information */
472 * We get the number of corrected bits per page to compare
473 * the correction density.
475 corr = (mtd->writesize * conf->strength) / conf->step_size;
476 ds_corr = (mtd->writesize * reqs->strength) / reqs->step_size;
478 return corr >= ds_corr && conf->strength >= reqs->strength;
480 EXPORT_SYMBOL(nand_ecc_is_strong_enough);
482 MODULE_LICENSE("GPL");
483 MODULE_AUTHOR("Miquel Raynal <miquel.raynal@bootlin.com>");
484 MODULE_DESCRIPTION("Generic ECC engine");