skeleton: add option example

Add an example of ioengine specific options, which can/should exist
within each ioengine code. Also fix/add documentation.

Also see e59b9e11('move skip_bad= option to engines/mtd.c').

Signed-off-by: Tomohiro Kusumi <tkusumi@tuxera.com>
Signed-off-by: Jens Axboe <axboe@kernel.dk>

diff --git a/HOWTO b/HOWTO
index 3a720c35b68e59d948921689ac56b6c2bfc7e95d..2a70b7c629b6d6470625ac98e02dad555571f1ed 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -1791,7 +1791,9 @@ I/O engine
                **external**
                        Prefix to specify loading an external I/O engine object file. Append
                        the engine filename, e.g. ``ioengine=external:/tmp/foo.o`` to load
-                       ioengine :file:`foo.o` in :file:`/tmp`.
+                       ioengine :file:`foo.o` in :file:`/tmp`. The path can be either
+                       absolute or relative. See :file:`engines/skeleton_external.c` for
+                       details of writing an external I/O engine.
 
 
 I/O engine specific parameters

diff --git a/engines/skeleton_external.c b/engines/skeleton_external.c
index 4bebcc45a9d39fa857233c86cc9a3b6264d88423..56f89f957b5f502ccfe0add680ac80c6ef9d4a85 100644 (file)
--- a/engines/skeleton_external.c
+++ b/engines/skeleton_external.c
@@ -3,7 +3,8 @@
  *
  * Should be compiled with:
  *
- * gcc -Wall -O2 -g -shared -rdynamic -fPIC -o engine.o engine.c
+ * gcc -Wall -O2 -g -shared -rdynamic -fPIC -o skeleton_external.o skeleton_external.c
+ * (also requires -D_GNU_SOURCE -DCONFIG_STRSEP on Linux)
  *
  */
 #include <stdio.h>
@@ -13,6 +14,7 @@
 #include <assert.h>
 
 #include "../fio.h"
+#include "../optgroup.h"
 
 /*
  * The core of the module is identical to the ones included with fio,
@@ -20,6 +22,32 @@
  * for external modules, they should be gotten through dlsym()
  */
 
+/*
+ * The io engine can define its own options within the io engine source.
+ * The option member must not be at offset 0, due to the way fio parses
+ * the given option. Just add a padding pointer unless the io engine has
+ * something usable.
+ */
+struct fio_skeleton_options {
+       void *pad; /* avoid ->off1 of fio_option becomes 0 */
+       unsigned int dummy;
+};
+
+static struct fio_option options[] = {
+       {
+               .name   = "dummy",
+               .lname  = "ldummy",
+               .type   = FIO_OPT_STR_SET,
+               .off1   = offsetof(struct fio_skeleton_options, dummy),
+               .help   = "Set dummy",
+               .category = FIO_OPT_C_ENGINE, /* always use this */
+               .group  = FIO_OPT_G_INVALID, /* this can be different */
+       },
+       {
+               .name   = NULL,
+       },
+};
+
 /*
  * The ->event() hook is called to match an event number with an io_u.
  * After the core has called ->getevents() and it has returned eg 3,
@@ -140,4 +168,6 @@ struct ioengine_ops ioengine = {
        .cleanup        = fio_skeleton_cleanup,
        .open_file      = fio_skeleton_open,
        .close_file     = fio_skeleton_close,
+       .options        = options,
+       .option_struct_size     = sizeof(struct fio_skeleton_options),
 };

diff --git a/fio.1 b/fio.1
index 5b63dfd728082bf52006a2da7cb4522914f74ce7..97133dacbb846d286c8f2219a7f5178b42cc38f5 100644 (file)
--- a/fio.1
+++ b/fio.1
@@ -1572,7 +1572,9 @@ Read and write using device DAX to a persistent memory device (e.g.,
 .B external
 Prefix to specify loading an external I/O engine object file. Append
 the engine filename, e.g. `ioengine=external:/tmp/foo.o' to load
-ioengine `foo.o' in `/tmp'.
+ioengine `foo.o' in `/tmp'. The path can be either
+absolute or relative. See `engines/skeleton_external.c' in the fio source for
+details of writing an external I/O engine.
 .SS "I/O engine specific parameters"
 In addition, there are some parameters which are only valid when a specific
 \fBioengine\fR is in use. These are used identically to normal parameters,