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