[man pages] Various updates.

Makefile.in

@@ -107,10 +107,10 @@ SOURCE=\
 	thin-provisioning/thin_repair.cc \
 	thin-provisioning/thin_restore.cc \
 	thin-provisioning/thin_rmap.cc \
+	thin-provisioning/thin_trim.cc \
 	thin-provisioning/xml_format.cc
 
 DEVTOOLS_SOURCE=\
-	thin-provisioning/thin_trim.cc \
 	thin-provisioning/thin_ll_dump.cc \
 	thin-provisioning/thin_ll_restore.cc \
 	thin-provisioning/thin_show_duplicates.cc \
@@ -250,6 +250,7 @@ install: bin/pdata_tools
 	ln -s -f pdata_tools $(BINDIR)/thin_restore
 	ln -s -f pdata_tools $(BINDIR)/thin_rmap
 	ln -s -f pdata_tools $(BINDIR)/thin_metadata_size
+	ln -s -f pdata_tools $(BINDIR)/thin_trim
 	ln -s -f pdata_tools $(BINDIR)/era_check
 	ln -s -f pdata_tools $(BINDIR)/era_dump
 	ln -s -f pdata_tools $(BINDIR)/era_invalidate
@@ -257,6 +258,7 @@ install: bin/pdata_tools
 	$(INSTALL_DIR) $(MANPATH)/man8
 	$(INSTALL_DATA) man8/cache_check.8 $(MANPATH)/man8
 	$(INSTALL_DATA) man8/cache_dump.8 $(MANPATH)/man8
+	$(INSTALL_DATA) man8/cache_metadata_size.8 $(MANPATH)/man8
 	$(INSTALL_DATA) man8/cache_repair.8 $(MANPATH)/man8
 	$(INSTALL_DATA) man8/cache_restore.8 $(MANPATH)/man8
 	$(INSTALL_DATA) man8/cache_writeback.8 $(MANPATH)/man8
@@ -270,15 +272,15 @@ install: bin/pdata_tools
 	$(INSTALL_DATA) man8/thin_metadata_size.8 $(MANPATH)/man8
 	$(INSTALL_DATA) man8/era_check.8 $(MANPATH)/man8
 	$(INSTALL_DATA) man8/era_dump.8 $(MANPATH)/man8
+	$(INSTALL_DATA) man8/era_restore.8 $(MANPATH)/man8
 	$(INSTALL_DATA) man8/era_invalidate.8 $(MANPATH)/man8
+	$(INSTALL_DATA) man8/thin_trim.8 $(MANPATH)/man8
 ifeq ("@DEVTOOLS@", "yes")
 	ln -s -f pdata_tools $(BINDIR)/thin_show_duplicates
-	ln -s -f pdata_tools $(BINDIR)/thin_trim
 	ln -s -f pdata_tools $(BINDIR)/thin_ll_dump
 	ln -s -f pdata_tools $(BINDIR)/thin_show_duplicates
 	ln -s -f pdata_tools $(BINDIR)/thin_generate_metadata
 	ln -s -f pdata_tools $(BINDIR)/thin_scan
-	$(INSTALL_DATA) man8/thin_trim.8 $(MANPATH)/man8
 endif
 
 #	$(INSTALL_DATA) man8/era_restore.8 $(MANPATH)/man8

caching/cache_metadata_size.cc

@@ -141,7 +141,8 @@ cache_metadata_size_cmd::usage(ostream &out) const
 	    << "  {-V|--version}" << endl
 	    << "  {--block-size <sectors>}" << endl
 	    << "  {--device-size <sectors>}" << endl
-	    << "  {--nr-blocks <natural>}" << endl << endl
+	    << "  {--nr-blocks <natural>}" << endl
+	    << "  {--max-hint-width <nr bytes>}" << endl << endl
 	    << "These all relate to the size of the fast device (eg, SSD), rather" << endl
 	    << "than the whole cached device." << endl;
 }
