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__ */ 500
This page was automatically generated by LXR 0.3.1. • OpenWrt