Back to home page

OSCL-LXR
 
 

     

0001 // SPDX-License-Identifier: GPL-2.0-or-later
0002 /*
0003  * Copyright (c) International Business Machines Corp., 2006
0004  *
0005  * Author: Artem Bityutskiy (Битюцкий Артём)
0006  */
0007 
0008 /* This file mostly implements UBI kernel API functions */
0009 
0010 #include <linux/module.h>
0011 #include <linux/err.h>
0012 #include <linux/slab.h>
0013 #include <linux/namei.h>
0014 #include <linux/fs.h>
0015 #include <asm/div64.h>
0016 #include "ubi.h"
0017 
0018 /**
0019  * ubi_do_get_device_info - get information about UBI device.
0020  * @ubi: UBI device description object
0021  * @di: the information is stored here
0022  *
0023  * This function is the same as 'ubi_get_device_info()', but it assumes the UBI
0024  * device is locked and cannot disappear.
0025  */
0026 void ubi_do_get_device_info(struct ubi_device *ubi, struct ubi_device_info *di)
0027 {
0028     di->ubi_num = ubi->ubi_num;
0029     di->leb_size = ubi->leb_size;
0030     di->leb_start = ubi->leb_start;
0031     di->min_io_size = ubi->min_io_size;
0032     di->max_write_size = ubi->max_write_size;
0033     di->ro_mode = ubi->ro_mode;
0034     di->cdev = ubi->cdev.dev;
0035 }
0036 EXPORT_SYMBOL_GPL(ubi_do_get_device_info);
0037 
0038 /**
0039  * ubi_get_device_info - get information about UBI device.
0040  * @ubi_num: UBI device number
0041  * @di: the information is stored here
0042  *
0043  * This function returns %0 in case of success, %-EINVAL if the UBI device
0044  * number is invalid, and %-ENODEV if there is no such UBI device.
0045  */
0046 int ubi_get_device_info(int ubi_num, struct ubi_device_info *di)
0047 {
0048     struct ubi_device *ubi;
0049 
0050     if (ubi_num < 0 || ubi_num >= UBI_MAX_DEVICES)
0051         return -EINVAL;
0052     ubi = ubi_get_device(ubi_num);
0053     if (!ubi)
0054         return -ENODEV;
0055     ubi_do_get_device_info(ubi, di);
0056     ubi_put_device(ubi);
0057     return 0;
0058 }
0059 EXPORT_SYMBOL_GPL(ubi_get_device_info);
0060 
0061 /**
0062  * ubi_do_get_volume_info - get information about UBI volume.
0063  * @ubi: UBI device description object
0064  * @vol: volume description object
0065  * @vi: the information is stored here
0066  */
0067 void ubi_do_get_volume_info(struct ubi_device *ubi, struct ubi_volume *vol,
0068                 struct ubi_volume_info *vi)
0069 {
0070     vi->vol_id = vol->vol_id;
0071     vi->ubi_num = ubi->ubi_num;
0072     vi->size = vol->reserved_pebs;
0073     vi->used_bytes = vol->used_bytes;
0074     vi->vol_type = vol->vol_type;
0075     vi->corrupted = vol->corrupted;
0076     vi->upd_marker = vol->upd_marker;
0077     vi->alignment = vol->alignment;
0078     vi->usable_leb_size = vol->usable_leb_size;
0079     vi->name_len = vol->name_len;
0080     vi->name = vol->name;
0081     vi->cdev = vol->cdev.dev;
0082 }
0083 
0084 /**
0085  * ubi_get_volume_info - get information about UBI volume.
0086  * @desc: volume descriptor
0087  * @vi: the information is stored here
0088  */
0089 void ubi_get_volume_info(struct ubi_volume_desc *desc,
0090              struct ubi_volume_info *vi)
0091 {
0092     ubi_do_get_volume_info(desc->vol->ubi, desc->vol, vi);
0093 }
0094 EXPORT_SYMBOL_GPL(ubi_get_volume_info);
0095 
0096 /**
0097  * ubi_open_volume - open UBI volume.
0098  * @ubi_num: UBI device number
0099  * @vol_id: volume ID
0100  * @mode: open mode
0101  *
0102  * The @mode parameter specifies if the volume should be opened in read-only
0103  * mode, read-write mode, or exclusive mode. The exclusive mode guarantees that
0104  * nobody else will be able to open this volume. UBI allows to have many volume
0105  * readers and one writer at a time.
0106  *
0107  * If a static volume is being opened for the first time since boot, it will be
0108  * checked by this function, which means it will be fully read and the CRC
0109  * checksum of each logical eraseblock will be checked.
0110  *
0111  * This function returns volume descriptor in case of success and a negative
0112  * error code in case of failure.
0113  */
0114 struct ubi_volume_desc *ubi_open_volume(int ubi_num, int vol_id, int mode)
0115 {
0116     int err;
0117     struct ubi_volume_desc *desc;
0118     struct ubi_device *ubi;
0119     struct ubi_volume *vol;
0120 
0121     dbg_gen("open device %d, volume %d, mode %d", ubi_num, vol_id, mode);
0122 
0123     if (ubi_num < 0 || ubi_num >= UBI_MAX_DEVICES)
0124         return ERR_PTR(-EINVAL);
0125 
0126     if (mode != UBI_READONLY && mode != UBI_READWRITE &&
0127         mode != UBI_EXCLUSIVE && mode != UBI_METAONLY)
0128         return ERR_PTR(-EINVAL);
0129 
0130     /*
0131      * First of all, we have to get the UBI device to prevent its removal.
0132      */
0133     ubi = ubi_get_device(ubi_num);
0134     if (!ubi)
0135         return ERR_PTR(-ENODEV);
0136 
0137     if (vol_id < 0 || vol_id >= ubi->vtbl_slots) {
0138         err = -EINVAL;
0139         goto out_put_ubi;
0140     }
0141 
0142     desc = kmalloc(sizeof(struct ubi_volume_desc), GFP_KERNEL);
0143     if (!desc) {
0144         err = -ENOMEM;
0145         goto out_put_ubi;
0146     }
0147 
0148     err = -ENODEV;
0149     if (!try_module_get(THIS_MODULE))
0150         goto out_free;
0151 
0152     spin_lock(&ubi->volumes_lock);
0153     vol = ubi->volumes[vol_id];
0154     if (!vol)
0155         goto out_unlock;
0156 
0157     err = -EBUSY;
0158     switch (mode) {
0159     case UBI_READONLY:
0160         if (vol->exclusive)
0161             goto out_unlock;
0162         vol->readers += 1;
0163         break;
0164 
0165     case UBI_READWRITE:
0166         if (vol->exclusive || vol->writers > 0)
0167             goto out_unlock;
0168         vol->writers += 1;
0169         break;
0170 
0171     case UBI_EXCLUSIVE:
0172         if (vol->exclusive || vol->writers || vol->readers ||
0173             vol->metaonly)
0174             goto out_unlock;
0175         vol->exclusive = 1;
0176         break;
0177 
0178     case UBI_METAONLY:
0179         if (vol->metaonly || vol->exclusive)
0180             goto out_unlock;
0181         vol->metaonly = 1;
0182         break;
0183     }
0184     get_device(&vol->dev);
0185     vol->ref_count += 1;
0186     spin_unlock(&ubi->volumes_lock);
0187 
0188     desc->vol = vol;
0189     desc->mode = mode;
0190 
0191     mutex_lock(&ubi->ckvol_mutex);
0192     if (!vol->checked && !vol->skip_check) {
0193         /* This is the first open - check the volume */
0194         err = ubi_check_volume(ubi, vol_id);
0195         if (err < 0) {
0196             mutex_unlock(&ubi->ckvol_mutex);
0197             ubi_close_volume(desc);
0198             return ERR_PTR(err);
0199         }
0200         if (err == 1) {
0201             ubi_warn(ubi, "volume %d on UBI device %d is corrupted",
0202                  vol_id, ubi->ubi_num);
0203             vol->corrupted = 1;
0204         }
0205         vol->checked = 1;
0206     }
0207     mutex_unlock(&ubi->ckvol_mutex);
0208 
0209     return desc;
0210 
0211 out_unlock:
0212     spin_unlock(&ubi->volumes_lock);
0213     module_put(THIS_MODULE);
0214 out_free:
0215     kfree(desc);
0216 out_put_ubi:
0217     ubi_err(ubi, "cannot open device %d, volume %d, error %d",
0218         ubi_num, vol_id, err);
0219     ubi_put_device(ubi);
0220     return ERR_PTR(err);
0221 }
0222 EXPORT_SYMBOL_GPL(ubi_open_volume);
0223 
0224 /**
0225  * ubi_open_volume_nm - open UBI volume by name.
0226  * @ubi_num: UBI device number
0227  * @name: volume name
0228  * @mode: open mode
0229  *
0230  * This function is similar to 'ubi_open_volume()', but opens a volume by name.
0231  */
0232 struct ubi_volume_desc *ubi_open_volume_nm(int ubi_num, const char *name,
0233                        int mode)
0234 {
0235     int i, vol_id = -1, len;
0236     struct ubi_device *ubi;
0237     struct ubi_volume_desc *ret;
0238 
0239     dbg_gen("open device %d, volume %s, mode %d", ubi_num, name, mode);
0240 
0241     if (!name)
0242         return ERR_PTR(-EINVAL);
0243 
0244     len = strnlen(name, UBI_VOL_NAME_MAX + 1);
0245     if (len > UBI_VOL_NAME_MAX)
0246         return ERR_PTR(-EINVAL);
0247 
0248     if (ubi_num < 0 || ubi_num >= UBI_MAX_DEVICES)
0249         return ERR_PTR(-EINVAL);
0250 
0251     ubi = ubi_get_device(ubi_num);
0252     if (!ubi)
0253         return ERR_PTR(-ENODEV);
0254 
0255     spin_lock(&ubi->volumes_lock);
0256     /* Walk all volumes of this UBI device */
0257     for (i = 0; i < ubi->vtbl_slots; i++) {
0258         struct ubi_volume *vol = ubi->volumes[i];
0259 
0260         if (vol && len == vol->name_len && !strcmp(name, vol->name)) {
0261             vol_id = i;
0262             break;
0263         }
0264     }
0265     spin_unlock(&ubi->volumes_lock);
0266 
0267     if (vol_id >= 0)
0268         ret = ubi_open_volume(ubi_num, vol_id, mode);
0269     else
0270         ret = ERR_PTR(-ENODEV);
0271 
0272     /*
0273      * We should put the UBI device even in case of success, because
0274      * 'ubi_open_volume()' took a reference as well.
0275      */
0276     ubi_put_device(ubi);
0277     return ret;
0278 }
0279 EXPORT_SYMBOL_GPL(ubi_open_volume_nm);
0280 
0281 /**
0282  * ubi_open_volume_path - open UBI volume by its character device node path.
0283  * @pathname: volume character device node path
0284  * @mode: open mode
0285  *
0286  * This function is similar to 'ubi_open_volume()', but opens a volume the path
0287  * to its character device node.
0288  */
0289 struct ubi_volume_desc *ubi_open_volume_path(const char *pathname, int mode)
0290 {
0291     int error, ubi_num, vol_id;
0292     struct path path;
0293     struct kstat stat;
0294 
0295     dbg_gen("open volume %s, mode %d", pathname, mode);
0296 
0297     if (!pathname || !*pathname)
0298         return ERR_PTR(-EINVAL);
0299 
0300     error = kern_path(pathname, LOOKUP_FOLLOW, &path);
0301     if (error)
0302         return ERR_PTR(error);
0303 
0304     error = vfs_getattr(&path, &stat, STATX_TYPE, AT_STATX_SYNC_AS_STAT);
0305     path_put(&path);
0306     if (error)
0307         return ERR_PTR(error);
0308 
0309     if (!S_ISCHR(stat.mode))
0310         return ERR_PTR(-EINVAL);
0311 
0312     ubi_num = ubi_major2num(MAJOR(stat.rdev));
0313     vol_id = MINOR(stat.rdev) - 1;
0314 
0315     if (vol_id >= 0 && ubi_num >= 0)
0316         return ubi_open_volume(ubi_num, vol_id, mode);
0317     return ERR_PTR(-ENODEV);
0318 }
0319 EXPORT_SYMBOL_GPL(ubi_open_volume_path);
0320 
0321 /**
0322  * ubi_close_volume - close UBI volume.
0323  * @desc: volume descriptor
0324  */
0325 void ubi_close_volume(struct ubi_volume_desc *desc)
0326 {
0327     struct ubi_volume *vol = desc->vol;
0328     struct ubi_device *ubi = vol->ubi;
0329 
0330     dbg_gen("close device %d, volume %d, mode %d",
0331         ubi->ubi_num, vol->vol_id, desc->mode);
0332 
0333     spin_lock(&ubi->volumes_lock);
0334     switch (desc->mode) {
0335     case UBI_READONLY:
0336         vol->readers -= 1;
0337         break;
0338     case UBI_READWRITE:
0339         vol->writers -= 1;
0340         break;
0341     case UBI_EXCLUSIVE:
0342         vol->exclusive = 0;
0343         break;
0344     case UBI_METAONLY:
0345         vol->metaonly = 0;
0346         break;
0347     }
0348     vol->ref_count -= 1;
0349     spin_unlock(&ubi->volumes_lock);
0350 
0351     kfree(desc);
0352     put_device(&vol->dev);
0353     ubi_put_device(ubi);
0354     module_put(THIS_MODULE);
0355 }
0356 EXPORT_SYMBOL_GPL(ubi_close_volume);
0357 
0358 /**
0359  * leb_read_sanity_check - does sanity checks on read requests.
0360  * @desc: volume descriptor
0361  * @lnum: logical eraseblock number to read from
0362  * @offset: offset within the logical eraseblock to read from
0363  * @len: how many bytes to read
0364  *
0365  * This function is used by ubi_leb_read() and ubi_leb_read_sg()
0366  * to perform sanity checks.
0367  */
0368 static int leb_read_sanity_check(struct ubi_volume_desc *desc, int lnum,
0369                  int offset, int len)
0370 {
0371     struct ubi_volume *vol = desc->vol;
0372     struct ubi_device *ubi = vol->ubi;
0373     int vol_id = vol->vol_id;
0374 
0375     if (vol_id < 0 || vol_id >= ubi->vtbl_slots || lnum < 0 ||
0376         lnum >= vol->used_ebs || offset < 0 || len < 0 ||
0377         offset + len > vol->usable_leb_size)
0378         return -EINVAL;
0379 
0380     if (vol->vol_type == UBI_STATIC_VOLUME) {
0381         if (vol->used_ebs == 0)
0382             /* Empty static UBI volume */
0383             return 0;
0384         if (lnum == vol->used_ebs - 1 &&
0385             offset + len > vol->last_eb_bytes)
0386             return -EINVAL;
0387     }
0388 
0389     if (vol->upd_marker)
0390         return -EBADF;
0391 
0392     return 0;
0393 }
0394 
0395 /**
0396  * ubi_leb_read - read data.
0397  * @desc: volume descriptor
0398  * @lnum: logical eraseblock number to read from
0399  * @buf: buffer where to store the read data
0400  * @offset: offset within the logical eraseblock to read from
0401  * @len: how many bytes to read
0402  * @check: whether UBI has to check the read data's CRC or not.
0403  *
0404  * This function reads data from offset @offset of logical eraseblock @lnum and
0405  * stores the data at @buf. When reading from static volumes, @check specifies
0406  * whether the data has to be checked or not. If yes, the whole logical
0407  * eraseblock will be read and its CRC checksum will be checked (i.e., the CRC
0408  * checksum is per-eraseblock). So checking may substantially slow down the
0409  * read speed. The @check argument is ignored for dynamic volumes.
0410  *
0411  * In case of success, this function returns zero. In case of failure, this
0412  * function returns a negative error code.
0413  *
0414  * %-EBADMSG error code is returned:
0415  * o for both static and dynamic volumes if MTD driver has detected a data
0416  *   integrity problem (unrecoverable ECC checksum mismatch in case of NAND);
0417  * o for static volumes in case of data CRC mismatch.
0418  *
0419  * If the volume is damaged because of an interrupted update this function just
0420  * returns immediately with %-EBADF error code.
0421  */
0422 int ubi_leb_read(struct ubi_volume_desc *desc, int lnum, char *buf, int offset,
0423          int len, int check)
0424 {
0425     struct ubi_volume *vol = desc->vol;
0426     struct ubi_device *ubi = vol->ubi;
0427     int err, vol_id = vol->vol_id;
0428 
0429     dbg_gen("read %d bytes from LEB %d:%d:%d", len, vol_id, lnum, offset);
0430 
0431     err = leb_read_sanity_check(desc, lnum, offset, len);
0432     if (err < 0)
0433         return err;
0434 
0435     if (len == 0)
0436         return 0;
0437 
0438     err = ubi_eba_read_leb(ubi, vol, lnum, buf, offset, len, check);
0439     if (err && mtd_is_eccerr(err) && vol->vol_type == UBI_STATIC_VOLUME) {
0440         ubi_warn(ubi, "mark volume %d as corrupted", vol_id);
0441         vol->corrupted = 1;
0442     }
0443 
0444     return err;
0445 }
0446 EXPORT_SYMBOL_GPL(ubi_leb_read);
0447 
0448 
0449 /**
0450  * ubi_leb_read_sg - read data into a scatter gather list.
0451  * @desc: volume descriptor
0452  * @lnum: logical eraseblock number to read from
0453  * @sgl: UBI scatter gather list to store the read data
0454  * @offset: offset within the logical eraseblock to read from
0455  * @len: how many bytes to read
0456  * @check: whether UBI has to check the read data's CRC or not.
0457  *
0458  * This function works exactly like ubi_leb_read_sg(). But instead of
0459  * storing the read data into a buffer it writes to an UBI scatter gather
0460  * list.
0461  */
0462 int ubi_leb_read_sg(struct ubi_volume_desc *desc, int lnum, struct ubi_sgl *sgl,
0463             int offset, int len, int check)
0464 {
0465     struct ubi_volume *vol = desc->vol;
0466     struct ubi_device *ubi = vol->ubi;
0467     int err, vol_id = vol->vol_id;
0468 
0469     dbg_gen("read %d bytes from LEB %d:%d:%d", len, vol_id, lnum, offset);
0470 
0471     err = leb_read_sanity_check(desc, lnum, offset, len);
0472     if (err < 0)
0473         return err;
0474 
0475     if (len == 0)
0476         return 0;
0477 
0478     err = ubi_eba_read_leb_sg(ubi, vol, sgl, lnum, offset, len, check);
0479     if (err && mtd_is_eccerr(err) && vol->vol_type == UBI_STATIC_VOLUME) {
0480         ubi_warn(ubi, "mark volume %d as corrupted", vol_id);
0481         vol->corrupted = 1;
0482     }
0483 
0484     return err;
0485 }
0486 EXPORT_SYMBOL_GPL(ubi_leb_read_sg);
0487 
0488 /**
0489  * ubi_leb_write - write data.
0490  * @desc: volume descriptor
0491  * @lnum: logical eraseblock number to write to
0492  * @buf: data to write
0493  * @offset: offset within the logical eraseblock where to write
0494  * @len: how many bytes to write
0495  *
0496  * This function writes @len bytes of data from @buf to offset @offset of
0497  * logical eraseblock @lnum.
0498  *
0499  * This function takes care of physical eraseblock write failures. If write to
0500  * the physical eraseblock write operation fails, the logical eraseblock is
0501  * re-mapped to another physical eraseblock, the data is recovered, and the
0502  * write finishes. UBI has a pool of reserved physical eraseblocks for this.
0503  *
0504  * If all the data were successfully written, zero is returned. If an error
0505  * occurred and UBI has not been able to recover from it, this function returns
0506  * a negative error code. Note, in case of an error, it is possible that
0507  * something was still written to the flash media, but that may be some
0508  * garbage.
0509  *
0510  * If the volume is damaged because of an interrupted update this function just
0511  * returns immediately with %-EBADF code.
0512  */
0513 int ubi_leb_write(struct ubi_volume_desc *desc, int lnum, const void *buf,
0514           int offset, int len)
0515 {
0516     struct ubi_volume *vol = desc->vol;
0517     struct ubi_device *ubi = vol->ubi;
0518     int vol_id = vol->vol_id;
0519 
0520     dbg_gen("write %d bytes to LEB %d:%d:%d", len, vol_id, lnum, offset);
0521 
0522     if (vol_id < 0 || vol_id >= ubi->vtbl_slots)
0523         return -EINVAL;
0524 
0525     if (desc->mode == UBI_READONLY || vol->vol_type == UBI_STATIC_VOLUME)
0526         return -EROFS;
0527 
0528     if (!ubi_leb_valid(vol, lnum) || offset < 0 || len < 0 ||
0529         offset + len > vol->usable_leb_size ||
0530         offset & (ubi->min_io_size - 1) || len & (ubi->min_io_size - 1))
0531         return -EINVAL;
0532 
0533     if (vol->upd_marker)
0534         return -EBADF;
0535 
0536     if (len == 0)
0537         return 0;
0538 
0539     return ubi_eba_write_leb(ubi, vol, lnum, buf, offset, len);
0540 }
0541 EXPORT_SYMBOL_GPL(ubi_leb_write);
0542 
0543 /*
0544  * ubi_leb_change - change logical eraseblock atomically.
0545  * @desc: volume descriptor
0546  * @lnum: logical eraseblock number to change
0547  * @buf: data to write
0548  * @len: how many bytes to write
0549  *
0550  * This function changes the contents of a logical eraseblock atomically. @buf
0551  * has to contain new logical eraseblock data, and @len - the length of the
0552  * data, which has to be aligned. The length may be shorter than the logical
0553  * eraseblock size, ant the logical eraseblock may be appended to more times
0554  * later on. This function guarantees that in case of an unclean reboot the old
0555  * contents is preserved. Returns zero in case of success and a negative error
0556  * code in case of failure.
0557  */
0558 int ubi_leb_change(struct ubi_volume_desc *desc, int lnum, const void *buf,
0559            int len)
0560 {
0561     struct ubi_volume *vol = desc->vol;
0562     struct ubi_device *ubi = vol->ubi;
0563     int vol_id = vol->vol_id;
0564 
0565     dbg_gen("atomically write %d bytes to LEB %d:%d", len, vol_id, lnum);
0566 
0567     if (vol_id < 0 || vol_id >= ubi->vtbl_slots)
0568         return -EINVAL;
0569 
0570     if (desc->mode == UBI_READONLY || vol->vol_type == UBI_STATIC_VOLUME)
0571         return -EROFS;
0572 
0573     if (!ubi_leb_valid(vol, lnum) || len < 0 ||
0574         len > vol->usable_leb_size || len & (ubi->min_io_size - 1))
0575         return -EINVAL;
0576 
0577     if (vol->upd_marker)
0578         return -EBADF;
0579 
0580     if (len == 0)
0581         return 0;
0582 
0583     return ubi_eba_atomic_leb_change(ubi, vol, lnum, buf, len);
0584 }
0585 EXPORT_SYMBOL_GPL(ubi_leb_change);
0586 
0587 /**
0588  * ubi_leb_erase - erase logical eraseblock.
0589  * @desc: volume descriptor
0590  * @lnum: logical eraseblock number
0591  *
0592  * This function un-maps logical eraseblock @lnum and synchronously erases the
0593  * correspondent physical eraseblock. Returns zero in case of success and a
0594  * negative error code in case of failure.
0595  *
0596  * If the volume is damaged because of an interrupted update this function just
0597  * returns immediately with %-EBADF code.
0598  */
0599 int ubi_leb_erase(struct ubi_volume_desc *desc, int lnum)
0600 {
0601     struct ubi_volume *vol = desc->vol;
0602     struct ubi_device *ubi = vol->ubi;
0603     int err;
0604 
0605     dbg_gen("erase LEB %d:%d", vol->vol_id, lnum);
0606 
0607     if (desc->mode == UBI_READONLY || vol->vol_type == UBI_STATIC_VOLUME)
0608         return -EROFS;
0609 
0610     if (!ubi_leb_valid(vol, lnum))
0611         return -EINVAL;
0612 
0613     if (vol->upd_marker)
0614         return -EBADF;
0615 
0616     err = ubi_eba_unmap_leb(ubi, vol, lnum);
0617     if (err)
0618         return err;
0619 
0620     return ubi_wl_flush(ubi, vol->vol_id, lnum);
0621 }
0622 EXPORT_SYMBOL_GPL(ubi_leb_erase);
0623 
0624 /**
0625  * ubi_leb_unmap - un-map logical eraseblock.
0626  * @desc: volume descriptor
0627  * @lnum: logical eraseblock number
0628  *
0629  * This function un-maps logical eraseblock @lnum and schedules the
0630  * corresponding physical eraseblock for erasure, so that it will eventually be
0631  * physically erased in background. This operation is much faster than the
0632  * erase operation.
0633  *
0634  * Unlike erase, the un-map operation does not guarantee that the logical
0635  * eraseblock will contain all 0xFF bytes when UBI is initialized again. For
0636  * example, if several logical eraseblocks are un-mapped, and an unclean reboot
0637  * happens after this, the logical eraseblocks will not necessarily be
0638  * un-mapped again when this MTD device is attached. They may actually be
0639  * mapped to the same physical eraseblocks again. So, this function has to be
0640  * used with care.
0641  *
0642  * In other words, when un-mapping a logical eraseblock, UBI does not store
0643  * any information about this on the flash media, it just marks the logical
0644  * eraseblock as "un-mapped" in RAM. If UBI is detached before the physical
0645  * eraseblock is physically erased, it will be mapped again to the same logical
0646  * eraseblock when the MTD device is attached again.
0647  *
0648  * The main and obvious use-case of this function is when the contents of a
0649  * logical eraseblock has to be re-written. Then it is much more efficient to
0650  * first un-map it, then write new data, rather than first erase it, then write
0651  * new data. Note, once new data has been written to the logical eraseblock,
0652  * UBI guarantees that the old contents has gone forever. In other words, if an
0653  * unclean reboot happens after the logical eraseblock has been un-mapped and
0654  * then written to, it will contain the last written data.
0655  *
0656  * This function returns zero in case of success and a negative error code in
0657  * case of failure. If the volume is damaged because of an interrupted update
0658  * this function just returns immediately with %-EBADF code.
0659  */
0660 int ubi_leb_unmap(struct ubi_volume_desc *desc, int lnum)
0661 {
0662     struct ubi_volume *vol = desc->vol;
0663     struct ubi_device *ubi = vol->ubi;
0664 
0665     dbg_gen("unmap LEB %d:%d", vol->vol_id, lnum);
0666 
0667     if (desc->mode == UBI_READONLY || vol->vol_type == UBI_STATIC_VOLUME)
0668         return -EROFS;
0669 
0670     if (!ubi_leb_valid(vol, lnum))
0671         return -EINVAL;
0672 
0673     if (vol->upd_marker)
0674         return -EBADF;
0675 
0676     return ubi_eba_unmap_leb(ubi, vol, lnum);
0677 }
0678 EXPORT_SYMBOL_GPL(ubi_leb_unmap);
0679 
0680 /**
0681  * ubi_leb_map - map logical eraseblock to a physical eraseblock.
0682  * @desc: volume descriptor
0683  * @lnum: logical eraseblock number
0684  *
0685  * This function maps an un-mapped logical eraseblock @lnum to a physical
0686  * eraseblock. This means, that after a successful invocation of this
0687  * function the logical eraseblock @lnum will be empty (contain only %0xFF
0688  * bytes) and be mapped to a physical eraseblock, even if an unclean reboot
0689  * happens.
0690  *
0691  * This function returns zero in case of success, %-EBADF if the volume is
0692  * damaged because of an interrupted update, %-EBADMSG if the logical
0693  * eraseblock is already mapped, and other negative error codes in case of
0694  * other failures.
0695  */
0696 int ubi_leb_map(struct ubi_volume_desc *desc, int lnum)
0697 {
0698     struct ubi_volume *vol = desc->vol;
0699     struct ubi_device *ubi = vol->ubi;
0700 
0701     dbg_gen("map LEB %d:%d", vol->vol_id, lnum);
0702 
0703     if (desc->mode == UBI_READONLY || vol->vol_type == UBI_STATIC_VOLUME)
0704         return -EROFS;
0705 
0706     if (!ubi_leb_valid(vol, lnum))
0707         return -EINVAL;
0708 
0709     if (vol->upd_marker)
0710         return -EBADF;
0711 
0712     if (ubi_eba_is_mapped(vol, lnum))
0713         return -EBADMSG;
0714 
0715     return ubi_eba_write_leb(ubi, vol, lnum, NULL, 0, 0);
0716 }
0717 EXPORT_SYMBOL_GPL(ubi_leb_map);
0718 
0719 /**
0720  * ubi_is_mapped - check if logical eraseblock is mapped.
0721  * @desc: volume descriptor
0722  * @lnum: logical eraseblock number
0723  *
0724  * This function checks if logical eraseblock @lnum is mapped to a physical
0725  * eraseblock. If a logical eraseblock is un-mapped, this does not necessarily
0726  * mean it will still be un-mapped after the UBI device is re-attached. The
0727  * logical eraseblock may become mapped to the physical eraseblock it was last
0728  * mapped to.
0729  *
0730  * This function returns %1 if the LEB is mapped, %0 if not, and a negative
0731  * error code in case of failure. If the volume is damaged because of an
0732  * interrupted update this function just returns immediately with %-EBADF error
0733  * code.
0734  */
0735 int ubi_is_mapped(struct ubi_volume_desc *desc, int lnum)
0736 {
0737     struct ubi_volume *vol = desc->vol;
0738 
0739     dbg_gen("test LEB %d:%d", vol->vol_id, lnum);
0740 
0741     if (!ubi_leb_valid(vol, lnum))
0742         return -EINVAL;
0743 
0744     if (vol->upd_marker)
0745         return -EBADF;
0746 
0747     return ubi_eba_is_mapped(vol, lnum);
0748 }
0749 EXPORT_SYMBOL_GPL(ubi_is_mapped);
0750 
0751 /**
0752  * ubi_sync - synchronize UBI device buffers.
0753  * @ubi_num: UBI device to synchronize
0754  *
0755  * The underlying MTD device may cache data in hardware or in software. This
0756  * function ensures the caches are flushed. Returns zero in case of success and
0757  * a negative error code in case of failure.
0758  */
0759 int ubi_sync(int ubi_num)
0760 {
0761     struct ubi_device *ubi;
0762 
0763     ubi = ubi_get_device(ubi_num);
0764     if (!ubi)
0765         return -ENODEV;
0766 
0767     mtd_sync(ubi->mtd);
0768     ubi_put_device(ubi);
0769     return 0;
0770 }
0771 EXPORT_SYMBOL_GPL(ubi_sync);
0772 
0773 /**
0774  * ubi_flush - flush UBI work queue.
0775  * @ubi_num: UBI device to flush work queue
0776  * @vol_id: volume id to flush for
0777  * @lnum: logical eraseblock number to flush for
0778  *
0779  * This function executes all pending works for a particular volume id / logical
0780  * eraseblock number pair. If either value is set to %UBI_ALL, then it acts as
0781  * a wildcard for all of the corresponding volume numbers or logical
0782  * eraseblock numbers. It returns zero in case of success and a negative error
0783  * code in case of failure.
0784  */
0785 int ubi_flush(int ubi_num, int vol_id, int lnum)
0786 {
0787     struct ubi_device *ubi;
0788     int err = 0;
0789 
0790     ubi = ubi_get_device(ubi_num);
0791     if (!ubi)
0792         return -ENODEV;
0793 
0794     err = ubi_wl_flush(ubi, vol_id, lnum);
0795     ubi_put_device(ubi);
0796     return err;
0797 }
0798 EXPORT_SYMBOL_GPL(ubi_flush);
0799 
0800 BLOCKING_NOTIFIER_HEAD(ubi_notifiers);
0801 
0802 /**
0803  * ubi_register_volume_notifier - register a volume notifier.
0804  * @nb: the notifier description object
0805  * @ignore_existing: if non-zero, do not send "added" notification for all
0806  *                   already existing volumes
0807  *
0808  * This function registers a volume notifier, which means that
0809  * 'nb->notifier_call()' will be invoked when an UBI  volume is created,
0810  * removed, re-sized, re-named, or updated. The first argument of the function
0811  * is the notification type. The second argument is pointer to a
0812  * &struct ubi_notification object which describes the notification event.
0813  * Using UBI API from the volume notifier is prohibited.
0814  *
0815  * This function returns zero in case of success and a negative error code
0816  * in case of failure.
0817  */
0818 int ubi_register_volume_notifier(struct notifier_block *nb,
0819                  int ignore_existing)
0820 {
0821     int err;
0822 
0823     err = blocking_notifier_chain_register(&ubi_notifiers, nb);
0824     if (err != 0)
0825         return err;
0826     if (ignore_existing)
0827         return 0;
0828 
0829     /*
0830      * We are going to walk all UBI devices and all volumes, and
0831      * notify the user about existing volumes by the %UBI_VOLUME_ADDED
0832      * event. We have to lock the @ubi_devices_mutex to make sure UBI
0833      * devices do not disappear.
0834      */
0835     mutex_lock(&ubi_devices_mutex);
0836     ubi_enumerate_volumes(nb);
0837     mutex_unlock(&ubi_devices_mutex);
0838 
0839     return err;
0840 }
0841 EXPORT_SYMBOL_GPL(ubi_register_volume_notifier);
0842 
0843 /**
0844  * ubi_unregister_volume_notifier - unregister the volume notifier.
0845  * @nb: the notifier description object
0846  *
0847  * This function unregisters volume notifier @nm and returns zero in case of
0848  * success and a negative error code in case of failure.
0849  */
0850 int ubi_unregister_volume_notifier(struct notifier_block *nb)
0851 {
0852     return blocking_notifier_chain_unregister(&ubi_notifiers, nb);
0853 }
0854 EXPORT_SYMBOL_GPL(ubi_unregister_volume_notifier);
[ Source navigation ] [ Diff markup ] [ Identifier search ] [ general search ]

This page was automatically generated by the 2.1.0 LXR engine.

The LXR team
Valid CSS 2.1! Valid HTML 4.01!