drm/doc: Document device wedged event

Add documentation for device wedged event in a new "Device wedging"
chapter. This describes basic definitions, prerequisites and consumer
expectations along wit

drm/doc: Document device wedged event

Add documentation for device wedged event in a new "Device wedging"
chapter. This describes basic definitions, prerequisites and consumer
expectations along with an example.

v8: Improve introduction (Christian, Rodrigo)
v9: Add prerequisites section (Christian)
v10: Clarify mmap cleanup and consumer prerequisites (Christian, Aravind)
v11: Reference wedged event in device reset chapter (André)
v12: Refine consumer expectations and terminologies (Xaver, Pekka)

Signed-off-by: Raag Jadav <[email protected]>
Reviewed-by: Christian König <[email protected]>
Reviewed-by: André Almeida <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]
Signed-off-by: Rodrigo Vivi <[email protected]>

show more ...

drm/doc: Document submission error signaling

Different approaches have been tried to signal resets and other errors in
vendor specific ways which not only resulted in a wide variety of
implementatio

drm/doc: Document submission error signaling

Different approaches have been tried to signal resets and other errors in
vendor specific ways which not only resulted in a wide variety of
implementations but also repeating the same bugs and problems over different
drivers.

Document that drivers should use dma_fence based error signaling which is
vendor agnostic and allows userspace to query submission errors in generic
non-vendor specific code.

Signed-off-by: Christian König <[email protected]>
Acked-by: Daniel Vetter <[email protected]>
Reviewed-by: Alex Deucher <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm/doc: use cross-references for macros

These will show up as monospace, and will get linkified as soon as
we document the macro they point to.

Signed-off-by: Simon Ser <[email protected]>
Acked

drm/doc: use cross-references for macros

These will show up as monospace, and will get linkified as soon as
we document the macro they point to.

Signed-off-by: Simon Ser <[email protected]>
Acked-by: Daniel Vetter <[email protected]>
Acked-by: Pekka Paalanen <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm/doc: Document DRM device reset expectations

Create a section that specifies how to deal with DRM device resets for
kernel and userspace drivers.

Signed-off-by: André Almeida <andrealmeid@igalia

drm/doc: Document DRM device reset expectations

Create a section that specifies how to deal with DRM device resets for
kernel and userspace drivers.

Signed-off-by: André Almeida <[email protected]>
Acked-by: Pekka Paalanen <[email protected]>
Acked-by: Sebastian Wick <[email protected]>
Reviewed-by: Christian König <[email protected]>
Signed-off-by: Christian König <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

doc: uapi: Add document describing dma-buf semantics

Since there's a lot of confusion around this, document both the rules
and the best practices around negotiating, allocating, importing, and
using

doc: uapi: Add document describing dma-buf semantics

Since there's a lot of confusion around this, document both the rules
and the best practices around negotiating, allocating, importing, and
using buffers when crossing context/process/device/subsystem boundaries.

This ties up all of dma-buf, formats and modifiers, and their usage.

Signed-off-by: Daniel Stone <[email protected]>
Signed-off-by: Simon Ser <[email protected]>
Reviewed-by: Simon Ser <[email protected]>
Reviewed-by: Sui Jingfeng <[email protected]>
Acked-by: Daniel Vetter <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm/doc: make drm-uapi igt-tests more readable

Correct grammar and make the use of the igt-tests more readable.

Signed-off-by: Randy Dunlap <[email protected]>
Cc: Gabriela Bittencourt <gabriel

drm/doc: make drm-uapi igt-tests more readable

Correct grammar and make the use of the igt-tests more readable.

Signed-off-by: Randy Dunlap <[email protected]>
Cc: Gabriela Bittencourt <[email protected]>
Cc: Rodrigo Siqueira <[email protected]>
Cc: David Airlie <[email protected]>
Cc: Daniel Vetter <[email protected]>
Cc: Maarten Lankhorst <[email protected]>
Cc: Maxime Ripard <[email protected]>
Cc: Thomas Zimmermann <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm/doc: Clarify what ioctls can be used on render nodes

The documentation for render nodes indicates that only "PRIME-related"
ioctls are valid on render nodes, but the documentation does not clari

drm/doc: Clarify what ioctls can be used on render nodes

The documentation for render nodes indicates that only "PRIME-related"
ioctls are valid on render nodes, but the documentation does not clarify
what that means. If the reader is not familiar with PRIME, they may
beleive this to be only the ioctls with "PRIME" in the name and not other
ioctls such as set of syncobj ioctls. Clarify the situation for the
reader by referencing where the reader will find a current list of valid
ioctls.

Signed-off-by: Jeffrey Hugo <[email protected]>
Acked-by: Pekka Paalanen <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm: clarify usage of drm leases

