[PATCH] Add per-option help

It's hard to remember all the options that fio supports, so add a
'cmdhelp' option that either prints all possible options (if argument
is 'all'), or specific option help (if argument is the command).

Signed-off-by: Jens Axboe <jens.axboe@oracle.com>

diff --git a/README b/README
index bfed0ef7194ed4968c1b24ef76b40d8a797de61c..97251d019cb1925d43d25591473343b4f3ef4d18 100644 (file)
--- a/README
+++ b/README
@@ -59,6 +59,8 @@ $ fio
         --bandwidth-log Generate per-job bandwidth logs
         --minimal       Minimal (terse) output
         --version       Print version info and exit
+       --help          Print this page
+       --cmdhelp=cmd   Print command help, "all" for all of them
 
 Any parameters following the options will be assumed to be job files,
 unless they match a job file parameter. You can add as many as you want,

diff --git a/init.c b/init.c
index 06b10a9b2cc723d5cebb49f253e7a1922701e32e..4ac2783d28a4ced91c1076e3b069a3e4bc659a5b 100644 (file)
--- a/init.c
+++ b/init.c
@@ -77,94 +77,112 @@ static struct fio_option options[] = {
                .name   = "name",
                .type   = FIO_OPT_STR_STORE,
                .off1   = td_var_offset(name),
+               .help   = "Name of this job",
        },
        {
                .name   = "directory",
                .type   = FIO_OPT_STR_STORE,
                .off1   = td_var_offset(directory),
+               .help   = "Directory to store files in",
        },
        {
                .name   = "filename",
                .type   = FIO_OPT_STR_STORE,
                .off1   = td_var_offset(filename),
+               .help   = "Force the use of a specific file",
        },
        {
                .name   = "rw",
                .type   = FIO_OPT_STR,
                .cb     = str_rw_cb,
+               .help   = "IO direction (read, write, rw, etc)",
        },
        {
                .name   = "ioengine",
                .type   = FIO_OPT_STR,
                .cb     = str_ioengine_cb,
+               .help   = "IO engine to use (sync, aio, etc)",
        },
        {
                .name   = "mem",
                .type   = FIO_OPT_STR,
                .cb     = str_mem_cb,
+               .help   = "Backing type for IO buffers (malloc, shm, etc)",
        },
        {
                .name   = "verify",
                .type   = FIO_OPT_STR,
                .cb     = str_verify_cb,
+               .help   = "Verify sum function (md5 or crc32)",
        },
        {
                .name   = "write_iolog",
                .type   = FIO_OPT_STR_STORE,
                .off1   = td_var_offset(write_iolog_file),
+               .help   = "Store IO pattern to file",
        },
        {
                .name   = "read_iolog",
                .type   = FIO_OPT_STR_STORE,
                .off1   = td_var_offset(read_iolog_file),
+               .help   = "Playback IO pattern from file",
        },
        {
                .name   = "exec_prerun",
                .type   = FIO_OPT_STR_STORE,
                .off1   = td_var_offset(exec_prerun),
+               .help   = "Execute this file prior to running job",
        },
        {
                .name   = "exec_postrun",
                .type   = FIO_OPT_STR_STORE,
                .off1   = td_var_offset(exec_postrun),
+               .help   = "Execute this file after running job",
        },
 #ifdef FIO_HAVE_IOSCHED_SWITCH
        {
                .name   = "ioscheduler",
                .type   = FIO_OPT_STR_STORE,
                .off1   = td_var_offset(ioscheduler),
+               .help   = "Use this IO scheduler on the backing device",
        },
 #endif
        {
                .name   = "size",
                .type   = FIO_OPT_STR_VAL,
                .off1   = td_var_offset(total_file_size),
+               .help   = "Size of device or file",
        },
        {
                .name   = "bs",
                .type   = FIO_OPT_STR_VAL_INT,
                .off1   = td_var_offset(bs[DDIR_READ]),
                .off2   = td_var_offset(bs[DDIR_WRITE]),
+               .help   = "Block size unit",
        },
        {
                .name   = "offset",
                .type   = FIO_OPT_STR_VAL,
                .off1   = td_var_offset(start_offset),
+               .help   = "Start IO from this offset",
        },
        {
                .name   = "zonesize",
                .type   = FIO_OPT_STR_VAL,
                .off1   = td_var_offset(zone_size),
+               .help   = "Give size of an IO zone",
        },
        {
                .name   = "zoneskip",
                .type   = FIO_OPT_STR_VAL,
                .off1   = td_var_offset(zone_skip),
+               .help   = "Space between IO zones",
        },
        {
                .name   = "lockmem",
                .type   = FIO_OPT_STR_VAL,
                .cb     = str_lockmem_cb,
+               .help   = "Lock down this amount of memory",
        },
        {
                .name   = "bsrange",
@@ -173,202 +191,241 @@ static struct fio_option options[] = {
                .off2   = td_var_offset(max_bs[DDIR_READ]),
                .off3   = td_var_offset(min_bs[DDIR_WRITE]),
                .off4   = td_var_offset(max_bs[DDIR_WRITE]),
+               .help   = "Set block size range",
        },
        {
                .name   = "nrfiles",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(nr_files),
+               .help   = "Split job workload between this number of files",
        },
        {
                .name   = "iodepth",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(iodepth),
+               .help   = "Amount of IO buffers to keep in flight",
        },
        {
                .name   = "fsync",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(fsync_blocks),
+               .help   = "Issue fsync for writes every given number of blocks",
        },
        {
                .name   = "rwmixcycle",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(rwmixcycle),
+               .help   = "Cycle period for mixed read/write workloads",
        },
        {
                .name   = "rwmixread",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(rwmixread),
                .max_val= 100,
+               .help   = "Percentage of mixed workload that is reads",
        },
        {
                .name   = "rwmixwrite",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(rwmixwrite),
                .max_val= 100,
+               .help   = "Percentage of mixed workload that is writes",
        },
        {
                .name   = "nice",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(nice),
+               .help   = "Set job CPU nice value",
        },
 #ifdef FIO_HAVE_IOPRIO
        {
                .name   = "prio",
                .type   = FIO_OPT_INT,
                .cb     = str_prio_cb,
+               .help   = "Set job IO priority value",
        },
        {
                .name   = "prioclass",
                .type   = FIO_OPT_INT,
                .cb     = str_prioclass_cb,
+               .help   = "Set job IO priority class",
        },
 #endif
        {
                .name   = "thinktime",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(thinktime),
+               .help   = "Idle time between IO buffers",
        },
        {
                .name   = "thinktime_blocks",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(thinktime_blocks),
+               .help   = "IO buffer period between 'thinktime'",
        },
        {
                .name   = "rate",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(rate),
+               .help   = "Set bandwidth rate",
        },
        {
                .name   = "ratemin",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(ratemin),
+               .help   = "The bottom limit accepted",
        },
        {
                .name   = "ratecycle",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(ratecycle),
+               .name   = "Window average for rate limits",
        },
        {
                .name   = "startdelay",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(start_delay),
+               .help   = "Only start job when this period has passed",
        },
        {
                .name   = "timeout",
                .type   = FIO_OPT_STR_VAL_TIME,
                .off1   = td_var_offset(timeout),
+               .help   = "Stop workload when this amount of time has passed",
        },
        {
                .name   = "invalidate",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(invalidate_cache),
+               .help   = "Invalidate buffer/page cache prior to running job",
        },
        {
                .name   = "sync",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(sync_io),
+               .help   = "Use O_SYNC for buffered writes",
        },
        {
                .name   = "bwavgtime",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(bw_avg_time),
+               .help   = "Time window over which to calculate bandwidth",
        },
        {
                .name   = "create_serialize",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(create_serialize),
+               .help   = "Serialize creating of job files",
        },
        {
                .name   = "create_fsync",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(create_fsync),
+               .help   = "Fsync file after creation",
        },
        {
                .name   = "loops",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(loops),
+               .help   = "Number of times to run the job",
        },
        {
                .name   = "numjobs",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(numjobs),
+               .help   = "Duplicate this job this many times",
        },
        {
                .name   = "cpuload",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(cpuload),
+               .help   = "Use this percentage of CPU",
        },
        {
                .name   = "cpuchunks",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(cpucycle),
+               .help   = "Length of the CPU burn cycles",
        },
        {
                .name   = "direct",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(odirect),
+               .help   = "Use O_DIRECT IO",
        },
        {
                .name   = "overwrite",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(overwrite),
+               .help   = "When writing, set whether to overwrite current data",
        },
 #ifdef FIO_HAVE_CPU_AFFINITY
        {
                .name   = "cpumask",
                .type   = FIO_OPT_INT,
                .cb     = str_cpumask_cb,
+               .help   = "CPU affinity mask",
        },
 #endif
        {
                .name   = "end_fsync",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(end_fsync),
+               .help   = "Include fsync at the end of job",
        },
        {
                .name   = "unlink",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(unlink),
+               .help   = "Unlink files after job has completed",
        },
        {
                .name   = "exitall",
                .type   = FIO_OPT_STR_SET,
                .cb     = str_exitall_cb,
+               .help   = "Terminate all jobs when one exits",
        },
        {
                .name   = "stonewall",
                .type   = FIO_OPT_STR_SET,
                .off1   = td_var_offset(stonewall),
+               .help   = "Insert a hard barrier between this job and previous",
        },
        {
                .name   = "thread",
                .type   = FIO_OPT_STR_SET,
                .off1   = td_var_offset(thread),
+               .help   = "Use threads instead of forks",
        },
        {
                .name   = "write_bw_log",
                .type   = FIO_OPT_STR_SET,
                .off1   = td_var_offset(write_bw_log),
+               .help   = "Write log of bandwidth during run",
        },
        {
                .name   = "write_lat_log",
                .type   = FIO_OPT_STR_SET,
                .off1   = td_var_offset(write_lat_log),
+               .help   = "Write log of latency during run",
        },
        {
                .name   = "norandommap",
                .type   = FIO_OPT_STR_SET,
                .off1   = td_var_offset(norandommap),
+               .help   = "Accept potential duplicate random blocks",
        },
        {
                .name   = "bs_unaligned",
                .type   = FIO_OPT_STR_SET,
                .off1   = td_var_offset(bs_unaligned),
+               .help   = "Don't sector align IO buffer sizes",
        },
        {
                .name   = "hugepage-size",
                .type   = FIO_OPT_STR_VAL,
                .off1   = td_var_offset(hugepage_size),
+               .help   = "When using hugepages, specify size of each page",
        },
        {
                .name = NULL,
@@ -414,6 +471,16 @@ static struct option long_options[FIO_JOB_OPTS + FIO_CMD_OPTS] = {
                .has_arg        = no_argument,
                .val            = 'v',
        },
+       {
+               .name           = "help",
+               .has_arg        = no_argument,
+               .val            = 'h',
+       },
+       {
+               .name           = "cmdhelp",
+               .has_arg        = required_argument,
+               .val            = 'c',
+       },
        {
                .name           = NULL,
        },
@@ -1103,6 +1170,8 @@ static void usage(void)
        printf("\t--bandwidth-log\tGenerate per-job bandwidth logs\n");
        printf("\t--minimal\tMinimal (terse) output\n");
        printf("\t--version\tPrint version info and exit\n");
+       printf("\t--help\t\tPrint this page\n");
+       printf("\t--cmdhelp=cmd\tPrint command help, \"all\" for all of them\n");
 }
 
 static int parse_cmd_line(int argc, char *argv[])
@@ -1135,6 +1204,9 @@ static int parse_cmd_line(int argc, char *argv[])
                case 'h':
                        usage();
                        exit(0);
+               case 'c':
+                       show_cmd_help(options, optarg);
+                       exit(0);
                case 'v':
                        printf("%s\n", fio_version_string);
                        exit(0);

diff --git a/parse.c b/parse.c
index 50d8ae5e5f4fe56ea12ba5ff33ca76fe48e114a4..7ff474b1dfec5f1daaa31418910aaad4e6fda1fc 100644 (file)
--- a/parse.c
+++ b/parse.c
@@ -361,3 +361,34 @@ int parse_option(const char *opt, struct fio_option *options, void *data)
        fprintf(stderr, "fio: failed parsing %s\n", opt);
        return 1;
 }
