[PATCH v4 08/10] cmd: ubi: export more APIs to public

[Weijie Gao]

Export the following functions to public:

- ubi_detach(): this is paired with ubi_part(). One may call this function
  to completely clean up the ubi subsystem after using ubi_part().

- ubi_{create,find,remove}_vol: this is a set of functions for volume
  management.

The original ubi_create_vol is renamed to __ubi_create_vol to allow the new
ubi_create_vol() being used as a wrapper for __ubi_create_vol() with volume
name.

Also, comments are added for all exported functions.

Signed-off-by: Weijie Gao <weijie.gao at mediatek.com>
---
v4: squashed api function comments into this patch.
    make ubi_remove_vol() as a wrapper of __ubi_remove_vol() due to changes
     of previous patch.
v3: updated commit message
v2: not changed
---
 cmd/ubi.c           | 23 +++++++++---
 include/ubi_uboot.h | 91 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 108 insertions(+), 6 deletions(-)

diff --git a/cmd/ubi.c b/cmd/ubi.c
index b0b513cfe53..9b2b66b5a99 100644
--- a/cmd/ubi.c
+++ b/cmd/ubi.c
@@ -213,8 +213,8 @@ bad:
 	return err;
 }
 
-static int ubi_create_vol(const char *volume, int64_t size, bool dynamic,
-			  int vol_id, bool skipcheck)
+int ubi_create_vol(const char *volume, int64_t size, bool dynamic, int vol_id,
+		   bool skipcheck)
 {
 	struct ubi_mkvol_req req;
 	int err;
@@ -246,7 +246,7 @@ static int ubi_create_vol(const char *volume, int64_t size, bool dynamic,
 	return ubi_create_volume(ubi, &req);
 }
 
-static struct ubi_volume *ubi_find_volume(const char *volume)
+struct ubi_volume *ubi_find_volume(const char *volume)
 {
 	struct ubi_volume *vol;
 	int i;
@@ -270,7 +270,7 @@ static struct ubi_volume *ubi_require_volume(const char *volume)
 	return vol;
 }
 
-static int ubi_remove_vol(struct ubi_volume *vol)
+static int __ubi_remove_vol(struct ubi_volume *vol)
 {
 	int err, reserved_pebs, i;
 
@@ -315,6 +315,17 @@ out_err:
 	return err;
 }
 
+int ubi_remove_vol(const char *volume)
+{
+	struct ubi_volume *vol;
+
+	vol = ubi_require_volume(volume);
+	if (!vol)
+		return -ENODEV;
+
+	return __ubi_remove_vol(vol);
+}
+
 static int ubi_rename_vol(const char *oldname, const char *newname)
 {
 	struct ubi_volume *vol;
@@ -632,7 +643,7 @@ static int ubi_set_skip_check(const char *volume, bool skip_check)
 	return ubi_change_vtbl_record(ubi, vol->vol_id, &vtbl_rec);
 }
 
-static int ubi_detach(void)
+int ubi_detach(void)
 {
 #ifdef CONFIG_CMD_UBIFS
 	/*
@@ -830,7 +841,7 @@ static int do_ubi(struct cmd_tbl *cmdtp, int flag, int argc, char *const argv[])
 
 			vol_id = vol->vol_id;
 
-			ret = ubi_remove_vol(vol);
+			ret = __ubi_remove_vol(vol);
 			if (ret)
 				return CMD_RET_FAILURE;
 
diff --git a/include/ubi_uboot.h b/include/ubi_uboot.h
index 6ebd8a3b613..c337b760e96 100644
--- a/include/ubi_uboot.h
+++ b/include/ubi_uboot.h
@@ -47,11 +47,102 @@
 int ubi_mtd_param_parse(const char *val, struct kernel_param *kp);
 int ubi_init(void);
 void ubi_exit(void);
+
+/**
+ * ubi_detach() - detach UBI from MTD partition
+ *
+ * This function performs the cleanup of the UBI subsystem to make sure the
+ * MTD partition can be safely used for another purpose, or be attached again
+ * with ubi_part().
+ *
+ * Any mounted UBIFS will be unmounted automatically.
+ *
+ * Return: 0
+ */
+int ubi_detach(void);
+
+/**
+ * ubi_part() - attach UBI to MTD partition
+ * @part_name: name of the MTD partition to attach
+ * @vid_header_offset: VID header offset (string)
+ *
+ * This function detaches any existing UBI device, then probes for the
+ * specified MTD partition, and then scans it to initialize UBI.
+ *
+ * @vid_header_offset is optional and is usually set to NULL.
+ *
+ * Return: 0 on success, 1 if partition not found, or -ve on error.
+ */
 int ubi_part(const char *part_name, const char *vid_header_offset);
+
+/**
+ * ubi_volume_write() - write data to UBI volume
+ * @volume: name of the volume to write to
+ * @buf: data buffer to be written
+ * @offset: start offset for writing
+ * @size: number of bytes to write
+ *
+ * This function writes data to the specific UBI volume. If the offset is zero,
+ * it initiates a full volume update. Otherwise, it performs an offset-based
+ * write using LEB changes.
+ *
+ * Return: 0 on success, or -ve on error.
+ */
 int ubi_volume_write(const char *volume, const void *buf, loff_t offset,
 		     size_t size);
+
+/**
+ * ubi_volume_read() - read data from UBI volume
+ * @volume: name of the volume to read from
+ * @buf: buffer to hold the read data
+ * @offset: start offset for reading
+ * @size: number of bytes to read
+ *
+ * This function reads data from the specified UBI volume. If @size is zero,
+ * the function reads the entire volume content starting from @offset.
+ *
+ * Return: 0 on success, or -ve on error.
+ */
 int ubi_volume_read(const char *volume, void *buf, loff_t offset, size_t size);
 
+/**
+ * ubi_create_vol() - create UBI volume
+ * @volume: name of the volume to create
+ * @size: size of the volume in bytes
+ * @dynamic: create dynamic volume if set to true
+ * @vol_id: volume ID
+ * @skipcheck: skip CRC check on this volume if set to true
+ *
+ * This function creates a new UBI volume with the specified parameters.
+ * If @size is negative, all available space will be used.
+ * For volume ID auto assignment, pass %UBI_VOL_NUM_AUTO to @vol_id.
+ *
+ * Return: 0 on success, or -ve on error.
+ */
+int ubi_create_vol(const char *volume, int64_t size, bool dynamic, int vol_id,
+		   bool skipcheck);
+
+/**
+ * ubi_find_volume() - find UBI volume by name
+ * @volume: name of the volume to find
+ *
+ * This function searches for a UBI volume with the specified name in the
+ * current UBI device.
+ *
+ * Return: pointer to the UBI volume structure, or %NULL if not found.
+ */
+struct ubi_volume *ubi_find_volume(const char *volume);
+
+/**
+ * ubi_remove_vol() - remove UBI volume
+ * @volume: name of the volume to remove
+ *
+ * This function removes an existing UBI volume from the current UBI device.
+ *
+ * Return: 0 on success, or -ve on error.
+ */
+int ubi_remove_vol(const char *volume);
+
 extern struct ubi_device *ubi_devices[];
 int cmd_ubifs_mount(const char *vol_name);
 int cmd_ubifs_umount(void);
-- 
2.45.2