The get_state()/set_state and the corresponding data types
(struct tuner_state and enum tuner_param) are old DVB interfaces
that came from the DVBv3 time.

Nowadays, set_params() provide a better way to set the tuner
and demod parameters. So, no need to keep those legacy stuff,
as all drivers that were using it got converted.

With this patch, all kABI elements at dvb_frontend.h are now
documented.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

There are several tuner_param values that aren't by any driver or core:
	DVBFE_TUNER_TUNERSTEP
	DVBFE_TUNER_IFFREQ
	DVBFE_TUNER_REFCLOCK
	DVBFE_TUNER_IQSENSE
	DVBFE_TUNER_DUMMY

Several of those correspond to the values at the tuner_state
struct with is also only initialized by not used anyware:
	u32 tunerstep;
	u32 ifreq;
	u32 refclock;

It doesn't make sense to keep anything at the kABI that it is
not used. So, get rid of them.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Those functions should be implemented on all drivers. So, document
them.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

As SEC tone and voltage could have changed during
suspend(), restore them to their previous values at
resume().
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

The DocBook description of this header has two issues:
- It calls the Kernel ABI as API, instead of kABI;
- It mentions that the DVB frontend kABI is not described
  within the document. As this will actually generate a
  single DocBook, this is actually not true, now that
  the documentation for the frontend was added.

So, fix both issues.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

This header file provides the kABI functions used by the
Digital TV Frontend core support. Add a description for
this kABI, to add at the device_drivers Kernel DocBook.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Documents the most used functions at the Digital TV
kABI: dvb_frontend_register(), dvb_frontend_unregister()
and dvb_frontend_detach().
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

The dvb_frontend_reinitialise() function is a special case
used by just one frontend. Document it, for completeness.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

This function is used mainly at the DVB core, in order to provide
emulation for a legacy ioctl. The only current exception is
the stv0299 driver, with takes more than 8ms to switch voltage,
breaking the emulation for FE_DISHNETWORK_SEND_LEGACY_CMD.

Document that.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Classify the functions at the DVB core per API. That makes easier
to understand how they're related to the userspace API.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

It is better to keep the documentation overview at the header file,
as this makes easier for developers to remember to fix when needed.
Suggested-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

While we can't document #defines, documenting enums are
well supported by kernel-doc. So, convert the bitmap defines
into an enum.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

The usage of #define at the kABI is fine, but it doesn't
allow adding a proper description. As those defines deserve
a proper documentation, let's convert them into an enum and
document them at device-drivers DocBook.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

The dvb/kdapi.tmpl has already an extensive documentation about
this callback. Now that we've added function typedefs at kernel-doc,
add such documentation at demux.h, for it to appear at device-drivers
DocBook.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

The dvb/kdapi.tmpl has already an extensive documentation about
this callback. Now that we've added function typedefs at kernel-doc,
add such documentation at demux.h, for it to appear at device-drivers
DocBook.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

There are lots of CodingStyle violations here. Now that we're
touching a log on this header files, adding the documentation
here, make sure that this will follow the Kernel CodingStyle.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Document the following data types:
	struct dmx_ts_feed
	struct dmx_section_filter
	struct dmx_section_feed
	enum dmx_frontend_source
	struct dmx_frontend
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>

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>

There are two callbacks still not documented:
	.//drivers/media/dvb-core/demux.h:422: warning: No description found for parameter 'get_pes_pids'
	.//drivers/media/dvb-core/demux.h:422: warning: No description found for parameter 'get_stc'

The purpose of first one is clear. The second one is used only
on the obsolete av7110 driver, and its purpose is not clear,
as it just returns a 64-bit word from the firmware to userspace.

Let's document get_pes_pids and mark get_stc as private, adding
a comment to not use it, while this is not documented.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

There are two DVB demux callbacks and ioctls that aren't documented
and aren't used at all by the DVB core or by any DVB driver upstream.

Let's comment out the code for those two ioctls and remove on some
future version.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

There are a few inconsistencies between the old documentation
that got imported into the header and the current status.

Update them, and use the proper doc-nano nomenclature for
struct artuments "@", instead of foo().
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>

There are several CodingStyle violations at the DVB code. While
we won't be fixing them as a hole, let's fix at least the
headers, as we're touching on them already in order to properly
document them.

No functional changes.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

This struct is already documented at the header file, but it is
not using Kernel doc-nano format. Convert to it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Adds Terratec H7 Rev. 4 with USB id 0ccd:10a5 to DVBSky driver.
Signed-off-by: NErik Andresen <erik@vontaene.de>
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Those two came from dvb_register_adapter cut-and-paste:

	.//drivers/media/dvb-core/dvbdev.h:199: warning: Excess function parameter 'device' description in 'dvb_register_device'
	.//drivers/media/dvb-core/dvbdev.h:199: warning: Excess function parameter 'adapter_nums' description in 'dvb_register_device'

Remove them.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>

Document the most relevant functions and data structs for
developers that are working with the DVB subsystem.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

That struct is used on every DVB Front End driver, as it
contains what's needed to register/use a frontend at the
Kernel.

Document it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

Most of the parameters here are already well defined at
the userspace documentation. Yet, it is good to add some
documentation, for the developers to be sure that they
are the same as the ones at userspace API.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

This is one of the most important functions of the DVB
frontend, containing the logic needed to set the parameters
at the demux and to send commands via SEC.

Document it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

The dvb_frontend.c core defines a FE_ALGO_HW symbol that it is
never used. Also, both cx24123 returns 1 to get_algo() callback
instead of using DVBFE_ALGO_HW.

Probably, those are some left overs from some code cleanup.

Let's stop returning magic numbers and use the proper macro
value.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

Add documentation for struct analog_demod_info and
struct analog_demod_ops.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

The struct dvb_tuner_ops contains lots of callbacks used
by tuners. Document them.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

That struct inside dvb-frontend.h stores some parameters
from V4L2 API (videodev2.h), in order to be used by the
hybrid analog/digital TV tuners.

Document it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

This enum is not used anymore, as drivers use the
modulation definitions from the public API. It is probably
a left over from some DVB core cleanup.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

Despite being used everywhere at DVB frontends, the
struct dvb_tuner_info were never documented.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

Add Documentation for dvb_frontend_tune_settings struct.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

There are already some comments at dvb_ringbuffer.h that are ready
for DocBook, although not properly formatted.

Convert them, fix some issues and add this file to
the device-drivers DocBook.

While here, put multi-line comments on the right format.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>

There are already some comments at dvb_math.h that are ready
for DocBook, although not properly formatted.

Convert them, fix some issues and add this file to
the device-drivers DocBook.
Signed-off-by: NMauro Carvalho Chehab <mchehab@osg.samsung.com>
Acked-by: NJonathan Corbet <corbet@lwn.net>