sys/vm/uma.h

   1 /*-
   2  * Copyright (c) 2004, 2005,
   3  *     Bosko Milekic <bmilekic@FreeBSD.org>.  All rights reserved.
   4  * Copyright (c) 2002, 2003, 2004, 2005,
   5  *     Jeffrey Roberson <jeff@FreeBSD.org>.  All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  * 1. Redistributions of source code must retain the above copyright
  11  *    notice unmodified, this list of conditions, and the following
  12  *    disclaimer.
  13  * 2. Redistributions in binary form must reproduce the above copyright
  14  *    notice, this list of conditions and the following disclaimer in the
  15  *    documentation and/or other materials provided with the distribution.
  16  *
  17  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  18  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  21  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27  *
  28  * $FreeBSD$
  29  *
  30  */
  31
  32 /*
  33  * uma.h - External definitions for the Universal Memory Allocator
  34  *
  35 */
  36
  37 #ifndef VM_UMA_H
  38 #define VM_UMA_H
  39
  40 #include <sys/param.h>          /* For NULL */
  41 #include <sys/malloc.h>         /* For M_* */
  42
  43 /* User visable parameters */
  44 #define UMA_SMALLEST_UNIT       (PAGE_SIZE / 256) /* Smallest item allocated */
  45
  46 /* Types and type defs */
  47
  48 struct uma_zone;
  49 /* Opaque type used as a handle to the zone */
  50 typedef struct uma_zone * uma_zone_t;
  51
  52 /*
  53  * Item constructor
  54  *
  55  * Arguments:
  56  *      item  A pointer to the memory which has been allocated.
  57  *      arg   The arg field passed to uma_zalloc_arg
  58  *      size  The size of the allocated item
  59  *      flags See zalloc flags
  60  *
  61  * Returns:
  62  *      0      on success
  63  *      errno  on failure
  64  *
  65  * Discussion:
  66  *      The constructor is called just before the memory is returned
  67  *      to the user. It may block if necessary.
  68  */
  69 typedef int (*uma_ctor)(void *mem, int size, void *arg, int flags);
  70
  71 /*
  72  * Item destructor
  73  *
  74  * Arguments:
  75  *      item  A pointer to the memory which has been allocated.
  76  *      size  The size of the item being destructed.
  77  *      arg   Argument passed through uma_zfree_arg
  78  *
  79  * Returns:
  80  *      Nothing
  81  *
  82  * Discussion:
  83  *      The destructor may perform operations that differ from those performed
  84  *      by the initializer, but it must leave the object in the same state.
  85  *      This IS type stable storage.  This is called after EVERY zfree call.
  86  */
  87 typedef void (*uma_dtor)(void *mem, int size, void *arg);
  88
  89 /*
  90  * Item initializer
  91  *
  92  * Arguments:
  93  *      item  A pointer to the memory which has been allocated.
  94  *      size  The size of the item being initialized.
  95  *      flags See zalloc flags
  96  *
  97  * Returns:
  98  *      0      on success
  99  *      errno  on failure
 100  *
 101  * Discussion:
 102  *      The initializer is called when the memory is cached in the uma zone.
 103  *      this should be the same state that the destructor leaves the object in.
 104  */
 105 typedef int (*uma_init)(void *mem, int size, int flags);
 106
 107 /*
 108  * Item discard function
 109  *
 110  * Arguments:
 111  *      item  A pointer to memory which has been 'freed' but has not left the
 112  *            zone's cache.
 113  *      size  The size of the item being discarded.
 114  *
 115  * Returns:
 116  *      Nothing
 117  *
 118  * Discussion:
 119  *      This routine is called when memory leaves a zone and is returned to the
 120  *      system for other uses.  It is the counter part to the init function.
 121  */
 122 typedef void (*uma_fini)(void *mem, int size);
 123
 124 /*
 125  * What's the difference between initializing and constructing?
 126  *
 127  * The item is initialized when it is cached, and this is the state that the
 128  * object should be in when returned to the allocator. The purpose of this is
 129  * to remove some code which would otherwise be called on each allocation by
 130  * utilizing a known, stable state.  This differs from the constructor which
 131  * will be called on EVERY allocation.
 132  *
 133  * For example, in the initializer you may want to initialize embeded locks,
 134  * NULL list pointers, set up initial states, magic numbers, etc.  This way if
 135  * the object is held in the allocator and re-used it won't be necessary to
 136  * re-initialize it.
 137  *
 138  * The constructor may be used to lock a data structure, link it on to lists,
 139  * bump reference counts or total counts of outstanding structures, etc.
 140  *
 141  */
 142
 143
 144 /* Function proto types */
 145
 146 /*
 147  * Create a new uma zone
 148  *
 149  * Arguments:
 150  *      name  The text name of the zone for debugging and stats, this memory
 151  *              should not be freed until the zone has been deallocated.
 152  *      size  The size of the object that is being created.
 153  *      ctor  The constructor that is called when the object is allocated
 154  *      dtor  The destructor that is called when the object is freed.
 155  *      init  An initializer that sets up the initial state of the memory.
 156  *      fini  A discard function that undoes initialization done by init.
 157  *              ctor/dtor/init/fini may all be null, see notes above.
 158  *      align A bitmask that corisponds to the requested alignment
 159  *              eg 4 would be 0x3
 160  *      flags A set of parameters that control the behavior of the zone
 161  *
 162  * Returns:
 163  *      A pointer to a structure which is intended to be opaque to users of
 164  *      the interface.  The value may be null if the wait flag is not set.
 165  */
 166 uma_zone_t uma_zcreate(char *name, size_t size, uma_ctor ctor, uma_dtor dtor,
 167                         uma_init uminit, uma_fini fini, int align,
 168                         u_int16_t flags);
 169
 170 /*
 171  * Create a secondary uma zone
 172  *
 173  * Arguments:
 174  *      name  The text name of the zone for debugging and stats, this memory
 175  *              should not be freed until the zone has been deallocated.
 176  *      ctor  The constructor that is called when the object is allocated
 177  *      dtor  The destructor that is called when the object is freed.
 178  *      zinit  An initializer that sets up the initial state of the memory
 179  *              as the object passes from the Keg's slab to the Zone's cache.
 180  *      zfini  A discard function that undoes initialization done by init
 181  *              as the object passes from the Zone's cache to the Keg's slab.
 182  *
 183  *              ctor/dtor/zinit/zfini may all be null, see notes above.
 184  *              Note that the zinit and zfini specified here are NOT
 185  *              exactly the same as the init/fini specified to uma_zcreate()
 186  *              when creating a master zone.  These zinit/zfini are called
 187  *              on the TRANSITION from keg to zone (and vice-versa). Once
 188  *              these are set, the primary zone may alter its init/fini
 189  *              (which are called when the object passes from VM to keg)
 190  *              using uma_zone_set_init/fini()) as well as its own
 191  *              zinit/zfini (unset by default for master zone) with
 192  *              uma_zone_set_zinit/zfini() (note subtle 'z' prefix).
 193  *
 194  *      master  A reference to this zone's Master Zone (Primary Zone),
 195  *              which contains the backing Keg for the Secondary Zone
 196  *              being added.
 197  *
 198  * Returns:
 199  *      A pointer to a structure which is intended to be opaque to users of
 200  *      the interface.  The value may be null if the wait flag is not set.
 201  */
 202 uma_zone_t uma_zsecond_create(char *name, uma_ctor ctor, uma_dtor dtor,
 203                     uma_init zinit, uma_fini zfini, uma_zone_t master);
 204
 205 /*
 206  * Definitions for uma_zcreate flags
 207  *
 208  * These flags share space with UMA_ZFLAGs in uma_int.h.  Be careful not to
 209  * overlap when adding new features.  0xf000 is in use by uma_int.h.
 210  */
 211 #define UMA_ZONE_PAGEABLE       0x0001  /* Return items not fully backed by
 212                                            physical memory XXX Not yet */
 213 #define UMA_ZONE_ZINIT          0x0002  /* Initialize with zeros */
 214 #define UMA_ZONE_STATIC         0x0004  /* Staticly sized zone */
 215 #define UMA_ZONE_OFFPAGE        0x0008  /* Force the slab structure allocation
 216                                            off of the real memory */
 217 #define UMA_ZONE_MALLOC         0x0010  /* For use by malloc(9) only! */
 218 #define UMA_ZONE_NOFREE         0x0020  /* Do not free slabs of this type! */
 219 #define UMA_ZONE_MTXCLASS       0x0040  /* Create a new lock class */
 220 #define UMA_ZONE_VM             0x0080  /*
 221                                          * Used for internal vm datastructures
 222                                          * only.
 223                                          */
 224 #define UMA_ZONE_HASH           0x0100  /*
 225                                          * Use a hash table instead of caching
 226                                          * information in the vm_page.
 227                                          */
 228 #define UMA_ZONE_SECONDARY      0x0200  /* Zone is a Secondary Zone */
 229 #define UMA_ZONE_REFCNT         0x0400  /* Allocate refcnts in slabs */
 230 #define UMA_ZONE_MAXBUCKET      0x0800  /* Use largest buckets */
 231
 232 /* Definitions for align */
 233 #define UMA_ALIGN_PTR   (sizeof(void *) - 1)    /* Alignment fit for ptr */
 234 #define UMA_ALIGN_LONG  (sizeof(long) - 1)      /* "" long */
 235 #define UMA_ALIGN_INT   (sizeof(int) - 1)       /* "" int */
 236 #define UMA_ALIGN_SHORT (sizeof(short) - 1)     /* "" short */
 237 #define UMA_ALIGN_CHAR  (sizeof(char) - 1)      /* "" char */
 238 #define UMA_ALIGN_CACHE (16 - 1)                /* Cache line size align */
 239
 240 /*
 241  * Destroys an empty uma zone.  If the zone is not empty uma complains loudly.
 242  *
 243  * Arguments:
 244  *      zone  The zone we want to destroy.
 245  *
 246  */
 247 void uma_zdestroy(uma_zone_t zone);
 248
 249 /*
 250  * Allocates an item out of a zone
 251  *
 252  * Arguments:
 253  *      zone  The zone we are allocating from
 254  *      arg   This data is passed to the ctor function
 255  *      flags See sys/malloc.h for available flags.
 256  *
 257  * Returns:
 258  *      A non null pointer to an initialized element from the zone is
 259  *      garanteed if the wait flag is M_WAITOK, otherwise a null pointer may be
 260  *      returned if the zone is empty or the ctor failed.
 261  */
 262
 263 void *uma_zalloc_arg(uma_zone_t zone, void *arg, int flags);
 264
 265 /*
 266  * Allocates an item out of a zone without supplying an argument
 267  *
 268  * This is just a wrapper for uma_zalloc_arg for convenience.
 269  *
 270  */
 271 static __inline void *uma_zalloc(uma_zone_t zone, int flags);
 272
 273 static __inline void *
 274 uma_zalloc(uma_zone_t zone, int flags)
 275 {
 276         return uma_zalloc_arg(zone, NULL, flags);
 277 }
 278
 279 /*
 280  * Frees an item back into the specified zone.
 281  *
 282  * Arguments:
 283  *      zone  The zone the item was originally allocated out of.
 284  *      item  The memory to be freed.
 285  *      arg   Argument passed to the destructor
 286  *
 287  * Returns:
 288  *      Nothing.
 289  */
 290
 291 void uma_zfree_arg(uma_zone_t zone, void *item, void *arg);
 292
 293 /*
 294  * Frees an item back to a zone without supplying an argument
 295  *
 296  * This is just a wrapper for uma_zfree_arg for convenience.
 297  *
 298  */
 299 static __inline void uma_zfree(uma_zone_t zone, void *item);
 300
 301 static __inline void
 302 uma_zfree(uma_zone_t zone, void *item)
 303 {
 304         uma_zfree_arg(zone, item, NULL);
 305 }
 306
 307 /*
 308  * XXX The rest of the prototypes in this header are h0h0 magic for the VM.
 309  * If you think you need to use it for a normal zone you're probably incorrect.
 310  */
 311
 312 /*
 313  * Backend page supplier routines
 314  *
 315  * Arguments:
 316  *      zone  The zone that is requesting pages
 317  *      size  The number of bytes being requested
 318  *      pflag Flags for these memory pages, see below.
 319  *      wait  Indicates our willingness to block.
 320  *
 321  * Returns:
 322  *      A pointer to the alloced memory or NULL on failure.
 323  */
 324
 325 typedef void *(*uma_alloc)(uma_zone_t zone, int size, u_int8_t *pflag, int wait);
 326
 327 /*
 328  * Backend page free routines
 329  *
 330  * Arguments:
 331  *      item  A pointer to the previously allocated pages
 332  *      size  The original size of the allocation
 333  *      pflag The flags for the slab.  See UMA_SLAB_* below
 334  *
 335  * Returns:
 336  *      None
 337  */
 338 typedef void (*uma_free)(void *item, int size, u_int8_t pflag);
 339
 340
 341
 342 /*
 343  * Sets up the uma allocator. (Called by vm_mem_init)
 344  *
 345  * Arguments:
 346  *      bootmem  A pointer to memory used to bootstrap the system.
 347  *
 348  * Returns:
 349  *      Nothing
 350  *
 351  * Discussion:
 352  *      This memory is used for zones which allocate things before the
 353  *      backend page supplier can give us pages.  It should be
 354  *      UMA_SLAB_SIZE * UMA_BOOT_PAGES bytes. (see uma_int.h)
 355  *
 356  */
 357
 358 void uma_startup(void *bootmem);
 359
 360 /*
 361  * Finishes starting up the allocator.  This should
 362  * be called when kva is ready for normal allocs.
 363  *
 364  * Arguments:
 365  *      None
 366  *
 367  * Returns:
 368  *      Nothing
 369  *
 370  * Discussion:
 371  *      uma_startup2 is called by kmeminit() to enable us of uma for malloc.
 372  */
 373
 374 void uma_startup2(void);
 375
 376 /*
 377  * Reclaims unused memory for all zones
 378  *
 379  * Arguments:
 380  *      None
 381  * Returns:
 382  *      None
 383  *
 384  * This should only be called by the page out daemon.
 385  */
 386
 387 void uma_reclaim(void);
 388
 389 /*
 390  * Switches the backing object of a zone
 391  *
 392  * Arguments:
 393  *      zone  The zone to update
 394  *      obj   The obj to use for future allocations
 395  *      size  The size of the object to allocate
 396  *
 397  * Returns:
 398  *      0  if kva space can not be allocated
 399  *      1  if successful
 400  *
 401  * Discussion:
 402  *      A NULL object can be used and uma will allocate one for you.  Setting
 403  *      the size will limit the amount of memory allocated to this zone.
 404  *
 405  */
 406 struct vm_object;
 407 int uma_zone_set_obj(uma_zone_t zone, struct vm_object *obj, int size);
 408
 409 /*
 410  * Sets a high limit on the number of items allowed in a zone
 411  *
 412  * Arguments:
 413  *      zone  The zone to limit
 414  *
 415  * Returns:
 416  *      Nothing
 417  */
 418 void uma_zone_set_max(uma_zone_t zone, int nitems);
 419
 420 /*
 421  * The following two routines (uma_zone_set_init/fini)
 422  * are used to set the backend init/fini pair which acts on an
 423  * object as it becomes allocated and is placed in a slab within
 424  * the specified zone's backing keg.  These should probably not
 425  * be changed once allocations have already begun and only
 426  * immediately upon zone creation.
 427  */
 428 void uma_zone_set_init(uma_zone_t zone, uma_init uminit);
 429 void uma_zone_set_fini(uma_zone_t zone, uma_fini fini);
 430
 431 /*
 432  * The following two routines (uma_zone_set_zinit/zfini) are
 433  * used to set the zinit/zfini pair which acts on an object as
 434  * it passes from the backing Keg's slab cache to the
 435  * specified Zone's bucket cache.  These should probably not
 436  * be changed once allocations have already begun and
 437  * only immediately upon zone creation.
 438  */
 439 void uma_zone_set_zinit(uma_zone_t zone, uma_init zinit);
 440 void uma_zone_set_zfini(uma_zone_t zone, uma_fini zfini);
 441
 442 /*
 443  * Replaces the standard page_alloc or obj_alloc functions for this zone
 444  *
 445  * Arguments:
 446  *      zone   The zone whos back end allocator is being changed.
 447  *      allocf A pointer to the allocation function
 448  *
 449  * Returns:
 450  *      Nothing
 451  *
 452  * Discussion:
 453  *      This could be used to implement pageable allocation, or perhaps
 454  *      even DMA allocators if used in conjunction with the OFFPAGE
 455  *      zone flag.
 456  */
 457
 458 void uma_zone_set_allocf(uma_zone_t zone, uma_alloc allocf);
 459
 460 /*
 461  * Used for freeing memory provided by the allocf above
 462  *
 463  * Arguments:
 464  *      zone  The zone that intends to use this free routine.
 465  *      freef The page freeing routine.
 466  *
 467  * Returns:
 468  *      Nothing
 469  */
 470
 471 void uma_zone_set_freef(uma_zone_t zone, uma_free freef);
 472
 473 /*
 474  * These flags are setable in the allocf and visable in the freef.
 475  */
 476 #define UMA_SLAB_BOOT   0x01            /* Slab alloced from boot pages */
 477 #define UMA_SLAB_KMEM   0x02            /* Slab alloced from kmem_map */
 478 #define UMA_SLAB_PRIV   0x08            /* Slab alloced from priv allocator */
 479 #define UMA_SLAB_OFFP   0x10            /* Slab is managed separately  */
 480 #define UMA_SLAB_MALLOC 0x20            /* Slab is a large malloc slab */
 481 /* 0x40 and 0x80 are available */
 482
 483 /*
 484  * Used to pre-fill a zone with some number of items
 485  *
 486  * Arguments:
 487  *      zone    The zone to fill
 488  *      itemcnt The number of items to reserve
 489  *
 490  * Returns:
 491  *      Nothing
 492  *
 493  * NOTE: This is blocking and should only be done at startup
 494  */
 495 void uma_prealloc(uma_zone_t zone, int itemcnt);
 496
 497 /*
 498  * Used to lookup the reference counter allocated for an item
 499  * from a UMA_ZONE_REFCNT zone.  For UMA_ZONE_REFCNT zones,
 500  * reference counters are allocated for items and stored in
 501  * the underlying slab header.
 502  *
 503  * Arguments:
 504  *      zone  The UMA_ZONE_REFCNT zone to which the item belongs.
 505  *      item  The address of the item for which we want a refcnt.
 506  *
 507  * Returns:
 508  *      A pointer to a u_int32_t reference counter.
 509  */
 510 u_int32_t *uma_find_refcnt(uma_zone_t zone, void *item);
 511
 512 #endif