diff options
| -rw-r--r-- | Makefile.am | 1 | ||||
| -rw-r--r-- | ubi-utils/Makemodule.am | 5 | ||||
| -rw-r--r-- | ubi-utils/ubinize.8 | 136 | ||||
| -rw-r--r-- | ubi-utils/ubinize.c | 66 |
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; } } |