korg/linux
0
0
Fork 0
mirror of https://mirrors.bfsu.edu.cn/git/linux.git synced 2024-11-11 12:28:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

media updates for v4.8-rc1

Browse Source 
-----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1
 
 iQIcBAABAgAGBQJXmLuzAAoJEAhfPr2O5OEVXyUP/jzXfbc5e72ECimqZQnJeK3a
 +MrJUrvp9W/7e99WUHwb2QoDYo/SDpXdbLbRjU0BTnPy47XS8J10MxsfE1eRnfds
 +TAhw96Hs3Wm3A5OxQfqPsZmq3AtGpU+HJ/zzulpY0bTqEzAtD8oUO9ZjT39Eshz
 xFbeIr6Kco6N6W4Ja998g4uBmvjN/24xOjSmuETja+gK2zztFPp70opefA2+crdY
 ChOgdUOj6cPDZlddExGf9oVrEMJhM9tn2ACrbFsD0sWPvix145JbVXgaOdGrt2Jc
 huRREv9tKte2/Os7IQ8wN33Jzca6RtdXg3twlauGIOjhYuaeVoaSCqQrRgKNjFl+
 CWTucHGnCP82bfmFvQxCWkhGKGGMzcNdQlnjKM7PrGPrSwW9+FNpLzs5XDX5S0gj
 UYkS/smbwzOOrfEcttFCMs5EGoAs+zOYzHtyCKp4EyWcznN5wRR8y3L3cdhmGAiG
 jAqTh/orjSOnnM2qQXqt574IiGTVvJqGEZyLAWC16HKbRaEFzL/+9Z79lkoxQfPn
 iLALAtTagFjxj/5ITxr5b2TzgWZ+GNFnyEpeC4DXqdESVfuZX00wiy0YEq1JFG+J
 RIj3VQpDqUwIs5KMqGQDG/S58iCfR83AIJBpSFIWaCHByvZ3thL8H4og20oZ8Akt
 TQXCqmzIvzn8QIZS/Pge
 =CN+v
 -----END PGP SIGNATURE-----

Merge tag 'media/v4.8-4' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media

Pull media documentation updates from Mauro Carvalho Chehab:
 "This patch series does the conversion of all media documentation stuff
  to Restrutured Text markup format and add them to the
  Documentation/index.rst file.

  The media documentation was grouped into 4 books:

    - media uAPI
    - media kAPI
    - V4L driver-specific documentation
    - DVB driver-specific documentation

  It also contains several documentation improvements and one fixup
  patch for a core issue with cropcap.

  PS.  After this patch series, the media DocBook is deprecated and
  should be removed.  I'll add such patch on a future pull request"

* tag 'media/v4.8-4' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (322 commits)
  [media] cx23885-cardlist.rst: add a new card
  [media] doc-rst: add some needed escape codes
  [media] doc-rst: kapi: use :c:func: instead of :cpp:func
  doc-rst: kernel-doc: fix a change introduced by mistake
  [media] v4l2-ioctl.h add debug info for struct v4l2_ioctl_ops
  [media] dvb_ringbuffer.h: some documentation improvements
  [media] v4l2-ctrls.h: fully document the header file
  [media] doc-rst: Fix some typedef ugly warnings
  [media] doc-rst: reorganize the kAPI v4l2 chapters
  [media] rename v4l2-framework.rst to v4l2-intro.rst
  [media] move V4L2 clocks to a separate .rst file
  [media] v4l2-fh.rst: add cross references and markups
  [media] v4l2-fh.rst: add fh contents from v4l2-framework.rst
  [media] v4l2-fh.h: add documentation for it
  [media] v4l2-event.rst: add cross-references and markups
  [media] v4l2-event.h: document all functions
  [media] v4l2-event.rst: add text from v4l2-framework.rst
  [media] v4l2-framework.rst: remove videobuf quick chapter
  [media] v4l2-dev: add cross-references and improve markup
  [media] doc-rst: move v4l2-dev doc to a separate file
  ...
This commit is contained in:
Linus Torvalds 2016-07-27 14:58:31 -07:00
commit ff9a082fda
619 changed files with 88280 additions and 10992 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
Documentation/DocBook/device-drivers.tmpl
View File

@ -247,64 +247,6 @@ X!Isound/sound_firmware.c
-->
</chapter>
<chapter id="mediadev">
<title>Media Devices</title>
<sect1><title>Video2Linux devices</title>
!Iinclude/media/tuner.h
!Iinclude/media/tuner-types.h
!Iinclude/media/tveeprom.h
!Iinclude/media/v4l2-async.h
!Iinclude/media/v4l2-ctrls.h
!Iinclude/media/v4l2-dv-timings.h
!Iinclude/media/v4l2-event.h
!Iinclude/media/v4l2-flash-led-class.h
!Iinclude/media/v4l2-mc.h
!Iinclude/media/v4l2-mediabus.h
!Iinclude/media/v4l2-mem2mem.h
!Iinclude/media/v4l2-of.h
!Iinclude/media/v4l2-rect.h
!Iinclude/media/v4l2-subdev.h
!Iinclude/media/videobuf2-core.h
!Iinclude/media/videobuf2-v4l2.h
!Iinclude/media/videobuf2-memops.h
</sect1>
<sect1><title>Digital TV (DVB) devices</title>
<sect1><title>Digital TV Common functions</title>
!Idrivers/media/dvb-core/dvb_math.h
!Idrivers/media/dvb-core/dvb_ringbuffer.h
!Idrivers/media/dvb-core/dvbdev.h
</sect1>
<sect1><title>Digital TV Frontend kABI</title>
!Pdrivers/media/dvb-core/dvb_frontend.h Digital TV Frontend
!Idrivers/media/dvb-core/dvb_frontend.h
</sect1>
<sect1><title>Digital TV Demux kABI</title>
!Pdrivers/media/dvb-core/demux.h Digital TV Demux
<sect1><title>Demux Callback API</title>
!Pdrivers/media/dvb-core/demux.h Demux Callback
</sect1>
!Idrivers/media/dvb-core/demux.h
</sect1>
<sect1><title>Digital TV Conditional Access kABI</title>
!Idrivers/media/dvb-core/dvb_ca_en50221.h
</sect1>
</sect1>
<sect1><title>Remote Controller devices</title>
!Iinclude/media/rc-core.h
!Iinclude/media/lirc_dev.h
</sect1>
<sect1><title>Media Controller devices</title>
!Pinclude/media/media-device.h Media Controller
!Iinclude/media/media-device.h
!Iinclude/media/media-devnode.h
!Iinclude/media/media-entity.h
</sect1>
<sect1><title>Consumer Electronics Control devices</title>
!Iinclude/media/cec-edid.h
</sect1>
</chapter>
<chapter id="uart16x50">
<title>16x50 UART Driver</title>

2
Documentation/DocBook/media/v4l/fdl-appendix.xml
View File

@ -526,7 +526,7 @@
<para>
You may extract a single document from such a collection, and
dispbibute it individually under this License, provided you
distribute it individually under this License, provided you
insert a copy of this License into the extracted document, and
follow this License in all other respects regarding verbatim
copying of that document.

2
Documentation/DocBook/media/v4l/lirc_device_interface.xml
View File

@ -114,7 +114,7 @@ on working with the default settings initially.</para>
<para>Some receiver have maximum resolution which is defined by internal
sample rate or data format limitations. E.g. it's common that signals can
only be reported in 50 microsecond steps. This integer value is used by
lircd to automatically adjust the aeps tolerance value in the lircd
lircd to automatically adjust the steps tolerance value in the lircd
config file.</para>
</listitem>
</varlistentry>

3
Documentation/Makefile.sphinx
View File

@ -38,9 +38,10 @@ ALLSPHINXOPTS = -D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) -d $(B
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
quiet_cmd_sphinx = SPHINX $@
cmd_sphinx = $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2
cmd_sphinx = BUILDDIR=$(BUILDDIR) $(SPHINXBUILD) -b $2 $(ALLSPHINXOPTS) $(BUILDDIR)/$2
htmldocs:
$(MAKE) BUILDDIR=$(BUILDDIR) -f $(srctree)/Documentation/media/Makefile $@
$(call cmd,sphinx,html)
pdfdocs:

13
Documentation/conf.py
View File

@ -28,7 +28,7 @@ sys.path.insert(0, os.path.abspath('sphinx'))
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['kernel-doc', 'rstFlatTable']
extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include']
# Gracefully handle missing rst2pdf.
try:
@ -176,7 +176,14 @@ except ImportError:
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path = ['_static']
html_static_path = ['sphinx-static']
html_context = {
'css_files': [
'_static/theme_overrides.css',
],
}
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
@ -404,7 +411,7 @@ epub_exclude_files = ['search.html']
# multiple PDF files here actually tries to get the cross-referencing right
# *between* PDF files.
pdf_documents = [
('index', u'Kernel', u'Kernel', u'J. Random Bozo'),
('kernel-documentation', u'Kernel', u'Kernel', u'J. Random Bozo'),
]
# kernel-doc extension configuration for running Sphinx directly (e.g. by Read

232
Documentation/dvb/README.dvb-usb
View File

@ -1,232 +0,0 @@
Documentation for dvb-usb-framework module and its devices
Idea behind the dvb-usb-framework
=================================
In March 2005 I got the new Twinhan USB2.0 DVB-T device. They provided specs and a firmware.
Quite keen I wanted to put the driver (with some quirks of course) into dibusb.
After reading some specs and doing some USB snooping, it realized, that the
dibusb-driver would be a complete mess afterwards. So I decided to do it in a
different way: With the help of a dvb-usb-framework.
The framework provides generic functions (mostly kernel API calls), such as:
- Transport Stream URB handling in conjunction with dvb-demux-feed-control
(bulk and isoc are supported)
- registering the device for the DVB-API
- registering an I2C-adapter if applicable
- remote-control/input-device handling
- firmware requesting and loading (currently just for the Cypress USB
controllers)
- other functions/methods which can be shared by several drivers (such as
functions for bulk-control-commands)
- TODO: a I2C-chunker. It creates device-specific chunks of register-accesses
depending on length of a register and the number of values that can be
multi-written and multi-read.
The source code of the particular DVB USB devices does just the communication
with the device via the bus. The connection between the DVB-API-functionality
is done via callbacks, assigned in a static device-description (struct
dvb_usb_device) each device-driver has to have.
For an example have a look in drivers/media/usb/dvb-usb/vp7045*.
Objective is to migrate all the usb-devices (dibusb, cinergyT2, maybe the
ttusb; flexcop-usb already benefits from the generic flexcop-device) to use
the dvb-usb-lib.
TODO: dynamic enabling and disabling of the pid-filter in regard to number of
feeds requested.
Supported devices
========================
See the LinuxTV DVB Wiki at www.linuxtv.org for a complete list of
cards/drivers/firmwares:
https://linuxtv.org/wiki/index.php/DVB_USB
0. History & News:
2005-06-30 - added support for WideView WT-220U (Thanks to Steve Chang)
2005-05-30 - added basic isochronous support to the dvb-usb-framework
added support for Conexant Hybrid reference design and Nebula DigiTV USB
2005-04-17 - all dibusb devices ported to make use of the dvb-usb-framework
2005-04-02 - re-enabled and improved remote control code.
2005-03-31 - ported the Yakumo/Hama/Typhoon DVB-T USB2.0 device to dvb-usb.
2005-03-30 - first commit of the dvb-usb-module based on the dibusb-source. First device is a new driver for the
TwinhanDTV Alpha / MagicBox II USB2.0-only DVB-T device.
(change from dvb-dibusb to dvb-usb)
2005-03-28 - added support for the AVerMedia AverTV DVB-T USB2.0 device (Thanks to Glen Harris and Jiun-Kuei Jung, AVerMedia)
2005-03-14 - added support for the Typhoon/Yakumo/HAMA DVB-T mobile USB2.0
2005-02-11 - added support for the KWorld/ADSTech Instant DVB-T USB2.0. Thanks a lot to Joachim von Caron
2005-02-02 - added support for the Hauppauge Win-TV Nova-T USB2
2005-01-31 - distorted streaming is gone for USB1.1 devices
2005-01-13 - moved the mirrored pid_filter_table back to dvb-dibusb
- first almost working version for HanfTek UMT-010
- found out, that Yakumo/HAMA/Typhoon are predecessors of the HanfTek UMT-010
2005-01-10 - refactoring completed, now everything is very delightful
- tuner quirks for some weird devices (Artec T1 AN2235 device has sometimes a
Panasonic Tuner assembled). Tunerprobing implemented. Thanks a lot to Gunnar Wittich.
2004-12-29 - after several days of struggling around bug of no returning URBs fixed.
2004-12-26 - refactored the dibusb-driver, splitted into separate files
- i2c-probing enabled
2004-12-06 - possibility for demod i2c-address probing
- new usb IDs (Compro, Artec)
2004-11-23 - merged changes from DiB3000MC_ver2.1
- revised the debugging
- possibility to deliver the complete TS for USB2.0
2004-11-21 - first working version of the dib3000mc/p frontend driver.
2004-11-12 - added additional remote control keys. Thanks to Uwe Hanke.
2004-11-07 - added remote control support. Thanks to David Matthews.
2004-11-05 - added support for a new devices (Grandtec/Avermedia/Artec)
- merged my changes (for dib3000mb/dibusb) to the FE_REFACTORING, because it became HEAD
- moved transfer control (pid filter, fifo control) from usb driver to frontend, it seems
better settled there (added xfer_ops-struct)
- created a common files for frontends (mc/p/mb)
2004-09-28 - added support for a new device (Unknown, vendor ID is Hyper-Paltek)
2004-09-20 - added support for a new device (Compro DVB-U2000), thanks
to Amaury Demol for reporting
- changed usb TS transfer method (several urbs, stopping transfer
before setting a new pid)
2004-09-13 - added support for a new device (Artec T1 USB TVBOX), thanks
to Christian Motschke for reporting
2004-09-05 - released the dibusb device and dib3000mb-frontend driver
(old news for vp7041.c)
2004-07-15 - found out, by accident, that the device has a TUA6010XS for
PLL
2004-07-12 - figured out, that the driver should also work with the
CTS Portable (Chinese Television System)
2004-07-08 - firmware-extraction-2.422-problem solved, driver is now working
properly with firmware extracted from 2.422
- #if for 2.6.4 (dvb), compile issue
- changed firmware handling, see vp7041.txt sec 1.1
2004-07-02 - some tuner modifications, v0.1, cleanups, first public
2004-06-28 - now using the dvb_dmx_swfilter_packets, everything
runs fine now
2004-06-27 - able to watch and switching channels (pre-alpha)
- no section filtering yet
2004-06-06 - first TS received, but kernel oops :/
2004-05-14 - firmware loader is working
2004-05-11 - start writing the driver
1. How to use?
1.1. Firmware
Most of the USB drivers need to download a firmware to the device before start
working.
Have a look at the Wikipage for the DVB-USB-drivers to find out, which firmware
you need for your device:
https://linuxtv.org/wiki/index.php/DVB_USB
1.2. Compiling
Since the driver is in the linux kernel, activating the driver in
your favorite config-environment should sufficient. I recommend
to compile the driver as module. Hotplug does the rest.
If you use dvb-kernel enter the build-2.6 directory run 'make' and 'insmod.sh
load' afterwards.
1.3. Loading the drivers
Hotplug is able to load the driver, when it is needed (because you plugged
in the device).
If you want to enable debug output, you have to load the driver manually and
from within the dvb-kernel cvs repository.
first have a look, which debug level are available:
modinfo dvb-usb
modinfo dvb-usb-vp7045
etc.
modprobe dvb-usb debug=<level>
modprobe dvb-usb-vp7045 debug=<level>
etc.
should do the trick.
When the driver is loaded successfully, the firmware file was in
the right place and the device is connected, the "Power"-LED should be
turned on.
At this point you should be able to start a dvb-capable application. I'm use
(t|s)zap, mplayer and dvbscan to test the basics. VDR-xine provides the
long-term test scenario.
2. Known problems and bugs
- Don't remove the USB device while running an DVB application, your system
will go crazy or die most likely.
2.1. Adding support for devices
TODO
2.2. USB1.1 Bandwidth limitation
A lot of the currently supported devices are USB1.1 and thus they have a
maximum bandwidth of about 5-6 MBit/s when connected to a USB2.0 hub.
This is not enough for receiving the complete transport stream of a
DVB-T channel (which is about 16 MBit/s). Normally this is not a
problem, if you only want to watch TV (this does not apply for HDTV),
but watching a channel while recording another channel on the same
frequency simply does not work very well. This applies to all USB1.1
DVB-T devices, not just the dvb-usb-devices)
The bug, where the TS is distorted by a heavy usage of the device is gone
definitely. All dvb-usb-devices I was using (Twinhan, Kworld, DiBcom) are
working like charm now with VDR. Sometimes I even was able to record a channel
and watch another one.
2.3. Comments
Patches, comments and suggestions are very very welcome.
3. Acknowledgements
Amaury Demol (Amaury.Demol@parrot.com) and Francois Kanounnikoff from DiBcom for
providing specs, code and help, on which the dvb-dibusb, dib3000mb and
dib3000mc are based.
David Matthews for identifying a new device type (Artec T1 with AN2235)
and for extending dibusb with remote control event handling. Thank you.
Alex Woods for frequently answering question about usb and dvb
stuff, a big thank you.
Bernd Wagner for helping with huge bug reports and discussions.
Gunnar Wittich and Joachim von Caron for their trust for providing
root-shells on their machines to implement support for new devices.
Allan Third and Michael Hutchinson for their help to write the Nebula
digitv-driver.
Glen Harris for bringing up, that there is a new dibusb-device and Jiun-Kuei
Jung from AVerMedia who kindly provided a special firmware to get the device
up and running in Linux.
Jennifer Chen, Jeff and Jack from Twinhan for kindly supporting by
writing the vp7045-driver.
Steve Chang from WideView for providing information for new devices and
firmware files.
Michael Paxton for submitting remote control keymaps.
Some guys on the linux-dvb mailing list for encouraging me.
Peter Schildmann >peter.schildmann-nospam-at-web.de< for his
user-level firmware loader, which saves a lot of time
(when writing the vp7041 driver)
Ulf Hermenau for helping me out with traditional chinese.
André Smoktun and Christian Frömmel for supporting me with
hardware and listening to my problems very patiently.

301
Documentation/dvb/avermedia.txt
View File

@ -1,301 +0,0 @@
HOWTO: Get An Avermedia DVB-T working under Linux
______________________________________________
Table of Contents
Assumptions and Introduction
The Avermedia DVB-T
Getting the card going
Receiving DVB-T in Australia
Known Limitations
Further Update
Assumptions and Introduction
It is assumed that the reader understands the basic structure
of the Linux Kernel DVB drivers and the general principles of
Digital TV.
One significant difference between Digital TV and Analogue TV
that the unwary (like myself) should consider is that,
although the component structure of budget DVB-T cards are
substantially similar to Analogue TV cards, they function in
substantially different ways.
The purpose of an Analogue TV is to receive and display an
Analogue Television signal. An Analogue TV signal (otherwise
known as composite video) is an analogue encoding of a
sequence of image frames (25 per second) rasterised using an
interlacing technique. Interlacing takes two fields to
represent one frame. Computers today are at their best when
dealing with digital signals, not analogue signals and a
composite video signal is about as far removed from a digital
data stream as you can get. Therefore, an Analogue TV card for
a PC has the following purpose:
* Tune the receiver to receive a broadcast signal
* demodulate the broadcast signal
* demultiplex the analogue video signal and analogue audio
signal (note some countries employ a digital audio signal
embedded within the modulated composite analogue signal -
NICAM.)
* digitize the analogue video signal and make the resulting
datastream available to the data bus.
The digital datastream from an Analogue TV card is generated
by circuitry on the card and is often presented uncompressed.
For a PAL TV signal encoded at a resolution of 768x576 24-bit
color pixels over 25 frames per second - a fair amount of data
is generated and must be processed by the PC before it can be
displayed on the video monitor screen. Some Analogue TV cards
for PCs have onboard MPEG2 encoders which permit the raw
digital data stream to be presented to the PC in an encoded
and compressed form - similar to the form that is used in
Digital TV.
The purpose of a simple budget digital TV card (DVB-T,C or S)
is to simply:
* Tune the received to receive a broadcast signal.
* Extract the encoded digital datastream from the broadcast
signal.
* Make the encoded digital datastream (MPEG2) available to
the data bus.
The significant difference between the two is that the tuner
on the analogue TV card spits out an Analogue signal, whereas
the tuner on the digital TV card spits out a compressed
encoded digital datastream. As the signal is already
digitised, it is trivial to pass this datastream to the PC
databus with minimal additional processing and then extract
the digital video and audio datastreams passing them to the
appropriate software or hardware for decoding and viewing.
_________________________________________________________
The Avermedia DVB-T
The Avermedia DVB-T is a budget PCI DVB card. It has 3 inputs:
* RF Tuner Input
* Composite Video Input (RCA Jack)
* SVIDEO Input (Mini-DIN)
The RF Tuner Input is the input to the tuner module of the
card. The Tuner is otherwise known as the "Frontend" . The
Frontend of the Avermedia DVB-T is a Microtune 7202D. A timely
post to the linux-dvb mailing list ascertained that the
Microtune 7202D is supported by the sp887x driver which is
found in the dvb-hw CVS module.
The DVB-T card is based around the BT878 chip which is a very
common multimedia bridge and often found on Analogue TV cards.
There is no on-board MPEG2 decoder, which means that all MPEG2
decoding must be done in software, or if you have one, on an
MPEG2 hardware decoding card or chipset.
_________________________________________________________
Getting the card going
In order to fire up the card, it is necessary to load a number
of modules from the DVB driver set. Prior to this it will have
been necessary to download these drivers from the linuxtv CVS
server and compile them successfully.
Depending on the card's feature set, the Device Driver API for
DVB under Linux will expose some of the following device files
in the /dev tree:
* /dev/dvb/adapter0/audio0
* /dev/dvb/adapter0/ca0
* /dev/dvb/adapter0/demux0
* /dev/dvb/adapter0/dvr0
* /dev/dvb/adapter0/frontend0
* /dev/dvb/adapter0/net0
* /dev/dvb/adapter0/osd0
* /dev/dvb/adapter0/video0
The primary device nodes that we are interested in (at this
stage) for the Avermedia DVB-T are:
* /dev/dvb/adapter0/dvr0
* /dev/dvb/adapter0/frontend0
The dvr0 device node is used to read the MPEG2 Data Stream and
the frontend0 node is used to tune the frontend tuner module.
At this stage, it has not been able to ascertain the
functionality of the remaining device nodes in respect of the
Avermedia DVBT. However, full functionality in respect of
tuning, receiving and supplying the MPEG2 data stream is
possible with the currently available versions of the driver.
It may be possible that additional functionality is available
from the card (i.e. viewing the additional analogue inputs
that the card presents), but this has not been tested yet. If
I get around to this, I'll update the document with whatever I
find.
To power up the card, load the following modules in the
following order:
* modprobe bttv (normally loaded automatically)
* modprobe dvb-bt8xx (or place dvb-bt8xx in /etc/modules)
Insertion of these modules into the running kernel will
activate the appropriate DVB device nodes. It is then possible
to start accessing the card with utilities such as scan, tzap,
dvbstream etc.
The frontend module sp887x.o, requires an external firmware.
Please use the command "get_dvb_firmware sp887x" to download
it. Then copy it to /usr/lib/hotplug/firmware or /lib/firmware/
(depending on configuration of firmware hotplug).
Receiving DVB-T in Australia
I have no experience of DVB-T in other countries other than
Australia, so I will attempt to explain how it works here in
Melbourne and how this affects the configuration of the DVB-T
card.
The Digital Broadcasting Australia website has a Reception
locatortool which provides information on transponder channels
and frequencies. My local transmitter happens to be Mount
Dandenong.
The frequencies broadcast by Mount Dandenong are:
Table 1. Transponder Frequencies Mount Dandenong, Vic, Aus.
Broadcaster Channel Frequency
ABC VHF 12 226.5 MHz
TEN VHF 11 219.5 MHz
NINE VHF 8 191.625 MHz
SEVEN VHF 6 177.5 MHz
SBS UHF 29 536.5 MHz
The Scan utility has a set of compiled-in defaults for various
countries and regions, but if they do not suit, or if you have
a pre-compiled scan binary, you can specify a data file on the
command line which contains the transponder frequencies. Here
is a sample file for the above channel transponders:
# Data file for DVB scan program
#
# C Frequency SymbolRate FEC QAM
# S Frequency Polarisation SymbolRate FEC
# T Frequency Bandwidth FEC FEC2 QAM Mode Guard Hier
T 226500000 7MHz 2/3 NONE QAM64 8k 1/8 NONE
T 191625000 7MHz 2/3 NONE QAM64 8k 1/8 NONE
T 219500000 7MHz 2/3 NONE QAM64 8k 1/8 NONE
T 177500000 7MHz 2/3 NONE QAM64 8k 1/8 NONE
T 536500000 7MHz 2/3 NONE QAM64 8k 1/8 NONE
The defaults for the transponder frequency and other
modulation parameters were obtained from www.dba.org.au.
When Scan runs, it will output channels.conf information for
any channel's transponders which the card's frontend can lock
onto. (i.e. any whose signal is strong enough at your
antenna).
Here's my channels.conf file for anyone who's interested:
ABC HDTV:226500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_4:QAM_64
:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:2307:0:560
ABC TV Melbourne:226500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_
4:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:65
0:561
ABC TV 2:226500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_4:QAM_64
:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:562
ABC TV 3:226500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_4:QAM_64
:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:563
ABC TV 4:226500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_4:QAM_64
:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:564
ABC DiG Radio:226500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_4:Q
AM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:0:2311:56
6
TEN Digital:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM
_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:158
5
TEN Digital 1:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:Q
AM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:1
586
TEN Digital 2:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:Q
AM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:1
587
TEN Digital 3:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:Q
AM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:1
588
TEN Digital:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM
_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:158
9
TEN Digital 4:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:Q
AM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:1
590
TEN Digital:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM
_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:159
1
TEN HD:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:T
RANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:514:0:1592
TEN Digital:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM
_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:159
3
Nine Digital:191625000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QA
M_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:513:660:10
72
Nine Digital HD:191625000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2
:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:0:1
073
Nine Guide:191625000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_
64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:514:670:1074
7 Digital:177500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_6
4:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:769:770:1328
7 Digital 1:177500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM
_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:769:770:1329
7 Digital 2:177500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM
_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:769:770:1330
7 Digital 3:177500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM
_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:769:770:1331
7 HD Digital:177500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QA
M_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:833:834:133
2
7 Program Guide:177500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3
:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:865:866:
1334
SBS HD:536500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:T
RANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:102:103:784
SBS DIGITAL 1:536500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:Q
AM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:161:81:785
SBS DIGITAL 2:536500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:Q
AM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:162:83:786
SBS EPG:536500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:
TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:163:85:787
SBS RADIO 1:536500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM
_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:0:201:798
SBS RADIO 2:536500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM
_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:0:202:799
_________________________________________________________
Known Limitations
At present I can say with confidence that the frontend tunes
via /dev/dvb/adapter{x}/frontend0 and supplies an MPEG2 stream
via /dev/dvb/adapter{x}/dvr0. I have not tested the
functionality of any other part of the card yet. I will do so
over time and update this document.
There are some limitations in the i2c layer due to a returned
error message inconsistency. Although this generates errors in
dmesg and the system logs, it does not appear to affect the
ability of the frontend to function correctly.
_________________________________________________________
Further Update
dvbstream and VideoLAN Client on windows works a treat with
DVB, in fact this is currently serving as my main way of
viewing DVB-T at the moment. Additionally, VLC is happily
decoding HDTV signals, although the PC is dropping the odd
frame here and there - I assume due to processing capability -
as all the decoding is being done under windows in software.
Many thanks to Nigel Pearson for the updates to this document
since the recent revision of the driver.
February 14th 2006

98
Documentation/dvb/bt8xx.txt
View File

@ -1,98 +0,0 @@
How to get the bt8xx cards working
==================================
1) General information
======================
This class of cards has a bt878a as the PCI interface, and require the bttv driver
for accessing the i2c bus and the gpio pins of the bt8xx chipset.
Please see Documentation/dvb/cards.txt => o Cards based on the Conexant Bt8xx PCI bridge:
Compiling kernel please enable:
a.)"Device drivers" => "Multimedia devices" => "Video For Linux" => "Enable Video for Linux API 1 (DEPRECATED)"
b.)"Device drivers" => "Multimedia devices" => "Video For Linux" => "Video Capture Adapters" => "BT848 Video For Linux"
c.)"Device drivers" => "Multimedia devices" => "Digital Video Broadcasting Devices" => "DVB for Linux" "DVB Core Support" "Bt8xx based PCI Cards"
Please use the following options with care as deselection of drivers which are in fact necessary
may result in DVB devices that cannot be tuned due to lack of driver support:
You can save RAM by deselecting every frontend module that your DVB card does not need.
First please remove the static dependency of DVB card drivers on all frontend modules for all possible card variants by enabling:
d.) "Device drivers" => "Multimedia devices" => "Digital Video Broadcasting Devices"
=> "DVB for Linux" "DVB Core Support" "Load and attach frontend modules as needed"
If you know the frontend driver that your card needs please enable:
e.)"Device drivers" => "Multimedia devices" => "Digital Video Broadcasting Devices"
=> "DVB for Linux" "DVB Core Support" "Customise DVB Frontends" => "Customise the frontend modules to build"
Then please select your card-specific frontend module.
2) Loading Modules
==================
Regular case: If the bttv driver detects a bt8xx-based DVB card, all frontend and backend modules will be loaded automatically.
Exceptions are:
- Old TwinHan DST cards or clones with or without CA slot and not containing an Eeprom.
People running udev please see Documentation/dvb/udev.txt.
In the following cases overriding the PCI type detection for dvb-bt8xx might be necessary:
2a) Running TwinHan and Clones
------------------------------
$ modprobe bttv card=113
$ modprobe dst
Useful parameters for verbosity level and debugging the dst module:
verbose=0: messages are disabled
1: only error messages are displayed
2: notifications are displayed
3: other useful messages are displayed
4: debug setting
dst_addons=0: card is a free to air (FTA) card only
0x20: card has a conditional access slot for scrambled channels
The autodetected values are determined by the cards' "response string".
In your logs see f. ex.: dst_get_device_id: Recognize [DSTMCI].
For bug reports please send in a complete log with verbose=4 activated.
Please also see Documentation/dvb/ci.txt.
2b) Running multiple cards
--------------------------
Examples of card ID's:
Pinnacle PCTV Sat: 94
Nebula Electronics Digi TV: 104
pcHDTV HD-2000 TV: 112
Twinhan DST and clones: 113
Avermedia AverTV DVB-T 771: 123
Avermedia AverTV DVB-T 761: 124
DViCO FusionHDTV DVB-T Lite: 128
DViCO FusionHDTV 5 Lite: 135
Notice: The order of the card ID should be uprising:
Example:
$ modprobe bttv card=113 card=135
For a full list of card ID's please see Documentation/video4linux/CARDLIST.bttv.
In case of further problems please subscribe and send questions to the mailing list: linux-dvb@linuxtv.org.
2c) Probing the cards with broken PCI subsystem ID
--------------------------------------------------
There are some TwinHan cards that the EEPROM has become corrupted for some
reason. The cards do not have correct PCI subsystem ID. But we can force
probing the cards with broken PCI subsystem ID
$ echo 109e 0878 $subvendor $subdevice > \
/sys/bus/pci/drivers/bt878/new_id
109e: PCI_VENDOR_ID_BROOKTREE
0878: PCI_DEVICE_ID_BROOKTREE_878
Authors: Richard Walker,
Jamie Honan,
Michael Hunold,
Manu Abraham,
Uwe Bugla,
Michael Krufky

96
Documentation/dvb/contributors.txt
View File

@ -1,96 +0,0 @@
Thanks go to the following people for patches and contributions:
Michael Hunold <m.hunold@gmx.de>
for the initial saa7146 driver and its recent overhaul
Christian Theiss
for his work on the initial Linux DVB driver
Marcus Metzler <mocm@metzlerbros.de>
Ralph Metzler <rjkm@metzlerbros.de>
for their continuing work on the DVB driver
Michael Holzt <kju@debian.org>
for his contributions to the dvb-net driver
Diego Picciani <d.picciani@novacomp.it>
for CyberLogin for Linux which allows logging onto EON
(in case you are wondering where CyberLogin is, EON changed its login
procedure and CyberLogin is no longer used.)
Martin Schaller <martin@smurf.franken.de>
for patching the cable card decoder driver
Klaus Schmidinger <Klaus.Schmidinger@cadsoft.de>
for various fixes regarding tuning, OSD and CI stuff and his work on VDR
Steve Brown <sbrown@cortland.com>
for his AFC kernel thread
Christoph Martin <martin@uni-mainz.de>
for his LIRC infrared handler
Andreas Oberritter <obi@linuxtv.org>
Dennis Noermann <dennis.noermann@noernet.de>
Felix Domke <tmbinc@elitedvb.net>
Florian Schirmer <jolt@tuxbox.org>
Ronny Strutz <3des@elitedvb.de>
Wolfram Joost <dbox2@frokaschwei.de>
...and all the other dbox2 people
for many bugfixes in the generic DVB Core, frontend drivers and
their work on the dbox2 port of the DVB driver
Oliver Endriss <o.endriss@gmx.de>
for many bugfixes
Andrew de Quincey <adq_dvb@lidskialf.net>
for the tda1004x frontend driver, and various bugfixes
Peter Schildmann <peter.schildmann@web.de>
for the driver for the Technisat SkyStar2 PCI DVB card
Vadim Catana <skystar@moldova.cc>
Roberto Ragusa <r.ragusa@libero.it>
Augusto Cardoso <augusto@carhil.net>
for all the work for the FlexCopII chipset by B2C2,Inc.
Davor Emard <emard@softhome.net>
for his work on the budget drivers, the demux code,
the module unloading problems, ...
Hans-Frieder Vogt <hfvogt@arcor.de>
for his work on calculating and checking the crc's for the
TechnoTrend/Hauppauge DEC driver firmware
Michael Dreher <michael@5dot1.de>
Andreas 'randy' Weinberger
for the support of the Fujitsu-Siemens Activy budget DVB-S
Kenneth Aafløy <ke-aa@frisurf.no>
for adding support for Typhoon DVB-S budget card
Ernst Peinlich <e.peinlich@inode.at>
for tuning/DiSEqC support for the DEC 3000-s
Peter Beutner <p.beutner@gmx.net>
for the IR code for the ttusb-dec driver
Wilson Michaels <wilsonmichaels@earthlink.net>
for the lgdt330x frontend driver, and various bugfixes
Michael Krufky <mkrufky@linuxtv.org>
for maintaining v4l/dvb inter-tree dependencies
Taylor Jacob <rtjacob@earthlink.net>
for the nxt2002 frontend driver
Jean-Francois Thibert <jeanfrancois@sagetv.com>
for the nxt2004 frontend driver
Kirk Lapray <kirk.lapray@gmail.com>
for the or51211 and or51132 frontend drivers, and
for merging the nxt2002 and nxt2004 modules into a
single nxt200x frontend driver.
(If you think you should be in this list, but you are not, drop a
line to the DVB mailing list)

