The patch below converts the #ifndef SYMBOL / #define SYMBOL / #endif symbol
[mirror/scst/.git] / doc / sgv_cache.txt
1                         SCST SGV CACHE.
2
3                 PROGRAMMING INTERFACE DESCRIPTION.
4
5                      For SCST version 1.0.2
6
7 SCST SGV cache is a memory management subsystem in SCST. One can call it
8 a "memory pool", but Linux kernel already have a mempool interface,
9 which serves different purposes. SGV cache provides to SCST core, target
10 drivers and backend dev handlers facilities to allocate, build and cache
11 SG vectors for data buffers. The main advantage of it is the caching
12 facility, when it doesn't free to the system each vector, which is not
13 used anymore, but keeps it for a while (possibly indefinitely) to let it
14 be reused by the next consecutive command. This allows to:
15
16  - Reduce commands processing latencies and, hence, improve performance;
17
18  - Make commands processing latencies predictable, which is essential
19    for RT applications.
20
21 The freed SG vectors are kept by the SGV cache either for some (possibly
22 indefinite) time, or, optionally, until the system needs more memory and
23 asks to free some using the set_shrinker() interface. Also the SGV cache
24 allows to:
25
26   - Cluster pages together. "Cluster" means merging adjacent pages in a
27 single SG entry. It allows to have less SG entries in the resulting SG
28 vector, hence improve performance handling it as well as allow to
29 work with bigger buffers on hardware with limited SG capabilities.
30
31   - Set custom page allocator functions. For instance, scst_user device
32 handler uses this facility to eliminate unneeded mapping/unmapping of
33 user space pages and avoid unneeded IOCTL calls for buffers allocations.
34 In fileio_tgt application, which uses a regular malloc() function to
35 allocate data buffers, this facility allows ~30% less CPU load and
36 considerable performance increase.
37
38  - Prevent each initiator or all initiators altogether to allocate too 
39 much memory and DoS the target. Consider 10 initiators, which can have
40 access to 10 devices each. Any of them can queue up to 64 commands, each
41 can transfer up to 1MB of data. So, all of them in a peak can allocate
42 up to 10*10*64 = ~6.5GB of memory for data buffers. This amount must be
43 limited somehow and the SGV cache performs this function. 
44
45 From implementation POV the SGV cache is a simple extension of the kmem
46 cache. It can work in 2 modes:
47
48 1. With fixed size buffers.
49
50 2. With a set of power 2 size buffers. In this mode each SGV cache
51 (struct sgv_pool) has SGV_POOL_ELEMENTS (11 currently) of kmem caches.
52 Each of those kmem caches keeps SGV cache objects (struct sgv_pool_obj)
53 corresponding to SG vectors with size of order X pages. For instance,
54 request to allocate 4 pages will be served from kmem cache[2], since the
55 order of the of number of requested pages is 2. If later request to
56 allocate 11KB comes, the same SG vector with 4 pages will be reused (see
57 below). This mode is in average allows less memory overhead comparing
58 with the fixed size buffers mode.
59
60 Consider how the SGV cache works in the set of buffers mode. When a
61 request to allocate new SG vector comes, sgv_pool_alloc() via 
62 sgv_get_obj() checks if there is already a cached vector with that
63 order. If yes, then that vector will be reused and its length, if 
64 necessary, will be modified to match the requested size. In the above 
65 example request for 11KB buffer, 4 pages vector will be reused and
66 modified using trans_tbl to contain 3 pages and the last entry will be
67 modified to contain the requested length - 2*PAGE_SIZE. If there is no
68 cached object, then a new sgv_pool_obj will be allocated from the
69 corresponding kmem cache, chosen by the order of number of requested
70 pages. Then that vector will be filled by pages and returned.
71
72 In the fixed size buffers mode the SGV cache works similarly, except
73 that it always allocate buffer with the predefined fixed size. I.e.
74 even for 4K request the whole buffer with predefined size, say, 1MB,
75 will be used.
76
77 In both modes, if size of a request exceeds the maximum allowed for
78 caching buffer size, the requested buffer will be allocated, but not
79 cached.
80
81 Freed cached sgv_pool_obj objects are actually freed to the system
82 either by the purge work, which is scheduled once in 60 seconds, or in
83 sgv_shrink() called by system, when it's asking for memory.
84
85
86                         Interface.
87
88 struct sgv_pool *sgv_pool_create(const char *name,
89         enum sgv_clustering_types clustered, int single_alloc_pages,
90         bool shared, int purge_interval)
91         
92 This function creates and initializes an SGV cache. It has the following
93 arguments:
94
95  - name - the name of the SGV cache
96
97  - clustered - sets type of the pages clustering. The type can be:
98
99      * sgv_no_clustering - no clustering performed.
100
101      * sgv_tail_clustering - a page will only be merged with the latest
102        previously allocated page, so the order of pages in the SG will be
103        preserved
104
105      * sgv_full_clustering - free merging of pages at any place in
106        the SG is allowed. This mode usually provides the best merging
107        rate.
108  
109  - single_alloc_pages - if 0, then the SGV cache will work in the set of
110    power 2 size buffers mode. If >0, then the SGV cache will work in the
111    fixed size buffers mode. In this case single_alloc_pages sets the
112    size of each buffer in pages.
113
114  - shared - sets if the SGV cache can be shared between devices or not.
115    The cache sharing allowed only between devices created inside the same
116    address space. If an SGV cache is shared, each subsequent call of
117    sgv_pool_create() with the same cache name will not create a new cache,
118    but instead return a reference to it.
119
120  - purge_interval - sets the cache purging interval. I.e. an SG buffer
121    will be freed if it's unused for time t purge_interval <= t <
122    2*purge_interval. If purge_interval is 0, then the default interval
123    will be used (60 seconds). If purge_interval <0, then the automatic
124    purging will be disabled. Shrinking by the system's demand will also
125    be disabled.
126
127 Returns the resulting SGV cache or NULL in case of any error.
128
129
130 void sgv_pool_del(struct sgv_pool *pool)
131
132 This function deletes the corresponding SGV cache. If the cache is
133 shared, it will decrease its reference counter. If the reference counter
134 reaches 0, the cache will be destroyed.
135
136
137 void sgv_pool_flush(struct sgv_pool *pool)
138
139 This function flushes, i.e. frees, all the cached entries in the SGV
140 cache.
141
142
143 void sgv_pool_set_allocator(struct sgv_pool *pool,
144         struct page *(*alloc_pages_fn)(struct scatterlist *sg, gfp_t gfp, void *priv),
145         void (*free_pages_fn)(struct scatterlist *sg, int sg_count, void *priv));
146
147 This function allows to set for the SGV cache a custom pages allocator. For
148 instance, scst_user uses such function to supply to the cache mapped from
149 user space pages.
150
151 alloc_pages_fn() has the following parameters:
152
153  - sg - SG entry, to which the allocated page should be added.
154  
155  - gfp - the allocation GFP flags
156  
157  - priv - pointer to a private data supplied to sgv_pool_alloc()
158  
159 This function should return the allocated page or NULL, if no page was
160 allocated.
161
162
163 free_pages_fn() has the following parameters:
164
165  - sg - SG vector to free
166  
167  - sg_count - number of SG entries in the sg
168  
169  - priv - pointer to a private data supplied to the corresponding sgv_pool_alloc()
170
171
172 struct scatterlist *sgv_pool_alloc(struct sgv_pool *pool, unsigned int size,
173         gfp_t gfp_mask, int flags, int *count,
174         struct sgv_pool_obj **sgv, struct scst_mem_lim *mem_lim, void *priv)
175
176 This function allocates an SG vector from the SGV cache. It has the
177 following parameters:
178
179  - pool - the cache to alloc from
180
181  - size - size of the resulting SG vector in bytes
182
183  - gfp_mask - the allocation mask
184  
185  - flags - the allocation flags. The following flags are possible and
186    can be set using OR operation:
187  
188      * SGV_POOL_ALLOC_NO_CACHED - the SG vector must not be cached.
189  
190      * SGV_POOL_NO_ALLOC_ON_CACHE_MISS - don't do an allocation on a
191        cache miss.
192  
193      * SGV_POOL_RETURN_OBJ_ON_ALLOC_FAIL - return an empty SGV object,
194        i.e. without the SG vector, if the allocation can't be completed.
195        For instance, because SGV_POOL_NO_ALLOC_ON_CACHE_MISS flag set.
196  
197  - count - the resulting count of SG entries in the resulting SG vector.
198
199  - sgv - the resulting SGV object. It should be used to free the
200    resulting SG vector.
201  
202  - mem_lim - memory limits, see below.
203  
204  - priv - pointer to private for this allocation data. This pointer will
205    be supplied to alloc_pages_fn() and free_pages_fn() and can be
206    retrieved by sgv_get_priv().
207
208 This function returns pointer to the resulting SG vector or NULL in case
209 of any error.
210
211
212 void sgv_pool_free(struct sgv_pool_obj *sgv, struct scst_mem_lim *mem_lim)
213
214 This function frees previously allocated SG vector, referenced by SGV
215 cache object sgv.
216
217
218 void *sgv_get_priv(struct sgv_pool_obj *sgv)
219
220 This function allows to get the allocation private data for this SGV
221 cache object sgv. The private data are set by sgv_pool_alloc().
222
223
224 void scst_init_mem_lim(struct scst_mem_lim *mem_lim)
225
226 This function initializes memory limits structure mem_lim according to
227 the current system configuration. This structure should be latter used
228 to track and limit allocated by one or more SGV caches memory.
229
230
231                 Runtime information and statistics.
232
233 Runtime information and statistics is available in /proc/scsi_tgt/sgv.
234