@@ -164,7 +165,7 @@ cache_metadata_size_cmd::run(int argc, char **argv)
 		cout << calc_size(nr_blocks, fs.max_hint_width) << " sectors" << endl;
 
 	} catch (std::exception const &e) {
-		cerr << e.what();
+		cerr << e.what() << "\n";
 		return 1;
 	}
 

era/era_invalidate.cc

@@ -199,6 +199,7 @@ era_invalidate_cmd::usage(std::ostream &out) const
 	    << "  {-h|--help}\n"
 	    << "  {-o <xml file>}\n"
 	    << "  {--metadata-snapshot}\n"
+	    << "  {--written-since}\n"
 	    << "  {-V|--version}" << endl;
 }
 

man8/cache_check.8

@@ -40,6 +40,10 @@ Skip checking of the policy hint values metadata.
 .IP "\fB\-\-skip-discards\fP"
 Skip checking of the discard bits in the metadata.
 
+.IP "\fB\-\-clear\-needs\-check\-flag\fP"
+The kernel may set a flag to force the pool to be checked before it's next
+activated.  Set this switch to clear the flag if the check is successful.
+
 .SH EXAMPLE
 Analyses and repairs cache metadata on logical volume
 /dev/vg/metadata:

man8/cache_dump.8

@@ -31,6 +31,9 @@ Repair the metadata whilst dumping it.
 .IP "\fB\-h, \-\-help\fP".
 Print help and exit.
 
+.IP "\fB-o \<xml file\>\fP".
+Specify an output file for the xml, rather than printing to stdout.
+
 .IP "\fB\-V, \-\-version\fP".
 Output version information and exit.
 

man8/cache_metadata_size.8

@@ -0,0 +1,43 @@
+.TH CACHE_METADATA_SIZE 8 "Thin Provisioning Tools" "Red Hat, Inc."
+.SH NAME
+cache_metadata_size \- Estimate the size of the metadata device needed for a given configuration
+
+.SH SYNOPSIS
+.B cache_metadata_size
+.RB [ options ]
+
+.SH DESCRIPTION
+.B cache_metadata_size
+estimates the size of the metadata.  Either \-\-nr\-blocks, or \-\-block\-size
+and \-\-device\-size must be specified.
+
+.SH OPTIONS
+.IP "\fB\-\-nr\-blocks\fP \<natural\>"
+Specify the number of cache blocks.
+
+.IP "\fB\-\-block-size\fP \<sectors\>"
+Specify the size of each cache block in 512 byte sectors.
+
+.IP "\fB\-\-device\-size\fP \<sectors\>"
+Specify total size of the fast device used in the cache.  In 512 byte sectors.
+
+.IP "\fB\-\-max\-hint\-width\fP \<nr bytes\>"
+Cache policies use a per block 'hint' to record extra info (for instance hit
+counts).  At the moment all policies use a 4 byte hint width.  If you want to use
+a different hint width specify it with this switch.
+
+.SH EXAMPLE
+.B cache_metadata_size --nr-blocks 10240
+.sp
+.B cache_metadata_size --block-size 128 --device-size 1024000
+
+.SH SEE ALSO
+.B cache_dump(8)
+.B cache_repair(8)
+.B cache_restore(8)
+
+.SH AUTHOR
+Joe Thornber <ejt@redhat.com>
+.br
+Heinz Mauelshagen <heinzm@redhat.com>
+

man8/cache_restore.8

@@ -33,10 +33,11 @@ Input file or device with metadata.
 Output file or device for repaired binary metadata.  If a file is used
 then it must be preallocated, and large enough to hold the metadata.
 
-.IP "\fB{\-\-debug-override-metadata-version}\fP \fI<integer>\fP"
+.IP "\fB\-\-metadata\-version\fP \fI{1|2}\fP"
-ONLY FOR DEBUGGING PURPOSES:
+Choose metadata version.
-.br
+
-override the version stored in the metadata.
+.IP "\fB\-q, \-\-quiet\fP"
+Don't print any output.  Check the exit code to test for success.
 
 .IP "\fB\-h, \-\-help\fP"
 Print help and exit.
