Clarify what tool-specific options are (#3444)

Fixes #3443

Modify the help message of pbench-register-tool to warn against using
operational options (i.e. options used internally by pbench) for a
tool when it is registered.

Modify the help message of base-tool (and everybody who is symlinked
to it) to clarify which are operational options and which are
tool-specific options: operational options should not be specified
when registering a tool: they are used by pbench internally; only
tool-specific options are specifed when registering the tool (on the
RHS of `--` in the invocation of `pbench-register-tool`).

PBENCH-1173

agent/tool-scripts/base-tool

@@ -191,17 +191,26 @@ esac
 
 function usage {
 	printf -- "The following options are available:\n\n"
+	printf -- "Operational options - do *not* specify any of these when you register a tool:\n\n"
 	printf -- "\t--install                 verify this perf tool will work\n\n"
 	printf -- "\t--start|stop|postprocess  start/stop/postprocess the data collection\n"
 	printf -- "\t-d str|--dir=str          directory to store data collection (required)\n"
+
+	printf -- "\nTool-specific options - these should be specified when you register a tool:\n\n"
+
 	case "${tool}" in
-	blktrace|bpftrace|kvmtrace|lockstat|oc|perf|strace|systemtap|tcpdump)
-		:  # These tools don't use interval
+	lockstat)
+		:  # Tools that don't take *any* tool-specific options
+		printf -- "\tNo tool-specific options for this tool\n"
+		;;
+	blktrace|bpftrace|kvmtrace|oc|perf|strace|systemtap|tcpdump)
+		:  # Tools that don't use '--interval' but take other tool-specific options
 		;;
 	*)
 		printf -- "\t--interval=int            number of seconds between each data collection (optional, default is %s seconds)\n" "${def_interval}"
 		;;
 	esac
+
 	case "${tool}" in
 	blktrace)
 		printf -- "\t--devices=str,[str]       the list of block devices to trace (required w/ --start)\n"
@@ -278,7 +287,9 @@ function usage {
 		printf -- "\t                           but not both at the same time\n"
 		;;
 	esac
-	printf -- "\n\t-h|--help                 display this help message\n"
+
+	printf -- "\nHelp option - do *not* specify this when you register a tool:\n\n"
+	printf -- "\t-h|--help                 display this help message\n\n"
 }
 
 # Process options and arguments
@@ -582,7 +593,7 @@ install)
 		local _installed_rpm
 		local _rc
 		_installed_rpm="$(require-rpm "${_tpn}" "${_tpv}")"
-		_rc=${?} 
+		_rc=${?}
 		if [[ ${_rc} != 0 ]]; then
 			printf -- "%s: %s is not installed\n" "${tool}" "${_tpn}${_tpv:+-${_tpv}}" >&2
 		else

agent/tool-scripts/tests/blktrace/gold/stderr

@@ -2,12 +2,20 @@ blktrace: Error, one of the following options is required, --install|--start|--s
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--devices=str,[str]       the list of block devices to trace (required w/ --start)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 blktrace: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/blktrace/tools-group/blktrace', missing
 blktrace: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/blktrace/tools-group/blktrace', missing

agent/tool-scripts/tests/bpftrace/gold/stderr

@@ -2,12 +2,20 @@ bpftrace: Error, one of the following options is required, --install|--start|--s
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--script=str              path to the bpftrace script (required w/ --start)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 bpftrace: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/bpftrace/tools-group/bpftrace', missing
 bpftrace: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/bpftrace/tools-group/bpftrace', missing

agent/tool-scripts/tests/cpuacct/gold/stderr

@@ -2,12 +2,20 @@ cpuacct: Error, one of the following options is required, --install|--start|--st
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 cpuacct: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/cpuacct/tools-group/cpuacct', missing
 cpuacct: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/cpuacct/tools-group/cpuacct', missing

agent/tool-scripts/tests/disk/gold/stderr

@@ -2,12 +2,20 @@ disk: Error, one of the following options is required, --install|--start|--stop|
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 disk: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/disk/tools-group/disk', missing
 disk: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/disk/tools-group/disk', missing

agent/tool-scripts/tests/dm-cache/gold/stderr

@@ -2,12 +2,20 @@ dm-cache: Error, one of the following options is required, --install|--start|--s
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 dm-cache: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/dm-cache/tools-group/dm-cache', missing
 dm-cache: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/dm-cache/tools-group/dm-cache', missing