62
Documentation/dvb/readme.txt
View File

@ -1,62 +0,0 @@
Linux Digital Video Broadcast (DVB) subsystem
=============================================
The main development site and CVS repository for these
drivers is https://linuxtv.org.
The developer mailing list linux-dvb is also hosted there,
see https://linuxtv.org/lists.php. Please check
the archive https://linuxtv.org/pipermail/linux-dvb/
and the Wiki https://linuxtv.org/wiki/
before asking newbie questions on the list.
API documentation, utilities and test/example programs
are available as part of the old driver package for Linux 2.4
(linuxtv-dvb-1.0.x.tar.gz), or from CVS (module DVB).
We plan to split this into separate packages, but it's not
been done yet.
https://linuxtv.org/downloads/
What's inside this directory:
"avermedia.txt"
contains detailed information about the
Avermedia DVB-T cards. See also "bt8xx.txt".
"bt8xx.txt"
contains detailed information about the
various bt8xx based "budget" DVB cards.
"cards.txt"
contains a list of supported hardware.
"ci.txt"
contains detailed information about the
CI module as part from TwinHan cards and Clones.
"contributors.txt"
is the who-is-who of DVB development.
"faq.txt"
contains frequently asked questions and their answers.
"get_dvb_firmware"
script to download and extract firmware for those devices
that require it.
"ttusb-dec.txt"
contains detailed information about the
TT DEC2000/DEC3000 USB DVB hardware.
"udev.txt"
how to get DVB and udev up and running.
"README.dvb-usb"
contains detailed information about the DVB USB cards.
"README.flexcop"
contains detailed information about the
Technisat- and Flexcop B2C2 drivers.
Good luck and have fun!

78
Documentation/dvb/technisat.txt
View File

@ -1,78 +0,0 @@
How to set up the Technisat/B2C2 Flexcop devices
================================================
1) 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:
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)...
2) 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:
2a) Main module part:
"Multimedia support" => "DVB/ATSC adapters"
=> "Technisat/B2C2 FlexcopII(b) and FlexCopIII adapters"
a.) => "Technisat/B2C2 Air/Sky/Cable2PC PCI" (PCI card) or
b.) => "Technisat/B2C2 Air/Sky/Cable2PC USB" (USB 1.1 adapter)
and for troubleshooting purposes:
c.) => "Enable debug for the B2C2 FlexCop drivers"
2b) Frontend / Tuner / Demodulator module part:
"Multimedia support" => "DVB/ATSC adapters"
=> "Customise the frontend modules to build" "Customise DVB frontends" =>
1.) SkyStar DVB-S Revision 2.3:
a.) => "Zarlink VP310/MT312/ZL10313 based"
b.) => "Generic I2C PLL based tuners"
2.) SkyStar DVB-S Revision 2.6:
a.) => "ST STV0299 based"
b.) => "Generic I2C PLL based tuners"
3.) SkyStar DVB-S Revision 2.7:
a.) => "Samsung S5H1420 based"
b.) => "Integrant ITD1000 Zero IF tuner for DVB-S/DSS"
c.) => "ISL6421 SEC controller"
4.) SkyStar DVB-S Revision 2.8:
a.) => "Conexant CX24123 based"
b.) => "Conexant CX24113/CX24128 tuner for DVB-S/DSS"
c.) => "ISL6421 SEC controller"
5.) AirStar DVB-T card:
a.) => "Zarlink MT352 based"
b.) => "Generic I2C PLL based tuners"
6.) CableStar DVB-C card:
a.) => "ST STV0297 based"
b.) => "Generic I2C PLL based tuners"
7.) AirStar ATSC card 1st generation:
a.) => "Broadcom BCM3510"
8.) AirStar ATSC card 2nd generation:
a.) => "NxtWave Communications NXT2002/NXT2004 based"
b.) => "Generic I2C PLL based tuners"
9.) AirStar ATSC card 3rd generation:
a.) => "LG Electronics LGDT3302/LGDT3303 based"
b.) "Multimedia support" => "Customise analog and hybrid tuner modules to build"
=> "Simple tuner support"
Author: Uwe Bugla <uwe.bugla@gmx.de> August 2009

45
Documentation/dvb/ttusb-dec.txt
View File

@ -1,45 +0,0 @@
TechnoTrend/Hauppauge DEC USB Driver
====================================
Driver Status
-------------
Supported:
DEC2000-t
DEC2450-t
DEC3000-s
Linux Kernels 2.4 and 2.6
Video Streaming
Audio Streaming
Section Filters
Channel Zapping
Hotplug firmware loader under 2.6 kernels
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:
"get_dvb_firmware dec2000t"
"get_dvb_firmware dec2540t"
"get_dvb_firmware dec3000s"
Compilation Notes for 2.4 kernels
---------------------------------
For 2.4 kernels the firmware for the DECs is compiled into the driver itself.
Copy the three files downloaded above into the build-2.4 directory.
Hotplug Firmware Loading for 2.6 kernels
----------------------------------------
For 2.6 kernels the firmware is loaded at the point that the driver module is
loaded. See linux/Documentation/dvb/firmware.txt for more information.
Copy the three files downloaded above into the /usr/lib/hotplug/firmware or
/lib/firmware directory (depending on configuration of firmware hotplug).

4
Documentation/index.rst
View File

@ -14,6 +14,10 @@ Contents:
:maxdepth: 2
kernel-documentation
media/media_uapi
media/media_kapi
media/dvb-drivers/index
media/v4l-drivers/index
Indices and tables
==================

60
Documentation/media/Makefile Normal file
View File

