sys/vm/uma.h

   1 /*
   2  * Copyright (c) 2002, Jeffrey Roberson <jroberson@chesapeake.net>
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice unmodified, this list of conditions, and the following
  10  *    disclaimer.
  11  * 2. Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the distribution.
  14  *
  15  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  16  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  19  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25  *
  26  * $FreeBSD$
  27  *
  28  */
  29
  30 /*
  31  * uma.h - External definitions for the Universal Memory Allocator
  32  *
  33  * Jeff Roberson <jroberson@chesapeake.net>
  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  *
  59  * Returns:
  60  *      Nothing
  61  *
  62  * Discussion:
  63  *      The constructor is called just before the memory is returned
  64  *      to the user. It may block if neccisary.
  65  */
  66 typedef void (*uma_ctor)(void *mem, int size, void *arg);
  67
  68 /*
  69  * Item destructor
  70  *
  71  * Arguments:
  72  *      item  A pointer to the memory which has been allocated.
  73  *      size  The size of the item being destructed.
  74  *      arg   Argument passed through uma_zfree_arg
  75  *
  76  * Returns:
  77  *      Nothing
  78  *
  79  * Discussion:
  80  *      The destructor may perform operations that differ from those performed
  81  *      by the initializer, but it must leave the object in the same state.
  82  *      This IS type stable storage.  This is called after EVERY zfree call.
  83  */
  84 typedef void (*uma_dtor)(void *mem, int size, void *arg);
  85
  86 /*
  87  * Item initializer
  88  *
  89  * Arguments:
  90  *      item  A pointer to the memory which has been allocated.
  91  *      size  The size of the item being initialized.
  92  *
  93  * Returns:
  94  *      Nothing
  95  *
  96  * Discussion:
  97  *      The initializer is called when the memory is cached in the uma zone.
  98  *      this should be the same state that the destructor leaves the object in.
  99  */
 100 typedef void (*uma_init)(void *mem, int size);
 101
 102 /*
 103  * Item discard function
 104  *
 105  * Arguments:
 106  *      item  A pointer to memory which has been 'freed' but has not left the
 107  *            zone's cache.
 108  *      size  The size of the item being discarded.
 109  *
 110  * Returns:
 111  *      Nothing
 112  *
 113  * Discussion:
 114  *      This routine is called when memory leaves a zone and is returned to the
 115  *      system for other uses.  It is the counter part to the init function.
 116  */
 117 typedef void (*uma_fini)(void *mem, int size);
 118
 119 /*
 120  * What's the difference between initializing and constructing?
 121  *
 122  * The item is initialized when it is cached, and this is the state that the
 123  * object should be in when returned to the allocator. The purpose of this is
 124  * to remove some code which would otherwise be called on each allocation by
 125  * utilizing a known, stable state.  This differs from the constructor which
 126  * will be called on EVERY allocation.
 127  *
 128  * For example, in the initializer you may want to initialize embeded locks,
 129  * NULL list pointers, set up initial states, magic numbers, etc.  This way if
 130  * the object is held in the allocator and re-used it won't be neccisary to
 131  * re-initialize it.
 132  *
 133  * The constructor may be used to lock a data structure, link it on to lists,
 134  * bump reference counts or total counts of outstanding structures, etc.
 135  *
 136  */
 137
 138
 139 /* Function proto types */
 140
 141 /*
 142  * Create a new uma zone
 143  *
 144  * Arguments:
 145  *      name  The text name of the zone for debugging and stats, this memory
 146  *              should not be freed until the zone has been deallocated.
 147  *      size  The size of the object that is being created.
 148  *      ctor  The constructor that is called when the object is allocated
 149  *      dtor  The destructor that is called when the object is freed.
 150  *      init  An initializer that sets up the initial state of the memory.
 151  *      fini  A discard function that undoes initialization done by init.
 152  *              ctor/dtor/init/fini may all be null, see notes above.
 153  *      align A bitmask that corisponds to the requested alignment
 154  *              eg 4 would be 0x3
 155  *      flags A set of parameters that control the behavior of the zone
 156  *
 157  * Returns:
 158  *      A pointer to a structure which is intended to be opaque to users of
 159  *      the interface.  The value may be null if the wait flag is not set.
 160  */
 161
 162 uma_zone_t uma_zcreate(char *name, size_t size, uma_ctor ctor, uma_dtor dtor,
 163                         uma_init uminit, uma_fini fini, int align,
 164                         u_int16_t flags);
 165
 166 /* Definitions for uma_zcreate flags */
 167 #define UMA_ZONE_PAGEABLE       0x0001  /* Return items not fully backed by
 168                                            physical memory XXX Not yet */
 169 #define UMA_ZONE_ZINIT          0x0002  /* Initialize with zeros */
 170 #define UMA_ZONE_STATIC         0x0004  /* Staticly sized zone */
 171 #define UMA_ZONE_OFFPAGE        0x0008  /* Force the slab structure allocation
 172                                            off of the real memory */
 173 #define UMA_ZONE_MALLOC         0x0010  /* For use by malloc(9) only! */
 174 #define UMA_ZONE_NOFREE         0x0020  /* Do not free slabs of this type! */
 175 #define UMA_ZONE_MTXCLASS       0x0040  /* Create a new lock class */
 176 #define UMA_ZONE_VM             0x0080  /* Used for internal vm datastructures */
 177
 178 /* Definitions for align */
 179 #define UMA_ALIGN_PTR   (sizeof(void *) - 1)    /* Alignment fit for ptr */
 180 #define UMA_ALIGN_LONG  (sizeof(long) - 1)      /* "" long */
 181 #define UMA_ALIGN_INT   (sizeof(int) - 1)       /* "" int */
 182 #define UMA_ALIGN_SHORT (sizeof(short) - 1)     /* "" short */
 183 #define UMA_ALIGN_CHAR  (sizeof(char) - 1)      /* "" char */
 184 #define UMA_ALIGN_CACHE (16 - 1)                /* Cache line size align */
 185
 186 /*
 187  * Destroys an empty uma zone.  If the zone is not empty uma complains loudly.
 188  *
 189  * Arguments:
 190  *      zone  The zone we want to destroy.
 191  *
 192  */
 193
 194 void uma_zdestroy(uma_zone_t zone);
 195
 196 /*
 197  * Allocates an item out of a zone
 198  *
 199  * Arguments:
 200  *      zone  The zone we are allocating from
 201  *      arg   This data is passed to the ctor function
 202  *      flags See sys/malloc.h for available flags.
 203  *
 204  * Returns:
 205  *      A non null pointer to an initialized element from the zone is
 206  *      garanteed if the wait flag is M_WAITOK, otherwise a null pointer may be
 207  *      returned if the zone is empty or the ctor failed.
 208  */
 209
 210 void *uma_zalloc_arg(uma_zone_t zone, void *arg, int flags);
 211
 212 /*
 213  * Allocates an item out of a zone without supplying an argument
 214  *
 215  * This is just a wrapper for uma_zalloc_arg for convenience.
 216  *
 217  */
 218 static __inline void *uma_zalloc(uma_zone_t zone, int flags);
 219
 220 static __inline void *
 221 uma_zalloc(uma_zone_t zone, int flags)
 222 {
 223         return uma_zalloc_arg(zone, NULL, flags);
 224 }
 225
 226 /*
 227  * Frees an item back into the specified zone.
 228  *
 229  * Arguments:
 230  *      zone  The zone the item was originally allocated out of.
 231  *      item  The memory to be freed.
 232  *      arg   Argument passed to the destructor
 233  *
 234  * Returns:
 235  *      Nothing.
 236  */
 237
 238 void uma_zfree_arg(uma_zone_t zone, void *item, void *arg);
 239
 240 /*
 241  * Frees an item back to a zone without supplying an argument
 242  *
 243  * This is just a wrapper for uma_zfree_arg for convenience.
 244  *
 245  */
 246 static __inline void uma_zfree(uma_zone_t zone, void *item);
 247
 248 static __inline void
 249 uma_zfree(uma_zone_t zone, void *item)
 250 {
 251         uma_zfree_arg(zone, item, NULL);
 252 }
 253
 254 /*
 255  * XXX The rest of the prototypes in this header are h0h0 magic for the VM.
 256  * If you think you need to use it for a normal zone you're probably incorrect.
 257  */
 258
 259 /*
 260  * Backend page supplier routines
 261  *
 262  * Arguments:
 263  *      zone  The zone that is requesting pages
 264  *      size  The number of bytes being requested
 265  *      pflag Flags for these memory pages, see below.
 266  *      wait  Indicates our willingness to block.
 267  *
 268  * Returns:
 269  *      A pointer to the alloced memory or NULL on failure.
 270  */
 271
 272 typedef void *(*uma_alloc)(uma_zone_t zone, int size, u_int8_t *pflag, int wait);
 273
 274 /*
 275  * Backend page free routines
 276  *
 277  * Arguments:
 278  *      item  A pointer to the previously allocated pages
 279  *      size  The original size of the allocation
 280  *      pflag The flags for the slab.  See UMA_SLAB_* below
 281  *
 282  * Returns:
 283  *      None
 284  */
 285 typedef void (*uma_free)(void *item, int size, u_int8_t pflag);
 286
 287
 288
 289 /*
 290  * Sets up the uma allocator. (Called by vm_mem_init)
 291  *
 292  * Arguments:
 293  *      bootmem  A pointer to memory used to bootstrap the system.
 294  *
 295  * Returns:
 296  *      Nothing
 297  *
 298  * Discussion:
 299  *      This memory is used for zones which allocate things before the
 300  *      backend page supplier can give us pages.  It should be
 301  *      UMA_SLAB_SIZE * UMA_BOOT_PAGES bytes. (see uma_int.h)
 302  *
 303  */
 304
 305 void uma_startup(void *bootmem);
 306
 307 /*
 308  * Finishes starting up the allocator.  This should
 309  * be called when kva is ready for normal allocs.
 310  *
 311  * Arguments:
 312  *      hash   An area of memory that will become the malloc hash
 313  *      elems  The number of elements in this array
 314  *
 315  * Returns:
 316  *      Nothing
 317  *
 318  * Discussion:
 319  *      uma_startup2 is called by kmeminit() to prepare the malloc
 320  *      hash bucket, and enable use of uma for malloc ops.
 321  */
 322
 323 void uma_startup2(void *hash, u_long elems);
 324
 325 /*
 326  * Reclaims unused memory for all zones
 327  *
 328  * Arguments:
 329  *      None
 330  * Returns:
 331  *      None
 332  *
 333  * This should only be called by the page out daemon.
 334  */
 335
 336 void uma_reclaim(void);
 337
 338 /*
 339  * Switches the backing object of a zone
 340  *
 341  * Arguments:
 342  *      zone  The zone to update
 343  *      obj   The obj to use for future allocations
 344  *      size  The size of the object to allocate
 345  *
 346  * Returns:
 347  *      0  if kva space can not be allocated
 348  *      1  if successful
 349  *
 350  * Discussion:
 351  *      A NULL object can be used and uma will allocate one for you.  Setting
 352  *      the size will limit the amount of memory allocated to this zone.
 353  *
 354  */
 355 struct vm_object;
 356 int uma_zone_set_obj(uma_zone_t zone, struct vm_object *obj, int size);
 357
 358 /*
 359  * Sets a high limit on the number of items allowed in a zone
 360  *
 361  * Arguments:
 362  *      zone  The zone to limit
 363  *
 364  * Returns:
 365  *      Nothing
 366  */
 367 void uma_zone_set_max(uma_zone_t zone, int nitems);
 368
 369 /*
 370  * Replaces the standard page_alloc or obj_alloc functions for this zone
 371  *
 372  * Arguments:
 373  *      zone   The zone whos back end allocator is being changed.
 374  *      allocf A pointer to the allocation function
 375  *
 376  * Returns:
 377  *      Nothing
 378  *
 379  * Discussion:
 380  *      This could be used to implement pageable allocation, or perhaps
 381  *      even DMA allocators if used in conjunction with the OFFPAGE
 382  *      zone flag.
 383  */
 384
 385 void uma_zone_set_allocf(uma_zone_t zone, uma_alloc allocf);
 386
 387 /*
 388  * Used for freeing memory provided by the allocf above
 389  *
 390  * Arguments:
 391  *      zone  The zone that intends to use this free routine.
 392  *      freef The page freeing routine.
 393  *
 394  * Returns:
 395  *      Nothing
 396  */
 397
 398 void uma_zone_set_freef(uma_zone_t zone, uma_free freef);
 399
 400 /*
 401  * These flags are setable in the allocf and visable in the freef.
 402  */
 403 #define UMA_SLAB_BOOT   0x01            /* Slab alloced from boot pages */
 404 #define UMA_SLAB_KMEM   0x02            /* Slab alloced from kmem_map */
 405 #define UMA_SLAB_PRIV   0x08            /* Slab alloced from priv allocator */
 406 #define UMA_SLAB_OFFP   0x10            /* Slab is managed separately  */
 407 #define UMA_SLAB_MALLOC 0x20            /* Slab is a large malloc slab */
 408 /* 0x40 and 0x80 are available */
 409
 410 /*
 411  * Used to pre-fill a zone with some number of items
 412  *
 413  * Arguments:
 414  *      zone    The zone to fill
 415  *      itemcnt The number of items to reserve
 416  *
 417  * Returns:
 418  *      Nothing
 419  *
 420  * NOTE: This is blocking and should only be done at startup
 421  */
 422 void uma_prealloc(uma_zone_t zone, int itemcnt);
 423
 424
 425 #endif