libfstools: support file paths longer than 255 chars
[project/fstools.git] / 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__ */