@ -0,0 +1,60 @@
# Generate the *.h.rst files from uAPI headers
PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl
UAPI = $(srctree)/include/uapi/linux
KAPI = $(srctree)/include/linux
SRC_DIR=$(srctree)/Documentation/media
FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \
videodev2.h.rst media.h.rst cec.h.rst lirc.h.rst
TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
htmldocs: $(BUILDDIR) ${TARGETS}
$(BUILDDIR):
$(Q)mkdir -p $@
# Rule to convert a .h file to inline RST documentation
gen_rst = \
echo ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions; \
${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions
quiet_gen_rst = echo ' PARSE $(patsubst $(srctree)/%,%,$<)'; \
${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions
silent_gen_rst = ${gen_rst}
$(BUILDDIR)/audio.h.rst: ${UAPI}/dvb/audio.h ${PARSER} $(SRC_DIR)/audio.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/ca.h.rst: ${UAPI}/dvb/ca.h ${PARSER} $(SRC_DIR)/ca.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/dmx.h.rst: ${UAPI}/dvb/dmx.h ${PARSER} $(SRC_DIR)/dmx.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/frontend.h.rst: ${UAPI}/dvb/frontend.h ${PARSER} $(SRC_DIR)/frontend.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/net.h.rst: ${UAPI}/dvb/net.h ${PARSER} $(SRC_DIR)/net.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/video.h.rst: ${UAPI}/dvb/video.h ${PARSER} $(SRC_DIR)/video.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/videodev2.h.rst: ${UAPI}/videodev2.h ${PARSER} $(SRC_DIR)/videodev2.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/media.h.rst: ${UAPI}/media.h ${PARSER} $(SRC_DIR)/media.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/cec.h.rst: ${KAPI}/cec.h ${PARSER} $(SRC_DIR)/cec.h.rst.exceptions
@$($(quiet)gen_rst)
$(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exceptions
@$($(quiet)gen_rst)
cleandocs:
-rm ${TARGETS}

20
Documentation/media/audio.h.rst.exceptions Normal file
View File

@ -0,0 +1,20 @@
# Ignore header name
ignore define _DVBAUDIO_H_
# Typedef pointing to structs
replace typedef audio_karaoke_t audio-karaoke
# Undocumented audio caps, as this is a deprecated API anyway
ignore define AUDIO_CAP_DTS
ignore define AUDIO_CAP_LPCM
ignore define AUDIO_CAP_MP1
ignore define AUDIO_CAP_MP2
ignore define AUDIO_CAP_MP3
ignore define AUDIO_CAP_AAC
ignore define AUDIO_CAP_OGG
ignore define AUDIO_CAP_SDDS
ignore define AUDIO_CAP_AC3
# some typedefs should point to struct/enums
replace typedef audio_mixer_t audio-mixer
replace typedef audio_status_t audio-status

24
Documentation/media/ca.h.rst.exceptions Normal file
View File

@ -0,0 +1,24 @@
# Ignore header name
ignore define _DVBCA_H_
# struct ca_slot_info defines
replace define CA_CI ca-slot-info
replace define CA_CI_LINK ca-slot-info
replace define CA_CI_PHYS ca-slot-info
replace define CA_DESCR ca-slot-info
replace define CA_SC ca-slot-info
replace define CA_CI_MODULE_PRESENT ca-slot-info
replace define CA_CI_MODULE_READY ca-slot-info
# struct ca_descr_info defines
replace define CA_ECD ca-descr-info
replace define CA_NDS ca-descr-info
replace define CA_DSS ca-descr-info
# some typedefs should point to struct/enums
replace typedef ca_pid_t ca-pid
replace typedef ca_slot_info_t ca-slot-info
replace typedef ca_descr_info_t ca-descr-info
replace typedef ca_caps_t ca-caps
replace typedef ca_msg_t ca-msg
replace typedef ca_descr_t ca-descr

492
Documentation/media/cec.h.rst.exceptions Normal file
View File

@ -0,0 +1,492 @@
# Ignore header name
ignore define _CEC_UAPI_H
# Rename some symbols, to avoid namespace conflicts
replace struct cec_event_state_change cec-event-state-change_s
replace struct cec_event_lost_msgs cec-event-lost-msgs_s
replace enum cec_mode_initiator cec-mode-initiator_e
replace enum cec_mode_follower cec-mode-follower_e
# define macros to ignore
ignore define CEC_MAX_MSG_SIZE
ignore define CEC_MAX_LOG_ADDRS
ignore define CEC_LOG_ADDR_MASK_TV
ignore define CEC_LOG_ADDR_MASK_RECORD
ignore define CEC_LOG_ADDR_MASK_TUNER
ignore define CEC_LOG_ADDR_MASK_PLAYBACK
ignore define CEC_LOG_ADDR_MASK_AUDIOSYSTEM
ignore define CEC_LOG_ADDR_MASK_BACKUP
ignore define CEC_LOG_ADDR_MASK_SPECIFIC
ignore define CEC_LOG_ADDR_MASK_UNREGISTERED
# Shouldn't them be documented?
ignore define CEC_LOG_ADDR_INVALID
ignore define CEC_PHYS_ADDR_INVALID
ignore define CEC_VENDOR_ID_NONE
ignore define CEC_MODE_INITIATOR_MSK
ignore define CEC_MODE_FOLLOWER_MSK
ignore define CEC_EVENT_FL_INITIAL_STATE
# Part of CEC 2.0 spec - shouldn't be documented too?
ignore define CEC_LOG_ADDR_TV
ignore define CEC_LOG_ADDR_RECORD_1
ignore define CEC_LOG_ADDR_RECORD_2
ignore define CEC_LOG_ADDR_TUNER_1
ignore define CEC_LOG_ADDR_PLAYBACK_1
ignore define CEC_LOG_ADDR_AUDIOSYSTEM
ignore define CEC_LOG_ADDR_TUNER_2
ignore define CEC_LOG_ADDR_TUNER_3
ignore define CEC_LOG_ADDR_PLAYBACK_2
ignore define CEC_LOG_ADDR_RECORD_3
ignore define CEC_LOG_ADDR_TUNER_4
ignore define CEC_LOG_ADDR_PLAYBACK_3
ignore define CEC_LOG_ADDR_BACKUP_1
ignore define CEC_LOG_ADDR_BACKUP_2
ignore define CEC_LOG_ADDR_SPECIFIC
ignore define CEC_LOG_ADDR_UNREGISTERED
ignore define CEC_LOG_ADDR_BROADCAST
# IMHO, those should also be documented
ignore define CEC_MSG_ACTIVE_SOURCE
ignore define CEC_MSG_IMAGE_VIEW_ON
ignore define CEC_MSG_TEXT_VIEW_ON
ignore define CEC_MSG_INACTIVE_SOURCE
ignore define CEC_MSG_REQUEST_ACTIVE_SOURCE
ignore define CEC_MSG_ROUTING_CHANGE
ignore define CEC_MSG_ROUTING_INFORMATION
ignore define CEC_MSG_SET_STREAM_PATH
ignore define CEC_MSG_STANDBY
ignore define CEC_MSG_RECORD_OFF
ignore define CEC_MSG_RECORD_ON
ignore define CEC_OP_RECORD_SRC_OWN
ignore define CEC_OP_RECORD_SRC_DIGITAL
ignore define CEC_OP_RECORD_SRC_ANALOG
ignore define CEC_OP_RECORD_SRC_EXT_PLUG
ignore define CEC_OP_RECORD_SRC_EXT_PHYS_ADDR
ignore define CEC_OP_SERVICE_ID_METHOD_BY_DIG_ID
ignore define CEC_OP_SERVICE_ID_METHOD_BY_CHANNEL
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_GEN
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_GEN
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_GEN
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_BS
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_CS
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_T
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_CABLE
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_SAT
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_T
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_C
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_S
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_S2
ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_T
ignore define CEC_OP_ANA_BCAST_TYPE_CABLE
ignore define CEC_OP_ANA_BCAST_TYPE_SATELLITE
ignore define CEC_OP_ANA_BCAST_TYPE_TERRESTRIAL
ignore define CEC_OP_BCAST_SYSTEM_PAL_BG
ignore define CEC_OP_BCAST_SYSTEM_SECAM_LQ
ignore define CEC_OP_BCAST_SYSTEM_PAL_M
ignore define CEC_OP_BCAST_SYSTEM_NTSC_M
ignore define CEC_OP_BCAST_SYSTEM_PAL_I
ignore define CEC_OP_BCAST_SYSTEM_SECAM_DK
ignore define CEC_OP_BCAST_SYSTEM_SECAM_BG
ignore define CEC_OP_BCAST_SYSTEM_SECAM_L
ignore define CEC_OP_BCAST_SYSTEM_PAL_DK
ignore define CEC_OP_BCAST_SYSTEM_OTHER
ignore define CEC_OP_CHANNEL_NUMBER_FMT_1_PART
ignore define CEC_OP_CHANNEL_NUMBER_FMT_2_PART
ignore define CEC_MSG_RECORD_STATUS
ignore define CEC_OP_RECORD_STATUS_CUR_SRC
ignore define CEC_OP_RECORD_STATUS_DIG_SERVICE
ignore define CEC_OP_RECORD_STATUS_ANA_SERVICE
ignore define CEC_OP_RECORD_STATUS_EXT_INPUT
ignore define CEC_OP_RECORD_STATUS_NO_DIG_SERVICE
ignore define CEC_OP_RECORD_STATUS_NO_ANA_SERVICE
ignore define CEC_OP_RECORD_STATUS_NO_SERVICE
ignore define CEC_OP_RECORD_STATUS_INVALID_EXT_PLUG
ignore define CEC_OP_RECORD_STATUS_INVALID_EXT_PHYS_ADDR
ignore define CEC_OP_RECORD_STATUS_UNSUP_CA
ignore define CEC_OP_RECORD_STATUS_NO_CA_ENTITLEMENTS
ignore define CEC_OP_RECORD_STATUS_CANT_COPY_SRC
ignore define CEC_OP_RECORD_STATUS_NO_MORE_COPIES
ignore define CEC_OP_RECORD_STATUS_NO_MEDIA
ignore define CEC_OP_RECORD_STATUS_PLAYING
ignore define CEC_OP_RECORD_STATUS_ALREADY_RECORDING
ignore define CEC_OP_RECORD_STATUS_MEDIA_PROT
ignore define CEC_OP_RECORD_STATUS_NO_SIGNAL
ignore define CEC_OP_RECORD_STATUS_MEDIA_PROBLEM
ignore define CEC_OP_RECORD_STATUS_NO_SPACE
ignore define CEC_OP_RECORD_STATUS_PARENTAL_LOCK
ignore define CEC_OP_RECORD_STATUS_TERMINATED_OK
ignore define CEC_OP_RECORD_STATUS_ALREADY_TERM
ignore define CEC_OP_RECORD_STATUS_OTHER
ignore define CEC_MSG_RECORD_TV_SCREEN
ignore define CEC_MSG_CLEAR_ANALOGUE_TIMER
ignore define CEC_OP_REC_SEQ_SUNDAY
ignore define CEC_OP_REC_SEQ_MONDAY
ignore define CEC_OP_REC_SEQ_TUESDAY
ignore define CEC_OP_REC_SEQ_WEDNESDAY
ignore define CEC_OP_REC_SEQ_THURSDAY
ignore define CEC_OP_REC_SEQ_FRIDAY
ignore define CEC_OP_REC_SEQ_SATERDAY
ignore define CEC_OP_REC_SEQ_ONCE_ONLY
ignore define CEC_MSG_CLEAR_DIGITAL_TIMER
ignore define CEC_MSG_CLEAR_EXT_TIMER
ignore define CEC_OP_EXT_SRC_PLUG
ignore define CEC_OP_EXT_SRC_PHYS_ADDR
ignore define CEC_MSG_SET_ANALOGUE_TIMER
ignore define CEC_MSG_SET_DIGITAL_TIMER
ignore define CEC_MSG_SET_EXT_TIMER
ignore define CEC_MSG_SET_TIMER_PROGRAM_TITLE
ignore define CEC_MSG_TIMER_CLEARED_STATUS
ignore define CEC_OP_TIMER_CLR_STAT_RECORDING
ignore define CEC_OP_TIMER_CLR_STAT_NO_MATCHING
ignore define CEC_OP_TIMER_CLR_STAT_NO_INFO
ignore define CEC_OP_TIMER_CLR_STAT_CLEARED
ignore define CEC_MSG_TIMER_STATUS
ignore define CEC_OP_TIMER_OVERLAP_WARNING_NO_OVERLAP
ignore define CEC_OP_TIMER_OVERLAP_WARNING_OVERLAP
ignore define CEC_OP_MEDIA_INFO_UNPROT_MEDIA
ignore define CEC_OP_MEDIA_INFO_PROT_MEDIA
ignore define CEC_OP_MEDIA_INFO_NO_MEDIA
ignore define CEC_OP_PROG_IND_NOT_PROGRAMMED
ignore define CEC_OP_PROG_IND_PROGRAMMED
ignore define CEC_OP_PROG_INFO_ENOUGH_SPACE
ignore define CEC_OP_PROG_INFO_NOT_ENOUGH_SPACE
ignore define CEC_OP_PROG_INFO_MIGHT_NOT_BE_ENOUGH_SPACE
ignore define CEC_OP_PROG_INFO_NONE_AVAILABLE
ignore define CEC_OP_PROG_ERROR_NO_FREE_TIMER
ignore define CEC_OP_PROG_ERROR_DATE_OUT_OF_RANGE
ignore define CEC_OP_PROG_ERROR_REC_SEQ_ERROR
ignore define CEC_OP_PROG_ERROR_INV_EXT_PLUG
ignore define CEC_OP_PROG_ERROR_INV_EXT_PHYS_ADDR
ignore define CEC_OP_PROG_ERROR_CA_UNSUPP
ignore define CEC_OP_PROG_ERROR_INSUF_CA_ENTITLEMENTS
ignore define CEC_OP_PROG_ERROR_RESOLUTION_UNSUPP
ignore define CEC_OP_PROG_ERROR_PARENTAL_LOCK
ignore define CEC_OP_PROG_ERROR_CLOCK_FAILURE
ignore define CEC_OP_PROG_ERROR_DUPLICATE
ignore define CEC_MSG_CEC_VERSION
ignore define CEC_OP_CEC_VERSION_1_3A
ignore define CEC_OP_CEC_VERSION_1_4
ignore define CEC_OP_CEC_VERSION_2_0
ignore define CEC_MSG_GET_CEC_VERSION
ignore define CEC_MSG_GIVE_PHYSICAL_ADDR
ignore define CEC_MSG_GET_MENU_LANGUAGE
ignore define CEC_MSG_REPORT_PHYSICAL_ADDR
ignore define CEC_OP_PRIM_DEVTYPE_TV
ignore define CEC_OP_PRIM_DEVTYPE_RECORD
ignore define CEC_OP_PRIM_DEVTYPE_TUNER
ignore define CEC_OP_PRIM_DEVTYPE_PLAYBACK
ignore define CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM
ignore define CEC_OP_PRIM_DEVTYPE_SWITCH
ignore define CEC_OP_PRIM_DEVTYPE_PROCESSOR
ignore define CEC_MSG_SET_MENU_LANGUAGE
ignore define CEC_MSG_REPORT_FEATURES
ignore define CEC_OP_ALL_DEVTYPE_TV
ignore define CEC_OP_ALL_DEVTYPE_RECORD
ignore define CEC_OP_ALL_DEVTYPE_TUNER
ignore define CEC_OP_ALL_DEVTYPE_PLAYBACK
ignore define CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM
ignore define CEC_OP_ALL_DEVTYPE_SWITCH
ignore define CEC_OP_FEAT_EXT
ignore define CEC_OP_FEAT_RC_TV_PROFILE_NONE
ignore define CEC_OP_FEAT_RC_TV_PROFILE_1
ignore define CEC_OP_FEAT_RC_TV_PROFILE_2
ignore define CEC_OP_FEAT_RC_TV_PROFILE_3
ignore define CEC_OP_FEAT_RC_TV_PROFILE_4
ignore define CEC_OP_FEAT_RC_SRC_HAS_DEV_ROOT_MENU
ignore define CEC_OP_FEAT_RC_SRC_HAS_DEV_SETUP_MENU
ignore define CEC_OP_FEAT_RC_SRC_HAS_CONTENTS_MENU
ignore define CEC_OP_FEAT_RC_SRC_HAS_MEDIA_TOP_MENU
ignore define CEC_OP_FEAT_RC_SRC_HAS_MEDIA_CONTEXT_MENU
ignore define CEC_OP_FEAT_DEV_HAS_RECORD_TV_SCREEN
ignore define CEC_OP_FEAT_DEV_HAS_SET_OSD_STRING
ignore define CEC_OP_FEAT_DEV_HAS_DECK_CONTROL
ignore define CEC_OP_FEAT_DEV_HAS_SET_AUDIO_RATE
ignore define CEC_OP_FEAT_DEV_SINK_HAS_ARC_TX
ignore define CEC_OP_FEAT_DEV_SOURCE_HAS_ARC_RX
ignore define CEC_MSG_GIVE_FEATURES
ignore define CEC_MSG_DECK_CONTROL
ignore define CEC_OP_DECK_CTL_MODE_SKIP_FWD
ignore define CEC_OP_DECK_CTL_MODE_SKIP_REV
ignore define CEC_OP_DECK_CTL_MODE_STOP
ignore define CEC_OP_DECK_CTL_MODE_EJECT
ignore define CEC_MSG_DECK_STATUS
ignore define CEC_OP_DECK_INFO_PLAY
ignore define CEC_OP_DECK_INFO_RECORD
ignore define CEC_OP_DECK_INFO_PLAY_REV
ignore define CEC_OP_DECK_INFO_STILL
ignore define CEC_OP_DECK_INFO_SLOW
ignore define CEC_OP_DECK_INFO_SLOW_REV
ignore define CEC_OP_DECK_INFO_FAST_FWD
ignore define CEC_OP_DECK_INFO_FAST_REV
ignore define CEC_OP_DECK_INFO_NO_MEDIA
ignore define CEC_OP_DECK_INFO_STOP
ignore define CEC_OP_DECK_INFO_SKIP_FWD
ignore define CEC_OP_DECK_INFO_SKIP_REV
ignore define CEC_OP_DECK_INFO_INDEX_SEARCH_FWD
ignore define CEC_OP_DECK_INFO_INDEX_SEARCH_REV
ignore define CEC_OP_DECK_INFO_OTHER
ignore define CEC_MSG_GIVE_DECK_STATUS
ignore define CEC_OP_STATUS_REQ_ON
ignore define CEC_OP_STATUS_REQ_OFF
ignore define CEC_OP_STATUS_REQ_ONCE
ignore define CEC_MSG_PLAY
ignore define CEC_OP_PLAY_MODE_PLAY_FWD
ignore define CEC_OP_PLAY_MODE_PLAY_REV
ignore define CEC_OP_PLAY_MODE_PLAY_STILL
ignore define CEC_OP_PLAY_MODE_PLAY_FAST_FWD_MIN
ignore define CEC_OP_PLAY_MODE_PLAY_FAST_FWD_MED
ignore define CEC_OP_PLAY_MODE_PLAY_FAST_FWD_MAX
ignore define CEC_OP_PLAY_MODE_PLAY_FAST_REV_MIN
ignore define CEC_OP_PLAY_MODE_PLAY_FAST_REV_MED
ignore define CEC_OP_PLAY_MODE_PLAY_FAST_REV_MAX
ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_FWD_MIN
ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_FWD_MED
ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_FWD_MAX
ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_REV_MIN
ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_REV_MED
ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_REV_MAX
ignore define CEC_MSG_GIVE_TUNER_DEVICE_STATUS
ignore define CEC_MSG_SELECT_ANALOGUE_SERVICE
ignore define CEC_MSG_SELECT_DIGITAL_SERVICE
ignore define CEC_MSG_TUNER_DEVICE_STATUS
ignore define CEC_OP_REC_FLAG_USED
ignore define CEC_OP_REC_FLAG_NOT_USED
ignore define CEC_OP_TUNER_DISPLAY_INFO_DIGITAL
ignore define CEC_OP_TUNER_DISPLAY_INFO_NONE
ignore define CEC_OP_TUNER_DISPLAY_INFO_ANALOGUE
ignore define CEC_MSG_TUNER_STEP_DECREMENT
ignore define CEC_MSG_TUNER_STEP_INCREMENT
ignore define CEC_MSG_DEVICE_VENDOR_ID
ignore define CEC_MSG_GIVE_DEVICE_VENDOR_ID
ignore define CEC_MSG_VENDOR_COMMAND
ignore define CEC_MSG_VENDOR_COMMAND_WITH_ID
ignore define CEC_MSG_VENDOR_REMOTE_BUTTON_DOWN
ignore define CEC_MSG_VENDOR_REMOTE_BUTTON_UP
ignore define CEC_MSG_SET_OSD_STRING
ignore define CEC_OP_DISP_CTL_DEFAULT
ignore define CEC_OP_DISP_CTL_UNTIL_CLEARED
ignore define CEC_OP_DISP_CTL_CLEAR
ignore define CEC_MSG_GIVE_OSD_NAME
ignore define CEC_MSG_SET_OSD_NAME
ignore define CEC_MSG_MENU_REQUEST
ignore define CEC_OP_MENU_REQUEST_ACTIVATE
ignore define CEC_OP_MENU_REQUEST_DEACTIVATE
ignore define CEC_OP_MENU_REQUEST_QUERY
ignore define CEC_MSG_MENU_STATUS
ignore define CEC_OP_MENU_STATE_ACTIVATED
ignore define CEC_OP_MENU_STATE_DEACTIVATED
ignore define CEC_MSG_USER_CONTROL_PRESSED
ignore define CEC_OP_UI_BCAST_TYPE_TOGGLE_ALL
ignore define CEC_OP_UI_BCAST_TYPE_TOGGLE_DIG_ANA
ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE
ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE_T
ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE_CABLE
ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE_SAT
ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL
ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_T
ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_CABLE
ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_SAT
ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_COM_SAT
ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_COM_SAT2
ignore define CEC_OP_UI_BCAST_TYPE_IP
ignore define CEC_OP_UI_SND_PRES_CTL_DUAL_MONO
ignore define CEC_OP_UI_SND_PRES_CTL_KARAOKE
ignore define CEC_OP_UI_SND_PRES_CTL_DOWNMIX
ignore define CEC_OP_UI_SND_PRES_CTL_REVERB
ignore define CEC_OP_UI_SND_PRES_CTL_EQUALIZER
ignore define CEC_OP_UI_SND_PRES_CTL_BASS_UP
ignore define CEC_OP_UI_SND_PRES_CTL_BASS_NEUTRAL
ignore define CEC_OP_UI_SND_PRES_CTL_BASS_DOWN
ignore define CEC_OP_UI_SND_PRES_CTL_TREBLE_UP
ignore define CEC_OP_UI_SND_PRES_CTL_TREBLE_NEUTRAL
ignore define CEC_OP_UI_SND_PRES_CTL_TREBLE_DOWN
ignore define CEC_MSG_USER_CONTROL_RELEASED
ignore define CEC_MSG_GIVE_DEVICE_POWER_STATUS
ignore define CEC_MSG_REPORT_POWER_STATUS
ignore define CEC_OP_POWER_STATUS_ON
ignore define CEC_OP_POWER_STATUS_STANDBY
ignore define CEC_OP_POWER_STATUS_TO_ON
ignore define CEC_OP_POWER_STATUS_TO_STANDBY
ignore define CEC_MSG_FEATURE_ABORT
ignore define CEC_OP_ABORT_UNRECOGNIZED_OP
ignore define CEC_OP_ABORT_INCORRECT_MODE
ignore define CEC_OP_ABORT_NO_SOURCE
ignore define CEC_OP_ABORT_INVALID_OP
ignore define CEC_OP_ABORT_REFUSED
ignore define CEC_OP_ABORT_UNDETERMINED
ignore define CEC_MSG_ABORT
ignore define CEC_MSG_GIVE_AUDIO_STATUS
ignore define CEC_MSG_GIVE_SYSTEM_AUDIO_MODE_STATUS
ignore define CEC_MSG_REPORT_AUDIO_STATUS
ignore define CEC_OP_AUD_MUTE_STATUS_OFF
ignore define CEC_OP_AUD_MUTE_STATUS_ON
ignore define CEC_MSG_REPORT_SHORT_AUDIO_DESCRIPTOR
ignore define CEC_MSG_REQUEST_SHORT_AUDIO_DESCRIPTOR
ignore define CEC_MSG_SET_SYSTEM_AUDIO_MODE
ignore define CEC_OP_SYS_AUD_STATUS_OFF
ignore define CEC_OP_SYS_AUD_STATUS_ON
ignore define CEC_MSG_SYSTEM_AUDIO_MODE_REQUEST
ignore define CEC_MSG_SYSTEM_AUDIO_MODE_STATUS
ignore define CEC_OP_AUD_FMT_ID_CEA861
ignore define CEC_OP_AUD_FMT_ID_CEA861_CXT
ignore define CEC_MSG_SET_AUDIO_RATE
ignore define CEC_OP_AUD_RATE_OFF
ignore define CEC_OP_AUD_RATE_WIDE_STD
ignore define CEC_OP_AUD_RATE_WIDE_FAST
ignore define CEC_OP_AUD_RATE_WIDE_SLOW
ignore define CEC_OP_AUD_RATE_NARROW_STD
ignore define CEC_OP_AUD_RATE_NARROW_FAST
ignore define CEC_OP_AUD_RATE_NARROW_SLOW
ignore define CEC_MSG_INITIATE_ARC
ignore define CEC_MSG_REPORT_ARC_INITIATED
ignore define CEC_MSG_REPORT_ARC_TERMINATED
ignore define CEC_MSG_REQUEST_ARC_INITIATION
ignore define CEC_MSG_REQUEST_ARC_TERMINATION
ignore define CEC_MSG_TERMINATE_ARC
ignore define CEC_MSG_REQUEST_CURRENT_LATENCY
ignore define CEC_MSG_REPORT_CURRENT_LATENCY
ignore define CEC_OP_LOW_LATENCY_MODE_OFF
ignore define CEC_OP_LOW_LATENCY_MODE_ON
ignore define CEC_OP_AUD_OUT_COMPENSATED_NA
ignore define CEC_OP_AUD_OUT_COMPENSATED_DELAY
ignore define CEC_OP_AUD_OUT_COMPENSATED_NO_DELAY
ignore define CEC_OP_AUD_OUT_COMPENSATED_PARTIAL_DELAY
ignore define CEC_MSG_CDC_MESSAGE
ignore define CEC_MSG_CDC_HEC_INQUIRE_STATE
ignore define CEC_MSG_CDC_HEC_REPORT_STATE
ignore define CEC_OP_HEC_FUNC_STATE_NOT_SUPPORTED
ignore define CEC_OP_HEC_FUNC_STATE_INACTIVE
ignore define CEC_OP_HEC_FUNC_STATE_ACTIVE
ignore define CEC_OP_HEC_FUNC_STATE_ACTIVATION_FIELD
ignore define CEC_OP_HOST_FUNC_STATE_NOT_SUPPORTED
ignore define CEC_OP_HOST_FUNC_STATE_INACTIVE
ignore define CEC_OP_HOST_FUNC_STATE_ACTIVE
ignore define CEC_OP_ENC_FUNC_STATE_EXT_CON_NOT_SUPPORTED
ignore define CEC_OP_ENC_FUNC_STATE_EXT_CON_INACTIVE
ignore define CEC_OP_ENC_FUNC_STATE_EXT_CON_ACTIVE
ignore define CEC_OP_CDC_ERROR_CODE_NONE
ignore define CEC_OP_CDC_ERROR_CODE_CAP_UNSUPPORTED
ignore define CEC_OP_CDC_ERROR_CODE_WRONG_STATE
ignore define CEC_OP_CDC_ERROR_CODE_OTHER
ignore define CEC_OP_HEC_SUPPORT_NO
ignore define CEC_OP_HEC_SUPPORT_YES
ignore define CEC_OP_HEC_ACTIVATION_ON
ignore define CEC_OP_HEC_ACTIVATION_OFF
ignore define CEC_MSG_CDC_HEC_SET_STATE_ADJACENT
ignore define CEC_MSG_CDC_HEC_SET_STATE
ignore define CEC_OP_HEC_SET_STATE_DEACTIVATE
ignore define CEC_OP_HEC_SET_STATE_ACTIVATE
ignore define CEC_MSG_CDC_HEC_REQUEST_DEACTIVATION
ignore define CEC_MSG_CDC_HEC_NOTIFY_ALIVE
ignore define CEC_MSG_CDC_HEC_DISCOVER
ignore define CEC_MSG_CDC_HPD_SET_STATE
ignore define CEC_OP_HPD_STATE_CP_EDID_DISABLE
ignore define CEC_OP_HPD_STATE_CP_EDID_ENABLE
ignore define CEC_OP_HPD_STATE_CP_EDID_DISABLE_ENABLE
ignore define CEC_OP_HPD_STATE_EDID_DISABLE
ignore define CEC_OP_HPD_STATE_EDID_ENABLE
ignore define CEC_OP_HPD_STATE_EDID_DISABLE_ENABLE
ignore define CEC_MSG_CDC_HPD_REPORT_STATE
ignore define CEC_OP_HPD_ERROR_NONE
ignore define CEC_OP_HPD_ERROR_INITIATOR_NOT_CAPABLE
ignore define CEC_OP_HPD_ERROR_INITIATOR_WRONG_STATE
ignore define CEC_OP_HPD_ERROR_OTHER
ignore define CEC_OP_HPD_ERROR_NONE_NO_VIDEO

63
Documentation/media/dmx.h.rst.exceptions Normal file
View File

@ -0,0 +1,63 @@
# Ignore header name
ignore define _UAPI_DVBDMX_H_
# Ignore limit constants
ignore define DMX_FILTER_SIZE
# dmx-pes-type-t enum symbols
replace enum dmx_ts_pes dmx-pes-type-t
replace symbol DMX_PES_AUDIO0 dmx-pes-type-t
replace symbol DMX_PES_VIDEO0 dmx-pes-type-t
replace symbol DMX_PES_TELETEXT0 dmx-pes-type-t
replace symbol DMX_PES_SUBTITLE0 dmx-pes-type-t
replace symbol DMX_PES_PCR0 dmx-pes-type-t
replace symbol DMX_PES_AUDIO1 dmx-pes-type-t
replace symbol DMX_PES_VIDEO1 dmx-pes-type-t
replace symbol DMX_PES_TELETEXT1 dmx-pes-type-t
replace symbol DMX_PES_SUBTITLE1 dmx-pes-type-t
replace symbol DMX_PES_PCR1 dmx-pes-type-t
replace symbol DMX_PES_AUDIO2 dmx-pes-type-t
replace symbol DMX_PES_VIDEO2 dmx-pes-type-t
replace symbol DMX_PES_TELETEXT2 dmx-pes-type-t
replace symbol DMX_PES_SUBTITLE2 dmx-pes-type-t
replace symbol DMX_PES_PCR2 dmx-pes-type-t
replace symbol DMX_PES_AUDIO3 dmx-pes-type-t
replace symbol DMX_PES_VIDEO3 dmx-pes-type-t
replace symbol DMX_PES_TELETEXT3 dmx-pes-type-t
replace symbol DMX_PES_SUBTITLE3 dmx-pes-type-t
replace symbol DMX_PES_PCR3 dmx-pes-type-t
replace symbol DMX_PES_OTHER dmx-pes-type-t
# Ignore obsolete symbols
ignore define DMX_PES_AUDIO
ignore define DMX_PES_VIDEO
ignore define DMX_PES_TELETEXT
ignore define DMX_PES_SUBTITLE
ignore define DMX_PES_PCR
# dmx_input_t symbols
replace enum dmx_input dmx-input-t
replace symbol DMX_IN_FRONTEND dmx-input-t
replace symbol DMX_IN_DVR dmx-input-t
# dmx_source_t symbols
replace enum dmx_source dmx-source-t
replace symbol DMX_SOURCE_FRONT0 dmx-source-t
replace symbol DMX_SOURCE_FRONT1 dmx-source-t
replace symbol DMX_SOURCE_FRONT2 dmx-source-t
replace symbol DMX_SOURCE_FRONT3 dmx-source-t
replace symbol DMX_SOURCE_DVR0 dmx-source-t
replace symbol DMX_SOURCE_DVR1 dmx-source-t
replace symbol DMX_SOURCE_DVR2 dmx-source-t
replace symbol DMX_SOURCE_DVR3 dmx-source-t
# Flags for struct dmx_sct_filter_params
replace define DMX_CHECK_CRC dmx-sct-filter-params
replace define DMX_ONESHOT dmx-sct-filter-params
replace define DMX_IMMEDIATE_START dmx-sct-filter-params
replace define DMX_KERNEL_CLIENT dmx-sct-filter-params
# some typedefs should point to struct/enums
replace typedef dmx_caps_t dmx-caps
replace typedef dmx_filter_t dmx-filter

267
Documentation/media/dvb-drivers/avermedia.rst Normal file
View File

@ -0,0 +1,267 @@
HOWTO: Get An Avermedia DVB-T working under Linux
-------------------------------------------------
February 14th 2006
.. note::
This documentation is outdated. Please check at the DVB wiki
at https://linuxtv.org/wiki for more updated info.
There's a section there specific for Avermedia boards at:
https://linuxtv.org/wiki/index.php/AVerMedia
Assumptions and Introduction
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is assumed that the reader understands the basic structure
of the Linux Kernel DVB drivers and the general principles of
Digital TV.
One significant difference between Digital TV and Analogue TV
that the unwary (like myself) should consider is that,
although the component structure of budget DVB-T cards are
substantially similar to Analogue TV cards, they function in
substantially different ways.
The purpose of an Analogue TV is to receive and display an
Analogue Television signal. An Analogue TV signal (otherwise
known as composite video) is an analogue encoding of a
sequence of image frames (25 per second) rasterised using an
interlacing technique. Interlacing takes two fields to
represent one frame. Computers today are at their best when
dealing with digital signals, not analogue signals and a
composite video signal is about as far removed from a digital
data stream as you can get. Therefore, an Analogue TV card for
a PC has the following purpose:
* Tune the receiver to receive a broadcast signal
* demodulate the broadcast signal
* demultiplex the analogue video signal and analogue audio
signal. **NOTE:** some countries employ a digital audio signal
embedded within the modulated composite analogue signal -
NICAM.)
* digitize the analogue video signal and make the resulting
datastream available to the data bus.
The digital datastream from an Analogue TV card is generated
by circuitry on the card and is often presented uncompressed.
For a PAL TV signal encoded at a resolution of 768x576 24-bit
color pixels over 25 frames per second - a fair amount of data
is generated and must be processed by the PC before it can be
displayed on the video monitor screen. Some Analogue TV cards
for PCs have onboard MPEG2 encoders which permit the raw
digital data stream to be presented to the PC in an encoded
and compressed form - similar to the form that is used in
Digital TV.
The purpose of a simple budget digital TV card (DVB-T,C or S)
is to simply:
* Tune the received to receive a broadcast signal.
* Extract the encoded digital datastream from the broadcast
signal.
* Make the encoded digital datastream (MPEG2) available to
the data bus.
The significant difference between the two is that the tuner
on the analogue TV card spits out an Analogue signal, whereas
the tuner on the digital TV card spits out a compressed
encoded digital datastream. As the signal is already
digitised, it is trivial to pass this datastream to the PC
databus with minimal additional processing and then extract
the digital video and audio datastreams passing them to the
appropriate software or hardware for decoding and viewing.
The Avermedia DVB-T
~~~~~~~~~~~~~~~~~~~
The Avermedia DVB-T is a budget PCI DVB card. It has 3 inputs:
* RF Tuner Input
* Composite Video Input (RCA Jack)
* SVIDEO Input (Mini-DIN)
The RF Tuner Input is the input to the tuner module of the
card. The Tuner is otherwise known as the "Frontend" . The
Frontend of the Avermedia DVB-T is a Microtune 7202D. A timely
post to the linux-dvb mailing list ascertained that the
Microtune 7202D is supported by the sp887x driver which is
found in the dvb-hw CVS module.
The DVB-T card is based around the BT878 chip which is a very
common multimedia bridge and often found on Analogue TV cards.
There is no on-board MPEG2 decoder, which means that all MPEG2
decoding must be done in software, or if you have one, on an
MPEG2 hardware decoding card or chipset.
Getting the card going
~~~~~~~~~~~~~~~~~~~~~~
In order to fire up the card, it is necessary to load a number
of modules from the DVB driver set. Prior to this it will have
been necessary to download these drivers from the linuxtv CVS
server and compile them successfully.
Depending on the card's feature set, the Device Driver API for
DVB under Linux will expose some of the following device files
in the /dev tree:
* /dev/dvb/adapter0/audio0
* /dev/dvb/adapter0/ca0
* /dev/dvb/adapter0/demux0
* /dev/dvb/adapter0/dvr0
* /dev/dvb/adapter0/frontend0
* /dev/dvb/adapter0/net0
* /dev/dvb/adapter0/osd0
* /dev/dvb/adapter0/video0
The primary device nodes that we are interested in (at this
stage) for the Avermedia DVB-T are:
* /dev/dvb/adapter0/dvr0
* /dev/dvb/adapter0/frontend0
The dvr0 device node is used to read the MPEG2 Data Stream and
the frontend0 node is used to tune the frontend tuner module.
At this stage, it has not been able to ascertain the
functionality of the remaining device nodes in respect of the
Avermedia DVBT. However, full functionality in respect of
tuning, receiving and supplying the MPEG2 data stream is
possible with the currently available versions of the driver.
It may be possible that additional functionality is available
from the card (i.e. viewing the additional analogue inputs
that the card presents), but this has not been tested yet. If
I get around to this, I'll update the document with whatever I
find.
To power up the card, load the following modules in the
following order:
* modprobe bttv (normally loaded automatically)
* modprobe dvb-bt8xx (or place dvb-bt8xx in /etc/modules)
Insertion of these modules into the running kernel will
activate the appropriate DVB device nodes. It is then possible
to start accessing the card with utilities such as scan, tzap,
dvbstream etc.
The frontend module sp887x.o, requires an external firmware.
Please use the command "get_dvb_firmware sp887x" to download
it. Then copy it to /usr/lib/hotplug/firmware or /lib/firmware/
(depending on configuration of firmware hotplug).
Receiving DVB-T in Australia
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
I have no experience of DVB-T in other countries other than
Australia, so I will attempt to explain how it works here in
Melbourne and how this affects the configuration of the DVB-T
card.
The Digital Broadcasting Australia website has a Reception
locatortool which provides information on transponder channels
and frequencies. My local transmitter happens to be Mount
Dandenong.
The frequencies broadcast by Mount Dandenong are:
Table 1. Transponder Frequencies Mount Dandenong, Vic, Aus.
Broadcaster Channel Frequency
ABC VHF 12 226.5 MHz
TEN VHF 11 219.5 MHz
NINE VHF 8 191.625 MHz
SEVEN VHF 6 177.5 MHz
SBS UHF 29 536.5 MHz
The Scan utility has a set of compiled-in defaults for various
countries and regions, but if they do not suit, or if you have
a pre-compiled scan binary, you can specify a data file on the
command line which contains the transponder frequencies. Here
is a sample file for the above channel transponders:
::
# Data file for DVB scan program
#
# C Frequency SymbolRate FEC QAM
# S Frequency Polarisation SymbolRate FEC
# T Frequency Bandwidth FEC FEC2 QAM Mode Guard Hier
T 226500000 7MHz 2/3 NONE QAM64 8k 1/8 NONE
T 191625000 7MHz 2/3 NONE QAM64 8k 1/8 NONE
T 219500000 7MHz 2/3 NONE QAM64 8k 1/8 NONE
T 177500000 7MHz 2/3 NONE QAM64 8k 1/8 NONE
T 536500000 7MHz 2/3 NONE QAM64 8k 1/8 NONE
The defaults for the transponder frequency and other
modulation parameters were obtained from www.dba.org.au.
When Scan runs, it will output channels.conf information for
any channel's transponders which the card's frontend can lock
onto. (i.e. any whose signal is strong enough at your
antenna).
Here's my channels.conf file for anyone who's interested:
::
ABC HDTV:226500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_4:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:2307:0:560
ABC TV Melbourne:226500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_4:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:561
ABC TV 2:226500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_4:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:562
ABC TV 3:226500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_4:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:563
ABC TV 4:226500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_4:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:564
ABC DiG Radio:226500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_3_4:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:0:2311:566
TEN Digital:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:1585
TEN Digital 1:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:1586
TEN Digital 2:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:1587
TEN Digital 3:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:1588
TEN Digital:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:1589
TEN Digital 4:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:1590
TEN Digital:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:1591
TEN HD:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:514:0:1592
TEN Digital:219500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:650:1593
Nine Digital:191625000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:513:660:1072
Nine Digital HD:191625000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:512:0:1073
Nine Guide:191625000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_3_4:FEC_1_2:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_16:HIERARCHY_NONE:514:670:1074
7 Digital:177500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:769:770:1328
7 Digital 1:177500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:769:770:1329
7 Digital 2:177500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:769:770:1330
7 Digital 3:177500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:769:770:1331
7 HD Digital:177500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:833:834:1332
7 Program Guide:177500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:865:866:1334
SBS HD:536500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:102:103:784
SBS DIGITAL 1:536500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:161:81:785
SBS DIGITAL 2:536500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:162:83:786
SBS EPG:536500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:163:85:787
SBS RADIO 1:536500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:0:201:798
SBS RADIO 2:536500000:INVERSION_OFF:BANDWIDTH_7_MHZ:FEC_2_3:FEC_2_3:QAM_64:TRANSMISSION_MODE_8K:GUARD_INTERVAL_1_8:HIERARCHY_NONE:0:202:799
Known Limitations
~~~~~~~~~~~~~~~~~
At present I can say with confidence that the frontend tunes
via /dev/dvb/adapter{x}/frontend0 and supplies an MPEG2 stream
via /dev/dvb/adapter{x}/dvr0. I have not tested the
functionality of any other part of the card yet. I will do so
over time and update this document.
There are some limitations in the i2c layer due to a returned
error message inconsistency. Although this generates errors in
dmesg and the system logs, it does not appear to affect the
ability of the frontend to function correctly.
Further Update
~~~~~~~~~~~~~~
dvbstream and VideoLAN Client on windows works a treat with
DVB, in fact this is currently serving as my main way of
viewing DVB-T at the moment. Additionally, VLC is happily
decoding HDTV signals, although the PC is dropping the odd
frame here and there - I assume due to processing capability -
as all the decoding is being done under windows in software.
Many thanks to Nigel Pearson for the updates to this document
since the recent revision of the driver.

122
Documentation/media/dvb-drivers/bt8xx.rst Normal file
View File

@ -0,0 +1,122 @@
How to get the bt8xx cards working
==================================
Authors: Richard Walker,
Jamie Honan,
Michael Hunold,
Manu Abraham,
Uwe Bugla,
Michael Krufky
.. note::
This documentation is outdated. Please check at the DVB wiki
at https://linuxtv.org/wiki for more updated info.
General information
-------------------
This class of cards has a bt878a as the PCI interface, and require the bttv driver
for accessing the i2c bus and the gpio pins of the bt8xx chipset.
Please see Documentation/dvb/cards.txt => o Cards based on the Conexant Bt8xx PCI bridge:
Compiling kernel please enable:
#) ``Device drivers`` => ``Multimedia devices`` => ``Video For Linux`` => ``Enable Video for Linux API 1 (DEPRECATED)``
#) ``Device drivers`` => ``Multimedia devices`` => ``Video For Linux`` => ``Video Capture Adapters`` => ``BT848 Video For Linux``
#) ``Device drivers`` => ``Multimedia devices`` => ``Digital Video Broadcasting Devices`` => ``DVB for Linux`` ``DVB Core Support`` ``Bt8xx based PCI Cards``
Please use the following options with care as deselection of drivers which are in fact necessary may result in DVB devices that cannot be tuned due to lack of driver support:
You can save RAM by deselecting every frontend module that your DVB card does not need.
First please remove the static dependency of DVB card drivers on all frontend modules for all possible card variants by enabling:
#) ``Device drivers`` => ``Multimedia devices`` => ``Digital Video Broadcasting Devices`` => ``DVB for Linux`` ``DVB Core Support`` ``Load and attach frontend modules as needed``
If you know the frontend driver that your card needs please enable:
#) ``Device drivers`` => ``Multimedia devices`` => ``Digital Video Broadcasting Devices`` => ``DVB for Linux`` ``DVB Core Support`` ``Customise DVB Frontends`` => ``Customise the frontend modules to build``
Then please select your card-specific frontend module.
Loading Modules
---------------
Regular case: If the bttv driver detects a bt8xx-based DVB card, all frontend and backend modules will be loaded automatically.
Exceptions are:
- Old TwinHan DST cards or clones with or without CA slot and not containing an Eeprom.
People running udev please see Documentation/dvb/udev.txt.
In the following cases overriding the PCI type detection for dvb-bt8xx might be necessary:
Running TwinHan and Clones
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: none
$ modprobe bttv card=113
$ modprobe dst
Useful parameters for verbosity level and debugging the dst module:
.. code-block:: none
verbose=0: messages are disabled
1: only error messages are displayed
2: notifications are displayed
3: other useful messages are displayed
4: debug setting
dst_addons=0: card is a free to air (FTA) card only
0x20: card has a conditional access slot for scrambled channels
The autodetected values are determined by the cards' "response string".
In your logs see f. ex.: dst_get_device_id: Recognize [DSTMCI].
For bug reports please send in a complete log with verbose=4 activated.
Please also see Documentation/dvb/ci.txt.
Running multiple cards
~~~~~~~~~~~~~~~~~~~~~~
Examples of card ID's:
.. code-block:: none
Pinnacle PCTV Sat: 94
Nebula Electronics Digi TV: 104
pcHDTV HD-2000 TV: 112
Twinhan DST and clones: 113
Avermedia AverTV DVB-T 771: 123
Avermedia AverTV DVB-T 761: 124
DViCO FusionHDTV DVB-T Lite: 128
DViCO FusionHDTV 5 Lite: 135
.. note::
The order of the card ID should be uprising:
Example:
.. code-block:: none
$ modprobe bttv card=113 card=135
For a full list of card ID's please see Documentation/video4linux/CARDLIST.bttv.
In case of further problems please subscribe and send questions to the mailing list: linux-dvb@linuxtv.org.
Probing the cards with broken PCI subsystem ID
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are some TwinHan cards that the EEPROM has become corrupted for some
reason. The cards do not have correct PCI subsystem ID. But we can force
probing the cards with broken PCI subsystem ID
.. code-block:: none
$ echo 109e 0878 $subvendor $subdevice > \
/sys/bus/pci/drivers/bt878/new_id
.. code-block:: none
109e: PCI_VENDOR_ID_BROOKTREE
0878: PCI_DEVICE_ID_BROOKTREE_878

71
Documentation/dvb/cards.txt → Documentation/media/dvb-drivers/cards.rst
View File

@ -1,23 +1,36 @@
Hardware supported by the linuxtv.org DVB drivers
=================================================
Generally, the DVB hardware manufacturers frequently change the
frontends (i.e. tuner / demodulator units) used, usually without
changing the product name, revision number or specs. Some cards
are also available in versions with different frontends for
DVB-S/DVB-C/DVB-T. Thus the frontend drivers are listed separately.
.. note::
Note 1: There is no guarantee that every frontend driver works
out of the box with every card, because of different wiring.
This documentation is outdated. Please check at the DVB wiki
at https://linuxtv.org/wiki for more updated info.
Note 2: The demodulator chips can be used with a variety of
tuner/PLL chips, and not all combinations are supported. Often
the demodulator and tuner/PLL chip are inside a metal box for
shielding, and the whole metal box has its own part number.
Please look at
https://linuxtv.org/wiki/index.php/Hardware_Device_Information
for an updated list of supported cards.
Generally, the DVB hardware manufacturers frequently change the
frontends (i.e. tuner / demodulator units) used, usually without
changing the product name, revision number or specs. Some cards
are also available in versions with different frontends for
DVB-S/DVB-C/DVB-T. Thus the frontend drivers are listed separately.
.. note::
#) There is no guarantee that every frontend driver works
out of the box with every card, because of different wiring.
#) The demodulator chips can be used with a variety of
tuner/PLL chips, and not all combinations are supported. Often
the demodulator and tuner/PLL chip are inside a metal box for
shielding, and the whole metal box has its own part number.
o Frontends drivers:
- Frontends drivers:
- dvb_dummy_fe: for testing...
DVB-S:
- ves1x93 : Alps BSRV2 (ves1893 demodulator) and dbox2 (ves1993)
- cx24110 : Conexant HM1221/HM1811 (cx24110 or cx24106 demod, cx24108 PLL)
@ -26,21 +39,23 @@ o Frontends drivers:
- stv0299 : Alps BSRU6 (tsa5059 PLL), LG TDQB-S00x (tsa5059 PLL),
LG TDQF-S001F (sl1935 PLL), Philips SU1278 (tua6100 PLL),
Philips SU1278SH (tsa5059 PLL), Samsung TBMU24112IMB, Technisat Sky2Pc with bios Rev. 2.6
DVB-C:
- ves1820 : various (ves1820 demodulator, sp5659c or spXXXX PLL)
- at76c651 : Atmel AT76c651(B) with DAT7021 PLL
DVB-T:
- alps_tdlb7 : Alps TDLB7 (sp8870 demodulator, sp5659 PLL)
- alps_tdmb7 : Alps TDMB7 (cx22700 demodulator)
- grundig_29504-401 : Grundig 29504-401 (LSI L64781 demodulator), tsa5060 PLL
- tda1004x : Philips tda10045h (td1344 or tdm1316l PLL)
- nxt6000 : Alps TDME7 (MITEL SP5659 PLL), Alps TDED4 (TI ALP510 PLL),
Comtech DVBT-6k07 (SP5730 PLL)
(NxtWave Communications NXT6000 demodulator)
- nxt6000 : Alps TDME7 (MITEL SP5659 PLL), Alps TDED4 (TI ALP510 PLL), Comtech DVBT-6k07 (SP5730 PLL), (NxtWave Communications NXT6000 demodulator)
- sp887x : Microtune 7202D
- dib3000mb : DiBcom 3000-MB demodulator
DVB-S/C/T:
- dst : TwinHan DST Frontend
ATSC:
- nxt200x : Nxtwave NXT2002 & NXT2004
- or51211 : or51211 based (pcHDTV HD2000 card)
@ -49,10 +64,10 @@ o Frontends drivers:
- lgdt330x : LG Electronics DT3302 & DT3303
o Cards based on the Phillips saa7146 multimedia PCI bridge chip:
- Cards based on the Phillips saa7146 multimedia PCI bridge chip:
- TI AV7110 based cards (i.e. with hardware MPEG decoder):
- Siemens/Technotrend/Hauppauge PCI DVB card revision 1.1, 1.3, 1.5, 1.6, 2.1
(aka Hauppauge Nexus)
- Siemens/Technotrend/Hauppauge PCI DVB card revision 1.1, 1.3, 1.5, 1.6, 2.1 (aka Hauppauge Nexus)
- "budget" cards (i.e. without hardware MPEG decoder):
- Technotrend Budget / Hauppauge WinTV-Nova PCI Cards
- SATELCO Multimedia PCI
@ -60,10 +75,12 @@ o Cards based on the Phillips saa7146 multimedia PCI bridge chip:
- Typhoon DVB-S budget
- Fujitsu-Siemens Activy DVB-S budget card
o Cards based on the B2C2 Inc. FlexCopII/IIb/III:
- Cards based on the B2C2 Inc. FlexCopII/IIb/III:
- Technisat SkyStar2 PCI DVB card revision 2.3, 2.6B, 2.6C
o Cards based on the Conexant Bt8xx PCI bridge:
- Cards based on the Conexant Bt8xx PCI bridge:
- Pinnacle PCTV Sat DVB
- Nebula Electronics DigiTV
- TwinHan DST
@ -73,11 +90,13 @@ o Cards based on the Conexant Bt8xx PCI bridge:
- DViCO FusionHDTV DVB-T Lite
- DViCO FusionHDTV5 Lite
o Technotrend / Hauppauge DVB USB devices:
- Technotrend / Hauppauge DVB USB devices:
- Nova USB
- DEC 2000-T, 3000-S, 2540-T
o DiBcom DVB-T USB based devices:
- DiBcom DVB-T USB based devices:
- Twinhan VisionPlus VisionDTV USB-Ter DVB-T Device
- HAMA DVB-T USB device
- CTS Portable (Chinese Television System)
@ -92,9 +111,10 @@ o DiBcom DVB-T USB based devices:
- Yakumo DVB-T mobile USB2.0
- DiBcom USB2.0 DVB-T reference device (non-public)
o Experimental support for the analog module of the Siemens DVB-C PCI card
- Experimental support for the analog module of the Siemens DVB-C PCI card
- Cards based on the Conexant cx2388x PCI bridge:
o Cards based on the Conexant cx2388x PCI bridge:
- ADS Tech Instant TV DVB-T PCI
- ATI HDTV Wonder
- digitalnow DNTV Live! DVB-T
@ -109,7 +129,8 @@ o Cards based on the Conexant cx2388x PCI bridge:
- TerraTec Cinergy 1400 DVB-T
- WinFast DTV1000-T
o Cards based on the Phillips saa7134 PCI bridge:
- Cards based on the Phillips saa7134 PCI bridge:
- Medion 7134
- Pinnacle PCTV 300i DVB-T + PAL
- LifeView FlyDVB-T DUO

186
Documentation/dvb/ci.txt → Documentation/media/dvb-drivers/ci.rst
View File

@ -1,52 +1,68 @@
* For the user
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
NOTE: This document describes the usage of the high level CI API as
Digital TV Conditional Access Interface (CI API)
================================================
.. note::
This documentation is outdated.
This document describes the usage of the high level CI API as
in accordance to the Linux DVB API. This is a not a documentation for the,
existing low level CI API.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To utilize the High Level CI capabilities,
.. note::
(1*) This point is valid only for the Twinhan/clones
For the Twinhan/Twinhan clones, the dst_ca module handles the CI
hardware handling.This module is loaded automatically if a CI
(Common Interface, that holds the CAM (Conditional Access Module)
is detected.
For the Twinhan/Twinhan clones, the dst_ca module handles the CI
hardware handling.This module is loaded automatically if a CI
(Common Interface, that holds the CAM (Conditional Access Module)
is detected.
(2) one requires a userspace application, ca_zap. This small userland
application is in charge of sending the descrambling related information
to the CAM.
ca_zap
~~~~~~
An userspace application, like ``ca_zap`` is required to handle encrypted
MPEG-TS streams.
The ``ca_zap`` userland application is in charge of sending the
descrambling related information to the Conditional Access Module (CAM).
This application requires the following to function properly as of now.
(a) Tune to a valid channel, with szap.
eg: $ szap -c channels.conf -r "TMC" -x
a) Tune to a valid channel, with szap.
(b) a channels.conf containing a valid PMT PID
eg: TMC:11996:h:0:27500:278:512:650:321
eg: $ szap -c channels.conf -r "TMC" -x
here 278 is a valid PMT PID. the rest of the values are the
same ones that szap uses.
b) a channels.conf containing a valid PMT PID
(c) after running a szap, you have to run ca_zap, for the
descrambler to function,
eg: $ ca_zap channels.conf "TMC"
eg: TMC:11996:h:0:27500:278:512:650:321
(d) Hopefully enjoy your favourite subscribed channel as you do with
a FTA card.
here 278 is a valid PMT PID. the rest of the values are the
same ones that szap uses.
(3) Currently ca_zap, and dst_test, both are meant for demonstration
c) after running a szap, you have to run ca_zap, for the
descrambler to function,
eg: $ ca_zap channels.conf "TMC"
d) Hopefully enjoy your favourite subscribed channel as you do with
a FTA card.
.. note::
Currently ca_zap, and dst_test, both are meant for demonstration
purposes only, they can become full fledged applications if necessary.
* Cards that fall in this category
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Cards that fall in this category
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
At present the cards that fall in this category are the Twinhan and its
clones, these cards are available as VVMER, Tomato, Hercules, Orange and
so on.
* CI modules that are supported
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
CI modules that are supported
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The CI module support is largely dependent upon the firmware on the cards
Some cards do support almost all of the available CI modules. There is
nothing much that can be done in order to make additional CI modules
@ -58,11 +74,12 @@ Modules that have been tested by this driver at present are
(2) Viaccess from SCM
(3) Dragoncam
* The High level CI API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The High level CI API
~~~~~~~~~~~~~~~~~~~~~
For the programmer
^^^^^^^^^^^^^^^^^^
* For the programmer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
With the High Level CI approach any new card with almost any random
architecture can be implemented with this style, the definitions
inside the switch statement can be easily adapted for any card, thereby
@ -74,29 +91,30 @@ array to/from the CI ioctls as defined in the Linux DVB API. No changes
have been made in the API to accommodate this feature.
* Why the need for another CI interface ?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Why the need for another CI interface?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is one of the most commonly asked question. Well a nice question.
Strictly speaking this is not a new interface.
The CI interface is defined in the DVB API in ca.h as
The CI interface is defined in the DVB API in ca.h as:
typedef struct ca_slot_info {
int num; /* slot number */
.. code-block:: c
int type; /* CA interface this slot supports */
#define CA_CI 1 /* CI high level interface */
#define CA_CI_LINK 2 /* CI link layer level interface */
#define CA_CI_PHYS 4 /* CI physical layer level interface */
#define CA_DESCR 8 /* built-in descrambler */
#define CA_SC 128 /* simple smart card interface */
unsigned int flags;
#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
#define CA_CI_MODULE_READY 2
} ca_slot_info_t;
typedef struct ca_slot_info {
int num; /* slot number */
int type; /* CA interface this slot supports */
#define CA_CI 1 /* CI high level interface */
#define CA_CI_LINK 2 /* CI link layer level interface */
#define CA_CI_PHYS 4 /* CI physical layer level interface */
#define CA_DESCR 8 /* built-in descrambler */
#define CA_SC 128 /* simple smart card interface */
unsigned int flags;
#define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */
#define CA_CI_MODULE_READY 2
} ca_slot_info_t;
This CI interface follows the CI high level interface, which is not
implemented by most applications. Hence this area is revisited.
@ -113,7 +131,6 @@ means that no session management, link layer or a transport layer do
exist in this case in the application to driver communication. It is
as simple as that. The driver/hardware has to take care of that.
With this High Level CI interface, the interface can be defined with the
regular ioctls.
@ -129,34 +146,36 @@ All these ioctls are also valid for the High level CI interface
#define CA_SET_PID _IOW('o', 135, ca_pid_t)
On querying the device, the device yields information thus
On querying the device, the device yields information thus:
CA_GET_SLOT_INFO
----------------------------
Command = [info]
APP: Number=[1]
APP: Type=[1]
APP: flags=[1]
APP: CI High level interface
APP: CA/CI Module Present
.. code-block:: none
CA_GET_CAP
----------------------------
Command = [caps]
APP: Slots=[1]
APP: Type=[1]
APP: Descrambler keys=[16]
APP: Type=[1]
CA_GET_SLOT_INFO
----------------------------
Command = [info]
APP: Number=[1]
APP: Type=[1]
APP: flags=[1]
APP: CI High level interface
APP: CA/CI Module Present
CA_SEND_MSG
----------------------------
Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]
Found CA descriptor @ program level
CA_GET_CAP
----------------------------
Command = [caps]
APP: Slots=[1]
APP: Type=[1]
APP: Descrambler keys=[16]
APP: Type=[1]
(20) ES type=[2] ES pid=[201] ES length =[0 (0x0)]
(25) ES type=[4] ES pid=[301] ES length =[0 (0x0)]
ca_message length is 25 (0x19) bytes
EN50221 CA MSG=[ 9f 80 32 19 03 01 2d d1 f0 08 01 09 06 06 04 05 50 ff f1 02 e0 c9 00 00 04 e1 2d 00 00]
CA_SEND_MSG
----------------------------
Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1]
Found CA descriptor @ program level
(20) ES type=[2] ES pid=[201] ES length =[0 (0x0)]
(25) ES type=[4] ES pid=[301] ES length =[0 (0x0)]
ca_message length is 25 (0x19) bytes
EN50221 CA MSG=[ 9f 80 32 19 03 01 2d d1 f0 08 01 09 06 06 04 05 50 ff f1 02 e0 c9 00 00 04 e1 2d 00 00]
Not all ioctl's are implemented in the driver from the API, the other
@ -164,21 +183,20 @@ features of the hardware that cannot be implemented by the API are achieved
using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is
used to exchange the data to maintain compatibility with other hardware.
.. code-block:: c
/* a message to/from a CI-CAM */
typedef struct ca_msg {
unsigned int index;
unsigned int type;
unsigned int length;
unsigned char msg[256];
} ca_msg_t;
/* a message to/from a CI-CAM */
typedef struct ca_msg {
unsigned int index;
unsigned int type;
unsigned int length;
unsigned char msg[256];
} ca_msg_t;
The flow of data can be described thus,
.. code-block:: none
App (User)
-----

129
Documentation/media/dvb-drivers/contributors.rst Normal file
View File

@ -0,0 +1,129 @@
Contributors
============
.. note::
This documentation is outdated. There are several other DVB contributors
that aren't listed below.
Thanks go to the following people for patches and contributions:
- Michael Hunold <m.hunold@gmx.de>
- for the initial saa7146 driver and its recent overhaul
- Christian Theiss
- for his work on the initial Linux DVB driver
- Marcus Metzler <mocm@metzlerbros.de> and
Ralph Metzler <rjkm@metzlerbros.de>
- for their continuing work on the DVB driver
- Michael Holzt <kju@debian.org>
- for his contributions to the dvb-net driver
- Diego Picciani <d.picciani@novacomp.it>
- for CyberLogin for Linux which allows logging onto EON
(in case you are wondering where CyberLogin is, EON changed its login
procedure and CyberLogin is no longer used.)
- Martin Schaller <martin@smurf.franken.de>
- for patching the cable card decoder driver
- Klaus Schmidinger <Klaus.Schmidinger@cadsoft.de>
- for various fixes regarding tuning, OSD and CI stuff and his work on VDR
- Steve Brown <sbrown@cortland.com>
- for his AFC kernel thread
- Christoph Martin <martin@uni-mainz.de>
- for his LIRC infrared handler
- Andreas Oberritter <obi@linuxtv.org>,
Dennis Noermann <dennis.noermann@noernet.de>,
Felix Domke <tmbinc@elitedvb.net>,
Florian Schirmer <jolt@tuxbox.org>,
Ronny Strutz <3des@elitedvb.de>,
Wolfram Joost <dbox2@frokaschwei.de>
and all the other dbox2 people
- for many bugfixes in the generic DVB Core, frontend drivers and
their work on the dbox2 port of the DVB driver
- Oliver Endriss <o.endriss@gmx.de>
- for many bugfixes
- Andrew de Quincey <adq_dvb@lidskialf.net>
- for the tda1004x frontend driver, and various bugfixes
- Peter Schildmann <peter.schildmann@web.de>
- for the driver for the Technisat SkyStar2 PCI DVB card
- Vadim Catana <skystar@moldova.cc>,
Roberto Ragusa <r.ragusa@libero.it> and
Augusto Cardoso <augusto@carhil.net>
- for all the work for the FlexCopII chipset by B2C2,Inc.
- Davor Emard <emard@softhome.net>
- for his work on the budget drivers, the demux code,
the module unloading problems, ...
- Hans-Frieder Vogt <hfvogt@arcor.de>
- for his work on calculating and checking the crc's for the
TechnoTrend/Hauppauge DEC driver firmware
- Michael Dreher <michael@5dot1.de> and
Andreas 'randy' Weinberger
- for the support of the Fujitsu-Siemens Activy budget DVB-S
- Kenneth Aafløy <ke-aa@frisurf.no>
- for adding support for Typhoon DVB-S budget card
- Ernst Peinlich <e.peinlich@inode.at>
- for tuning/DiSEqC support for the DEC 3000-s
- Peter Beutner <p.beutner@gmx.net>
- for the IR code for the ttusb-dec driver
- Wilson Michaels <wilsonmichaels@earthlink.net>
- for the lgdt330x frontend driver, and various bugfixes
- Michael Krufky <mkrufky@linuxtv.org>
- for maintaining v4l/dvb inter-tree dependencies
- Taylor Jacob <rtjacob@earthlink.net>
- for the nxt2002 frontend driver
- Jean-Francois Thibert <jeanfrancois@sagetv.com>
- for the nxt2004 frontend driver
- Kirk Lapray <kirk.lapray@gmail.com>
- for the or51211 and or51132 frontend drivers, and
for merging the nxt2002 and nxt2004 modules into a
single nxt200x frontend driver.
(If you think you should be in this list, but you are not, drop a
line to the DVB mailing list)