agent/tool-scripts/tests/docker-info/gold/stderr

@@ -2,12 +2,20 @@ docker-info: Error, one of the following options is required, --install|--start|
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 docker-info: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/docker-info/tools-group/docker-info', missing
 docker-info: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/docker-info/tools-group/docker-info', missing

agent/tool-scripts/tests/docker/gold/stderr

@@ -2,12 +2,20 @@ docker: Error, one of the following options is required, --install|--start|--sto
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 docker: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/docker/tools-group/docker', missing
 docker: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/docker/tools-group/docker', missing

agent/tool-scripts/tests/haproxy-ocp/gold/stderr

@@ -2,13 +2,21 @@ haproxy-ocp: Error, one of the following options is required, --install|--start|
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 	--counters-clear-all      clear all HAProxy counters at tool start (optional, default: 'false')
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 haproxy-ocp: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/haproxy-ocp/tools-group/haproxy-ocp', missing
 haproxy-ocp: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/haproxy-ocp/tools-group/haproxy-ocp', missing

agent/tool-scripts/tests/iostat/gold/stderr

@@ -2,13 +2,21 @@ iostat: Error, one of the following options is required, --install|--start|--sto
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 	--options=str             options passed directly to the tool (optional)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 iostat: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/iostat/tools-group/iostat', missing
 iostat: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/iostat/tools-group/iostat', missing

agent/tool-scripts/tests/jmap/gold/stderr

@@ -2,14 +2,22 @@ jmap: Error, one of the following options is required, --install|--start|--stop|
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 	--pid=int                 a process ID to jmap
 	--pattern=str             jmap any PID which name matches this string (via pgrep)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 jmap: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/jmap/tools-group/jmap', missing
 jmap: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/jmap/tools-group/jmap', missing

agent/tool-scripts/tests/jstack/gold/stderr

@@ -2,14 +2,22 @@ jstack: Error, one of the following options is required, --install|--start|--sto
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 	--pid=int                 a process ID to jstack
 	--pattern=str             jstack any PID which name matches this string (via pgrep)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 jstack: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/jstack/tools-group/jstack', missing
 jstack: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/jstack/tools-group/jstack', missing

agent/tool-scripts/tests/kvm-spinlock/gold/stderr

@@ -2,12 +2,20 @@ kvm-spinlock: Error, one of the following options is required, --install|--start
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 kvm-spinlock: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/kvm-spinlock/tools-group/kvm-spinlock', missing
 kvm-spinlock: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/kvm-spinlock/tools-group/kvm-spinlock', missing

agent/tool-scripts/tests/kvmstat/gold/stderr

@@ -2,12 +2,20 @@ kvmstat: Error, one of the following options is required, --install|--start|--st
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 kvmstat: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/kvmstat/tools-group/kvmstat', missing
 kvmstat: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/kvmstat/tools-group/kvmstat', missing

agent/tool-scripts/tests/kvmtrace/gold/stderr

@@ -2,15 +2,23 @@ kvmtrace: Error, one of the following options is required, --install|--start|--s
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--vm=str                  the hostname of the vm running (to get kallsyms)
 	--timeout=int             how long the trace will run (default is 1 second)
 	                          If 0 is used, the trace will not stop until stop-tools is called
 	--start-delay=int         sleep this many seconds before starting the trace (default is 0 seconds)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 kvmtrace: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/kvmtrace/tools-group/kvmtrace', missing
 kvmtrace: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/kvmtrace/tools-group/kvmtrace', missing

agent/tool-scripts/tests/lockstat/gold/stderr

@@ -2,11 +2,20 @@ lockstat: Error, one of the following options is required, --install|--start|--s
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
 
+Tool-specific options - these should be specified when you register a tool:
+
+	No tool-specific options for this tool
+
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 lockstat: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/lockstat/tools-group/lockstat', missing
 lockstat: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/lockstat/tools-group/lockstat', missing

agent/tool-scripts/tests/mpstat/gold/stderr

@@ -2,13 +2,21 @@ mpstat: Error, one of the following options is required, --install|--start|--sto
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--install                 verify this perf tool will work
 
 	--start|stop|postprocess  start/stop/postprocess the data collection
 	-d str|--dir=str          directory to store data collection (required)
+
+Tool-specific options - these should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 	--options=str             options passed directly to the tool (optional)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 mpstat: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/mpstat/tools-group/mpstat', missing
 mpstat: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/mpstat/tools-group/mpstat', missing