Documentation/gpu: Add a VM_BIND async document

Add a motivation for and description of asynchronous VM_BIND operation

v2:
- Fix typos (Nirmoy Das)
- Improve the description of a memory fence (Oak Zeng)
- Add a reference to the document in the Xe RFC.
- Add pointers to sample uAPI suggestions
v3:
- Address review comments (Danilo Krummrich)
- Formatting fixes
v4:
- Address typos (Francois Dugast)
- Explain why in-fences are not allowed for VM_BIND operations for long-
running workloads (Matthew Brost)
v5:
- More typo- and style fixing
- Further clarify the implications of disallowing in-fences for VM_BIND
operations for long-running workloads (Matthew Brost)
v6:
- Point out that a gpu_vm is a virtual GPU Address space.
(Danilo Krummrich)
- For an explanation of dma-fences point to the dma-fence documentation.
(Paulo Zanoni)
- Clarify that VM_BIND errors are reported synchronously. (Paulo Zanoni)
- Use an rst doc reference when pointing to the async vm_bind document
from the xe merge plan.
- Add the VM_BIND documentation to the drm documentation table-of-content,
using an intermediate "Misc DRM driver uAPI- and feature implementation
guidelines"
v7:
- Update the error handling documentation to remove the VM error state.
v8:
- Clarify error handling and difference in operation support between
async VM_BIND and sync VM_BIND. (Paulo Zanoni)
- Update the sample uAPI with a self-contained example. (Paulo Zanoni)

Cc: Paulo R Zanoni <paulo.r.zanoni@intel.com>
Signed-off-by: Thomas Hellström <thomas.hellstrom@linux.intel.com>
Acked-by: Nirmoy Das <nirmoy.das@intel.com>
Reviewed-by: Danilo Krummrich <dakr@redhat.com>
Reviewed-by: Matthew Brost <matthew.brost@intel.com>
Reviewed-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Reviewed-by: Paulo Zanoni <paulo.r.zanoni@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20231012132552.20196-1-thomas.hellstrom@linux.intel.com

drm: Add initial ci/ subdirectory

Developers can easily execute several tests on different devices
by just pushing their branch to their fork in a repository hosted
on gitlab.freedesktop.org which has an infrastructure to run jobs
in several runners and farms with different devices.

There are also other automated tools that uprev dependencies,
monitor the infra, and so on that are already used by the Mesa
project, and we can reuse them too.

Also, store expectations about what the DRM drivers are supposed
to pass in the IGT test suite. By storing the test expectations
along with the code, we can make sure both stay in sync with each
other so we can know when a code change breaks those expectations.

Also, include a configuration file that points to the out-of-tree
CI scripts.

This will allow all contributors to drm to reuse the infrastructure
already in gitlab.freedesktop.org to test the driver on several
generations of the hardware.

Signed-off-by: Tomeu Vizoso <tomeu.vizoso@collabora.com>
Signed-off-by: Helen Koike <helen.koike@collabora.com>
Acked-by: Daniel Stone <daniels@collabora.com>
Acked-by: Rob Clark <robdclark@gmail.com>
Tested-by: Rob Clark <robdclark@gmail.com>
[sima: Remove top-level empty file test, spotted by sfr]
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20230811171953.176431-1-helen.koike@collabora.com

Docs/subsystem-apis: Remove '[The ]Linux' prefixes from titles of listed documents

Some documents that listed on subsystem-apis have 'Linux' or 'The Linux'
title prefixes. It's duplicated information, and makes finding the
document of interest with human eyes not easy. Remove the prefixes from
the titles.

Signed-off-by: SeongJae Park <sj@kernel.org>
Acked-by: Iwona Winiarska <iwona.winiarska@intel.com>
Acked-by: Bjorn Helgaas <bhelgaas@google.com>
Link: https://lore.kernel.org/r/20230122184834.181977-1-sj@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

drm: Document fdinfo format specification

Proposal to standardise the fdinfo text format as optionally output by DRM
drivers.

Idea is that a simple but, well defined, spec will enable generic
userspace tools to be written while at the same time avoiding a more heavy
handed approach of adding a mid-layer to DRM.

i915 implements a subset of the spec, everything apart from the memory
stats currently, and a matching intel_gpu_top tool exists.

Open is to see if AMD can migrate to using the proposed GPU utilisation
key-value pairs, or if they are not workable to see whether to go
vendor specific, or if a standardised alternative can be found which is
workable for both drivers.

Same for the memory utilisation key-value pairs proposal.

v2:
* Update for removal of name and pid.

v3:
* 'Drm-driver' tag will be obtained from struct drm_driver.name. (Daniel)

v4:
* Added drm-engine-capacity- tag.