@@ -44,6 +45,16 @@ Print help and exit.
 .IP "\fB\-V, \-\-version\fP"
 Output version information and exit.
 
+.IP "\fB\-\-debug-override-metadata-version\fP \fI<integer>\fP"
+ONLY FOR DEBUGGING PURPOSES:
+.br
+override the version stored in the metadata.
+
+.IP "\fB\-\-omit\-clean\-shutdown\fP"
+ONLY FOR DEBUGGING PURPOSES:
+.br
+Don't set the clean shutdown flag.
+
 .SH EXAMPLE
 Restores the XML formatted cache metadata on file
 .B metadata

man8/cache_writeback.8

@@ -32,11 +32,18 @@ Slow device being cached.
 .IP "\fB\-\-fast\-device\fP \fI{device|file}\fP"
 Fast device containing the data that needs to be written back.
 
-.IP "\fB\-\-skip\-metadata\-update\fP"
+.IP "\fB\-\-no\-metadata\-update\fP"
 Do not update the metadata to clear the dirty flags for written back
 data.  You may not want to do this if you're decommissioning the
 cache.
 
+.IP "\fB\-\-buffer\-size\-meg \fI{size}\fP"
+Specify the size for the metadata cache.  Defaults to 16 Gig, a larger size may
+improve performance.
+
+.IP "\fB\-\-list\-failed\-blocks\fP
+List any blocks that failed the writeback process.
+
 .IP "\fB\-h, \-\-help\fP"
 Print help and exit.
 

man8/era_dump.8

@@ -25,7 +25,7 @@ in order to put it back onto a metadata
 
 This tool cannot be run on live metadata.
 
-.IP "\fB\-r, \-\-repair\fP".
+.IP "\fB\-\-repair\fP".
 Repair the metadata whilst dumping it.
 
 .IP "\fB\-h, \-\-help\fP".
@@ -39,6 +39,9 @@ Fold any unprocessed write sets into the final era array.  You
 probably want to do this if you're intending to process the results as
 it simplifies the XML.
 
+.IP "\fB-o \fI{xml file}\fP"
+Specify a file for the output rather than writing to stdout.
+
 .SH EXAMPLES
 Dumps era metadata on logical volume /dev/vg/metadata
 to standard output in XML format:

man8/era_invalidate.8

@@ -25,6 +25,12 @@ Write output to a file rather than
 .B stdout
 .
 
+.IP "\fB\-\-metadata\-snapshot\fP"
+Use the metadata snapshot rather than the current superblock.
+
+.IP "\fB\-\-written-since {era}\fP"
+Blocks written since the given era will be listed.
+
 .SH EXAMPLE
 List the blocks that may have been written since the beginning of era
 13 on the metadata device /dev/vg/metadata.

man8/era_restore.8

