code:
.. SPDX-License-Identifier: GPL-2.0

.. include:: <isonum.txt>

=========================================
Rockchip Image Signal Processor (rkisp1)
=========================================

Introduction
============

This file documents the driver for the Rockchip ISP1 that is part of RK3288
and RK3399 SoCs. The driver is located under drivers/staging/media/rkisp1
and uses the Media-Controller API.

Revisions
=========

There exist multiple smaller revisions to this ISP that got introduced in
later SoCs. Revisions can be found in the enum :c:type:`rkisp1_cif_isp_version`
in the UAPI and the revision of the ISP inside the running SoC can be read
in the field hw_revision of struct media_device_info as returned by
ioctl MEDIA_IOC_DEVICE_INFO.

Versions in use are:

- RKISP1_V10: used at least in rk3288 and rk3399
- RKISP1_V11: declared in the original vendor code, but not used
- RKISP1_V12: used at least in rk3326 and px30
- RKISP1_V13: used at least in rk1808

Topology
========
.. _rkisp1_topology_graph:

.. kernel-figure:: rkisp1.dot
    :alt:   Diagram of the default media pipeline topology
    :align: center

The driver has 4 video devices:

- rkisp1_mainpath: capture device for retrieving images, usually in higher
  resolution.
- rkisp1_selfpath: capture device for retrieving images.
- rkisp1_stats: a metadata capture device that sends statistics.
- rkisp1_params: a metadata output device that receives parameters
  configurations from userspace.

The driver has 3 subdevices:

- rkisp1_resizer_mainpath: used to resize and downsample frames for the
  mainpath capture device.
- rkisp1_resizer_selfpath: used to resize and downsample frames for the
  selfpath capture device.
- rkisp1_isp: is connected to the sensor and is responsible for all the isp
  operations.

rkisp1_mainpath, rkisp1_selfpath - Frames Capture Video Nodes
-------------------------------------------------------------
Those are the `mainpath` and `selfpath` capture devices to capture frames.
Those entities are the DMA engines that write the frames to memory.
The selfpath video device can capture YUV/RGB formats. Its input is YUV encoded
stream and it is able to convert it to RGB. The selfpath is not able to
capture bayer formats.
The mainpath can capture both bayer and YUV formats but it is not able to
capture RGB formats.
Both capture videos support
the ``V4L2_CAP_IO_MC`` :ref:`capability <device-capabilities>`.

rkisp1_resizer_mainpath, rkisp1_resizer_selfpath - Resizers Subdevices Nodes
----------------------------------------------------------------------------
Those are resizer entities for the mainpath and the selfpath. Those entities
can scale the frames up and down and also change the YUV sampling (for example
YUV4:2:2 -> YUV4:2:0). They also have cropping capability on the sink pad.
The resizers entities can only operate on YUV:4:2:2 format
(MEDIA_BUS_FMT_YUYV8_2X8).
The mainpath capture device supports capturing video in bayer formats. In that
case the resizer of the mainpath is set to 'bypass' mode - it just forward the
frame without operating on it.

rkisp1_isp - Image Signal Processing Subdevice Node
---------------------------------------------------
This is the isp entity. It is connected to the sensor on sink pad 0 and
receives the frames using the CSI-2 protocol. It is responsible of configuring
the CSI-2 protocol. It has a cropping capability on sink pad 0 that is
connected to the sensor and on source pad 2 connected to the resizer entities.
Cropping on sink pad 0 defines the image region from the sensor.
Cropping on source pad 2 defines the region for the Image Stabilizer (IS).

.. _rkisp1_stats:

rkisp1_stats - Statistics Video Node
------------------------------------
The statistics video node outputs the 3A (auto focus, auto exposure and auto
white balance) statistics, and also histogram statistics for the frames that
are being processed by the rkisp1 to userspace applications.
Using these data, applications can implement algorithms and re-parameterize
the driver through the rkisp_params node to improve image quality during a
video stream.
The buffer format is defined by struct :c:type:`rkisp1_stat_buffer`, and
userspace should set
:ref:`V4L2_META_FMT_RK_ISP1_STAT_3A <v4l2-meta-fmt-rk-isp1-stat-3a>` as the
dataformat.

.. _rkisp1_params:

rkisp1_params - Parameters Video Node
-------------------------------------
The rkisp1_params video node receives a set of parameters from userspace
to be applied to the hardware during a video stream, allowing userspace
to dynamically modify values such as black level, cross talk corrections
and others.

The buffer format is defined by struct :c:type:`rkisp1_params_cfg`, and
userspace should set
:ref:`V4L2_META_FMT_RK_ISP1_PARAMS <v4l2-meta-fmt-rk-isp1-params>` as the
dataformat.

Capturing Video Frames Example
==============================

In the following example, the sensor connected to pad 0 of 'rkisp1_isp' is
imx219.

The following commands can be used to capture video from the selfpath video
node with dimension 900x800 planar format YUV 4:2:2. It uses all cropping
capabilities possible, (see explanation right below)

.. code-block:: bash

	# set the links
	"media-ctl" "-d" "platform:rkisp1" "-r"
	"media-ctl" "-d" "platform:rkisp1" "-l" "'imx219 4-0010':0 -> 'rkisp1_isp':0 [1]"
	"media-ctl" "-d" "platform:rkisp1" "-l" "'rkisp1_isp':2 -> 'rkisp1_resizer_selfpath':0 [1]"
	"media-ctl" "-d" "platform:rkisp1" "-l" "'rkisp1_isp':2 -> 'rkisp1_resizer_mainpath':0 [0]"

	# set format for imx219 4-0010:0
	"media-ctl" "-d" "platform:rkisp1" "--set-v4l2" '"imx219 4-0010":0 [fmt:SRGGB10_1X10/1640x1232]'

	# set format for rkisp1_isp pads:
	"media-ctl" "-d" "platform:rkisp1" "--set-v4l2" '"rkisp1_isp":0 [fmt:SRGGB10_1X10/1640x1232 crop: (0,0)/1600x1200]'
	"media-ctl" "-d" "platform:rkisp1" "--set-v4l2" '"rkisp1_isp":2 [fmt:YUYV8_2X8/1600x1200 crop: (0,0)/1500x1100]'

	# set format for rkisp1_resizer_selfpath pads:
	"media-ctl" "-d" "platform:rkisp1" "--set-v4l2" '"rkisp1_resizer_selfpath":0 [fmt:YUYV8_2X8/1500x1100 crop: (300,400)/1400x1000]'
	"media-ctl" "-d" "platform:rkisp1" "--set-v4l2" '"rkisp1_resizer_selfpath":1 [fmt:YUYV8_2X8/900x800]'

	# set format for rkisp1_selfpath:
	"v4l2-ctl" "-z" "platform:rkisp1" "-d" "rkisp1_selfpath" "-v" "width=900,height=800,"
	"v4l2-ctl" "-z" "platform:rkisp1" "-d" "rkisp1_selfpath" "-v" "pixelformat=422P"

	# start streaming:
	v4l2-ctl "-z" "platform:rkisp1" "-d" "rkisp1_selfpath" "--stream-mmap" "--stream-count" "10"

In the above example the sensor is configured to bayer format:
`SRGGB10_1X10/1640x1232`. The rkisp1_isp:0 pad should be configured to the
same mbus format and dimensions as the sensor, otherwise streaming will fail
with 'EPIPE' error. So it is also configured to `SRGGB10_1X10/1640x1232`.
In addition, the rkisp1_isp:0 pad is configured to cropping `(0,0)/1600x1200`.

The cropping dimensions are automatically propagated to be the format of the
isp source pad `rkisp1_isp:2`. Another cropping operation is configured on
the isp source pad: `(0,0)/1500x1100`.

The resizer's sink pad `rkisp1_resizer_selfpath` should be configured to format
`YUYV8_2X8/1500x1100` in order to match the format on the other side of the
link. In addition a cropping `(300,400)/1400x1000` is configured on it.

The source pad of the resizer, `rkisp1_resizer_selfpath:1` is configured to
format `YUYV8_2X8/900x800`. That means that the resizer first crop a window
of `(300,400)/1400x100` from the received frame and then scales this window
to dimension `900x800`.

Note that the above example does not uses the stats-params control loop.
Therefore the capture frames will not go through the 3A algorithms and
probably won't have a good quality, and can even look dark and greenish.

Configuring Quantization
========================

The driver supports limited and full range quantization on YUV formats,
where limited is the default.
To switch between one or the other, userspace should use the Colorspace
Conversion API (CSC) for subdevices on source pad 2 of the
isp (`rkisp1_isp:2`). The quantization configured on this pad is the
quantization of the captured video frames on the mainpath and selfpath
video nodes.
Note that the resizer and capture entities will always report
``V4L2_QUANTIZATION_DEFAULT`` even if the quantization is configured to full
range on `rkisp1_isp:2`. So in order to get the configured quantization,
application should get it from pad `rkisp1_isp:2`.


code:
.. SPDX-License-Identifier: GPL-2.0

SAA7134 cards list
==================

.. tabularcolumns:: |p{1.4cm}|p{11.1cm}|p{4.2cm}|

.. flat-table::
   :header-rows: 1
   :widths: 2 19 18
   :stub-columns: 0

   * - Card number
     - Card name
     - PCI subsystem IDs

   * - 0
     - UNKNOWN/GENERIC
     -

   * - 1
     - Proteus Pro [philips reference design]
     - 1131:2001, 1131:2001

   * - 2
     - LifeView FlyVIDEO3000
     - 5168:0138, 4e42:0138

   * - 3
     - LifeView/Typhoon FlyVIDEO2000
     - 5168:0138, 4e42:0138

   * - 4
     - EMPRESS
     - 1131:6752

   * - 5
     - SKNet Monster TV
     - 1131:4e85

   * - 6
     - Tevion MD 9717
     -

   * - 7
     - KNC One TV-Station RDS / Typhoon TV Tuner RDS
     - 1131:fe01, 1894:fe01

   * - 8
     - Terratec Cinergy 400 TV
     - 153b:1142

   * - 9
     - Medion 5044
     -

   * - 10
     - Kworld/KuroutoShikou SAA7130-TVPCI
     -

   * - 11
     - Terratec Cinergy 600 TV
     - 153b:1143

   * - 12
     - Medion 7134
     - 16be:0003, 16be:5000

   * - 13
     - Typhoon TV+Radio 90031
     -

   * - 14
     - ELSA EX-VISION 300TV
     - 1048:226b

   * - 15
     - ELSA EX-VISION 500TV
     - 1048:226a

   * - 16
     - ASUS TV-FM 7134
     - 1043:4842, 1043:4830, 1043:4840

   * - 17
     - AOPEN VA1000 POWER
     - 1131:7133

   * - 18
     - BMK MPEX No Tuner
     -

   * - 19
     - Compro VideoMate TV
     - 185b:c100

   * - 20
     - Matrox CronosPlus
     - 102B:48d0

   * - 21
     - 10MOONS PCI TV CAPTURE CARD
     - 1131:2001

   * - 22
     - AverMedia M156 / Medion 2819
     - 1461:a70b

   * - 23
     - BMK MPEX Tuner
     -

   * - 24
     - KNC One TV-Station DVR
     - 1894:a006

   * - 25
     - ASUS TV-FM 7133
     - 1043:4843

   * - 26
     - Pinnacle PCTV Stereo (saa7134)
     - 11bd:002b

   * - 27
     - Manli MuchTV M-TV002
     -

   * - 28
     - Manli MuchTV M-TV001
     -

   * - 29
     - Nagase Sangyo TransGear 3000TV
     - 1461:050c

   * - 30
     - Elitegroup ECS TVP3XP FM1216 Tuner Card(PAL-BG,FM)
     - 1019:4cb4

   * - 31
     - Elitegroup ECS TVP3XP FM1236 Tuner Card (NTSC,FM)
     - 1019:4cb5

   * - 32
     - AVACS SmartTV
     -

   * - 33
     - AVerMedia DVD EZMaker
     - 1461:10ff

   * - 34
     - Noval Prime TV 7133
     -

   * - 35
     - AverMedia AverTV Studio 305
     - 1461:2115

   * - 36
     - UPMOST PURPLE TV
     - 12ab:0800

   * - 37
     - Items MuchTV Plus / IT-005
     -

   * - 38
     - Terratec Cinergy 200 TV
     - 153b:1152

   * - 39
     - LifeView FlyTV Platinum Mini
     - 5168:0212, 4e42:0212, 5169:1502

   * - 40
     - Compro VideoMate TV PVR/FM
     - 185b:c100

   * - 41
     - Compro VideoMate TV Gold+
     - 185b:c100

   * - 42
     - Sabrent SBT-TVFM (saa7130)
     -

   * - 43
     - :Zolid Xpert TV7134
     -

   * - 44
     - Empire PCI TV-Radio LE
     -

   * - 45
     - Avermedia AVerTV Studio 307
     - 1461:9715

   * - 46
     - AVerMedia Cardbus TV/Radio (E500)
     - 1461:d6ee

   * - 47
     - Terratec Cinergy 400 mobile
     - 153b:1162

   * - 48
     - Terratec Cinergy 600 TV MK3
     - 153b:1158

   * - 49
     - Compro VideoMate Gold+ Pal
     - 185b:c200

   * - 50
     - Pinnacle PCTV 300i DVB-T + PAL
     - 11bd:002d

   * - 51
     - ProVideo PV952
     - 1540:9524

   * - 52
     - AverMedia AverTV/305
     - 1461:2108

   * - 53
     - ASUS TV-FM 7135
     - 1043:4845

   * - 54
     - LifeView FlyTV Platinum FM / Gold
     - 5168:0214, 5168:5214, 1489:0214, 5168:0304

   * - 55
     - LifeView FlyDVB-T DUO / MSI TV@nywhere Duo
     - 5168:0306, 4E42:0306

   * - 56
     - Avermedia AVerTV 307
     - 1461:a70a

   * - 57
     - Avermedia AVerTV GO 007 FM
     - 1461:f31f

   * - 58
     - ADS Tech Instant TV (saa7135)
     - 1421:0350, 1421:0351, 1421:0370, 1421:1370

   * - 59
     - Kworld/Tevion V-Stream Xpert TV PVR7134
     -

   * - 60
     - LifeView/Typhoon/Genius FlyDVB-T Duo Cardbus
     - 5168:0502, 4e42:0502, 1489:0502

   * - 61
     - Philips TOUGH DVB-T reference design
     - 1131:2004

   * - 62
     - Compro VideoMate TV Gold+II
     -

   * - 63
     - Kworld Xpert TV PVR7134
     -

   * - 64
     - FlyTV mini Asus Digimatrix
     - 1043:0210

   * - 65
     - V-Stream Studio TV Terminator
     -

   * - 66
     - Yuan TUN-900 (saa7135)
     -

   * - 67
     - Beholder BeholdTV 409 FM
     - 0000:4091

   * - 68
     - GoTView 7135 PCI
     - 5456:7135

   * - 69
     - Philips EUROPA V3 reference design
     - 1131:2004

   * - 70
     - Compro Videomate DVB-T300
     - 185b:c900

   * - 71
     - Compro Videomate DVB-T200
     - 185b:c901

   * - 72
     - RTD Embedded Technologies VFG7350
     - 1435:7350

   * - 73
     - RTD Embedded Technologies VFG7330
     - 1435:7330

   * - 74
     - LifeView FlyTV Platinum Mini2
     - 14c0:1212

   * - 75
     - AVerMedia AVerTVHD MCE A180
     - 1461:1044

   * - 76
     - SKNet MonsterTV Mobile
     - 1131:4ee9

   * - 77
     - Pinnacle PCTV 40i/50i/110i (saa7133)
     - 11bd:002e

   * - 78
     - ASUSTeK P7131 Dual
     - 1043:4862

   * - 79
     - Sedna/MuchTV PC TV Cardbus TV/Radio (ITO25 Rev:2B)
     -

   * - 80
     - ASUS Digimatrix TV
     - 1043:0210

   * - 81
     - Philips Tiger reference design
     - 1131:2018

   * - 82
     - MSI TV@Anywhere plus
     - 1462:6231, 1462:8624

   * - 83
     - Terratec Cinergy 250 PCI TV
     - 153b:1160

   * - 84
     - LifeView FlyDVB Trio
     - 5168:0319

   * - 85
     - AverTV DVB-T 777
     - 1461:2c05, 1461:2c05

   * - 86
     - LifeView FlyDVB-T / Genius VideoWonder DVB-T
     - 5168:0301, 1489:0301

   * - 87
     - ADS Instant TV Duo Cardbus PTV331
     - 0331:1421

   * - 88
     - Tevion/KWorld DVB-T 220RF
     - 17de:7201

   * - 89
     - ELSA EX-VISION 700TV
     - 1048:226c

   * - 90
     - Kworld ATSC110/115
     - 17de:7350, 17de:7352

   * - 91
     - AVerMedia A169 B
     - 1461:7360

   * - 92
     - AVerMedia A169 B1
     - 1461:6360

   * - 93
     - Medion 7134 Bridge #2
     - 16be:0005

   * - 94
     - LifeView FlyDVB-T Hybrid Cardbus/MSI TV @nywhere A/D NB
     - 5168:3306, 5168:3502, 5168:3307, 4e42:3502

   * - 95
     - LifeView FlyVIDEO3000 (NTSC)
     - 5169:0138

   * - 96
     - Medion Md8800 Quadro
     - 16be:0007, 16be:0008, 16be:000d

   * - 97
     - LifeView FlyDVB-S /Acorp TV134DS
     - 5168:0300, 4e42:0300

   * - 98
     - Proteus Pro 2309
     - 0919:2003

   * - 99
     - AVerMedia TV Hybrid A16AR
     - 1461:2c00

   * - 100
     - Asus Europa2 OEM
     - 1043:4860

   * - 101
     - Pinnacle PCTV 310i
     - 11bd:002f

   * - 102
     - Avermedia AVerTV Studio 507
     - 1461:9715

   * - 103
     - Compro Videomate DVB-T200A
     -

   * - 104
     - Hauppauge WinTV-HVR1110 DVB-T/Hybrid
     - 0070:6700, 0070:6701, 0070:6702, 0070:6703, 0070:6704, 0070:6705

   * - 105
     - Terratec Cinergy HT PCMCIA
     - 153b:1172

   * - 106
     - Encore ENLTV
     - 1131:2342, 1131:2341, 3016:2344

   * - 107
     - Encore ENLTV-FM
     - 1131:230f

   * - 108
     - Terratec Cinergy HT PCI
     - 153b:1175

   * - 109
     - Philips Tiger - S Reference design
     -

   * - 110
     - Avermedia M102
     - 1461:f31e

   * - 111
     - ASUS P7131 4871
     - 1043:4871

   * - 112
     - ASUSTeK P7131 Hybrid
     - 1043:4876

   * - 113
     - Elitegroup ECS TVP3XP FM1246 Tuner Card (PAL,FM)
     - 1019:4cb6

   * - 114
     - KWorld DVB-T 210
     - 17de:7250

   * - 115
     - Sabrent PCMCIA TV-PCB05
     - 0919:2003

   * - 116
     - 10MOONS TM300 TV Card
     - 1131:2304

   * - 117
     - Avermedia Super 007
     - 1461:f01d

   * - 118
     - Beholder BeholdTV 401
     - 0000:4016

   * - 119
     - Beholder BeholdTV 403
     - 0000:4036

   * - 120
     - Beholder BeholdTV 403 FM
     - 0000:4037

   * - 121
     - Beholder BeholdTV 405
     - 0000:4050

   * - 122
     - Beholder BeholdTV 405 FM
     - 0000:4051

   * - 123
     - Beholder BeholdTV 407
     - 0000:4070

   * - 124
     - Beholder BeholdTV 407 FM
     - 0000:4071

   * - 125
     - Beholder BeholdTV 409
     - 0000:4090

   * - 126
     - Beholder BeholdTV 505 FM
     - 5ace:5050

   * - 127
     - Beholder BeholdTV 507 FM / BeholdTV 509 FM
     - 5ace:5070, 5ace:5090

   * - 128
     - Beholder BeholdTV Columbus TV/FM
     - 0000:5201

   * - 129
     - Beholder BeholdTV 607 FM
     - 5ace:6070

   * - 130
     - Beholder BeholdTV M6
     - 5ace:6190

   * - 131
     - Twinhan Hybrid DTV-DVB 3056 PCI
     - 1822:0022

   * - 132
     - Genius TVGO AM11MCE
     -

   * - 133
     - NXP Snake DVB-S reference design
     -

   * - 134
     - Medion/Creatix CTX953 Hybrid
     - 16be:0010

   * - 135
     - MSI TV@nywhere A/D v1.1
     - 1462:8625

   * - 136
     - AVerMedia Cardbus TV/Radio (E506R)
     - 1461:f436

   * - 137
     - AVerMedia Hybrid TV/Radio (A16D)
     - 1461:f936

   * - 138
     - Avermedia M115
     - 1461:a836

   * - 139
     - Compro VideoMate T750
     - 185b:c900

   * - 140
     - Avermedia DVB-S Pro A700
     - 1461:a7a1

   * - 141
     - Avermedia DVB-S Hybrid+FM A700
     - 1461:a7a2

   * - 142
     - Beholder BeholdTV H6
     - 5ace:6290

   * - 143
     - Beholder BeholdTV M63
     - 5ace:6191

   * - 144
     - Beholder BeholdTV M6 Extra
     - 5ace:6193

   * - 145
     - AVerMedia MiniPCI DVB-T Hybrid M103
     - 1461:f636, 1461:f736

   * - 146
     - ASUSTeK P7131 Analog
     -

   * - 147
     - Asus Tiger 3in1
     - 1043:4878

   * - 148
     - Encore ENLTV-FM v5.3
     - 1a7f:2008

   * - 149
     - Avermedia PCI pure analog (M135A)
     - 1461:f11d

   * - 150
     - Zogis Real Angel 220
     -

   * - 151
     - ADS Tech Instant HDTV
     - 1421:0380

   * - 152
     - Asus Tiger Rev:1.00
     - 1043:4857

   * - 153
     - Kworld Plus TV Analog Lite PCI
     - 17de:7128

   * - 154
     - Avermedia AVerTV GO 007 FM Plus
     - 1461:f31d

   * - 155
     - Hauppauge WinTV-HVR1150 ATSC/QAM-Hybrid
     - 0070:6706, 0070:6708

   * - 156
     - Hauppauge WinTV-HVR1120 DVB-T/Hybrid
     - 0070:6707, 0070:6709, 0070:670a

   * - 157
     - Avermedia AVerTV Studio 507UA
     - 1461:a11b

   * - 158
     - AVerMedia Cardbus TV/Radio (E501R)
     - 1461:b7e9

   * - 159
     - Beholder BeholdTV 505 RDS
     - 0000:505B

   * - 160
     - Beholder BeholdTV 507 RDS
     - 0000:5071

   * - 161
     - Beholder BeholdTV 507 RDS
     - 0000:507B

   * - 162
     - Beholder BeholdTV 607 FM
     - 5ace:6071

   * - 163
     - Beholder BeholdTV 609 FM
     - 5ace:6090

   * - 164
     - Beholder BeholdTV 609 FM
     - 5ace:6091

   * - 165
     - Beholder BeholdTV 607 RDS
     - 5ace:6072

   * - 166
     - Beholder BeholdTV 607 RDS
     - 5ace:6073

   * - 167
     - Beholder BeholdTV 609 RDS
     - 5ace:6092

   * - 168
     - Beholder BeholdTV 609 RDS
     - 5ace:6093

   * - 169
     - Compro VideoMate S350/S300
     - 185b:c900

   * - 170
     - AverMedia AverTV Studio 505
     - 1461:a115

   * - 171
     - Beholder BeholdTV X7
     - 5ace:7595

   * - 172
     - RoverMedia TV Link Pro FM
     - 19d1:0138

   * - 173
     - Zolid Hybrid TV Tuner PCI
     - 1131:2004

   * - 174
     - Asus Europa Hybrid OEM
     - 1043:4847

   * - 175
     - Leadtek Winfast DTV1000S
     - 107d:6655

   * - 176
     - Beholder BeholdTV 505 RDS
     - 0000:5051

   * - 177
     - Hawell HW-404M7
     -

   * - 178
     - Beholder BeholdTV H7
     - 5ace:7190

   * - 179
     - Beholder BeholdTV A7
     - 5ace:7090

   * - 180
     - Avermedia PCI M733A
     - 1461:4155, 1461:4255

   * - 181
     - TechoTrend TT-budget T-3000
     - 13c2:2804

   * - 182
     - Kworld PCI SBTVD/ISDB-T Full-Seg Hybrid
     - 17de:b136

   * - 183
     - Compro VideoMate Vista M1F
     - 185b:c900

   * - 184
     - Encore ENLTV-FM 3
     - 1a7f:2108

   * - 185
     - MagicPro ProHDTV Pro2 DMB-TH/Hybrid
     - 17de:d136

   * - 186
     - Beholder BeholdTV 501
     - 5ace:5010

   * - 187
     - Beholder BeholdTV 503 FM
     - 5ace:5030

   * - 188
     - Sensoray 811/911
     - 6000:0811, 6000:0911

   * - 189
     - Kworld PC150-U
     - 17de:a134

   * - 190
     - Asus My Cinema PS3-100
     - 1043:48cd

   * - 191
     - Hawell HW-9004V1
     -

   * - 192
     - AverMedia AverTV Satellite Hybrid+FM A706
     - 1461:2055

   * - 193
     - WIS Voyager or compatible
     - 1905:7007

   * - 194
     - AverMedia AverTV/505
     - 1461:a10a

   * - 195
     - Leadtek Winfast TV2100 FM
     - 107d:6f3a

   * - 196
     - SnaZio* TVPVR PRO
     - 1779:13cf

