// SPDX-License-Identifier: GPL-2.0+ /* * Generic Error-Correcting Code (ECC) engine * * Copyright (C) 2019 Macronix * Author: * Miquèl RAYNAL <[email protected]> * * * This file describes the abstraction of any NAND ECC engine. It has been * designed to fit most cases, including parallel NANDs and SPI-NANDs. * * There are three main situations where instantiating this ECC engine makes * sense: * - external: The ECC engine is outside the NAND pipeline, typically this * is a software ECC engine, or an hardware engine that is * outside the NAND controller pipeline. * - pipelined: The ECC engine is inside the NAND pipeline, ie. on the * controller's side. This is the case of most of the raw NAND * controllers. In the pipeline case, the ECC bytes are * generated/data corrected on the fly when a page is * written/read. * - ondie: The ECC engine is inside the NAND pipeline, on the chip's side. * Some NAND chips can correct themselves the data. * * Besides the initial setup and final cleanups, the interfaces are rather * simple: * - prepare: Prepare an I/O request. Enable/disable the ECC engine based on * the I/O request type. In case of software correction or external * engine, this step may involve to derive the ECC bytes and place * them in the OOB area before a write. * - finish: Finish an I/O request. Correct the data in case of a read * request and report the number of corrected bits/uncorrectable * errors. Most likely empty for write operations, unless you have * hardware specific stuff to do, like shutting down the engine to * save power. * * The I/O request should be enclosed in a prepare()/finish() pair of calls * and will behave differently depending on the requested I/O type: * - raw: Correction disabled * - ecc: Correction enabled * * The request direction is impacting the logic as well: * - read: Load data from the NAND chip * - write: Store data in the NAND chip * * Mixing all this combinations together gives the following behavior. * Those are just examples, drivers are free to add custom steps in their * prepare/finish hook. * * [external ECC engine] * - external + prepare + raw + read: do nothing * - external + finish + raw + read: do nothing * - external + prepare + raw + write: do nothing * - external + finish + raw + write: do nothing * - external + prepare + ecc + read: do nothing * - external + finish + ecc + read: calculate expected ECC bytes, extract * ECC bytes from OOB buffer, correct * and report any bitflip/error * - external + prepare + ecc + write: calculate ECC bytes and store them at * the right place in the OOB buffer based * on the OOB layout * - external + finish + ecc + write: do nothing * * [pipelined ECC engine] * - pipelined + prepare + raw + read: disable the controller's ECC engine if * activated * - pipelined + finish + raw + read: do nothing * - pipelined + prepare + raw + write: disable the controller's ECC engine if * activated * - pipelined + finish + raw + write: do nothing * - pipelined + prepare + ecc + read: enable the controller's ECC engine if * deactivated * - pipelined + finish + ecc + read: check the status, report any * error/bitflip * - pipelined + prepare + ecc + write: enable the controller's ECC engine if * deactivated * - pipelined + finish + ecc + write: do nothing * * [ondie ECC engine] * - ondie + prepare + raw + read: send commands to disable the on-chip ECC * engine if activated * - ondie + finish + raw + read: do nothing * - ondie + prepare + raw + write: send commands to disable the on-chip ECC * engine if activated * - ondie + finish + raw + write: do nothing * - ondie + prepare + ecc + read: send commands to enable the on-chip ECC * engine if deactivated * - ondie + finish + ecc + read: send commands to check the status, report * any error/bitflip * - ondie + prepare + ecc + write: send commands to enable the on-chip ECC * engine if deactivated * - ondie + finish + ecc + write: do nothing */ #include <linux/module.h> #include <linux/mtd/nand.h> #include <linux/platform_device.h> #include <linux/slab.h> #include <linux/of.h> #include <linux/of_platform.h> static LIST_HEAD(on_host_hw_engines); static DEFINE_MUTEX(on_host_hw_engines_mutex); /** * nand_ecc_init_ctx - Init the ECC engine context * @nand: the NAND device * * On success, the caller is responsible of calling @nand_ecc_cleanup_ctx(). */ int nand_ecc_init_ctx(struct nand_device *nand) { … } EXPORT_SYMBOL(…); /** * nand_ecc_cleanup_ctx - Cleanup the ECC engine context * @nand: the NAND device */ void nand_ecc_cleanup_ctx(struct nand_device *nand) { … } EXPORT_SYMBOL(…); /** * nand_ecc_prepare_io_req - Prepare an I/O request * @nand: the NAND device * @req: the I/O request */ int nand_ecc_prepare_io_req(struct nand_device *nand, struct nand_page_io_req *req) { … } EXPORT_SYMBOL(…); /** * nand_ecc_finish_io_req - Finish an I/O request * @nand: the NAND device * @req: the I/O request */ int nand_ecc_finish_io_req(struct nand_device *nand, struct nand_page_io_req *req) { … } EXPORT_SYMBOL(…); /* Define default OOB placement schemes for large and small page devices */ static int nand_ooblayout_ecc_sp(struct mtd_info *mtd, int section, struct mtd_oob_region *oobregion) { … } static int nand_ooblayout_free_sp(struct mtd_info *mtd, int section, struct mtd_oob_region *oobregion) { … } static const struct mtd_ooblayout_ops nand_ooblayout_sp_ops = …; const struct mtd_ooblayout_ops *nand_get_small_page_ooblayout(void) { … } EXPORT_SYMBOL_GPL(…); static int nand_ooblayout_ecc_lp(struct mtd_info *mtd, int section, struct mtd_oob_region *oobregion) { … } static int nand_ooblayout_free_lp(struct mtd_info *mtd, int section, struct mtd_oob_region *oobregion) { … } static const struct mtd_ooblayout_ops nand_ooblayout_lp_ops = …; const struct mtd_ooblayout_ops *nand_get_large_page_ooblayout(void) { … } EXPORT_SYMBOL_GPL(…); /* * Support the old "large page" layout used for 1-bit Hamming ECC where ECC * are placed at a fixed offset. */ static int nand_ooblayout_ecc_lp_hamming(struct mtd_info *mtd, int section, struct mtd_oob_region *oobregion) { … } static int nand_ooblayout_free_lp_hamming(struct mtd_info *mtd, int section, struct mtd_oob_region *oobregion) { … } static const struct mtd_ooblayout_ops nand_ooblayout_lp_hamming_ops = …; const struct mtd_ooblayout_ops *nand_get_large_page_hamming_ooblayout(void) { … } EXPORT_SYMBOL_GPL(…); static enum nand_ecc_engine_type of_get_nand_ecc_engine_type(struct device_node *np) { … } static const char * const nand_ecc_placement[] = …; static enum nand_ecc_placement of_get_nand_ecc_placement(struct device_node *np) { … } static const char * const nand_ecc_algos[] = …; static enum nand_ecc_algo of_get_nand_ecc_algo(struct device_node *np) { … } static int of_get_nand_ecc_step_size(struct device_node *np) { … } static int of_get_nand_ecc_strength(struct device_node *np) { … } void of_get_nand_ecc_user_config(struct nand_device *nand) { … } EXPORT_SYMBOL(…); /** * nand_ecc_is_strong_enough - Check if the chip configuration meets the * datasheet requirements. * * @nand: Device to check * * If our configuration corrects A bits per B bytes and the minimum * required correction level is X bits per Y bytes, then we must ensure * both of the following are true: * * (1) A / B >= X / Y * (2) A >= X * * Requirement (1) ensures we can correct for the required bitflip density. * Requirement (2) ensures we can correct even when all bitflips are clumped * in the same sector. */ bool nand_ecc_is_strong_enough(struct nand_device *nand) { … } EXPORT_SYMBOL(…); /* ECC engine driver internal helpers */ int nand_ecc_init_req_tweaking(struct nand_ecc_req_tweak_ctx *ctx, struct nand_device *nand) { … } EXPORT_SYMBOL_GPL(…); void nand_ecc_cleanup_req_tweaking(struct nand_ecc_req_tweak_ctx *ctx) { … } EXPORT_SYMBOL_GPL(…); /* * Ensure data and OOB area is fully read/written otherwise the correction might * not work as expected. */ void nand_ecc_tweak_req(struct nand_ecc_req_tweak_ctx *ctx, struct nand_page_io_req *req) { … } EXPORT_SYMBOL_GPL(…); void nand_ecc_restore_req(struct nand_ecc_req_tweak_ctx *ctx, struct nand_page_io_req *req) { … } EXPORT_SYMBOL_GPL(…); struct nand_ecc_engine *nand_ecc_get_sw_engine(struct nand_device *nand) { … } EXPORT_SYMBOL(…); struct nand_ecc_engine *nand_ecc_get_on_die_hw_engine(struct nand_device *nand) { … } EXPORT_SYMBOL(…); int nand_ecc_register_on_host_hw_engine(struct nand_ecc_engine *engine) { … } EXPORT_SYMBOL(…); int nand_ecc_unregister_on_host_hw_engine(struct nand_ecc_engine *engine) { … } EXPORT_SYMBOL(…); static struct nand_ecc_engine *nand_ecc_match_on_host_hw_engine(struct device *dev) { … } struct nand_ecc_engine *nand_ecc_get_on_host_hw_engine(struct nand_device *nand) { … } EXPORT_SYMBOL(…); void nand_ecc_put_on_host_hw_engine(struct nand_device *nand) { … } EXPORT_SYMBOL(…); /* * In the case of a pipelined engine, the device registering the ECC * engine is not necessarily the ECC engine itself but may be a host controller. * It is then useful to provide a helper to retrieve the right device object * which actually represents the ECC engine. */ struct device *nand_ecc_get_engine_dev(struct device *host) { … } MODULE_LICENSE(…) …; MODULE_AUTHOR(…) …; MODULE_DESCRIPTION(…) …;
Codebase Browser
linux