libubi/libubi.h

   1 /*
   2  * Copyright (c) International Business Machines Corp., 2006
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
  12  * the GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software
  16  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17  *
  18  * Author: Artem Bityutskiy
  19  *
  20  * UBI (Unsorted Block Images) library.
  21  */
  22
  23 #ifndef __LIBUBI_H__
  24 #define __LIBUBI_H__
  25
  26 #include <ctype.h>
  27 #include <stdlib.h>
  28 #include <errno.h>
  29 #include <stdint.h>
  30 #include "ubi-user.h"
  31 #include "ubi-media.h"
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /* UBI version libubi is made for */
  38 #define LIBUBI_UBI_VERSION 1
  39
  40 /* Maximum physical eraseblock size in bytes */
  41 #define UBI_MAX_PEB_SZ (2*1024*1024)
  42
  43 #define errmsg(fmt, ...) fprintf(stderr, fmt, ## __VA_ARGS__)
  44 #define sys_errmsg(fmt, ...) fprintf(stderr, fmt, ## __VA_ARGS__)
  45
  46 long long ubiutils_get_bytes(const char *str);
  47 void ubiutils_print_bytes(long long bytes, int bracket);
  48 void ubiutils_print_text(FILE *stream, const char *text, int width);
  49 int ubiutils_srand(void);
  50
  51
  52 #define simple_strtoX(func, type) \
  53 static inline type simple_##func(const char *snum, int *error) \
  54 { \
  55         char *endptr; \
  56         type ret = func(snum, &endptr, 0); \
  57  \
  58         if (error && (!*snum || *endptr)) { \
  59                 errmsg("%s: unable to parse the number '%s'", #func, snum); \
  60                 *error = 1; \
  61         } \
  62  \
  63         return ret; \
  64 }
  65 simple_strtoX(strtol, long int)
  66 simple_strtoX(strtoll, long long int)
  67 simple_strtoX(strtoul, unsigned long int)
  68 simple_strtoX(strtoull, unsigned long long int)
  69
  70
  71 /* UBI library descriptor */
  72 typedef void * libubi_t;
  73
  74 /**
  75  * struct ubi_attach_request - MTD device attachment request.
  76  * @dev_num: number to assign to the newly created UBI device
  77  *           (%UBI_DEV_NUM_AUTO should be used to automatically assign the
  78  *           number)
  79  * @mtd_num: MTD device number to attach (used if @mtd_dev_node is %NULL)
  80  * @mtd_dev_node: path to MTD device node to attach
  81  * @vid_hdr_offset: VID header offset (%0 means default offset and this is what
  82  *                  most of the users want)
  83  * @max_beb_per1024: Maximum expected bad eraseblocks per 1024 eraseblocks
  84  */
  85 struct ubi_attach_request
  86 {
  87         int dev_num;
  88         int mtd_num;
  89         const char *mtd_dev_node;
  90         int vid_hdr_offset;
  91         int max_beb_per1024;
  92 };
  93
  94 /**
  95  * struct ubi_mkvol_request - volume creation request.
  96  * @vol_id: ID to assign to the new volume (%UBI_VOL_NUM_AUTO should be used to
  97  *          automatically assign ID)
  98  * @alignment: volume alignment
  99  * @bytes: volume size in bytes
 100  * @vol_type: volume type (%UBI_DYNAMIC_VOLUME or %UBI_STATIC_VOLUME)
 101  * @name: volume name
 102  */
 103 struct ubi_mkvol_request
 104 {
 105         int vol_id;
 106         int alignment;
 107         long long bytes;
 108         int vol_type;
 109         const char *name;
 110 };
 111
 112 /**
 113  * struct ubi_info - general UBI information.
 114  * @dev_count: count of UBI devices in system
 115  * @lowest_dev_num: lowest UBI device number
 116  * @highest_dev_num: highest UBI device number
 117  * @version: UBI version
 118  * @ctrl_major: major number of the UBI control device
 119  * @ctrl_minor: minor number of the UBI control device
 120  */
 121 struct ubi_info
 122 {
 123         int dev_count;
 124         int lowest_dev_num;
 125         int highest_dev_num;
 126         int version;
 127         int ctrl_major;
 128         int ctrl_minor;
 129 };
 130
 131 /**
 132  * struct ubi_dev_info - UBI device information.
 133  * @dev_num: UBI device number
 134  * @mtd_num: MTD device number on top of which this UBI device is working
 135  * @vol_count: count of volumes on this UBI device
 136  * @lowest_vol_id: lowest volume ID
 137  * @highest_vol_id: highest volume ID
 138  * @major: major number of corresponding character device
 139  * @minor: minor number of corresponding character device
 140  * @total_lebs: total number of logical eraseblocks on this UBI device
 141  * @avail_lebs: how many logical eraseblocks are not used and available for new
 142  *             volumes
 143  * @total_bytes: @total_lebs * @leb_size
 144  * @avail_bytes: @avail_lebs * @leb_size
 145  * @bad_count: count of bad physical eraseblocks
 146  * @leb_size: logical eraseblock size
 147  * @max_ec: current highest erase counter value
 148  * @bad_rsvd: how many physical eraseblocks of the underlying flash device are
 149  *            reserved for bad eraseblocks handling
 150  * @max_vol_count: maximum possible number of volumes on this UBI device
 151  * @min_io_size: minimum input/output unit size of the UBI device
 152  */
 153 struct ubi_dev_info
 154 {
 155         int dev_num;
 156         int mtd_num;
 157         int vol_count;
 158         int lowest_vol_id;
 159         int highest_vol_id;
 160         int major;
 161         int minor;
 162         int total_lebs;
 163         int avail_lebs;
 164         long long total_bytes;
 165         long long avail_bytes;
 166         int bad_count;
 167         int leb_size;
 168         long long max_ec;
 169         int bad_rsvd;
 170         int max_vol_count;
 171         int min_io_size;
 172 };
 173
 174 /**
 175  * struct ubi_vol_info - UBI volume information.
 176  * @dev_num: UBI device number the volume resides on
 177  * @vol_id: ID of this volume
 178  * @major: major number of corresponding volume character device
 179  * @minor: minor number of corresponding volume character device
 180  * @type: volume type (%UBI_DYNAMIC_VOLUME or %UBI_STATIC_VOLUME)
 181  * @alignment: alignment of this volume
 182  * @data_bytes: how many data bytes are stored on this volume (equivalent to
 183  *              @rsvd_bytes for dynamic volumes)
 184  * @rsvd_bytes: how many bytes are reserved for this volume
 185  * @rsvd_lebs: how many logical eraseblocks are reserved for this volume
 186  * @leb_size: logical eraseblock size of this volume (may be less then
 187  *            device's logical eraseblock size due to alignment)
 188  * @corrupted: non-zero if the volume is corrupted
 189  * @name: volume name (null-terminated)
 190  */
 191 struct ubi_vol_info
 192 {
 193         int dev_num;
 194         int vol_id;
 195         int major;
 196         int minor;
 197         int type;
 198         int alignment;
 199         long long data_bytes;
 200         long long rsvd_bytes;
 201         int rsvd_lebs;
 202         int leb_size;
 203         int corrupted;
 204         char name[UBI_VOL_NAME_MAX + 1];
 205 };
 206
 207 /**
 208  * libubi_open - open UBI library.
 209  *
 210  * This function initializes and opens the UBI library and returns UBI library
 211  * descriptor in case of success and %NULL in case of failure. In case of
 212  * failure, errno contains the error code or zero if UBI is not present in the
 213  * system.
 214  */
 215 libubi_t libubi_open(void);
 216
 217 /**
 218  * libubi_close - close UBI library.
 219  * @desc: UBI library descriptor
 220  */
 221 void libubi_close(libubi_t desc);
 222
 223 /**
 224  * ubi_get_info - get general UBI information.
 225  * @desc: UBI library descriptor
 226  * @info: pointer to the &struct ubi_info object to fill
 227  *
 228  * This function fills the passed @info object with general UBI information and
 229  * returns %0 in case of success and %-1 in case of failure.
 230  */
 231 int ubi_get_info(libubi_t desc, struct ubi_info *info);
 232
 233 /**
 234  * mtd_num2ubi_dev - find UBI device by attached MTD device.
 235  * @@desc: UBI library descriptor
 236  * @mtd_num: MTD device number
 237  * @dev_num: UBI device number is returned here
 238  *
 239  * This function finds UBI device to which MTD device @mtd_num is attached.
 240  * Returns %0 if the UBI device was found and %-1 if not.
 241  */
 242 int mtd_num2ubi_dev(libubi_t desc, int mtd_num, int *dev_num);
 243
 244 /**
 245  * ubi_attach - attach an MTD device by its node path or bt MTD device number
 246  * @desc: UBI library descriptor
 247  * @node: name of the UBI control character device node
 248  * @req: MTD attach request
 249  *
 250  * This function creates new UBI device by attaching an MTD device described by
 251  * @req. If @req->mtd_dev_node is given it should contain path to the MTD
 252  * device node. Otherwise @req->mtd_num will be used.
 253  *
 254  * Returns %0 in case of success, %-1 in case of failure (errno is set) and %1
 255  * if parameter @req->max_beb_per1024 was ignored by kernel (because the kernel
 256  * is old and does not support this feature, which was added in 3.7). The newly
 257  * created UBI device number is returned in @req->dev_num. In the MTD device
 258  * was specified by its device node path, the MTD device number is returned in
 259  * @req->mtd_num.
 260  */
 261 int ubi_attach(libubi_t desc, const char *node, struct ubi_attach_request *req);
 262
 263 /**
 264  * ubi_detach_mtd - detach an MTD device.
 265  * @desc: UBI library descriptor
 266  * @node: name of the UBI control character device node
 267  * @mtd_num: MTD device number to detach
 268  *
 269  * This function detaches MTD device number @mtd_num from UBI, which means the
 270  * corresponding UBI device is removed. Returns zero in case of success and %-1
 271  * in case of failure.
 272  */
 273 int ubi_detach_mtd(libubi_t desc, const char *node, int mtd_num);
 274
 275 /**
 276  * ubi_detach - detach an MTD device by its node path.
 277  * @desc: UBI library descriptor
 278  * @node: name of the UBI control character device node
 279  * @mtd_dev_node: path to an MTD device node
 280  *
 281  * This function detaches an MTD device @mtd_dev_node from UBI. Returns zero in
 282  * case of success and %-1 in case of failure.
 283  */
 284 int ubi_detach(libubi_t desc, const char *node, const char *mtd_dev_node);
 285
 286 /**
 287  * ubi_remove_dev - remove an UBI device.
 288  * @desc: UBI library descriptor
 289  * @node: name of the UBI control character device node
 290  * @ubi_dev: UBI device number to remove
 291  *
 292  * This function removes UBI device number @ubi_dev and returns zero in case of
 293  * success and %-1 in case of failure.
 294  */
 295 int ubi_remove_dev(libubi_t desc, const char *node, int ubi_dev);
 296
 297 /**
 298  * ubi_mkvol - create an UBI volume.
 299  * @desc: UBI library descriptor
 300  * @node: name of the UBI character device to create a volume at
 301  * @req: UBI volume creation request
 302  *
 303  * This function creates a UBI volume as described at @req and returns %0 in
 304  * case of success and %-1 in case of failure. The assigned volume ID is
 305  * returned in @req->vol_id.
 306  */
 307 int ubi_mkvol(libubi_t desc, const char *node, struct ubi_mkvol_request *req);
 308
 309 /**
 310  * ubi_rmvol - remove a UBI volume.
 311  * @desc: UBI library descriptor
 312  * @node: name of the UBI character device to remove a volume from
 313  * @vol_id: ID of the volume to remove
 314  *
 315  * This function removes volume @vol_id from UBI device @node and returns %0 in
 316  * case of success and %-1 in case of failure.
 317  */
 318 int ubi_rmvol(libubi_t desc, const char *node, int vol_id);
 319
 320
 321 /**
 322  * ubi_rnvols - rename UBI volumes.
 323  * @desc: UBI library descriptor
 324  * @node: name of the UBI character device to remove a volume from
 325  * @rnvol: description of volumes to rename
 326  *
 327  * This function removes volume @vol_id from UBI device @node and returns %0 in
 328  * case of success and %-1 in case of failure.
 329  */
 330 int ubi_rnvols(libubi_t desc, const char *node, struct ubi_rnvol_req *rnvol);
 331
 332 /**
 333  * ubi_rsvol - re-size UBI volume.
 334  * @desc: UBI library descriptor
 335  * @node: name of the UBI character device owning the volume which should be
 336  *        re-sized
 337  * @vol_id: volume ID to re-size
 338  * @bytes: new volume size in bytes
 339  *
 340  * This function returns %0 in case of success and %-1 in case of error.
 341  */
 342 int ubi_rsvol(libubi_t desc, const char *node, int vol_id, long long bytes);
 343
 344 /**
 345  * ubi_probe_node - test UBI node.
 346  * @desc: UBI library descriptor
 347  * @node: the node to test
 348  *
 349  * This function tests whether @node is a UBI device or volume node and returns
 350  * %1 if this is an UBI device node, %2 if this is a volume node, and %-1 if
 351  * this is not an UBI device or volume node (errno is ENODEV in this case) or
 352  * if an error occurred.
 353  */
 354 int ubi_probe_node(libubi_t desc, const char *node);
 355
 356 /**
 357  * ubi_get_dev_info - get UBI device information.
 358  * @desc: UBI library descriptor
 359  * @node: name of the UBI character device to fetch information about
 360  * @info: pointer to the &struct ubi_dev_info object to fill
 361  *
 362  * This function fills the passed @info object with UBI device information and
 363  * returns %0 in case of success and %-1 in case of failure. If the UBI device
 364  * corresponding to @node does not exist, errno is set to @ENODEV.
 365  */
 366 int ubi_get_dev_info(libubi_t desc, const char *node,
 367                      struct ubi_dev_info *info);
 368
 369 /**
 370  * ubi_dev_present - check whether an UBI device is present.
 371  * @desc: UBI library descriptor
 372  * @dev_num: UBI device number to check
 373  *
 374  * This function returns %1 if UBI device is present and %0 if not.
 375  */
 376 int ubi_dev_present(libubi_t desc, int dev_num);
 377
 378 /**
 379  * ubi_get_dev_info1 - get UBI device information.
 380  * @desc: UBI library descriptor
 381  * @dev_num: UBI device number to fetch information about
 382  * @info: pointer to the &struct ubi_dev_info object to fill
 383  *
 384  * This function is identical to 'ubi_get_dev_info()' except that it accepts UBI
 385  * device number, not UBI character device. If the UBI device @dev_num does not
 386  * exist, errno is set to @ENODEV.
 387  */
 388 int ubi_get_dev_info1(libubi_t desc, int dev_num, struct ubi_dev_info *info);
 389
 390 /**
 391  * ubi_get_vol_info - get UBI volume information.
 392  * @desc: UBI library descriptor
 393  * @node: name of the UBI volume character device to fetch information about
 394  * @info: pointer to the &struct ubi_vol_info object to fill
 395  *
 396  * This function fills the passed @info object with UBI volume information and
 397  * returns %0 in case of success and %-1 in case of failure. If the UBI volume
 398  * corresponding to @node does not exist, errno is set to @ENODEV.
 399  */
 400 int ubi_get_vol_info(libubi_t desc, const char *node,
 401                      struct ubi_vol_info *info);
 402
 403 /**
 404  * ubi_get_vol_info1 - get UBI volume information.
 405  * @desc: UBI library descriptor
 406  * @dev_num: UBI device number
 407  * @vol_id: ID of the UBI volume to fetch information about
 408  * @info: pointer to the &struct ubi_vol_info object to fill
 409  *
 410  * This function is identical to 'ubi_get_vol_info()' except that it accepts UBI
 411  * volume ID, not UBI volume character device. If the UBI device @dev_num does
 412  * not exist, or if the UBI volume @vol_id does not exist, errno is set to
 413  * @ENODEV.
 414  */
 415 int ubi_get_vol_info1(libubi_t desc, int dev_num, int vol_id,
 416                       struct ubi_vol_info *info);
 417
 418 /**
 419  * ubi_get_vol_info1_nm - get UBI volume information by volume name.
 420  * @desc: UBI library descriptor
 421  * @dev_num: UBI device number
 422  * @name: name of the UBI volume to fetch information about
 423  * @info: pointer to the &struct ubi_vol_info object to fill
 424  *
 425  * This function is identical to 'ubi_get_vol_info()' except that it accepts UBI
 426  * volume name, not UBI volume ID. If the UBI device @dev_num does not exist,
 427  * or if the UBI volume @name does not exist, errno is set to @ENODEV.
 428  */
 429 int ubi_get_vol_info1_nm(libubi_t desc, int dev_num, const char *name,
 430                          struct ubi_vol_info *info);
 431
 432 /**
 433  * ubi_update_start - start UBI volume update.
 434  * @desc: UBI library descriptor
 435  * @fd: volume character device file descriptor
 436  * @bytes: how many bytes will be written to the volume
 437  *
 438  * This function initiates UBI volume update and returns %0 in case of success
 439  * and %-1 in case of error. The caller is assumed to write @bytes data to the
 440  * volume @fd afterward.
 441  */
 442 int ubi_update_start(libubi_t desc, int fd, long long bytes);
 443
 444 /**
 445  * ubi_leb_change_start - start atomic LEB change.
 446  * @desc: UBI library descriptor
 447  * @fd: volume character device file descriptor
 448  * @lnum: LEB number to change
 449  * @bytes: how many bytes of new data will be written to the LEB
 450  *
 451  * This function initiates atomic LEB change operation and returns %0 in case
 452  * of success and %-1 in case of error. he caller is assumed to write @bytes
 453  * data to the volume @fd afterward.
 454  */
 455 int ubi_leb_change_start(libubi_t desc, int fd, int lnum, int bytes);
 456
 457 /**
 458  * ubi_set_property - set volume propety.
 459  * @fd: volume character device file descriptor
 460  * @property: the property to change (%UBI_VOL_PROP_DIRECT_WRITE, etc)
 461  * @value: new value of the changed property
 462  *
 463  * This function changes a property of a volume. Returns zero in case of
 464  * success and a negative error code in case of error.
 465  */
 466 int ubi_set_property(int fd, uint8_t property, uint64_t value);
 467
 468 /**
 469  * ubi_leb_unmap - unmap a logical eraseblock.
 470  * @fd: volume character device file descriptor
 471  * @lnum: logical eraseblock to unmap
 472  *
 473  * This function unmaps LEB @lnum and returns zero in case of success and a
 474  * negative error code in case of error.
 475  */
 476 int ubi_leb_unmap(int fd, int lnum);
 477
 478 /**
 479  * ubi_is_mapped - check if logical eraseblock is mapped.
 480  * @fd: volume character device file descriptor
 481  * @lnum: logical eraseblock number
 482  *
 483  * This function checks if logical eraseblock @lnum is mapped to a physical
 484  * eraseblock. If a logical eraseblock is un-mapped, this does not necessarily
 485  * mean it will still be un-mapped after the UBI device is re-attached. The
 486  * logical eraseblock may become mapped to the physical eraseblock it was last
 487  * mapped to.
 488  *
 489  * This function returns %1 if the LEB is mapped, %0 if not, and %-1 in case of
 490  * failure. If the volume is damaged because of an interrupted update errno
 491  * set with %EBADF error code.
 492  */
 493 int ubi_is_mapped(int fd, int lnum);
 494
 495 #ifdef __cplusplus
 496 }
 497 #endif
 498
 499 #endif /* !__LIBUBI_H__ */