These two didn't get documented properly, do so.

Pointed out by Daniel.

v1.1: add missing boilerplate (Daniel)
Reviewed-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NDave Airlie <airlied@redhat.com>

In all cases the text requires that new drivers are converted to the
atomic interfaces.

v2: Add overview for state handling.

v3: Review from Sean: Some spelling fixes and drop the misguided
hunk to remove rgba8888 from the plane helpers compat list.

Cc: Sean Paul <seanpaul@chromium.org>
Reviewed-by: NSean Paul <seanpaul@chromium.org>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Some differences compared to Rob's patches again:
- Dropped the committed and checked booleans. Checking will be
  internally enforced by always calling ->atomic_check before
  ->atomic_commit. And async handling needs to be solved differently
  because the current scheme completely side-steps ww mutex deadlock
  avoidance (and so either reinvents a new deadlock avoidance wheel or
  like the current code just deadlocks).

- State for connectors needed to be added, since now they have a
  full-blown drm_connector_state (so that drivers have something to
  attach their own stuff to).

- Refcounting is gone. I plane to solve async updates differently,
  since the lock-passing scheme doesn't cut it (since it abuses ww
  mutexes). Essentially what we need for async is a simple ownership
  transfer from the caller to the driver. That doesn't need full-blown
  refcounting.

- The acquire ctx is a pointer. Real atomic callers should have that
  on their stack, legacy entry points need to put the right one
  (obtained by drm_modeset_legacy_acuire_ctx) in there.

- I've dropped all hooks except check/commit. All the begin/end
  handling is done by core functions and is the same.

- commit/check are just thin wrappers that ensure that ->check is
  always called.

- To help out with locking in the legacy implementations I've added a
  helper to just grab all locks in the backoff case.

v2: Add notices that check/commit can fail with EDEADLK.

v3:
- More consistent naming for state_alloc.
- Add state_clear which is needed for backoff and retry.

v4: Planes/connectors can switch between crtcs, and we need to be
careful that we grab the state (and locks) for both the old and new
crtc. Improve the interface functions to ensure this.

v5: Add functions to grab affected connectors for a crtc and to recompute
the crtc->enable state. This is useful for both helper and atomic ioctl
code when e.g. removing a connector.

v6: Squash in fixup from Fengguang to use ERR_CAST.

v7: Add debug output.

v8: Make checkpatch happy about kcalloc argument ordering.

v9: Improve kerneldoc in drm_crtc.h

v10:
- Fix another kcalloc argument misorder I've missed.
- More polish for kerneldoc.

v11: Clarify the ownership rules for the state object. The new rule is
that a successful drm_atomic_commit (whether synchronous or asnyc)
always inherits the state and is responsible for the clean-up. That
way async and sync ->commit functions are more similar.

v12: A few bugfixes:
- Assign state->state pointers correctly when grabbing state objects -
  we need to link them up with the global state.
- Handle a NULL crtc in set_crtc_for_plane to simplify code flow a bit
  for the callers of this function.

v13: Review from Sean:
- kerneldoc spelling fixes
- Don't overallocate states->planes.
- Handle NULL crtc in set_crtc_for_connector.

v14: Sprinkle __must_check over all functions which do wait/wound
locking to make sure callers don't forget this. Since I have ;-)

v15: Be more explicit in the kerneldoc when functions can return
-EDEADLK what to do. And that every other -errno is fatal.

v16: Indent with tabs instead of space, spotted by Ander.

v17: Review from Thierry, small kerneldoc and other naming polish.

Cc: Thierry Reding <thierry.reding@gmail.com>
Cc: Ander Conselvan de Oliveira <conselvan2@gmail.com>
Cc: Daniel Thompson <daniel.thompson@linaro.org>
Cc: Fengguang Wu <fengguang.wu@intel.com>
Cc: Sean Paul <seanpaul@chromium.org>
Cc: Matt Roper <matthew.d.roper@intel.com>
Reviewed-by: NSean Paul <seanpaul@chromium.org>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

While writing atomic docs I've noticed that I don't get any errors
for my screw-ups in drm_crtc.h. Fix this immediately.

This just does the bare minimum to get starts, lots of stuff isn't
properly documented yet unfortunately.

v2: Fix adjacent spelling error Sean noticed.
Reviewed-by: NSean Paul <seanpaul@chromium.org>
Cc: Sean Paul <seanpaul@chromium.org>
Reviewed-by: NThierry Reding <treding@nvidia.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

v2: Fix spelling fail.
Reviewed-by: NPaulo Zanoni <paulo.r.zanoni@intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>

Just start with the basics for now.

Since there's a lot of different functionality in i915_irq.c I've
decided to split it into different sections and pull in just the
relevant functions. Splitting into different files looks like a lot
more work since the interrupt handlers do an awful lot of reuse all
over.

v2: Rebase onto changed function names.
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
Reviewed-by: NPaulo Zanoni <paulo.r.zanoni@intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

I've decided not to document the functions exported to the audio
driver since really, they shouldn't exist ...

v2: Improvements from Imre's review plus a few more spelling fixes
I've spotted.
Reviewed-by: NImre Deak <imre.deak@intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Only !P can be used together with a function list.

Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
Acked-by: NAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: NDave Airlie <airlied@redhat.com>

I shouldn't ask everyone to do this and fail myself ...

This extracts all the frontbuffer tracking functions into
intel_frontbuffer.c, adds a DOC overview section and also adds the
missing kerneldoc for i915_gem_track_fb and also pulls it into the
same section for convenience.

v2: Don't forget about the header files.

v3: Oops, might check compilation next time around. To make my life
easier drop the increase_pllclock from set_base_atomic since really,
it doesn't matter if you see your Oops or kgdb with a tiny bit of lag.

v4: Try to better explain how to actually use this, requested by Paulo
on irc.

v5: Explain invalidate/flush a bit clearer.

v6: s/business/busyness/
Acked-by: NPaulo Zanoni <paulo.r.zanoni@intel.com>
Cc: Paulo Zanoni <paulo.r.zanoni@intel.com>
Cc: Vandana Kannan <vandana.kannan@intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>

This merges all the remains of drm_usb into its only user, udl. We can
then drop all the drm_usb stuff, including dev->usbdev.
Signed-off-by: NDavid Herrmann <dh.herrmann@gmail.com>
Reviewed-by: NThierry Reding <treding@nvidia.com>
Reviewed-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NDave Airlie <airlied@redhat.com>

Add theory of operation notes to intel_lrc.c and comments to externally
visible functions.

v2: Add notes on logical ring context creation.

v3: Use kerneldoc.

v4: Integrate it in the DocBook template.

Signed-off-by: Thomas Daniel <thomas.daniel@intel.com> (v1)
Signed-off-by: Oscar Mateo <oscar.mateo@intel.com> (v2, v3)
Reviewed-by: NDamien Lespiau <damien.lespiau@intel.com>
[danvet: Drop hunk about render ring init function since that's not
yet merged.]
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Commit 21d70354 ("drm: move drm_stub.c to drm_drv.c") moves the code
from drm_stub.c into drm_drv.c. Update DocBook to include that instead.

This also came in via other people, but all the same.
Signed-off-by: NThierry Reding <treding@nvidia.com>
Reviewed-by: NDavid Herrmann <dh.herrmann@gmail.com>
Signed-off-by: NDave Airlie <airlied@redhat.com>

Add a small static inline helper to grab the vblank wait queue based on
the drm_crtc.

This is useful for drivers to do internal vblank waits using
wait_event() & co.

v2: Pimp commit message (Daniel)
    Add kernel doc (Daniel)
Suggested-by: NDaniel Vetter <daniel@ffwll.ch>
Signed-off-by: NVille Syrjälä <ville.syrjala@linux.intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Add a flag to drm_device which will cause the vblank code to bypass the
disable timer and always disable the vblank interrupt immediately when
the last reference is dropped.

v2: Add some notes about the flag to the kernel doc
Reviewed-by: NMatt Roper <matthew.d.roper@intel.com>
Reviewed-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NVille Syrjälä <ville.syrjala@linux.intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Make drm_vblank_put() disable the vblank interrupt immediately when the
refcount drops to zero and drm_vblank_offdelay<0.

v2: Preserve the current drm_vblank_offdelay==0 'never disable' behaviur
Reviewed-by: NMatt Roper <matthew.d.roper@intel.com>
Signed-off-by: NVille Syrjälä <ville.syrjala@linux.intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Updated drm documentation to include desscription of aspect ratio property.

v2: Updated aspect ratio specific documentation on top of the HTML table created.
Signed-off-by: NVandana Kannan <vandana.kannan@intel.com>
Cc: Sagar Kamble <sagar.a.kamble@intel.com>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Reviewed-by: NSagar Kamble <sagar.a.kamble@intel.com>
Acked-by: NDave Airlie <airlied@gmail.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Cc: damien.lespiau@intel.com
Cc: daniel.vetter@ffwll.ch
Cc: ville.syrjala@linux.intel.com
Signed-off-by: NSagar Kamble <sagar.a.kamble@intel.com>
Reviewed-by: NDamien Lespiau <damien.lespiau@intel.com>
Acked-by: NDave Airlie <airlied@linux.ie>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

These property descriptions were kept as placeholder. Removing them for simplicity.

Cc: damien.lespiau@intel.com
Cc: daniel.vetter@ffwll.ch
Cc: ville.syrjala@linux.intel.com
Signed-off-by: NSagar Kamble <sagar.a.kamble@intel.com>
Reviewed-by: NDamien Lespiau <damien.lespiau@intel.com>
Acked-by: NDave Airlie <airlied@linux.ie>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

This is the initial import of the helper for displayport multistream.

It consists of a topology manager, init/destroy/set mst state

It supports DP 1.2 MST sideband msg protocol handler - via hpd irqs

connector detect and edid retrieval interface.

It supports i2c device over DP 1.2 sideband msg protocol (EDID reads only)

bandwidth manager API via vcpi allocation and payload updating,
along with a helper to check the ACT status.

Objects:
MST topology manager - one per toplevel MST capable GPU port - not sure if this should be higher level again
MST branch unit - one instance per plugged branching unit - one at top of hierarchy - others hanging from ports
MST port - one port per port reported by branching units, can have MST units hanging from them as well.

Changes since initial posting:
a) add a mutex responsbile for the queues, it locks the sideband and msg slots, and msgs to transmit state
b) add worker to handle connection state change events, for MST device chaining and hotplug
c) add a payload spinlock
d) add path sideband msg support
e) fixup enum path resources transmit
f) reduce max dpcd msg to 16, as per DP1.2 spec.
g) separate tx queue kicking from irq processing and move irq acking back to drivers.

Changes since v0.2:
a) reorganise code,
b) drop ACT forcing code
c) add connector naming interface using path property
d) add topology dumper helper
e) proper reference counting and lookup for ports and mstbs.
f) move tx kicking into a workq
g) add aux locking - this should be redone
h) split teardown into two parts
i) start working on documentation on interface.

Changes since v0.3:
a) vc payload locking and tracking fixes
b) add hotplug callback into driver - replaces crazy return 1 scheme
c) txmsg + mst branch device refcount fixes
d) don't bail on mst shutdown if device is gone
e) change irq handler to take all 4 bytes of SINK_COUNT + ESI vectors
f) make DP payload updates timeout longer - observed on docking station redock
g) add more info to debugfs dumper

Changes since v0.4:
a) suspend/resume support
b) more debugging in debugfs

Changes since v0.5:
a) use byte * to avoid unnecessary stack usage
b) fix num_sdp_streams interpretation.
c) init payload state for unplug events
d) remove lenovo dock sink count hack
e) drop aux lock - post rebase
f) call hotplug on port destroy

TODO:
misc features
Reviewed-by: NTodd Previte <tprevite@gmail.com>
Signed-off-by: NDave Airlie <airlied@redhat.com>

Introduce generic functions to register and unregister connectors. This
provides a common place to add and remove associated user space
interfaces.
Signed-off-by: NThomas Wood <thomas.wood@intel.com>
Reviewed-by: NDavid Herrmann <dh.herrmann@gmail.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Matt aded this plane property before we had a table giving a summary of
the properties. Add it there.

Cc: Matt Roper <matthew.d.roper@intel.com>
Signed-off-by: NDamien Lespiau <damien.lespiau@intel.com>
Signed-off-by: NDave Airlie <airlied@redhat.com>

Signed-off-by: NDamien Lespiau <damien.lespiau@intel.com>
Reviewed-by: NAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: NDave Airlie <airlied@redhat.com>

With the recent addition of the drm_set_unique() function, devices can
now be registered without requiring a drm_bus. Add a brief description
to the DRM docbook to show how that can be achieved.
Reviewed-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NThierry Reding <treding@nvidia.com>

Describe how devices are registered using the drm_*_init() functions.
Adding this to docbook requires a largish set of changes to the comments
in drm_{pci,usb,platform}.c since they are doxygen-style rather than
proper kernel-doc and therefore mess with the docbook generation.

While at it, mark usage of drm_put_dev() as discouraged in favour of
calling drm_dev_unregister() and drm_dev_unref() directly.
Acked-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NThierry Reding <treding@nvidia.com>

For atomic, it will be quite necessary to not need to care so much
about locking order.  And 'state' gives us a convenient place to stash a
ww_ctx for any sort of update that needs to grab multiple crtc locks.

Because we will want to eventually make locking even more fine grained
(giving locks to planes, connectors, etc), split out drm_modeset_lock
and drm_modeset_acquire_ctx to track acquired locks.

Atomic will use this to keep track of which locks have been acquired
in a transaction.

v1: original
v2: remove a few things not needed until atomic, for now
v3: update for v3 of connection_mutex patch..
v4: squash in docbook
v5: doc tweaks/fixes
Signed-off-by: NRob Clark <robdclark@gmail.com>
Reviewed-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NDave Airlie <airlied@redhat.com>

Started documenting drm properties for drm drivers. This patch provides
information about properties in drm, i915, psb and cdv/gma-500. Information
about other properties can be added on top of these.

v2: Added description of drm properties in armada, exynos, i2c/ch7006, noveau,
omap, qxl, radeon, rcar-du

