Signed-off-by: NLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Reviewed-by: NAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: NDave Airlie <airlied@redhat.com>

The i915 driver has been fixed not to modify the mode argument of the
encoder mode_fixup operation. Remove the related comment from the
documentation.
Signed-off-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: NAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: NDave Airlie <airlied@redhat.com>

Define the rules for using irqs from drm drivers.
Signed-off-by: NLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Reviewed-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NDave Airlie <airlied@redhat.com>

The 'struct' keyword was missing so struct drm_rect documentation never
ended up in the generated docs.

Also move the drm_rect documentations to a new section alognside the
various helper functions and add a short description about the intended
purpose of drm_rect.

v2: Move to new section and add general description
Signed-off-by: NVille Syrjälä <ville.syrjala@linux.intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

struct drm_rect represents a simple rectangle. The utility
functions are there to help driver writers.

v2: Moved the region stuff into its own file, made the smaller funcs
    static inline, used 64bit maths in the scaled clipping function to
    avoid overflows (instead it will saturate to INT_MIN or INT_MAX).
v3: Renamed drm_region to drm_rect, drm_region_clip to
    drm_rect_intersect, and drm_region_subsample to drm_rect_downscale.
v4: Renamed some function parameters, improve kernel-doc comments a bit,
    and actually generate documentation for drm_rect.[ch].
v5: s/RETUTRNS/RETURNS/
Reviewed-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: NChris Wilson <chris@chris-wilson.co.uk>
Signed-off-by: NVille Syrjälä <ville.syrjala@linux.intel.com>
Acked-by: NDave Airlie <airlied@gmail.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Driver implementations of the drm_crtc's .page_flip() function are
required to update the crtc->fb field on success to reflect that the new
framebuffer is now in use. This is important to keep reference counting
on the framebuffers balanced.

While at it, document this requirement to keep others from falling into
the same trap.
Suggested-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NThierry Reding <thierry.reding@avionic-design.de>
Reviewed-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Add a reference section about the EDID helper functions to the DRM
documentation.
Signed-off-by: NThierry Reding <thierry.reding@avionic-design.de>
Reviewed-by: NAlex Deucher <alexander.deucher@amd.com>

Now that the fbdev helper interface for drivers is trimmed down,
update the kerneldoc for all the remaining exported functions.

I've tried to beat the DocBook a bit by reordering the function
references a bit into a more sensible ordering. But that didn't work
out at all. Hence just extend the in-code DOC: section a bit.

Also remove the LOCKING: sections - especially for the setup functions
they're totally bogus. But that's not a documentation problem, but
simply an artifact of the current rather hazardous locking around drm
init and even more so around fbdev setup ...

v2: Some further improvements:
- Also add documentation for drm_fb_helper_single_add_all_connectors,
  Dave Airlie didn't want me to kill this one from the fb helper
  interface.
- Update docs for drm_fb_helper_fill_var/fix - they should be used
  from the driver's ->fb_probe callback to setup the fbdev info
  structure.
- Clarify what the ->fb_probe callback should all do - it needs to
  setup both the fbdev info and allocate the drm framebuffer used as
  backing storage.
- Add basic documentaation for the drm_fb_helper_funcs driver callback
  vfunc.

v3: Implement clarifications Laurent Pinchart suggested in his review.

v4: Fix another mispelling Laurent spotted.

Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Acked-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Instead of reimplementing all of the dma_buf functionality in every driver,
create helpers drm_prime_import and drm_prime_export that implement them in
terms of new, lower-level hook functions:

  gem_prime_pin: callback when a buffer is created, used to pin buffers into GTT
  gem_prime_get_sg_table: convert a drm_gem_object to an sg_table for export
  gem_prime_import_sg_table: convert an sg_table into a drm_gem_object
  gem_prime_vmap, gem_prime_vunmap: map and unmap an object

These hooks are optional; drivers can opt in by using drm_gem_prime_import and
drm_gem_prime_export as the .gem_prime_import and .gem_prime_export fields of
struct drm_driver.

v2:
- Drop .begin_cpu_access.  None of the drivers this code replaces implemented
  it.  Having it here was a leftover from when I was trying to include i915 in
  this rework.
