The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/vm/uma.h

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

    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: releng/6.0/sys/vm/uma.h 148476 2005-07-28 12:10:19Z rwatson $
   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 visable 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 /* 
   52  * Item constructor
   53  *
   54  * Arguments:
   55  *      item  A pointer to the memory which has been allocated.
   56  *      arg   The arg field passed to uma_zalloc_arg
   57  *      size  The size of the allocated item
   58  *      flags See zalloc flags
   59  * 
   60  * Returns:
   61  *      0      on success
   62  *      errno  on failure
   63  *
   64  * Discussion:
   65  *      The constructor is called just before the memory is returned
   66  *      to the user. It may block if necessary.
   67  */
   68 typedef int (*uma_ctor)(void *mem, int size, void *arg, int flags);
   69 
   70 /*
   71  * Item destructor
   72  *
   73  * Arguments:
   74  *      item  A pointer to the memory which has been allocated.
   75  *      size  The size of the item being destructed.
   76  *      arg   Argument passed through uma_zfree_arg
   77  * 
   78  * Returns:
   79  *      Nothing
   80  *
   81  * Discussion:
   82  *      The destructor may perform operations that differ from those performed
   83  *      by the initializer, but it must leave the object in the same state.
   84  *      This IS type stable storage.  This is called after EVERY zfree call.
   85  */
   86 typedef void (*uma_dtor)(void *mem, int size, void *arg);
   87 
   88 /* 
   89  * Item initializer
   90  *
   91  * Arguments:
   92  *      item  A pointer to the memory which has been allocated.
   93  *      size  The size of the item being initialized.
   94  *      flags See zalloc flags
   95  * 
   96  * Returns:
   97  *      0      on success
   98  *      errno  on failure
   99  *
  100  * Discussion:
  101  *      The initializer is called when the memory is cached in the uma zone. 
  102  *      this should be the same state that the destructor leaves the object in.
  103  */
  104 typedef int (*uma_init)(void *mem, int size, int flags);
  105 
  106 /*
  107  * Item discard function
  108  *
  109  * Arguments:
  110  *      item  A pointer to memory which has been 'freed' but has not left the 
  111  *            zone's cache.
  112  *      size  The size of the item being discarded.
  113  *
  114  * Returns:
  115  *      Nothing
  116  *
  117  * Discussion:
  118  *      This routine is called when memory leaves a zone and is returned to the
  119  *      system for other uses.  It is the counter part to the init function.
  120  */
  121 typedef void (*uma_fini)(void *mem, int size);
  122 
  123 /*
  124  * What's the difference between initializing and constructing?
  125  *
  126  * The item is initialized when it is cached, and this is the state that the 
  127  * object should be in when returned to the allocator. The purpose of this is
  128  * to remove some code which would otherwise be called on each allocation by
  129  * utilizing a known, stable state.  This differs from the constructor which
  130  * will be called on EVERY allocation.
  131  *
  132  * For example, in the initializer you may want to initialize embeded locks,
  133  * NULL list pointers, set up initial states, magic numbers, etc.  This way if
  134  * the object is held in the allocator and re-used it won't be necessary to
  135  * re-initialize it.
  136  *
  137  * The constructor may be used to lock a data structure, link it on to lists,
  138  * bump reference counts or total counts of outstanding structures, etc.
  139  *
  140  */
  141 
  142 
  143 /* Function proto types */
  144 
  145 /*
  146  * Create a new uma zone
  147  *
  148  * Arguments:
  149  *      name  The text name of the zone for debugging and stats, this memory
  150  *              should not be freed until the zone has been deallocated.
  151  *      size  The size of the object that is being created.
  152  *      ctor  The constructor that is called when the object is allocated
  153  *      dtor  The destructor that is called when the object is freed.
  154  *      init  An initializer that sets up the initial state of the memory.
  155  *      fini  A discard function that undoes initialization done by init.
  156  *              ctor/dtor/init/fini may all be null, see notes above.
  157  *      align A bitmask that corisponds to the requested alignment
  158  *              eg 4 would be 0x3
  159  *      flags A set of parameters that control the behavior of the zone
  160  *
  161  * Returns:
  162  *      A pointer to a structure which is intended to be opaque to users of
  163  *      the interface.  The value may be null if the wait flag is not set.
  164  */
  165 uma_zone_t uma_zcreate(char *name, size_t size, uma_ctor ctor, uma_dtor dtor,
  166                         uma_init uminit, uma_fini fini, int align,
  167                         u_int32_t flags);
  168 
  169 /*
  170  * Create a secondary uma zone
  171  *
  172  * Arguments:
  173  *      name  The text name of the zone for debugging and stats, this memory
  174  *              should not be freed until the zone has been deallocated.
  175  *      ctor  The constructor that is called when the object is allocated
  176  *      dtor  The destructor that is called when the object is freed.
  177  *      zinit  An initializer that sets up the initial state of the memory
  178  *              as the object passes from the Keg's slab to the Zone's cache.
  179  *      zfini  A discard function that undoes initialization done by init
  180  *              as the object passes from the Zone's cache to the Keg's slab.
  181  *
  182  *              ctor/dtor/zinit/zfini may all be null, see notes above.
  183  *              Note that the zinit and zfini specified here are NOT
  184  *              exactly the same as the init/fini specified to uma_zcreate()
  185  *              when creating a master zone.  These zinit/zfini are called
  186  *              on the TRANSITION from keg to zone (and vice-versa). Once
  187  *              these are set, the primary zone may alter its init/fini
  188  *              (which are called when the object passes from VM to keg)
  189  *              using uma_zone_set_init/fini()) as well as its own
  190  *              zinit/zfini (unset by default for master zone) with
  191  *              uma_zone_set_zinit/zfini() (note subtle 'z' prefix).
  192  *
  193  *      master  A reference to this zone's Master Zone (Primary Zone),
  194  *              which contains the backing Keg for the Secondary Zone
  195  *              being added.
  196  *
  197  * Returns:
  198  *      A pointer to a structure which is intended to be opaque to users of
  199  *      the interface.  The value may be null if the wait flag is not set.
  200  */
  201 uma_zone_t uma_zsecond_create(char *name, uma_ctor ctor, uma_dtor dtor,
  202                     uma_init zinit, uma_fini zfini, uma_zone_t master);
  203 
  204 /*
  205  * Definitions for uma_zcreate flags
  206  *
  207  * These flags share space with UMA_ZFLAGs in uma_int.h.  Be careful not to
  208  * overlap when adding new features.  0xf0000000 is in use by uma_int.h.
  209  */
  210 #define UMA_ZONE_PAGEABLE       0x0001  /* Return items not fully backed by
  211                                            physical memory XXX Not yet */
  212 #define UMA_ZONE_ZINIT          0x0002  /* Initialize with zeros */
  213 #define UMA_ZONE_STATIC         0x0004  /* Staticly sized zone */
  214 #define UMA_ZONE_OFFPAGE        0x0008  /* Force the slab structure allocation
  215                                            off of the real memory */
  216 #define UMA_ZONE_MALLOC         0x0010  /* For use by malloc(9) only! */
  217 #define UMA_ZONE_NOFREE         0x0020  /* Do not free slabs of this type! */
  218 #define UMA_ZONE_MTXCLASS       0x0040  /* Create a new lock class */
  219 #define UMA_ZONE_VM             0x0080  /*
  220                                          * Used for internal vm datastructures
  221                                          * only.
  222                                          */
  223 #define UMA_ZONE_HASH           0x0100  /*
  224                                          * Use a hash table instead of caching
  225                                          * information in the vm_page.
  226                                          */
  227 #define UMA_ZONE_SECONDARY      0x0200  /* Zone is a Secondary Zone */
  228 #define UMA_ZONE_REFCNT         0x0400  /* Allocate refcnts in slabs */
  229 #define UMA_ZONE_MAXBUCKET      0x0800  /* Use largest buckets */
  230 
  231 /* Definitions for align */
  232 #define UMA_ALIGN_PTR   (sizeof(void *) - 1)    /* Alignment fit for ptr */
  233 #define UMA_ALIGN_LONG  (sizeof(long) - 1)      /* "" long */
  234 #define UMA_ALIGN_INT   (sizeof(int) - 1)       /* "" int */
  235 #define UMA_ALIGN_SHORT (sizeof(short) - 1)     /* "" short */
  236 #define UMA_ALIGN_CHAR  (sizeof(char) - 1)      /* "" char */
  237 #define UMA_ALIGN_CACHE (16 - 1)                /* Cache line size align */
  238 
  239 /*
  240  * Destroys an empty uma zone.  If the zone is not empty uma complains loudly.
  241  *
  242  * Arguments:
  243  *      zone  The zone we want to destroy.
  244  *
  245  */
  246 void uma_zdestroy(uma_zone_t zone);
  247 
  248 /*
  249  * Allocates an item out of a zone
  250  *
  251  * Arguments:
  252  *      zone  The zone we are allocating from
  253  *      arg   This data is passed to the ctor function
  254  *      flags See sys/malloc.h for available flags.
  255  *
  256  * Returns:
  257  *      A non null pointer to an initialized element from the zone is
  258  *      garanteed if the wait flag is M_WAITOK, otherwise a null pointer may be
  259  *      returned if the zone is empty or the ctor failed.
  260  */
  261 
  262 void *uma_zalloc_arg(uma_zone_t zone, void *arg, int flags);
  263 
  264 /*
  265  * Allocates an item out of a zone without supplying an argument
  266  *
  267  * This is just a wrapper for uma_zalloc_arg for convenience.
  268  *
  269  */
  270 static __inline void *uma_zalloc(uma_zone_t zone, int flags);
  271 
  272 static __inline void *
  273 uma_zalloc(uma_zone_t zone, int flags)
  274 {
  275         return uma_zalloc_arg(zone, NULL, flags);
  276 }
  277 
  278 /*
  279  * Frees an item back into the specified zone.
  280  *
  281  * Arguments:
  282  *      zone  The zone the item was originally allocated out of.
  283  *      item  The memory to be freed.
  284  *      arg   Argument passed to the destructor
  285  *
  286  * Returns:
  287  *      Nothing.
  288  */
  289 
  290 void uma_zfree_arg(uma_zone_t zone, void *item, void *arg);
  291 
  292 /*
  293  * Frees an item back to a zone without supplying an argument
  294  *
  295  * This is just a wrapper for uma_zfree_arg for convenience.
  296  *
  297  */
  298 static __inline void uma_zfree(uma_zone_t zone, void *item);
  299 
  300 static __inline void
  301 uma_zfree(uma_zone_t zone, void *item)
  302 {
  303         uma_zfree_arg(zone, item, NULL);
  304 }
  305 
  306 /*
  307  * XXX The rest of the prototypes in this header are h0h0 magic for the VM.
  308  * If you think you need to use it for a normal zone you're probably incorrect.
  309  */
  310 
  311 /*
  312  * Backend page supplier routines
  313  *
  314  * Arguments:
  315  *      zone  The zone that is requesting pages
  316  *      size  The number of bytes being requested
  317  *      pflag Flags for these memory pages, see below.
  318  *      wait  Indicates our willingness to block.
  319  *
  320  * Returns:
  321  *      A pointer to the alloced memory or NULL on failure.
  322  */
  323 
  324 typedef void *(*uma_alloc)(uma_zone_t zone, int size, u_int8_t *pflag, int wait);
  325 
  326 /*
  327  * Backend page free routines
  328  *
  329  * Arguments:
  330  *      item  A pointer to the previously allocated pages
  331  *      size  The original size of the allocation
  332  *      pflag The flags for the slab.  See UMA_SLAB_* below
  333  *
  334  * Returns:
  335  *      None
  336  */
  337 typedef void (*uma_free)(void *item, int size, u_int8_t pflag);
  338 
  339 
  340 
  341 /*
  342  * Sets up the uma allocator. (Called by vm_mem_init)
  343  *
  344  * Arguments:
  345  *      bootmem  A pointer to memory used to bootstrap the system.
  346  *
  347  * Returns:
  348  *      Nothing
  349  *
  350  * Discussion:
  351  *      This memory is used for zones which allocate things before the
  352  *      backend page supplier can give us pages.  It should be
  353  *      UMA_SLAB_SIZE * UMA_BOOT_PAGES bytes. (see uma_int.h)
  354  *
  355  */
  356 
  357 void uma_startup(void *bootmem);
  358 
  359 /*
  360  * Finishes starting up the allocator.  This should
  361  * be called when kva is ready for normal allocs.
  362  *
  363  * Arguments:
  364  *      None
  365  *
  366  * Returns:
  367  *      Nothing
  368  *
  369  * Discussion:
  370  *      uma_startup2 is called by kmeminit() to enable us of uma for malloc.
  371  */
  372  
  373 void uma_startup2(void);
  374 
  375 /*
  376  * Reclaims unused memory for all zones
  377  *
  378  * Arguments:
  379  *      None
  380  * Returns:
  381  *      None
  382  *
  383  * This should only be called by the page out daemon.
  384  */
  385 
  386 void uma_reclaim(void);
  387 
  388 /*
  389  * Switches the backing object of a zone
  390  *
  391  * Arguments:
  392  *      zone  The zone to update
  393  *      obj   The obj to use for future allocations
  394  *      size  The size of the object to allocate
  395  *
  396  * Returns:
  397  *      0  if kva space can not be allocated
  398  *      1  if successful
  399  *
  400  * Discussion:
  401  *      A NULL object can be used and uma will allocate one for you.  Setting
  402  *      the size will limit the amount of memory allocated to this zone.
  403  *
  404  */
  405 struct vm_object;
  406 int uma_zone_set_obj(uma_zone_t zone, struct vm_object *obj, int size);
  407 
  408 /*
  409  * Sets a high limit on the number of items allowed in a zone
  410  *
  411  * Arguments:
  412  *      zone  The zone to limit
  413  *
  414  * Returns:
  415  *      Nothing
  416  */
  417 void uma_zone_set_max(uma_zone_t zone, int nitems);
  418 
  419 /*
  420  * The following two routines (uma_zone_set_init/fini)
  421  * are used to set the backend init/fini pair which acts on an
  422  * object as it becomes allocated and is placed in a slab within
  423  * the specified zone's backing keg.  These should probably not
  424  * be changed once allocations have already begun and only
  425  * immediately upon zone creation.
  426  */
  427 void uma_zone_set_init(uma_zone_t zone, uma_init uminit);
  428 void uma_zone_set_fini(uma_zone_t zone, uma_fini fini);
  429 
  430 /*
  431  * The following two routines (uma_zone_set_zinit/zfini) are
  432  * used to set the zinit/zfini pair which acts on an object as
  433  * it passes from the backing Keg's slab cache to the
  434  * specified Zone's bucket cache.  These should probably not
  435  * be changed once allocations have already begun and
  436  * only immediately upon zone creation.
  437  */
  438 void uma_zone_set_zinit(uma_zone_t zone, uma_init zinit);
  439 void uma_zone_set_zfini(uma_zone_t zone, uma_fini zfini);
  440 
  441 /*
  442  * Replaces the standard page_alloc or obj_alloc functions for this zone
  443  *
  444  * Arguments:
  445  *      zone   The zone whos back end allocator is being changed.
  446  *      allocf A pointer to the allocation function
  447  *
  448  * Returns:
  449  *      Nothing
  450  *
  451  * Discussion:
  452  *      This could be used to implement pageable allocation, or perhaps
  453  *      even DMA allocators if used in conjunction with the OFFPAGE
  454  *      zone flag.
  455  */
  456 
  457 void uma_zone_set_allocf(uma_zone_t zone, uma_alloc allocf);
  458 
  459 /*
  460  * Used for freeing memory provided by the allocf above
  461  *
  462  * Arguments:
  463  *      zone  The zone that intends to use this free routine.
  464  *      freef The page freeing routine.
  465  *
  466  * Returns:
  467  *      Nothing
  468  */
  469 
  470 void uma_zone_set_freef(uma_zone_t zone, uma_free freef);
  471 
  472 /*
  473  * These flags are setable in the allocf and visable in the freef.
  474  */
  475 #define UMA_SLAB_BOOT   0x01            /* Slab alloced from boot pages */
  476 #define UMA_SLAB_KMEM   0x02            /* Slab alloced from kmem_map */
  477 #define UMA_SLAB_PRIV   0x08            /* Slab alloced from priv allocator */
  478 #define UMA_SLAB_OFFP   0x10            /* Slab is managed separately  */
  479 #define UMA_SLAB_MALLOC 0x20            /* Slab is a large malloc slab */
  480 /* 0x40 and 0x80 are available */
  481 
  482 /*
  483  * Used to pre-fill a zone with some number of items
  484  *
  485  * Arguments:
  486  *      zone    The zone to fill
  487  *      itemcnt The number of items to reserve
  488  *
  489  * Returns:
  490  *      Nothing
  491  *
  492  * NOTE: This is blocking and should only be done at startup
  493  */
  494 void uma_prealloc(uma_zone_t zone, int itemcnt);
  495 
  496 /*
  497  * Used to lookup the reference counter allocated for an item
  498  * from a UMA_ZONE_REFCNT zone.  For UMA_ZONE_REFCNT zones,
  499  * reference counters are allocated for items and stored in
  500  * the underlying slab header.
  501  *
  502  * Arguments:
  503  *      zone  The UMA_ZONE_REFCNT zone to which the item belongs.
  504  *      item  The address of the item for which we want a refcnt.
  505  *
  506  * Returns:
  507  *      A pointer to a u_int32_t reference counter.
  508  */
  509 u_int32_t *uma_find_refcnt(uma_zone_t zone, void *item);
  510 
  511 /*
  512  * Exported statistics structures to be used by user space monitoring tools.
  513  * Statistics stream consusts of a uma_stream_header, followed by a series of
  514  * alternative uma_type_header and uma_type_stat structures.  Statistics
  515  * structures
  516  */
  517 #define UMA_STREAM_VERSION      0x00000001
  518 struct uma_stream_header {
  519         u_int32_t       ush_version;    /* Stream format version. */
  520         u_int32_t       ush_maxcpus;    /* Value of MAXCPU for stream. */
  521         u_int32_t       ush_count;      /* Number of records. */
  522         u_int32_t       _ush_pad;       /* Pad/reserved field. */
  523 };
  524 
  525 #define UTH_MAX_NAME    32
  526 #define UTH_ZONE_SECONDARY      0x00000001
  527 struct uma_type_header {
  528         /*
  529          * Static per-zone data, some extracted from the supporting keg.
  530          */
  531         char            uth_name[UTH_MAX_NAME];
  532         u_int32_t       uth_align;      /* Keg: alignment. */
  533         u_int32_t       uth_size;       /* Keg: requested size of item. */
  534         u_int32_t       uth_rsize;      /* Keg: real size of item. */
  535         u_int32_t       uth_maxpages;   /* Keg: maximum number of pages. */
  536         u_int32_t       uth_limit;      /* Keg: max items to allocate. */
  537 
  538         /*
  539          * Current dynamic zone/keg-derived statistics.
  540          */
  541         u_int32_t       uth_pages;      /* Keg: pages allocated. */
  542         u_int32_t       uth_keg_free;   /* Keg: items free. */
  543         u_int32_t       uth_zone_free;  /* Zone: items free. */
  544         u_int32_t       uth_bucketsize; /* Zone: desired bucket size. */
  545         u_int32_t       uth_zone_flags; /* Zone: flags. */
  546         u_int64_t       uth_allocs;     /* Zone: number of allocations. */
  547         u_int64_t       uth_frees;      /* Zone: number of frees. */
  548         u_int64_t       uth_fails;      /* Zone: number of alloc failures. */
  549         u_int64_t       _uth_reserved1[3];      /* Reserved. */
  550 };
  551 
  552 struct uma_percpu_stat {
  553         u_int64_t       ups_allocs;     /* Cache: number of alloctions. */
  554         u_int64_t       ups_frees;      /* Cache: number of frees. */
  555         u_int64_t       ups_cache_free; /* Cache: free items in cache. */
  556         u_int64_t       _ups_reserved[5];       /* Reserved. */
  557 };
  558 
  559 #endif

Cache object: 67f1d90083843e8b03bc80745bec7fb7


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.