From 62e7b4a377ac7a35bc7b1d4d8f4bcb717a84625d Mon Sep 17 00:00:00 2001 From: Loic Dachary Date: Mon, 23 Feb 2015 19:52:03 +0100 Subject: [PATCH] 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 --- src/test/cli/crushtool/help.t | 82 +++++++++++++++++++++++++---------- src/tools/crushtool.cc | 82 +++++++++++++++++++++++++---------- 2 files changed, 116 insertions(+), 48 deletions(-) diff --git a/src/test/cli/crushtool/help.t b/src/test/cli/crushtool/help.t index 7d549195206bd..cd7d4a7685421 100644 --- 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 6a70c942ca595..41f0e70ea078a 100644 --- 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 { -- 2.39.5