common/regions/regions.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 #ifndef NBDKIT_REGIONS_H
  34 #define NBDKIT_REGIONS_H
  35
  36 #include <stdint.h>
  37 #include <stdarg.h>
  38 #include <assert.h>
  39
  40 #include "vector.h"
  41
  42 /* This defines a very simple structure used to define the virtual
  43  * disk in the partitioning and floppy plugins.
  44  *
  45  * We split the virtual disk into non-overlapping, contiguous regions.
  46  * These are stored in an array, ordered by address.
  47  *
  48  * Each region can be one of several types, referring to a backing
  49  * file, some data stored in memory, or zero padding.
  50  */
  51
  52 /* Region type. */
  53 enum region_type {
  54   region_file,        /* contents of the i'th file */
  55   region_data,        /* pointer to in-memory data */
  56   region_zero,        /* padding */
  57 };
  58
  59 /* Region. */
  60 struct region {
  61   uint64_t start, len, end;    /* byte offsets; end = start + len - 1 */
  62   enum region_type type;
  63   union {
  64     size_t i;                  /* region_file: i'th file */
  65     const unsigned char *data; /* region_data: data */
  66   } u;
  67
  68   /* Optional name or description of this region.  This is not used by
  69    * the regions code but can be added to regions to make debugging
  70    * easier.
  71    */
  72   const char *description;
  73 };
  74
  75 /* Vector of struct region. */
  76 DEFINE_VECTOR_TYPE (regions, struct region);
  77
  78 extern void init_regions (regions *regions)
  79   __attribute__ ((__nonnull__ (1)));
  80 extern void free_regions (regions *regions)
  81   __attribute__ ((__nonnull__ (1)));
  82
  83 /* Return the number of regions. */
  84 static inline size_t __attribute__ ((__nonnull__ (1)))
  85 nr_regions (regions *rs)
  86 {
  87   return rs->len;
  88 }
  89
  90 /* Return the virtual size of the disk. */
  91 static inline int64_t __attribute__ ((__nonnull__ (1)))
  92 virtual_size (regions *rs)
  93 {
  94   if (rs->len == 0)
  95     return 0;
  96   else
  97     return rs->ptr[rs->len-1].end + 1;
  98 }
  99
 100 /* Look up the region corresponding to the given offset.  If the
 101  * offset is inside the disk image then this cannot return NULL.
 102  */
 103 extern const struct region *find_region (const regions *regions,
 104                                          uint64_t offset)
 105   __attribute__ ((__nonnull__ (1)));
 106
 107 /* Append one region of a given length, plus up to two optional
 108  * padding regions.
 109  *
 110  * pre_aligment (if != 0) describes the required alignment of this
 111  * region.  A padding region of type region_zero is inserted before
 112  * the main region if required.
 113  *
 114  * post_alignment (if != 0) describes the required alignment after
 115  * this region.  A padding region of type region_zero is inserted
 116  * after the main region if required.
 117  *
 118  * If type == region_file, it must be followed by u.i parameter.
 119  * If type == region_data, it must be followed by u.data parameter.
 120  */
 121 extern int append_region_len (regions *regions,
 122                               const char *description, uint64_t len,
 123                               uint64_t pre_aligment, uint64_t post_alignment,
 124                               enum region_type type, ...);
 125
 126 /* Same as append_region_len (above) but instead of specifying the
 127  * size of the main region, specify the end byte as an offset.  Note
 128  * the end byte is included in the region, it's is NOT the end+1 byte.
 129  */
 130 extern int append_region_end (regions *regions,
 131                               const char *description, uint64_t end,
 132                               uint64_t pre_aligment, uint64_t post_alignment,
 133                               enum region_type type, ...);
 134
 135 #endif /* NBDKIT_REGIONS_H */