Signed-off-by: Tvrtko Ursulin <tvrtko.ursulin@intel.com>
Cc: David M Nieto <David.Nieto@amd.com>
Cc: Christian König <christian.koenig@amd.com>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Daniel Stone <daniel@fooishbar.org>
Cc: Chris Healy <cphealy@gmail.com>
Acked-by: Christian König <christian.koenig@amd.com>
Reviewed-by: Umesh Nerlige Ramappa <umesh.nerlige.ramappa@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20220401142205.3123159-7-tvrtko.ursulin@linux.intel.com

drm/doc: add section for driver uAPI

Add section for drm/i915 uAPI and pull in i915_drm.h.

Suggested-by: Daniel Vetter <daniel@ffwll.ch>
Signed-off-by: Matthew Auld <matthew.auld@intel.com>
Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Cc: Daniel Vetter <daniel.vetter@intel.com>
Cc: Kenneth Graunke <kenneth@whitecape.org>
Cc: Jason Ekstrand <jason@jlekstrand.net>
Cc: Dave Airlie <airlied@gmail.com>
Cc: dri-devel@lists.freedesktop.org
Cc: mesa-dev@lists.freedesktop.org
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20210419105741.27844-2-matthew.auld@intel.com

drm/doc: Add RFC section

Motivated by the pre-review process for i915 gem/gt features, but
probably useful in general for complex stuff.

v2: Add reminder to not forget userspace projects in the discussion
(Simon, Jason)

v3: Actually put this into a folder, so we have it all (.rst files and
headers for kerneldoc) contained somewhere separate (Jason)

Cc: Simon Ser <contact@emersion.fr>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Joonas Lahtinen <joonas.lahtinen@linux.intel.com>
Cc: Rodrigo Vivi <rodrigo.vivi@intel.com>
Cc: Jason Ekstrand <jason@jlekstrand.net>
Cc: Dave Airlie <airlied@redhat.com>
Acked-by: Jason Ekstrand <jason@jlekstrand.net>
Acked-by: Simon Ser <contact@emersion.fr>
Acked-by: Rodrigo Vivi <rodrigo.vivi@intel.com>
Acked-by: Dave Airlie <airlied@redhat.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20210325225859.1684116-1-daniel.vetter@ffwll.ch

doc-rst: Wire-up Backlight kernel-doc documentation

Include backlight so the documentation is now generated with make
htmldocs and friends.

Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
Reviewed-by: Daniel Thompson <daniel.thompson@linaro.org>
Reviewed-by: Emil Velikov <emil.l.velikov@gmail.com>
Signed-off-by: Lee Jones <lee.jones@linaro.org>

drm: Begin an API for in-kernel clients

This the beginning of an API for in-kernel clients.
First out is a way to get a framebuffer backed by a dumb buffer.

Only GEM drivers are supported.
The original idea of using an exported dma-buf was dropped because it
also creates an anonomous file descriptor which doesn't work when the
buffer is created from a kernel thread. The easy way out is to use
drm_driver.gem_prime_vmap to get the virtual address, which requires a
GEM object. This excludes the vmwgfx driver which is the only non-GEM
driver apart from the legacy ones. A solution for vmwgfx will have to be
worked out later if it wants to support the client API which it probably
will when we have a bootsplash client.

Suggested-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Noralf Trønnes <noralf@tronnes.org>
Reviewed-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: https://patchwork.freedesktop.org/patch/msgid/20180703160354.59955-2-noralf@tronnes.org

drm/doc: Put all driver docs into a separate chapter

We have quite a few driver docs now, which is great, but having them
all in the top-level gpu documentation chapter makes it harder to spot
the core/shared bits.

Stuff them into a separate chapter and ecourage people to add even
more!

Reviewed-by: Alex Deucher <alexander.deucher@amd.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Link: https://patchwork.freedesktop.org/patch/msgid/20180316075926.13584-1-daniel.vetter@ffwll.ch

drm/tve200: Add new driver for TVE200

This adds a new DRM driver for the Faraday Technology TVE200
block. This "TV Encoder" encodes a ITU-T BT.656 stream and can
be found in the StorLink SL3516 (later Cortina Systems CS3516)
as well as the Grain Media GM8180.

I do not have definitive word from anyone at Faraday that this
IP block is theirs, but it bears the hallmark of their 3-digit
version code (200) and is used in two SoCs from completely
different companies. (Grain Media was fully owned by Faraday
until it was transferred to NovoTek this january, and
Faraday did lots of work on the StorLink SoCs.)

The D-Link DIR-685 uses this in connection with the Ilitek
ILI9322 panel driver that supports BT.656 input, while the
GM8180 apparently has been used with the Cirrus Logic CS4954
digital video encoder. The oldest user seems to be
something called Techwall 2835.

This driver is heavily inspired by Eric Anholt's PL111
driver and therefore I have mentioned all the ancestor authors
in the header file.

Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Reviewed-by: Eric Anholt <eric@anholt.net>
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
Link: https://patchwork.freedesktop.org/patch/msgid/20170820100557.24991-2-linus.walleij@linaro.org

drm/tegra: Add driver documentation

Adds some driver documentation for Tegra. It provides a short overview
of the hardware and software architectures.

