2 * Copyright (C) 2013-2019 Red Hat Inc.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are
8 * * Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
11 * * Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
15 * * Neither the name of Red Hat nor the names of its contributors may be
16 * used to endorse or promote products derived from this software without
17 * specific prior written permission.
19 * THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND
20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
21 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
22 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR
23 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
26 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
27 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 /* See nbdkit-filter(3) for documentation and how to write a filter. */
35 #ifndef NBDKIT_FILTER_H
36 #define NBDKIT_FILTER_H
40 #include <nbdkit-common.h>
46 #define NBDKIT_FILTER_API_VERSION 6 /* Corresponding to v1.16+ */
48 #define NBDKIT_ZERO_NONE 0
49 #define NBDKIT_ZERO_EMULATE 1
50 #define NBDKIT_ZERO_NATIVE 2
52 struct nbdkit_extent
{
58 extern struct nbdkit_extents
*nbdkit_extents_new (uint64_t start
, uint64_t end
);
59 extern void nbdkit_extents_free (struct nbdkit_extents
*);
60 extern size_t nbdkit_extents_count (const struct nbdkit_extents
*);
61 extern struct nbdkit_extent
nbdkit_get_extent (const struct nbdkit_extents
*,
64 typedef int nbdkit_next_config (void *nxdata
,
65 const char *key
, const char *value
);
66 typedef int nbdkit_next_config_complete (void *nxdata
);
67 typedef int nbdkit_next_open (void *nxdata
,
70 struct nbdkit_next_ops
{
71 /* Performs close + open on the underlying chain.
72 * Used by the retry filter.
74 int (*reopen
) (void *nxdata
, int readonly
);
76 /* The rest of the next ops are the same as normal plugin operations. */
77 int64_t (*get_size
) (void *nxdata
);
79 int (*can_write
) (void *nxdata
);
80 int (*can_flush
) (void *nxdata
);
81 int (*is_rotational
) (void *nxdata
);
82 int (*can_trim
) (void *nxdata
);
83 int (*can_zero
) (void *nxdata
);
84 int (*can_fast_zero
) (void *nxdata
);
85 int (*can_extents
) (void *nxdata
);
86 int (*can_fua
) (void *nxdata
);
87 int (*can_multi_conn
) (void *nxdata
);
88 int (*can_cache
) (void *nxdata
);
90 int (*pread
) (void *nxdata
, void *buf
, uint32_t count
, uint64_t offset
,
91 uint32_t flags
, int *err
);
92 int (*pwrite
) (void *nxdata
,
93 const void *buf
, uint32_t count
, uint64_t offset
,
94 uint32_t flags
, int *err
);
95 int (*flush
) (void *nxdata
, uint32_t flags
, int *err
);
96 int (*trim
) (void *nxdata
, uint32_t count
, uint64_t offset
, uint32_t flags
,
98 int (*zero
) (void *nxdata
, uint32_t count
, uint64_t offset
, uint32_t flags
,
100 int (*extents
) (void *nxdata
, uint32_t count
, uint64_t offset
, uint32_t flags
,
101 struct nbdkit_extents
*extents
, int *err
);
102 int (*cache
) (void *nxdata
, uint32_t count
, uint64_t offset
, uint32_t flags
,
106 struct nbdkit_filter
{
107 /* Do not set these fields directly; use NBDKIT_REGISTER_FILTER.
108 * They exist so that we can diagnose filters compiled against one
109 * version of the header with a runtime compiled against a different
110 * version. As of API version 6, _version is also part of the
111 * guaranteed ABI, so we no longer have to remember to bump API
112 * versions regardless of other API/ABI changes later in the struct.
115 const char *_version
;
117 /* Because there is no ABI guarantee, new fields may be added where
118 * logically appropriate.
121 const char *longname
;
122 const char *description
;
125 void (*unload
) (void);
127 int (*config
) (nbdkit_next_config
*next
, void *nxdata
,
128 const char *key
, const char *value
);
129 int (*config_complete
) (nbdkit_next_config_complete
*next
, void *nxdata
);
130 const char *config_help
;
131 int (*thread_model
) (void);
133 void * (*open
) (nbdkit_next_open
*next
, void *nxdata
,
135 void (*close
) (void *handle
);
137 int (*prepare
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
138 void *handle
, int readonly
);
139 int (*finalize
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
142 int64_t (*get_size
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
145 int (*can_write
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
147 int (*can_flush
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
149 int (*is_rotational
) (struct nbdkit_next_ops
*next_ops
,
152 int (*can_trim
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
154 int (*can_zero
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
156 int (*can_fast_zero
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
158 int (*can_extents
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
160 int (*can_fua
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
162 int (*can_multi_conn
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
164 int (*can_cache
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
167 int (*pread
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
168 void *handle
, void *buf
, uint32_t count
, uint64_t offset
,
169 uint32_t flags
, int *err
);
170 int (*pwrite
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
172 const void *buf
, uint32_t count
, uint64_t offset
,
173 uint32_t flags
, int *err
);
174 int (*flush
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
175 void *handle
, uint32_t flags
, int *err
);
176 int (*trim
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
177 void *handle
, uint32_t count
, uint64_t offset
, uint32_t flags
,
179 int (*zero
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
180 void *handle
, uint32_t count
, uint64_t offset
, uint32_t flags
,
182 int (*extents
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
183 void *handle
, uint32_t count
, uint64_t offset
, uint32_t flags
,
184 struct nbdkit_extents
*extents
, int *err
);
185 int (*cache
) (struct nbdkit_next_ops
*next_ops
, void *nxdata
,
186 void *handle
, uint32_t count
, uint64_t offset
, uint32_t flags
,
190 #define NBDKIT_REGISTER_FILTER(filter) \
192 struct nbdkit_filter * \
195 (filter)._api_version = NBDKIT_FILTER_API_VERSION; \
196 (filter)._version = NBDKIT_VERSION_STRING; \
204 #endif /* NBDKIT_FILTER_H */