Commit 85c6e6e2 authored by Artem Bityutskiy's avatar Artem Bityutskiy
Browse files

UBI: amend commentaries 



Hch asked not to use "unit" for sub-systems, let it be so.
Also some other commentaries modifications.

Signed-off-by: default avatarArtem Bityutskiy <Artem.Bityutskiy@nokia.com>
parent bb84c1a1

drivers/mtd/ubi/build.c

+1 −1
Original line number Diff line number Diff line
@@ -524,7 +524,7 @@ out_si: 
}



/**

 * io_init - initialize I/O unit for a given UBI device.

 * io_init - initialize I/O sub-system for a given UBI device.

 * @ubi: UBI device description object

 *

 * If @ubi->vid_hdr_offset or @ubi->leb_start is zero, default offsets are

drivers/mtd/ubi/debug.h

+3 −3
Original line number Diff line number Diff line
@@ -76,21 +76,21 @@ void ubi_dbg_dump_mkvol_req(const struct ubi_mkvol_req *req); 
#endif /* CONFIG_MTD_UBI_DEBUG_MSG */



#ifdef CONFIG_MTD_UBI_DEBUG_MSG_EBA

/* Messages from the eraseblock association unit */

/* Messages from the eraseblock association sub-system */

#define dbg_eba(fmt, ...) dbg_msg(fmt, ##__VA_ARGS__)

#else

#define dbg_eba(fmt, ...) ({})

#endif



#ifdef CONFIG_MTD_UBI_DEBUG_MSG_WL

/* Messages from the wear-leveling unit */

/* Messages from the wear-leveling sub-system */

#define dbg_wl(fmt, ...) dbg_msg(fmt, ##__VA_ARGS__)

#else

#define dbg_wl(fmt, ...) ({})

#endif



#ifdef CONFIG_MTD_UBI_DEBUG_MSG_IO

/* Messages from the input/output unit */

/* Messages from the input/output sub-system */

#define dbg_io(fmt, ...) dbg_msg(fmt, ##__VA_ARGS__)

#else

#define dbg_io(fmt, ...) ({})

drivers/mtd/ubi/eba.c

+11 −11
Original line number Diff line number Diff line
@@ -19,20 +19,20 @@ 
 */



/*

 * The UBI Eraseblock Association (EBA) unit.

 * The UBI Eraseblock Association (EBA) sub-system.

 *

 * This unit is responsible for I/O to/from logical eraseblock.

 * 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 unit 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.

 * 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
@@ -1128,7 +1128,7 @@ out_unlock_leb: 
}



/**

 * ubi_eba_init_scan - initialize the EBA unit using scanning information.

 * ubi_eba_init_scan - initialize the EBA sub-system using scanning information.

 * @ubi: UBI device description object

 * @si: scanning information

 *
@@ -1143,7 +1143,7 @@ int ubi_eba_init_scan(struct ubi_device *ubi, struct ubi_scan_info *si) 
	struct ubi_scan_leb *seb;

	struct rb_node *rb;



	dbg_eba("initialize EBA unit");

	dbg_eba("initialize EBA sub-system");



	spin_lock_init(&ubi->ltree_lock);

	mutex_init(&ubi->alc_mutex);
@@ -1209,7 +1209,7 @@ int ubi_eba_init_scan(struct ubi_device *ubi, struct ubi_scan_info *si) 
		ubi->rsvd_pebs  += ubi->beb_rsvd_pebs;

	}



	dbg_eba("EBA unit is initialized");

	dbg_eba("EBA sub-system is initialized");

	return 0;



out_free:

drivers/mtd/ubi/io.c

+11 −11
Original line number Diff line number Diff line
@@ -20,15 +20,15 @@ 
 */