@@ -0,0 +1,64 @@
+.TH ERA_RESTORE 8 "Thin Provisioning Tools" "Red Hat, Inc." \" -*- nroff -*-
+.SH NAME
+era_restore \- restore era metadata file to device or file
+
+.SH SYNOPSIS
+.B era_restore
+.RB [ options ]
+.RB -i
+.I {device|file}
+.RB -o
+.I {device|file}
+
+.SH DESCRIPTION
+.B era_restore
+restores era metadata created by the respective
+device-mapper target dumped into an XML formatted (see
+.BR era_dump(8) )
+.I file
+, which optionally can be preprocessed before the restore to another
+.I device
+or
+.I file.
+If restored to a metadata
+.I device
+, the metadata can be processed by the device-mapper target.
+
+This tool cannot be run on live metadata.
+
+.IP "\fB\-i, \-\-input\fP \fI{device|file}\fP"
+Input file or device with metadata.
+
+.IP "\fB\-o, \-\-output\fP \fI{device|file}\fP"
+Output file or device for repaired binary metadata.  If a file is used
+then it must be preallocated, and large enough to hold the metadata.
+
+.IP "\fB\-q, \-\-quiet\fP"
+Don't print any output.  Check the exit code to test for success.
+
+.IP "\fB\-h, \-\-help\fP"
+Print help and exit.
+
+.IP "\fB\-V, \-\-version\fP"
+Output version information and exit.
+
+.SH EXAMPLE
+Restores the XML formatted era metadata on file
+.B metadata
+to logical volume /dev/vg/metadata for further processing by the
+respective device-mapper target:
+.sp
+.B era_restore -i metadata -o /dev/vg/metadata
+
+.SH DIAGNOSTICS
+.B era_restore
+returns an exit code of 0 for success or 1 for error.
+
+.SH SEE ALSO
+.B era_dump(8)
+.B era_check(8)
+
+.SH AUTHOR
+Joe Thornber <ejt@redhat.com>
+.br
+Heinz Mauelshagen <HeinzM@RedHat.com>

man8/thin_delta.8

@@ -17,7 +17,7 @@ This tool cannot be run on live metadata unless the \fB\-\-metadata\-snap\fP opt
 .IP "\fB\-\-thin1, \-\-snap1\fP"
 The numeric identifier for the first thin volume to diff.
 
-.IP "\fB\-\-thin1, \-\-snap1\fP"
+.IP "\fB\-\-thin2, \-\-snap2\fP"
 The numeric identifier for the second thin volume to diff.
 
 .IP "\fB\-m, \-\-metadata\-snap\fP [block#]"

man8/thin_dump.8

@@ -51,6 +51,9 @@ times to select more than one thin device.
 .IP "\fB\-\-skip\-mappings".
 Do not dump the mappings.
 
+.IP "\fB-o \fI{xml file}\fP"
+Specify a file for the output rather than writing to stdout.
+
 .IP "\fB\-h, \-\-help\fP".
 Print help and exit.
 

man8/thin_ls.8

@@ -30,9 +30,6 @@ Don't output headers.
 If you want to get information out of a live pool then you will need
 to take a metadata snapshot and use this switch.
 
-.IP "\fB\-\-verbose"
-Provide extra information on the mappings.
-
 .IP "\fB\-h, \-\-help\fP"
 Print help and exit.
 

thin-provisioning/commands.cc

@@ -16,12 +16,12 @@ thin_provisioning::register_thin_commands(base::application &app)
 	app.add_cmd(command::ptr(new thin_restore_cmd()));
 	app.add_cmd(command::ptr(new thin_repair_cmd()));
 	app.add_cmd(command::ptr(new thin_rmap_cmd()));
+	app.add_cmd(command::ptr(new thin_trim_cmd()));
 
 #ifdef DEV_TOOLS
 	app.add_cmd(command::ptr(new thin_ll_dump_cmd()));
 	app.add_cmd(command::ptr(new thin_ll_restore_cmd()));
 	app.add_cmd(command::ptr(new thin_scan_cmd()));
-	app.add_cmd(command::ptr(new thin_trim_cmd()));
 	app.add_cmd(command::ptr(new thin_generate_metadata_cmd()));
 	app.add_cmd(command::ptr(new thin_show_duplicates_cmd()));
 	app.add_cmd(command::ptr(new thin_show_metadata_cmd()));

thin-provisioning/thin_dump.cc

@@ -123,6 +123,7 @@ thin_dump_cmd::usage(std::ostream &out) const
 	    << "  {-m|--metadata-snap} [block#]\n"
 	    << "  {-o <xml file>}\n"
 	    << "  {--dev-id} <dev-id>\n"
+	    << "  {--skip-mappings}\n"
 	    << "  {-V|--version}" << endl;
 }