DRM Memory Management

DRM memory management와 TTM·GEM의 차이

현대 Linux system은 framebuffer, texture, vertex와 기타 graphics data를 저장하기 위해 많은 graphics memory가 필요합니다. 이 data는 매우 동적이므로 graphics memory를 효율적으로 관리하는 일은 graphics stack에 필수적이며 DRM infrastructure의 중심 역할을 합니다.

DRM core에는 Translation Table Manager(TTM)와 Graphics Execution Manager(GEM) 두 memory manager가 있습니다. 먼저 개발된 TTM은 모든 hardware 요구를 하나의 userspace API로 수용하는 범용 해법을 목표로 했습니다. Unified Memory Architecture(UMA) device와 전용 video RAM을 가진 대부분의 discrete video card를 모두 지원하지만, 그 결과 code가 크고 복잡해져 driver 개발에 사용하기 어려웠습니다.

GEM은 TTM의 복잡성에 대응해 Intel이 후원한 project로 시작했습니다. 모든 graphics memory 문제를 해결하는 대신 driver 사이의 공통 code를 찾아 공유 support library로 만들었습니다. 초기화와 실행 요구사항은 TTM보다 단순하지만 video RAM 관리 기능이 없어 UMA device로 제한됩니다.

=====================
DRM Memory Management
=====================

Modern Linux systems require large amount of graphics memory to store
frame buffers, textures, vertices and other graphics-related data. Given
the very dynamic nature of many of that data, managing graphics memory
efficiently is thus crucial for the graphics stack and plays a central
role in the DRM infrastructure.

The DRM core includes two memory managers, namely Translation Table Manager
(TTM) and Graphics Execution Manager (GEM). TTM was the first DRM memory
manager to be developed and tried to be a one-size-fits-them all
solution. It provides a single userspace API to accommodate the need of
all hardware, supporting both Unified Memory Architecture (UMA) devices
and devices with dedicated video RAM (i.e. most discrete video cards).
This resulted in a large, complex piece of code that turned out to be
hard to use for driver development.

GEM started as an Intel-sponsored project in reaction to TTM's
complexity. Its design philosophy is completely different: instead of
providing a solution to every graphics memory-related problems, GEM
identified common code between drivers and created a support library to
share it. GEM has simpler initialization and execution requirements than
TTM, but has no video RAM management capabilities and is thus limited to
UMA devices.

TTM device, placement, resource, TT와 page pool

TTM reference는 module 개요와 caching interface를 시작으로 device object, resource placement, resource object, translation table(TT) object, page pool을 문서화합니다.

각 영역은 header의 `:internal:` declaration과 구현 file의 `:export:` API를 짝지어 제공합니다. Placement는 memory domain 선택 조건을, resource object는 할당된 memory resource를, TT와 pool은 backing page와 page 재사용을 담당하는 interface를 구성합니다.

The Translation Table Manager (TTM)
===================================

.. kernel-doc:: drivers/gpu/drm/ttm/ttm_module.c
   :doc: TTM

.. kernel-doc:: include/drm/ttm/ttm_caching.h
   :internal:

TTM device object reference
---------------------------

.. kernel-doc:: include/drm/ttm/ttm_device.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/ttm/ttm_device.c
   :export:

TTM resource placement reference
--------------------------------

.. kernel-doc:: include/drm/ttm/ttm_placement.h
   :internal:

TTM resource object reference
-----------------------------

.. kernel-doc:: include/drm/ttm/ttm_resource.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/ttm/ttm_resource.c
   :export:

TTM TT object reference
-----------------------

.. kernel-doc:: include/drm/ttm/ttm_tt.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/ttm/ttm_tt.c
   :export:

TTM page pool reference
-----------------------

.. kernel-doc:: include/drm/ttm/ttm_pool.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/ttm/ttm_pool.c
   :export:

GEM operation과 초기화

GEM은 userspace·kernel API에서 모든 use case를 완전히 다루지 않습니다. Userspace에는 표준 memory operation을, driver에는 helper function을 제공하고 hardware-specific operation은 driver의 private API로 구현하게 합니다.

Userspace API는 LWN의 `GEM - the Graphics Execution Manager <http://lwn.net/Articles/283798/>` 문서에 설명되어 있습니다. 다소 오래되었지만 GEM API 원칙을 잘 보여 줍니다. 공통 GEM API의 일부로 기술된 buffer allocation과 read/write operation은 현재 driver-specific ioctl로 구현됩니다.

GEM은 data 내용을 알지 못한 채 추상 buffer object를 관리합니다. 따라서 buffer allocation이나 synchronization primitive처럼 내용·목적을 알아야 하는 API는 GEM 범위 밖이며 driver-specific ioctl로 구현해야 합니다.

기본 GEM operation은 memory allocation·free, command execution, command 실행 시 aperture 관리입니다. Buffer object backing memory는 주로 Linux shmem layer가 제공합니다. Command execution, pinning, buffer read/write, mapping, domain ownership transfer 같은 device-specific operation은 driver-specific ioctl에 맡깁니다.

GEM driver는 `struct drm_driver`의 `driver_features` field에 `DRIVER_GEM` bit를 설정해야 합니다. 그러면 DRM core가 load operation 전에 GEM core를 자동 초기화하고 object allocation용 address space pool을 제공하는 DRM Memory Manager object를 만듭니다.

KMS configuration에서는 hardware가 요구하면 core GEM 초기화 뒤 command ring buffer를 할당·초기화해야 합니다. UMA device의 초기 framebuffer와 큰 contiguous region을 제공하는 이른바 stolen memory는 보통 GEM이 관리하지 않으므로 별도의 DRM MM object로 초기화해야 합니다.

The Graphics Execution Manager (GEM)
====================================

The GEM design approach has resulted in a memory manager that doesn't
provide full coverage of all (or even all common) use cases in its
userspace or kernel API. GEM exposes a set of standard memory-related
operations to userspace and a set of helper functions to drivers, and
let drivers implement hardware-specific operations with their own
private API.

The GEM userspace API is described in the `GEM - the Graphics Execution
Manager <http://lwn.net/Articles/283798/>`__ article on LWN. While
slightly outdated, the document provides a good overview of the GEM API
principles. Buffer allocation and read and write operations, described
as part of the common GEM API, are currently implemented using
driver-specific ioctls.

GEM is data-agnostic. It manages abstract buffer objects without knowing
what individual buffers contain. APIs that require knowledge of buffer
contents or purpose, such as buffer allocation or synchronization
primitives, are thus outside of the scope of GEM and must be implemented
using driver-specific ioctls.

On a fundamental level, GEM involves several operations:

-  Memory allocation and freeing
-  Command execution
-  Aperture management at command execution time

Buffer object allocation is relatively straightforward and largely
provided by Linux's shmem layer, which provides memory to back each
object.

Device-specific operations, such as command execution, pinning, buffer
read & write, mapping, and domain ownership transfers are left to
driver-specific ioctls.

GEM Initialization
------------------

Drivers that use GEM must set the DRIVER_GEM bit in the struct
:c:type:`struct drm_driver <drm_driver>` driver_features
field. The DRM core will then automatically initialize the GEM core
before calling the load operation. Behind the scene, this will create a
DRM Memory Manager object which provides an address space pool for
object allocation.

In a KMS configuration, drivers need to allocate and initialize a
command ring buffer following core GEM initialization if required by the
hardware. UMA devices usually have what is called a "stolen" memory
region, which provides space for the initial framebuffer and large,
contiguous memory regions required by the device. This space is
typically not managed by GEM, and must be initialized separately into
its own DRM MM object.

GEM object 생성, backing storage와 수명

GEM은 object 생성과 object를 뒷받침하는 memory allocation을 서로 다른 operation으로 나눕니다. GEM object는 `struct drm_gem_object`로 표현되며 driver는 private 정보를 추가하기 위해 이 구조체를 embed한 driver-specific object type을 만드는 것이 일반적입니다.

Driver는 고유 object type의 instance를 할당하고 `drm_gem_object_init()`에 DRM device, GEM object pointer, byte 단위 buffer size를 전달해 embed한 base object를 초기화합니다.

GEM은 shmem으로 anonymous pageable memory를 할당합니다. `drm_gem_object_init()`은 요청 크기의 shmfs file을 만들어 `drm_gem_object.filp`에 저장합니다. Graphics hardware가 system memory를 직접 쓰면 main storage가 되고, 그렇지 않으면 backing store가 됩니다.

실제 physical page는 driver가 각 page에 `shmem_read_mapping_page_gfp()`를 호출해 할당합니다. Object 초기화 때 즉시 할당하거나 userspace access의 page fault 또는 DMA transfer 시작처럼 memory가 필요할 때까지 지연할 수 있습니다.