/*

 * UBI input/output unit.

 * UBI input/output sub-system.

 *

 * This unit provides a uniform way to work with all kinds of the underlying

 * MTD devices. It also implements handy functions for reading and writing UBI

 * headers.

 * This sub-system provides a uniform way to work with all kinds of the

 * underlying MTD devices. It also implements handy functions for reading and

 * writing UBI headers.

 *

 * We are trying to have a paranoid mindset and not to trust to what we read

 * from the flash media in order to be more secure and robust. So this unit

 * validates every single header it reads from the flash media.

 * from the flash media in order to be more secure and robust. So this

 * sub-system validates every single header it reads from the flash media.

 *

 * Some words about how the eraseblock headers are stored.

 *
@@ -79,11 +79,11 @@ 
 * 512-byte chunks, we have to allocate one more buffer and copy our VID header

 * to offset 448 of this buffer.

 *

 * The I/O unit does the following trick in order to avoid this extra copy.

 * It always allocates a @ubi->vid_hdr_alsize bytes buffer for the VID header

 * and returns a pointer to offset @ubi->vid_hdr_shift of this buffer. When the

 * VID header is being written out, it shifts the VID header pointer back and

 * writes the whole sub-page.

 * The I/O sub-system does the following trick in order to avoid this extra

 * copy. It always allocates a @ubi->vid_hdr_alsize bytes buffer for the VID

 * header and returns a pointer to offset @ubi->vid_hdr_shift of this buffer.

 * When the VID header is being written out, it shifts the VID header pointer

 * back and writes the whole sub-page.

 */



#include <linux/crc32.h>

drivers/mtd/ubi/scan.c

+15 −13
Original line number Diff line number Diff line
@@ -19,9 +19,9 @@ 
 */



/*

 * UBI scanning unit.

 * UBI scanning sub-system.

 *

 * This unit is responsible for scanning the flash media, checking UBI

 * This sub-system is responsible for scanning the flash media, checking UBI

 * headers and providing complete information about the UBI flash image.

 *

 * The scanning information is represented by a &struct ubi_scan_info' object.
@@ -103,7 +103,7 @@ static int add_to_list(struct ubi_scan_info *si, int pnum, int ec, 
 * non-zero if an inconsistency was found and zero if not.

 *

 * Note, UBI does sanity check of everything it reads from the flash media.

 * Most of the checks are done in the I/O unit. Here we check that the

 * Most of the checks are done in the I/O sub-system. Here we check that the

 * information in the VID header is consistent to the information in other VID

 * headers of the same volume.

 */
@@ -256,8 +256,8 @@ static int compare_lebs(struct ubi_device *ubi, const struct ubi_scan_leb *seb, 
		 * that versions that are close to %0xFFFFFFFF are less then

		 * versions that are close to %0.

		 *

		 * The UBI WL unit guarantees that the number of pending tasks

		 * is not greater then %0x7FFFFFFF. So, if the difference

		 * The UBI WL sub-system guarantees that the number of pending

		 * tasks is not greater then %0x7FFFFFFF. So, if the difference

		 * between any two versions is greater or equivalent to

		 * %0x7FFFFFFF, there was an overflow and the logical

		 * eraseblock with lower version is actually newer then the one
@@ -645,9 +645,9 @@ void ubi_scan_rm_volume(struct ubi_scan_info *si, struct ubi_scan_volume *sv) 
 *

 * This function erases physical eraseblock 'pnum', and writes the erase

 * counter header to it. This function should only be used on UBI device

 * initialization stages, when the EBA unit had not been yet initialized. This

 * function returns zero in case of success and a negative error code in case

 * of failure.

 * initialization stages, when the EBA sub-system had not been yet initialized.

 * This function returns zero in case of success and a negative error code in

 * case of failure.

 */

int ubi_scan_erase_peb(struct ubi_device *ubi, const struct ubi_scan_info *si,

		       int pnum, int ec)
@@ -687,9 +687,10 @@ out_free: 
 * @si: scanning information

 *

 * This function returns a free physical eraseblock. It is supposed to be

 * called on the UBI initialization stages when the wear-leveling unit is not

 * initialized yet. This function picks a physical eraseblocks from one of the

 * lists, writes the EC header if it is needed, and removes it from the list.

 * called on the UBI initialization stages when the wear-leveling sub-system is

 * not initialized yet. This function picks a physical eraseblocks from one of

 * the lists, writes the EC header if it is needed, and removes it from the

 * list.

 *

 * This function returns scanning physical eraseblock information in case of

 * success and an error code in case of failure.
@@ -764,8 +765,9 @@ static int process_eb(struct ubi_device *ubi, struct ubi_scan_info *si, int pnum 
		return err;

	else if (err) {

		/*

		 * FIXME: this is actually duty of the I/O unit to initialize

		 * this, but MTD does not provide enough information.

		 * FIXME: this is actually duty of the I/O sub-system to

		 * initialize this, but MTD does not provide enough

		 * information.

		 */

		si->bad_peb_count += 1;

		return 0;