mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
synced 2025-01-14 17:14:09 +00:00
[media] tuner-core: Improve function documentation
This driver is complex, and used by everyone. Better to have it properly documented. No functional changes are done in this patch. Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>
This commit is contained in:
Mauro Carvalho Chehab
parent
ad020dc2fe
commit
a2894e3f8e
@ -1,7 +1,17 @@
|
||||
/*
|
||||
*
|
||||
* i2c tv tuner chip device driver
|
||||
* core core, i.e. kernel interfaces, registering and so on
|
||||
*
|
||||
* Copyright(c) by Ralph Metzler, Gerd Knorr, Gunther Mayer
|
||||
*
|
||||
* Copyright(c) 2005-2011 by Mauro Carvalho Chehab
|
||||
* - Added support for a separate Radio tuner
|
||||
* - Major rework and cleanups at the code
|
||||
*
|
||||
* This driver supports many devices and the idea is to let the driver
|
||||
* detect which device is present. So rather than listing all supported
|
||||
* devices here, we pretend to support a single, fake device type that will
|
||||
* handle both radio and analog TV tuning.
|
||||
*/
|
||||
|
||||
#include <linux/module.h>
|
||||
@ -67,6 +77,7 @@ module_param_string(ntsc, ntsc, sizeof(ntsc), 0644);
|
||||
*/
|
||||
|
||||
static LIST_HEAD(tuner_list);
|
||||
static const struct v4l2_subdev_ops tuner_ops;
|
||||
|
||||
/*
|
||||
* Debug macros
|
||||
@ -124,6 +135,13 @@ struct tuner {
|
||||
const char *name;
|
||||
};
|
||||
|
||||
/*
|
||||
* Function prototypes
|
||||
*/
|
||||
|
||||
static void set_tv_freq(struct i2c_client *c, unsigned int freq);
|
||||
static void set_radio_freq(struct i2c_client *c, unsigned int freq);
|
||||
|
||||
/*
|
||||
* tuner attach/detach logic
|
||||
*/
|
||||
@ -233,13 +251,24 @@ static struct analog_demod_ops tuner_analog_ops = {
|
||||
};
|
||||
|
||||
/*
|
||||
* Functions that are common to both TV and radio
|
||||
* Functions to select between radio and TV and tuner probe functions
|
||||
*/
|
||||
|
||||
static void set_tv_freq(struct i2c_client *c, unsigned int freq);
|
||||
static void set_radio_freq(struct i2c_client *c, unsigned int freq);
|
||||
static const struct v4l2_subdev_ops tuner_ops;
|
||||
|
||||
/**
|
||||
* set_type - Sets the tuner type for a given device
|
||||
*
|
||||
* @c: i2c_client descriptoy
|
||||
* @type: type of the tuner (e. g. tuner number)
|
||||
* @new_mode_mask: Indicates if tuner supports TV and/or Radio
|
||||
* @new_config: an optional parameter ranging from 0-255 used by
|
||||
a few tuners to adjust an internal parameter,
|
||||
like LNA mode
|
||||
* @tuner_callback: an optional function to be called when switching
|
||||
* to analog mode
|
||||
*
|
||||
* This function applys the tuner config to tuner specified
|
||||
* by tun_setup structure. It contains several per-tuner initialization "magic"
|
||||
*/
|
||||
static void set_type(struct i2c_client *c, unsigned int type,
|
||||
unsigned int new_mode_mask, unsigned int new_config,
|
||||
int (*tuner_callback) (void *dev, int component, int cmd, int arg))
|
||||
@ -452,6 +481,15 @@ static int tuner_s_type_addr(struct v4l2_subdev *sd,
|
||||
return 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* tuner_s_config - Sets tuner configuration
|
||||
*
|
||||
* @sd: subdev descriptor
|
||||
* @cfg: tuner configuration
|
||||
*
|
||||
* Calls tuner set_config() private function to set some tuner-internal
|
||||
* parameters
|
||||
*/
|
||||
static int tuner_s_config(struct v4l2_subdev *sd,
|
||||
const struct v4l2_priv_tun_config *cfg)
|
||||
{
|
||||
@ -470,10 +508,20 @@ static int tuner_s_config(struct v4l2_subdev *sd,
|
||||
return 0;
|
||||
}
|
||||
|
||||
/* Search for existing radio and/or TV tuners on the given I2C adapter.
|
||||
Note that when this function is called from tuner_probe you can be
|
||||
certain no other devices will be added/deleted at the same time, I2C
|
||||
core protects against that. */
|
||||
/**
|
||||
* tuner_lookup - Seek for tuner adapters
|
||||
*
|
||||
* @adap: i2c_adapter struct
|
||||
* @radio: pointer to be filled if the adapter is radio
|
||||
* @tv: pointer to be filled if the adapter is TV
|
||||
*
|
||||
* Search for existing radio and/or TV tuners on the given I2C adapter,
|
||||
* discarding demod-only adapters (tda9887).
|
||||
*
|
||||
* Note that when this function is called from tuner_probe you can be
|
||||
* certain no other devices will be added/deleted at the same time, I2C
|
||||
* core protects against that.
|
||||
*/
|
||||
static void tuner_lookup(struct i2c_adapter *adap,
|
||||
struct tuner **radio, struct tuner **tv)
|
||||
{
|
||||
@ -502,8 +550,20 @@ static void tuner_lookup(struct i2c_adapter *adap,
|
||||
}
|
||||
}
|
||||
|
||||
/* During client attach, set_type is called by adapter's attach_inform callback.
|
||||
set_type must then be completed by tuner_probe.
|
||||
/**
|
||||
*tuner_probe - Probes the existing tuners on an I2C bus
|
||||
*
|
||||
* @client: i2c_client descriptor
|
||||
* @id: not used
|
||||
*
|
||||
* This routine probes for tuners at the expected I2C addresses. On most
|
||||
* cases, if a device answers to a given I2C address, it assumes that the
|
||||
* device is a tuner. On a few cases, however, an additional logic is needed
|
||||
* to double check if the device is really a tuner, or to identify the tuner
|
||||
* type, like on tea5767/5761 devices.
|
||||
*
|
||||
* During client attach, set_type is called by adapter's attach_inform callback.
|
||||
* set_type must then be completed by tuner_probe.
|
||||
*/
|
||||
static int tuner_probe(struct i2c_client *client,
|
||||
const struct i2c_device_id *id)
|
||||
@ -618,6 +678,12 @@ register_client:
|
||||
return 0;
|
||||
}
|
||||
|
||||
/**
|
||||
* tuner_remove - detaches a tuner
|
||||
*
|
||||
* @client: i2c_client descriptor
|
||||
*/
|
||||
|
||||
static int tuner_remove(struct i2c_client *client)
|
||||
{
|
||||
struct tuner *t = to_tuner(i2c_get_clientdata(client));
|
||||
@ -635,7 +701,12 @@ static int tuner_remove(struct i2c_client *client)
|
||||
* Functions that are specific for TV mode
|
||||
*/
|
||||
|
||||
/* Set tuner frequency, freq in Units of 62.5kHz = 1/16MHz */
|
||||
/**
|
||||
* set_tv_freq - Set tuner frequency, freq in Units of 62.5 kHz = 1/16MHz
|
||||
*
|
||||
* @c: i2c_client descriptor
|
||||
* @freq: frequency
|
||||
*/
|
||||
static void set_tv_freq(struct i2c_client *c, unsigned int freq)
|
||||
{
|
||||
struct tuner *t = to_tuner(i2c_get_clientdata(c));
|
||||
@ -675,7 +746,19 @@ static void set_tv_freq(struct i2c_client *c, unsigned int freq)
|
||||
analog_ops->set_params(&t->fe, ¶ms);
|
||||
}
|
||||
|
||||
/* get more precise norm info from insmod option */
|
||||
/**
|
||||
* tuner_fixup_std - force a given video standard variant
|
||||
*
|
||||
* @t: tuner internal struct
|
||||
*
|
||||
* A few devices or drivers have problem to detect some standard variations.
|
||||
* On other operational systems, the drivers generally have a per-country
|
||||
* code, and some logic to apply per-country hacks. V4L2 API doesn't provide
|
||||
* such hacks. Instead, it relies on a proper video standard selection from
|
||||
* the userspace application. However, as some apps are buggy, not allowing
|
||||
* to distinguish all video standard variations, a modprobe parameter can
|
||||
* be used to force a video standard match.
|
||||
*/
|
||||
static int tuner_fixup_std(struct tuner *t)
|
||||
{
|
||||
if ((t->std & V4L2_STD_PAL) == V4L2_STD_PAL) {
|
||||
@ -797,6 +880,12 @@ static int tuner_fixup_std(struct tuner *t)
|
||||
* Functions that are specific for Radio mode
|
||||
*/
|
||||
|
||||
/**
|
||||
* set_radio_freq - Set tuner frequency, freq in Units of 62.5 Hz = 1/16kHz
|
||||
*
|
||||
* @c: i2c_client descriptor
|
||||
* @freq: frequency
|
||||
*/
|
||||
static void set_radio_freq(struct i2c_client *c, unsigned int freq)
|
||||
{
|
||||
struct tuner *t = to_tuner(i2c_get_clientdata(c));
|
||||
@ -972,7 +1061,9 @@ static int tuner_s_power(struct v4l2_subdev *sd, int on)
|
||||
return 0;
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------------- */
|
||||
/*
|
||||
* Function to splicitly change mode to radio. Probably not needed anymore
|
||||
*/
|
||||
|
||||
static int tuner_s_radio(struct v4l2_subdev *sd)
|
||||
{
|
||||
@ -984,9 +1075,10 @@ static int tuner_s_radio(struct v4l2_subdev *sd)
|
||||
return 0;
|
||||
}
|
||||
|
||||
/* --- v4l ioctls --- */
|
||||
/* take care: bttv does userspace copying, we'll get a
|
||||
kernel pointer here... */
|
||||
/*
|
||||
* Tuner callbacks to handle userspace ioctl's
|
||||
*/
|
||||
|
||||
static int tuner_s_std(struct v4l2_subdev *sd, v4l2_std_id std)
|
||||
{
|
||||
struct tuner *t = to_tuner(sd);
|
||||
@ -1137,7 +1229,9 @@ static int tuner_command(struct i2c_client *client, unsigned cmd, void *arg)
|
||||
return -ENOIOCTLCMD;
|
||||
}
|
||||
|
||||
/* ----------------------------------------------------------------------- */
|
||||
/*
|
||||
* Callback structs
|
||||
*/
|
||||
|
||||
static const struct v4l2_subdev_core_ops tuner_core_ops = {
|
||||
.log_status = tuner_log_status,
|
||||
@ -1160,11 +1254,10 @@ static const struct v4l2_subdev_ops tuner_ops = {
|
||||
.tuner = &tuner_tuner_ops,
|
||||
};
|
||||
|
||||
/* ----------------------------------------------------------------------- */
|
||||
/*
|
||||
* I2C structs and module init functions
|
||||
*/
|
||||
|
||||
/* This driver supports many devices and the idea is to let the driver
|
||||
detect which device is present. So rather than listing all supported
|
||||
devices here, we pretend to support a single, fake device type. */
|
||||
static const struct i2c_device_id tuner_id[] = {
|
||||
{ "tuner", }, /* autodetect */
|
||||
{ }
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user