Documentation/gpu: VM_BIND locking document

Add the first version of the VM_BIND locking document which is
intended to be part of the xe driver upstreaming agreement.

The document describes and discuss the locking used during exec-
functions, evicton and for userptr gpu-vmas. Intention is to be using the
same nomenclature as the drm-vm-bind-async.rst.

v2:
- s/gvm/gpu_vm/g (Rodrigo Vivi)
- Clarify the userptr seqlock with a pointer to mm/mmu_notifier.c
(Rodrigo Vivi)
- Adjust commit message accordingly.
- Add SPDX license header.

v3:
- Large update to align with the drm_gpuvm manager locking
- Add "Efficient userptr gpu_vma exec function iteration" section
- Add "Locking at bind- and unbind time" section.

v4:
- Fix tabs vs space errors by untabifying (Rodrigo Vivi)
- Minor style fixes and typos (Rodrigo Vivi)
- Clarify situations where stale GPU mappings are occurring and how
access through these mappings are blocked. (Rodrigo Vivi)
- Insert into the toctree in implementation_guidelines.rst

v5:
- Add a section about recoverable page-faults.
- Use local references to other documentation where possible
(Bagas Sanjaya)
- General documentation fixes and typos (Danilo Krummrich and
Boris Brezillon)
- Improve the documentation around locks that need to be grabbed from the
dm-fence critical section (Boris Brezillon)
- Add more references to the DRM GPUVM helpers (Danilo Krummrich and
Boriz Brezillon)
- Update the rfc/xe.rst document.

v6:
- Rework wording to improve readability (Boris Brezillon, Rodrigo Vivi,
Bagas Sanjaya)
- Various minor fixes across the document (Boris Brezillon)

Cc: Rodrigo Vivi <rodrigo.vivi@intel.com>
Signed-off-by: Thomas Hellström <thomas.hellstrom@linux.intel.com>
Reviewed-by: Boris Brezillon <boris.brezillon@collabora.com>
Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Reviewed-by: Danilo Krummrich <dakr@redhat.com>
Acked-by: John Hubbard <jhubbard@nvidia.com> # Documentation/core-api/pin_user_pages.rst changes
Link: https://patchwork.freedesktop.org/patch/msgid/20231129090637.2629-1-thomas.hellstrom@linux.intel.com

drm/sched: implement dynamic job-flow control

Currently, job flow control is implemented simply by limiting the number
of jobs in flight. Therefore, a scheduler is initialized with a credit
limit that corresponds to the number of jobs which can be sent to the
hardware.

This implies that for each job, drivers need to account for the maximum
job size possible in order to not overflow the ring buffer.

However, there are drivers, such as Nouveau, where the job size has a
rather large range. For such drivers it can easily happen that job
submissions not even filling the ring by 1% can block subsequent
submissions, which, in the worst case, can lead to the ring run dry.

In order to overcome this issue, allow for tracking the actual job size
instead of the number of jobs. Therefore, add a field to track a job's
credit count, which represents the number of credits a job contributes
to the scheduler's credit limit.

Signed-off-by: Danilo Krummrich <dakr@redhat.com>
Reviewed-by: Luben Tuikov <ltuikov89@gmail.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20231110001638.71750-1-dakr@redhat.com

drm/gpuvm: doc: fix filename references

Commit f72c2db47080 ("drm/gpuvm: rename struct drm_gpuva_manager to
struct drm_gpuvm") did also change the corresponding filenames which are
referenced from the documentation, but were not adjusted accordingly.
Hence, fix up those filenames.

Fixes: f72c2db47080 ("drm/gpuvm: rename struct drm_gpuva_manager to struct drm_gpuvm")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/dri-devel/20230926150725.4cca5fc5@canb.auug.org.au/
Signed-off-by: Danilo Krummrich <dakr@redhat.com>
Acked-by: Dave Airlie <airlied@redhat.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20230926105146.10808-1-dakr@redhat.com

drm/doc: fix underline for section "DRM Sync Objects"

It doesn't line up.

Signed-off-by: Simon Ser <contact@emersion.fr>
Suggested-by: Jani Nikula <jani.nikula@intel.com>
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20230803102505.392577-1-contact@emersion.fr

drm/doc: use proper cross-references for sections

When I originally wrote these docs, I couldn't manage to insert a
cross-reference to a section. Here's how it can be done.

Signed-off-by: Simon Ser <contact@emersion.fr>
Reviewed-by: Jani Nikula <jani.nikula@intel.com>
Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Pekka Paalanen <pekka.paalanen@collabora.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20230803095734.386761-1-contact@emersion.fr

drm: manager to keep track of GPUs VA mappings

Add infrastructure to keep track of GPU virtual address (VA) mappings
with a decicated VA space manager implementation.

New UAPIs, motivated by Vulkan sparse memory bindings graphics drivers
start implementing, allow userspace applications to request multiple and
arbitrary GPU VA mappings of buffer objects. The DRM GPU VA manager is
intended to serve the following purposes in this context.

1) Provide infrastructure to track GPU VA allocations and mappings,
using an interval tree (RB-tree).

