ceph/src/spdk/ocf/inc/ocf_volume.h

   1 /*
   2  * Copyright(c) 2012-2018 Intel Corporation
   3  * SPDX-License-Identifier: BSD-3-Clause-Clear
   4  */
   5
   6 #ifndef __OCF_VOLUME_H__
   7 #define __OCF_VOLUME_H__
   8
   9 /**
  10  * @file
  11  * @brief OCF volume API
  12  */
  13
  14 #include "ocf_types.h"
  15 #include "ocf_env.h"
  16 #include "ocf_err.h"
  17
  18 struct ocf_io;
  19
  20 /**
  21  * @brief OCF volume UUID maximum allowed size
  22  */
  23 #define OCF_VOLUME_UUID_MAX_SIZE        (4096UL - sizeof(uint32_t))
  24
  25 /**
  26  * @brief OCF volume UUID
  27  */
  28 struct ocf_volume_uuid {
  29         size_t size;
  30                 /*!< UUID data size */
  31
  32         void *data;
  33                 /*!< UUID data content */
  34 };
  35
  36 /**
  37  * @brief This structure describes volume capabilities
  38  */
  39 struct ocf_volume_caps {
  40         uint32_t atomic_writes : 1;
  41                 /*!< Volume supports atomic writes */
  42 };
  43
  44 /**
  45  * @brief OCF volume interface declaration
  46  */
  47 struct ocf_volume_ops {
  48         /**
  49          * @brief Submit IO on this volume
  50          *
  51          * @param[in] io IO to be submitted
  52          */
  53         void (*submit_io)(struct ocf_io *io);
  54
  55         /**
  56          * @brief Submit IO with flush command
  57          *
  58          * @param[in] io IO to be submitted
  59          */
  60         void (*submit_flush)(struct ocf_io *io);
  61
  62         /**
  63          * @brief Submit IO with metadata
  64          *
  65          * @param[in] io IO to be submitted
  66          */
  67         void (*submit_metadata)(struct ocf_io *io);
  68
  69         /**
  70          * @brief Submit IO with discard command
  71          *
  72          * @param[in] io IO to be submitted
  73          */
  74         void (*submit_discard)(struct ocf_io *io);
  75
  76         /**
  77          * @brief Submit operation to write zeroes to target address (including
  78          *        metadata extended LBAs in atomic mode)
  79          *
  80          * @param[in] io IO description (addr, size)
  81          */
  82         void (*submit_write_zeroes)(struct ocf_io *io);
  83
  84         /**
  85          * @brief Open volume
  86          *
  87          * @note This function performs volume initialization and should
  88          *       be called before any other operation on volume
  89          *
  90          * @param[in] volume Volume
  91          * @param[in] volume_params optional volume parameters, opaque to OCF
  92          */
  93         int (*open)(ocf_volume_t volume, void *volume_params);
  94
  95         /**
  96          * @brief Close volume
  97          *
  98          * @param[in] volume Volume
  99          */
 100         void (*close)(ocf_volume_t volume);
 101
 102         /**
 103          * @brief Close volume
 104          *
 105          * @param[in] volume Volume
 106          */
 107         unsigned int (*get_max_io_size)(ocf_volume_t volume);
 108
 109         /**
 110          * @brief Close volume
 111          *
 112          * @param[in] volume Volume
 113          */
 114         uint64_t (*get_length)(ocf_volume_t volume);
 115 };
 116
 117 /**
 118  * @brief This structure describes volume properties
 119  */
 120 struct ocf_volume_properties {
 121         const char *name;
 122                 /*!< The name of volume operations */
 123
 124         uint32_t io_priv_size;
 125                 /*!< Size of io private context structure */
 126
 127         uint32_t volume_priv_size;
 128                 /*!< Size of volume private context structure */
 129
 130         struct ocf_volume_caps caps;
 131                 /*!< Volume capabilities */
 132
 133         struct ocf_volume_ops ops;
 134                 /*!< Volume operations */
 135
 136         struct ocf_io_ops io_ops;
 137                 /*!< IO operations */
 138 };
 139
 140 /**
 141  * @brief Initialize UUID from string
 142  *
 143  * @param[in] uuid UUID to be initialized
 144  * @param[in] str NULL-terminated string
 145  *
 146  * @return Zero when success, othewise error
 147  */
 148 static inline int ocf_uuid_set_str(ocf_uuid_t uuid, char *str)
 149 {
 150         size_t len = env_strnlen(str, OCF_VOLUME_UUID_MAX_SIZE);
 151
 152         if (len >= OCF_VOLUME_UUID_MAX_SIZE)
 153                 return -OCF_ERR_INVAL;
 154
 155         uuid->data = str;
 156         uuid->size = len + 1;
 157
 158         return 0;
 159 }
 160
 161 /**
 162  * @brief Obtain string from UUID
 163  * @param[in] uuid pointer to UUID
 164  * @return String contained within UUID
 165  */
 166 static inline const char *ocf_uuid_to_str(const struct ocf_volume_uuid *uuid)
 167 {
 168         return uuid->data;
 169 }
 170
 171 /**
 172  * @brief Initialize volume
 173  *
 174  * @param[in] volume volume handle
 175  * @param[in] type cache/core volume type
 176  * @param[in] uuid OCF volume UUID
 177  * @param[in] uuid_copy crate copy of uuid data
 178  *
 179  * @return Zero when success, othewise error
 180  */
 181 int ocf_volume_init(ocf_volume_t volume, ocf_volume_type_t type,
 182                 struct ocf_volume_uuid *uuid, bool uuid_copy);
 183
 184 /**
 185  * @brief Deinitialize volume
 186  *
 187  * @param[in] volume volume handle
 188  */
 189 void ocf_volume_deinit(ocf_volume_t volume);
 190
 191 /**
 192  * @brief Allocate and initialize volume
 193  *
 194  * @param[out] volume pointer to volume handle
 195  * @param[in] type cache/core volume type
 196  * @param[in] uuid OCF volume UUID
 197  *
 198  * @return Zero when success, othewise en error
 199  */
 200 int ocf_volume_create(ocf_volume_t *volume, ocf_volume_type_t type,
 201                 struct ocf_volume_uuid *uuid);
 202
 203 /**
 204  * @brief Deinitialize and free volume
 205  *
 206  * @param[in] volume volume handle
 207  */
 208 void ocf_volume_destroy(ocf_volume_t volume);
 209
 210 /**
 211  * @brief Get volume type
 212  *
 213  * @param[in] volume Volume
 214  *
 215  * @return Volume type
 216  */
 217 ocf_volume_type_t ocf_volume_get_type(ocf_volume_t volume);
 218
 219 /**
 220  * @brief Get volume UUID
 221  *
 222  * @param[in] volume Volume
 223  *
 224  * @return UUID of volume
 225  */
 226 const struct ocf_volume_uuid *ocf_volume_get_uuid(ocf_volume_t volume);
 227
 228 /**
 229  * @brief Get private context of volume
 230  *
 231  * @param[in] volume Volume
 232  *
 233  * @return Volume private context
 234  */
 235 void *ocf_volume_get_priv(ocf_volume_t volume);
 236
 237 /**
 238  * @brief Get cache handle for given volume
 239  *
 240  * @param volume volume handle
 241  *
 242  * @return Handle to cache for which volume belongs to
 243  */
 244 ocf_cache_t ocf_volume_get_cache(ocf_volume_t volume);
 245
 246 /**
 247  * @brief Check if volume supports atomic mode
 248  *
 249  * @param[in] volume Volume
 250  *
 251  * @return Non-zero value if volume is atomic, otherwise zero
 252  */
 253 int ocf_volume_is_atomic(ocf_volume_t volume);
 254
 255 /**
 256  * @brief Allocate new io
 257  *
 258  * @param[in] volume Volume
 259  *
 260  * @return ocf_io on success atomic, otherwise NULL
 261  */
 262 struct ocf_io *ocf_volume_new_io(ocf_volume_t volume);
 263
 264 /**
 265  * @brief Submit io to volume
 266  *
 267  * @param[in] io IO
 268  */
 269 void ocf_volume_submit_io(struct ocf_io *io);
 270
 271 /**
 272  * @brief Submit flush to volume
 273  *
 274  * @param[in] io IO
 275  */
 276 void ocf_volume_submit_flush(struct ocf_io *io);
 277
 278 /**
 279  * @brief Submit discard to volume
 280  *
 281  * @param[in] io IO
 282  */
 283 void ocf_volume_submit_discard(struct ocf_io *io);
 284
 285 /**
 286  * @brief Open volume
 287  *
 288  * @param[in] volume Volume
 289  * @param[in] volume_params Opaque volume params
 290  *
 291  * @return Zero when success, othewise en error
 292  */
 293 int ocf_volume_open(ocf_volume_t volume, void *volume_params);
 294
 295 /**
 296  * @brief Get volume max io size
 297  *
 298  * @param[in] volume Volume
 299  */
 300 void ocf_volume_close(ocf_volume_t volume);
 301
 302 /**
 303  * @brief Get volume max io size
 304  *
 305  * @param[in] volume Volume
 306  *
 307  * @return Volume max io size in bytes
 308  */
 309 unsigned int ocf_volume_get_max_io_size(ocf_volume_t volume);
 310
 311 /**
 312  * @brief Get volume length
 313  *
 314  * @param[in] volume Volume
 315  *
 316  * @return Length of volume in bytes
 317  */
 318 uint64_t ocf_volume_get_length(ocf_volume_t volume);
 319
 320 #endif /* __OCF_VOLUME_H__ */