+
+int show_cmd_help(struct fio_option *options, const char *name)
+{
+       int show_all = !strcmp(name, "all");
+       struct fio_option *o = &options[0];
+       const char *typehelp[] = {
+               "string (opt=bla)",
+               "string with possible k/m/g postfix (opt=4k)",
+               "string with range and postfix (opt=1k-4k)",
+               "string with time postfix (opt=10s)",
+               "string (opt=bla)",
+               "string with dual range (opt=1k-4k,4k-8k)",
+               "integer value (opt=100)",
+               "no argument (opt)",
+       };
+
+       while (o->name) {
+               int match = !strcmp(name, o->name);
+
+               if (show_all || match) {
+                       printf("%s: %s\n", o->name, o->help);
+                       if (match)
+                               printf("type: %s\n", typehelp[o->type]);
+               }
+
+               o++;
+       }
+
+
+       return 0;
+}

diff --git a/parse.h b/parse.h
index adbb3208e644c7bcac22ed96c58206553f9e1d42..9cfd68de5403631101241514945608293072abcb 100644 (file)
--- a/parse.h
+++ b/parse.h
@@ -27,12 +27,14 @@ struct fio_option {
        unsigned int off4;
        unsigned int max_val;
        void *cb;
+       const char *help;
 };
 
 typedef int (str_cb_fn)(void *, char *);
 
 extern int parse_option(const char *, struct fio_option *, void *);
 extern int parse_cmd_option(const char *t, const char *l, struct fio_option *, void *);
+extern int show_cmd_help(struct fio_option *, const char *);
 
 extern void strip_blank_front(char **);
 extern void strip_blank_end(char *);