- Possibility to operate with single size entries as well as control of the reclamat...
[mirror/scst/.git] / scst / include / scst_sgv.h
1 /*
2  *  include/scst_sgv.h
3  *
4  *  Copyright (C) 2004 - 2009 Vladislav Bolkhovitin <vst@vlnb.net>
5  *  Copyright (C) 2007 - 2009 ID7 Ltd.
6  *
7  *  Include file for SCST SGV cache.
8  *
9  *  This program is free software; you can redistribute it and/or
10  *  modify it under the terms of the GNU General Public License
11  *  as published by the Free Software Foundation, version 2
12  *  of the License.
13  *
14  *  This program is distributed in the hope that it will be useful,
15  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
16  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  *  GNU General Public License for more details.
18  */
19 #ifndef __SCST_SGV_H
20 #define __SCST_SGV_H
21
22 /** SGV pool routines and flag bits **/
23
24 /* Set if the allocated object must be not from the cache */
25 #define SGV_POOL_ALLOC_NO_CACHED                1
26
27 /* Set if there should not be any memory allocations on a cache miss */
28 #define SGV_POOL_NO_ALLOC_ON_CACHE_MISS         2
29
30 /* Set an object should be returned even if it doesn't have SG vector built */
31 #define SGV_POOL_RETURN_OBJ_ON_ALLOC_FAIL       4
32
33 struct sgv_pool_obj;
34 struct sgv_pool;
35
36 struct scst_mem_lim {
37         /* How much memory allocated under this object */
38         atomic_t alloced_pages;
39
40         /*
41          * How much memory allowed to allocated under this object. Put here
42          * mostly to save a possible cache miss accessing scst_max_dev_cmd_mem.
43          */
44         int max_allowed_pages;
45 };
46
47 /* Types of clustering */
48 enum sgv_clustering_types {
49         /* No clustering performed */
50         sgv_no_clustering = 0,
51
52         /*
53          * A page will only be merged with the latest previously allocated
54          * page, so the order of pages in the SG will be preserved.
55          */
56         sgv_tail_clustering,
57
58         /*
59          * Free merging of pages at any place in the SG is allowed. This mode
60          * usually provides the best merging rate.
61          */
62         sgv_full_clustering,
63 };
64
65 /**
66  * sgv_pool_create - creates and initializes an SGV cache
67  * @name:       the name of the SGV cache
68  * @clustered:  sets type of the pages clustering.
69  * @single_alloc_pages: if 0, then the SGV cache will work in the set of
70  *              power 2 size buffers mode. If >0, then the SGV cache will
71  *              work in the fixed size buffers mode. In this case
72  *              single_alloc_pages sets the size of each buffer in pages.
73  * @shared:     sets if the SGV cache can be shared between devices or not.
74  *              The cache sharing allowed only between devices created inside
75  *              the same address space. If an SGV cache is shared, each
76  *              subsequent call of sgv_pool_create() with the same cache name
77  *              will not create a new cache, but instead return a reference
78  *              to it.
79  * @purge_interval      sets the cache purging interval. I.e., an SG buffer
80  *              will be freed if it's unused for time t
81  *              purge_interval <= t < 2*purge_interval. If purge_interval
82  *              is 0, then the default interval will be used (60 seconds).
83  *              If purge_interval <0, then the automatic purging will be
84  *              disabled.
85  *
86  * Description:
87  *    Returns the resulting SGV cache or NULL in case of any error.
88  */
89 struct sgv_pool *sgv_pool_create(const char *name,
90         enum sgv_clustering_types clustered, int single_alloc_pages,
91         bool shared, int purge_interval);
92
93 /**
94  * sgv_pool_del - deletes the corresponding SGV cache
95  * @:pool       the cache to delete.
96  *
97  * Description:
98  *    If the cache is shared, it will decrease its reference counter.
99  *    If the reference counter reaches 0, the cache will be destroyed.
100  */
101 void sgv_pool_del(struct sgv_pool *pool);
102
103 /**
104  * sgv_pool_flush - flushes the SGV cache
105  * @:pool       the cache to flush
106  *
107  * Description:
108  *    Flushes, i.e. frees, all the cached entries in the SGV cache.
109  */
110 void sgv_pool_flush(struct sgv_pool *pool);
111
112 /**
113  * sgv_pool_set_allocator - allows to set a custom pages allocator
114  * @:pool       the cache
115  * @:alloc_pages_fn     pages allocation function
116  * @:free_pages_fn      pages freeing function
117  *
118  * Description:
119  *    See the SGV cache documentation for more details.
120  */
121 void sgv_pool_set_allocator(struct sgv_pool *pool,
122         struct page *(*alloc_pages_fn)(struct scatterlist *, gfp_t, void *),
123         void (*free_pages_fn)(struct scatterlist *, int, void *));
124
125 /**
126  * sgv_pool_alloc - allocates an SG vector from the SGV cache
127  * @:pool       the cache to alloc from
128  * @:size       size of the resulting SG vector in bytes
129  * @:gfp_mask   the allocation mask
130  * @:flags      the allocation flags
131  * @:count      the resulting count of SG entries in the resulting SG vector
132  * @:sgv        the resulting SGV object
133  * @:mem_lim    memory limits
134  * @:priv       pointer to private for this allocation data
135  *
136  * Description:
137  *    Returns pointer to the resulting SG vector or NULL in case
138  *    of any error. See the SGV cache documentation for more details.
139  */
140 struct scatterlist *sgv_pool_alloc(struct sgv_pool *pool, unsigned int size,
141         gfp_t gfp_mask, int flags, int *count,
142         struct sgv_pool_obj **sgv, struct scst_mem_lim *mem_lim, void *priv);
143
144 /**
145  * sgv_pool_free - frees previously allocated SG vector
146  * @:sgv        the SGV object to free
147  * @:mem_lim    memory limits
148  *
149  * Description:
150  *    Frees previously allocated SG vector, referenced by SGV cache object sgv
151  */
152 void sgv_pool_free(struct sgv_pool_obj *sgv, struct scst_mem_lim *mem_lim);
153
154 /**
155  * sgv_get_priv - returns the private allocation data
156  * @:sgv        the SGV object  
157  *
158  * Description:
159  *     Allows to get the allocation private data for this SGV
160  *     cache object sgv. The private data are set by sgv_pool_alloc().
161  */
162 void *sgv_get_priv(struct sgv_pool_obj *sgv);
163
164 /**
165  * scst_init_mem_lim - initializes memory limits
166  * @:mem_lim    memory limits
167  *
168  * Description:
169  *    Initializes memory limits structure mem_lim according to
170  *    the current system configuration. This structure should be latter used
171  *    to track and limit allocated by one or more SGV caches memory.
172  */
173 void scst_init_mem_lim(struct scst_mem_lim *mem_lim);
174
175 #endif /* __SCST_SGV_H */