drivers/gpu/drm/xe/xe_bo_doc.h

Source file repositories/reference/linux-study-clean/drivers/gpu/drm/xe/xe_bo_doc.h

File Facts

System
Linux kernel
Corpus path
drivers/gpu/drm/xe/xe_bo_doc.h
Extension
.h
Size
7665 bytes
Lines
180
Domain
Driver Families
Bucket
drivers/gpu
Inferred role
Driver Families: implementation source
Status
source implementation candidate

Why This File Exists

Repeatable hardware-adapter layer. Deep compatibility for every driver is out of scope; this atlas records patterns, probe lifecycles, bus glue, IRQ/DMA usage, and links back to core abstractions.

Dependency Surface

Detected Declarations

Annotated Snippet

#ifndef _XE_BO_DOC_H_
#define _XE_BO_DOC_H_

/**
 * DOC: Buffer Objects (BO)
 *
 * BO management
 * =============
 *
 * TTM manages (placement, eviction, etc...) all BOs in Xe.
 *
 * BO creation
 * ===========
 *
 * Create a chunk of memory which can be used by the GPU. Placement rules
 * (sysmem or vram region) passed in upon creation. TTM handles placement of BO
 * and can trigger eviction of other BOs to make space for the new BO.
 *
 * Kernel BOs
 * ----------
 *
 * A kernel BO is created as part of driver load (e.g. uC firmware images, GuC
 * ADS, etc...) or a BO created as part of a user operation which requires
 * a kernel BO (e.g. engine state, memory for page tables, etc...). These BOs
 * are typically mapped in the GGTT (any kernel BOs aside memory for page tables
 * are in the GGTT), are pinned (can't move or be evicted at runtime), have a
 * vmap (Xe can access the memory via xe_map layer) and have contiguous physical
 * memory.
 *
 * More details of why kernel BOs are pinned and contiguous below.
 *
 * User BOs
 * --------
 *
 * A user BO is created via the DRM_IOCTL_XE_GEM_CREATE IOCTL. Once it is
 * created the BO can be mmap'd (via DRM_IOCTL_XE_GEM_MMAP_OFFSET) for user
 * access and it can be bound for GPU access (via DRM_IOCTL_XE_VM_BIND). All
 * user BOs are evictable and user BOs are never pinned by Xe. The allocation of
 * the backing store can be deferred from creation time until first use which is
 * either mmap, bind, or pagefault.
 *
 * Private BOs
 * ~~~~~~~~~~~
 *
 * A private BO is a user BO created with a valid VM argument passed into the
 * create IOCTL. If a BO is private it cannot be exported via prime FD and
 * mappings can only be created for the BO within the VM it is tied to. Lastly,
 * the BO dma-resv slots / lock point to the VM's dma-resv slots / lock (all
 * private BOs to a VM share common dma-resv slots / lock).
 *
 * External BOs
 * ~~~~~~~~~~~~
 *
 * An external BO is a user BO created with a NULL VM argument passed into the
 * create IOCTL. An external BO can be shared with different UMDs / devices via
 * prime FD and the BO can be mapped into multiple VMs. An external BO has its
 * own unique dma-resv slots / lock. An external BO will be in an array of all
 * VMs which has a mapping of the BO. This allows VMs to lookup and lock all
 * external BOs mapped in the VM as needed.
 *
 * BO placement
 * ~~~~~~~~~~~~
 *
 * When a user BO is created, a mask of valid placements is passed indicating
 * which memory regions are considered valid.
 *
 * The memory region information is available via query uAPI (TODO: add link).
 *
 * BO validation
 * =============
 *
 * BO validation (ttm_bo_validate) refers to ensuring a BO has a valid
 * placement. If a BO was swapped to temporary storage, a validation call will
 * trigger a move back to a valid (location where GPU can access BO) placement.
 * Validation of a BO may evict other BOs to make room for the BO being
 * validated.
 *
 * BO eviction / moving
 * ====================
 *
 * All eviction (or in other words, moving a BO from one memory location to
 * another) is routed through TTM with a callback into Xe.
 *
 * Runtime eviction
 * ----------------
 *
 * Runtime evictions refers to during normal operations where TTM decides it
 * needs to move a BO. Typically this is because TTM needs to make room for
 * another BO and the evicted BO is first BO on LRU list that is not locked.
 *

Annotation

Implementation Notes