Embedded device처럼 physically contiguous system memory가 필요하면 anonymous pageable memory가 적합하지 않을 수 있습니다. 이 경우 `drm_gem_private_object_init()`으로 shmfs backing이 없는 private GEM object를 만들며 storage는 driver가 관리해야 합니다.

모든 GEM object는 core가 reference count를 관리합니다. `drm_gem_object_get()`으로 reference를 얻고 `drm_gem_object_put()`으로 해제합니다. 마지막 reference가 사라지면 core가 mandatory `gem_object_funcs.free` operation을 호출합니다.

`void (*free)(struct drm_gem_object *obj);` callback은 object와 모든 관련 resource를 해제해야 합니다. 여기에는 GEM core가 만든 resource도 포함되며 `drm_gem_object_release()`로 정리해야 합니다.

GEM Objects Creation
--------------------

GEM splits creation of GEM objects and allocation of the memory that
backs them in two distinct operations.

GEM objects are represented by an instance of struct :c:type:`struct
drm_gem_object <drm_gem_object>`. Drivers usually need to
extend GEM objects with private information and thus create a
driver-specific GEM object structure type that embeds an instance of
struct :c:type:`struct drm_gem_object <drm_gem_object>`.

To create a GEM object, a driver allocates memory for an instance of its
specific GEM object type and initializes the embedded struct
:c:type:`struct drm_gem_object <drm_gem_object>` with a call
to drm_gem_object_init(). The function takes a pointer
to the DRM device, a pointer to the GEM object and the buffer object
size in bytes.

GEM uses shmem to allocate anonymous pageable memory.
drm_gem_object_init() will create an shmfs file of the
requested size and store it into the struct :c:type:`struct
drm_gem_object <drm_gem_object>` filp field. The memory is
used as either main storage for the object when the graphics hardware
uses system memory directly or as a backing store otherwise.

Drivers are responsible for the actual physical pages allocation by
calling shmem_read_mapping_page_gfp() for each page.
Note that they can decide to allocate pages when initializing the GEM
object, or to delay allocation until the memory is needed (for instance
when a page fault occurs as a result of a userspace memory access or
when the driver needs to start a DMA transfer involving the memory).

Anonymous pageable memory allocation is not always desired, for instance
when the hardware requires physically contiguous system memory as is
often the case in embedded devices. Drivers can create GEM objects with
no shmfs backing (called private GEM objects) by initializing them with a call
to drm_gem_private_object_init() instead of drm_gem_object_init(). Storage for
private GEM objects must be managed by drivers.

GEM Objects Lifetime
--------------------

All GEM objects are reference-counted by the GEM core. References can be
acquired and release by calling drm_gem_object_get() and drm_gem_object_put()
respectively.

When the last reference to a GEM object is released the GEM core calls
the :c:type:`struct drm_gem_object_funcs <gem_object_funcs>` free
operation. That operation is mandatory for GEM-enabled drivers and must
free the GEM object and all associated resources.

void (\*free) (struct drm_gem_object \*obj); Drivers are
responsible for freeing all GEM object resources. This includes the
resources created by the GEM core, which need to be released with
drm_gem_object_release().

Handle·name·PRIME과 userspace mapping

Userspace와 kernel은 local handle, global name, 최근에는 file descriptor로 GEM object를 참조합니다. 모두 32-bit integer이고 file descriptor에는 일반 Linux kernel 제한이 적용됩니다.

GEM handle은 DRM file에 local합니다. Application은 driver-specific ioctl로 handle을 얻고 다른 표준·driver ioctl에서 object를 참조합니다. DRM file을 닫으면 모든 GEM handle이 해제되고 관련 object reference도 감소합니다.

Driver는 `drm_gem_handle_create()`로 locally unique handle을 만들고 `drm_gem_handle_delete()`로 삭제하며 `drm_gem_object_lookup()`으로 handle의 object를 찾습니다. Handle은 object를 소유하지 않고 reference만 잡습니다. Leak을 막으려면 driver가 소유한 초기 reference 등을 별도로 내려야 하며, `dumb_create`에서 object와 handle을 함께 만들 때도 handle을 반환하기 전에 초기 reference를 내려야 합니다.

