linux.git/Documentation/gpu/drm-uapi.rst, branch v4.14

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

2017-06-20T08:41:29+00:00

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 
Acked-by: Thierry Reding 
Signed-off-by: Daniel Vetter 
Link: http://patchwork.freedesktop.org/patch/msgid/20170531092045.3950-1-daniel.vetter@ffwll.ch

drm: document drm_ioctl.[hc]

2017-04-04T18:47:54+00:00

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 
Reviewed-by: Neil Armstrong 
Signed-off-by: Daniel Vetter 
Link: http://patchwork.freedesktop.org/patch/msgid/20170404095304.17599-4-daniel.vetter@ffwll.ch

drm: Consolidate and document sysfs support

2017-04-04T18:47:54+00:00

- 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 
Signed-off-by: Daniel Vetter 
Link: http://patchwork.freedesktop.org/patch/msgid/20170404095304.17599-2-daniel.vetter@ffwll.ch

drm/debugfs: Add kerneldoc

2017-03-24T08:36:06+00:00

I've decided to not document drm_debugfs_remove_files, it's on the way
out.

The biggest part is a huge todo.rst entry with what all should be
improved.

v2: Nits from Gabriel.

Cc: Gabriel Krisman Bertazi 
Reviewed-by: Gabriel Krisman Bertazi 
Signed-off-by: Daniel Vetter 
Link: http://patchwork.freedesktop.org/patch/msgid/20170322205401.24897-1-daniel.vetter@ffwll.ch

drm: document driver interface for CRC capturing

2017-03-24T08:36:06+00:00

This was missed in Tomeu's patch. Also remove the kerneldoc for the
internal function, we don't document that in general.

While at it word-smith the docs slightly for more clarity.

Cc: Tomeu Vizoso 
Reviewed-by: Tomeu Vizoso 
Signed-off-by: Daniel Vetter 
Link: http://patchwork.freedesktop.org/patch/msgid/20170322083617.13361-4-daniel.vetter@ffwll.ch

drm/doc: Document drm_file.[hc]

2017-03-14T13:38:33+00:00

Well, mostly drm_file.h, and clean up all related things:

- I didnt' figure out the difference between preclose and postclose.
  The existing explanation in drm-internals.rst didn't convince me,
  since it's also really outdated - we clean up pending DRM events in
  the core nowadays. I put a FIXME in for the future.

- Another FIXME is to have a macro for default fops.

- Lots of links all around, main areas are to tie the overview in
  drm_file.c more into the callbacks in struct drm_device, and the
  other is to link render/primary node code to the right sections in
  drm-uapi.rst.

- Also moved the open/close stuff to drm_drv.h from drm-internals.rst,
  seems like the better place for that information. Since that section
  was rather outdated this amounted to full-on rewrite.

A big missing piece here is some overview graph, but I think better to
wait with that one until drm_device and drm_driver are also fully
documented.

v2: Nits from Sean.

Reviewed-by: Sean Paul 
Reviewed-by: Liviu Dudau 
Signed-off-by: Daniel Vetter 
Link: http://patchwork.freedesktop.org/patch/msgid/20170308141257.12119-12-daniel.vetter@ffwll.ch

drm/docs: Small cleanup in drm-uapi.rst

2016-12-30T11:53:33+00:00

- Remove the outdated hunk about driver documentation which somehow
  got misplaced here in the split-up.

- Collect all the testing&validation stuff together and give the CRC
  section a heading for prettier output.

Cc: Tomeu Vizoso 
Cc: Jani Nikula 
Reviewed-by: David Herrmann 
Signed-off-by: Daniel Vetter 
Link: http://patchwork.freedesktop.org/patch/msgid/1483044517-5770-1-git-send-email-daniel.vetter@ffwll.ch

drm: Add API for capturing frame CRCs

2016-10-17T14:44:34+00:00

Adds files and directories to debugfs for controlling and reading frame
CRCs, per CRTC:

dri/0/crtc-0/crc
dri/0/crtc-0/crc/control
dri/0/crtc-0/crc/data

Drivers can implement the set_crc_source callback() in drm_crtc_funcs to
start and stop generating frame CRCs and can add entries to the output
by calling drm_crtc_add_crc_entry.

