sys/vm/uma.h

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