From 2fed7882a8aa97618d66b5f6517e1068e19edafa Mon Sep 17 00:00:00 2001 From: Artem Bityutskiy Date: Fri, 18 Jan 2013 16:28:47 +0200 Subject: [PATCH] Add bmaptool man page Change-Id: I9a0e7b29e3d0506801f04000cd20eb4283c253b3 Signed-off-by: Artem Bityutskiy --- docs/man1/bmaptool.1 | 228 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 docs/man1/bmaptool.1 diff --git a/docs/man1/bmaptool.1 b/docs/man1/bmaptool.1 new file mode 100644 index 0000000..c002d1e --- /dev/null +++ b/docs/man1/bmaptool.1 @@ -0,0 +1,228 @@ +.TH BMAPTOOL "1" "January 2013" "bmap-tools 2.0" "User Commands" + +.SH NAME + +.PP +bmaptool - create block map (bmap) for a file or copy a file using bmap + +.SH SYNOPSIS + +.PP +.B bmaptool +[\-\-help] [\-\-version] [\-\-quiet] [] + +.SH DESCRIPTION + +.PP +\fIBmaptool\fR is a generic tool for creating the block map (bmap) for a file and +copying files using the block map. The idea is that large files, like raw +system image files, can be copied or flashed a lot faster with \fIbmaptool\fR than +with traditional tools, like "dd" or "cp". + +.PP +\fIBmaptool\fR supports 2 subcommands: +.RS 2 +1. \fBcopy\fR - copy a file to another file using bmap or flash an image to a block device +.RE +.RS 2 +2. \fBcreate\fR - create a bmap for a file +.RE + +.PP +Please, find full documentation for the project at +\fBhttps://source.tizen.org/documentation/reference/bmaptool\fR + +.\" =========================================================================== +.\" Global options +.\" =========================================================================== +.SH OPTIONS + +.PP +\-\-version +.RS 2 +Print \fIbmaptool\fR version and exit. +.RE + +.PP +\-h, \-\-help +.RS 2 +Print short help text and exit. +.RE + +.PP +\-q, \-\-quiet +.RS 2 +Be quiet, do not print extra information. +.RE + +.\" =========================================================================== +.\" Commands descriptions +.\" =========================================================================== +.SH COMMANDS + +.\" +.\" The "copy" command description +.\" +.SS \fBcopy\fR [options] IMAGE DEST + +.RS 2 +Copy file IMAGE to the destination regular file or block device DEST +using bmap. IMAGE may either be a local path or an URL. DEST may either +be a regular file or a block device (only local). + +.PP +Unless the bmap file is explicitly specified with the "--bmap" option, \fIbmaptool\fR +automatically discovers it by looking for a file with the same basename as IMAGE +but with the ".bmap" extension. The bmap file is only looked for in +IMAGE's directory (or base URL, in case IMAGE was specified as an URL). If the +bmap file is not found, \fIbmaptool\fR fails. To copy without bmap, use +the "--nobmap" option. + +.PP +Both IMAGE and the bmap file may be specified as an URL (http://, ftp://, +https://, file://). In order to make \fIbmaptool\fR use a proxy server, please, +specify the proxy using the standard "$http_proxy", "$https_proxy", "$ftp_proxy" +or "$no_proxy" environment variables. + +.PP +IMAGE may be compressed, in which case \fIbmaptool\fR decompresses it on-the-fly. +The compression type is detected by the file extension and the following +compression types are supported: ".bz2", ".gz", ".tar.gz" or ".tgz", and +".tar.bz2". If IMAGE has none of these extensions, it is assumed to be +uncompressed. + +.PP +If DEST is a block device node (e.g., "/dev/sdg"), \fIbmaptool\fR opens it in +exclusive mode. This means that it will fail if any other process has IMAGE +block device node opened. This also means that no other processes will be able +to open IMAGE until \fIbmaptool\fR finishes the copying. Please, see semantics +of the "O_EXCL" flag of the "open()" syscall. +.RE + +.\" +.\" The "copy" command's options +.\" +.RS 2 +\fBOPTIONS\fR +.RS 2 +\-h, \-\-help +.RS 2 +Print short help text about the "copy" subcommand and exit. +.RE + +.PP +\-\-bmap BMAP +.RS 2 +Use bmap file "BMAP" for copying. If this option is not specified, \fIbmaptool\fR +tries to automatically discover the bmap file. +.RE + +.PP +\-\-nobmap +.RS 2 +Disable automatic bmap file discovery and force flashing entire IMAGE without bmap. +.RE + +.PP +\-\-no-verify +.RS 2 +Do not verify SHA1 checksums when copying (not recommended). The checksums are +stored in the bmap file, and normally \fIbmaptool\fR verifies that the data in +IMAGE matches the checksums. +.RE +.RE +.RE + +.\" +.\" The "copy" command's examples +.\" +.RS 2 +\fBEXAMPLES\fR +.RS 2 +\fIbmaptool\fR copy --bmap image.bmap image.raw /dev/sdg +.RS 2 +Copy non-compressed local file "image.raw" to block device "/dev/sdg" using bmap file "image.bmap". +.RE +.RE + +.RS 2 +\fIbmaptool\fR copy image.raw.bz2 /dev/sdg +.RS 2 +Copy bz2-compressed local file "image.raw.bz2" to block device "/dev/sdg". The +image file is uncompressed on-the-fly. The bamap file is discovered +automatically. +.RE +.RE + +.RS 2 +\fIbmaptool\fR copy http://my-server.com/files/image.raw.bz2 $HOME/tmp/file +.RS 2 +Copy bz2-compressed remote "image.raw.bz2" to regular file "$HOME/tmp/file". +The image file is uncompressed on-the-fly. The bamap file is discovered +automatically. +.RE +.RE + + +.\" +.\" The "create" command description +.\" +.SS \fBcreate\fR [options] IMAGE + +.PP +Generate bmap for a regular file IMAGE. Internally, this subcommand uses the +Linux "FIEMAP" ioctl to find out which IMAGE blocks are mapped. By default, the +resulting bmap file is printed to stdout, unless the "--output" option is used. + +.\" +.\" The "create" command's options +.\" +.RS 2 +\fBOPTIONS\fR +.RS 2 +\-h, \-\-help +.RS 2 +Print short help text about the "create" subcommand and exit. +.RE + +.PP +\-o, \-\-output OUTPUT +.RS 2 +Save the generated bmap in the OUTPUT file (by default the bmap is printed to +stdout). +.RE + +.PP +\-\-no-checksum +.RS 2 +Generate a bmap file without SHA1 checksums (not recommended). +.RE +.RE +.RE + +.\" +.\" The "create" command's examples +.\" +.RS 2 +\fBEXAMPLES\fR +.RS 2 +\fIbmaptool\fR create image.raw +.RS 2 +Generate bmap for the "image.raw" file and print it to stdout. +.RE +.RE + +.RS 2 +\fIbmaptool\fR create -o image.bmap image.raw +.RS 2 +Generate bmap for the "image.raw" file and save it in "image.bmap". +.RE +.RE + +.SH AUTHOR + +Artem Bityutskiy . + +.SH REPORTING BUGS + +Please, report bugs to Artem Bityutskiy . -- 2.7.4