180 lines · c
1/* SPDX-License-Identifier: MIT */2/*3 * Copyright © 2022 Intel Corporation4 */5 6#ifndef _XE_BO_DOC_H_7#define _XE_BO_DOC_H_8 9/**10 * DOC: Buffer Objects (BO)11 *12 * BO management13 * =============14 *15 * TTM manages (placement, eviction, etc...) all BOs in XE.16 *17 * BO creation18 * ===========19 *20 * Create a chunk of memory which can be used by the GPU. Placement rules21 * (sysmem or vram region) passed in upon creation. TTM handles placement of BO22 * and can trigger eviction of other BOs to make space for the new BO.23 *24 * Kernel BOs25 * ----------26 *27 * A kernel BO is created as part of driver load (e.g. uC firmware images, GuC28 * ADS, etc...) or a BO created as part of a user operation which requires29 * a kernel BO (e.g. engine state, memory for page tables, etc...). These BOs30 * are typically mapped in the GGTT (any kernel BOs aside memory for page tables31 * are in the GGTT), are pinned (can't move or be evicted at runtime), have a32 * vmap (XE can access the memory via xe_map layer) and have contiguous physical33 * memory.34 *35 * More details of why kernel BOs are pinned and contiguous below.36 *37 * User BOs38 * --------39 *40 * A user BO is created via the DRM_IOCTL_XE_GEM_CREATE IOCTL. Once it is41 * created the BO can be mmap'd (via DRM_IOCTL_XE_GEM_MMAP_OFFSET) for user42 * access and it can be bound for GPU access (via DRM_IOCTL_XE_VM_BIND). All43 * user BOs are evictable and user BOs are never pinned by XE. The allocation of44 * the backing store can be defered from creation time until first use which is45 * either mmap, bind, or pagefault.46 *47 * Private BOs48 * ~~~~~~~~~~~49 *50 * A private BO is a user BO created with a valid VM argument passed into the51 * create IOCTL. If a BO is private it cannot be exported via prime FD and52 * 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 (all54 * private BOs to a VM share common dma-resv slots / lock).55 *56 * External BOs57 * ~~~~~~~~~~~~58 *59 * An external BO is a user BO created with a NULL VM argument passed into the60 * create IOCTL. An external BO can be shared with different UMDs / devices via61 * prime FD and the BO can be mapped into multiple VMs. An external BO has its62 * own unique dma-resv slots / lock. An external BO will be in an array of all63 * VMs which has a mapping of the BO. This allows VMs to lookup and lock all64 * external BOs mapped in the VM as needed.65 *66 * BO placement67 * ~~~~~~~~~~~~68 *69 * When a user BO is created, a mask of valid placements is passed indicating70 * which memory regions are considered valid.71 *72 * The memory region information is available via query uAPI (TODO: add link).73 *74 * BO validation75 * =============76 *77 * BO validation (ttm_bo_validate) refers to ensuring a BO has a valid78 * placement. If a BO was swapped to temporary storage, a validation call will79 * 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 being81 * validated.82 *83 * BO eviction / moving84 * ====================85 *86 * All eviction (or in other words, moving a BO from one memory location to87 * another) is routed through TTM with a callback into XE.88 *89 * Runtime eviction90 * ----------------91 *92 * Runtime evictions refers to during normal operations where TTM decides it93 * needs to move a BO. Typically this is because TTM needs to make room for94 * 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 is97 * not space in VRAM. There could be multiple BOs which have sysmem and VRAM98 * placement rules which currently reside in VRAM, TTM trigger a will move of99 * one (or multiple) of these BO(s) until there is room in VRAM to place the new100 * BO. The evicted BO(s) are valid but still need new bindings before the BO101 * used again (exec or compute mode rebind worker).102 *103 * Another example would be, TTM can't find a BO to evict which has another104 * 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 invalid106 * 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's109 * dma-resv slots.110 *111 * WW locking tries to ensures if 2 VMs use 51% of the memory forward progress112 * is made on both VMs.113 *114 * Runtime eviction uses per a GT migration engine (TODO: link to migration115 * engine doc) to do a GPU memcpy from one location to another.116 *117 * Rebinds after runtime eviction118 * ------------------------------119 *120 * When BOs are moved, every mapping (VMA) of the BO needs to rebound before121 * the BO is used again. Every VMA is added to an evicted list of its VM when122 * the BO is moved. This is safe because of the VM locking structure (TODO: link123 * to VM locking doc). On the next use of a VM (exec or compute mode rebind124 * worker) the evicted VMA list is checked and rebinds are triggered. In the125 * case of faulting VM, the rebind is done in the page fault handler.126 *127 * Suspend / resume eviction of VRAM128 * ---------------------------------129 *130 * During device suspend / resume VRAM may lose power which means the contents131 * of VRAM's memory is blown away. Thus BOs present in VRAM at the time of132 * 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-pinned135 * (user) BOs to sysmem. External BOs that are pinned need to be manually136 * evicted with a simple loop + xe_bo_evict call. It gets a little trickier137 * with kernel BOs.138 *139 * Some kernel BOs are used by the GT migration engine to do moves, thus we140 * can't move all of the BOs via the GT migration engine. For simplity, use a141 * 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. TTM144 * makes this rather easy but the caveat is the memory must be contiguous. Again145 * for simplity, we enforce that all kernel (pinned) BOs are contiguous and146 * 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 / resume151 * ------------------------------152 *153 * Most kernel BOs have GGTT mappings which must be restored during the resume154 * process. All user BOs are rebound after validation on their next use.155 *156 * Future work157 * ===========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 memory161 * required for the GuC to load and the memory for the GT migrate engine to162 * operate.163 *164 * Do not require kernel BOs to be contiguous in physical memory / restored to165 * the same physical address on resume. In all likelihood the only memory that166 * needs to be restored to the same physical address is memory used for page167 * tables. All of that memory is allocated 1 page at time so the contiguous168 * requirement isn't needed. Some work on the vmap code would need to be done if169 * kernel BOs are not contiguous too.170 *171 * Make some kernel BO evictable rather than pinned. An example of this would be172 * engine state, in all likelihood if the dma-slots of these BOs where properly173 * 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 is176 * repopulated on resume), add flag to mark such objects as no save / restore.177 */178 179#endif180