repo_name: angery/linux


code:
.. SPDX-License-Identifier: GPL-2.0

The saa7134 driver
==================

Author Gerd Hoffmann

This is a v4l2/oss device driver for saa7130/33/34/35 based capture / TV
boards.

Status
------

Almost everything is working.  video, sound, tuner, radio, mpeg ts, ...

As with bttv, card-specific tweaks are needed.  Check CARDLIST for a
list of known TV cards and saa7134-cards.c for the drivers card
configuration info.

Build
-----

Once you pick up a Kernel source, you should configure, build,
install and boot the new kernel.  You'll need at least
these config options::

    ./scripts/config -e PCI
    ./scripts/config -e INPUT
    ./scripts/config -m I2C
    ./scripts/config -m MEDIA_SUPPORT
    ./scripts/config -e MEDIA_PCI_SUPPORT
    ./scripts/config -e MEDIA_ANALOG_TV_SUPPORT
    ./scripts/config -e MEDIA_DIGITAL_TV_SUPPORT
    ./scripts/config -e MEDIA_RADIO_SUPPORT
    ./scripts/config -e RC_CORE
    ./scripts/config -e MEDIA_SUBDRV_AUTOSELECT
    ./scripts/config -m VIDEO_SAA7134
    ./scripts/config -e SAA7134_ALSA
    ./scripts/config -e VIDEO_SAA7134_RC
    ./scripts/config -e VIDEO_SAA7134_DVB
    ./scripts/config -e VIDEO_SAA7134_GO7007

To build and install, you should run::

    make && make modules_install && make install

Once the new Kernel is booted, saa7134 driver should be loaded automatically.

Depending on the card you might have to pass ``card=<nr>`` as insmod option.
If so, please check Documentation/admin-guide/media/saa7134-cardlist.rst
for valid choices.

Once you have your card type number, you can pass a modules configuration
via a file (usually, it is either ``/etc/modules.conf`` or some file at
``/etc/modules-load.d/``, but the actual place depends on your
distribution), with this content::

    options saa7134 card=13 # Assuming that your card type is #13

Changes / Fixes
---------------

Please mail to linux-media AT vger.kernel.org unified diffs against
the linux media git tree:

    https://git.linuxtv.org/media_tree.git/

This is done by committing a patch at a clone of the git tree and
submitting the patch using ``git send-email``. Don't forget to
describe at the lots  what it changes / which problem it fixes / whatever
it is good for ...

Known Problems
--------------

* The tuner for the flyvideos isn't detected automatically and the
  default might not work for you depending on which version you have.
  There is a ``tuner=`` insmod option to override the driver's default.

Credits
-------

andrew.stevens@philips.com + werner.leeb@philips.com for providing
saa7134 hardware specs and sample board.


code:
.. SPDX-License-Identifier: GPL-2.0

SAA7164 cards list
==================

.. tabularcolumns:: |p{1.4cm}|p{11.1cm}|p{4.2cm}|

.. flat-table::
   :header-rows: 1
   :widths: 2 19 18
   :stub-columns: 0

   * - Card number
     - Card name
     - PCI subsystem IDs

   * - 0
     - Unknown
     -

   * - 1
     - Generic Rev2
     -

   * - 2
     - Generic Rev3
     -

   * - 3
     - Hauppauge WinTV-HVR2250
     - 0070:8880, 0070:8810

   * - 4
     - Hauppauge WinTV-HVR2200
     - 0070:8980

   * - 5
     - Hauppauge WinTV-HVR2200
     - 0070:8900

   * - 6
     - Hauppauge WinTV-HVR2200
     - 0070:8901

   * - 7
     - Hauppauge WinTV-HVR2250
     - 0070:8891, 0070:8851

   * - 8
     - Hauppauge WinTV-HVR2250
     - 0070:88A1

   * - 9
     - Hauppauge WinTV-HVR2200
     - 0070:8940

   * - 10
     - Hauppauge WinTV-HVR2200
     - 0070:8953

   * - 11
     - Hauppauge WinTV-HVR2255(proto)
     - 0070:f111

   * - 12
     - Hauppauge WinTV-HVR2255
     - 0070:f111

   * - 13
     - Hauppauge WinTV-HVR2205
     - 0070:f123, 0070:f120


code:
.. SPDX-License-Identifier: GPL-2.0

.. include:: <isonum.txt>

The Silicon Labs Si470x FM Radio Receivers driver
=================================================

Copyright |copy| 2009 Tobias Lorenz <tobias.lorenz@gmx.net>

Information from Silicon Labs
-----------------------------

Silicon Laboratories is the manufacturer of the radio ICs, that nowadays are the
most often used radio receivers in cell phones. Usually they are connected with
I2C. But SiLabs also provides a reference design, which integrates this IC,
together with a small microcontroller C8051F321, to form a USB radio.
Part of this reference design is also a radio application in binary and source
code. The software also contains an automatic firmware upgrade to the most
current version. Information on these can be downloaded here:
http://www.silabs.com/usbradio

Supported ICs
-------------

The following ICs have a very similar register set, so that they are or will be
supported somewhen by the driver:

- Si4700: FM radio receiver
- Si4701: FM radio receiver, RDS Support
- Si4702: FM radio receiver
- Si4703: FM radio receiver, RDS Support
- Si4704: FM radio receiver, no external antenna required
- Si4705: FM radio receiver, no external antenna required, RDS support, Dig I/O
- Si4706: Enhanced FM RDS/TMC radio receiver, no external antenna required, RDS
	  Support
- Si4707: Dedicated weather band radio receiver with SAME decoder, RDS Support
- Si4708: Smallest FM receivers
- Si4709: Smallest FM receivers, RDS Support

More information on these can be downloaded here:
http://www.silabs.com/products/mcu/Pages/USBFMRadioRD.aspx

Supported USB devices
---------------------

Currently the following USB radios (vendor:product) with the Silicon Labs si470x
chips are known to work:

- 10c4:818a: Silicon Labs USB FM Radio Reference Design
- 06e1:a155: ADS/Tech FM Radio Receiver (formerly Instant FM Music) (RDX-155-EF)
- 1b80:d700: KWorld USB FM Radio SnapMusic Mobile 700 (FM700)
- 10c5:819a: Sanei Electric, Inc. FM USB Radio (sold as DealExtreme.com PCear)

Software
--------

Testing is usually done with most application under Debian/testing:

- fmtools - Utility for managing FM tuner cards
- gnomeradio - FM-radio tuner for the GNOME desktop
- gradio - GTK FM radio tuner
- kradio - Comfortable Radio Application for KDE
- radio - ncurses-based radio application
- mplayer - The Ultimate Movie Player For Linux
- v4l2-ctl - Collection of command line video4linux utilities

For example, you can use:

.. code-block:: none

	v4l2-ctl -d /dev/radio0 --set-ctrl=volume=10,mute=0 --set-freq=95.21 --all

There is also a library libv4l, which can be used. It's going to have a function
for frequency seeking, either by using hardware functionality as in radio-si470x
or by implementing a function as we currently have in every of the mentioned
programs. Somewhen the radio programs should make use of libv4l.

For processing RDS information, there is a project ongoing at:
http://rdsd.berlios.de/

There is currently no project for making TMC sentences human readable.

Audio Listing
-------------

USB Audio is provided by the ALSA snd_usb_audio module. It is recommended to
also select SND_USB_AUDIO, as this is required to get sound from the radio. For
listing you have to redirect the sound, for example using one of the following
commands. Please adjust the audio devices to your needs (/dev/dsp* and hw:x,x).

If you just want to test audio (very poor quality):

.. code-block:: none

	cat /dev/dsp1 > /dev/dsp

If you use sox + OSS try:

.. code-block:: none

	sox -2 --endian little -r 96000 -t oss /dev/dsp1 -t oss /dev/dsp

or using sox + alsa:

.. code-block:: none

	sox --endian little -c 2 -S -r 96000 -t alsa hw:1 -t alsa -r 96000 hw:0

If you use arts try:

.. code-block:: none

	arecord -D hw:1,0 -r96000 -c2 -f S16_LE | artsdsp aplay -B -

If you use mplayer try:

.. code-block:: none

	mplayer -radio adevice=hw=1.0:arate=96000 \
		-rawaudio rate=96000 \
		radio://<frequency>/capture

Module Parameters
-----------------

After loading the module, you still have access to some of them in the sysfs
mount under /sys/module/radio_si470x/parameters. The contents of read-only files
(0444) are not updated, even if space, band and de are changed using private
video controls. The others are runtime changeable.

Errors
------

Increase tune_timeout, if you often get -EIO errors.

When timed out or band limit is reached, hw_freq_seek returns -EAGAIN.

If you get any errors from snd_usb_audio, please report them to the ALSA people.

Open Issues
-----------

V4L minor device allocation and parameter setting is not perfect. A solution is
currently under discussion.

There is an USB interface for downloading/uploading new firmware images. Support
for it can be implemented using the request_firmware interface.

There is a RDS interrupt mode. The driver is already using the same interface
for polling RDS information, but is currently not using the interrupt mode.

There is a LED interface, which can be used to override the LED control
programmed in the firmware. This can be made available using the LED support
functions in the kernel.

Other useful information and links
----------------------------------

http://www.silabs.com/usbradio


code:
.. SPDX-License-Identifier: GPL-2.0

.. include:: <isonum.txt>

The Silicon Labs Si4713 FM Radio Transmitter Driver
===================================================

Copyright |copy| 2009 Nokia Corporation

Contact: Eduardo Valentin <eduardo.valentin@nokia.com>

Information about the Device
----------------------------

This chip is a Silicon Labs product. It is a I2C device, currently on 0x63 address.
Basically, it has transmission and signal noise level measurement features.

The Si4713 integrates transmit functions for FM broadcast stereo transmission.
The chip also allows integrated receive power scanning to identify low signal
power FM channels.

The chip is programmed using commands and responses. There are also several
properties which can change the behavior of this chip.

Users must comply with local regulations on radio frequency (RF) transmission.

Device driver description
-------------------------

There are two modules to handle this device. One is a I2C device driver
and the other is a platform driver.

The I2C device driver exports a v4l2-subdev interface to the kernel.
All properties can also be accessed by v4l2 extended controls interface, by
using the v4l2-subdev calls (g_ext_ctrls, s_ext_ctrls).

The platform device driver exports a v4l2 radio device interface to user land.
So, it uses the I2C device driver as a sub device in order to send the user
commands to the actual device. Basically it is a wrapper to the I2C device driver.

Applications can use v4l2 radio API to specify frequency of operation, mute state,
etc. But mostly of its properties will be present in the extended controls.

When the v4l2 mute property is set to 1 (true), the driver will turn the chip off.

Properties description
----------------------

The properties can be accessed using v4l2 extended controls.
Here is an output from v4l2-ctl util:

.. code-block:: none

	/ # v4l2-ctl -d /dev/radio0 --all -L
	Driver Info:
		Driver name   : radio-si4713
		Card type     : Silicon Labs Si4713 Modulator
		Bus info      :
		Driver version: 0
		Capabilities  : 0x00080800
			RDS Output
			Modulator
	Audio output: 0 (FM Modulator Audio Out)
	Frequency: 1408000 (88.000000 MHz)
	Video Standard = 0x00000000
	Modulator:
		Name                 : FM Modulator
		Capabilities         : 62.5 Hz stereo rds
		Frequency range      : 76.0 MHz - 108.0 MHz
		Subchannel modulation: stereo+rds

	User Controls

				mute (bool) : default=1 value=0

	FM Radio Modulator Controls

		rds_signal_deviation (int)  : min=0 max=90000 step=10 default=200 value=200 flags=slider
			rds_program_id (int)  : min=0 max=65535 step=1 default=0 value=0
		rds_program_type (int)  : min=0 max=31 step=1 default=0 value=0
			rds_ps_name (str)  : min=0 max=96 step=8 value='si4713  '
			rds_radio_text (str)  : min=0 max=384 step=32 value=''
	audio_limiter_feature_enabled (bool) : default=1 value=1
	audio_limiter_release_time (int)  : min=250 max=102390 step=50 default=5010 value=5010 flags=slider
		audio_limiter_deviation (int)  : min=0 max=90000 step=10 default=66250 value=66250 flags=slider
	audio_compression_feature_enabl (bool) : default=1 value=1
		audio_compression_gain (int)  : min=0 max=20 step=1 default=15 value=15 flags=slider
	audio_compression_threshold (int)  : min=-40 max=0 step=1 default=-40 value=-40 flags=slider
	audio_compression_attack_time (int)  : min=0 max=5000 step=500 default=0 value=0 flags=slider
	audio_compression_release_time (int)  : min=100000 max=1000000 step=100000 default=1000000 value=1000000 flags=slider
	pilot_tone_feature_enabled (bool) : default=1 value=1
		pilot_tone_deviation (int)  : min=0 max=90000 step=10 default=6750 value=6750 flags=slider
		pilot_tone_frequency (int)  : min=0 max=19000 step=1 default=19000 value=19000 flags=slider
		pre_emphasis_settings (menu) : min=0 max=2 default=1 value=1
		tune_power_level (int)  : min=0 max=120 step=1 default=88 value=88 flags=slider
		tune_antenna_capacitor (int)  : min=0 max=191 step=1 default=0 value=110 flags=slider

Here is a summary of them:

* Pilot is an audible tone sent by the device.

- pilot_frequency - Configures the frequency of the stereo pilot tone.
- pilot_deviation - Configures pilot tone frequency deviation level.
- pilot_enabled - Enables or disables the pilot tone feature.

* The si4713 device is capable of applying audio compression to the
  transmitted signal.

- acomp_enabled - Enables or disables the audio dynamic range control feature.
- acomp_gain - Sets the gain for audio dynamic range control.
- acomp_threshold - Sets the threshold level for audio dynamic range control.
- acomp_attack_time - Sets the attack time for audio dynamic range control.
- acomp_release_time - Sets the release time for audio dynamic range control.

* Limiter setups audio deviation limiter feature. Once a over deviation occurs,
  it is possible to adjust the front-end gain of the audio input and always
  prevent over deviation.

- limiter_enabled - Enables or disables the limiter feature.
- limiter_deviation - Configures audio frequency deviation level.
- limiter_release_time - Sets the limiter release time.

* Tuning power

- power_level - Sets the output power level for signal transmission.
  antenna_capacitor - This selects the value of antenna tuning capacitor
  manually or automatically if set to zero.

* RDS related

- rds_ps_name - Sets the RDS ps name field for transmission.
- rds_radio_text - Sets the RDS radio text for transmission.
- rds_pi - Sets the RDS PI field for transmission.
- rds_pty - Sets the RDS PTY field for transmission.

* Region related

- preemphasis - sets the preemphasis to be applied for transmission.

RNL
---

This device also has an interface to measure received noise level. To do that, you should
ioctl the device node. Here is an code of example:

.. code-block:: none

	int main (int argc, char *argv[])
	{
		struct si4713_rnl rnl;
		int fd = open("/dev/radio0", O_RDWR);
		int rval;

		if (argc < 2)
			return -EINVAL;

		if (fd < 0)
			return fd;

		sscanf(argv[1], "%d", &rnl.frequency);

		rval = ioctl(fd, SI4713_IOC_MEASURE_RNL, &rnl);
		if (rval < 0)
			return rval;

		printf("received noise level: %d\n", rnl.rnl);

		close(fd);
	}

The struct si4713_rnl and SI4713_IOC_MEASURE_RNL are defined under
include/linux/platform_data/media/si4713.h.

Stereo/Mono and RDS subchannels
-------------------------------

The device can also be configured using the available sub channels for
transmission. To do that use S/G_MODULATOR ioctl and configure txsubchans properly.
Refer to the V4L2 API specification for proper use of this ioctl.

Testing
-------
Testing is usually done with v4l2-ctl utility for managing FM tuner cards.
The tool can be found in v4l-dvb repository under v4l2-apps/util directory.

Example for setting rds ps name:

.. code-block:: none

	# v4l2-ctl -d /dev/radio0 --set-ctrl=rds_ps_name="Dummy"


code:
.. SPDX-License-Identifier: GPL-2.0

.. include:: <isonum.txt>

The SI476x Driver
=================

Copyright |copy| 2013 Andrey Smirnov <andrew.smirnov@gmail.com>

TODO for the driver
-------------------

- According to the SiLabs' datasheet it is possible to update the
  firmware of the radio chip in the run-time, thus bringing it to the
  most recent version. Unfortunately I couldn't find any mentioning of
  the said firmware update for the old chips that I tested the driver
  against, so for chips like that the driver only exposes the old
  functionality.

Parameters exposed over debugfs
-------------------------------
SI476x allow user to get multiple characteristics that can be very
useful for EoL testing/RF performance estimation, parameters that have
very little to do with V4L2 subsystem. Such parameters are exposed via
debugfs and can be accessed via regular file I/O operations.

The drivers exposes following files:

* /sys/kernel/debug/<device-name>/acf
  This file contains ACF(Automatically Controlled Features) status
  information. The contents of the file is binary data of the
  following layout:

  .. tabularcolumns:: |p{7ex}|p{12ex}|L|

  =============  ==============   ====================================
  Offset	 Name		  Description
  =============  ==============   ====================================
  0x00		 blend_int	  Flag, set when stereo separation has
				  crossed below the blend threshold
  0x01		 hblend_int	  Flag, set when HiBlend cutoff
				  frequency is lower than threshold
  0x02		 hicut_int	  Flag, set when HiCut cutoff
				  frequency is lower than threshold
  0x03		 chbw_int	  Flag, set when channel filter
				  bandwidth is less than threshold
  0x04		 softmute_int	  Flag indicating that softmute
				  attenuation has increased above
				  softmute threshold
  0x05		 smute		  0 - Audio is not soft muted
				  1 - Audio is soft muted
  0x06		 smattn		  Soft mute attenuation level in dB
  0x07		 chbw		  Channel filter bandwidth in kHz
  0x08		 hicut		  HiCut cutoff frequency in units of
				  100Hz
  0x09		 hiblend	  HiBlend cutoff frequency in units
				  of 100 Hz
  0x10		 pilot		  0 - Stereo pilot is not present
				  1 - Stereo pilot is present
  0x11		 stblend	  Stereo blend in %
  =============  ==============   ====================================

* /sys/kernel/debug/<device-name>/rds_blckcnt
  This file contains statistics about RDS receptions. It's binary data
  has the following layout:

  .. tabularcolumns:: |p{7ex}|p{12ex}|L|

  =============  ==============   ====================================
  Offset	 Name		  Description
  =============  ==============   ====================================
  0x00		 expected	  Number of expected RDS blocks
  0x02		 received	  Number of received RDS blocks
  0x04		 uncorrectable	  Number of uncorrectable RDS blocks
  =============  ==============   ====================================

* /sys/kernel/debug/<device-name>/agc
  This file contains information about parameters pertaining to
  AGC(Automatic Gain Control)

  The layout is:

  .. tabularcolumns:: |p{7ex}|p{12ex}|L|

  =============  ==============   ====================================
  Offset	 Name		  Description
  =============  ==============   ====================================
  0x00		 mxhi		  0 - FM Mixer PD high threshold is
				  not tripped
				  1 - FM Mixer PD high threshold is
				  tripped
  0x01		 mxlo		  ditto for FM Mixer PD low
  0x02		 lnahi		  ditto for FM LNA PD high
  0x03		 lnalo		  ditto for FM LNA PD low
  0x04		 fmagc1		  FMAGC1 attenuator resistance
				  (see datasheet for more detail)
  0x05		 fmagc2		  ditto for FMAGC2
  0x06		 pgagain	  PGA gain in dB
  0x07		 fmwblang	  FM/WB LNA Gain in dB
  =============  ==============   ====================================

* /sys/kernel/debug/<device-name>/rsq
  This file contains information about parameters pertaining to
  RSQ(Received Signal Quality)

  The layout is:

  .. tabularcolumns:: |p{7ex}|p{12ex}|p{60ex}|

  =============  ==============   ====================================
  Offset	 Name		  Description
  =============  ==============   ====================================
  0x00		 multhint	  0 - multipath value has not crossed
				  the Multipath high threshold
				  1 - multipath value has crossed
				  the Multipath high threshold
  0x01		 multlint	  ditto for Multipath low threshold
  0x02		 snrhint	  0 - received signal's SNR has not
				  crossed high threshold
				  1 - received signal's SNR has
				  crossed high threshold
  0x03		 snrlint	  ditto for low threshold
  0x04		 rssihint	  ditto for RSSI high threshold
  0x05		 rssilint	  ditto for RSSI low threshold
  0x06		 bltf		  Flag indicating if seek command
				  reached/wrapped seek band limit
  0x07		 snr_ready	  Indicates that SNR metrics is ready
  0x08		 rssiready	  ditto for RSSI metrics
  0x09		 injside	  0 - Low-side injection is being used
				  1 - High-side injection is used
  0x10		 afcrl		  Flag indicating if AFC rails
  0x11		 valid		  Flag indicating if channel is valid
  0x12		 readfreq	  Current tuned frequency
  0x14		 freqoff	  Signed frequency offset in units of
				  2ppm
  0x15		 rssi		  Signed value of RSSI in dBuV
  0x16		 snr		  Signed RF SNR in dB
  0x17		 issi		  Signed Image Strength Signal
				  indicator
  0x18		 lassi		  Signed Low side adjacent Channel
				  Strength indicator
  0x19		 hassi		  ditto fpr High side
  0x20		 mult		  Multipath indicator
  0x21		 dev		  Frequency deviation
  0x24		 assi		  Adjacent channel SSI
  0x25		 usn		  Ultrasonic noise indicator
  0x26		 pilotdev	  Pilot deviation in units of 100 Hz
  0x27		 rdsdev		  ditto for RDS
  0x28		 assidev	  ditto for ASSI
  0x29		 strongdev	  Frequency deviation
  0x30		 rdspi		  RDS PI code
  =============  ==============   ====================================

* /sys/kernel/debug/<device-name>/rsq_primary
  This file contains information about parameters pertaining to
  RSQ(Received Signal Quality) for primary tuner only. Layout is as
  the one above.


code:
.. SPDX-License-Identifier: GPL-2.0

Siano cards list
================

.. tabularcolumns:: p{13.3cm}|p{4.2cm}|

.. flat-table::
   :header-rows: 1
   :widths: 17 16
   :stub-columns: 0

   * - Card name
     - USB IDs
   * - Hauppauge Catamount
     - 2040:1700
   * - Hauppauge Okemo-A
     - 2040:1800
   * - Hauppauge Okemo-B
     - 2040:1801
   * - Hauppauge WinTV MiniCard
     - 2040:2000, 2040:200a, 2040:2010, 2040:2011, 2040:2019
   * - Hauppauge WinTV MiniCard Rev 2
     - 2040:2009
   * - Hauppauge WinTV MiniStick
     - 2040:5500, 2040:5510, 2040:5520, 2040:5530, 2040:5580, 2040:5590, 2040:b900, 2040:b910, 2040:b980, 2040:b990, 2040:c000, 2040:c010, 2040:c080, 2040:c090, 2040:c0a0, 2040:f5a0
   * - Hauppauge microStick 77e
     - 2013:0257
   * - ONDA Data Card Digital Receiver
     - 19D2:0078
   * - Siano Denver (ATSC-M/H) Digital Receiver
     - 187f:0800
   * - Siano Denver (TDMB) Digital Receiver
     - 187f:0700
   * - Siano Ming Digital Receiver
     - 187f:0310
   * - Siano Nice Digital Receiver
     - 187f:0202, 187f:0202
   * - Siano Nova A Digital Receiver
     - 187f:0200
   * - Siano Nova B Digital Receiver
     - 187f:0201
   * - Siano Pele Digital Receiver
     - 187f:0500
   * - Siano Rio Digital Receiver
     - 187f:0600, 3275:0080
   * - Siano Stellar Digital Receiver
     - 187f:0100
   * - Siano Stellar Digital Receiver ROM
     - 187f:0010
   * - Siano Vega Digital Receiver
     - 187f:0300
   * - Siano Venice Digital Receiver
     - 187f:0301, 187f:0301, 187f:0302
   * - ZTE Data Card Digital Receiver
     - 19D2:0086


code:
.. SPDX-License-Identifier: GPL-2.0

How to set up the Technisat/B2C2 Flexcop devices
================================================

.. note::

   This documentation is outdated.

Author: Uwe Bugla <uwe.bugla@gmx.de> August 2009

Find out what device you have
-----------------------------

Important Notice: The driver does NOT support Technisat USB 2 devices!

First start your linux box with a shipped kernel:

.. code-block:: none

	lspci -vvv for a PCI device (lsusb -vvv for an USB device) will show you for example:
	02:0b.0 Network controller: Techsan Electronics Co Ltd B2C2 FlexCopII DVB chip /
	Technisat SkyStar2 DVB card (rev 02)

	dmesg | grep frontend may show you for example:
	DVB: registering frontend 0 (Conexant CX24123/CX24109)...

Kernel compilation:
-------------------

If the Flexcop / Technisat is the only DVB / TV / Radio device in your box
get rid of unnecessary modules and check this one:

``Multimedia support`` => ``Customise analog and hybrid tuner modules to build``

In this directory uncheck every driver which is activated there
(except ``Simple tuner support`` for ATSC 3rd generation only -> see case 9 please).

Then please activate:

- Main module part:

  ``Multimedia support`` => ``DVB/ATSC adapters`` => ``Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters``

  #) => ``Technisat/B2C2 Air/Sky/Cable2PC PCI`` (PCI card) or
  #) => ``Technisat/B2C2 Air/Sky/Cable2PC USB`` (USB 1.1 adapter)
     and for troubleshooting purposes:
  #) => ``Enable debug for the B2C2 FlexCop drivers``

- Frontend / Tuner / Demodulator module part:

  ``Multimedia support`` => ``DVB/ATSC adapters``
   => ``Customise the frontend modules to build`` ``Customise DVB frontends`` =>

  - SkyStar DVB-S Revision 2.3:

    #) => ``Zarlink VP310/MT312/ZL10313 based``
    #) => ``Generic I2C PLL based tuners``

  - SkyStar DVB-S Revision 2.6:

    #) => ``ST STV0299 based``
    #) => ``Generic I2C PLL based tuners``

  - SkyStar DVB-S Revision 2.7:

    #) => ``Samsung S5H1420 based``
    #) => ``Integrant ITD1000 Zero IF tuner for DVB-S/DSS``
    #) => ``ISL6421 SEC controller``

  - SkyStar DVB-S Revision 2.8:

    #) => ``Conexant CX24123 based``
    #) => ``Conexant CX24113/CX24128 tuner for DVB-S/DSS``
    #) => ``ISL6421 SEC controller``

  - AirStar DVB-T card:

    #) => ``Zarlink MT352 based``
    #) => ``Generic I2C PLL based tuners``

  - CableStar DVB-C card:

    #) => ``ST STV0297 based``
    #) => ``Generic I2C PLL based tuners``

  - AirStar ATSC card 1st generation:

    #) => ``Broadcom BCM3510``

  - AirStar ATSC card 2nd generation:

    #) => ``NxtWave Communications NXT2002/NXT2004 based``
    #) => ``Generic I2C PLL based tuners``

  - AirStar ATSC card 3rd generation:

    #) => ``LG Electronics LGDT3302/LGDT3303 based``
    #) ``Multimedia support`` => ``Customise analog and hybrid tuner modules to build`` => ``Simple tuner support``


code:
.. SPDX-License-Identifier: GPL-2.0

TM6000 cards list
=================

.. tabularcolumns:: |p{1.4cm}|p{11.1cm}|p{4.2cm}|

.. flat-table::
   :header-rows: 1
   :widths: 2 19 18
   :stub-columns: 0

   * - Card number
     - Card name
     - USB IDs

   * - 0
     - Unknown tm6000 video grabber
     -

   * - 1
     - Generic tm5600 board
     - 6000:0001

   * - 2
     - Generic tm6000 board
     -

   * - 3
     - Generic tm6010 board
     - 6000:0002

   * - 4
     - 10Moons UT 821
     -

   * - 5
     - 10Moons UT 330
     -

   * - 6
     - ADSTECH Dual TV USB
     - 06e1:f332

   * - 7
     - Freecom Hybrid Stick / Moka DVB-T Receiver Dual
     - 14aa:0620

   * - 8
     - ADSTECH Mini Dual TV USB
     - 06e1:b339

   * - 9
     - Hauppauge WinTV HVR-900H / WinTV USB2-Stick
     - 2040:6600, 2040:6601, 2040:6610, 2040:6611

   * - 10
     - Beholder Wander DVB-T/TV/FM USB2.0
     - 6000:dec0

   * - 11
     - Beholder Voyager TV/FM USB2.0
     - 6000:dec1

   * - 12
     - Terratec Cinergy Hybrid XE / Cinergy Hybrid-Stick
     - 0ccd:0086, 0ccd:00A5

   * - 13
     - Twinhan TU501(704D1)
     - 13d3:3240, 13d3:3241, 13d3:3243, 13d3:3264

   * - 14
     - Beholder Wander Lite DVB-T/TV/FM USB2.0
     - 6000:dec2

   * - 15
     - Beholder Voyager Lite TV/FM USB2.0
     - 6000:dec3

   * - 16
     - Terratec Grabster AV 150/250 MX
     - 0ccd:0079


code:
.. SPDX-License-Identifier: GPL-2.0

TechnoTrend/Hauppauge DEC USB Driver
====================================

Driver Status
-------------

Supported:

	- DEC2000-t
	- DEC2450-t
	- DEC3000-s
	- Video Streaming
	- Audio Streaming
	- Section Filters
	- Channel Zapping
	- Hotplug firmware loader

To Do:

	- Tuner status information
	- DVB network interface
	- Streaming video PC->DEC
	- Conax support for 2450-t

Getting the Firmware
--------------------
To download the firmware, use the following commands:

.. code-block:: none

	scripts/get_dvb_firmware dec2000t
	scripts/get_dvb_firmware dec2540t
	scripts/get_dvb_firmware dec3000s

Hotplug Firmware Loading
------------------------

Since 2.6 kernels, the firmware is loaded at the point that the driver module
is loaded.

Copy the three files downloaded above into the /usr/lib/hotplug/firmware or
/lib/firmware directory (depending on configuration of firmware hotplug).


code:
.. SPDX-License-Identifier: GPL-2.0

Tuner cards list
================

============ =====================================================
Tuner number Card name
============ =====================================================
0            Temic PAL (4002 FH5)
1            Philips PAL_I (FI1246 and compatibles)
2            Philips NTSC (FI1236,FM1236 and compatibles)
3            Philips (SECAM+PAL_BG) (FI1216MF, FM1216MF, FR1216MF)
4            NoTuner
5            Philips PAL_BG (FI1216 and compatibles)
6            Temic NTSC (4032 FY5)
7            Temic PAL_I (4062 FY5)
8            Temic NTSC (4036 FY5)
9            Alps HSBH1
10           Alps TSBE1
11           Alps TSBB5
12           Alps TSBE5
13           Alps TSBC5
14           Temic PAL_BG (4006FH5)
15           Alps TSCH6
16           Temic PAL_DK (4016 FY5)
17           Philips NTSC_M (MK2)
18           Temic PAL_I (4066 FY5)
19           Temic PAL* auto (4006 FN5)
20           Temic PAL_BG (4009 FR5) or PAL_I (4069 FR5)
21           Temic NTSC (4039 FR5)
22           Temic PAL/SECAM multi (4046 FM5)
23           Philips PAL_DK (FI1256 and compatibles)
24           Philips PAL/SECAM multi (FQ1216ME)
25           LG PAL_I+FM (TAPC-I001D)
26           LG PAL_I (TAPC-I701D)
27           LG NTSC+FM (TPI8NSR01F)
28           LG PAL_BG+FM (TPI8PSB01D)
29           LG PAL_BG (TPI8PSB11D)
30           Temic PAL* auto + FM (4009 FN5)
31           SHARP NTSC_JP (2U5JF5540)
32           Samsung PAL TCPM9091PD27
33           MT20xx universal
34           Temic PAL_BG (4106 FH5)
35           Temic PAL_DK/SECAM_L (4012 FY5)
36           Temic NTSC (4136 FY5)
37           LG PAL (newer TAPC series)
38           Philips PAL/SECAM multi (FM1216ME MK3)
39           LG NTSC (newer TAPC series)
40           HITACHI V7-J180AT
41           Philips PAL_MK (FI1216 MK)
42           Philips FCV1236D ATSC/NTSC dual in
43           Philips NTSC MK3 (FM1236MK3 or FM1236/F)
44           Philips 4 in 1 (ATI TV Wonder Pro/Conexant)
45           Microtune 4049 FM5
46           Panasonic VP27s/ENGE4324D
47           LG NTSC (TAPE series)
48           Tenna TNF 8831 BGFF)
49           Microtune 4042 FI5 ATSC/NTSC dual in
50           TCL 2002N
51           Philips PAL/SECAM_D (FM 1256 I-H3)
52           Thomson DTT 7610 (ATSC/NTSC)
53           Philips FQ1286
54           Philips/NXP TDA 8290/8295 + 8275/8275A/18271
55           TCL 2002MB
56           Philips PAL/SECAM multi (FQ1216AME MK4)
57           Philips FQ1236A MK4
58           Ymec TVision TVF-8531MF/8831MF/8731MF
59           Ymec TVision TVF-5533MF
60           Thomson DTT 761X (ATSC/NTSC)
61           Tena TNF9533-D/IF/TNF9533-B/DF
62           Philips TEA5767HN FM Radio
63           Philips FMD1216ME MK3 Hybrid Tuner
64           LG TDVS-H06xF
65           Ymec TVF66T5-B/DFF
66           LG TALN series
67           Philips TD1316 Hybrid Tuner
68           Philips TUV1236D ATSC/NTSC dual in
69           Tena TNF 5335 and similar models
70           Samsung TCPN 2121P30A
71           Xceive xc2028/xc3028 tuner
72           Thomson FE6600
73           Samsung TCPG 6121P30A
75           Philips TEA5761 FM Radio
76           Xceive 5000 tuner
77           TCL tuner MF02GIP-5N-E
78           Philips FMD1216MEX MK3 Hybrid Tuner
79           Philips PAL/SECAM multi (FM1216 MK5)
80           Philips FQ1216LME MK3 PAL/SECAM w/active loopthrough
81           Partsnic (Daewoo) PTI-5NF05
82           Philips CU1216L
83           NXP TDA18271
84           Sony BTF-Pxn01Z
85           Philips FQ1236 MK5
86           Tena TNF5337 MFD
87           Xceive 4000 tuner
88           Xceive 5000C tuner
89           Sony BTF-PG472Z PAL/SECAM
90           Sony BTF-PK467Z NTSC-M-JP
91           Sony BTF-PB463Z NTSC-M
============ =====================================================


code:
.. SPDX-License-Identifier: GPL-2.0

USB drivers
===========

The USB boards are identified by an identification called USB ID.

The ``lsusb`` command allows identifying the USB IDs::

    $ lsusb
    ...
    Bus 001 Device 015: ID 046d:082d Logitech, Inc. HD Pro Webcam C920
    Bus 001 Device 074: ID 2040:b131 Hauppauge
    Bus 001 Device 075: ID 2013:024f PCTV Systems nanoStick T2 290e
    ...

Newer camera devices use a standard way to expose themselves as such,
via USB Video Class. Those cameras are automatically supported by the
``uvc-driver``.

Older cameras and TV USB devices uses USB Vendor Classes: each vendor
defines its own way to access the device. This section contains
card lists for such vendor-class devices.

While this is not as common as on PCI, sometimes the same USB ID is used
by different products. So, several media drivers allow passing a ``card=``
parameter, in order to setup a card number that would match the correct
settings for an specific product type.

The current supported USB cards (not including staging drivers) are
listed below\ [#]_.

.. [#]

   some of the drivers have sub-drivers, not shown at this table.
   In particular, gspca driver has lots of sub-drivers,
   for cameras not supported by the USB Video Class (UVC) driver,
   as shown at :doc:`gspca card list <gspca-cardlist>`.

======================  =========================================================
Driver                  Name
======================  =========================================================
airspy                  AirSpy
au0828                  Auvitek AU0828
b2c2-flexcop-usb        Technisat/B2C2 Air/Sky/Cable2PC USB
cpia2                   CPiA2 Video For Linux
cx231xx                 Conexant cx231xx USB video capture
dvb-as102               Abilis AS102 DVB receiver
dvb-ttusb-budget        Technotrend/Hauppauge Nova - USB devices
dvb-usb-a800            AVerMedia AverTV DVB-T USB 2.0 (A800)
dvb-usb-af9005          Afatech AF9005 DVB-T USB1.1
dvb-usb-af9015          Afatech AF9015 DVB-T USB2.0
dvb-usb-af9035          Afatech AF9035 DVB-T USB2.0
dvb-usb-anysee          Anysee DVB-T/C USB2.0
dvb-usb-au6610          Alcor Micro AU6610 USB2.0
dvb-usb-az6007          AzureWave 6007 and clones DVB-T/C USB2.0
dvb-usb-az6027          Azurewave DVB-S/S2 USB2.0 AZ6027
dvb-usb-ce6230          Intel CE6230 DVB-T USB2.0
dvb-usb-cinergyT2       Terratec CinergyT2/qanu USB 2.0 DVB-T
dvb-usb-cxusb           Conexant USB2.0 hybrid
dvb-usb-dib0700         DiBcom DiB0700
dvb-usb-dibusb-common   DiBcom DiB3000M-B
dvb-usb-dibusb-mc       DiBcom DiB3000M-C/P
dvb-usb-digitv          Nebula Electronics uDigiTV DVB-T USB2.0
dvb-usb-dtt200u         WideView WT-200U and WT-220U (pen) DVB-T
dvb-usb-dtv5100         AME DTV-5100 USB2.0 DVB-T
dvb-usb-dvbsky          DVBSky USB
dvb-usb-dw2102          DvbWorld & TeVii DVB-S/S2 USB2.0
dvb-usb-ec168           E3C EC168 DVB-T USB2.0
dvb-usb-gl861           Genesys Logic GL861 USB2.0
dvb-usb-gp8psk          GENPIX 8PSK->USB module
dvb-usb-lmedm04         LME DM04/QQBOX DVB-S USB2.0
dvb-usb-m920x           Uli m920x DVB-T USB2.0
dvb-usb-nova-t-usb2     Hauppauge WinTV-NOVA-T usb2 DVB-T USB2.0
dvb-usb-opera           Opera1 DVB-S USB2.0 receiver
dvb-usb-pctv452e        Pinnacle PCTV HDTV Pro USB device/TT Connect S2-3600
dvb-usb-rtl28xxu        Realtek RTL28xxU DVB USB
dvb-usb-technisat-usb2  Technisat DVB-S/S2 USB2.0
dvb-usb-ttusb2          Pinnacle 400e DVB-S USB2.0
dvb-usb-umt-010         HanfTek UMT-010 DVB-T USB2.0
dvb_usb_v2              Support for various USB DVB devices v2
dvb-usb-vp702x          TwinhanDTV StarBox and clones DVB-S USB2.0
dvb-usb-vp7045          TwinhanDTV Alpha/MagicBoxII, DNTV tinyUSB2, Beetle USB2.0
em28xx                  Empia EM28xx USB devices
go7007                  WIS GO7007 MPEG encoder
gspca                   Drivers for several USB Cameras
hackrf                  HackRF
hdpvr                   Hauppauge HD PVR
msi2500                 Mirics MSi2500
mxl111sf-tuner          MxL111SF DTV USB2.0
pvrusb2                 Hauppauge WinTV-PVR USB2
pwc                     USB Philips Cameras
s2250                   Sensoray 2250/2251
s2255drv                USB Sensoray 2255 video capture device
smsusb                  Siano SMS1xxx based MDTV receiver
stkwebcam               USB Syntek DC1125 Camera
tm6000-alsa             TV Master TM5600/6000/6010 audio
tm6000-dvb              DVB Support for tm6000 based TV cards
tm6000                  TV Master TM5600/6000/6010 driver
ttusb_dec               Technotrend/Hauppauge USB DEC devices
usbtv                   USBTV007 video capture
uvcvideo                USB Video Class (UVC)
zd1301                  ZyDAS ZD1301
zr364xx                 USB ZR364XX Camera
======================  =========================================================

.. toctree::
	:maxdepth: 1

	au0828-cardlist
	cx231xx-cardlist
	em28xx-cardlist
	tm6000-cardlist
	siano-cardlist

	gspca-cardlist

	dvb-usb-dib0700-cardlist
	dvb-usb-dibusb-mb-cardlist
	dvb-usb-dibusb-mc-cardlist

	dvb-usb-a800-cardlist
	dvb-usb-af9005-cardlist
	dvb-usb-az6027-cardlist
	dvb-usb-cinergyT2-cardlist
	dvb-usb-cxusb-cardlist
	dvb-usb-digitv-cardlist
	dvb-usb-dtt200u-cardlist
	dvb-usb-dtv5100-cardlist
	dvb-usb-dw2102-cardlist
	dvb-usb-gp8psk-cardlist
	dvb-usb-m920x-cardlist
	dvb-usb-nova-t-usb2-cardlist
	dvb-usb-opera1-cardlist
	dvb-usb-pctv452e-cardlist
	dvb-usb-technisat-usb2-cardlist
	dvb-usb-ttusb2-cardlist
	dvb-usb-umt-010-cardlist
	dvb-usb-vp702x-cardlist
	dvb-usb-vp7045-cardlist

	dvb-usb-af9015-cardlist
	dvb-usb-af9035-cardlist
	dvb-usb-anysee-cardlist
	dvb-usb-au6610-cardlist
	dvb-usb-az6007-cardlist
	dvb-usb-ce6230-cardlist
	dvb-usb-dvbsky-cardlist
	dvb-usb-ec168-cardlist
	dvb-usb-gl861-cardlist
	dvb-usb-lmedm04-cardlist
	dvb-usb-mxl111sf-cardlist
	dvb-usb-rtl28xxu-cardlist
	dvb-usb-zd1301-cardlist

	other-usb-cardlist


code:
.. SPDX-License-Identifier: GPL-2.0

.. _uapi-v4l-drivers:

===============================================
Video4Linux (V4L) driver-specific documentation
===============================================

.. toctree::
	:maxdepth: 2

	bttv
	cafe_ccic
	cpia2
	cx88
	davinci-vpbe
	fimc
	imx
	imx7
	ipu3
	ivtv
	meye
	omap3isp
	omap4_camera
	philips
	qcom_camss
	rcar-fdp1
	rkisp1
	saa7134
	si470x
	si4713
	si476x
	vimc
	visl
	vivid


code:
# SPDX-License-Identifier: GPL-2.0

digraph board {
	rankdir=TB
	n00000001 [label="{{} | Sensor A\n/dev/v4l-subdev0 | {<port0> 0}}", shape=Mrecord, style=filled, fillcolor=green]
	n00000001:port0 -> n00000005:port0 [style=bold]
	n00000001:port0 -> n0000000b [style=bold]
	n00000001 -> n00000002
	n00000002 [label="{{} | Lens A\n/dev/v4l-subdev5 | {<port0>}}", shape=Mrecord, style=filled, fillcolor=green]
	n00000003 [label="{{} | Sensor B\n/dev/v4l-subdev1 | {<port0> 0}}", shape=Mrecord, style=filled, fillcolor=green]
	n00000003:port0 -> n00000008:port0 [style=bold]
	n00000003:port0 -> n0000000f [style=bold]
	n00000003 -> n00000004
	n00000004 [label="{{} | Lens B\n/dev/v4l-subdev6 | {<port0>}}", shape=Mrecord, style=filled, fillcolor=green]
	n00000005 [label="{{<port0> 0} | Debayer A\n/dev/v4l-subdev2 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green]
	n00000005:port1 -> n00000015:port0
	n00000008 [label="{{<port0> 0} | Debayer B\n/dev/v4l-subdev3 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green]
	n00000008:port1 -> n00000015:port0 [style=dashed]
	n0000000b [label="Raw Capture 0\n/dev/video0", shape=box, style=filled, fillcolor=yellow]
	n0000000f [label="Raw Capture 1\n/dev/video1", shape=box, style=filled, fillcolor=yellow]
	n00000013 [label="{{} | RGB/YUV Input\n/dev/v4l-subdev4 | {<port0> 0}}", shape=Mrecord, style=filled, fillcolor=green]
	n00000013:port0 -> n00000015:port0 [style=dashed]
	n00000015 [label="{{<port0> 0} | Scaler\n/dev/v4l-subdev5 | {<port1> 1}}", shape=Mrecord, style=filled, fillcolor=green]
	n00000015:port1 -> n00000018 [style=bold]
	n00000018 [label="RGB/YUV Capture\n/dev/video2", shape=box, style=filled, fillcolor=yellow]
}


code:
.. SPDX-License-Identifier: GPL-2.0

The Virtual Media Controller Driver (vimc)
==========================================

The vimc driver emulates complex video hardware using the V4L2 API and the Media
API. It has a capture device and three subdevices: sensor, debayer and scaler.

Topology
--------

The topology is hardcoded, although you could modify it in vimc-core and
recompile the driver to achieve your own topology. This is the default topology:

.. _vimc_topology_graph:

.. kernel-figure:: vimc.dot
    :alt:   Diagram of the default media pipeline topology
    :align: center

    Media pipeline graph on vimc

Configuring the topology
~~~~~~~~~~~~~~~~~~~~~~~~

Each subdevice will come with its default configuration (pixelformat, height,
width, ...). One needs to configure the topology in order to match the
configuration on each linked subdevice to stream frames through the pipeline.
If the configuration doesn't match, the stream will fail. The ``v4l-utils``
package is a bundle of user-space applications, that comes with ``media-ctl`` and
``v4l2-ctl`` that can be used to configure the vimc configuration. This sequence
of commands fits for the default topology:

.. code-block:: bash

        media-ctl -d platform:vimc -V '"Sensor A":0[fmt:SBGGR8_1X8/640x480]'
        media-ctl -d platform:vimc -V '"Debayer A":0[fmt:SBGGR8_1X8/640x480]'
        media-ctl -d platform:vimc -V '"Scaler":0[fmt:RGB888_1X24/640x480]'
        media-ctl -d platform:vimc -V '"Scaler":0[crop:(100,50)/400x150]'
        media-ctl -d platform:vimc -V '"Scaler":1[fmt:RGB888_1X24/300x700]'
        v4l2-ctl -z platform:vimc -d "RGB/YUV Capture" -v width=300,height=700
        v4l2-ctl -z platform:vimc -d "Raw Capture 0" -v pixelformat=BA81

Subdevices
----------

Subdevices define the behavior of an entity in the topology. Depending on the
subdevice, the entity can have multiple pads of type source or sink.

vimc-sensor:
	Generates images in several formats using video test pattern generator.
	Exposes:

	* 1 Pad source

vimc-lens:
	Ancillary lens for a sensor. Supports auto focus control. Linked to
	a vimc-sensor using an ancillary link. The lens supports FOCUS_ABSOLUTE
	control.

.. code-block:: bash

	media-ctl -p
	...
	- entity 28: Lens A (0 pad, 0 link)
			type V4L2 subdev subtype Lens flags 0
			device node name /dev/v4l-subdev6
	- entity 29: Lens B (0 pad, 0 link)
			type V4L2 subdev subtype Lens flags 0
			device node name /dev/v4l-subdev7
	v4l2-ctl -d /dev/v4l-subdev7 -C focus_absolute
	focus_absolute: 0

vimc-debayer:
	Transforms images in bayer format into a non-bayer format.
	Exposes:

	* 1 Pad sink
	* 1 Pad source

vimc-scaler:
	Re-size the image to meet the source pad resolution. E.g.: if the sync
	pad is configured to 360x480 and the source to 1280x720, the image will
	be stretched to fit the source resolution. Works for any resolution
	within the vimc limitations (even shrinking the image if necessary).
	Exposes:

	* 1 Pad sink
	* 1 Pad source

vimc-capture:
	Exposes node /dev/videoX to allow userspace to capture the stream.
	Exposes:

	* 1 Pad sink
	* 1 Pad source

Module options
--------------

Vimc has a module parameter to configure the driver.

* ``allocator=<unsigned int>``

	memory allocator selection, default is 0. It specifies the way buffers
	will be allocated.

		- 0: vmalloc
		- 1: dma-contig


code:
.. SPDX-License-Identifier: GPL-2.0

The Virtual Stateless Decoder Driver (visl)
===========================================

A virtual stateless decoder device for stateless uAPI development
purposes.

This tool's objective is to help the development and testing of
userspace applications that use the V4L2 stateless API to decode media.

A userspace implementation can use visl to run a decoding loop even when
no hardware is available or when the kernel uAPI for the codec has not
been upstreamed yet. This can reveal bugs at an early stage.

This driver can also trace the contents of the V4L2 controls submitted
to it.  It can also dump the contents of the vb2 buffers through a
debugfs interface. This is in many ways similar to the tracing
infrastructure available for other popular encode/decode APIs out there
and can help develop a userspace application by using another (working)
one as a reference.

.. note::

        No actual decoding of video frames is performed by visl. The
        V4L2 test pattern generator is used to write various debug information
        to the capture buffers instead.

Module parameters
-----------------

- visl_debug: Activates debug info, printing various debug messages through
  dprintk. Also controls whether per-frame debug info is shown. Defaults to off.
  Note that enabling this feature can result in slow performance through serial.

- visl_transtime_ms: Simulated process time in milliseconds. Slowing down the
  decoding speed can be useful for debugging.

- visl_dprintk_frame_start, visl_dprintk_frame_nframes: Dictates a range of
  frames where dprintk is activated. This only controls the dprintk tracing on a
  per-frame basis. Note that printing a lot of data can be slow through serial.

- keep_bitstream_buffers: Controls whether bitstream (i.e. OUTPUT) buffers are
  kept after a decoding session. Defaults to false so as to reduce the amount of
  clutter. keep_bitstream_buffers == false works well when live debugging the
  client program with GDB.

- bitstream_trace_frame_start, bitstream_trace_nframes: Similar to
  visl_dprintk_frame_start, visl_dprintk_nframes, but controls the dumping of
  buffer data through debugfs instead.

What is the default use case for this driver?
---------------------------------------------

This driver can be used as a way to compare different userspace implementations.
This assumes that a working client is run against visl and that the ftrace and
OUTPUT buffer data is subsequently used to debug a work-in-progress
implementation.

Information on reference frames, their timestamps, the status of the OUTPUT and
CAPTURE queues and more can be read directly from the CAPTURE buffers.

Supported codecs
----------------

The following codecs are supported:

- FWHT
- MPEG2
- VP8
- VP9
- H.264
- HEVC

visl trace events
-----------------
The trace events are defined on a per-codec basis, e.g.:

.. code-block:: bash

        $ ls /sys/kernel/debug/tracing/events/ | grep visl
        visl_fwht_controls
        visl_h264_controls
        visl_hevc_controls
        visl_mpeg2_controls
        visl_vp8_controls
        visl_vp9_controls

For example, in order to dump HEVC SPS data:

.. code-block:: bash

        $ echo 1 >  /sys/kernel/debug/tracing/events/visl_hevc_controls/v4l2_ctrl_hevc_sps/enable

The SPS data will be dumped to the trace buffer, i.e.:

.. code-block:: bash

        $ cat /sys/kernel/debug/tracing/trace
        video_parameter_set_id 0
        seq_parameter_set_id 0
        pic_width_in_luma_samples 1920
        pic_height_in_luma_samples 1080
        bit_depth_luma_minus8 0
        bit_depth_chroma_minus8 0
        log2_max_pic_order_cnt_lsb_minus4 4
        sps_max_dec_pic_buffering_minus1 6
        sps_max_num_reorder_pics 2
        sps_max_latency_increase_plus1 0
        log2_min_luma_coding_block_size_minus3 0
        log2_diff_max_min_luma_coding_block_size 3
        log2_min_luma_transform_block_size_minus2 0
        log2_diff_max_min_luma_transform_block_size 3
        max_transform_hierarchy_depth_inter 2
        max_transform_hierarchy_depth_intra 2
        pcm_sample_bit_depth_luma_minus1 0
        pcm_sample_bit_depth_chroma_minus1 0
        log2_min_pcm_luma_coding_block_size_minus3 0
        log2_diff_max_min_pcm_luma_coding_block_size 0
        num_short_term_ref_pic_sets 0
        num_long_term_ref_pics_sps 0
        chroma_format_idc 1
        sps_max_sub_layers_minus1 0
        flags AMP_ENABLED|SAMPLE_ADAPTIVE_OFFSET|TEMPORAL_MVP_ENABLED|STRONG_INTRA_SMOOTHING_ENABLED

Dumping OUTPUT buffer data through debugfs
------------------------------------------

If the **VISL_DEBUGFS** Kconfig is enabled, visl will populate
**/sys/kernel/debug/visl/bitstream** with OUTPUT buffer data according to the
values of bitstream_trace_frame_start and bitstream_trace_nframes. This can
highlight errors as broken clients may fail to fill the buffers properly.

A single file is created for each processed OUTPUT buffer. Its name contains an
integer that denotes the buffer sequence, i.e.:

.. code-block:: c

	snprintf(name, 32, "bitstream%d", run->src->sequence);

Dumping the values is simply a matter of reading from the file, i.e.:

For the buffer with sequence == 0:

.. code-block:: bash

        $ xxd /sys/kernel/debug/visl/bitstream/bitstream0
        00000000: 2601 af04 d088 bc25 a173 0e41 a4f2 3274  &......%.s.A..2t
        00000010: c668 cb28 e775 b4ac f53a ba60 f8fd 3aa1  .h.(.u...:.`..:.
        00000020: 46b4 bcfc 506c e227 2372 e5f5 d7ea 579f  F...Pl.'#r....W.
        00000030: 6371 5eb5 0eb8 23b5 ca6a 5de5 983a 19e4  cq^...#..j]..:..
        00000040: e8c3 4320 b4ba a226 cbc1 4138 3a12 32d6  ..C ...&..A8:.2.
        00000050: fef3 247b 3523 4e90 9682 ac8e eb0c a389  ..${5#N.........
        00000060: ddd0 6cfc 0187 0e20 7aae b15b 1812 3d33  ..l.... z..[..=3
        00000070: e1c5 f425 a83a 00b7 4f18 8127 3c4c aefb  ...%.:..O..'<L..

For the buffer with sequence == 1:

.. code-block:: bash

        $ xxd /sys/kernel/debug/visl/bitstream/bitstream1
        00000000: 0201 d021 49e1 0c40 aa11 1449 14a6 01dc  ...!I..@...I....
        00000010: 7023 889a c8cd 2cd0 13b4 dab0 e8ca 21fe  p#....,.......!.
        00000020: c4c8 ab4c 486e 4e2f b0df 96cc c74e 8dde  ...LHnN/.....N..
        00000030: 8ce7 ee36 d880 4095 4d64 30a0 ff4f 0c5e  ...6..@.Md0..O.^
        00000040: f16b a6a1 d806 ca2a 0ece a673 7bea 1f37  .k.....*...s{..7
        00000050: 370f 5bb9 1dc4 ba21 6434 bc53 0173 cba0  7.[....!d4.S.s..
        00000060: dfe6 bc99 01ea b6e0 346b 92b5 c8de 9f5d  ........4k.....]
        00000070: e7cc 3484 1769 fef2 a693 a945 2c8b 31da  ..4..i.....E,.1.

And so on.

By default, the files are removed during STREAMOFF. This is to reduce the amount
of clutter.