include/nbdkit-filter.h

   1 /* nbdkit
   2  * Copyright (C) 2013-2020 Red Hat Inc.
   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 struct nbdkit_extent {
  53   uint64_t offset;
  54   uint64_t length;
  55   uint32_t type;
  56 };
  57
  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 *,
  62                                                size_t);
  63
  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_preconnect (void *nxdata, int readonly);
  68 typedef int nbdkit_next_open (void *nxdata, int readonly);
  69
  70 struct nbdkit_next_ops {
  71   /* Performs close + open on the underlying chain.
  72    * Used by the retry filter.
  73    */
  74   int (*reopen) (void *nxdata, int readonly);
  75
  76   /* The rest of the next ops are the same as normal plugin operations. */
  77   int64_t (*get_size) (void *nxdata);
  78
  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);
  89   int (*init_sparse) (void *nxdata);
  90   int (*init_zero) (void *nxdata);
  91
  92   int (*pread) (void *nxdata, void *buf, uint32_t count, uint64_t offset,
  93                 uint32_t flags, int *err);
  94   int (*pwrite) (void *nxdata,
  95                  const void *buf, uint32_t count, uint64_t offset,
  96                  uint32_t flags, int *err);
  97   int (*flush) (void *nxdata, uint32_t flags, int *err);
  98   int (*trim) (void *nxdata, uint32_t count, uint64_t offset, uint32_t flags,
  99                int *err);
 100   int (*zero) (void *nxdata, uint32_t count, uint64_t offset, uint32_t flags,
 101                int *err);
 102   int (*extents) (void *nxdata, uint32_t count, uint64_t offset, uint32_t flags,
 103                   struct nbdkit_extents *extents, int *err);
 104   int (*cache) (void *nxdata, uint32_t count, uint64_t offset, uint32_t flags,
 105                 int *err);
 106 };
 107
 108 struct nbdkit_filter {
 109   /* Do not set these fields directly; use NBDKIT_REGISTER_FILTER.
 110    * They exist so that we can diagnose filters compiled against one
 111    * version of the header with a runtime compiled against a different
 112    * version.  As of API version 6, _version is also part of the
 113    * guaranteed ABI, so we no longer have to remember to bump API
 114    * versions regardless of other API/ABI changes later in the struct.
 115    */
 116   int _api_version;
 117   const char *_version;
 118
 119   /* Because there is no ABI guarantee, new fields may be added where
 120    * logically appropriate.
 121    */
 122   const char *name;
 123   const char *longname;
 124   const char *description;
 125
 126   void (*load) (void);
 127   void (*unload) (void);
 128
 129   int (*config) (nbdkit_next_config *next, void *nxdata,
 130                  const char *key, const char *value);
 131   int (*config_complete) (nbdkit_next_config_complete *next, void *nxdata);
 132   const char *config_help;
 133   int (*thread_model) (void);
 134   int (*preconnect) (nbdkit_next_preconnect *next, void *nxdata, int readonly);
 135
 136   void * (*open) (nbdkit_next_open *next, void *nxdata,
 137                   int readonly);
 138   void (*close) (void *handle);
 139
 140   int (*prepare) (struct nbdkit_next_ops *next_ops, void *nxdata,
 141                   void *handle, int readonly);
 142   int (*finalize) (struct nbdkit_next_ops *next_ops, void *nxdata,
 143                    void *handle);
 144
 145   int64_t (*get_size) (struct nbdkit_next_ops *next_ops, void *nxdata,
 146                        void *handle);
 147
 148   int (*can_write) (struct nbdkit_next_ops *next_ops, void *nxdata,
 149                     void *handle);
 150   int (*can_flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
 151                     void *handle);
 152   int (*is_rotational) (struct nbdkit_next_ops *next_ops,
 153                         void *nxdata,
 154                         void *handle);
 155   int (*can_trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
 156                    void *handle);
 157   int (*can_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
 158                    void *handle);
 159   int (*can_fast_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
 160                         void *handle);
 161   int (*can_extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
 162                       void *handle);
 163   int (*can_fua) (struct nbdkit_next_ops *next_ops, void *nxdata,
 164                   void *handle);
 165   int (*can_multi_conn) (struct nbdkit_next_ops *next_ops, void *nxdata,
 166                          void *handle);
 167   int (*can_cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
 168                     void *handle);
 169   int (*init_sparse) (struct nbdkit_next_ops *next_ops, void *nxdata,
 170                       void *handle);
 171   int (*init_zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
 172                     void *handle);
 173
 174   int (*pread) (struct nbdkit_next_ops *next_ops, void *nxdata,
 175                 void *handle, void *buf, uint32_t count, uint64_t offset,
 176                 uint32_t flags, int *err);
 177   int (*pwrite) (struct nbdkit_next_ops *next_ops, void *nxdata,
 178                  void *handle,
 179                  const void *buf, uint32_t count, uint64_t offset,
 180                  uint32_t flags, int *err);
 181   int (*flush) (struct nbdkit_next_ops *next_ops, void *nxdata,
 182                 void *handle, uint32_t flags, int *err);
 183   int (*trim) (struct nbdkit_next_ops *next_ops, void *nxdata,
 184                void *handle, uint32_t count, uint64_t offset, uint32_t flags,
 185                int *err);
 186   int (*zero) (struct nbdkit_next_ops *next_ops, void *nxdata,
 187                void *handle, uint32_t count, uint64_t offset, uint32_t flags,
 188                int *err);
 189   int (*extents) (struct nbdkit_next_ops *next_ops, void *nxdata,
 190                   void *handle, uint32_t count, uint64_t offset, uint32_t flags,
 191                   struct nbdkit_extents *extents, int *err);
 192   int (*cache) (struct nbdkit_next_ops *next_ops, void *nxdata,
 193                 void *handle, uint32_t count, uint64_t offset, uint32_t flags,
 194                 int *err);
 195 };
 196
 197 #define NBDKIT_REGISTER_FILTER(filter)                                  \
 198   NBDKIT_CXX_LANG_C                                                     \
 199   struct nbdkit_filter *                                                \
 200   filter_init (void)                                                    \
 201   {                                                                     \
 202     (filter)._api_version = NBDKIT_FILTER_API_VERSION;                  \
 203     (filter)._version = NBDKIT_VERSION_STRING;                          \
 204     return &(filter);                                                   \
 205   }
 206
 207 #ifdef __cplusplus
 208 }
 209 #endif
 210
 211 #endif /* NBDKIT_FILTER_H */