1 /* SPDX-License-Identifier: MIT */ 2 /* 3 * Copyright © 2022 Intel Corporation 4 */ 5 6 #ifndef _XE_BO_DOC_H_ 7 #define _XE_BO_DOC_H_ 8 9 /** 10 * DOC: Buffer Objects (BO) 11 * 12 * BO management 13 * ============= 14 * 15 * TTM manages (placement, eviction, etc...) all BOs in XE. 16 * 17 * BO creation 18 * =========== 19 * 20 * Create a chunk of memory which can be used by the GPU. Placement rules 21 * (sysmem or vram region) passed in upon creation. TTM handles placement of BO 22 * and can trigger eviction of other BOs to make space for the new BO. 23 * 24 * Kernel BOs 25 * ---------- 26 * 27 * A kernel BO is created as part of driver load (e.g. uC firmware images, GuC 28 * ADS, etc...) or a BO created as part of a user operation which requires 29 * a kernel BO (e.g. engine state, memory for page tables, etc...). These BOs 30 * are typically mapped in the GGTT (any kernel BOs aside memory for page tables 31 * are in the GGTT), are pinned (can't move or be evicted at runtime), have a 32 * vmap (XE can access the memory via xe_map layer) and have contiguous physical 33 * memory. 34 * 35 * More details of why kernel BOs are pinned and contiguous below. 36 * 37 * User BOs 38 * -------- 39 * 40 * A user BO is created via the DRM_IOCTL_XE_GEM_CREATE IOCTL. Once it is 41 * created the BO can be mmap'd (via DRM_IOCTL_XE_GEM_MMAP_OFFSET) for user 42 * access and it can be bound for GPU access (via DRM_IOCTL_XE_VM_BIND). All 43 * user BOs are evictable and user BOs are never pinned by XE. The allocation of 44 * the backing store can be defered from creation time until first use which is 45 * either mmap, bind, or pagefault. 46 * 47 * Private BOs 48 * ~~~~~~~~~~~ 49 * 50 * A private BO is a user BO created with a valid VM argument passed into the 51 * create IOCTL. If a BO is private it cannot be exported via prime FD and 52 * mappings can only be created for the BO within the VM it is tied to. Lastly, 53 * the BO dma-resv slots / lock point to the VM's dma-resv slots / lock (all 54 * private BOs to a VM share common dma-resv slots / lock). 55 * 56 * External BOs 57 * ~~~~~~~~~~~~ 58 * 59 * An external BO is a user BO created with a NULL VM argument passed into the 60 * create IOCTL. An external BO can be shared with different UMDs / devices via 61 * prime FD and the BO can be mapped into multiple VMs. An external BO has its 62 * own unique dma-resv slots / lock. An external BO will be in an array of all 63 * VMs which has a mapping of the BO. This allows VMs to lookup and lock all 64 * external BOs mapped in the VM as needed. 65 * 66 * BO placement 67 * ~~~~~~~~~~~~ 68 * 69 * When a user BO is created, a mask of valid placements is passed indicating 70 * which memory regions are considered valid. 71 * 72 * The memory region information is available via query uAPI (TODO: add link). 73 * 74 * BO validation 75 * ============= 76 * 77 * BO validation (ttm_bo_validate) refers to ensuring a BO has a valid 78 * placement. If a BO was swapped to temporary storage, a validation call will 79 * trigger a move back to a valid (location where GPU can access BO) placement. 80 * Validation of a BO may evict other BOs to make room for the BO being 81 * validated. 82 * 83 * BO eviction / moving 84 * ==================== 85 * 86 * All eviction (or in other words, moving a BO from one memory location to 87 * another) is routed through TTM with a callback into XE. 88 * 89 * Runtime eviction 90 * ---------------- 91 * 92 * Runtime evictions refers to during normal operations where TTM decides it 93 * needs to move a BO. Typically this is because TTM needs to make room for 94 * another BO and the evicted BO is first BO on LRU list that is not locked. 95 * 96 * An example of this is a new BO which can only be placed in VRAM but there is 97 * not space in VRAM. There could be multiple BOs which have sysmem and VRAM 98 * placement rules which currently reside in VRAM, TTM trigger a will move of 99 * one (or multiple) of these BO(s) until there is room in VRAM to place the new 100 * BO. The evicted BO(s) are valid but still need new bindings before the BO 101 * used again (exec or compute mode rebind worker). 102 * 103 * Another example would be, TTM can't find a BO to evict which has another 104 * valid placement. In this case TTM will evict one (or multiple) unlocked BO(s) 105 * to a temporary unreachable (invalid) placement. The evicted BO(s) are invalid 106 * and before next use need to be moved to a valid placement and rebound. 107 * 108 * In both cases, moves of these BOs are scheduled behind the fences in the BO's 109 * dma-resv slots. 110 * 111 * WW locking tries to ensures if 2 VMs use 51% of the memory forward progress 112 * is made on both VMs. 113 * 114 * Runtime eviction uses per a GT migration engine (TODO: link to migration 115 * engine doc) to do a GPU memcpy from one location to another. 116 * 117 * Rebinds after runtime eviction 118 * ------------------------------ 119 * 120 * When BOs are moved, every mapping (VMA) of the BO needs to rebound before 121 * the BO is used again. Every VMA is added to an evicted list of its VM when 122 * the BO is moved. This is safe because of the VM locking structure (TODO: link 123 * to VM locking doc). On the next use of a VM (exec or compute mode rebind 124 * worker) the evicted VMA list is checked and rebinds are triggered. In the 125 * case of faulting VM, the rebind is done in the page fault handler. 126 * 127 * Suspend / resume eviction of VRAM 128 * --------------------------------- 129 * 130 * During device suspend / resume VRAM may lose power which means the contents 131 * of VRAM's memory is blown away. Thus BOs present in VRAM at the time of 132 * suspend must be moved to sysmem in order for their contents to be saved. 133 * 134 * A simple TTM call (ttm_resource_manager_evict_all) can move all non-pinned 135 * (user) BOs to sysmem. External BOs that are pinned need to be manually 136 * evicted with a simple loop + xe_bo_evict call. It gets a little trickier 137 * with kernel BOs. 138 * 139 * Some kernel BOs are used by the GT migration engine to do moves, thus we 140 * can't move all of the BOs via the GT migration engine. For simplity, use a 141 * TTM memcpy (CPU) to move any kernel (pinned) BO on either suspend or resume. 142 * 143 * Some kernel BOs need to be restored to the exact same physical location. TTM 144 * makes this rather easy but the caveat is the memory must be contiguous. Again 145 * for simplity, we enforce that all kernel (pinned) BOs are contiguous and 146 * restored to the same physical location. 147 * 148 * Pinned external BOs in VRAM are restored on resume via the GPU. 149 * 150 * Rebinds after suspend / resume 151 * ------------------------------ 152 * 153 * Most kernel BOs have GGTT mappings which must be restored during the resume 154 * process. All user BOs are rebound after validation on their next use. 155 * 156 * Future work 157 * =========== 158 * 159 * Trim the list of BOs which is saved / restored via TTM memcpy on suspend / 160 * resume. All we really need to save / restore via TTM memcpy is the memory 161 * required for the GuC to load and the memory for the GT migrate engine to 162 * operate. 163 * 164 * Do not require kernel BOs to be contiguous in physical memory / restored to 165 * the same physical address on resume. In all likelihood the only memory that 166 * needs to be restored to the same physical address is memory used for page 167 * tables. All of that memory is allocated 1 page at time so the contiguous 168 * requirement isn't needed. Some work on the vmap code would need to be done if 169 * kernel BOs are not contiguous too. 170 * 171 * Make some kernel BO evictable rather than pinned. An example of this would be 172 * engine state, in all likelihood if the dma-slots of these BOs where properly 173 * used rather than pinning we could safely evict + rebind these BOs as needed. 174 * 175 * Some kernel BOs do not need to be restored on resume (e.g. GuC ADS as that is 176 * repopulated on resume), add flag to mark such objects as no save / restore. 177 */ 178 179 #endif 180