summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2016-09-01 15:03:14 +0200
committerDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2016-11-17 11:36:56 +0100
commit942dec0faab61b3d9c814ed013c578edde94d0bb (patch)
treec3220d5cdb4e4f12f7c4f2fd77407686ae6c389f
parente635677589fa9fed6310e8ec2c3cab7afa93b9ce (diff)
Add ubinize manpage
This patch removes the lengthy help text from the ubinize utility that attempted to describte the file format and every minor detail, and reformats it into a more readable man page. Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>
-rw-r--r--Makefile.am1
-rw-r--r--ubi-utils/Makemodule.am5
-rw-r--r--ubi-utils/ubinize.8136
-rw-r--r--ubi-utils/ubinize.c66
4 files changed, 153 insertions, 55 deletions
diff --git a/Makefile.am b/Makefile.am
index a3457c0..23c1940 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -22,6 +22,7 @@ noinst_SCRIPTS =
pkglibexec_PROGRAMS =
pkglibexec_SCRIPTS =
dist_man1_MANS =
+dist_man8_MANS =
EXTRA_DIST =
diff --git a/ubi-utils/Makemodule.am b/ubi-utils/Makemodule.am
index ea18235..dc68f38 100644
--- a/ubi-utils/Makemodule.am
+++ b/ubi-utils/Makemodule.am
@@ -66,8 +66,13 @@ UBI_EXTRA = \
UBI_HEADER = \
ubi-utils/include ubi-utils/libubi_int.h
+UBI_MAN = \
+ ubi-utils/ubinize.8
+
EXTRA_DIST += $(UBI_HEADER) $(UBI_EXTRA)
+dist_man8_MANS += $(UBI_MAN)
+
sbin_PROGRAMS += $(UBI_BINS)
noinst_LIBRARIES += libubi.a libubigen.a
diff --git a/ubi-utils/ubinize.8 b/ubi-utils/ubinize.8
new file mode 100644
index 0000000..baf8abf
--- /dev/null
+++ b/ubi-utils/ubinize.8
@@ -0,0 +1,136 @@
+.TH UBINIZE 8 "September 2016" "mtd-utils"
+.SH NAME
+ubinize \- a tool for generating UBI images
+.SH SYNOPSIS
+.B ubinize
+[-o filename] [-p <bytes>] [-m <bytes>] [-s <bytes>] [-O <num>] [-e <num>]
+[-x <num>] [-Q <num>] [-v] [-h] [-V] [--output=<filename>] [--peb-size=<bytes>]
+[--min-io-size=<bytes>] [--sub-page-size=<bytes>] [--vid-hdr-offset=<num>]
+[--erase-counter=<num>] [--ubi-ver=<num>] [--image-seq=<num>] [--verbose]
+[--help] [--version] ini-file
+.SH DESCRIPTION
+An UBI image may contain one or more UBI volumes which have to be defined in
+the input configuration ini-file. The ini file defines all the UBI volumes \-
+their characteristics and the contents, but it does not define the
+characteristics of the flash the UBI image is generated for. Instead, the
+flash characteristics are defined via the command-line options. Note, if not
+sure about some of the command-line parameters, do not specify them and let
+the utility use default values.
+.SH OPTIONS
+.TP
+.BR \-o , " \-\-output=\fIfile\fP"
+Specify output file
+.TP
+.BR \-p , " \-\-peb\-size=\fIbytes\fP"
+Size of the physical eraseblock of the flash this UBI image is created for
+in bytes, kilobytes (KiB), or megabytes (MiB). This parameter is mandatory.
+.TP
+.BR \-m , " \-\-min\-io-size=\fIbytes\fP"
+Minimum input/output unit size of the flash in bytes
+.TP
+.BR \-s , " \-\-sub\-page\-size=\fIbytes\fP"
+Minimum input/output unit used for UBI headers, e.g. sub-page size in case
+of NAND flash (equivalent to the minimum input/output unit size by default).
+.TP
+.BR \-O , " \-\-vid\-hdr\-offset=\fInum\fP"
+Offset if the VID header from start of the physical eraseblock (default is the
+next minimum I/O unit or sub-page after the EC header)
+.TP
+.BR \-e , " \-\-erase\-counter=\fInum\fP"
+The erase counter value to put to EC headers (default is 0).
+.TP
+.BR \-x , " \-\-ubi\-ver=\fInum\fP"
+UBI version number to put to EC headers (default is 1).
+.TP
+.BR \-Q , " \-\-image\-seq=\fInum\fP"
+32-bit UBI image sequence number to use (by default a random number is picked).
+.TP
+.BR \-v , " \-\-verbose"
+Be verbose.
+.TP
+.BR \-h , " \-\-help"
+Print a help message and exit.
+.TP
+.BR \-V , " \-\-version"
+Print program version and exit.
+.SH EXAMPLE
+ubinize -o ubi.img -p 16KiB -m 512 -s 256 cfg.ini
+
+Create UBI image \fIubi.img\fP as described by configuration file
+\fIcfg.ini\fP.
+
+A physical erase block on the flash is \fI16KiB\fP in size and has \fI512\fP
+byte pages with \fI256\fP byte sub-pages.
+.SH INI-FILE FORMAT
+The input configuration ini-file describes all the volumes which have to
+be included to the output UBI image. Each volume is described in its own
+section which may be named arbitrarily. The section consists on
+"key=value" pairs, for example:
+.PP
+.in +4n
+.nf
+[jffs2\-volume]
+mode=ubi
+image=../jffs2.img
+vol_id=1
+vol_size=30MiB
+vol_type=dynamic
+vol_name=jffs2_volume
+vol_flags=autoresize
+vol_alignment=1
+.fi
+.in
+
+This example configuration file tells the utility to create an UBI image
+with one volume with ID 1, volume size 30MiB, the volume is dynamic, has
+name \fIjffs2_volume\fP, \fIautoresize\fP volume flag, and alignment 1.
+
+The \fBimage=../jffs2.img\fP line tells the utility to take the contents of
+the volume from the \fB../jffs2.img\fP file. The size of the image file has
+to be less or equivalent to the volume size (30MiB).
+
+The \fBmode=ubi\fP line is mandatory and just tells that the section describes
+an UBI volume \- other section modes may be added in the future.
+
+Notes:
+.IP \[bu] 4
+Size in vol_size might be specified kilobytes (KiB), megabytes (MiB),
+gigabytes (GiB) or bytes (no modifier).
+.IP \[bu]
+If "vol_size" key is absent, the volume size is assumed to be
+equivalent to the size of the image file (defined by "image" key).
+.IP \[bu]
+If the "image" is absent, the volume is assumed to be empty
+.IP \[bu]
+Volume alignment must not be greater than the logical eraseblock size.
+.IP \[bu]
+One ini file may contain arbitrary number of sections, the utility will
+put all the volumes which are described by these section to the output
+UBI image file.
+.SH AUTHORS
+.nf
+Man page written by David Oberhollenzer, based on the help text of
+the ubinize utility written by Artem Bityutskiy and Oliver Lohmann.
+.fi
+.SH REPORTING BUGS
+Report mtd-utils bugs to the Linux mtd mailing list.
+.TP
+Linux mtd mailing list: <linux-mtd@lists.infradead.org>
+.TP
+Linux mtd home page: <http://www.linux-mtd.infradead.org/>
+.SH AVAILABILITY
+The ubinize command is part of the mtd-utils package and is available from
+ftp://ftp.infradead.org/pub/mtd-utils/.
+.SH COPYRIGHT
+Copyright \(co International Business Machines Corp., 2006
+.br
+Copyright \(co 2008 Nokia Corporation
+.br
+Copyright \(co 2016 sigma star gmbh
+
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl2.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH SEE ALSO
+.BR mkfs.jffs2 (1)
diff --git a/ubi-utils/ubinize.c b/ubi-utils/ubinize.c
index 60bbd9a..b5ebadc 100644
--- a/ubi-utils/ubinize.c
+++ b/ubi-utils/ubinize.c
@@ -39,15 +39,6 @@
#include "common.h"
#include "ubiutils-common.h"
-static const char doc[] = PROGRAM_NAME " version " VERSION
-" - a tool to generate UBI images. An UBI image may contain one or more UBI "
-"volumes which have to be defined in the input configuration ini-file. The "
-"ini file defines all the UBI volumes - their characteristics and the "
-"contents, but it does not define the characteristics of the flash the UBI "
-"image is generated for. Instead, the flash characteristics are defined via "
-"the command-line options. Note, if not sure about some of the command-line "
-"parameters, do not specify them and let the utility use default values.";
-
static const char optionsstr[] =
"-o, --output=<file name> output file name\n"
"-p, --peb-size=<bytes> size of the physical eraseblock of the flash\n"
@@ -72,49 +63,13 @@ static const char optionsstr[] =
" (by default a random number is picked)\n"
"-v, --verbose be verbose\n"
"-h, --help print help message\n"
-"-V, --version print program version";
+"-V, --version print program version\n\n";
static const char usage[] =
-"Usage: " PROGRAM_NAME " [-o filename] [-p <bytes>] [-m <bytes>] [-s <bytes>] [-O <num>] [-e <num>]\n"
-"\t\t[-x <num>] [-Q <num>] [-v] [-h] [-V] [--output=<filename>] [--peb-size=<bytes>]\n"
-"\t\t[--min-io-size=<bytes>] [--sub-page-size=<bytes>] [--vid-hdr-offset=<num>]\n"
-"\t\t[--erase-counter=<num>] [--ubi-ver=<num>] [--image-seq=<num>] [--verbose] [--help]\n"
-"\t\t[--version] ini-file\n"
-"Example: " PROGRAM_NAME " -o ubi.img -p 16KiB -m 512 -s 256 cfg.ini - create UBI image\n"
-" 'ubi.img' as described by configuration file 'cfg.ini'";
-
-static const char ini_doc[] = "INI-file format.\n"
-"The input configuration ini-file describes all the volumes which have to\n"
-"be included to the output UBI image. Each volume is described in its own\n"
-"section which may be named arbitrarily. The section consists on\n"
-"\"key=value\" pairs, for example:\n\n"
-"[jffs2-volume]\n"
-"mode=ubi\n"
-"image=../jffs2.img\n"
-"vol_id=1\n"
-"vol_size=30MiB\n"
-"vol_type=dynamic\n"
-"vol_name=jffs2_volume\n"
-"vol_flags=autoresize\n"
-"vol_alignment=1\n\n"
-"This example configuration file tells the utility to create an UBI image\n"
-"with one volume with ID 1, volume size 30MiB, the volume is dynamic, has\n"
-"name \"jffs2_volume\", \"autoresize\" volume flag, and alignment 1. The\n"
-"\"image=../jffs2.img\" line tells the utility to take the contents of the\n"
-"volume from the \"../jffs2.img\" file. The size of the image file has to be\n"
-"less or equivalent to the volume size (30MiB). The \"mode=ubi\" line is\n"
-"mandatory and just tells that the section describes an UBI volume - other\n"
-"section modes may be added in the future.\n"
-"Notes:\n"
-" * size in vol_size might be specified kilobytes (KiB), megabytes (MiB),\n"
-" gigabytes (GiB) or bytes (no modifier);\n"
-" * if \"vol_size\" key is absent, the volume size is assumed to be\n"
-" equivalent to the size of the image file (defined by \"image\" key);\n"
-" * if the \"image\" is absent, the volume is assumed to be empty;\n"
-" * volume alignment must not be greater than the logical eraseblock size;\n"
-" * one ini file may contain arbitrary number of sections, the utility will\n"
-" put all the volumes which are described by these section to the output\n"
-" UBI image file.";
+"Usage: " PROGRAM_NAME " [options] <ini-file>\n\n"
+"Generate UBI images. An UBI image may contain one or more UBI volumes which\n"
+"have to be defined in the input configuration ini-file. The flash\n"
+"characteristics are defined via the command-line options.\n\n";
static const struct option long_options[] = {
{ .name = "output", .has_arg = 1, .flag = NULL, .val = 'o' },
@@ -227,10 +182,10 @@ static int parse_opt(int argc, char * const argv[])
break;
case 'h':
- ubiutils_print_text(stdout, doc, 80);
- printf("\n%s\n\n", ini_doc);
- printf("%s\n\n", usage);
- printf("%s\n", optionsstr);
+ fputs(usage, stdout);
+ fputs(optionsstr, stdout);
+ printf("For more information see `man 8 %s`\n\n",
+ PROGRAM_NAME);
exit(EXIT_SUCCESS);
case 'V':
@@ -238,7 +193,8 @@ static int parse_opt(int argc, char * const argv[])
exit(EXIT_SUCCESS);
default:
- fprintf(stderr, "Use -h for help\n");
+ fputs(usage, stderr);
+ fputs("Use -h for help\n\n", stderr);
return -1;
}
}