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 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