1# Memorystatus Subsystem 2 3Dealing with memory pressure by forcibly recovering pages. 4 5## Overview 6<a name="overview"></a> 7 8The xnu memorystatus subsystem is responsible for recovering the system when we're running dangerously low 9certain resources. Currently it monitors the following resources: 10 11- memory 12- vnodes 13- compressor space 14- swap space 15- zone map VA 16 17Depending on the resource, there are a variety of actions that memorystatus might take. 18One of the most common actions is to kill 1 or more processes in an attempt to recover the system. 19In addition to monitoring system level resources, the memorystatus code is also responsible 20for killing processes that go over their per-process memory limits. 21 22The memorystatus contains code to perform four actions in response to resource shortages: 23- Kill Processes 24- Freeze Processes 25- Send warning notifications 26- Swap memory from apps 27 28Each of these actions are covered in their own document in this folder. 29 30## Code Layout 31<a name="code-layout"></a> 32 33The memorystatus code lives on the BSD side of xnu. It's comprised of the following C files: 34 35- `bsd/kern/kern_memorystatus_policy.c` 36 Contains the policy decisions around when to perform which action. 37- `bsd/kern/kern_memorystatus_freeze.c` 38 Implementation of the freezer. See `doc/memorystatus/freezer.md` for details. 39- `bsd/kern/kern_memorystatus.c` 40 Contains mechanical code to implement the kill and swap actions. Should not contain any policy 41 (that should be in `bsd/kern/kern_memorystatus_policy.c`), but that's a recent refactor so 42 is a bit of a WIP. 43- `bsd/kern/kern_memorystatus_notify.c` 44 Contains both the policy and mechanical bits to send out memory pressure notifications. See `doc/memorystatus/notify.md` 45 46And the following headers: 47- `bsd/kern/kern_memorystatus_internal.h` 48- `bsd/sys/kern_memorystatus_notify.h` 49- `bsd/sys/kern_memorystatus_freeze.h` 50- `bsd/sys/kern_memorystatus.h` 51 52## Design 53<a name="design"></a> 54 55The memorystatus subsystem is designed around a central health check. 56All of the fields in this health check are defined in the `memorystatus_system_health_t` struct. See `bsd/kern/kern_memorystatus_internal.h` for the struct definition. 57 58Most of the monitoring and actions taken by the memorystatus subsystem happen in the `memorystatus_thread` (`bsd/kern/kern_memorystatus.c`). However, there are some synchronous actions that happen on other threads. See `doc/memorystatus/kill.md` for more documentation on specific kill types. 59 60Whenever it's woken up the memorystatus thread does the following: 611. Fill in the system health state by calling `memorystatus_health_check`) 621. Log this state to the os log (or serial if we're early in boot) 631. Check if the system is healthy via `memorystatus_is_system_healthy` 641. If the system is unhealthy, pick a recovery action and perform it. See `memorystatus_pick_action` (in `bsd/kern/kern_memorystatus_policy.c`) for the conditions that trigger specific actions. Note that we sometimes do pre-emptive actions on a healthy system if we're somewhat low on a specific resource. For example, we'll kill procs over their soft limit if we're under 15% available pages even if the system is otherwise healthy. 651. Go back to step 1 until the system is healthy and the thread can block. 66 67Notice that the memorystatus thread does not explicitly check why it was woken up. 68To keep the synchronization simple, anytime a resource shortage is detected the memorystatus 69thread is woken up *blindly* and it will do a full system health check. 70 71### Jetsam Bands 72 73The memorystatus subsystem has 210 priority levels. Every process in the system (except launchd) has a jetsam priority level. Higher numbers are more important. 74 75Each priority level is tracked as a TAILQ linked list . There is one global array, `memstat_bucket`, containing all of these TAILQ lists. 76A process's priority is tracked in the proc structure (See `bsd/sys/proc_internal.h`). `p_memstat_effective_priority` stores the proc's current jetsam priority, and `p_memstat_list` stores the TAILQ linkage. All lists are protected by the `proc_list_mlock` (Yes this is bad for scalability. Ideally we'd use finer grain locking or at least not share the global lock with the scheduler. See [rdar://36390487](rdar://36390487)) . 77 78Many kill types kill in ascending jetsam priority level. See `doc/memorystatus/kill.md` for more details. 79The jetsam band is either asserted by [RunningBoard](https://stashweb.sd.apple.com/projects/COREOS/repos/runningboard/browse) (apps and runningboard managed daemons) or determined by the jetsam priority set in the [JetsamProperties](https://stashweb.sd.apple.com/projects/COREOS/repos/jetsamproperties/browse) database. 80 81For reference, here are some of the band numbers: 82| Band Number | Name | Description | 83| ----------- | ---- | ----------- | 84| 0 | `JETSAM_PRIORITY_IDLE` | Idle processes | 85| 30 | `JETSAM_PRIORITY_BACKGROUND` | Docked apps on iOS. Some active daemons on other platforms. | 86| 40 | `JETSAM_PRIORITY_MAIL` | Docked apps on watchOS. Some active daemons on other platforms. | 87| 75 | `JETSAM_PRIORITY_FREEZER` | Suspended & frozen processes | 88| 100 | `JETSAM_PRIORITY_FOREGROUND` | Foreground app processes | 89| 140 | - | mediaserverd | 90| 160 | `JETSAM_PRIORITY_HOME` | SpringBoard | 91| 180 | `JETSAM_PRIORITY_IMPORTANT` | RunningBoard, watchdogd, thermalmonitord, etc.. | 92| 190 | `JETSAM_PRIORITY_CRITICAL` | CommCenter | 93 94See the full jetsam band reference on [confluence](https://confluence.sd.apple.com/display/allOSSystemsInternals/Jetsam#Jetsam-JetsamPriorities). 95 96### Daemon lifecycle 97 98The memorystatus subsystem is heavily intertwined with daemon lifecycle. A full discussion of daemon lifecycle is outside the scope of this document. If you're curious, here are some good resources: 99- [Daemon Overview](https://confluence.sd.apple.com/display/allOSSystemsInternals/Daemons#) 100- [RunningBoard's Process Management Documentation](https://confluence.sd.apple.com/display/allOSSystemsInternals/Process+Management+Paradigms) 101- [PressuredExit (A.K.A. activity tracking)](https://confluence.sd.apple.com/display/allOSSystemsInternals/Pressured+Exit) 102 103From the perspective of memorystatus there are essentially two kinds of processes: managed and unmanaged. Managed processes have their lifecycle managed by RunningBoard and have the `P_MEMSTAT_MANAGED` bit set on the `p_memstat_state` field. RunningBoard moves these processes between different jetsam bands based on their open assertions. 104 105Unmanaged processes go into their active jetsam band when they take out transactions. 106 107Daemons have different memory limits when they're inactive (in band 0) vs. active (above band 0). The inactive memory limit, active memory limit, and active jetsam band are determined via [JetsamProperties](https://stashweb.sd.apple.com/projects/COREOS/repos/jetsamproperties/browse). [Launchd](https://stashweb.sd.apple.com/projects/COREOS/repos/libxpc/browse) reads the JetsamProperties database and passes these values down to the kernel via posix_spawn(2) attributes. memorystatus stashes these values on the proc structure (`p_memstat_memlimit_active`, `p_memstat_memlimit_inactive`, `p_memstat_requestedpriority`), and applies them as daemons move between states. 108 109### Memory Monitoring 110 111Memorystatus makes most memory decisions based on the `memorystatus_available_pages` metric. This metric reflects the number of pages that memorystatus thinks could quickly be made free. This metric is defined in the `VM_CHECK_MEMORYSTATUS` macro in `osfmk/vm/vm_page.h`. 112 113Currently on non-macOS systems, it's defined as `pageable_external + free + secluded_over_target + purgeable`. Breaking that down: 114- `pageable_external`: file backed page count 115- `free`: free page count 116- `secluded_over_target`: `(vm_page_secluded_count - vm_page_secluded_target)`. This target comes from the device tree `kern.secluded_mem_mb`. Secluded memory is a special pool of memory that's intended for the camera so that it can startup faster on memory constrained systems. 117- `purgeable`: The number of purgeable volatile pages in the system. Purgeable memory is an API for clients to specify that the VM can treat the contents of a range of pages as volatile and quickly free the backing pages under pressure. See `osfmk/mach/vm_purgable.h` for the API. Note that the API was accidentally exported with incorrect spelling ("purgable" instead of "purgeable") 118 119Since we purge purgeable memory and trim the secluded pool quickly under memory pressure, this can generally be approximated to `free + file_backed` for a system under pressure. 120 121The `VM_CHECK_MEMORYSTATUS` macro is called whenever a page is allocated, wired, freed, etc... Basically `memorystatus_available_pages` is supposed to always be accurate down to a page level. On our larger memory systems (8 and 16GB iPads in particular) this might be overkill. 122And it calls into `memorystatus_pages_update` to actually update `memorystatus_available_pages` and issue the blind wakeup of the memorystatus thread if necessary. `memorystatus_pages_update` is also responsible for waking the freezer and memory pressure notification threads. 123 124The following configurable (EDT) thresholds determine which actions to take when `memorystatus_available_pages` is low. Each action is taken until `memorystatus_available_pages` rises back above the threshold. 125 126- `kern.memstat_pressure_mb`: only processes which have violated their "soft/HWM" memory limits may be killed (see `JETSAM_REASON_MEMORY_HIGHWATER`).\* 127- `kern.memstat_idle_mb`: only processes whose priority is `JETSAM_PRIORITY_IDLE` may be killed (see `JETSAM_REASON_MEMORY_IDLE_EXIT`) 128- `kern.memstat_critical_mb`: any process may be killed in ascending jetsam priority order (see `JETSAM_REASON_MEMORY_VMPAGESHORTAGE`) 129 130\*Note that the memorystatus pressure threshold does *not* determine the "system memory pressure level" (used to send pressure notifications and trigger sustained-pressure jetsams), which is monitored via a different subsystem. 131 132## Threads 133<a name="threads"></a> 134 135This section lists the threads that comprise the memorystatus subsystem. More details on each thread are below. 136 137| Thread name | Main function | wake event | 138| ----------- | ------------- | ---------- | 139| VM\_memorystatus\_1 | `memorystatus_thread` | `jt_wakeup_cond` in `jetsam_thread_state_t` | 140| VM\_freezer | `memorystatus_freeze_thread` | `memorystatus_freeze_wakeup` | 141| VM\_pressure | `vm_pressure_thread` | `vm_pressure_thread` | 142 143### VM\_memorystatus\_1 144 145This is the jetsam thread. It's responsible for running the system health check and performing most jetsam kills (see `doc/memorystatus/kill.md` for a kill breakdown). 146 147It's woken up via a call to `memorystatus_thread_wake` whenever any subsystem determines we're running low on a monitored resource. The wakeup is blind and the thread will immediately do a health check to determine what's wrong with the system. 148 149NB: There are technically three memorystatus threads: `VM_memorystatus_1`, `VM_memorystatus_2`, and `VM_memorystatus_3`. But we currently only use `VM_memorystatus_1`. At one point we tried to parallelize jetsam to speed it up, but this effort was unsuccessful. The other threads are just dead code at this point. 150 151### VM\_freezer 152 153This is the freezer thread. It's responsible for freezing processes under memory pressure and demoting processes when the freezer is full. See `doc/memorystatus/freeze.md` for more details on the freezer. 154 155It's woken up by issuing a `thread_wakeup` call to the `memorystatus_freeze_wakeup` global. This is done in `memorystatus_pages_update` if `memorystatus_freeze_thread_should_run` returns true. It's also done whenever `memorystatus_on_inactivity` runs. 156 157Upon wakeup the freezer thread will call `memorystatus_pick_freeze_count_for_wakeup` and attempt 158to freeze up to that many processes before blocking. `memorystatus_pick_freeze_count_for_wakeup` returns 1 on most platforms. But if app swap is enabled (M1 and later iPad Pros) it will return the total number of procs in all eligible bands. 159 160### VM\_pressure 161 162This is the memorystatus notification thread. It's woken up by the pageout thread via `vm_pressure_response`. `vm_pressure_response` is also called in `memorystatus_pages_update`. 163 164When awoken it calls `consider_vm_pressure_events` which winds its way to `memorystatus_update_vm_pressure`. This routine checks if the pressure level has changed and issues memory pressure notifications. It also schedules the thread call for sustained pressure kills. 165 166On macOS this thread also does idle exit kills. 167 168## Snapshots 169<a name="snapshots"></a> 170The memorystatus subsystem provides a snapshot mechanism so that 171ReportCrash can generate JetsamEvent.ips files. These files contain 172a snapshot of the system at the time that memorystatus performed 173some kills. The snapshot data structure is `memorystatus_jetsam_snapshot_t` defined in `bsd/sys/kern_memorystatus.h`. Generally speaking the snapshot contains system level memory statistics along with entries for each process in the system. Since we do not want to wake up ReportCrash while the system is low on memory, we maintain one global snapshot (`memorystatus_jetsam_snapshot` in `bsd/kern/kern_memorystatus.c`) while we're performing kills and only wake up ReportCrash once the system is healthy again. See `memorystatus_post_snapshot` in `bsd/kern/kern_memorystatus.c` which is called right before the jetsam thread blocks. 174 175**NB**: Posting the snapshot just means sending a notification to userspace that the snapshot is ready. Userspace (currently OSAnalytics) must make the `memorystatus_control` syscall with the `MEMORYSTATUS_CMD_GET_JETSAM_SNAPSHOT` subcommand to retrieve the snapshot. See `memorystatus_cmd_get_jetsam_snapshot` in `bsd/kern/kern_memorystatus.c` for details. Since we only have one global snapshot its cleared on read and thus can only have 1 consumer in userspace. 176 177### Freezer Snapshot 178The freezer snapshot, `memorystatus_jetsam_snapshot_freezer`, is a second global jetsam snapshot object. It reuses the snapshot struct definition but only contains apps that have been jetsammed. 179dasd reads this snapshot and uses it as an input for its freezer recommendation algorithm. However, we're not currently using the dasd recommendation algorithm for the freezer so this snapshot really only serves a diagnostic purpose today. 180This snapshot is also reset when dasd reads it. Note that it has to be separate from the OSAnalytics snapshot so that these daemons can read the snapshots independently. 181 182## Dumping Caches 183<a name="dumping-caches"></a> 184 185In general system caches should be cleared before we do higher band jetsams. Userspace entities should do this via purgeable memory if possible, or memory pressure notifications if not. In the kernel, memorystatus calls `memorystatus_approaching_fg_band` when we're about to do a fg band kill. This in turn calls `memorystatus_dump_caches` to clear the PPLs cache and purge all task corpses. This also sends out a notification to other entities to clear their caches (see `memorystatus_issue_fg_band_notify`). To avoid unnecessary corpse forking and purging, memorystatus blocks all additional corpse creation after it purges them until the system returns to a healthy state. 186