Another pile of vfuncs from the old gpu.tmpl xml documentation that
I've forgotten to delete. I spotted a few more things to
clarify/extend in the new kerneldoc while going through this once
more.

v2: Spelling fixes (Thierry).

v3: More spelling fixes and use Thierry's proposal to clarify why
drivers need to validate modes both in ->mode_fixup and ->mode_valid.

Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Thierry Reding <treding@nvidia.com>
Acked-by: NThierry Reding <treding@nvidia.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>

Fix indentation of vga_switcheroo sections in gpu.tmpl.

Change section type of API documentation from "chapter" to "sect1"
so that the individual functions no longer clutter up the ToC.
Group together under a new "API" chapter.

Fix wording "heretoforth" -> "henceforth".
Signed-off-by: NLukas Wunner <lukas@wunner.de>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

I missed a few paragraphs in the docbook that need to be pulled into
the fbdev vfunc docs.

v2: Spelling fixes from Thierry.

Cc: Thierry Reding <treding@nvidia.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1449564561-3896-3-git-send-email-daniel.vetter@ffwll.chReviewed-by: NThierry Reding <treding@nvidia.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>

DRM Docbook is now Markdown ready. This means its doc is able to
use markdown text on it.

* Documentation/DocBook/drm.tmpl: Contains a table duplicated from
  drivers/gpu/drm/i915/i915_reg.h. This is not needed anymore

* drivers/gpu/drm/drm_modeset_lock.c: had a code example that used
  to look pretty bad on html. Fixed by using proper code markup.

* drivers/gpu/drm/drm_prime.c: Remove spaces between lines to make
  a proper markup list.

* drivers/gpu/drm/i915/i915_reg.h: Altought pandoc supports tables,
  it doesn't support table cell spanning. But we can use fixed-width
  for those special cases.

* include/drm/drm_vma_manager.h: Another code example that should be
  proper indented with four spaces.

v2 (Daniel): Adjust name to gpu.xml due to rename.

v3 (Daniel):
Split out the actual enabling in the Makefile - this way we can merge
the conversion, while just keeping the enabling in a drm-private tree.

Signed-off-by: Danilo Cesar Lemes de Paula <danilo.cesar@collabora.co.uk> (v1)
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: Stephan Mueller <smueller@chronox.de>
Cc: Michal Marek <mmarek@suse.cz>
Cc: linux-kernel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: intel-gfx <intel-gfx@lists.freedesktop.org>
Cc: dri-devel <dri-devel@lists.freedesktop.org>
Acked-by: NDave Airlie <airlied@redhat.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1448471279-19748-2-git-send-email-daniel.vetter@ffwll.ch

Every time I type or review docs this seems a bit different. Try to
document the common style so we can try to unify at least new docs.

v2: Spelling fixes from Pierre, Laurent and Jani.

v3: More spelling fixes from Lukas.

Cc: Pierre Moreau <pierre.morrow@free.fr>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: Lukas Wunner <lukas@wunner.de>
Acked-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1449564561-3896-1-git-send-email-daniel.vetter@ffwll.ch

This was in the documentation for modeset helper hooks, where it is a
bit misplaced.

v2: Reindent the drm_mode_status enum, inspired by Ville.

v3: Suggestions from Ville and Thierry.

v4: Small fixup that 0day spotted.

v5: Slight change to avoid accidental headings in kerneldoc output.

Cc: ville.syrjala@linux.intel.com
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-27-git-send-email-daniel.vetter@ffwll.ch
Reviewed-by: Ville Syrjälä <ville.syrjala@linux.intel.com> (v3)
Reviewed-by: Thierry Reding <treding@nvidia.com> (v3)

And merge any docbook we have into the kerneldoc comments.

Since it's a legacy entry point with only two implementation (one each
in atomic and legacy crtc helpers) I've made the documentation for
set_config fairly sparse - no one should ever need to look at this
again, all the ABI we have is baked into code.

