Doug / smarc-fsl-linux-kernel

Download as
Browse Code ยป

Commit fbd0107f4d33be01c9fb2c630036bd66b7e3d4dc

Authored by Artem Bityutskiy
1 parent 1fc2e3e59d
Exists in smarc-l5.0.0_1.0.0-ga and in 5 other branches imx_3.10.17_1.0.1_ga, imx_3.10.53_1.1.0_ga, imx_3.14.28_1.0.0_ga, smarc-imx_3.10.53_1.1.0_ga, smarc-imx_3.14.28_1.0.0_ga

UBI: amend comments after all the renamings 

This patch amends commentaries in scan.[ch] to match the new logic. Reminder -
we did the restructuring to prepare the code for adding the fastmap. This patch
also renames a couple of functions - it was too difficult to separate out that
change and I decided that it is not too bad to have it in the same patch with
commentaries changes.

Signed-off-by: Artem Bityutskiy <artem.bityutskiy@linux.intel.com>

Showing 6 changed files with 73 additions and 81 deletions Side-by-side Diff

drivers/mtd/ubi/build.c
Diff comments   View file @ fbd0107
... ... @@ -27,10 +27,6 @@
27 27 * module load parameters or the kernel boot parameters. If MTD devices were
28 28 * specified, UBI does not attach any MTD device, but it is possible to do
29 29 * later using the "UBI control device".
30   - *
31   - * At the moment we only attach UBI devices by scanning, which will become a
32   - * bottleneck when flashes reach certain large size. Then one may improve UBI
33   - * and add other methods, although it does not seem to be easy to do.
34 30 */
35 31  
36 32 #include <linux/err.h>
37 33  
... ... @@ -790,11 +786,11 @@
790 786 ubi_msg("data offset: %d", ubi->leb_start);
791 787  
792 788 /*
793   - * Note, ideally, we have to initialize ubi->bad_peb_count here. But
  789 + * Note, ideally, we have to initialize @ubi->bad_peb_count here. But
794 790 * unfortunately, MTD does not provide this information. We should loop
795 791 * over all physical eraseblocks and invoke mtd->block_is_bad() for
796   - * each physical eraseblock. So, we skip ubi->bad_peb_count
797   - * uninitialized and initialize it after scanning.
  792 + * each physical eraseblock. So, we leave @ubi->bad_peb_count
  793 + * uninitialized so far.
798 794 */
799 795  
800 796 return 0;
... ... @@ -805,7 +801,7 @@
805 801 * @ubi: UBI device description object
806 802 * @vol_id: ID of the volume to re-size
807 803 *
808   - * This function re-sizes the volume marked by the @UBI_VTBL_AUTORESIZE_FLG in
  804 + * This function re-sizes the volume marked by the %UBI_VTBL_AUTORESIZE_FLG in
809 805 * the volume table to the largest possible size. See comments in ubi-header.h
810 806 * for more description of the flag. Returns zero in case of success and a
811 807 * negative error code in case of failure.
drivers/mtd/ubi/io.c
Diff comments   View file @ fbd0107
... ... @@ -513,8 +513,7 @@
513 513 * It is important to first invalidate the EC header, and then the VID
514 514 * header. Otherwise a power cut may lead to valid EC header and
515 515 * invalid VID header, in which case UBI will treat this PEB as
516   - * corrupted and will try to preserve it, and print scary warnings (see
517   - * the header comment in scan.c for more information).
  516 + * corrupted and will try to preserve it, and print scary warnings.
