// SPDX-License-Identifier: GPL-2.0-or-later /* * Copyright (c) International Business Machines Corp., 2006 * * Author: Artem Bityutskiy (Битюцкий Артём) */ /* * The UBI Eraseblock Association (EBA) sub-system. * * This sub-system is responsible for I/O to/from logical eraseblock. * * Although in this implementation the EBA table is fully kept and managed in * RAM, which assumes poor scalability, it might be (partially) maintained on * flash in future implementations. * * The EBA sub-system implements per-logical eraseblock locking. Before * accessing a logical eraseblock it is locked for reading or writing. The * per-logical eraseblock locking is implemented by means of the lock tree. The * lock tree is an RB-tree which refers all the currently locked logical * eraseblocks. The lock tree elements are &struct ubi_ltree_entry objects. * They are indexed by (@vol_id, @lnum) pairs. * * EBA also maintains the global sequence counter which is incremented each * time a logical eraseblock is mapped to a physical eraseblock and it is * stored in the volume identifier header. This means that each VID header has * a unique sequence number. The sequence number is only increased an we assume * 64 bits is enough to never overflow. */ #include <linux/slab.h> #include <linux/crc32.h> #include <linux/err.h> #include "ubi.h" /** * struct ubi_eba_entry - structure encoding a single LEB -> PEB association * @pnum: the physical eraseblock number attached to the LEB * * This structure is encoding a LEB -> PEB association. Note that the LEB * number is not stored here, because it is the index used to access the * entries table. */ struct ubi_eba_entry { … }; /** * struct ubi_eba_table - LEB -> PEB association information * @entries: the LEB to PEB mapping (one entry per LEB). * * This structure is private to the EBA logic and should be kept here. * It is encoding the LEB to PEB association table, and is subject to * changes. */ struct ubi_eba_table { … }; /** * ubi_next_sqnum - get next sequence number. * @ubi: UBI device description object * * This function returns next sequence number to use, which is just the current * global sequence counter value. It also increases the global sequence * counter. */ unsigned long long ubi_next_sqnum(struct ubi_device *ubi) { … } /** * ubi_get_compat - get compatibility flags of a volume. * @ubi: UBI device description object * @vol_id: volume ID * * This function returns compatibility flags for an internal volume. User * volumes have no compatibility flags, so %0 is returned. */ static int ubi_get_compat(const struct ubi_device *ubi, int vol_id) { … } /** * ubi_eba_get_ldesc - get information about a LEB * @vol: volume description object * @lnum: logical eraseblock number * @ldesc: the LEB descriptor to fill * * Used to query information about a specific LEB. * It is currently only returning the physical position of the LEB, but will be * extended to provide more information. */ void ubi_eba_get_ldesc(struct ubi_volume *vol, int lnum, struct ubi_eba_leb_desc *ldesc) { … } /** * ubi_eba_create_table - allocate a new EBA table and initialize it with all * LEBs unmapped * @vol: volume containing the EBA table to copy * @nentries: number of entries in the table * * Allocate a new EBA table and initialize it with all LEBs unmapped. * Returns a valid pointer if it succeed, an ERR_PTR() otherwise. */ struct ubi_eba_table *ubi_eba_create_table(struct ubi_volume *vol, int nentries) { … } /** * ubi_eba_destroy_table - destroy an EBA table * @tbl: the table to destroy * * Destroy an EBA table. */ void ubi_eba_destroy_table(struct ubi_eba_table *tbl) { … } /** * ubi_eba_copy_table - copy the EBA table attached to vol into another table * @vol: volume containing the EBA table to copy * @dst: destination * @nentries: number of entries to copy * * Copy the EBA table stored in vol into the one pointed by dst. */ void ubi_eba_copy_table(struct ubi_volume *vol, struct ubi_eba_table *dst, int nentries) { … } /** * ubi_eba_replace_table - assign a new EBA table to a volume * @vol: volume containing the EBA table to copy * @tbl: new EBA table * * Assign a new EBA table to the volume and release the old one. */ void ubi_eba_replace_table(struct ubi_volume *vol, struct ubi_eba_table *tbl) { … } /** * ltree_lookup - look up the lock tree. * @ubi: UBI device description object * @vol_id: volume ID * @lnum: logical eraseblock number * * This function returns a pointer to the corresponding &struct ubi_ltree_entry * object if the logical eraseblock is locked and %NULL if it is not. * @ubi->ltree_lock has to be locked. */ static struct ubi_ltree_entry *ltree_lookup(struct ubi_device *ubi, int vol_id, int lnum) { … } /** * ltree_add_entry - add new entry to the lock tree. * @ubi: UBI device description object * @vol_id: volume ID * @lnum: logical eraseblock number * * This function adds new entry for logical eraseblock (@vol_id, @lnum) to the * lock tree. If such entry is already there, its usage counter is increased. * Returns pointer to the lock tree entry or %-ENOMEM if memory allocation * failed. */ static struct ubi_ltree_entry *ltree_add_entry(struct ubi_device *ubi, int vol_id, int lnum) { … } /** * leb_read_lock - lock logical eraseblock for reading. * @ubi: UBI device description object * @vol_id: volume ID * @lnum: logical eraseblock number * * This function locks a logical eraseblock for reading. Returns zero in case * of success and a negative error code in case of failure. */ static int leb_read_lock(struct ubi_device *ubi, int vol_id, int lnum) { … } /** * leb_read_unlock - unlock logical eraseblock. * @ubi: UBI device description object * @vol_id: volume ID * @lnum: logical eraseblock number */ static void leb_read_unlock(struct ubi_device *ubi, int vol_id, int lnum) { … } /** * leb_write_lock - lock logical eraseblock for writing. * @ubi: UBI device description object * @vol_id: volume ID * @lnum: logical eraseblock number * * This function locks a logical eraseblock for writing. Returns zero in case * of success and a negative error code in case of failure. */ static int leb_write_lock(struct ubi_device *ubi, int vol_id, int lnum) { … } /** * leb_write_trylock - try to lock logical eraseblock for writing. * @ubi: UBI device description object * @vol_id: volume ID * @lnum: logical eraseblock number * * This function locks a logical eraseblock for writing if there is no * contention and does nothing if there is contention. Returns %0 in case of * success, %1 in case of contention, and a negative error code in case of * failure. */ static int leb_write_trylock(struct ubi_device *ubi, int vol_id, int lnum) { … } /** * leb_write_unlock - unlock logical eraseblock. * @ubi: UBI device description object * @vol_id: volume ID * @lnum: logical eraseblock number */ static void leb_write_unlock(struct ubi_device *ubi, int vol_id, int lnum) { … } /** * ubi_eba_is_mapped - check if a LEB is mapped. * @vol: volume description object * @lnum: logical eraseblock number * * This function returns true if the LEB is mapped, false otherwise. */ bool ubi_eba_is_mapped(struct ubi_volume *vol, int lnum) { … } /** * ubi_eba_unmap_leb - un-map logical eraseblock. * @ubi: UBI device description object * @vol: volume description object * @lnum: logical eraseblock number * * This function un-maps logical eraseblock @lnum and schedules corresponding * physical eraseblock for erasure. Returns zero in case of success and a * negative error code in case of failure. */ int ubi_eba_unmap_leb(struct ubi_device *ubi, struct ubi_volume *vol, int lnum) { … } #ifdef CONFIG_MTD_UBI_FASTMAP /** * check_mapping - check and fixup a mapping * @ubi: UBI device description object * @vol: volume description object * @lnum: logical eraseblock number * @pnum: physical eraseblock number * * Checks whether a given mapping is valid. Fastmap cannot track LEB unmap * operations, if such an operation is interrupted the mapping still looks * good, but upon first read an ECC is reported to the upper layer. * Normaly during the full-scan at attach time this is fixed, for Fastmap * we have to deal with it while reading. * If the PEB behind a LEB shows this symthom we change the mapping to * %UBI_LEB_UNMAPPED and schedule the PEB for erasure. * * Returns 0 on success, negative error code in case of failure. */ static int check_mapping(struct ubi_device *ubi, struct ubi_volume *vol, int lnum, int *pnum) { … } #else static int check_mapping(struct ubi_device *ubi, struct ubi_volume *vol, int lnum, int *pnum) { return 0; } #endif /** * ubi_eba_read_leb - read data. * @ubi: UBI device description object * @vol: volume description object * @lnum: logical eraseblock number * @buf: buffer to store the read data * @offset: offset from where to read * @len: how many bytes to read * @check: data CRC check flag * * If the logical eraseblock @lnum is unmapped, @buf is filled with 0xFF * bytes. The @check flag only makes sense for static volumes and forces * eraseblock data CRC checking. * * In case of success this function returns zero. In case of a static volume, * if data CRC mismatches - %-EBADMSG is returned. %-EBADMSG may also be * returned for any volume type if an ECC error was detected by the MTD device * driver. Other negative error cored may be returned in case of other errors. */ int ubi_eba_read_leb(struct ubi_device *ubi, struct ubi_volume *vol, int lnum, void *buf, int offset, int len, int check) { … } /** * ubi_eba_read_leb_sg - read data into a scatter gather list. * @ubi: UBI device description object * @vol: volume description object * @lnum: logical eraseblock number * @sgl: UBI scatter gather list to store the read data * @offset: offset from where to read * @len: how many bytes to read * @check: data CRC check flag * * This function works exactly like ubi_eba_read_leb(). But instead of * storing the read data into a buffer it writes to an UBI scatter gather * list. */ int ubi_eba_read_leb_sg(struct ubi_device *ubi, struct ubi_volume *vol, struct ubi_sgl *sgl, int lnum, int offset, int len, int check) { … } /** * try_recover_peb - try to recover from write failure. * @vol: volume description object * @pnum: the physical eraseblock to recover * @lnum: logical eraseblock number * @buf: data which was not written because of the write failure * @offset: offset of the failed write * @len: how many bytes should have been written * @vidb: VID buffer * @retry: whether the caller should retry in case of failure * * This function is called in case of a write failure and moves all good data * from the potentially bad physical eraseblock to a good physical eraseblock. * This function also writes the data which was not written due to the failure. * Returns 0 in case of success, and a negative error code in case of failure. * In case of failure, the %retry parameter is set to false if this is a fatal * error (retrying won't help), and true otherwise. */ static int try_recover_peb(struct ubi_volume *vol, int pnum, int lnum, const void *buf, int offset, int len, struct ubi_vid_io_buf *vidb, bool *retry) { … } /** * recover_peb - recover from write failure. * @ubi: UBI device description object * @pnum: the physical eraseblock to recover * @vol_id: volume ID * @lnum: logical eraseblock number * @buf: data which was not written because of the write failure * @offset: offset of the failed write * @len: how many bytes should have been written * * This function is called in case of a write failure and moves all good data * from the potentially bad physical eraseblock to a good physical eraseblock. * This function also writes the data which was not written due to the failure. * Returns 0 in case of success, and a negative error code in case of failure. * This function tries %UBI_IO_RETRIES before giving up. */ static int recover_peb(struct ubi_device *ubi, int pnum, int vol_id, int lnum, const void *buf, int offset, int len) { … } /** * try_write_vid_and_data - try to write VID header and data to a new PEB. * @vol: volume description object * @lnum: logical eraseblock number * @vidb: the VID buffer to write * @buf: buffer containing the data * @offset: where to start writing data * @len: how many bytes should be written * * This function tries to write VID header and data belonging to logical * eraseblock @lnum of volume @vol to a new physical eraseblock. Returns zero * in case of success and a negative error code in case of failure. * In case of error, it is possible that something was still written to the * flash media, but may be some garbage. */ static int try_write_vid_and_data(struct ubi_volume *vol, int lnum, struct ubi_vid_io_buf *vidb, const void *buf, int offset, int len) { … } /** * ubi_eba_write_leb - write data to dynamic volume. * @ubi: UBI device description object * @vol: volume description object * @lnum: logical eraseblock number * @buf: the data to write * @offset: offset within the logical eraseblock where to write * @len: how many bytes to write * * This function writes data to logical eraseblock @lnum of a dynamic volume * @vol. Returns zero in case of success and a negative error code in case * of failure. In case of error, it is possible that something was still * written to the flash media, but may be some garbage. * This function retries %UBI_IO_RETRIES times before giving up. */ int ubi_eba_write_leb(struct ubi_device *ubi, struct ubi_volume *vol, int lnum, const void *buf, int offset, int len) { … } /** * ubi_eba_write_leb_st - write data to static volume. * @ubi: UBI device description object * @vol: volume description object * @lnum: logical eraseblock number * @buf: data to write * @len: how many bytes to write * @used_ebs: how many logical eraseblocks will this volume contain * * This function writes data to logical eraseblock @lnum of static volume * @vol. The @used_ebs argument should contain total number of logical * eraseblock in this static volume. * * When writing to the last logical eraseblock, the @len argument doesn't have * to be aligned to the minimal I/O unit size. Instead, it has to be equivalent * to the real data size, although the @buf buffer has to contain the * alignment. In all other cases, @len has to be aligned. * * It is prohibited to write more than once to logical eraseblocks of static * volumes. This function returns zero in case of success and a negative error * code in case of failure. */ int ubi_eba_write_leb_st(struct ubi_device *ubi, struct ubi_volume *vol, int lnum, const void *buf, int len, int used_ebs) { … } /* * ubi_eba_atomic_leb_change - change logical eraseblock atomically. * @ubi: UBI device description object * @vol: volume description object * @lnum: logical eraseblock number * @buf: data to write * @len: how many bytes to write * * This function changes the contents of a logical eraseblock atomically. @buf * has to contain new logical eraseblock data, and @len - the length of the * data, which has to be aligned. This function guarantees that in case of an * unclean reboot the old contents is preserved. Returns zero in case of * success and a negative error code in case of failure. * * UBI reserves one LEB for the "atomic LEB change" operation, so only one * LEB change may be done at a time. This is ensured by @ubi->alc_mutex. */ int ubi_eba_atomic_leb_change(struct ubi_device *ubi, struct ubi_volume *vol, int lnum, const void *buf, int len) { … } /** * is_error_sane - check whether a read error is sane. * @err: code of the error happened during reading * * This is a helper function for 'ubi_eba_copy_leb()' which is called when we * cannot read data from the target PEB (an error @err happened). If the error * code is sane, then we treat this error as non-fatal. Otherwise the error is * fatal and UBI will be switched to R/O mode later. * * The idea is that we try not to switch to R/O mode if the read error is * something which suggests there was a real read problem. E.g., %-EIO. Or a * memory allocation failed (-%ENOMEM). Otherwise, it is safer to switch to R/O * mode, simply because we do not know what happened at the MTD level, and we * cannot handle this. E.g., the underlying driver may have become crazy, and * it is safer to switch to R/O mode to preserve the data. * * And bear in mind, this is about reading from the target PEB, i.e. the PEB * which we have just written. */ static int is_error_sane(int err) { … } /** * ubi_eba_copy_leb - copy logical eraseblock. * @ubi: UBI device description object * @from: physical eraseblock number from where to copy * @to: physical eraseblock number where to copy * @vidb: data structure from where the VID header is derived * * This function copies logical eraseblock from physical eraseblock @from to * physical eraseblock @to. The @vid_hdr buffer may be changed by this * function. Returns: * o %0 in case of success; * o %MOVE_CANCEL_RACE, %MOVE_TARGET_WR_ERR, %MOVE_TARGET_BITFLIPS, etc; * o a negative error code in case of failure. */ int ubi_eba_copy_leb(struct ubi_device *ubi, int from, int to, struct ubi_vid_io_buf *vidb) { … } /** * print_rsvd_warning - warn about not having enough reserved PEBs. * @ubi: UBI device description object * @ai: UBI attach info object * * This is a helper function for 'ubi_eba_init()' which is called when UBI * cannot reserve enough PEBs for bad block handling. This function makes a * decision whether we have to print a warning or not. The algorithm is as * follows: * o if this is a new UBI image, then just print the warning * o if this is an UBI image which has already been used for some time, print * a warning only if we can reserve less than 10% of the expected amount of * the reserved PEB. * * The idea is that when UBI is used, PEBs become bad, and the reserved pool * of PEBs becomes smaller, which is normal and we do not want to scare users * with a warning every time they attach the MTD device. This was an issue * reported by real users. */ static void print_rsvd_warning(struct ubi_device *ubi, struct ubi_attach_info *ai) { … } /** * self_check_eba - run a self check on the EBA table constructed by fastmap. * @ubi: UBI device description object * @ai_fastmap: UBI attach info object created by fastmap * @ai_scan: UBI attach info object created by scanning * * Returns < 0 in case of an internal error, 0 otherwise. * If a bad EBA table entry was found it will be printed out and * ubi_assert() triggers. */ int self_check_eba(struct ubi_device *ubi, struct ubi_attach_info *ai_fastmap, struct ubi_attach_info *ai_scan) { … } /** * ubi_eba_init - initialize the EBA sub-system using attaching information. * @ubi: UBI device description object * @ai: attaching information * * This function returns zero in case of success and a negative error code in * case of failure. */ int ubi_eba_init(struct ubi_device *ubi, struct ubi_attach_info *ai) { … }