GEM name은 DRM file에 local하지 않아 process 사이에서 global object reference로 전달할 수 있습니다. DRM API에서 직접 쓰지 못하므로 `DRM_IOCTL_GEM_FLINK`로 handle을 name으로, `DRM_IOCTL_GEM_OPEN`으로 name을 handle로 변환합니다. 이 변환은 driver 지원 없이 DRM core가 처리합니다.

GEM은 PRIME을 통해 dma-buf file descriptor 기반 buffer sharing도 지원합니다. Driver는 제공된 helper로 export/import를 올바르게 구현해야 합니다. 상세 참조는 원문에도 `?`로 남아 있습니다. File descriptor 공유는 추측하기 쉬운 global GEM name보다 본질적으로 안전하고 cross-device sharing도 지원하므로 선호됩니다. GEM name sharing은 legacy userspace에만 지원됩니다.

Mapping은 비용이 크므로 GEM은 random access가 꼭 필요하지 않다면 driver-specific ioctl의 read/write 방식 접근을 선호합니다. GEM object는 자체 file handle이 없어 `mmap()`으로 직접 mapping할 수 없습니다. Driver ioctl 내부에서 `do_mmap()`을 부르는 첫 방식은 새 driver에서 권장되지 않아 이 문서가 설명하지 않습니다.

두 번째 방식은 DRM file handle에 `mmap()`을 호출하고 offset argument로 fake offset을 전달합니다. Mapping 전에 `drm_gem_create_mmap_offset()`으로 object에 fake offset을 연결하고 그 값을 driver-specific 방식으로 application에 전달해야 합니다.

Core helper `drm_gem_mmap()`은 offset으로 object를 찾아 VMA operation을 `drm_driver.gem_vm_ops`로 설정합니다. Memory를 즉시 userspace에 mapping하지 않고 driver fault handler가 page를 하나씩 mapping하게 합니다. Driver는 `gem_vm_ops`에 다음 `struct vm_operations_struct`를 제공해야 합니다.

struct vm_operations_struct {
    void (*open)(struct vm_area_struct *area);
    void (*close)(struct vm_area_struct *area);
    vm_fault_t (*fault)(struct vm_fault *vmf);
};

`open`과 `close` operation은 GEM object reference count를 갱신해야 하며 `drm_gem_vm_open()`과 `drm_gem_vm_close()` helper를 직접 handler로 사용할 수 있습니다. `fault` handler는 page fault 때 개별 page를 userspace에 mapping하고 allocation 정책에 따라 fault 시점 또는 object 생성 시점에 page를 할당합니다.

Page fault 대신 object 전체를 미리 mapping하려는 driver는 자체 mmap file operation을 구현할 수 있습니다. MMU가 없는 platform에서는 `drm_gem_dma_get_unmapped_area()`가 제안 mapping address를 제공하며 `file_operations.get_unmapped_area`가 이 함수를 가리켜야 합니다. 상세 정보는 `Documentation/admin-guide/mm/nommu-mmap.rst`에 있습니다.

GEM Objects Naming
------------------

Communication between userspace and the kernel refers to GEM objects
using local handles, global names or, more recently, file descriptors.
All of those are 32-bit integer values; the usual Linux kernel limits
apply to the file descriptors.

GEM handles are local to a DRM file. Applications get a handle to a GEM
object through a driver-specific ioctl, and can use that handle to refer
to the GEM object in other standard or driver-specific ioctls. Closing a
DRM file handle frees all its GEM handles and dereferences the
associated GEM objects.

To create a handle for a GEM object drivers call drm_gem_handle_create(). The
function takes a pointer to the DRM file and the GEM object and returns a
locally unique handle.  When the handle is no longer needed drivers delete it
with a call to drm_gem_handle_delete(). Finally the GEM object associated with a
handle can be retrieved by a call to drm_gem_object_lookup().

Handles don't take ownership of GEM objects, they only take a reference
to the object that will be dropped when the handle is destroyed. To
avoid leaking GEM objects, drivers must make sure they drop the
reference(s) they own (such as the initial reference taken at object
creation time) as appropriate, without any special consideration for the
handle. For example, in the particular case of combined GEM object and
handle creation in the implementation of the dumb_create operation,
drivers must drop the initial reference to the GEM object before
returning the handle.