Signed-off-by: Thierry Reding <treding@nvidia.com>
Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Thierry Reding <treding@nvidia.com>

drm/pl111: Initial drm/kms driver for pl111

This is a modesetting driver for the pl111 CLCD display controller
found on various ARM platforms such as the Versatile Express. The
driver has only been tested on the bcm911360_entphn platform so far,
with PRIME-based buffer sharing between vc4 and clcd.

It reuses the existing devicetree binding, while not using quite as
many of its properties as the fbdev driver does (those are left for
future work).

v2: Nearly complete rewrite by anholt, cutting 2/3 of the code thanks
to DRM core's excellent new helpers.
v3: Don't match pl110 any more, don't attach if we don't have a DRM
panel, use DRM_GEM_CMA_FOPS, update MAINTAINERS, use the simple
display helper, use drm_gem_cma_dumb_create (same as our wrapper).
v4: Change the driver's .name to not clash with fbdev in sysfs, drop
platform alias, drop redundant "drm" in DRM driver name, hook up
.prepare_fb to the CMA helper so that DMA fences should work.
v5: Move register definitions inside the driver directory, fix build
in COMPILE_TEST and !AMBA mode.
v6: Drop TIM2_CLKSEL for now to be consistent with existing DT
bindings, switch back to external register definitions.

Signed-off-by: Tom Cooksey <tom.cooksey@arm.com>
Signed-off-by: Eric Anholt <eric@anholt.net>
Reviewed-by: Linus Walleij <linus.walleij@linaro.org> (v5)
Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/20170413031746.12921-2-eric@anholt.net

drm/meson: Add RST to bring together kerneldoc

Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>

drm: bridge: dw-hdmi: Add Documentation on supported input formats

This patch adds a new DRM documentation entry and links to the input
format table added in the dw_hdmi header.

Reviewed-by: Archit Taneja <architt@codeaurora.org>
Acked-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Neil Armstrong <narmstrong@baylibre.com>

drm/vc4: Add RST to bring together vc4 kerneldoc.

This doesn't yet produce coherent documentation of the module, but at
least gets the kerneldoc built and somewhat glued together.

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

drm: Add DRM support for tiny LCD displays

tinydrm provides helpers for very simple displays that can use
CMA backed framebuffers and need flushing on changes.

Signed-off-by: Noralf Trønnes <noralf@tronnes.org>
Acked-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Acked-by: Thierry Reding <treding@nvidia.com>

drm/doc: Add TODO list

This commit adds a TODO list to the GPU driver developer's guide. The
content was taken from the DRMJanitors page on the X.Org wiki:

https://www.x.org/wiki/DRMJanitors/

The goal is to track a list of refactorings that would be nice to see
merged eventually. Sometimes these would be encountered during patch
review on the mailing list, and at other times one can come across
these while working in a specific area of code.

Signed-off-by: Thierry Reding <treding@nvidia.com>
Acked-by: Sean Paul <seanpaul@chromium.org>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Link: http://patchwork.freedesktop.org/patch/msgid/20170207175113.2793-1-thierry.reding@gmail.com

doc-rst: include index only in subproject AND html

The index should only be included if the build of the sub-folder is done
with the html-builder (HTML output).

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst: add index to sub-folders

Add a index if only a sub-folder is build e.g.::

make SPHINXDIRS=media cleandocs htmldocs

BTW: removed dead search link in the top-index file

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

vgaarbiter: rst-ifiy and polish kerneldoc

Move the documentation into Documentation/gpu, link it up and pull in
the kernel doc.

No actual text changes except that I did polish the kerneldoc a bit,
especially for vga_client_register().

v2: Remove some rst from vga-switcheroo.rst that I don't understand,
but which seems to be the reason why the new vgaarbiter.rst sometimes
drops out of the sidebar index.

v3: Drop one level of headings and clarify the vgaarb one a bit.

v4: Fix some typos (Sean).

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Sean Paul <seanpaul@chromium.org>
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-20-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

Documentation/gpu: split up the gpu documentation

Make the gpu documentation easier to manage by splitting to separate
files. Again, this is just the split, no real edits.

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/bd2b599b5105c28c8f05923005e6cc9b7efa7fc1.1466506505.git.jani.nikula@intel.com

Documentation/gpu: add new gpu.rst converted from DocBook gpu.tmpl

This is the first step towards converting the DocBook gpu.tmpl to Sphinx
and reStructuredText, the new kernel documentation tool and markup.

Use Jon's "cheesy conversion script" in Documentation/sphinx/tmplcvt to
do the rough conversion. Do the manual edits in follow-up patches. Add a
new Documentation/gpu directories for the graphics related
documentation. (Hooray, now we can have directories based on topics
rather than tools under Documentation.)

We also won't remove the DocBook gpu.tmpl yet so it's easier to build
both and compare the results for parity.

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/bc7b4f9ac037632e0c8469c079d21fad5eaa39a0.1466506505.git.jani.nikula@intel.com