518 517 */
519 518 addr = (loff_t)pnum * ubi->peb_size;
520 519 err = mtd_write(ubi->mtd, addr, 4, &written, (void *)&data);
drivers/mtd/ubi/scan.c
Diff comments   View file @ fbd0107
... ... @@ -19,21 +19,21 @@
19 19 */
20 20  
21 21 /*
22   - * UBI scanning sub-system.
  22 + * UBI attaching sub-system.
23 23 *
24   - * This sub-system is responsible for scanning the flash media, checking UBI
25   - * headers and providing complete information about the UBI flash image.
  24 + * This sub-system is responsible for attaching MTD devices and it also
  25 + * implements flash media scanning.
26 26 *
27 27 * The attaching information is represented by a &struct ubi_attach_info'
28   - * object. Information about found volumes is represented by
29   - * &struct ubi_ainf_volume objects which are kept in volume RB-tree with root
30   - * at the @volumes field. The RB-tree is indexed by the volume ID.
  28 + * object. Information about volumes is represented by &struct ubi_ainf_volume
  29 + * objects which are kept in volume RB-tree with root at the @volumes field.
  30 + * The RB-tree is indexed by the volume ID.
31 31 *
32   - * Scanned logical eraseblocks are represented by &struct ubi_ainf_peb objects.
33   - * These objects are kept in per-volume RB-trees with the root at the
34   - * corresponding &struct ubi_ainf_volume object. To put it differently, we keep
35   - * an RB-tree of per-volume objects and each of these objects is the root of
36   - * RB-tree of per-eraseblock objects.
  32 + * Logical eraseblocks are represented by &struct ubi_ainf_peb objects. These
  33 + * objects are kept in per-volume RB-trees with the root at the corresponding
  34 + * &struct ubi_ainf_volume object. To put it differently, we keep an RB-tree of
  35 + * per-volume objects and each of these objects is the root of RB-tree of
  36 + * per-LEB objects.
37 37 *
38 38 * Corrupted physical eraseblocks are put to the @corr list, free physical
39 39 * eraseblocks are put to the @free list and the physical eraseblock to be
40 40  
41 41  
... ... @@ -51,28 +51,29 @@
51 51 *
52 52 * 1. Corruptions caused by power cuts. These are expected corruptions and UBI
53 53 * tries to handle them gracefully, without printing too many warnings and
54   - * error messages. The idea is that we do not lose important data in these case
55   - * - we may lose only the data which was being written to the media just before
56   - * the power cut happened, and the upper layers (e.g., UBIFS) are supposed to
57   - * handle such data losses (e.g., by using the FS journal).
  54 + * error messages. The idea is that we do not lose important data in these
  55 + * cases - we may lose only the data which were being written to the media just
  56 + * before the power cut happened, and the upper layers (e.g., UBIFS) are
  57 + * supposed to handle such data losses (e.g., by using the FS journal).
58 58 *
59 59 * When UBI detects a corruption (CRC-32 mismatch) in a PEB, and it looks like
60 60 * the reason is a power cut, UBI puts this PEB to the @erase list, and all
61 61 * PEBs in the @erase list are scheduled for erasure later.
62 62 *
63 63 * 2. Unexpected corruptions which are not caused by power cuts. During
64   - * scanning, such PEBs are put to the @corr list and UBI preserves them.
  64 + * attaching, such PEBs are put to the @corr list and UBI preserves them.
65 65 * Obviously, this lessens the amount of available PEBs, and if at some point
66 66 * UBI runs out of free PEBs, it switches to R/O mode. UBI also loudly informs
67 67 * about such PEBs every time the MTD device is attached.
68 68 *
69 69 * However, it is difficult to reliably distinguish between these types of
70   - * corruptions and UBI's strategy is as follows. UBI assumes corruption type 2
71   - * if the VID header is corrupted and the data area does not contain all 0xFFs,
72   - * and there were no bit-flips or integrity errors while reading the data area.
73   - * Otherwise UBI assumes corruption type 1. So the decision criteria are as
74   - * follows.
75   - * o If the data area contains only 0xFFs, there is no data, and it is safe
  70 + * corruptions and UBI's strategy is as follows (in case of attaching by
  71 + * scanning). UBI assumes corruption type 2 if the VID header is corrupted and
  72 + * the data area does not contain all 0xFFs, and there were no bit-flips or
  73 + * integrity errors (e.g., ECC errors in case of NAND) while reading the data
  74 + * area. Otherwise UBI assumes corruption type 1. So the decision criteria
  75 + * are as follows.
  76 + * o If the data area contains only 0xFFs, there are no data, and it is safe
76 77 * to just erase this PEB - this is corruption type 1.
77 78 * o If the data area has bit-flips or data integrity errors (ECC errors on
78 79 * NAND), it is probably a PEB which was being erased when power cut
... ... @@ -102,7 +103,8 @@
102 103 * @to_head: if not zero, add to the head of the list
103 104 * @list: the list to add to
104 105 *
105   - * This function adds physical eraseblock @pnum to free, erase, or alien lists.
  106 + * This function allocates a 'struct ubi_ainf_peb' object for physical
  107 + * eraseblock @pnum and adds it to the "free", "erase", or "alien" lists.
106 108 * If @to_head is not zero, PEB will be added to the head of the list, which
107 109 * basically means it will be processed first later. E.g., we add corrupted
108 110 * PEBs (corrupted due to power cuts) to the head of the erase list to make
... ... @@ -144,9 +146,10 @@
144 146 * @pnum: physical eraseblock number to add
145 147 * @ec: erase counter of the physical eraseblock
146 148 *
147   - * This function adds corrupted physical eraseblock @pnum to the 'corr' list.
148   - * The corruption was presumably not caused by a power cut. Returns zero in
149   - * case of success and a negative error code in case of failure.
  149 + * This function allocates a 'struct ubi_ainf_peb' object for a corrupted
  150 + * physical eraseblock @pnum and adds it to the 'corr' list. The corruption
  151 + * was presumably not caused by a power cut. Returns zero in case of success
  152 + * and a negative error code in case of failure.
150 153 */
151 154 static int add_corrupted(struct ubi_attach_info *ai, int pnum, int ec)
152 155 {
... ... @@ -241,8 +244,8 @@
241 244 * If the volume corresponding to the @vid_hdr logical eraseblock is already
242 245 * present in the attaching information, this function does nothing. Otherwise
243 246 * it adds corresponding volume to the attaching information. Returns a pointer
244   - * to the scanning volume object in case of success and a negative error code
245   - * in case of failure.
  247 + * to the allocated "av" object in case of success and a negative error code in
  248 + * case of failure.
246 249 */
247 250 static struct ubi_ainf_volume *add_volume(struct ubi_attach_info *ai,
248 251 int vol_id, int pnum,
... ... @@ -425,7 +428,7 @@
425 428 }
426 429  
427 430 /**
428   - * ubi_add_to_av - add physical eraseblock to the attaching information.
  431 + * ubi_add_to_av - add used physical eraseblock to the attaching information.
429 432 * @ubi: UBI device description object
430 433 * @ai: attaching information
431 434 * @pnum: the physical eraseblock number
... ... @@ -692,8 +695,8 @@
692 695 * the lists, writes the EC header if it is needed, and removes it from the
693 696 * list.
694 697 *
695   - * This function returns scanning physical eraseblock information in case of
696   - * success and an error code in case of failure.
  698 + * This function returns a pointer to the "aeb" of the found free PEB in case
  699 + * of success and an error code in case of failure.
697 700 */
698 701 struct ubi_ainf_peb *ubi_early_get_peb(struct ubi_device *ubi,
699 702 struct ubi_attach_info *ai)
700 703  
701 704  
... ... @@ -793,16 +796,18 @@
793 796 }
794 797  
795 798 /**
796   - * process_eb - read, check UBI headers, and add them to attaching information.
  799 + * scan_peb - scan and process UBI headers of a PEB.
797 800 * @ubi: UBI device description object
798 801 * @ai: attaching information
799 802 * @pnum: the physical eraseblock number
800 803 *
801   - * This function returns a zero if the physical eraseblock was successfully
802   - * handled and a negative error code in case of failure.
  804 + * This function reads UBI headers of PEB @pnum, checks them, and adds
  805 + * information about this PEB to the corresponding list or RB-tree in the
  806 + * "attaching info" structure. Returns zero if the physical eraseblock was
  807 + * successfully handled and a negative error code in case of failure.
803 808 */
804   -static int process_eb(struct ubi_device *ubi, struct ubi_attach_info *ai,
805   - int pnum)
  809 +static int scan_peb(struct ubi_device *ubi, struct ubi_attach_info *ai,
  810 + int pnum)