GEM names are similar in purpose to handles but are not local to DRM
files. They can be passed between processes to reference a GEM object
globally. Names can't be used directly to refer to objects in the DRM
API, applications must convert handles to names and names to handles
using the DRM_IOCTL_GEM_FLINK and DRM_IOCTL_GEM_OPEN ioctls
respectively. The conversion is handled by the DRM core without any
driver-specific support.

GEM also supports buffer sharing with dma-buf file descriptors through
PRIME. GEM-based drivers must use the provided helpers functions to
implement the exporting and importing correctly. See ?. Since sharing
file descriptors is inherently more secure than the easily guessable and
global GEM names it is the preferred buffer sharing mechanism. Sharing
buffers through GEM names is only supported for legacy userspace.
Furthermore PRIME also allows cross-device buffer sharing since it is
based on dma-bufs.

GEM Objects Mapping
-------------------

Because mapping operations are fairly heavyweight GEM favours
read/write-like access to buffers, implemented through driver-specific
ioctls, over mapping buffers to userspace. However, when random access
to the buffer is needed (to perform software rendering for instance),
direct access to the object can be more efficient.

The mmap system call can't be used directly to map GEM objects, as they
don't have their own file handle. Two alternative methods currently
co-exist to map GEM objects to userspace. The first method uses a
driver-specific ioctl to perform the mapping operation, calling
do_mmap() under the hood. This is often considered
dubious, seems to be discouraged for new GEM-enabled drivers, and will
thus not be described here.

The second method uses the mmap system call on the DRM file handle. void
\*mmap(void \*addr, size_t length, int prot, int flags, int fd, off_t
offset); DRM identifies the GEM object to be mapped by a fake offset
passed through the mmap offset argument. Prior to being mapped, a GEM
object must thus be associated with a fake offset. To do so, drivers
must call drm_gem_create_mmap_offset() on the object.

Once allocated, the fake offset value must be passed to the application
in a driver-specific way and can then be used as the mmap offset
argument.

The GEM core provides a helper method drm_gem_mmap() to
handle object mapping. The method can be set directly as the mmap file
operation handler. It will look up the GEM object based on the offset
value and set the VMA operations to the :c:type:`struct drm_driver
<drm_driver>` gem_vm_ops field. Note that drm_gem_mmap() doesn't map memory to
userspace, but relies on the driver-provided fault handler to map pages
individually.

To use drm_gem_mmap(), drivers must fill the struct :c:type:`struct drm_driver
<drm_driver>` gem_vm_ops field with a pointer to VM operations.

The VM operations is a :c:type:`struct vm_operations_struct <vm_operations_struct>`
made up of several fields, the more interesting ones being:

.. code-block:: c

        struct vm_operations_struct {
                void (*open)(struct vm_area_struct * area);
                void (*close)(struct vm_area_struct * area);
                vm_fault_t (*fault)(struct vm_fault *vmf);
        };


The open and close operations must update the GEM object reference
count. Drivers can use the drm_gem_vm_open() and drm_gem_vm_close() helper
functions directly as open and close handlers.

The fault operation handler is responsible for mapping individual pages
to userspace when a page fault occurs. Depending on the memory
allocation scheme, drivers can allocate pages at fault time, or can
decide to allocate memory for the GEM object at the time the object is
created.

Drivers that want to map the GEM object upfront instead of handling page
faults can implement their own mmap file operation handler.

For platforms without MMU the GEM core provides a helper method
drm_gem_dma_get_unmapped_area(). The mmap() routines will call this to get a
proposed address for the mapping.

To use drm_gem_dma_get_unmapped_area(), drivers must fill the struct
:c:type:`struct file_operations <file_operations>` get_unmapped_area field with
a pointer on drm_gem_dma_get_unmapped_area().

More detailed information about get_unmapped_area can be found in
Documentation/admin-guide/mm/nommu-mmap.rst

CPU·GPU coherency와 command execution

Object를 device에 mapping하거나 command buffer에서 사용할 때 backing page를 memory로 flush하고 write-combined로 표시해 GPU와 coherent하게 만듭니다. GPU rendering이 끝난 뒤 CPU가 object에 접근하면 GPU cache flush 등을 통해 CPU의 memory view와도 coherent하게 해야 합니다.

이 CPU↔GPU coherency 관리는 device-specific ioctl이 object의 현재 domain을 평가하고 필요한 flush·synchronization을 수행해 목표 coherency domain으로 옮깁니다. Object가 active render target이라 busy하면 domain 설정은 client를 block하고 rendering 완료를 기다린 뒤 flush합니다.

