Add bmaptool man page

Change-Id: I9a0e7b29e3d0506801f04000cd20eb4283c253b3
Signed-off-by: Artem Bityutskiy <artem.bityutskiy@intel.com>

diff --git a/docs/man1/bmaptool.1 b/docs/man1/bmaptool.1
new file mode 100644 (file)
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] <subcommand> [<args>]
+
+.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 <artem.bityutskiy@linux.intel.com>.
+
+.SH REPORTING BUGS
+
+Please, report bugs to Artem Bityutskiy <artem.bityutskiy@linux.intel.com>.