Add suboption help texts
[fio.git] / init.c
diff --git a/init.c b/init.c
index 194242439dc93b61b4126ce8a1a9fa3808b08980..cf00bb1abc1e58dafe3d24a6b48845489c99cc75 100644 (file)
--- a/init.c
+++ b/init.c
@@ -22,7 +22,6 @@
 
 #define td_var_offset(var)     ((size_t) &((struct thread_data *)0)->var)
 
-static int str_ioengine_cb(void *, const char *);
 static int str_mem_cb(void *, const char *);
 static int str_lockmem_cb(void *, unsigned long *);
 #ifdef FIO_HAVE_IOPRIO
@@ -31,6 +30,10 @@ static int str_prioclass_cb(void *, unsigned int *);
 #endif
 static int str_exitall_cb(void);
 static int str_cpumask_cb(void *, unsigned int *);
+static int str_fst_cb(void *, const char *);
+static int str_filename_cb(void *, const char *);
+static int str_directory_cb(void *, const char *);
+static int str_opendir_cb(void *, const char *);
 
 #define __stringify_1(x)       #x
 #define __stringify(x)         __stringify_1(x)
@@ -55,13 +58,22 @@ static struct fio_option options[] = {
                .name   = "directory",
                .type   = FIO_OPT_STR_STORE,
                .off1   = td_var_offset(directory),
+               .cb     = str_directory_cb,
                .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",
+               .cb     = str_filename_cb,
+               .help   = "File(s) to use for the workload",
+       },
+       {
+               .name   = "opendir",
+               .type   = FIO_OPT_STR_STORE,
+               .off1   = td_var_offset(opendir),
+               .cb     = str_opendir_cb,
+               .help   = "Recursively add files from this directory and down",
        },
        {
                .name   = "rw",
@@ -70,41 +82,83 @@ static struct fio_option options[] = {
                .help   = "IO direction",
                .def    = "read",
                .posval = {
-                         { .ival = "read", .oval = TD_DDIR_READ },
-                         { .ival = "write", .oval = TD_DDIR_WRITE },
-                         { .ival = "randread", .oval = TD_DDIR_RANDREAD },
-                         { .ival = "randwrite", .oval = TD_DDIR_RANDWRITE },
-                         { .ival = "rw", .oval = TD_DDIR_RW },
-                         { .ival = "randrw", .oval = TD_DDIR_RANDRW },
+                         { .ival = "read",
+                           .oval = TD_DDIR_READ,
+                           .help = "Sequential read",
+                         },
+                         { .ival = "write",
+                           .oval = TD_DDIR_WRITE,
+                           .help = "Sequential write",
+                         },
+                         { .ival = "randread",
+                           .oval = TD_DDIR_RANDREAD,
+                           .help = "Random read",
                          },
+                         { .ival = "randwrite",
+                           .oval = TD_DDIR_RANDWRITE,
+                           .help = "Random write",
+                          },
+                         { .ival = "rw",
+                           .oval = TD_DDIR_RW,
+                           .help = "Sequential read and write mix",
+                         },
+                         { .ival = "randrw",
+                           .oval = TD_DDIR_RANDRW,
+                           .help = "Random read and write mix"
+                         },
+               },
        },
        {
                .name   = "ioengine",
-               .type   = FIO_OPT_STR,
-               .cb     = str_ioengine_cb,
+               .type   = FIO_OPT_STR_STORE,
+               .off1   = td_var_offset(ioengine),
                .help   = "IO engine to use",
                .def    = "sync",
                .posval = {
-                         { .ival = "sync", },
+                         { .ival = "sync",
+                           .help = "Use read/write",
+                         },
 #ifdef FIO_HAVE_LIBAIO
-                         { .ival = "libaio", },
+                         { .ival = "libaio",
+                           .help = "Linux native asynchronous IO",
+                         },
 #endif
 #ifdef FIO_HAVE_POSIXAIO
-                         { .ival = "posixaio", },
+                         { .ival = "posixaio",
+                           .help = "POSIX asynchronous IO",
+                         },
 #endif
-                         { .ival = "mmap", },
+                         { .ival = "mmap",
+                           .help = "Memory mapped IO",
+                         },
 #ifdef FIO_HAVE_SPLICE
-                         { .ival = "splice", },
+                         { .ival = "splice",
+                           .help = "splice/vmsplice based IO",
+                         },
 #endif
 #ifdef FIO_HAVE_SGIO
-                         { .ival = "sg", },
+                         { .ival = "sg",
+                           .help = "SCSI generic v3 IO",
+                         },
 #endif
-                         { .ival = "null", }, { .ival = "net", },
+                         { .ival = "null",
+                           .help = "Testing engine (no data transfer)",
+                         },
+                         { .ival = "net",
+                           .help = "Network IO",
+                         },
 #ifdef FIO_HAVE_SYSLET
-                         { .ival = "syslet-rw", },
+                         { .ival = "syslet-rw",
+                           .help = "syslet enabled async pread/pwrite IO",
+                         },
 #endif
-                         { .ival = "external", },
+                         { .ival = "cpuio",
+                           .help = "CPU cycler burner engine",
+                         },
+                         { .ival = "external",
+                           .help = "Load external engine (append name)",
                          },
+               },
        },
        {
                .name   = "iodepth",
@@ -181,16 +235,29 @@ static struct fio_option options[] = {
                .help   = "Split job workload between this number of files",
                .def    = "1",
        },
+       {
+               .name   = "openfiles",
+               .type   = FIO_OPT_INT,
+               .off1   = td_var_offset(open_files),
+               .help   = "Number of files to keep open at the same time",
+       },
        {
                .name   = "file_service_type",
                .type   = FIO_OPT_STR,
+               .cb     = str_fst_cb,
                .off1   = td_var_offset(file_service_type),
                .help   = "How to select which file to service next",
                .def    = "roundrobin",
                .posval = {
-                         { .ival = "random", .oval = FIO_FSERVICE_RANDOM },
-                         { .ival = "roundrobin", .oval = FIO_FSERVICE_RR },
+                         { .ival = "random",
+                           .oval = FIO_FSERVICE_RANDOM,
+                           .help = "Choose a file at random",
                          },
+                         { .ival = "roundrobin",
+                           .oval = FIO_FSERVICE_RR,
+                           .help = "Round robin select files",
+                         },
+               },
        },
        {
                .name   = "fsync",
@@ -258,16 +325,31 @@ static struct fio_option options[] = {
                .help   = "Backing type for IO buffers",
                .def    = "malloc",
                .posval = {
-                         { .ival = "malloc", .oval = MEM_MALLOC },
-                         { .ival = "shm", .oval = MEM_SHM },
+                         { .ival = "malloc",
+                           .oval = MEM_MALLOC,
+                           .help = "Use malloc(3) for IO buffers",
+                         },
+                         { .ival = "shm",
+                           .oval = MEM_SHM,
+                           .help = "Use shared memory segments for IO buffers",
+                         },
 #ifdef FIO_HAVE_HUGETLB
-                         { .ival = "shmhuge", .oval = MEM_SHMHUGE },
+                         { .ival = "shmhuge",
+                           .oval = MEM_SHMHUGE,
+                           .help = "Like shm, but use huge pages",
+                         },
 #endif
-                         { .ival = "mmap", .oval = MEM_MMAP },
+                         { .ival = "mmap",
+                           .oval = MEM_MMAP,
+                           .help = "Use mmap(2) (file or anon) for IO buffers",
+                         },
 #ifdef FIO_HAVE_HUGETLB
-                         { .ival = "mmaphuge", .oval = MEM_MMAPHUGE },
-#endif
+                         { .ival = "mmaphuge",
+                           .oval = MEM_MMAPHUGE,
+                           .help = "Like mmap, but use huge pages",
                          },
+#endif
+                 },
        },
        {
                .name   = "verify",
@@ -276,10 +358,19 @@ static struct fio_option options[] = {
                .help   = "Verify sum function",
                .def    = "0",
                .posval = {
-                         { .ival = "0", .oval = VERIFY_NONE },
-                         { .ival = "crc32", .oval = VERIFY_CRC32 },
-                         { .ival = "md5", .oval = VERIFY_MD5 },
+                         { .ival = "0",
+                           .oval = VERIFY_NONE,
+                           .help = "Don't do IO verification",
+                         },
+                         { .ival = "crc32",
+                           .oval = VERIFY_CRC32,
+                           .help = "Use crc32 checksums for verification",
+                         },
+                         { .ival = "md5",
+                           .oval = VERIFY_MD5,
+                           .help = "Use md5 checksums for verification",
                          },
+               },
        },
        {
                .name   = "write_iolog",
@@ -395,7 +486,7 @@ static struct fio_option options[] = {
                .name   = "thinktime_spin",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(thinktime_spin),
-               .help   = "Start thinktime by spinning this amount (usec)",
+               .help   = "Start think time by spinning this amount (usec)",
                .def    = "0",
        },
        {
@@ -469,7 +560,8 @@ static struct fio_option options[] = {
                .name   = "cpuchunks",
                .type   = FIO_OPT_INT,
                .off1   = td_var_offset(cpucycle),
-               .help   = "Length of the CPU burn cycles",
+               .help   = "Length of the CPU burn cycles (usecs)",
+               .def    = "50000",
        },
 #ifdef FIO_HAVE_CPU_AFFINITY
        {
@@ -486,6 +578,13 @@ static struct fio_option options[] = {
                .help   = "Include fsync at the end of job",
                .def    = "0",
        },
+       {
+               .name   = "fsync_on_close",
+               .type   = FIO_OPT_BOOL,
+               .off1   = td_var_offset(fsync_on_close),
+               .help   = "fsync files on close",
+               .def    = "0",
+       },
        {
                .name   = "unlink",
                .type   = FIO_OPT_BOOL,
@@ -530,6 +629,12 @@ static struct fio_option options[] = {
                .help   = "When using hugepages, specify size of each page",
                .def    = __stringify(FIO_HUGE_PAGE),
        },
+       {
+               .name   = "group_reporting",
+               .type   = FIO_OPT_STR_SET,
+               .off1   = td_var_offset(group_reporting),
+               .help   = "Do reporting on a per-group basis",
+       },
        {
                .name = NULL,
        },
@@ -591,7 +696,7 @@ static struct option long_options[FIO_JOB_OPTS + FIO_CMD_OPTS] = {
 
 static int def_timeout = 0;
 
-static char fio_version_string[] = "fio 1.12";
+static char fio_version_string[] = "fio 1.14";
 
 static char **ini_file;
 static int max_jobs = MAX_JOBS;
@@ -608,6 +713,8 @@ FILE *f_err = NULL;
 static int write_lat_log = 0;
 int write_bw_log = 0;
 
+static int prev_group_jobs;
+
 FILE *get_f_out()
 {
        return f_out;
@@ -668,13 +775,13 @@ static void fixup_options(struct thread_data *td)
                td->iodepth = 1;
        else {
                if (!td->iodepth)
-                       td->iodepth = td->nr_files;
+                       td->iodepth = td->open_files;
        }
 
        /*
         * only really works for sequential io for now, and with 1 file
         */
-       if (td->zone_size && td_random(td) && td->nr_files == 1)
+       if (td->zone_size && td_random(td) && td->open_files == 1)
                td->zone_size = 0;
 
        /*
@@ -704,12 +811,6 @@ static void fixup_options(struct thread_data *td)
        if (td->bs_unaligned && (td->odirect || td->io_ops->flags & FIO_RAWIO))
                log_err("fio: bs_unaligned may not work with raw io\n");
 
-       /*
-        * O_DIRECT and char doesn't mix, clear that flag if necessary.
-        */
-       if (td->filetype == FIO_TYPE_CHAR && td->odirect)
-               td->odirect = 0;
-
        /*
         * thinktime_spin must be less than thinktime
         */
@@ -736,6 +837,12 @@ static void fixup_options(struct thread_data *td)
         */
        if (td->iodepth_batch > td->iodepth || !td->iodepth_batch)
                td->iodepth_batch = td->iodepth;
+
+       if (td->nr_files > td->files_index)
+               td->nr_files = td->files_index;
+
+       if (td->open_files > td->nr_files || !td->open_files)
+               td->open_files = td->nr_files;
 }
 
 /*
@@ -759,6 +866,20 @@ static char *to_kmg(unsigned int val)
        return buf;
 }
 
+/* External engines are specified by "external:name.o") */
+static const char *get_engine_name(const char *str)
+{
+       char *p = strstr(str, ":");
+
+       if (!p)
+               return str;
+
+       p++;
+       strip_blank_front(&p);
+       strip_blank_end(p);
+       return p;
+}
+
 /*
  * Adds a job to the list of things todo. Sanitizes the various options
  * to make sure we don't have conflicts, and initializes various
@@ -768,9 +889,11 @@ static int add_job(struct thread_data *td, const char *jobname, int job_add_num)
 {
        const char *ddir_str[] = { NULL, "read", "write", "rw", NULL,
                                   "randread", "randwrite", "randrw" };
-       struct stat sb;
-       int numjobs, i;
+       unsigned int i;
        struct fio_file *f;
+       const char *engine;
+       char fname[PATH_MAX];
+       int numjobs;
 
        /*
         * the def_thread is just for options, it's not a real job
@@ -778,80 +901,56 @@ static int add_job(struct thread_data *td, const char *jobname, int job_add_num)
        if (td == &def_thread)
                return 0;
 
-       assert(td->io_ops);
-
-       if (td->odirect)
-               td->io_ops->flags |= FIO_RAWIO;
-
-       td->filetype = FIO_TYPE_FILE;
-       if (td->filename && !lstat(td->filename, &sb)) {
-               if (S_ISBLK(sb.st_mode))
-                       td->filetype = FIO_TYPE_BD;
-               else if (S_ISCHR(sb.st_mode))
-                       td->filetype = FIO_TYPE_CHAR;
+       engine = get_engine_name(td->ioengine);
+       td->io_ops = load_ioengine(td, engine);
+       if (!td->io_ops) {
+               log_err("fio: failed to load engine %s\n", engine);
+               return 1;
        }
 
-       fixup_options(td);
-
-       if (td->filename)
-               td->nr_uniq_files = 1;
+       if (td->use_thread)
+               nr_thread++;
        else
-               td->nr_uniq_files = td->nr_files;
-
-       if (td->filetype == FIO_TYPE_FILE || td->filename) {
-               char tmp[PATH_MAX];
-               int len = 0;
+               nr_process++;
 
-               if (td->directory && td->directory[0] != '\0') {
-                       if (lstat(td->directory, &sb) < 0) {
-                               log_err("fio: %s is not a directory\n", td->directory);
-                               td_verror(td, errno, "lstat");
-                               return 1;
-                       }
-                       if (!S_ISDIR(sb.st_mode)) {
-                               log_err("fio: %s is not a directory\n", td->directory);
-                               return 1;
-                       }
-                       len = sprintf(tmp, "%s/", td->directory);
-               }
+       if (td->odirect)
+               td->io_ops->flags |= FIO_RAWIO;
 
-               td->files = malloc(sizeof(struct fio_file) * td->nr_files);
+       if (!td->filename && !td->files_index) {
+               td->filename = strdup(jobname);
 
-               for_each_file(td, f, i) {
-                       memset(f, 0, sizeof(*f));
-                       f->fd = -1;
-
-                       if (td->filename)
-                               sprintf(tmp + len, "%s", td->filename);
-                       else
-                               sprintf(tmp + len, "%s.%d.%d", jobname, td->thread_number, i);
-                       f->file_name = strdup(tmp);
+               if (td->nr_files == 1)
+                       add_file(td, td->filename);
+               else {
+                       for (i = 0; i < td->nr_files; i++) {
+                               sprintf(fname, "%s.%d.%d", td->filename, td->thread_number, i);
+                               add_file(td, fname);
+                       }
                }
-       } else {
-               td->nr_files = 1;
-               td->files = malloc(sizeof(struct fio_file));
-               f = &td->files[0];
-
-               memset(f, 0, sizeof(*f));
-               f->fd = -1;
-               f->file_name = strdup(jobname);
        }
 
+       fixup_options(td);
+
        for_each_file(td, f, i) {
-               f->file_size = td->total_file_size / td->nr_files;
-               f->file_offset = td->start_offset;
+               if (td->directory && f->filetype == FIO_TYPE_FILE) {
+                       sprintf(fname, "%s/%s", td->directory, f->file_name);
+                       f->file_name = strdup(fname);
+               }
        }
                
-       fio_sem_init(&td->mutex, 0);
+       td->mutex = fio_sem_init(0);
 
        td->ts.clat_stat[0].min_val = td->ts.clat_stat[1].min_val = ULONG_MAX;
        td->ts.slat_stat[0].min_val = td->ts.slat_stat[1].min_val = ULONG_MAX;
        td->ts.bw_stat[0].min_val = td->ts.bw_stat[1].min_val = ULONG_MAX;
 
-       if (td->stonewall && td->thread_number > 1)
+       if ((td->stonewall || td->numjobs > 1) && prev_group_jobs) {
+               prev_group_jobs = 0;
                groupid++;
+       }
 
        td->groupid = groupid;
+       prev_group_jobs++;
 
        if (setup_rate(td))
                goto err;
@@ -868,7 +967,7 @@ static int add_job(struct thread_data *td, const char *jobname, int job_add_num)
 
        if (!terse_output) {
                if (!job_add_num) {
-                       if (td->io_ops->flags & FIO_CPUIO)
+                       if (!strcmp(td->io_ops->name, "cpuio"))
                                fprintf(f_out, "%s: ioengine=cpu, cpuload=%u, cpucycle=%u\n", td->name, td->cpuload, td->cpucycle);
                        else {
                                char *c1, *c2, *c3, *c4;
@@ -907,6 +1006,12 @@ static int add_job(struct thread_data *td, const char *jobname, int job_add_num)
                if (add_job(td_new, jobname, job_add_num))
                        goto err;
        }
+
+       if (td->numjobs > 1) {
+               groupid++;
+               prev_group_jobs = 0;
+       }
+
        return 0;
 err:
        put_job(td);
@@ -920,10 +1025,11 @@ err:
 int init_random_state(struct thread_data *td)
 {
        unsigned long seeds[5];
-       int fd, num_maps, blocks, i;
+       int fd, num_maps, blocks;
        struct fio_file *f;
+       unsigned int i;
 
-       if (td->io_ops->flags & FIO_CPUIO)
+       if (td->io_ops->flags & FIO_DISKLESSIO)
                return 0;
 
        fd = open("/dev/urandom", O_RDONLY);
@@ -958,6 +1064,10 @@ int init_random_state(struct thread_data *td)
                        blocks = (f->real_file_size + td->rw_min_bs - 1) / td->rw_min_bs;
                        num_maps = (blocks + BLOCKS_PER_MAP-1)/ BLOCKS_PER_MAP;
                        f->file_map = malloc(num_maps * sizeof(long));
+                       if (!f->file_map) {
+                               log_err("fio: failed allocating random map. If running a large number of jobs, try the 'norandommap' option\n");
+                               return 1;
+                       }
                        f->num_maps = num_maps;
                        memset(f->file_map, 0, num_maps * sizeof(long));
                }
@@ -1000,7 +1110,7 @@ static int is_empty_or_comment(char *line)
 /*
  * Check if mmap/mmaphuge has a :/foo/bar/file at the end. If so, return that.
  */
-static char *get_mmap_file(const char *str)
+static char *get_opt_postfix(const char *str)
 {
        char *p = strstr(str, ":");
 
@@ -1018,7 +1128,7 @@ static int str_mem_cb(void *data, const char *mem)
        struct thread_data *td = data;
 
        if (td->mem_type == MEM_MMAPHUGE || td->mem_type == MEM_MMAP) {
-               td->mmapfile = get_mmap_file(mem);
+               td->mmapfile = get_opt_postfix(mem);
                if (td->mem_type == MEM_MMAPHUGE && !td->mmapfile) {
                        log_err("fio: mmaphuge:/path/to/file\n");
                        return 1;
@@ -1028,32 +1138,6 @@ static int str_mem_cb(void *data, const char *mem)
        return 0;
 }
 
-/* External engines are specified by "external:name.o") */
-static const char *get_engine_name(const char *str)
-{
-       char *p = strstr(str, ":");
-
-       if (!p)
-               return str;
-
-       p++;
-       strip_blank_front(&p);
-       strip_blank_end(p);
-       return p;
-}
-
-static int str_ioengine_cb(void *data, const char *str)
-{
-       struct thread_data *td = data;
-       const char *name = get_engine_name(str);
-
-       td->io_ops = load_ioengine(td, name);
-       if (td->io_ops)
-               return 0;
-
-       return 1;
-}
-
 static int str_lockmem_cb(void fio_unused *data, unsigned long *val)
 {
        mlock_size = *val;
@@ -1092,6 +1176,70 @@ static int str_cpumask_cb(void *data, unsigned int *val)
        return 0;
 }
 
+static int str_fst_cb(void *data, const char *str)
+{
+       struct thread_data *td = data;
+       char *nr = get_opt_postfix(str);
+
+       td->file_service_nr = 1;
+       if (nr)
+               td->file_service_nr = atoi(nr);
+
+       return 0;
+}
+
+static int str_filename_cb(void *data, const char *input)
+{
+       struct thread_data *td = data;
+       char *fname, *str, *p;
+
+       p = str = strdup(input);
+
+       strip_blank_front(&str);
+       strip_blank_end(str);
+
+       if (!td->files_index)
+               td->nr_files = 0;
+
+       while ((fname = strsep(&str, ":")) != NULL) {
+               if (!strlen(fname))
+                       break;
+               add_file(td, fname);
+               td->nr_files++;
+       }
+
+       free(p);
+       return 0;
+}
+
+static int str_directory_cb(void *data, const char fio_unused *str)
+{
+       struct thread_data *td = data;
+       struct stat sb;
+
+       if (lstat(td->directory, &sb) < 0) {
+               log_err("fio: %s is not a directory\n", td->directory);
+               td_verror(td, errno, "lstat");
+               return 1;
+       }
+       if (!S_ISDIR(sb.st_mode)) {
+               log_err("fio: %s is not a directory\n", td->directory);
+               return 1;
+       }
+
+       return 0;
+}
+
+static int str_opendir_cb(void *data, const char fio_unused *str)
+{
+       struct thread_data *td = data;
+
+       if (!td->files_index)
+               td->nr_files = 0;
+
+       return add_dir_files(td, td->opendir);
+}
+
 /*
  * This is our [ini] type file parser.
  */
@@ -1223,7 +1371,7 @@ static int parse_cmd_line(int argc, char *argv[])
        struct thread_data *td = NULL;
        int c, ini_idx = 0, lidx, ret, dont_add_job = 0;
 
-       while ((c = getopt_long(argc, argv, "", long_options, &lidx)) != -1) {
+       while ((c = getopt_long_only(argc, argv, "", long_options, &lidx)) != -1) {
                switch (c) {
                case 't':
                        def_timeout = atoi(optarg);