crush: re-organize the help to clarify ordering

The options are grouped according to the stage they relate to

   - input/build
   - tunables adjustments
   - modifications
   - display/test
   - output

Signed-off-by: Loic Dachary <ldachary@redhat.com>

diff --git a/src/test/cli/crushtool/help.t b/src/test/cli/crushtool/help.t
index 7d549195206bdd2abcfbf7491c094e6c10d6d1e7..cd7d4a7685421258c5c9a5b393517cbbc2fd51f7 100644 (file)
--- a/src/test/cli/crushtool/help.t
+++ b/src/test/cli/crushtool/help.t
@@ -1,23 +1,48 @@
   $ crushtool --help
   usage: crushtool ...
+  
+  Display, modify and test a crush map
+  
+  There are five stages, running one after the other:
+  
+   - input/build
+   - tunables adjustments
+   - modifications
+   - display/test
+   - output
+  
+  Options that are not specific to a stage.
+  
+     [--infn|-i infile]
+                           read the crush map from infile
+  
+  Options for the input/build stage
+  
      --decompile|-d map    decompile a crush map to source
-     --tree                print map summary as a tree
-     --compile|-c map.txt  compile a map from source
-     [-o outfile [--clobber]]
+     [--outfn|-o outfile]
                            specify output for for (de)compilation
+     --compile|-c map.txt  compile a map from source
+     --enable-unsafe-tunables compile with unsafe tunables
      --build --num_osds N layer1 ...
                            build a new map, where each 'layer' is
                              'name (uniform|straw|list|tree) size'
-     -i mapfn --test       test a range of inputs on the map
-        [--min-x x] [--max-x x] [--x x]
-        [--min-rule r] [--max-rule r] [--rule r]
-        [--num-rep n]
-        [--batches b]      split the CRUSH mapping into b > 1 rounds
-        [--weight|-w devno weight]
-                           where weight is 0 to 1.0
-        [--simulate]       simulate placements using a random
-                           number generator in place of the CRUSH
-                           algorithm
+  
+  Options for the tunables adjustments stage
+  
+     --set-choose-local-tries N
+                           set choose local retries before re-descent
+     --set-choose-local-fallback-tries N
+                           set choose local retries using fallback
+                           permutation before re-descent
+     --set-choose-total-tries N
+                           set choose total descent attempts
+     --set-chooseleaf-descend-once <0|1>
+                           set chooseleaf to (not) retry the recursive descent
+     --set-chooseleaf-vary-r <0|1>
+                           set chooseleaf to (not) vary r based on parent
+  
+  Options for the modifications stage
+  
      -i mapfn --add-item id weight name [--loc type name ...]
                            insert an item into the hierarchy at the
                            given location
@@ -30,8 +55,22 @@
                            reweight a given item (and adjust ancestor
                            weights as needed)
      -i mapfn --reweight   recalculate all bucket weights
+  
+  Options for the display/test stage
+  
+     --tree                print map summary as a tree
      -i mapfn --show-location id
                            show location for given device id
+     -i mapfn --test       test a range of inputs on the map
+        [--min-x x] [--max-x x] [--x x]
+        [--min-rule r] [--max-rule r] [--rule r]
+        [--num-rep n]
+        [--batches b]      split the CRUSH mapping into b > 1 rounds
+        [--weight|-w devno weight]
+                           where weight is 0 to 1.0
+        [--simulate]       simulate placements using a random
+                           number generator in place of the CRUSH
+                           algorithm
      --show-utilization    show OSD usage
      --show utilization-all
                            include zero weight items
@@ -39,17 +78,6 @@
      --show-mappings       show mappings
      --show-bad-mappings   show bad mappings
      --show-choose-tries   show choose tries histogram
-     --set-choose-local-tries N
-                           set choose local retries before re-descent
-     --set-choose-local-fallback-tries N
-                           set choose local retries using fallback
-                           permutation before re-descent
-     --set-choose-total-tries N
-                           set choose total descent attempts
-     --set-chooseleaf-descend-once <0|1>
-                           set chooseleaf to (not) retry the recursive descent
-     --set-chooseleaf-vary-r <0|1>
-                           set chooseleaf to (not) vary r based on parent
      --output-name name
                            prepend the data file(s) generated during the
                            testing routine with name
@@ -57,6 +85,12 @@
                            export select data generated during testing routine
                            to CSV files for off-line post-processing
                            use --help-output for more information
+  
+  Options for the output stage
+  
+     [--outfn|-o outfile]
+                           specify output for for modified crush map
+  
   $ crushtool --help-output
   data output from testing routine ...
             absolute_weights