355
Documentation/media/dvb-drivers/dvb-usb.rst Normal file
View File

@ -0,0 +1,355 @@
Idea behind the dvb-usb-framework
=================================
.. note::
#) This documentation is outdated. Please check at the DVB wiki
at https://linuxtv.org/wiki for more updated info.
#) **deprecated:** Newer DVB USB drivers should use the dvb-usb-v2 framework.
In March 2005 I got the new Twinhan USB2.0 DVB-T device. They provided specs
and a firmware.
Quite keen I wanted to put the driver (with some quirks of course) into dibusb.
After reading some specs and doing some USB snooping, it realized, that the
dibusb-driver would be a complete mess afterwards. So I decided to do it in a
different way: With the help of a dvb-usb-framework.
The framework provides generic functions (mostly kernel API calls), such as:
- Transport Stream URB handling in conjunction with dvb-demux-feed-control
(bulk and isoc are supported)
- registering the device for the DVB-API
- registering an I2C-adapter if applicable
- remote-control/input-device handling
- firmware requesting and loading (currently just for the Cypress USB
controllers)
- other functions/methods which can be shared by several drivers (such as
functions for bulk-control-commands)
- TODO: a I2C-chunker. It creates device-specific chunks of register-accesses
depending on length of a register and the number of values that can be
multi-written and multi-read.
The source code of the particular DVB USB devices does just the communication
with the device via the bus. The connection between the DVB-API-functionality
is done via callbacks, assigned in a static device-description (struct
dvb_usb_device) each device-driver has to have.
For an example have a look in drivers/media/usb/dvb-usb/vp7045*.
Objective is to migrate all the usb-devices (dibusb, cinergyT2, maybe the
ttusb; flexcop-usb already benefits from the generic flexcop-device) to use
the dvb-usb-lib.
TODO: dynamic enabling and disabling of the pid-filter in regard to number of
feeds requested.
Supported devices
-----------------
See the LinuxTV DVB Wiki at https://linuxtv.org for a complete list of
cards/drivers/firmwares:
https://linuxtv.org/wiki/index.php/DVB_USB
0. History & News:
2005-06-30
- added support for WideView WT-220U (Thanks to Steve Chang)
2005-05-30
- added basic isochronous support to the dvb-usb-framework
- added support for Conexant Hybrid reference design and Nebula
DigiTV USB
2005-04-17
- all dibusb devices ported to make use of the dvb-usb-framework
2005-04-02
- re-enabled and improved remote control code.
2005-03-31
- ported the Yakumo/Hama/Typhoon DVB-T USB2.0 device to dvb-usb.
2005-03-30
- first commit of the dvb-usb-module based on the dibusb-source.
First device is a new driver for the
TwinhanDTV Alpha / MagicBox II USB2.0-only DVB-T device.
- (change from dvb-dibusb to dvb-usb)
2005-03-28
- added support for the AVerMedia AverTV DVB-T USB2.0 device
(Thanks to Glen Harris and Jiun-Kuei Jung, AVerMedia)
2005-03-14
- added support for the Typhoon/Yakumo/HAMA DVB-T mobile USB2.0
2005-02-11
- added support for the KWorld/ADSTech Instant DVB-T USB2.0.
Thanks a lot to Joachim von Caron
2005-02-02
- added support for the Hauppauge Win-TV Nova-T USB2
2005-01-31
- distorted streaming is gone for USB1.1 devices
2005-01-13
- moved the mirrored pid_filter_table back to dvb-dibusb
first almost working version for HanfTek UMT-010
found out, that Yakumo/HAMA/Typhoon are predecessors of the HanfTek UMT-010
2005-01-10
- refactoring completed, now everything is very delightful
- tuner quirks for some weird devices (Artec T1 AN2235 device has sometimes a
Panasonic Tuner assembled). Tunerprobing implemented.
Thanks a lot to Gunnar Wittich.
2004-12-29
- after several days of struggling around bug of no returning URBs fixed.
2004-12-26
- refactored the dibusb-driver, splitted into separate files
- i2c-probing enabled
2004-12-06
- possibility for demod i2c-address probing
- new usb IDs (Compro, Artec)
2004-11-23
- merged changes from DiB3000MC_ver2.1
- revised the debugging
- possibility to deliver the complete TS for USB2.0
2004-11-21
- first working version of the dib3000mc/p frontend driver.
2004-11-12
- added additional remote control keys. Thanks to Uwe Hanke.
2004-11-07
- added remote control support. Thanks to David Matthews.
2004-11-05
- added support for a new devices (Grandtec/Avermedia/Artec)
- merged my changes (for dib3000mb/dibusb) to the FE_REFACTORING, because it became HEAD
- moved transfer control (pid filter, fifo control) from usb driver to frontend, it seems
better settled there (added xfer_ops-struct)
- created a common files for frontends (mc/p/mb)
2004-09-28
- added support for a new device (Unknown, vendor ID is Hyper-Paltek)
2004-09-20
- added support for a new device (Compro DVB-U2000), thanks
to Amaury Demol for reporting
- changed usb TS transfer method (several urbs, stopping transfer
before setting a new pid)
2004-09-13
- added support for a new device (Artec T1 USB TVBOX), thanks
to Christian Motschke for reporting
2004-09-05
- released the dibusb device and dib3000mb-frontend driver
(old news for vp7041.c)
2004-07-15
- found out, by accident, that the device has a TUA6010XS for PLL
2004-07-12
- figured out, that the driver should also work with the
CTS Portable (Chinese Television System)
2004-07-08
- firmware-extraction-2.422-problem solved, driver is now working
properly with firmware extracted from 2.422
- #if for 2.6.4 (dvb), compile issue
- changed firmware handling, see vp7041.txt sec 1.1
2004-07-02
- some tuner modifications, v0.1, cleanups, first public
2004-06-28
- now using the dvb_dmx_swfilter_packets, everything runs fine now
2004-06-27
- able to watch and switching channels (pre-alpha)
- no section filtering yet
2004-06-06
- first TS received, but kernel oops :/
2004-05-14
- firmware loader is working
2004-05-11
- start writing the driver
How to use?
-----------
Firmware
~~~~~~~~
Most of the USB drivers need to download a firmware to the device before start
working.
Have a look at the Wikipage for the DVB-USB-drivers to find out, which firmware
you need for your device:
https://linuxtv.org/wiki/index.php/DVB_USB
Compiling
~~~~~~~~~
Since the driver is in the linux kernel, activating the driver in
your favorite config-environment should sufficient. I recommend
to compile the driver as module. Hotplug does the rest.
If you use dvb-kernel enter the build-2.6 directory run 'make' and 'insmod.sh
load' afterwards.
Loading the drivers
~~~~~~~~~~~~~~~~~~~
Hotplug is able to load the driver, when it is needed (because you plugged
in the device).
If you want to enable debug output, you have to load the driver manually and
from within the dvb-kernel cvs repository.
first have a look, which debug level are available:
.. code-block:: none
# modinfo dvb-usb
# modinfo dvb-usb-vp7045
etc.
.. code-block:: none
modprobe dvb-usb debug=<level>
modprobe dvb-usb-vp7045 debug=<level>
etc.
should do the trick.
When the driver is loaded successfully, the firmware file was in
the right place and the device is connected, the "Power"-LED should be
turned on.
At this point you should be able to start a dvb-capable application. I'm use
(t|s)zap, mplayer and dvbscan to test the basics. VDR-xine provides the
long-term test scenario.
Known problems and bugs
-----------------------
- Don't remove the USB device while running an DVB application, your system
will go crazy or die most likely.
Adding support for devices
~~~~~~~~~~~~~~~~~~~~~~~~~~
TODO
USB1.1 Bandwidth limitation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
A lot of the currently supported devices are USB1.1 and thus they have a
maximum bandwidth of about 5-6 MBit/s when connected to a USB2.0 hub.
This is not enough for receiving the complete transport stream of a
DVB-T channel (which is about 16 MBit/s). Normally this is not a
problem, if you only want to watch TV (this does not apply for HDTV),
but watching a channel while recording another channel on the same
frequency simply does not work very well. This applies to all USB1.1
DVB-T devices, not just the dvb-usb-devices)
The bug, where the TS is distorted by a heavy usage of the device is gone
definitely. All dvb-usb-devices I was using (Twinhan, Kworld, DiBcom) are
working like charm now with VDR. Sometimes I even was able to record a channel
and watch another one.
Comments
~~~~~~~~
Patches, comments and suggestions are very very welcome.
3. Acknowledgements
-------------------
Amaury Demol (Amaury.Demol@parrot.com) and Francois Kanounnikoff from DiBcom for
providing specs, code and help, on which the dvb-dibusb, dib3000mb and
dib3000mc are based.
David Matthews for identifying a new device type (Artec T1 with AN2235)
and for extending dibusb with remote control event handling. Thank you.
Alex Woods for frequently answering question about usb and dvb
stuff, a big thank you.
Bernd Wagner for helping with huge bug reports and discussions.
Gunnar Wittich and Joachim von Caron for their trust for providing
root-shells on their machines to implement support for new devices.
Allan Third and Michael Hutchinson for their help to write the Nebula
digitv-driver.
Glen Harris for bringing up, that there is a new dibusb-device and Jiun-Kuei
Jung from AVerMedia who kindly provided a special firmware to get the device
up and running in Linux.
Jennifer Chen, Jeff and Jack from Twinhan for kindly supporting by
writing the vp7045-driver.
Steve Chang from WideView for providing information for new devices and
firmware files.
Michael Paxton for submitting remote control keymaps.
Some guys on the linux-dvb mailing list for encouraging me.
Peter Schildmann >peter.schildmann-nospam-at-web.de< for his
user-level firmware loader, which saves a lot of time
(when writing the vp7041 driver)
Ulf Hermenau for helping me out with traditional chinese.
André Smoktun and Christian Frömmel for supporting me with
hardware and listening to my problems very patiently.

18
Documentation/dvb/faq.txt → Documentation/media/dvb-drivers/faq.rst
View File

@ -1,3 +1,11 @@
FAQ
===
.. note::
This documentation is outdated. Please check at the DVB wiki
at https://linuxtv.org/wiki for more updated info.
Some very frequently asked questions about linuxtv-dvb
1. The signal seems to die a few seconds after tuning.
@ -71,8 +79,7 @@ Some very frequently asked questions about linuxtv-dvb
http://www.dbox2.info/
LinuxDVB on the dBox2
http://www.tuxbox.org/
http://cvs.tuxbox.org/
http://www.tuxbox.org/ and http://cvs.tuxbox.org/
the TuxBox CVS many interesting DVB applications and the dBox2
DVB source
@ -85,8 +92,7 @@ Some very frequently asked questions about linuxtv-dvb
http://mplayerhq.hu/
mplayer
http://xine.sourceforge.net/
http://xinehq.de/
http://xine.sourceforge.net/ and http://xinehq.de/
xine
http://www.mythtv.org/
@ -125,6 +131,9 @@ Some very frequently asked questions about linuxtv-dvb
Check your routes if they include the multicast address range.
Additionally make sure that "source validation by reversed path
lookup" is disabled:
.. code-block:: none
$ "echo 0 > /proc/sys/net/ipv4/conf/dvb0/rp_filter"
7. What the hell are all those modules that need to be loaded?
@ -156,4 +165,3 @@ Some very frequently asked questions about linuxtv-dvb
- dvb-ttpci: The main driver for AV7110 based, full-featured
DVB-S/C/T cards
eof

42
Documentation/media/dvb-drivers/index.rst Normal file
View File

@ -0,0 +1,42 @@
.. -*- coding: utf-8; mode: rst -*-
.. include:: <isonum.txt>
##############################################
Linux Digital TV driver-specific documentation
##############################################
**Copyright** |copy| 2001-2016 : LinuxTV Developers
This documentation is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation version 2 of the License.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
For more details see the file COPYING in the source distribution of Linux.
.. class:: toc-title
Table of Contents
.. toctree::
:maxdepth: 5
:numbered:
intro
avermedia
bt8xx
cards
ci
dvb-usb
faq
lmedm04
opera-firmware
technisat
ttusb-dec
udev
contributors

21
Documentation/media/dvb-drivers/intro.rst Normal file
View File

@ -0,0 +1,21 @@
Introdution
===========
The main development site and GIT repository for these
drivers is https://linuxtv.org.
The DVB mailing list linux-dvb is hosted at vger. Please see
http://vger.kernel.org/vger-lists.html#linux-media for details.
There are also some other old lists hosted at https://linuxtv.org/lists.php. Please check the archive https://linuxtv.org/pipermail/linux-dvb/.
The media subsystem Wiki is hosted at https://linuxtv.org/wiki/.
Please check it before asking newbie questions on the list.
API documentation is documented at the Kernel. You'll also find useful
documentation at: https://linuxtv.org/docs.php.
You may also find useful material at https://linuxtv.org/downloads/.
In order to get firmware from proprietary drivers, there's a script at
the kernel tree, at scripts/get_dvb_firmware.

72
Documentation/dvb/lmedm04.txt → Documentation/media/dvb-drivers/lmedm04.rst
View File

@ -1,7 +1,10 @@
Firmware files for lmedm04 cards
================================
To extract firmware for the DM04/QQBOX you need to copy the
following file(s) to this directory.
for DM04+/QQBOX LME2510C (Sharp 7395 Tuner)
For DM04+/QQBOX LME2510C (Sharp 7395 Tuner)
-------------------------------------------
The Sharp 7395 driver can be found in windows/system32/drivers
@ -9,38 +12,43 @@ The Sharp 7395 driver can be found in windows/system32/drivers
US2A0D.sys (dated 17 Mar 2009)
and run
./get_dvb_firmware lme2510c_s7395
and run:
will produce
dvb-usb-lme2510c-s7395.fw
.. code-block:: none
scripts/get_dvb_firmware lme2510c_s7395
will produce dvb-usb-lme2510c-s7395.fw
An alternative but older firmware can be found on the driver
disk DVB-S_EN_3.5A in BDADriver/driver
LMEBDA_DVBS7395C.sys (dated 18 Jan 2008)
and run
./get_dvb_firmware lme2510c_s7395_old
and run:
will produce
dvb-usb-lme2510c-s7395.fw
.. code-block:: none
--------------------------------------------------------------------
./get_dvb_firmware lme2510c_s7395_old
will produce dvb-usb-lme2510c-s7395.fw
The LG firmware can be found on the driver
disk DM04+_5.1A[LG] in BDADriver/driver
for DM04 LME2510 (LG Tuner)
For DM04 LME2510 (LG Tuner)
---------------------------
LMEBDA_DVBS.sys (dated 13 Nov 2007)
and run
./get_dvb_firmware lme2510_lg
and run:
will produce
dvb-usb-lme2510-lg.fw
.. code-block:: none
./get_dvb_firmware lme2510_lg
will produce dvb-usb-lme2510-lg.fw
Other LG firmware can be extracted manually from US280D.sys
@ -48,34 +56,50 @@ only found in windows/system32/drivers
dd if=US280D.sys ibs=1 skip=42360 count=3924 of=dvb-usb-lme2510-lg.fw
for DM04 LME2510C (LG Tuner)
---------------------------
For DM04 LME2510C (LG Tuner)
----------------------------
dd if=US280D.sys ibs=1 skip=35200 count=3850 of=dvb-usb-lme2510c-lg.fw
.. code-block:: none
dd if=US280D.sys ibs=1 skip=35200 count=3850 of=dvb-usb-lme2510c-lg.fw
---------------------------------------------------------------------
The Sharp 0194 tuner driver can be found in windows/system32/drivers
US290D.sys (dated 09 Apr 2009)
For LME2510
dd if=US290D.sys ibs=1 skip=36856 count=3976 of=dvb-usb-lme2510-s0194.fw
-----------
.. code-block:: none
dd if=US290D.sys ibs=1 skip=36856 count=3976 of=dvb-usb-lme2510-s0194.fw
For LME2510C
dd if=US290D.sys ibs=1 skip=33152 count=3697 of=dvb-usb-lme2510c-s0194.fw
------------
.. code-block:: none
dd if=US290D.sys ibs=1 skip=33152 count=3697 of=dvb-usb-lme2510c-s0194.fw
---------------------------------------------------------------------
The m88rs2000 tuner driver can be found in windows/system32/drivers
US2B0D.sys (dated 29 Jun 2010)
dd if=US2B0D.sys ibs=1 skip=34432 count=3871 of=dvb-usb-lme2510c-rs2000.fw
.. code-block:: none
dd if=US2B0D.sys ibs=1 skip=34432 count=3871 of=dvb-usb-lme2510c-rs2000.fw
We need to modify id of rs2000 firmware or it will warm boot id 3344:1120.
echo -ne \\xF0\\x22 | dd conv=notrunc bs=1 count=2 seek=266 of=dvb-usb-lme2510c-rs2000.fw
.. code-block:: none
echo -ne \\xF0\\x22 | dd conv=notrunc bs=1 count=2 seek=266 of=dvb-usb-lme2510c-rs2000.fw
Copy the firmware file(s) to /lib/firmware

14
Documentation/dvb/opera-firmware.txt → Documentation/media/dvb-drivers/opera-firmware.rst
View File

@ -1,3 +1,8 @@
Opera firmware
==============
Author: Marco Gittler <g.marco@freenet.de>
To extract the firmware for the Opera DVB-S1 USB-Box
you need to copy the files:
@ -6,9 +11,11 @@ you need to copy the files:
from the windriver disk into this directory.
Then run
Then run:
./get_dvb_firmware opera1
.. code-block:: none
scripts/get_dvb_firmware opera1
and after that you have 2 files:
@ -22,6 +29,3 @@ Copy them into /lib/firmware/ .
After that the driver can load the firmware
(if you have enabled firmware loading
in kernel config and have hotplug running).
Marco Gittler <g.marco@freenet.de>

98
Documentation/media/dvb-drivers/technisat.rst Normal file
View File

@ -0,0 +1,98 @@
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``

43
Documentation/media/dvb-drivers/ttusb-dec.rst Normal file
View File

@ -0,0 +1,43 @@
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).

31
Documentation/dvb/udev.txt → Documentation/media/dvb-drivers/udev.rst
View File

@ -1,9 +1,22 @@
UDEV rules for DVB
==================
.. note::
#) This documentation is outdated. Udev on modern distributions auto-detect
the DVB devices.
#) **TODO:** change this document to explain how to make DVB devices
persistent, as, when a machine has multiple devices, they may be detected
on different orders, which could cause apps that relies on the device
numbers to fail.
The DVB subsystem currently registers to the sysfs subsystem using the
"class_simple" interface.
This means that only the basic information like module loading parameters
are presented through sysfs. Other things that might be interesting are
currently *not* available.
currently **not** available.
Nevertheless it's now possible to add proper udev rules so that the
DVB device nodes are created automatically.
@ -21,10 +34,11 @@ The script should be called "dvb.sh" and should be placed into a script
dir where udev can execute it, most likely /etc/udev/scripts/
So, create a new file /etc/udev/scripts/dvb.sh and add the following:
------------------------------schnipp------------------------------------------------
#!/bin/sh
/bin/echo $1 | /bin/sed -e 's,dvb\([0-9]\)\.\([^0-9]*\)\([0-9]\),dvb/adapter\1/\2\3,'
------------------------------schnipp------------------------------------------------
.. code-block:: none
#!/bin/sh
/bin/echo $1 | /bin/sed -e 's,dvb\([0-9]\)\.\([^0-9]*\)\([0-9]\),dvb/adapter\1/\2\3,'
Don't forget to make the script executable with "chmod".
@ -34,9 +48,10 @@ directory for rule files. The main udev configuration file /etc/udev/udev.conf
will tell you the directory where the rules are, most likely it's /etc/udev/rules.d/
Create a new rule file in that directory called "dvb.rule" and add the following line:
------------------------------schnipp------------------------------------------------
KERNEL="dvb*", PROGRAM="/etc/udev/scripts/dvb.sh %k", NAME="%c"
------------------------------schnipp------------------------------------------------
.. code-block:: none
KERNEL="dvb*", PROGRAM="/etc/udev/scripts/dvb.sh %k", NAME="%c"
If you want more control over the device nodes (for example a special group membership)
have a look at "man udev".

47
Documentation/media/frontend.h.rst.exceptions Normal file
View File

@ -0,0 +1,47 @@
# Ignore header name
ignore define _DVBFRONTEND_H_
# Group layer A-C symbols together
replace define DTV_ISDBT_LAYERA_FEC dtv-isdbt-layer-fec
replace define DTV_ISDBT_LAYERB_FEC dtv-isdbt-layer-fec
replace define DTV_ISDBT_LAYERC_FEC dtv-isdbt-layer-fec
replace define DTV_ISDBT_LAYERA_MODULATION dtv-isdbt-layer-modulation
replace define DTV_ISDBT_LAYERB_MODULATION dtv-isdbt-layer-modulation
replace define DTV_ISDBT_LAYERC_MODULATION dtv-isdbt-layer-modulation
replace define DTV_ISDBT_LAYERA_SEGMENT_COUNT dtv-isdbt-layer-segment-count
replace define DTV_ISDBT_LAYERB_SEGMENT_COUNT dtv-isdbt-layer-segment-count
replace define DTV_ISDBT_LAYERC_SEGMENT_COUNT dtv-isdbt-layer-segment-count
replace define DTV_ISDBT_LAYERA_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving
replace define DTV_ISDBT_LAYERB_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving
replace define DTV_ISDBT_LAYERC_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving
# Ignore legacy defines
ignore define DTV_ISDBS_TS_ID_LEGACY
ignore define SYS_DVBC_ANNEX_AC
ignore define SYS_DMBTH
# Ignore limits
ignore define DTV_MAX_COMMAND
ignore define MAX_DTV_STATS
ignore define DTV_IOCTL_MAX_MSGS
# Stats enum is documented altogether
replace enum fecap_scale_params frontend-stat-properties
replace symbol FE_SCALE_COUNTER frontend-stat-properties
replace symbol FE_SCALE_DECIBEL frontend-stat-properties
replace symbol FE_SCALE_NOT_AVAILABLE frontend-stat-properties
replace symbol FE_SCALE_RELATIVE frontend-stat-properties
# the same reference is used for both get and set ioctls
replace ioctl FE_SET_PROPERTY FE_GET_PROPERTY
# Ignore struct used only internally at Kernel
ignore struct dtv_cmds_h
# Typedefs that use the enum reference
replace typedef fe_sec_voltage_t fe-sec-voltage
# Replaces for flag constants
replace define FE_TUNE_MODE_ONESHOT fe_set_frontend_tune_mode
replace define LNA_AUTO dtv-lna
replace define NO_STREAM_ID_FILTER dtv-stream-id

46
Documentation/media/intro.rst Normal file
View File

@ -0,0 +1,46 @@
.. -*- coding: utf-8; mode: rst -*-
============
Introduction
============
This document covers the Linux Kernel to Userspace API's used by video
and radio streaming devices, including video cameras, analog and digital
TV receiver cards, AM/FM receiver cards, Software Defined Radio (SDR),
streaming capture and output devices, codec devices and remote controllers.
A typical media device hardware is shown at :ref:`typical_media_device`.
.. _typical_media_device:
.. figure:: media_api_files/typical_media_device.*
:alt: typical_media_device.svg
:align: center
Typical Media Device
The media infrastructure API was designed to control such devices. It is
divided into five parts.
1. The :ref:`first part <v4l2spec>` covers radio, video capture and output,
cameras, analog TV devices and codecs.
2. The :ref:`second part <dvbapi>` covers the API used for digital TV and
Internet reception via one of the several digital tv standards. While it is
called as DVB API, in fact it covers several different video standards
including DVB-T/T2, DVB-S/S2, DVB-C, ATSC, ISDB-T, ISDB-S, DTMB, etc. The
complete list of supported standards can be found at
:ref:`fe-delivery-system-t`.
3. The :ref:`third part <remote_controllers>` covers the Remote Controller API.
4. The :ref:`fourth part <media_controller>` covers the Media Controller API.
5. The :ref:`fifth part <cec>` covers the CEC (Consumer Electronics Control) API.
It should also be noted that a media device may also have audio components, like
mixers, PCM capture, PCM playback, etc, which are controlled via ALSA API. For
additional information and for the latest development code, see:
`https://linuxtv.org <https://linuxtv.org>`__. For discussing improvements,
reporting troubles, sending new drivers, etc, please mail to: `Linux Media
Mailing List (LMML) <http://vger.kernel.org/vger-lists.html#linux-media>`__.

132
Documentation/media/kapi/dtv-core.rst Normal file
View File

@ -0,0 +1,132 @@
Digital TV (DVB) devices
------------------------
Digital TV Common functions
---------------------------
.. kernel-doc:: drivers/media/dvb-core/dvb_math.h
.. kernel-doc:: drivers/media/dvb-core/dvb_ringbuffer.h
.. kernel-doc:: drivers/media/dvb-core/dvbdev.h
.. kernel-doc:: drivers/media/dvb-core/dvb_math.h
:export: drivers/media/dvb-core/dvb_math.c
.. kernel-doc:: drivers/media/dvb-core/dvbdev.h
:export: drivers/media/dvb-core/dvbdev.c
Digital TV Frontend kABI
------------------------
Digital TV Frontend
~~~~~~~~~~~~~~~~~~~
The Digital TV Frontend kABI defines a driver-internal interface for
registering low-level, hardware specific driver to a hardware independent
frontend layer. It is only of interest for Digital TV device driver writers.
The header file for this API is named dvb_frontend.h and located in
drivers/media/dvb-core.
Before using the Digital TV frontend core, the bridge driver should attach
the frontend demod, tuner and SEC devices and call
:c:func:`dvb_register_frontend()`,
in order to register the new frontend at the subsystem. At device
detach/removal, the bridge driver should call
:c:func:`dvb_unregister_frontend()` to
remove the frontend from the core and then :c:func:`dvb_frontend_detach()`
to free the memory allocated by the frontend drivers.
The drivers should also call :c:func:`dvb_frontend_suspend()` as part of
their handler for the :c:type:`device_driver`.\ ``suspend()``, and
:c:func:`dvb_frontend_resume()` as
part of their handler for :c:type:`device_driver`.\ ``resume()``.
A few other optional functions are provided to handle some special cases.
.. kernel-doc:: drivers/media/dvb-core/dvb_frontend.h
Digital TV Demux kABI
---------------------
Digital TV Demux
~~~~~~~~~~~~~~~~
The Kernel Digital TV Demux kABI defines a driver-internal interface for
registering low-level, hardware specific driver to a hardware independent
demux layer. It is only of interest for Digital TV device driver writers.
The header file for this kABI is named demux.h and located in
drivers/media/dvb-core.
The demux kABI should be implemented for each demux in the system. It is
used to select the TS source of a demux and to manage the demux resources.
When the demux client allocates a resource via the demux kABI, it receives
a pointer to the kABI of that resource.
Each demux receives its TS input from a DVB front-end or from memory, as
set via this demux kABI. In a system with more than one front-end, the kABI
can be used to select one of the DVB front-ends as a TS source for a demux,
unless this is fixed in the HW platform.
The demux kABI only controls front-ends regarding to their connections with
demuxes; the kABI used to set the other front-end parameters, such as
tuning, are devined via the Digital TV Frontend kABI.
The functions that implement the abstract interface demux should be defined
static or module private and registered to the Demux core for external
access. It is not necessary to implement every function in the struct
&dmx_demux. For example, a demux interface might support Section filtering,
but not PES filtering. The kABI client is expected to check the value of any
function pointer before calling the function: the value of ``NULL`` means
that the function is not available.
Whenever the functions of the demux API modify shared data, the
possibilities of lost update and race condition problems should be
addressed, e.g. by protecting parts of code with mutexes.
Note that functions called from a bottom half context must not sleep.
Even a simple memory allocation without using ``GFP_ATOMIC`` can result in a
kernel thread being put to sleep if swapping is needed. For example, the
Linux Kernel calls the functions of a network device interface from a
bottom half context. Thus, if a demux kABI function is called from network
device code, the function must not sleep.
Demux Callback API
------------------
Demux Callback
~~~~~~~~~~~~~~
This kernel-space API comprises the callback functions that deliver filtered
data to the demux client. Unlike the other DVB kABIs, these functions are
provided by the client and called from the demux code.
The function pointers of this abstract interface are not packed into a
structure as in the other demux APIs, because the callback functions are
registered and used independent of each other. As an example, it is possible
for the API client to provide several callback functions for receiving TS
packets and no callbacks for PES packets or sections.
The functions that implement the callback API need not be re-entrant: when
a demux driver calls one of these functions, the driver is not allowed to
call the function again before the original call returns. If a callback is
triggered by a hardware interrupt, it is recommended to use the Linux
bottom half mechanism or start a tasklet instead of making the callback
function call directly from a hardware interrupt.
This mechanism is implemented by :c:func:`dmx_ts_cb()` and :cpp:func:`dmx_section_cb()`
callbacks.
.. kernel-doc:: drivers/media/dvb-core/demux.h
Digital TV Conditional Access kABI
----------------------------------
.. kernel-doc:: drivers/media/dvb-core/dvb_ca_en50221.h

263
Documentation/media/kapi/mc-core.rst Normal file
View File

@ -0,0 +1,263 @@
Media Controller devices
------------------------
Media Controller
~~~~~~~~~~~~~~~~
The media controller userspace API is documented in
:ref:`the Media Controller uAPI book <media_controller>`. This document focus
on the kernel-side implementation of the media framework.
Abstract media device model
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Discovering a device internal topology, and configuring it at runtime, is one
of the goals of the media framework. To achieve this, hardware devices are
modelled as an oriented graph of building blocks called entities connected
through pads.
An entity is a basic media hardware building block. It can correspond to
a large variety of logical blocks such as physical hardware devices
(CMOS sensor for instance), logical hardware devices (a building block
in a System-on-Chip image processing pipeline), DMA channels or physical
connectors.
A pad is a connection endpoint through which an entity can interact with
other entities. Data (not restricted to video) produced by an entity
flows from the entity's output to one or more entity inputs. Pads should
not be confused with physical pins at chip boundaries.
A link is a point-to-point oriented connection between two pads, either
on the same entity or on different entities. Data flows from a source
pad to a sink pad.
Media device
^^^^^^^^^^^^
A media device is represented by a :c:type:`struct media_device <media_device>`
instance, defined in ``include/media/media-device.h``.
Allocation of the structure is handled by the media device driver, usually by
embedding the :c:type:`media_device` instance in a larger driver-specific
structure.
Drivers register media device instances by calling
:c:func:`__media_device_register()` via the macro ``media_device_register()``
and unregistered by calling :c:func:`media_device_unregister()`.
Entities
^^^^^^^^
Entities are represented by a :c:type:`struct media_entity <media_entity>`
instance, defined in ``include/media/media-entity.h``. The structure is usually
embedded into a higher-level structure, such as
:c:type:`v4l2_subdev` or :c:type:`video_device`
instances, although drivers can allocate entities directly.
Drivers initialize entity pads by calling
:c:func:`media_entity_pads_init()`.
Drivers register entities with a media device by calling
:c:func:`media_device_register_entity()`
and unregistred by calling
:c:func:`media_device_unregister_entity()`.
Interfaces
^^^^^^^^^^
Interfaces are represented by a
:c:type:`struct media_interface <media_interface>` instance, defined in
``include/media/media-entity.h``. Currently, only one type of interface is
defined: a device node. Such interfaces are represented by a
:c:type:`struct media_intf_devnode <media_intf_devnode>`.
Drivers initialize and create device node interfaces by calling
:c:func:`media_devnode_create()`
and remove them by calling:
:c:func:`media_devnode_remove()`.
Pads
^^^^
Pads are represented by a :c:type:`struct media_pad <media_pad>` instance,
defined in ``include/media/media-entity.h``. Each entity stores its pads in
a pads array managed by the entity driver. Drivers usually embed the array in
a driver-specific structure.
Pads are identified by their entity and their 0-based index in the pads
array.
Both information are stored in the :c:type:`struct media_pad`, making the
:c:type:`media_pad` pointer the canonical way to store and pass link references.
Pads have flags that describe the pad capabilities and state.
``MEDIA_PAD_FL_SINK`` indicates that the pad supports sinking data.
``MEDIA_PAD_FL_SOURCE`` indicates that the pad supports sourcing data.
.. note::
One and only one of ``MEDIA_PAD_FL_SINK`` or ``MEDIA_PAD_FL_SOURCE`` must
be set for each pad.
Links
^^^^^
Links are represented by a :c:type:`struct media_link <media_link>` instance,
defined in ``include/media/media-entity.h``. There are two types of links:
**1. pad to pad links**:
Associate two entities via their PADs. Each entity has a list that points
to all links originating at or targeting any of its pads.
A given link is thus stored twice, once in the source entity and once in
the target entity.
Drivers create pad to pad links by calling:
:c:func:`media_create_pad_link()` and remove with
:c:func:`media_entity_remove_links()`.
**2. interface to entity links**:
Associate one interface to a Link.
Drivers create interface to entity links by calling:
:c:func:`media_create_intf_link()` and remove with
:c:func:`media_remove_intf_links()`.
.. note::
Links can only be created after having both ends already created.
Links have flags that describe the link capabilities and state. The
valid values are described at :c:func:`media_create_pad_link()` and
:c:func:`media_create_intf_link()`.
Graph traversal
^^^^^^^^^^^^^^^
The media framework provides APIs to iterate over entities in a graph.
To iterate over all entities belonging to a media device, drivers can use
the media_device_for_each_entity macro, defined in
``include/media/media-device.h``.
.. code-block:: c
struct media_entity *entity;
media_device_for_each_entity(entity, mdev) {
// entity will point to each entity in turn
...
}
Drivers might also need to iterate over all entities in a graph that can be
reached only through enabled links starting at a given entity. The media
framework provides a depth-first graph traversal API for that purpose.
.. note::
Graphs with cycles (whether directed or undirected) are **NOT**
supported by the graph traversal API. To prevent infinite loops, the graph
traversal code limits the maximum depth to ``MEDIA_ENTITY_ENUM_MAX_DEPTH``,
currently defined as 16.
Drivers initiate a graph traversal by calling
:c:func:`media_entity_graph_walk_start()`
The graph structure, provided by the caller, is initialized to start graph
traversal at the given entity.
Drivers can then retrieve the next entity by calling
:c:func:`media_entity_graph_walk_next()`
When the graph traversal is complete the function will return ``NULL``.
Graph traversal can be interrupted at any moment. No cleanup function call
is required and the graph structure can be freed normally.
Helper functions can be used to find a link between two given pads, or a pad
connected to another pad through an enabled link
:c:func:`media_entity_find_link()` and
:c:func:`media_entity_remote_pad()`.
Use count and power handling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Due to the wide differences between drivers regarding power management
needs, the media controller does not implement power management. However,
the :c:type:`struct media_entity <media_entity>` includes a ``use_count``
field that media drivers
can use to track the number of users of every entity for power management
needs.
The :c:type:`media_entity<media_entity>`.\ ``use_count`` field is owned by
media drivers and must not be
touched by entity drivers. Access to the field must be protected by the
:c:type:`media_device`.\ ``graph_mutex`` lock.
Links setup
^^^^^^^^^^^
Link properties can be modified at runtime by calling
:c:func:`media_entity_setup_link()`.
Pipelines and media streams
^^^^^^^^^^^^^^^^^^^^^^^^^^^
When starting streaming, drivers must notify all entities in the pipeline to
prevent link states from being modified during streaming by calling
:c:func:`media_entity_pipeline_start()`.
The function will mark all entities connected to the given entity through
enabled links, either directly or indirectly, as streaming.
The :c:type:`struct media_pipeline <media_pipeline>` instance pointed to by
the pipe argument will be stored in every entity in the pipeline.
Drivers should embed the :c:type:`struct media_pipeline <media_pipeline>`
in higher-level pipeline structures and can then access the
pipeline through the :c:type:`struct media_entity <media_entity>`
pipe field.
Calls to :c:func:`media_entity_pipeline_start()` can be nested.
The pipeline pointer must be identical for all nested calls to the function.
:c:func:`media_entity_pipeline_start()` may return an error. In that case,
it will clean up any of the changes it did by itself.
When stopping the stream, drivers must notify the entities with
:c:func:`media_entity_pipeline_stop()`.
If multiple calls to :c:func:`media_entity_pipeline_start()` have been
made the same number of :c:func:`media_entity_pipeline_stop()` calls
are required to stop streaming.
The :c:type:`media_entity`.\ ``pipe`` field is reset to ``NULL`` on the last
nested stop call.
Link configuration will fail with ``-EBUSY`` by default if either end of the
link is a streaming entity. Links that can be modified while streaming must
be marked with the ``MEDIA_LNK_FL_DYNAMIC`` flag.
If other operations need to be disallowed on streaming entities (such as
changing entities configuration parameters) drivers can explicitly check the
media_entity stream_count field to find out if an entity is streaming. This
operation must be done with the media_device graph_mutex held.
Link validation
^^^^^^^^^^^^^^^
Link validation is performed by :c:func:`media_entity_pipeline_start()`
for any entity which has sink pads in the pipeline. The
:c:type:`media_entity`.\ ``link_validate()`` callback is used for that
purpose. In ``link_validate()`` callback, entity driver should check
that the properties of the source pad of the connected entity and its own
sink pad match. It is up to the type of the entity (and in the end, the
properties of the hardware) what matching actually means.
Subsystems should facilitate link validation by providing subsystem specific
helper functions to provide easy access for commonly needed information, and
in the end provide a way to use driver-specific callbacks.
.. kernel-doc:: include/media/media-device.h
.. kernel-doc:: include/media/media-devnode.h
.. kernel-doc:: include/media/media-entity.h

14
Documentation/media/kapi/rc-core.rst Normal file
View File

@ -0,0 +1,14 @@
Remote Controller devices
-------------------------
Remote Controller core
~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: include/media/rc-core.h
.. kernel-doc:: include/media/rc-map.h
LIRC
~~~~
.. kernel-doc:: include/media/lirc_dev.h

29
Documentation/media/kapi/v4l2-clocks.rst Normal file
View File

@ -0,0 +1,29 @@
V4L2 clocks
-----------
.. attention::
This is a temporary API and it shall be replaced by the generic
clock API, when the latter becomes widely available.
Many subdevices, like camera sensors, TV decoders and encoders, need a clock
signal to be supplied by the system. Often this clock is supplied by the
respective bridge device. The Linux kernel provides a Common Clock Framework for
this purpose. However, it is not (yet) available on all architectures. Besides,
the nature of the multi-functional (clock, data + synchronisation, I2C control)
connection of subdevices to the system might impose special requirements on the
clock API usage. E.g. V4L2 has to support clock provider driver unregistration
while a subdevice driver is holding a reference to the clock. For these reasons
a V4L2 clock helper API has been developed and is provided to bridge and
subdevice drivers.
The API consists of two parts: two functions to register and unregister a V4L2
clock source: v4l2_clk_register() and v4l2_clk_unregister() and calls to control
a clock object, similar to the respective generic clock API calls:
v4l2_clk_get(), v4l2_clk_put(), v4l2_clk_enable(), v4l2_clk_disable(),
v4l2_clk_get_rate(), and v4l2_clk_set_rate(). Clock suppliers have to provide
clock operations that will be called when clock users invoke respective API
methods.
It is expected that once the CCF becomes available on all relevant
architectures this API will be removed.

6
Documentation/media/kapi/v4l2-common.rst Normal file
View File

@ -0,0 +1,6 @@
V4L2 common functions and data structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/v4l2-common.h
.. kernel-doc:: include/media/v4l2-ioctl.h

162
Documentation/video4linux/v4l2-controls.txt → Documentation/media/kapi/v4l2-controls.rst
View File

@ -1,5 +1,8 @@
V4L2 Controls
=============
Introduction
============
------------
The V4L2 control API seems simple enough, but quickly becomes very hard to
implement correctly in drivers. But much of the code needed to handle controls
@ -26,7 +29,7 @@ for V4L2 drivers and struct v4l2_subdev for sub-device drivers.
Objects in the framework
========================
------------------------
There are two main objects:
@ -39,12 +42,14 @@ controls, possibly to controls owned by other handlers.
Basic usage for V4L2 and sub-device drivers
===========================================
-------------------------------------------
1) Prepare the driver:
1.1) Add the handler to your driver's top-level struct:
.. code-block:: none
struct foo_dev {
...
struct v4l2_ctrl_handler ctrl_handler;
@ -55,16 +60,20 @@ Basic usage for V4L2 and sub-device drivers
1.2) Initialize the handler:
.. code-block:: none
v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls);
The second argument is a hint telling the function how many controls this
handler is expected to handle. It will allocate a hashtable based on this
information. It is a hint only.
The second argument is a hint telling the function how many controls this
handler is expected to handle. It will allocate a hashtable based on this
information. It is a hint only.
1.3) Hook the control handler into the driver:
1.3.1) For V4L2 drivers do this:
.. code-block:: none
struct foo_dev {
...
struct v4l2_device v4l2_dev;
@ -75,15 +84,17 @@ Basic usage for V4L2 and sub-device drivers
foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler;
Where foo->v4l2_dev is of type struct v4l2_device.
Where foo->v4l2_dev is of type struct v4l2_device.
Finally, remove all control functions from your v4l2_ioctl_ops (if any):
vidioc_queryctrl, vidioc_query_ext_ctrl, vidioc_querymenu, vidioc_g_ctrl,
vidioc_s_ctrl, vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls.
Those are now no longer needed.
Finally, remove all control functions from your v4l2_ioctl_ops (if any):
vidioc_queryctrl, vidioc_query_ext_ctrl, vidioc_querymenu, vidioc_g_ctrl,
vidioc_s_ctrl, vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls.
Those are now no longer needed.
1.3.2) For sub-device drivers do this:
.. code-block:: none
struct foo_dev {
...
struct v4l2_subdev sd;
@ -94,10 +105,12 @@ Basic usage for V4L2 and sub-device drivers
foo->sd.ctrl_handler = &foo->ctrl_handler;
Where foo->sd is of type struct v4l2_subdev.
Where foo->sd is of type struct v4l2_subdev.
1.4) Clean up the handler at the end:
.. code-block:: none
v4l2_ctrl_handler_free(&foo->ctrl_handler);
@ -105,12 +118,16 @@ Basic usage for V4L2 and sub-device drivers
You add non-menu controls by calling v4l2_ctrl_new_std:
.. code-block:: none
struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl,
const struct v4l2_ctrl_ops *ops,
u32 id, s32 min, s32 max, u32 step, s32 def);
Menu and integer menu controls are added by calling v4l2_ctrl_new_std_menu:
.. code-block:: none
struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl,
const struct v4l2_ctrl_ops *ops,
u32 id, s32 max, s32 skip_mask, s32 def);
@ -118,6 +135,8 @@ Menu and integer menu controls are added by calling v4l2_ctrl_new_std_menu:
Menu controls with a driver specific menu are added by calling
v4l2_ctrl_new_std_menu_items:
.. code-block:: none
struct v4l2_ctrl *v4l2_ctrl_new_std_menu_items(
struct v4l2_ctrl_handler *hdl,
const struct v4l2_ctrl_ops *ops, u32 id, s32 max,
@ -126,12 +145,16 @@ v4l2_ctrl_new_std_menu_items:
Integer menu controls with a driver specific menu can be added by calling
v4l2_ctrl_new_int_menu:
.. code-block:: none
struct v4l2_ctrl *v4l2_ctrl_new_int_menu(struct v4l2_ctrl_handler *hdl,
const struct v4l2_ctrl_ops *ops,
u32 id, s32 max, s32 def, const s64 *qmenu_int);
These functions are typically called right after the v4l2_ctrl_handler_init:
.. code-block:: none
static const s64 exp_bias_qmenu[] = {
-2, -1, 0, 1, 2
};
@ -208,6 +231,8 @@ a bit faster that way.
3) Optionally force initial control setup:
.. code-block:: none
v4l2_ctrl_handler_setup(&foo->ctrl_handler);
This will call s_ctrl for all controls unconditionally. Effectively this
@ -217,12 +242,16 @@ the hardware are in sync.
4) Finally: implement the v4l2_ctrl_ops
.. code-block:: none
static const struct v4l2_ctrl_ops foo_ctrl_ops = {
.s_ctrl = foo_s_ctrl,
};
Usually all you need is s_ctrl:
.. code-block:: none
static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
{
struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
@ -247,16 +276,14 @@ to do any validation of control values, or implement QUERYCTRL, QUERY_EXT_CTRL
and QUERYMENU. And G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported.
==============================================================================
.. note::
The remainder of this document deals with more advanced topics and scenarios.
In practice the basic usage as described above is sufficient for most drivers.
===============================================================================
The remainder sections deal with more advanced controls topics and scenarios.
In practice the basic usage as described above is sufficient for most drivers.
Inheriting Controls
===================
-------------------
When a sub-device is registered with a V4L2 driver by calling
v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev
@ -271,21 +298,25 @@ of v4l2_device.
Accessing Control Values
========================
------------------------
The following union is used inside the control framework to access control
values:
union v4l2_ctrl_ptr {
s32 *p_s32;
s64 *p_s64;
char *p_char;
void *p;
};
.. code-block:: none
union v4l2_ctrl_ptr {
s32 *p_s32;
s64 *p_s64;
char *p_char;
void *p;
};
The v4l2_ctrl struct contains these fields that can be used to access both
current and new values:
.. code-block:: none
s32 val;
struct {
s32 val;
@ -297,6 +328,8 @@ current and new values:
If the control has a simple s32 type type, then:
.. code-block:: none
&ctrl->val == ctrl->p_new.p_s32
&ctrl->cur.val == ctrl->p_cur.p_s32
@ -319,6 +352,8 @@ exception is for controls that return a volatile register such as a signal
strength read-out that changes continuously. In that case you will need to
implement g_volatile_ctrl like this:
.. code-block:: none
static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl)
{
switch (ctrl->id) {
@ -335,6 +370,8 @@ changes.
To mark a control as volatile you have to set V4L2_CTRL_FLAG_VOLATILE:
.. code-block:: none
ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...);
if (ctrl)
ctrl->flags |= V4L2_CTRL_FLAG_VOLATILE;
@ -354,6 +391,8 @@ not to introduce deadlocks.
Outside of the control ops you have to go through to helper functions to get
or set a single control value safely in your driver:
.. code-block:: none
s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl);
int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val);
@ -363,6 +402,8 @@ will result in a deadlock since these helpers lock the handler as well.
You can also take the handler lock yourself:
.. code-block:: none
mutex_lock(&state->ctrl_handler.lock);
pr_info("String value is '%s'\n", ctrl1->p_cur.p_char);
pr_info("Integer value is '%s'\n", ctrl2->cur.val);
@ -370,10 +411,12 @@ You can also take the handler lock yourself:
Menu Controls
=============
-------------
The v4l2_ctrl struct contains this union:
.. code-block:: none
union {
u32 step;
u32 menu_skip_mask;
@ -396,10 +439,12 @@ control, or by calling v4l2_ctrl_new_std_menu().
Custom Controls
===============
---------------
Driver specific controls can be created using v4l2_ctrl_new_custom():
.. code-block:: none
static const struct v4l2_ctrl_config ctrl_filter = {
.ops = &ctrl_custom_ops,
.id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER,
@ -422,7 +467,7 @@ control and will fill in the name, type and flags fields accordingly.
Active and Grabbed Controls
===========================
---------------------------
If you get more complex relationships between controls, then you may have to
activate and deactivate controls. For example, if the Chroma AGC control is
@ -446,16 +491,18 @@ starts or stops streaming.
Control Clusters
================
----------------
By default all controls are independent from the others. But in more
complex scenarios you can get dependencies from one control to another.
In that case you need to 'cluster' them:
.. code-block:: none
struct foo {
struct v4l2_ctrl_handler ctrl_handler;
#define AUDIO_CL_VOLUME (0)
#define AUDIO_CL_MUTE (1)
#define AUDIO_CL_VOLUME (0)
#define AUDIO_CL_MUTE (1)
struct v4l2_ctrl *audio_cluster[2];
...
};
@ -474,6 +521,8 @@ composite control. Similar to how a 'struct' works in C.
So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set
all two controls belonging to the audio_cluster:
.. code-block:: none
static int foo_s_ctrl(struct v4l2_ctrl *ctrl)
{
struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler);
@ -494,12 +543,16 @@ all two controls belonging to the audio_cluster:
In the example above the following are equivalent for the VOLUME case:
.. code-block:: none
ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME]
ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE]
In practice using cluster arrays like this becomes very tiresome. So instead
the following equivalent method is used:
.. code-block:: none
struct {
/* audio cluster */
struct v4l2_ctrl *volume;
@ -510,6 +563,8 @@ The anonymous struct is used to clearly 'cluster' these two control pointers,
but it serves no other purpose. The effect is the same as creating an
array with two control pointers. So you can just do:
.. code-block:: none
state->volume = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
state->mute = v4l2_ctrl_new_std(&state->ctrl_handler, ...);
v4l2_ctrl_cluster(2, &state->volume);
@ -539,7 +594,7 @@ The 'is_new' flag is always 1 when called from v4l2_ctrl_handler_setup().
Handling autogain/gain-type Controls with Auto Clusters
=======================================================
-------------------------------------------------------
A common type of control cluster is one that handles 'auto-foo/foo'-type
controls. Typical examples are autogain/gain, autoexposure/exposure,
@ -564,8 +619,10 @@ changing that control affects the control flags of the manual controls.
In order to simplify this a special variation of v4l2_ctrl_cluster was
introduced:
void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
u8 manual_val, bool set_volatile);
.. code-block:: none
void v4l2_ctrl_auto_cluster(unsigned ncontrols, struct v4l2_ctrl **controls,
u8 manual_val, bool set_volatile);
The first two arguments are identical to v4l2_ctrl_cluster. The third argument
tells the framework which value switches the cluster into manual mode. The
@ -582,7 +639,7 @@ flag and volatile handling.
VIDIOC_LOG_STATUS Support
=========================
-------------------------
This ioctl allow you to dump the current status of a driver to the kernel log.
The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the
@ -592,7 +649,7 @@ for you.
Different Handlers for Different Video Nodes
============================================
--------------------------------------------
Usually the V4L2 driver has just one control handler that is global for
all video nodes. But you can also specify different control handlers for
@ -617,6 +674,8 @@ of another handler (e.g. for a video device node), then you should first add
the controls to the first handler, add the other controls to the second
handler and finally add the first handler to the second. For example:
.. code-block:: none
v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...);
v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
@ -629,6 +688,8 @@ all controls.
Or you can add specific controls to a handler:
.. code-block:: none
volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...);
v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...);
v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...);
@ -636,6 +697,8 @@ Or you can add specific controls to a handler:
What you should not do is make two identical controls for two handlers.
For example:
.. code-block:: none
v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...);
v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_AUDIO_MUTE, ...);
@ -645,7 +708,7 @@ can twiddle.
Finding Controls
================
----------------
Normally you have created the controls yourself and you can store the struct
v4l2_ctrl pointer into your own struct.
@ -655,6 +718,8 @@ not own. For example, if you have to find a volume control from a subdev.
You can do that by calling v4l2_ctrl_find:
.. code-block:: none
struct v4l2_ctrl *volume;
volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME);
@ -662,6 +727,8 @@ You can do that by calling v4l2_ctrl_find:
Since v4l2_ctrl_find will lock the handler you have to be careful where you
use it. For example, this is not a good idea:
.. code-block:: none
struct v4l2_ctrl_handler ctrl_handler;
v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...);
@ -669,6 +736,8 @@ use it. For example, this is not a good idea:
...and in video_ops.s_ctrl:
.. code-block:: none
case V4L2_CID_BRIGHTNESS:
contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST);
...
@ -680,7 +749,7 @@ It is recommended not to use this function from inside the control ops.
Inheriting Controls
===================
-------------------
When one control handler is added to another using v4l2_ctrl_add_handler, then
by default all controls from one are merged to the other. But a subdev might
@ -689,6 +758,8 @@ not when it is used in consumer-level hardware. In that case you want to keep
those low-level controls local to the subdev. You can do this by simply
setting the 'is_private' flag of the control to 1:
.. code-block:: none
static const struct v4l2_ctrl_config ctrl_private = {
.ops = &ctrl_custom_ops,
.id = V4L2_CID_...,
@ -705,7 +776,7 @@ These controls will now be skipped when v4l2_ctrl_add_handler is called.
V4L2_CTRL_TYPE_CTRL_CLASS Controls
==================================
----------------------------------
Controls of this type can be used by GUIs to get the name of the control class.
A fully featured GUI can make a dialog with multiple tabs with each tab
@ -718,14 +789,16 @@ class is added.
Adding Notify Callbacks
=======================
-----------------------
Sometimes the platform or bridge driver needs to be notified when a control
from a sub-device driver changes. You can set a notify callback by calling
this function:
void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl,
void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv);
.. code-block:: none
void v4l2_ctrl_notify(struct v4l2_ctrl *ctrl,
void (*notify)(struct v4l2_ctrl *ctrl, void *priv), void *priv);
Whenever the give control changes value the notify callback will be called
with a pointer to the control and the priv pointer that was passed with
@ -734,3 +807,8 @@ notify function is called.
There can be only one notify function per control handler. Any attempt
to set another notify function will cause a WARN_ON.
v4l2_ctrl functions and data structures
---------------------------------------
.. kernel-doc:: include/media/v4l2-ctrls.h

26
Documentation/media/kapi/v4l2-core.rst Normal file
View File

@ -0,0 +1,26 @@
Video2Linux devices
-------------------
.. toctree::
:maxdepth: 1
v4l2-intro
v4l2-dev
v4l2-device
v4l2-fh
v4l2-subdev
v4l2-event
v4l2-controls
v4l2-videobuf
v4l2-videobuf2
v4l2-clocks
v4l2-dv-timings
v4l2-flash-led-class
v4l2-mc
v4l2-mediabus
v4l2-mem2mem
v4l2-of
v4l2-rect
v4l2-tuner
v4l2-common
v4l2-tveeprom

363
Documentation/media/kapi/v4l2-dev.rst Normal file
View File

@ -0,0 +1,363 @@
Video device' s internal representation
=======================================
The actual device nodes in the ``/dev`` directory are created using the
:c:type:`video_device` struct (``v4l2-dev.h``). This struct can either be
allocated dynamically or embedded in a larger struct.
To allocate it dynamically use :c:func:`video_device_alloc`:
.. code-block:: c
struct video_device *vdev = video_device_alloc();
if (vdev == NULL)
return -ENOMEM;
vdev->release = video_device_release;
If you embed it in a larger struct, then you must set the ``release()``
callback to your own function:
.. code-block:: c
struct video_device *vdev = &my_vdev->vdev;
vdev->release = my_vdev_release;
The ``release()`` callback must be set and it is called when the last user
of the video device exits.
The default :c:func:`video_device_release` callback currently
just calls ``kfree`` to free the allocated memory.
There is also a ::c:func:`video_device_release_empty` function that does
nothing (is empty) and should be used if the struct is embedded and there
is nothing to do when it is released.
You should also set these fields of :c:type:`video_device`:
- :c:type:`video_device`->v4l2_dev: must be set to the :c:type:`v4l2_device`
parent device.
- :c:type:`video_device`->name: set to something descriptive and unique.
- :c:type:`video_device`->vfl_dir: set this to ``VFL_DIR_RX`` for capture
devices (``VFL_DIR_RX`` has value 0, so this is normally already the
default), set to ``VFL_DIR_TX`` for output devices and ``VFL_DIR_M2M`` for mem2mem (codec) devices.
- :c:type:`video_device`->fops: set to the :c:type:`v4l2_file_operations`
struct.
- :c:type:`video_device`->ioctl_ops: if you use the :c:type:`v4l2_ioctl_ops`
to simplify ioctl maintenance (highly recommended to use this and it might
become compulsory in the future!), then set this to your
:c:type:`v4l2_ioctl_ops` struct. The :c:type:`video_device`->vfl_type and
:c:type:`video_device`->vfl_dir fields are used to disable ops that do not
match the type/dir combination. E.g. VBI ops are disabled for non-VBI nodes,
and output ops are disabled for a capture device. This makes it possible to
provide just one :c:type:`v4l2_ioctl_ops struct` for both vbi and
video nodes.
- :c:type:`video_device`->lock: leave to ``NULL`` if you want to do all the
locking in the driver. Otherwise you give it a pointer to a struct
``mutex_lock`` and before the :c:type:`video_device`->unlocked_ioctl
file operation is called this lock will be taken by the core and released
afterwards. See the next section for more details.
- :c:type:`video_device`->queue: a pointer to the struct :c:type:`vb2_queue`
associated with this device node.
If queue is not ``NULL``, and queue->lock is not ``NULL``, then queue->lock
is used for the queuing ioctls (``VIDIOC_REQBUFS``, ``CREATE_BUFS``,
``QBUF``, ``DQBUF``, ``QUERYBUF``, ``PREPARE_BUF``, ``STREAMON`` and
``STREAMOFF``) instead of the lock above.
That way the :ref:`vb2 <vb2_framework>` queuing framework does not have
to wait for other ioctls. This queue pointer is also used by the
:ref:`vb2 <vb2_framework>` helper functions to check for
queuing ownership (i.e. is the filehandle calling it allowed to do the
operation).
- :c:type:`video_device`->prio: keeps track of the priorities. Used to
implement ``VIDIOC_G_PRIORITY`` and ``VIDIOC_S_PRIORITY``.
If left to ``NULL``, then it will use the struct :c:type:`v4l2_prio_state`
in :c:type:`v4l2_device`. If you want to have a separate priority state per
(group of) device node(s), then you can point it to your own struct
:c:type:`v4l2_prio_state`.
- :c:type:`video_device`->dev_parent: you only set this if v4l2_device was
registered with ``NULL`` as the parent ``device`` struct. This only happens
in cases where one hardware device has multiple PCI devices that all share
the same :c:type:`v4l2_device` core.
The cx88 driver is an example of this: one core :c:type:`v4l2_device` struct,
but it is used by both a raw video PCI device (cx8800) and a MPEG PCI device
(cx8802). Since the :c:type:`v4l2_device` cannot be associated with two PCI
devices at the same time it is setup without a parent device. But when the
struct :c:type:`video_device` is initialized you **do** know which parent
PCI device to use and so you set ``dev_device`` to the correct PCI device.
If you use :c:type:`v4l2_ioctl_ops`, then you should set
:c:type:`video_device`->unlocked_ioctl to :c:func:`video_ioctl2` in your
:c:type:`v4l2_file_operations` struct.
In some cases you want to tell the core that a function you had specified in
your :c:type:`v4l2_ioctl_ops` should be ignored. You can mark such ioctls by
calling this function before :c:func:`video_register_device` is called:
:c:func:`v4l2_disable_ioctl <v4l2_disable_ioctl>`
(:c:type:`vdev <video_device>`, cmd).
This tends to be needed if based on external factors (e.g. which card is
being used) you want to turns off certain features in :c:type:`v4l2_ioctl_ops`
without having to make a new struct.
The :c:type:`v4l2_file_operations` struct is a subset of file_operations.
The main difference is that the inode argument is omitted since it is never
used.
If integration with the media framework is needed, you must initialize the
:c:type:`media_entity` struct embedded in the :c:type:`video_device` struct
(entity field) by calling :c:func:`media_entity_pads_init`:
.. code-block:: c
struct media_pad *pad = &my_vdev->pad;
int err;
err = media_entity_pads_init(&vdev->entity, 1, pad);
The pads array must have been previously initialized. There is no need to
manually set the struct media_entity type and name fields.
A reference to the entity will be automatically acquired/released when the
video device is opened/closed.
ioctls and locking
------------------
The V4L core provides optional locking services. The main service is the
lock field in struct :c:type:`video_device`, which is a pointer to a mutex.
If you set this pointer, then that will be used by unlocked_ioctl to
serialize all ioctls.
If you are using the :ref:`videobuf2 framework <vb2_framework>`, then there
is a second lock that you can set: :c:type:`video_device`->queue->lock. If
set, then this lock will be used instead of :c:type:`video_device`->lock
to serialize all queuing ioctls (see the previous section
for the full list of those ioctls).
The advantage of using a different lock for the queuing ioctls is that for some
drivers (particularly USB drivers) certain commands such as setting controls
can take a long time, so you want to use a separate lock for the buffer queuing
ioctls. That way your ``VIDIOC_DQBUF`` doesn't stall because the driver is busy
changing the e.g. exposure of the webcam.
Of course, you can always do all the locking yourself by leaving both lock
pointers at ``NULL``.
If you use the old :ref:`videobuf framework <vb_framework>` then you must
pass the :c:type:`video_device`->lock to the videobuf queue initialize
function: if videobuf has to wait for a frame to arrive, then it will
temporarily unlock the lock and relock it afterwards. If your driver also
waits in the code, then you should do the same to allow other
processes to access the device node while the first process is waiting for
something.
In the case of :ref:`videobuf2 <vb2_framework>` you will need to implement the
``wait_prepare()`` and ``wait_finish()`` callbacks to unlock/lock if applicable.
If you use the ``queue->lock`` pointer, then you can use the helper functions
:c:func:`vb2_ops_wait_prepare` and :cpp:func:`vb2_ops_wait_finish`.
The implementation of a hotplug disconnect should also take the lock from
:c:type:`video_device` before calling v4l2_device_disconnect. If you are also
using :c:type:`video_device`->queue->lock, then you have to first lock
:c:type:`video_device`->queue->lock followed by :c:type:`video_device`->lock.
That way you can be sure no ioctl is running when you call
:c:type:`v4l2_device_disconnect`.
Video device registration
-------------------------
Next you register the video device with :c:func:`video_register_device`.
This will create the character device for you.
.. code-block:: c
err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
if (err) {
video_device_release(vdev); /* or kfree(my_vdev); */
return err;
}
If the :c:type:`v4l2_device` parent device has a not ``NULL`` mdev field,
the video device entity will be automatically registered with the media
device.
Which device is registered depends on the type argument. The following
types exist:
- ``VFL_TYPE_GRABBER``: ``/dev/videoX`` for video input/output devices
- ``VFL_TYPE_VBI``: ``/dev/vbiX`` for vertical blank data (i.e. closed captions, teletext)
- ``VFL_TYPE_RADIO``: ``/dev/radioX`` for radio tuners
- ``VFL_TYPE_SDR``: ``/dev/swradioX`` for Software Defined Radio tuners
The last argument gives you a certain amount of control over the device
device node number used (i.e. the X in ``videoX``). Normally you will pass -1
to let the v4l2 framework pick the first free number. But sometimes users
want to select a specific node number. It is common that drivers allow
the user to select a specific device node number through a driver module
option. That number is then passed to this function and video_register_device
will attempt to select that device node number. If that number was already
in use, then the next free device node number will be selected and it
will send a warning to the kernel log.
Another use-case is if a driver creates many devices. In that case it can
be useful to place different video devices in separate ranges. For example,
video capture devices start at 0, video output devices start at 16.
So you can use the last argument to specify a minimum device node number
and the v4l2 framework will try to pick the first free number that is equal
or higher to what you passed. If that fails, then it will just pick the
first free number.
Since in this case you do not care about a warning about not being able
to select the specified device node number, you can call the function
:c:func:`video_register_device_no_warn` instead.
Whenever a device node is created some attributes are also created for you.
If you look in ``/sys/class/video4linux`` you see the devices. Go into e.g.
``video0`` and you will see 'name', 'dev_debug' and 'index' attributes. The
'name' attribute is the 'name' field of the video_device struct. The
'dev_debug' attribute can be used to enable core debugging. See the next
section for more detailed information on this.
The 'index' attribute is the index of the device node: for each call to
:c:func:`video_register_device()` the index is just increased by 1. The
first video device node you register always starts with index 0.
Users can setup udev rules that utilize the index attribute to make fancy
device names (e.g. '``mpegX``' for MPEG video capture device nodes).
After the device was successfully registered, then you can use these fields:
- :c:type:`video_device`->vfl_type: the device type passed to
:c:func:`video_register_device`.
- :c:type:`video_device`->minor: the assigned device minor number.
- :c:type:`video_device`->num: the device node number (i.e. the X in
``videoX``).
- :c:type:`video_device`->index: the device index number.
If the registration failed, then you need to call
:c:func:`video_device_release` to free the allocated :c:type:`video_device`
struct, or free your own struct if the :c:type:`video_device` was embedded in
it. The ``vdev->release()`` callback will never be called if the registration
failed, nor should you ever attempt to unregister the device if the
registration failed.
video device debugging
----------------------
The 'dev_debug' attribute that is created for each video, vbi, radio or swradio
device in ``/sys/class/video4linux/<devX>/`` allows you to enable logging of
file operations.
It is a bitmask and the following bits can be set:
===== ================================================================
Mask Description
===== ================================================================
0x01 Log the ioctl name and error code. VIDIOC_(D)QBUF ioctls are
only logged if bit 0x08 is also set.
0x02 Log the ioctl name arguments and error code. VIDIOC_(D)QBUF
ioctls are
only logged if bit 0x08 is also set.
0x04 Log the file operations open, release, read, write, mmap and
get_unmapped_area. The read and write operations are only
logged if bit 0x08 is also set.
0x08 Log the read and write file operations and the VIDIOC_QBUF and
VIDIOC_DQBUF ioctls.
0x10 Log the poll file operation.
===== ================================================================
Video device cleanup
--------------------
When the video device nodes have to be removed, either during the unload
of the driver or because the USB device was disconnected, then you should
unregister them with:
:c:func:`video_unregister_device`
(:c:type:`vdev <video_device>`);
This will remove the device nodes from sysfs (causing udev to remove them
from ``/dev``).
After :c:func:`video_unregister_device` returns no new opens can be done.
However, in the case of USB devices some application might still have one of
these device nodes open. So after the unregister all file operations (except
release, of course) will return an error as well.
When the last user of the video device node exits, then the ``vdev->release()``
callback is called and you can do the final cleanup there.
Don't forget to cleanup the media entity associated with the video device if
it has been initialized:
:c:func:`media_entity_cleanup <media_entity_cleanup>`
(&vdev->entity);
This can be done from the release callback.
helper functions
----------------
There are a few useful helper functions:
- file and :c:type:`video_device` private data
You can set/get driver private data in the video_device struct using:
:c:func:`video_get_drvdata <video_get_drvdata>`
(:c:type:`vdev <video_device>`);
:c:func:`video_set_drvdata <video_set_drvdata>`
(:c:type:`vdev <video_device>`);
Note that you can safely call :c:func:`video_set_drvdata` before calling
:c:func:`video_register_device`.
And this function:
:c:func:`video_devdata <video_devdata>`
(struct file \*file);
returns the video_device belonging to the file struct.
The :c:func:`video_devdata` function combines :cpp:func:`video_get_drvdata`
with :c:func:`video_devdata`:
:c:func:`video_drvdata <video_drvdata>`
(struct file \*file);
You can go from a :c:type:`video_device` struct to the v4l2_device struct using:
.. code-block:: c
struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
- Device node name
The :c:type:`video_device` node kernel name can be retrieved using:
:c:func:`video_device_node_name <video_device_node_name>`
(:c:type:`vdev <video_device>`);
The name is used as a hint by userspace tools such as udev. The function
should be used where possible instead of accessing the video_device::num and
video_device::minor fields.
video_device functions and data structures
------------------------------------------
.. kernel-doc:: include/media/v4l2-dev.h

144
Documentation/media/kapi/v4l2-device.rst Normal file
View File

@ -0,0 +1,144 @@
V4L2 device instance
--------------------
Each device instance is represented by a struct :c:type:`v4l2_device`.
Very simple devices can just allocate this struct, but most of the time you
would embed this struct inside a larger struct.
You must register the device instance by calling:
:c:func:`v4l2_device_register <v4l2_device_register>`
(dev, :c:type:`v4l2_dev <v4l2_device>`).
Registration will initialize the :c:type:`v4l2_device` struct. If the
dev->driver_data field is ``NULL``, it will be linked to
:c:type:`v4l2_dev <v4l2_device>` argument.
Drivers that want integration with the media device framework need to set
dev->driver_data manually to point to the driver-specific device structure
that embed the struct :c:type:`v4l2_device` instance. This is achieved by a
``dev_set_drvdata()`` call before registering the V4L2 device instance.
They must also set the struct :c:type:`v4l2_device` mdev field to point to a
properly initialized and registered :c:type:`media_device` instance.
If :c:type:`v4l2_dev <v4l2_device>`\ ->name is empty then it will be set to a
value derived from dev (driver name followed by the bus_id, to be precise).
If you set it up before calling :c:func:`v4l2_device_register` then it will
be untouched. If dev is ``NULL``, then you **must** setup
:c:type:`v4l2_dev <v4l2_device>`\ ->name before calling
:c:func:`v4l2_device_register`.
You can use :c:func:`v4l2_device_set_name` to set the name based on a driver
name and a driver-global atomic_t instance. This will generate names like
``ivtv0``, ``ivtv1``, etc. If the name ends with a digit, then it will insert
a dash: ``cx18-0``, ``cx18-1``, etc. This function returns the instance number.
The first ``dev`` argument is normally the ``struct device`` pointer of a
``pci_dev``, ``usb_interface`` or ``platform_device``. It is rare for dev to
be ``NULL``, but it happens with ISA devices or when one device creates
multiple PCI devices, thus making it impossible to associate
:c:type:`v4l2_dev <v4l2_device>` with a particular parent.
You can also supply a ``notify()`` callback that can be called by sub-devices
to notify you of events. Whether you need to set this depends on the
sub-device. Any notifications a sub-device supports must be defined in a header
in ``include/media/subdevice.h``.
V4L2 devices are unregistered by calling:
:c:func:`v4l2_device_unregister`
(:c:type:`v4l2_dev <v4l2_device>`).
If the dev->driver_data field points to :c:type:`v4l2_dev <v4l2_device>`,
it will be reset to ``NULL``. Unregistering will also automatically unregister
all subdevs from the device.
If you have a hotpluggable device (e.g. a USB device), then when a disconnect
happens the parent device becomes invalid. Since :c:type:`v4l2_device` has a
pointer to that parent device it has to be cleared as well to mark that the
parent is gone. To do this call:
:c:func:`v4l2_device_disconnect`
(:c:type:`v4l2_dev <v4l2_device>`).
This does *not* unregister the subdevs, so you still need to call the
:c:func:`v4l2_device_unregister` function for that. If your driver is not
hotpluggable, then there is no need to call :c:func:`v4l2_device_disconnect`.
Sometimes you need to iterate over all devices registered by a specific
driver. This is usually the case if multiple device drivers use the same
hardware. E.g. the ivtvfb driver is a framebuffer driver that uses the ivtv
hardware. The same is true for alsa drivers for example.
You can iterate over all registered devices as follows:
.. code-block:: c
static int callback(struct device *dev, void *p)
{
struct v4l2_device *v4l2_dev = dev_get_drvdata(dev);
/* test if this device was inited */
if (v4l2_dev == NULL)
return 0;
...
return 0;
}
int iterate(void *p)
{
struct device_driver *drv;
int err;
/* Find driver 'ivtv' on the PCI bus.
pci_bus_type is a global. For USB busses use usb_bus_type. */
drv = driver_find("ivtv", &pci_bus_type);
/* iterate over all ivtv device instances */
err = driver_for_each_device(drv, NULL, p, callback);
put_driver(drv);
return err;
}
Sometimes you need to keep a running counter of the device instance. This is
commonly used to map a device instance to an index of a module option array.
The recommended approach is as follows:
.. code-block:: c
static atomic_t drv_instance = ATOMIC_INIT(0);
static int drv_probe(struct pci_dev *pdev, const struct pci_device_id *pci_id)
{
...
state->instance = atomic_inc_return(&drv_instance) - 1;
}
If you have multiple device nodes then it can be difficult to know when it is
safe to unregister :c:type:`v4l2_device` for hotpluggable devices. For this
purpose :c:type:`v4l2_device` has refcounting support. The refcount is
increased whenever :c:func:`video_register_device` is called and it is
decreased whenever that device node is released. When the refcount reaches
zero, then the :c:type:`v4l2_device` release() callback is called. You can
do your final cleanup there.
If other device nodes (e.g. ALSA) are created, then you can increase and
decrease the refcount manually as well by calling:
:c:func:`v4l2_device_get`
(:c:type:`v4l2_dev <v4l2_device>`).
or:
:c:func:`v4l2_device_put`
(:c:type:`v4l2_dev <v4l2_device>`).
Since the initial refcount is 1 you also need to call
:c:func:`v4l2_device_put` in the ``disconnect()`` callback (for USB devices)
or in the ``remove()`` callback (for e.g. PCI devices), otherwise the refcount
will never reach 0.
v4l2_device functions and data structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/v4l2-device.h

4
Documentation/media/kapi/v4l2-dv-timings.rst Normal file
View File

@ -0,0 +1,4 @@
V4L2 DV Timings functions
^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/v4l2-dv-timings.h

137
Documentation/media/kapi/v4l2-event.rst Normal file
View File

@ -0,0 +1,137 @@
V4L2 events
-----------
The V4L2 events provide a generic way to pass events to user space.
The driver must use :c:type:`v4l2_fh` to be able to support V4L2 events.
Events are defined by a type and an optional ID. The ID may refer to a V4L2
object such as a control ID. If unused, then the ID is 0.
When the user subscribes to an event the driver will allocate a number of
kevent structs for that event. So every (type, ID) event tuple will have
its own set of kevent structs. This guarantees that if a driver is generating
lots of events of one type in a short time, then that will not overwrite
events of another type.
But if you get more events of one type than the number of kevents that were
reserved, then the oldest event will be dropped and the new one added.
Furthermore, the internal struct :c:type:`v4l2_subscribed_event` has
``merge()`` and ``replace()`` callbacks which drivers can set. These
callbacks are called when a new event is raised and there is no more room.
The ``replace()`` callback allows you to replace the payload of the old event
with that of the new event, merging any relevant data from the old payload
into the new payload that replaces it. It is called when this event type has
only one kevent struct allocated. The ``merge()`` callback allows you to merge
the oldest event payload into that of the second-oldest event payload. It is
called when there are two or more kevent structs allocated.
This way no status information is lost, just the intermediate steps leading
up to that state.
A good example of these ``replace``/``merge`` callbacks is in v4l2-event.c:
``ctrls_replace()`` and ``ctrls_merge()`` callbacks for the control event.
.. note::
these callbacks can be called from interrupt context, so they must
be fast.
In order to queue events to video device, drivers should call:
:c:func:`v4l2_event_queue <v4l2_event_queue>`
(:c:type:`vdev <video_device>`, :ref:`ev <v4l2-event>`)
The driver's only responsibility is to fill in the type and the data fields.
The other fields will be filled in by V4L2.
Event subscription
~~~~~~~~~~~~~~~~~~
Subscribing to an event is via:
:c:func:`v4l2_event_subscribe <v4l2_event_subscribe>`
(:c:type:`fh <v4l2_fh>`, :ref:`sub <v4l2-event-subscription>` ,
elems, :c:type:`ops <v4l2_subscribed_event_ops>`)
This function is used to implement :c:type:`video_device`->
:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_subscribe_event``,
but the driver must check first if the driver is able to produce events
with specified event id, and then should call
:c:func:`v4l2_event_subscribe` to subscribe the event.
The elems argument is the size of the event queue for this event. If it is 0,
then the framework will fill in a default value (this depends on the event
type).
The ops argument allows the driver to specify a number of callbacks:
======== ==============================================================
Callback Description
======== ==============================================================
add called when a new listener gets added (subscribing to the same
event twice will only cause this callback to get called once)
del called when a listener stops listening
replace replace event 'old' with event 'new'.
merge merge event 'old' into event 'new'.
======== ==============================================================
All 4 callbacks are optional, if you don't want to specify any callbacks
the ops argument itself maybe ``NULL``.
Unsubscribing an event
~~~~~~~~~~~~~~~~~~~~~~
Unsubscribing to an event is via:
:c:func:`v4l2_event_unsubscribe <v4l2_event_unsubscribe>`
(:c:type:`fh <v4l2_fh>`, :ref:`sub <v4l2-event-subscription>`)
This function is used to implement :c:type:`video_device`->
:c:type:`ioctl_ops <v4l2_ioctl_ops>`-> ``vidioc_unsubscribe_event``.
A driver may call :c:func:`v4l2_event_unsubscribe` directly unless it
wants to be involved in unsubscription process.
The special type ``V4L2_EVENT_ALL`` may be used to unsubscribe all events. The
drivers may want to handle this in a special way.
Check if there's a pending event
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Checking if there's a pending event is via:
:c:func:`v4l2_event_pending <v4l2_event_pending>`
(:c:type:`fh <v4l2_fh>`)
This function returns the number of pending events. Useful when implementing
poll.
How events work
~~~~~~~~~~~~~~~
Events are delivered to user space through the poll system call. The driver
can use :c:type:`v4l2_fh`->wait (a wait_queue_head_t) as the argument for
``poll_wait()``.
There are standard and private events. New standard events must use the
smallest available event type. The drivers must allocate their events from
their own class starting from class base. Class base is
``V4L2_EVENT_PRIVATE_START`` + n * 1000 where n is the lowest available number.
The first event type in the class is reserved for future use, so the first
available event type is 'class base + 1'.
An example on how the V4L2 events may be used can be found in the OMAP
3 ISP driver (``drivers/media/platform/omap3isp``).
A subdev can directly send an event to the :c:type:`v4l2_device` notify
function with ``V4L2_DEVICE_NOTIFY_EVENT``. This allows the bridge to map
the subdev that sends the event to the video node(s) associated with the
subdev that need to be informed about such an event.
V4L2 event functions and data structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/v4l2-event.h

139
Documentation/media/kapi/v4l2-fh.rst Normal file
View File

@ -0,0 +1,139 @@
V4L2 File handlers
------------------
struct :c:type:`v4l2_fh` provides a way to easily keep file handle specific
data that is used by the V4L2 framework.
.. attention::
New drivers must use struct :c:type:`v4l2_fh`
since it is also used to implement priority handling
(:ref:`VIDIOC_G_PRIORITY`).
The users of :c:type:`v4l2_fh` (in the V4L2 framework, not the driver) know
whether a driver uses :c:type:`v4l2_fh` as its ``file->private_data`` pointer
by testing the ``V4L2_FL_USES_V4L2_FH`` bit in :c:type:`video_device`->flags.
This bit is set whenever :c:func:`v4l2_fh_init` is called.
struct :c:type:`v4l2_fh` is allocated as a part of the driver's own file handle
structure and ``file->private_data`` is set to it in the driver's ``open()``
function by the driver.
In many cases the struct :c:type:`v4l2_fh` will be embedded in a larger
structure. In that case you should call:
#) :c:func:`v4l2_fh_init` and :cpp:func:`v4l2_fh_add` in ``open()``
#) :c:func:`v4l2_fh_del` and :cpp:func:`v4l2_fh_exit` in ``release()``
Drivers can extract their own file handle structure by using the container_of
macro.
Example:
.. code-block:: c
struct my_fh {
int blah;
struct v4l2_fh fh;
};
...
int my_open(struct file *file)
{
struct my_fh *my_fh;
struct video_device *vfd;
int ret;
...
my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
...
v4l2_fh_init(&my_fh->fh, vfd);
...
file->private_data = &my_fh->fh;
v4l2_fh_add(&my_fh->fh);
return 0;
}
int my_release(struct file *file)
{
struct v4l2_fh *fh = file->private_data;
struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
...
v4l2_fh_del(&my_fh->fh);
v4l2_fh_exit(&my_fh->fh);
kfree(my_fh);
return 0;
}
Below is a short description of the :c:type:`v4l2_fh` functions used:
:c:func:`v4l2_fh_init <v4l2_fh_init>`
(:c:type:`fh <v4l2_fh>`, :c:type:`vdev <video_device>`)
- Initialise the file handle. This **MUST** be performed in the driver's
:c:type:`v4l2_file_operations`->open() handler.
:c:func:`v4l2_fh_add <v4l2_fh_add>`
(:c:type:`fh <v4l2_fh>`)
- Add a :c:type:`v4l2_fh` to :c:type:`video_device` file handle list.
Must be called once the file handle is completely initialized.
:c:func:`v4l2_fh_del <v4l2_fh_del>`
(:c:type:`fh <v4l2_fh>`)
- Unassociate the file handle from :c:type:`video_device`. The file handle
exit function may now be called.
:c:func:`v4l2_fh_exit <v4l2_fh_exit>`
(:c:type:`fh <v4l2_fh>`)
- Uninitialise the file handle. After uninitialisation the :c:type:`v4l2_fh`
memory can be freed.
If struct :c:type:`v4l2_fh` is not embedded, then you can use these helper functions:
:c:func:`v4l2_fh_open <v4l2_fh_open>`
(struct file \*filp)
- This allocates a struct :c:type:`v4l2_fh`, initializes it and adds it to
the struct :c:type:`video_device` associated with the file struct.
:c:func:`v4l2_fh_release <v4l2_fh_release>`
(struct file \*filp)
- This deletes it from the struct :c:type:`video_device` associated with the
file struct, uninitialised the :c:type:`v4l2_fh` and frees it.
These two functions can be plugged into the v4l2_file_operation's ``open()``
and ``release()`` ops.
Several drivers need to do something when the first file handle is opened and
when the last file handle closes. Two helper functions were added to check
whether the :c:type:`v4l2_fh` struct is the only open filehandle of the
associated device node:
:c:func:`v4l2_fh_is_singular <v4l2_fh_is_singular>`
(:c:type:`fh <v4l2_fh>`)
- Returns 1 if the file handle is the only open file handle, else 0.
:c:func:`v4l2_fh_is_singular_file <v4l2_fh_is_singular_file>`
(struct file \*filp)
- Same, but it calls v4l2_fh_is_singular with filp->private_data.
V4L2 fh functions and data structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/v4l2-fh.h

4
Documentation/media/kapi/v4l2-flash-led-class.rst Normal file
View File

@ -0,0 +1,4 @@
V4L2 flash functions and data structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/v4l2-flash-led-class.h

74
Documentation/media/kapi/v4l2-intro.rst Normal file
View File

@ -0,0 +1,74 @@
Introduction
------------
The V4L2 drivers tend to be very complex due to the complexity of the
hardware: most devices have multiple ICs, export multiple device nodes in
/dev, and create also non-V4L2 devices such as DVB, ALSA, FB, I2C and input
(IR) devices.
Especially the fact that V4L2 drivers have to setup supporting ICs to
do audio/video muxing/encoding/decoding makes it more complex than most.
Usually these ICs are connected to the main bridge driver through one or
more I2C busses, but other busses can also be used. Such devices are
called 'sub-devices'.
For a long time the framework was limited to the video_device struct for
creating V4L device nodes and video_buf for handling the video buffers
(note that this document does not discuss the video_buf framework).
This meant that all drivers had to do the setup of device instances and
connecting to sub-devices themselves. Some of this is quite complicated
to do right and many drivers never did do it correctly.
There is also a lot of common code that could never be refactored due to
the lack of a framework.
So this framework sets up the basic building blocks that all drivers
need and this same framework should make it much easier to refactor
common code into utility functions shared by all drivers.
A good example to look at as a reference is the v4l2-pci-skeleton.c
source that is available in samples/v4l/. It is a skeleton driver for
a PCI capture card, and demonstrates how to use the V4L2 driver
framework. It can be used as a template for real PCI video capture driver.
Structure of a V4L driver
-------------------------
All drivers have the following structure:
1) A struct for each device instance containing the device state.
2) A way of initializing and commanding sub-devices (if any).
3) Creating V4L2 device nodes (/dev/videoX, /dev/vbiX and /dev/radioX)
and keeping track of device-node specific data.
4) Filehandle-specific structs containing per-filehandle data;
5) video buffer handling.
This is a rough schematic of how it all relates:
.. code-block:: none
device instances
|
+-sub-device instances
|
\-V4L2 device nodes
|
\-filehandle instances
Structure of the V4L2 framework
-------------------------------
The framework closely resembles the driver structure: it has a v4l2_device
struct for the device instance data, a v4l2_subdev struct to refer to
sub-device instances, the video_device struct stores V4L2 device node data
and the v4l2_fh struct keeps track of filehandle instances.
The V4L2 framework also optionally integrates with the media framework. If a
driver sets the struct v4l2_device mdev field, sub-devices and video nodes
will automatically appear in the media framework as entities.

4
Documentation/media/kapi/v4l2-mc.rst Normal file
View File

@ -0,0 +1,4 @@
V4L2 Media Controller functions and data structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/v4l2-mc.h

4
Documentation/media/kapi/v4l2-mediabus.rst Normal file
View File

@ -0,0 +1,4 @@
V4L2 Media Bus functions and data structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/v4l2-mediabus.h

4
Documentation/media/kapi/v4l2-mem2mem.rst Normal file
View File

@ -0,0 +1,4 @@
V4L2 Memory to Memory functions and data structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/v4l2-mem2mem.h

3
Documentation/media/kapi/v4l2-of.rst Normal file
View File

@ -0,0 +1,3 @@
V4L2 Open Firmware kAPI
^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/v4l2-of.h

4
Documentation/media/kapi/v4l2-rect.rst Normal file
View File

@ -0,0 +1,4 @@
V4L2 rect helper functions
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/v4l2-rect.h

445
Documentation/media/kapi/v4l2-subdev.rst Normal file
View File

@ -0,0 +1,445 @@
V4L2 sub-devices
----------------
Many drivers need to communicate with sub-devices. These devices can do all
sort of tasks, but most commonly they handle audio and/or video muxing,
encoding or decoding. For webcams common sub-devices are sensors and camera
controllers.
Usually these are I2C devices, but not necessarily. In order to provide the
driver with a consistent interface to these sub-devices the
:c:type:`v4l2_subdev` struct (v4l2-subdev.h) was created.
Each sub-device driver must have a :c:type:`v4l2_subdev` struct. This struct
can be stand-alone for simple sub-devices or it might be embedded in a larger
struct if more state information needs to be stored. Usually there is a
low-level device struct (e.g. ``i2c_client``) that contains the device data as
setup by the kernel. It is recommended to store that pointer in the private
data of :c:type:`v4l2_subdev` using :c:func:`v4l2_set_subdevdata`. That makes
it easy to go from a :c:type:`v4l2_subdev` to the actual low-level bus-specific
device data.
You also need a way to go from the low-level struct to :c:type:`v4l2_subdev`.
For the common i2c_client struct the i2c_set_clientdata() call is used to store
a :c:type:`v4l2_subdev` pointer, for other busses you may have to use other
methods.
Bridges might also need to store per-subdev private data, such as a pointer to
bridge-specific per-subdev private data. The :c:type:`v4l2_subdev` structure
provides host private data for that purpose that can be accessed with
:c:func:`v4l2_get_subdev_hostdata` and :cpp:func:`v4l2_set_subdev_hostdata`.
From the bridge driver perspective, you load the sub-device module and somehow
obtain the :c:type:`v4l2_subdev` pointer. For i2c devices this is easy: you call
``i2c_get_clientdata()``. For other busses something similar needs to be done.
Helper functions exists for sub-devices on an I2C bus that do most of this
tricky work for you.
Each :c:type:`v4l2_subdev` contains function pointers that sub-device drivers
can implement (or leave ``NULL`` if it is not applicable). Since sub-devices can
do so many different things and you do not want to end up with a huge ops struct
of which only a handful of ops are commonly implemented, the function pointers
are sorted according to category and each category has its own ops struct.
The top-level ops struct contains pointers to the category ops structs, which
may be NULL if the subdev driver does not support anything from that category.
It looks like this:
.. code-block:: c
struct v4l2_subdev_core_ops {
int (*log_status)(struct v4l2_subdev *sd);
int (*init)(struct v4l2_subdev *sd, u32 val);
...
};
struct v4l2_subdev_tuner_ops {
...
};
struct v4l2_subdev_audio_ops {
...
};
struct v4l2_subdev_video_ops {
...
};
struct v4l2_subdev_pad_ops {
...
};
struct v4l2_subdev_ops {
const struct v4l2_subdev_core_ops *core;
const struct v4l2_subdev_tuner_ops *tuner;
const struct v4l2_subdev_audio_ops *audio;
const struct v4l2_subdev_video_ops *video;
const struct v4l2_subdev_pad_ops *video;
};
The core ops are common to all subdevs, the other categories are implemented
depending on the sub-device. E.g. a video device is unlikely to support the
audio ops and vice versa.
This setup limits the number of function pointers while still making it easy
to add new ops and categories.
A sub-device driver initializes the :c:type:`v4l2_subdev` struct using:
:c:func:`v4l2_subdev_init <v4l2_subdev_init>`
(:c:type:`sd <v4l2_subdev>`, &\ :c:type:`ops <v4l2_subdev_ops>`).
Afterwards you need to initialize :c:type:`sd <v4l2_subdev>`->name with a
unique name and set the module owner. This is done for you if you use the
i2c helper functions.
If integration with the media framework is needed, you must initialize the
:c:type:`media_entity` struct embedded in the :c:type:`v4l2_subdev` struct
(entity field) by calling :c:func:`media_entity_pads_init`, if the entity has
pads:
.. code-block:: c
struct media_pad *pads = &my_sd->pads;
int err;
err = media_entity_pads_init(&sd->entity, npads, pads);
The pads array must have been previously initialized. There is no need to
manually set the struct :c:type:`media_entity` function and name fields, but the
revision field must be initialized if needed.
A reference to the entity will be automatically acquired/released when the
subdev device node (if any) is opened/closed.
Don't forget to cleanup the media entity before the sub-device is destroyed:
.. code-block:: c
media_entity_cleanup(&sd->entity);
If the subdev driver intends to process video and integrate with the media
framework, it must implement format related functionality using
:c:type:`v4l2_subdev_pad_ops` instead of :c:type:`v4l2_subdev_video_ops`.
In that case, the subdev driver may set the link_validate field to provide
its own link validation function. The link validation function is called for
every link in the pipeline where both of the ends of the links are V4L2
sub-devices. The driver is still responsible for validating the correctness
of the format configuration between sub-devices and video nodes.
If link_validate op is not set, the default function
:c:func:`v4l2_subdev_link_validate_default` is used instead. This function
ensures that width, height and the media bus pixel code are equal on both source
and sink of the link. Subdev drivers are also free to use this function to
perform the checks mentioned above in addition to their own checks.
There are currently two ways to register subdevices with the V4L2 core. The
first (traditional) possibility is to have subdevices registered by bridge
drivers. This can be done when the bridge driver has the complete information
about subdevices connected to it and knows exactly when to register them. This
is typically the case for internal subdevices, like video data processing units
within SoCs or complex PCI(e) boards, camera sensors in USB cameras or connected
to SoCs, which pass information about them to bridge drivers, usually in their
platform data.
There are however also situations where subdevices have to be registered
asynchronously to bridge devices. An example of such a configuration is a Device
Tree based system where information about subdevices is made available to the
system independently from the bridge devices, e.g. when subdevices are defined
in DT as I2C device nodes. The API used in this second case is described further
below.
Using one or the other registration method only affects the probing process, the
run-time bridge-subdevice interaction is in both cases the same.
In the synchronous case a device (bridge) driver needs to register the
:c:type:`v4l2_subdev` with the v4l2_device:
:c:func:`v4l2_device_register_subdev <v4l2_device_register_subdev>`
(:c:type:`v4l2_dev <v4l2_device>`, :c:type:`sd <v4l2_subdev>`).
This can fail if the subdev module disappeared before it could be registered.
After this function was called successfully the subdev->dev field points to
the :c:type:`v4l2_device`.
If the v4l2_device parent device has a non-NULL mdev field, the sub-device
entity will be automatically registered with the media device.
You can unregister a sub-device using:
:c:func:`v4l2_device_unregister_subdev <v4l2_device_unregister_subdev>`
(:c:type:`sd <v4l2_subdev>`).
Afterwards the subdev module can be unloaded and
:c:type:`sd <v4l2_subdev>`->dev == ``NULL``.
You can call an ops function either directly:
.. code-block:: c
err = sd->ops->core->g_std(sd, &norm);
but it is better and easier to use this macro:
.. code-block:: c
err = v4l2_subdev_call(sd, core, g_std, &norm);
The macro will to the right ``NULL`` pointer checks and returns ``-ENODEV``
if :c:type:`sd <v4l2_subdev>` is ``NULL``, ``-ENOIOCTLCMD`` if either
:c:type:`sd <v4l2_subdev>`->core or :c:type:`sd <v4l2_subdev>`->core->g_std is ``NULL``, or the actual result of the
:c:type:`sd <v4l2_subdev>`->ops->core->g_std ops.
It is also possible to call all or a subset of the sub-devices:
.. code-block:: c
v4l2_device_call_all(v4l2_dev, 0, core, g_std, &norm);
Any subdev that does not support this ops is skipped and error results are
ignored. If you want to check for errors use this:
.. code-block:: c
err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_std, &norm);
Any error except ``-ENOIOCTLCMD`` will exit the loop with that error. If no
errors (except ``-ENOIOCTLCMD``) occurred, then 0 is returned.
The second argument to both calls is a group ID. If 0, then all subdevs are
called. If non-zero, then only those whose group ID match that value will
be called. Before a bridge driver registers a subdev it can set
:c:type:`sd <v4l2_subdev>`->grp_id to whatever value it wants (it's 0 by
default). This value is owned by the bridge driver and the sub-device driver
will never modify or use it.
The group ID gives the bridge driver more control how callbacks are called.
For example, there may be multiple audio chips on a board, each capable of
changing the volume. But usually only one will actually be used when the
user want to change the volume. You can set the group ID for that subdev to
e.g. AUDIO_CONTROLLER and specify that as the group ID value when calling
``v4l2_device_call_all()``. That ensures that it will only go to the subdev
that needs it.
If the sub-device needs to notify its v4l2_device parent of an event, then
it can call ``v4l2_subdev_notify(sd, notification, arg)``. This macro checks
whether there is a ``notify()`` callback defined and returns ``-ENODEV`` if not.
Otherwise the result of the ``notify()`` call is returned.
The advantage of using :c:type:`v4l2_subdev` is that it is a generic struct and
does not contain any knowledge about the underlying hardware. So a driver might
contain several subdevs that use an I2C bus, but also a subdev that is
controlled through GPIO pins. This distinction is only relevant when setting
up the device, but once the subdev is registered it is completely transparent.
In the asynchronous case subdevice probing can be invoked independently of the
bridge driver availability. The subdevice driver then has to verify whether all
the requirements for a successful probing are satisfied. This can include a
check for a master clock availability. If any of the conditions aren't satisfied
the driver might decide to return ``-EPROBE_DEFER`` to request further reprobing
attempts. Once all conditions are met the subdevice shall be registered using
the :c:func:`v4l2_async_register_subdev` function. Unregistration is
performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices
registered this way are stored in a global list of subdevices, ready to be
picked up by bridge drivers.
Bridge drivers in turn have to register a notifier object with an array of
subdevice descriptors that the bridge device needs for its operation. This is
performed using the :c:func:`v4l2_async_notifier_register` call. To
unregister the notifier the driver has to call
:c:func:`v4l2_async_notifier_unregister`. The former of the two functions
takes two arguments: a pointer to struct :c:type:`v4l2_device` and a pointer to
struct :c:type:`v4l2_async_notifier`. The latter contains a pointer to an array
of pointers to subdevice descriptors of type struct :c:type:`v4l2_async_subdev`
type. The V4L2 core will then use these descriptors to match asynchronously
registered
subdevices to them. If a match is detected the ``.bound()`` notifier callback
is called. After all subdevices have been located the .complete() callback is
called. When a subdevice is removed from the system the .unbind() method is
called. All three callbacks are optional.
V4L2 sub-device userspace API
-----------------------------
Beside exposing a kernel API through the :c:type:`v4l2_subdev_ops` structure,
V4L2 sub-devices can also be controlled directly by userspace applications.
Device nodes named ``v4l-subdev``\ *X* can be created in ``/dev`` to access
sub-devices directly. If a sub-device supports direct userspace configuration
it must set the ``V4L2_SUBDEV_FL_HAS_DEVNODE`` flag before being registered.
After registering sub-devices, the :c:type:`v4l2_device` driver can create
device nodes for all registered sub-devices marked with
``V4L2_SUBDEV_FL_HAS_DEVNODE`` by calling
:c:func:`v4l2_device_register_subdev_nodes`. Those device nodes will be
automatically removed when sub-devices are unregistered.
The device node handles a subset of the V4L2 API.
``VIDIOC_QUERYCTRL``,
``VIDIOC_QUERYMENU``,
``VIDIOC_G_CTRL``,
``VIDIOC_S_CTRL``,
``VIDIOC_G_EXT_CTRLS``,
``VIDIOC_S_EXT_CTRLS`` and
``VIDIOC_TRY_EXT_CTRLS``:
The controls ioctls are identical to the ones defined in V4L2. They
behave identically, with the only exception that they deal only with
controls implemented in the sub-device. Depending on the driver, those
controls can be also be accessed through one (or several) V4L2 device
nodes.
``VIDIOC_DQEVENT``,
``VIDIOC_SUBSCRIBE_EVENT`` and
``VIDIOC_UNSUBSCRIBE_EVENT``
The events ioctls are identical to the ones defined in V4L2. They
behave identically, with the only exception that they deal only with
events generated by the sub-device. Depending on the driver, those
events can also be reported by one (or several) V4L2 device nodes.
Sub-device drivers that want to use events need to set the
``V4L2_SUBDEV_USES_EVENTS`` :c:type:`v4l2_subdev`.flags and initialize
:c:type:`v4l2_subdev`.nevents to events queue depth before registering
the sub-device. After registration events can be queued as usual on the
:c:type:`v4l2_subdev`.devnode device node.
To properly support events, the ``poll()`` file operation is also
implemented.
Private ioctls
All ioctls not in the above list are passed directly to the sub-device
driver through the core::ioctl operation.
I2C sub-device drivers
----------------------
Since these drivers are so common, special helper functions are available to
ease the use of these drivers (``v4l2-common.h``).
The recommended method of adding :c:type:`v4l2_subdev` support to an I2C driver
is to embed the :c:type:`v4l2_subdev` struct into the state struct that is
created for each I2C device instance. Very simple devices have no state
struct and in that case you can just create a :c:type:`v4l2_subdev` directly.
A typical state struct would look like this (where 'chipname' is replaced by
the name of the chip):
.. code-block:: c
struct chipname_state {
struct v4l2_subdev sd;
... /* additional state fields */
};
Initialize the :c:type:`v4l2_subdev` struct as follows:
.. code-block:: c
v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
This function will fill in all the fields of :c:type:`v4l2_subdev` ensure that
the :c:type:`v4l2_subdev` and i2c_client both point to one another.
You should also add a helper inline function to go from a :c:type:`v4l2_subdev`
pointer to a chipname_state struct:
.. code-block:: c
static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
{
return container_of(sd, struct chipname_state, sd);
}
Use this to go from the :c:type:`v4l2_subdev` struct to the ``i2c_client``
struct:
.. code-block:: c
struct i2c_client *client = v4l2_get_subdevdata(sd);
And this to go from an ``i2c_client`` to a :c:type:`v4l2_subdev` struct:
.. code-block:: c
struct v4l2_subdev *sd = i2c_get_clientdata(client);
Make sure to call
:c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`)
when the ``remove()`` callback is called. This will unregister the sub-device
from the bridge driver. It is safe to call this even if the sub-device was
never registered.
You need to do this because when the bridge driver destroys the i2c adapter
the ``remove()`` callbacks are called of the i2c devices on that adapter.
After that the corresponding v4l2_subdev structures are invalid, so they
have to be unregistered first. Calling
:c:func:`v4l2_device_unregister_subdev`\ (:c:type:`sd <v4l2_subdev>`)
from the ``remove()`` callback ensures that this is always done correctly.
The bridge driver also has some helper functions it can use:
.. code-block:: c
struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
"module_foo", "chipid", 0x36, NULL);
This loads the given module (can be ``NULL`` if no module needs to be loaded)
and calls :c:func:`i2c_new_device` with the given ``i2c_adapter`` and
chip/address arguments. If all goes well, then it registers the subdev with
the v4l2_device.
You can also use the last argument of :c:func:`v4l2_i2c_new_subdev` to pass
an array of possible I2C addresses that it should probe. These probe addresses
are only used if the previous argument is 0. A non-zero argument means that you
know the exact i2c address so in that case no probing will take place.
Both functions return ``NULL`` if something went wrong.
Note that the chipid you pass to :c:func:`v4l2_i2c_new_subdev` is usually
the same as the module name. It allows you to specify a chip variant, e.g.
"saa7114" or "saa7115". In general though the i2c driver autodetects this.
The use of chipid is something that needs to be looked at more closely at a
later date. It differs between i2c drivers and as such can be confusing.
To see which chip variants are supported you can look in the i2c driver code
for the i2c_device_id table. This lists all the possibilities.
There are two more helper functions:
:c:func:`v4l2_i2c_new_subdev_cfg`: this function adds new irq and
platform_data arguments and has both 'addr' and 'probed_addrs' arguments:
if addr is not 0 then that will be used (non-probing variant), otherwise the
probed_addrs are probed.
For example: this will probe for address 0x10:
.. code-block:: c
struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter,
"module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10));
:c:func:`v4l2_i2c_new_subdev_board` uses an :c:type:`i2c_board_info` struct
which is passed to the i2c driver and replaces the irq, platform_data and addr
arguments.
If the subdev supports the s_config core ops, then that op is called with
the irq and platform_data arguments after the subdev was setup.
The older :c:func:`v4l2_i2c_new_subdev` and
:c:func:`v4l2_i2c_new_probed_subdev` functions will call ``s_config`` as
well, but with irq set to 0 and platform_data set to ``NULL``.
V4L2 sub-device functions and data structures
---------------------------------------------
.. kernel-doc:: include/media/v4l2-subdev.h
.. kernel-doc:: include/media/v4l2-async.h

6
Documentation/media/kapi/v4l2-tuner.rst Normal file
View File

@ -0,0 +1,6 @@
Tuner functions and data structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/tuner.h
.. kernel-doc:: include/media/tuner-types.h

4
Documentation/media/kapi/v4l2-tveeprom.rst Normal file
View File

@ -0,0 +1,4 @@
Hauppauge TV EEPROM functions and data structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/tveeprom.h

53
Documentation/video4linux/videobuf → Documentation/media/kapi/v4l2-videobuf.rst
View File

@ -1,7 +1,20 @@
An introduction to the videobuf layer
Jonathan Corbet <corbet@lwn.net>
.. _vb_framework:
Videobuf Framework
==================
Author: Jonathan Corbet <corbet@lwn.net>
Current as of 2.6.33
.. note::
The videobuf framework was deprecated in favor of videobuf2. Shouldn't
be used on new drivers.
Introduction
------------
The videobuf layer functions as a sort of glue layer between a V4L2 driver
and user space. It handles the allocation and management of buffers for
the storage of video frames. There is a set of functions which can be used
@ -14,6 +27,7 @@ author, but the payback comes in the form of reduced code in the driver and
a consistent implementation of the V4L2 user-space API.
Buffer types
------------
Not all video devices use the same kind of buffers. In fact, there are (at
least) three common variations:
@ -48,10 +62,13 @@ the kernel and a description of this technique is currently beyond the
scope of this document.]
Data structures, callbacks, and initialization
----------------------------------------------
Depending on which type of buffers are being used, the driver should
include one of the following files:
.. code-block:: none
<media/videobuf-dma-sg.h> /* Physically scattered */
<media/videobuf-vmalloc.h> /* vmalloc() buffers */
<media/videobuf-dma-contig.h> /* Physically contiguous */
@ -65,6 +82,8 @@ the queue.
The next step is to write four simple callbacks to help videobuf deal with
the management of buffers:
.. code-block:: none
struct videobuf_queue_ops {
int (*buf_setup)(struct videobuf_queue *q,
unsigned int *count, unsigned int *size);
@ -91,6 +110,8 @@ passed to buf_prepare(), which should set the buffer's size, width, height,
and field fields properly. If the buffer's state field is
VIDEOBUF_NEEDS_INIT, the driver should pass it to:
.. code-block:: none
int videobuf_iolock(struct videobuf_queue* q, struct videobuf_buffer *vb,
struct v4l2_framebuffer *fbuf);
@ -110,6 +131,8 @@ Finally, buf_release() is called when a buffer is no longer intended to be
used. The driver should ensure that there is no I/O active on the buffer,
then pass it to the appropriate free routine(s):
.. code-block:: none
/* Scatter/gather drivers */
int videobuf_dma_unmap(struct videobuf_queue *q,
struct videobuf_dmabuf *dma);
@ -124,6 +147,8 @@ then pass it to the appropriate free routine(s):
One way to ensure that a buffer is no longer under I/O is to pass it to:
.. code-block:: none
int videobuf_waiton(struct videobuf_buffer *vb, int non_blocking, int intr);
Here, vb is the buffer, non_blocking indicates whether non-blocking I/O
@ -131,12 +156,15 @@ should be used (it should be zero in the buf_release() case), and intr
controls whether an interruptible wait is used.
File operations
---------------
At this point, much of the work is done; much of the rest is slipping
videobuf calls into the implementation of the other driver callbacks. The
first step is in the open() function, which must initialize the
videobuf queue. The function to use depends on the type of buffer used:
.. code-block:: none
void videobuf_queue_sg_init(struct videobuf_queue *q,
struct videobuf_queue_ops *ops,
struct device *dev,
@ -182,6 +210,8 @@ applications have a chance of working with the device. Videobuf makes it
easy to do that with the same code. To implement read(), the driver need
only make a call to one of:
.. code-block:: none
ssize_t videobuf_read_one(struct videobuf_queue *q,
char __user *data, size_t count,
loff_t *ppos, int nonblocking);
@ -201,6 +231,8 @@ anticipation of another read() call happening in the near future).
The poll() function can usually be implemented with a direct call to:
.. code-block:: none
unsigned int videobuf_poll_stream(struct file *file,
struct videobuf_queue *q,
poll_table *wait);
@ -213,6 +245,8 @@ the mmap() system call to enable user space to access the data. In many
V4L2 drivers, the often-complex mmap() implementation simplifies to a
single call to:
.. code-block:: none
int videobuf_mmap_mapper(struct videobuf_queue *q,
struct vm_area_struct *vma);
@ -220,6 +254,8 @@ Everything else is handled by the videobuf code.
The release() function requires two separate videobuf calls:
.. code-block:: none
void videobuf_stop(struct videobuf_queue *q);
int videobuf_mmap_free(struct videobuf_queue *q);
@ -233,12 +269,15 @@ buffers are still mapped, but every driver in the 2.6.32 kernel cheerfully
ignores its return value.
ioctl() operations
------------------
The V4L2 API includes a very long list of driver callbacks to respond to
the many ioctl() commands made available to user space. A number of these
- those associated with streaming I/O - turn almost directly into videobuf
calls. The relevant helper functions are:
.. code-block:: none
int videobuf_reqbufs(struct videobuf_queue *q,
struct v4l2_requestbuffers *req);
int videobuf_querybuf(struct videobuf_queue *q, struct v4l2_buffer *b);
@ -259,6 +298,7 @@ complex, of course, since they will also need to deal with starting and
stopping the capture engine.
Buffer allocation
-----------------
Thus far, we have talked about buffers, but have not looked at how they are
allocated. The scatter/gather case is the most complex on this front. For
@ -272,11 +312,15 @@ If the driver needs to do its own memory allocation, it should be done in
the vidioc_reqbufs() function, *after* calling videobuf_reqbufs(). The
first step is a call to:
.. code-block:: none
struct videobuf_dmabuf *videobuf_to_dma(struct videobuf_buffer *buf);
The returned videobuf_dmabuf structure (defined in
<media/videobuf-dma-sg.h>) includes a couple of relevant fields:
.. code-block:: none
struct scatterlist *sglist;
int sglen;
@ -300,6 +344,7 @@ kernel drivers, or those contained within huge pages, will work with these
drivers.
Filling the buffers
-------------------
The final part of a videobuf implementation has no direct callback - it's
the portion of the code which actually puts frame data into the buffers,
@ -331,10 +376,14 @@ For scatter/gather drivers, the needed memory pointers will be found in the
scatterlist structure described above. Drivers using the vmalloc() method
can get a memory pointer with:
.. code-block:: none
void *videobuf_to_vmalloc(struct videobuf_buffer *buf);
For contiguous DMA drivers, the function to use is:
.. code-block:: none
dma_addr_t videobuf_to_dma_contig(struct videobuf_buffer *buf);
The contiguous DMA API goes out of its way to hide the kernel-space address

10
Documentation/media/kapi/v4l2-videobuf2.rst Normal file
View File

@ -0,0 +1,10 @@
.. _vb2_framework:
V4L2 videobuf2 functions and data structures
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. kernel-doc:: include/media/videobuf2-core.h
.. kernel-doc:: include/media/videobuf2-v4l2.h
.. kernel-doc:: include/media/videobuf2-memops.h

43
Documentation/media/lirc.h.rst.exceptions Normal file
View File

@ -0,0 +1,43 @@
# Ignore header name
ignore define _LINUX_LIRC_H
# Ignore helper macros
ignore define lirc_t
ignore define LIRC_SPACE
ignore define LIRC_PULSE
ignore define LIRC_FREQUENCY
ignore define LIRC_TIMEOUT
ignore define LIRC_VALUE
ignore define LIRC_MODE2
ignore define LIRC_IS_SPACE
ignore define LIRC_IS_PULSE
ignore define LIRC_IS_FREQUENCY
ignore define LIRC_IS_TIMEOUT
ignore define LIRC_MODE2SEND
ignore define LIRC_SEND2MODE
ignore define LIRC_MODE2REC
ignore define LIRC_REC2MODE
ignore define LIRC_CAN_SEND
ignore define LIRC_CAN_REC
ignore define LIRC_CAN_SEND_MASK
ignore define LIRC_CAN_REC_MASK
ignore define LIRC_CAN_SET_REC_DUTY_CYCLE
# Undocumented macros
ignore define PULSE_BIT
ignore define PULSE_MASK
ignore define LIRC_MODE2_SPACE
ignore define LIRC_MODE2_PULSE
ignore define LIRC_MODE2_TIMEOUT
ignore define LIRC_VALUE_MASK
ignore define LIRC_MODE2_MASK
ignore define LIRC_MODE_RAW

30
Documentation/media/media.h.rst.exceptions Normal file
View File

@ -0,0 +1,30 @@
# Ignore header name
ignore define __LINUX_MEDIA_H
# Ignore macros
ignore define MEDIA_API_VERSION
ignore define MEDIA_ENT_F_BASE
ignore define MEDIA_ENT_F_OLD_BASE
ignore define MEDIA_ENT_F_OLD_SUBDEV_BASE
ignore define MEDIA_INTF_T_DVB_BASE
ignore define MEDIA_INTF_T_V4L_BASE
ignore define MEDIA_INTF_T_ALSA_BASE
#ignore legacy entity type macros
ignore define MEDIA_ENT_TYPE_SHIFT
ignore define MEDIA_ENT_TYPE_MASK
ignore define MEDIA_ENT_SUBTYPE_MASK
ignore define MEDIA_ENT_T_DEVNODE_UNKNOWN
ignore define MEDIA_ENT_T_DEVNODE
ignore define MEDIA_ENT_T_DEVNODE_V4L
ignore define MEDIA_ENT_T_DEVNODE_FB
ignore define MEDIA_ENT_T_DEVNODE_ALSA
ignore define MEDIA_ENT_T_DEVNODE_DVB
ignore define MEDIA_ENT_T_UNKNOWN
ignore define MEDIA_ENT_T_V4L2_VIDEO
ignore define MEDIA_ENT_T_V4L2_SUBDEV
ignore define MEDIA_ENT_T_V4L2_SUBDEV_SENSOR
ignore define MEDIA_ENT_T_V4L2_SUBDEV_FLASH
ignore define MEDIA_ENT_T_V4L2_SUBDEV_LENS
ignore define MEDIA_ENT_T_V4L2_SUBDEV_DECODER
ignore define MEDIA_ENT_T_V4L2_SUBDEV_TUNER

BIN
Documentation/media/media_api_files/typical_media_device.pdf Normal file
View File

Binary file not shown.

28
Documentation/media/media_api_files/typical_media_device.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

34
Documentation/media/media_kapi.rst Normal file
View File

@ -0,0 +1,34 @@
.. -*- coding: utf-8; mode: rst -*-
.. include:: <isonum.txt>
===================================
Media subsystem kernel internal API
===================================
**Copyright** |copy| 2009-2016 : LinuxTV Developers
This documentation is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option) any
later version.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
For more details see the file COPYING in the source distribution of Linux.
.. class:: toc-title
Table of Contents
.. toctree::
:maxdepth: 5
:numbered:
kapi/v4l2-core
kapi/dtv-core
kapi/rc-core
kapi/mc-core

31
Documentation/media/media_uapi.rst Normal file
View File

@ -0,0 +1,31 @@
.. -*- coding: utf-8; mode: rst -*-
.. include:: <isonum.txt>
########################################
Linux Media Infrastructure userspace API
########################################
**Copyright** |copy| 2009-2016 : LinuxTV Developers
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation. A copy of
the license is included in the chapter entitled "GNU Free Documentation
License".
.. class:: toc-title
Table of Contents
.. toctree::
:maxdepth: 1
intro
uapi/v4l/v4l2
uapi/dvb/dvbapi
uapi/rc/remote_controllers
uapi/mediactl/media-controller
uapi/cec/cec-api
uapi/gen-errors
uapi/fdl-appendix

11
Documentation/media/net.h.rst.exceptions Normal file
View File

@ -0,0 +1,11 @@
# Ignore header name
ignore define _DVBNET_H_
# Ignore old ioctls/structs
ignore ioctl __NET_ADD_IF_OLD
ignore ioctl __NET_GET_IF_OLD
ignore struct __dvb_net_if_old
# Macros used at struct dvb_net_if
replace define DVB_NET_FEEDTYPE_MPE dvb-net-if
replace define DVB_NET_FEEDTYPE_ULE dvb-net-if

43
Documentation/media/uapi/cec/cec-api.rst Normal file
View File

@ -0,0 +1,43 @@
.. -*- coding: utf-8; mode: rst -*-
.. include:: <isonum.txt>
.. _cec:
#########################################
Part V - Consumer Electronics Control API
#########################################
This part describes the CEC: Consumer Electronics Control
.. class:: toc-title
Table of Contents
.. toctree::
:maxdepth: 5
:numbered:
cec-intro
cec-funcs
cec-header
**********************
Revision and Copyright
**********************
Authors:
- Verkuil, Hans <hans.verkuil@cisco.com>
- Initial version.
**Copyright** |copy| 2016 : Hans Verkuil
****************
Revision History
****************
:revision: 1.0.0 / 2016-03-17 (*hv*)
Initial revision

49
Documentation/media/uapi/cec/cec-func-close.rst Normal file
View File

@ -0,0 +1,49 @@
.. -*- coding: utf-8; mode: rst -*-
.. _cec-func-close:
***********
cec close()
***********
Name
====
cec-close - Close a cec device
Synopsis
========
.. code-block:: c
#include <unistd.h>
.. cpp:function:: int close( int fd )
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <func-open>`.
Description
===========
.. note:: This documents the proposed CEC API. This API is not yet finalized
and is currently only available as a staging kernel module.
Closes the cec device. Resources associated with the file descriptor are
freed. The device configuration remain unchanged.
Return Value
============
:c:func:`close()` returns 0 on success. On error, -1 is returned, and
``errno`` is set appropriately. Possible error codes are:
``EBADF``
``fd`` is not a valid open file descriptor.

