mtd/ubi/ubi.h

1 /* SPDX-License-Identifier: GPL-2.0-or-later */
31 #include "ubi-media.h"
57  * This marker in the EBA table means that the LEB is um-mapped.
60 #define UBI_LEB_UNMAPPED -1
64  * returning error. The below constant defines how many times UBI re-tries.
70  * number of (global) erase cycles PEBs are protected from the wear-leveling
76 #define UBI_UNKNOWN -1
86  * Error codes returned by the I/O sub-system.
91  *                     (uncorrectable ECC error in case of NAND)
95  *                         (uncorrectable ECC error in case of NAND)
96  * UBI_IO_BITFLIPS: bit-flips were detected and corrected
98  * Note, it is probably better to have bit-flip and ebadmsg as flags which can
121  * MOVE_TARGET_BITFLIPS: canceled because a bit-flip was detected in the
135  * Return codes of the fastmap sub-system
157  * struct ubi_vid_io_buf - VID buffer used to read/write VID info to/from the
168  * struct ubi_wl_entry - wear-leveling entry.
169  * @u.rb: link in the corresponding (free/used) RB-tree
174  * This data structure is used in the WL sub-system. Each physical eraseblock
176  * RB-trees. See WL sub-system for details.
188  * struct ubi_ltree_entry - an entry in the lock tree.
189  * @rb: links RB-tree nodes
196  * This data structure is used in the EBA sub-system to implement per-LEB
197  * locking. When a logical eraseblock is being locked - corresponding
198  * &struct ubi_ltree_entry object is inserted to the lock tree (@ubi->ltree).
199  * See EBA sub-system for details.
210  * struct ubi_rename_entry - volume re-name description data structure.
213  * @remove: if not zero, this volume should be removed, not re-named
215  * @list: links re-name entries into a list
217  * This data structure is utilized in the multiple volume re-name code. Namely,
233  * struct ubi_fastmap_layout - in-memory fastmap data structure.
235  * @to_be_tortured: if non-zero tortured this PEB
238  * @max_wl_pool_size: maximal size of the pool used by the WL sub-system
249  * struct ubi_fm_pool - in-memory fastmap pool
268  * struct ubi_eba_leb_desc - EBA logical eraseblock descriptor
283  * struct ubi_volume - UBI volume description data structure.
284  * @dev: device object to make use of the the Linux device model
289  * @readers: number of users holding this volume in read-only mode
290  * @writers: number of users holding this volume in read-write mode
316  * @eba_tbl: EBA table of this volume (LEB->PEB mapping)
327  * @checkmap: bitmap to remember which PEB->LEB mappings got checked,
332  * dynamic volumes - it is user's responsibility to assure their data
381  * struct ubi_volume_desc - UBI volume descriptor returned when it is opened.
394  * struct ubi_debug_info - debugging information for an UBI device.
400  * @emulate_bitflips: emulate bit-flips for testing purposes
404  * @power_cut_min: minimum number of writes before emulating a power cut
412  * @dfs_emulate_bitflips: debugfs knob to emulate bit-flips
415  * @dfs_power_cut_min: debugfs knob for minimum writes before power cut
443  * struct ubi_device - UBI device description structure
444  * @dev: UBI device object to use the the Linux device model
452  *                @vol->readers, @vol->writers, @vol->exclusive,
453  *                @vol->metaonly, @vol->ref_count, @vol->mapping and
454  *                @vol->eba_tbl.
464  * @autoresize_vol_id: ID of the volume which has to be auto-resized at the end
468  * @vtbl: in-RAM volume table copy
469  * @device_mutex: protects on-flash volume table and serializes volume
470  *                creation, deletion, update, re-size, re-name and set
481  * @fm_disabled: non-zero if fastmap is disabled (default)
482  * @fm: in-memory data structure of the currently used fastmap
483  * @fm_pool: in-memory data structure of the fastmap pool
484  * @fm_wl_pool: in-memory data structure of the fastmap pool used by the WL
485  *		sub-system
492  * @fm_work_scheduled: non-zero if fastmap work was scheduled
493  * @fast_attach: non-zero if UBI was attached by fastmap
498  * @used: RB-tree of used physical eraseblocks
499  * @erroneous: RB-tree of erroneous used physical eraseblocks
500  * @free: RB-tree of free physical eraseblocks
502  * @scrub: RB-tree of physical eraseblocks which need scrubbing
504  *      protected from the wear-leveling worker)
513  * @wl_scheduled: non-zero if the wear-leveling was scheduled
537  * @ro_mode: if the UBI device is in read-only mode
547  * @vid_hdr_shift: contains @vid_hdr_offset - @vid_hdr_aloffset
549  * @nor_flash: non-zero if working on top of NOR flash
584 	/* Note, mean_ec is not updated run-time - should be fixed */
587 	/* EBA sub-system's stuff */
609 	/* Wear-leveling sub-system's stuff */
631 	/* I/O sub-system's stuff */
663  * struct ubi_ainf_peb - attach information about a physical eraseblock.
671  * @u: unions RB-tree or @list links
672  * @u.rb: link in the per-volume RB-tree of &struct ubi_ainf_peb objects
694  * struct ubi_ainf_volume - attaching information about a volume.
707  * @rb: link in the volume RB-tree
708  * @root: root of the RB-tree containing all the eraseblock belonging to this
728  * struct ubi_attach_info - MTD device attaching information.
729  * @volumes: root of the volume RB-tree
734  *         those belonging to "preserve"-compatible internal volumes)
760  * be used by other UBI sub-systems to build final UBI data structures, further
761  * error-recovery and so on.
791  * struct ubi_work - UBI work description data structure.
801  * WL sub-system is shutting down.
875 	return lnum >= 0 && lnum < vol->reserved_pebs;  in ubi_leb_valid()
991 	return -ENOSYS;  in ubiblock_create()
995 	return -ENOSYS;  in ubiblock_remove()
1000  * ubi_for_each_free_peb - walk the UBI free RB tree.
1002  * @e: a pointer to a ubi_wl_entry to use as cursor
1003  * @pos: a pointer to RB-tree entry type to use as a loop counter
1006 	ubi_rb_for_each_entry((tmp_rb), (e), &(ubi)->free, u.rb)
1009  * ubi_for_each_used_peb - walk the UBI used RB tree.
1011  * @e: a pointer to a ubi_wl_entry to use as cursor
1012  * @pos: a pointer to RB-tree entry type to use as a loop counter
1015 	ubi_rb_for_each_entry((tmp_rb), (e), &(ubi)->used, u.rb)
1018  * ubi_for_each_scub_peb - walk the UBI scub RB tree.
1020  * @e: a pointer to a ubi_wl_entry to use as cursor
1021  * @pos: a pointer to RB-tree entry type to use as a loop counter
1024 	ubi_rb_for_each_entry((tmp_rb), (e), &(ubi)->scrub, u.rb)
1027  * ubi_for_each_protected_peb - walk the UBI protection queue.
1030  * @e: a pointer to a ubi_wl_entry to use as cursor
1034 		list_for_each_entry((e), &(ubi->pq[(i)]), u.list)
1037  * ubi_rb_for_each_entry - walk an RB-tree.
1038  * @rb: a pointer to type 'struct rb_node' to use as a loop counter
1039  * @pos: a pointer to RB-tree entry type to use as a loop counter
1040  * @root: RB-tree's root
1041  * @member: the name of the 'struct rb_node' within the RB-tree entry
1051  * ubi_move_aeb_to_list - move a PEB from the volume tree to a list.
1061 		rb_erase(&aeb->u.rb, &av->root);  in ubi_move_aeb_to_list()
1062 		list_add_tail(&aeb->u.list, list);  in ubi_move_aeb_to_list()
1066  * ubi_init_vid_buf - Initialize a VID buffer
1076 		memset(buf, 0, ubi->vid_hdr_alsize);  in ubi_init_vid_buf()
1078 	vidb->buffer = buf;  in ubi_init_vid_buf()
1079 	vidb->hdr = buf + ubi->vid_hdr_shift;  in ubi_init_vid_buf()
1083  * ubi_init_vid_buf - Allocate a VID buffer
1085  * @gfp_flags: GFP flags to use for the allocation
1097 	buf = kmalloc(ubi->vid_hdr_alsize, gfp_flags);  in ubi_alloc_vid_buf()
1109  * ubi_free_vid_buf - Free a VID buffer
1117 	kfree(vidb->buffer);  in ubi_free_vid_buf()
1122  * ubi_get_vid_hdr - Get the VID header attached to a VID buffer
1127 	return vidb->hdr;  in ubi_get_vid_hdr()
1139 	return ubi_io_read(ubi, buf, pnum, offset + ubi->leb_start, len);  in ubi_io_read_data()
1151 	return ubi_io_write(ubi, buf, pnum, offset + ubi->leb_start, len);  in ubi_io_write_data()
1155  * ubi_ro_mode - switch to read-only mode.
1160 	if (!ubi->ro_mode) {  in ubi_ro_mode()
1161 		ubi->ro_mode = 1;  in ubi_ro_mode()
1162 		ubi_warn(ubi, "switch to read-only mode");  in ubi_ro_mode()
1168  * vol_id2idx - get table index by volume ID.
1175 		return vol_id - UBI_INTERNAL_VOL_START + ubi->vtbl_slots;  in vol_id2idx()
1181  * idx2vol_id - get volume ID by table index.
1187 	if (idx >= ubi->vtbl_slots)  in idx2vol_id()
1188 		return idx - ubi->vtbl_slots + UBI_INTERNAL_VOL_START;  in idx2vol_id()
1194  * ubi_is_fm_vol - check whether a volume ID is a Fastmap volume.
1209  * ubi_find_fm_block - check whether a PEB is part of the current Fastmap.
1221 	if (ubi->fm) {  in ubi_find_fm_block()
1222 		for (i = 0; i < ubi->fm->used_blocks; i++) {  in ubi_find_fm_block()
1223 			if (ubi->fm->e[i]->pnum == pnum)  in ubi_find_fm_block()
1224 				return ubi->fm->e[i];  in ubi_find_fm_block()