We make the following changes to the documentation of drm leases to
make it easier to reason about their usage. In particular, we clarify
the lifetime and locking ru

drm: clarify usage of drm leases

We make the following changes to the documentation of drm leases to
make it easier to reason about their usage. In particular, we clarify
the lifetime and locking rules of lease fields in drm_master:

1. Make it clear that &drm_device.mode_config.idr_mutex protects the
lease idr and list structures for drm_master. The lessor field itself
doesn't need to be protected as it doesn't change after it's set in
drm_lease_create.

2. Add descriptions for the lifetime of lessors and leases.

3. Add an overview DOC: section in drm-uapi.rst that defines the
terminology for drm leasing, and explains how leases work and why
they're used.

Signed-off-by: Desmond Cheong Zhi Xi <[email protected]>
Reviewed-by: Daniel Vetter <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm/doc: document how userspace should find out CRTC index

In this patch we add a section to document what userspace should do to
find out the CRTC index. This is important as they may be many place

drm/doc: document how userspace should find out CRTC index

In this patch we add a section to document what userspace should do to
find out the CRTC index. This is important as they may be many places in
the documentation that need this, so it's better to just point to this
section and avoid repetition.

Signed-off-by: Leandro Ribeiro <[email protected]>
Reviewed-by: Pekka Paalanen <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm/doc: render drm.h uapi docs

It doesn't seem like drm.h docs are included anywhere. Render them next
to drm_mode.h, under the "Userspace API Structures" section.

This also allows references to e

drm/doc: render drm.h uapi docs

It doesn't seem like drm.h docs are included anywhere. Render them next
to drm_mode.h, under the "Userspace API Structures" section.

This also allows references to e.g. DRM_CAP_* to be properly linkified
elsewhere in our docs.

Signed-off-by: Simon Ser <[email protected]>
Acked-by: Daniel Vetter <[email protected]>
Cc: Pekka Paalanen <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm/doc: device hot-unplug for userspace

Set up the expectations on how hot-unplugging a DRM device should look like to
userspace.

Written by Daniel Vetter's request and largely based on his commen

drm/doc: device hot-unplug for userspace

Set up the expectations on how hot-unplugging a DRM device should look like to
userspace.

Written by Daniel Vetter's request and largely based on his comments in IRC and
from https://lists.freedesktop.org/archives/dri-devel/2020-May/265484.html .

A related Wayland protocol change proposal is at
https://gitlab.freedesktop.org/wayland/wayland-protocols/-/merge_requests/35

Signed-off-by: Pekka Paalanen <[email protected]>
Reviewed-by: Daniel Vetter <[email protected]>
Reviewed-by: Alex Deucher <[email protected]>
Acked-by: Noralf Trønnes <[email protected]>
Cc: Andrey Grodzovsky <[email protected]>
Cc: Dave Airlie <[email protected]>
Cc: Sean Paul <[email protected]>
Cc: Simon Ser <[email protected]>
Cc: Ben Skeggs <[email protected]>
Cc: Karol Herbst <[email protected]>
Acked-by: Simon Ser <[email protected]>
Signed-off-by: Emil Velikov <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

Documentation: gpu/drm-uapi: eliminate duplicated word

Drop the doubled word "when".

Signed-off-by: Randy Dunlap <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]

Documentation: gpu/drm-uapi: eliminate duplicated word

Drop the doubled word "when".

Signed-off-by: Randy Dunlap <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Cc: David Airlie <[email protected]>
Cc: Daniel Vetter <[email protected]>
Cc: [email protected]
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

drm/doc: Add VKMS module description and use to "Testing and Validation"

Add a description on VKMS module and the cases in which it should be used.
There's a brief explanation on how to set it and u

drm/doc: Add VKMS module description and use to "Testing and Validation"

Add a description on VKMS module and the cases in which it should be used.
There's a brief explanation on how to set it and use it in a VM, along with
an example of running an igt-test.

Changes since V3:
Rodrigo:
- Change the log message to imperative
- Fix some bad spelling/writing
- Add a blank line before enumeration

Changes since V2:
Andre:
- Avoid repetition of words in the same sentence;
- Make the explanation on 'setting the kernel' shorter, eliminate the
'make menuconfig' command;
- Add tab on enumeration to have one line per item;
- Clarify from each machine igt-tests commands should be ran on.

Reviewed-by: Rodrigo Siqueira <[email protected]>
Signed-off-by: Gabriela Bittencourt <[email protected]>
Signed-off-by: Rodrigo Siqueira <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm/doc: Update IGT documentation