For ->page_flip otoh I kept all the extensive docs from the docbook
and even extended it where it was lacking: Currently we have a pile of
legacy page_flip implemantations, and even for atomic drivers there's
not yet a standard implementation in the helpers. Which means every
driver needs to implement this itself, and precise specs are really
valuable.

Otherwise there's just cursor, which really just boils down to "use at
least universal planes". And gamma tables (where we have a bit a mess
with the fbdev helper gamma hooks).

v2: Spelling fixes (Eric).

v3: Suggestions from Thierry.

Cc: Eric Anholt <eric@anholt.net>
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-20-git-send-email-daniel.vetter@ffwll.ch

Yes these are internal functions and not exported and we generally
don't document them. But for symmetry with the _set_property functions
(which are exported for the atomic helpers) I'd like to document them.
Upcoming vtable kerneldoc will reference both the set and get_property
functions.

v2: Suggestions from Thierry.
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>
Reviewed-by: NThierry Reding <treding@nvidia.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-17-git-send-email-daniel.vetter@ffwll.ch

- Merge the docbook into the kerneldoc comments.

- Spec in detail the precise semantics of the callbacks.

- For consistency in wording and easier review roll out kerneldoc also
  for crtc, encoder and connector for the standard hooks they share
  with planes.

v2: Suggestions from Thierry.
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-8-git-send-email-daniel.vetter@ffwll.chReviewed-by: NThierry Reding <treding@nvidia.com>

Duplication is bad, luckily both help texts highlighted different
issues so the kerneldoc gained quite a bit!

While at it also sprinkle more references to the vtable structs around
and make it clear that legacy CRTC helpers are deprecated and which
functions to use instead.

v2: Spelling fixes and polish (Thierry).
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-6-git-send-email-daniel.vetter@ffwll.chReviewed-by: NThierry Reding <treding@nvidia.com>

Currently we have 4 helper libraries (probe, crtc, plane & atomic)
that all use the same helper vtables. And that's by necessity since we
don't want to litter the core structs with one ops pointer per helper
library. Also often the reuse the same hooks (like atomic does, to
facilite conversion from existing drivers using crtc and plane
helpers).

Given all that it doesn't make sense to put the docs for these next to
specific helpers. Instead extract them into a new header file and
section in the docbook, and add references to them everywhere.

Unfortunately kernel-doc complains when an include directive doesn't
find anything (and it does by dumping crap into the output file). We
have to remove the now empty includes to avoid that, instead of leaving
them in for future proofing.

v2: More OCD in ordering functions.

v3: Spelling plus collate copyright headers properly.
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1449218769-16577-4-git-send-email-daniel.vetter@ffwll.chReviewed-by: NThierry Reding <treding@nvidia.com>

A bunch of things have been removed meanwhile and docs not fully
brought up to speed. And a few gaps closed where I noticed missing
kerneldoc while reading through the overview sections.
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1445533889-7661-3-git-send-email-daniel.vetter@ffwll.chReviewed-by: NAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

I just realized that I've forgotten to update all the gem refcounting
docs. For pennance also add pretty docs for the overall drm_gem_object
structure, with a few links thrown in fore good.

As usually we need to make sure the kerneldoc reference is at most a
sect2 for otherwise it won't be listed.
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
Link: http://patchwork.freedesktop.org/patch/msgid/1445533889-7661-1-git-send-email-daniel.vetter@ffwll.chReviewed-by: NAlex Deucher <alexander.deucher@amd.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

These have been missing in the template file although they provide
good kernel doc comments.  Let's add them.
Signed-off-by: NTakashi Iwai <tiwai@suse.de>

While there is nothing wrong with the transfer_ack_begin and
transfer_ack_end callbacks per-se, the last documented user was part of the
alsa-driver 0.5.12a package, which was released 14 years ago and even
predates the upstream integration of the ALSA core and has subsequently
been superseded by newer alsa-driver releases.

