include/linux/flex_array.h

   1 #ifndef _FLEX_ARRAY_H
   2 #define _FLEX_ARRAY_H
   3
   4 #include <linux/types.h>
   5 #include <linux/reciprocal_div.h>
   6 #include <asm/page.h>
   7
   8 #define FLEX_ARRAY_PART_SIZE PAGE_SIZE
   9 #define FLEX_ARRAY_BASE_SIZE PAGE_SIZE
  10
  11 struct flex_array_part;
  12
  13 /*
  14  * This is meant to replace cases where an array-like
  15  * structure has gotten too big to fit into kmalloc()
  16  * and the developer is getting tempted to use
  17  * vmalloc().
  18  */
  19
  20 struct flex_array {
  21         union {
  22                 struct {
  23                         int element_size;
  24                         int total_nr_elements;
  25                         int elems_per_part;
  26                         struct reciprocal_value reciprocal_elems;
  27                         struct flex_array_part *parts[];
  28                 };
  29                 /*
  30                  * This little trick makes sure that
  31                  * sizeof(flex_array) == PAGE_SIZE
  32                  */
  33                 char padding[FLEX_ARRAY_BASE_SIZE];
  34         };
  35 };
  36
  37 /* Number of bytes left in base struct flex_array, excluding metadata */
  38 #define FLEX_ARRAY_BASE_BYTES_LEFT                                      \
  39         (FLEX_ARRAY_BASE_SIZE - offsetof(struct flex_array, parts))
  40
  41 /* Number of pointers in base to struct flex_array_part pages */
  42 #define FLEX_ARRAY_NR_BASE_PTRS                                         \
  43         (FLEX_ARRAY_BASE_BYTES_LEFT / sizeof(struct flex_array_part *))
  44
  45 /* Number of elements of size that fit in struct flex_array_part */
  46 #define FLEX_ARRAY_ELEMENTS_PER_PART(size)                              \
  47         (FLEX_ARRAY_PART_SIZE / size)
  48
  49 /*
  50  * Defines a statically allocated flex array and ensures its parameters are
  51  * valid.
  52  */
  53 #define DEFINE_FLEX_ARRAY(__arrayname, __element_size, __total)         \
  54         struct flex_array __arrayname = { { {                           \
  55                 .element_size = (__element_size),                       \
  56                 .total_nr_elements = (__total),                         \
  57         } } };                                                          \
  58         static inline void __arrayname##_invalid_parameter(void)        \
  59         {                                                               \
  60                 BUILD_BUG_ON((__total) > FLEX_ARRAY_NR_BASE_PTRS *      \
  61                         FLEX_ARRAY_ELEMENTS_PER_PART(__element_size));  \
  62         }
  63
  64 /**
  65  * flex_array_alloc() - Creates a flexible array.
  66  * @element_size:       individual object size.
  67  * @total:              maximum number of objects which can be stored.
  68  * @flags:              GFP flags
  69  *
  70  * Return:              Returns an object of structure flex_array.
  71  */
  72 struct flex_array *flex_array_alloc(int element_size, unsigned int total,
  73                 gfp_t flags);
  74
  75 /**
  76  * flex_array_prealloc() - Ensures that memory for the elements indexed in the
  77  * range defined by start and nr_elements has been allocated.
  78  * @fa:                 array to allocate memory to.
  79  * @start:              start address
  80  * @nr_elements:        number of elements to be allocated.
  81  * @flags:              GFP flags
  82  *
  83  */
  84 int flex_array_prealloc(struct flex_array *fa, unsigned int start,
  85                 unsigned int nr_elements, gfp_t flags);
  86
  87 /**
  88  * flex_array_free() - Removes all elements of a flexible array.
  89  * @fa:         array to be freed.
  90  */
  91 void flex_array_free(struct flex_array *fa);
  92
  93 /**
  94  * flex_array_free_parts() - Removes all elements of a flexible array, but
  95  * leaves the array itself in place.
  96  * @fa:         array to be emptied.
  97  */
  98 void flex_array_free_parts(struct flex_array *fa);
  99
 100 /**
 101  * flex_array_put() - Stores data into a flexible array.
 102  * @fa:         array where element is to be stored.
 103  * @element_nr: position to copy, must be less than the maximum specified when
 104  *              the array was created.
 105  * @src:        data source to be copied into the array.
 106  * @flags:      GFP flags
 107  *
 108  * Return:      Returns zero on success, a negative error code otherwise.
 109  */
 110 int flex_array_put(struct flex_array *fa, unsigned int element_nr, void *src,
 111                 gfp_t flags);
 112
 113 /**
 114  * flex_array_clear() - Clears an individual element in the array, sets the
 115  * given element to FLEX_ARRAY_FREE.
 116  * @element_nr: element position to clear.
 117  * @fa:         array to which element to be cleared belongs.
 118  *
 119  * Return:      Returns zero on success, -EINVAL otherwise.
 120  */
 121 int flex_array_clear(struct flex_array *fa, unsigned int element_nr);
 122
 123 /**
 124  * flex_array_get() - Retrieves data into a flexible array.
 125  *
 126  * @element_nr: Element position to retrieve data from.
 127  * @fa:         array from which data is to be retrieved.
 128  *
 129  * Return:      Returns a pointer to the data element, or NULL if that
 130  *              particular element has never been allocated.
 131  */
 132 void *flex_array_get(struct flex_array *fa, unsigned int element_nr);
 133
 134 /**
 135  * flex_array_shrink() - Reduces the allocated size of an array.
 136  * @fa:         array to shrink.
 137  *
 138  * Return:      Returns number of pages of memory actually freed.
 139  *
 140  */
 141 int flex_array_shrink(struct flex_array *fa);
 142
 143 #define flex_array_put_ptr(fa, nr, src, gfp) \
 144         flex_array_put(fa, nr, (void *)&(src), gfp)
 145
 146 void *flex_array_get_ptr(struct flex_array *fa, unsigned int element_nr);
 147
 148 #endif /* _FLEX_ARRAY_H */