The IGT documentation in this page is telling us to build it using
make. According to commit 67993c1 ("automake: Point builders at
meson") from the IGT project, thi

drm/doc: Update IGT documentation

The IGT documentation in this page is telling us to build it using
make. According to commit 67993c1 ("automake: Point builders at
meson") from the IGT project, this is deprecated and IGT should be
built with meson. Instead of having a documentation for IGT in this
page, point to their GitLab README, which should always be up to
date.

Signed-off-by: Leandro Ribeiro <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm: ADD UAPI structure definition section in kernel doc

Add a new section for UAPI structure and helper definitions
in kernel docbook.

Suggested-by: Daniel Vetter <[email protected]>
Signed-off-by:

drm: ADD UAPI structure definition section in kernel doc

Add a new section for UAPI structure and helper definitions
in kernel docbook.

Suggested-by: Daniel Vetter <[email protected]>
Signed-off-by: Uma Shankar <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm/doc: More fine-tuning on userspace review requirements

With Eric's patch

commit ba6e798ecf320716780bb6a6088a8d17dcba1d49
Author: Eric Anholt <[email protected]>
Date: Wed Apr 24 11:56:17 2019 -

drm/doc: More fine-tuning on userspace review requirements

With Eric's patch

commit ba6e798ecf320716780bb6a6088a8d17dcba1d49
Author: Eric Anholt <[email protected]>
Date: Wed Apr 24 11:56:17 2019 -0700

drm/doc: Document expectation that userspace review looks at kernel uAPI.

there's been concerns raised that we expect userspace people to do
in-depth kernel patch review. That's not reasonable, same way kernel
people can't review all the userspace we have. Try to clarify
expectations a bit more.

Cc: Eric Anholt <[email protected]>
Cc: Pekka Paalanen <[email protected]>
Cc: [email protected]
Cc: [email protected]
Acked-by: Eric Anholt <[email protected]>
Reviewed-by: Simon Ser <[email protected]>
Reviewed-by: Pekka Paalanen <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm/doc: Document expectation that userspace review looks at kernel uAPI.

The point of this review process is that userspace using the new uAPI
can actually live with the uAPI being provided, and it

drm/doc: Document expectation that userspace review looks at kernel uAPI.

The point of this review process is that userspace using the new uAPI
can actually live with the uAPI being provided, and it's hard to know
that without having actually looked into a kernel patch yourself.

Signed-off-by: Eric Anholt <[email protected]>
Suggested-by: Daniel Vetter <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]
Reviewed-by: Daniel Vetter <[email protected]>

show more ...

drm/doc: Allow new UAPI to be used once it's in drm-next/drm-misc-next.

I was trying to figure out if it was permissible to merge the Mesa
side of V3D's CSD support yet while it's in drm-misc-next b

drm/doc: Allow new UAPI to be used once it's in drm-next/drm-misc-next.

I was trying to figure out if it was permissible to merge the Mesa
side of V3D's CSD support yet while it's in drm-misc-next but not
drm-next, and developers on #dri-devel IRC had differing opinions of
what the requirement was.

v2: Restrict to just drm-next or drm-misc-next on airlied's request.

Signed-off-by: Eric Anholt <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]
Reviewed-by: Daniel Vetter <[email protected]>

show more ...

drm/doc: Make igts for cross-driver stuff strongly suggested

Compared to the RFC[1] no changes to the patch itself, but igt moved
forward a lot:

- gitlab CI builds with: reduced configs/libraries,

drm/doc: Make igts for cross-driver stuff strongly suggested

Compared to the RFC[1] no changes to the patch itself, but igt moved
forward a lot:

- gitlab CI builds with: reduced configs/libraries, arm cross build
and a sysroot build (should address all the build/cross platform
concerns raised in the RFC discussions).

- tests reorganized into subdirectories so that the i915-gem tests
don't clog the main/shared tests directory anymore

- quite a few more non-intel people contributing/reviewing/committing
igt tests patches.

I think this addresses all the concerns raised in the RFC discussions,
and assuming there's enough Acks and no new issues that pop up, we can
go ahead with this.

v2:
- Use "should" (in the usual RFC sense) to make it clear that in the
end this is all up to reviewer's discretion, as usual (Jani).
- Also in the title s/mandatory/strongly suggested/ (me)
- Make it clear we're not going to block features if a testcase is not
feasible, given hw and state of igt, both having some good gaps in
what can be tested (Harry, Eric, Sean, ...).

