uma.h revision 95766
160786Sps/* 260786Sps * Copyright (c) 2002, Jeffrey Roberson <jroberson@chesapeake.net> 360786Sps * All rights reserved. 460786Sps * 560786Sps * Redistribution and use in source and binary forms, with or without 660786Sps * modification, are permitted provided that the following conditions 789019Sps * are met: 860786Sps * 1. Redistributions of source code must retain the above copyright 960786Sps * notice unmodified, this list of conditions, and the following 10237613Sdelphij * disclaimer. 1160786Sps * 2. Redistributions in binary form must reproduce the above copyright 1260786Sps * notice, this list of conditions and the following disclaimer in the 1360786Sps * documentation and/or other materials provided with the distribution. 14238730Sdelphij * 15237613Sdelphij * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16237613Sdelphij * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17237613Sdelphij * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18237613Sdelphij * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19237613Sdelphij * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20237613Sdelphij * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21237613Sdelphij * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22237613Sdelphij * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23237613Sdelphij * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24237613Sdelphij * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25237613Sdelphij * 26237613Sdelphij * $FreeBSD: head/sys/vm/uma.h 95766 2002-04-30 04:26:34Z jeff $ 27237613Sdelphij * 28237613Sdelphij */ 29237613Sdelphij 30237613Sdelphij/* 31237613Sdelphij * uma.h - External definitions for the Universal Memory Allocator 32237613Sdelphij * 33237613Sdelphij * Jeff Roberson <jroberson@chesapeake.net> 34237613Sdelphij*/ 35237613Sdelphij 36237613Sdelphij#ifndef VM_UMA_H 37237613Sdelphij#define VM_UMA_H 38237613Sdelphij 39237613Sdelphij#include <sys/param.h> /* For NULL */ 40237613Sdelphij#include <sys/malloc.h> /* For M_* */ 41222906Sdelphij 42222906Sdelphij/* User visable parameters */ 43222906Sdelphij#define UMA_SMALLEST_UNIT (PAGE_SIZE / 256) /* Smallest item allocated */ 44222906Sdelphij 45222906Sdelphij/* Types and type defs */ 46222906Sdelphij 47222906Sdelphijstruct uma_zone; 48222906Sdelphij/* Opaque type used as a handle to the zone */ 49222906Sdelphijtypedef struct uma_zone * uma_zone_t; 50221715Sdelphij 51221715Sdelphij/* 52221715Sdelphij * Item constructor 53221715Sdelphij * 54221715Sdelphij * Arguments: 55221715Sdelphij * item A pointer to the memory which has been allocated. 56221715Sdelphij * arg The arg field passed to uma_zalloc_arg 57221715Sdelphij * size The size of the allocated item 58221715Sdelphij * 59221715Sdelphij * Returns: 60221715Sdelphij * Nothing 61221715Sdelphij * 62221715Sdelphij * Discussion: 63221715Sdelphij * The constructor is called just before the memory is returned 64221715Sdelphij * to the user. It may block if neccisary. 65221715Sdelphij */ 66221715Sdelphijtypedef void (*uma_ctor)(void *mem, int size, void *arg); 67221715Sdelphij 68221715Sdelphij/* 69221715Sdelphij * Item destructor 70221715Sdelphij * 71221715Sdelphij * Arguments: 72221715Sdelphij * item A pointer to the memory which has been allocated. 73221715Sdelphij * size The size of the item being destructed. 74221715Sdelphij * arg Argument passed through uma_zfree_arg 75221715Sdelphij * 76221715Sdelphij * Returns: 77221715Sdelphij * Nothing 78221715Sdelphij * 79221715Sdelphij * Discussion: 80221715Sdelphij * The destructor may perform operations that differ from those performed 81195941Sdelphij * by the initializer, but it must leave the object in the same state. 82195941Sdelphij * This IS type stable storage. This is called after EVERY zfree call. 83195941Sdelphij */ 84195941Sdelphijtypedef void (*uma_dtor)(void *mem, int size, void *arg); 85195941Sdelphij 86195941Sdelphij/* 87195941Sdelphij * Item initializer 88195941Sdelphij * 89195941Sdelphij * Arguments: 90195941Sdelphij * item A pointer to the memory which has been allocated. 91195941Sdelphij * size The size of the item being initialized. 92195941Sdelphij * 93191930Sdelphij * Returns: 9460786Sps * Nothing 95191930Sdelphij * 96191930Sdelphij * Discussion: 97191930Sdelphij * The initializer is called when the memory is cached in the uma zone. 98191930Sdelphij * this should be the same state that the destructor leaves the object in. 99191930Sdelphij */ 100191930Sdelphijtypedef void (*uma_init)(void *mem, int size); 101191930Sdelphij 102191930Sdelphij/* 103191930Sdelphij * Item discard function 104191930Sdelphij * 105191930Sdelphij * Arguments: 106191930Sdelphij * item A pointer to memory which has been 'freed' but has not left the 107191930Sdelphij * zone's cache. 108191930Sdelphij * size The size of the item being discarded. 109191930Sdelphij * 110191930Sdelphij * Returns: 111191930Sdelphij * Nothing 112191930Sdelphij * 113191930Sdelphij * Discussion: 114191930Sdelphij * This routine is called when memory leaves a zone and is returned to the 115191930Sdelphij * system for other uses. It is the counter part to the init function. 116191930Sdelphij */ 117191930Sdelphijtypedef void (*uma_fini)(void *mem, int size); 118191930Sdelphij 119191930Sdelphij/* 120191930Sdelphij * What's the difference between initializing and constructing? 121191930Sdelphij * 122191930Sdelphij * The item is initialized when it is cached, and this is the state that the 123191930Sdelphij * object should be in when returned to the allocator. The purpose of this is 124191930Sdelphij * to remove some code which would otherwise be called on each allocation by 125191930Sdelphij * utilizing a known, stable state. This differs from the constructor which 126191930Sdelphij * will be called on EVERY allocation. 127191930Sdelphij * 128191930Sdelphij * For example, in the initializer you may want to initialize embeded locks, 129191930Sdelphij * NULL list pointers, set up initial states, magic numbers, etc. This way if 130191930Sdelphij * the object is held in the allocator and re-used it won't be neccisary to 131191930Sdelphij * re-initialize it. 132191930Sdelphij * 133191930Sdelphij * The constructor may be used to lock a data structure, link it on to lists, 134191930Sdelphij * bump reference counts or total counts of outstanding structures, etc. 135191930Sdelphij * 136191930Sdelphij */ 137191930Sdelphij 138191930Sdelphij 139191930Sdelphij/* Function proto types */ 140191930Sdelphij 141191930Sdelphij/* 142191930Sdelphij * Create a new uma zone 143191930Sdelphij * 144191930Sdelphij * Arguments: 145191930Sdelphij * name The text name of the zone for debugging and stats, this memory 146191930Sdelphij * should not be freed until the zone has been deallocated. 147191930Sdelphij * size The size of the object that is being created. 148191930Sdelphij * ctor The constructor that is called when the object is allocated 149191930Sdelphij * dtor The destructor that is called when the object is freed. 150173932Sdelphij * init An initializer that sets up the initial state of the memory. 151173682Sdelphij * fini A discard function that undoes initialization done by init. 152173682Sdelphij * ctor/dtor/init/fini may all be null, see notes above. 153173682Sdelphij * align A bitmask that corisponds to the requested alignment 154173682Sdelphij * eg 4 would be 0x3 155173682Sdelphij * flags A set of parameters that control the behavior of the zone 156173682Sdelphij * 157173682Sdelphij * Returns: 158173682Sdelphij * A pointer to a structure which is intended to be opaque to users of 159173682Sdelphij * the interface. The value may be null if the wait flag is not set. 160173682Sdelphij */ 161172597Sdelphij 162172468Sdelphijuma_zone_t uma_zcreate(char *name, int size, uma_ctor ctor, uma_dtor dtor, 163172468Sdelphij uma_init uminit, uma_fini fini, int align, 164172468Sdelphij u_int16_t flags); 165172468Sdelphij 166172468Sdelphij/* Definitions for uma_zcreate flags */ 167172468Sdelphij#define UMA_ZONE_PAGEABLE 0x0001 /* Return items not fully backed by 168172468Sdelphij physical memory XXX Not yet */ 169172468Sdelphij#define UMA_ZONE_ZINIT 0x0002 /* Initialize with zeros */ 170172468Sdelphij#define UMA_ZONE_STATIC 0x0004 /* Staticly sized zone */ 171172597Sdelphij#define UMA_ZONE_OFFPAGE 0x0008 /* Force the slab structure allocation 172172597Sdelphij off of the real memory */ 173172468Sdelphij#define UMA_ZONE_MALLOC 0x0010 /* For use by malloc(9) only! */ 174172468Sdelphij#define UMA_ZONE_NOFREE 0x0020 /* Do not free slabs of this type! */ 175170964Sdelphij#define UMA_ZONE_MTXCLASS 0x0040 /* Create a new lock class */ 176170256Sdelphij 177170256Sdelphij/* Definitions for align */ 178170256Sdelphij#define UMA_ALIGN_PTR (sizeof(void *) - 1) /* Alignment fit for ptr */ 179170256Sdelphij#define UMA_ALIGN_LONG (sizeof(long) - 1) /* "" long */ 180170256Sdelphij#define UMA_ALIGN_INT (sizeof(int) - 1) /* "" int */ 181170256Sdelphij#define UMA_ALIGN_SHORT (sizeof(short) - 1) /* "" short */ 182170256Sdelphij#define UMA_ALIGN_CHAR (sizeof(char) - 1) /* "" char */ 183170256Sdelphij#define UMA_ALIGN_CACHE (16 - 1) /* Cache line size align */ 184170256Sdelphij 185170256Sdelphij/* 186170256Sdelphij * Destroys an empty uma zone. If the zone is not empty uma complains loudly. 187170256Sdelphij * 188170256Sdelphij * Arguments: 189170256Sdelphij * zone The zone we want to destroy. 190170256Sdelphij * 191170256Sdelphij */ 192170256Sdelphij 193170256Sdelphijvoid uma_zdestroy(uma_zone_t zone); 194170256Sdelphij 195170256Sdelphij/* 196170256Sdelphij * Allocates an item out of a zone 197170256Sdelphij * 198170256Sdelphij * Arguments: 199170256Sdelphij * zone The zone we are allocating from 200170256Sdelphij * arg This data is passed to the ctor function 201170256Sdelphij * flags See sys/malloc.h for available flags. 202170256Sdelphij * 203170256Sdelphij * Returns: 204170256Sdelphij * A non null pointer to an initialized element from the zone is 205170256Sdelphij * garanteed if the wait flag is M_WAITOK, otherwise a null pointer may be 206170256Sdelphij * returned if the zone is empty or the ctor failed. 207170256Sdelphij */ 208170256Sdelphij 209170256Sdelphijvoid *uma_zalloc_arg(uma_zone_t zone, void *arg, int flags); 210170256Sdelphij 211170256Sdelphij/* 212170256Sdelphij * Allocates an item out of a zone without supplying an argument 213170256Sdelphij * 214170256Sdelphij * This is just a wrapper for uma_zalloc_arg for convenience. 215170256Sdelphij * 216170256Sdelphij */ 217170256Sdelphijstatic __inline void *uma_zalloc(uma_zone_t zone, int flags); 218170256Sdelphij 219170256Sdelphijstatic __inline void * 220170256Sdelphijuma_zalloc(uma_zone_t zone, int flags) 221170256Sdelphij{ 222161475Sdelphij return uma_zalloc_arg(zone, NULL, flags); 223161475Sdelphij} 224161475Sdelphij 225161475Sdelphij/* 226161475Sdelphij * Frees an item back into the specified zone. 227161475Sdelphij * 228161475Sdelphij * Arguments: 229161475Sdelphij * zone The zone the item was originally allocated out of. 230161475Sdelphij * item The memory to be freed. 231161475Sdelphij * arg Argument passed to the destructor 232161475Sdelphij * 233161475Sdelphij * Returns: 234161475Sdelphij * Nothing. 235161475Sdelphij */ 236161475Sdelphij 237161475Sdelphijvoid uma_zfree_arg(uma_zone_t zone, void *item, void *arg); 238161475Sdelphij 239161475Sdelphij/* 240161475Sdelphij * Frees an item back to a zone without supplying an argument 241161475Sdelphij * 242161475Sdelphij * This is just a wrapper for uma_zfree_arg for convenience. 243161475Sdelphij * 244161475Sdelphij */ 245161475Sdelphijstatic __inline void uma_zfree(uma_zone_t zone, void *item); 246161475Sdelphij 247161475Sdelphijstatic __inline void 248161475Sdelphijuma_zfree(uma_zone_t zone, void *item) 249161475Sdelphij{ 250161475Sdelphij return uma_zfree_arg(zone, item, NULL); 251161475Sdelphij} 252161475Sdelphij 253161475Sdelphij/* 254161475Sdelphij * XXX The rest of the prototypes in this header are h0h0 magic for the VM. 255161475Sdelphij * If you think you need to use it for a normal zone you're probably incorrect. 256161475Sdelphij */ 257161475Sdelphij 258161475Sdelphij/* 259161475Sdelphij * Backend page supplier routines 260161475Sdelphij * 261161475Sdelphij * Arguments: 262161475Sdelphij * zone The zone that is requesting pages 263161475Sdelphij * size The number of bytes being requested 264161475Sdelphij * pflag Flags for these memory pages, see below. 265161475Sdelphij * wait Indicates our willingness to block. 266161475Sdelphij * 267161475Sdelphij * Returns: 268161475Sdelphij * A pointer to the alloced memory or NULL on failure. 269161475Sdelphij */ 270161475Sdelphij 271161475Sdelphijtypedef void *(*uma_alloc)(uma_zone_t zone, int size, u_int8_t *pflag, int wait); 272161475Sdelphij 273161475Sdelphij/* 274161475Sdelphij * Backend page free routines 275161475Sdelphij * 276161475Sdelphij * Arguments: 277161475Sdelphij * item A pointer to the previously allocated pages 278128345Stjr * size The original size of the allocation 27989019Sps * pflag The flags for the slab. See UMA_SLAB_* below 280128345Stjr * 281128345Stjr * Returns: 282128345Stjr * None 283128345Stjr */ 284128345Stjrtypedef void (*uma_free)(void *item, int size, u_int8_t pflag); 285128345Stjr 286128345Stjr 287128345Stjr 288128345Stjr/* 289128345Stjr * Sets up the uma allocator. (Called by vm_mem_init) 290128345Stjr * 291128345Stjr * Arguments: 292128345Stjr * bootmem A pointer to memory used to bootstrap the system. 293128345Stjr * 294128345Stjr * Returns: 295128345Stjr * Nothing 296128345Stjr * 297128345Stjr * Discussion: 298128345Stjr * This memory is used for zones which allocate things before the 299128345Stjr * backend page supplier can give us pages. It should be 300128345Stjr * UMA_SLAB_SIZE * UMA_BOOT_PAGES bytes. (see uma_int.h) 301128345Stjr * 302128345Stjr */ 303128345Stjr 304128345Stjrvoid uma_startup(void *bootmem); 305128345Stjr 306128345Stjr/* 307128345Stjr * Finishes starting up the allocator. This should 308128345Stjr * be called when kva is ready for normal allocs. 309128345Stjr * 310128345Stjr * Arguments: 31189019Sps * hash An area of memory that will become the malloc hash 31289019Sps * elems The number of elements in this array 31389019Sps * 31489019Sps * Returns: 31589019Sps * Nothing 31689019Sps * 31789019Sps * Discussion: 31889019Sps * uma_startup2 is called by kmeminit() to prepare the malloc 31989019Sps * hash bucket, and enable use of uma for malloc ops. 32089019Sps */ 32189019Sps 32289019Spsvoid uma_startup2(void *hash, u_long elems); 32389019Sps 32489019Sps/* 32589019Sps * Reclaims unused memory for all zones 32689019Sps * 32789019Sps * Arguments: 32889019Sps * None 32989019Sps * Returns: 33089019Sps * None 33189019Sps * 33289019Sps * This should only be called by the page out daemon. 33389019Sps */ 33489019Sps 33589019Spsvoid uma_reclaim(void); 33689019Sps 337128345Stjr/* 338128345Stjr * Switches the backing object of a zone 33989019Sps * 340128345Stjr * Arguments: 341128345Stjr * zone The zone to update 34289019Sps * obj The obj to use for future allocations 34389019Sps * size The size of the object to allocate 34489019Sps * 34589019Sps * Returns: 34689019Sps * 0 if kva space can not be allocated 34789019Sps * 1 if successful 34889019Sps * 34989019Sps * Discussion: 350128345Stjr * A NULL object can be used and uma will allocate one for you. Setting 351128345Stjr * the size will limit the amount of memory allocated to this zone. 35289019Sps * 35389019Sps */ 35489019Spsstruct vm_object; 35589019Spsint uma_zone_set_obj(uma_zone_t zone, struct vm_object *obj, int size); 35689019Sps 35789019Sps/* 35863128Sps * Sets a high limit on the number of items allowed in a zone 35963128Sps * 36063128Sps * Arguments: 36163128Sps * zone The zone to limit 36263128Sps * 36363128Sps * Returns: 36463128Sps * Nothing 36563128Sps */ 36663128Spsvoid uma_zone_set_max(uma_zone_t zone, int nitems); 36763128Sps 36863128Sps/* 36963128Sps * Replaces the standard page_alloc or obj_alloc functions for this zone 37063128Sps * 37163128Sps * Arguments: 37260786Sps * zone The zone whos back end allocator is being changed. 37360786Sps * allocf A pointer to the allocation function 37460786Sps * 37560786Sps * Returns: 37660786Sps * Nothing 37760786Sps * 37860786Sps * Discussion: 37960786Sps * This could be used to implement pageable allocation, or perhaps 38060786Sps * even DMA allocators if used in conjunction with the OFFPAGE 38160786Sps * zone flag. 38260786Sps */ 38360786Sps 38460786Spsvoid uma_zone_set_allocf(uma_zone_t zone, uma_alloc allocf); 38560786Sps 38660786Sps/* 38760786Sps * Used for freeing memory provided by the allocf above 38860786Sps * 38960786Sps * Arguments: 39060786Sps * zone The zone that intends to use this free routine. 39160786Sps * freef The page freeing routine. 39260786Sps * 39360786Sps * Returns: 39460786Sps * Nothing 39560786Sps */ 39660786Sps 39760786Spsvoid uma_zone_set_freef(uma_zone_t zone, uma_free freef); 39860786Sps 39960786Sps/* 40060786Sps * These flags are setable in the allocf and visable in the freef. 40160786Sps */ 40260786Sps#define UMA_SLAB_BOOT 0x01 /* Slab alloced from boot pages */ 40360786Sps#define UMA_SLAB_KMEM 0x02 /* Slab alloced from kmem_map */ 40460786Sps#define UMA_SLAB_KMAP 0x04 /* Slab alloced from kernel_map */ 40560786Sps#define UMA_SLAB_PRIV 0x08 /* Slab alloced from priv allocator */ 40660786Sps#define UMA_SLAB_OFFP 0x10 /* Slab is managed separately */ 40760786Sps#define UMA_SLAB_MALLOC 0x20 /* Slab is a large malloc slab */ 40860786Sps/* 0x40 and 0x80 are available */ 40960786Sps 41060786Sps/* 41160786Sps * Used to pre-fill a zone with some number of items 41260786Sps * 41360786Sps * Arguments: 41460786Sps * zone The zone to fill 41560786Sps * itemcnt The number of items to reserve 41660786Sps * 41760786Sps * Returns: 41860786Sps * Nothing 41960786Sps * 42060786Sps * NOTE: This is blocking and should only be done at startup 42160786Sps */ 42260786Spsvoid uma_prealloc(uma_zone_t zone, int itemcnt); 42360786Sps 42460786Sps 42560786Sps#endif 42660786Sps