806 811 {
807 812 long long uninitialized_var(ec);
808 813 int err, bitflips = 0, vol_id, ec_err = 0;
... ... @@ -814,11 +819,6 @@
814 819 if (err < 0)
815 820 return err;
816 821 else if (err) {
817   - /*
818   - * FIXME: this is actually duty of the I/O sub-system to
819   - * initialize this, but MTD does not provide enough
820   - * information.
821   - */
822 822 ai->bad_peb_count += 1;
823 823 return 0;
824 824 }
825 825  
826 826  
... ... @@ -1033,18 +1033,17 @@
1033 1033 }
1034 1034  
1035 1035 /**
1036   - * check_what_we_have - check what PEB were found by scanning.
  1036 + * late_analysis - analyze the overall situation with PEB.
1037 1037 * @ubi: UBI device description object
1038 1038 * @ai: attaching information
1039 1039 *
1040   - * This is a helper function which takes a look what PEBs were found by
1041   - * scanning, and decides whether the flash is empty and should be formatted and
1042   - * whether there are too many corrupted PEBs and we should not attach this
1043   - * MTD device. Returns zero if we should proceed with attaching the MTD device,
1044   - * and %-EINVAL if we should not.
  1040 + * This is a helper function which takes a look what PEBs we have after we
  1041 + * gather information about all of them ("ai" is compete). It decides whether
  1042 + * the flash is empty and should be formatted of whether there are too many
  1043 + * corrupted PEBs and we should not attach this MTD device. Returns zero if we
  1044 + * should proceed with attaching the MTD device, and %-EINVAL if we should not.
1045 1045 */
1046   -static int check_what_we_have(struct ubi_device *ubi,
1047   - struct ubi_attach_info *ai)
  1046 +static int late_analysis(struct ubi_device *ubi, struct ubi_attach_info *ai)