v3: Removed "Property Object" column since it is implementation related. Property
type column refined.[Ville's review comments]

v4: Removed whitespace warnings and minor nits. [Randy's review comments]

v5: Restructured output for ENUM properties

v6: Review comments on formatting the table. [Laurent's review comments]

v7: Minor restructuring. [Laurent's review comments]

Cc: Rob Landley <rob@landley.net>
Cc: Dave Airlie <airlied@redhat.com>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Acked-by: NLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Cc: David Herrmann <dh.herrmann@gmail.com>
Cc: Alex Deucher <alexander.deucher@amd.com>
Cc: "Ville Syrjälä" <ville.syrjala@linux.intel.com>
Cc: Sagar Kamble <sagar.a.kamble@intel.com>
Cc: "Purushothaman, Vijay A" <vijay.a.purushothaman@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: dri-devel@lists.freedesktop.org
Signed-off-by: NSagar Kamble <sagar.a.kamble@intel.com>
Signed-off-by: NDave Airlie <airlied@redhat.com>

Fix spelling typo in DocBook/drm.tmpl
Signed-off-by: NMasanari Iida <standby24x7@gmail.com>
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NDave Airlie <airlied@redhat.com>

Fix spelling typo in DocBook/drm.tmpl
Signed-off-by: NMasanari Iida <standby24x7@gmail.com>
Signed-off-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

The ascii art version of the DPIO diagram gets mangled by docbook, so
we can't use it there. Insted provide another version built using
<table>.
Signed-off-by: NVille Syrjälä <ville.syrjala@linux.intel.com>
Reviewed-by: NChon Ming Lee <chon.ming.lee@intel.com>
Reviewed-by: NDamien Lespiau <damien.lespiau@intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Document the internal structure of the VLV display PHY a bit to help
people understand how the different register blocks relate to each
other.

v2: Add a bit more text
    Make it a DOC: comment, but leave the ascii art out since
    it would get mangled
Signed-off-by: NVille Syrjälä <ville.syrjala@linux.intel.com>
Reviewed-by: NChon Ming Lee <chon.ming.lee@intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

- Integrate into the drm DocBook
- Disable kerneldoc for functions not exported to drivers.
- Properly document the new drm_vblank_on|off and add cautious
  comments explaining when drm_vblank_pre|post_modesets shouldn't be
  used.
- General polish and OCD.

v2: Polish as suggested by Thierry.

Cc: Thierry Reding <thierry.reding@gmail.com>
Reviewed-by: NVille Syrjälä <ville.syrjala@linux.intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Leftover from the old days of ums and should be used any longer. Since

commit 29935554
Author: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Date:   Wed May 30 00:58:09 2012 +0200

    drm: Disallow DRM_IOCTL_MODESET_CTL for KMS drivers

it is a complete no-Op for kms drivers.

v2: Fix up mangled sentence spotted by Michel.

Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Michel Dänzer <michel@daenzer.net>
Reviewed-by: NVille Syrjälä <ville.syrjala@linux.intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Ville noticed that we have this nice kerneldoc but it's not integrated
anywhere. Fix this asap!

Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
Cc: Brad Volkin <bradley.d.volkin@intel.com>
Reviewed-by: NVille Syrjälä <ville.syrjala@linux.intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Unfortunately this requires a drm-wide change, and I didn't see a sane
way around that. Luckily it's fairly simple, we just need to inline
the respective get_irq implementation from either drm_pci.c or
drm_platform.c.

With that we can now also remove drm_dev_to_irq from drm_irq.c.
Reviewed-by: NThierry Reding <treding@nvidia.com>
Reviewed-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Many drm connectors do not need mode validation.
The patch makes this callback optional and removes dumb implementations.

v2: Rebase:
- imx move to a shared (but still dummy) ->mode_valid implementation.
- probe helpers have been extracted to drm_probe_helper.c

Signed-off-by: Andrzej Hajda <a.hajda@samsung.com> (v1)
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

This is leftover stuff from my previous doc round which I kinda wanted
to do but didn't yet due to rebase hell.

The modeset helpers and the probing helpers a independent and e.g.
i915 uses the probing stuff but has its own modeset infrastructure. It
hence makes to split this up. While at it add a DOC: comment for the
probing libraray.

It would be rather neat to pull some of the DocBook documenting these
two helpers into in-line DOC: comments. But unfortunately kerneldoc
doesn't support markdown or something similar to make nice-looking
documentation, so the current state is better.
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: NDave Airlie <airlied@redhat.com>

Signed-off-by: NMatt Roper <matthew.d.roper@intel.com>
Reviewed-by: NRob Clark <robdclark@gmail.com>

Oops. This is a regression from

commit 5d7a9515
Author: Daniel Vetter <daniel.vetter@ffwll.ch>
Date:   Fri Jan 4 22:31:20 2013 +0100

    drm/doc: updates for new framebuffer lifetime rules
Reviewed-by: NAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

- Tune down yelling RETURNS.
- OCD align all the parameters the same.
- Add missing kerneldoc, which also means that we need to include the
  kerneldoc from the drm_modes.h header now.
- Add missing Returns: sections.
- General polish and clarification - especially the kerneldoc for the
  mode creation helpers seems to have been some good specimen of
  copypasta gone wrong.

All actual code changes have all been extracted into prep patches
since there was simply too much to polish.

v2: More polish for the command line modeline functions.
Reviewed-by: NAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

And clean it up so that there's no kerneldoc warnings. There's still a
lot to do with this one here.
Reviewed-by: NAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>