2) Generically connect GPU VA mappings to their backing buffers, in
particular DRM GEM objects.

3) Provide a common implementation to perform more complex mapping
operations on the GPU VA space. In particular splitting and merging
of GPU VA mappings, e.g. for intersecting mapping requests or partial
unmap requests.

Acked-by: Thomas Hellström <thomas.hellstrom@linux.intel.com>
Acked-by: Matthew Brost <matthew.brost@intel.com>
Reviewed-by: Boris Brezillon <boris.brezillon@collabora.com>
Tested-by: Matthew Brost <matthew.brost@intel.com>
Tested-by: Donald Robson <donald.robson@imgtec.com>
Suggested-by: Dave Airlie <airlied@redhat.com>
Signed-off-by: Danilo Krummrich <dakr@redhat.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20230720001443.2380-2-dakr@redhat.com

drm: execution context for GEM buffers v7

This adds the infrastructure for an execution context for GEM buffers
which is similar to the existing TTMs execbuf util and intended to replace
it in the long term.

The basic functionality is that we abstracts the necessary loop to lock
many different GEM buffers with automated deadlock and duplicate handling.

v2: drop xarray and use dynamic resized array instead, the locking
overhead is unnecessary and measurable.
v3: drop duplicate tracking, radeon is really the only one needing that.
v4: fixes issues pointed out by Danilo, some typos in comments and a
helper for lock arrays of GEM objects.
v5: some suggestions by Boris Brezillon, especially just use one retry
macro, drop loop in prepare_array, use flags instead of bool
v6: minor changes suggested by Thomas, Boris and Danilo
v7: minor typos pointed out by checkpatch.pl fixed

Signed-off-by: Christian König <christian.koenig@amd.com>
Reviewed-by: Boris Brezillon <boris.brezillon@collabora.com>
Reviewed-by: Danilo Krummrich <dakr@redhat.com>
Tested-by: Danilo Krummrich <dakr@redhat.com>
Acked-by: Alex Deucher <alexander.deucher@amd.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20230711133122.3710-2-christian.koenig@amd.com

drm/gem: rename GEM CMA helpers to GEM DMA helpers

Rename "GEM CMA" helpers to "GEM DMA" helpers - considering the
hierarchy of APIs (mm/cma -> dma -> gem dma) calling them "GEM
DMA" seems to be more applicable.

Besides that, commit e57924d4ae80 ("drm/doc: Task to rename CMA helpers")
requests to rename the CMA helpers and implies that people seem to be
confused about the naming.

In order to do this renaming the following script was used:

```
#!/bin/bash

DIRS="drivers/gpu include/drm Documentation/gpu"

REGEX_SYM_UPPER="[0-9A-Z_\-]"
REGEX_SYM_LOWER="[0-9a-z_\-]"

REGEX_GREP_UPPER="(${REGEX_SYM_UPPER}*)(GEM)_CMA_(${REGEX_SYM_UPPER}*)"
REGEX_GREP_LOWER="(${REGEX_SYM_LOWER}*)(gem)_cma_(${REGEX_SYM_LOWER}*)"

REGEX_SED_UPPER="s/${REGEX_GREP_UPPER}/\1\2_DMA_\3/g"
REGEX_SED_LOWER="s/${REGEX_GREP_LOWER}/\1\2_dma_\3/g"

# Find all upper case 'CMA' symbols and replace them with 'DMA'.
for ff in $(grep -REHl "${REGEX_GREP_UPPER}" $DIRS)
do
sed -i -E "$REGEX_SED_UPPER" $ff
done

# Find all lower case 'cma' symbols and replace them with 'dma'.
for ff in $(grep -REHl "${REGEX_GREP_LOWER}" $DIRS)
do
sed -i -E "$REGEX_SED_LOWER" $ff
done

# Replace all occurrences of 'CMA' / 'cma' in comments and
# documentation files with 'DMA' / 'dma'.
for ff in $(grep -RiHl " cma " $DIRS)
do
sed -i -E "s/ cma / dma /g" $ff
sed -i -E "s/ CMA / DMA /g" $ff
done

# Rename all 'cma_obj's to 'dma_obj'.
for ff in $(grep -RiHl "cma_obj" $DIRS)
do
sed -i -E "s/cma_obj/dma_obj/g" $ff
done
```

Only a few more manual modifications were needed, e.g. reverting the
following modifications in some DRM Kconfig files

- select CMA if HAVE_DMA_CONTIGUOUS
+ select DMA if HAVE_DMA_CONTIGUOUS