GPU device에서 가장 중요한 GEM 기능 중 하나는 client에 command execution interface를 제공하는 것입니다. Client가 기존 memory object reference를 담은 command buffer를 구성해 제출하면 GEM은 모든 object를 GTT에 bind하고 buffer를 실행하며 같은 buffer를 공유하는 client 사이를 동기화합니다.

이 과정에서 GTT object를 evict·rebind하고 fixed GTT offset을 client에서 숨기는 relocation을 제공할 수 있으며 비용이 큽니다. Command buffer가 GTT에 들어갈 수 있는 것보다 많은 object를 참조하면 GEM이 거부해 rendering이 일어나지 않습니다. Pre-965 2D blit처럼 fence register가 필요한 object도 사용 가능한 register 수를 넘으면 안 됩니다. 이런 resource 관리는 `libdrm`이 client에게서 추상화해야 합니다.

Memory Coherency
----------------

When mapped to the device or used in a command buffer, backing pages for
an object are flushed to memory and marked write combined so as to be
coherent with the GPU. Likewise, if the CPU accesses an object after the
GPU has finished rendering to the object, then the object must be made
coherent with the CPU's view of memory, usually involving GPU cache
flushing of various kinds. This core CPU<->GPU coherency management is
provided by a device-specific ioctl, which evaluates an object's current
domain and performs any necessary flushing or synchronization to put the
object into the desired coherency domain (note that the object may be
busy, i.e. an active render target; in that case, setting the domain
blocks the client and waits for rendering to complete before performing
any necessary flushing operations).

Command Execution
-----------------

Perhaps the most important GEM function for GPU devices is providing a
command execution interface to clients. Client programs construct
command buffers containing references to previously allocated memory
objects, and then submit them to GEM. At that point, GEM takes care to
bind all the objects into the GTT, execute the buffer, and provide
necessary synchronization between clients accessing the same buffers.
This often involves evicting some objects from the GTT and re-binding
others (a fairly expensive operation), and providing relocation support
which hides fixed GTT offsets from clients. Clients must take care not
to submit command buffers that reference more objects than can fit in
the GTT; otherwise, GEM will reject them and no rendering will occur.
Similarly, if several objects in the buffer require fence registers to
be allocated for correct rendering (e.g. 2D blits on pre-965 chips),
care must be taken not to require more fence registers than are
available to the client. Such resource management should be abstracted
from the client in libdrm.

GEM helper와 VMA offset manager

GEM function reference는 core object API와 DMA, SHMEM, VRAM, TTM-backed GEM helper를 구분합니다. 각 helper군은 구현 overview, header 내부 interface, exported API를 조합합니다.

VMA offset manager는 GEM object mapping에 쓰는 fake offset address space를 관리합니다. `drm_vma_manager.c`의 overview·exported API와 `drm_vma_manager.h` 내부 interface가 연결됩니다.

GEM Function Reference
----------------------

.. kernel-doc:: include/drm/drm_gem.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_gem.c
   :export:

GEM DMA Helper Functions Reference
----------------------------------

.. kernel-doc:: drivers/gpu/drm/drm_gem_dma_helper.c
   :doc: dma helpers

.. kernel-doc:: include/drm/drm_gem_dma_helper.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_gem_dma_helper.c
   :export:

GEM SHMEM Helper Function Reference
-----------------------------------

.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
   :doc: overview

.. kernel-doc:: include/drm/drm_gem_shmem_helper.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_gem_shmem_helper.c
   :export:

GEM VRAM Helper Functions Reference
-----------------------------------

.. kernel-doc:: drivers/gpu/drm/drm_gem_vram_helper.c
   :doc: overview

.. kernel-doc:: include/drm/drm_gem_vram_helper.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_gem_vram_helper.c
   :export:

GEM TTM Helper Functions Reference
-----------------------------------

.. kernel-doc:: drivers/gpu/drm/drm_gem_ttm_helper.c
   :doc: overview

.. kernel-doc:: drivers/gpu/drm/drm_gem_ttm_helper.c
   :export:

VMA Offset Manager
==================

.. kernel-doc:: drivers/gpu/drm/drm_vma_manager.c
   :doc: vma offset manager

.. kernel-doc:: include/drm/drm_vma_manager.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_vma_manager.c
   :export:

.. _prime_buffer_sharing:

PRIME sharing과 DRM MM range allocator

PRIME은 원래 multi-GPU OPTIMUS platform을 위해 만들어진 DRM의 cross-device buffer sharing framework입니다. Userspace에서 PRIME buffer는 dma-buf 기반 file descriptor입니다.

PRIME 절은 buffer export/import의 overview와 lifetime rule, helper 설명, 내부 header와 exported API를 제공합니다.

DRM MM range allocator는 address-space range 할당의 overview와 LRU scan·eviction 지원, 내부 interface와 exported API를 제공합니다.

PRIME Buffer Sharing
====================

PRIME is the cross device buffer sharing framework in drm, originally
created for the OPTIMUS range of multi-gpu platforms. To userspace PRIME
buffers are dma-buf based file descriptors.

Overview and Lifetime Rules
---------------------------

.. kernel-doc:: drivers/gpu/drm/drm_prime.c
   :doc: overview and lifetime rules

PRIME Helper Functions
----------------------

.. kernel-doc:: drivers/gpu/drm/drm_prime.c
   :doc: PRIME Helpers

PRIME Function References
-------------------------

.. kernel-doc:: include/drm/drm_prime.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_prime.c
   :export:

DRM MM Range Allocator
======================

Overview
--------

.. kernel-doc:: drivers/gpu/drm/drm_mm.c
   :doc: Overview

LRU Scan/Eviction Support
-------------------------

.. kernel-doc:: drivers/gpu/drm/drm_mm.c
   :doc: lru scan roster

DRM MM Range Allocator Function References
------------------------------------------

.. kernel-doc:: include/drm/drm_mm.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_mm.c
   :export:

.. _drm_gpuvm:

GPUVM, allocator, sync object와 scheduler

DRM GPUVM 절은 GPU virtual memory의 overview, mapping split·merge, locking, example, 내부 interface와 exported API를 제공합니다. `_drm_gpuvm`과 `_drm_gpuvm_locking` anchor로 개요와 locking 절을 직접 참조할 수 있습니다.

DRM buddy allocator는 buddy allocation API를, cache handling 절은 fast write-combined `memcpy()`를 포함한 cache helper를 제공합니다.

DRM sync object는 GPU 작업 synchronization object의 overview, 내부 interface, exported API를 문서화합니다. DRM execution context는 여러 object의 reservation·locking을 조율하는 execution helper의 overview와 API를 제공합니다.

GPU scheduler는 scheduler core overview와 flow control, scheduler header 내부 interface, main scheduler와 entity의 exported API를 제공합니다.

DRM GPUVM
=========

Overview
--------

.. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c
   :doc: Overview

Split and Merge
---------------

.. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c
   :doc: Split and Merge

.. _drm_gpuvm_locking:

Locking
-------

.. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c
   :doc: Locking

Examples
--------

.. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c
   :doc: Examples

DRM GPUVM Function References
-----------------------------

.. kernel-doc:: include/drm/drm_gpuvm.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_gpuvm.c
   :export:

DRM Buddy Allocator
===================

DRM Buddy Function References
-----------------------------

.. kernel-doc:: drivers/gpu/drm/drm_buddy.c
   :export:

DRM Cache Handling and Fast WC memcpy()
=======================================

.. kernel-doc:: drivers/gpu/drm/drm_cache.c
   :export:

.. _drm_sync_objects:

DRM Sync Objects
================

.. kernel-doc:: drivers/gpu/drm/drm_syncobj.c
   :doc: Overview

.. kernel-doc:: include/drm/drm_syncobj.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_syncobj.c
   :export:

DRM Execution context
=====================

.. kernel-doc:: drivers/gpu/drm/drm_exec.c
   :doc: Overview

.. kernel-doc:: include/drm/drm_exec.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/drm_exec.c
   :export:

GPU Scheduler
=============

Overview
--------

.. kernel-doc:: drivers/gpu/drm/scheduler/sched_main.c
   :doc: Overview

Flow Control
------------

.. kernel-doc:: drivers/gpu/drm/scheduler/sched_main.c
   :doc: Flow Control

Scheduler Function References
-----------------------------

.. kernel-doc:: include/drm/gpu_scheduler.h
   :internal:

.. kernel-doc:: drivers/gpu/drm/scheduler/sched_main.c
   :export:

.. kernel-doc:: drivers/gpu/drm/scheduler/sched_entity.c
   :export: