Merge branch 'evelu-peak' of https://github.com/ErwanAliasr1/fio
[fio.git] / engines / skeleton_external.c
CommitLineData
da51c050
JA
1/*
2 * Skeleton for a sample external io engine
3 *
4 * Should be compiled with:
5 *
44364a99 6 * gcc -Wall -O2 -g -D_GNU_SOURCE -include ../config-host.h -shared -rdynamic -fPIC -o skeleton_external.o skeleton_external.c
d243fd6d 7 * (also requires -D_GNU_SOURCE -DCONFIG_STRSEP on Linux)
da51c050
JA
8 *
9 */
10#include <stdio.h>
11#include <stdlib.h>
12#include <unistd.h>
13#include <errno.h>
14#include <assert.h>
15
16#include "../fio.h"
d243fd6d 17#include "../optgroup.h"
da51c050
JA
18
19/*
20 * The core of the module is identical to the ones included with fio,
21 * read those. You cannot use register_ioengine() and unregister_ioengine()
22 * for external modules, they should be gotten through dlsym()
23 */
24
d243fd6d
TK
25/*
26 * The io engine can define its own options within the io engine source.
27 * The option member must not be at offset 0, due to the way fio parses
28 * the given option. Just add a padding pointer unless the io engine has
29 * something usable.
30 */
31struct fio_skeleton_options {
32 void *pad; /* avoid ->off1 of fio_option becomes 0 */
33 unsigned int dummy;
34};
35
36static struct fio_option options[] = {
37 {
38 .name = "dummy",
39 .lname = "ldummy",
40 .type = FIO_OPT_STR_SET,
41 .off1 = offsetof(struct fio_skeleton_options, dummy),
42 .help = "Set dummy",
43 .category = FIO_OPT_C_ENGINE, /* always use this */
44 .group = FIO_OPT_G_INVALID, /* this can be different */
45 },
46 {
47 .name = NULL,
48 },
49};
50
830a78b0
JA
51/*
52 * The ->event() hook is called to match an event number with an io_u.
53 * After the core has called ->getevents() and it has returned eg 3,
54 * the ->event() hook must return the 3 events that have completed for
55 * subsequent calls to ->event() with [0-2]. Required.
56 */
57static struct io_u *fio_skeleton_event(struct thread_data *td, int event)
58{
59 return NULL;
60}
61
62/*
63 * The ->getevents() hook is used to reap completion events from an async
64 * io engine. It returns the number of completed events since the last call,
65 * which may then be retrieved by calling the ->event() hook with the event
66 * numbers. Required.
67 */
e7d2e616 68static int fio_skeleton_getevents(struct thread_data *td, unsigned int min,
1f440ece 69 unsigned int max, const struct timespec *t)
830a78b0
JA
70{
71 return 0;
72}
73
74/*
75 * The ->cancel() hook attempts to cancel the io_u. Only relevant for
76 * async io engines, and need not be supported.
77 */
78static int fio_skeleton_cancel(struct thread_data *td, struct io_u *io_u)
79{
80 return 0;
81}
82
83/*
84 * The ->queue() hook is responsible for initiating io on the io_u
85 * being passed in. If the io engine is a synchronous one, io may complete
86 * before ->queue() returns. Required.
e2a26d2c
JA
87 *
88 * The io engine must transfer in the direction noted by io_u->ddir
89 * to the buffer pointed to by io_u->xfer_buf for as many bytes as
03e20d68 90 * io_u->xfer_buflen. Residual data count may be set in io_u->resid
36167d82 91 * for a short read/write.
830a78b0 92 */
2e4ef4fb
JA
93static enum fio_q_status fio_skeleton_queue(struct thread_data *td,
94 struct io_u *io_u)
830a78b0 95{
7101d9c2
JA
96 /*
97 * Double sanity check to catch errant write on a readonly setup
98 */
99 fio_ro_check(td, io_u);
100
36167d82
JA
101 /*
102 * Could return FIO_Q_QUEUED for a queued request,
103 * FIO_Q_COMPLETED for a completed request, and FIO_Q_BUSY
104 * if we could queue no more at this point (you'd have to
105 * define ->commit() to handle that.
106 */
107 return FIO_Q_COMPLETED;
830a78b0
JA
108}
109
110/*
111 * The ->prep() function is called for each io_u prior to being submitted
112 * with ->queue(). This hook allows the io engine to perform any
34403fb1 113 * preparatory actions on the io_u, before being submitted. Not required.
830a78b0
JA
114 */
115static int fio_skeleton_prep(struct thread_data *td, struct io_u *io_u)
116{
117 return 0;
118}
119
120/*
121 * The init function is called once per thread/process, and should set up
122 * any structures that this io engine requires to keep track of io. Not
123 * required.
124 */
125static int fio_skeleton_init(struct thread_data *td)
126{
127 return 0;
128}
129
130/*
de8f6de9 131 * This is paired with the ->init() function and is called when a thread is
830a78b0
JA
132 * done doing io. Should tear down anything setup by the ->init() function.
133 * Not required.
134 */
135static void fio_skeleton_cleanup(struct thread_data *td)
136{
137}
138
b5af8293
JA
139/*
140 * Hook for opening the given file. Unless the engine has special
2201299e 141 * needs, it usually just provides generic_open_file() as the handler.
b5af8293
JA
142 */
143static int fio_skeleton_open(struct thread_data *td, struct fio_file *f)
144{
2201299e 145 return generic_open_file(td, f);
b5af8293
JA
146}
147
148/*
149 * Hook for closing a file. See fio_skeleton_open().
150 */
151static int fio_skeleton_close(struct thread_data *td, struct fio_file *f)
152{
2201299e 153 return generic_close_file(td, f);
b5af8293
JA
154}
155
6c5b11d3
DLM
156/*
157 * Hook for getting the zoned model of a zoned block device for zonemode=zbd.
158 * The zoned model can be one of (see zbd_types.h):
6c5b11d3
DLM
159 * - ZBD_NONE: regular block device (zone emulation will be used)
160 * - ZBD_HOST_AWARE: host aware zoned block device
161 * - ZBD_HOST_MANAGED: host managed zoned block device
162 */
163static int fio_skeleton_get_zoned_model(struct thread_data *td,
164 struct fio_file *f, enum zbd_zoned_model *model)
165{
166 *model = ZBD_NONE;
167 return 0;
168}
169
170/*
171 * Hook called for getting zone information of a ZBD_HOST_AWARE or
172 * ZBD_HOST_MANAGED zoned block device. Up to @nr_zones zone information
173 * structures can be reported using the array zones for zones starting from
174 * @offset. The number of zones reported must be returned or a negative error
175 * code in case of error.
176 */
177static int fio_skeleton_report_zones(struct thread_data *td, struct fio_file *f,
178 uint64_t offset, struct zbd_zone *zones,
179 unsigned int nr_zones)
180{
181 return 0;
182}
183
184/*
185 * Hook called for resetting the write pointer position of zones of a
186 * ZBD_HOST_AWARE or ZBD_HOST_MANAGED zoned block device. The write pointer
187 * position of all zones in the range @offset..@offset + @length must be reset.
188 */
189static int fio_skeleton_reset_wp(struct thread_data *td, struct fio_file *f,
190 uint64_t offset, uint64_t length)
191{
192 return 0;
193}
194
d2f442bc
NC
195/*
196 * Hook called for getting the maximum number of open zones for a
197 * ZBD_HOST_MANAGED zoned block device.
198 * A @max_open_zones value set to zero means no limit.
199 */
200static int fio_skeleton_get_max_open_zones(struct thread_data *td,
201 struct fio_file *f,
202 unsigned int *max_open_zones)
203{
204 return 0;
205}
206
da51c050
JA
207/*
208 * Note that the structure is exported, so that fio can get it via
13690c10 209 * dlsym(..., "ioengine"); for (and only for) external engines.
da51c050
JA
210 */
211struct ioengine_ops ioengine = {
212 .name = "engine_name",
213 .version = FIO_IOOPS_VERSION,
214 .init = fio_skeleton_init,
215 .prep = fio_skeleton_prep,
216 .queue = fio_skeleton_queue,
830a78b0 217 .cancel = fio_skeleton_cancel,
da51c050
JA
218 .getevents = fio_skeleton_getevents,
219 .event = fio_skeleton_event,
220 .cleanup = fio_skeleton_cleanup,
b5af8293
JA
221 .open_file = fio_skeleton_open,
222 .close_file = fio_skeleton_close,
6c5b11d3
DLM
223 .get_zoned_model = fio_skeleton_get_zoned_model,
224 .report_zones = fio_skeleton_report_zones,
225 .reset_wp = fio_skeleton_reset_wp,
d2f442bc 226 .get_max_open_zones = fio_skeleton_get_max_open_zones,
d243fd6d
TK
227 .options = options,
228 .option_struct_size = sizeof(struct fio_skeleton_options),
da51c050 229};