KMS documentation for userspace

[Daniel Vetter]

On Wed, Jun 19, 2019 at 9:36 PM Simon Ser <contact at emersion.fr> wrote:
>
> Hi all,
>
> With Wayland compositors and DRM leases, the number of DRM userspace
> programs has increased (and will probably continue to increase).
> However it's been pretty hard to find good DRM docs for userspace.
>
> The resources currently available are:
>
> - The kernel docs, although only the high level overview is useful to
>   userspace.
> - User-contributed tutorials, like [1] and [2].
> - To help userspace understand hardware capabilities and limitations,
>   I've recently started a DRM database dump project [3].
>
> (Anything else I've missed?)
>
> We still lack docs that describe how to properly use the KMS API and
> the KMS properties. There is a deprecated list at [4], and another list
> mixed with kernel structs at [5]. This is not great for userspace
> developers.
>
> So I wanted to know if there's interest from the kernel community to
> maintain documentation for userspace? Or should userspace maintain its
> own docs of the kernel API?
>
> I don't know what would be the best place for these docs. If they live
> in kernel doc comments, then references to kernel functions and
> guidelines for kernel devs will appear (just like in the current docs).
> If they live outside of the kernel source code or outside of the kernel
> tree, they might get outdated.
>
> Thoughts?

tldr; Yes, I just didn't get around to it yet.

The rough plan is to actually document ioctls and properties and all
that stuff in drm-uapi.rst, and then cross-link that with the
driver-side documentation. Current status:
- ioctl docs: doesn't exist
- property docs: spotty, needs to be extracted from
https://01.org/linuxgraphics/gfx-docs/drm/gpu/drm-kms.html#kms-properties
without going crazy (I think you got your links for references 4 and 5
wrong, but it's all the same chapter anyway)
- figure out whether we can use the media uapi sphinx stuff to catch
when new ioctls/structs/props have been added without corresponding
documentation
- figure out what to do with the libdrm manpages. Some stuff we really
want to also document there. But geez nroff. Maybe we need to stuff
libdrm into the kernel, dunno.

I'd say 5-10 years of chugging along until this is fixed. The
in-kernel docs took about as long:

commit 2d2ef822758e3f5da59c40a392d0c6d89394d4b4
Author: Jesse Barnes <jbarnes at virtuousgeek.org>
Date:   Mon Oct 26 13:06:31 2009 -0700

    drm: add initial DRM developer documentation

If you are exceendingly bored and want to get started right away,
document everything in include/uapi/drm/drm*.h as a start :-)

Cheers, Daniel

> Thanks,
>
> [1]: https://github.com/ascent12/drm_doc
> [2]: https://gitlab.freedesktop.org/daniels/kms-quads
> [3]: https://drmdb.emersion.fr/
> [4]: https://01.org/linuxgraphics/gfx-docs/drm/gpu/drm-kms.html#standard-connector-properties
> [5]: https://01.org/linuxgraphics/gfx-docs/drm/gpu/drm-kms.html#existing-kms-properties
>
> --
> Simon Ser
> https://emersion.fr
>
>
> _______________________________________________
> dri-devel mailing list
> dri-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel



-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch