diff options
author | Mauro Carvalho Chehab <mchehab@redhat.com> | 2011-02-15 07:15:19 -0500 |
---|---|---|
committer | Mauro Carvalho Chehab <mchehab@redhat.com> | 2011-03-21 19:32:03 -0400 |
commit | a2894e3f8ed691b4873c8122e66902fbf0e78e0b (patch) | |
tree | 3b0705a7abf7206260a6c546d4c8b088d21ff42d /drivers/media/video/tuner-core.c | |
parent | ad020dc2fe9039628cf6cef42cd1b76531ee8411 (diff) |
[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>
Diffstat (limited to 'drivers/media/video/tuner-core.c')
-rw-r--r-- | drivers/media/video/tuner-core.c | 139 |
1 files changed, 116 insertions, 23 deletions
diff --git a/drivers/media/video/tuner-core.c b/drivers/media/video/tuner-core.c index 5e1437c358f8..2c7fe18cedeb 100644 --- a/drivers/media/video/tuner-core.c +++ b/drivers/media/video/tuner-core.c | |||
@@ -1,7 +1,17 @@ | |||
1 | /* | 1 | /* |
2 | * | ||
3 | * i2c tv tuner chip device driver | 2 | * i2c tv tuner chip device driver |
4 | * core core, i.e. kernel interfaces, registering and so on | 3 | * core core, i.e. kernel interfaces, registering and so on |
4 | * | ||
5 | * Copyright(c) by Ralph Metzler, Gerd Knorr, Gunther Mayer | ||
6 | * | ||
7 | * Copyright(c) 2005-2011 by Mauro Carvalho Chehab | ||
8 | * - Added support for a separate Radio tuner | ||
9 | * - Major rework and cleanups at the code | ||
10 | * | ||
11 | * This driver supports many devices and the idea is to let the driver | ||
12 | * detect which device is present. So rather than listing all supported | ||
13 | * devices here, we pretend to support a single, fake device type that will | ||
14 | * handle both radio and analog TV tuning. | ||
5 | */ | 15 | */ |
6 | 16 | ||
7 | #include <linux/module.h> | 17 | #include <linux/module.h> |
@@ -67,6 +77,7 @@ module_param_string(ntsc, ntsc, sizeof(ntsc), 0644); | |||
67 | */ | 77 | */ |
68 | 78 | ||
69 | static LIST_HEAD(tuner_list); | 79 | static LIST_HEAD(tuner_list); |
80 | static const struct v4l2_subdev_ops tuner_ops; | ||
70 | 81 | ||
71 | /* | 82 | /* |
72 | * Debug macros | 83 | * Debug macros |
@@ -125,6 +136,13 @@ struct tuner { | |||
125 | }; | 136 | }; |
126 | 137 | ||
127 | /* | 138 | /* |
139 | * Function prototypes | ||
140 | */ | ||
141 | |||
142 | static void set_tv_freq(struct i2c_client *c, unsigned int freq); | ||
143 | static void set_radio_freq(struct i2c_client *c, unsigned int freq); | ||
144 | |||
145 | /* | ||
128 | * tuner attach/detach logic | 146 | * tuner attach/detach logic |
129 | */ | 147 | */ |
130 | 148 | ||
@@ -233,13 +251,24 @@ static struct analog_demod_ops tuner_analog_ops = { | |||
233 | }; | 251 | }; |
234 | 252 | ||
235 | /* | 253 | /* |
236 | * Functions that are common to both TV and radio | 254 | * Functions to select between radio and TV and tuner probe functions |
237 | */ | 255 | */ |
238 | 256 | ||
239 | static void set_tv_freq(struct i2c_client *c, unsigned int freq); | 257 | /** |
240 | static void set_radio_freq(struct i2c_client *c, unsigned int freq); | 258 | * set_type - Sets the tuner type for a given device |
241 | static const struct v4l2_subdev_ops tuner_ops; | 259 | * |
242 | 260 | * @c: i2c_client descriptoy | |
261 | * @type: type of the tuner (e. g. tuner number) | ||
262 | * @new_mode_mask: Indicates if tuner supports TV and/or Radio | ||
263 | * @new_config: an optional parameter ranging from 0-255 used by | ||
264 | a few tuners to adjust an internal parameter, | ||
265 | like LNA mode | ||
266 | * @tuner_callback: an optional function to be called when switching | ||
267 | * to analog mode | ||
268 | * | ||
269 | * This function applys the tuner config to tuner specified | ||
270 | * by tun_setup structure. It contains several per-tuner initialization "magic" | ||
271 | */ | ||
243 | static void set_type(struct i2c_client *c, unsigned int type, | 272 | static void set_type(struct i2c_client *c, unsigned int type, |
244 | unsigned int new_mode_mask, unsigned int new_config, | 273 | unsigned int new_mode_mask, unsigned int new_config, |
245 | int (*tuner_callback) (void *dev, int component, int cmd, int arg)) | 274 | 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, | |||
452 | return 0; | 481 | return 0; |
453 | } | 482 | } |
454 | 483 | ||
484 | /** | ||
485 | * tuner_s_config - Sets tuner configuration | ||
486 | * | ||
487 | * @sd: subdev descriptor | ||
488 | * @cfg: tuner configuration | ||
489 | * | ||
490 | * Calls tuner set_config() private function to set some tuner-internal | ||
491 | * parameters | ||
492 | */ | ||
455 | static int tuner_s_config(struct v4l2_subdev *sd, | 493 | static int tuner_s_config(struct v4l2_subdev *sd, |
456 | const struct v4l2_priv_tun_config *cfg) | 494 | const struct v4l2_priv_tun_config *cfg) |
457 | { | 495 | { |
@@ -470,10 +508,20 @@ static int tuner_s_config(struct v4l2_subdev *sd, | |||
470 | return 0; | 508 | return 0; |
471 | } | 509 | } |
472 | 510 | ||
473 | /* Search for existing radio and/or TV tuners on the given I2C adapter. | 511 | /** |
474 | Note that when this function is called from tuner_probe you can be | 512 | * tuner_lookup - Seek for tuner adapters |
475 | certain no other devices will be added/deleted at the same time, I2C | 513 | * |
476 | core protects against that. */ | 514 | * @adap: i2c_adapter struct |
515 | * @radio: pointer to be filled if the adapter is radio | ||
516 | * @tv: pointer to be filled if the adapter is TV | ||
517 | * | ||
518 | * Search for existing radio and/or TV tuners on the given I2C adapter, | ||
519 | * discarding demod-only adapters (tda9887). | ||
520 | * | ||
521 | * Note that when this function is called from tuner_probe you can be | ||
522 | * certain no other devices will be added/deleted at the same time, I2C | ||
523 | * core protects against that. | ||
524 | */ | ||
477 | static void tuner_lookup(struct i2c_adapter *adap, | 525 | static void tuner_lookup(struct i2c_adapter *adap, |
478 | struct tuner **radio, struct tuner **tv) | 526 | struct tuner **radio, struct tuner **tv) |
479 | { | 527 | { |
@@ -502,8 +550,20 @@ static void tuner_lookup(struct i2c_adapter *adap, | |||
502 | } | 550 | } |
503 | } | 551 | } |
504 | 552 | ||
505 | /* During client attach, set_type is called by adapter's attach_inform callback. | 553 | /** |
506 | set_type must then be completed by tuner_probe. | 554 | *tuner_probe - Probes the existing tuners on an I2C bus |
555 | * | ||
556 | * @client: i2c_client descriptor | ||
557 | * @id: not used | ||
558 | * | ||
559 | * This routine probes for tuners at the expected I2C addresses. On most | ||
560 | * cases, if a device answers to a given I2C address, it assumes that the | ||
561 | * device is a tuner. On a few cases, however, an additional logic is needed | ||
562 | * to double check if the device is really a tuner, or to identify the tuner | ||
563 | * type, like on tea5767/5761 devices. | ||
564 | * | ||
565 | * During client attach, set_type is called by adapter's attach_inform callback. | ||
566 | * set_type must then be completed by tuner_probe. | ||
507 | */ | 567 | */ |
508 | static int tuner_probe(struct i2c_client *client, | 568 | static int tuner_probe(struct i2c_client *client, |
509 | const struct i2c_device_id *id) | 569 | const struct i2c_device_id *id) |
@@ -618,6 +678,12 @@ register_client: | |||
618 | return 0; | 678 | return 0; |
619 | } | 679 | } |
620 | 680 | ||
681 | /** | ||
682 | * tuner_remove - detaches a tuner | ||
683 | * | ||
684 | * @client: i2c_client descriptor | ||
685 | */ | ||
686 | |||
621 | static int tuner_remove(struct i2c_client *client) | 687 | static int tuner_remove(struct i2c_client *client) |
622 | { | 688 | { |
623 | struct tuner *t = to_tuner(i2c_get_clientdata(client)); | 689 | struct tuner *t = to_tuner(i2c_get_clientdata(client)); |
@@ -635,7 +701,12 @@ static int tuner_remove(struct i2c_client *client) | |||
635 | * Functions that are specific for TV mode | 701 | * Functions that are specific for TV mode |
636 | */ | 702 | */ |
637 | 703 | ||
638 | /* Set tuner frequency, freq in Units of 62.5kHz = 1/16MHz */ | 704 | /** |
705 | * set_tv_freq - Set tuner frequency, freq in Units of 62.5 kHz = 1/16MHz | ||
706 | * | ||
707 | * @c: i2c_client descriptor | ||
708 | * @freq: frequency | ||
709 | */ | ||
639 | static void set_tv_freq(struct i2c_client *c, unsigned int freq) | 710 | static void set_tv_freq(struct i2c_client *c, unsigned int freq) |
640 | { | 711 | { |
641 | struct tuner *t = to_tuner(i2c_get_clientdata(c)); | 712 | 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) | |||
675 | analog_ops->set_params(&t->fe, ¶ms); | 746 | analog_ops->set_params(&t->fe, ¶ms); |
676 | } | 747 | } |
677 | 748 | ||
678 | /* get more precise norm info from insmod option */ | 749 | /** |
750 | * tuner_fixup_std - force a given video standard variant | ||
751 | * | ||
752 | * @t: tuner internal struct | ||
753 | * | ||
754 | * A few devices or drivers have problem to detect some standard variations. | ||
755 | * On other operational systems, the drivers generally have a per-country | ||
756 | * code, and some logic to apply per-country hacks. V4L2 API doesn't provide | ||
757 | * such hacks. Instead, it relies on a proper video standard selection from | ||
758 | * the userspace application. However, as some apps are buggy, not allowing | ||
759 | * to distinguish all video standard variations, a modprobe parameter can | ||
760 | * be used to force a video standard match. | ||
761 | */ | ||
679 | static int tuner_fixup_std(struct tuner *t) | 762 | static int tuner_fixup_std(struct tuner *t) |
680 | { | 763 | { |
681 | if ((t->std & V4L2_STD_PAL) == V4L2_STD_PAL) { | 764 | if ((t->std & V4L2_STD_PAL) == V4L2_STD_PAL) { |
@@ -797,6 +880,12 @@ static int tuner_fixup_std(struct tuner *t) | |||
797 | * Functions that are specific for Radio mode | 880 | * Functions that are specific for Radio mode |
798 | */ | 881 | */ |
799 | 882 | ||
883 | /** | ||
884 | * set_radio_freq - Set tuner frequency, freq in Units of 62.5 Hz = 1/16kHz | ||
885 | * | ||
886 | * @c: i2c_client descriptor | ||
887 | * @freq: frequency | ||
888 | */ | ||
800 | static void set_radio_freq(struct i2c_client *c, unsigned int freq) | 889 | static void set_radio_freq(struct i2c_client *c, unsigned int freq) |
801 | { | 890 | { |
802 | struct tuner *t = to_tuner(i2c_get_clientdata(c)); | 891 | struct tuner *t = to_tuner(i2c_get_clientdata(c)); |
@@ -972,7 +1061,9 @@ static int tuner_s_power(struct v4l2_subdev *sd, int on) | |||
972 | return 0; | 1061 | return 0; |
973 | } | 1062 | } |
974 | 1063 | ||
975 | /* ---------------------------------------------------------------------- */ | 1064 | /* |
1065 | * Function to splicitly change mode to radio. Probably not needed anymore | ||
1066 | */ | ||
976 | 1067 | ||
977 | static int tuner_s_radio(struct v4l2_subdev *sd) | 1068 | static int tuner_s_radio(struct v4l2_subdev *sd) |
978 | { | 1069 | { |
@@ -984,9 +1075,10 @@ static int tuner_s_radio(struct v4l2_subdev *sd) | |||
984 | return 0; | 1075 | return 0; |
985 | } | 1076 | } |
986 | 1077 | ||
987 | /* --- v4l ioctls --- */ | 1078 | /* |
988 | /* take care: bttv does userspace copying, we'll get a | 1079 | * Tuner callbacks to handle userspace ioctl's |
989 | kernel pointer here... */ | 1080 | */ |
1081 | |||
990 | static int tuner_s_std(struct v4l2_subdev *sd, v4l2_std_id std) | 1082 | static int tuner_s_std(struct v4l2_subdev *sd, v4l2_std_id std) |
991 | { | 1083 | { |
992 | struct tuner *t = to_tuner(sd); | 1084 | struct tuner *t = to_tuner(sd); |
@@ -1137,7 +1229,9 @@ static int tuner_command(struct i2c_client *client, unsigned cmd, void *arg) | |||
1137 | return -ENOIOCTLCMD; | 1229 | return -ENOIOCTLCMD; |
1138 | } | 1230 | } |
1139 | 1231 | ||
1140 | /* ----------------------------------------------------------------------- */ | 1232 | /* |
1233 | * Callback structs | ||
1234 | */ | ||
1141 | 1235 | ||
1142 | static const struct v4l2_subdev_core_ops tuner_core_ops = { | 1236 | static const struct v4l2_subdev_core_ops tuner_core_ops = { |
1143 | .log_status = tuner_log_status, | 1237 | .log_status = tuner_log_status, |
@@ -1160,11 +1254,10 @@ static const struct v4l2_subdev_ops tuner_ops = { | |||
1160 | .tuner = &tuner_tuner_ops, | 1254 | .tuner = &tuner_tuner_ops, |
1161 | }; | 1255 | }; |
1162 | 1256 | ||
1163 | /* ----------------------------------------------------------------------- */ | 1257 | /* |
1258 | * I2C structs and module init functions | ||
1259 | */ | ||
1164 | 1260 | ||
1165 | /* This driver supports many devices and the idea is to let the driver | ||
1166 | detect which device is present. So rather than listing all supported | ||
1167 | devices here, we pretend to support a single, fake device type. */ | ||
1168 | static const struct i2c_device_id tuner_id[] = { | 1261 | static const struct i2c_device_id tuner_id[] = { |
1169 | { "tuner", }, /* autodetect */ | 1262 | { "tuner", }, /* autodetect */ |
1170 | { } | 1263 | { } |