as well as manually picking the occurrences of 'CMA'/'cma' in comments and
documentation which relate to "GEM CMA", but not "FB CMA".

Also drivers/gpu/drm/Makefile was fixed up manually after renaming
drm_gem_cma_helper.c to drm_gem_dma_helper.c.

This patch is compile-time tested building a x86_64 kernel with
`make allyesconfig && make drivers/gpu/drm`.

Acked-by: Sam Ravnborg <sam@ravnborg.org>
Acked-by: Thomas Zimmermann <tzimmermann@suse.de>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Danilo Krummrich <dakr@redhat.com>
Reviewed-by: Liviu Dudau <liviu.dudau@arm.com> #drivers/gpu/drm/arm
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
Link: https://patchwork.freedesktop.org/patch/msgid/20220802000405.949236-4-dakr@redhat.com

drm/doc: pull in drm_buddy.c

Make sure we pull in the kernel-doc for this.

Reported-by: Daniel Vetter <daniel@ffwll.ch>
Signed-off-by: Matthew Auld <matthew.auld@intel.com>
Cc: Arunpravin <Arunpravin.PaneerSelvam@amd.com>
Cc: Christian König <christian.koenig@amd.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20220208151228.344997-1-matthew.auld@intel.com
Signed-off-by: Christian König <christian.koenig@amd.com>
Reviewed-by: Christian König <christian.koenig@amd.com>

drm/doc: Fix TTM acronym

The TTM acronym is defined for the first time in the documentation as
"Translation Table Maps". Afterwards, "Translation Table Manager" is
used as definition.

Fix the first definition to avoid confusion.

Signed-off-by: José Expósito <jose.exposito89@gmail.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20220107180230.132666-1-jose.exposito89@gmail.com

drm/ttm: enable TTM page pool kerneldoc

Fix the remaining warnings and finally enable this.

Signed-off-by: Christian König <christian.koenig@amd.com>
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210908132933.3269-9-christian.koenig@amd.com

drm/ttm: enable TTM TT object kerneldoc v2

Fix the remaining warnings and finally enable this.

v2: add caching enum link

Signed-off-by: Christian König <christian.koenig@amd.com>
Reviewed-by: Matthew Auld <matthew.auld@intel.com>
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210908132933.3269-8-christian.koenig@amd.com

drm/ttm: enable TTM placement kerneldoc

Fix the last remaining warning and finally enable this.

Signed-off-by: Christian König <christian.koenig@amd.com>
Reviewed-by: Matthew Auld <matthew.auld@intel.com>
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210908132933.3269-7-christian.koenig@amd.com

drm/ttm: enable TTM resource object kerneldoc v2

Fix the last two remaining warnings and finally enable this.

v2: add caching enum link

Signed-off-by: Christian König <christian.koenig@amd.com>
Reviewed-by: Matthew Auld <matthew.auld@intel.com>
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210908132933.3269-6-christian.koenig@amd.com

drm/ttm: enable TTM device object kerneldoc v2

Fix the remaining warnings, switch to inline structure documentation
and finally enable this.

v2: adjust based on suggestions from Alex

Signed-off-by: Christian König <christian.koenig@amd.com>
Reviewed-by: Matthew Auld <matthew.auld@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210908132933.3269-5-christian.koenig@amd.com

drm/ttm: add kerneldoc for enum ttm_caching

Briefly describe what this is all about.

Signed-off-by: Christian König <christian.koenig@amd.com>
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210908132933.3269-4-christian.koenig@amd.com

drm/ttm: add some general module kerneldoc

For now just a brief description of what TTM is all about.

Signed-off-by: Christian König <christian.koenig@amd.com>
Reviewed-by: Matthew Auld <matthew.auld@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210908132933.3269-3-christian.koenig@amd.com

drm/ttm: remove the outdated kerneldoc section

Clean up to start over with new and more accurate documentation.

Signed-off-by: Christian König <christian.koenig@amd.com>
Reviewed-by: Matthew Auld <matthew.auld@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210908132933.3269-2-christian.koenig@amd.com

drm/sched: improve docs around drm_sched_entity

I found a few too many things that are tricky and not documented, so I
started typing.

I found a few more things that looked broken while typing, see the
varios FIXME in drm_sched_entity.

