osfmk/mach/vm_purgable.h

   1 /*
   2  * Copyright (c) 2003-2007 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28
  29 /*
  30  * Virtual memory map purgeable object definitions.
  31  * Objects that will be needed in the future (forward cached objects) should be queued LIFO.
  32  * Objects that have been used and are cached for reuse (backward cached) should be queued FIFO.
  33  * Every user of purgeable memory is entitled to using the highest volatile group (7).
  34  * Only if a client wants some of its objects to definitely be purged earlier, it can put those in
  35  * another group. This could be used to make all FIFO objects (in the lower group) go away before
  36  * any LIFO objects (in the higher group) go away.
  37  * Objects that should not get any chance to stay around can be marked as "obsolete". They will
  38  * be emptied before any other objects or pages are reclaimed. Obsolete objects are not emptied
  39  * in any particular order.
  40  * 'purgeable' is recognized as the correct spelling. For historical reasons, definitions
  41  * in this file are spelled 'purgable'.
  42  */
  43
  44 #ifndef _MACH_VM_PURGABLE_H_
  45 #define _MACH_VM_PURGABLE_H_
  46
  47 /*
  48  *      Types defined:
  49  *
  50  *      vm_purgable_t   purgeable object control codes.
  51  */
  52
  53 typedef int     vm_purgable_t;
  54
  55 /*
  56  *      Enumeration of valid values for vm_purgable_t.
  57  */
  58 #define VM_PURGABLE_SET_STATE   ((vm_purgable_t) 0)     /* set state of purgeable object */
  59 #define VM_PURGABLE_GET_STATE   ((vm_purgable_t) 1)     /* get state of purgeable object */
  60 #define VM_PURGABLE_PURGE_ALL   ((vm_purgable_t) 2)     /* purge all volatile objects now */
  61 #define VM_PURGABLE_SET_STATE_FROM_KERNEL ((vm_purgable_t) 3) /* set state from kernel */
  62
  63 /*
  64  * Purgeable state:
  65  *
  66  *  31 15 14 13 12 11 10 8 7 6 5 4 3 2 1 0
  67  * +-----+--+-----+--+----+-+-+---+---+---+
  68  * |     |NA|DEBUG|  | GRP| |B|ORD|   |STA|
  69  * +-----+--+-----+--+----+-+-+---+---+---+
  70  * " ": unused (i.e. reserved)
  71  * STA: purgeable state
  72  *      see: VM_PURGABLE_NONVOLATILE=0 to VM_PURGABLE_DENY=3
  73  * ORD: order
  74  *      see:VM_VOLATILE_ORDER_*
  75  * B: behavior
  76  *      see: VM_PURGABLE_BEHAVIOR_*
  77  * GRP: group
  78  *      see: VM_VOLATILE_GROUP_*
  79  * DEBUG: debug
  80  *      see: VM_PURGABLE_DEBUG_*
  81  * NA: no aging
  82  *      see: VM_PURGABLE_NO_AGING*
  83  */
  84
  85 #define VM_PURGABLE_NO_AGING_SHIFT      16
  86 #define VM_PURGABLE_NO_AGING_MASK       (0x1 << VM_PURGABLE_NO_AGING_SHIFT)
  87 #define VM_PURGABLE_NO_AGING            (0x1 << VM_PURGABLE_NO_AGING_SHIFT)
  88
  89 #define VM_PURGABLE_DEBUG_SHIFT 12
  90 #define VM_PURGABLE_DEBUG_MASK  (0x3 << VM_PURGABLE_DEBUG_SHIFT)
  91 #define VM_PURGABLE_DEBUG_EMPTY (0x1 << VM_PURGABLE_DEBUG_SHIFT)
  92 #define VM_PURGABLE_DEBUG_FAULT (0x2 << VM_PURGABLE_DEBUG_SHIFT)
  93
  94 /*
  95  * Volatile memory ordering groups (group zero objects are purged before group 1, etc...
  96  * It is implementation dependent as to whether these groups are global or per-address space.
  97  * (for the moment, they are global).
  98  */
  99 #define VM_VOLATILE_GROUP_SHIFT         8
 100 #define VM_VOLATILE_GROUP_MASK          (7 << VM_VOLATILE_GROUP_SHIFT)
 101 #define VM_VOLATILE_GROUP_DEFAULT   VM_VOLATILE_GROUP_0
 102
 103 #define VM_VOLATILE_GROUP_0                     (0 << VM_VOLATILE_GROUP_SHIFT)
 104 #define VM_VOLATILE_GROUP_1                     (1 << VM_VOLATILE_GROUP_SHIFT)
 105 #define VM_VOLATILE_GROUP_2                     (2 << VM_VOLATILE_GROUP_SHIFT)
 106 #define VM_VOLATILE_GROUP_3                     (3 << VM_VOLATILE_GROUP_SHIFT)
 107 #define VM_VOLATILE_GROUP_4                     (4 << VM_VOLATILE_GROUP_SHIFT)
 108 #define VM_VOLATILE_GROUP_5                     (5 << VM_VOLATILE_GROUP_SHIFT)
 109 #define VM_VOLATILE_GROUP_6                     (6 << VM_VOLATILE_GROUP_SHIFT)
 110 #define VM_VOLATILE_GROUP_7                     (7 << VM_VOLATILE_GROUP_SHIFT)
 111
 112 /*
 113  * Purgeable behavior
 114  * Within the same group, FIFO objects will be emptied before objects that are added later.
 115  * LIFO objects will be emptied after objects that are added later.
 116  * - Input only, not returned on state queries.
 117  */
 118 #define VM_PURGABLE_BEHAVIOR_SHIFT  6
 119 #define VM_PURGABLE_BEHAVIOR_MASK   (1 << VM_PURGABLE_BEHAVIOR_SHIFT)
 120 #define VM_PURGABLE_BEHAVIOR_FIFO   (0 << VM_PURGABLE_BEHAVIOR_SHIFT)
 121 #define VM_PURGABLE_BEHAVIOR_LIFO   (1 << VM_PURGABLE_BEHAVIOR_SHIFT)
 122
 123 /*
 124  * Obsolete object.
 125  * Disregard volatile group, and put object into obsolete queue instead, so it is the next object
 126  * to be purged.
 127  * - Input only, not returned on state queries.
 128  */
 129 #define VM_PURGABLE_ORDERING_SHIFT              5
 130 #define VM_PURGABLE_ORDERING_MASK               (1 << VM_PURGABLE_ORDERING_SHIFT)
 131 #define VM_PURGABLE_ORDERING_OBSOLETE   (1 << VM_PURGABLE_ORDERING_SHIFT)
 132 #define VM_PURGABLE_ORDERING_NORMAL             (0 << VM_PURGABLE_ORDERING_SHIFT)
 133
 134
 135 /*
 136  * Obsolete parameter - do not use
 137  */
 138 #define VM_VOLATILE_ORDER_SHIFT                 4
 139 #define VM_VOLATILE_ORDER_MASK                  (1 << VM_VOLATILE_ORDER_SHIFT)
 140 #define VM_VOLATILE_MAKE_FIRST_IN_GROUP (1 << VM_VOLATILE_ORDER_SHIFT)
 141 #define VM_VOLATILE_MAKE_LAST_IN_GROUP  (0 << VM_VOLATILE_ORDER_SHIFT)
 142
 143 /*
 144  * Valid states of a purgeable object.
 145  */
 146 #define VM_PURGABLE_STATE_MIN   0               /* minimum purgeable object state value */
 147 #define VM_PURGABLE_STATE_MAX   3               /* maximum purgeable object state value */
 148 #define VM_PURGABLE_STATE_MASK  3               /* mask to separate state from group */
 149
 150 #define VM_PURGABLE_NONVOLATILE 0               /* purgeable object is non-volatile */
 151 #define VM_PURGABLE_VOLATILE    1               /* purgeable object is volatile */
 152 #define VM_PURGABLE_EMPTY       2               /* purgeable object is volatile and empty */
 153 #define VM_PURGABLE_DENY        3               /* (mark) object not purgeable */
 154
 155 #define VM_PURGABLE_ALL_MASKS   (VM_PURGABLE_STATE_MASK | \
 156                                  VM_VOLATILE_ORDER_MASK | \
 157                                  VM_PURGABLE_ORDERING_MASK | \
 158                                  VM_PURGABLE_BEHAVIOR_MASK | \
 159                                  VM_VOLATILE_GROUP_MASK | \
 160                                  VM_PURGABLE_DEBUG_MASK | \
 161                                  VM_PURGABLE_NO_AGING_MASK)
 162 #endif  /* _MACH_VM_PURGABLE_H_ */