It is possible to use:
	make DOCBOOKS=device-drivers.xml htmldocs

To produce just a few docbooks. In such case, the media docs
won't be built, causing the makefile target to return an error.

While this is ok for human eyes, if the above is used on an script,
it would cause troubles.

Fix it by only creating/filling the media_api directory if the
media_api.xml is found at DOCBOOKS.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Commit 5240f4e6 ("[media] DocBook/media/Makefile: Avoid make htmldocs
to fail") introduced a mkdir which is always called through
install_media_images from the Documentation/DocBook/Makefile htmldocs rule.
If you run 'make htmldocs' more than once you get:

 mkdir: cannot create directory ‘./Documentation/DocBook//media_api’:
  File exists

Add -p to the mkdir to continue no matter if the dir already exists.
Signed-off-by: NGraham Whaley <graham.whaley@linux.intel.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

If make is called twice like that:
	make V=1 DOCBOOKS=device-drivers.xml htmldocs

Make will fail with:

	make -f ./scripts/Makefile.build obj=scripts/basic
	rm -f .tmp_quiet_recordmcount
	make -f ./scripts/Makefile.build obj=scripts build_docproc
	make -f ./scripts/Makefile.build obj=Documentation/DocBook htmldocs
	rm -rf Documentation/DocBook/index.html; echo '<h1>Linux Kernel HTML Documentation</h1>' >> Documentation/DocBook/index.html && echo '<h2>Kernel Version: 4.2.0-rc2</h2>' >> Documentation/DocBook/index.html && cat Documentation/DocBook/device-drivers.html >> Documentation/DocBook/index.html
	cp ./Documentation/DocBook//bayer.png ./Documentation/DocBook//constraints.png ./Documentation/DocBook//crop.gif ./Documentation/DocBook//dvbstb.png ./Documentation/DocBook//fieldseq_bt.gif ./Documentation/DocBook//fieldseq_tb.gif ./Documentation/DocBook//nv12mt.gif ./Documentation/DocBook//nv12mt_example.gif ./Documentation/DocBook//pipeline.png ./Documentation/DocBook//selection.png ./Documentation/DocBook//vbi_525.gif ./Documentation/DocBook//vbi_625.gif ./Documentation/DocBook//vbi_hsync.gif ./Documentation/DocBook/media/*.svg ./Documentation/DocBook/media/v4l/*.svg ./Documentation/DocBook//media_api
	cp: target './Documentation/DocBook//media_api' is not a directory
	Documentation/DocBook/Makefile:53: recipe for target 'htmldocs' failed
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

Use a table for the Demux output. No new information added
here. They were all merged inside the table.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

The comments may affect enum value parsing. Use cpp to remove
them.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

In order to be sure that all enum definitions will be documented,
let's parse the enum values and add xref links to them.

Lots of missing references will be risen as we miss adding
id's to those symbols at the documentation. Next patches will
fix this.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

The DVB network API was not documented. There are just some
placeholders there.

Replace it by a proper documentation.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

The typedef parser is wrong and doesn't get some of the
types defined at the DVB API. Improve it, as we want to add
cross-references to those types.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

The new code that detects undocumented ioctls hits some false
positives:

This one is not documented, nor it should, as this is
there just to reserve namespace:

	Warning: can't find reference for VIDIOC_RESERVED ioctl

But those are already documented together with other ioctls:

	Warning: can't find reference for VIDIOC_UNSUBSCRIBE_EVENT ioctl
	Warning: can't find reference for FE_GET_PROPERTY ioctl
	Warning: can't find reference for VIDIOC_SUBDEV_G_EDID ioctl
	Warning: can't find reference for VIDIOC_SUBDEV_S_EDID ioctl
	Warning: can't find reference for VIDIOC_SUBDEV_S_DV_TIMINGS ioctl
	Warning: can't find reference for VIDIOC_SUBDEV_G_DV_TIMINGS ioctl
	Warning: can't find reference for VIDIOC_SUBDEV_QUERY_DV_TIMINGS ioctl

So, we need to just be sure to point to the right documentation.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Those ioctls are already parsed. No need to explicitly add
them.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

There are several badly documented undocumented ioctls.
Currently, it just generates an empty link. Instead of doing that,
only add references to the ones that exists, and add a warning
for all references that weren't found.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Create xref links for all DTV properties and link the frontend.h
to each. Also use them at the DVB frontent API example.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Instead of having two refentries, merge them into just one,
like what's done with other similar ioctls at V4L2 side.

That makes the entry cleaner and will allow to add the associated
structures together with the refentry.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

An illustration of what's considered a typical media device
may help people to better understand the contents of the media
infrastructure API docbook. So, add it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

I've got a harmless warning when running make cleandocs on an already
cleaned tree:
  Documentation/DocBook/media/Makefile:28: recipe for target 'cleanmediadocs' failed
  make[1]: [cleanmediadocs] Error 1 (ignored)

Suppress this by passing -f to rm.
Acked-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Signed-off-by: NTakashi Iwai <tiwai@suse.de>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The v4l2_pix_format structure has no reserved field. It is embedded in
the v4l2_framebuffer structure which has no reserved fields either, and
in the v4l2_format structure which has reserved fields that were not
previously required to be zeroed out by applications.

To allow extending v4l2_pix_format, inline it in the v4l2_framebuffer
structure, and use the priv field as a magic value to indicate that the
application has set all v4l2_pix_format extended fields and zeroed all
reserved fields following the v4l2_pix_format field in the v4l2_format
structure.

The availability of this API extension is reported to userspace through
the new V4L2_CAP_EXT_PIX_FORMAT capability flag. Just checking that the
priv field is still set to the magic value at [GS]_FMT return wouldn't
be enough, as older kernels don't zero the priv field on return.

To simplify the internal API towards drivers zero the extended fields
and set the priv field to the magic value for applications not aware of
the extensions.
Signed-off-by: NLaurent Pinchart <laurent.pinchart+renesas@ideasonboard.com>
Signed-off-by: NMauro Carvalho Chehab <m.chehab@samsung.com>

After commits 890676c6 (kbuild: Use relative path when building in the source
tree) and 9da0763b (kbuild: Use relative path when building in a subdir
of the source tree), the $(srctree) variable can be a relative path.
This breaks Documentation/DocBook/media/Makefile, because it tries to
create symlinks from a subdirectory of the object tree to the source
tree. Fix this by using a full path in this case.
Reported-by: NRandy Dunlap <rdunlap@infradead.org>
Acked-by: NRandy Dunlap <rdunlap@infradead.org>
Tested-by: NRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: NMichal Marek <mmarek@suse.cz>

Prior to commit 42661299 ("[media] DocBook: Move all media docbook
stuff into its own directory") it was possible to build only a single
(or more) book(s) by calling, for example

    make htmldocs DOCBOOKS=80211.xml

This now fails:

    cp: target `.../Documentation/DocBook//media_api' is not a directory

Ignore errors from that copy to make this possible again.

Fixes: 42661299 ("[media] DocBook: Move all media docbook stuff into its own directory")
Signed-off-by: NJohannes Berg <johannes.berg@intel.com>
Acked-by: NRandy Dunlap <rdunlap@xenotime.net>
Cc: Mauro Carvalho Chehab <mchehab@redhat.com>
Signed-off-by: NAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: NLinus Torvalds <torvalds@linux-foundation.org>

The uapi changeset forgot to fix the header locations, needed
for the DocBook specs. Fix it.

Cc: David Howells <dhowells@redhat.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

More validation fixes as reported by xmllint.

There are still three xmllint errors after this remaining regarding SVG file support.
Signed-off-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

Add documentation for V4L2 subdev selection API. This changes also
experimental V4L2 subdev API so that scaling now works through selection API
only.
Signed-off-by: NSakari Ailus <sakari.ailus@iki.fi>
Acked-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

There are several errors reported by V4L that aren't described.
They can occur on almost all ioctl's. Instead of adding them
into each ioctl, create a new chapter.

For V4L, the new chapter will automatically be listed on all
places, as there's a macro used everywhere there.
Acked-by: NHans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

The patch utility doesn't work with non-binary files. This causes some
tools to break, like generating tarball targets and the scripts that
generate diff patches at http://www.kernel.org/pub/linux/kernel/v2.6/.

So, let's convert all binaries to ascii using base64, and add a
logic at Makefile to convert them back into binaries at runtime.
Reported-by: NRandy Dunlap <randy.dunlap@oracle.com>
Reported-by: NAndrew Morton <akpm@linux-foundation.org>
Reviewed-by: NMichal Marek <mmarek@suse.cz>
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

While here, remove the mediaindexdocs from PHONY.
Reported-by: NRandy Dunlap <randy.dunlap@oracle.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

Make the reference links at video.h.xml to match the ones at video.xml.
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

The av7110 uses an OSD API. Such API is not documented at all. Also,
the osd.h API uses camelCase and some other weird stuff. Also, dvb-core
doesn't recognize it.

I don't see any good reason why we should document it. It seems better
to just let it as-is. If ever needed, it is probably better to write
a different API for dvb-core.
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

There's no documentation at all for the DVB net API. Still, better to
remove a few warnings about the missing symbols. So, add the net data
structure inside the net.xml. Now, only the ioctl documentation is missed.
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

Make the reference links at dmx.h.xml to match the ones at demux.xml.

While here, also syncronizes the structures defined inside the API,
in order to match the current API.
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

Make sure that both ca.h.xml and ca.xml will match the same names for
the sections/links.

This way, it is now possible to identify API spec gaps:

Error: no ID for constraint linkend: ca-pid.
Error: no ID for constraint linkend: ca-pid.
Error: no ID for constraint linkend: CA_RESET.
Error: no ID for constraint linkend: CA_GET_CAP.
Error: no ID for constraint linkend: CA_GET_SLOT_INFO.
Error: no ID for constraint linkend: CA_GET_DESCR_INFO.
Error: no ID for constraint linkend: CA_GET_MSG.
Error: no ID for constraint linkend: CA_SEND_MSG.
Error: no ID for constraint linkend: CA_SET_DESCR.
Error: no ID for constraint linkend: CA_SET_PID.

Basically, in this case, no CA ioctl is described at the specs, and one
file structure (ca-pid) is missing.
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

Make sure that both audio.h.xml and audio.xml will match the same names.
This way, it is now possible to identify API spec gaps:

Error: no ID for constraint linkend: AUDIO_CONTINUE.
Error: no ID for constraint linkend: AUDIO_GET_PTS.
Error: no ID for constraint linkend: AUDIO_BILINGUAL_CHANNEL_SELECT.

While here, fix the cut-and-paste description error on AUDIO_SET_KARAOKE.
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

Remove the remaining:
	Error: no ID for constraint linkend:

With this patch, the dvb frontend API matches the current
dvb core implementation.
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

The frontend.h.xml now references to the main document. However,
several references are missed.

Links the trivial ones with the corresponding API descriptions.

While here, updates the main API to reflect the API improvements.
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

Associate the frontend.h DVB S2API parmeters to the corresponding
documentation at the spec.
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

The fe_type_t documentation was incomplete and not linked to the
dvb/frontend.h.xml. Properly document it.

Also, drop a note that newer formats are only supported via
FE_GET_PROPERTY/FE_GET_SET_PROPERTY ioctls.
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

With this change, it is now possible to discover the gap between
the API defined inside include/dvb/frontend.h and the one documented
into the specs.
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>

This patch addresses several issues pointed by Randy Dunlap
<rdunlap@xenotime.net> at changeset ece722c:

- In the generated index.html file, "media" is listed first, but it
  should be listed in alphabetical order, not first.

- The generated files are (hidden) in .tmpmedia/

- The link from the top-level index.html file to "media" is to
  media/index.html, but the file is actually in .tmpmedia/media/index.html

- Please build docs with and without using "O=builddir" and test that.

- Would it be possible for media to have its own Makefile instead of
  merging into this one?

Due to the way cleandocs target works, I had to rename the media DocBook
to media_api, otherwise cleandocs would remove the /media directory.

Thanks-to: Randy Dunlap <rdunlap@xenotime.net>
Signed-off-by: NMauro Carvalho Chehab <mchehab@redhat.com>