- Use mutex_lock instead of mutex_lock_interruptible, as these three drivers
  did.  This patch series shouldn't change that behavior.
- Rename helpers to gem_prime_get_sg_table and gem_prime_import_sg_table.
  Rename struct sg_table* variables to 'sgt' for clarity.
- Update drm.tmpl for these new hooks.

v3:
- Pass the vaddr down to the driver.  This lets drivers that just call vunmap on
  the pointer avoid having to store the pointer in their GEM private structures.
- Move documentation into a /** DOC */ comment in drm_prime.c and include it in
  drm.tmpl with a !P line.  I tried to use !F lines to include documentation of
  the individual functions from drmP.h, but the docproc / kernel-doc scripts
  barf on that file, so hopefully this is good enough for now.
- apply refcount fix from commit be8a42ae
  ("drm/prime: drop reference on imported dma-buf come from gem")
Signed-off-by: NAaron Plattner <aplattner@nvidia.com>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: David Airlie <airlied@linux.ie>
Signed-off-by: NDave Airlie <airlied@redhat.com>

Now that framebuffer are reference-counted for all use-sites, update
the documentation accordingly to stress the new rules for
initialization and teardown.

Also add a short paragraph about the implications for drivers of the
new locking rules.
Reviewed-by: NRob Clark <rob@ti.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

And do a quick pass to adjust them to the last few (years?) of changes
...

This time actually compile-tested ;-)
Reviewed-by: NRob Clark <rob@ti.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

I didn't bother with documenting the really trivial new "extract
something from dpcd" helpers, but the i2c over aux ch is now
documented a bit.

v2: Clarify the comment for i2c_dp_aux_add_bus a bit.

v3: Fix more spelling fail spotted by Laurent Pinchart.
Acked-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NDave Airlie <airlied@redhat.com>

Again only minimal changes to make kerneldoc no longer shout. Plus a
little introduction in the form of a inline DOC: section to quickly
explain what this is all about.

v2: Fixup spelling fail.
Acked-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NDave Airlie <airlied@redhat.com>

- Add the missing doc for drm_helper_move_panel_connectors_to_head.
- Fixup any outdated stuff in existing sections. I've only looked at
  those kerneldoc headers that actually resulted in a complaint from
  the kerneldoc parser tool.

v2:
- Actually include the docbook snippet in the right patch.
- Fix spelling fail.

v3: It's now called drm_crtc_helper_set_mode, spotted by Laurent
Pinchart.
Acked-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NDave Airlie <airlied@redhat.com>

I'm devoting all my wrath to that fight, so don't misname it ;-)

v2: Make it clear that this section talks about kms helpers.
Acked-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NDave Airlie <airlied@redhat.com>

A helper that drivers can use to send vblank event after a pageflip.
If the driver doesn't support proper vblank irq based time/seqn then
just pass -1 for the pipe # to get do_gettimestamp() behavior (since
there are a lot of drivers that don't use drm_vblank_count_and_time())

Also an internal send_vblank_event() helper for the various other code
paths within drm_irq that also need to send vblank events.

v1: original
v2: add back 'vblwait->reply.sequence = seq' which should not have
    been deleted
v3: add WARN_ON() in case lock is not held and comments
v4: use WARN_ON_SMP() instead to fix issue with !SMP && !DEBUG_SPINLOCK
    as pointed out by Marcin Slusarz
v5: update docbook
Signed-off-by: NRob Clark <rob@ti.com>
Signed-off-by: NDave Airlie <airlied@redhat.com>

Signed-off-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: NRob Clark <rob.clark@linaro.org>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

  From Webster's Revised Unabridged Dictionary (1913) [web1913]:

    So-called \So"-called`\, a.
       So named; called by such a name (but perhaps called thus with
       doubtful propriety).

  From WordNet (r) 2.0 [wn]:

    so-called
         adj : doubtful or suspect; "these so-called experts are no help"
               [syn: {alleged(a)}, {supposed}]

My strong conviction is that widespread use of 'so gennant'
or 'sogennant' in German has led to the creeping misuse of
'so-called' in English (especially through technical writings).

In English, it would be better to use:

  what is called

or a better translation of 'so gennant':

  so named
Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>

Signed-off-by: NMichael Witten <mfwitten@gmail.com>