1048 1047 {
1049 1048 struct ubi_ainf_peb *aeb;
1050 1049 int max_corr, peb_count;
... ... @@ -1112,7 +1111,8 @@
1112 1111 * @ubi: UBI device description object
1113 1112 *
1114 1113 * This function does full scanning of an MTD device and returns complete
1115   - * information about it. In case of failure, an error code is returned.
  1114 + * information about it in form of a "struct ubi_attach_info" object. In case
  1115 + * of failure, an error code is returned.
1116 1116 */
1117 1117 struct ubi_attach_info *ubi_scan(struct ubi_device *ubi)
1118 1118 {
... ... @@ -1151,7 +1151,7 @@
1151 1151 cond_resched();
1152 1152  
1153 1153 dbg_gen("process PEB %d", pnum);
1154   - err = process_eb(ubi, ai, pnum);
  1154 + err = scan_peb(ubi, ai, pnum);
1155 1155 if (err < 0)
1156 1156 goto out_vidh;
1157 1157 }
... ... @@ -1162,7 +1162,7 @@
1162 1162 if (ai->ec_count)
1163 1163 ai->mean_ec = div_u64(ai->ec_sum, ai->ec_count);
1164 1164  
1165   - err = check_what_we_have(ubi, ai);
  1165 + err = late_analysis(ubi, ai);
1166 1166 if (err)
1167 1167 goto out_vidh;
1168 1168  
1169 1169  
... ... @@ -1208,12 +1208,11 @@
1208 1208 }
1209 1209  
1210 1210 /**
1211   - * destroy_av - free the scanning volume information
1212   - * @av: scanning volume information
  1211 + * destroy_av - free volume attaching information.
  1212 + * @av: volume attaching information
1213 1213 * @ai: attaching information
1214 1214 *
1215   - * This function destroys the volume RB-tree (@av->root) and the scanning
1216   - * volume information.
  1215 + * This function destroys the volume attaching information.
1217 1216 */
1218 1217 static void destroy_av(struct ubi_attach_info *ai, struct ubi_ainf_volume *av)
1219 1218 {
drivers/mtd/ubi/scan.h
Diff comments   View file @ fbd0107
... ... @@ -146,7 +146,7 @@
146 146 * ubi_move_aeb_to_list - move a PEB from the volume tree to a list.
147 147 *
148 148 * @av: volume attaching information
149   - * @aeb: scanning eraseblock information
  149 + * @aeb: attaching eraseblock information
150 150 * @list: the list to move to
151 151 */
152 152 static inline void ubi_move_aeb_to_list(struct ubi_ainf_volume *av,
drivers/mtd/ubi/ubi-media.h
Diff comments   View file @ fbd0107
... ... @@ -149,10 +149,10 @@
149 149 * The @image_seq field is used to validate a UBI image that has been prepared
150 150 * for a UBI device. The @image_seq value can be any value, but it must be the
151 151 * same on all eraseblocks. UBI will ensure that all new erase counter headers
152   - * also contain this value, and will check the value when scanning at start-up.
  152 + * also contain this value, and will check the value when attaching the flash.
153 153 * One way to make use of @image_seq is to increase its value by one every time
154 154 * an image is flashed over an existing image, then, if the flashing does not
155   - * complete, UBI will detect the error when scanning.
  155 + * complete, UBI will detect the error when attaching the media.
156 156 */
157 157 struct ubi_ec_hdr {
158 158 __be32 magic;
drivers/mtd/ubi/vtbl.c
Diff comments   View file @ fbd0107
... ... @@ -37,16 +37,15 @@
37 37 * LEB 1. This scheme guarantees recoverability from unclean reboots.
38 38 *
39 39 * In this UBI implementation the on-flash volume table does not contain any
40   - * information about how many data static volumes contain. This information may
41   - * be found from the scanning data.
  40 + * information about how much data static volumes contain.
42 41 *
43 42 * But it would still be beneficial to store this information in the volume
44 43 * table. For example, suppose we have a static volume X, and all its physical
45 44 * eraseblocks became bad for some reasons. Suppose we are attaching the
46   - * corresponding MTD device, the scanning has found no logical eraseblocks
  45 + * corresponding MTD device, for some reason we find no logical eraseblocks
47 46 * corresponding to the volume X. According to the volume table volume X does
48 47 * exist. So we don't know whether it is just empty or all its physical
49   - * eraseblocks went bad. So we cannot alarm the user about this corruption.
  48 + * eraseblocks went bad. So we cannot alarm the user properly.
50 49 *
51 50 * The volume table also stores so-called "update marker", which is used for
52 51 * volume updates. Before updating the volume, the update marker is set, and
53 52  
54 53  
... ... @@ -702,16 +701,16 @@
702 701 }
703 702  
704 703 /**
705   - * check_scanning_info - check that attaching information.
  704 + * check_attaching_info - check that attaching information.
706 705 * @ubi: UBI device description object
707 706 * @ai: attaching information
708 707 *
709 708 * Even though we protect on-flash data by CRC checksums, we still don't trust
710 709 * the media. This function ensures that attaching information is consistent to
711   - * the information read from the volume table. Returns zero if the scanning
  710 + * the information read from the volume table. Returns zero if the attaching
712 711 * information is OK and %-EINVAL if it is not.
713 712 */
714   -static int check_scanning_info(const struct ubi_device *ubi,
  713 +static int check_attaching_info(const struct ubi_device *ubi,
715 714 struct ubi_attach_info *ai)
716 715 {
717 716 int err, i;
718 717  
... ... @@ -719,15 +718,14 @@
719 718 struct ubi_volume *vol;
720 719  
721 720 if (ai->vols_found > UBI_INT_VOL_COUNT + ubi->vtbl_slots) {
722   - ubi_err("scanning found %d volumes, maximum is %d + %d",
  721 + ubi_err("found %d volumes while attaching, maximum is %d + %d",
723 722 ai->vols_found, UBI_INT_VOL_COUNT, ubi->vtbl_slots);
724 723 return -EINVAL;
725 724 }
726 725  
727 726 if (ai->highest_vol_id >= ubi->vtbl_slots + UBI_INT_VOL_COUNT &&
728 727 ai->highest_vol_id < UBI_INTERNAL_VOL_START) {
729   - ubi_err("too large volume ID %d found by scanning",
730   - ai->highest_vol_id);
  728 + ubi_err("too large volume ID %d found", ai->highest_vol_id);
731 729 return -EINVAL;
732 730 }
733 731  
... ... @@ -749,7 +747,7 @@
749 747 continue;
750 748  
751 749 /*
752   - * During scanning we found a volume which does not
  750 + * During attaching we found a volume which does not
753 751 * exist according to the information in the volume
754 752 * table. This must have happened due to an unclean
755 753 * reboot while the volume was being removed. Discard
... ... @@ -839,7 +837,7 @@
839 837 * Make sure that the attaching information is consistent to the
840 838 * information stored in the volume table.
841 839 */
842   - err = check_scanning_info(ubi, ai);
  840 + err = check_attaching_info(ubi, ai);
843 841 if (err)
844 842 goto out_free;
845 843