include/nbdkit-filter.h

   1 /* nbdkit
   2  * Copyright Red Hat
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions are
   6  * met:
   7  *
   8  * * Redistributions of source code must retain the above copyright
   9  * notice, this list of conditions and the following disclaimer.
  10  *
  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.
  14  *
  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.
  18  *
  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
  30  * SUCH DAMAGE.
  31  */
  32
  33 /* See nbdkit-filter(3) for documentation and how to write a filter. */
  34
  35 #ifndef NBDKIT_FILTER_H
  36 #define NBDKIT_FILTER_H
  37
  38 #include <stdlib.h>
  39
  40 #include <nbdkit-common.h>
  41
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 #define NBDKIT_FILTER_API_VERSION 6 /* Corresponding to v1.16+ */
  47
  48 #define NBDKIT_ZERO_NONE     0
  49 #define NBDKIT_ZERO_EMULATE  1
  50 #define NBDKIT_ZERO_NATIVE   2
  51
  52 #ifdef NBDKIT_INTERNAL
  53 /* Opaque types encapsulating all information needed for calling into
  54  * the next filter or plugin.
  55  */
  56 typedef struct backend nbdkit_backend;
  57 typedef struct context nbdkit_context;
  58 typedef struct context nbdkit_next;
  59 #else
  60 typedef struct nbdkit_backend nbdkit_backend;
  61 typedef struct nbdkit_context nbdkit_context;
  62 typedef struct nbdkit_next_ops nbdkit_next;
  63 #endif
  64
  65 /* Next ops. */
  66 typedef int nbdkit_next_config (nbdkit_backend *nxdata,
  67                                 const char *key, const char *value);
  68 typedef int nbdkit_next_config_complete (nbdkit_backend *nxdata);
  69 typedef int nbdkit_next_preconnect (nbdkit_backend *nxdata, int readonly);
  70 typedef int nbdkit_next_list_exports (nbdkit_backend *nxdata, int readonly,
  71                                       struct nbdkit_exports *exports);
  72 typedef const char *nbdkit_next_default_export (nbdkit_backend *nxdata,
  73                                                 int readonly);
  74 typedef int nbdkit_next_open (nbdkit_context *context,
  75                               int readonly, const char *exportname);
  76
  77 struct nbdkit_next_ops {
  78   /* These callbacks are only needed when managing the backend manually
  79    * rather than via nbdkit_next_open.
  80    */
  81   int (*prepare) (nbdkit_next *nxdata);
  82   int (*finalize) (nbdkit_next *nxdata);
  83
  84   /* These callbacks are the same as normal plugin operations. */
  85   int64_t (*get_size) (nbdkit_next *nxdata);
  86   const char * (*export_description) (nbdkit_next *nxdata);
  87   int (*block_size) (nbdkit_next *nxdata,
  88                      uint32_t *minimum, uint32_t *preferred, uint32_t *maximum);
  89
  90   int (*can_write) (nbdkit_next *nxdata);
  91   int (*can_flush) (nbdkit_next *nxdata);
  92   int (*is_rotational) (nbdkit_next *nxdata);
  93   int (*can_trim) (nbdkit_next *nxdata);
  94   int (*can_zero) (nbdkit_next *nxdata);
  95   int (*can_fast_zero) (nbdkit_next *nxdata);
  96   int (*can_extents) (nbdkit_next *nxdata);
  97   int (*can_fua) (nbdkit_next *nxdata);
  98   int (*can_multi_conn) (nbdkit_next *nxdata);
  99   int (*can_cache) (nbdkit_next *nxdata);
 100
 101   int (*pread) (nbdkit_next *nxdata,
 102                 void *buf, uint32_t count, uint64_t offset,
 103                 uint32_t flags, int *err);
 104   int (*pwrite) (nbdkit_next *nxdata,
 105                  const void *buf, uint32_t count, uint64_t offset,
 106                  uint32_t flags, int *err);
 107   int (*flush) (nbdkit_next *nxdata, uint32_t flags, int *err);
 108   int (*trim) (nbdkit_next *nxdata, uint32_t count, uint64_t offset,
 109                uint32_t flags, int *err);
 110   int (*zero) (nbdkit_next *nxdata, uint32_t count, uint64_t offset,
 111                uint32_t flags, int *err);
 112   int (*extents) (nbdkit_next *nxdata, uint32_t count, uint64_t offset,
 113                   uint32_t flags, struct nbdkit_extents *extents, int *err);
 114   int (*cache) (nbdkit_next *nxdata, uint32_t count, uint64_t offset,
 115                 uint32_t flags, int *err);
 116
 117   /* Note: Actual instances of this struct contain additional opaque
 118    * data not listed in this header; you cannot manually copy or
 119    * initialize sizeof(struct nbdkit_next_ops) bytes, but must instead
 120    * use unchanged pointers obtained from the nbdkit API.
 121    */
 122 };
 123
 124 /* Extent functions. */
 125 struct nbdkit_extent {
 126   uint64_t offset;
 127   uint64_t length;
 128   uint32_t type;
 129 };
 130
 131 NBDKIT_EXTERN_DECL (struct nbdkit_extents *, nbdkit_extents_new,
 132                     (uint64_t start, uint64_t end));
 133 NBDKIT_EXTERN_DECL (void, nbdkit_extents_free, (struct nbdkit_extents *));
 134 NBDKIT_EXTERN_DECL (size_t, nbdkit_extents_count,
 135                     (const struct nbdkit_extents *));
 136 NBDKIT_EXTERN_DECL (struct nbdkit_extent, nbdkit_get_extent,
 137                     (const struct nbdkit_extents *, size_t));
 138 NBDKIT_EXTERN_DECL (struct nbdkit_extents *, nbdkit_extents_full,
 139                     (nbdkit_next *next,
 140                      uint32_t count, uint64_t offset,
 141                      uint32_t flags, int *err));
 142 NBDKIT_EXTERN_DECL (int, nbdkit_extents_aligned,
 143                     (nbdkit_next *next,
 144                      uint32_t count, uint64_t offset,
 145                      uint32_t flags, uint32_t align,
 146                      struct nbdkit_extents *extents, int *err));
 147
 148 /* Export functions. */
 149 struct nbdkit_export {
 150   char *name;
 151   char *description;
 152 };
 153
 154 NBDKIT_EXTERN_DECL (struct nbdkit_exports *, nbdkit_exports_new,
 155                     (void));
 156 NBDKIT_EXTERN_DECL (void, nbdkit_exports_free, (struct nbdkit_exports *));
 157 NBDKIT_EXTERN_DECL (size_t, nbdkit_exports_count,
 158                     (const struct nbdkit_exports *));
 159 NBDKIT_EXTERN_DECL (const struct nbdkit_export, nbdkit_get_export,
 160                     (const struct nbdkit_exports *, size_t));
 161
 162 /* Manual management of backend access. */
 163 NBDKIT_EXTERN_DECL (nbdkit_backend *, nbdkit_context_get_backend,
 164                     (nbdkit_context *context));
 165 NBDKIT_EXTERN_DECL (nbdkit_next *, nbdkit_next_context_open,
 166                     (nbdkit_backend *backend, int readonly,
 167                      const char *exportname, int shared));
 168 NBDKIT_EXTERN_DECL (void, nbdkit_next_context_close, (nbdkit_next *next));
 169 NBDKIT_EXTERN_DECL (nbdkit_next *, nbdkit_context_set_next,
 170                     (nbdkit_context *context, nbdkit_next *next));
 171
 172 /* Filter struct. */
 173 struct nbdkit_filter {
 174   /* Do not set these fields directly; use NBDKIT_REGISTER_FILTER.
 175    * They exist so that we can diagnose filters compiled against one
 176    * version of the header with a runtime compiled against a different
 177    * version.  As of API version 6, _version is also part of the
 178    * guaranteed ABI, so we no longer have to remember to bump API
 179    * versions regardless of other API/ABI changes later in the struct.
 180    */
 181   int _api_version;
 182   const char *_version;
 183
 184   /* Because there is no ABI guarantee, new fields may be added where
 185    * logically appropriate.
 186    */
 187   const char *name;
 188   const char *longname;
 189   const char *description;
 190
 191   void (*load) (void);
 192   void (*unload) (void);
 193
 194   int (*config) (nbdkit_next_config *next, nbdkit_backend *nxdata,
 195                  const char *key, const char *value);
 196   int (*config_complete) (nbdkit_next_config_complete *next,
 197                           nbdkit_backend *nxdata);
 198   const char *config_help;
 199   int (*thread_model) (void);
 200   int (*get_ready) (int thread_model);
 201   int (*after_fork) (nbdkit_backend *backend);
 202   void (*cleanup) (nbdkit_backend *backend);
 203   int (*preconnect) (nbdkit_next_preconnect *next, nbdkit_backend *nxdata,
 204                      int readonly);
 205   int (*list_exports) (nbdkit_next_list_exports *next, nbdkit_backend *nxdata,
 206                        int readonly, int is_tls,
 207                        struct nbdkit_exports *exports);
 208   const char * (*default_export) (nbdkit_next_default_export *next,
 209                                   nbdkit_backend *nxdata,
 210                                   int readonly, int is_tls);
 211
 212   void * (*open) (nbdkit_next_open *next, nbdkit_context *context,
 213                   int readonly, const char *exportname, int is_tls);
 214   void (*close) (void *handle);
 215
 216   int (*prepare) (nbdkit_next *next,
 217                   void *handle, int readonly);
 218   int (*finalize) (nbdkit_next *next,
 219                    void *handle);
 220
 221   int64_t (*get_size) (nbdkit_next *next,
 222                        void *handle);
 223   const char * (*export_description) (nbdkit_next *next, void *handle);
 224   int (*block_size) (nbdkit_next *next, void *handle,
 225                      uint32_t *minimum, uint32_t *preferred, uint32_t *maximum);
 226
 227   int (*can_write) (nbdkit_next *next,
 228                     void *handle);
 229   int (*can_flush) (nbdkit_next *next,
 230                     void *handle);
 231   int (*is_rotational) (nbdkit_next *next, void *handle);
 232   int (*can_trim) (nbdkit_next *next,
 233                    void *handle);
 234   int (*can_zero) (nbdkit_next *next,
 235                    void *handle);
 236   int (*can_fast_zero) (nbdkit_next *next, void *handle);
 237   int (*can_extents) (nbdkit_next *next,
 238                       void *handle);
 239   int (*can_fua) (nbdkit_next *next,
 240                   void *handle);
 241   int (*can_multi_conn) (nbdkit_next *next, void *handle);
 242   int (*can_cache) (nbdkit_next *next,
 243                     void *handle);
 244
 245   int (*pread) (nbdkit_next *next,
 246                 void *handle, void *buf, uint32_t count, uint64_t offset,
 247                 uint32_t flags, int *err);
 248   int (*pwrite) (nbdkit_next *next,
 249                  void *handle,
 250                  const void *buf, uint32_t count, uint64_t offset,
 251                  uint32_t flags, int *err);
 252   int (*flush) (nbdkit_next *next,
 253                 void *handle, uint32_t flags, int *err);
 254   int (*trim) (nbdkit_next *next,
 255                void *handle, uint32_t count, uint64_t offset, uint32_t flags,
 256                int *err);
 257   int (*zero) (nbdkit_next *next,
 258                void *handle, uint32_t count, uint64_t offset, uint32_t flags,
 259                int *err);
 260   int (*extents) (nbdkit_next *next,
 261                   void *handle, uint32_t count, uint64_t offset, uint32_t flags,
 262                   struct nbdkit_extents *extents, int *err);
 263   int (*cache) (nbdkit_next *next,
 264                 void *handle, uint32_t count, uint64_t offset, uint32_t flags,
 265                 int *err);
 266 };
 267
 268 #define NBDKIT_REGISTER_FILTER(filter)                                  \
 269   NBDKIT_CXX_LANG_C                                                     \
 270   NBDKIT_DLL_PUBLIC                                                     \
 271   struct nbdkit_filter *                                                \
 272   filter_init (void)                                                    \
 273   {                                                                     \
 274     (filter)._api_version = NBDKIT_FILTER_API_VERSION;                  \
 275     (filter)._version = NBDKIT_VERSION_STRING;                          \
 276     return &(filter);                                                   \
 277   }
 278
 279 #ifdef __cplusplus
 280 }
 281 #endif
 282
 283 #endif /* NBDKIT_FILTER_H */