]> CyberLeo.Net >> Repos - FreeBSD/releng/9.2.git/blob - sys/vm/uma.h
- Copy stable/9 to releng/9.2 as part of the 9.2-RELEASE cycle.
[FreeBSD/releng/9.2.git] / sys / vm / uma.h
1 /*-
2  * Copyright (c) 2002, 2003, 2004, 2005 Jeffrey Roberson <jeff@FreeBSD.org>
3  * Copyright (c) 2004, 2005 Bosko Milekic <bmilekic@FreeBSD.org>
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  * 1. Redistributions of source code must retain the above copyright
10  *    notice unmodified, this list of conditions, and the following
11  *    disclaimer.
12  * 2. Redistributions in binary form must reproduce the above copyright
13  *    notice, this list of conditions and the following disclaimer in the
14  *    documentation and/or other materials provided with the distribution.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  *
27  * $FreeBSD$
28  *
29  */
30
31 /*
32  * uma.h - External definitions for the Universal Memory Allocator
33  *
34 */
35
36 #ifndef VM_UMA_H
37 #define VM_UMA_H
38
39 #include <sys/param.h>          /* For NULL */
40 #include <sys/malloc.h>         /* For M_* */
41
42 /* User visible parameters */
43 #define UMA_SMALLEST_UNIT       (PAGE_SIZE / 256) /* Smallest item allocated */
44
45 /* Types and type defs */
46
47 struct uma_zone;
48 /* Opaque type used as a handle to the zone */
49 typedef struct uma_zone * uma_zone_t;
50
51 void zone_drain(uma_zone_t);
52
53 /* 
54  * Item constructor
55  *
56  * Arguments:
57  *      item  A pointer to the memory which has been allocated.
58  *      arg   The arg field passed to uma_zalloc_arg
59  *      size  The size of the allocated item
60  *      flags See zalloc flags
61  * 
62  * Returns:
63  *      0      on success
64  *      errno  on failure
65  *
66  * Discussion:
67  *      The constructor is called just before the memory is returned
68  *      to the user. It may block if necessary.
69  */
70 typedef int (*uma_ctor)(void *mem, int size, void *arg, int flags);
71
72 /*
73  * Item destructor
74  *
75  * Arguments:
76  *      item  A pointer to the memory which has been allocated.
77  *      size  The size of the item being destructed.
78  *      arg   Argument passed through uma_zfree_arg
79  * 
80  * Returns:
81  *      Nothing
82  *
83  * Discussion:
84  *      The destructor may perform operations that differ from those performed
85  *      by the initializer, but it must leave the object in the same state.
86  *      This IS type stable storage.  This is called after EVERY zfree call.
87  */
88 typedef void (*uma_dtor)(void *mem, int size, void *arg);
89
90 /* 
91  * Item initializer
92  *
93  * Arguments:
94  *      item  A pointer to the memory which has been allocated.
95  *      size  The size of the item being initialized.
96  *      flags See zalloc flags
97  * 
98  * Returns:
99  *      0      on success
100  *      errno  on failure
101  *
102  * Discussion:
103  *      The initializer is called when the memory is cached in the uma zone. 
104  *      The initializer and the destructor should leave the object in the same
105  *      state.
106  */
107 typedef int (*uma_init)(void *mem, int size, int flags);
108
109 /*
110  * Item discard function
111  *
112  * Arguments:
113  *      item  A pointer to memory which has been 'freed' but has not left the 
114  *            zone's cache.
115  *      size  The size of the item being discarded.
116  *
117  * Returns:
118  *      Nothing
119  *
120  * Discussion:
121  *      This routine is called when memory leaves a zone and is returned to the
122  *      system for other uses.  It is the counter-part to the init function.
123  */
124 typedef void (*uma_fini)(void *mem, int size);
125
126 /*
127  * What's the difference between initializing and constructing?
128  *
129  * The item is initialized when it is cached, and this is the state that the 
130  * object should be in when returned to the allocator. The purpose of this is
131  * to remove some code which would otherwise be called on each allocation by
132  * utilizing a known, stable state.  This differs from the constructor which
133  * will be called on EVERY allocation.
134  *
135  * For example, in the initializer you may want to initialize embedded locks,
136  * NULL list pointers, set up initial states, magic numbers, etc.  This way if
137  * the object is held in the allocator and re-used it won't be necessary to
138  * re-initialize it.
139  *
140  * The constructor may be used to lock a data structure, link it on to lists,
141  * bump reference counts or total counts of outstanding structures, etc.
142  *
143  */
144
145
146 /* Function proto types */
147
148 /*
149  * Create a new uma zone
150  *
151  * Arguments:
152  *      name  The text name of the zone for debugging and stats. This memory
153  *              should not be freed until the zone has been deallocated.
154  *      size  The size of the object that is being created.
155  *      ctor  The constructor that is called when the object is allocated.
156  *      dtor  The destructor that is called when the object is freed.
157  *      init  An initializer that sets up the initial state of the memory.
158  *      fini  A discard function that undoes initialization done by init.
159  *              ctor/dtor/init/fini may all be null, see notes above.
160  *      align A bitmask that corresponds to the requested alignment
161  *              eg 4 would be 0x3
162  *      flags A set of parameters that control the behavior of the zone.
163  *
164  * Returns:
165  *      A pointer to a structure which is intended to be opaque to users of
166  *      the interface.  The value may be null if the wait flag is not set.
167  */
168 uma_zone_t uma_zcreate(const char *name, size_t size, uma_ctor ctor,
169                     uma_dtor dtor, uma_init uminit, uma_fini fini,
170                     int align, u_int32_t flags);
171
172 /*
173  * Create a secondary uma zone
174  *
175  * Arguments:
176  *      name  The text name of the zone for debugging and stats. This memory
177  *              should not be freed until the zone has been deallocated.
178  *      ctor  The constructor that is called when the object is allocated.
179  *      dtor  The destructor that is called when the object is freed.
180  *      zinit  An initializer that sets up the initial state of the memory
181  *              as the object passes from the Keg's slab to the Zone's cache.
182  *      zfini  A discard function that undoes initialization done by init
183  *              as the object passes from the Zone's cache to the Keg's slab.
184  *
185  *              ctor/dtor/zinit/zfini may all be null, see notes above.
186  *              Note that the zinit and zfini specified here are NOT
187  *              exactly the same as the init/fini specified to uma_zcreate()
188  *              when creating a master zone.  These zinit/zfini are called
189  *              on the TRANSITION from keg to zone (and vice-versa). Once
190  *              these are set, the primary zone may alter its init/fini
191  *              (which are called when the object passes from VM to keg)
192  *              using uma_zone_set_init/fini()) as well as its own
193  *              zinit/zfini (unset by default for master zone) with
194  *              uma_zone_set_zinit/zfini() (note subtle 'z' prefix).
195  *
196  *      master  A reference to this zone's Master Zone (Primary Zone),
197  *              which contains the backing Keg for the Secondary Zone
198  *              being added.
199  *
200  * Returns:
201  *      A pointer to a structure which is intended to be opaque to users of
202  *      the interface.  The value may be null if the wait flag is not set.
203  */
204 uma_zone_t uma_zsecond_create(char *name, uma_ctor ctor, uma_dtor dtor,
205                     uma_init zinit, uma_fini zfini, uma_zone_t master);
206
207 /*
208  * Add a second master to a secondary zone.  This provides multiple data
209  * backends for objects with the same size.  Both masters must have
210  * compatible allocation flags.  Presently, UMA_ZONE_MALLOC type zones are
211  * the only supported.
212  *
213  * Returns:
214  *      Error on failure, 0 on success.
215  */
216 int uma_zsecond_add(uma_zone_t zone, uma_zone_t master);
217
218 /*
219  * Definitions for uma_zcreate flags
220  *
221  * These flags share space with UMA_ZFLAGs in uma_int.h.  Be careful not to
222  * overlap when adding new features.  0xf0000000 is in use by uma_int.h.
223  */
224 #define UMA_ZONE_PAGEABLE       0x0001  /* Return items not fully backed by
225                                            physical memory XXX Not yet */
226 #define UMA_ZONE_ZINIT          0x0002  /* Initialize with zeros */
227 #define UMA_ZONE_STATIC         0x0004  /* Statically sized zone */
228 #define UMA_ZONE_OFFPAGE        0x0008  /* Force the slab structure allocation
229                                            off of the real memory */
230 #define UMA_ZONE_MALLOC         0x0010  /* For use by malloc(9) only! */
231 #define UMA_ZONE_NOFREE         0x0020  /* Do not free slabs of this type! */
232 #define UMA_ZONE_MTXCLASS       0x0040  /* Create a new lock class */
233 #define UMA_ZONE_VM             0x0080  /*
234                                          * Used for internal vm datastructures
235                                          * only.
236                                          */
237 #define UMA_ZONE_HASH           0x0100  /*
238                                          * Use a hash table instead of caching
239                                          * information in the vm_page.
240                                          */
241 #define UMA_ZONE_SECONDARY      0x0200  /* Zone is a Secondary Zone */
242 #define UMA_ZONE_REFCNT         0x0400  /* Allocate refcnts in slabs */
243 #define UMA_ZONE_MAXBUCKET      0x0800  /* Use largest buckets */
244 #define UMA_ZONE_CACHESPREAD    0x1000  /*
245                                          * Spread memory start locations across
246                                          * all possible cache lines.  May
247                                          * require many virtually contiguous
248                                          * backend pages and can fail early.
249                                          */
250 #define UMA_ZONE_VTOSLAB        0x2000  /* Zone uses vtoslab for lookup. */
251 #define UMA_ZONE_NODUMP         0x4000  /*
252                                          * Zone's pages will not be included in
253                                          * mini-dumps.
254                                          */
255
256 /*
257  * These flags are shared between the keg and zone.  In zones wishing to add
258  * new kegs these flags must be compatible.  Some are determined based on
259  * physical parameters of the request and may not be provided by the consumer.
260  */
261 #define UMA_ZONE_INHERIT                                                \
262     (UMA_ZONE_OFFPAGE | UMA_ZONE_MALLOC | UMA_ZONE_HASH |               \
263     UMA_ZONE_REFCNT | UMA_ZONE_VTOSLAB)
264
265 /* Definitions for align */
266 #define UMA_ALIGN_PTR   (sizeof(void *) - 1)    /* Alignment fit for ptr */
267 #define UMA_ALIGN_LONG  (sizeof(long) - 1)      /* "" long */
268 #define UMA_ALIGN_INT   (sizeof(int) - 1)       /* "" int */
269 #define UMA_ALIGN_SHORT (sizeof(short) - 1)     /* "" short */
270 #define UMA_ALIGN_CHAR  (sizeof(char) - 1)      /* "" char */
271 #define UMA_ALIGN_CACHE (0 - 1)                 /* Cache line size align */
272
273 /*
274  * Destroys an empty uma zone.  If the zone is not empty uma complains loudly.
275  *
276  * Arguments:
277  *      zone  The zone we want to destroy.
278  *
279  */
280 void uma_zdestroy(uma_zone_t zone);
281
282 /*
283  * Allocates an item out of a zone
284  *
285  * Arguments:
286  *      zone  The zone we are allocating from
287  *      arg   This data is passed to the ctor function
288  *      flags See sys/malloc.h for available flags.
289  *
290  * Returns:
291  *      A non-null pointer to an initialized element from the zone is
292  *      guaranteed if the wait flag is M_WAITOK.  Otherwise a null pointer
293  *      may be returned if the zone is empty or the ctor failed.
294  */
295
296 void *uma_zalloc_arg(uma_zone_t zone, void *arg, int flags);
297
298 /*
299  * Allocates an item out of a zone without supplying an argument
300  *
301  * This is just a wrapper for uma_zalloc_arg for convenience.
302  *
303  */
304 static __inline void *uma_zalloc(uma_zone_t zone, int flags);
305
306 static __inline void *
307 uma_zalloc(uma_zone_t zone, int flags)
308 {
309         return uma_zalloc_arg(zone, NULL, flags);
310 }
311
312 /*
313  * Frees an item back into the specified zone.
314  *
315  * Arguments:
316  *      zone  The zone the item was originally allocated out of.
317  *      item  The memory to be freed.
318  *      arg   Argument passed to the destructor
319  *
320  * Returns:
321  *      Nothing.
322  */
323
324 void uma_zfree_arg(uma_zone_t zone, void *item, void *arg);
325
326 /*
327  * Frees an item back to a zone without supplying an argument
328  *
329  * This is just a wrapper for uma_zfree_arg for convenience.
330  *
331  */
332 static __inline void uma_zfree(uma_zone_t zone, void *item);
333
334 static __inline void
335 uma_zfree(uma_zone_t zone, void *item)
336 {
337         uma_zfree_arg(zone, item, NULL);
338 }
339
340 /*
341  * XXX The rest of the prototypes in this header are h0h0 magic for the VM.
342  * If you think you need to use it for a normal zone you're probably incorrect.
343  */
344
345 /*
346  * Backend page supplier routines
347  *
348  * Arguments:
349  *      zone  The zone that is requesting pages.
350  *      size  The number of bytes being requested.
351  *      pflag Flags for these memory pages, see below.
352  *      wait  Indicates our willingness to block.
353  *
354  * Returns:
355  *      A pointer to the allocated memory or NULL on failure.
356  */
357
358 typedef void *(*uma_alloc)(uma_zone_t zone, int size, u_int8_t *pflag, int wait);
359
360 /*
361  * Backend page free routines
362  *
363  * Arguments:
364  *      item  A pointer to the previously allocated pages.
365  *      size  The original size of the allocation.
366  *      pflag The flags for the slab.  See UMA_SLAB_* below.
367  *
368  * Returns:
369  *      None
370  */
371 typedef void (*uma_free)(void *item, int size, u_int8_t pflag);
372
373
374
375 /*
376  * Sets up the uma allocator. (Called by vm_mem_init)
377  *
378  * Arguments:
379  *      bootmem  A pointer to memory used to bootstrap the system.
380  *
381  * Returns:
382  *      Nothing
383  *
384  * Discussion:
385  *      This memory is used for zones which allocate things before the
386  *      backend page supplier can give us pages.  It should be
387  *      UMA_SLAB_SIZE * boot_pages bytes. (see uma_int.h)
388  *
389  */
390
391 void uma_startup(void *bootmem, int boot_pages);
392
393 /*
394  * Finishes starting up the allocator.  This should
395  * be called when kva is ready for normal allocs.
396  *
397  * Arguments:
398  *      None
399  *
400  * Returns:
401  *      Nothing
402  *
403  * Discussion:
404  *      uma_startup2 is called by kmeminit() to enable us of uma for malloc.
405  */
406  
407 void uma_startup2(void);
408
409 /*
410  * Reclaims unused memory for all zones
411  *
412  * Arguments:
413  *      None
414  * Returns:
415  *      None
416  *
417  * This should only be called by the page out daemon.
418  */
419
420 void uma_reclaim(void);
421
422 /*
423  * Sets the alignment mask to be used for all zones requesting cache
424  * alignment.  Should be called by MD boot code prior to starting VM/UMA.
425  *
426  * Arguments:
427  *      align The alignment mask
428  *
429  * Returns:
430  *      Nothing
431  */
432 void uma_set_align(int align);
433
434 /*
435  * Switches the backing object of a zone
436  *
437  * Arguments:
438  *      zone  The zone to update.
439  *      obj   The VM object to use for future allocations.
440  *      size  The size of the object to allocate.
441  *
442  * Returns:
443  *      0  if kva space can not be allocated
444  *      1  if successful
445  *
446  * Discussion:
447  *      A NULL object can be used and uma will allocate one for you.  Setting
448  *      the size will limit the amount of memory allocated to this zone.
449  *
450  */
451 struct vm_object;
452 int uma_zone_set_obj(uma_zone_t zone, struct vm_object *obj, int size);
453
454 /*
455  * Sets a high limit on the number of items allowed in a zone
456  *
457  * Arguments:
458  *      zone  The zone to limit
459  *      nitems  The requested upper limit on the number of items allowed
460  *
461  * Returns:
462  *      int  The effective value of nitems after rounding up based on page size
463  */
464 int uma_zone_set_max(uma_zone_t zone, int nitems);
465
466 /*
467  * Obtains the effective limit on the number of items in a zone
468  *
469  * Arguments:
470  *      zone  The zone to obtain the effective limit from
471  *
472  * Return:
473  *      0  No limit
474  *      int  The effective limit of the zone
475  */
476 int uma_zone_get_max(uma_zone_t zone);
477
478 /*
479  * Obtains the approximate current number of items allocated from a zone
480  *
481  * Arguments:
482  *      zone  The zone to obtain the current allocation count from
483  *
484  * Return:
485  *      int  The approximate current number of items allocated from the zone
486  */
487 int uma_zone_get_cur(uma_zone_t zone);
488
489 /*
490  * The following two routines (uma_zone_set_init/fini)
491  * are used to set the backend init/fini pair which acts on an
492  * object as it becomes allocated and is placed in a slab within
493  * the specified zone's backing keg.  These should probably not
494  * be changed once allocations have already begun, but only be set
495  * immediately upon zone creation.
496  */
497 void uma_zone_set_init(uma_zone_t zone, uma_init uminit);
498 void uma_zone_set_fini(uma_zone_t zone, uma_fini fini);
499
500 /*
501  * The following two routines (uma_zone_set_zinit/zfini) are
502  * used to set the zinit/zfini pair which acts on an object as
503  * it passes from the backing Keg's slab cache to the
504  * specified Zone's bucket cache.  These should probably not
505  * be changed once allocations have already begun, but only be set
506  * immediately upon zone creation.
507  */
508 void uma_zone_set_zinit(uma_zone_t zone, uma_init zinit);
509 void uma_zone_set_zfini(uma_zone_t zone, uma_fini zfini);
510
511 /*
512  * Replaces the standard page_alloc or obj_alloc functions for this zone
513  *
514  * Arguments:
515  *      zone   The zone whose backend allocator is being changed.
516  *      allocf A pointer to the allocation function
517  *
518  * Returns:
519  *      Nothing
520  *
521  * Discussion:
522  *      This could be used to implement pageable allocation, or perhaps
523  *      even DMA allocators if used in conjunction with the OFFPAGE
524  *      zone flag.
525  */
526
527 void uma_zone_set_allocf(uma_zone_t zone, uma_alloc allocf);
528
529 /*
530  * Used for freeing memory provided by the allocf above
531  *
532  * Arguments:
533  *      zone  The zone that intends to use this free routine.
534  *      freef The page freeing routine.
535  *
536  * Returns:
537  *      Nothing
538  */
539
540 void uma_zone_set_freef(uma_zone_t zone, uma_free freef);
541
542 /*
543  * These flags are setable in the allocf and visible in the freef.
544  */
545 #define UMA_SLAB_BOOT   0x01            /* Slab alloced from boot pages */
546 #define UMA_SLAB_KMEM   0x02            /* Slab alloced from kmem_map */
547 #define UMA_SLAB_KERNEL 0x04            /* Slab alloced from kernel_map */
548 #define UMA_SLAB_PRIV   0x08            /* Slab alloced from priv allocator */
549 #define UMA_SLAB_OFFP   0x10            /* Slab is managed separately  */
550 #define UMA_SLAB_MALLOC 0x20            /* Slab is a large malloc slab */
551 /* 0x40 and 0x80 are available */
552
553 /*
554  * Used to pre-fill a zone with some number of items
555  *
556  * Arguments:
557  *      zone    The zone to fill
558  *      itemcnt The number of items to reserve
559  *
560  * Returns:
561  *      Nothing
562  *
563  * NOTE: This is blocking and should only be done at startup
564  */
565 void uma_prealloc(uma_zone_t zone, int itemcnt);
566
567 /*
568  * Used to lookup the reference counter allocated for an item
569  * from a UMA_ZONE_REFCNT zone.  For UMA_ZONE_REFCNT zones,
570  * reference counters are allocated for items and stored in
571  * the underlying slab header.
572  *
573  * Arguments:
574  *      zone  The UMA_ZONE_REFCNT zone to which the item belongs.
575  *      item  The address of the item for which we want a refcnt.
576  *
577  * Returns:
578  *      A pointer to a u_int32_t reference counter.
579  */
580 u_int32_t *uma_find_refcnt(uma_zone_t zone, void *item);
581
582 /*
583  * Used to determine if a fixed-size zone is exhausted.
584  *
585  * Arguments:
586  *      zone    The zone to check
587  *
588  * Returns:
589  *      Non-zero if zone is exhausted.
590  */
591 int uma_zone_exhausted(uma_zone_t zone);
592 int uma_zone_exhausted_nolock(uma_zone_t zone);
593
594 /*
595  * Exported statistics structures to be used by user space monitoring tools.
596  * Statistics stream consists of a uma_stream_header, followed by a series of
597  * alternative uma_type_header and uma_type_stat structures.
598  */
599 #define UMA_STREAM_VERSION      0x00000001
600 struct uma_stream_header {
601         u_int32_t       ush_version;    /* Stream format version. */
602         u_int32_t       ush_maxcpus;    /* Value of MAXCPU for stream. */
603         u_int32_t       ush_count;      /* Number of records. */
604         u_int32_t       _ush_pad;       /* Pad/reserved field. */
605 };
606
607 #define UTH_MAX_NAME    32
608 #define UTH_ZONE_SECONDARY      0x00000001
609 struct uma_type_header {
610         /*
611          * Static per-zone data, some extracted from the supporting keg.
612          */
613         char            uth_name[UTH_MAX_NAME];
614         u_int32_t       uth_align;      /* Keg: alignment. */
615         u_int32_t       uth_size;       /* Keg: requested size of item. */
616         u_int32_t       uth_rsize;      /* Keg: real size of item. */
617         u_int32_t       uth_maxpages;   /* Keg: maximum number of pages. */
618         u_int32_t       uth_limit;      /* Keg: max items to allocate. */
619
620         /*
621          * Current dynamic zone/keg-derived statistics.
622          */
623         u_int32_t       uth_pages;      /* Keg: pages allocated. */
624         u_int32_t       uth_keg_free;   /* Keg: items free. */
625         u_int32_t       uth_zone_free;  /* Zone: items free. */
626         u_int32_t       uth_bucketsize; /* Zone: desired bucket size. */
627         u_int32_t       uth_zone_flags; /* Zone: flags. */
628         u_int64_t       uth_allocs;     /* Zone: number of allocations. */
629         u_int64_t       uth_frees;      /* Zone: number of frees. */
630         u_int64_t       uth_fails;      /* Zone: number of alloc failures. */
631         u_int64_t       uth_sleeps;     /* Zone: number of alloc sleeps. */
632         u_int64_t       _uth_reserved1[2];      /* Reserved. */
633 };
634
635 struct uma_percpu_stat {
636         u_int64_t       ups_allocs;     /* Cache: number of allocations. */
637         u_int64_t       ups_frees;      /* Cache: number of frees. */
638         u_int64_t       ups_cache_free; /* Cache: free items in cache. */
639         u_int64_t       _ups_reserved[5];       /* Reserved. */
640 };
641
642 #endif