v2:
- Lots of good fixes suggested by Thierry.
- Added documentation.
- Changed the debugfs layout.
- Moved to allocate the entries circular queue once when frame
generation gets enabled for the first time.
v3:
- Use the control file just to select the source, and start and stop
capture when the data file is opened and closed, respectively.
- Make variable the number of CRC values per entry, per source.
- Allocate entries queue each time we start capturing as now there
isn't a fixed number of CRC values per entry.
- Store the frame counter in the data file as a 8-digit hex number.
- For sources that cannot provide useful frame numbers, place
XXXXXXXX in the frame field.

v4:
- Build only if CONFIG_DEBUG_FS is enabled.
- Use memdup_user_nul.
- Consolidate calculation of the size of an entry in a helper.
- Add 0x prefix to hex numbers in the data file.
- Remove unnecessary snprintf and strlen usage in read callback.

v5:
- Made the crcs array in drm_crtc_crc_entry fixed-size
- Lots of other smaller improvements suggested by Emil Velikov

v7:
- Move definition of drm_debugfs_crtc_crc_add to drm_internal.h

v8:
- Call debugfs_remove_recursive when we fail to create the minor
device

v9:
- Register the debugfs directory for a crtc from
drm_crtc_register_all()

v10:
- Don't let debugfs failures interrupt CRTC registration (Emil
Velikov)

v11:
- Remove extra brace that broke compilation. Sorry!

Signed-off-by: Tomeu Vizoso
Reviewed-by: Emil Velikov
Acked-by: Benjamin Gaignard
Signed-off-by: Daniel Vetter
Link: http://patchwork.freedesktop.org/patch/msgid/1475767268-14379-3-git-send-email-tomeu.vizoso@collabora.com

drm/doc: Add a few words on validation with IGT

2016-09-01T08:41:53+00:00

Also provide some pointers for building IGT as some kernel hackers might
not be that familiar with building stuff on Linux distros.

Signed-off-by: Tomeu Vizoso 
Cc: Daniel Vetter 
Signed-off-by: Daniel Vetter 
Link: http://patchwork.freedesktop.org/patch/msgid/1472715695-19812-1-git-send-email-tomeu.vizoso@collabora.com

drm/doc: Document uapi requirements in DRM

2016-08-23T21:13:08+00:00

Everyone knows them, except all the new folks joining from the ARM
side haven't lived through all the pain of the past years and are
entirely surprised when I raise this. Definitely time to document
this.

Last time this was a big discussion was about 6 years ago, when qcom
tried to land a kernel driver without userspace. Dave Airlie made the
rules really clear:

http://airlied.livejournal.com/73115.html

This write-up here is essentially what I've put into a presentation a
while ago, which was also reviewed by Dave:

http://blog.ffwll.ch/2015/05/gfx-kernel-upstreaming-requirements.html

v2: Fix typos Eric&Rob spotted.

v3: Nitpick from Jani.

Cc: Dave Airlie 
Cc: Oded Gabbay 
Cc: Russell King 
Cc: Tomi Valkeinen 
Cc: Eric Anholt 
Cc: Thomas Hellstrom 
Cc: Sinclair Yeh 
Cc: Lucas Stach 
Cc: Benjamin Gaignard 
Cc: Mark Yao 
Cc: Laurent Pinchart 
Cc: Ben Skeggs 
Cc: Rob Clark 
Cc: CK Hu 
Cc: Xinliang Liu 
Cc: Philipp Zabel 
Cc: Stefan Agner 
Cc: Inki Dae 
Cc: Maxime Ripard  
Cc: Boris Brezillon 
Cc: Jani Nikula 
Cc: Daniel Vetter 
Cc: Thierry Reding 
Cc: Christian König 
Cc: Alex Deucher 
Cc: Gerd Hoffmann 
Cc: Brian Starkey 
Cc: Liviu Dudau 
Cc: Alexey Brodkin 
Acked-by: Dave Airlie 
Reviewed-by: Rob Clark 
Reviewed-by: Christian König 
Reviewed-by: Eric Anholt 
Reviewed-by: Jani Nikula 
Signed-off-by: Daniel Vetter 
Signed-off-by: Dave Airlie