This seems to indicate that there is no need for having these callbacks and
they are just cruft that can be removed.
Signed-off-by: NLars-Peter Clausen <lars@metafoo.de>
Signed-off-by: NTakashi Iwai <tiwai@suse.de>

The size / offset information of all firmware ingredients are
now caculated from header. Driver will validate the header and
rsa key size. If any component is out of boundary, driver will
reject the loading too.

v6: Clean up warnings from make docs

v5: Tidy up GuC titles in kernel/Doc

v4: Now using 'size_dw' for those defined in css_header

v3: 1) Move DOC to intel_guc_fwif.h right before css_header
definition. Add more comments.
    2) Change 'size' to 'len' or 'length' to avoid confusion.
    3) Add UOS_RSA_SCRATCH_MAX_COUNT according to BSpec. And
driver validate size of RSA key now.
    4) Add fw component size/offset info to intel_guc_fw.

v2: Add indent into DOC to make fixed-width format rather than
change the tmpl.

v1: 1) guc_css_header is defined as __packed now
    2) Add and correct GuC related topics in kernel/Doc
Signed-off-by: NAlex Dai <yu.dai@intel.com>
Reviewed-by: NDave Gordon <david.s.gordon@intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

- Update the copyright year to 2015 in media_api.tmpl.
- Main version number of the spec updated to 4.4.
- Version 3.21 was used for one changelog, this should be 4.1.
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

A copy-paste from DECODER_CMD : replace decoded by encoded.
Signed-off-by: NJean-Michel Hautbois <jean-michel.hautbois@veo-labs.com>
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Add SDR specific notes to G_MODULATOR / S_MODULATOR documentation.
Signed-off-by: NAntti Palosaari <crope@iki.fi>
[hans.verkuil@cisco.com: add quotes in "The term 'modulator'"]
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Add SDR specific notes to G_TUNER / S_TUNER documentation.
Add V4L2_TUNER_SDR and V4L2_TUNER_RF to supported tuner types to
table.
Signed-off-by: NAntti Palosaari <crope@iki.fi>
[hans.verkuil@cisco.com: add quotes in "The term 'tuner'"]
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Add new modulator type field to documentation.
Signed-off-by: NAntti Palosaari <crope@iki.fi>
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Add documentation for V4L SDR transmitter (output) devices.
Signed-off-by: NAntti Palosaari <crope@iki.fi>
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Add brief description for tuner RF gain control.
Signed-off-by: NAntti Palosaari <crope@iki.fi>
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

SDR receiver has ADC (Analog-to-Digital Converter) and SDR transmitter
has DAC (Digital-to-Analog Converter). Originally I though it could
be good idea to have own type for receiver and transmitter, but now I
feel one common type for SDR is enough. So lets rename it.
Signed-off-by: NAntti Palosaari <crope@iki.fi>
Acked-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
[hans.verkuil@cisco.com: this was added in 4.4, so update 4.2 to 4.4]
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Requires Markdown support.
Signed-off-by: NLukas Wunner <lukas@wunner.de>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

Following Daniel's renaming of the document.
Signed-off-by: NLukas Wunner <lukas@wunner.de>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

DRM is a lot more than a direct rendering manager nowadays, and there's
also a bunch of things worth documenting for gpu driver developers
outside of drivers/gpu/drm, like vgaarb, vga_switcheroo or the various
hardware buses like host1x and ipu-v3.

To avoid further confusion let's rename the top-level to reflect
reality.

And yes I'm already looking forward to when we need to replace the G
in GPU with a * ;-)

Inspired by a thread with Lukas since he refused to include the
vga_switcheroo docs into the drm docs because it's not drm.

Cc: Lukas Wunner <lukas@wunner.de>
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
[Lukas: Drop BUG() easter egg in i915_gem_execbuffer.c spotted by Jani
and fix typos in commit message.]
Signed-off-by: NLukas Wunner <lukas@wunner.de>
Acked-by: NDave Airlie <airlied@gmail.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