diff --git a/src/tools/crushtool.cc b/src/tools/crushtool.cc
index 6a70c942ca5953ab8c5e8ee276fa39d7424ff213..41f0e70ea078ab409558721ef34ce4f0c6173733 100644 (file)
--- a/src/tools/crushtool.cc
+++ b/src/tools/crushtool.cc
@@ -86,24 +86,49 @@ cout << "                               OSD id (int), proportional weight (float
 void usage()
 {
   cout << "usage: crushtool ...\n";
+  cout << "\n";
+  cout << "Display, modify and test a crush map\n";
+  cout << "\n";
+  cout << "There are five stages, running one after the other:\n";
+  cout << "\n";
+  cout << " - input/build\n";
+  cout << " - tunables adjustments\n";
+  cout << " - modifications\n";
+  cout << " - display/test\n";
+  cout << " - output\n";
+  cout << "\n";
+  cout << "Options that are not specific to a stage.\n";
+  cout << "\n";
+  cout << "   [--infn|-i infile]\n";
+  cout << "                         read the crush map from infile\n";
+  cout << "\n";
+  cout << "Options for the input/build stage\n";
+  cout << "\n";
   cout << "   --decompile|-d map    decompile a crush map to source\n";
-  cout << "   --tree                print map summary as a tree\n";
-  cout << "   --compile|-c map.txt  compile a map from source\n";
-  cout << "   [-o outfile [--clobber]]\n";
+  cout << "   [--outfn|-o outfile]\n";
   cout << "                         specify output for for (de)compilation\n";
+  cout << "   --compile|-c map.txt  compile a map from source\n";
+  cout << "   --enable-unsafe-tunables compile with unsafe tunables\n";
   cout << "   --build --num_osds N layer1 ...\n";
   cout << "                         build a new map, where each 'layer' is\n";
   cout << "                           'name (uniform|straw|list|tree) size'\n";
-  cout << "   -i mapfn --test       test a range of inputs on the map\n";
-  cout << "      [--min-x x] [--max-x x] [--x x]\n";
-  cout << "      [--min-rule r] [--max-rule r] [--rule r]\n";
-  cout << "      [--num-rep n]\n";
-  cout << "      [--batches b]      split the CRUSH mapping into b > 1 rounds\n";
-  cout << "      [--weight|-w devno weight]\n";
-  cout << "                         where weight is 0 to 1.0\n";
-  cout << "      [--simulate]       simulate placements using a random\n";
-  cout << "                         number generator in place of the CRUSH\n";
-  cout << "                         algorithm\n";
+  cout << "\n";
+  cout << "Options for the tunables adjustments stage\n";
+  cout << "\n";
+  cout << "   --set-choose-local-tries N\n";
+  cout << "                         set choose local retries before re-descent\n";
+  cout << "   --set-choose-local-fallback-tries N\n";
+  cout << "                         set choose local retries using fallback\n";
+  cout << "                         permutation before re-descent\n";
+  cout << "   --set-choose-total-tries N\n";
+  cout << "                         set choose total descent attempts\n";
+  cout << "   --set-chooseleaf-descend-once <0|1>\n";
+  cout << "                         set chooseleaf to (not) retry the recursive descent\n";
+  cout << "   --set-chooseleaf-vary-r <0|1>\n";
+  cout << "                         set chooseleaf to (not) vary r based on parent\n";
+  cout << "\n";
+  cout << "Options for the modifications stage\n";
+  cout << "\n";
   cout << "   -i mapfn --add-item id weight name [--loc type name ...]\n";
   cout << "                         insert an item into the hierarchy at the\n";
   cout << "                         given location\n";
@@ -116,8 +141,22 @@ void usage()
   cout << "                         reweight a given item (and adjust ancestor\n"
        << "                         weights as needed)\n";
   cout << "   -i mapfn --reweight   recalculate all bucket weights\n";
+  cout << "\n";
+  cout << "Options for the display/test stage\n";
+  cout << "\n";
+  cout << "   --tree                print map summary as a tree\n";
   cout << "   -i mapfn --show-location id\n";
   cout << "                         show location for given device id\n";
+  cout << "   -i mapfn --test       test a range of inputs on the map\n";
+  cout << "      [--min-x x] [--max-x x] [--x x]\n";
+  cout << "      [--min-rule r] [--max-rule r] [--rule r]\n";
+  cout << "      [--num-rep n]\n";
+  cout << "      [--batches b]      split the CRUSH mapping into b > 1 rounds\n";
+  cout << "      [--weight|-w devno weight]\n";
+  cout << "                         where weight is 0 to 1.0\n";
+  cout << "      [--simulate]       simulate placements using a random\n";
+  cout << "                         number generator in place of the CRUSH\n";
+  cout << "                         algorithm\n";
   cout << "   --show-utilization    show OSD usage\n";
   cout << "   --show utilization-all\n";
   cout << "                         include zero weight items\n";
@@ -125,17 +164,6 @@ void usage()
   cout << "   --show-mappings       show mappings\n";
   cout << "   --show-bad-mappings   show bad mappings\n";
   cout << "   --show-choose-tries   show choose tries histogram\n";
-  cout << "   --set-choose-local-tries N\n";
-  cout << "                         set choose local retries before re-descent\n";
-  cout << "   --set-choose-local-fallback-tries N\n";
-  cout << "                         set choose local retries using fallback\n";
-  cout << "                         permutation before re-descent\n";
-  cout << "   --set-choose-total-tries N\n";
-  cout << "                         set choose total descent attempts\n";
-  cout << "   --set-chooseleaf-descend-once <0|1>\n";
-  cout << "                         set chooseleaf to (not) retry the recursive descent\n";
-  cout << "   --set-chooseleaf-vary-r <0|1>\n";
-  cout << "                         set chooseleaf to (not) vary r based on parent\n";
   cout << "   --output-name name\n";
   cout << "                         prepend the data file(s) generated during the\n";
   cout << "                         testing routine with name\n";
@@ -143,6 +171,12 @@ void usage()
   cout << "                         export select data generated during testing routine\n";
   cout << "                         to CSV files for off-line post-processing\n";
   cout << "                         use --help-output for more information\n";
+  cout << "\n";
+  cout << "Options for the output stage\n";
+  cout << "\n";
+  cout << "   [--outfn|-o outfile]\n";
+  cout << "                         specify output for for modified crush map\n";
+  cout << "\n";
 }
 
 struct bucket_types_t {