include/media/tuner-types.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 /*
   3  * descriptions for simple tuners.
   4  */
   5
   6 #ifndef __TUNER_TYPES_H__
   7 #define __TUNER_TYPES_H__
   8
   9 /**
  10  * enum param_type - type of the tuner pameters
  11  *
  12  * @TUNER_PARAM_TYPE_RADIO:     Tuner params are for FM and/or AM radio
  13  * @TUNER_PARAM_TYPE_PAL:       Tuner params are for PAL color TV standard
  14  * @TUNER_PARAM_TYPE_SECAM:     Tuner params are for SECAM color TV standard
  15  * @TUNER_PARAM_TYPE_NTSC:      Tuner params are for NTSC color TV standard
  16  * @TUNER_PARAM_TYPE_DIGITAL:   Tuner params are for digital TV
  17  */
  18 enum param_type {
  19         TUNER_PARAM_TYPE_RADIO,
  20         TUNER_PARAM_TYPE_PAL,
  21         TUNER_PARAM_TYPE_SECAM,
  22         TUNER_PARAM_TYPE_NTSC,
  23         TUNER_PARAM_TYPE_DIGITAL,
  24 };
  25
  26 /**
  27  * struct tuner_range - define the frequencies supported by the tuner
  28  *
  29  * @limit:              Max frequency supported by that range, in 62.5 kHz
  30  *                      (TV) or 62.5 Hz (Radio), as defined by
  31  *                      V4L2_TUNER_CAP_LOW.
  32  * @config:             Value of the band switch byte (BB) to setup this mode.
  33  * @cb:                 Value of the CB byte to setup this mode.
  34  *
  35  * Please notice that digital tuners like xc3028/xc4000/xc5000 don't use
  36  * those ranges, as they're defined inside the driver. This is used by
  37  * analog tuners that are compatible with the "Philips way" to setup the
  38  * tuners. On those devices, the tuner set is done via 4 bytes:
  39  *
  40  *      #) divider byte1 (DB1)
  41  *      #) divider byte 2 (DB2)
  42  *      #) Control byte (CB)
  43  *      #) band switch byte (BB)
  44  *
  45  * Some tuners also have an additional optional Auxiliary byte (AB).
  46  */
  47 struct tuner_range {
  48         unsigned short limit;
  49         unsigned char config;
  50         unsigned char cb;
  51 };
  52
  53 /**
  54  * struct tuner_params - Parameters to be used to setup the tuner. Those
  55  *                       are used by drivers/media/tuners/tuner-types.c in
  56  *                       order to specify the tuner properties. Most of
  57  *                       the parameters are for tuners based on tda9887 IF-PLL
  58  *                       multi-standard analog TV/Radio demodulator, with is
  59  *                       very common on legacy analog tuners.
  60  *
  61  * @type:                       Type of the tuner parameters, as defined at
  62  *                              enum param_type. If the tuner supports multiple
  63  *                              standards, an array should be used, with one
  64  *                              row per different standard.
  65  * @cb_first_if_lower_freq:     Many Philips-based tuners have a comment in
  66  *                              their datasheet like
  67  *                              "For channel selection involving band
  68  *                              switching, and to ensure smooth tuning to the
  69  *                              desired channel without causing unnecessary
  70  *                              charge pump action, it is recommended to
  71  *                              consider the difference between wanted channel
  72  *                              frequency and the current channel frequency.
  73  *                              Unnecessary charge pump action will result
  74  *                              in very low tuning voltage which may drive the
  75  *                              oscillator to extreme conditions".
  76  *                              Set cb_first_if_lower_freq to 1, if this check
  77  *                              is required for this tuner. I tested this for
  78  *                              PAL by first setting the TV frequency to
  79  *                              203 MHz and then switching to 96.6 MHz FM
  80  *                              radio. The result was static unless the
  81  *                              control byte was sent first.
  82  * @has_tda9887:                Set to 1 if this tuner uses a tda9887
  83  * @port1_fm_high_sensitivity:  Many Philips tuners use tda9887 PORT1 to select
  84  *                              the FM radio sensitivity. If this setting is 1,
  85  *                              then set PORT1 to 1 to get proper FM reception.
  86  * @port2_fm_high_sensitivity:  Some Philips tuners use tda9887 PORT2 to select
  87  *                              the FM radio sensitivity. If this setting is 1,
  88  *                              then set PORT2 to 1 to get proper FM reception.
  89  * @fm_gain_normal:             Some Philips tuners use tda9887 cGainNormal to
  90  *                              select the FM radio sensitivity. If this
  91  *                              setting is 1, e register will use cGainNormal
  92  *                              instead of cGainLow.
  93  * @intercarrier_mode:          Most tuners with a tda9887 use QSS mode.
  94  *                              Some (cheaper) tuners use Intercarrier mode.
  95  *                              If this setting is 1, then the tuner needs to
  96  *                              be set to intercarrier mode.
  97  * @port1_active:               This setting sets the default value for PORT1.
  98  *                              0 means inactive, 1 means active. Note: the
  99  *                              actual bit value written to the tda9887 is
 100  *                              inverted. So a 0 here means a 1 in the B6 bit.
 101  * @port2_active:               This setting sets the default value for PORT2.
 102  *                              0 means inactive, 1 means active. Note: the
 103  *                              actual bit value written to the tda9887 is
 104  *                              inverted. So a 0 here means a 1 in the B7 bit.
 105  * @port1_invert_for_secam_lc:  Sometimes PORT1 is inverted when the SECAM-L'
 106  *                              standard is selected. Set this bit to 1 if this
 107  *                              is needed.
 108  * @port2_invert_for_secam_lc:  Sometimes PORT2 is inverted when the SECAM-L'
 109  *                              standard is selected. Set this bit to 1 if this
 110  *                              is needed.
 111  * @port1_set_for_fm_mono:      Some cards require PORT1 to be 1 for mono Radio
 112  *                              FM and 0 for stereo.
 113  * @default_pll_gating_18:      Select 18% (or according to datasheet 0%)
 114  *                              L standard PLL gating, vs the driver default
 115  *                              of 36%.
 116  * @radio_if:                   IF to use in radio mode.  Tuners with a
 117  *                              separate radio IF filter seem to use 10.7,
 118  *                              while those without use 33.3 for PAL/SECAM
 119  *                              tuners and 41.3 for NTSC tuners.
 120  *                              0 = 10.7, 1 = 33.3, 2 = 41.3
 121  * @default_top_low:            Default tda9887 TOP value in dB for the low
 122  *                              band. Default is 0. Range: -16:+15
 123  * @default_top_mid:            Default tda9887 TOP value in dB for the mid
 124  *                              band. Default is 0. Range: -16:+15
 125  * @default_top_high:           Default tda9887 TOP value in dB for the high
 126  *                              band. Default is 0. Range: -16:+15
 127  * @default_top_secam_low:      Default tda9887 TOP value in dB for SECAM-L/L'
 128  *                              for the low band. Default is 0. Several tuners
 129  *                              require a different TOP value for the
 130  *                              SECAM-L/L' standards. Range: -16:+15
 131  * @default_top_secam_mid:      Default tda9887 TOP value in dB for SECAM-L/L'
 132  *                              for the mid band. Default is 0. Several tuners
 133  *                              require a different TOP value for the
 134  *                              SECAM-L/L' standards. Range: -16:+15
 135  * @default_top_secam_high:     Default tda9887 TOP value in dB for SECAM-L/L'
 136  *                              for the high band. Default is 0. Several tuners
 137  *                              require a different TOP value for the
 138  *                              SECAM-L/L' standards. Range: -16:+15
 139  * @iffreq:                     Intermediate frequency (IF) used by the tuner
 140  *                              on digital mode.
 141  * @count:                      Size of the ranges array.
 142  * @ranges:                     Array with the frequency ranges supported by
 143  *                              the tuner.
 144  */
 145 struct tuner_params {
 146         enum param_type type;
 147
 148         unsigned int cb_first_if_lower_freq:1;
 149         unsigned int has_tda9887:1;
 150         unsigned int port1_fm_high_sensitivity:1;
 151         unsigned int port2_fm_high_sensitivity:1;
 152         unsigned int fm_gain_normal:1;
 153         unsigned int intercarrier_mode:1;
 154         unsigned int port1_active:1;
 155         unsigned int port2_active:1;
 156         unsigned int port1_invert_for_secam_lc:1;
 157         unsigned int port2_invert_for_secam_lc:1;
 158         unsigned int port1_set_for_fm_mono:1;
 159         unsigned int default_pll_gating_18:1;
 160         unsigned int radio_if:2;
 161         signed int default_top_low:5;
 162         signed int default_top_mid:5;
 163         signed int default_top_high:5;
 164         signed int default_top_secam_low:5;
 165         signed int default_top_secam_mid:5;
 166         signed int default_top_secam_high:5;
 167
 168         u16 iffreq;
 169
 170         unsigned int count;
 171         struct tuner_range *ranges;
 172 };
 173
 174 /**
 175  * struct tunertype - describes the known tuners.
 176  *
 177  * @name:       string with the tuner's name.
 178  * @count:      size of &struct tuner_params array.
 179  * @params:     pointer to &struct tuner_params array.
 180  *
 181  * @min:        minimal tuner frequency, in 62.5 kHz step.
 182  *              should be multiplied to 16 to convert to MHz.
 183  * @max:        minimal tuner frequency, in 62.5 kHz step.
 184  *              Should be multiplied to 16 to convert to MHz.
 185  * @stepsize:   frequency step, in Hz.
 186  * @initdata:   optional byte sequence to initialize the tuner.
 187  * @sleepdata:  optional byte sequence to power down the tuner.
 188  */
 189 struct tunertype {
 190         char *name;
 191         unsigned int count;
 192         struct tuner_params *params;
 193
 194         u16 min;
 195         u16 max;
 196         u32 stepsize;
 197
 198         u8 *initdata;
 199         u8 *sleepdata;
 200 };
 201
 202 extern struct tunertype tuners[];
 203 extern unsigned const int tuner_count;
 204
 205 #endif