2
0

libubi.h 16 KB

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