68
Documentation/media/uapi/cec/cec-func-ioctl.rst Normal file
View File

@ -0,0 +1,68 @@
.. -*- coding: utf-8; mode: rst -*-
.. _cec-func-ioctl:
***********
cec ioctl()
***********
Name
====
cec-ioctl - Control a cec device
Synopsis
========
.. code-block:: c
#include <sys/ioctl.h>
.. cpp:function:: int ioctl( int fd, int request, void *argp )
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <func-open>`.
``request``
CEC ioctl request code as defined in the cec.h header file, for
example :ref:`CEC_ADAP_G_CAPS`.
``argp``
Pointer to a request-specific structure.
Description
===========
.. note:: This documents the proposed CEC API. This API is not yet finalized
and is currently only available as a staging kernel module.
The :c:func:`ioctl()` function manipulates cec device parameters. The
argument ``fd`` must be an open file descriptor.
The ioctl ``request`` code specifies the cec function to be called. It
has encoded in it whether the argument is an input, output or read/write
parameter, and the size of the argument ``argp`` in bytes.
Macros and structures definitions specifying cec ioctl requests and
their parameters are located in the cec.h header file. All cec ioctl
requests, their respective function and parameters are specified in
:ref:`cec-user-func`.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
Request-specific error codes are listed in the individual requests
descriptions.
When an ioctl that takes an output or read/write parameter fails, the
parameter remains unmodified.

80
Documentation/media/uapi/cec/cec-func-open.rst Normal file
View File

@ -0,0 +1,80 @@
.. -*- coding: utf-8; mode: rst -*-
.. _cec-func-open:
**********
cec open()
**********
Name
====
cec-open - Open a cec device
Synopsis
========
.. code-block:: c
#include <fcntl.h>
.. cpp:function:: int open( const char *device_name, int flags )
Arguments
=========
``device_name``
Device to be opened.
``flags``
Open flags. Access mode must be ``O_RDWR``.
When the ``O_NONBLOCK`` flag is given, the
:ref:`CEC_RECEIVE <CEC_RECEIVE>` and :ref:`CEC_DQEVENT <CEC_DQEVENT>` ioctls
will return the ``EAGAIN`` error code when no message or event is available, and
ioctls :ref:`CEC_TRANSMIT <CEC_TRANSMIT>`,
:ref:`CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` and
:ref:`CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
all return 0.
Other flags have no effect.
Description
===========
.. note:: This documents the proposed CEC API. This API is not yet finalized
and is currently only available as a staging kernel module.
To open a cec device applications call :c:func:`open()` with the
desired device name. The function has no side effects; the device
configuration remain unchanged.
When the device is opened in read-only mode, attempts to modify its
configuration will result in an error, and ``errno`` will be set to
EBADF.
Return Value
============
:c:func:`open()` returns the new file descriptor on success. On error,
-1 is returned, and ``errno`` is set appropriately. Possible error codes
include:
``EACCES``
The requested access to the file is not allowed.
``EMFILE``
The process already has the maximum number of files open.
``ENFILE``
The system limit on the total number of open files has been reached.
``ENOMEM``
Insufficient kernel memory was available.
``ENXIO``
No device corresponding to this device special file exists.

70
Documentation/media/uapi/cec/cec-func-poll.rst Normal file
View File

@ -0,0 +1,70 @@
.. -*- coding: utf-8; mode: rst -*-
.. _cec-func-poll:
**********
cec poll()
**********
Name
====
cec-poll - Wait for some event on a file descriptor
Synopsis
========
.. code-block:: c
#include <sys/poll.h>
.. cpp:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout )
Arguments
=========
Description
===========
.. note:: This documents the proposed CEC API. This API is not yet finalized
and is currently only available as a staging kernel module.
With the :c:func:`poll()` function applications can wait for CEC
events.
On success :c:func:`poll()` returns the number of file descriptors
that have been selected (that is, file descriptors for which the
``revents`` field of the respective :c:type:`struct pollfd` structure
is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in
the ``revents`` field if there are messages in the receive queue. If the
transmit queue has room for new messages, the ``POLLOUT`` and
``POLLWRNORM`` flags are set. If there are events in the event queue,
then the ``POLLPRI`` flag is set. When the function timed out it returns
a value of zero, on failure it returns -1 and the ``errno`` variable is
set appropriately.
For more details see the :c:func:`poll()` manual page.
Return Value
============
On success, :c:func:`poll()` returns the number structures which have
non-zero ``revents`` fields, or zero if the call timed out. On error -1
is returned, and the ``errno`` variable is set appropriately:
``EBADF``
One or more of the ``ufds`` members specify an invalid file
descriptor.
``EFAULT``
``ufds`` references an inaccessible memory area.
``EINTR``
The call was interrupted by a signal.
``EINVAL``
The ``nfds`` argument is greater than ``OPEN_MAX``.

21
Documentation/media/uapi/cec/cec-funcs.rst Normal file
View File

@ -0,0 +1,21 @@
.. _cec-user-func:
******************
Function Reference
******************
.. toctree::
:maxdepth: 1
:numbered:
cec-func-open
cec-func-close
cec-func-ioctl
cec-func-poll
cec-ioc-adap-g-caps
cec-ioc-adap-g-log-addrs
cec-ioc-adap-g-phys-addr
cec-ioc-dqevent
cec-ioc-g-mode
cec-ioc-receive

10
Documentation/media/uapi/cec/cec-header.rst Normal file
View File

@ -0,0 +1,10 @@
.. -*- coding: utf-8; mode: rst -*-
.. _cec_header:
***************
CEC Header File
***************
.. kernel-include:: $BUILDDIR/cec.h.rst

31
Documentation/media/uapi/cec/cec-intro.rst Normal file
View File

@ -0,0 +1,31 @@
.. _cec-intro:
Introduction
============
.. note:: This documents the proposed CEC API. This API is not yet finalized
and is currently only available as a staging kernel module.
HDMI connectors provide a single pin for use by the Consumer Electronics
Control protocol. This protocol allows different devices connected by an
HDMI cable to communicate. The protocol for CEC version 1.4 is defined
in supplements 1 (CEC) and 2 (HEAC or HDMI Ethernet and Audio Return
Channel) of the HDMI 1.4a (:ref:`hdmi`) specification and the
extensions added to CEC version 2.0 are defined in chapter 11 of the
HDMI 2.0 (:ref:`hdmi2`) specification.
The bitrate is very slow (effectively no more than 36 bytes per second)
and is based on the ancient AV.link protocol used in old SCART
connectors. The protocol closely resembles a crazy Rube Goldberg
contraption and is an unholy mix of low and high level messages. Some
messages, especially those part of the HEAC protocol layered on top of
CEC, need to be handled by the kernel, others can be handled either by
the kernel or by userspace.
In addition, CEC can be implemented in HDMI receivers, transmitters and
in USB devices that have an HDMI input and an HDMI output and that
control just the CEC pin.
Drivers that support CEC will create a CEC device node (/dev/cecX) to
give userspace access to the CEC adapter. The
:ref:`CEC_ADAP_G_CAPS` ioctl will tell userspace what it is allowed to do.

165
Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst Normal file
View File

@ -0,0 +1,165 @@
.. -*- coding: utf-8; mode: rst -*-
.. _CEC_ADAP_G_CAPS:
*********************
ioctl CEC_ADAP_G_CAPS
*********************
Name
====
CEC_ADAP_G_CAPS - Query device capabilities
Synopsis
========
.. cpp:function:: int ioctl( int fd, int request, struct cec_caps *argp )
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <cec-func-open>`.
``request``
CEC_ADAP_G_CAPS
``argp``
Description
===========
.. note:: This documents the proposed CEC API. This API is not yet finalized
and is currently only available as a staging kernel module.
All cec devices must support :ref:`ioctl CEC_ADAP_G_CAPS <CEC_ADAP_G_CAPS>`. To query
device information, applications call the ioctl with a pointer to a
struct :ref:`cec_caps <cec-caps>`. The driver fills the structure and
returns the information to the application. The ioctl never fails.
.. _cec-caps:
.. flat-table:: struct cec_caps
:header-rows: 0
:stub-columns: 0
:widths: 1 1 16
- .. row 1
- char
- ``driver[32]``
- The name of the cec adapter driver.
- .. row 2
- char
- ``name[32]``
- The name of this CEC adapter. The combination ``driver`` and
``name`` must be unique.
- .. row 3
- __u32
- ``capabilities``
- The capabilities of the CEC adapter, see
:ref:`cec-capabilities`.
- .. row 4
- __u32
- ``version``
- CEC Framework API version, formatted with the ``KERNEL_VERSION()``
macro.
.. _cec-capabilities:
.. flat-table:: CEC Capabilities Flags
:header-rows: 0
:stub-columns: 0
:widths: 3 1 8
- .. _`CEC-CAP-PHYS-ADDR`:
- ``CEC_CAP_PHYS_ADDR``
- 0x00000001
- Userspace has to configure the physical address by calling
:ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`. If
this capability isn't set, then setting the physical address is
handled by the kernel whenever the EDID is set (for an HDMI
receiver) or read (for an HDMI transmitter).
- .. _`CEC-CAP-LOG-ADDRS`:
- ``CEC_CAP_LOG_ADDRS``
- 0x00000002
- Userspace has to configure the logical addresses by calling
:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`. If
this capability isn't set, then the kernel will have configured
this.
- .. _`CEC-CAP-TRANSMIT`:
- ``CEC_CAP_TRANSMIT``
- 0x00000004
- Userspace can transmit CEC messages by calling
:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. This implies that
userspace can be a follower as well, since being able to transmit
messages is a prerequisite of becoming a follower. If this
capability isn't set, then the kernel will handle all CEC
transmits and process all CEC messages it receives.
- .. _`CEC-CAP-PASSTHROUGH`:
- ``CEC_CAP_PASSTHROUGH``
- 0x00000008
- Userspace can use the passthrough mode by calling
:ref:`ioctl CEC_S_MODE <CEC_S_MODE>`.
- .. _`CEC-CAP-RC`:
- ``CEC_CAP_RC``
- 0x00000010
- This adapter supports the remote control protocol.
- .. _`CEC-CAP-MONITOR-ALL`:
- ``CEC_CAP_MONITOR_ALL``
- 0x00000020
- The CEC hardware can monitor all messages, not just directed and
broadcast messages.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

436
Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst Normal file
View File

@ -0,0 +1,436 @@
.. -*- coding: utf-8; mode: rst -*-
.. _CEC_ADAP_LOG_ADDRS:
.. _CEC_ADAP_G_LOG_ADDRS:
.. _CEC_ADAP_S_LOG_ADDRS:
****************************************************
ioctls CEC_ADAP_G_LOG_ADDRS and CEC_ADAP_S_LOG_ADDRS
****************************************************
Name
====
CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses
Synopsis
========
.. cpp:function:: int ioctl( int fd, int request, struct cec_log_addrs *argp )
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <cec-func-open>`.
``request``
CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS
``argp``
Description
===========
.. note:: This documents the proposed CEC API. This API is not yet finalized
and is currently only available as a staging kernel module.
To query the current CEC logical addresses, applications call
:ref:`ioctl CEC_ADAP_G_LOG_ADDRS <CEC_ADAP_G_LOG_ADDRS>` with a pointer to a
:c:type:`struct cec_log_addrs` where the driver stores the logical addresses.
To set new logical addresses, applications fill in
:c:type:`struct cec_log_addrs` and call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
with a pointer to this struct. The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
is only available if ``CEC_CAP_LOG_ADDRS`` is set (the ``ENOTTY`` error code is
returned otherwise). The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
can only be called by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
the ``EBUSY`` error code will be returned.
To clear existing logical addresses set ``num_log_addrs`` to 0. All other fields
will be ignored in that case. The adapter will go to the unconfigured state.
If the physical address is valid (see :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`),
then this ioctl will block until all requested logical
addresses have been claimed. If the file descriptor is in non-blocking mode then it will
not wait for the logical addresses to be claimed, instead it just returns 0.
A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the
logical addresses are claimed or cleared.
Attempting to call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` when
logical address types are already defined will return with error ``EBUSY``.
.. _cec-log-addrs:
.. flat-table:: struct cec_log_addrs
:header-rows: 0
:stub-columns: 0
:widths: 1 1 16
- .. row 1
- __u8
- ``log_addr[CEC_MAX_LOG_ADDRS]``
- The actual logical addresses that were claimed. This is set by the
driver. If no logical address could be claimed, then it is set to
``CEC_LOG_ADDR_INVALID``. If this adapter is Unregistered, then
``log_addr[0]`` is set to 0xf and all others to
``CEC_LOG_ADDR_INVALID``.
- .. row 2
- __u16
- ``log_addr_mask``
- The bitmask of all logical addresses this adapter has claimed. If
this adapter is Unregistered then ``log_addr_mask`` sets bit 15
and clears all other bits. If this adapter is not configured at
all, then ``log_addr_mask`` is set to 0. Set by the driver.
- .. row 3
- __u8
- ``cec_version``
- The CEC version that this adapter shall use. See
:ref:`cec-versions`. Used to implement the
``CEC_MSG_CEC_VERSION`` and ``CEC_MSG_REPORT_FEATURES`` messages.
Note that :ref:`CEC_OP_CEC_VERSION_1_3A <CEC-OP-CEC-VERSION-1-3A>` is not allowed by the CEC
framework.
- .. row 4
- __u8
- ``num_log_addrs``
- Number of logical addresses to set up. Must be ≤
``available_log_addrs`` as returned by
:ref:`CEC_ADAP_G_CAPS`. All arrays in
this structure are only filled up to index
``available_log_addrs``-1. The remaining array elements will be
ignored. Note that the CEC 2.0 standard allows for a maximum of 2
logical addresses, although some hardware has support for more.
``CEC_MAX_LOG_ADDRS`` is 4. The driver will return the actual
number of logical addresses it could claim, which may be less than
what was requested. If this field is set to 0, then the CEC
adapter shall clear all claimed logical addresses and all other
fields will be ignored.
- .. row 5
- __u32
- ``vendor_id``
- The vendor ID is a 24-bit number that identifies the specific
vendor or entity. Based on this ID vendor specific commands may be
defined. If you do not want a vendor ID then set it to
``CEC_VENDOR_ID_NONE``.
- .. row 6
- __u32
- ``flags``
- Flags. No flags are defined yet, so set this to 0.
- .. row 7
- char
- ``osd_name[15]``
- The On-Screen Display name as is returned by the
``CEC_MSG_SET_OSD_NAME`` message.
- .. row 8
- __u8
- ``primary_device_type[CEC_MAX_LOG_ADDRS]``
- Primary device type for each logical address. See
:ref:`cec-prim-dev-types` for possible types.
- .. row 9
- __u8
- ``log_addr_type[CEC_MAX_LOG_ADDRS]``
- Logical address types. See :ref:`cec-log-addr-types` for
possible types. The driver will update this with the actual
logical address type that it claimed (e.g. it may have to fallback
to :ref:`CEC_LOG_ADDR_TYPE_UNREGISTERED <CEC-LOG-ADDR-TYPE-UNREGISTERED>`).
- .. row 10
- __u8
- ``all_device_types[CEC_MAX_LOG_ADDRS]``
- CEC 2.0 specific: the bit mask of all device types. See
:ref:`cec-all-dev-types-flags`. It is used in the CEC 2.0
``CEC_MSG_REPORT_FEATURES`` message. For CEC 1.4 you can either leave
this field to 0, or fill it in according to the CEC 2.0 guidelines to
give the CEC framework more information about the device type, even
though the framework won't use it directly in the CEC message.
- .. row 11
- __u8
- ``features[CEC_MAX_LOG_ADDRS][12]``
- Features for each logical address. It is used in the CEC 2.0
``CEC_MSG_REPORT_FEATURES`` message. The 12 bytes include both the
RC Profile and the Device Features. For CEC 1.4 you can either leave
this field to all 0, or fill it in according to the CEC 2.0 guidelines to
give the CEC framework more information about the device type, even
though the framework won't use it directly in the CEC message.
.. _cec-versions:
.. flat-table:: CEC Versions
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
- .. _`CEC-OP-CEC-VERSION-1-3A`:
- ``CEC_OP_CEC_VERSION_1_3A``
- 4
- CEC version according to the HDMI 1.3a standard.
- .. _`CEC-OP-CEC-VERSION-1-4B`:
- ``CEC_OP_CEC_VERSION_1_4B``
- 5
- CEC version according to the HDMI 1.4b standard.
- .. _`CEC-OP-CEC-VERSION-2-0`:
- ``CEC_OP_CEC_VERSION_2_0``
- 6
- CEC version according to the HDMI 2.0 standard.
.. _cec-prim-dev-types:
.. flat-table:: CEC Primary Device Types
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
- .. _`CEC-OP-PRIM-DEVTYPE-TV`:
- ``CEC_OP_PRIM_DEVTYPE_TV``
- 0
- Use for a TV.
- .. _`CEC-OP-PRIM-DEVTYPE-RECORD`:
- ``CEC_OP_PRIM_DEVTYPE_RECORD``
- 1
- Use for a recording device.
- .. _`CEC-OP-PRIM-DEVTYPE-TUNER`:
- ``CEC_OP_PRIM_DEVTYPE_TUNER``
- 3
- Use for a device with a tuner.
- .. _`CEC-OP-PRIM-DEVTYPE-PLAYBACK`:
- ``CEC_OP_PRIM_DEVTYPE_PLAYBACK``
- 4
- Use for a playback device.
- .. _`CEC-OP-PRIM-DEVTYPE-AUDIOSYSTEM`:
- ``CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM``
- 5
- Use for an audio system (e.g. an audio/video receiver).
- .. _`CEC-OP-PRIM-DEVTYPE-SWITCH`:
- ``CEC_OP_PRIM_DEVTYPE_SWITCH``
- 6
- Use for a CEC switch.
- .. _`CEC-OP-PRIM-DEVTYPE-VIDEOPROC`:
- ``CEC_OP_PRIM_DEVTYPE_VIDEOPROC``
- 7
- Use for a video processor device.
.. _cec-log-addr-types:
.. flat-table:: CEC Logical Address Types
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
- .. _`CEC-LOG-ADDR-TYPE-TV`:
- ``CEC_LOG_ADDR_TYPE_TV``
- 0
- Use for a TV.
- .. _`CEC-LOG-ADDR-TYPE-RECORD`:
- ``CEC_LOG_ADDR_TYPE_RECORD``
- 1
- Use for a recording device.
- .. _`CEC-LOG-ADDR-TYPE-TUNER`:
- ``CEC_LOG_ADDR_TYPE_TUNER``
- 2
- Use for a tuner device.
- .. _`CEC-LOG-ADDR-TYPE-PLAYBACK`:
- ``CEC_LOG_ADDR_TYPE_PLAYBACK``
- 3
- Use for a playback device.
- .. _`CEC-LOG-ADDR-TYPE-AUDIOSYSTEM`:
- ``CEC_LOG_ADDR_TYPE_AUDIOSYSTEM``
- 4
- Use for an audio system device.
- .. _`CEC-LOG-ADDR-TYPE-SPECIFIC`:
- ``CEC_LOG_ADDR_TYPE_SPECIFIC``
- 5
- Use for a second TV or for a video processor device.
- .. _`CEC-LOG-ADDR-TYPE-UNREGISTERED`:
- ``CEC_LOG_ADDR_TYPE_UNREGISTERED``
- 6
- Use this if you just want to remain unregistered. Used for pure
CEC switches or CDC-only devices (CDC: Capability Discovery and
Control).
.. _cec-all-dev-types-flags:
.. flat-table:: CEC All Device Types Flags
:header-rows: 0
:stub-columns: 0
:widths: 3 1 4
- .. _`CEC-OP-ALL-DEVTYPE-TV`:
- ``CEC_OP_ALL_DEVTYPE_TV``
- 0x80
- This supports the TV type.
- .. _`CEC-OP-ALL-DEVTYPE-RECORD`:
- ``CEC_OP_ALL_DEVTYPE_RECORD``
- 0x40
- This supports the Recording type.
- .. _`CEC-OP-ALL-DEVTYPE-TUNER`:
- ``CEC_OP_ALL_DEVTYPE_TUNER``
- 0x20
- This supports the Tuner type.
- .. _`CEC-OP-ALL-DEVTYPE-PLAYBACK`:
- ``CEC_OP_ALL_DEVTYPE_PLAYBACK``
- 0x10
- This supports the Playback type.
- .. _`CEC-OP-ALL-DEVTYPE-AUDIOSYSTEM`:
- ``CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM``
- 0x08
- This supports the Audio System type.
- .. _`CEC-OP-ALL-DEVTYPE-SWITCH`:
- ``CEC_OP_ALL_DEVTYPE_SWITCH``
- 0x04
- This supports the CEC Switch or Video Processing type.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

82
Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst Normal file
View File

@ -0,0 +1,82 @@
.. -*- coding: utf-8; mode: rst -*-
.. _CEC_ADAP_PHYS_ADDR:
.. _CEC_ADAP_G_PHYS_ADDR:
.. _CEC_ADAP_S_PHYS_ADDR:
****************************************************
ioctls CEC_ADAP_G_PHYS_ADDR and CEC_ADAP_S_PHYS_ADDR
****************************************************
Name
====
CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address
Synopsis
========
.. cpp:function:: int ioctl( int fd, int request, __u16 *argp )
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <cec-func-open>`.
``request``
CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR
``argp``
Description
===========
.. note:: This documents the proposed CEC API. This API is not yet finalized
and is currently only available as a staging kernel module.
To query the current physical address applications call
:ref:`ioctl CEC_ADAP_G_PHYS_ADDR <CEC_ADAP_G_PHYS_ADDR>` with a pointer to a __u16 where the
driver stores the physical address.
To set a new physical address applications store the physical address in
a __u16 and call :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` with a pointer to
this integer. The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` is only available if
``CEC_CAP_PHYS_ADDR`` is set (the ``ENOTTY`` error code will be returned
otherwise). The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can only be called
by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
the ``EBUSY`` error code will be returned.
To clear an existing physical address use ``CEC_PHYS_ADDR_INVALID``.
The adapter will go to the unconfigured state.
If logical address types have been defined (see :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`),
then this ioctl will block until all
requested logical addresses have been claimed. If the file descriptor is in non-blocking mode
then it will not wait for the logical addresses to be claimed, instead it just returns 0.
A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the physical address
changes.
The physical address is a 16-bit number where each group of 4 bits
represent a digit of the physical address a.b.c.d where the most
significant 4 bits represent 'a'. The CEC root device (usually the TV)
has address 0.0.0.0. Every device that is hooked up to an input of the
TV has address a.0.0.0 (where 'a' is ≥ 1), devices hooked up to those in
turn have addresses a.b.0.0, etc. So a topology of up to 5 devices deep
is supported. The physical address a device shall use is stored in the
EDID of the sink.
For example, the EDID for each HDMI input of the TV will have a
different physical address of the form a.0.0.0 that the sources will
read out and use as their physical address.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

231
Documentation/media/uapi/cec/cec-ioc-dqevent.rst Normal file
View File

@ -0,0 +1,231 @@
.. -*- coding: utf-8; mode: rst -*-
.. _CEC_DQEVENT:
*****************
ioctl CEC_DQEVENT
*****************
Name
====
CEC_DQEVENT - Dequeue a CEC event
Synopsis
========
.. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp )
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <cec-func-open>`.
``request``
CEC_DQEVENT
``argp``
Description
===========
.. note:: This documents the proposed CEC API. This API is not yet finalized
and is currently only available as a staging kernel module.
CEC devices can send asynchronous events. These can be retrieved by
calling :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>`. If the file descriptor is in
non-blocking mode and no event is pending, then it will return -1 and
set errno to the ``EAGAIN`` error code.
The internal event queues are per-filehandle and per-event type. If
there is no more room in a queue then the last event is overwritten with
the new one. This means that intermediate results can be thrown away but
that the latest event is always available. This also means that is it
possible to read two successive events that have the same value (e.g.
two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with
the same state). In that case the intermediate state changes were lost but
it is guaranteed that the state did change in between the two events.
.. _cec-event-state-change_s:
.. flat-table:: struct cec_event_state_change
:header-rows: 0
:stub-columns: 0
:widths: 1 1 8
- .. row 1
- __u16
- ``phys_addr``
- The current physical address.
- .. row 2
- __u16
- ``log_addr_mask``
- The current set of claimed logical addresses.
.. _cec-event-lost-msgs_s:
.. flat-table:: struct cec_event_lost_msgs
:header-rows: 0
:stub-columns: 0
:widths: 1 1 16
- .. row 1
- __u32
- ``lost_msgs``
- Set to the number of lost messages since the filehandle was opened
or since the last time this event was dequeued for this
filehandle. The messages lost are the oldest messages. So when a
new message arrives and there is no more room, then the oldest
message is discarded to make room for the new one. The internal
size of the message queue guarantees that all messages received in
the last two seconds will be stored. Since messages should be
replied to within a second according to the CEC specification,
this is more than enough.
.. _cec-event:
.. flat-table:: struct cec_event
:header-rows: 0
:stub-columns: 0
:widths: 1 1 1 8
- .. row 1
- __u64
- ``ts``
- Timestamp of the event in ns.
The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
the same clock from userspace use :c:func:`clock_gettime(2)`.
-
- .. row 2
- __u32
- ``event``
- The CEC event type, see :ref:`cec-events`.
-
- .. row 3
- __u32
- ``flags``
- Event flags, see :ref:`cec-event-flags`.
-
- .. row 4
- union
- (anonymous)
-
-
- .. row 5
-
- struct cec_event_state_change
- ``state_change``
- The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>`
event.
- .. row 6
-
- struct cec_event_lost_msgs
- ``lost_msgs``
- The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>`
event.
.. _cec-events:
.. flat-table:: CEC Events Types
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
- .. _`CEC-EVENT-STATE-CHANGE`:
- ``CEC_EVENT_STATE_CHANGE``
- 1
- Generated when the CEC Adapter's state changes. When open() is
called an initial event will be generated for that filehandle with
the CEC Adapter's state at that time.
- .. _`CEC-EVENT-LOST-MSGS`:
- ``CEC_EVENT_LOST_MSGS``
- 2
- Generated if one or more CEC messages were lost because the
application didn't dequeue CEC messages fast enough.
.. _cec-event-flags:
.. flat-table:: CEC Event Flags
:header-rows: 0
:stub-columns: 0
:widths: 3 1 8
- .. _`CEC-EVENT-FL-INITIAL-VALUE`:
- ``CEC_EVENT_FL_INITIAL_VALUE``
- 1
- Set for the initial events that are generated when the device is
opened. See the table above for which events do this. This allows
applications to learn the initial state of the CEC adapter at
open() time.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

