diff options
Diffstat (limited to 'ubi-utils/inc')
| -rw-r--r-- | ubi-utils/inc/libubi.h | 268 | ||||
| -rw-r--r-- | ubi-utils/inc/libubiold.h | 310 |
2 files changed, 578 insertions, 0 deletions
diff --git a/ubi-utils/inc/libubi.h b/ubi-utils/inc/libubi.h new file mode 100644 index 0000000..d39c1b9 --- /dev/null +++ b/ubi-utils/inc/libubi.h @@ -0,0 +1,268 @@ +/* + * Copyright (c) International Business Machines Corp., 2006 + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See + * the GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + * + * Author: Artem B. Bityutskiy + * + * UBI (Unsorted Block Images) library. + */ + +#ifndef __LIBUBI_H__ +#define __LIBUBI_H__ + +#include <stdint.h> +#include <mtd/ubi-user.h> +#include <ctype.h> +#include <mtd/ubi-header.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/* UBI version libubi is made for */ +#define LIBUBI_UBI_VERSION 1 + +/* UBI library descriptor */ +typedef void * libubi_t; + +/** + * struct ubi_mkvol_request - volume creation request. + * */ +struct ubi_mkvol_request +{ + int vol_id; + int alignment; + long long bytes; + int vol_type; + const char *name; +}; + +/** + * struct ubi_info - general UBI information. + * + * @dev_count count of UBI devices in system + * @lowest_dev_num lowest UBI device number + * @highest_dev_num highest UBI device number + * @version UBI version + */ +struct ubi_info +{ + int dev_count; + int lowest_dev_num; + int highest_dev_num; + int version; +}; + +/** + * struct ubi_dev_info - UBI device information. + * + * @vol_count count of volumes on this UBI device + * @lowest_vol_num lowest volume number + * @highest_vol_num highest volume number + * @total_ebs total number of eraseblocks on this UBI device + * @avail_ebs how many eraseblocks are not used and available for new + * volumes + * @total_bytes @total_ebs * @eb_size + * @avail_bytes @avail_ebs * @eb_size + * @bad_count count of bad eraseblocks + * @eb_size size of UBI eraseblock + * @max_ec current highest erase counter value + * @bad_rsvd how many physical eraseblocks of the underlying flash + * device are reserved for bad eraseblocks handling + * @max_vol_count maximum count of volumes on this UBI device + * @min_io_size minimum input/output size of the UBI device + */ +struct ubi_dev_info +{ + int dev_num; + int vol_count; + int lowest_vol_num; + int highest_vol_num; + int total_ebs; + int avail_ebs; + long long total_bytes; + long long avail_bytes; + int bad_count; + int eb_size; + long long max_ec; + int bad_rsvd; + int max_vol_count; + int min_io_size; +}; + +/** + * struct ubi_vol_info - UBI volume information. + * + * @dev_num UBI device number the volume resides on + * @vol_id ID of this volume + * @type volume type (%UBI_DYNAMIC_VOLUME or %UBI_STATIC_VOLUME) + * @alignment alignemnt of this volume + * @data_bytes how many data bytes are stored on this volume (equivalent to + * @rsvd_bytes for dynamic volumes) + * @rsvd_bytes how many bytes are reserved for this volume + * @rsvd_ebs how many eraseblocks are reserved for this volume + * @eb_size logical eraseblock size of this volume (may be less then + * device's logical eraseblock size due to alignment) + * @corrupted the volume is corrupted if this flag is not zero + * @name volume name (null-terminated) + */ +struct ubi_vol_info +{ + int dev_num; + int vol_id; + int type; + int alignment; + long long data_bytes; + long long rsvd_bytes; + int rsvd_ebs; + int eb_size; + int corrupted; + char name[UBI_VOL_NAME_MAX + 1]; +}; + +/** + * libubi_open - open UBI library. + * + * This function initializes and opens the UBI library and returns UBI library + * descriptor in case of success and %NULL in case of failure. + */ +libubi_t libubi_open(void); + +/** + * libubi_close - close UBI library + * + * @desc UBI library descriptor + */ +void libubi_close(libubi_t desc); + +/** + * ubi_get_info - get general UBI information. + * + * @info pointer to the &struct ubi_info object to fill + * @desc UBI library descriptor + * + * This function fills the passed @info object with general UBI information and + * returns %0 in case of success and %-1 in case of failure. + */ +int ubi_get_info(libubi_t desc, struct ubi_info *info); + +/** + * ubi_mkvol - create an UBI volume. + * + * @desc UBI library descriptor + * @node name of the UBI character device to create a volume at + * @req UBI volume creation request (defined at <mtd/ubi-user.h>) + * + * This function creates a UBI volume as described at @req and returns %0 in + * case of success and %-1 in case of failure. The assigned volume ID is + * returned in @req->vol_id. + */ +int ubi_mkvol(libubi_t desc, const char *node, struct ubi_mkvol_request *req); + +/** + * ubi_rmvol - remove a UBI volume. + * + * @desc UBI library descriptor + * @node name of the UBI character device to remove a volume from + * @vol_id ID of the volume to remove + * + * This function removes volume @vol_id from UBI device @node and returns %0 in + * case of success and %-1 in case of failure. + */ +int ubi_rmvol(libubi_t desc, const char *node, int vol_id); + +/** + * ubi_rsvol - re-size UBI volume. + * + * @desc UBI library descriptor + * @node name of the UBI character device owning the volume which should be + * re-sized + * @vol_id volume ID to re-size + * @bytes new volume size in bytes + * + * This function returns %0 in case of success and %-1 in case of error. + */ +int ubi_rsvol(libubi_t desc, const char *node, int vol_id, long long bytes); + +/** + * ubi_get_dev_info - get UBI device information. + * + * @desc UBI library descriptor + * @node name of the UBI character device to fetch information about + * @info pointer to the &struct ubi_dev_info object to fill + * + * This function fills the passed @info object with UBI device information and + * returns %0 in case of success and %-1 in case of failure. + */ +int ubi_get_dev_info(libubi_t desc, const char *node, + struct ubi_dev_info *info); + +/** + * ubi_get_dev_info1 - get UBI device information. + * + * @desc UBI library descriptor + * @dev_num UBI device number to fetch information about + * @info pointer to the &struct ubi_dev_info object to fill + * + * This function is identical to 'ubi_get_dev_info()' except that it accepts UBI + * device number, not UBI character device. + */ +int ubi_get_dev_info1(libubi_t desc, int dev_num, struct ubi_dev_info *info); + +/** + * ubi_get_vol_info - get UBI volume information. + * + * @desc UBI library descriptor + * @node name of the UBI volume character device to fetch information about + * @info pointer to the &struct ubi_vol_info object to fill + * + * This function fills the passed @info object with UBI volume information and + * returns %0 in case of success and %-1 in case of failure. + */ +int ubi_get_vol_info(libubi_t desc, const char *node, + struct ubi_vol_info *info); + +/** + * ubi_get_vol_info1 - get UBI volume information. + * + * @desc UBI library descriptor + * @dev_num UBI device number + * @vol_id ID of the UBI volume to fetch information about + * @info pointer to the &struct ubi_vol_info object to fill + * + * This function is identical to 'ubi_get_vol_info()' except that it accepts UBI + * volume number, not UBI volume character device. + */ +int ubi_get_vol_info1(libubi_t desc, int dev_num, int vol_id, + struct ubi_vol_info *info); + +/** + * ubi_update_start - start UBI volume update. + * + * @desc UBI library descriptor + * @fd volume character devie file descriptor + * @bytes how many bytes will be written to the volume + * + * This function initiates UBI volume update and returns %0 in case of success + * and %-1 in case of error. + */ +int ubi_update_start(libubi_t desc, int fd, long long bytes); + +#ifdef __cplusplus +} +#endif + +#endif /* !__LIBUBI_H__ */ diff --git a/ubi-utils/inc/libubiold.h b/ubi-utils/inc/libubiold.h new file mode 100644 index 0000000..f13d812 --- /dev/null +++ b/ubi-utils/inc/libubiold.h @@ -0,0 +1,310 @@ +#ifndef __UBI_H__ +#define __UBI_H__ +/* + * Copyright (c) International Business Machines Corp., 2006 + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See + * the GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + */ + +/* + * UBI (Unsorted Block Images) library. + * @file libubi.h + * @author Artem B. Bityutskiy + * @author Additions: Oliver Lohmann + * @version 1.0 + */ + +#include <stdint.h> +#include <mtd/ubi-user.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @section eh Error Handling + * The following error indication policy is used: in case of success, all + * library functions return 0, in case of failure they either return UBI error + * codes, or -1 if a system error occured; in the latter case the exact error + * code has to be in the errno variable. + * + * @def UBI_ENOTFOUND + * @brief UBI was not found in the system. + * @def UBI_EBUG + * @brief An error due to bug in kernel part of UBI in UBI library. + * @def UBI_EINVAL + * @brief Invalid argument. + * @def UBI_EMACS + * @brief Highest error value. + */ +#define UBI_ENOTFOUND 1 +#define UBI_EBUG 2 +#define UBI_EINVAL 3 +#define UBI_EMAX 4 + + +/** + * UBI library descriptor, vague for library users. + */ +typedef struct ubi_lib *ubi_lib_t; + +/** + * struct ubi_info - general information about UBI. + * + * @version UBI version + * @nlen_max maximum length of names of volumes + * @dev_count count UBI devices in the system + */ +struct ubi_info +{ + unsigned int version; + unsigned int nlen_max; + unsigned int dev_count; +}; + +/** + * struct ubi_dev_info - information about an UBI device + * + * @wear average number of erasures of flash erasable blocks + * @major major number of the corresponding character device + * @minor minor number of the corresponding character device + * @eb_size size of eraseblocks + * @total_ebs total count of eraseblocks + * @avail_ebs count of unused eraseblock available for new volumes + * @vol_count total count of volumes in this UBI device + */ +struct ubi_dev_info +{ + unsigned long long wear; + unsigned int major; + unsigned int minor; + unsigned int eb_size; + unsigned int total_ebs; + unsigned int avail_ebs; + unsigned int vol_count; +}; + +/** + * struct ubi_vol_info - information about an UBI volume + * + * @bytes volume size in bytes + * @eraseblocks volume size in eraseblocks + * @major major number of the corresponding character device + * @minor minor number of the corresponding character device + * @type volume type (%UBI_DYNAMIC_VOLUME or %UBI_STATIC_VOLUME) + * @dev_path device path to volume + * @name volume name + */ +struct ubi_vol_info +{ + unsigned long long bytes; + unsigned int eraseblocks; + unsigned int major; + unsigned int minor; + int type; + char *dev_path; + char *name; +}; + +/** + * ubi_mkvol - create a dynamic UBI volume. + * + * @desc UBI library descriptor + * @devn Number of UBI device to create new volume on + * @vol_id volume ID to assign to the new volume + * @vol_type volume type (%UBI_DYNAMIC_VOLUME or %UBI_STATIC_VOLUME) + * @bytes volume size in bytes + * @alignment volume alignment + * @name volume name + * + * This function creates new UBI volume. If @vol_id is %UBI_VOLN_AUTO, then + * volume number is assigned automatically. This function returns positive + * volume number of the new volume in case of success or %-1 in case of + * failure. + */ +int ubi_mkvol(ubi_lib_t desc, int devn, int vol_id, int vol_type, + long long bytes, int alignment, const char *name); + +/** + * ubi_rmvol - remove a volume. + * + * @desc UBI library descriptor + * @devn Number of UBI device to remove volume from + * @vol_id volume ID to remove + * + * This function returns zero in case of success or %-1 in case of failure. + */ +int ubi_rmvol(ubi_lib_t desc, int devn, int vol_id); + +/** + * ubi_get_info - get UBI information. + * + * @desc UBI library descriptor + * @ubi UBI information is returned here + * + * This function retrieves information about UBI and puts it to @ubi. Returns + * zero in case of success and %-1 in case of failure. + */ +int ubi_get_info(ubi_lib_t desc, struct ubi_info *ubi); + +/** + * ubi_vol_open - open a UBI volume + * + * @desc UBI library descriptor + * @devn Number of UBI device on which to open the volume + * @vol_id Number of UBI device on which to open the volume + * @flags Flags to pass to open() + * + * This function opens a UBI volume on a given UBI device. It returns + * the file descriptor of the opened volume device. In case of an + * error %-1 is returned and errno is set appropriately. + */ +int ubi_vol_open(ubi_lib_t desc, int devn, int vol_id, int flags); + +/** + * ubi_vol_close - close a UBI volume + * + * @vol_fd file descriptor of UBI volume to close + * + * This function closes the given UBI device. + */ +int ubi_vol_close(int vol_fd); + +/** + * ubi_vol_update - initiate volume update on a UBI volume + * @vol_fd File descriptor of UBI volume to update + * @bytes No. of bytes which shall be written. + * + * Initiates a volume update on a given volume. The caller must then + * actually write the appropriate number of bytes to the volume by + * calling write(). Returns 0 on success, else error. + */ +int ubi_vol_update(int vol_fd, unsigned long long bytes); + +/** + * ubi_vol_fopen_read - open a volume for reading, returning a FILE * + * @desc UBI library descriptor + * @devn UBI device number + * @vol_id volume ID to read + * + * Opens a volume for reading. Reading itself can then be performed + * with fread(). The stream can be closed with fclose(). Returns a + * stream on success, else NULL. + */ +FILE * +ubi_vol_fopen_read(ubi_lib_t desc, int devn, uint32_t vol_id); + +/** + * ubi_vol_fopen_update - open a volume for writing, returning a FILE * + * @desc UBI library descriptor + * @devn UBI device number + * @vol_id volume ID to update + * @bytes No. of bytes which shall be written. + * + * Initiates a volume update on a given volume. The caller must then + * actually write the appropriate number of bytes to the volume by + * calling fwrite(). The file can be closed with fclose(). Returns a + * stream on success, else NULL. + */ +FILE * +ubi_vol_fopen_update(ubi_lib_t desc, int devn, uint32_t vol_id, + unsigned long long bytes); + +/** + * ubi_vol_get_used_bytes - determine used bytes in a UBI volume + * @vol_fd File descriptor of UBI volume + * @bytes Pointer to result + * + * Returns 0 on success, else error. + */ +int ubi_vol_get_used_bytes(int vol_fd, unsigned long long *bytes); + +/** + * ubi_open - open UBI library. + * + * @desc A pointer to an UBI library descriptor + * + * Returns zero in case of success. + */ +int ubi_open(ubi_lib_t *desc); + +/** + * ubi_close - close UBI library. + * + * @desc A pointer to an UBI library descriptor + */ +int ubi_close(ubi_lib_t *desc); + + +/** + * ubi_perror - print UBI error. + * + * @prefix a prefix string to prepend to the error message + * @code error code + * + * If @code is %-1, this function calls 'perror()' + */ +void ubi_perror(const char *prefix, int code); + +/** + * ubi_set_cdev_pattern - set 'sprintf()'-like pattern of paths to UBI + * character devices. + * + * @desc UBI library descriptor + * @pattern the pattern to set + * + * The default UBI character device path is "/dev/ubi%u". + */ +int ubi_set_cdev_pattern(ubi_lib_t desc, const char *pattern); + +/** + * ubi_get_dev_info get information about an UBI device. + * + * @desc UBI library descriptor + * @devn UBI device number + * @di the requested information is returned here + */ +int ubi_get_dev_info(ubi_lib_t desc, unsigned int devn, + struct ubi_dev_info *di); + +/** + * ubi_set_vol_cdev_pattern - set 'sprintf()'-like pattµern ofpaths to UBI + * volume character devices. + * + * @desc UBI library descriptor + * @pattern the pattern to set + * + * The default UBI character device path is "/dev/ubi%u_%u". + */ +int ubi_set_vol_cdev_pattern(ubi_lib_t desc, const char *pattern); + +/** + * ubi_get_vol_info - get information about an UBI volume + * + * @desc UBI library descriptor + * @devn UBI device number the volume belongs to + * @vol_id the requested volume number + * @vi volume information is returned here + * + * Users must free the volume name string @vi->name. + */ +int ubi_get_vol_info(ubi_lib_t desc, unsigned int devn, unsigned int vol_id, + struct ubi_vol_info *vi); + +#ifdef __cplusplus +} +#endif + +#endif /* !__UBI_H__ */ |