With the prep patches for i915 all kms drivers either have
DRM_UNLOCKED on all their ioctls. Or the ioctl always directly returns
with an invariant return value when in modeset mode. But that's only
the case for i915 and radeon. The drm core ioctls are unfortunately
too much a mess still to dare this.

Follow-up patches will remove DRM_UNLOCKED from all kms drivers to
prove that this is indeed the case.

Also update the documentation.

v2: Really only do this for driver ioctls, spotted by David Herrmann.
And drop spurious whitespace change.

Cc: David Herrmann <dh.herrmann@gmail.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@intel.com>
Reviewed-by: NDavid Herrmann <dh.herrmann@gmail.com>
Reviewed-by: NChristian König <christian.koenig@amd.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

For location and connectivity services, userspace would often like
to know the time when the BSS was last seen. The current "last seen"
value is calculated in a way that makes it less useful, especially
if the system suspended in the meantime.

Add the ability for the driver to report a real CLOCK_BOOTTIME stamp
that can then be reported to userspace (if present).

Drivers wishing to use this must be converted to the new API to call
cfg80211_inform_bss_data() or cfg80211_inform_bss_frame_data(). They
need to ensure the reported value is accurate enough even when the
frame might have been buffered in the device (e.g. firmware.)
Signed-off-by: NDmitry Shmidt <dimitrysh@google.com>
[modified to use struct, inlines]
Signed-off-by: NJohannes Berg <johannes.berg@intel.com>

Now that the Demux kABI is documented at device-drivers.xml,
remove it from the API docbook.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

There are several stuff at media's kdapi.xml that don't
belong there, as it documents the Kernel internal ABI, and
not the userspace API.

Add the documentation here. The hole kdapi.xml will be
removed on a latter patch, after we finish documenting
what's there at the proper places.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

The DVB core has a provision for other frontend sources, but no
drivers use it. The kdapi.xml contains provision for some other
frontend source types, but it is not in sync with the code.

So, remove the unused types and sync both files.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Add the item of i915_component.h in DocBook and add the DOC for
i915_component.h. Explain the struct i915_audio_component_ops and
struct i915_audio_component_audio_ops usage.
Signed-off-by: NLibin Yang <libin.yang@intel.com>
Signed-off-by: NDaniel Vetter <daniel.vetter@ffwll.ch>

This enum is not actually used anymore. The only value used from
the enum is DMX_OK, passed as a parameter on two callbacks.

Yet, this value is not used anywhere. So, just remove it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

The DocBook/media/dvb/kdapi.xml contains the description of
the kABI for DVB. The problem is that, by being maintained
on a separate file and not being updated for years, it got
outdated. So, for example, some callback parameters were
changed, but the DocBook were still using the old stuff.

As a first step to fix it, let's move the documentation of
struct dmx_demux into demux.h and fix the parameters used
there.

For now, don't document any other field nor touch the
descriptions that got moved, letting this job to other
patches. That makes easier to review the patch.

PS.: Please notice that an additional patch will be needed
in order to fix the return values (some uses non-existent
return codes) and to the functions and callbacks mentioned at
the descriptions.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

The struct lirc_driver is already documented, but on some
internal format. Convert it to Kernel doc-nano format and
add documentation for some additional parameters that are
also present at the structure.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

This header declares the code and structures used to parse
Hauppauge eeproms. As this is part of the V4L2 common, and
used by several drivers, let's properly document it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

The tuner-types.h is part of the V4L2 core and should be
touched for every new tuner added. So, it deserves to be
documented at the device-drivers DocBook.

Add it to device-drivers.tmpl and add descriptions for
enum param_type and struct tuner_range.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

This is part of the V4L2 core, so its kABI should be
documented at device-drivers DocBook.

Add the meta-tags for that.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

This header should also be used to generate documentation. So,
add it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>