1: https://patchwork.kernel.org/patch/10648851/
Cc: Petri Latvala <[email protected]>
Cc: Arkadiusz Hiler <[email protected]>
Cc: Liviu Dudau <[email protected]>
Cc: Sean Paul <[email protected]>
Cc: Eric Anholt <[email protected]>
Cc: Alex Deucher <[email protected]>
Cc: Dave Airlie <[email protected]>
Cc: Daniel Stone <[email protected]>
Cc: "Wentland, Harry" <[email protected]>
Cc: Brian Starkey <[email protected]>
Reviewed-by: Eric Anholt <[email protected]> (v1)
Acked-by: Petri Latvala <[email protected]>
Acked-by: Arkadiusz Hiler <[email protected]>
Acked-by: Sean Paul <[email protected]>
Acked-by: "Wentland, Harry" <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Acked-by: Liviu Dudau <[email protected]>
Acked-by: Jani Nikula <[email protected]>
Acked-by: Brian Starkey <[email protected]>
Acked-by: Tomi Valkeinen <[email protected]>
Acked-by: Boris Brezillon <[email protected]>
Acked-by: Alex Deucher <[email protected]>
Acked-by: Dave Airlie <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

Documentation: fix spelling mistake, EACCESS -> EACCES

Trivial fix to a spelling mistake of the error access name EACCESS,
rename to EACCES

Signed-off-by: Colin Ian King <[email protected]>

Documentation: fix spelling mistake, EACCESS -> EACCES

Trivial fix to a spelling mistake of the error access name EACCESS,
rename to EACCES

Signed-off-by: Colin Ian King <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

drm/doc: Update errno handbook

We recently bikeshedded this to a different flavour, but forgot to
update the recommendations.

Cc: Chris Wilson <[email protected]>
Cc: Ville Syrjälä <ville.sy

drm/doc: Update errno handbook

We recently bikeshedded this to a different flavour, but forgot to
update the recommendations.

Cc: Chris Wilson <[email protected]>
Cc: Ville Syrjälä <[email protected]>
Reviewed-by: Chris Wilson <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm/doc: Document ioctl errno value patterns

We're not super-consistent about these, but I think it's worth to
document at least the commmon patterns.

v2:
- Add a not about ENOTTY (it's just a conf

drm/doc: Document ioctl errno value patterns

We're not super-consistent about these, but I think it's worth to
document at least the commmon patterns.

v2:
- Add a not about ENOTTY (it's just a confusing name, but used
exactly what it's meant for in DRM) (Chris).
- Unconfuse the text for ENODEV (Daniel)
- Move text undert the IOCTL heading (Chris).
- typos

Cc: Daniel Stone <[email protected]>
Cc: Joonas Lahtinen <[email protected]>
Cc: Chris Wilson <[email protected]>
Cc: "Zhang, Tina" <[email protected]>
Reviewed-by: Chris Wilson <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: https://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm/doc: Improve ioctl/fops docs a bit more

I spotted a markup issue, plus adding the descriptions in drm_driver.
Plus a few more links while at it.

I'm still mildly unhappy with the split between

drm/doc: Improve ioctl/fops docs a bit more

I spotted a markup issue, plus adding the descriptions in drm_driver.
Plus a few more links while at it.

I'm still mildly unhappy with the split between fops and ioctls, but I
still think having the ioctls in the uapi chapter makes more sense. Oh
well ...

v2: Rebase.

v3: Move misplace hunk to the right patch.

Cc: Stefan Agner <[email protected]>
Acked-by: Thierry Reding <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: http://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm: document drm_ioctl.[hc]

Also unify/merge with the existing stuff.

I was a bit torn where to put this, but in the end I decided to put
all the ioctl/sysfs/debugfs stuff into drm-uapi.rst. That

drm: document drm_ioctl.[hc]

Also unify/merge with the existing stuff.

I was a bit torn where to put this, but in the end I decided to put
all the ioctl/sysfs/debugfs stuff into drm-uapi.rst. That means we
have a bit a split with the other uapi related stuff used internally,
like drm_file.[hc], but I think overall this makes more sense.

If it's too confusing we can always add more cross-links to make it
more discoverable. But the auto-sprinkling of links kernel-doc already
does seems sufficient.

Also for prettier docs and more cross-links, switch the internal
defines over to an enum, as usual.

v2: Update kerneldoc fro drm_compat_ioctl too (caught by 0day), plus a
bit more drive-by polish.

v3: Fix typo, spotted by xerpi on irc (Sergi).

v4: Add missing space in comment (Neil).

Cc: Sergi Granell <[email protected]>
Reviewed-by: Neil Armstrong <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: http://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...

drm: Consolidate and document sysfs support

- remove docs for internal func, doesn't add value
- add short overview snippet instead explaining that drivers don't
have to bother themselves with reg

drm: Consolidate and document sysfs support

- remove docs for internal func, doesn't add value
- add short overview snippet instead explaining that drivers don't
have to bother themselves with reg/unreg concerns
- drop the ttm comment about drmP.h, drmP.h is disappearing ...

Reviewed-by: Neil Armstrong <[email protected]>
Signed-off-by: Daniel Vetter <[email protected]>
Link: http://patchwork.freedesktop.org/patch/msgid/[email protected]

show more ...