Also some of the usual logics:
- actually include sched_entity.c declarations, that was lost in the
move here: 620e762f9a98 ("drm/scheduler: move entity handling into
separate file")

- Ditch the kerneldoc for internal functions, keep the comments where
they're describing more than what the function name already implies.

- Switch drm_sched_entity to inline docs.

Acked-by: Melissa Wen <mwen@igalia.com>
Reviewed-by: Boris Brezillon <boris.brezillon@collabora.com> (v1)
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Cc: Lucas Stach <l.stach@pengutronix.de>
Cc: David Airlie <airlied@linux.ie>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Maxime Ripard <mripard@kernel.org>
Cc: Thomas Zimmermann <tzimmermann@suse.de>
Cc: "Christian König" <christian.koenig@amd.com>
Cc: Boris Brezillon <boris.brezillon@collabora.com>
Cc: Steven Price <steven.price@arm.com>
Cc: Emma Anholt <emma@anholt.net>
Cc: Lee Jones <lee.jones@linaro.org>
Cc: Andrey Grodzovsky <andrey.grodzovsky@amd.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210805104705.862416-7-daniel.vetter@ffwll.ch

drm/ttm: ttm_bo_device is now ttm_device

These names were changed in

commit 8af8a109b34fa88b8b91f25d11485b37d37549c3
Author: Christian König <christian.koenig@amd.com>
Date: Thu Oct 1 14:51:40 2020 +0200

drm/ttm: device naming cleanup

But he missed a couple of them.

Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
Cc: Christian König <christian.koenig@amd.com>
Fixes: 8af8a109b34f ("drm/ttm: device naming cleanup")
Link: https://patchwork.freedesktop.org/patch/msgid/20210812203443.1725307-1-jason@jlekstrand.net
Reviewed-by: Christian König <christian.koenig@amd.com>
Signed-off-by: Christian König <christian.koenig@amd.com>

drm: Add a prefetching memcpy_from_wc

Reading out of write-combining mapped memory is typically very slow
since the CPU doesn't prefetch. However some archs have special
instructions to do this.

So add a best-effort memcpy_from_wc taking dma-buf-map pointer
arguments that attempts to use a fast prefetching memcpy and
otherwise falls back to ordinary memcopies, taking the iomem tagging
into account.

The code is largely copied from i915_memcpy_from_wc.

Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Christian König <christian.koenig@amd.com>
Suggested-by: Daniel Vetter <daniel@ffwll.ch>
Signed-off-by: Thomas Hellström <thomas.hellstrom@linux.intel.com>
Acked-by: Christian König <christian.koenig@amd.com>
Acked-by: Daniel Vetter <daniel@ffwll.ch>
Link: https://lore.kernel.org/r/20210602083818.241793-5-thomas.hellstrom@linux.intel.com
Link: https://patchwork.freedesktop.org/patch/msgid/20210602083818.241793-5-thomas.hellstrom@linux.intel.com

drm: Remove obsolete GEM and PRIME callbacks from struct drm_driver

Several GEM and PRIME callbacks have been deprecated in favor of
per-instance GEM object functions. Remove the callbacks as they are
now unused. The only exception is .gem_prime_mmap, which is still
in use by several drivers.

What is also gone is gem_vm_ops in struct drm_driver. All drivers now
use struct drm_gem_object_funcs.vm_ops instead.

While at it, the patch also improves error handling around calls
to .free and .get_sg_table callbacks.

v3:
* restore default call to drm_gem_prime_export() in
drm_gem_prime_handle_to_fd()
* return -ENOSYS if get_sg_table is not set
* drop all checks for obj->funcs
* clean up TODO list and documentation
v2:
* update related TODO item (Sam)

Signed-off-by: Thomas Zimmermann <tzimmermann@suse.de>
Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Acked-by: Christian König <christian.koenig@amd.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20200923102159.24084-23-tzimmermann@suse.de

docs: move nommu-mmap.txt to admin-guide and rename to ReST

The nommu-mmap.txt file provides description of user visible
behaviuour. So, move it to the admin-guide.

As it is already at the ReST, also rename it.

Suggested-by: Mike Rapoport <rppt@linux.ibm.com>
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/3a63d1833b513700755c85bf3bda0a6c4ab56986.1592918949.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

drm/doc: Some polish for shmem helpers

- Move the shmem helper section to the drm-mm.rst file, next to the
vram helpers. Makes a lot more sense there with the now wider scope.
Also, that's where the all the other backing storage stuff resides.
It's just the framebuffer helpers that should be in the kms helper
section.

- Try to clarify which functiosn are for implementing
drm_gem_object_funcs, and which for drivers to call directly. At
least one driver screwed that up a bit.

Cc: Gerd Hoffmann <kraxel@redhat.com>
Cc: Rob Herring <robh@kernel.org>
Cc: Noralf Trønnes <noralf@tronnes.org>
Reviewed-by: Thomas Zimmermann <tzimmermann@suse.de>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20200511093554.211493-4-daniel.vetter@ffwll.ch

drm: remove _unlocked suffix in drm_gem_object_put_unlocked

Spelling out _unlocked for each and every driver is a annoying.
Especially if we consider how many drivers, do not know (or need to)
about the horror stories involving struct_mutex.

Just drop the suffix. It makes the API cleaner.

Done via the following script:

__from=drm_gem_object_put_unlocked
__to=drm_gem_object_put
for __file in $(git grep --name-only $__from); do
sed -i "s/$__from/$__to/g" $__file;
done

Pay special attention to the compat #define

v2: keep sed and #define removal separate

Cc: David Airlie <airlied@linux.ie>
Cc: Daniel Vetter <daniel@ffwll.ch>
Signed-off-by: Emil Velikov <emil.velikov@collabora.com>
Acked-by: Sam Ravnborg <sam@ravnborg.org> (v1)
Reviewed-by: Steven Price <steven.price@arm.com>
Acked-by: Thomas Zimmermann <tzimmermann@suse.de>
Link: https://patchwork.freedesktop.org/patch/msgid/20200515095118.2743122-14-emil.l.velikov@gmail.com

drm/doc: drop struct_mutex references

There's little point in providing partial and ancient information about
the struct_mutex. Some drivers are using it, new ones should not.

As-it this only provides for confusion.

Signed-off-by: Emil Velikov <emil.velikov@collabora.com>
Acked-by: Sam Ravnborg <sam@ravnborg.org>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Acked-by: Thomas Zimmermann <tzimmermann@suse.de>
Link: https://patchwork.freedesktop.org/patch/msgid/20200515095118.2743122-5-emil.l.velikov@gmail.com

drm/vram-helpers: Merge code into a single file

Most of the documentation was in an otherwise empty file, which was
probably just left from a previous clean-up effort. So move code and
documentation into a single file.

Signed-off-by: Thomas Zimmermann <tzimmermann@suse.de>
Acked-by: Gerd Hoffmann <kraxel@redhat.com>
Acked-by: Sam Ravnborg <sam@ravnborg.org>
Link: https://patchwork.freedesktop.org/patch/msgid/20200331081238.24749-1-tzimmermann@suse.de

drm/doc: Drop :c:func: markup

Kernel sphinx has learned how to do that in

commit d74b0d31dddeac2b44c715588d53d9a1e5b1158e
Author: Jonathan Corbet <corbet@lwn.net>
Date: Thu Apr 25 07:55:07 2019 -0600

Docs: An initial automarkup extension for sphinx

Unfortunately it hasn't learned that yet for structures, so we're
stuck with the :c:type: noise for now still.

Reviewed-by: Thierry Reding <treding@nvidia.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20191204101933.861169-1-daniel.vetter@ffwll.ch

Documentation/gpu: Fix no structured comments warning for drm_gem_ttm_helper.h

Fixes
include/drm/drm_gem_ttm_helper.h:1: warning: no structured comments found

Fixes: ff540b76f14a ("drm/ttm: add drm gem ttm helpers, starting with drm_gem_ttm_print_info()")
Cc: Gerd Hoffmann <kraxel@redhat.com>
Cc: Thomas Zimmermann <tzimmermann@suse.de>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Maxime Ripard <maxime.ripard@bootlin.com>
Cc: Sean Paul <sean@poorly.run>
Cc: David Airlie <airlied@linux.ie>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: dri-devel@lists.freedesktop.org
Acked-by: Thomas Zimmermann <tzimmermann@suse.de>
Reviewed-by: Gerd Hoffmann <kraxel@redhat.com>
Signed-off-by: Sean Paul <seanpaul@chromium.org>
Link: https://patchwork.freedesktop.org/patch/msgid/20190920193558.89815-2-sean@poorly.run

drm/vram: Move VRAM memory manager to GEM VRAM implementation

The separation between GEM VRAM objects and the memory manager is
artificial, as they are only used with each other. Copying both
implementations into the same file is a first step to simplifying
the code.

This patch only moves code without functional changes.

v3:
* update to use dev->vma_offset_manager
v2:
* update for debugfs support
* typos in commit message

Signed-off-by: Thomas Zimmermann <tzimmermann@suse.de>
Acked-by: Gerd Hoffmann <kraxel@redhat.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20190911110910.30698-2-tzimmermann@suse.de

drm/ttm: add drm gem ttm helpers, starting with drm_gem_ttm_print_info()

Now with ttm_buffer_object being a subclass of drm_gem_object we can
easily lookup ttm_buffer_object for a given drm_gem_object, which in
turn allows to create common helper functions.

This patch starts off with a drm_gem_ttm_print_info() helper function
which adds some ttm specific lines to the debug output.

Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
Acked-by: Thomas Zimmermann <tzimmermann@suse.de>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/20190904054740.20817-3-kraxel@redhat.com

drm/prime: Update docs

Yes this is a bit a big patch, but since it's essentially a complete
rewrite of all the prime docs I didn't see how to better split it up.

Changes:
- Consistently point to drm_gem_object_funcs as the preferred hooks,
where applicable.

- Document all the hooks in &drm_driver that lacked kerneldoc.

- Completely new overview section, which now also includes the cleaned
up lifetime/reference counting subchapter. I also mentioned the weak
references in there due to the lookup caches.

- Completely rewritten helper intro section, highlight the
import/export related functionality.

- Polish for all the functions and more cross references.

I also sprinkled a bunch of todos all over.

Most important: 0 code changes in here. The cleanup motivated by
reading and improving all this will follow later on.

v2: Actually update the prime helper docs. Plus add a few FIXMEs that
I won't address right away in subsequent cleanup patches.

v3:
- Split out the function moving. This patch is now exclusively
documentation changes.
- Typos and nits (Sam).

v4: Polish suggestions from Noralf.

Acked-by: Gerd Hoffmann <kraxel@redhat.com>
Acked-by: Emil Velikov <emil.velikov@collabora.com>
Acked-by: Noralf Trønnes <noralf@tronnes.org>
Cc: Thomas Zimmermann <tzimmermann@suse.de>
Cc: Gerd Hoffmann <kraxel@redhat.com>
Cc: Noralf Trønnes <noralf@tronnes.org>
Cc: Sam Ravnborg <sam@ravnborg.org>
Cc: Eric Anholt <eric@anholt.net>
Cc: Emil Velikov <emil.l.velikov@gmail.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20190620124615.24434-1-daniel.vetter@ffwll.ch

drm: Integrate VRAM MM into struct drm_device

There's now a pointer to struct drm_vram_mm stored in struct drm_device.
DRM drivers that use VRAM MM should use this field to refer to their
instance of the data structure. Appropriate helpers are now provided as
well.

Adding struct drm_vram_mm to struct drm_device further avoids wrappers
and boilerplate code in drivers. This patch implements default functions
for callbacks in struct drm_driver and struct file_operations that use
the struct drm_vram_mm stored in struct drm_device. Drivers that need to
provide their own implementations can still do so.

The patch also adds documentation for the VRAM helper library in general.

v5:
* set .llseek to no_llseek() from DRM_VRAM_MM_FILE_OPERATIONS
v4:
* cleanups from checkpatch.pl
* document VRAM helper library

Signed-off-by: Thomas Zimmermann <tzimmermann@suse.de>
Link: http://patchwork.freedesktop.org/patch/msgid/20190508082630.15116-9-tzimmermann@suse.de
Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>

drm: Add VRAM MM, a simple memory manager for dedicated VRAM

The VRAM MM memory manager is a helper library that manages dedicated video
memory of simple framebuffer devices. It is supported to be used with
struct drm_gem_vram_object, but does not depend on it.

The implementation is based on the respective code from ast, bochs, and
mgag200. These drivers share the exact same implementation except for type
names. The helpers are currently build with TTM. This may change in future
revisions.

v4:
* cleanups from checkpatch.pl
v2:
* renamed to struct drm_vram_mm
* add drm_vram_mm_mmap() helper
* documentation fixes

Signed-off-by: Thomas Zimmermann <tzimmermann@suse.de>
Link: http://patchwork.freedesktop.org/patch/msgid/20190508082630.15116-7-tzimmermann@suse.de
Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>

drm: Add |struct drm_gem_vram_object| and helpers

The type |struct drm_gem_vram_object| implements a GEM object for simple
framebuffer devices with dedicated video memory. The BO is either located
in VRAM or system memory.

The implementation has been created from the respective code in ast,
bochs and mgag200. These drivers copy their implementation from each
other; except for the names of several data types. The helpers are
currently build with TTM, but this is considered an implementation
detail and may change in future updates.

v5:
* do WARN_ON_ONCE for pin-count mismatches
* allocate only 2 entries in placements array
v4:
* cleanups from checkpatch.pl
* removed several fixed-size types from interfaces
* DRM_VRAM_HELPER now selects DRM_TTM
* remove separate config option for GEM VRAM
v2:
* rename to |struct drm_gem_vram_object|
* move drm_is_gem_ttm() to a later patch in the series
* add drm_gem_vram_kmap_at()
* return is_iomem from kmap functions
* redefine TTM placement flags for public interface
* documentation fixes

Signed-off-by: Thomas Zimmermann <tzimmermann@suse.de>
Link: http://patchwork.freedesktop.org/patch/msgid/20190508082630.15116-2-tzimmermann@suse.de
Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>

Documentation: drm: Remove dangling pointer from drm-mm.rst

Fixes htmldocs build error:
Error: Cannot open file ../drivers/gpu/drm/drm_global.c

Fixes: 2bb42410b1bd ("drm: Remove drm_global.{c,h} v2")
Cc: Thomas Zimmermann <tzimmermann@suse.de>
Cc: Christian König <christian.koenig@amd.com>
Cc: Junwei Zhang <Jerry.Zhang@amd.com>
Cc: Alex Deucher <alexander.deucher@amd.com>
Cc: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Cc: Maxime Ripard <maxime.ripard@bootlin.com>
Cc: Sean Paul <sean@poorly.run>
Cc: David Airlie <airlied@linux.ie>
Cc: Christian Koenig <christian.koenig@amd.com>
Cc: Huang Rui <ray.huang@amd.com>
Cc: dri-devel@lists.freedesktop.org
Signed-off-by: Sean Paul <seanpaul@chromium.org>
Reviewed-by: Christian König <christian.koenig@amd.com>
Signed-off-by: Dave Airlie <airlied@redhat.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20181129155522.33749-1-sean@poorly.run

drm/ttm: Rename ttm_bo_global_{init,release}() to ttm_bo_global_ref_{,}()

The functions ttm_bo_global_init() and ttm_bo_global_release() do not
receive an argument of type struct ttm_bo_global. Both take a struct
drm_global_reference that contains points to a struct ttm_bo_global_ref.
Renaming them reflects this.

Signed-off-by: Thomas Zimmermann <tzimmermann@suse.de>
Reviewed-by: Christian König <christian.koenig@amd.com>
Signed-off-by: Alex Deucher <alexander.deucher@amd.com>

Document/gpu: Use new vm_fault_t type

We have introduce new return type vm_fault_t for
fault handler. Update the document for the same.

Signed-off-by: Souptick Joarder <jrdr.linux@gmail.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20180904041505.GA2712@jordon-HP-15-Notebook-PC

drm/doc: Adapt GPU scheduler references for renamed C file

Fixes: "drm/scheduler: rename gpu_scheduler.c to sched_main.c"
Reviewed-by: Christian König <christian.koenig@amd.com>
Signed-off-by: Michel Dänzer <michel.daenzer@amd.com>
Signed-off-by: Alex Deucher <alexander.deucher@amd.com>

drm/doc: Add a label for the PRIME Buffer Sharing chapter

So that it can be referenced from e.g. DOC comments.

Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Signed-off-by: Michel Dänzer <michel.daenzer@amd.com>
Signed-off-by: Alex Deucher <alexander.deucher@amd.com>

drm/doc: add a chapter for gpu scheduler

Signed-off-by: Nayan Deshmukh <nayan26deshmukh@gmail.com>
Reviewed-by: Christian König <christian.koenig@amd.com>
Acked-by: Daniel Vetter <daniel@ffwll.ch>
Signed-off-by: Alex Deucher <alexander.deucher@amd.com>

drm/syncobj: Fix kerneldoc

make htmldocs helps with catching these.

Cc: Dave Airlie <airlied@gmail.com>
Acked-by: Dave Airlie <airlied@gmail.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20170718074113.5554-1-daniel.vetter@ffwll.ch
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

drm: Update docs around gem_free_object

Not all places correctly stated that gem_free_object_unlocked is the
one to use.

Reported-by: Eric Anholt <eric@anholt.net
Cc: Eric Anholt <eric@anholt.net
Reviewed-by: Eric Anholt <eric@anholt.net>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20170718063337.31942-1-daniel.vetter@ffwll.ch
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>

docs: Use :internal: for include/drm/drm_syncobj.h

Documentation/gpu/drm-mm.rst includes from include/drm/drm_syncobj.h with
:export:, but this is a header file without export directives. That
results in this warning:

./include/drm/drm_syncobj.h:1: warning: no structured comments found

...and a failure to obtain the documentation from that file. Switch to
:internal: instead to make both problems go away.

Cc: dri-devel@lists.freedesktop.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

drm: introduce sync objects (v4)

Sync objects are new toplevel drm object, that contain a
pointer to a fence. This fence can be updated via command
submission ioctls via drivers.

There is also a generic wait obj API modelled on the vulkan
wait API (with code modelled on some amdgpu code).

These objects can be converted to an opaque fd that can be
passes between processes.

v2: rename reference/unreference to put/get (Chris)
fix leaked reference (David Zhou)
drop mutex in favour of cmpxchg (Chris)
v3: cleanups from danvet, rebase on drm_fops rename
check fd_flags is 0 in ioctls.
v4: export find/free, change replace fence to take a
syncobj. In order to support lookup first, replace
later semantics which seem in the end to be cleaner.

Reviewed-by: Sean Paul <seanpaul@chromium.org>
Reviewed-by: Chris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: Dave Airlie <airlied@redhat.com>

drm/doc: Consistent kerneldoc include order

First overview text (if there is any), then headers (since generally
you want to start out with the data structures), then all the other
stuff with functions.

Most of this is pre-shpinx, since with the old docbook only the
overview stuff was pulled in directly. Everything else was put in a
per-section index, so include order didn't really matter.

Acked-by: Eric Anholt <eric@anholt.net>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170302151638.1882-4-daniel.vetter@ffwll.ch

drm: Extract drm_prime.h

Plus a little bit more documentation.

v2: Untangle the missing forward decls to make drm_prime|gem.h
free-standing.

Reviewed-by: Gustavo Padovan <gustavo.padovan@collabora.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170308141257.12119-3-daniel.vetter@ffwll.ch

drm: Introduce drm_gem_object_{get,put}()

For consistency with other reference counting APIs in the kernel, add
drm_gem_object_get() and drm_gem_object_put(), as well as an unlocked
variant of the latter, to reference count GEM buffer objects.

Compatibility aliases are added to keep existing code working. To help
speed up the transition, all the instances of the old functions in the
DRM core are already replaced in this commit.

The existing semantic patch for the DRM subsystem-wide conversion is
extended to account for these new helpers.

Reviewed-by: Sean Paul <seanpaul@chromium.org>
Acked-by: Christian König <christian.koenig@amd.com>
Signed-off-by: Thierry Reding <treding@nvidia.com>
Link: http://patchwork.freedesktop.org/patch/msgid/20170228144643.5668-6-thierry.reding@gmail.com

Documentation/gpu: drm-mm.rst: fix formatting for struct vm_operations_struct

drm-mm.rst contains some unformatted dump of the vm_operations_struct
structure. Add some C formatting around it and some context for the
dump. While there, update the structure to resemble the new signature
for the fault handler after commit 25d3db7600b8 (mm, fs: reduce fault,
page_mkwrite, and pfn_mkwrite to take only vmf).

Signed-off-by: Liviu Dudau <liviu.dudau@arm.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/20170131174109.13690-1-Liviu.Dudau@arm.com

drm: Document drm_cache interface

Notice that this uncovers an issue with the kernel-doc handling of array
arguments, causing the first parameter of drm_clflush_pages() to not
show up in the rst-generated page. A proposed fix is under review in
linux-doc: <http://www.spinics.net/lists/linux-doc/msg42544.html>

Changes since v1:
- Add section to drm-mm.rst.
- Fix kernel-doc style issues.
- s/memory/kernel memory/.

Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.co.uk>
Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/20170109215649.6860-1-krisman@collabora.co.uk

drm: allow to use mmuless SoC

Some SoC without MMU have display driver where a drm/kms driver
could be implemented.

Before doing such kind of thing drm/kms must allow to use mmuless devices.
This patch propose to remove MMU configuration flag and add a cma helper
function to help implementing mmuless display driver

version 4:
- add documentation about drm_gem_cma_get_unmapped_area()
- stub it MMU case

Signed-off-by: Benjamin Gaignard <benjamin.gaignard@linaro.org>
[danvet: Use recommended struct member references in kernel-doc.]
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/1483521177-21794-4-git-send-email-benjamin.gaignard@linaro.org

drm/mm: Some doc polish

Added some boilerplate for the structs, documented members where they
are relevant and plenty of markup for hyperlinks all over. And a few
small wording polish.

Note that the intro needs some more love after the DRM_MM_INSERT_*
patch from Chris has landed.

v2: Spelling fixes (Chris).

v3: Use &struct foo instead of &foo structure (Chris).

Cc: Chris Wilson <chris@chris-wilson.co.uk>
Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com>
Reviewed-by: David Herrmann <dh.herrmann@gmail.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1483044517-5770-3-git-send-email-daniel.vetter@ffwll.ch

drm: Update TTM initialization documentation

ttm_global_reference was renamed to drm_global_reference. This updates
the documentation to reflect that. While we are there, document the
drm_global_reference API and update the initialization interface
documentation.

Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.co.uk>
[danvet: Keep the warning, ttm docs are still massively inadequate.]
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/20161228143216.26821-7-krisman@collabora.co.uk

Documentation/gpu: use code-block with proper language

Now that we don't have automatic syntax highlighting, use the code-block
directive with the explicitly selected language, where appropriate.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>

drm/doc: Reorg drm-mm.rst

- Readjust headings - we lost one level through the extraction into a
separate .rst file.
- Merge helper reference sections with the helper documentation - that
split was just an artifact of the docbook toolchain sucking at too
deep nesting levels. No such problems with sphinx.
- Move the cma helpers in with the gem documentation, since they're
helpers to implement gem using CMA/dma memory as a backend.

Reviewed-by: Sean Paul <seanpaul@chromium.org>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1471034937-651-4-git-send-email-daniel.vetter@ffwll.ch

Documentation/gpu: split up mm, kms and kms-helpers from internals

Make the documents more manageable.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/be992e56eb8442d6e03b52444df5a42525085718.1466506505.git.jani.nikula@intel.com