295
Documentation/media/uapi/cec/cec-ioc-g-mode.rst Normal file
View File

@ -0,0 +1,295 @@
.. -*- coding: utf-8; mode: rst -*-
.. _CEC_MODE:
.. _CEC_G_MODE:
.. _CEC_S_MODE:
********************************
ioctls CEC_G_MODE and CEC_S_MODE
********************************
CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter
Synopsis
========
.. cpp:function:: int ioctl( int fd, int request, __u32 *argp )
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <cec-func-open>`.
``request``
CEC_G_MODE, CEC_S_MODE
``argp``
Description
===========
.. note:: This documents the proposed CEC API. This API is not yet finalized
and is currently only available as a staging kernel module.
By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent
applications from stepping on each others toes it must be possible to
obtain exclusive access to the CEC adapter. This ioctl sets the
filehandle to initiator and/or follower mode which can be exclusive
depending on the chosen mode. The initiator is the filehandle that is
used to initiate messages, i.e. it commands other CEC devices. The
follower is the filehandle that receives messages sent to the CEC
adapter and processes them. The same filehandle can be both initiator
and follower, or this role can be taken by two different filehandles.
When a CEC message is received, then the CEC framework will decide how
it will be processed. If the message is a reply to an earlier
transmitted message, then the reply is sent back to the filehandle that
is waiting for it. In addition the CEC framework will process it.
If the message is not a reply, then the CEC framework will process it
first. If there is no follower, then the message is just discarded and a
feature abort is sent back to the initiator if the framework couldn't
process it. If there is a follower, then the message is passed on to the
follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue
the new message. The framework expects the follower to make the right
decisions.
The CEC framework will process core messages unless requested otherwise
by the follower. The follower can enable the passthrough mode. In that
case, the CEC framework will pass on most core messages without
processing them and the follower will have to implement those messages.
There are some messages that the core will always process, regardless of
the passthrough mode. See :ref:`cec-core-processing` for details.
If there is no initiator, then any CEC filehandle can use
:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive
initiator then only that initiator can call
:ref:`CEC_TRANSMIT`. The follower can of course
always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
Available initiator modes are:
.. _cec-mode-initiator_e:
.. flat-table:: Initiator Modes
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
- .. _`CEC-MODE-NO-INITIATOR`:
- ``CEC_MODE_NO_INITIATOR``
- 0x0
- This is not an initiator, i.e. it cannot transmit CEC messages or
make any other changes to the CEC adapter.
- .. _`CEC-MODE-INITIATOR`:
- ``CEC_MODE_INITIATOR``
- 0x1
- This is an initiator (the default when the device is opened) and
it can transmit CEC messages and make changes to the CEC adapter,
unless there is an exclusive initiator.
- .. _`CEC-MODE-EXCL-INITIATOR`:
- ``CEC_MODE_EXCL_INITIATOR``
- 0x2
- This is an exclusive initiator and this file descriptor is the
only one that can transmit CEC messages and make changes to the
CEC adapter. If someone else is already the exclusive initiator
then an attempt to become one will return the ``EBUSY`` error code
error.
Available follower modes are:
.. _cec-mode-follower_e:
.. flat-table:: Follower Modes
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
- .. _`CEC-MODE-NO-FOLLOWER`:
- ``CEC_MODE_NO_FOLLOWER``
- 0x00
- This is not a follower (the default when the device is opened).
- .. _`CEC-MODE-FOLLOWER`:
- ``CEC_MODE_FOLLOWER``
- 0x10
- This is a follower and it will receive CEC messages unless there
is an exclusive follower. You cannot become a follower if
:ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
was specified, the ``EINVAL`` error code is returned in that case.
- .. _`CEC-MODE-EXCL-FOLLOWER`:
- ``CEC_MODE_EXCL_FOLLOWER``
- 0x20
- This is an exclusive follower and only this file descriptor will
receive CEC messages for processing. If someone else is already
the exclusive follower then an attempt to become one will return
the ``EBUSY`` error code. You cannot become a follower if
:ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
was specified, the ``EINVAL`` error code is returned in that case.
- .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`:
- ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU``
- 0x30
- This is an exclusive follower and only this file descriptor will
receive CEC messages for processing. In addition it will put the
CEC device into passthrough mode, allowing the exclusive follower
to handle most core messages instead of relying on the CEC
framework for that. If someone else is already the exclusive
follower then an attempt to become one will return the ``EBUSY`` error
code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>`
is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` was specified,
the ``EINVAL`` error code is returned in that case.
- .. _`CEC-MODE-MONITOR`:
- ``CEC_MODE_MONITOR``
- 0xe0
- Put the file descriptor into monitor mode. Can only be used in
combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise EINVAL error
code will be returned. In monitor mode all messages this CEC
device transmits and all messages it receives (both broadcast
messages and directed messages for one its logical addresses) will
be reported. This is very useful for debugging. This is only
allowed if the process has the ``CAP_NET_ADMIN`` capability. If
that is not set, then the ``EPERM`` error code is returned.
- .. _`CEC-MODE-MONITOR-ALL`:
- ``CEC_MODE_MONITOR_ALL``
- 0xf0
- Put the file descriptor into 'monitor all' mode. Can only be used
in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise
the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages
this CEC device transmits and all messages it receives, including
directed messages for other CEC devices will be reported. This is
very useful for debugging, but not all devices support this. This
mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set,
otherwise the ``EINVAL`` error code is returned. This is only allowed if
the process has the ``CAP_NET_ADMIN`` capability. If that is not
set, then the ``EPERM`` error code is returned.
Core message processing details:
.. _cec-core-processing:
.. flat-table:: Core Message Processing
:header-rows: 0
:stub-columns: 0
:widths: 1 8
- .. _`CEC-MSG-GET-CEC-VERSION`:
- ``CEC_MSG_GET_CEC_VERSION``
- When in passthrough mode this message has to be handled by
userspace, otherwise the core will return the CEC version that was
set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
- .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`:
- ``CEC_MSG_GIVE_DEVICE_VENDOR_ID``
- When in passthrough mode this message has to be handled by
userspace, otherwise the core will return the vendor ID that was
set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
- .. _`CEC-MSG-ABORT`:
- ``CEC_MSG_ABORT``
- When in passthrough mode this message has to be handled by
userspace, otherwise the core will return a feature refused
message as per the specification.
- .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`:
- ``CEC_MSG_GIVE_PHYSICAL_ADDR``
- When in passthrough mode this message has to be handled by
userspace, otherwise the core will report the current physical
address.
- .. _`CEC-MSG-GIVE-OSD-NAME`:
- ``CEC_MSG_GIVE_OSD_NAME``
- When in passthrough mode this message has to be handled by
userspace, otherwise the core will report the current OSD name as
was set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
- .. _`CEC-MSG-GIVE-FEATURES`:
- ``CEC_MSG_GIVE_FEATURES``
- When in passthrough mode this message has to be handled by
userspace, otherwise the core will report the current features as
was set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
or the message is ignored if the CEC version was older than 2.0.
- .. _`CEC-MSG-USER-CONTROL-PRESSED`:
- ``CEC_MSG_USER_CONTROL_PRESSED``
- If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set, then generate a remote control key
press. This message is always passed on to userspace.
- .. _`CEC-MSG-USER-CONTROL-RELEASED`:
- ``CEC_MSG_USER_CONTROL_RELEASED``
- If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set, then generate a remote control key
release. This message is always passed on to userspace.
- .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`:
- ``CEC_MSG_REPORT_PHYSICAL_ADDR``
- The CEC framework will make note of the reported physical address
and then just pass the message on to userspace.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

360
Documentation/media/uapi/cec/cec-ioc-receive.rst Normal file
View File

@ -0,0 +1,360 @@
.. -*- coding: utf-8; mode: rst -*-
.. _CEC_TRANSMIT:
.. _CEC_RECEIVE:
***********************************
ioctls CEC_RECEIVE and CEC_TRANSMIT
***********************************
Name
====
CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message
Synopsis
========
.. cpp:function:: int ioctl( int fd, int request, struct cec_msg *argp )
Arguments
=========
``fd``
File descriptor returned by :ref:`open() <cec-func-open>`.
``request``
CEC_RECEIVE, CEC_TRANSMIT
``argp``
Description
===========
.. note:: This documents the proposed CEC API. This API is not yet finalized
and is currently only available as a staging kernel module.
To receive a CEC message the application has to fill in the
``timeout`` field of :c:type:`struct cec_msg` and pass it to :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
If the file descriptor is in non-blocking mode and there are no received
messages pending, then it will return -1 and set errno to the ``EAGAIN``
error code. If the file descriptor is in blocking mode and ``timeout``
is non-zero and no message arrived within ``timeout`` milliseconds, then
it will return -1 and set errno to the ``ETIMEDOUT`` error code.
A received message can be:
1. a message received from another CEC device (the ``sequence`` field will
be 0).
2. the result of an earlier non-blocking transmit (the ``sequence`` field will
be non-zero).
To send a CEC message the application has to fill in the
:c:type:`struct cec_msg` and pass it to
:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is only available if
``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit
queue, then it will return -1 and set errno to the ``EBUSY`` error code.
The transmit queue has enough room for 18 messages (about 1 second worth
of 2-byte messages). Note that the CEC kernel framework will also reply
to core messages (see :ref:cec-core-processing), so it is not a good
idea to fully fill up the transmit queue.
If the file descriptor is in non-blocking mode then the transmit will
return 0 and the result of the transmit will be available via
:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once the transmit has finished
(including waiting for a reply, if requested).
The ``sequence`` field is filled in for every transmit and this can be
checked against the received messages to find the corresponding transmit
result.
.. _cec-msg:
.. flat-table:: struct cec_msg
:header-rows: 0
:stub-columns: 0
:widths: 1 1 16
- .. row 1
- __u64
- ``tx_ts``
- Timestamp in ns of when the last byte of the message was transmitted.
The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
the same clock from userspace use :c:func:`clock_gettime(2)`.
- .. row 2
- __u64
- ``rx_ts``
- Timestamp in ns of when the last byte of the message was received.
The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
the same clock from userspace use :c:func:`clock_gettime(2)`.
- .. row 3
- __u32
- ``len``
- The length of the message. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in
by the application. The driver will fill this in for
:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be
filled in by the driver with the length of the reply message if ``reply`` was set.
- .. row 4
- __u32
- ``timeout``
- The timeout in milliseconds. This is the time the device will wait
for a message to be received before timing out. If it is set to 0,
then it will wait indefinitely when it is called by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`,
then it will be replaced by 1000 if the ``reply`` is non-zero or
ignored if ``reply`` is 0.
- .. row 5
- __u32
- ``sequence``
- A non-zero sequence number is automatically assigned by the CEC framework
for all transmitted messages. It is used by the CEC framework when it queues
the transmit result (when transmit was called in non-blocking mode). This
allows the application to associate the received message with the original
transmit.
- .. row 6
- __u32
- ``flags``
- Flags. No flags are defined yet, so set this to 0.
- .. row 7
- __u8
- ``tx_status``
- The status bits of the transmitted message. See
:ref:`cec-tx-status` for the possible status values. It is 0 if
this messages was received, not transmitted.
- .. row 8
- __u8
- ``msg[16]``
- The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the
application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be filled in by the driver with
the payload of the reply message if ``timeout`` was set.
- .. row 8
- __u8
- ``reply``
- Wait until this message is replied. If ``reply`` is 0 and the
``timeout`` is 0, then don't wait for a reply but return after
transmitting the message. Ignored by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
The case where ``reply`` is 0 (this is the opcode for the Feature Abort
message) and ``timeout`` is non-zero is specifically allowed to make it
possible to send a message and wait up to ``timeout`` milliseconds for a
Feature Abort reply. In this case ``rx_status`` will either be set
to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or
:ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC-RX-STATUS-FEATURE-ABORT>`.
- .. row 9
- __u8
- ``rx_status``
- The status bits of the received message. See
:ref:`cec-rx-status` for the possible status values. It is 0 if
this message was transmitted, not received, unless this is the
reply to a transmitted message. In that case both ``rx_status``
and ``tx_status`` are set.
- .. row 10
- __u8
- ``tx_status``
- The status bits of the transmitted message. See
:ref:`cec-tx-status` for the possible status values. It is 0 if
this messages was received, not transmitted.
- .. row 11
- __u8
- ``tx_arb_lost_cnt``
- A counter of the number of transmit attempts that resulted in the
Arbitration Lost error. This is only set if the hardware supports
this, otherwise it is always 0. This counter is only valid if the
:ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set.
- .. row 12
- __u8
- ``tx_nack_cnt``
- A counter of the number of transmit attempts that resulted in the
Not Acknowledged error. This is only set if the hardware supports
this, otherwise it is always 0. This counter is only valid if the
:ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set.
- .. row 13
- __u8
- ``tx_low_drive_cnt``
- A counter of the number of transmit attempts that resulted in the
Arbitration Lost error. This is only set if the hardware supports
this, otherwise it is always 0. This counter is only valid if the
:ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set.
- .. row 14
- __u8
- ``tx_error_cnt``
- A counter of the number of transmit errors other than Arbitration
Lost or Not Acknowledged. This is only set if the hardware
supports this, otherwise it is always 0. This counter is only
valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
.. _cec-tx-status:
.. flat-table:: CEC Transmit Status
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
- .. _`CEC-TX-STATUS-OK`:
- ``CEC_TX_STATUS_OK``
- 0x01
- The message was transmitted successfully. This is mutually
exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`. Other bits can still
be set if earlier attempts met with failure before the transmit
was eventually successful.
- .. _`CEC-TX-STATUS-ARB-LOST`:
- ``CEC_TX_STATUS_ARB_LOST``
- 0x02
- CEC line arbitration was lost.
- .. _`CEC-TX-STATUS-NACK`:
- ``CEC_TX_STATUS_NACK``
- 0x04
- Message was not acknowledged.
- .. _`CEC-TX-STATUS-LOW-DRIVE`:
- ``CEC_TX_STATUS_LOW_DRIVE``
- 0x08
- Low drive was detected on the CEC bus. This indicates that a
follower detected an error on the bus and requests a
retransmission.
- .. _`CEC-TX-STATUS-ERROR`:
- ``CEC_TX_STATUS_ERROR``
- 0x10
- Some error occurred. This is used for any errors that do not fit
the previous two, either because the hardware could not tell which
error occurred, or because the hardware tested for other
conditions besides those two.
- .. _`CEC-TX-STATUS-MAX-RETRIES`:
- ``CEC_TX_STATUS_MAX_RETRIES``
- 0x20
- The transmit failed after one or more retries. This status bit is
mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`. Other bits can still
be set to explain which failures were seen.
.. _cec-rx-status:
.. flat-table:: CEC Receive Status
:header-rows: 0
:stub-columns: 0
:widths: 3 1 16
- .. _`CEC-RX-STATUS-OK`:
- ``CEC_RX_STATUS_OK``
- 0x01
- The message was received successfully.
- .. _`CEC-RX-STATUS-TIMEOUT`:
- ``CEC_RX_STATUS_TIMEOUT``
- 0x02
- The reply to an earlier transmitted message timed out.
- .. _`CEC-RX-STATUS-FEATURE-ABORT`:
- ``CEC_RX_STATUS_FEATURE_ABORT``
- 0x04
- The message was received successfully but the reply was
``CEC_MSG_FEATURE_ABORT``. This status is only set if this message
was the reply to an earlier transmitted message.
Return Value
============
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

64
Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst Normal file
View File

@ -0,0 +1,64 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_BILINGUAL_CHANNEL_SELECT:
==============================
AUDIO_BILINGUAL_CHANNEL_SELECT
==============================
Name
----
AUDIO_BILINGUAL_CHANNEL_SELECT
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT, audio_channel_select_t)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_BILINGUAL_CHANNEL_SELECT for this command.
- .. row 3
- audio_channel_select_t ch
- Select the output format of the audio (mono left/right, stereo).
Description
-----------
This ioctl is obsolete. Do not use in new drivers. It has been replaced
by the V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control
for MPEG decoders controlled through V4L2.
This ioctl call asks the Audio Device to select the requested channel
for bilingual streams if possible.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

63
Documentation/media/uapi/dvb/audio-channel-select.rst Normal file
View File

@ -0,0 +1,63 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_CHANNEL_SELECT:
====================
AUDIO_CHANNEL_SELECT
====================
Name
----
AUDIO_CHANNEL_SELECT
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT, audio_channel_select_t)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_CHANNEL_SELECT for this command.
- .. row 3
- audio_channel_select_t ch
- Select the output format of the audio (mono left/right, stereo).
Description
-----------
This ioctl is for DVB devices only. To control a V4L2 decoder use the
V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead.
This ioctl call asks the Audio Device to select the requested channel if
possible.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

54
Documentation/media/uapi/dvb/audio-clear-buffer.rst Normal file
View File

@ -0,0 +1,54 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_CLEAR_BUFFER:
==================
AUDIO_CLEAR_BUFFER
==================
Name
----
AUDIO_CLEAR_BUFFER
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_CLEAR_BUFFER for this command.
Description
-----------
This ioctl call asks the Audio Device to clear all software and hardware
buffers of the audio decoder device.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

54
Documentation/media/uapi/dvb/audio-continue.rst Normal file
View File

@ -0,0 +1,54 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_CONTINUE:
==============
AUDIO_CONTINUE
==============
Name
----
AUDIO_CONTINUE
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_CONTINUE)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_CONTINUE for this command.
Description
-----------
This ioctl restarts the decoding and playing process previously paused
with AUDIO_PAUSE command.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

54
Documentation/media/uapi/dvb/audio-fclose.rst Normal file
View File

@ -0,0 +1,54 @@
.. -*- coding: utf-8; mode: rst -*-
.. _audio_fclose:
=================
DVB audio close()
=================
Name
----
DVB audio close()
Synopsis
--------
.. cpp:function:: int close(int fd)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
Description
-----------
This system call closes a previously opened audio device.
Return Value
------------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``EBADF``
- fd is not a valid open file descriptor.

104
Documentation/media/uapi/dvb/audio-fopen.rst Normal file
View File

@ -0,0 +1,104 @@
.. -*- coding: utf-8; mode: rst -*-
.. _audio_fopen:
================
DVB audio open()
================
Name
----
DVB audio open()
Synopsis
--------
.. cpp:function:: int open(const char *deviceName, int flags)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- const char \*deviceName
- Name of specific audio device.
- .. row 2
- int flags
- A bit-wise OR of the following flags:
- .. row 3
-
- O_RDONLY read-only access
- .. row 4
-
- O_RDWR read/write access
- .. row 5
-
- O_NONBLOCK open in non-blocking mode
- .. row 6
-
- (blocking mode is the default)
Description
-----------
This system call opens a named audio device (e.g.
/dev/dvb/adapter0/audio0) for subsequent use. When an open() call has
succeeded, the device will be ready for use. The significance of
blocking or non-blocking mode is described in the documentation for
functions where there is a difference. It does not affect the semantics
of the open() call itself. A device opened in blocking mode can later be
put into non-blocking mode (and vice versa) using the F_SETFL command
of the fcntl system call. This is a standard system call, documented in
the Linux manual page for fcntl. Only one user can open the Audio Device
in O_RDWR mode. All other attempts to open the device in this mode will
fail, and an error code will be returned. If the Audio Device is opened
in O_RDONLY mode, the only ioctl call that can be used is
AUDIO_GET_STATUS. All other call will return with an error code.
Return Value
------------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``ENODEV``
- Device driver not loaded/available.
- .. row 2
- ``EBUSY``
- Device or resource busy.
- .. row 3
- ``EINVAL``
- Invalid argument.

82
Documentation/media/uapi/dvb/audio-fwrite.rst Normal file
View File

@ -0,0 +1,82 @@
.. -*- coding: utf-8; mode: rst -*-
.. _audio_fwrite:
=================
DVB audio write()
=================
Name
----
DVB audio write()
Synopsis
--------
.. cpp:function:: size_t write(int fd, const void *buf, size_t count)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- void \*buf
- Pointer to the buffer containing the PES data.
- .. row 3
- size_t count
- Size of buf.
Description
-----------
This system call can only be used if AUDIO_SOURCE_MEMORY is selected
in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in
PES format. If O_NONBLOCK is not specified the function will block
until buffer space is available. The amount of data to be transferred is
implied by count.
Return Value
------------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``EPERM``
- Mode AUDIO_SOURCE_MEMORY not selected.
- .. row 2
- ``ENOMEM``
- Attempted to write more data than the internal buffer can hold.
- .. row 3
- ``EBADF``
- fd is not a valid open file descriptor.

60
Documentation/media/uapi/dvb/audio-get-capabilities.rst Normal file
View File

@ -0,0 +1,60 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_GET_CAPABILITIES:
======================
AUDIO_GET_CAPABILITIES
======================
Name
----
AUDIO_GET_CAPABILITIES
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES, unsigned int *cap)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_GET_CAPABILITIES for this command.
- .. row 3
- unsigned int \*cap
- Returns a bit array of supported sound formats.
Description
-----------
This ioctl call asks the Audio Device to tell us about the decoding
capabilities of the audio hardware.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

69
Documentation/media/uapi/dvb/audio-get-pts.rst Normal file
View File

@ -0,0 +1,69 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_GET_PTS:
=============
AUDIO_GET_PTS
=============
Name
----
AUDIO_GET_PTS
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_PTS, __u64 *pts)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_GET_PTS for this command.
- .. row 3
- __u64 \*pts
- Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 /
ISO/IEC 13818-1.
The PTS should belong to the currently played frame if possible,
but may also be a value close to it like the PTS of the last
decoded frame or the last PTS extracted by the PES parser.
Description
-----------
This ioctl is obsolete. Do not use in new drivers. If you need this
functionality, then please contact the linux-media mailing list
(`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__).
This ioctl call asks the Audio Device to return the current PTS
timestamp.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

60
Documentation/media/uapi/dvb/audio-get-status.rst Normal file
View File

@ -0,0 +1,60 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_GET_STATUS:
================
AUDIO_GET_STATUS
================
Name
----
AUDIO_GET_STATUS
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_STATUS, struct audio_status *status)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_GET_STATUS for this command.
- .. row 3
- struct audio_status \*status
- Returns the current state of Audio Device.
Description
-----------
This ioctl call asks the Audio Device to return the current state of the
Audio Device.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

55
Documentation/media/uapi/dvb/audio-pause.rst Normal file
View File

@ -0,0 +1,55 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_PAUSE:
===========
AUDIO_PAUSE
===========
Name
----
AUDIO_PAUSE
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_PAUSE)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_PAUSE for this command.
Description
-----------
This ioctl call suspends the audio stream being played. Decoding and
playing are paused. It is then possible to restart again decoding and
playing process of the audio stream using AUDIO_CONTINUE command.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

54
Documentation/media/uapi/dvb/audio-play.rst Normal file
View File

@ -0,0 +1,54 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_PLAY:
==========
AUDIO_PLAY
==========
Name
----
AUDIO_PLAY
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_PLAY)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_PLAY for this command.
Description
-----------
This ioctl call asks the Audio Device to start playing an audio stream
from the selected source.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

62
Documentation/media/uapi/dvb/audio-select-source.rst Normal file
View File

@ -0,0 +1,62 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_SELECT_SOURCE:
===================
AUDIO_SELECT_SOURCE
===================
Name
----
AUDIO_SELECT_SOURCE
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, audio_stream_source_t source)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_SELECT_SOURCE for this command.
- .. row 3
- audio_stream_source_t source
- Indicates the source that shall be used for the Audio stream.
Description
-----------
This ioctl call informs the audio device which source shall be used for
the input data. The possible sources are demux or memory. If
AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device
through the write command.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

71
Documentation/media/uapi/dvb/audio-set-attributes.rst Normal file
View File

@ -0,0 +1,71 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_SET_ATTRIBUTES:
====================
AUDIO_SET_ATTRIBUTES
====================
Name
----
AUDIO_SET_ATTRIBUTES
Synopsis
--------
.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES, audio_attributes_t attr )
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_SET_ATTRIBUTES for this command.
- .. row 3
- audio_attributes_t attr
- audio attributes according to section ??
Description
-----------
This ioctl is intended for DVD playback and allows you to set certain
information about the audio stream.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``EINVAL``
- attr is not a valid or supported attribute setting.

70
Documentation/media/uapi/dvb/audio-set-av-sync.rst Normal file
View File

@ -0,0 +1,70 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_SET_AV_SYNC:
=================
AUDIO_SET_AV_SYNC
=================
Name
----
AUDIO_SET_AV_SYNC
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, boolean state)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_AV_SYNC for this command.
- .. row 3
- boolean state
- Tells the DVB subsystem if A/V synchronization shall be ON or OFF.
- .. row 4
-
- TRUE AV-sync ON
- .. row 5
-
- FALSE AV-sync OFF
Description
-----------
This ioctl call asks the Audio Device to turn ON or OFF A/V
synchronization.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

74
Documentation/media/uapi/dvb/audio-set-bypass-mode.rst Normal file
View File

@ -0,0 +1,74 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_SET_BYPASS_MODE:
=====================
AUDIO_SET_BYPASS_MODE
=====================
Name
----
AUDIO_SET_BYPASS_MODE
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, boolean mode)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_SET_BYPASS_MODE for this command.
- .. row 3
- boolean mode
- Enables or disables the decoding of the current Audio stream in
the DVB subsystem.
- .. row 4
-
- TRUE Bypass is disabled
- .. row 5
-
- FALSE Bypass is enabled
Description
-----------
This ioctl call asks the Audio Device to bypass the Audio decoder and
forward the stream without decoding. This mode shall be used if streams
that can’t be handled by the DVB system shall be decoded. Dolby
DigitalTM streams are automatically forwarded by the DVB subsystem if
the hardware can handle it.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

71
Documentation/media/uapi/dvb/audio-set-ext-id.rst Normal file
View File

@ -0,0 +1,71 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_SET_EXT_ID:
================
AUDIO_SET_EXT_ID
================
Name
----
AUDIO_SET_EXT_ID
Synopsis
--------
.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_EXT_ID, int id)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_SET_EXT_ID for this command.
- .. row 3
- int id
- audio sub_stream_id
Description
-----------
This ioctl can be used to set the extension id for MPEG streams in DVD
playback. Only the first 3 bits are recognized.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``EINVAL``
- id is not a valid id.

65
Documentation/media/uapi/dvb/audio-set-id.rst Normal file
View File

@ -0,0 +1,65 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_SET_ID:
============
AUDIO_SET_ID
============
Name
----
AUDIO_SET_ID
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_ID, int id)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_SET_ID for this command.
- .. row 3
- int id
- audio sub-stream id
Description
-----------
This ioctl selects which sub-stream is to be decoded if a program or
system stream is sent to the video device. If no audio stream type is
set the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for
AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow for
other stream types. If the stream type is set the id just specifies the
substream id of the audio stream and only the first 5 bits are
recognized.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

70
Documentation/media/uapi/dvb/audio-set-karaoke.rst Normal file
View File

@ -0,0 +1,70 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_SET_KARAOKE:
=================
AUDIO_SET_KARAOKE
=================
Name
----
AUDIO_SET_KARAOKE
Synopsis
--------
.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_KARAOKE, audio_karaoke_t *karaoke)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_SET_KARAOKE for this command.
- .. row 3
- audio_karaoke_t \*karaoke
- karaoke settings according to section ??.
Description
-----------
This ioctl allows one to set the mixer settings for a karaoke DVD.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- ``EINVAL``
- karaoke is not a valid or supported karaoke setting.

59
Documentation/media/uapi/dvb/audio-set-mixer.rst Normal file
View File

@ -0,0 +1,59 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_SET_MIXER:
===============
AUDIO_SET_MIXER
===============
Name
----
AUDIO_SET_MIXER
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_SET_ID for this command.
- .. row 3
- audio_mixer_t \*mix
- mixer settings.
Description
-----------
This ioctl lets you adjust the mixer settings of the audio decoder.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

74
Documentation/media/uapi/dvb/audio-set-mute.rst Normal file
View File

@ -0,0 +1,74 @@
.. -*- coding: utf-8; mode: rst -*-
.. _AUDIO_SET_MUTE:
==============
AUDIO_SET_MUTE
==============
Name
----
AUDIO_SET_MUTE
Synopsis
--------
.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_MUTE, boolean state)
Arguments
---------
.. flat-table::
:header-rows: 0
:stub-columns: 0
- .. row 1
- int fd
- File descriptor returned by a previous call to open().
- .. row 2
- int request
- Equals AUDIO_SET_MUTE for this command.
- .. row 3
- boolean state
- Indicates if audio device shall mute or not.
- .. row 4
-
- TRUE Audio Mute
- .. row 5
-
- FALSE Audio Un-mute
Description
-----------
This ioctl is for DVB devices only. To control a V4L2 decoder use the
V4L2 :ref:`VIDIOC_DECODER_CMD` with the
``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead.
This ioctl call asks the audio device to mute the stream that is
currently being played.
Return Value
------------
On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

Some files were not shown because too many files have changed in this diff Show More