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