From 54f38fcae536ea202ce7d6a359521492fba30c1f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 4 Mar 2020 10:21:39 +0100 Subject: media: docs: move uAPI book to userspace-api/media Since 2017, there is an space reserved for userspace API, created by changeset 1d596dee3862 ("docs: Create a user-space API guide"). As the media subsystem was one of the first subsystems to use Sphinx, until this patch, we were keeping things on a separate place. Let's just use the new location, as having all uAPI altogether will likely make things easier for developers. Signed-off-by: Mauro Carvalho Chehab --- Documentation/media/Makefile | 69 - Documentation/media/audio.h.rst.exceptions | 19 - Documentation/media/ca.h.rst.exceptions | 25 - Documentation/media/cec.h.rst.exceptions | 575 -- Documentation/media/conf_nitpick.py | 111 - Documentation/media/dmx.h.rst.exceptions | 66 - Documentation/media/frontend.h.rst.exceptions | 214 - Documentation/media/index.rst | 2 +- Documentation/media/intro.rst | 46 - Documentation/media/lirc.h.rst.exceptions | 80 - Documentation/media/media.h.rst.exceptions | 32 - Documentation/media/media_uapi.rst | 33 - Documentation/media/net.h.rst.exceptions | 13 - Documentation/media/typical_media_device.svg | 116 - Documentation/media/uapi/cec/cec-api.rst | 54 - Documentation/media/uapi/cec/cec-func-close.rst | 54 - Documentation/media/uapi/cec/cec-func-ioctl.rst | 73 - Documentation/media/uapi/cec/cec-func-open.rst | 85 - Documentation/media/uapi/cec/cec-func-poll.rst | 85 - Documentation/media/uapi/cec/cec-funcs.rst | 30 - Documentation/media/uapi/cec/cec-header.rst | 17 - Documentation/media/uapi/cec/cec-intro.rst | 49 - .../media/uapi/cec/cec-ioc-adap-g-caps.rst | 150 - .../media/uapi/cec/cec-ioc-adap-g-conn-info.rst | 105 - .../media/uapi/cec/cec-ioc-adap-g-log-addrs.rst | 378 - .../media/uapi/cec/cec-ioc-adap-g-phys-addr.rst | 100 - Documentation/media/uapi/cec/cec-ioc-dqevent.rst | 257 - Documentation/media/uapi/cec/cec-ioc-g-mode.rst | 301 - Documentation/media/uapi/cec/cec-ioc-receive.rst | 391 - Documentation/media/uapi/cec/cec-pin-error-inj.rst | 334 - .../uapi/dvb/audio-bilingual-channel-select.rst | 66 - .../media/uapi/dvb/audio-channel-select.rst | 66 - .../media/uapi/dvb/audio-clear-buffer.rst | 55 - Documentation/media/uapi/dvb/audio-continue.rst | 56 - Documentation/media/uapi/dvb/audio-fclose.rst | 63 - Documentation/media/uapi/dvb/audio-fopen.rst | 115 - Documentation/media/uapi/dvb/audio-fwrite.rst | 91 - .../media/uapi/dvb/audio-get-capabilities.rst | 63 - Documentation/media/uapi/dvb/audio-get-status.rst | 63 - Documentation/media/uapi/dvb/audio-pause.rst | 57 - Documentation/media/uapi/dvb/audio-play.rst | 56 - .../media/uapi/dvb/audio-select-source.rst | 65 - Documentation/media/uapi/dvb/audio-set-av-sync.rst | 67 - .../media/uapi/dvb/audio-set-bypass-mode.rst | 70 - Documentation/media/uapi/dvb/audio-set-id.rst | 67 - Documentation/media/uapi/dvb/audio-set-mixer.rst | 61 - Documentation/media/uapi/dvb/audio-set-mute.rst | 71 - .../media/uapi/dvb/audio-set-streamtype.rst | 77 - Documentation/media/uapi/dvb/audio-stop.rst | 56 - Documentation/media/uapi/dvb/audio.rst | 34 - Documentation/media/uapi/dvb/audio_data_types.rst | 123 - .../media/uapi/dvb/audio_function_calls.rst | 37 - Documentation/media/uapi/dvb/ca-fclose.rst | 50 - Documentation/media/uapi/dvb/ca-fopen.rst | 84 - Documentation/media/uapi/dvb/ca-get-cap.rst | 53 - Documentation/media/uapi/dvb/ca-get-descr-info.rst | 49 - Documentation/media/uapi/dvb/ca-get-msg.rst | 59 - Documentation/media/uapi/dvb/ca-get-slot-info.rst | 64 - Documentation/media/uapi/dvb/ca-reset.rst | 51 - Documentation/media/uapi/dvb/ca-send-msg.rst | 58 - Documentation/media/uapi/dvb/ca-set-descr.rst | 53 - Documentation/media/uapi/dvb/ca.rst | 32 - Documentation/media/uapi/dvb/ca_data_types.rst | 16 - Documentation/media/uapi/dvb/ca_function_calls.rst | 27 - Documentation/media/uapi/dvb/ca_high_level.rst | 157 - Documentation/media/uapi/dvb/demux.rst | 30 - Documentation/media/uapi/dvb/dmx-add-pid.rst | 56 - Documentation/media/uapi/dvb/dmx-expbuf.rst | 97 - Documentation/media/uapi/dvb/dmx-fclose.rst | 52 - Documentation/media/uapi/dvb/dmx-fopen.rst | 98 - Documentation/media/uapi/dvb/dmx-fread.rst | 87 - Documentation/media/uapi/dvb/dmx-fwrite.rst | 79 - Documentation/media/uapi/dvb/dmx-get-pes-pids.rst | 71 - Documentation/media/uapi/dvb/dmx-get-stc.rst | 73 - Documentation/media/uapi/dvb/dmx-mmap.rst | 125 - Documentation/media/uapi/dvb/dmx-munmap.rst | 63 - Documentation/media/uapi/dvb/dmx-qbuf.rst | 93 - Documentation/media/uapi/dvb/dmx-querybuf.rst | 72 - Documentation/media/uapi/dvb/dmx-remove-pid.rst | 57 - Documentation/media/uapi/dvb/dmx-reqbufs.rst | 83 - .../media/uapi/dvb/dmx-set-buffer-size.rst | 57 - Documentation/media/uapi/dvb/dmx-set-filter.rst | 64 - .../media/uapi/dvb/dmx-set-pes-filter.rst | 76 - Documentation/media/uapi/dvb/dmx-start.rst | 75 - Documentation/media/uapi/dvb/dmx-stop.rst | 52 - Documentation/media/uapi/dvb/dmx_fcalls.rst | 37 - Documentation/media/uapi/dvb/dmx_types.rst | 16 - .../media/uapi/dvb/dvb-fe-read-status.rst | 32 - .../media/uapi/dvb/dvb-frontend-event.rst | 22 - .../media/uapi/dvb/dvb-frontend-parameters.rst | 126 - Documentation/media/uapi/dvb/dvbapi.rst | 126 - Documentation/media/uapi/dvb/dvbproperty.rst | 133 - Documentation/media/uapi/dvb/dvbstb.svg | 43 - Documentation/media/uapi/dvb/examples.rst | 23 - Documentation/media/uapi/dvb/fe-bandwidth-t.rst | 81 - .../media/uapi/dvb/fe-diseqc-recv-slave-reply.rst | 55 - .../media/uapi/dvb/fe-diseqc-reset-overload.rst | 53 - .../media/uapi/dvb/fe-diseqc-send-burst.rst | 59 - .../media/uapi/dvb/fe-diseqc-send-master-cmd.rst | 56 - .../uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst | 62 - .../media/uapi/dvb/fe-enable-high-lnb-voltage.rst | 61 - Documentation/media/uapi/dvb/fe-get-event.rst | 78 - Documentation/media/uapi/dvb/fe-get-frontend.rst | 69 - Documentation/media/uapi/dvb/fe-get-info.rst | 70 - Documentation/media/uapi/dvb/fe-get-property.rst | 83 - Documentation/media/uapi/dvb/fe-read-ber.rst | 57 - .../media/uapi/dvb/fe-read-signal-strength.rst | 57 - Documentation/media/uapi/dvb/fe-read-snr.rst | 57 - Documentation/media/uapi/dvb/fe-read-status.rst | 72 - .../media/uapi/dvb/fe-read-uncorrected-blocks.rst | 59 - .../media/uapi/dvb/fe-set-frontend-tune-mode.rst | 64 - Documentation/media/uapi/dvb/fe-set-frontend.rst | 78 - Documentation/media/uapi/dvb/fe-set-tone.rst | 65 - Documentation/media/uapi/dvb/fe-set-voltage.rst | 69 - Documentation/media/uapi/dvb/fe-type-t.rst | 98 - .../media/uapi/dvb/fe_property_parameters.rst | 1014 --- Documentation/media/uapi/dvb/frontend-header.rst | 13 - .../uapi/dvb/frontend-property-cable-systems.rst | 82 - .../dvb/frontend-property-satellite-systems.rst | 112 - .../dvb/frontend-property-terrestrial-systems.rst | 301 - .../media/uapi/dvb/frontend-stat-properties.rst | 252 - Documentation/media/uapi/dvb/frontend.rst | 63 - Documentation/media/uapi/dvb/frontend_f_close.rst | 57 - Documentation/media/uapi/dvb/frontend_f_open.rst | 117 - Documentation/media/uapi/dvb/frontend_fcalls.rst | 31 - .../media/uapi/dvb/frontend_legacy_api.rst | 45 - .../media/uapi/dvb/frontend_legacy_dvbv3_api.rst | 25 - Documentation/media/uapi/dvb/headers.rst | 30 - Documentation/media/uapi/dvb/intro.rst | 190 - Documentation/media/uapi/dvb/legacy_dvb_apis.rst | 39 - Documentation/media/uapi/dvb/net-add-if.rst | 60 - Documentation/media/uapi/dvb/net-get-if.rst | 59 - Documentation/media/uapi/dvb/net-remove-if.rst | 55 - Documentation/media/uapi/dvb/net-types.rst | 16 - Documentation/media/uapi/dvb/net.rst | 48 - .../media/uapi/dvb/query-dvb-frontend-info.rst | 20 - .../media/uapi/dvb/video-clear-buffer.rst | 63 - Documentation/media/uapi/dvb/video-command.rst | 105 - Documentation/media/uapi/dvb/video-continue.rst | 66 - .../media/uapi/dvb/video-fast-forward.rst | 83 - Documentation/media/uapi/dvb/video-fclose.rst | 62 - Documentation/media/uapi/dvb/video-fopen.rst | 122 - Documentation/media/uapi/dvb/video-freeze.rst | 70 - Documentation/media/uapi/dvb/video-fwrite.rst | 90 - .../media/uapi/dvb/video-get-capabilities.rst | 70 - Documentation/media/uapi/dvb/video-get-event.rst | 114 - .../media/uapi/dvb/video-get-frame-count.rst | 74 - Documentation/media/uapi/dvb/video-get-pts.rst | 78 - Documentation/media/uapi/dvb/video-get-size.rst | 78 - Documentation/media/uapi/dvb/video-get-status.rst | 80 - Documentation/media/uapi/dvb/video-play.rst | 66 - .../media/uapi/dvb/video-select-source.rst | 84 - Documentation/media/uapi/dvb/video-set-blank.rst | 73 - .../media/uapi/dvb/video-set-display-format.rst | 69 - Documentation/media/uapi/dvb/video-set-format.rst | 92 - .../media/uapi/dvb/video-set-streamtype.rst | 70 - Documentation/media/uapi/dvb/video-slowmotion.rst | 83 - .../media/uapi/dvb/video-stillpicture.rst | 70 - Documentation/media/uapi/dvb/video-stop.rst | 83 - Documentation/media/uapi/dvb/video-try-command.rst | 75 - Documentation/media/uapi/dvb/video.rst | 43 - .../media/uapi/dvb/video_function_calls.rst | 42 - Documentation/media/uapi/dvb/video_types.rst | 255 - Documentation/media/uapi/fdl-appendix.rst | 478 -- Documentation/media/uapi/gen-errors.rst | 103 - .../media/uapi/mediactl/media-controller-intro.rst | 40 - .../media/uapi/mediactl/media-controller-model.rst | 42 - .../media/uapi/mediactl/media-controller.rst | 62 - .../media/uapi/mediactl/media-func-close.rst | 54 - .../media/uapi/mediactl/media-func-ioctl.rst | 74 - .../media/uapi/mediactl/media-func-open.rst | 76 - Documentation/media/uapi/mediactl/media-funcs.rst | 33 - Documentation/media/uapi/mediactl/media-header.rst | 17 - .../media/uapi/mediactl/media-ioc-device-info.rst | 118 - .../uapi/mediactl/media-ioc-enum-entities.rst | 156 - .../media/uapi/mediactl/media-ioc-enum-links.rst | 157 - .../media/uapi/mediactl/media-ioc-g-topology.rst | 307 - .../uapi/mediactl/media-ioc-request-alloc.rst | 90 - .../media/uapi/mediactl/media-ioc-setup-link.rst | 74 - .../uapi/mediactl/media-request-ioc-queue.rst | 102 - .../uapi/mediactl/media-request-ioc-reinit.rst | 75 - Documentation/media/uapi/mediactl/media-types.rst | 425 -- Documentation/media/uapi/mediactl/request-api.rst | 276 - .../media/uapi/mediactl/request-func-close.rst | 73 - .../media/uapi/mediactl/request-func-ioctl.rst | 91 - .../media/uapi/mediactl/request-func-poll.rst | 101 - Documentation/media/uapi/rc/keytable.c.rst | 183 - Documentation/media/uapi/rc/lirc-dev-intro.rst | 171 - Documentation/media/uapi/rc/lirc-dev.rst | 21 - Documentation/media/uapi/rc/lirc-func.rst | 34 - Documentation/media/uapi/rc/lirc-get-features.rst | 200 - Documentation/media/uapi/rc/lirc-get-rec-mode.rst | 74 - .../media/uapi/rc/lirc-get-rec-resolution.rst | 54 - Documentation/media/uapi/rc/lirc-get-send-mode.rst | 78 - Documentation/media/uapi/rc/lirc-get-timeout.rst | 63 - Documentation/media/uapi/rc/lirc-header.rst | 17 - Documentation/media/uapi/rc/lirc-read.rst | 76 - .../uapi/rc/lirc-set-measure-carrier-mode.rst | 53 - .../media/uapi/rc/lirc-set-rec-carrier-range.rst | 54 - .../media/uapi/rc/lirc-set-rec-carrier.rst | 53 - .../media/uapi/rc/lirc-set-rec-timeout-reports.rst | 56 - .../media/uapi/rc/lirc-set-rec-timeout.rst | 61 - .../media/uapi/rc/lirc-set-send-carrier.rst | 48 - .../media/uapi/rc/lirc-set-send-duty-cycle.rst | 54 - .../media/uapi/rc/lirc-set-transmitter-mask.rst | 58 - .../media/uapi/rc/lirc-set-wideband-receiver.rst | 63 - Documentation/media/uapi/rc/lirc-write.rst | 82 - Documentation/media/uapi/rc/rc-intro.rst | 31 - Documentation/media/uapi/rc/rc-protos.rst | 456 -- Documentation/media/uapi/rc/rc-sysfs-nodes.rst | 151 - Documentation/media/uapi/rc/rc-table-change.rst | 25 - Documentation/media/uapi/rc/rc-tables.rst | 766 -- Documentation/media/uapi/rc/remote_controllers.rst | 59 - Documentation/media/uapi/v4l/app-pri.rst | 37 - Documentation/media/uapi/v4l/async.rst | 16 - Documentation/media/uapi/v4l/audio.rst | 104 - Documentation/media/uapi/v4l/bayer.svg | 56 - Documentation/media/uapi/v4l/biblio.rst | 416 -- Documentation/media/uapi/v4l/buffer.rst | 817 -- Documentation/media/uapi/v4l/capture-example.rst | 20 - Documentation/media/uapi/v4l/capture.c.rst | 671 -- Documentation/media/uapi/v4l/colorspaces-defs.rst | 183 - .../media/uapi/v4l/colorspaces-details.rst | 813 -- Documentation/media/uapi/v4l/colorspaces.rst | 170 - Documentation/media/uapi/v4l/common-defs.rst | 20 - Documentation/media/uapi/v4l/common.rst | 64 - Documentation/media/uapi/v4l/compat.rst | 25 - Documentation/media/uapi/v4l/constraints.svg | 37 - Documentation/media/uapi/v4l/control.rst | 512 -- Documentation/media/uapi/v4l/crop.rst | 324 - Documentation/media/uapi/v4l/crop.svg | 290 - Documentation/media/uapi/v4l/depth-formats.rst | 24 - Documentation/media/uapi/v4l/dev-capture.rst | 111 - Documentation/media/uapi/v4l/dev-decoder.rst | 1101 --- Documentation/media/uapi/v4l/dev-event.rst | 54 - Documentation/media/uapi/v4l/dev-mem2mem.rst | 49 - Documentation/media/uapi/v4l/dev-meta.rst | 74 - Documentation/media/uapi/v4l/dev-osd.rst | 157 - Documentation/media/uapi/v4l/dev-output.rst | 108 - Documentation/media/uapi/v4l/dev-overlay.rst | 328 - Documentation/media/uapi/v4l/dev-radio.rst | 59 - Documentation/media/uapi/v4l/dev-raw-vbi.rst | 306 - Documentation/media/uapi/v4l/dev-rds.rst | 191 - Documentation/media/uapi/v4l/dev-sdr.rst | 114 - Documentation/media/uapi/v4l/dev-sliced-vbi.rst | 669 -- .../media/uapi/v4l/dev-stateless-decoder.rst | 424 -- Documentation/media/uapi/v4l/dev-subdev.rst | 503 -- Documentation/media/uapi/v4l/dev-touch.rst | 63 - Documentation/media/uapi/v4l/devices.rst | 33 - Documentation/media/uapi/v4l/diff-v4l.rst | 693 -- Documentation/media/uapi/v4l/dmabuf.rst | 169 - Documentation/media/uapi/v4l/dv-timings.rst | 45 - Documentation/media/uapi/v4l/ext-ctrls-camera.rst | 515 -- Documentation/media/uapi/v4l/ext-ctrls-codec.rst | 4264 ----------- Documentation/media/uapi/v4l/ext-ctrls-detect.rst | 71 - Documentation/media/uapi/v4l/ext-ctrls-dv.rst | 166 - Documentation/media/uapi/v4l/ext-ctrls-flash.rst | 192 - Documentation/media/uapi/v4l/ext-ctrls-fm-rx.rst | 95 - Documentation/media/uapi/v4l/ext-ctrls-fm-tx.rst | 188 - .../media/uapi/v4l/ext-ctrls-image-process.rst | 63 - .../media/uapi/v4l/ext-ctrls-image-source.rst | 67 - Documentation/media/uapi/v4l/ext-ctrls-jpeg.rst | 113 - .../media/uapi/v4l/ext-ctrls-rf-tuner.rst | 96 - Documentation/media/uapi/v4l/extended-controls.rst | 180 - Documentation/media/uapi/v4l/field-order.rst | 172 - Documentation/media/uapi/v4l/fieldseq_bt.svg | 2621 ------- Documentation/media/uapi/v4l/fieldseq_tb.svg | 2618 ------- Documentation/media/uapi/v4l/format.rst | 99 - Documentation/media/uapi/v4l/func-close.rst | 56 - Documentation/media/uapi/v4l/func-ioctl.rst | 69 - Documentation/media/uapi/v4l/func-mmap.rst | 148 - Documentation/media/uapi/v4l/func-munmap.rst | 65 - Documentation/media/uapi/v4l/func-open.rst | 90 - Documentation/media/uapi/v4l/func-poll.rst | 124 - Documentation/media/uapi/v4l/func-read.rst | 140 - Documentation/media/uapi/v4l/func-select.rst | 127 - Documentation/media/uapi/v4l/func-write.rst | 91 - Documentation/media/uapi/v4l/hist-v4l2.rst | 1374 ---- Documentation/media/uapi/v4l/hsv-formats.rst | 26 - Documentation/media/uapi/v4l/io.rst | 58 - .../media/uapi/v4l/libv4l-introduction.rst | 191 - Documentation/media/uapi/v4l/libv4l.rst | 20 - Documentation/media/uapi/v4l/meta-formats.rst | 27 - Documentation/media/uapi/v4l/mmap.rst | 292 - Documentation/media/uapi/v4l/nv12mt.svg | 477 -- Documentation/media/uapi/v4l/nv12mt_example.svg | 1616 ---- Documentation/media/uapi/v4l/open.rst | 165 - Documentation/media/uapi/v4l/pipeline.dot | 14 - Documentation/media/uapi/v4l/pixfmt-bayer.rst | 39 - Documentation/media/uapi/v4l/pixfmt-cnf4.rst | 31 - Documentation/media/uapi/v4l/pixfmt-compressed.rst | 232 - Documentation/media/uapi/v4l/pixfmt-grey.rst | 51 - Documentation/media/uapi/v4l/pixfmt-indexed.rst | 54 - Documentation/media/uapi/v4l/pixfmt-intro.rst | 58 - Documentation/media/uapi/v4l/pixfmt-inzi.rst | 89 - Documentation/media/uapi/v4l/pixfmt-m420.rst | 133 - Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst | 220 - .../media/uapi/v4l/pixfmt-meta-intel-ipu3.rst | 104 - Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst | 58 - Documentation/media/uapi/v4l/pixfmt-meta-vivid.rst | 60 - .../media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst | 175 - .../media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst | 136 - Documentation/media/uapi/v4l/pixfmt-nv12.rst | 136 - Documentation/media/uapi/v4l/pixfmt-nv12m.rst | 151 - Documentation/media/uapi/v4l/pixfmt-nv12mt.rst | 67 - Documentation/media/uapi/v4l/pixfmt-nv16.rst | 160 - Documentation/media/uapi/v4l/pixfmt-nv16m.rst | 164 - Documentation/media/uapi/v4l/pixfmt-nv24.rst | 102 - Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst | 164 - Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst | 380 - Documentation/media/uapi/v4l/pixfmt-reserved.rst | 282 - Documentation/media/uapi/v4l/pixfmt-rgb.rst | 1304 ---- Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst | 37 - Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst | 41 - Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst | 37 - Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst | 41 - .../media/uapi/v4l/pixfmt-sdr-pcu16be.rst | 62 - .../media/uapi/v4l/pixfmt-sdr-pcu18be.rst | 62 - .../media/uapi/v4l/pixfmt-sdr-pcu20be.rst | 62 - Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst | 39 - .../media/uapi/v4l/pixfmt-srggb10-ipu3.rst | 342 - Documentation/media/uapi/v4l/pixfmt-srggb10.rst | 83 - .../media/uapi/v4l/pixfmt-srggb10alaw8.rst | 31 - .../media/uapi/v4l/pixfmt-srggb10dpcm8.rst | 35 - Documentation/media/uapi/v4l/pixfmt-srggb10p.rst | 81 - Documentation/media/uapi/v4l/pixfmt-srggb12.rst | 84 - Documentation/media/uapi/v4l/pixfmt-srggb12p.rst | 94 - Documentation/media/uapi/v4l/pixfmt-srggb14.rst | 82 - Documentation/media/uapi/v4l/pixfmt-srggb14p.rst | 152 - Documentation/media/uapi/v4l/pixfmt-srggb16.rst | 76 - Documentation/media/uapi/v4l/pixfmt-srggb8.rst | 61 - Documentation/media/uapi/v4l/pixfmt-tch-td08.rst | 59 - Documentation/media/uapi/v4l/pixfmt-tch-td16.rst | 74 - Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst | 57 - Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst | 73 - Documentation/media/uapi/v4l/pixfmt-uv8.rst | 54 - Documentation/media/uapi/v4l/pixfmt-uyvy.rst | 117 - .../media/uapi/v4l/pixfmt-v4l2-mplane.rst | 138 - Documentation/media/uapi/v4l/pixfmt-v4l2.rst | 171 - Documentation/media/uapi/v4l/pixfmt-vyuy.rst | 115 - Documentation/media/uapi/v4l/pixfmt-y10.rst | 72 - Documentation/media/uapi/v4l/pixfmt-y10b.rst | 40 - Documentation/media/uapi/v4l/pixfmt-y10p.rst | 50 - Documentation/media/uapi/v4l/pixfmt-y12.rst | 72 - Documentation/media/uapi/v4l/pixfmt-y12i.rst | 43 - Documentation/media/uapi/v4l/pixfmt-y14.rst | 72 - Documentation/media/uapi/v4l/pixfmt-y16-be.rst | 76 - Documentation/media/uapi/v4l/pixfmt-y16.rst | 76 - Documentation/media/uapi/v4l/pixfmt-y41p.rst | 158 - Documentation/media/uapi/v4l/pixfmt-y8i.rst | 73 - Documentation/media/uapi/v4l/pixfmt-yuv410.rst | 134 - Documentation/media/uapi/v4l/pixfmt-yuv411p.rst | 122 - Documentation/media/uapi/v4l/pixfmt-yuv420.rst | 150 - Documentation/media/uapi/v4l/pixfmt-yuv420m.rst | 159 - Documentation/media/uapi/v4l/pixfmt-yuv422m.rst | 148 - Documentation/media/uapi/v4l/pixfmt-yuv422p.rst | 136 - Documentation/media/uapi/v4l/pixfmt-yuv444m.rst | 148 - Documentation/media/uapi/v4l/pixfmt-yuyv.rst | 125 - Documentation/media/uapi/v4l/pixfmt-yvyu.rst | 115 - Documentation/media/uapi/v4l/pixfmt-z16.rst | 73 - Documentation/media/uapi/v4l/pixfmt.rst | 45 - Documentation/media/uapi/v4l/planar-apis.rst | 68 - Documentation/media/uapi/v4l/querycap.rst | 41 - Documentation/media/uapi/v4l/rw.rst | 54 - Documentation/media/uapi/v4l/sdr-formats.rst | 29 - .../media/uapi/v4l/selection-api-configuration.rst | 144 - .../media/uapi/v4l/selection-api-examples.rst | 91 - .../media/uapi/v4l/selection-api-intro.rst | 35 - .../media/uapi/v4l/selection-api-targets.rst | 27 - .../media/uapi/v4l/selection-api-vs-crop-api.rst | 46 - Documentation/media/uapi/v4l/selection-api.rst | 23 - Documentation/media/uapi/v4l/selection.svg | 1178 --- Documentation/media/uapi/v4l/selections-common.rst | 30 - Documentation/media/uapi/v4l/standard.rst | 192 - Documentation/media/uapi/v4l/streaming-par.rst | 40 - Documentation/media/uapi/v4l/subdev-formats.rst | 7833 -------------------- .../uapi/v4l/subdev-image-processing-crop.svg | 312 - .../uapi/v4l/subdev-image-processing-full.svg | 752 -- ...ubdev-image-processing-scaling-multi-source.svg | 550 -- Documentation/media/uapi/v4l/tch-formats.rst | 25 - Documentation/media/uapi/v4l/tuner.rst | 92 - Documentation/media/uapi/v4l/user-func.rst | 88 - Documentation/media/uapi/v4l/userp.rst | 128 - .../media/uapi/v4l/v4l2-selection-flags.rst | 51 - .../media/uapi/v4l/v4l2-selection-targets.rst | 78 - Documentation/media/uapi/v4l/v4l2.rst | 423 -- Documentation/media/uapi/v4l/v4l2grab-example.rst | 24 - Documentation/media/uapi/v4l/v4l2grab.c.rst | 176 - Documentation/media/uapi/v4l/vbi_525.svg | 821 -- Documentation/media/uapi/v4l/vbi_625.svg | 870 --- Documentation/media/uapi/v4l/vbi_hsync.svg | 321 - Documentation/media/uapi/v4l/video.rst | 75 - Documentation/media/uapi/v4l/videodev.rst | 16 - .../media/uapi/v4l/vidioc-create-bufs.rst | 141 - Documentation/media/uapi/v4l/vidioc-cropcap.rst | 143 - .../media/uapi/v4l/vidioc-dbg-g-chip-info.rst | 167 - .../media/uapi/v4l/vidioc-dbg-g-register.rst | 171 - .../media/uapi/v4l/vidioc-decoder-cmd.rst | 226 - Documentation/media/uapi/v4l/vidioc-dqevent.rst | 391 - .../media/uapi/v4l/vidioc-dv-timings-cap.rst | 169 - .../media/uapi/v4l/vidioc-encoder-cmd.rst | 168 - .../media/uapi/v4l/vidioc-enum-dv-timings.rst | 114 - Documentation/media/uapi/v4l/vidioc-enum-fmt.rst | 159 - .../media/uapi/v4l/vidioc-enum-frameintervals.rst | 203 - .../media/uapi/v4l/vidioc-enum-framesizes.rst | 213 - .../media/uapi/v4l/vidioc-enum-freq-bands.rst | 150 - Documentation/media/uapi/v4l/vidioc-enumaudio.rst | 62 - .../media/uapi/v4l/vidioc-enumaudioout.rst | 67 - Documentation/media/uapi/v4l/vidioc-enuminput.rst | 242 - Documentation/media/uapi/v4l/vidioc-enumoutput.rst | 165 - Documentation/media/uapi/v4l/vidioc-enumstd.rst | 367 - Documentation/media/uapi/v4l/vidioc-expbuf.rst | 175 - Documentation/media/uapi/v4l/vidioc-g-audio.rst | 135 - Documentation/media/uapi/v4l/vidioc-g-audioout.rst | 108 - Documentation/media/uapi/v4l/vidioc-g-crop.rst | 119 - Documentation/media/uapi/v4l/vidioc-g-ctrl.rst | 106 - .../media/uapi/v4l/vidioc-g-dv-timings.rst | 312 - Documentation/media/uapi/v4l/vidioc-g-edid.rst | 154 - .../media/uapi/v4l/vidioc-g-enc-index.rst | 156 - .../media/uapi/v4l/vidioc-g-ext-ctrls.rst | 416 -- Documentation/media/uapi/v4l/vidioc-g-fbuf.rst | 362 - Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 161 - .../media/uapi/v4l/vidioc-g-frequency.rst | 112 - Documentation/media/uapi/v4l/vidioc-g-input.rst | 71 - Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst | 134 - .../media/uapi/v4l/vidioc-g-modulator.rst | 202 - Documentation/media/uapi/v4l/vidioc-g-output.rst | 73 - Documentation/media/uapi/v4l/vidioc-g-parm.rst | 270 - Documentation/media/uapi/v4l/vidioc-g-priority.rst | 100 - .../media/uapi/v4l/vidioc-g-selection.rst | 200 - .../media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst | 202 - Documentation/media/uapi/v4l/vidioc-g-std.rst | 81 - Documentation/media/uapi/v4l/vidioc-g-tuner.rst | 476 -- Documentation/media/uapi/v4l/vidioc-log-status.rst | 56 - Documentation/media/uapi/v4l/vidioc-overlay.rst | 61 - .../media/uapi/v4l/vidioc-prepare-buf.rst | 65 - Documentation/media/uapi/v4l/vidioc-qbuf.rst | 205 - .../media/uapi/v4l/vidioc-query-dv-timings.rst | 94 - Documentation/media/uapi/v4l/vidioc-querybuf.rst | 87 - Documentation/media/uapi/v4l/vidioc-querycap.rst | 284 - Documentation/media/uapi/v4l/vidioc-queryctrl.rst | 616 -- Documentation/media/uapi/v4l/vidioc-querystd.rst | 77 - Documentation/media/uapi/v4l/vidioc-reqbufs.rst | 169 - .../media/uapi/v4l/vidioc-s-hw-freq-seek.rst | 147 - Documentation/media/uapi/v4l/vidioc-streamon.rst | 113 - .../uapi/v4l/vidioc-subdev-enum-frame-interval.rst | 120 - .../uapi/v4l/vidioc-subdev-enum-frame-size.rst | 125 - .../uapi/v4l/vidioc-subdev-enum-mbus-code.rst | 98 - .../media/uapi/v4l/vidioc-subdev-g-crop.rst | 125 - .../media/uapi/v4l/vidioc-subdev-g-fmt.rst | 154 - .../uapi/v4l/vidioc-subdev-g-frame-interval.rst | 120 - .../media/uapi/v4l/vidioc-subdev-g-selection.rst | 125 - .../media/uapi/v4l/vidioc-subscribe-event.rst | 123 - Documentation/media/uapi/v4l/yuv-formats.rst | 64 - Documentation/media/video.h.rst.exceptions | 39 - Documentation/media/videodev2.h.rst.exceptions | 572 -- 456 files changed, 1 insertion(+), 81522 deletions(-) delete mode 100644 Documentation/media/Makefile delete mode 100644 Documentation/media/audio.h.rst.exceptions delete mode 100644 Documentation/media/ca.h.rst.exceptions delete mode 100644 Documentation/media/cec.h.rst.exceptions delete mode 100644 Documentation/media/conf_nitpick.py delete mode 100644 Documentation/media/dmx.h.rst.exceptions delete mode 100644 Documentation/media/frontend.h.rst.exceptions delete mode 100644 Documentation/media/intro.rst delete mode 100644 Documentation/media/lirc.h.rst.exceptions delete mode 100644 Documentation/media/media.h.rst.exceptions delete mode 100644 Documentation/media/media_uapi.rst delete mode 100644 Documentation/media/net.h.rst.exceptions delete mode 100644 Documentation/media/typical_media_device.svg delete mode 100644 Documentation/media/uapi/cec/cec-api.rst delete mode 100644 Documentation/media/uapi/cec/cec-func-close.rst delete mode 100644 Documentation/media/uapi/cec/cec-func-ioctl.rst delete mode 100644 Documentation/media/uapi/cec/cec-func-open.rst delete mode 100644 Documentation/media/uapi/cec/cec-func-poll.rst delete mode 100644 Documentation/media/uapi/cec/cec-funcs.rst delete mode 100644 Documentation/media/uapi/cec/cec-header.rst delete mode 100644 Documentation/media/uapi/cec/cec-intro.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-adap-g-conn-info.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-dqevent.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-g-mode.rst delete mode 100644 Documentation/media/uapi/cec/cec-ioc-receive.rst delete mode 100644 Documentation/media/uapi/cec/cec-pin-error-inj.rst delete mode 100644 Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst delete mode 100644 Documentation/media/uapi/dvb/audio-channel-select.rst delete mode 100644 Documentation/media/uapi/dvb/audio-clear-buffer.rst delete mode 100644 Documentation/media/uapi/dvb/audio-continue.rst delete mode 100644 Documentation/media/uapi/dvb/audio-fclose.rst delete mode 100644 Documentation/media/uapi/dvb/audio-fopen.rst delete mode 100644 Documentation/media/uapi/dvb/audio-fwrite.rst delete mode 100644 Documentation/media/uapi/dvb/audio-get-capabilities.rst delete mode 100644 Documentation/media/uapi/dvb/audio-get-status.rst delete mode 100644 Documentation/media/uapi/dvb/audio-pause.rst delete mode 100644 Documentation/media/uapi/dvb/audio-play.rst delete mode 100644 Documentation/media/uapi/dvb/audio-select-source.rst delete mode 100644 Documentation/media/uapi/dvb/audio-set-av-sync.rst delete mode 100644 Documentation/media/uapi/dvb/audio-set-bypass-mode.rst delete mode 100644 Documentation/media/uapi/dvb/audio-set-id.rst delete mode 100644 Documentation/media/uapi/dvb/audio-set-mixer.rst delete mode 100644 Documentation/media/uapi/dvb/audio-set-mute.rst delete mode 100644 Documentation/media/uapi/dvb/audio-set-streamtype.rst delete mode 100644 Documentation/media/uapi/dvb/audio-stop.rst delete mode 100644 Documentation/media/uapi/dvb/audio.rst delete mode 100644 Documentation/media/uapi/dvb/audio_data_types.rst delete mode 100644 Documentation/media/uapi/dvb/audio_function_calls.rst delete mode 100644 Documentation/media/uapi/dvb/ca-fclose.rst delete mode 100644 Documentation/media/uapi/dvb/ca-fopen.rst delete mode 100644 Documentation/media/uapi/dvb/ca-get-cap.rst delete mode 100644 Documentation/media/uapi/dvb/ca-get-descr-info.rst delete mode 100644 Documentation/media/uapi/dvb/ca-get-msg.rst delete mode 100644 Documentation/media/uapi/dvb/ca-get-slot-info.rst delete mode 100644 Documentation/media/uapi/dvb/ca-reset.rst delete mode 100644 Documentation/media/uapi/dvb/ca-send-msg.rst delete mode 100644 Documentation/media/uapi/dvb/ca-set-descr.rst delete mode 100644 Documentation/media/uapi/dvb/ca.rst delete mode 100644 Documentation/media/uapi/dvb/ca_data_types.rst delete mode 100644 Documentation/media/uapi/dvb/ca_function_calls.rst delete mode 100644 Documentation/media/uapi/dvb/ca_high_level.rst delete mode 100644 Documentation/media/uapi/dvb/demux.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-add-pid.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-expbuf.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-fclose.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-fopen.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-fread.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-fwrite.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-get-pes-pids.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-get-stc.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-mmap.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-munmap.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-qbuf.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-querybuf.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-remove-pid.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-reqbufs.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-set-buffer-size.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-set-filter.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-set-pes-filter.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-start.rst delete mode 100644 Documentation/media/uapi/dvb/dmx-stop.rst delete mode 100644 Documentation/media/uapi/dvb/dmx_fcalls.rst delete mode 100644 Documentation/media/uapi/dvb/dmx_types.rst delete mode 100644 Documentation/media/uapi/dvb/dvb-fe-read-status.rst delete mode 100644 Documentation/media/uapi/dvb/dvb-frontend-event.rst delete mode 100644 Documentation/media/uapi/dvb/dvb-frontend-parameters.rst delete mode 100644 Documentation/media/uapi/dvb/dvbapi.rst delete mode 100644 Documentation/media/uapi/dvb/dvbproperty.rst delete mode 100644 Documentation/media/uapi/dvb/dvbstb.svg delete mode 100644 Documentation/media/uapi/dvb/examples.rst delete mode 100644 Documentation/media/uapi/dvb/fe-bandwidth-t.rst delete mode 100644 Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst delete mode 100644 Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst delete mode 100644 Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst delete mode 100644 Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst delete mode 100644 Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst delete mode 100644 Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst delete mode 100644 Documentation/media/uapi/dvb/fe-get-event.rst delete mode 100644 Documentation/media/uapi/dvb/fe-get-frontend.rst delete mode 100644 Documentation/media/uapi/dvb/fe-get-info.rst delete mode 100644 Documentation/media/uapi/dvb/fe-get-property.rst delete mode 100644 Documentation/media/uapi/dvb/fe-read-ber.rst delete mode 100644 Documentation/media/uapi/dvb/fe-read-signal-strength.rst delete mode 100644 Documentation/media/uapi/dvb/fe-read-snr.rst delete mode 100644 Documentation/media/uapi/dvb/fe-read-status.rst delete mode 100644 Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst delete mode 100644 Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst delete mode 100644 Documentation/media/uapi/dvb/fe-set-frontend.rst delete mode 100644 Documentation/media/uapi/dvb/fe-set-tone.rst delete mode 100644 Documentation/media/uapi/dvb/fe-set-voltage.rst delete mode 100644 Documentation/media/uapi/dvb/fe-type-t.rst delete mode 100644 Documentation/media/uapi/dvb/fe_property_parameters.rst delete mode 100644 Documentation/media/uapi/dvb/frontend-header.rst delete mode 100644 Documentation/media/uapi/dvb/frontend-property-cable-systems.rst delete mode 100644 Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst delete mode 100644 Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst delete mode 100644 Documentation/media/uapi/dvb/frontend-stat-properties.rst delete mode 100644 Documentation/media/uapi/dvb/frontend.rst delete mode 100644 Documentation/media/uapi/dvb/frontend_f_close.rst delete mode 100644 Documentation/media/uapi/dvb/frontend_f_open.rst delete mode 100644 Documentation/media/uapi/dvb/frontend_fcalls.rst delete mode 100644 Documentation/media/uapi/dvb/frontend_legacy_api.rst delete mode 100644 Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst delete mode 100644 Documentation/media/uapi/dvb/headers.rst delete mode 100644 Documentation/media/uapi/dvb/intro.rst delete mode 100644 Documentation/media/uapi/dvb/legacy_dvb_apis.rst delete mode 100644 Documentation/media/uapi/dvb/net-add-if.rst delete mode 100644 Documentation/media/uapi/dvb/net-get-if.rst delete mode 100644 Documentation/media/uapi/dvb/net-remove-if.rst delete mode 100644 Documentation/media/uapi/dvb/net-types.rst delete mode 100644 Documentation/media/uapi/dvb/net.rst delete mode 100644 Documentation/media/uapi/dvb/query-dvb-frontend-info.rst delete mode 100644 Documentation/media/uapi/dvb/video-clear-buffer.rst delete mode 100644 Documentation/media/uapi/dvb/video-command.rst delete mode 100644 Documentation/media/uapi/dvb/video-continue.rst delete mode 100644 Documentation/media/uapi/dvb/video-fast-forward.rst delete mode 100644 Documentation/media/uapi/dvb/video-fclose.rst delete mode 100644 Documentation/media/uapi/dvb/video-fopen.rst delete mode 100644 Documentation/media/uapi/dvb/video-freeze.rst delete mode 100644 Documentation/media/uapi/dvb/video-fwrite.rst delete mode 100644 Documentation/media/uapi/dvb/video-get-capabilities.rst delete mode 100644 Documentation/media/uapi/dvb/video-get-event.rst delete mode 100644 Documentation/media/uapi/dvb/video-get-frame-count.rst delete mode 100644 Documentation/media/uapi/dvb/video-get-pts.rst delete mode 100644 Documentation/media/uapi/dvb/video-get-size.rst delete mode 100644 Documentation/media/uapi/dvb/video-get-status.rst delete mode 100644 Documentation/media/uapi/dvb/video-play.rst delete mode 100644 Documentation/media/uapi/dvb/video-select-source.rst delete mode 100644 Documentation/media/uapi/dvb/video-set-blank.rst delete mode 100644 Documentation/media/uapi/dvb/video-set-display-format.rst delete mode 100644 Documentation/media/uapi/dvb/video-set-format.rst delete mode 100644 Documentation/media/uapi/dvb/video-set-streamtype.rst delete mode 100644 Documentation/media/uapi/dvb/video-slowmotion.rst delete mode 100644 Documentation/media/uapi/dvb/video-stillpicture.rst delete mode 100644 Documentation/media/uapi/dvb/video-stop.rst delete mode 100644 Documentation/media/uapi/dvb/video-try-command.rst delete mode 100644 Documentation/media/uapi/dvb/video.rst delete mode 100644 Documentation/media/uapi/dvb/video_function_calls.rst delete mode 100644 Documentation/media/uapi/dvb/video_types.rst delete mode 100644 Documentation/media/uapi/fdl-appendix.rst delete mode 100644 Documentation/media/uapi/gen-errors.rst delete mode 100644 Documentation/media/uapi/mediactl/media-controller-intro.rst delete mode 100644 Documentation/media/uapi/mediactl/media-controller-model.rst delete mode 100644 Documentation/media/uapi/mediactl/media-controller.rst delete mode 100644 Documentation/media/uapi/mediactl/media-func-close.rst delete mode 100644 Documentation/media/uapi/mediactl/media-func-ioctl.rst delete mode 100644 Documentation/media/uapi/mediactl/media-func-open.rst delete mode 100644 Documentation/media/uapi/mediactl/media-funcs.rst delete mode 100644 Documentation/media/uapi/mediactl/media-header.rst delete mode 100644 Documentation/media/uapi/mediactl/media-ioc-device-info.rst delete mode 100644 Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst delete mode 100644 Documentation/media/uapi/mediactl/media-ioc-enum-links.rst delete mode 100644 Documentation/media/uapi/mediactl/media-ioc-g-topology.rst delete mode 100644 Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst delete mode 100644 Documentation/media/uapi/mediactl/media-ioc-setup-link.rst delete mode 100644 Documentation/media/uapi/mediactl/media-request-ioc-queue.rst delete mode 100644 Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst delete mode 100644 Documentation/media/uapi/mediactl/media-types.rst delete mode 100644 Documentation/media/uapi/mediactl/request-api.rst delete mode 100644 Documentation/media/uapi/mediactl/request-func-close.rst delete mode 100644 Documentation/media/uapi/mediactl/request-func-ioctl.rst delete mode 100644 Documentation/media/uapi/mediactl/request-func-poll.rst delete mode 100644 Documentation/media/uapi/rc/keytable.c.rst delete mode 100644 Documentation/media/uapi/rc/lirc-dev-intro.rst delete mode 100644 Documentation/media/uapi/rc/lirc-dev.rst delete mode 100644 Documentation/media/uapi/rc/lirc-func.rst delete mode 100644 Documentation/media/uapi/rc/lirc-get-features.rst delete mode 100644 Documentation/media/uapi/rc/lirc-get-rec-mode.rst delete mode 100644 Documentation/media/uapi/rc/lirc-get-rec-resolution.rst delete mode 100644 Documentation/media/uapi/rc/lirc-get-send-mode.rst delete mode 100644 Documentation/media/uapi/rc/lirc-get-timeout.rst delete mode 100644 Documentation/media/uapi/rc/lirc-header.rst delete mode 100644 Documentation/media/uapi/rc/lirc-read.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-measure-carrier-mode.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-rec-carrier.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-rec-timeout.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-send-carrier.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-send-duty-cycle.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-transmitter-mask.rst delete mode 100644 Documentation/media/uapi/rc/lirc-set-wideband-receiver.rst delete mode 100644 Documentation/media/uapi/rc/lirc-write.rst delete mode 100644 Documentation/media/uapi/rc/rc-intro.rst delete mode 100644 Documentation/media/uapi/rc/rc-protos.rst delete mode 100644 Documentation/media/uapi/rc/rc-sysfs-nodes.rst delete mode 100644 Documentation/media/uapi/rc/rc-table-change.rst delete mode 100644 Documentation/media/uapi/rc/rc-tables.rst delete mode 100644 Documentation/media/uapi/rc/remote_controllers.rst delete mode 100644 Documentation/media/uapi/v4l/app-pri.rst delete mode 100644 Documentation/media/uapi/v4l/async.rst delete mode 100644 Documentation/media/uapi/v4l/audio.rst delete mode 100644 Documentation/media/uapi/v4l/bayer.svg delete mode 100644 Documentation/media/uapi/v4l/biblio.rst delete mode 100644 Documentation/media/uapi/v4l/buffer.rst delete mode 100644 Documentation/media/uapi/v4l/capture-example.rst delete mode 100644 Documentation/media/uapi/v4l/capture.c.rst delete mode 100644 Documentation/media/uapi/v4l/colorspaces-defs.rst delete mode 100644 Documentation/media/uapi/v4l/colorspaces-details.rst delete mode 100644 Documentation/media/uapi/v4l/colorspaces.rst delete mode 100644 Documentation/media/uapi/v4l/common-defs.rst delete mode 100644 Documentation/media/uapi/v4l/common.rst delete mode 100644 Documentation/media/uapi/v4l/compat.rst delete mode 100644 Documentation/media/uapi/v4l/constraints.svg delete mode 100644 Documentation/media/uapi/v4l/control.rst delete mode 100644 Documentation/media/uapi/v4l/crop.rst delete mode 100644 Documentation/media/uapi/v4l/crop.svg delete mode 100644 Documentation/media/uapi/v4l/depth-formats.rst delete mode 100644 Documentation/media/uapi/v4l/dev-capture.rst delete mode 100644 Documentation/media/uapi/v4l/dev-decoder.rst delete mode 100644 Documentation/media/uapi/v4l/dev-event.rst delete mode 100644 Documentation/media/uapi/v4l/dev-mem2mem.rst delete mode 100644 Documentation/media/uapi/v4l/dev-meta.rst delete mode 100644 Documentation/media/uapi/v4l/dev-osd.rst delete mode 100644 Documentation/media/uapi/v4l/dev-output.rst delete mode 100644 Documentation/media/uapi/v4l/dev-overlay.rst delete mode 100644 Documentation/media/uapi/v4l/dev-radio.rst delete mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi.rst delete mode 100644 Documentation/media/uapi/v4l/dev-rds.rst delete mode 100644 Documentation/media/uapi/v4l/dev-sdr.rst delete mode 100644 Documentation/media/uapi/v4l/dev-sliced-vbi.rst delete mode 100644 Documentation/media/uapi/v4l/dev-stateless-decoder.rst delete mode 100644 Documentation/media/uapi/v4l/dev-subdev.rst delete mode 100644 Documentation/media/uapi/v4l/dev-touch.rst delete mode 100644 Documentation/media/uapi/v4l/devices.rst delete mode 100644 Documentation/media/uapi/v4l/diff-v4l.rst delete mode 100644 Documentation/media/uapi/v4l/dmabuf.rst delete mode 100644 Documentation/media/uapi/v4l/dv-timings.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-camera.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-codec.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-detect.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-dv.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-flash.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-fm-rx.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-fm-tx.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-image-process.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-image-source.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-jpeg.rst delete mode 100644 Documentation/media/uapi/v4l/ext-ctrls-rf-tuner.rst delete mode 100644 Documentation/media/uapi/v4l/extended-controls.rst delete mode 100644 Documentation/media/uapi/v4l/field-order.rst delete mode 100644 Documentation/media/uapi/v4l/fieldseq_bt.svg delete mode 100644 Documentation/media/uapi/v4l/fieldseq_tb.svg delete mode 100644 Documentation/media/uapi/v4l/format.rst delete mode 100644 Documentation/media/uapi/v4l/func-close.rst delete mode 100644 Documentation/media/uapi/v4l/func-ioctl.rst delete mode 100644 Documentation/media/uapi/v4l/func-mmap.rst delete mode 100644 Documentation/media/uapi/v4l/func-munmap.rst delete mode 100644 Documentation/media/uapi/v4l/func-open.rst delete mode 100644 Documentation/media/uapi/v4l/func-poll.rst delete mode 100644 Documentation/media/uapi/v4l/func-read.rst delete mode 100644 Documentation/media/uapi/v4l/func-select.rst delete mode 100644 Documentation/media/uapi/v4l/func-write.rst delete mode 100644 Documentation/media/uapi/v4l/hist-v4l2.rst delete mode 100644 Documentation/media/uapi/v4l/hsv-formats.rst delete mode 100644 Documentation/media/uapi/v4l/io.rst delete mode 100644 Documentation/media/uapi/v4l/libv4l-introduction.rst delete mode 100644 Documentation/media/uapi/v4l/libv4l.rst delete mode 100644 Documentation/media/uapi/v4l/meta-formats.rst delete mode 100644 Documentation/media/uapi/v4l/mmap.rst delete mode 100644 Documentation/media/uapi/v4l/nv12mt.svg delete mode 100644 Documentation/media/uapi/v4l/nv12mt_example.svg delete mode 100644 Documentation/media/uapi/v4l/open.rst delete mode 100644 Documentation/media/uapi/v4l/pipeline.dot delete mode 100644 Documentation/media/uapi/v4l/pixfmt-bayer.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-cnf4.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-compressed.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-grey.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-indexed.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-intro.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-inzi.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-m420.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-meta-d4xx.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-meta-intel-ipu3.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-meta-uvc.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-meta-vivid.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgo.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-meta-vsp1-hgt.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12m.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv16.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv16m.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv24.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-packed-hsv.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-reserved.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-rgb.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-pcu16be.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-pcu18be.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-pcu20be.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10-ipu3.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb12.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb12p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb14.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb14p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb16.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb8.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-tch-td08.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-tch-td16.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-tch-tu08.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-tch-tu16.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-uv8.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-uyvy.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-v4l2-mplane.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-v4l2.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-vyuy.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y10.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y10b.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y10p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y12.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y12i.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y14.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y16-be.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y16.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y41p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-y8i.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv410.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv411p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv420.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv420m.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv422m.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv422p.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv444m.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yuyv.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-yvyu.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt-z16.rst delete mode 100644 Documentation/media/uapi/v4l/pixfmt.rst delete mode 100644 Documentation/media/uapi/v4l/planar-apis.rst delete mode 100644 Documentation/media/uapi/v4l/querycap.rst delete mode 100644 Documentation/media/uapi/v4l/rw.rst delete mode 100644 Documentation/media/uapi/v4l/sdr-formats.rst delete mode 100644 Documentation/media/uapi/v4l/selection-api-configuration.rst delete mode 100644 Documentation/media/uapi/v4l/selection-api-examples.rst delete mode 100644 Documentation/media/uapi/v4l/selection-api-intro.rst delete mode 100644 Documentation/media/uapi/v4l/selection-api-targets.rst delete mode 100644 Documentation/media/uapi/v4l/selection-api-vs-crop-api.rst delete mode 100644 Documentation/media/uapi/v4l/selection-api.rst delete mode 100644 Documentation/media/uapi/v4l/selection.svg delete mode 100644 Documentation/media/uapi/v4l/selections-common.rst delete mode 100644 Documentation/media/uapi/v4l/standard.rst delete mode 100644 Documentation/media/uapi/v4l/streaming-par.rst delete mode 100644 Documentation/media/uapi/v4l/subdev-formats.rst delete mode 100644 Documentation/media/uapi/v4l/subdev-image-processing-crop.svg delete mode 100644 Documentation/media/uapi/v4l/subdev-image-processing-full.svg delete mode 100644 Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg delete mode 100644 Documentation/media/uapi/v4l/tch-formats.rst delete mode 100644 Documentation/media/uapi/v4l/tuner.rst delete mode 100644 Documentation/media/uapi/v4l/user-func.rst delete mode 100644 Documentation/media/uapi/v4l/userp.rst delete mode 100644 Documentation/media/uapi/v4l/v4l2-selection-flags.rst delete mode 100644 Documentation/media/uapi/v4l/v4l2-selection-targets.rst delete mode 100644 Documentation/media/uapi/v4l/v4l2.rst delete mode 100644 Documentation/media/uapi/v4l/v4l2grab-example.rst delete mode 100644 Documentation/media/uapi/v4l/v4l2grab.c.rst delete mode 100644 Documentation/media/uapi/v4l/vbi_525.svg delete mode 100644 Documentation/media/uapi/v4l/vbi_625.svg delete mode 100644 Documentation/media/uapi/v4l/vbi_hsync.svg delete mode 100644 Documentation/media/uapi/v4l/video.rst delete mode 100644 Documentation/media/uapi/v4l/videodev.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-create-bufs.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-cropcap.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-dqevent.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enum-fmt.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enumaudio.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enumaudioout.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enuminput.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enumoutput.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-enumstd.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-expbuf.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-audio.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-audioout.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-crop.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-ctrl.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-edid.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-enc-index.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-fbuf.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-fmt.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-frequency.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-input.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-modulator.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-output.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-parm.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-priority.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-selection.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-std.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-tuner.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-log-status.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-overlay.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-prepare-buf.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-qbuf.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-querybuf.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-querycap.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-queryctrl.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-querystd.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-reqbufs.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-streamon.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst delete mode 100644 Documentation/media/uapi/v4l/vidioc-subscribe-event.rst delete mode 100644 Documentation/media/uapi/v4l/yuv-formats.rst delete mode 100644 Documentation/media/video.h.rst.exceptions delete mode 100644 Documentation/media/videodev2.h.rst.exceptions (limited to 'Documentation/media') diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile deleted file mode 100644 index d75d70f191bc..000000000000 --- a/Documentation/media/Makefile +++ /dev/null @@ -1,69 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Rules to convert a .h file to inline RST documentation - -SRC_DIR=$(srctree)/Documentation/media -PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl -UAPI = $(srctree)/include/uapi/linux -KAPI = $(srctree)/include/linux - -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)) - -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: ${UAPI}/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) - -# Media build rules - -.PHONY: all html epub xml latex - -all: $(IMGDOT) $(BUILDDIR) ${TARGETS} -html: all -epub: all -xml: all -latex: $(IMGPDF) all -linkcheck: - -clean: - -rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null - -$(BUILDDIR): - $(Q)mkdir -p $@ diff --git a/Documentation/media/audio.h.rst.exceptions b/Documentation/media/audio.h.rst.exceptions deleted file mode 100644 index cf6620477f73..000000000000 --- a/Documentation/media/audio.h.rst.exceptions +++ /dev/null @@ -1,19 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Ignore header name -ignore define _DVBAUDIO_H_ - -# 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 :c:type:`audio_mixer` -replace typedef audio_status_t :c:type:`audio_status` diff --git a/Documentation/media/ca.h.rst.exceptions b/Documentation/media/ca.h.rst.exceptions deleted file mode 100644 index f6828238eb48..000000000000 --- a/Documentation/media/ca.h.rst.exceptions +++ /dev/null @@ -1,25 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Ignore header name -ignore define _DVBCA_H_ - -# struct ca_slot_info defines -replace define CA_CI :c:type:`ca_slot_info` -replace define CA_CI_LINK :c:type:`ca_slot_info` -replace define CA_CI_PHYS :c:type:`ca_slot_info` -replace define CA_DESCR :c:type:`ca_slot_info` -replace define CA_SC :c:type:`ca_slot_info` -replace define CA_CI_MODULE_PRESENT :c:type:`ca_slot_info` -replace define CA_CI_MODULE_READY :c:type:`ca_slot_info` - -# struct ca_descr_info defines -replace define CA_ECD :c:type:`ca_descr_info` -replace define CA_NDS :c:type:`ca_descr_info` -replace define CA_DSS :c:type:`ca_descr_info` - -# some typedefs should point to struct/enums -replace typedef ca_slot_info_t :c:type:`ca_slot_info` -replace typedef ca_descr_info_t :c:type:`ca_descr_info` -replace typedef ca_caps_t :c:type:`ca_caps` -replace typedef ca_msg_t :c:type:`ca_msg` -replace typedef ca_descr_t :c:type:`ca_descr` diff --git a/Documentation/media/cec.h.rst.exceptions b/Documentation/media/cec.h.rst.exceptions deleted file mode 100644 index d83790ccac8e..000000000000 --- a/Documentation/media/cec.h.rst.exceptions +++ /dev/null @@ -1,575 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# Ignore header name -ignore define _CEC_UAPI_H - -# 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 - -# 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_CMD_SELECT -ignore define CEC_OP_UI_CMD_UP -ignore define CEC_OP_UI_CMD_DOWN -ignore define CEC_OP_UI_CMD_LEFT -ignore define CEC_OP_UI_CMD_RIGHT -ignore define CEC_OP_UI_CMD_RIGHT_UP -ignore define CEC_OP_UI_CMD_RIGHT_DOWN -ignore define CEC_OP_UI_CMD_LEFT_UP -ignore define CEC_OP_UI_CMD_LEFT_DOWN -ignore define CEC_OP_UI_CMD_DEVICE_ROOT_MENU -ignore define CEC_OP_UI_CMD_DEVICE_SETUP_MENU -ignore define CEC_OP_UI_CMD_CONTENTS_MENU -ignore define CEC_OP_UI_CMD_FAVORITE_MENU -ignore define CEC_OP_UI_CMD_BACK -ignore define CEC_OP_UI_CMD_MEDIA_TOP_MENU -ignore define CEC_OP_UI_CMD_MEDIA_CONTEXT_SENSITIVE_MENU -ignore define CEC_OP_UI_CMD_NUMBER_ENTRY_MODE -ignore define CEC_OP_UI_CMD_NUMBER_11 -ignore define CEC_OP_UI_CMD_NUMBER_12 -ignore define CEC_OP_UI_CMD_NUMBER_0_OR_NUMBER_10 -ignore define CEC_OP_UI_CMD_NUMBER_1 -ignore define CEC_OP_UI_CMD_NUMBER_2 -ignore define CEC_OP_UI_CMD_NUMBER_3 -ignore define CEC_OP_UI_CMD_NUMBER_4 -ignore define CEC_OP_UI_CMD_NUMBER_5 -ignore define CEC_OP_UI_CMD_NUMBER_6 -ignore define CEC_OP_UI_CMD_NUMBER_7 -ignore define CEC_OP_UI_CMD_NUMBER_8 -ignore define CEC_OP_UI_CMD_NUMBER_9 -ignore define CEC_OP_UI_CMD_DOT -ignore define CEC_OP_UI_CMD_ENTER -ignore define CEC_OP_UI_CMD_CLEAR -ignore define CEC_OP_UI_CMD_NEXT_FAVORITE -ignore define CEC_OP_UI_CMD_CHANNEL_UP -ignore define CEC_OP_UI_CMD_CHANNEL_DOWN -ignore define CEC_OP_UI_CMD_PREVIOUS_CHANNEL -ignore define CEC_OP_UI_CMD_SOUND_SELECT -ignore define CEC_OP_UI_CMD_INPUT_SELECT -ignore define CEC_OP_UI_CMD_DISPLAY_INFORMATION -ignore define CEC_OP_UI_CMD_HELP -ignore define CEC_OP_UI_CMD_PAGE_UP -ignore define CEC_OP_UI_CMD_PAGE_DOWN -ignore define CEC_OP_UI_CMD_POWER -ignore define CEC_OP_UI_CMD_VOLUME_UP -ignore define CEC_OP_UI_CMD_VOLUME_DOWN -ignore define CEC_OP_UI_CMD_MUTE -ignore define CEC_OP_UI_CMD_PLAY -ignore define CEC_OP_UI_CMD_STOP -ignore define CEC_OP_UI_CMD_PAUSE -ignore define CEC_OP_UI_CMD_RECORD -ignore define CEC_OP_UI_CMD_REWIND -ignore define CEC_OP_UI_CMD_FAST_FORWARD -ignore define CEC_OP_UI_CMD_EJECT -ignore define CEC_OP_UI_CMD_SKIP_FORWARD -ignore define CEC_OP_UI_CMD_SKIP_BACKWARD -ignore define CEC_OP_UI_CMD_STOP_RECORD -ignore define CEC_OP_UI_CMD_PAUSE_RECORD -ignore define CEC_OP_UI_CMD_ANGLE -ignore define CEC_OP_UI_CMD_SUB_PICTURE -ignore define CEC_OP_UI_CMD_VIDEO_ON_DEMAND -ignore define CEC_OP_UI_CMD_ELECTRONIC_PROGRAM_GUIDE -ignore define CEC_OP_UI_CMD_TIMER_PROGRAMMING -ignore define CEC_OP_UI_CMD_INITIAL_CONFIGURATION -ignore define CEC_OP_UI_CMD_SELECT_BROADCAST_TYPE -ignore define CEC_OP_UI_CMD_SELECT_SOUND_PRESENTATION -ignore define CEC_OP_UI_CMD_AUDIO_DESCRIPTION -ignore define CEC_OP_UI_CMD_INTERNET -ignore define CEC_OP_UI_CMD_3D_MODE -ignore define CEC_OP_UI_CMD_PLAY_FUNCTION -ignore define CEC_OP_UI_CMD_PAUSE_PLAY_FUNCTION -ignore define CEC_OP_UI_CMD_RECORD_FUNCTION -ignore define CEC_OP_UI_CMD_PAUSE_RECORD_FUNCTION -ignore define CEC_OP_UI_CMD_STOP_FUNCTION -ignore define CEC_OP_UI_CMD_MUTE_FUNCTION -ignore define CEC_OP_UI_CMD_RESTORE_VOLUME_FUNCTION -ignore define CEC_OP_UI_CMD_TUNE_FUNCTION -ignore define CEC_OP_UI_CMD_SELECT_MEDIA_FUNCTION -ignore define CEC_OP_UI_CMD_SELECT_AV_INPUT_FUNCTION -ignore define CEC_OP_UI_CMD_SELECT_AUDIO_INPUT_FUNCTION -ignore define CEC_OP_UI_CMD_POWER_TOGGLE_FUNCTION -ignore define CEC_OP_UI_CMD_POWER_OFF_FUNCTION -ignore define CEC_OP_UI_CMD_POWER_ON_FUNCTION -ignore define CEC_OP_UI_CMD_F1_BLUE -ignore define CEC_OP_UI_CMD_F2_RED -ignore define CEC_OP_UI_CMD_F3_GREEN -ignore define CEC_OP_UI_CMD_F4_YELLOW -ignore define CEC_OP_UI_CMD_F5 -ignore define CEC_OP_UI_CMD_DATA - -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 diff --git a/Documentation/media/conf_nitpick.py b/Documentation/media/conf_nitpick.py deleted file mode 100644 index d0c50d75f518..000000000000 --- a/Documentation/media/conf_nitpick.py +++ /dev/null @@ -1,111 +0,0 @@ -# -*- coding: utf-8; mode: python -*- - -# SPDX-License-Identifier: GPL-2.0 - -project = 'Linux Media Subsystem Documentation' - -# It is possible to run Sphinx in nickpick mode with: -nitpicky = True - -# within nit-picking build, do not refer to any intersphinx object -intersphinx_mapping = {} - -# In nickpick mode, it will complain about lots of missing references that -# -# 1) are just typedefs like: bool, __u32, etc; -# 2) It will complain for things like: enum, NULL; -# 3) It will complain for symbols that should be on different -# books (but currently aren't ported to ReST) -# -# The list below has a list of such symbols to be ignored in nitpick mode -# -nitpick_ignore = [ - ("c:func", "clock_gettime"), - ("c:func", "close"), - ("c:func", "container_of"), - ("c:func", "copy_from_user"), - ("c:func", "copy_to_user"), - ("c:func", "determine_valid_ioctls"), - ("c:func", "ERR_PTR"), - ("c:func", "i2c_new_device"), - ("c:func", "ioctl"), - ("c:func", "IS_ERR"), - ("c:func", "KERNEL_VERSION"), - ("c:func", "mmap"), - ("c:func", "open"), - ("c:func", "pci_name"), - ("c:func", "poll"), - ("c:func", "PTR_ERR"), - ("c:func", "read"), - ("c:func", "release"), - ("c:func", "set"), - ("c:func", "struct fd_set"), - ("c:func", "struct pollfd"), - ("c:func", "usb_make_path"), - ("c:func", "wait_finish"), - ("c:func", "wait_prepare"), - ("c:func", "write"), - - ("c:type", "atomic_t"), - ("c:type", "bool"), - ("c:type", "boolean"), - ("c:type", "buf_queue"), - ("c:type", "device"), - ("c:type", "device_driver"), - ("c:type", "device_node"), - ("c:type", "enum"), - ("c:type", "fd"), - ("c:type", "fd_set"), - ("c:type", "file"), - ("c:type", "i2c_adapter"), - ("c:type", "i2c_board_info"), - ("c:type", "i2c_client"), - ("c:type", "int16_t"), - ("c:type", "ktime_t"), - ("c:type", "led_classdev_flash"), - ("c:type", "list_head"), - ("c:type", "lock_class_key"), - ("c:type", "module"), - ("c:type", "mutex"), - ("c:type", "NULL"), - ("c:type", "off_t"), - ("c:type", "pci_dev"), - ("c:type", "pdvbdev"), - ("c:type", "poll_table"), - ("c:type", "platform_device"), - ("c:type", "pollfd"), - ("c:type", "poll_table_struct"), - ("c:type", "s32"), - ("c:type", "s64"), - ("c:type", "sd"), - ("c:type", "size_t"), - ("c:type", "spi_board_info"), - ("c:type", "spi_device"), - ("c:type", "spi_master"), - ("c:type", "ssize_t"), - ("c:type", "fb_fix_screeninfo"), - ("c:type", "pollfd"), - ("c:type", "timeval"), - ("c:type", "video_capability"), - ("c:type", "timeval"), - ("c:type", "__u16"), - ("c:type", "u16"), - ("c:type", "__u32"), - ("c:type", "u32"), - ("c:type", "__u64"), - ("c:type", "u64"), - ("c:type", "u8"), - ("c:type", "uint16_t"), - ("c:type", "uint32_t"), - ("c:type", "union"), - ("c:type", "__user"), - ("c:type", "usb_device"), - ("c:type", "usb_interface"), - ("c:type", "v4l2_std_id"), - ("c:type", "video_system_t"), - ("c:type", "vm_area_struct"), - - # Opaque structures - - ("c:type", "v4l2_m2m_dev"), -] diff --git a/Documentation/media/dmx.h.rst.exceptions b/Documentation/media/dmx.h.rst.exceptions deleted file mode 100644 index afc14d384b83..000000000000 --- a/Documentation/media/dmx.h.rst.exceptions +++ /dev/null @@ -1,66 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# 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 :c:type:`dmx_pes_type` -replace symbol DMX_PES_AUDIO0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_VIDEO0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_TELETEXT0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_SUBTITLE0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_PCR0 :c:type:`dmx_pes_type` -replace symbol DMX_PES_AUDIO1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_VIDEO1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_TELETEXT1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_SUBTITLE1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_PCR1 :c:type:`dmx_pes_type` -replace symbol DMX_PES_AUDIO2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_VIDEO2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_TELETEXT2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_SUBTITLE2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_PCR2 :c:type:`dmx_pes_type` -replace symbol DMX_PES_AUDIO3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_VIDEO3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_TELETEXT3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_SUBTITLE3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_PCR3 :c:type:`dmx_pes_type` -replace symbol DMX_PES_OTHER :c:type:`dmx_pes_type` - -# 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 :c:type:`dmx_input` -replace symbol DMX_IN_FRONTEND :c:type:`dmx_input` -replace symbol DMX_IN_DVR :c:type:`dmx_input` - -# Flags for struct dmx_sct_filter_params -replace define DMX_CHECK_CRC :c:type:`dmx_sct_filter_params` -replace define DMX_ONESHOT :c:type:`dmx_sct_filter_params` -replace define DMX_IMMEDIATE_START :c:type:`dmx_sct_filter_params` - -# some typedefs should point to struct/enums -replace typedef dmx_filter_t :c:type:`dmx_filter` -replace typedef dmx_pes_type_t :c:type:`dmx_pes_type` -replace typedef dmx_input_t :c:type:`dmx_input` - -replace symbol DMX_BUFFER_FLAG_HAD_CRC32_DISCARD :c:type:`dmx_buffer_flags` -replace symbol DMX_BUFFER_FLAG_TEI :c:type:`dmx_buffer_flags` -replace symbol DMX_BUFFER_PKT_COUNTER_MISMATCH :c:type:`dmx_buffer_flags` -replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_DETECTED :c:type:`dmx_buffer_flags` -replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_INDICATOR :c:type:`dmx_buffer_flags` - -replace symbol DMX_OUT_DECODER :c:type:`dmx_output` -replace symbol DMX_OUT_TAP :c:type:`dmx_output` -replace symbol DMX_OUT_TS_TAP :c:type:`dmx_output` -replace symbol DMX_OUT_TSDEMUX_TAP :c:type:`dmx_output` - -replace ioctl DMX_DQBUF dmx_qbuf diff --git a/Documentation/media/frontend.h.rst.exceptions b/Documentation/media/frontend.h.rst.exceptions deleted file mode 100644 index 6283702c08c8..000000000000 --- a/Documentation/media/frontend.h.rst.exceptions +++ /dev/null @@ -1,214 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# 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 - -# the same reference is used for both get and set ioctls -replace ioctl FE_SET_PROPERTY :c:type:`FE_GET_PROPERTY` - -# Typedefs that use the enum reference -replace typedef fe_sec_voltage_t :c:type:`fe_sec_voltage` - -# Replaces for flag constants -replace define FE_TUNE_MODE_ONESHOT :c:func:`FE_SET_FRONTEND_TUNE_MODE` -replace define LNA_AUTO dtv-lna -replace define NO_STREAM_ID_FILTER dtv-stream-id - -# Those enums are defined at the frontend.h header, and not externally - -ignore symbol FE_IS_STUPID -ignore symbol FE_CAN_INVERSION_AUTO -ignore symbol FE_CAN_FEC_1_2 -ignore symbol FE_CAN_FEC_2_3 -ignore symbol FE_CAN_FEC_3_4 -ignore symbol FE_CAN_FEC_4_5 -ignore symbol FE_CAN_FEC_5_6 -ignore symbol FE_CAN_FEC_6_7 -ignore symbol FE_CAN_FEC_7_8 -ignore symbol FE_CAN_FEC_8_9 -ignore symbol FE_CAN_FEC_AUTO -ignore symbol FE_CAN_QPSK -ignore symbol FE_CAN_QAM_16 -ignore symbol FE_CAN_QAM_32 -ignore symbol FE_CAN_QAM_64 -ignore symbol FE_CAN_QAM_128 -ignore symbol FE_CAN_QAM_256 -ignore symbol FE_CAN_QAM_AUTO -ignore symbol FE_CAN_TRANSMISSION_MODE_AUTO -ignore symbol FE_CAN_BANDWIDTH_AUTO -ignore symbol FE_CAN_GUARD_INTERVAL_AUTO -ignore symbol FE_CAN_HIERARCHY_AUTO -ignore symbol FE_CAN_8VSB -ignore symbol FE_CAN_16VSB -ignore symbol FE_HAS_EXTENDED_CAPS -ignore symbol FE_CAN_MULTISTREAM -ignore symbol FE_CAN_TURBO_FEC -ignore symbol FE_CAN_2G_MODULATION -ignore symbol FE_NEEDS_BENDING -ignore symbol FE_CAN_RECOVER -ignore symbol FE_CAN_MUTE_TS - -ignore symbol QPSK -ignore symbol QAM_16 -ignore symbol QAM_32 -ignore symbol QAM_64 -ignore symbol QAM_128 -ignore symbol QAM_256 -ignore symbol QAM_AUTO -ignore symbol VSB_8 -ignore symbol VSB_16 -ignore symbol PSK_8 -ignore symbol APSK_16 -ignore symbol APSK_32 -ignore symbol DQPSK -ignore symbol QAM_4_NR - -ignore symbol SEC_VOLTAGE_13 -ignore symbol SEC_VOLTAGE_18 -ignore symbol SEC_VOLTAGE_OFF - -ignore symbol SEC_TONE_ON -ignore symbol SEC_TONE_OFF - -ignore symbol SEC_MINI_A -ignore symbol SEC_MINI_B - -ignore symbol FE_NONE -ignore symbol FE_HAS_SIGNAL -ignore symbol FE_HAS_CARRIER -ignore symbol FE_HAS_VITERBI -ignore symbol FE_HAS_SYNC -ignore symbol FE_HAS_LOCK -ignore symbol FE_REINIT -ignore symbol FE_TIMEDOUT - -ignore symbol FEC_NONE -ignore symbol FEC_1_2 -ignore symbol FEC_2_3 -ignore symbol FEC_3_4 -ignore symbol FEC_4_5 -ignore symbol FEC_5_6 -ignore symbol FEC_6_7 -ignore symbol FEC_7_8 -ignore symbol FEC_8_9 -ignore symbol FEC_AUTO -ignore symbol FEC_3_5 -ignore symbol FEC_9_10 -ignore symbol FEC_2_5 - -ignore symbol TRANSMISSION_MODE_AUTO -ignore symbol TRANSMISSION_MODE_1K -ignore symbol TRANSMISSION_MODE_2K -ignore symbol TRANSMISSION_MODE_8K -ignore symbol TRANSMISSION_MODE_4K -ignore symbol TRANSMISSION_MODE_16K -ignore symbol TRANSMISSION_MODE_32K -ignore symbol TRANSMISSION_MODE_C1 -ignore symbol TRANSMISSION_MODE_C3780 -ignore symbol TRANSMISSION_MODE_2K -ignore symbol TRANSMISSION_MODE_8K - -ignore symbol GUARD_INTERVAL_AUTO -ignore symbol GUARD_INTERVAL_1_128 -ignore symbol GUARD_INTERVAL_1_32 -ignore symbol GUARD_INTERVAL_1_16 -ignore symbol GUARD_INTERVAL_1_8 -ignore symbol GUARD_INTERVAL_1_4 -ignore symbol GUARD_INTERVAL_19_128 -ignore symbol GUARD_INTERVAL_19_256 -ignore symbol GUARD_INTERVAL_PN420 -ignore symbol GUARD_INTERVAL_PN595 -ignore symbol GUARD_INTERVAL_PN945 - -ignore symbol HIERARCHY_NONE -ignore symbol HIERARCHY_AUTO -ignore symbol HIERARCHY_1 -ignore symbol HIERARCHY_2 -ignore symbol HIERARCHY_4 - -ignore symbol INTERLEAVING_NONE -ignore symbol INTERLEAVING_AUTO -ignore symbol INTERLEAVING_240 -ignore symbol INTERLEAVING_720 - -ignore symbol PILOT_ON -ignore symbol PILOT_OFF -ignore symbol PILOT_AUTO - -ignore symbol ROLLOFF_35 -ignore symbol ROLLOFF_20 -ignore symbol ROLLOFF_25 -ignore symbol ROLLOFF_AUTO - -ignore symbol INVERSION_ON -ignore symbol INVERSION_OFF -ignore symbol INVERSION_AUTO - -ignore symbol SYS_UNDEFINED -ignore symbol SYS_DVBC_ANNEX_A -ignore symbol SYS_DVBC_ANNEX_B -ignore symbol SYS_DVBC_ANNEX_C -ignore symbol SYS_ISDBC -ignore symbol SYS_DVBT -ignore symbol SYS_DVBT2 -ignore symbol SYS_ISDBT -ignore symbol SYS_ATSC -ignore symbol SYS_ATSCMH -ignore symbol SYS_DTMB -ignore symbol SYS_DVBS -ignore symbol SYS_DVBS2 -ignore symbol SYS_TURBO -ignore symbol SYS_ISDBS -ignore symbol SYS_DAB -ignore symbol SYS_DSS -ignore symbol SYS_CMMB -ignore symbol SYS_DVBH - -ignore symbol ATSCMH_SCCC_BLK_SEP -ignore symbol ATSCMH_SCCC_BLK_COMB -ignore symbol ATSCMH_SCCC_BLK_RES - -ignore symbol ATSCMH_SCCC_CODE_HLF -ignore symbol ATSCMH_SCCC_CODE_QTR -ignore symbol ATSCMH_SCCC_CODE_RES - -ignore symbol ATSCMH_RSFRAME_ENS_PRI -ignore symbol ATSCMH_RSFRAME_ENS_SEC - -ignore symbol ATSCMH_RSFRAME_PRI_ONLY -ignore symbol ATSCMH_RSFRAME_PRI_SEC -ignore symbol ATSCMH_RSFRAME_RES - -ignore symbol ATSCMH_RSCODE_211_187 -ignore symbol ATSCMH_RSCODE_223_187 -ignore symbol ATSCMH_RSCODE_235_187 -ignore symbol ATSCMH_RSCODE_RES - -ignore symbol FE_SCALE_NOT_AVAILABLE -ignore symbol FE_SCALE_DECIBEL -ignore symbol FE_SCALE_RELATIVE -ignore symbol FE_SCALE_COUNTER diff --git a/Documentation/media/index.rst b/Documentation/media/index.rst index 0301c25ff887..8118c2d001ff 100644 --- a/Documentation/media/index.rst +++ b/Documentation/media/index.rst @@ -12,7 +12,7 @@ Linux Media Subsystem Documentation .. toctree:: :maxdepth: 2 - media_uapi + ../userspace-api/media/index media_kapi dvb-drivers/index v4l-drivers/index diff --git a/Documentation/media/intro.rst b/Documentation/media/intro.rst deleted file mode 100644 index 4a6bd665b884..000000000000 --- a/Documentation/media/intro.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -============ -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: - -.. kernel-figure:: typical_media_device.svg - :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 ` covers radio, video capture and output, - cameras, analog TV devices and codecs. - -2. The :ref:`second part ` 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 - :c:type:`fe_delivery_system`. - -3. The :ref:`third part ` covers the Remote Controller API. - -4. The :ref:`fourth part ` covers the Media Controller API. - -5. The :ref:`fifth part ` 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 `__. For discussing improvements, -reporting troubles, sending new drivers, etc, please mail to: `Linux Media -Mailing List (LMML) `__. diff --git a/Documentation/media/lirc.h.rst.exceptions b/Documentation/media/lirc.h.rst.exceptions deleted file mode 100644 index ac768d769113..000000000000 --- a/Documentation/media/lirc.h.rst.exceptions +++ /dev/null @@ -1,80 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# 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 - -# Obsolete ioctls - -ignore ioctl LIRC_GET_LENGTH - -# rc protocols - -ignore symbol RC_PROTO_UNKNOWN -ignore symbol RC_PROTO_OTHER -ignore symbol RC_PROTO_RC5 -ignore symbol RC_PROTO_RC5X_20 -ignore symbol RC_PROTO_RC5_SZ -ignore symbol RC_PROTO_JVC -ignore symbol RC_PROTO_SONY12 -ignore symbol RC_PROTO_SONY15 -ignore symbol RC_PROTO_SONY20 -ignore symbol RC_PROTO_NEC -ignore symbol RC_PROTO_NECX -ignore symbol RC_PROTO_NEC32 -ignore symbol RC_PROTO_SANYO -ignore symbol RC_PROTO_MCIR2_KBD -ignore symbol RC_PROTO_MCIR2_MSE -ignore symbol RC_PROTO_RC6_0 -ignore symbol RC_PROTO_RC6_6A_20 -ignore symbol RC_PROTO_RC6_6A_24 -ignore symbol RC_PROTO_RC6_6A_32 -ignore symbol RC_PROTO_RC6_MCE -ignore symbol RC_PROTO_SHARP -ignore symbol RC_PROTO_XMP -ignore symbol RC_PROTO_CEC -ignore symbol RC_PROTO_IMON -ignore symbol RC_PROTO_RCMM12 -ignore symbol RC_PROTO_RCMM24 -ignore symbol RC_PROTO_RCMM32 -ignore symbol RC_PROTO_XBOX_DVD - -# Undocumented macros - -ignore define PULSE_BIT -ignore define PULSE_MASK - -ignore define LIRC_MODE2_SPACE -ignore define LIRC_MODE2_PULSE - -ignore define LIRC_VALUE_MASK -ignore define LIRC_MODE2_MASK - -ignore define LIRC_MODE_RAW -ignore define LIRC_MODE_LIRCCODE diff --git a/Documentation/media/media.h.rst.exceptions b/Documentation/media/media.h.rst.exceptions deleted file mode 100644 index 9b4c26502d95..000000000000 --- a/Documentation/media/media.h.rst.exceptions +++ /dev/null @@ -1,32 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# 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_ENT_F_DTV_DECODER -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 diff --git a/Documentation/media/media_uapi.rst b/Documentation/media/media_uapi.rst deleted file mode 100644 index 0753005c7bb4..000000000000 --- a/Documentation/media/media_uapi.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -.. include:: - -######################################## -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, with no -Invariant Sections. A copy of the license is included in the chapter -entitled "GNU Free Documentation License". - -.. only:: html - - .. 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 diff --git a/Documentation/media/net.h.rst.exceptions b/Documentation/media/net.h.rst.exceptions deleted file mode 100644 index 5159aa4bbbb9..000000000000 --- a/Documentation/media/net.h.rst.exceptions +++ /dev/null @@ -1,13 +0,0 @@ -# SPDX-License-Identifier: GPL-2.0 - -# 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 :c:type:`dvb_net_if` -replace define DVB_NET_FEEDTYPE_ULE :c:type:`dvb_net_if` diff --git a/Documentation/media/typical_media_device.svg b/Documentation/media/typical_media_device.svg deleted file mode 100644 index bfd5c7db3b00..000000000000 --- a/Documentation/media/typical_media_device.svg +++ /dev/null @@ -1,116 +0,0 @@ - - -image/svg+xmlAudio decoder -Video decoder -Audio encoder -Button Key/IR input logic -EEPROM -Sensor -System Bus -Demux -Conditional Access Module -Video encoder -Radio / Analog TV -Digital TV -PS.: picture is not complete: other blocks may be present -Webcam -Processing blocks -Smartcard -TunerFM/TV -Satellite Equipment Control (SEC) -Demod -I2C Bus (control bus) -Digital TV Frontend - -CPU -PCI, USB, SPI, I2C, ... -Bridge - DMA - diff --git a/Documentation/media/uapi/cec/cec-api.rst b/Documentation/media/uapi/cec/cec-api.rst deleted file mode 100644 index 0780ba07995a..000000000000 --- a/Documentation/media/uapi/cec/cec-api.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. include:: - -.. _cec: - -######################################### -Part V - Consumer Electronics Control API -######################################### - -This part describes the CEC: Consumer Electronics Control - - -.. only:: html - - .. class:: toc-title - - Table of Contents - -.. toctree:: - :maxdepth: 5 - :numbered: - - cec-intro - cec-funcs - cec-pin-error-inj - cec-header - - -********************** -Revision and Copyright -********************** -Authors: - -- Verkuil, Hans - - - Initial version. - -**Copyright** |copy| 2016 : Hans Verkuil - -**************** -Revision History -**************** - -:revision: 1.0.0 / 2016-03-17 (*hv*) - -Initial revision diff --git a/Documentation/media/uapi/cec/cec-func-close.rst b/Documentation/media/uapi/cec/cec-func-close.rst deleted file mode 100644 index e10d675546f8..000000000000 --- a/Documentation/media/uapi/cec/cec-func-close.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec-func-close: - -*********** -cec close() -*********** - -Name -==== - -cec-close - Close a cec device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int close( int fd ) - :name: cec-close - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - - -Description -=========== - -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. diff --git a/Documentation/media/uapi/cec/cec-func-ioctl.rst b/Documentation/media/uapi/cec/cec-func-ioctl.rst deleted file mode 100644 index c18d4ba5eb37..000000000000 --- a/Documentation/media/uapi/cec/cec-func-ioctl.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec-func-ioctl: - -*********** -cec ioctl() -*********** - -Name -==== - -cec-ioctl - Control a cec device - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int ioctl( int fd, int request, void *argp ) - :name: cec-ioctl - -Arguments -========= - -``fd`` - File descriptor returned by :c: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 -=========== - -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 ` 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. diff --git a/Documentation/media/uapi/cec/cec-func-open.rst b/Documentation/media/uapi/cec/cec-func-open.rst deleted file mode 100644 index f235aa80155c..000000000000 --- a/Documentation/media/uapi/cec/cec-func-open.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec-func-open: - -********** -cec open() -********** - -Name -==== - -cec-open - Open a cec device - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int open( const char *device_name, int flags ) - :name: cec-open - - -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 ` and :ref:`CEC_DQEVENT ` ioctls - will return the ``EAGAIN`` error code when no message or event is available, and - ioctls :ref:`CEC_TRANSMIT `, - :ref:`CEC_ADAP_S_PHYS_ADDR ` and - :ref:`CEC_ADAP_S_LOG_ADDRS ` - all return 0. - - Other flags have no effect. - - -Description -=========== - -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. diff --git a/Documentation/media/uapi/cec/cec-func-poll.rst b/Documentation/media/uapi/cec/cec-func-poll.rst deleted file mode 100644 index 3f6c5b0effa3..000000000000 --- a/Documentation/media/uapi/cec/cec-func-poll.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec-func-poll: - -********** -cec poll() -********** - -Name -==== - -cec-poll - Wait for some event on a file descriptor - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) - :name: cec-poll - -Arguments -========= - -``ufds`` - List of FD events to be watched - -``nfds`` - Number of FD events at the \*ufds array - -``timeout`` - Timeout to wait for events - - -Description -=========== - -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 struct :c:type:`pollfd` -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 times 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`` value exceeds the ``RLIMIT_NOFILE`` value. Use - ``getrlimit()`` to obtain this value. diff --git a/Documentation/media/uapi/cec/cec-funcs.rst b/Documentation/media/uapi/cec/cec-funcs.rst deleted file mode 100644 index dc6da9c639a8..000000000000 --- a/Documentation/media/uapi/cec/cec-funcs.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec-user-func: - -****************** -Function Reference -****************** - - -.. toctree:: - :maxdepth: 1 - - 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-adap-g-conn-info - cec-ioc-dqevent - cec-ioc-g-mode - cec-ioc-receive diff --git a/Documentation/media/uapi/cec/cec-header.rst b/Documentation/media/uapi/cec/cec-header.rst deleted file mode 100644 index 726f9766a130..000000000000 --- a/Documentation/media/uapi/cec/cec-header.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec_header: - -*************** -CEC Header File -*************** - -.. kernel-include:: $BUILDDIR/cec.h.rst - diff --git a/Documentation/media/uapi/cec/cec-intro.rst b/Documentation/media/uapi/cec/cec-intro.rst deleted file mode 100644 index 05088fcefe81..000000000000 --- a/Documentation/media/uapi/cec/cec-intro.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _cec-intro: - -Introduction -============ - -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. - -In order to check the support and test it, it is suggested to download -the `v4l-utils `_ package. It -provides three tools to handle CEC: - -- cec-ctl: the Swiss army knife of CEC. Allows you to configure, transmit - and monitor CEC messages. - -- cec-compliance: does a CEC compliance test of a remote CEC device to - determine how compliant the CEC implementation is. - -- cec-follower: emulates a CEC follower. diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst deleted file mode 100644 index 76761a98c312..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-caps.rst +++ /dev/null @@ -1,150 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CEC_ADAP_G_CAPS: - -********************* -ioctl CEC_ADAP_G_CAPS -********************* - -Name -==== - -CEC_ADAP_G_CAPS - Query device capabilities - -Synopsis -======== - -.. c:function:: int ioctl( int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp ) - :name: CEC_ADAP_G_CAPS - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - - -Description -=========== - -All cec devices must support :ref:`ioctl CEC_ADAP_G_CAPS `. To query -device information, applications call the ioctl with a pointer to a -struct :c:type:`cec_caps`. The driver fills the structure and -returns the information to the application. The ioctl never fails. - -.. tabularcolumns:: |p{1.2cm}|p{2.5cm}|p{13.8cm}| - -.. c:type:: cec_caps - -.. flat-table:: struct cec_caps - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 16 - - * - char - - ``driver[32]`` - - The name of the cec adapter driver. - * - char - - ``name[32]`` - - The name of this CEC adapter. The combination ``driver`` and - ``name`` must be unique. - * - __u32 - - ``capabilities`` - - The capabilities of the CEC adapter, see - :ref:`cec-capabilities`. - * - __u32 - - ``version`` - - CEC Framework API version, formatted with the ``KERNEL_VERSION()`` - macro. - - -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| - -.. _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 `. 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 `. 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 `. 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-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. - * .. _`CEC-CAP-NEEDS-HPD`: - - - ``CEC_CAP_NEEDS_HPD`` - - 0x00000040 - - The CEC hardware is only active if the HDMI Hotplug Detect pin is - high. This makes it impossible to use CEC to wake up displays that - set the HPD pin low when in standby mode, but keep the CEC bus - alive. - * .. _`CEC-CAP-MONITOR-PIN`: - - - ``CEC_CAP_MONITOR_PIN`` - - 0x00000080 - - The CEC hardware can monitor CEC pin changes from low to high voltage - and vice versa. When in pin monitoring mode the application will - receive ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events. - * .. _`CEC-CAP-CONNECTOR-INFO`: - - - ``CEC_CAP_CONNECTOR_INFO`` - - 0x00000100 - - If this capability is set, then :ref:`CEC_ADAP_G_CONNECTOR_INFO` can - be used. - -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 ` chapter. diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-conn-info.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-conn-info.rst deleted file mode 100644 index 6818ddf1495c..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-conn-info.rst +++ /dev/null @@ -1,105 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 -.. -.. Copyright 2019 Google LLC -.. -.. _CEC_ADAP_G_CONNECTOR_INFO: - -******************************* -ioctl CEC_ADAP_G_CONNECTOR_INFO -******************************* - -Name -==== - -CEC_ADAP_G_CONNECTOR_INFO - Query HDMI connector information - -Synopsis -======== - -.. c:function:: int ioctl( int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp ) - :name: CEC_ADAP_G_CONNECTOR_INFO - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - - -Description -=========== - -Using this ioctl an application can learn which HDMI connector this CEC -device corresponds to. While calling this ioctl the application should -provide a pointer to a cec_connector_info struct which will be populated -by the kernel with the info provided by the adapter's driver. This ioctl -is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set. - -.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| - -.. c:type:: cec_connector_info - -.. flat-table:: struct cec_connector_info - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 8 - - * - __u32 - - ``type`` - - The type of connector this adapter is associated with. - * - union { - - ``(anonymous)`` - * - ``struct cec_drm_connector_info`` - - drm - - :ref:`cec-drm-connector-info` - * - } - - - - -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| - -.. _connector-type: - -.. flat-table:: Connector types - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 8 - - * .. _`CEC-CONNECTOR-TYPE-NO-CONNECTOR`: - - - ``CEC_CONNECTOR_TYPE_NO_CONNECTOR`` - - 0 - - No connector is associated with the adapter/the information is not - provided by the driver. - * .. _`CEC-CONNECTOR-TYPE-DRM`: - - - ``CEC_CONNECTOR_TYPE_DRM`` - - 1 - - Indicates that a DRM connector is associated with this adapter. - Information about the connector can be found in - :ref:`cec-drm-connector-info`. - -.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.6cm}| - -.. c:type:: cec_drm_connector_info - -.. _cec-drm-connector-info: - -.. flat-table:: struct cec_drm_connector_info - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 8 - - * .. _`CEC-DRM-CONNECTOR-TYPE-CARD-NO`: - - - __u32 - - ``card_no`` - - DRM card number: the number from a card's path, e.g. 0 in case of - /dev/card0. - * .. _`CEC-DRM-CONNECTOR-TYPE-CONNECTOR_ID`: - - - __u32 - - ``connector_id`` - - DRM connector ID. diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst deleted file mode 100644 index 26465094e3f1..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst +++ /dev/null @@ -1,378 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _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 -======== - -.. c:function:: int ioctl( int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp ) - :name: CEC_ADAP_G_LOG_ADDRS - -.. c:function:: int ioctl( int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp ) - :name: CEC_ADAP_S_LOG_ADDRS - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - Pointer to struct :c:type:`cec_log_addrs`. - -Description -=========== - -To query the current CEC logical addresses, applications call -:ref:`ioctl CEC_ADAP_G_LOG_ADDRS ` with a pointer to a -struct :c:type:`cec_log_addrs` where the driver stores the logical addresses. - -To set new logical addresses, applications fill in -struct :c:type:`cec_log_addrs` and call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` -with a pointer to this struct. The :ref:`ioctl 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 ` -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 and the -``cec_version``, ``vendor_id`` and ``osd_name`` fields are all reset to their default -values (CEC version 2.0, no vendor ID and an empty OSD name). - -If the physical address is valid (see :ref:`ioctl 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 ` event is sent when the -logical addresses are claimed or cleared. - -Attempting to call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` when -logical address types are already defined will return with error ``EBUSY``. - -.. c:type:: cec_log_addrs - -.. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{7.5cm}| - -.. cssclass:: longtable - -.. flat-table:: struct cec_log_addrs - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 16 - - * - __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``. - * - __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. - * - __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 ` is not allowed by the CEC - framework. - * - __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. - * - __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``. - * - __u32 - - ``flags`` - - Flags. See :ref:`cec-log-addrs-flags` for a list of available flags. - * - char - - ``osd_name[15]`` - - The On-Screen Display name as is returned by the - ``CEC_MSG_SET_OSD_NAME`` message. - * - __u8 - - ``primary_device_type[CEC_MAX_LOG_ADDRS]`` - - Primary device type for each logical address. See - :ref:`cec-prim-dev-types` for possible types. - * - __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 `). - * - __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. - * - __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. - - -.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| - -.. _cec-log-addrs-flags: - -.. flat-table:: Flags for struct cec_log_addrs - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * .. _`CEC-LOG-ADDRS-FL-ALLOW-UNREG-FALLBACK`: - - - ``CEC_LOG_ADDRS_FL_ALLOW_UNREG_FALLBACK`` - - 1 - - By default if no logical address of the requested type can be claimed, then - it will go back to the unconfigured state. If this flag is set, then it will - fallback to the Unregistered logical address. Note that if the Unregistered - logical address was explicitly requested, then this flag has no effect. - * .. _`CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU`: - - - ``CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU`` - - 2 - - By default the ``CEC_MSG_USER_CONTROL_PRESSED`` and ``CEC_MSG_USER_CONTROL_RELEASED`` - messages are only passed on to the follower(s), if any. If this flag is set, - then these messages are also passed on to the remote control input subsystem - and will appear as keystrokes. This features needs to be enabled explicitly. - If CEC is used to enter e.g. passwords, then you may not want to enable this - to avoid trivial snooping of the keystrokes. - * .. _`CEC-LOG-ADDRS-FL-CDC-ONLY`: - - - ``CEC_LOG_ADDRS_FL_CDC_ONLY`` - - 4 - - If this flag is set, then the device is CDC-Only. CDC-Only CEC devices - are CEC devices that can only handle CDC messages. - - All other messages are ignored. - - -.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.7cm}| - -.. _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. - - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| - -.. _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. - - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| - -.. _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). - - - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| - -.. _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 ` chapter. - -The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` can return the following -error codes: - -ENOTTY - The ``CEC_CAP_LOG_ADDRS`` capability wasn't set, so this ioctl is not supported. - -EBUSY - The CEC adapter is currently configuring itself, or it is already configured and - ``num_log_addrs`` is non-zero, or another filehandle is in exclusive follower or - initiator mode, or the filehandle is in mode ``CEC_MODE_NO_INITIATOR``. - -EINVAL - The contents of struct :c:type:`cec_log_addrs` is invalid. diff --git a/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst b/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst deleted file mode 100644 index 693be2f9bf2e..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst +++ /dev/null @@ -1,100 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _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 -======== - -.. c:function:: int ioctl( int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp ) - :name: CEC_ADAP_G_PHYS_ADDR - -.. c:function:: int ioctl( int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp ) - :name: CEC_ADAP_S_PHYS_ADDR - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - Pointer to the CEC address. - -Description -=========== - -To query the current physical address applications call -:ref:`ioctl 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 ` with a pointer to -this integer. The :ref:`ioctl 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 ` 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 `), -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 ` 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 ` chapter. - -The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR ` can return the following -error codes: - -ENOTTY - The ``CEC_CAP_PHYS_ADDR`` capability wasn't set, so this ioctl is not supported. - -EBUSY - Another filehandle is in exclusive follower or initiator mode, or the filehandle - is in mode ``CEC_MODE_NO_INITIATOR``. - -EINVAL - The physical address is malformed. diff --git a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst b/Documentation/media/uapi/cec/cec-ioc-dqevent.rst deleted file mode 100644 index d16b226b1bef..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-dqevent.rst +++ /dev/null @@ -1,257 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CEC_DQEVENT: - -***************** -ioctl CEC_DQEVENT -***************** - -Name -==== - -CEC_DQEVENT - Dequeue a CEC event - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp ) - :name: CEC_DQEVENT - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - - -Description -=========== - -CEC devices can send asynchronous events. These can be retrieved by -calling :c:func:`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 ` 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. - -.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}| - -.. c:type:: cec_event_state_change - -.. flat-table:: struct cec_event_state_change - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 8 - - * - __u16 - - ``phys_addr`` - - The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no - valid physical address is set. - * - __u16 - - ``log_addr_mask`` - - The current set of claimed logical addresses. This is 0 if no logical - addresses are claimed or if ``phys_addr`` is ``CEC_PHYS_ADDR_INVALID``. - If bit 15 is set (``1 << CEC_LOG_ADDR_UNREGISTERED``) then this device - has the unregistered logical address. In that case all other bits are 0. - * - __u16 - - ``have_conn_info`` - - If non-zero, then HDMI connector information is available. - This field is only valid if ``CEC_CAP_CONNECTOR_INFO`` is set. If that - capability is set and ``have_conn_info`` is zero, then that indicates - that the HDMI connector device is not instantiated, either because - the HDMI driver is still configuring the device or because the HDMI - device was unbound. - - -.. c:type:: cec_event_lost_msgs - -.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}| - -.. flat-table:: struct cec_event_lost_msgs - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 16 - - * - __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. - - -.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| - -.. c:type:: cec_event - -.. flat-table:: struct cec_event - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 8 - - * - __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`. - * - __u32 - - ``event`` - - The CEC event type, see :ref:`cec-events`. - * - __u32 - - ``flags`` - - Event flags, see :ref:`cec-event-flags`. - * - union { - - (anonymous) - * - struct cec_event_state_change - - ``state_change`` - - The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE ` - event. - * - struct cec_event_lost_msgs - - ``lost_msgs`` - - The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS ` - event. - * - } - - - - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| - -.. _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-PIN-CEC-LOW`: - - - ``CEC_EVENT_PIN_CEC_LOW`` - - 3 - - Generated if the CEC pin goes from a high voltage to a low voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. - * .. _`CEC-EVENT-PIN-CEC-HIGH`: - - - ``CEC_EVENT_PIN_CEC_HIGH`` - - 4 - - Generated if the CEC pin goes from a low voltage to a high voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. - * .. _`CEC-EVENT-PIN-HPD-LOW`: - - - ``CEC_EVENT_PIN_HPD_LOW`` - - 5 - - Generated if the HPD pin goes from a high voltage to a low voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. When open() is called, the HPD pin can be read and - if the HPD is low, then an initial event will be generated for that - filehandle. - * .. _`CEC-EVENT-PIN-HPD-HIGH`: - - - ``CEC_EVENT_PIN_HPD_HIGH`` - - 6 - - Generated if the HPD pin goes from a low voltage to a high voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. When open() is called, the HPD pin can be read and - if the HPD is high, then an initial event will be generated for that - filehandle. - * .. _`CEC-EVENT-PIN-5V-LOW`: - - - ``CEC_EVENT_PIN_5V_LOW`` - - 6 - - Generated if the 5V pin goes from a high voltage to a low voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. When open() is called, the 5V pin can be read and - if the 5V is low, then an initial event will be generated for that - filehandle. - * .. _`CEC-EVENT-PIN-5V-HIGH`: - - - ``CEC_EVENT_PIN_5V_HIGH`` - - 7 - - Generated if the 5V pin goes from a low voltage to a high voltage. - Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` - capability set. When open() is called, the 5V pin can be read and - if the 5V is high, then an initial event will be generated for that - filehandle. - - -.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}| - -.. _cec-event-flags: - -.. flat-table:: CEC Event Flags - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 8 - - * .. _`CEC-EVENT-FL-INITIAL-STATE`: - - - ``CEC_EVENT_FL_INITIAL_STATE`` - - 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. - * .. _`CEC-EVENT-FL-DROPPED-EVENTS`: - - - ``CEC_EVENT_FL_DROPPED_EVENTS`` - - 2 - - Set if one or more events of the given event type have been dropped. - This is an indication that the application cannot keep up. - - - -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 ` chapter. - -The :ref:`ioctl CEC_DQEVENT ` can return the following -error codes: - -EAGAIN - This is returned when the filehandle is in non-blocking mode and there - are no pending events. - -ERESTARTSYS - An interrupt (e.g. Ctrl-C) arrived while in blocking mode waiting for - events to arrive. diff --git a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst b/Documentation/media/uapi/cec/cec-ioc-g-mode.rst deleted file mode 100644 index 2535b77e3459..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-g-mode.rst +++ /dev/null @@ -1,301 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _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 -======== - -.. c:function:: int ioctl( int fd, CEC_G_MODE, __u32 *argp ) - :name: CEC_G_MODE - -.. c:function:: int ioctl( int fd, CEC_S_MODE, __u32 *argp ) - :name: CEC_S_MODE - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - Pointer to CEC mode. - -Description -=========== - -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 ` 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 `. 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 `. - -Available initiator modes are: - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| - -.. _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: - -.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}| - -.. _cec-mode-follower_e: - -.. cssclass:: longtable - -.. 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 ` is not set or if :ref:`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 ` is not set or if :ref:`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 ` - is not set or if :ref:`CEC_MODE_NO_INITIATOR ` was specified, - the ``EINVAL`` error code is returned in that case. - * .. _`CEC-MODE-MONITOR-PIN`: - - - ``CEC_MODE_MONITOR_PIN`` - - 0xd0 - - Put the file descriptor into pin monitoring mode. Can only be used in - combination with :ref:`CEC_MODE_NO_INITIATOR `, - otherwise the ``EINVAL`` error code will be returned. - This mode requires that the :ref:`CEC_CAP_MONITOR_PIN ` - capability is set, otherwise the ``EINVAL`` error code is returned. - While in pin monitoring mode this file descriptor can receive the - ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events to see the - low-level CEC pin transitions. This is very useful for debugging. - This mode 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`: - - - ``CEC_MODE_MONITOR`` - - 0xe0 - - Put the file descriptor into monitor mode. Can only be used in - combination with :ref:`CEC_MODE_NO_INITIATOR `, - otherwise the ``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 `, 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 ` 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: - -.. tabularcolumns:: |p{6.6cm}|p{10.9cm}| - -.. _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`` - - The core will return the CEC version that was set with - :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `, - except when in passthrough mode. In passthrough mode the core - does nothing and this message has to be handled by a follower - instead. - * .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`: - - - ``CEC_MSG_GIVE_DEVICE_VENDOR_ID`` - - The core will return the vendor ID that was set with - :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `, - except when in passthrough mode. In passthrough mode the core - does nothing and this message has to be handled by a follower - instead. - * .. _`CEC-MSG-ABORT`: - - - ``CEC_MSG_ABORT`` - - The core will return a Feature Abort message with reason - 'Feature Refused' as per the specification, except when in - passthrough mode. In passthrough mode the core does nothing - and this message has to be handled by a follower instead. - * .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`: - - - ``CEC_MSG_GIVE_PHYSICAL_ADDR`` - - The core will report the current physical address, except when - in passthrough mode. In passthrough mode the core does nothing - and this message has to be handled by a follower instead. - * .. _`CEC-MSG-GIVE-OSD-NAME`: - - - ``CEC_MSG_GIVE_OSD_NAME`` - - The core will report the current OSD name that was set with - :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `, - except when in passthrough mode. In passthrough mode the core - does nothing and this message has to be handled by a follower - instead. - * .. _`CEC-MSG-GIVE-FEATURES`: - - - ``CEC_MSG_GIVE_FEATURES`` - - The core will do nothing if the CEC version is older than 2.0, - otherwise it will report the current features that were set with - :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `, - except when in passthrough mode. In passthrough mode the core - does nothing (for any CEC version) and this message has to be handled - by a follower instead. - * .. _`CEC-MSG-USER-CONTROL-PRESSED`: - - - ``CEC_MSG_USER_CONTROL_PRESSED`` - - If :ref:`CEC_CAP_RC ` is set and if - :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU ` - is set, then generate a remote control key - press. This message is always passed on to the follower(s). - * .. _`CEC-MSG-USER-CONTROL-RELEASED`: - - - ``CEC_MSG_USER_CONTROL_RELEASED`` - - If :ref:`CEC_CAP_RC ` is set and if - :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU ` - is set, then generate a remote control key - release. This message is always passed on to the follower(s). - * .. _`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 the follower(s). - - - -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 ` chapter. - -The :ref:`ioctl CEC_S_MODE ` can return the following -error codes: - -EINVAL - The requested mode is invalid. - -EPERM - Monitor mode is requested, but the process does have the ``CAP_NET_ADMIN`` - capability. - -EBUSY - Someone else is already an exclusive follower or initiator. diff --git a/Documentation/media/uapi/cec/cec-ioc-receive.rst b/Documentation/media/uapi/cec/cec-ioc-receive.rst deleted file mode 100644 index 4137903d672e..000000000000 --- a/Documentation/media/uapi/cec/cec-ioc-receive.rst +++ /dev/null @@ -1,391 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CEC_TRANSMIT: -.. _CEC_RECEIVE: - -*********************************** -ioctls CEC_RECEIVE and CEC_TRANSMIT -*********************************** - -Name -==== - -CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, CEC_RECEIVE, struct cec_msg \*argp ) - :name: CEC_RECEIVE - -.. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg \*argp ) - :name: CEC_TRANSMIT - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``argp`` - Pointer to struct cec_msg. - -Description -=========== - -To receive a CEC message the application has to fill in the -``timeout`` field of struct :c:type:`cec_msg` and pass it to -:ref:`ioctl 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 struct -:c:type:`cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT `. -The :ref:`ioctl 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 ` 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. - -Normally calling :ref:`ioctl CEC_TRANSMIT ` when the physical -address is invalid (due to e.g. a disconnect) will return ``ENONET``. - -However, the CEC specification allows sending messages from 'Unregistered' to -'TV' when the physical address is invalid since some TVs pull the hotplug detect -pin of the HDMI connector low when they go into standby, or when switching to -another input. - -When the hotplug detect pin goes low the EDID disappears, and thus the -physical address, but the cable is still connected and CEC still works. -In order to detect/wake up the device it is allowed to send poll and 'Image/Text -View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). - -.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}| - -.. c:type:: cec_msg - -.. cssclass:: longtable - -.. flat-table:: struct cec_msg - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 16 - - * - __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`. - * - __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`. - * - __u32 - - ``len`` - - The length of the message. For :ref:`ioctl CEC_TRANSMIT ` this is filled in - by the application. The driver will fill this in for - :ref:`ioctl CEC_RECEIVE `. For :ref:`ioctl CEC_TRANSMIT ` it will be - filled in by the driver with the length of the reply message if ``reply`` was set. - * - __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 `. - If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT `, - then it will be replaced by 1000 if the ``reply`` is non-zero or - ignored if ``reply`` is 0. - * - __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. - * - __u32 - - ``flags`` - - Flags. See :ref:`cec-msg-flags` for a list of available flags. - * - __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 message was received, not transmitted. - * - __u8 - - ``msg[16]`` - - The message payload. For :ref:`ioctl CEC_TRANSMIT ` this is filled in by the - application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE `. - For :ref:`ioctl CEC_TRANSMIT ` it will be filled in by the driver with - the payload of the reply message if ``timeout`` was set. - * - __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 `. - 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 ` or - :ref:`CEC_RX_STATUS_FEATURE_ABORT `. - - If the transmitter message is ``CEC_MSG_INITIATE_ARC`` then the ``reply`` - values ``CEC_MSG_REPORT_ARC_INITIATED`` and ``CEC_MSG_REPORT_ARC_TERMINATED`` - are processed differently: either value will match both possible replies. - The reason is that the ``CEC_MSG_INITIATE_ARC`` message is the only CEC - message that has two possible replies other than Feature Abort. The - ``reply`` field will be updated with the actual reply so that it is - synchronized with the contents of the received message. - * - __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. - * - __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 message was received, not transmitted. - * - __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 ` status bit is set. - * - __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 ` status bit is set. - * - __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 ` status bit is set. - * - __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 ` status bit is set. - - -.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}| - -.. _cec-msg-flags: - -.. flat-table:: Flags for struct cec_msg - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`: - - - ``CEC_MSG_FL_REPLY_TO_FOLLOWERS`` - - 1 - - If a CEC transmit expects a reply, then by default that reply is only sent to - the filehandle that called :ref:`ioctl CEC_TRANSMIT `. If this - flag is set, then the reply is also sent to all followers, if any. If the - filehandle that called :ref:`ioctl CEC_TRANSMIT ` is also a - follower, then that filehandle will receive the reply twice: once as the - result of the :ref:`ioctl CEC_TRANSMIT `, and once via - :ref:`ioctl CEC_RECEIVE `. - - * .. _`CEC-MSG-FL-RAW`: - - - ``CEC_MSG_FL_RAW`` - - 2 - - Normally CEC messages are validated before transmitting them. If this - flag is set when :ref:`ioctl CEC_TRANSMIT ` is called, - then no validation takes place and the message is transmitted as-is. - This is useful when debugging CEC issues. - This flag is only allowed if the process has the ``CAP_SYS_RAWIO`` - capability. If that is not set, then the ``EPERM`` error code is - returned. - - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| - -.. _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 `. - 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, i.e. another transmit started at the - same time with a higher priority. Optional status, not all hardware - can detect this error condition. - * .. _`CEC-TX-STATUS-NACK`: - - - ``CEC_TX_STATUS_NACK`` - - 0x04 - - Message was not acknowledged. Note that some hardware cannot tell apart - a 'Not Acknowledged' status from other error conditions, i.e. the result - of a transmit is just OK or FAIL. In that case this status will be - returned when the transmit failed. - * .. _`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. Optional status, not all hardware can detect this - error condition. - * .. _`CEC-TX-STATUS-ERROR`: - - - ``CEC_TX_STATUS_ERROR`` - - 0x10 - - Some error occurred. This is used for any errors that do not fit - ``CEC_TX_STATUS_ARB_LOST`` or ``CEC_TX_STATUS_LOW_DRIVE``, either because - the hardware could not tell which error occurred, or because the hardware - tested for other conditions besides those two. Optional status. - * .. _`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 `. - Other bits can still be set to explain which failures were seen. - * .. _`CEC-TX-STATUS-ABORTED`: - - - ``CEC_TX_STATUS_ABORTED`` - - 0x40 - - The transmit was aborted due to an HDMI disconnect, or the adapter - was unconfigured, or a transmit was interrupted, or the driver - returned an error when attempting to start a transmit. - * .. _`CEC-TX-STATUS-TIMEOUT`: - - - ``CEC_TX_STATUS_TIMEOUT`` - - 0x80 - - The transmit timed out. This should not normally happen and this - indicates a driver problem. - - -.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| - -.. _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. - * .. _`CEC-RX-STATUS-ABORTED`: - - - ``CEC_RX_STATUS_ABORTED`` - - 0x08 - - The wait for a reply to an earlier transmitted message was aborted - because the HDMI cable was disconnected, the adapter was unconfigured - or the :ref:`CEC_TRANSMIT ` that waited for a - reply was interrupted. - - - -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 ` chapter. - -The :ref:`ioctl CEC_RECEIVE ` can return the following -error codes: - -EAGAIN - No messages are in the receive queue, and the filehandle is in non-blocking mode. - -ETIMEDOUT - The ``timeout`` was reached while waiting for a message. - -ERESTARTSYS - The wait for a message was interrupted (e.g. by Ctrl-C). - -The :ref:`ioctl CEC_TRANSMIT ` can return the following -error codes: - -ENOTTY - The ``CEC_CAP_TRANSMIT`` capability wasn't set, so this ioctl is not supported. - -EPERM - The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` - has never been called, or ``CEC_MSG_FL_RAW`` was used from a process that - did not have the ``CAP_SYS_RAWIO`` capability. - -ENONET - The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` - was called, but the physical address is invalid so no logical address was claimed. - An exception is made in this case for transmits from initiator 0xf ('Unregistered') - to destination 0 ('TV'). In that case the transmit will proceed as usual. - -EBUSY - Another filehandle is in exclusive follower or initiator mode, or the filehandle - is in mode ``CEC_MODE_NO_INITIATOR``. This is also returned if the transmit - queue is full. - -EINVAL - The contents of struct :c:type:`cec_msg` is invalid. - -ERESTARTSYS - The wait for a successful transmit was interrupted (e.g. by Ctrl-C). diff --git a/Documentation/media/uapi/cec/cec-pin-error-inj.rst b/Documentation/media/uapi/cec/cec-pin-error-inj.rst deleted file mode 100644 index 725f8b1c9965..000000000000 --- a/Documentation/media/uapi/cec/cec-pin-error-inj.rst +++ /dev/null @@ -1,334 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -CEC Pin Framework Error Injection -================================= - -The CEC Pin Framework is a core CEC framework for CEC hardware that only -has low-level support for the CEC bus. Most hardware today will have -high-level CEC support where the hardware deals with driving the CEC bus, -but some older devices aren't that fancy. However, this framework also -allows you to connect the CEC pin to a GPIO on e.g. a Raspberry Pi and -you have now made a CEC adapter. - -What makes doing this so interesting is that since we have full control -over the bus it is easy to support error injection. This is ideal to -test how well CEC adapters can handle error conditions. - -Currently only the cec-gpio driver (when the CEC line is directly -connected to a pull-up GPIO line) and the AllWinner A10/A20 drm driver -support this framework. - -If ``CONFIG_CEC_PIN_ERROR_INJ`` is enabled, then error injection is available -through debugfs. Specifically, in ``/sys/kernel/debug/cec/cecX/`` there is -now an ``error-inj`` file. - -.. note:: - - The error injection commands are not a stable ABI and may change in the - future. - -With ``cat error-inj`` you can see both the possible commands and the current -error injection status:: - - $ cat /sys/kernel/debug/cec/cec0/error-inj - # Clear error injections: - # clear clear all rx and tx error injections - # rx-clear clear all rx error injections - # tx-clear clear all tx error injections - # clear clear all rx and tx error injections for - # rx-clear clear all rx error injections for - # tx-clear clear all tx error injections for - # - # RX error injection: - # [,] rx-nack NACK the message instead of sending an ACK - # [,] rx-low-drive force a low-drive condition at this bit position - # [,] rx-add-byte add a spurious byte to the received CEC message - # [,] rx-remove-byte remove the last byte from the received CEC message - # [,] rx-arb-lost generate a POLL message to trigger an arbitration lost - # - # TX error injection settings: - # tx-ignore-nack-until-eom ignore early NACKs until EOM - # tx-custom-low-usecs define the 'low' time for the custom pulse - # tx-custom-high-usecs define the 'high' time for the custom pulse - # tx-custom-pulse transmit the custom pulse once the bus is idle - # - # TX error injection: - # [,] tx-no-eom don't set the EOM bit - # [,] tx-early-eom set the EOM bit one byte too soon - # [,] tx-add-bytes append (1-255) spurious bytes to the message - # [,] tx-remove-byte drop the last byte from the message - # [,] tx-short-bit make this bit shorter than allowed - # [,] tx-long-bit make this bit longer than allowed - # [,] tx-custom-bit send the custom pulse instead of this bit - # [,] tx-short-start send a start pulse that's too short - # [,] tx-long-start send a start pulse that's too long - # [,] tx-custom-start send the custom pulse instead of the start pulse - # [,] tx-last-bit stop sending after this bit - # [,] tx-low-drive force a low-drive condition at this bit position - # - # CEC message opcode (0-255) or 'any' - # 'once' (default), 'always', 'toggle' or 'off' - # CEC message bit (0-159) - # 10 bits per 'byte': bits 0-7: data, bit 8: EOM, bit 9: ACK - # CEC poll message used to test arbitration lost (0x00-0xff, default 0x0f) - # microseconds (0-10000000, default 1000) - - clear - -You can write error injection commands to ``error-inj`` using -``echo 'cmd' >error-inj`` or ``cat cmd.txt >error-inj``. The ``cat error-inj`` -output contains the current error commands. You can save the output to a file -and use it as an input to ``error-inj`` later. - -Basic Syntax ------------- - -Leading spaces/tabs are ignored. If the next character is a ``#`` or the end -of the line was reached, then the whole line is ignored. Otherwise a command -is expected. - -The error injection commands fall in two main groups: those relating to -receiving CEC messages and those relating to transmitting CEC messages. In -addition, there are commands to clear existing error injection commands and -to create custom pulses on the CEC bus. - -Most error injection commands can be executed for specific CEC opcodes or for -all opcodes (``any``). Each command also has a 'mode' which can be ``off`` -(can be used to turn off an existing error injection command), ``once`` -(the default) which will trigger the error injection only once for the next -received or transmitted message, ``always`` to always trigger the error -injection and ``toggle`` to toggle the error injection on or off for every -transmit or receive. - -So '``any rx-nack``' will NACK the next received CEC message, -'``any,always rx-nack``' will NACK all received CEC messages and -'``0x82,toggle rx-nack``' will only NACK if an Active Source message was -received and do that only for every other received message. - -After an error was injected with mode ``once`` the error injection command -is cleared automatically, so ``once`` is a one-time deal. - -All combinations of ```` and error injection commands can co-exist. So -this is fine:: - - 0x9e tx-add-bytes 1 - 0x9e tx-early-eom - 0x9f tx-add-bytes 2 - any rx-nack - -All four error injection commands will be active simultaneously. - -However, if the same ```` and command combination is specified, -but with different arguments:: - - 0x9e tx-add-bytes 1 - 0x9e tx-add-bytes 2 - -Then the second will overwrite the first. - -Clear Error Injections ----------------------- - -``clear`` - Clear all error injections. - -``rx-clear`` - Clear all receive error injections - -``tx-clear`` - Clear all transmit error injections - -`` clear`` - Clear all error injections for the given opcode. - -`` rx-clear`` - Clear all receive error injections for the given opcode. - -`` tx-clear`` - Clear all transmit error injections for the given opcode. - -Receive Messages ----------------- - -``[,] rx-nack`` - NACK broadcast messages and messages directed to this CEC adapter. - Every byte of the message will be NACKed in case the transmitter - keeps transmitting after the first byte was NACKed. - -``[,] rx-low-drive `` - Force a Low Drive condition at this bit position. If specifies - a specific CEC opcode then the bit position must be at least 18, - otherwise the opcode hasn't been received yet. This tests if the - transmitter can handle the Low Drive condition correctly and reports - the error correctly. Note that a Low Drive in the first 4 bits can also - be interpreted as an Arbitration Lost condition by the transmitter. - This is implementation dependent. - -``[,] rx-add-byte`` - Add a spurious 0x55 byte to the received CEC message, provided - the message was 15 bytes long or less. This is useful to test - the high-level protocol since spurious bytes should be ignored. - -``[,] rx-remove-byte`` - Remove the last byte from the received CEC message, provided it - was at least 2 bytes long. This is useful to test the high-level - protocol since messages that are too short should be ignored. - -``[,] rx-arb-lost `` - Generate a POLL message to trigger an Arbitration Lost condition. - This command is only allowed for ```` values of ``next`` or ``all``. - As soon as a start bit has been received the CEC adapter will switch - to transmit mode and it will transmit a POLL message. By default this is - 0x0f, but it can also be specified explicitly via the ```` argument. - - This command can be used to test the Arbitration Lost condition in - the remote CEC transmitter. Arbitration happens when two CEC adapters - start sending a message at the same time. In that case the initiator - with the most leading zeroes wins and the other transmitter has to - stop transmitting ('Arbitration Lost'). This is very hard to test, - except by using this error injection command. - - This does not work if the remote CEC transmitter has logical address - 0 ('TV') since that will always win. - -Transmit Messages ------------------ - -``tx-ignore-nack-until-eom`` - This setting changes the behavior of transmitting CEC messages. Normally - as soon as the receiver NACKs a byte the transmit will stop, but the - specification also allows that the full message is transmitted and only - at the end will the transmitter look at the ACK bit. This is not - recommended behavior since there is no point in keeping the CEC bus busy - for longer than is strictly needed. Especially given how slow the bus is. - - This setting can be used to test how well a receiver deals with - transmitters that ignore NACKs until the very end of the message. - -``[,] tx-no-eom`` - Don't set the EOM bit. Normally the last byte of the message has the EOM - (End-Of-Message) bit set. With this command the transmit will just stop - without ever sending an EOM. This can be used to test how a receiver - handles this case. Normally receivers have a time-out after which - they will go back to the Idle state. - -``[,] tx-early-eom`` - Set the EOM bit one byte too soon. This obviously only works for messages - of two bytes or more. The EOM bit will be set for the second-to-last byte - and not for the final byte. The receiver should ignore the last byte in - this case. Since the resulting message is likely to be too short for this - same reason the whole message is typically ignored. The receiver should be - in Idle state after the last byte was transmitted. - -``[,] tx-add-bytes `` - Append ```` (1-255) spurious bytes to the message. The extra bytes - have the value of the byte position in the message. So if you transmit a - two byte message (e.g. a Get CEC Version message) and add 2 bytes, then - the full message received by the remote CEC adapter is - ``0x40 0x9f 0x02 0x03``. - - This command can be used to test buffer overflows in the receiver. E.g. - what does it do when it receives more than the maximum message size of 16 - bytes. - -``[,] tx-remove-byte`` - Drop the last byte from the message, provided the message is at least - two bytes long. The receiver should ignore messages that are too short. - -``[,] tx-short-bit `` - Make this bit period shorter than allowed. The bit position cannot be - an Ack bit. If specifies a specific CEC opcode then the bit position - must be at least 18, otherwise the opcode hasn't been received yet. - Normally the period of a data bit is between 2.05 and 2.75 milliseconds. - With this command the period of this bit is 1.8 milliseconds, this is - done by reducing the time the CEC bus is high. This bit period is less - than is allowed and the receiver should respond with a Low Drive - condition. - - This command is ignored for 0 bits in bit positions 0 to 3. This is - because the receiver also looks for an Arbitration Lost condition in - those first four bits and it is undefined what will happen if it - sees a too-short 0 bit. - -``[,] tx-long-bit `` - Make this bit period longer than is valid. The bit position cannot be - an Ack bit. If specifies a specific CEC opcode then the bit position - must be at least 18, otherwise the opcode hasn't been received yet. - Normally the period of a data bit is between 2.05 and 2.75 milliseconds. - With this command the period of this bit is 2.9 milliseconds, this is - done by increasing the time the CEC bus is high. - - Even though this bit period is longer than is valid it is undefined what - a receiver will do. It might just accept it, or it might time out and - return to Idle state. Unfortunately the CEC specification is silent about - this. - - This command is ignored for 0 bits in bit positions 0 to 3. This is - because the receiver also looks for an Arbitration Lost condition in - those first four bits and it is undefined what will happen if it - sees a too-long 0 bit. - -``[,] tx-short-start`` - Make this start bit period shorter than allowed. Normally the period of - a start bit is between 4.3 and 4.7 milliseconds. With this command the - period of the start bit is 4.1 milliseconds, this is done by reducing - the time the CEC bus is high. This start bit period is less than is - allowed and the receiver should return to Idle state when this is detected. - -``[,] tx-long-start`` - Make this start bit period longer than is valid. Normally the period of - a start bit is between 4.3 and 4.7 milliseconds. With this command the - period of the start bit is 5 milliseconds, this is done by increasing - the time the CEC bus is high. This start bit period is more than is - valid and the receiver should return to Idle state when this is detected. - - Even though this start bit period is longer than is valid it is undefined - what a receiver will do. It might just accept it, or it might time out and - return to Idle state. Unfortunately the CEC specification is silent about - this. - -``[,] tx-last-bit `` - Just stop transmitting after this bit. If specifies a specific CEC - opcode then the bit position must be at least 18, otherwise the opcode - hasn't been received yet. This command can be used to test how the receiver - reacts when a message just suddenly stops. It should time out and go back - to Idle state. - -``[,] tx-low-drive `` - Force a Low Drive condition at this bit position. If specifies a - specific CEC opcode then the bit position must be at least 18, otherwise - the opcode hasn't been received yet. This can be used to test how the - receiver handles Low Drive conditions. Note that if this happens at bit - positions 0-3 the receiver can interpret this as an Arbitration Lost - condition. This is implementation dependent. - -Custom Pulses -------------- - -``tx-custom-low-usecs `` - This defines the duration in microseconds that the custom pulse pulls - the CEC line low. The default is 1000 microseconds. - -``tx-custom-high-usecs `` - This defines the duration in microseconds that the custom pulse keeps the - CEC line high (unless another CEC adapter pulls it low in that time). - The default is 1000 microseconds. The total period of the custom pulse is - ``tx-custom-low-usecs + tx-custom-high-usecs``. - -``[,] tx-custom-bit `` - Send the custom bit instead of a regular data bit. The bit position cannot - be an Ack bit. If specifies a specific CEC opcode then the bit - position must be at least 18, otherwise the opcode hasn't been received yet. - -``[,] tx-custom-start`` - Send the custom bit instead of a regular start bit. - -``tx-custom-pulse`` - Transmit a single custom pulse as soon as the CEC bus is idle. diff --git a/Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst b/Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst deleted file mode 100644 index ee2ee74dafa3..000000000000 --- a/Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_BILINGUAL_CHANNEL_SELECT: - -============================== -AUDIO_BILINGUAL_CHANNEL_SELECT -============================== - -Name ----- - -AUDIO_BILINGUAL_CHANNEL_SELECT - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_BILINGUAL_CHANNEL_SELECT, struct *audio_channel_select) - :name: AUDIO_BILINGUAL_CHANNEL_SELECT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - 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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-channel-select.rst b/Documentation/media/uapi/dvb/audio-channel-select.rst deleted file mode 100644 index ebb2f121c4c8..000000000000 --- a/Documentation/media/uapi/dvb/audio-channel-select.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_CHANNEL_SELECT: - -==================== -AUDIO_CHANNEL_SELECT -==================== - -Name ----- - -AUDIO_CHANNEL_SELECT - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_CHANNEL_SELECT, struct *audio_channel_select) - :name: AUDIO_CHANNEL_SELECT - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - audio_channel_select_t ch - - - Select the output format of the audio (mono left/right, stereo). - - -Description ------------ - -This ioctl is for Digital TV 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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-clear-buffer.rst b/Documentation/media/uapi/dvb/audio-clear-buffer.rst deleted file mode 100644 index c5b62cde18c8..000000000000 --- a/Documentation/media/uapi/dvb/audio-clear-buffer.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_CLEAR_BUFFER: - -================== -AUDIO_CLEAR_BUFFER -================== - -Name ----- - -AUDIO_CLEAR_BUFFER - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_CLEAR_BUFFER) - :name: 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(). - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-continue.rst b/Documentation/media/uapi/dvb/audio-continue.rst deleted file mode 100644 index 6bdc99e39e20..000000000000 --- a/Documentation/media/uapi/dvb/audio-continue.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_CONTINUE: - -============== -AUDIO_CONTINUE -============== - -Name ----- - -AUDIO_CONTINUE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_CONTINUE) - :name: AUDIO_CONTINUE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-fclose.rst b/Documentation/media/uapi/dvb/audio-fclose.rst deleted file mode 100644 index 1e4ad7a0325d..000000000000 --- a/Documentation/media/uapi/dvb/audio-fclose.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_fclose: - -======================== -Digital TV audio close() -======================== - -Name ----- - -Digital TV audio close() - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int close(int fd) - :name: dvb-audio-close - - -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. diff --git a/Documentation/media/uapi/dvb/audio-fopen.rst b/Documentation/media/uapi/dvb/audio-fopen.rst deleted file mode 100644 index 2cf4d83661f4..000000000000 --- a/Documentation/media/uapi/dvb/audio-fopen.rst +++ /dev/null @@ -1,115 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_fopen: - -======================= -Digital TV audio open() -======================= - -Name ----- - -Digital TV audio open() - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int open(const char *deviceName, int flags) - :name: dvb-audio-open - - -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 ------------- - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. 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. diff --git a/Documentation/media/uapi/dvb/audio-fwrite.rst b/Documentation/media/uapi/dvb/audio-fwrite.rst deleted file mode 100644 index 6dc6bf6cbbc7..000000000000 --- a/Documentation/media/uapi/dvb/audio-fwrite.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_fwrite: - -========================= -Digital TV audio write() -========================= - -Name ----- - -Digital TV audio write() - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: size_t write(int fd, const void *buf, size_t count) - :name: dvb-audio-write - - -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. diff --git a/Documentation/media/uapi/dvb/audio-get-capabilities.rst b/Documentation/media/uapi/dvb/audio-get-capabilities.rst deleted file mode 100644 index 4f1ec47e8ac2..000000000000 --- a/Documentation/media/uapi/dvb/audio-get-capabilities.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_GET_CAPABILITIES: - -====================== -AUDIO_GET_CAPABILITIES -====================== - -Name ----- - -AUDIO_GET_CAPABILITIES - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_GET_CAPABILITIES, unsigned int *cap) - :name: AUDIO_GET_CAPABILITIES - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - 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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-get-status.rst b/Documentation/media/uapi/dvb/audio-get-status.rst deleted file mode 100644 index 30e4dd7fce6d..000000000000 --- a/Documentation/media/uapi/dvb/audio-get-status.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_GET_STATUS: - -================ -AUDIO_GET_STATUS -================ - -Name ----- - -AUDIO_GET_STATUS - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_GET_STATUS, struct audio_status *status) - :name: AUDIO_GET_STATUS - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - 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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-pause.rst b/Documentation/media/uapi/dvb/audio-pause.rst deleted file mode 100644 index 4567ecd9e0a3..000000000000 --- a/Documentation/media/uapi/dvb/audio-pause.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_PAUSE: - -=========== -AUDIO_PAUSE -=========== - -Name ----- - -AUDIO_PAUSE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_PAUSE) - :name: AUDIO_PAUSE - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-play.rst b/Documentation/media/uapi/dvb/audio-play.rst deleted file mode 100644 index 17acd4c411b8..000000000000 --- a/Documentation/media/uapi/dvb/audio-play.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_PLAY: - -========== -AUDIO_PLAY -========== - -Name ----- - -AUDIO_PLAY - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_PLAY) - :name: AUDIO_PLAY - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-select-source.rst b/Documentation/media/uapi/dvb/audio-select-source.rst deleted file mode 100644 index c5ed6243b11c..000000000000 --- a/Documentation/media/uapi/dvb/audio-select-source.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SELECT_SOURCE: - -=================== -AUDIO_SELECT_SOURCE -=================== - -Name ----- - -AUDIO_SELECT_SOURCE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SELECT_SOURCE, struct audio_stream_source *source) - :name: AUDIO_SELECT_SOURCE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - 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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-av-sync.rst b/Documentation/media/uapi/dvb/audio-set-av-sync.rst deleted file mode 100644 index c116d105fdea..000000000000 --- a/Documentation/media/uapi/dvb/audio-set-av-sync.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_AV_SYNC: - -================= -AUDIO_SET_AV_SYNC -================= - -Name ----- - -AUDIO_SET_AV_SYNC - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_AV_SYNC, boolean state) - :name: AUDIO_SET_AV_SYNC - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - boolean state - - - Tells the Digital TV subsystem if A/V synchronization shall be ON or OFF. - - TRUE: AV-sync ON - - 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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst b/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst deleted file mode 100644 index d68f05d48d12..000000000000 --- a/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_BYPASS_MODE: - -===================== -AUDIO_SET_BYPASS_MODE -===================== - -Name ----- - -AUDIO_SET_BYPASS_MODE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_BYPASS_MODE, boolean mode) - :name: AUDIO_SET_BYPASS_MODE - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - boolean mode - - - Enables or disables the decoding of the current Audio stream in - the Digital TV subsystem. - - TRUE: Bypass is disabled - - 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 Digital TV system shall be decoded. Dolby -DigitalTM streams are automatically forwarded by the Digital TV 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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-id.rst b/Documentation/media/uapi/dvb/audio-set-id.rst deleted file mode 100644 index aeb6ace6cd1e..000000000000 --- a/Documentation/media/uapi/dvb/audio-set-id.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_ID: - -============ -AUDIO_SET_ID -============ - -Name ----- - -AUDIO_SET_ID - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_ID, int id) - :name: AUDIO_SET_ID - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - 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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-mixer.rst b/Documentation/media/uapi/dvb/audio-set-mixer.rst deleted file mode 100644 index 60781aa88202..000000000000 --- a/Documentation/media/uapi/dvb/audio-set-mixer.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_MIXER: - -=============== -AUDIO_SET_MIXER -=============== - -Name ----- - -AUDIO_SET_MIXER - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_MIXER, struct audio_mixer *mix) - :name: AUDIO_SET_MIXER - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - 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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-mute.rst b/Documentation/media/uapi/dvb/audio-set-mute.rst deleted file mode 100644 index 4449f225e48c..000000000000 --- a/Documentation/media/uapi/dvb/audio-set-mute.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_MUTE: - -============== -AUDIO_SET_MUTE -============== - -Name ----- - -AUDIO_SET_MUTE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_SET_MUTE, boolean state) - :name: AUDIO_SET_MUTE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - boolean state - - - Indicates if audio device shall mute or not. - - TRUE: Audio Mute - - FALSE: Audio Un-mute - - -Description ------------ - -This ioctl is for Digital TV 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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-streamtype.rst b/Documentation/media/uapi/dvb/audio-set-streamtype.rst deleted file mode 100644 index d20c34fc7128..000000000000 --- a/Documentation/media/uapi/dvb/audio-set-streamtype.rst +++ /dev/null @@ -1,77 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_SET_STREAMTYPE: - -==================== -AUDIO_SET_STREAMTYPE -==================== - -Name ----- - -AUDIO_SET_STREAMTYPE - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(fd, AUDIO_SET_STREAMTYPE, int type) - :name: AUDIO_SET_STREAMTYPE - - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - - - - int fd - - - File descriptor returned by a previous call to open(). - - - - - - int type - - - stream type - - -Description ------------ - -This ioctl tells the driver which kind of audio stream to expect. This -is useful if the stream offers several audio sub-streams like LPCM and -AC3. - - -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 ` chapter. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EINVAL`` - - - type is not a valid or supported stream type. diff --git a/Documentation/media/uapi/dvb/audio-stop.rst b/Documentation/media/uapi/dvb/audio-stop.rst deleted file mode 100644 index 1bba2e50c364..000000000000 --- a/Documentation/media/uapi/dvb/audio-stop.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _AUDIO_STOP: - -========== -AUDIO_STOP -========== - -Name ----- - -AUDIO_STOP - -.. attention:: This ioctl is deprecated - -Synopsis --------- - -.. c:function:: int ioctl(int fd, AUDIO_STOP) - :name: AUDIO_STOP - -Arguments ---------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - int fd - - - File descriptor returned by a previous call to open(). - - -Description ------------ - -This ioctl call asks the Audio Device to stop playing the current -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/audio.rst b/Documentation/media/uapi/dvb/audio.rst deleted file mode 100644 index ebc18fca76a4..000000000000 --- a/Documentation/media/uapi/dvb/audio.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_audio: - -####################### -Digital TV Audio Device -####################### - -The Digital TV audio device controls the MPEG2 audio decoder of the Digital -TV hardware. It can be accessed through ``/dev/dvb/adapter?/audio?``. Data -types and and ioctl definitions can be accessed by including -``linux/dvb/audio.h`` in your application. - -Please note that some Digital TV cards don’t have their own MPEG decoder, which -results in the omission of the audio and video device. - -These ioctls were also used by V4L2 to control MPEG decoders implemented -in V4L2. The use of these ioctls for that purpose has been made obsolete -and proper V4L2 ioctls or controls have been created to replace that -functionality. - - -.. toctree:: - :maxdepth: 1 - - audio_data_types - audio_function_calls diff --git a/Documentation/media/uapi/dvb/audio_data_types.rst b/Documentation/media/uapi/dvb/audio_data_types.rst deleted file mode 100644 index 5b032fe13b9d..000000000000 --- a/Documentation/media/uapi/dvb/audio_data_types.rst +++ /dev/null @@ -1,123 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_data_types: - -**************** -Audio Data Types -**************** - -This section describes the structures, data types and defines used when -talking to the audio device. - -.. c:type:: audio_stream_source - -The audio stream source is set through the AUDIO_SELECT_SOURCE call -and can take the following values, depending on whether we are replaying -from an internal (demux) or external (user write) source. - - -.. code-block:: c - - typedef enum { - AUDIO_SOURCE_DEMUX, - AUDIO_SOURCE_MEMORY - } audio_stream_source_t; - -AUDIO_SOURCE_DEMUX selects the demultiplexer (fed either by the -frontend or the DVR device) as the source of the video stream. If -AUDIO_SOURCE_MEMORY is selected the stream comes from the application -through the ``write()`` system call. - - -.. c:type:: audio_play_state - -The following values can be returned by the AUDIO_GET_STATUS call -representing the state of audio playback. - - -.. code-block:: c - - typedef enum { - AUDIO_STOPPED, - AUDIO_PLAYING, - AUDIO_PAUSED - } audio_play_state_t; - - -.. c:type:: audio_channel_select - -The audio channel selected via AUDIO_CHANNEL_SELECT is determined by -the following values. - - -.. code-block:: c - - typedef enum { - AUDIO_STEREO, - AUDIO_MONO_LEFT, - AUDIO_MONO_RIGHT, - AUDIO_MONO, - AUDIO_STEREO_SWAPPED - } audio_channel_select_t; - - -.. c:type:: audio_status - -The AUDIO_GET_STATUS call returns the following structure informing -about various states of the playback operation. - - -.. code-block:: c - - typedef struct audio_status { - boolean AV_sync_state; - boolean mute_state; - audio_play_state_t play_state; - audio_stream_source_t stream_source; - audio_channel_select_t channel_select; - boolean bypass_mode; - audio_mixer_t mixer_state; - } audio_status_t; - - -.. c:type:: audio_mixer - -The following structure is used by the AUDIO_SET_MIXER call to set the -audio volume. - - -.. code-block:: c - - typedef struct audio_mixer { - unsigned int volume_left; - unsigned int volume_right; - } audio_mixer_t; - - -.. _audio_encodings: - -audio encodings -=============== - -A call to AUDIO_GET_CAPABILITIES returns an unsigned integer with the -following bits set according to the hardwares capabilities. - - -.. code-block:: c - - #define AUDIO_CAP_DTS 1 - #define AUDIO_CAP_LPCM 2 - #define AUDIO_CAP_MP1 4 - #define AUDIO_CAP_MP2 8 - #define AUDIO_CAP_MP3 16 - #define AUDIO_CAP_AAC 32 - #define AUDIO_CAP_OGG 64 - #define AUDIO_CAP_SDDS 128 - #define AUDIO_CAP_AC3 256 diff --git a/Documentation/media/uapi/dvb/audio_function_calls.rst b/Documentation/media/uapi/dvb/audio_function_calls.rst deleted file mode 100644 index 5478e78b085e..000000000000 --- a/Documentation/media/uapi/dvb/audio_function_calls.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio_function_calls: - -******************** -Audio Function Calls -******************** - -.. toctree:: - :maxdepth: 1 - - audio-fopen - audio-fclose - audio-fwrite - audio-stop - audio-play - audio-pause - audio-continue - audio-select-source - audio-set-mute - audio-set-av-sync - audio-set-bypass-mode - audio-channel-select - audio-bilingual-channel-select - audio-get-status - audio-get-capabilities - audio-clear-buffer - audio-set-id - audio-set-mixer - audio-set-streamtype diff --git a/Documentation/media/uapi/dvb/ca-fclose.rst b/Documentation/media/uapi/dvb/ca-fclose.rst deleted file mode 100644 index e273444ccc67..000000000000 --- a/Documentation/media/uapi/dvb/ca-fclose.rst +++ /dev/null @@ -1,50 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _ca_fclose: - -===================== -Digital TV CA close() -===================== - -Name ----- - -Digital TV CA close() - - -Synopsis --------- - -.. c:function:: int close(int fd) - :name: dvb-ca-close - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -Description ------------ - -This system call closes a previously opened CA device. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-fopen.rst b/Documentation/media/uapi/dvb/ca-fopen.rst deleted file mode 100644 index e11ebeae5693..000000000000 --- a/Documentation/media/uapi/dvb/ca-fopen.rst +++ /dev/null @@ -1,84 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _ca_fopen: - -==================== -Digital TV CA open() -==================== - -Name ----- - -Digital TV CA open() - - -Synopsis --------- - -.. c:function:: int open(const char *name, int flags) - :name: dvb-ca-open - - -Arguments ---------- - -``name`` - Name of specific Digital TV CA device. - -``flags`` - A bit-wise OR of the following flags: - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - ``O_RDONLY`` - - read-only access - - - - ``O_RDWR`` - - read/write access - - - - ``O_NONBLOCK`` - - open in non-blocking mode - (blocking mode is the default) - - -Description ------------ - -This system call opens a named ca device (e.g. ``/dev/dvb/adapter?/ca?``) -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 CA Device in ``O_RDWR`` mode. All other -attempts to open the device in this mode will fail, and an error code -will be returned. - - -Return Value ------------- - - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-get-cap.rst b/Documentation/media/uapi/dvb/ca-get-cap.rst deleted file mode 100644 index 9e4fb5186373..000000000000 --- a/Documentation/media/uapi/dvb/ca-get-cap.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_GET_CAP: - -========== -CA_GET_CAP -========== - -Name ----- - -CA_GET_CAP - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_GET_CAP, struct ca_caps *caps) - :name: CA_GET_CAP - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``caps`` - Pointer to struct :c:type:`ca_caps`. - -Description ------------ - -Queries the Kernel for information about the available CA and descrambler -slots, and their types. - -Return Value ------------- - -On success 0 is returned and :c:type:`ca_caps` is filled. - -On error, -1 is returned and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-get-descr-info.rst b/Documentation/media/uapi/dvb/ca-get-descr-info.rst deleted file mode 100644 index 80ef43a339df..000000000000 --- a/Documentation/media/uapi/dvb/ca-get-descr-info.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_GET_DESCR_INFO: - -================= -CA_GET_DESCR_INFO -================= - -Name ----- - -CA_GET_DESCR_INFO - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_GET_DESCR_INFO, struct ca_descr_info *desc) - :name: CA_GET_DESCR_INFO - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``desc`` - Pointer to struct :c:type:`ca_descr_info`. - -Description ------------ - -Returns information about all descrambler slots. - -Return Value ------------- - -On success 0 is returned, and :c:type:`ca_descr_info` is filled. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-get-msg.rst b/Documentation/media/uapi/dvb/ca-get-msg.rst deleted file mode 100644 index bcb7955a0ddc..000000000000 --- a/Documentation/media/uapi/dvb/ca-get-msg.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_GET_MSG: - -========== -CA_GET_MSG -========== - -Name ----- - -CA_GET_MSG - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_GET_MSG, struct ca_msg *msg) - :name: CA_GET_MSG - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``msg`` - Pointer to struct :c:type:`ca_msg`. - -Description ------------ - -Receives a message via a CI CA module. - -.. note:: - - Please notice that, on most drivers, this is done by reading from - the /dev/adapter?/ca? device node. - - -Return Value ------------- - - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-get-slot-info.rst b/Documentation/media/uapi/dvb/ca-get-slot-info.rst deleted file mode 100644 index 1ea5c497f2ea..000000000000 --- a/Documentation/media/uapi/dvb/ca-get-slot-info.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_GET_SLOT_INFO: - -================ -CA_GET_SLOT_INFO -================ - -Name ----- - -CA_GET_SLOT_INFO - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_GET_SLOT_INFO, struct ca_slot_info *info) - :name: CA_GET_SLOT_INFO - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``info`` - Pointer to struct :c:type:`ca_slot_info`. - -Description ------------ - -Returns information about a CA slot identified by -:c:type:`ca_slot_info`.slot_num. - - -Return Value ------------- - -On success 0 is returned, and :c:type:`ca_slot_info` is filled. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - ``ENODEV`` - - the slot is not available. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-reset.rst b/Documentation/media/uapi/dvb/ca-reset.rst deleted file mode 100644 index 29fda19984be..000000000000 --- a/Documentation/media/uapi/dvb/ca-reset.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_RESET: - -======== -CA_RESET -======== - -Name ----- - -CA_RESET - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_RESET) - :name: CA_RESET - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -Description ------------ - -Puts the Conditional Access hardware on its initial state. It should -be called before start using the CA hardware. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-send-msg.rst b/Documentation/media/uapi/dvb/ca-send-msg.rst deleted file mode 100644 index 5a3c4e8120c4..000000000000 --- a/Documentation/media/uapi/dvb/ca-send-msg.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_SEND_MSG: - -=========== -CA_SEND_MSG -=========== - -Name ----- - -CA_SEND_MSG - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_SEND_MSG, struct ca_msg *msg) - :name: CA_SEND_MSG - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``msg`` - Pointer to struct :c:type:`ca_msg`. - - -Description ------------ - -Sends a message via a CI CA module. - -.. note:: - - Please notice that, on most drivers, this is done by writing - to the /dev/adapter?/ca? device node. - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca-set-descr.rst b/Documentation/media/uapi/dvb/ca-set-descr.rst deleted file mode 100644 index d36464ba2317..000000000000 --- a/Documentation/media/uapi/dvb/ca-set-descr.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _CA_SET_DESCR: - -============ -CA_SET_DESCR -============ - -Name ----- - -CA_SET_DESCR - - -Synopsis --------- - -.. c:function:: int ioctl(fd, CA_SET_DESCR, struct ca_descr *desc) - :name: CA_SET_DESCR - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``msg`` - Pointer to struct :c:type:`ca_descr`. - -Description ------------ - -CA_SET_DESCR is used for feeding descrambler CA slots with descrambling -keys (referred as control words). - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/ca.rst b/Documentation/media/uapi/dvb/ca.rst deleted file mode 100644 index c6ee624b1234..000000000000 --- a/Documentation/media/uapi/dvb/ca.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_ca: - -#################### -Digital TV CA Device -#################### - -The Digital TV CA device controls the conditional access hardware. It -can be accessed through ``/dev/dvb/adapter?/ca?``. Data types and and ioctl -definitions can be accessed by including ``linux/dvb/ca.h`` in your -application. - -.. note:: - - There are three ioctls at this API that aren't documented: - :ref:`CA_GET_MSG`, :ref:`CA_SEND_MSG` and :ref:`CA_SET_DESCR`. - Documentation for them are welcome. - -.. toctree:: - :maxdepth: 1 - - ca_data_types - ca_function_calls - ca_high_level diff --git a/Documentation/media/uapi/dvb/ca_data_types.rst b/Documentation/media/uapi/dvb/ca_data_types.rst deleted file mode 100644 index 834c8ab4c300..000000000000 --- a/Documentation/media/uapi/dvb/ca_data_types.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _ca_data_types: - -************* -CA Data Types -************* - -.. kernel-doc:: include/uapi/linux/dvb/ca.h diff --git a/Documentation/media/uapi/dvb/ca_function_calls.rst b/Documentation/media/uapi/dvb/ca_function_calls.rst deleted file mode 100644 index 6985bebd0661..000000000000 --- a/Documentation/media/uapi/dvb/ca_function_calls.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _ca_function_calls: - -***************** -CA Function Calls -***************** - -.. toctree:: - :maxdepth: 1 - - ca-fopen - ca-fclose - ca-reset - ca-get-cap - ca-get-slot-info - ca-get-descr-info - ca-get-msg - ca-send-msg - ca-set-descr diff --git a/Documentation/media/uapi/dvb/ca_high_level.rst b/Documentation/media/uapi/dvb/ca_high_level.rst deleted file mode 100644 index a73f3691c31f..000000000000 --- a/Documentation/media/uapi/dvb/ca_high_level.rst +++ /dev/null @@ -1,157 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -The High level CI API -===================== - -.. note:: - - This documentation is outdated. - -This document describes the high level CI API as in accordance to the -Linux DVB API. - - -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 -eliminating the need for any additional ioctls. - -The disadvantage is that the driver/hardware has to manage the rest. For -the application programmer it would be as simple as sending/receiving an -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? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -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: - -.. code-block:: c - - 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. - -This CI interface is quite different in the case that it tries to -accommodate all other CI based devices, that fall into the other categories. - -This means that this CI interface handles the EN50221 style tags in the -Application layer only and no session management is taken care of by the -application. The driver/hardware will take care of all that. - -This interface is purely an EN50221 interface exchanging APDU's. This -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. - -All these ioctls are also valid for the High level CI interface - -#define CA_RESET _IO('o', 128) -#define CA_GET_CAP _IOR('o', 129, ca_caps_t) -#define CA_GET_SLOT_INFO _IOR('o', 130, ca_slot_info_t) -#define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t) -#define CA_GET_MSG _IOR('o', 132, ca_msg_t) -#define CA_SEND_MSG _IOW('o', 133, ca_msg_t) -#define CA_SET_DESCR _IOW('o', 134, ca_descr_t) - - -On querying the device, the device yields information thus: - -.. code-block:: none - - 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_GET_CAP - ---------------------------- - Command = [caps] - APP: Slots=[1] - APP: Type=[1] - APP: Descrambler keys=[16] - APP: Type=[1] - - 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 -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; - - -The flow of data can be described thus, - -.. code-block:: none - - App (User) - ----- - parse - | - | - v - en50221 APDU (package) - -------------------------------------- - | | | High Level CI driver - | | | - | v | - | en50221 APDU (unpackage) | - | | | - | | | - | v | - | sanity checks | - | | | - | | | - | v | - | do (H/W dep) | - -------------------------------------- - | Hardware - | - v - -The High Level CI interface uses the EN50221 DVB standard, following a -standard ensures futureproofness. diff --git a/Documentation/media/uapi/dvb/demux.rst b/Documentation/media/uapi/dvb/demux.rst deleted file mode 100644 index d8c0ff4015fe..000000000000 --- a/Documentation/media/uapi/dvb/demux.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_demux: - -####################### -Digital TV Demux Device -####################### - -The Digital TV demux device controls the MPEG-TS filters for the -digital TV. If the driver and hardware supports, those filters are -implemented at the hardware. Otherwise, the Kernel provides a software -emulation. - -It can be accessed through ``/dev/adapter?/demux?``. Data types and and -ioctl definitions can be accessed by including ``linux/dvb/dmx.h`` in -your application. - - -.. toctree:: - :maxdepth: 1 - - dmx_types - dmx_fcalls diff --git a/Documentation/media/uapi/dvb/dmx-add-pid.rst b/Documentation/media/uapi/dvb/dmx-add-pid.rst deleted file mode 100644 index f483268e4ede..000000000000 --- a/Documentation/media/uapi/dvb/dmx-add-pid.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_ADD_PID: - -=========== -DMX_ADD_PID -=========== - -Name ----- - -DMX_ADD_PID - - -Synopsis --------- - -.. c:function:: int ioctl(fd, DMX_ADD_PID, __u16 *pid) - :name: DMX_ADD_PID - - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -``pid`` - PID number to be filtered. - - -Description ------------ - -This ioctl call allows to add multiple PIDs to a transport stream filter -previously set up with :ref:`DMX_SET_PES_FILTER` and output equal to -:c:type:`DMX_OUT_TSDEMUX_TAP `. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-expbuf.rst b/Documentation/media/uapi/dvb/dmx-expbuf.rst deleted file mode 100644 index d7f0658f3db3..000000000000 --- a/Documentation/media/uapi/dvb/dmx-expbuf.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_EXPBUF: - -**************** -ioctl DMX_EXPBUF -**************** - -Name -==== - -DMX_EXPBUF - Export a buffer as a DMABUF file descriptor. - -.. warning:: this API is still experimental - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp ) - :name: DMX_EXPBUF - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`dmx_exportbuffer`. - - -Description -=========== - -This ioctl is an extension to the memory mapping I/O method. -It can be used to export a buffer as a DMABUF file at any time after -buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl. - -To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`. -Applications must set the ``index`` field. Valid index numbers -range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS` -(struct :c:type:`dmx_requestbuffers` ``count``) minus one. -Additional flags may be posted in the ``flags`` field. Refer to a manual -for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, -and O_RDWR are supported. -All other fields must be set to zero. In the -case of multi-planar API, every plane is exported separately using -multiple :ref:`DMX_EXPBUF` calls. - -After calling :ref:`DMX_EXPBUF` the ``fd`` field will be set by a -driver, on success. This is a DMABUF file descriptor. The application may -pass it to other DMABUF-aware devices. It is recommended to close a DMABUF -file when it is no longer used to allow the associated memory to be reclaimed. - - -Examples -======== - - -.. code-block:: c - - int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd) - { - struct dmx_exportbuffer expbuf; - - memset(&expbuf, 0, sizeof(expbuf)); - expbuf.type = bt; - expbuf.index = index; - if (ioctl(v4lfd, DMX_EXPBUF, &expbuf) == -1) { - perror("DMX_EXPBUF"); - return -1; - } - - *dmafd = expbuf.fd; - - return 0; - } - -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 ` chapter. - -EINVAL - A queue is not in MMAP mode or DMABUF exporting is not supported or - ``flags`` or ``index`` fields are invalid. diff --git a/Documentation/media/uapi/dvb/dmx-fclose.rst b/Documentation/media/uapi/dvb/dmx-fclose.rst deleted file mode 100644 index 05ff32270274..000000000000 --- a/Documentation/media/uapi/dvb/dmx-fclose.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx_fclose: - -======================== -Digital TV demux close() -======================== - -Name ----- - -Digital TV demux close() - - -Synopsis --------- - -.. c:function:: int close(int fd) - :name: dvb-dmx-close - - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to - :c:func:`open() `. - -Description ------------ - -This system call deactivates and deallocates a filter that was -previously allocated via the :c:func:`open() ` call. - - -Return Value ------------- - -On success 0 is returned. - -On error, -1 is returned and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-fopen.rst b/Documentation/media/uapi/dvb/dmx-fopen.rst deleted file mode 100644 index 2700a2fad68b..000000000000 --- a/Documentation/media/uapi/dvb/dmx-fopen.rst +++ /dev/null @@ -1,98 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx_fopen: - -======================= -Digital TV demux open() -======================= - -Name ----- - -Digital TV demux open() - - -Synopsis --------- - -.. c:function:: int open(const char *deviceName, int flags) - :name: dvb-dmx-open - -Arguments ---------- - -``name`` - Name of specific Digital TV demux device. - -``flags`` - A bit-wise OR of the following flags: - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - - ``O_RDONLY`` - - read-only access - - - - - ``O_RDWR`` - - read/write access - - - - - ``O_NONBLOCK`` - - open in non-blocking mode - (blocking mode is the default) - - -Description ------------ - -This system call, used with a device name of ``/dev/dvb/adapter?/demux?``, -allocates a new filter and returns a handle which can be used for -subsequent control of that filter. This call has to be made for each -filter to be used, i.e. every returned file descriptor is a reference to -a single filter. ``/dev/dvb/adapter?/dvr?`` is a logical device to be used -for retrieving Transport Streams for digital video recording. When -reading from this device a transport stream containing the packets from -all PES filters set in the corresponding demux device -(``/dev/dvb/adapter?/demux?``) having the output set to ``DMX_OUT_TS_TAP``. -A recorded Transport Stream is replayed by writing to this device. - -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. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - ``EMFILE`` - - “Too many open files”, i.e. no more filters available. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-fread.rst b/Documentation/media/uapi/dvb/dmx-fread.rst deleted file mode 100644 index 292fa98f39ff..000000000000 --- a/Documentation/media/uapi/dvb/dmx-fread.rst +++ /dev/null @@ -1,87 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx_fread: - -======================= -Digital TV demux read() -======================= - -Name ----- - -Digital TV demux read() - - -Synopsis --------- - -.. c:function:: size_t read(int fd, void *buf, size_t count) - :name: dvb-dmx-read - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - - ``buf`` - Buffer to be filled - -``count`` - Max number of bytes to read - -Description ------------ - -This system call returns filtered data, which might be section or Packetized -Elementary Stream (PES) data. The filtered data is transferred from -the driver’s internal circular buffer to ``buf``. The maximum amount of data -to be transferred is implied by count. - -.. note:: - - if a section filter created with - :c:type:`DMX_CHECK_CRC ` flag set, - data that fails on CRC check will be silently ignored. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - ``EWOULDBLOCK`` - - No data to return and ``O_NONBLOCK`` was specified. - - - - ``EOVERFLOW`` - - The filtered data was not read from the buffer in due time, - resulting in non-read data being lost. The buffer is flushed. - - - - ``ETIMEDOUT`` - - The section was not loaded within the stated timeout period. - See ioctl :ref:`DMX_SET_FILTER` for how to set a timeout. - - - - ``EFAULT`` - - The driver failed to write to the callers buffer due to an - invalid \*buf pointer. - - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-fwrite.rst b/Documentation/media/uapi/dvb/dmx-fwrite.rst deleted file mode 100644 index bdd4d4743bd5..000000000000 --- a/Documentation/media/uapi/dvb/dmx-fwrite.rst +++ /dev/null @@ -1,79 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx_fwrite: - -======================== -Digital TV demux write() -======================== - -Name ----- - -Digital TV demux write() - - -Synopsis --------- - -.. c:function:: ssize_t write(int fd, const void *buf, size_t count) - :name: dvb-dmx-write - -Arguments ---------- - -``fd`` - File descriptor returned by a previous call to :c:func:`open() `. - -``buf`` - Buffer with data to be written - -``count`` - Number of bytes at the buffer - -Description ------------ - -This system call is only provided by the logical device -``/dev/dvb/adapter?/dvr?``, associated with the physical demux device that -provides the actual DVR functionality. It is used for replay of a -digitally recorded Transport Stream. Matching filters have to be defined -in the corresponding physical demux device, ``/dev/dvb/adapter?/demux?``. -The amount of data to be transferred is implied by count. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - ``EWOULDBLOCK`` - - No data was written. This might happen if ``O_NONBLOCK`` was - specified and there is no more buffer space available (if - ``O_NONBLOCK`` is not specified the function will block until buffer - space is available). - - - - ``EBUSY`` - - This error code indicates that there are conflicting requests. The - corresponding demux device is setup to receive data from the - front- end. Make sure that these filters are stopped and that the - filters with input set to ``DMX_IN_DVR`` are started. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-get-pes-pids.rst b/Documentation/media/uapi/dvb/dmx-get-pes-pids.rst deleted file mode 100644 index fcd3dc06c095..000000000000 --- a/Documentation/media/uapi/dvb/dmx-get-pes-pids.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_GET_PES_PIDS: - -================ -DMX_GET_PES_PIDS -================ - -Name ----- - -DMX_GET_PES_PIDS - - -Synopsis --------- - -.. c:function:: int ioctl(fd, DMX_GET_PES_PIDS, __u16 pids[5]) - :name: DMX_GET_PES_PIDS - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -``pids`` - Array used to store 5 Program IDs. - - -Description ------------ - -This ioctl allows to query a DVB device to return the first PID used -by audio, video, textext, subtitle and PCR programs on a given service. -They're stored as: - -======================= ======== ======================================= -PID element position content -======================= ======== ======================================= -pids[DMX_PES_AUDIO] 0 first audio PID -pids[DMX_PES_VIDEO] 1 first video PID -pids[DMX_PES_TELETEXT] 2 first teletext PID -pids[DMX_PES_SUBTITLE] 3 first subtitle PID -pids[DMX_PES_PCR] 4 first Program Clock Reference PID -======================= ======== ======================================= - - -.. note:: - - A value equal to 0xffff means that the PID was not filled by the - Kernel. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-get-stc.rst b/Documentation/media/uapi/dvb/dmx-get-stc.rst deleted file mode 100644 index 2c81595f470a..000000000000 --- a/Documentation/media/uapi/dvb/dmx-get-stc.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_GET_STC: - -=========== -DMX_GET_STC -=========== - -Name ----- - -DMX_GET_STC - - -Synopsis --------- - -.. c:function:: int ioctl( int fd, DMX_GET_STC, struct dmx_stc *stc) - :name: DMX_GET_STC - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -``stc`` - Pointer to :c:type:`dmx_stc` where the stc data is to be stored. - - -Description ------------ - -This ioctl call returns the current value of the system time counter -(which is driven by a PES filter of type :c:type:`DMX_PES_PCR `). -Some hardware supports more than one STC, so you must specify which one by -setting the :c:type:`num ` field of stc before the ioctl (range 0...n). -The result is returned in form of a ratio with a 64 bit numerator -and a 32 bit denominator, so the real 90kHz STC value is -``stc->stc / stc->base``. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - .. row 1 - - - ``EINVAL`` - - - Invalid stc number. - - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-mmap.rst b/Documentation/media/uapi/dvb/dmx-mmap.rst deleted file mode 100644 index 34bb7766718f..000000000000 --- a/Documentation/media/uapi/dvb/dmx-mmap.rst +++ /dev/null @@ -1,125 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx-mmap: - -***************** -Digital TV mmap() -***************** - -Name -==== - -dmx-mmap - Map device memory into application address space - -.. warning:: this API is still experimental - -Synopsis -======== - -.. code-block:: c - - #include - #include - - -.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) - :name: dmx-mmap - -Arguments -========= - -``start`` - Map the buffer to this address in the application's address space. - When the ``MAP_FIXED`` flag is specified, ``start`` must be a - multiple of the pagesize and mmap will fail when the specified - address cannot be used. Use of this option is discouraged; - applications should just specify a ``NULL`` pointer here. - -``length`` - Length of the memory area to map. This must be a multiple of the - DVB packet length (188, on most drivers). - -``prot`` - The ``prot`` argument describes the desired memory protection. - Regardless of the device type and the direction of data exchange it - should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read - and write access to image buffers. Drivers should support at least - this combination of flags. - -``flags`` - The ``flags`` parameter specifies the type of the mapped object, - mapping options and whether modifications made to the mapped copy of - the page are private to the process or are to be shared with other - references. - - ``MAP_FIXED`` requests that the driver selects no other address than - the one specified. If the specified address cannot be used, - :ref:`mmap() ` will fail. If ``MAP_FIXED`` is specified, - ``start`` must be a multiple of the pagesize. Use of this option is - discouraged. - - One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set. - ``MAP_SHARED`` allows applications to share the mapped memory with - other (e. g. child-) processes. - - .. note:: - - The Linux Digital TV applications should not set the - ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` - flags. - -``fd`` - File descriptor returned by :ref:`open() `. - -``offset`` - Offset of the buffer in device memory, as returned by - :ref:`DMX_QUERYBUF` ioctl. - - -Description -=========== - -The :ref:`mmap() ` function asks to map ``length`` bytes starting at -``offset`` in the memory of the device specified by ``fd`` into the -application address space, preferably at address ``start``. This latter -address is a hint only, and is usually specified as 0. - -Suitable length and offset parameters are queried with the -:ref:`DMX_QUERYBUF` ioctl. Buffers must be allocated with the -:ref:`DMX_REQBUFS` ioctl before they can be queried. - -To unmap buffers the :ref:`munmap() ` function is used. - - -Return Value -============ - -On success :ref:`mmap() ` returns a pointer to the mapped buffer. On -error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set -appropriately. Possible error codes are: - -EBADF - ``fd`` is not a valid file descriptor. - -EACCES - ``fd`` is not open for reading and writing. - -EINVAL - The ``start`` or ``length`` or ``offset`` are not suitable. (E. g. - they are too large, or not aligned on a ``PAGESIZE`` boundary.) - - The ``flags`` or ``prot`` value is not supported. - - No buffers have been allocated with the - :ref:`DMX_REQBUFS` ioctl. - -ENOMEM - Not enough physical or virtual memory was available to complete the - request. diff --git a/Documentation/media/uapi/dvb/dmx-munmap.rst b/Documentation/media/uapi/dvb/dmx-munmap.rst deleted file mode 100644 index ef26b6f2b12b..000000000000 --- a/Documentation/media/uapi/dvb/dmx-munmap.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx-munmap: - -************ -DVB munmap() -************ - -Name -==== - -dmx-munmap - Unmap device memory - -.. warning:: This API is still experimental. - - -Synopsis -======== - -.. code-block:: c - - #include - #include - - -.. c:function:: int munmap( void *start, size_t length ) - :name: dmx-munmap - -Arguments -========= - -``start`` - Address of the mapped buffer as returned by the - :ref:`mmap() ` function. - -``length`` - Length of the mapped buffer. This must be the same value as given to - :ref:`mmap() `. - - -Description -=========== - -Unmaps a previously with the :ref:`mmap() ` function mapped -buffer and frees it, if possible. - - -Return Value -============ - -On success :ref:`munmap() ` returns 0, on failure -1 and the -``errno`` variable is set appropriately: - -EINVAL - The ``start`` or ``length`` is incorrect, or no buffers have been - mapped yet. diff --git a/Documentation/media/uapi/dvb/dmx-qbuf.rst b/Documentation/media/uapi/dvb/dmx-qbuf.rst deleted file mode 100644 index 9dc845daa59d..000000000000 --- a/Documentation/media/uapi/dvb/dmx-qbuf.rst +++ /dev/null @@ -1,93 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_QBUF: - -************************* -ioctl DMX_QBUF, DMX_DQBUF -************************* - -Name -==== - -DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver - -.. warning:: this API is still experimental - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, DMX_QBUF, struct dmx_buffer *argp ) - :name: DMX_QBUF - -.. c:function:: int ioctl( int fd, DMX_DQBUF, struct dmx_buffer *argp ) - :name: DMX_DQBUF - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`dmx_buffer`. - - -Description -=========== - -Applications call the ``DMX_QBUF`` ioctl to enqueue an empty -(capturing) or filled (output) buffer in the driver's incoming queue. -The semantics depend on the selected I/O method. - -To enqueue a buffer applications set the ``index`` field. Valid index -numbers range from zero to the number of buffers allocated with -:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus -one. The contents of the struct :c:type:`dmx_buffer` returned -by a :ref:`DMX_QUERYBUF` ioctl will do as well. - -When ``DMX_QBUF`` is called with a pointer to this structure, it locks the -memory pages of the buffer in physical memory, so they cannot be swapped -out to disk. Buffers remain locked until dequeued, until the -the device is closed. - -Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled -(capturing) buffer from the driver's outgoing queue. -They just set the ``index`` field with the buffer ID to be queued. -When ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`, -the driver fills the remaining fields or returns an error code. - -By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing -queue. When the ``O_NONBLOCK`` flag was given to the -:ref:`open() ` function, ``DMX_DQBUF`` returns -immediately with an ``EAGAIN`` error code when no buffer is available. - -The struct :c:type:`dmx_buffer` structure is specified in -:ref:`buffer`. - - -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 ` chapter. - -EAGAIN - Non-blocking I/O has been selected using ``O_NONBLOCK`` and no - buffer was in the outgoing queue. - -EINVAL - The ``index`` is out of bounds, or no buffers have been allocated yet. - -EIO - ``DMX_DQBUF`` failed due to an internal error. Can also indicate - temporary problems like signal loss or CRC errors. diff --git a/Documentation/media/uapi/dvb/dmx-querybuf.rst b/Documentation/media/uapi/dvb/dmx-querybuf.rst deleted file mode 100644 index 4cf36e821696..000000000000 --- a/Documentation/media/uapi/dvb/dmx-querybuf.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_QUERYBUF: - -****************** -ioctl DMX_QUERYBUF -****************** - -Name -==== - -DMX_QUERYBUF - Query the status of a buffer - -.. warning:: this API is still experimental - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, DMX_QUERYBUF, struct dvb_buffer *argp ) - :name: DMX_QUERYBUF - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`dvb_buffer`. - - -Description -=========== - -This ioctl is part of the mmap streaming I/O method. It can -be used to query the status of a buffer at any time after buffers have -been allocated with the :ref:`DMX_REQBUFS` ioctl. - -Applications set the ``index`` field. Valid index numbers range from zero -to the number of buffers allocated with :ref:`DMX_REQBUFS` -(struct :c:type:`dvb_requestbuffers` ``count``) minus one. - -After calling :ref:`DMX_QUERYBUF` with a pointer to this structure, -drivers return an error code or fill the rest of the structure. - -On success, the ``offset`` will contain the offset of the buffer from the -start of the device memory, the ``length`` field its size, and the -``bytesused`` the number of bytes occupied by data in the buffer (payload). - -Return Value -============ - -On success 0 is returned, the ``offset`` will contain the offset of the -buffer from the start of the device memory, the ``length`` field its size, -and the ``bytesused`` the number of bytes occupied by data in the buffer -(payload). - -On error it returns -1 and the ``errno`` variable is set -appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - -EINVAL - The ``index`` is out of bounds. diff --git a/Documentation/media/uapi/dvb/dmx-remove-pid.rst b/Documentation/media/uapi/dvb/dmx-remove-pid.rst deleted file mode 100644 index be992f44f306..000000000000 --- a/Documentation/media/uapi/dvb/dmx-remove-pid.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_REMOVE_PID: - -============== -DMX_REMOVE_PID -============== - -Name ----- - -DMX_REMOVE_PID - - -Synopsis --------- - -.. c:function:: int ioctl(fd, DMX_REMOVE_PID, __u16 *pid) - :name: DMX_REMOVE_PID - - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -``pid`` - PID of the PES filter to be removed. - - -Description ------------ - -This ioctl call allows to remove a PID when multiple PIDs are set on a -transport stream filter, e. g. a filter previously set up with output -equal to :c:type:`DMX_OUT_TSDEMUX_TAP `, created via either -:ref:`DMX_SET_PES_FILTER` or :ref:`DMX_ADD_PID`. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-reqbufs.rst b/Documentation/media/uapi/dvb/dmx-reqbufs.rst deleted file mode 100644 index b302785bf678..000000000000 --- a/Documentation/media/uapi/dvb/dmx-reqbufs.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_REQBUFS: - -***************** -ioctl DMX_REQBUFS -***************** - -Name -==== - -DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O - -.. warning:: this API is still experimental - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp ) - :name: DMX_REQBUFS - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`dmx_requestbuffers`. - -Description -=========== - -This ioctl is used to initiate a memory mapped or DMABUF based demux I/O. - -Memory mapped buffers are located in device memory and must be allocated -with this ioctl before they can be mapped into the application's address -space. User buffers are allocated by applications themselves, and this -ioctl is merely used to switch the driver into user pointer I/O mode and -to setup some internal structures. Similarly, DMABUF buffers are -allocated by applications through a device driver, and this ioctl only -configures the driver into DMABUF I/O mode without performing any direct -allocation. - -To allocate device buffers applications initialize all fields of the -struct :c:type:`dmx_requestbuffers` structure. They set the ``count`` field -to the desired number of buffers, and ``size`` to the size of each -buffer. - -When the ioctl is called with a pointer to this structure, the driver will -attempt to allocate the requested number of buffers and it stores the actual -number allocated in the ``count`` field. The ``count`` can be smaller than the number requested, even zero, when the driver runs out of free memory. A larger -number is also possible when the driver requires more buffers to -function correctly. The actual allocated buffer size can is returned -at ``size``, and can be smaller than what's requested. - -When this I/O method is not supported, the ioctl returns an ``EOPNOTSUPP`` -error code. - -Applications can call :ref:`DMX_REQBUFS` again to change the number of -buffers, however this cannot succeed when any buffers are still mapped. -A ``count`` value of zero frees all buffers, after aborting or finishing -any DMA in progress. - - -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 ` chapter. - -EOPNOTSUPP - The the requested I/O method is not supported. diff --git a/Documentation/media/uapi/dvb/dmx-set-buffer-size.rst b/Documentation/media/uapi/dvb/dmx-set-buffer-size.rst deleted file mode 100644 index 2dee0fb11f62..000000000000 --- a/Documentation/media/uapi/dvb/dmx-set-buffer-size.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_SET_BUFFER_SIZE: - -=================== -DMX_SET_BUFFER_SIZE -=================== - -Name ----- - -DMX_SET_BUFFER_SIZE - - -Synopsis --------- - -.. c:function:: int ioctl( int fd, DMX_SET_BUFFER_SIZE, unsigned long size) - :name: DMX_SET_BUFFER_SIZE - - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -``size`` - Unsigned long size - -Description ------------ - -This ioctl call is used to set the size of the circular buffer used for -filtered data. The default size is two maximum sized sections, i.e. if -this function is not called a buffer size of ``2 * 4096`` bytes will be -used. - - -Return Value ------------- - - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-set-filter.rst b/Documentation/media/uapi/dvb/dmx-set-filter.rst deleted file mode 100644 index 66afbb9f2fe4..000000000000 --- a/Documentation/media/uapi/dvb/dmx-set-filter.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_SET_FILTER: - -============== -DMX_SET_FILTER -============== - -Name ----- - -DMX_SET_FILTER - - -Synopsis --------- - -.. c:function:: int ioctl( int fd, DMX_SET_FILTER, struct dmx_sct_filter_params *params) - :name: DMX_SET_FILTER - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -``params`` - - Pointer to structure containing filter parameters. - - -Description ------------ - -This ioctl call sets up a filter according to the filter and mask -parameters provided. A timeout may be defined stating number of seconds -to wait for a section to be loaded. A value of 0 means that no timeout -should be applied. Finally there is a flag field where it is possible to -state whether a section should be CRC-checked, whether the filter should -be a ”one-shot” filter, i.e. if the filtering operation should be -stopped after the first section is received, and whether the filtering -operation should be started immediately (without waiting for a -:ref:`DMX_START` ioctl call). If a filter was previously set-up, this -filter will be canceled, and the receive buffer will be flushed. - - -Return Value ------------- - - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-set-pes-filter.rst b/Documentation/media/uapi/dvb/dmx-set-pes-filter.rst deleted file mode 100644 index dae5ab7878e5..000000000000 --- a/Documentation/media/uapi/dvb/dmx-set-pes-filter.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_SET_PES_FILTER: - -================== -DMX_SET_PES_FILTER -================== - -Name ----- - -DMX_SET_PES_FILTER - - -Synopsis --------- - -.. c:function:: int ioctl( int fd, DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params) - :name: DMX_SET_PES_FILTER - - -Arguments ---------- - - -``fd`` - File descriptor returned by :c:func:`open() `. - -``params`` - Pointer to structure containing filter parameters. - - -Description ------------ - -This ioctl call sets up a PES filter according to the parameters -provided. By a PES filter is meant a filter that is based just on the -packet identifier (PID), i.e. no PES header or payload filtering -capability is supported. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - .. row 1 - - - ``EBUSY`` - - - This error code indicates that there are conflicting requests. - There are active filters filtering data from another input source. - Make sure that these filters are stopped before starting this - filter. - - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-start.rst b/Documentation/media/uapi/dvb/dmx-start.rst deleted file mode 100644 index 488289d02504..000000000000 --- a/Documentation/media/uapi/dvb/dmx-start.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_START: - -========= -DMX_START -========= - -Name ----- - -DMX_START - - -Synopsis --------- - -.. c:function:: int ioctl( int fd, DMX_START) - :name: DMX_START - - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -Description ------------ - -This ioctl call is used to start the actual filtering operation defined -via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER`. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EINVAL`` - - - Invalid argument, i.e. no filtering parameters provided via the - :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` ioctls. - - - .. row 2 - - - ``EBUSY`` - - - This error code indicates that there are conflicting requests. - There are active filters filtering data from another input source. - Make sure that these filters are stopped before starting this - filter. - - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx-stop.rst b/Documentation/media/uapi/dvb/dmx-stop.rst deleted file mode 100644 index 982384d12923..000000000000 --- a/Documentation/media/uapi/dvb/dmx-stop.rst +++ /dev/null @@ -1,52 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _DMX_STOP: - -======== -DMX_STOP -======== - -Name ----- - -DMX_STOP - - -Synopsis --------- - -.. c:function:: int ioctl( int fd, DMX_STOP) - :name: DMX_STOP - - -Arguments ---------- - -``fd`` - File descriptor returned by :c:func:`open() `. - -Description ------------ - -This ioctl call is used to stop the actual filtering operation defined -via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` and -started via the :ref:`DMX_START` command. - - -Return Value ------------- - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/dmx_fcalls.rst b/Documentation/media/uapi/dvb/dmx_fcalls.rst deleted file mode 100644 index 67312ab65f94..000000000000 --- a/Documentation/media/uapi/dvb/dmx_fcalls.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx_fcalls: - -******************** -Demux Function Calls -******************** - -.. toctree:: - :maxdepth: 1 - - dmx-fopen - dmx-fclose - dmx-fread - dmx-fwrite - dmx-mmap - dmx-munmap - dmx-start - dmx-stop - dmx-set-filter - dmx-set-pes-filter - dmx-set-buffer-size - dmx-get-stc - dmx-get-pes-pids - dmx-add-pid - dmx-remove-pid - dmx-reqbufs - dmx-querybuf - dmx-expbuf - dmx-qbuf diff --git a/Documentation/media/uapi/dvb/dmx_types.rst b/Documentation/media/uapi/dvb/dmx_types.rst deleted file mode 100644 index b5cf704199e5..000000000000 --- a/Documentation/media/uapi/dvb/dmx_types.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dmx_types: - -**************** -Demux Data Types -**************** - -.. kernel-doc:: include/uapi/linux/dvb/dmx.h diff --git a/Documentation/media/uapi/dvb/dvb-fe-read-status.rst b/Documentation/media/uapi/dvb/dvb-fe-read-status.rst deleted file mode 100644 index 172783b75fb7..000000000000 --- a/Documentation/media/uapi/dvb/dvb-fe-read-status.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb-fe-read-status: - -*************************************** -Querying frontend status and statistics -*************************************** - -Once :ref:`FE_SET_PROPERTY ` is called, the -frontend will run a kernel thread that will periodically check for the -tuner lock status and provide statistics about the quality of the -signal. - -The information about the frontend tuner locking status can be queried -using :ref:`FE_READ_STATUS`. - -Signal statistics are provided via -:ref:`FE_GET_PROPERTY`. - -.. note:: - - Most statistics require the demodulator to be fully locked - (e. g. with :c:type:`FE_HAS_LOCK ` bit set). See - :ref:`Frontend statistics indicators ` for - more details. diff --git a/Documentation/media/uapi/dvb/dvb-frontend-event.rst b/Documentation/media/uapi/dvb/dvb-frontend-event.rst deleted file mode 100644 index ad4af66040c7..000000000000 --- a/Documentation/media/uapi/dvb/dvb-frontend-event.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. c:type:: dvb_frontend_event - -*************** -frontend events -*************** - - -.. code-block:: c - - struct dvb_frontend_event { - fe_status_t status; - struct dvb_frontend_parameters parameters; - }; diff --git a/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst b/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst deleted file mode 100644 index 67c2a316019f..000000000000 --- a/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst +++ /dev/null @@ -1,126 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. c:type:: dvb_frontend_parameters - -******************* -frontend parameters -******************* - -The kind of parameters passed to the frontend device for tuning depend -on the kind of hardware you are using. - -The struct ``dvb_frontend_parameters`` uses a union with specific -per-system parameters. However, as newer delivery systems required more -data, the structure size weren't enough to fit, and just extending its -size would break the existing applications. So, those parameters were -replaced by the usage of -:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY ` -ioctl's. The new API is flexible enough to add new parameters to -existing delivery systems, and to add newer delivery systems. - -So, newer applications should use -:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY ` -instead, in order to be able to support the newer System Delivery like -DVB-S2, DVB-T2, DVB-C2, ISDB, etc. - -All kinds of parameters are combined as a union in the -``dvb_frontend_parameters`` structure: - - -.. code-block:: c - - struct dvb_frontend_parameters { - uint32_t frequency; /* (absolute) frequency in Hz for QAM/OFDM */ - /* intermediate frequency in kHz for QPSK */ - fe_spectral_inversion_t inversion; - union { - struct dvb_qpsk_parameters qpsk; - struct dvb_qam_parameters qam; - struct dvb_ofdm_parameters ofdm; - struct dvb_vsb_parameters vsb; - } u; - }; - -In the case of QPSK frontends the ``frequency`` field specifies the -intermediate frequency, i.e. the offset which is effectively added to -the local oscillator frequency (LOF) of the LNB. The intermediate -frequency has to be specified in units of kHz. For QAM and OFDM -frontends the ``frequency`` specifies the absolute frequency and is -given in Hz. - - -.. c:type:: dvb_qpsk_parameters - -QPSK parameters -=============== - -For satellite QPSK frontends you have to use the ``dvb_qpsk_parameters`` -structure: - - -.. code-block:: c - - struct dvb_qpsk_parameters { - uint32_t symbol_rate; /* symbol rate in Symbols per second */ - fe_code_rate_t fec_inner; /* forward error correction (see above) */ - }; - - -.. c:type:: dvb_qam_parameters - -QAM parameters -============== - -for cable QAM frontend you use the ``dvb_qam_parameters`` structure: - - -.. code-block:: c - - struct dvb_qam_parameters { - uint32_t symbol_rate; /* symbol rate in Symbols per second */ - fe_code_rate_t fec_inner; /* forward error correction (see above) */ - fe_modulation_t modulation; /* modulation type (see above) */ - }; - - -.. c:type:: dvb_vsb_parameters - -VSB parameters -============== - -ATSC frontends are supported by the ``dvb_vsb_parameters`` structure: - - -.. code-block:: c - - struct dvb_vsb_parameters { - fe_modulation_t modulation; /* modulation type (see above) */ - }; - - -.. c:type:: dvb_ofdm_parameters - -OFDM parameters -=============== - -DVB-T frontends are supported by the ``dvb_ofdm_parameters`` structure: - - -.. code-block:: c - - struct dvb_ofdm_parameters { - fe_bandwidth_t bandwidth; - fe_code_rate_t code_rate_HP; /* high priority stream code rate */ - fe_code_rate_t code_rate_LP; /* low priority stream code rate */ - fe_modulation_t constellation; /* modulation type (see above) */ - fe_transmit_mode_t transmission_mode; - fe_guard_interval_t guard_interval; - fe_hierarchy_t hierarchy_information; - }; diff --git a/Documentation/media/uapi/dvb/dvbapi.rst b/Documentation/media/uapi/dvb/dvbapi.rst deleted file mode 100644 index 0fcc01f182f9..000000000000 --- a/Documentation/media/uapi/dvb/dvbapi.rst +++ /dev/null @@ -1,126 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. include:: - -.. _dvbapi: - -######################## -Part II - Digital TV API -######################## - -.. note:: - - This API is also known as Linux **DVB API**. - - It it was originally written to support the European digital TV - standard (DVB), and later extended to support all digital TV standards. - - In order to avoid confusion, within this document, it was opted to refer to - it, and to associated hardware as **Digital TV**. - - The word **DVB** is reserved to be used for: - - - the Digital TV API version - (e. g. DVB API version 3 or DVB API version 5); - - digital TV data types (enums, structs, defines, etc); - - digital TV device nodes (``/dev/dvb/...``); - - the European DVB standard. - -**Version 5.10** - -.. only:: html - - .. class:: toc-title - - Table of Contents - -.. toctree:: - :maxdepth: 5 - :numbered: - - intro - frontend - demux - ca - net - legacy_dvb_apis - examples - headers - - -********************** -Revision and Copyright -********************** - -Authors: - -- J. K. Metzler, Ralph - - - Original author of the Digital TV API documentation. - -- O. C. Metzler, Marcus - - - Original author of the Digital TV API documentation. - -- Carvalho Chehab, Mauro - - - Ported document to Docbook XML, addition of DVBv5 API, documentation gaps fix. - -**Copyright** |copy| 2002-2003 : Convergence GmbH - -**Copyright** |copy| 2009-2017 : Mauro Carvalho Chehab - -**************** -Revision History -**************** - -:revision: 2.2.0 / 2017-09-01 (*mcc*) - -Most gaps between the uAPI document and the Kernel implementation -got fixed for the non-legacy API. - -:revision: 2.1.0 / 2015-05-29 (*mcc*) - -DocBook improvements and cleanups, in order to document the system calls -on a more standard way and provide more description about the current -Digital TV API. - -:revision: 2.0.4 / 2011-05-06 (*mcc*) - -Add more information about DVBv5 API, better describing the frontend -GET/SET props ioctl's. - - -:revision: 2.0.3 / 2010-07-03 (*mcc*) - -Add some frontend capabilities flags, present on kernel, but missing at -the specs. - - -:revision: 2.0.2 / 2009-10-25 (*mcc*) - -documents FE_SET_FRONTEND_TUNE_MODE and -FE_DISHETWORK_SEND_LEGACY_CMD ioctls. - - -:revision: 2.0.1 / 2009-09-16 (*mcc*) - -Added ISDB-T test originally written by Patrick Boettcher - - -:revision: 2.0.0 / 2009-09-06 (*mcc*) - -Conversion from LaTex to DocBook XML. The contents is the same as the -original LaTex version. - - -:revision: 1.0.0 / 2003-07-24 (*rjkm*) - -Initial revision on LaTEX. diff --git a/Documentation/media/uapi/dvb/dvbproperty.rst b/Documentation/media/uapi/dvb/dvbproperty.rst deleted file mode 100644 index 0c4f5598f2be..000000000000 --- a/Documentation/media/uapi/dvb/dvbproperty.rst +++ /dev/null @@ -1,133 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend-properties: - -************** -Property types -************** - -Tuning into a Digital TV physical channel and starting decoding it -requires changing a set of parameters, in order to control the tuner, -the demodulator, the Linear Low-noise Amplifier (LNA) and to set the -antenna subsystem via Satellite Equipment Control - SEC (on satellite -systems). The actual parameters are specific to each particular digital -TV standards, and may change as the digital TV specs evolves. - -In the past (up to DVB API version 3 - DVBv3), the strategy used was to have a -union with the parameters needed to tune for DVB-S, DVB-C, DVB-T and -ATSC delivery systems grouped there. The problem is that, as the second -generation standards appeared, the size of such union was not big -enough to group the structs that would be required for those new -standards. Also, extending it would break userspace. - -So, the legacy union/struct based approach was deprecated, in favor -of a properties set approach. On such approach, -:ref:`FE_GET_PROPERTY and FE_SET_PROPERTY ` are used -to setup the frontend and read its status. - -The actual action is determined by a set of dtv_property cmd/data pairs. -With one single ioctl, is possible to get/set up to 64 properties. - -This section describes the new and recommended way to set the frontend, -with supports all digital TV delivery systems. - -.. note:: - - 1. On Linux DVB API version 3, setting a frontend was done via - struct :c:type:`dvb_frontend_parameters`. - - 2. Don't use DVB API version 3 calls on hardware with supports - newer standards. Such API provides no support or a very limited - support to new standards and/or new hardware. - - 3. Nowadays, most frontends support multiple delivery systems. - Only with DVB API version 5 calls it is possible to switch between - the multiple delivery systems supported by a frontend. - - 4. DVB API version 5 is also called *S2API*, as the first - new standard added to it was DVB-S2. - -**Example**: in order to set the hardware to tune into a DVB-C channel -at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol rate of 5.217 -Mbauds, those properties should be sent to -:ref:`FE_SET_PROPERTY ` ioctl: - - :ref:`DTV_DELIVERY_SYSTEM ` = SYS_DVBC_ANNEX_A - - :ref:`DTV_FREQUENCY ` = 651000000 - - :ref:`DTV_MODULATION ` = QAM_256 - - :ref:`DTV_INVERSION ` = INVERSION_AUTO - - :ref:`DTV_SYMBOL_RATE ` = 5217000 - - :ref:`DTV_INNER_FEC ` = FEC_3_4 - - :ref:`DTV_TUNE ` - -The code that would that would do the above is show in -:ref:`dtv-prop-example`. - -.. code-block:: c - :caption: Example: Setting digital TV frontend properties - :name: dtv-prop-example - - #include - #include - #include - #include - - static struct dtv_property props[] = { - { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A }, - { .cmd = DTV_FREQUENCY, .u.data = 651000000 }, - { .cmd = DTV_MODULATION, .u.data = QAM_256 }, - { .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO }, - { .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 }, - { .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 }, - { .cmd = DTV_TUNE } - }; - - static struct dtv_properties dtv_prop = { - .num = 6, .props = props - }; - - int main(void) - { - int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR); - - if (!fd) { - perror ("open"); - return -1; - } - if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) { - perror("ioctl"); - return -1; - } - printf("Frontend set\\n"); - return 0; - } - -.. attention:: While it is possible to directly call the Kernel code like the - above example, it is strongly recommended to use - `libdvbv5 `__, as it - provides abstraction to work with the supported digital TV standards and - provides methods for usual operations like program scanning and to - read/write channel descriptor files. - -.. toctree:: - :maxdepth: 1 - - fe_property_parameters - frontend-stat-properties - frontend-property-terrestrial-systems - frontend-property-cable-systems - frontend-property-satellite-systems - frontend-header diff --git a/Documentation/media/uapi/dvb/dvbstb.svg b/Documentation/media/uapi/dvb/dvbstb.svg deleted file mode 100644 index c7672148d6ff..000000000000 --- a/Documentation/media/uapi/dvb/dvbstb.svg +++ /dev/null @@ -1,43 +0,0 @@ - - -image/svg+xmlAntena -Frontend -CA -Demux -SEC -Audio -Video -TV -Decoder -Decoder - diff --git a/Documentation/media/uapi/dvb/examples.rst b/Documentation/media/uapi/dvb/examples.rst deleted file mode 100644 index eaa41bc8d173..000000000000 --- a/Documentation/media/uapi/dvb/examples.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_examples: - -******** -Examples -******** - -In the past, we used to have a set of examples here. However, those -examples got out of date and doesn't even compile nowadays. - -Also, nowadays, the best is to use the libdvbv5 DVB API nowadays, -with is fully documented. - -Please refer to the `libdvbv5 `__ -for updated/recommended examples. diff --git a/Documentation/media/uapi/dvb/fe-bandwidth-t.rst b/Documentation/media/uapi/dvb/fe-bandwidth-t.rst deleted file mode 100644 index c3d7837b5f87..000000000000 --- a/Documentation/media/uapi/dvb/fe-bandwidth-t.rst +++ /dev/null @@ -1,81 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -****************** -Frontend bandwidth -****************** - -.. c:type:: fe_bandwidth - -.. flat-table:: enum fe_bandwidth - :header-rows: 1 - :stub-columns: 0 - - - - .. row 1 - - - ID - - - Description - - - .. row 2 - - - .. _BANDWIDTH-AUTO: - - ``BANDWIDTH_AUTO`` - - - Autodetect bandwidth (if supported) - - - .. row 3 - - - .. _BANDWIDTH-1-712-MHZ: - - ``BANDWIDTH_1_712_MHZ`` - - - 1.712 MHz - - - .. row 4 - - - .. _BANDWIDTH-5-MHZ: - - ``BANDWIDTH_5_MHZ`` - - - 5 MHz - - - .. row 5 - - - .. _BANDWIDTH-6-MHZ: - - ``BANDWIDTH_6_MHZ`` - - - 6 MHz - - - .. row 6 - - - .. _BANDWIDTH-7-MHZ: - - ``BANDWIDTH_7_MHZ`` - - - 7 MHz - - - .. row 7 - - - .. _BANDWIDTH-8-MHZ: - - ``BANDWIDTH_8_MHZ`` - - - 8 MHz - - - .. row 8 - - - .. _BANDWIDTH-10-MHZ: - - ``BANDWIDTH_10_MHZ`` - - - 10 MHz diff --git a/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst b/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst deleted file mode 100644 index 88fd2186ca4d..000000000000 --- a/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_DISEQC_RECV_SLAVE_REPLY: - -******************************** -ioctl FE_DISEQC_RECV_SLAVE_REPLY -******************************** - -Name -==== - -FE_DISEQC_RECV_SLAVE_REPLY - Receives reply from a DiSEqC 2.0 command - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_DISEQC_RECV_SLAVE_REPLY, struct dvb_diseqc_slave_reply *argp ) - :name: FE_DISEQC_RECV_SLAVE_REPLY - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - pointer to struct :c:type:`dvb_diseqc_slave_reply`. - - -Description -=========== - -Receives reply from a DiSEqC 2.0 command. - -The received message is stored at the buffer pointed by ``argp``. - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst b/Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst deleted file mode 100644 index 92929c2e75db..000000000000 --- a/Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_DISEQC_RESET_OVERLOAD: - -****************************** -ioctl FE_DISEQC_RESET_OVERLOAD -****************************** - -Name -==== - -FE_DISEQC_RESET_OVERLOAD - Restores the power to the antenna subsystem, if it was powered off due - to power overload. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_DISEQC_RESET_OVERLOAD, NULL ) - :name: FE_DISEQC_RESET_OVERLOAD - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -Description -=========== - -If the bus has been automatically powered off due to power overload, -this ioctl call restores the power to the bus. The call requires -read/write access to the device. This call has no effect if the device -is manually powered off. Not all Digital TV adapters support this ioctl. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst b/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst deleted file mode 100644 index 8af872d306aa..000000000000 --- a/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_DISEQC_SEND_BURST: - -************************** -ioctl FE_DISEQC_SEND_BURST -************************** - -Name -==== - -FE_DISEQC_SEND_BURST - Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite selection. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_BURST, enum fe_sec_mini_cmd tone ) - :name: FE_DISEQC_SEND_BURST - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``tone`` - An integer enumered value described at :c:type:`fe_sec_mini_cmd`. - - -Description -=========== - -This ioctl is used to set the generation of a 22kHz tone burst for mini -DiSEqC satellite selection for 2x1 switches. This call requires -read/write permissions. - -It provides support for what's specified at -`Digital Satellite Equipment Control (DiSEqC) - Simple "ToneBurst" Detection Circuit specification. `__ - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst b/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst deleted file mode 100644 index 30a48114153c..000000000000 --- a/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_DISEQC_SEND_MASTER_CMD: - -******************************* -ioctl FE_DISEQC_SEND_MASTER_CMD -******************************* - -Name -==== - -FE_DISEQC_SEND_MASTER_CMD - Sends a DiSEqC command - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_DISEQC_SEND_MASTER_CMD, struct dvb_diseqc_master_cmd *argp ) - :name: FE_DISEQC_SEND_MASTER_CMD - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - pointer to struct - :c:type:`dvb_diseqc_master_cmd` - - -Description -=========== - -Sends the DiSEqC command pointed by :c:type:`dvb_diseqc_master_cmd` -to the antenna subsystem. - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. - diff --git a/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst b/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst deleted file mode 100644 index 13811289971b..000000000000 --- a/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_DISHNETWORK_SEND_LEGACY_CMD: - -****************************** -FE_DISHNETWORK_SEND_LEGACY_CMD -****************************** - -Name -==== - -FE_DISHNETWORK_SEND_LEGACY_CMD - - -Synopsis -======== - -.. c:function:: int ioctl(int fd, FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd) - :name: FE_DISHNETWORK_SEND_LEGACY_CMD - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``cmd`` - Sends the specified raw cmd to the dish via DISEqC. - - -Description -=========== - -.. warning:: - This is a very obscure legacy command, used only at stv0299 - driver. Should not be used on newer drivers. - -It provides a non-standard method for selecting Diseqc voltage on the -frontend, for Dish Network legacy switches. - -As support for this ioctl were added in 2004, this means that such -dishes were already legacy in 2004. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst b/Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst deleted file mode 100644 index 32b7d140d80b..000000000000 --- a/Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_ENABLE_HIGH_LNB_VOLTAGE: - -******************************** -ioctl FE_ENABLE_HIGH_LNB_VOLTAGE -******************************** - -Name -==== - -FE_ENABLE_HIGH_LNB_VOLTAGE - Select output DC level between normal LNBf voltages or higher LNBf - voltages. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_ENABLE_HIGH_LNB_VOLTAGE, unsigned int high ) - :name: FE_ENABLE_HIGH_LNB_VOLTAGE - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``high`` - Valid flags: - - - 0 - normal 13V and 18V. - - - >0 - enables slightly higher voltages instead of 13/18V, in order - to compensate for long antenna cables. - - -Description -=========== - -Select output DC level between normal LNBf voltages or higher LNBf -voltages between 0 (normal) or a value grater than 0 for higher -voltages. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-get-event.rst b/Documentation/media/uapi/dvb/fe-get-event.rst deleted file mode 100644 index 2573d5b9b636..000000000000 --- a/Documentation/media/uapi/dvb/fe-get-event.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_GET_EVENT: - -************ -FE_GET_EVENT -************ - -Name -==== - -FE_GET_EVENT - -.. attention:: This ioctl is deprecated. - - -Synopsis -======== - -.. c:function:: int ioctl(int fd, FE_GET_EVENT, struct dvb_frontend_event *ev) - :name: FE_GET_EVENT - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``ev`` - Points to the location where the event, if any, is to be stored. - - -Description -=========== - -This ioctl call returns a frontend event if available. If an event is -not available, the behavior depends on whether the device is in blocking -or non-blocking mode. In the latter case, the call fails immediately -with errno set to ``EWOULDBLOCK``. In the former case, the call blocks until -an event becomes available. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EWOULDBLOCK`` - - - There is no event pending, and the device is in non-blocking mode. - - - .. row 2 - - - ``EOVERFLOW`` - - - Overflow in event queue - one or more events were lost. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-get-frontend.rst b/Documentation/media/uapi/dvb/fe-get-frontend.rst deleted file mode 100644 index 6cd5250d1832..000000000000 --- a/Documentation/media/uapi/dvb/fe-get-frontend.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_GET_FRONTEND: - -*************** -FE_GET_FRONTEND -*************** - -Name -==== - -FE_GET_FRONTEND - -.. attention:: This ioctl is deprecated. - - -Synopsis -======== - -.. c:function:: int ioctl(int fd, FE_GET_FRONTEND, struct dvb_frontend_parameters *p) - :name: FE_GET_FRONTEND - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - - -``p`` - Points to parameters for tuning operation. - - -Description -=========== - -This ioctl call queries the currently effective frontend parameters. For -this command, read-only access to the device is sufficient. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EINVAL`` - - - Maximum supported symbol rate reached. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-get-info.rst b/Documentation/media/uapi/dvb/fe-get-info.rst deleted file mode 100644 index 551e68b11528..000000000000 --- a/Documentation/media/uapi/dvb/fe-get-info.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_GET_INFO: - -***************** -ioctl FE_GET_INFO -***************** - -Name -==== - -FE_GET_INFO - Query Digital TV frontend capabilities and returns information -about the - front-end. This call only requires read-only access to the device. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_GET_INFO, struct dvb_frontend_info *argp ) - :name: FE_GET_INFO - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - pointer to struct struct - :c:type:`dvb_frontend_info` - - -Description -=========== - -All Digital TV frontend devices support the :ref:`FE_GET_INFO` ioctl. It is -used to identify kernel devices compatible with this specification and to -obtain information about driver and hardware capabilities. The ioctl -takes a pointer to dvb_frontend_info which is filled by the driver. -When the driver is not compatible with this specification the ioctl -returns an error. - - -frontend capabilities -===================== - -Capabilities describe what a frontend can do. Some capabilities are -supported only on some specific frontend types. - -The frontend capabilities are described at :c:type:`fe_caps`. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-get-property.rst b/Documentation/media/uapi/dvb/fe-get-property.rst deleted file mode 100644 index 99386c7461b3..000000000000 --- a/Documentation/media/uapi/dvb/fe-get-property.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_GET_PROPERTY: - -************************************** -ioctl FE_SET_PROPERTY, FE_GET_PROPERTY -************************************** - -Name -==== - -FE_SET_PROPERTY - FE_GET_PROPERTY - FE_SET_PROPERTY sets one or more frontend properties. - FE_GET_PROPERTY returns one or more frontend properties. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_GET_PROPERTY, struct dtv_properties *argp ) - :name: FE_GET_PROPERTY - -.. c:function:: int ioctl( int fd, FE_SET_PROPERTY, struct dtv_properties *argp ) - :name: FE_SET_PROPERTY - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`dtv_properties`. - - -Description -=========== - -All Digital TV frontend devices support the ``FE_SET_PROPERTY`` and -``FE_GET_PROPERTY`` ioctls. The supported properties and statistics -depends on the delivery system and on the device: - -- ``FE_SET_PROPERTY:`` - - - This ioctl is used to set one or more frontend properties. - - - This is the basic command to request the frontend to tune into - some frequency and to start decoding the digital TV signal. - - - This call requires read/write access to the device. - -.. note:: - - At return, the values aren't updated to reflect the actual - parameters used. If the actual parameters are needed, an explicit - call to ``FE_GET_PROPERTY`` is needed. - -- ``FE_GET_PROPERTY:`` - - - This ioctl is used to get properties and statistics from the - frontend. - - - No properties are changed, and statistics aren't reset. - - - This call only requires read-only access to the device. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-read-ber.rst b/Documentation/media/uapi/dvb/fe-read-ber.rst deleted file mode 100644 index e579d648687e..000000000000 --- a/Documentation/media/uapi/dvb/fe-read-ber.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_READ_BER: - -*********** -FE_READ_BER -*********** - -Name -==== - -FE_READ_BER - -.. attention:: This ioctl is deprecated. - -Synopsis -======== - -.. c:function:: int ioctl(int fd, FE_READ_BER, uint32_t *ber) - :name: FE_READ_BER - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``ber`` - The bit error rate is stored into \*ber. - - -Description -=========== - -This ioctl call returns the bit error rate for the signal currently -received/demodulated by the front-end. For this command, read-only -access to the device is sufficient. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-read-signal-strength.rst b/Documentation/media/uapi/dvb/fe-read-signal-strength.rst deleted file mode 100644 index 0a0c0c2ff207..000000000000 --- a/Documentation/media/uapi/dvb/fe-read-signal-strength.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_READ_SIGNAL_STRENGTH: - -*********************** -FE_READ_SIGNAL_STRENGTH -*********************** - -Name -==== - -FE_READ_SIGNAL_STRENGTH - -.. attention:: This ioctl is deprecated. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_READ_SIGNAL_STRENGTH, uint16_t *strength) - :name: FE_READ_SIGNAL_STRENGTH - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``strength`` - The signal strength value is stored into \*strength. - - -Description -=========== - -This ioctl call returns the signal strength value for the signal -currently received by the front-end. For this command, read-only access -to the device is sufficient. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-read-snr.rst b/Documentation/media/uapi/dvb/fe-read-snr.rst deleted file mode 100644 index 2a7a0d8f1fd5..000000000000 --- a/Documentation/media/uapi/dvb/fe-read-snr.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_READ_SNR: - -*********** -FE_READ_SNR -*********** - -Name -==== - -FE_READ_SNR - -.. attention:: This ioctl is deprecated. - -Synopsis -======== - -.. c:function:: int ioctl(int fd, FE_READ_SNR, int16_t *snr) - :name: FE_READ_SNR - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``snr`` - The signal-to-noise ratio is stored into \*snr. - - -Description -=========== - -This ioctl call returns the signal-to-noise ratio for the signal -currently received by the front-end. For this command, read-only access -to the device is sufficient. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-read-status.rst b/Documentation/media/uapi/dvb/fe-read-status.rst deleted file mode 100644 index 0dfc9fdf568f..000000000000 --- a/Documentation/media/uapi/dvb/fe-read-status.rst +++ /dev/null @@ -1,72 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_READ_STATUS: - -******************** -ioctl FE_READ_STATUS -******************** - -Name -==== - -FE_READ_STATUS - Returns status information about the front-end. This call only requires - read-only access to the device - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_READ_STATUS, unsigned int *status ) - :name: FE_READ_STATUS - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``status`` - pointer to a bitmask integer filled with the values defined by enum - :c:type:`fe_status`. - - -Description -=========== - -All Digital TV frontend devices support the ``FE_READ_STATUS`` ioctl. It is -used to check about the locking status of the frontend after being -tuned. The ioctl takes a pointer to an integer where the status will be -written. - -.. note:: - - The size of status is actually sizeof(enum fe_status), with - varies according with the architecture. This needs to be fixed in the - future. - - -int fe_status -============= - -The fe_status parameter is used to indicate the current state and/or -state changes of the frontend hardware. It is produced using the enum -:c:type:`fe_status` values on a bitmask - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst b/Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst deleted file mode 100644 index 19c532f750aa..000000000000 --- a/Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_READ_UNCORRECTED_BLOCKS: - -************************** -FE_READ_UNCORRECTED_BLOCKS -************************** - -Name -==== - -FE_READ_UNCORRECTED_BLOCKS - -.. attention:: This ioctl is deprecated. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks) - :name: FE_READ_UNCORRECTED_BLOCKS - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``ublocks`` - The total number of uncorrected blocks seen by the driver so far. - - -Description -=========== - -This ioctl call returns the number of uncorrected blocks detected by the -device driver during its lifetime. For meaningful measurements, the -increment in block count during a specific time interval should be -calculated. For this command, read-only access to the device is -sufficient. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst b/Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst deleted file mode 100644 index 36e8913170e1..000000000000 --- a/Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_SET_FRONTEND_TUNE_MODE: - -******************************* -ioctl FE_SET_FRONTEND_TUNE_MODE -******************************* - -Name -==== - -FE_SET_FRONTEND_TUNE_MODE - Allow setting tuner mode flags to the frontend. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_SET_FRONTEND_TUNE_MODE, unsigned int flags ) - :name: FE_SET_FRONTEND_TUNE_MODE - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``flags`` - Valid flags: - - - 0 - normal tune mode - - - ``FE_TUNE_MODE_ONESHOT`` - When set, this flag will disable any - zigzagging or other "normal" tuning behaviour. Additionally, - there will be no automatic monitoring of the lock status, and - hence no frontend events will be generated. If a frontend device - is closed, this flag will be automatically turned off when the - device is reopened read-write. - - -Description -=========== - -Allow setting tuner mode flags to the frontend, between 0 (normal) or -``FE_TUNE_MODE_ONESHOT`` mode - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-set-frontend.rst b/Documentation/media/uapi/dvb/fe-set-frontend.rst deleted file mode 100644 index 23caae2588d2..000000000000 --- a/Documentation/media/uapi/dvb/fe-set-frontend.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_SET_FRONTEND: - -*************** -FE_SET_FRONTEND -*************** - -.. attention:: This ioctl is deprecated. - -Name -==== - -FE_SET_FRONTEND - - -Synopsis -======== - -.. c:function:: int ioctl(int fd, FE_SET_FRONTEND, struct dvb_frontend_parameters *p) - :name: FE_SET_FRONTEND - - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``p`` - Points to parameters for tuning operation. - - -Description -=========== - -This ioctl call starts a tuning operation using specified parameters. -The result of this call will be successful if the parameters were valid -and the tuning could be initiated. The result of the tuning operation in -itself, however, will arrive asynchronously as an event (see -documentation for :ref:`FE_GET_EVENT` and -FrontendEvent.) If a new :ref:`FE_SET_FRONTEND` -operation is initiated before the previous one was completed, the -previous operation will be aborted in favor of the new one. This command -requires read/write access to the device. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - .. row 1 - - - ``EINVAL`` - - - Maximum supported symbol rate reached. - - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-set-tone.rst b/Documentation/media/uapi/dvb/fe-set-tone.rst deleted file mode 100644 index fb605e8c9fc4..000000000000 --- a/Documentation/media/uapi/dvb/fe-set-tone.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_SET_TONE: - -***************** -ioctl FE_SET_TONE -***************** - -Name -==== - -FE_SET_TONE - Sets/resets the generation of the continuous 22kHz tone. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_SET_TONE, enum fe_sec_tone_mode tone ) - :name: FE_SET_TONE - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``tone`` - an integer enumered value described at :c:type:`fe_sec_tone_mode` - - -Description -=========== - -This ioctl is used to set the generation of the continuous 22kHz tone. -This call requires read/write permissions. - -Usually, satellite antenna subsystems require that the digital TV device -to send a 22kHz tone in order to select between high/low band on some -dual-band LNBf. It is also used to send signals to DiSEqC equipment, but -this is done using the DiSEqC ioctls. - -.. attention:: If more than one device is connected to the same antenna, - setting a tone may interfere on other devices, as they may lose the - capability of selecting the band. So, it is recommended that applications - would change to SEC_TONE_OFF when the device is not used. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-set-voltage.rst b/Documentation/media/uapi/dvb/fe-set-voltage.rst deleted file mode 100644 index c81a8e6a59aa..000000000000 --- a/Documentation/media/uapi/dvb/fe-set-voltage.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _FE_SET_VOLTAGE: - -******************** -ioctl FE_SET_VOLTAGE -******************** - -Name -==== - -FE_SET_VOLTAGE - Allow setting the DC level sent to the antenna subsystem. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, FE_SET_VOLTAGE, enum fe_sec_voltage voltage ) - :name: FE_SET_VOLTAGE - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``voltage`` - an integer enumered value described at :c:type:`fe_sec_voltage` - - -Description -=========== - -This ioctl allows to set the DC voltage level sent through the antenna -cable to 13V, 18V or off. - -Usually, a satellite antenna subsystems require that the digital TV -device to send a DC voltage to feed power to the LNBf. Depending on the -LNBf type, the polarization or the intermediate frequency (IF) of the -LNBf can controlled by the voltage level. Other devices (for example, -the ones that implement DISEqC and multipoint LNBf's don't need to -control the voltage level, provided that either 13V or 18V is sent to -power up the LNBf. - -.. attention:: if more than one device is connected to the same antenna, - setting a voltage level may interfere on other devices, as they may lose - the capability of setting polarization or IF. So, on those cases, setting - the voltage to SEC_VOLTAGE_OFF while the device is not is used is - recommended. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/fe-type-t.rst b/Documentation/media/uapi/dvb/fe-type-t.rst deleted file mode 100644 index 9720d2f7ba35..000000000000 --- a/Documentation/media/uapi/dvb/fe-type-t.rst +++ /dev/null @@ -1,98 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -************* -Frontend type -************* - -For historical reasons, frontend types are named by the type of -modulation used in transmission. The fontend types are given by -fe_type_t type, defined as: - - -.. c:type:: fe_type - -.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| - -.. flat-table:: Frontend types - :header-rows: 1 - :stub-columns: 0 - :widths: 3 1 4 - - - - .. row 1 - - - fe_type - - - Description - - - :ref:`DTV_DELIVERY_SYSTEM ` equivalent - type - - - .. row 2 - - - .. _FE-QPSK: - - ``FE_QPSK`` - - - For DVB-S standard - - - ``SYS_DVBS`` - - - .. row 3 - - - .. _FE-QAM: - - ``FE_QAM`` - - - For DVB-C annex A standard - - - ``SYS_DVBC_ANNEX_A`` - - - .. row 4 - - - .. _FE-OFDM: - - ``FE_OFDM`` - - - For DVB-T standard - - - ``SYS_DVBT`` - - - .. row 5 - - - .. _FE-ATSC: - - ``FE_ATSC`` - - - For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used - in US. - - - ``SYS_ATSC`` (terrestrial) or ``SYS_DVBC_ANNEX_B`` (cable) - - -Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described -at the above, as they're supported via the new -:ref:`FE_GET_PROPERTY/FE_GET_SET_PROPERTY ` -ioctl's, using the :ref:`DTV_DELIVERY_SYSTEM ` -parameter. - -In the old days, struct :c:type:`dvb_frontend_info` -used to contain ``fe_type_t`` field to indicate the delivery systems, -filled with either ``FE_QPSK, FE_QAM, FE_OFDM`` or ``FE_ATSC``. While this -is still filled to keep backward compatibility, the usage of this field -is deprecated, as it can report just one delivery system, but some -devices support multiple delivery systems. Please use -:ref:`DTV_ENUM_DELSYS ` instead. - -On devices that support multiple delivery systems, struct -:c:type:`dvb_frontend_info`::``fe_type_t`` is -filled with the currently standard, as selected by the last call to -:ref:`FE_SET_PROPERTY ` using the -:ref:`DTV_DELIVERY_SYSTEM ` property. diff --git a/Documentation/media/uapi/dvb/fe_property_parameters.rst b/Documentation/media/uapi/dvb/fe_property_parameters.rst deleted file mode 100644 index 2fd2954d8dae..000000000000 --- a/Documentation/media/uapi/dvb/fe_property_parameters.rst +++ /dev/null @@ -1,1014 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _fe_property_parameters: - -****************************** -Digital TV property parameters -****************************** - -There are several different Digital TV parameters that can be used by -:ref:`FE_SET_PROPERTY and FE_GET_PROPERTY ioctls`. -This section describes each of them. Please notice, however, that only -a subset of them are needed to setup a frontend. - - -.. _DTV-UNDEFINED: - -DTV_UNDEFINED -============= - -Used internally. A GET/SET operation for it won't change or return -anything. - - -.. _DTV-TUNE: - -DTV_TUNE -======== - -Interpret the cache of data, build either a traditional frontend -tunerequest so we can pass validation in the ``FE_SET_FRONTEND`` ioctl. - - -.. _DTV-CLEAR: - -DTV_CLEAR -========= - -Reset a cache of data specific to the frontend here. This does not -effect hardware. - - -.. _DTV-FREQUENCY: - -DTV_FREQUENCY -============= - -Frequency of the digital TV transponder/channel. - -.. note:: - - #. For satellite delivery systems, the frequency is in kHz. - - #. For cable and terrestrial delivery systems, the frequency is in - Hz. - - #. On most delivery systems, the frequency is the center frequency - of the transponder/channel. The exception is for ISDB-T, where - the main carrier has a 1/7 offset from the center. - - #. For ISDB-T, the channels are usually transmitted with an offset of - about 143kHz. E.g. a valid frequency could be 474,143 kHz. The - stepping is bound to the bandwidth of the channel which is - typically 6MHz. - - #. In ISDB-Tsb, the channel consists of only one or three segments the - frequency step is 429kHz, 3*429 respectively. - - -.. _DTV-MODULATION: - -DTV_MODULATION -============== - -Specifies the frontend modulation type for delivery systems that -supports more multiple modulations. - -The modulation can be one of the types defined by enum :c:type:`fe_modulation`. - -Most of the digital TV standards offers more than one possible -modulation type. - -The table below presents a summary of the types of modulation types -supported by each delivery system, as currently defined by specs. - -======================= ======================================================= -Standard Modulation types -======================= ======================================================= -ATSC (version 1) 8-VSB and 16-VSB. -DMTB 4-QAM, 16-QAM, 32-QAM, 64-QAM and 4-QAM-NR. -DVB-C Annex A/C 16-QAM, 32-QAM, 64-QAM and 256-QAM. -DVB-C Annex B 64-QAM. -DVB-T QPSK, 16-QAM and 64-QAM. -DVB-T2 QPSK, 16-QAM, 64-QAM and 256-QAM. -DVB-S No need to set. It supports only QPSK. -DVB-S2 QPSK, 8-PSK, 16-APSK and 32-APSK. -ISDB-T QPSK, DQPSK, 16-QAM and 64-QAM. -ISDB-S 8-PSK, QPSK and BPSK. -======================= ======================================================= - -.. note:: - - Please notice that some of the above modulation types may not be - defined currently at the Kernel. The reason is simple: no driver - needed such definition yet. - - -.. _DTV-BANDWIDTH-HZ: - -DTV_BANDWIDTH_HZ -================ - -Bandwidth for the channel, in HZ. - -Should be set only for terrestrial delivery systems. - -Possible values: ``1712000``, ``5000000``, ``6000000``, ``7000000``, -``8000000``, ``10000000``. - -======================= ======================================================= -Terrestrial Standard Possible values for bandwidth -======================= ======================================================= -ATSC (version 1) No need to set. It is always 6MHz. -DMTB No need to set. It is always 8MHz. -DVB-T 6MHz, 7MHz and 8MHz. -DVB-T2 1.172 MHz, 5MHz, 6MHz, 7MHz, 8MHz and 10MHz -ISDB-T 5MHz, 6MHz, 7MHz and 8MHz, although most places - use 6MHz. -======================= ======================================================= - - -.. note:: - - - #. For ISDB-Tsb, the bandwidth can vary depending on the number of - connected segments. - - It can be easily derived from other parameters - (DTV_ISDBT_SB_SEGMENT_IDX, DTV_ISDBT_SB_SEGMENT_COUNT). - - #. On Satellite and Cable delivery systems, the bandwidth depends on - the symbol rate. So, the Kernel will silently ignore any setting - :ref:`DTV-BANDWIDTH-HZ`. I will however fill it back with a - bandwidth estimation. - - Such bandwidth estimation takes into account the symbol rate set with - :ref:`DTV-SYMBOL-RATE`, and the rolloff factor, with is fixed for - DVB-C and DVB-S. - - For DVB-S2, the rolloff should also be set via :ref:`DTV-ROLLOFF`. - - -.. _DTV-INVERSION: - -DTV_INVERSION -============= - -Specifies if the frontend should do spectral inversion or not. - -The acceptable values are defined by :c:type:`fe_spectral_inversion`. - - -.. _DTV-DISEQC-MASTER: - -DTV_DISEQC_MASTER -================= - -Currently not implemented. - - -.. _DTV-SYMBOL-RATE: - -DTV_SYMBOL_RATE -=============== - -Used on cable and satellite delivery systems. - -Digital TV symbol rate, in bauds (symbols/second). - - -.. _DTV-INNER-FEC: - -DTV_INNER_FEC -============= - -Used on cable and satellite delivery systems. - -The acceptable values are defined by :c:type:`fe_code_rate`. - - -.. _DTV-VOLTAGE: - -DTV_VOLTAGE -=========== - -Used on satellite delivery systems. - -The voltage is usually used with non-DiSEqC capable LNBs to switch the -polarzation (horizontal/vertical). When using DiSEqC epuipment this -voltage has to be switched consistently to the DiSEqC commands as -described in the DiSEqC spec. - -The acceptable values are defined by :c:type:`fe_sec_voltage`. - - -.. _DTV-TONE: - -DTV_TONE -======== - -Currently not used. - - -.. _DTV-PILOT: - -DTV_PILOT -========= - -Used on DVB-S2. - -Sets DVB-S2 pilot. - -The acceptable values are defined by :c:type:`fe_pilot`. - - -.. _DTV-ROLLOFF: - -DTV_ROLLOFF -=========== - -Used on DVB-S2. - -Sets DVB-S2 rolloff. - -The acceptable values are defined by :c:type:`fe_rolloff`. - - -.. _DTV-DISEQC-SLAVE-REPLY: - -DTV_DISEQC_SLAVE_REPLY -====================== - -Currently not implemented. - - -.. _DTV-FE-CAPABILITY-COUNT: - -DTV_FE_CAPABILITY_COUNT -======================= - -Currently not implemented. - - -.. _DTV-FE-CAPABILITY: - -DTV_FE_CAPABILITY -================= - -Currently not implemented. - - -.. _DTV-DELIVERY-SYSTEM: - -DTV_DELIVERY_SYSTEM -=================== - -Specifies the type of the delivery system. - -The acceptable values are defined by :c:type:`fe_delivery_system`. - - -.. _DTV-ISDBT-PARTIAL-RECEPTION: - -DTV_ISDBT_PARTIAL_RECEPTION -=========================== - -Used only on ISDB. - -If ``DTV_ISDBT_SOUND_BROADCASTING`` is '0' this bit-field represents -whether the channel is in partial reception mode or not. - -If '1' ``DTV_ISDBT_LAYERA_*`` values are assigned to the center segment -and ``DTV_ISDBT_LAYERA_SEGMENT_COUNT`` has to be '1'. - -If in addition ``DTV_ISDBT_SOUND_BROADCASTING`` is '1' -``DTV_ISDBT_PARTIAL_RECEPTION`` represents whether this ISDB-Tsb channel -is consisting of one segment and layer or three segments and two layers. - -Possible values: 0, 1, -1 (AUTO) - - -.. _DTV-ISDBT-SOUND-BROADCASTING: - -DTV_ISDBT_SOUND_BROADCASTING -============================ - -Used only on ISDB. - -This field represents whether the other DTV_ISDBT_*-parameters are -referring to an ISDB-T and an ISDB-Tsb channel. (See also -``DTV_ISDBT_PARTIAL_RECEPTION``). - -Possible values: 0, 1, -1 (AUTO) - - -.. _DTV-ISDBT-SB-SUBCHANNEL-ID: - -DTV_ISDBT_SB_SUBCHANNEL_ID -========================== - -Used only on ISDB. - -This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'. - -(Note of the author: This might not be the correct description of the -``SUBCHANNEL-ID`` in all details, but it is my understanding of the -technical background needed to program a device) - -An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a -set of connected ISDB-Tsb channels. In this set of channels every -channel can be received independently. The number of connected ISDB-Tsb -segment can vary, e.g. depending on the frequency spectrum bandwidth -available. - -Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The -broadcaster has several possibilities to put those channels in the air: -Assuming a normal 13-segment ISDB-T spectrum he can align the 8 segments -from position 1-8 to 5-13 or anything in between. - -The underlying layer of segments are subchannels: each segment is -consisting of several subchannels with a predefined IDs. A sub-channel -is used to help the demodulator to synchronize on the channel. - -An ISDB-T channel is always centered over all sub-channels. As for the -example above, in ISDB-Tsb it is no longer as simple as that. - -``The DTV_ISDBT_SB_SUBCHANNEL_ID`` parameter is used to give the -sub-channel ID of the segment to be demodulated. - -Possible values: 0 .. 41, -1 (AUTO) - - -.. _DTV-ISDBT-SB-SEGMENT-IDX: - -DTV_ISDBT_SB_SEGMENT_IDX -======================== - -Used only on ISDB. - -This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'. - -``DTV_ISDBT_SB_SEGMENT_IDX`` gives the index of the segment to be -demodulated for an ISDB-Tsb channel where several of them are -transmitted in the connected manner. - -Possible values: 0 .. ``DTV_ISDBT_SB_SEGMENT_COUNT`` - 1 - -Note: This value cannot be determined by an automatic channel search. - - -.. _DTV-ISDBT-SB-SEGMENT-COUNT: - -DTV_ISDBT_SB_SEGMENT_COUNT -========================== - -Used only on ISDB. - -This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'. - -``DTV_ISDBT_SB_SEGMENT_COUNT`` gives the total count of connected -ISDB-Tsb channels. - -Possible values: 1 .. 13 - -Note: This value cannot be determined by an automatic channel search. - - -.. _isdb-hierq-layers: - -DTV-ISDBT-LAYER[A-C] parameters -=============================== - -Used only on ISDB. - -ISDB-T channels can be coded hierarchically. As opposed to DVB-T in -ISDB-T hierarchical layers can be decoded simultaneously. For that -reason a ISDB-T demodulator has 3 Viterbi and 3 Reed-Solomon decoders. - -ISDB-T has 3 hierarchical layers which each can use a part of the -available segments. The total number of segments over all layers has to -13 in ISDB-T. - -There are 3 parameter sets, for Layers A, B and C. - - -.. _DTV-ISDBT-LAYER-ENABLED: - -DTV_ISDBT_LAYER_ENABLED ------------------------ - -Used only on ISDB. - -Hierarchical reception in ISDB-T is achieved by enabling or disabling -layers in the decoding process. Setting all bits of -``DTV_ISDBT_LAYER_ENABLED`` to '1' forces all layers (if applicable) to -be demodulated. This is the default. - -If the channel is in the partial reception mode -(``DTV_ISDBT_PARTIAL_RECEPTION`` = 1) the central segment can be decoded -independently of the other 12 segments. In that mode layer A has to have -a ``SEGMENT_COUNT`` of 1. - -In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb according -to ``DTV_ISDBT_PARTIAL_RECEPTION``. ``SEGMENT_COUNT`` must be filled -accordingly. - -Only the values of the first 3 bits are used. Other bits will be silently ignored: - -``DTV_ISDBT_LAYER_ENABLED`` bit 0: layer A enabled - -``DTV_ISDBT_LAYER_ENABLED`` bit 1: layer B enabled - -``DTV_ISDBT_LAYER_ENABLED`` bit 2: layer C enabled - -``DTV_ISDBT_LAYER_ENABLED`` bits 3-31: unused - - -.. _DTV-ISDBT-LAYER-FEC: - -DTV_ISDBT_LAYER[A-C]_FEC ------------------------- - -Used only on ISDB. - -The Forward Error Correction mechanism used by a given ISDB Layer, as -defined by :c:type:`fe_code_rate`. - - -Possible values are: ``FEC_AUTO``, ``FEC_1_2``, ``FEC_2_3``, ``FEC_3_4``, -``FEC_5_6``, ``FEC_7_8`` - - -.. _DTV-ISDBT-LAYER-MODULATION: - -DTV_ISDBT_LAYER[A-C]_MODULATION -------------------------------- - -Used only on ISDB. - -The modulation used by a given ISDB Layer, as defined by -:c:type:`fe_modulation`. - -Possible values are: ``QAM_AUTO``, ``QPSK``, ``QAM_16``, ``QAM_64``, ``DQPSK`` - -.. note:: - - #. If layer C is ``DQPSK``, then layer B has to be ``DQPSK``. - - #. If layer B is ``DQPSK`` and ``DTV_ISDBT_PARTIAL_RECEPTION``\ = 0, - then layer has to be ``DQPSK``. - - -.. _DTV-ISDBT-LAYER-SEGMENT-COUNT: - -DTV_ISDBT_LAYER[A-C]_SEGMENT_COUNT ----------------------------------- - -Used only on ISDB. - -Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO) - -Note: Truth table for ``DTV_ISDBT_SOUND_BROADCASTING`` and -``DTV_ISDBT_PARTIAL_RECEPTION`` and ``LAYER[A-C]_SEGMENT_COUNT`` - -.. _isdbt-layer_seg-cnt-table: - -.. flat-table:: Truth table for ISDB-T Sound Broadcasting - :header-rows: 1 - :stub-columns: 0 - - - - .. row 1 - - - Partial Reception - - - Sound Broadcasting - - - Layer A width - - - Layer B width - - - Layer C width - - - total width - - - .. row 2 - - - 0 - - - 0 - - - 1 .. 13 - - - 1 .. 13 - - - 1 .. 13 - - - 13 - - - .. row 3 - - - 1 - - - 0 - - - 1 - - - 1 .. 13 - - - 1 .. 13 - - - 13 - - - .. row 4 - - - 0 - - - 1 - - - 1 - - - 0 - - - 0 - - - 1 - - - .. row 5 - - - 1 - - - 1 - - - 1 - - - 2 - - - 0 - - - 13 - - - -.. _DTV-ISDBT-LAYER-TIME-INTERLEAVING: - -DTV_ISDBT_LAYER[A-C]_TIME_INTERLEAVING --------------------------------------- - -Used only on ISDB. - -Valid values: 0, 1, 2, 4, -1 (AUTO) - -when DTV_ISDBT_SOUND_BROADCASTING is active, value 8 is also valid. - -Note: The real time interleaving length depends on the mode (fft-size). -The values here are referring to what can be found in the -TMCC-structure, as shown in the table below. - - -.. c:type:: isdbt_layer_interleaving_table - -.. flat-table:: ISDB-T time interleaving modes - :header-rows: 1 - :stub-columns: 0 - - - - .. row 1 - - - ``DTV_ISDBT_LAYER[A-C]_TIME_INTERLEAVING`` - - - Mode 1 (2K FFT) - - - Mode 2 (4K FFT) - - - Mode 3 (8K FFT) - - - .. row 2 - - - 0 - - - 0 - - - 0 - - - 0 - - - .. row 3 - - - 1 - - - 4 - - - 2 - - - 1 - - - .. row 4 - - - 2 - - - 8 - - - 4 - - - 2 - - - .. row 5 - - - 4 - - - 16 - - - 8 - - - 4 - - - -.. _DTV-ATSCMH-FIC-VER: - -DTV_ATSCMH_FIC_VER ------------------- - -Used only on ATSC-MH. - -Version number of the FIC (Fast Information Channel) signaling data. - -FIC is used for relaying information to allow rapid service acquisition -by the receiver. - -Possible values: 0, 1, 2, 3, ..., 30, 31 - - -.. _DTV-ATSCMH-PARADE-ID: - -DTV_ATSCMH_PARADE_ID --------------------- - -Used only on ATSC-MH. - -Parade identification number - -A parade is a collection of up to eight MH groups, conveying one or two -ensembles. - -Possible values: 0, 1, 2, 3, ..., 126, 127 - - -.. _DTV-ATSCMH-NOG: - -DTV_ATSCMH_NOG --------------- - -Used only on ATSC-MH. - -Number of MH groups per MH subframe for a designated parade. - -Possible values: 1, 2, 3, 4, 5, 6, 7, 8 - - -.. _DTV-ATSCMH-TNOG: - -DTV_ATSCMH_TNOG ---------------- - -Used only on ATSC-MH. - -Total number of MH groups including all MH groups belonging to all MH -parades in one MH subframe. - -Possible values: 0, 1, 2, 3, ..., 30, 31 - - -.. _DTV-ATSCMH-SGN: - -DTV_ATSCMH_SGN --------------- - -Used only on ATSC-MH. - -Start group number. - -Possible values: 0, 1, 2, 3, ..., 14, 15 - - -.. _DTV-ATSCMH-PRC: - -DTV_ATSCMH_PRC --------------- - -Used only on ATSC-MH. - -Parade repetition cycle. - -Possible values: 1, 2, 3, 4, 5, 6, 7, 8 - - -.. _DTV-ATSCMH-RS-FRAME-MODE: - -DTV_ATSCMH_RS_FRAME_MODE ------------------------- - -Used only on ATSC-MH. - -Reed Solomon (RS) frame mode. - -The acceptable values are defined by :c:type:`atscmh_rs_frame_mode`. - - -.. _DTV-ATSCMH-RS-FRAME-ENSEMBLE: - -DTV_ATSCMH_RS_FRAME_ENSEMBLE ----------------------------- - -Used only on ATSC-MH. - -Reed Solomon(RS) frame ensemble. - -The acceptable values are defined by :c:type:`atscmh_rs_frame_ensemble`. - - -.. _DTV-ATSCMH-RS-CODE-MODE-PRI: - -DTV_ATSCMH_RS_CODE_MODE_PRI ---------------------------- - -Used only on ATSC-MH. - -Reed Solomon (RS) code mode (primary). - -The acceptable values are defined by :c:type:`atscmh_rs_code_mode`. - - -.. _DTV-ATSCMH-RS-CODE-MODE-SEC: - -DTV_ATSCMH_RS_CODE_MODE_SEC ---------------------------- - -Used only on ATSC-MH. - -Reed Solomon (RS) code mode (secondary). - -The acceptable values are defined by :c:type:`atscmh_rs_code_mode`. - - -.. _DTV-ATSCMH-SCCC-BLOCK-MODE: - -DTV_ATSCMH_SCCC_BLOCK_MODE --------------------------- - -Used only on ATSC-MH. - -Series Concatenated Convolutional Code Block Mode. - -The acceptable values are defined by :c:type:`atscmh_sccc_block_mode`. - - -.. _DTV-ATSCMH-SCCC-CODE-MODE-A: - -DTV_ATSCMH_SCCC_CODE_MODE_A ---------------------------- - -Used only on ATSC-MH. - -Series Concatenated Convolutional Code Rate. - -The acceptable values are defined by :c:type:`atscmh_sccc_code_mode`. - -.. _DTV-ATSCMH-SCCC-CODE-MODE-B: - -DTV_ATSCMH_SCCC_CODE_MODE_B ---------------------------- - -Used only on ATSC-MH. - -Series Concatenated Convolutional Code Rate. - -Possible values are the same as documented on enum -:c:type:`atscmh_sccc_code_mode`. - - -.. _DTV-ATSCMH-SCCC-CODE-MODE-C: - -DTV_ATSCMH_SCCC_CODE_MODE_C ---------------------------- - -Used only on ATSC-MH. - -Series Concatenated Convolutional Code Rate. - -Possible values are the same as documented on enum -:c:type:`atscmh_sccc_code_mode`. - - -.. _DTV-ATSCMH-SCCC-CODE-MODE-D: - -DTV_ATSCMH_SCCC_CODE_MODE_D ---------------------------- - -Used only on ATSC-MH. - -Series Concatenated Convolutional Code Rate. - -Possible values are the same as documented on enum -:c:type:`atscmh_sccc_code_mode`. - - -.. _DTV-API-VERSION: - -DTV_API_VERSION -=============== - -Returns the major/minor version of the Digital TV API - - -.. _DTV-CODE-RATE-HP: - -DTV_CODE_RATE_HP -================ - -Used on terrestrial transmissions. - -The acceptable values are defined by :c:type:`fe_transmit_mode`. - - -.. _DTV-CODE-RATE-LP: - -DTV_CODE_RATE_LP -================ - -Used on terrestrial transmissions. - -The acceptable values are defined by :c:type:`fe_transmit_mode`. - - -.. _DTV-GUARD-INTERVAL: - -DTV_GUARD_INTERVAL -================== - -The acceptable values are defined by :c:type:`fe_guard_interval`. - -.. note:: - - #. If ``DTV_GUARD_INTERVAL`` is set the ``GUARD_INTERVAL_AUTO`` the - hardware will try to find the correct guard interval (if capable) and - will use TMCC to fill in the missing parameters. - #. Intervals ``GUARD_INTERVAL_1_128``, ``GUARD_INTERVAL_19_128`` - and ``GUARD_INTERVAL_19_256`` are used only for DVB-T2 at - present. - #. Intervals ``GUARD_INTERVAL_PN420``, ``GUARD_INTERVAL_PN595`` and - ``GUARD_INTERVAL_PN945`` are used only for DMTB at the present. - On such standard, only those intervals and ``GUARD_INTERVAL_AUTO`` - are valid. - -.. _DTV-TRANSMISSION-MODE: - -DTV_TRANSMISSION_MODE -===================== - - -Used only on OFTM-based standards, e. g. DVB-T/T2, ISDB-T, DTMB. - -Specifies the FFT size (with corresponds to the approximate number of -carriers) used by the standard. - -The acceptable values are defined by :c:type:`fe_transmit_mode`. - -.. note:: - - #. ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called - **mode** on such standard, and are numbered from 1 to 3: - - ==== ======== ======================== - Mode FFT size Transmission mode - ==== ======== ======================== - 1 2K ``TRANSMISSION_MODE_2K`` - 2 4K ``TRANSMISSION_MODE_4K`` - 3 8K ``TRANSMISSION_MODE_8K`` - ==== ======== ======================== - - #. If ``DTV_TRANSMISSION_MODE`` is set the ``TRANSMISSION_MODE_AUTO`` - the hardware will try to find the correct FFT-size (if capable) and - will use TMCC to fill in the missing parameters. - - #. DVB-T specifies 2K and 8K as valid sizes. - - #. DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K. - - #. DTMB specifies C1 and C3780. - - -.. _DTV-HIERARCHY: - -DTV_HIERARCHY -============= - -Used only on DVB-T and DVB-T2. - -Frontend hierarchy. - -The acceptable values are defined by :c:type:`fe_hierarchy`. - - -.. _DTV-STREAM-ID: - -DTV_STREAM_ID -============= - -Used on DVB-S2, DVB-T2 and ISDB-S. - -DVB-S2, DVB-T2 and ISDB-S support the transmission of several streams on -a single transport stream. This property enables the digital TV driver to -handle substream filtering, when supported by the hardware. By default, -substream filtering is disabled. - -For DVB-S2 and DVB-T2, the valid substream id range is from 0 to 255. - -For ISDB, the valid substream id range is from 1 to 65535. - -To disable it, you should use the special macro NO_STREAM_ID_FILTER. - -Note: any value outside the id range also disables filtering. - - -.. _DTV-DVBT2-PLP-ID-LEGACY: - -DTV_DVBT2_PLP_ID_LEGACY -======================= - -Obsolete, replaced with DTV_STREAM_ID. - - -.. _DTV-ENUM-DELSYS: - -DTV_ENUM_DELSYS -=============== - -A Multi standard frontend needs to advertise the delivery systems -provided. Applications need to enumerate the provided delivery systems, -before using any other operation with the frontend. Prior to it's -introduction, FE_GET_INFO was used to determine a frontend type. A -frontend which provides more than a single delivery system, -FE_GET_INFO doesn't help much. Applications which intends to use a -multistandard frontend must enumerate the delivery systems associated -with it, rather than trying to use FE_GET_INFO. In the case of a -legacy frontend, the result is just the same as with FE_GET_INFO, but -in a more structured format - -The acceptable values are defined by :c:type:`fe_delivery_system`. - - -.. _DTV-INTERLEAVING: - -DTV_INTERLEAVING -================ - -Time interleaving to be used. - -The acceptable values are defined by :c:type:`fe_interleaving`. - - -.. _DTV-LNA: - -DTV_LNA -======= - -Low-noise amplifier. - -Hardware might offer controllable LNA which can be set manually using -that parameter. Usually LNA could be found only from terrestrial devices -if at all. - -Possible values: 0, 1, LNA_AUTO - -0, LNA off - -1, LNA on - -use the special macro LNA_AUTO to set LNA auto - - -.. _DTV-SCRAMBLING-SEQUENCE-INDEX: - -DTV_SCRAMBLING_SEQUENCE_INDEX -============================= - -Used on DVB-S2. - -This 18 bit field, when present, carries the index of the DVB-S2 physical -layer scrambling sequence as defined in clause 5.5.4 of EN 302 307. -There is no explicit signalling method to convey scrambling sequence index -to the receiver. If S2 satellite delivery system descriptor is available -it can be used to read the scrambling sequence index (EN 300 468 table 41). - -By default, gold scrambling sequence index 0 is used. - -The valid scrambling sequence index range is from 0 to 262142. diff --git a/Documentation/media/uapi/dvb/frontend-header.rst b/Documentation/media/uapi/dvb/frontend-header.rst deleted file mode 100644 index 635fb4251214..000000000000 --- a/Documentation/media/uapi/dvb/frontend-header.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -Frontend uAPI data types -======================== - -.. kernel-doc:: include/uapi/linux/dvb/frontend.h diff --git a/Documentation/media/uapi/dvb/frontend-property-cable-systems.rst b/Documentation/media/uapi/dvb/frontend-property-cable-systems.rst deleted file mode 100644 index 97fbfc228c10..000000000000 --- a/Documentation/media/uapi/dvb/frontend-property-cable-systems.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend-property-cable-systems: - -***************************************** -Properties used on cable delivery systems -***************************************** - - -.. _dvbc-params: - -DVB-C delivery system -===================== - -The DVB-C Annex-A is the widely used cable standard. Transmission uses -QAM modulation. - -The DVB-C Annex-C is optimized for 6MHz, and is used in Japan. It -supports a subset of the Annex A modulation types, and a roll-off of -0.13, instead of 0.15 - -The following parameters are valid for DVB-C Annex A/C: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_SYMBOL_RATE ` - -- :ref:`DTV_INNER_FEC ` - -- :ref:`DTV_LNA ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _dvbc-annex-b-params: - -DVB-C Annex B delivery system -============================= - -The DVB-C Annex-B is only used on a few Countries like the United -States. - -The following parameters are valid for DVB-C Annex B: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_LNA ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. diff --git a/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst b/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst deleted file mode 100644 index 2bc880a3c826..000000000000 --- a/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend-property-satellite-systems: - -********************************************* -Properties used on satellite delivery systems -********************************************* - - -.. _dvbs-params: - -DVB-S delivery system -===================== - -The following parameters are valid for DVB-S: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_SYMBOL_RATE ` - -- :ref:`DTV_INNER_FEC ` - -- :ref:`DTV_VOLTAGE ` - -- :ref:`DTV_TONE ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - -Future implementations might add those two missing parameters: - -- :ref:`DTV_DISEQC_MASTER ` - -- :ref:`DTV_DISEQC_SLAVE_REPLY ` - - -.. _dvbs2-params: - -DVB-S2 delivery system -====================== - -In addition to all parameters valid for DVB-S, DVB-S2 supports the -following parameters: - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_PILOT ` - -- :ref:`DTV_ROLLOFF ` - -- :ref:`DTV_STREAM_ID ` - -- :ref:`DTV_SCRAMBLING_SEQUENCE_INDEX ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _turbo-params: - -Turbo code delivery system -========================== - -In addition to all parameters valid for DVB-S, turbo code supports the -following parameters: - -- :ref:`DTV_MODULATION ` - - -.. _isdbs-params: - -ISDB-S delivery system -====================== - -The following parameters are valid for ISDB-S: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_SYMBOL_RATE ` - -- :ref:`DTV_INNER_FEC ` - -- :ref:`DTV_VOLTAGE ` - -- :ref:`DTV_STREAM_ID ` diff --git a/Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst b/Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst deleted file mode 100644 index c20af13297e5..000000000000 --- a/Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst +++ /dev/null @@ -1,301 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend-property-terrestrial-systems: - -*********************************************** -Properties used on terrestrial delivery systems -*********************************************** - - -.. _dvbt-params: - -DVB-T delivery system -===================== - -The following parameters are valid for DVB-T: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_BANDWIDTH_HZ ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_CODE_RATE_HP ` - -- :ref:`DTV_CODE_RATE_LP ` - -- :ref:`DTV_GUARD_INTERVAL ` - -- :ref:`DTV_TRANSMISSION_MODE ` - -- :ref:`DTV_HIERARCHY ` - -- :ref:`DTV_LNA ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _dvbt2-params: - -DVB-T2 delivery system -====================== - -DVB-T2 support is currently in the early stages of development, so -expect that this section maygrow and become more detailed with time. - -The following parameters are valid for DVB-T2: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_BANDWIDTH_HZ ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_CODE_RATE_HP ` - -- :ref:`DTV_CODE_RATE_LP ` - -- :ref:`DTV_GUARD_INTERVAL ` - -- :ref:`DTV_TRANSMISSION_MODE ` - -- :ref:`DTV_HIERARCHY ` - -- :ref:`DTV_STREAM_ID ` - -- :ref:`DTV_LNA ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _isdbt: - -ISDB-T delivery system -====================== - -This ISDB-T/ISDB-Tsb API extension should reflect all information needed -to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible that some -very sophisticated devices won't need certain parameters to tune. - -The information given here should help application writers to know how -to handle ISDB-T and ISDB-Tsb hardware using the Linux Digital TV API. - -The details given here about ISDB-T and ISDB-Tsb are just enough to -basically show the dependencies between the needed parameter values, but -surely some information is left out. For more detailed information see -the following documents: - -ARIB STD-B31 - "Transmission System for Digital Terrestrial Television -Broadcasting" and - -ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial Television -Broadcasting". - -In order to understand the ISDB specific parameters, one has to have -some knowledge the channel structure in ISDB-T and ISDB-Tsb. I.e. it has -to be known to the reader that an ISDB-T channel consists of 13 -segments, that it can have up to 3 layer sharing those segments, and -things like that. - -The following parameters are valid for ISDB-T: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_BANDWIDTH_HZ ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_GUARD_INTERVAL ` - -- :ref:`DTV_TRANSMISSION_MODE ` - -- :ref:`DTV_ISDBT_LAYER_ENABLED ` - -- :ref:`DTV_ISDBT_PARTIAL_RECEPTION ` - -- :ref:`DTV_ISDBT_SOUND_BROADCASTING ` - -- :ref:`DTV_ISDBT_SB_SUBCHANNEL_ID ` - -- :ref:`DTV_ISDBT_SB_SEGMENT_IDX ` - -- :ref:`DTV_ISDBT_SB_SEGMENT_COUNT ` - -- :ref:`DTV_ISDBT_LAYERA_FEC ` - -- :ref:`DTV_ISDBT_LAYERA_MODULATION ` - -- :ref:`DTV_ISDBT_LAYERA_SEGMENT_COUNT ` - -- :ref:`DTV_ISDBT_LAYERA_TIME_INTERLEAVING ` - -- :ref:`DTV_ISDBT_LAYERB_FEC ` - -- :ref:`DTV_ISDBT_LAYERB_MODULATION ` - -- :ref:`DTV_ISDBT_LAYERB_SEGMENT_COUNT ` - -- :ref:`DTV_ISDBT_LAYERB_TIME_INTERLEAVING ` - -- :ref:`DTV_ISDBT_LAYERC_FEC ` - -- :ref:`DTV_ISDBT_LAYERC_MODULATION ` - -- :ref:`DTV_ISDBT_LAYERC_SEGMENT_COUNT ` - -- :ref:`DTV_ISDBT_LAYERC_TIME_INTERLEAVING ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _atsc-params: - -ATSC delivery system -==================== - -The following parameters are valid for ATSC: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_BANDWIDTH_HZ ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _atscmh-params: - -ATSC-MH delivery system -======================= - -The following parameters are valid for ATSC-MH: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_BANDWIDTH_HZ ` - -- :ref:`DTV_ATSCMH_FIC_VER ` - -- :ref:`DTV_ATSCMH_PARADE_ID ` - -- :ref:`DTV_ATSCMH_NOG ` - -- :ref:`DTV_ATSCMH_TNOG ` - -- :ref:`DTV_ATSCMH_SGN ` - -- :ref:`DTV_ATSCMH_PRC ` - -- :ref:`DTV_ATSCMH_RS_FRAME_MODE ` - -- :ref:`DTV_ATSCMH_RS_FRAME_ENSEMBLE ` - -- :ref:`DTV_ATSCMH_RS_CODE_MODE_PRI ` - -- :ref:`DTV_ATSCMH_RS_CODE_MODE_SEC ` - -- :ref:`DTV_ATSCMH_SCCC_BLOCK_MODE ` - -- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_A ` - -- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_B ` - -- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_C ` - -- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_D ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. - - -.. _dtmb-params: - -DTMB delivery system -==================== - -The following parameters are valid for DTMB: - -- :ref:`DTV_API_VERSION ` - -- :ref:`DTV_DELIVERY_SYSTEM ` - -- :ref:`DTV_TUNE ` - -- :ref:`DTV_CLEAR ` - -- :ref:`DTV_FREQUENCY ` - -- :ref:`DTV_MODULATION ` - -- :ref:`DTV_BANDWIDTH_HZ ` - -- :ref:`DTV_INVERSION ` - -- :ref:`DTV_INNER_FEC ` - -- :ref:`DTV_GUARD_INTERVAL ` - -- :ref:`DTV_TRANSMISSION_MODE ` - -- :ref:`DTV_INTERLEAVING ` - -- :ref:`DTV_LNA ` - -In addition, the :ref:`DTV QoS statistics ` -are also valid. diff --git a/Documentation/media/uapi/dvb/frontend-stat-properties.rst b/Documentation/media/uapi/dvb/frontend-stat-properties.rst deleted file mode 100644 index 546464db04b5..000000000000 --- a/Documentation/media/uapi/dvb/frontend-stat-properties.rst +++ /dev/null @@ -1,252 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend-stat-properties: - -****************************** -Frontend statistics indicators -****************************** - -The values are returned via ``dtv_property.stat``. If the property is -supported, ``dtv_property.stat.len`` is bigger than zero. - -For most delivery systems, ``dtv_property.stat.len`` will be 1 if the -stats is supported, and the properties will return a single value for -each parameter. - -It should be noted, however, that new OFDM delivery systems like ISDB -can use different modulation types for each group of carriers. On such -standards, up to 3 groups of statistics can be provided, and -``dtv_property.stat.len`` is updated to reflect the "global" metrics, -plus one metric per each carrier group (called "layer" on ISDB). - -So, in order to be consistent with other delivery systems, the first -value at :c:type:`dtv_property.stat.dtv_stats ` array refers -to the global metric. The other elements of the array represent each -layer, starting from layer A(index 1), layer B (index 2) and so on. - -The number of filled elements are stored at ``dtv_property.stat.len``. - -Each element of the ``dtv_property.stat.dtv_stats`` array consists on -two elements: - -- ``svalue`` or ``uvalue``, where ``svalue`` is for signed values of - the measure (dB measures) and ``uvalue`` is for unsigned values - (counters, relative scale) - -- ``scale`` - Scale for the value. It can be: - - - ``FE_SCALE_NOT_AVAILABLE`` - The parameter is supported by the - frontend, but it was not possible to collect it (could be a - transitory or permanent condition) - - - ``FE_SCALE_DECIBEL`` - parameter is a signed value, measured in - 1/1000 dB - - - ``FE_SCALE_RELATIVE`` - parameter is a unsigned value, where 0 - means 0% and 65535 means 100%. - - - ``FE_SCALE_COUNTER`` - parameter is a unsigned value that counts - the occurrence of an event, like bit error, block error, or lapsed - time. - - -.. _DTV-STAT-SIGNAL-STRENGTH: - -DTV_STAT_SIGNAL_STRENGTH -======================== - -Indicates the signal strength level at the analog part of the tuner or -of the demod. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_DECIBEL`` - signal strength is in 0.001 dBm units, power - measured in miliwatts. This value is generally negative. - -- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100% - measurement for power (actually, 0 to 65535). - - -.. _DTV-STAT-CNR: - -DTV_STAT_CNR -============ - -Indicates the Signal to Noise ratio for the main carrier. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_DECIBEL`` - Signal/Noise ratio is in 0.001 dB units. - -- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100% - measurement for Signal/Noise (actually, 0 to 65535). - - -.. _DTV-STAT-PRE-ERROR-BIT-COUNT: - -DTV_STAT_PRE_ERROR_BIT_COUNT -============================ - -Measures the number of bit errors before the forward error correction -(FEC) on the inner coding block (before Viterbi, LDPC or other inner -code). - -This measure is taken during the same interval as -``DTV_STAT_PRE_TOTAL_BIT_COUNT``. - -In order to get the BER (Bit Error Rate) measurement, it should be -divided by -:ref:`DTV_STAT_PRE_TOTAL_BIT_COUNT `. - -This measurement is monotonically increased, as the frontend gets more -bit count measurements. The frontend may reset it when a -channel/transponder is tuned. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_COUNTER`` - Number of error bits counted before the inner - coding. - - -.. _DTV-STAT-PRE-TOTAL-BIT-COUNT: - -DTV_STAT_PRE_TOTAL_BIT_COUNT -============================ - -Measures the amount of bits received before the inner code block, during -the same period as -:ref:`DTV_STAT_PRE_ERROR_BIT_COUNT ` -measurement was taken. - -It should be noted that this measurement can be smaller than the total -amount of bits on the transport stream, as the frontend may need to -manually restart the measurement, losing some data between each -measurement interval. - -This measurement is monotonically increased, as the frontend gets more -bit count measurements. The frontend may reset it when a -channel/transponder is tuned. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring - :ref:`DTV_STAT_PRE_ERROR_BIT_COUNT `. - - -.. _DTV-STAT-POST-ERROR-BIT-COUNT: - -DTV_STAT_POST_ERROR_BIT_COUNT -============================= - -Measures the number of bit errors after the forward error correction -(FEC) done by inner code block (after Viterbi, LDPC or other inner -code). - -This measure is taken during the same interval as -``DTV_STAT_POST_TOTAL_BIT_COUNT``. - -In order to get the BER (Bit Error Rate) measurement, it should be -divided by -:ref:`DTV_STAT_POST_TOTAL_BIT_COUNT `. - -This measurement is monotonically increased, as the frontend gets more -bit count measurements. The frontend may reset it when a -channel/transponder is tuned. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_COUNTER`` - Number of error bits counted after the inner - coding. - - -.. _DTV-STAT-POST-TOTAL-BIT-COUNT: - -DTV_STAT_POST_TOTAL_BIT_COUNT -============================= - -Measures the amount of bits received after the inner coding, during the -same period as -:ref:`DTV_STAT_POST_ERROR_BIT_COUNT ` -measurement was taken. - -It should be noted that this measurement can be smaller than the total -amount of bits on the transport stream, as the frontend may need to -manually restart the measurement, losing some data between each -measurement interval. - -This measurement is monotonically increased, as the frontend gets more -bit count measurements. The frontend may reset it when a -channel/transponder is tuned. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring - :ref:`DTV_STAT_POST_ERROR_BIT_COUNT `. - - -.. _DTV-STAT-ERROR-BLOCK-COUNT: - -DTV_STAT_ERROR_BLOCK_COUNT -========================== - -Measures the number of block errors after the outer forward error -correction coding (after Reed-Solomon or other outer code). - -This measurement is monotonically increased, as the frontend gets more -bit count measurements. The frontend may reset it when a -channel/transponder is tuned. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_COUNTER`` - Number of error blocks counted after the outer - coding. - - -.. _DTV-STAT-TOTAL-BLOCK-COUNT: - -DTV-STAT_TOTAL_BLOCK_COUNT -========================== - -Measures the total number of blocks received during the same period as -:ref:`DTV_STAT_ERROR_BLOCK_COUNT ` -measurement was taken. - -It can be used to calculate the PER indicator, by dividing -:ref:`DTV_STAT_ERROR_BLOCK_COUNT ` by -:ref:`DTV-STAT-TOTAL-BLOCK-COUNT`. - -Possible scales for this metric are: - -- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the - measurement was not complete yet. - -- ``FE_SCALE_COUNTER`` - Number of blocks counted while measuring - :ref:`DTV_STAT_ERROR_BLOCK_COUNT `. diff --git a/Documentation/media/uapi/dvb/frontend.rst b/Documentation/media/uapi/dvb/frontend.rst deleted file mode 100644 index 7ff225dfe11c..000000000000 --- a/Documentation/media/uapi/dvb/frontend.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_frontend: - -####################### -Digital TV Frontend API -####################### - -The Digital TV frontend API was designed to support three groups of delivery -systems: Terrestrial, cable and Satellite. Currently, the following -delivery systems are supported: - -- Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H, - DTMB, CMMB - -- Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B) - -- Satellite systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS - -The Digital TV frontend controls several sub-devices including: - -- Tuner - -- Digital TV demodulator - -- Low noise amplifier (LNA) - -- Satellite Equipment Control (SEC) [#f1]_. - -The frontend can be accessed through ``/dev/dvb/adapter?/frontend?``. -Data types and ioctl definitions can be accessed by including -``linux/dvb/frontend.h`` in your application. - -.. note:: - - Transmission via the internet (DVB-IP) and MMT (MPEG Media Transport) - is not yet handled by this API but a future extension is possible. - -.. [#f1] - - On Satellite systems, the API support for the Satellite Equipment - Control (SEC) allows to power control and to send/receive signals to - control the antenna subsystem, selecting the polarization and choosing - the Intermediate Frequency IF) of the Low Noise Block Converter Feed - Horn (LNBf). It supports the DiSEqC and V-SEC protocols. The DiSEqC - (digital SEC) specification is available at - `Eutelsat `__. - - -.. toctree:: - :maxdepth: 1 - - query-dvb-frontend-info - dvb-fe-read-status - dvbproperty - frontend_fcalls diff --git a/Documentation/media/uapi/dvb/frontend_f_close.rst b/Documentation/media/uapi/dvb/frontend_f_close.rst deleted file mode 100644 index af87c2a83719..000000000000 --- a/Documentation/media/uapi/dvb/frontend_f_close.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend_f_close: - -*************************** -Digital TV frontend close() -*************************** - -Name -==== - -fe-close - Close a frontend device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int close( int fd ) - :name: dvb-fe-close - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - - -Description -=========== - -This system call closes a previously opened front-end device. After -closing a front-end device, its corresponding hardware might be powered -down automatically. - - -Return Value -============ - -On success 0 is returned. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -Generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/frontend_f_open.rst b/Documentation/media/uapi/dvb/frontend_f_open.rst deleted file mode 100644 index 6a46ec5acf7b..000000000000 --- a/Documentation/media/uapi/dvb/frontend_f_open.rst +++ /dev/null @@ -1,117 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend_f_open: - -*************************** -Digital TV frontend open() -*************************** - -Name -==== - -fe-open - Open a frontend device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int open( const char *device_name, int flags ) - :name: dvb-fe-open - -Arguments -========= - -``device_name`` - Device to be opened. - -``flags`` - Open flags. Access can either be ``O_RDWR`` or ``O_RDONLY``. - - Multiple opens are allowed with ``O_RDONLY``. In this mode, only - query and read ioctls are allowed. - - Only one open is allowed in ``O_RDWR``. In this mode, all ioctls are - allowed. - - When the ``O_NONBLOCK`` flag is given, the system calls may return - ``EAGAIN`` error code when no data is available or when the device - driver is temporarily busy. - - Other flags have no effect. - - -Description -=========== - -This system call opens a named frontend device -(``/dev/dvb/adapter?/frontend?``) for subsequent use. Usually the first -thing to do after a successful open is to find out the frontend type -with :ref:`FE_GET_INFO`. - -The device can be opened in read-only mode, which only allows monitoring -of device status and statistics, or read/write mode, which allows any -kind of use (e.g. performing tuning operations.) - -In a system with multiple front-ends, it is usually the case that -multiple devices cannot be open in read/write mode simultaneously. As -long as a front-end device is opened in read/write mode, other open() -calls in read/write mode will either fail or block, depending on whether -non-blocking or blocking mode was specified. A front-end 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. -When an open() call has succeeded, the device will be ready for use in -the specified mode. This implies that the corresponding hardware is -powered up, and that other front-ends may have been powered down to make -that possible. - - -Return Value -============ - -On success :ref:`open() ` returns the new file descriptor. -On error, -1 is returned, and the ``errno`` variable is set appropriately. - -Possible error codes are: - - -On success 0 is returned, and :c:type:`ca_slot_info` is filled. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - ``EPERM`` - - The caller has no permission to access the device. - - - - ``EBUSY`` - - The the device driver is already in use. - - - - ``EMFILE`` - - The process already has the maximum number of files open. - - - - ``ENFILE`` - - The limit on the total number of files open on the system has been - reached. - - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/frontend_fcalls.rst b/Documentation/media/uapi/dvb/frontend_fcalls.rst deleted file mode 100644 index 9b3586f538ea..000000000000 --- a/Documentation/media/uapi/dvb/frontend_fcalls.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend_fcalls: - -####################### -Frontend Function Calls -####################### - -.. toctree:: - :maxdepth: 1 - - frontend_f_open - frontend_f_close - fe-get-info - fe-read-status - fe-get-property - fe-diseqc-reset-overload - fe-diseqc-send-master-cmd - fe-diseqc-recv-slave-reply - fe-diseqc-send-burst - fe-set-tone - fe-set-voltage - fe-enable-high-lnb-voltage - fe-set-frontend-tune-mode diff --git a/Documentation/media/uapi/dvb/frontend_legacy_api.rst b/Documentation/media/uapi/dvb/frontend_legacy_api.rst deleted file mode 100644 index 1ea749d09ca2..000000000000 --- a/Documentation/media/uapi/dvb/frontend_legacy_api.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend_legacy_types: - -Frontend Legacy Data Types -========================== - - -.. toctree:: - :maxdepth: 1 - - fe-type-t - fe-bandwidth-t - dvb-frontend-parameters - dvb-frontend-event - - -.. _frontend_legacy_fcalls: - -Frontend Legacy Function Calls -============================== - -Those functions are defined at DVB version 3. The support is kept in the -kernel due to compatibility issues only. Their usage is strongly not -recommended - - -.. toctree:: - :maxdepth: 1 - - fe-read-ber - fe-read-snr - fe-read-signal-strength - fe-read-uncorrected-blocks - fe-set-frontend - fe-get-frontend - fe-get-event - fe-dishnetwork-send-legacy-cmd diff --git a/Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst b/Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst deleted file mode 100644 index 1567bc73855a..000000000000 --- a/Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _frontend_legacy_dvbv3_api: - -*********************************************** -Digital TV Frontend legacy API (a. k. a. DVBv3) -*********************************************** - -The usage of this API is deprecated, as it doesn't support all digital -TV standards, doesn't provide good statistics measurements and provides -incomplete information. This is kept only to support legacy -applications. - - -.. toctree:: - :maxdepth: 1 - - frontend_legacy_api diff --git a/Documentation/media/uapi/dvb/headers.rst b/Documentation/media/uapi/dvb/headers.rst deleted file mode 100644 index edeabd9e8e90..000000000000 --- a/Documentation/media/uapi/dvb/headers.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -**************************** -Digital TV uAPI header files -**************************** - -Digital TV uAPI headers -*********************** - -.. kernel-include:: $BUILDDIR/frontend.h.rst - -.. kernel-include:: $BUILDDIR/dmx.h.rst - -.. kernel-include:: $BUILDDIR/ca.h.rst - -.. kernel-include:: $BUILDDIR/net.h.rst - -Legacy uAPI -*********** - -.. kernel-include:: $BUILDDIR/audio.h.rst - -.. kernel-include:: $BUILDDIR/video.h.rst diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst deleted file mode 100644 index f1384616ac4e..000000000000 --- a/Documentation/media/uapi/dvb/intro.rst +++ /dev/null @@ -1,190 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_introdution: - -************ -Introduction -************ - - -.. _requisites: - -What you need to know -===================== - -The reader of this document is required to have some knowledge in the -area of digital video broadcasting (Digital TV) and should be familiar with -part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e -you should know what a program/transport stream (PS/TS) is and what is -meant by a packetized elementary stream (PES) or an I-frame. - -Various Digital TV standards documents are available for download at: - -- European standards (DVB): http://www.dvb.org and/or http://www.etsi.org. -- American standards (ATSC): https://www.atsc.org/standards/ -- Japanese standards (ISDB): http://www.dibeg.org/ - -It is also necessary to know how to access Linux devices and how to -use ioctl calls. This also includes the knowledge of C or C++. - - -.. _history: - -History -======= - -The first API for Digital TV cards we used at Convergence in late 1999 was an -extension of the Video4Linux API which was primarily developed for frame -grabber cards. As such it was not really well suited to be used for Digital -TV cards and their new features like recording MPEG streams and filtering -several section and PES data streams at the same time. - -In early 2000, Convergence was approached by Nokia with a proposal for a new -standard Linux Digital TV API. As a commitment to the development of terminals -based on open standards, Nokia and Convergence made it available to all -Linux developers and published it on https://linuxtv.org in September -2000. With the Linux driver for the Siemens/Hauppauge DVB PCI card, -Convergence provided a first implementation of the Linux Digital TV API. -Convergence was the maintainer of the Linux Digital TV API in the early -days. - -Now, the API is maintained by the LinuxTV community (i.e. you, the reader -of this document). The Linux Digital TV API is constantly reviewed and -improved together with the improvements at the subsystem's core at the -Kernel. - - -.. _overview: - -Overview -======== - - -.. _stb_components: - -.. kernel-figure:: dvbstb.svg - :alt: dvbstb.svg - :align: center - - Components of a Digital TV card/STB - -A Digital TV card or set-top-box (STB) usually consists of the -following main hardware components: - -Frontend consisting of tuner and digital TV demodulator - Here the raw signal reaches the digital TV hardware from a satellite dish or - antenna or directly from cable. The frontend down-converts and - demodulates this signal into an MPEG transport stream (TS). In case - of a satellite frontend, this includes a facility for satellite - equipment control (SEC), which allows control of LNB polarization, - multi feed switches or dish rotors. - -Conditional Access (CA) hardware like CI adapters and smartcard slots - The complete TS is passed through the CA hardware. Programs to which - the user has access (controlled by the smart card) are decoded in - real time and re-inserted into the TS. - - .. note:: - - Not every digital TV hardware provides conditional access hardware. - -Demultiplexer which filters the incoming Digital TV MPEG-TS stream - The demultiplexer splits the TS into its components like audio and - video streams. Besides usually several of such audio and video - streams it also contains data streams with information about the - programs offered in this or other streams of the same provider. - -Audio and video decoder - The main targets of the demultiplexer are audio and video - decoders. After decoding, they pass on the uncompressed audio and - video to the computer screen or to a TV set. - - .. note:: - - Modern hardware usually doesn't have a separate decoder hardware, as - such functionality can be provided by the main CPU, by the graphics - adapter of the system or by a signal processing hardware embedded on - a Systems on a Chip (SoC) integrated circuit. - - It may also not be needed for certain usages (e.g. for data-only - uses like “internet over satellite”). - -:ref:`stb_components` shows a crude schematic of the control and data -flow between those components. - - - -.. _dvb_devices: - -Linux Digital TV Devices -======================== - -The Linux Digital TV API lets you control these hardware components through -currently six Unix-style character devices for video, audio, frontend, -demux, CA and IP-over-DVB networking. The video and audio devices -control the MPEG2 decoder hardware, the frontend device the tuner and -the Digital TV demodulator. The demux device gives you control over the PES -and section filters of the hardware. If the hardware does not support -filtering these filters can be implemented in software. Finally, the CA -device controls all the conditional access capabilities of the hardware. -It can depend on the individual security requirements of the platform, -if and how many of the CA functions are made available to the -application through this device. - -All devices can be found in the ``/dev`` tree under ``/dev/dvb``. The -individual devices are called: - -- ``/dev/dvb/adapterN/audioM``, - -- ``/dev/dvb/adapterN/videoM``, - -- ``/dev/dvb/adapterN/frontendM``, - -- ``/dev/dvb/adapterN/netM``, - -- ``/dev/dvb/adapterN/demuxM``, - -- ``/dev/dvb/adapterN/dvrM``, - -- ``/dev/dvb/adapterN/caM``, - -where ``N`` enumerates the Digital TV cards in a system starting from 0, and -``M`` enumerates the devices of each type within each adapter, starting -from 0, too. We will omit the “``/dev/dvb/adapterN/``\ ” in the further -discussion of these devices. - -More details about the data structures and function calls of all the -devices are described in the following chapters. - - -.. _include_files: - -API include files -================= - -For each of the Digital TV devices a corresponding include file exists. The -Digital TV API include files should be included in application sources with a -partial path like: - - -.. code-block:: c - - #include - - #include - - #include - - #include - - -To enable applications to support different API version, an additional -include file ``linux/dvb/version.h`` exists, which defines the constant -``DVB_API_VERSION``. This document describes ``DVB_API_VERSION 5.10``. diff --git a/Documentation/media/uapi/dvb/legacy_dvb_apis.rst b/Documentation/media/uapi/dvb/legacy_dvb_apis.rst deleted file mode 100644 index a43b4c36d935..000000000000 --- a/Documentation/media/uapi/dvb/legacy_dvb_apis.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _legacy_dvb_apis: - -*************************** -Digital TV Deprecated APIs -*************************** - -The APIs described here **should not** be used on new drivers or applications. - -The DVBv3 frontend API has issues with new delivery systems, including -DVB-S2, DVB-T2, ISDB, etc. - -There's just one driver for a very legacy hardware using the Digital TV -audio and video APIs. No modern drivers should use it. Instead, audio and -video should be using the V4L2 and ALSA APIs, and the pipelines should -be set via the Media Controller API. - -.. attention:: - - The APIs described here doesn't necessarily reflect the current - code implementation, as this section of the document was written - for DVB version 1, while the code reflects DVB version 3 - implementation. - - -.. toctree:: - :maxdepth: 1 - - frontend_legacy_dvbv3_api - video - audio diff --git a/Documentation/media/uapi/dvb/net-add-if.rst b/Documentation/media/uapi/dvb/net-add-if.rst deleted file mode 100644 index 1188641b453e..000000000000 --- a/Documentation/media/uapi/dvb/net-add-if.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _NET_ADD_IF: - -**************** -ioctl NET_ADD_IF -**************** - -Name -==== - -NET_ADD_IF - Creates a new network interface for a given Packet ID. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, NET_ADD_IF, struct dvb_net_if *net_if ) - :name: NET_ADD_IF - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``net_if`` - pointer to struct :c:type:`dvb_net_if` - - -Description -=========== - -The NET_ADD_IF ioctl system call selects the Packet ID (PID) that -contains a TCP/IP traffic, the type of encapsulation to be used (MPE or -ULE) and the interface number for the new interface to be created. When -the system call successfully returns, a new virtual network interface is -created. - -The struct :c:type:`dvb_net_if`::ifnum field will be -filled with the number of the created interface. - -Return Value -============ - -On success 0 is returned, and :c:type:`ca_slot_info` is filled. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/net-get-if.rst b/Documentation/media/uapi/dvb/net-get-if.rst deleted file mode 100644 index 7c4ef4b9d6cc..000000000000 --- a/Documentation/media/uapi/dvb/net-get-if.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _NET_GET_IF: - -**************** -ioctl NET_GET_IF -**************** - -Name -==== - -NET_GET_IF - Read the configuration data of an interface created via - :ref:`NET_ADD_IF `. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, NET_GET_IF, struct dvb_net_if *net_if ) - :name: NET_GET_IF - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``net_if`` - pointer to struct :c:type:`dvb_net_if` - - -Description -=========== - -The NET_GET_IF ioctl uses the interface number given by the struct -:c:type:`dvb_net_if`::ifnum field and fills the content of -struct :c:type:`dvb_net_if` with the packet ID and -encapsulation type used on such interface. If the interface was not -created yet with :ref:`NET_ADD_IF `, it will return -1 and fill -the ``errno`` with ``EINVAL`` error code. - - -Return Value -============ - -On success 0 is returned, and :c:type:`ca_slot_info` is filled. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/net-remove-if.rst b/Documentation/media/uapi/dvb/net-remove-if.rst deleted file mode 100644 index bf9a1602eeec..000000000000 --- a/Documentation/media/uapi/dvb/net-remove-if.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _NET_REMOVE_IF: - -******************* -ioctl NET_REMOVE_IF -******************* - -Name -==== - -NET_REMOVE_IF - Removes a network interface. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, NET_REMOVE_IF, int ifnum ) - :name: NET_REMOVE_IF - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``net_if`` - number of the interface to be removed - - -Description -=========== - -The NET_REMOVE_IF ioctl deletes an interface previously created via -:ref:`NET_ADD_IF `. - - -Return Value -============ - -On success 0 is returned, and :c:type:`ca_slot_info` is filled. - -On error -1 is returned, and the ``errno`` variable is set -appropriately. - -The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/net-types.rst b/Documentation/media/uapi/dvb/net-types.rst deleted file mode 100644 index 9e16462a1ef4..000000000000 --- a/Documentation/media/uapi/dvb/net-types.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _net_types: - -************** -Net Data Types -************** - -.. kernel-doc:: include/uapi/linux/dvb/net.h diff --git a/Documentation/media/uapi/dvb/net.rst b/Documentation/media/uapi/dvb/net.rst deleted file mode 100644 index 833daa381968..000000000000 --- a/Documentation/media/uapi/dvb/net.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _net: - -###################### -Digital TV Network API -###################### - -The Digital TV net device controls the mapping of data packages that are part -of a transport stream to be mapped into a virtual network interface, -visible through the standard Linux network protocol stack. - -Currently, two encapsulations are supported: - -- `Multi Protocol Encapsulation (MPE) `__ - -- `Ultra Lightweight Encapsulation (ULE) `__ - -In order to create the Linux virtual network interfaces, an application -needs to tell to the Kernel what are the PIDs and the encapsulation -types that are present on the transport stream. This is done through -``/dev/dvb/adapter?/net?`` device node. The data will be available via -virtual ``dvb?_?`` network interfaces, and will be controlled/routed via -the standard ip tools (like ip, route, netstat, ifconfig, etc). - -Data types and and ioctl definitions are defined via ``linux/dvb/net.h`` -header. - - -.. _net_fcalls: - -Digital TV net Function Calls -############################# - -.. toctree:: - :maxdepth: 1 - - net-types - net-add-if - net-remove-if - net-get-if diff --git a/Documentation/media/uapi/dvb/query-dvb-frontend-info.rst b/Documentation/media/uapi/dvb/query-dvb-frontend-info.rst deleted file mode 100644 index 9a6badc1d295..000000000000 --- a/Documentation/media/uapi/dvb/query-dvb-frontend-info.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _query-dvb-frontend-info: - -***************************** -Querying frontend information -***************************** - -Usually, the first thing to do when the frontend is opened is to check -the frontend capabilities. This is done using -:ref:`FE_GET_INFO`. This ioctl will enumerate the -Digital TV API version and other characteristics about the frontend, and can -be opened either in read only or read/write mode. diff --git a/Documentation/media/uapi/dvb/video-clear-buffer.rst b/Documentation/media/uapi/dvb/video-clear-buffer.rst deleted file mode 100644 index 5eb5546e8ce4..000000000000 --- a/Documentation/media/uapi/dvb/video-clear-buffer.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_CLEAR_BUFFER: - -================== -VIDEO_CLEAR_BUFFER -================== - -Name ----- - -VIDEO_CLEAR_BUFFER - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_CLEAR_BUFFER) - :name: VIDEO_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 VIDEO_CLEAR_BUFFER for this command. - - -Description ------------ - -This ioctl call clears all video buffers in the driver and in the -decoder 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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-command.rst b/Documentation/media/uapi/dvb/video-command.rst deleted file mode 100644 index 020b49645c6b..000000000000 --- a/Documentation/media/uapi/dvb/video-command.rst +++ /dev/null @@ -1,105 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_COMMAND: - -============= -VIDEO_COMMAND -============= - -Name ----- - -VIDEO_COMMAND - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_COMMAND, struct video_command *cmd) - :name: VIDEO_COMMAND - - -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 VIDEO_COMMAND for this command. - - - .. row 3 - - - struct video_command \*cmd - - - Commands the decoder. - - -Description ------------ - -This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders -this ioctl has been replaced by the -:ref:`VIDIOC_DECODER_CMD` ioctl. - -This ioctl commands the decoder. The ``video_command`` struct is a -subset of the ``v4l2_decoder_cmd`` struct, so refer to the -:ref:`VIDIOC_DECODER_CMD` documentation for -more information. - -.. c:type:: struct video_command - -.. code-block:: c - - /* The structure must be zeroed before use by the application - This ensures it can be extended safely in the future. */ - struct video_command { - __u32 cmd; - __u32 flags; - union { - struct { - __u64 pts; - } stop; - - struct { - /* 0 or 1000 specifies normal speed, - 1 specifies forward single stepping, - -1 specifies backward single stepping, - >1: playback at speed/1000 of the normal speed, - <-1: reverse playback at (-speed/1000) of the normal speed. */ - __s32 speed; - __u32 format; - } play; - - struct { - __u32 data[16]; - } raw; - }; - }; - - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-continue.rst b/Documentation/media/uapi/dvb/video-continue.rst deleted file mode 100644 index 2ae2067dfba8..000000000000 --- a/Documentation/media/uapi/dvb/video-continue.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_CONTINUE: - -============== -VIDEO_CONTINUE -============== - -Name ----- - -VIDEO_CONTINUE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_CONTINUE) - :name: VIDEO_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 VIDEO_CONTINUE for this command. - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` instead. - -This ioctl call restarts decoding and playing processes of the video -stream which was played before a call to VIDEO_FREEZE was made. - - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-fast-forward.rst b/Documentation/media/uapi/dvb/video-fast-forward.rst deleted file mode 100644 index 3f805f334ae1..000000000000 --- a/Documentation/media/uapi/dvb/video-fast-forward.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_FAST_FORWARD: - -================== -VIDEO_FAST_FORWARD -================== - -Name ----- - -VIDEO_FAST_FORWARD - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_FAST_FORWARD, int nFrames) - :name: VIDEO_FAST_FORWARD - - -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 VIDEO_FAST_FORWARD for this command. - - - .. row 3 - - - int nFrames - - - The number of frames to skip. - - -Description ------------ - -This ioctl call asks the Video Device to skip decoding of N number of -I-frames. This call can only be used if VIDEO_SOURCE_MEMORY is -selected. - - -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 ` chapter. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EPERM`` - - - Mode VIDEO_SOURCE_MEMORY not selected. diff --git a/Documentation/media/uapi/dvb/video-fclose.rst b/Documentation/media/uapi/dvb/video-fclose.rst deleted file mode 100644 index 3b0285b96a3c..000000000000 --- a/Documentation/media/uapi/dvb/video-fclose.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_fclose: - -================= -dvb video close() -================= - -Name ----- - -dvb video close() - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c: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 video device. - - -Return Value ------------- - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EBADF`` - - - fd is not a valid open file descriptor. diff --git a/Documentation/media/uapi/dvb/video-fopen.rst b/Documentation/media/uapi/dvb/video-fopen.rst deleted file mode 100644 index 7b2a8c750e6a..000000000000 --- a/Documentation/media/uapi/dvb/video-fopen.rst +++ /dev/null @@ -1,122 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_fopen: - -================ -dvb video open() -================ - -Name ----- - -dvb video open() - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c: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 video 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 video device (e.g. -/dev/dvb/adapter0/video0) 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 Video 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 Video Device is opened in O_RDONLY mode, the only -ioctl call that can be used is VIDEO_GET_STATUS. All other call will -return an error code. - - -Return Value ------------- - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``ENODEV`` - - - Device driver not loaded/available. - - - .. row 2 - - - ``EINTERNAL`` - - - Internal error. - - - .. row 3 - - - ``EBUSY`` - - - Device or resource busy. - - - .. row 4 - - - ``EINVAL`` - - - Invalid argument. diff --git a/Documentation/media/uapi/dvb/video-freeze.rst b/Documentation/media/uapi/dvb/video-freeze.rst deleted file mode 100644 index 6b31a4755d2c..000000000000 --- a/Documentation/media/uapi/dvb/video-freeze.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_FREEZE: - -============ -VIDEO_FREEZE -============ - -Name ----- - -VIDEO_FREEZE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_FREEZE) - :name: VIDEO_FREEZE - - -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 VIDEO_FREEZE for this command. - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` instead. - -This ioctl call suspends the live video stream being played. Decoding -and playing are frozen. It is then possible to restart the decoding and -playing process of the video stream using the VIDEO_CONTINUE command. -If VIDEO_SOURCE_MEMORY is selected in the ioctl call -VIDEO_SELECT_SOURCE, the Digital TV subsystem will not decode any more data -until the ioctl call VIDEO_CONTINUE or VIDEO_PLAY is performed. - - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-fwrite.rst b/Documentation/media/uapi/dvb/video-fwrite.rst deleted file mode 100644 index eb35b79eb85c..000000000000 --- a/Documentation/media/uapi/dvb/video-fwrite.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_fwrite: - -================= -dvb video write() -================= - -Name ----- - -dvb video write() - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c: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 VIDEO_SOURCE_MEMORY is selected -in the ioctl call VIDEO_SELECT_SOURCE. The data provided shall be in -PES format, unless the capability allows other formats. 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 VIDEO_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. diff --git a/Documentation/media/uapi/dvb/video-get-capabilities.rst b/Documentation/media/uapi/dvb/video-get-capabilities.rst deleted file mode 100644 index 971fdab70e15..000000000000 --- a/Documentation/media/uapi/dvb/video-get-capabilities.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_CAPABILITIES: - -====================== -VIDEO_GET_CAPABILITIES -====================== - -Name ----- - -VIDEO_GET_CAPABILITIES - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_GET_CAPABILITIES, unsigned int *cap) - :name: VIDEO_GET_CAPABILITIES - - -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 VIDEO_GET_CAPABILITIES for this command. - - - .. row 3 - - - unsigned int \*cap - - - Pointer to a location where to store the capability information. - - -Description ------------ - -This ioctl call asks the video device about its decoding capabilities. -On success it returns and integer which has bits set according to the -defines in section ??. - - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-get-event.rst b/Documentation/media/uapi/dvb/video-get-event.rst deleted file mode 100644 index 7f03fbe3d3b0..000000000000 --- a/Documentation/media/uapi/dvb/video-get-event.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_EVENT: - -=============== -VIDEO_GET_EVENT -=============== - -Name ----- - -VIDEO_GET_EVENT - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_GET_EVENT, struct video_event *ev) - :name: VIDEO_GET_EVENT - - -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 VIDEO_GET_EVENT for this command. - - - .. row 3 - - - struct video_event \*ev - - - Points to the location where the event, if any, is to be stored. - - -Description ------------ - -This ioctl is for Digital TV devices only. To get events from a V4L2 decoder -use the V4L2 :ref:`VIDIOC_DQEVENT` ioctl instead. - -This ioctl call returns an event of type video_event if available. If -an event is not available, the behavior depends on whether the device is -in blocking or non-blocking mode. In the latter case, the call fails -immediately with errno set to ``EWOULDBLOCK``. In the former case, the call -blocks until an event becomes available. The standard Linux poll() -and/or select() system calls can be used with the device file descriptor -to watch for new events. For select(), the file descriptor should be -included in the exceptfds argument, and for poll(), POLLPRI should be -specified as the wake-up condition. Read-only permissions are sufficient -for this ioctl call. - -.. c:type:: video_event - -.. code-block:: c - - struct video_event { - __s32 type; - #define VIDEO_EVENT_SIZE_CHANGED 1 - #define VIDEO_EVENT_FRAME_RATE_CHANGED 2 - #define VIDEO_EVENT_DECODER_STOPPED 3 - #define VIDEO_EVENT_VSYNC 4 - long timestamp; - union { - video_size_t size; - unsigned int frame_rate; /* in frames per 1000sec */ - unsigned char vsync_field; /* unknown/odd/even/progressive */ - } u; - }; - -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 ` chapter. - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EWOULDBLOCK`` - - - There is no event pending, and the device is in non-blocking mode. - - - .. row 2 - - - ``EOVERFLOW`` - - - Overflow in event queue - one or more events were lost. diff --git a/Documentation/media/uapi/dvb/video-get-frame-count.rst b/Documentation/media/uapi/dvb/video-get-frame-count.rst deleted file mode 100644 index ef35da7d4861..000000000000 --- a/Documentation/media/uapi/dvb/video-get-frame-count.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_FRAME_COUNT: - -===================== -VIDEO_GET_FRAME_COUNT -===================== - -Name ----- - -VIDEO_GET_FRAME_COUNT - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_GET_FRAME_COUNT, __u64 *pts) - :name: VIDEO_GET_FRAME_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 - - - int request - - - Equals VIDEO_GET_FRAME_COUNT for this command. - - - .. row 3 - - - __u64 \*pts - - - Returns the number of frames displayed since the decoder was - started. - - -Description ------------ - -This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders -this ioctl has been replaced by the ``V4L2_CID_MPEG_VIDEO_DEC_FRAME`` -control. - -This ioctl call asks the Video Device to return the number of displayed -frames since the decoder was started. - - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-get-pts.rst b/Documentation/media/uapi/dvb/video-get-pts.rst deleted file mode 100644 index 86ceefff7834..000000000000 --- a/Documentation/media/uapi/dvb/video-get-pts.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_PTS: - -============= -VIDEO_GET_PTS -============= - -Name ----- - -VIDEO_GET_PTS - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_GET_PTS, __u64 *pts) - :name: VIDEO_GET_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 VIDEO_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. For V4L2 decoders -this ioctl has been replaced by the ``V4L2_CID_MPEG_VIDEO_DEC_PTS`` -control. - -This ioctl call asks the Video 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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-get-size.rst b/Documentation/media/uapi/dvb/video-get-size.rst deleted file mode 100644 index cc92189d31fd..000000000000 --- a/Documentation/media/uapi/dvb/video-get-size.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_SIZE: - -============== -VIDEO_GET_SIZE -============== - -Name ----- - -VIDEO_GET_SIZE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_GET_SIZE, video_size_t *size) - :name: VIDEO_GET_SIZE - - -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 VIDEO_GET_SIZE for this command. - - - .. row 3 - - - video_size_t \*size - - - Returns the size and aspect ratio. - - -Description ------------ - -This ioctl returns the size and aspect ratio. - -.. c:type:: video_size_t - -.. code-block::c - - typedef struct { - int w; - int h; - video_format_t aspect_ratio; - } video_size_t; - - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-get-status.rst b/Documentation/media/uapi/dvb/video-get-status.rst deleted file mode 100644 index 8bfcf8fc3e19..000000000000 --- a/Documentation/media/uapi/dvb/video-get-status.rst +++ /dev/null @@ -1,80 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_GET_STATUS: - -================ -VIDEO_GET_STATUS -================ - -Name ----- - -VIDEO_GET_STATUS - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_GET_STATUS, struct video_status *status) - :name: VIDEO_GET_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 VIDEO_GET_STATUS for this command. - - - .. row 3 - - - struct video_status \*status - - - Returns the current status of the Video Device. - - -Description ------------ - -This ioctl call asks the Video Device to return the current status of -the device. - -.. c:type:: video_status - -.. code-block:: c - - struct video_status { - int video_blank; /* blank video on freeze? */ - video_play_state_t play_state; /* current state of playback */ - video_stream_source_t stream_source; /* current source (demux/memory) */ - video_format_t video_format; /* current aspect ratio of stream*/ - video_displayformat_t display_format;/* selected cropping mode */ - }; - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-play.rst b/Documentation/media/uapi/dvb/video-play.rst deleted file mode 100644 index fb3f4f168814..000000000000 --- a/Documentation/media/uapi/dvb/video-play.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_PLAY: - -========== -VIDEO_PLAY -========== - -Name ----- - -VIDEO_PLAY - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_PLAY) - :name: VIDEO_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 VIDEO_PLAY for this command. - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` instead. - -This ioctl call asks the Video Device to start playing a video 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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-select-source.rst b/Documentation/media/uapi/dvb/video-select-source.rst deleted file mode 100644 index 32cf025356dc..000000000000 --- a/Documentation/media/uapi/dvb/video-select-source.rst +++ /dev/null @@ -1,84 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SELECT_SOURCE: - -=================== -VIDEO_SELECT_SOURCE -=================== - -Name ----- - -VIDEO_SELECT_SOURCE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SELECT_SOURCE, video_stream_source_t source) - :name: VIDEO_SELECT_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 VIDEO_SELECT_SOURCE for this command. - - - .. row 3 - - - video_stream_source_t source - - - Indicates which source shall be used for the Video stream. - - -Description ------------ - -This ioctl is for Digital TV devices only. This ioctl was also supported by the -V4L2 ivtv driver, but that has been replaced by the ivtv-specific -``IVTV_IOC_PASSTHROUGH_MODE`` ioctl. - -This ioctl call informs the video device which source shall be used for -the input data. The possible sources are demux or memory. If memory is -selected, the data is fed to the video device through the write command. - -.. c:type:: video_stream_source_t - -.. code-block:: c - - typedef enum { - VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */ - VIDEO_SOURCE_MEMORY /* If this source is selected, the stream - comes from the user through the write - system call */ - } video_stream_source_t; - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-set-blank.rst b/Documentation/media/uapi/dvb/video-set-blank.rst deleted file mode 100644 index 901c3c80f167..000000000000 --- a/Documentation/media/uapi/dvb/video-set-blank.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SET_BLANK: - -=============== -VIDEO_SET_BLANK -=============== - -Name ----- - -VIDEO_SET_BLANK - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SET_BLANK, boolean mode) - :name: VIDEO_SET_BLANK - - -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 VIDEO_SET_BLANK for this command. - - - .. row 3 - - - boolean mode - - - TRUE: Blank screen when stop. - - - .. row 4 - - - - - FALSE: Show last decoded frame. - - -Description ------------ - -This ioctl call asks the Video Device to blank out the picture. - - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-set-display-format.rst b/Documentation/media/uapi/dvb/video-set-display-format.rst deleted file mode 100644 index ffdefa341207..000000000000 --- a/Documentation/media/uapi/dvb/video-set-display-format.rst +++ /dev/null @@ -1,69 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SET_DISPLAY_FORMAT: - -======================== -VIDEO_SET_DISPLAY_FORMAT -======================== - -Name ----- - -VIDEO_SET_DISPLAY_FORMAT - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SET_DISPLAY_FORMAT) - :name: VIDEO_SET_DISPLAY_FORMAT - - -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 VIDEO_SET_DISPLAY_FORMAT for this command. - - - .. row 3 - - - video_display_format_t format - - - Selects the video format to be used. - - -Description ------------ - -This ioctl call asks the Video Device to select the video format to be -applied by the MPEG chip on the video. - - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-set-format.rst b/Documentation/media/uapi/dvb/video-set-format.rst deleted file mode 100644 index 63e60214ab37..000000000000 --- a/Documentation/media/uapi/dvb/video-set-format.rst +++ /dev/null @@ -1,92 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SET_FORMAT: - -================ -VIDEO_SET_FORMAT -================ - -Name ----- - -VIDEO_SET_FORMAT - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SET_FORMAT, video_format_t format) - :name: VIDEO_SET_FORMAT - - -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 VIDEO_SET_FORMAT for this command. - - - .. row 3 - - - video_format_t format - - - video format of TV as defined in section ??. - - -Description ------------ - -This ioctl sets the screen format (aspect ratio) of the connected output -device (TV) so that the output of the decoder can be adjusted -accordingly. - -.. c:type:: video_format_t - -.. code-block:: c - - typedef enum { - VIDEO_FORMAT_4_3, /* Select 4:3 format */ - VIDEO_FORMAT_16_9, /* Select 16:9 format. */ - VIDEO_FORMAT_221_1 /* 2.21:1 */ - } video_format_t; - -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 ` chapter. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EINVAL`` - - - format is not a valid video format. diff --git a/Documentation/media/uapi/dvb/video-set-streamtype.rst b/Documentation/media/uapi/dvb/video-set-streamtype.rst deleted file mode 100644 index 845486a6e049..000000000000 --- a/Documentation/media/uapi/dvb/video-set-streamtype.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SET_STREAMTYPE: - -==================== -VIDEO_SET_STREAMTYPE -==================== - -Name ----- - -VIDEO_SET_STREAMTYPE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SET_STREAMTYPE, int type) - :name: VIDEO_SET_STREAMTYPE - - -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 VIDEO_SET_STREAMTYPE for this command. - - - .. row 3 - - - int type - - - stream type - - -Description ------------ - -This ioctl tells the driver which kind of stream to expect being written -to it. If this call is not used the default of video PES is used. Some -drivers might not support this call and always expect PES. - - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-slowmotion.rst b/Documentation/media/uapi/dvb/video-slowmotion.rst deleted file mode 100644 index 32c934aaf2ba..000000000000 --- a/Documentation/media/uapi/dvb/video-slowmotion.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_SLOWMOTION: - -================ -VIDEO_SLOWMOTION -================ - -Name ----- - -VIDEO_SLOWMOTION - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_SLOWMOTION, int nFrames) - :name: VIDEO_SLOWMOTION - - -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 VIDEO_SLOWMOTION for this command. - - - .. row 3 - - - int nFrames - - - The number of times to repeat each frame. - - -Description ------------ - -This ioctl call asks the video device to repeat decoding frames N number -of times. This call can only be used if VIDEO_SOURCE_MEMORY is -selected. - - -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 ` chapter. - - - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``EPERM`` - - - Mode VIDEO_SOURCE_MEMORY not selected. diff --git a/Documentation/media/uapi/dvb/video-stillpicture.rst b/Documentation/media/uapi/dvb/video-stillpicture.rst deleted file mode 100644 index 58035a7630e6..000000000000 --- a/Documentation/media/uapi/dvb/video-stillpicture.rst +++ /dev/null @@ -1,70 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_STILLPICTURE: - -================== -VIDEO_STILLPICTURE -================== - -Name ----- - -VIDEO_STILLPICTURE - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_STILLPICTURE, struct video_still_picture *sp) - :name: VIDEO_STILLPICTURE - - -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 VIDEO_STILLPICTURE for this command. - - - .. row 3 - - - struct video_still_picture \*sp - - - Pointer to a location where an I-frame and size is stored. - - -Description ------------ - -This ioctl call asks the Video Device to display a still picture -(I-frame). The input data shall contain an I-frame. If the pointer is -NULL, then the current displayed still picture is blanked. - - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-stop.rst b/Documentation/media/uapi/dvb/video-stop.rst deleted file mode 100644 index 732ace05e34b..000000000000 --- a/Documentation/media/uapi/dvb/video-stop.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_STOP: - -========== -VIDEO_STOP -========== - -Name ----- - -VIDEO_STOP - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(fd, VIDEO_STOP, boolean mode) - :name: VIDEO_STOP - - -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 VIDEO_STOP for this command. - - - .. row 3 - - - Boolean mode - - - Indicates how the screen shall be handled. - - - .. row 4 - - - - - TRUE: Blank screen when stop. - - - .. row 5 - - - - - FALSE: Show last decoded frame. - - -Description ------------ - -This ioctl is for Digital TV devices only. To control a V4L2 decoder use the -V4L2 :ref:`VIDIOC_DECODER_CMD` instead. - -This ioctl call asks the Video Device to stop playing the current -stream. Depending on the input parameter, the screen can be blanked out -or displaying the last decoded frame. - - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video-try-command.rst b/Documentation/media/uapi/dvb/video-try-command.rst deleted file mode 100644 index 37ecf8e91eb8..000000000000 --- a/Documentation/media/uapi/dvb/video-try-command.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _VIDEO_TRY_COMMAND: - -================= -VIDEO_TRY_COMMAND -================= - -Name ----- - -VIDEO_TRY_COMMAND - -.. attention:: This ioctl is deprecated. - -Synopsis --------- - -.. c:function:: int ioctl(int fd, VIDEO_TRY_COMMAND, struct video_command *cmd) - :name: VIDEO_TRY_COMMAND - - -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 VIDEO_TRY_COMMAND for this command. - - - .. row 3 - - - struct video_command \*cmd - - - Try a decoder command. - - -Description ------------ - -This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders -this ioctl has been replaced by the -:ref:`VIDIOC_TRY_DECODER_CMD ` ioctl. - -This ioctl tries a decoder command. The ``video_command`` struct is a -subset of the ``v4l2_decoder_cmd`` struct, so refer to the -:ref:`VIDIOC_TRY_DECODER_CMD ` documentation -for more information. - - -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 ` chapter. diff --git a/Documentation/media/uapi/dvb/video.rst b/Documentation/media/uapi/dvb/video.rst deleted file mode 100644 index 6d72ed0e2b2d..000000000000 --- a/Documentation/media/uapi/dvb/video.rst +++ /dev/null @@ -1,43 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _dvb_video: - -####################### -Digital TV Video Device -####################### - -The Digital TV video device controls the MPEG2 video decoder of the Digital -TV hardware. It can be accessed through **/dev/dvb/adapter0/video0**. Data -types and and ioctl definitions can be accessed by including -**linux/dvb/video.h** in your application. - -Note that the Digital TV video device only controls decoding of the MPEG video -stream, not its presentation on the TV or computer screen. On PCs this -is typically handled by an associated video4linux device, e.g. -**/dev/video**, which allows scaling and defining output windows. - -Some Digital TV cards don’t have their own MPEG decoder, which results in the -omission of the audio and video device as well as the video4linux -device. - -The ioctls that deal with SPUs (sub picture units) and navigation -packets are only supported on some MPEG decoders made for DVD playback. - -These ioctls were also used by V4L2 to control MPEG decoders implemented -in V4L2. The use of these ioctls for that purpose has been made obsolete -and proper V4L2 ioctls or controls have been created to replace that -functionality. - - -.. toctree:: - :maxdepth: 1 - - video_types - video_function_calls diff --git a/Documentation/media/uapi/dvb/video_function_calls.rst b/Documentation/media/uapi/dvb/video_function_calls.rst deleted file mode 100644 index 9e8e49e52b19..000000000000 --- a/Documentation/media/uapi/dvb/video_function_calls.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_function_calls: - -******************** -Video Function Calls -******************** - -.. toctree:: - :maxdepth: 1 - - video-fopen - video-fclose - video-fwrite - video-stop - video-play - video-freeze - video-continue - video-select-source - video-set-blank - video-get-status - video-get-frame-count - video-get-pts - video-get-event - video-command - video-try-command - video-get-size - video-set-display-format - video-stillpicture - video-fast-forward - video-slowmotion - video-get-capabilities - video-clear-buffer - video-set-streamtype - video-set-format diff --git a/Documentation/media/uapi/dvb/video_types.rst b/Documentation/media/uapi/dvb/video_types.rst deleted file mode 100644 index 2697400ccf62..000000000000 --- a/Documentation/media/uapi/dvb/video_types.rst +++ /dev/null @@ -1,255 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _video_types: - -**************** -Video Data Types -**************** - - -.. _video-format-t: - -video_format_t -============== - -The ``video_format_t`` data type defined by - - -.. code-block:: c - - typedef enum { - VIDEO_FORMAT_4_3, /* Select 4:3 format */ - VIDEO_FORMAT_16_9, /* Select 16:9 format. */ - VIDEO_FORMAT_221_1 /* 2.21:1 */ - } video_format_t; - -is used in the VIDEO_SET_FORMAT function (??) to tell the driver which -aspect ratio the output hardware (e.g. TV) has. It is also used in the -data structures video_status (??) returned by VIDEO_GET_STATUS (??) -and video_event (??) returned by VIDEO_GET_EVENT (??) which report -about the display format of the current video stream. - - -.. _video-displayformat-t: - -video_displayformat_t -===================== - -In case the display format of the video stream and of the display -hardware differ the application has to specify how to handle the -cropping of the picture. This can be done using the -VIDEO_SET_DISPLAY_FORMAT call (??) which accepts - - -.. code-block:: c - - typedef enum { - VIDEO_PAN_SCAN, /* use pan and scan format */ - VIDEO_LETTER_BOX, /* use letterbox format */ - VIDEO_CENTER_CUT_OUT /* use center cut out format */ - } video_displayformat_t; - -as argument. - - -.. _video-stream-source-t: - -video_stream_source_t -===================== - -The video stream source is set through the VIDEO_SELECT_SOURCE call -and can take the following values, depending on whether we are replaying -from an internal (demuxer) or external (user write) source. - - -.. code-block:: c - - typedef enum { - VIDEO_SOURCE_DEMUX, /* Select the demux as the main source */ - VIDEO_SOURCE_MEMORY /* If this source is selected, the stream - comes from the user through the write - system call */ - } video_stream_source_t; - -VIDEO_SOURCE_DEMUX selects the demultiplexer (fed either by the -frontend or the DVR device) as the source of the video stream. If -VIDEO_SOURCE_MEMORY is selected the stream comes from the application -through the **write()** system call. - - -.. _video-play-state-t: - -video_play_state_t -================== - -The following values can be returned by the VIDEO_GET_STATUS call -representing the state of video playback. - - -.. code-block:: c - - typedef enum { - VIDEO_STOPPED, /* Video is stopped */ - VIDEO_PLAYING, /* Video is currently playing */ - VIDEO_FREEZED /* Video is freezed */ - } video_play_state_t; - - -.. c:type:: video_command - -struct video_command -==================== - -The structure must be zeroed before use by the application This ensures -it can be extended safely in the future. - - -.. code-block:: c - - struct video_command { - __u32 cmd; - __u32 flags; - union { - struct { - __u64 pts; - } stop; - - struct { - /* 0 or 1000 specifies normal speed, - 1 specifies forward single stepping, - -1 specifies backward single stepping, - >>1: playback at speed/1000 of the normal speed, - <-1: reverse playback at (-speed/1000) of the normal speed. */ - __s32 speed; - __u32 format; - } play; - - struct { - __u32 data[16]; - } raw; - }; - }; - - -.. _video-size-t: - -video_size_t -============ - - -.. code-block:: c - - typedef struct { - int w; - int h; - video_format_t aspect_ratio; - } video_size_t; - - -.. c:type:: video_event - -struct video_event -================== - -The following is the structure of a video event as it is returned by the -VIDEO_GET_EVENT call. - - -.. code-block:: c - - struct video_event { - __s32 type; - #define VIDEO_EVENT_SIZE_CHANGED 1 - #define VIDEO_EVENT_FRAME_RATE_CHANGED 2 - #define VIDEO_EVENT_DECODER_STOPPED 3 - #define VIDEO_EVENT_VSYNC 4 - long timestamp; - union { - video_size_t size; - unsigned int frame_rate; /* in frames per 1000sec */ - unsigned char vsync_field; /* unknown/odd/even/progressive */ - } u; - }; - - -.. c:type:: video_status - -struct video_status -=================== - -The VIDEO_GET_STATUS call returns the following structure informing -about various states of the playback operation. - - -.. code-block:: c - - struct video_status { - int video_blank; /* blank video on freeze? */ - video_play_state_t play_state; /* current state of playback */ - video_stream_source_t stream_source; /* current source (demux/memory) */ - video_format_t video_format; /* current aspect ratio of stream */ - video_displayformat_t display_format;/* selected cropping mode */ - }; - -If video_blank is set video will be blanked out if the channel is -changed or if playback is stopped. Otherwise, the last picture will be -displayed. play_state indicates if the video is currently frozen, -stopped, or being played back. The stream_source corresponds to the -selected source for the video stream. It can come either from the -demultiplexer or from memory. The video_format indicates the aspect -ratio (one of 4:3 or 16:9) of the currently played video stream. -Finally, display_format corresponds to the selected cropping mode in -case the source video format is not the same as the format of the output -device. - - -.. c:type:: video_still_picture - -struct video_still_picture -========================== - -An I-frame displayed via the VIDEO_STILLPICTURE call is passed on -within the following structure. - - -.. code-block:: c - - /* pointer to and size of a single iframe in memory */ - struct video_still_picture { - char *iFrame; /* pointer to a single iframe in memory */ - int32_t size; - }; - - -.. _video_caps: - -video capabilities -================== - -A call to VIDEO_GET_CAPABILITIES returns an unsigned integer with the -following bits set according to the hardwares capabilities. - - -.. code-block:: c - - /* bit definitions for capabilities: */ - /* can the hardware decode MPEG1 and/or MPEG2? */ - #define VIDEO_CAP_MPEG1 1 - #define VIDEO_CAP_MPEG2 2 - /* can you send a system and/or program stream to video device? - (you still have to open the video and the audio device but only - send the stream to the video device) */ - #define VIDEO_CAP_SYS 4 - #define VIDEO_CAP_PROG 8 - /* can the driver also handle SPU, NAVI and CSS encoded data? - (CSS API is not present yet) */ - #define VIDEO_CAP_SPU 16 - #define VIDEO_CAP_NAVI 32 - #define VIDEO_CAP_CSS 64 diff --git a/Documentation/media/uapi/fdl-appendix.rst b/Documentation/media/uapi/fdl-appendix.rst deleted file mode 100644 index 9316b8617502..000000000000 --- a/Documentation/media/uapi/fdl-appendix.rst +++ /dev/null @@ -1,478 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _fdl: - -****************************** -GNU Free Documentation License -****************************** - - -.. _fdl-preamble: - -0. PREAMBLE -=========== - -The purpose of this License is to make a manual, textbook, or other -written document “free” in the sense of freedom: to assure everyone the -effective freedom to copy and redistribute it, with or without modifying -it, either commercially or noncommercially. Secondarily, this License -preserves for the author and publisher a way to get credit for their -work, while not being considered responsible for modifications made by -others. - -This License is a kind of “copyleft”, which means that derivative works -of the document must themselves be free in the same sense. It -complements the GNU General Public License, which is a copyleft license -designed for free software. - -We have designed this License in order to use it for manuals for free -software, because free software needs free documentation: a free program -should come with manuals providing the same freedoms that the software -does. But this License is not limited to software manuals; it can be -used for any textual work, regardless of subject matter or whether it is -published as a printed book. We recommend this License principally for -works whose purpose is instruction or reference. - - -.. _fdl-section1: - -1. APPLICABILITY AND DEFINITIONS -================================ - - -.. _fdl-document: - -This License applies to any manual or other work that contains a notice -placed by the copyright holder saying it can be distributed under the -terms of this License. The “Document”, below, refers to any such manual -or work. Any member of the public is a licensee, and is addressed as -“you”. - - -.. _fdl-modified: - -A “Modified Version” of the Document means any work containing the -Document or a portion of it, either copied verbatim, or with -modifications and/or translated into another language. - - -.. _fdl-secondary: - -A “Secondary Section” is a named appendix or a front-matter section of -the :ref:`Document ` that deals exclusively with the -relationship of the publishers or authors of the Document to the -Document's overall subject (or to related matters) and contains nothing -that could fall directly within that overall subject. (For example, if -the Document is in part a textbook of mathematics, a Secondary Section -may not explain any mathematics.) The relationship could be a matter of -historical connection with the subject or with related matters, or of -legal, commercial, philosophical, ethical or political position -regarding them. - - -.. _fdl-invariant: - -The “Invariant Sections” are certain -:ref:`Secondary Sections ` whose titles are designated, -as being those of Invariant Sections, in the notice that says that the -:ref:`Document ` is released under this License. - - -.. _fdl-cover-texts: - -The “Cover Texts” are certain short passages of text that are listed, as -Front-Cover Texts or Back-Cover Texts, in the notice that says that the -:ref:`Document ` is released under this License. - - -.. _fdl-transparent: - -A “Transparent” copy of the :ref:`Document ` means a -machine-readable copy, represented in a format whose specification is -available to the general public, whose contents can be viewed and edited -directly and straightforwardly with generic text editors or (for images -composed of pixels) generic paint programs or (for drawings) some widely -available drawing editor, and that is suitable for input to text -formatters or for automatic translation to a variety of formats suitable -for input to text formatters. A copy made in an otherwise Transparent -file format whose markup has been designed to thwart or discourage -subsequent modification by readers is not Transparent. A copy that is -not “Transparent” is called “Opaque”. - -Examples of suitable formats for Transparent copies include plain ASCII -without markup, Texinfo input format, LaTeX input format, SGML or XML -using a publicly available DTD, and standard-conforming simple HTML -designed for human modification. Opaque formats include PostScript, PDF, -proprietary formats that can be read and edited only by proprietary word -processors, SGML or XML for which the DTD and/or processing tools are -not generally available, and the machine-generated HTML produced by some -word processors for output purposes only. - - -.. _fdl-title-page: - -The “Title Page” means, for a printed book, the title page itself, plus -such following pages as are needed to hold, legibly, the material this -License requires to appear in the title page. For works in formats which -do not have any title page as such, “Title Page” means the text near the -most prominent appearance of the work's title, preceding the beginning -of the body of the text. - - -.. _fdl-section2: - -2. VERBATIM COPYING -=================== - -You may copy and distribute the :ref:`Document ` in any -medium, either commercially or noncommercially, provided that this -License, the copyright notices, and the license notice saying this -License applies to the Document are reproduced in all copies, and that -you add no other conditions whatsoever to those of this License. You may -not use technical measures to obstruct or control the reading or further -copying of the copies you make or distribute. However, you may accept -compensation in exchange for copies. If you distribute a large enough -number of copies you must also follow the conditions in -:ref:`section 3 `. - -You may also lend copies, under the same conditions stated above, and -you may publicly display copies. - - -.. _fdl-section3: - -3. COPYING IN QUANTITY -====================== - -If you publish printed copies of the :ref:`Document ` -numbering more than 100, and the Document's license notice requires -:ref:`Cover Texts `, you must enclose the copies in -covers that carry, clearly and legibly, all these Cover Texts: -Front-Cover Texts on the front cover, and Back-Cover Texts on the back -cover. Both covers must also clearly and legibly identify you as the -publisher of these copies. The front cover must present the full title -with all words of the title equally prominent and visible. You may add -other material on the covers in addition. Copying with changes limited -to the covers, as long as they preserve the title of the -:ref:`Document ` and satisfy these conditions, can be -treated as verbatim copying in other respects. - -If the required texts for either cover are too voluminous to fit -legibly, you should put the first ones listed (as many as fit -reasonably) on the actual cover, and continue the rest onto adjacent -pages. - -If you publish or distribute :ref:`Opaque ` copies of -the :ref:`Document ` numbering more than 100, you must -either include a machine-readable :ref:`Transparent ` -copy along with each Opaque copy, or state in or with each Opaque copy a -publicly-accessible computer-network location containing a complete -Transparent copy of the Document, free of added material, which the -general network-using public has access to download anonymously at no -charge using public-standard network protocols. If you use the latter -option, you must take reasonably prudent steps, when you begin -distribution of Opaque copies in quantity, to ensure that this -Transparent copy will remain thus accessible at the stated location -until at least one year after the last time you distribute an Opaque -copy (directly or through your agents or retailers) of that edition to -the public. - -It is requested, but not required, that you contact the authors of the -:ref:`Document ` well before redistributing any large -number of copies, to give them a chance to provide you with an updated -version of the Document. - - -.. _fdl-section4: - -4. MODIFICATIONS -================ - -You may copy and distribute a :ref:`Modified Version ` -of the :ref:`Document ` under the conditions of sections -:ref:`2 ` and :ref:`3 ` above, provided -that you release the Modified Version under precisely this License, with -the Modified Version filling the role of the Document, thus licensing -distribution and modification of the Modified Version to whoever -possesses a copy of it. In addition, you must do these things in the -Modified Version: - -- **A.** - Use in the :ref:`Title Page ` (and on the covers, - if any) a title distinct from that of the - :ref:`Document `, and from those of previous versions - (which should, if there were any, be listed in the History section of - the Document). You may use the same title as a previous version if - the original publisher of that version gives permission. - -- **B.** - List on the :ref:`Title Page `, as authors, one or - more persons or entities responsible for authorship of the - modifications in the :ref:`Modified Version `, - together with at least five of the principal authors of the - :ref:`Document ` (all of its principal authors, if it - has less than five). - -- **C.** - State on the :ref:`Title Page ` the name of the - publisher of the :ref:`Modified Version `, as the - publisher. - -- **D.** - Preserve all the copyright notices of the - :ref:`Document `. - -- **E.** - Add an appropriate copyright notice for your modifications adjacent - to the other copyright notices. - -- **F.** - Include, immediately after the copyright notices, a license notice - giving the public permission to use the - :ref:`Modified Version ` under the terms of this - License, in the form shown in the Addendum below. - -- **G.** - Preserve in that license notice the full lists of - :ref:`Invariant Sections ` and required - :ref:`Cover Texts ` given in the - :ref:`Document's ` license notice. - -- **H.** - Include an unaltered copy of this License. - -- **I.** - Preserve the section entitled “History”, and its title, and add to it - an item stating at least the title, year, new authors, and publisher - of the :ref:`Modified Version ` as given on the - :ref:`Title Page `. If there is no section entitled - “History” in the :ref:`Document `, create one stating - the title, year, authors, and publisher of the Document as given on - its Title Page, then add an item describing the Modified Version as - stated in the previous sentence. - -- **J.** - Preserve the network location, if any, given in the - :ref:`Document ` for public access to a - :ref:`Transparent ` copy of the Document, and - likewise the network locations given in the Document for previous - versions it was based on. These may be placed in the “History” - section. You may omit a network location for a work that was - published at least four years before the Document itself, or if the - original publisher of the version it refers to gives permission. - -- **K.** - In any section entitled “Acknowledgements” or “Dedications”, preserve - the section's title, and preserve in the section all the substance - and tone of each of the contributor acknowledgements and/or - dedications given therein. - -- **L.** - Preserve all the :ref:`Invariant Sections ` of the - :ref:`Document `, unaltered in their text and in - their titles. Section numbers or the equivalent are not considered - part of the section titles. - -- **M.** - Delete any section entitled “Endorsements”. Such a section may not be - included in the :ref:`Modified Version `. - -- **N.** - Do not retitle any existing section as “Endorsements” or to conflict - in title with any :ref:`Invariant Section `. - -If the :ref:`Modified Version ` includes new -front-matter sections or appendices that qualify as -:ref:`Secondary Sections ` and contain no material -copied from the Document, you may at your option designate some or all -of these sections as invariant. To do this, add their titles to the list -of :ref:`Invariant Sections ` in the Modified Version's -license notice. These titles must be distinct from any other section -titles. - -You may add a section entitled “Endorsements”, provided it contains -nothing but endorsements of your -:ref:`Modified Version ` by various parties--for -example, statements of peer review or that the text has been approved by -an organization as the authoritative definition of a standard. - -You may add a passage of up to five words as a -:ref:`Front-Cover Text `, and a passage of up to 25 -words as a :ref:`Back-Cover Text `, to the end of the -list of :ref:`Cover Texts ` in the -:ref:`Modified Version `. Only one passage of -Front-Cover Text and one of Back-Cover Text may be added by (or through -arrangements made by) any one entity. If the -:ref:`Document ` already includes a cover text for the -same cover, previously added by you or by arrangement made by the same -entity you are acting on behalf of, you may not add another; but you may -replace the old one, on explicit permission from the previous publisher -that added the old one. - -The author(s) and publisher(s) of the :ref:`Document ` -do not by this License give permission to use their names for publicity -for or to assert or imply endorsement of any -:ref:`Modified Version `. - - -.. _fdl-section5: - -5. COMBINING DOCUMENTS -====================== - -You may combine the :ref:`Document ` with other -documents released under this License, under the terms defined in -:ref:`section 4 ` above for modified versions, provided -that you include in the combination all of the -:ref:`Invariant Sections ` of all of the original -documents, unmodified, and list them all as Invariant Sections of your -combined work in its license notice. - -The combined work need only contain one copy of this License, and -multiple identical :ref:`Invariant Sections ` may be -replaced with a single copy. If there are multiple Invariant Sections -with the same name but different contents, make the title of each such -section unique by adding at the end of it, in parentheses, the name of -the original author or publisher of that section if known, or else a -unique number. Make the same adjustment to the section titles in the -list of Invariant Sections in the license notice of the combined work. - -In the combination, you must combine any sections entitled “History” in -the various original documents, forming one section entitled “History”; -likewise combine any sections entitled “Acknowledgements”, and any -sections entitled “Dedications”. You must delete all sections entitled -“Endorsements.” - - -.. _fdl-section6: - -6. COLLECTIONS OF DOCUMENTS -=========================== - -You may make a collection consisting of the -:ref:`Document ` and other documents released under this -License, and replace the individual copies of this License in the -various documents with a single copy that is included in the collection, -provided that you follow the rules of this License for verbatim copying -of each of the documents in all other respects. - -You may extract a single document from such a collection, and 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. - - -.. _fdl-section7: - -7. AGGREGATION WITH INDEPENDENT WORKS -===================================== - -A compilation of the :ref:`Document ` or its derivatives -with other separate and independent documents or works, in or on a -volume of a storage or distribution medium, does not as a whole count as -a :ref:`Modified Version ` of the Document, provided no -compilation copyright is claimed for the compilation. Such a compilation -is called an “aggregate”, and this License does not apply to the other -self-contained works thus compiled with the Document , on account of -their being thus compiled, if they are not themselves derivative works -of the Document. If the :ref:`Cover Text ` -requirement of :ref:`section 3 ` is applicable to these -copies of the Document, then if the Document is less than one quarter of -the entire aggregate, the Document's Cover Texts may be placed on covers -that surround only the Document within the aggregate. Otherwise they -must appear on covers around the whole aggregate. - - -.. _fdl-section8: - -8. TRANSLATION -============== - -Translation is considered a kind of modification, so you may distribute -translations of the :ref:`Document ` under the terms of -:ref:`section 4 `. Replacing -:ref:`Invariant Sections ` with translations requires -special permission from their copyright holders, but you may include -translations of some or all Invariant Sections in addition to the -original versions of these Invariant Sections. You may include a -translation of this License provided that you also include the original -English version of this License. In case of a disagreement between the -translation and the original English version of this License, the -original English version will prevail. - - -.. _fdl-section9: - -9. TERMINATION -============== - -You may not copy, modify, sublicense, or distribute the -:ref:`Document ` except as expressly provided for under -this License. Any other attempt to copy, modify, sublicense or -distribute the Document is void, and will automatically terminate your -rights under this License. However, parties who have received copies, or -rights, from you under this License will not have their licenses -terminated so long as such parties remain in full compliance. - - -.. _fdl-section10: - -10. FUTURE REVISIONS OF THIS LICENSE -==================================== - -The `Free Software Foundation `__ -may publish new, revised versions of the GNU Free Documentation License -from time to time. Such new versions will be similar in spirit to the -present version, but may differ in detail to address new problems or -concerns. See -`http://www.gnu.org/copyleft/ `__. - -Each version of the License is given a distinguishing version number. If -the :ref:`Document ` specifies that a particular -numbered version of this License “or any later version” applies to it, -you have the option of following the terms and conditions either of that -specified version or of any later version that has been published (not -as a draft) by the Free Software Foundation. If the Document does not -specify a version number of this License, you may choose any version -ever published (not as a draft) by the Free Software Foundation. - - -.. _fdl-using: - -Addendum -======== - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and license -notices just after the title page: - - Copyright © YEAR YOUR NAME. - - 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; with the :ref:`Invariant Sections ` - being LIST THEIR TITLES, with the - :ref:`Front-Cover Texts ` being LIST, and with - the :ref:`Back-Cover Texts ` being LIST. A copy - of the license is included in the section entitled “GNU Free - Documentation License”. - -If you have no :ref:`Invariant Sections `, write “with -no Invariant Sections” instead of saying which ones are invariant. If -you have no :ref:`Front-Cover Texts `, write “no -Front-Cover Texts” instead of “Front-Cover Texts being LIST”; likewise -for :ref:`Back-Cover Texts `. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of free -software license, such as the -`GNU General Public License `__, -to permit their use in free software. diff --git a/Documentation/media/uapi/gen-errors.rst b/Documentation/media/uapi/gen-errors.rst deleted file mode 100644 index 043c312dc06d..000000000000 --- a/Documentation/media/uapi/gen-errors.rst +++ /dev/null @@ -1,103 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _gen_errors: - -******************* -Generic Error Codes -******************* - - -.. _gen-errors: - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: Generic error codes - :header-rows: 0 - :stub-columns: 0 - :widths: 1 16 - - - - - ``EAGAIN`` (aka ``EWOULDBLOCK``) - - - The ioctl can't be handled because the device is in state where it - can't perform it. This could happen for example in case where - device is sleeping and ioctl is performed to query statistics. It - is also returned when the ioctl would need to wait for an event, - but the device was opened in non-blocking mode. - - - - ``EBADF`` - - - The file descriptor is not a valid. - - - - ``EBUSY`` - - - The ioctl can't be handled because the device is busy. This is - typically return while device is streaming, and an ioctl tried to - change something that would affect the stream, or would require - the usage of a hardware resource that was already allocated. The - ioctl must not be retried without performing another action to fix - the problem first (typically: stop the stream before retrying). - - - - ``EFAULT`` - - - There was a failure while copying data from/to userspace, probably - caused by an invalid pointer reference. - - - - ``EINVAL`` - - - One or more of the ioctl parameters are invalid or out of the - allowed range. This is a widely used error code. See the - individual ioctl requests for specific causes. - - - - ``ENODEV`` - - - Device not found or was removed. - - - - ``ENOMEM`` - - - There's not enough memory to handle the desired operation. - - - - ``ENOTTY`` - - - The ioctl is not supported by the driver, actually meaning that - the required functionality is not available, or the file - descriptor is not for a media device. - - - - ``ENOSPC`` - - - On USB devices, the stream ioctl's can return this error, meaning - that this request would overcommit the usb bandwidth reserved for - periodic transfers (up to 80% of the USB bandwidth). - - - - ``EPERM`` - - - Permission denied. Can be returned if the device needs write - permission, or some special capabilities is needed (e. g. root) - - - - ``EIO`` - - - I/O error. Typically used when there are problems communicating with - a hardware device. This could indicate broken or flaky hardware. - It's a 'Something is wrong, I give up!' type of error. - - - - ``ENXIO`` - - - No device corresponding to this device special file exists. - - -.. note:: - - #. This list is not exhaustive; ioctls may return other error codes. - Since errors may have side effects such as a driver reset, - applications should abort on unexpected errors, or otherwise - assume that the device is in a bad state. - - #. Request-specific error codes are listed in the individual - requests descriptions. diff --git a/Documentation/media/uapi/mediactl/media-controller-intro.rst b/Documentation/media/uapi/mediactl/media-controller-intro.rst deleted file mode 100644 index 281c559c2f3c..000000000000 --- a/Documentation/media/uapi/mediactl/media-controller-intro.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-controller-intro: - -Introduction -============ - -Media devices increasingly handle multiple related functions. Many USB -cameras include microphones, video capture hardware can also output -video, or SoC camera interfaces also perform memory-to-memory operations -similar to video codecs. - -Independent functions, even when implemented in the same hardware, can -be modelled as separate devices. A USB camera with a microphone will be -presented to userspace applications as V4L2 and ALSA capture devices. -The devices' relationships (when using a webcam, end-users shouldn't -have to manually select the associated USB microphone), while not made -available directly to applications by the drivers, can usually be -retrieved from sysfs. - -With more and more advanced SoC devices being introduced, the current -approach will not scale. Device topologies are getting increasingly -complex and can't always be represented by a tree structure. Hardware -blocks are shared between different functions, creating dependencies -between seemingly unrelated devices. - -Kernel abstraction APIs such as V4L2 and ALSA provide means for -applications to access hardware parameters. As newer hardware expose an -increasingly high number of those parameters, drivers need to guess what -applications really require based on limited information, thereby -implementing policies that belong to userspace. - -The media controller API aims at solving those problems. diff --git a/Documentation/media/uapi/mediactl/media-controller-model.rst b/Documentation/media/uapi/mediactl/media-controller-model.rst deleted file mode 100644 index b6d5902b556d..000000000000 --- a/Documentation/media/uapi/mediactl/media-controller-model.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-controller-model: - -Media device model -================== - -Discovering a device internal topology, and configuring it at runtime, -is one of the goals of the media controller API. To achieve this, -hardware devices and Linux Kernel interfaces are modelled as graph -objects on an oriented graph. The object types that constitute the graph -are: - -- An **entity** is a basic media hardware or software 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. - -- An **interface** is a graph representation of a Linux Kernel - userspace API interface, like a device node or a sysfs file that - controls one or more entities in the graph. - -- A **pad** is a data 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 **data 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. - -- An **interface link** is a point-to-point bidirectional control - connection between a Linux Kernel interface and an entity. diff --git a/Documentation/media/uapi/mediactl/media-controller.rst b/Documentation/media/uapi/mediactl/media-controller.rst deleted file mode 100644 index 6e624f690331..000000000000 --- a/Documentation/media/uapi/mediactl/media-controller.rst +++ /dev/null @@ -1,62 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. include:: - -.. _media_controller: - -############################## -Part IV - Media Controller API -############################## - -.. only:: html - - .. class:: toc-title - - Table of Contents - -.. toctree:: - :maxdepth: 5 - :numbered: - - media-controller-intro - media-controller-model - media-types - request-api - media-funcs - media-header - - -********************** -Revision and Copyright -********************** - -Authors: - -- Pinchart, Laurent - - - Initial version. - -- Carvalho Chehab, Mauro - - - MEDIA_IOC_G_TOPOLOGY documentation and documentation improvements. - -**Copyright** |copy| 2010 : Laurent Pinchart - -**Copyright** |copy| 2015-2016 : Mauro Carvalho Chehab - -**************** -Revision History -**************** - -:revision: 1.1.0 / 2015-12-12 (*mcc*) - -:revision: 1.0.0 / 2010-11-10 (*lp*) - -Initial revision diff --git a/Documentation/media/uapi/mediactl/media-func-close.rst b/Documentation/media/uapi/mediactl/media-func-close.rst deleted file mode 100644 index 369ccd4dee56..000000000000 --- a/Documentation/media/uapi/mediactl/media-func-close.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-func-close: - -************* -media close() -************* - -Name -==== - -media-close - Close a media device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int close( int fd ) - :name: mc-close - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - - -Description -=========== - -Closes the media device. Resources associated with the file descriptor -are freed. The device configuration remain unchanged. - - -Return Value -============ - -:ref:`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. diff --git a/Documentation/media/uapi/mediactl/media-func-ioctl.rst b/Documentation/media/uapi/mediactl/media-func-ioctl.rst deleted file mode 100644 index 9a990d6480f5..000000000000 --- a/Documentation/media/uapi/mediactl/media-func-ioctl.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-func-ioctl: - -************* -media ioctl() -************* - -Name -==== - -media-ioctl - Control a media device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int ioctl( int fd, int request, void *argp ) - :name: mc-ioctl - -Arguments -========= - -``fd`` - File descriptor returned by :c:func:`open() `. - -``request`` - Media ioctl request code as defined in the media.h header file, for - example MEDIA_IOC_SETUP_LINK. - -``argp`` - Pointer to a request-specific structure. - - -Description -=========== - -The :ref:`ioctl() ` function manipulates media device -parameters. The argument ``fd`` must be an open file descriptor. - -The ioctl ``request`` code specifies the media 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 media ioctl requests and -their parameters are located in the media.h header file. All media ioctl -requests, their respective function and parameters are specified in -:ref:`media-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 ` 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. diff --git a/Documentation/media/uapi/mediactl/media-func-open.rst b/Documentation/media/uapi/mediactl/media-func-open.rst deleted file mode 100644 index cd2f840ddf73..000000000000 --- a/Documentation/media/uapi/mediactl/media-func-open.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-func-open: - -************ -media open() -************ - -Name -==== - -media-open - Open a media device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int open( const char *device_name, int flags ) - :name: mc-open - -Arguments -========= - -``device_name`` - Device to be opened. - -``flags`` - Open flags. Access mode must be either ``O_RDONLY`` or ``O_RDWR``. - Other flags have no effect. - - -Description -=========== - -To open a media device applications call :ref:`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 -============ - -:ref:`open() ` returns the new file descriptor on success. On error, --1 is returned, and ``errno`` is set appropriately. Possible error codes -are: - -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. diff --git a/Documentation/media/uapi/mediactl/media-funcs.rst b/Documentation/media/uapi/mediactl/media-funcs.rst deleted file mode 100644 index 87b65df8252a..000000000000 --- a/Documentation/media/uapi/mediactl/media-funcs.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-user-func: - -****************** -Function Reference -****************** - - -.. toctree:: - :maxdepth: 1 - - media-func-open - media-func-close - media-func-ioctl - media-ioc-device-info - media-ioc-g-topology - media-ioc-enum-entities - media-ioc-enum-links - media-ioc-setup-link - media-ioc-request-alloc - request-func-close - request-func-ioctl - request-func-poll - media-request-ioc-queue - media-request-ioc-reinit diff --git a/Documentation/media/uapi/mediactl/media-header.rst b/Documentation/media/uapi/mediactl/media-header.rst deleted file mode 100644 index 1cb7c88aeff0..000000000000 --- a/Documentation/media/uapi/mediactl/media-header.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_header: - -**************************** -Media Controller Header File -**************************** - -.. kernel-include:: $BUILDDIR/media.h.rst - diff --git a/Documentation/media/uapi/mediactl/media-ioc-device-info.rst b/Documentation/media/uapi/mediactl/media-ioc-device-info.rst deleted file mode 100644 index f8038cfb708c..000000000000 --- a/Documentation/media/uapi/mediactl/media-ioc-device-info.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_ioc_device_info: - -*************************** -ioctl MEDIA_IOC_DEVICE_INFO -*************************** - -Name -==== - -MEDIA_IOC_DEVICE_INFO - Query device information - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp ) - :name: MEDIA_IOC_DEVICE_INFO - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`media_device_info`. - - -Description -=========== - -All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To -query device information, applications call the ioctl with a pointer to -a struct :c:type:`media_device_info`. The driver -fills the structure and returns the information to the application. The -ioctl never fails. - - -.. c:type:: media_device_info - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: struct media_device_info - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - - * - char - - ``driver``\ [16] - - Name of the driver implementing the media API as a NUL-terminated - ASCII string. The driver version is stored in the - ``driver_version`` field. - - Driver specific applications can use this information to verify - the driver identity. It is also useful to work around known bugs, - or to identify drivers in error reports. - - * - char - - ``model``\ [32] - - Device model name as a NUL-terminated UTF-8 string. The device - version is stored in the ``device_version`` field and is not be - appended to the model name. - - * - char - - ``serial``\ [40] - - Serial number as a NUL-terminated ASCII string. - - * - char - - ``bus_info``\ [32] - - Location of the device in the system as a NUL-terminated ASCII - string. This includes the bus type name (PCI, USB, ...) and a - bus-specific identifier. - - * - __u32 - - ``media_version`` - - Media API version, formatted with the ``KERNEL_VERSION()`` macro. - - * - __u32 - - ``hw_revision`` - - Hardware device revision in a driver-specific format. - - * - __u32 - - ``driver_version`` - - Media device driver version, formatted with the - ``KERNEL_VERSION()`` macro. Together with the ``driver`` field - this identifies a particular driver. - - * - __u32 - - ``reserved``\ [31] - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - -The ``serial`` and ``bus_info`` fields can be used to distinguish -between multiple instances of otherwise identical hardware. The serial -number takes precedence when provided and can be assumed to be unique. -If the serial number is an empty string, the ``bus_info`` field can be -used instead. The ``bus_info`` field is guaranteed to be unique, but can -vary across reboots or device unplug/replug. - - -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 ` chapter. diff --git a/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst b/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst deleted file mode 100644 index 33e2b110145c..000000000000 --- a/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst +++ /dev/null @@ -1,156 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_ioc_enum_entities: - -***************************** -ioctl MEDIA_IOC_ENUM_ENTITIES -***************************** - -Name -==== - -MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp ) - :name: MEDIA_IOC_ENUM_ENTITIES - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`media_entity_desc`. - - -Description -=========== - -To query the attributes of an entity, applications set the id field of a -struct :c:type:`media_entity_desc` structure and -call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this -structure. The driver fills the rest of the structure or returns an -EINVAL error code when the id is invalid. - -.. _media-ent-id-flag-next: - -Entities can be enumerated by or'ing the id with the -``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information -about the entity with the smallest id strictly larger than the requested -one ('next entity'), or the ``EINVAL`` error code if there is none. - -Entity IDs can be non-contiguous. Applications must *not* try to -enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing -id's until they get an error. - - -.. c:type:: media_entity_desc - -.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{11.2cm}| - -.. flat-table:: struct media_entity_desc - :header-rows: 0 - :stub-columns: 0 - :widths: 2 2 1 8 - - * - __u32 - - ``id`` - - - - Entity ID, set by the application. When the ID is or'ed with - ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns - the first entity with a larger ID. Do not expect that the ID will - always be the same for each instance of the device. In other words, - do not hardcode entity IDs in an application. - - * - char - - ``name``\ [32] - - - - Entity name as an UTF-8 NULL-terminated string. This name must be unique - within the media topology. - - * - __u32 - - ``type`` - - - - Entity type, see :ref:`media-entity-functions` for details. - - * - __u32 - - ``revision`` - - - - Entity revision. Always zero (obsolete) - - * - __u32 - - ``flags`` - - - - Entity flags, see :ref:`media-entity-flag` for details. - - * - __u32 - - ``group_id`` - - - - Entity group ID. Always zero (obsolete) - - * - __u16 - - ``pads`` - - - - Number of pads - - * - __u16 - - ``links`` - - - - Total number of outbound links. Inbound links are not counted in - this field. - - * - __u32 - - ``reserved[4]`` - - - - Reserved for future extensions. Drivers and applications must set - the array to zero. - - * - union { - - (anonymous) - - * - struct - - ``dev`` - - - - Valid for (sub-)devices that create a single device node. - - * - - - __u32 - - ``major`` - - Device node major number. - - * - - - __u32 - - ``minor`` - - Device node minor number. - - * - __u8 - - ``raw``\ [184] - - - - - * - } - - - - -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 ` chapter. - -EINVAL - The struct :c:type:`media_entity_desc` ``id`` - references a non-existing entity. diff --git a/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst deleted file mode 100644 index b827ebc398f8..000000000000 --- a/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst +++ /dev/null @@ -1,157 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_ioc_enum_links: - -************************** -ioctl MEDIA_IOC_ENUM_LINKS -************************** - -Name -==== - -MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp ) - :name: MEDIA_IOC_ENUM_LINKS - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`media_links_enum`. - - -Description -=========== - -To enumerate pads and/or links for a given entity, applications set the -entity field of a struct :c:type:`media_links_enum` -structure and initialize the struct -:c:type:`media_pad_desc` and struct -:c:type:`media_link_desc` structure arrays pointed by -the ``pads`` and ``links`` fields. They then call the -MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure. - -If the ``pads`` field is not NULL, the driver fills the ``pads`` array -with information about the entity's pads. The array must have enough -room to store all the entity's pads. The number of pads can be retrieved -with :ref:`MEDIA_IOC_ENUM_ENTITIES`. - -If the ``links`` field is not NULL, the driver fills the ``links`` array -with information about the entity's outbound links. The array must have -enough room to store all the entity's outbound links. The number of -outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`. - -Only forward links that originate at one of the entity's source pads are -returned during the enumeration process. - - -.. c:type:: media_links_enum - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: struct media_links_enum - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``entity`` - - Entity id, set by the application. - - * - struct :c:type:`media_pad_desc` - - \*\ ``pads`` - - Pointer to a pads array allocated by the application. Ignored if - NULL. - - * - struct :c:type:`media_link_desc` - - \*\ ``links`` - - Pointer to a links array allocated by the application. Ignored if - NULL. - - * - __u32 - - ``reserved[4]`` - - Reserved for future extensions. Drivers and applications must set - the array to zero. - - -.. c:type:: media_pad_desc - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: struct media_pad_desc - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``entity`` - - ID of the entity this pad belongs to. - - * - __u16 - - ``index`` - - Pad index, starts at 0. - - * - __u32 - - ``flags`` - - Pad flags, see :ref:`media-pad-flag` for more details. - - * - __u32 - - ``reserved[2]`` - - Reserved for future extensions. Drivers and applications must set - the array to zero. - - - -.. c:type:: media_link_desc - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: struct media_link_desc - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - struct :c:type:`media_pad_desc` - - ``source`` - - Pad at the origin of this link. - - * - struct :c:type:`media_pad_desc` - - ``sink`` - - Pad at the target of this link. - - * - __u32 - - ``flags`` - - Link flags, see :ref:`media-link-flag` for more details. - - * - __u32 - - ``reserved[2]`` - - Reserved for future extensions. Drivers and applications must set - the array to zero. - - -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 ` chapter. - -EINVAL - The struct :c:type:`media_links_enum` ``id`` - references a non-existing entity. diff --git a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst deleted file mode 100644 index 0a7d76ac8ded..000000000000 --- a/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst +++ /dev/null @@ -1,307 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_ioc_g_topology: - -************************** -ioctl MEDIA_IOC_G_TOPOLOGY -************************** - -Name -==== - -MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp ) - :name: MEDIA_IOC_G_TOPOLOGY - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`media_v2_topology`. - - -Description -=========== - -The typical usage of this ioctl is to call it twice. On the first call, -the structure defined at struct -:c:type:`media_v2_topology` should be zeroed. At -return, if no errors happen, this ioctl will return the -``topology_version`` and the total number of entities, interfaces, pads -and links. - -Before the second call, the userspace should allocate arrays to store -the graph elements that are desired, putting the pointers to them at the -ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the -other values untouched. - -If the ``topology_version`` remains the same, the ioctl should fill the -desired arrays with the media graph elements. - -.. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.5cm}| - -.. c:type:: media_v2_topology - -.. flat-table:: struct media_v2_topology - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 8 - - * - __u64 - - ``topology_version`` - - Version of the media graph topology. When the graph is created, - this field starts with zero. Every time a graph element is added - or removed, this field is incremented. - - * - __u32 - - ``num_entities`` - - Number of entities in the graph - - * - __u32 - - ``reserved1`` - - Applications and drivers shall set this to 0. - - * - __u64 - - ``ptr_entities`` - - A pointer to a memory area where the entities array will be - stored, converted to a 64-bits integer. It can be zero. if zero, - the ioctl won't store the entities. It will just update - ``num_entities`` - - * - __u32 - - ``num_interfaces`` - - Number of interfaces in the graph - - * - __u32 - - ``reserved2`` - - Applications and drivers shall set this to 0. - - * - __u64 - - ``ptr_interfaces`` - - A pointer to a memory area where the interfaces array will be - stored, converted to a 64-bits integer. It can be zero. if zero, - the ioctl won't store the interfaces. It will just update - ``num_interfaces`` - - * - __u32 - - ``num_pads`` - - Total number of pads in the graph - - * - __u32 - - ``reserved3`` - - Applications and drivers shall set this to 0. - - * - __u64 - - ``ptr_pads`` - - A pointer to a memory area where the pads array will be stored, - converted to a 64-bits integer. It can be zero. if zero, the ioctl - won't store the pads. It will just update ``num_pads`` - - * - __u32 - - ``num_links`` - - Total number of data and interface links in the graph - - * - __u32 - - ``reserved4`` - - Applications and drivers shall set this to 0. - - * - __u64 - - ``ptr_links`` - - A pointer to a memory area where the links array will be stored, - converted to a 64-bits integer. It can be zero. if zero, the ioctl - won't store the links. It will just update ``num_links`` - - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| - -.. c:type:: media_v2_entity - -.. flat-table:: struct media_v2_entity - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 8 - - * - __u32 - - ``id`` - - Unique ID for the entity. Do not expect that the ID will - always be the same for each instance of the device. In other words, - do not hardcode entity IDs in an application. - - * - char - - ``name``\ [64] - - Entity name as an UTF-8 NULL-terminated string. This name must be unique - within the media topology. - - * - __u32 - - ``function`` - - Entity main function, see :ref:`media-entity-functions` for details. - - * - __u32 - - ``flags`` - - Entity flags, see :ref:`media-entity-flag` for details. - Only valid if ``MEDIA_V2_ENTITY_HAS_FLAGS(media_version)`` - returns true. The ``media_version`` is defined in struct - :c:type:`media_device_info` and can be retrieved using - :ref:`MEDIA_IOC_DEVICE_INFO`. - - * - __u32 - - ``reserved``\ [5] - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| - -.. c:type:: media_v2_interface - -.. flat-table:: struct media_v2_interface - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 8 - - * - __u32 - - ``id`` - - Unique ID for the interface. Do not expect that the ID will - always be the same for each instance of the device. In other words, - do not hardcode interface IDs in an application. - - * - __u32 - - ``intf_type`` - - Interface type, see :ref:`media-intf-type` for details. - - * - __u32 - - ``flags`` - - Interface flags. Currently unused. - - * - __u32 - - ``reserved``\ [9] - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - * - struct media_v2_intf_devnode - - ``devnode`` - - Used only for device node interfaces. See - :c:type:`media_v2_intf_devnode` for details. - - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| - -.. c:type:: media_v2_intf_devnode - -.. flat-table:: struct media_v2_intf_devnode - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 8 - - * - __u32 - - ``major`` - - Device node major number. - - * - __u32 - - ``minor`` - - Device node minor number. - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| - -.. c:type:: media_v2_pad - -.. flat-table:: struct media_v2_pad - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 8 - - * - __u32 - - ``id`` - - Unique ID for the pad. Do not expect that the ID will - always be the same for each instance of the device. In other words, - do not hardcode pad IDs in an application. - - * - __u32 - - ``entity_id`` - - Unique ID for the entity where this pad belongs. - - * - __u32 - - ``flags`` - - Pad flags, see :ref:`media-pad-flag` for more details. - - * - __u32 - - ``index`` - - Pad index, starts at 0. Only valid if ``MEDIA_V2_PAD_HAS_INDEX(media_version)`` - returns true. The ``media_version`` is defined in struct - :c:type:`media_device_info` and can be retrieved using - :ref:`MEDIA_IOC_DEVICE_INFO`. - - * - __u32 - - ``reserved``\ [4] - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - -.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.7cm}| - -.. c:type:: media_v2_link - -.. flat-table:: struct media_v2_link - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 8 - - * - __u32 - - ``id`` - - Unique ID for the link. Do not expect that the ID will - always be the same for each instance of the device. In other words, - do not hardcode link IDs in an application. - - * - __u32 - - ``source_id`` - - On pad to pad links: unique ID for the source pad. - - On interface to entity links: unique ID for the interface. - - * - __u32 - - ``sink_id`` - - On pad to pad links: unique ID for the sink pad. - - On interface to entity links: unique ID for the entity. - - * - __u32 - - ``flags`` - - Link flags, see :ref:`media-link-flag` for more details. - - * - __u32 - - ``reserved``\ [6] - - Reserved for future extensions. Drivers and applications must set - this array to zero. - - -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 ` chapter. - -ENOSPC - This is returned when either one or more of the num_entities, - num_interfaces, num_links or num_pads are non-zero and are - smaller than the actual number of elements inside the graph. This - may happen if the ``topology_version`` changed when compared to the - last time this ioctl was called. Userspace should usually free the - area for the pointers, zero the struct elements and call this ioctl - again. diff --git a/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst deleted file mode 100644 index 6d4ca4ada2e0..000000000000 --- a/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst +++ /dev/null @@ -1,90 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_ioc_request_alloc: - -***************************** -ioctl MEDIA_IOC_REQUEST_ALLOC -***************************** - -Name -==== - -MEDIA_IOC_REQUEST_ALLOC - Allocate a request - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp ) - :name: MEDIA_IOC_REQUEST_ALLOC - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to an integer. - - -Description -=========== - -If the media device supports :ref:`requests `, then -this ioctl can be used to allocate a request. If it is not supported, then -``errno`` is set to ``ENOTTY``. A request is accessed through a file descriptor -that is returned in ``*argp``. - -If the request was successfully allocated, then the request file descriptor -can be passed to the :ref:`VIDIOC_QBUF `, -:ref:`VIDIOC_G_EXT_CTRLS `, -:ref:`VIDIOC_S_EXT_CTRLS ` and -:ref:`VIDIOC_TRY_EXT_CTRLS ` ioctls. - -In addition, the request can be queued by calling -:ref:`MEDIA_REQUEST_IOC_QUEUE` and re-initialized by calling -:ref:`MEDIA_REQUEST_IOC_REINIT`. - -Finally, the file descriptor can be :ref:`polled ` to wait -for the request to complete. - -The request will remain allocated until all the file descriptors associated -with it are closed by :ref:`close() ` and the driver no -longer uses the request internally. See also -:ref:`here ` for more information. - -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 ` chapter. - -ENOTTY - The driver has no support for requests. diff --git a/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst b/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst deleted file mode 100644 index ae39dbbe48a0..000000000000 --- a/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_ioc_setup_link: - -************************** -ioctl MEDIA_IOC_SETUP_LINK -************************** - -Name -==== - -MEDIA_IOC_SETUP_LINK - Modify the properties of a link - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp ) - :name: MEDIA_IOC_SETUP_LINK - - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`open() `. - -``argp`` - Pointer to struct :c:type:`media_link_desc`. - - -Description -=========== - -To change link properties applications fill a struct -:c:type:`media_link_desc` with link identification -information (source and sink pad) and the new requested link flags. They -then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to that -structure. - -The only configurable property is the ``ENABLED`` link flag to -enable/disable a link. Links marked with the ``IMMUTABLE`` link flag can -not be enabled or disabled. - -Link configuration has no side effect on other links. If an enabled link -at the sink pad prevents the link from being enabled, the driver returns -with an ``EBUSY`` error code. - -Only links marked with the ``DYNAMIC`` link flag can be enabled/disabled -while streaming media data. Attempting to enable or disable a streaming -non-dynamic link will return an ``EBUSY`` error code. - -If the specified link can't be found the driver returns with an ``EINVAL`` -error code. - - -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 ` chapter. - -EINVAL - The struct :c:type:`media_link_desc` references a - non-existing link, or the link is immutable and an attempt to modify - its configuration was made. diff --git a/Documentation/media/uapi/mediactl/media-request-ioc-queue.rst b/Documentation/media/uapi/mediactl/media-request-ioc-queue.rst deleted file mode 100644 index fc8458746d51..000000000000 --- a/Documentation/media/uapi/mediactl/media-request-ioc-queue.rst +++ /dev/null @@ -1,102 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_request_ioc_queue: - -***************************** -ioctl MEDIA_REQUEST_IOC_QUEUE -***************************** - -Name -==== - -MEDIA_REQUEST_IOC_QUEUE - Queue a request - - -Synopsis -======== - -.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE ) - :name: MEDIA_REQUEST_IOC_QUEUE - - -Arguments -========= - -``request_fd`` - File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. - - -Description -=========== - -If the media device supports :ref:`requests `, then -this request ioctl can be used to queue a previously allocated request. - -If the request was successfully queued, then the file descriptor can be -:ref:`polled ` to wait for the request to complete. - -If the request was already queued before, then ``EBUSY`` is returned. -Other errors can be returned if the contents of the request contained -invalid or inconsistent data, see the next section for a list of -common error codes. On error both the request and driver state are unchanged. - -Once a request is queued, then the driver is required to gracefully handle -errors that occur when the request is applied to the hardware. The -exception is the ``EIO`` error which signals a fatal error that requires -the application to stop streaming to reset the hardware state. - -It is not allowed to mix queuing requests with queuing buffers directly -(without a request). ``EBUSY`` will be returned if the first buffer was -queued directly and you next try to queue a request, or vice versa. - -A request must contain at least one buffer, otherwise this ioctl will -return an ``ENOENT`` error. - -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 ` chapter. - -EBUSY - The request was already queued or the application queued the first - buffer directly, but later attempted to use a request. It is not permitted - to mix the two APIs. -ENOENT - The request did not contain any buffers. All requests are required - to have at least one buffer. This can also be returned if some required - configuration is missing in the request. -ENOMEM - Out of memory when allocating internal data structures for this - request. -EINVAL - The request has invalid data. -EIO - The hardware is in a bad state. To recover, the application needs to - stop streaming to reset the hardware state and then try to restart - streaming. diff --git a/Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst b/Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst deleted file mode 100644 index 61381e87665a..000000000000 --- a/Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _media_request_ioc_reinit: - -****************************** -ioctl MEDIA_REQUEST_IOC_REINIT -****************************** - -Name -==== - -MEDIA_REQUEST_IOC_REINIT - Re-initialize a request - - -Synopsis -======== - -.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_REINIT ) - :name: MEDIA_REQUEST_IOC_REINIT - - -Arguments -========= - -``request_fd`` - File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. - -Description -=========== - -If the media device supports :ref:`requests `, then -this request ioctl can be used to re-initialize a previously allocated -request. - -Re-initializing a request will clear any existing data from the request. -This avoids having to :ref:`close() ` a completed -request and allocate a new request. Instead the completed request can just -be re-initialized and it is ready to be used again. - -A request can only be re-initialized if it either has not been queued -yet, or if it was queued and completed. Otherwise it will set ``errno`` -to ``EBUSY``. No other error codes can be returned. - -Return Value -============ - -On success 0 is returned, on error -1 and the ``errno`` variable is set -appropriately. - -EBUSY - The request is queued but not yet completed. diff --git a/Documentation/media/uapi/mediactl/media-types.rst b/Documentation/media/uapi/mediactl/media-types.rst deleted file mode 100644 index 3af6a414b501..000000000000 --- a/Documentation/media/uapi/mediactl/media-types.rst +++ /dev/null @@ -1,425 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-controller-types: - -Types and flags used to represent the media graph elements -========================================================== - -.. tabularcolumns:: |p{8.2cm}|p{10.3cm}| - -.. _media-entity-functions: -.. _MEDIA-ENT-F-UNKNOWN: -.. _MEDIA-ENT-F-V4L2-SUBDEV-UNKNOWN: -.. _MEDIA-ENT-F-IO-V4L: -.. _MEDIA-ENT-F-IO-VBI: -.. _MEDIA-ENT-F-IO-SWRADIO: -.. _MEDIA-ENT-F-IO-DTV: -.. _MEDIA-ENT-F-DTV-DEMOD: -.. _MEDIA-ENT-F-TS-DEMUX: -.. _MEDIA-ENT-F-DTV-CA: -.. _MEDIA-ENT-F-DTV-NET-DECAP: -.. _MEDIA-ENT-F-CONN-RF: -.. _MEDIA-ENT-F-CONN-SVIDEO: -.. _MEDIA-ENT-F-CONN-COMPOSITE: -.. _MEDIA-ENT-F-CAM-SENSOR: -.. _MEDIA-ENT-F-FLASH: -.. _MEDIA-ENT-F-LENS: -.. _MEDIA-ENT-F-ATV-DECODER: -.. _MEDIA-ENT-F-TUNER: -.. _MEDIA-ENT-F-IF-VID-DECODER: -.. _MEDIA-ENT-F-IF-AUD-DECODER: -.. _MEDIA-ENT-F-AUDIO-CAPTURE: -.. _MEDIA-ENT-F-AUDIO-PLAYBACK: -.. _MEDIA-ENT-F-AUDIO-MIXER: -.. _MEDIA-ENT-F-PROC-VIDEO-COMPOSER: -.. _MEDIA-ENT-F-PROC-VIDEO-PIXEL-FORMATTER: -.. _MEDIA-ENT-F-PROC-VIDEO-PIXEL-ENC-CONV: -.. _MEDIA-ENT-F-PROC-VIDEO-LUT: -.. _MEDIA-ENT-F-PROC-VIDEO-SCALER: -.. _MEDIA-ENT-F-PROC-VIDEO-STATISTICS: -.. _MEDIA-ENT-F-PROC-VIDEO-ENCODER: -.. _MEDIA-ENT-F-PROC-VIDEO-DECODER: -.. _MEDIA-ENT-F-VID-MUX: -.. _MEDIA-ENT-F-VID-IF-BRIDGE: -.. _MEDIA-ENT-F-DV-DECODER: -.. _MEDIA-ENT-F-DV-ENCODER: - -.. cssclass:: longtable - -.. flat-table:: Media entity functions - :header-rows: 0 - :stub-columns: 0 - - * - ``MEDIA_ENT_F_UNKNOWN`` and - ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN`` - - Unknown entity. That generally indicates that a driver didn't - initialize properly the entity, which is a Kernel bug - - * - ``MEDIA_ENT_F_IO_V4L`` - - Data streaming input and/or output entity. - - * - ``MEDIA_ENT_F_IO_VBI`` - - V4L VBI streaming input or output entity - - * - ``MEDIA_ENT_F_IO_SWRADIO`` - - V4L Software Digital Radio (SDR) streaming input or output entity - - * - ``MEDIA_ENT_F_IO_DTV`` - - DVB Digital TV streaming input or output entity - - * - ``MEDIA_ENT_F_DTV_DEMOD`` - - Digital TV demodulator entity. - - * - ``MEDIA_ENT_F_TS_DEMUX`` - - MPEG Transport stream demux entity. Could be implemented on - hardware or in Kernelspace by the Linux DVB subsystem. - - * - ``MEDIA_ENT_F_DTV_CA`` - - Digital TV Conditional Access module (CAM) entity - - * - ``MEDIA_ENT_F_DTV_NET_DECAP`` - - Digital TV network ULE/MLE desencapsulation entity. Could be - implemented on hardware or in Kernelspace - - * - ``MEDIA_ENT_F_CONN_RF`` - - Connector for a Radio Frequency (RF) signal. - - * - ``MEDIA_ENT_F_CONN_SVIDEO`` - - Connector for a S-Video signal. - - * - ``MEDIA_ENT_F_CONN_COMPOSITE`` - - Connector for a RGB composite signal. - - * - ``MEDIA_ENT_F_CAM_SENSOR`` - - Camera video sensor entity. - - * - ``MEDIA_ENT_F_FLASH`` - - Flash controller entity. - - * - ``MEDIA_ENT_F_LENS`` - - Lens controller entity. - - * - ``MEDIA_ENT_F_ATV_DECODER`` - - Analog video decoder, the basic function of the video decoder is - to accept analogue video from a wide variety of sources such as - broadcast, DVD players, cameras and video cassette recorders, in - either NTSC, PAL, SECAM or HD format, separating the stream into - its component parts, luminance and chrominance, and output it in - some digital video standard, with appropriate timing signals. - - * - ``MEDIA_ENT_F_TUNER`` - - Digital TV, analog TV, radio and/or software radio tuner, with - consists on a PLL tuning stage that converts radio frequency (RF) - signal into an Intermediate Frequency (IF). Modern tuners have - internally IF-PLL decoders for audio and video, but older models - have those stages implemented on separate entities. - - * - ``MEDIA_ENT_F_IF_VID_DECODER`` - - IF-PLL video decoder. It receives the IF from a PLL and decodes - the analog TV video signal. This is commonly found on some very - old analog tuners, like Philips MK3 designs. They all contain a - tda9887 (or some software compatible similar chip, like tda9885). - Those devices use a different I2C address than the tuner PLL. - - * - ``MEDIA_ENT_F_IF_AUD_DECODER`` - - IF-PLL sound decoder. It receives the IF from a PLL and decodes - the analog TV audio signal. This is commonly found on some very - old analog hardware, like Micronas msp3400, Philips tda9840, - tda985x, etc. Those devices use a different I2C address than the - tuner PLL and should be controlled together with the IF-PLL video - decoder. - - * - ``MEDIA_ENT_F_AUDIO_CAPTURE`` - - Audio Capture Function Entity. - - * - ``MEDIA_ENT_F_AUDIO_PLAYBACK`` - - Audio Playback Function Entity. - - * - ``MEDIA_ENT_F_AUDIO_MIXER`` - - Audio Mixer Function Entity. - - * - ``MEDIA_ENT_F_PROC_VIDEO_COMPOSER`` - - Video composer (blender). An entity capable of video - composing must have at least two sink pads and one source - pad, and composes input video frames onto output video - frames. Composition can be performed using alpha blending, - color keying, raster operations (ROP), stitching or any other - means. - - * - ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_FORMATTER`` - - Video pixel formatter. An entity capable of pixel formatting - must have at least one sink pad and one source pad. Read - pixel formatters read pixels from memory and perform a subset - of unpacking, cropping, color keying, alpha multiplication - and pixel encoding conversion. Write pixel formatters perform - a subset of dithering, pixel encoding conversion and packing - and write pixels to memory. - - * - ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_ENC_CONV`` - - Video pixel encoding converter. An entity capable of pixel - encoding conversion must have at least one sink pad and one - source pad, and convert the encoding of pixels received on - its sink pad(s) to a different encoding output on its source - pad(s). Pixel encoding conversion includes but isn't limited - to RGB to/from HSV, RGB to/from YUV and CFA (Bayer) to RGB - conversions. - - * - ``MEDIA_ENT_F_PROC_VIDEO_LUT`` - - Video look-up table. An entity capable of video lookup table - processing must have one sink pad and one source pad. It uses - the values of the pixels received on its sink pad to look up - entries in internal tables and output them on its source pad. - The lookup processing can be performed on all components - separately or combine them for multi-dimensional table - lookups. - - * - ``MEDIA_ENT_F_PROC_VIDEO_SCALER`` - - Video scaler. An entity capable of video scaling must have - at least one sink pad and one source pad, and scale the - video frame(s) received on its sink pad(s) to a different - resolution output on its source pad(s). The range of - supported scaling ratios is entity-specific and can differ - between the horizontal and vertical directions (in particular - scaling can be supported in one direction only). Binning and - sub-sampling (occasionally also referred to as skipping) are - considered as scaling. - - * - ``MEDIA_ENT_F_PROC_VIDEO_STATISTICS`` - - Video statistics computation (histogram, 3A, etc.). An entity - capable of statistics computation must have one sink pad and - one source pad. It computes statistics over the frames - received on its sink pad and outputs the statistics data on - its source pad. - - * - ``MEDIA_ENT_F_PROC_VIDEO_ENCODER`` - - Video (MPEG, HEVC, VPx, etc.) encoder. An entity capable of - compressing video frames. Must have one sink pad and at least - one source pad. - - * - ``MEDIA_ENT_F_PROC_VIDEO_DECODER`` - - Video (MPEG, HEVC, VPx, etc.) decoder. An entity capable of - decompressing a compressed video stream into uncompressed video - frames. Must have one sink pad and at least one source pad. - - * - ``MEDIA_ENT_F_VID_MUX`` - - Video multiplexer. An entity capable of multiplexing must have at - least two sink pads and one source pad, and must pass the video - frame(s) received from the active sink pad to the source pad. - - * - ``MEDIA_ENT_F_VID_IF_BRIDGE`` - - Video interface bridge. A video interface bridge entity must have at - least one sink pad and at least one source pad. It receives video - frames on its sink pad from an input video bus of one type (HDMI, eDP, - MIPI CSI-2, etc.), and outputs them on its source pad to an output - video bus of another type (eDP, MIPI CSI-2, parallel, etc.). - - * - ``MEDIA_ENT_F_DV_DECODER`` - - Digital video decoder. The basic function of the video decoder is - to accept digital video from a wide variety of sources - and output it in some digital video standard, with appropriate - timing signals. - - * - ``MEDIA_ENT_F_DV_ENCODER`` - - Digital video encoder. The basic function of the video encoder is - to accept digital video from some digital video standard with - appropriate timing signals (usually a parallel video bus with sync - signals) and output this to a digital video output connector such - as HDMI or DisplayPort. - -.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| - -.. _media-entity-flag: -.. _MEDIA-ENT-FL-DEFAULT: -.. _MEDIA-ENT-FL-CONNECTOR: - -.. flat-table:: Media entity flags - :header-rows: 0 - :stub-columns: 0 - - * - ``MEDIA_ENT_FL_DEFAULT`` - - Default entity for its type. Used to discover the default audio, - VBI and video devices, the default camera sensor, etc. - - * - ``MEDIA_ENT_FL_CONNECTOR`` - - The entity represents a connector. - - -.. tabularcolumns:: |p{6.5cm}|p{6.0cm}|p{5.0cm}| - -.. _media-intf-type: -.. _MEDIA-INTF-T-DVB-FE: -.. _MEDIA-INTF-T-DVB-DEMUX: -.. _MEDIA-INTF-T-DVB-DVR: -.. _MEDIA-INTF-T-DVB-CA: -.. _MEDIA-INTF-T-DVB-NET: -.. _MEDIA-INTF-T-V4L-VIDEO: -.. _MEDIA-INTF-T-V4L-VBI: -.. _MEDIA-INTF-T-V4L-RADIO: -.. _MEDIA-INTF-T-V4L-SUBDEV: -.. _MEDIA-INTF-T-V4L-SWRADIO: -.. _MEDIA-INTF-T-V4L-TOUCH: -.. _MEDIA-INTF-T-ALSA-PCM-CAPTURE: -.. _MEDIA-INTF-T-ALSA-PCM-PLAYBACK: -.. _MEDIA-INTF-T-ALSA-CONTROL: -.. _MEDIA-INTF-T-ALSA-COMPRESS: -.. _MEDIA-INTF-T-ALSA-RAWMIDI: -.. _MEDIA-INTF-T-ALSA-HWDEP: -.. _MEDIA-INTF-T-ALSA-SEQUENCER: -.. _MEDIA-INTF-T-ALSA-TIMER: - -.. flat-table:: Media interface types - :header-rows: 0 - :stub-columns: 0 - - * - ``MEDIA_INTF_T_DVB_FE`` - - Device node interface for the Digital TV frontend - - typically, /dev/dvb/adapter?/frontend? - - * - ``MEDIA_INTF_T_DVB_DEMUX`` - - Device node interface for the Digital TV demux - - typically, /dev/dvb/adapter?/demux? - - * - ``MEDIA_INTF_T_DVB_DVR`` - - Device node interface for the Digital TV DVR - - typically, /dev/dvb/adapter?/dvr? - - * - ``MEDIA_INTF_T_DVB_CA`` - - Device node interface for the Digital TV Conditional Access - - typically, /dev/dvb/adapter?/ca? - - * - ``MEDIA_INTF_T_DVB_NET`` - - Device node interface for the Digital TV network control - - typically, /dev/dvb/adapter?/net? - - * - ``MEDIA_INTF_T_V4L_VIDEO`` - - Device node interface for video (V4L) - - typically, /dev/video? - - * - ``MEDIA_INTF_T_V4L_VBI`` - - Device node interface for VBI (V4L) - - typically, /dev/vbi? - - * - ``MEDIA_INTF_T_V4L_RADIO`` - - Device node interface for radio (V4L) - - typically, /dev/radio? - - * - ``MEDIA_INTF_T_V4L_SUBDEV`` - - Device node interface for a V4L subdevice - - typically, /dev/v4l-subdev? - - * - ``MEDIA_INTF_T_V4L_SWRADIO`` - - Device node interface for Software Defined Radio (V4L) - - typically, /dev/swradio? - - * - ``MEDIA_INTF_T_V4L_TOUCH`` - - Device node interface for Touch device (V4L) - - typically, /dev/v4l-touch? - - * - ``MEDIA_INTF_T_ALSA_PCM_CAPTURE`` - - Device node interface for ALSA PCM Capture - - typically, /dev/snd/pcmC?D?c - - * - ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK`` - - Device node interface for ALSA PCM Playback - - typically, /dev/snd/pcmC?D?p - - * - ``MEDIA_INTF_T_ALSA_CONTROL`` - - Device node interface for ALSA Control - - typically, /dev/snd/controlC? - - * - ``MEDIA_INTF_T_ALSA_COMPRESS`` - - Device node interface for ALSA Compress - - typically, /dev/snd/compr? - - * - ``MEDIA_INTF_T_ALSA_RAWMIDI`` - - Device node interface for ALSA Raw MIDI - - typically, /dev/snd/midi? - - * - ``MEDIA_INTF_T_ALSA_HWDEP`` - - Device node interface for ALSA Hardware Dependent - - typically, /dev/snd/hwC?D? - - * - ``MEDIA_INTF_T_ALSA_SEQUENCER`` - - Device node interface for ALSA Sequencer - - typically, /dev/snd/seq - - * - ``MEDIA_INTF_T_ALSA_TIMER`` - - Device node interface for ALSA Timer - - typically, /dev/snd/timer - - -.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| - -.. _media-pad-flag: -.. _MEDIA-PAD-FL-SINK: -.. _MEDIA-PAD-FL-SOURCE: -.. _MEDIA-PAD-FL-MUST-CONNECT: - -.. flat-table:: Media pad flags - :header-rows: 0 - :stub-columns: 0 - - * - ``MEDIA_PAD_FL_SINK`` - - Input pad, relative to the entity. Input pads sink data and are - targets of links. - - * - ``MEDIA_PAD_FL_SOURCE`` - - Output pad, relative to the entity. Output pads source data and - are origins of links. - - * - ``MEDIA_PAD_FL_MUST_CONNECT`` - - If this flag is set and the pad is linked to any other pad, then - at least one of those links must be enabled for the entity to be - able to stream. There could be temporary reasons (e.g. device - configuration dependent) for the pad to need enabled links even - when this flag isn't set; the absence of the flag doesn't imply - there is none. - - -One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE`` -must be set for every pad. - -.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| - -.. _media-link-flag: -.. _MEDIA-LNK-FL-ENABLED: -.. _MEDIA-LNK-FL-IMMUTABLE: -.. _MEDIA-LNK-FL-DYNAMIC: -.. _MEDIA-LNK-FL-LINK-TYPE: - -.. flat-table:: Media link flags - :header-rows: 0 - :stub-columns: 0 - - * - ``MEDIA_LNK_FL_ENABLED`` - - The link is enabled and can be used to transfer media data. When - two or more links target a sink pad, only one of them can be - enabled at a time. - - * - ``MEDIA_LNK_FL_IMMUTABLE`` - - The link enabled state can't be modified at runtime. An immutable - link is always enabled. - - * - ``MEDIA_LNK_FL_DYNAMIC`` - - The link enabled state can be modified during streaming. This flag - is set by drivers and is read-only for applications. - - * - ``MEDIA_LNK_FL_LINK_TYPE`` - - This is a bitmask that defines the type of the link. Currently, - two types of links are supported: - - .. _MEDIA-LNK-FL-DATA-LINK: - - ``MEDIA_LNK_FL_DATA_LINK`` if the link is between two pads - - .. _MEDIA-LNK-FL-INTERFACE-LINK: - - ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an - interface and an entity diff --git a/Documentation/media/uapi/mediactl/request-api.rst b/Documentation/media/uapi/mediactl/request-api.rst deleted file mode 100644 index 01abe8103bdd..000000000000 --- a/Documentation/media/uapi/mediactl/request-api.rst +++ /dev/null @@ -1,276 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _media-request-api: - -Request API -=========== - -The Request API has been designed to allow V4L2 to deal with requirements of -modern devices (stateless codecs, complex camera pipelines, ...) and APIs -(Android Codec v2). One such requirement is the ability for devices belonging to -the same pipeline to reconfigure and collaborate closely on a per-frame basis. -Another is support of stateless codecs, which require controls to be applied -to specific frames (aka 'per-frame controls') in order to be used efficiently. - -While the initial use-case was V4L2, it can be extended to other subsystems -as well, as long as they use the media controller. - -Supporting these features without the Request API is not always possible and if -it is, it is terribly inefficient: user-space would have to flush all activity -on the media pipeline, reconfigure it for the next frame, queue the buffers to -be processed with that configuration, and wait until they are all available for -dequeuing before considering the next frame. This defeats the purpose of having -buffer queues since in practice only one buffer would be queued at a time. - -The Request API allows a specific configuration of the pipeline (media -controller topology + configuration for each media entity) to be associated with -specific buffers. This allows user-space to schedule several tasks ("requests") -with different configurations in advance, knowing that the configuration will be -applied when needed to get the expected result. Configuration values at the time -of request completion are also available for reading. - -General Usage -------------- - -The Request API extends the Media Controller API and cooperates with -subsystem-specific APIs to support request usage. At the Media Controller -level, requests are allocated from the supporting Media Controller device -node. Their life cycle is then managed through the request file descriptors in -an opaque way. Configuration data, buffer handles and processing results -stored in requests are accessed through subsystem-specific APIs extended for -request support, such as V4L2 APIs that take an explicit ``request_fd`` -parameter. - -Request Allocation ------------------- - -User-space allocates requests using :ref:`MEDIA_IOC_REQUEST_ALLOC` -for the media device node. This returns a file descriptor representing the -request. Typically, several such requests will be allocated. - -Request Preparation -------------------- - -Standard V4L2 ioctls can then receive a request file descriptor to express the -fact that the ioctl is part of said request, and is not to be applied -immediately. See :ref:`MEDIA_IOC_REQUEST_ALLOC` for a list of ioctls that -support this. Configurations set with a ``request_fd`` parameter are stored -instead of being immediately applied, and buffers queued to a request do not -enter the regular buffer queue until the request itself is queued. - -Request Submission ------------------- - -Once the configuration and buffers of the request are specified, it can be -queued by calling :ref:`MEDIA_REQUEST_IOC_QUEUE` on the request file descriptor. -A request must contain at least one buffer, otherwise ``ENOENT`` is returned. -A queued request cannot be modified anymore. - -.. caution:: - For :ref:`memory-to-memory devices ` you can use requests only for - output buffers, not for capture buffers. Attempting to add a capture buffer - to a request will result in an ``EBADR`` error. - -If the request contains configurations for multiple entities, individual drivers -may synchronize so the requested pipeline's topology is applied before the -buffers are processed. Media controller drivers do a best effort implementation -since perfect atomicity may not be possible due to hardware limitations. - -.. caution:: - - It is not allowed to mix queuing requests with directly queuing buffers: - whichever method is used first locks this in place until - :ref:`VIDIOC_STREAMOFF ` is called or the device is - :ref:`closed `. Attempts to directly queue a buffer when earlier - a buffer was queued via a request or vice versa will result in an ``EBUSY`` - error. - -Controls can still be set without a request and are applied immediately, -regardless of whether a request is in use or not. - -.. caution:: - - Setting the same control through a request and also directly can lead to - undefined behavior! - -User-space can :ref:`poll() ` a request file descriptor in -order to wait until the request completes. A request is considered complete -once all its associated buffers are available for dequeuing and all the -associated controls have been updated with the values at the time of completion. -Note that user-space does not need to wait for the request to complete to -dequeue its buffers: buffers that are available halfway through a request can -be dequeued independently of the request's state. - -A completed request contains the state of the device after the request was -executed. User-space can query that state by calling -:ref:`ioctl VIDIOC_G_EXT_CTRLS ` with the request file -descriptor. Calling :ref:`ioctl VIDIOC_G_EXT_CTRLS ` for a -request that has been queued but not yet completed will return ``EBUSY`` -since the control values might be changed at any time by the driver while the -request is in flight. - -.. _media-request-life-time: - -Recycling and Destruction -------------------------- - -Finally, a completed request can either be discarded or be reused. Calling -:ref:`close() ` on a request file descriptor will make -that file descriptor unusable and the request will be freed once it is no -longer in use by the kernel. That is, if the request is queued and then the -file descriptor is closed, then it won't be freed until the driver completed -the request. - -The :ref:`MEDIA_REQUEST_IOC_REINIT` will clear a request's state and make it -available again. No state is retained by this operation: the request is as -if it had just been allocated. - -Example for a Codec Device --------------------------- - -For use-cases such as :ref:`codecs `, the request API can be used -to associate specific controls to -be applied by the driver for the OUTPUT buffer, allowing user-space -to queue many such buffers in advance. It can also take advantage of requests' -ability to capture the state of controls when the request completes to read back -information that may be subject to change. - -Put into code, after obtaining a request, user-space can assign controls and one -OUTPUT buffer to it: - -.. code-block:: c - - struct v4l2_buffer buf; - struct v4l2_ext_controls ctrls; - int req_fd; - ... - if (ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd)) - return errno; - ... - ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; - ctrls.request_fd = req_fd; - if (ioctl(codec_fd, VIDIOC_S_EXT_CTRLS, &ctrls)) - return errno; - ... - buf.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; - buf.flags |= V4L2_BUF_FLAG_REQUEST_FD; - buf.request_fd = req_fd; - if (ioctl(codec_fd, VIDIOC_QBUF, &buf)) - return errno; - -Note that it is not allowed to use the Request API for CAPTURE buffers -since there are no per-frame settings to report there. - -Once the request is fully prepared, it can be queued to the driver: - -.. code-block:: c - - if (ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE)) - return errno; - -User-space can then either wait for the request to complete by calling poll() on -its file descriptor, or start dequeuing CAPTURE buffers. Most likely, it will -want to get CAPTURE buffers as soon as possible and this can be done using a -regular :ref:`VIDIOC_DQBUF `: - -.. code-block:: c - - struct v4l2_buffer buf; - - memset(&buf, 0, sizeof(buf)); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (ioctl(codec_fd, VIDIOC_DQBUF, &buf)) - return errno; - -Note that this example assumes for simplicity that for every OUTPUT buffer -there will be one CAPTURE buffer, but this does not have to be the case. - -We can then, after ensuring that the request is completed via polling the -request file descriptor, query control values at the time of its completion via -a call to :ref:`VIDIOC_G_EXT_CTRLS `. -This is particularly useful for volatile controls for which we want to -query values as soon as the capture buffer is produced. - -.. code-block:: c - - struct pollfd pfd = { .events = POLLPRI, .fd = req_fd }; - poll(&pfd, 1, -1); - ... - ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; - ctrls.request_fd = req_fd; - if (ioctl(codec_fd, VIDIOC_G_EXT_CTRLS, &ctrls)) - return errno; - -Once we don't need the request anymore, we can either recycle it for reuse with -:ref:`MEDIA_REQUEST_IOC_REINIT`... - -.. code-block:: c - - if (ioctl(req_fd, MEDIA_REQUEST_IOC_REINIT)) - return errno; - -... or close its file descriptor to completely dispose of it. - -.. code-block:: c - - close(req_fd); - -Example for a Simple Capture Device ------------------------------------ - -With a simple capture device, requests can be used to specify controls to apply -for a given CAPTURE buffer. - -.. code-block:: c - - struct v4l2_buffer buf; - struct v4l2_ext_controls ctrls; - int req_fd; - ... - if (ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd)) - return errno; - ... - ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; - ctrls.request_fd = req_fd; - if (ioctl(camera_fd, VIDIOC_S_EXT_CTRLS, &ctrls)) - return errno; - ... - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.flags |= V4L2_BUF_FLAG_REQUEST_FD; - buf.request_fd = req_fd; - if (ioctl(camera_fd, VIDIOC_QBUF, &buf)) - return errno; - -Once the request is fully prepared, it can be queued to the driver: - -.. code-block:: c - - if (ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE)) - return errno; - -User-space can then dequeue buffers, wait for the request completion, query -controls and recycle the request as in the M2M example above. diff --git a/Documentation/media/uapi/mediactl/request-func-close.rst b/Documentation/media/uapi/mediactl/request-func-close.rst deleted file mode 100644 index 2cff7770558e..000000000000 --- a/Documentation/media/uapi/mediactl/request-func-close.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _request-func-close: - -*************** -request close() -*************** - -Name -==== - -request-close - Close a request file descriptor - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int close( int fd ) - :name: req-close - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. - - -Description -=========== - -Closes the request file descriptor. Resources associated with the request -are freed once all file descriptors associated with the request are closed -and the driver has completed the request. -See :ref:`here ` for more information. - - -Return Value -============ - -:ref:`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. diff --git a/Documentation/media/uapi/mediactl/request-func-ioctl.rst b/Documentation/media/uapi/mediactl/request-func-ioctl.rst deleted file mode 100644 index de0781c61873..000000000000 --- a/Documentation/media/uapi/mediactl/request-func-ioctl.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _request-func-ioctl: - -*************** -request ioctl() -*************** - -Name -==== - -request-ioctl - Control a request file descriptor - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int ioctl( int fd, int cmd, void *argp ) - :name: req-ioctl - -Arguments -========= - -``fd`` - File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. - -``cmd`` - The request ioctl command code as defined in the media.h header file, for - example :ref:`MEDIA_REQUEST_IOC_QUEUE`. - -``argp`` - Pointer to a request-specific structure. - - -Description -=========== - -The :ref:`ioctl() ` function manipulates request -parameters. The argument ``fd`` must be an open file descriptor. - -The ioctl ``cmd`` code specifies the request 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 request ioctl commands and -their parameters are located in the media.h header file. All request ioctl -commands, their respective function and parameters are specified in -:ref:`media-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 ` chapter. - -Command-specific error codes are listed in the individual command -descriptions. - -When an ioctl that takes an output or read/write parameter fails, the -parameter remains unmodified. diff --git a/Documentation/media/uapi/mediactl/request-func-poll.rst b/Documentation/media/uapi/mediactl/request-func-poll.rst deleted file mode 100644 index ebaf33e21873..000000000000 --- a/Documentation/media/uapi/mediactl/request-func-poll.rst +++ /dev/null @@ -1,101 +0,0 @@ -.. This file is dual-licensed: you can use it either under the terms -.. of the GPL 2.0 or the GFDL 1.1+ license, at your option. Note that this -.. dual licensing only applies to this file, and not this project as a -.. whole. -.. -.. a) This file 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 file 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. -.. -.. Or, alternatively, -.. -.. b) 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections - -.. _request-func-poll: - -************** -request poll() -************** - -Name -==== - -request-poll - Wait for some event on a file descriptor - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) - :name: request-poll - -Arguments -========= - -``ufds`` - List of file descriptor events to be watched - -``nfds`` - Number of file descriptor events at the \*ufds array - -``timeout`` - Timeout to wait for events - - -Description -=========== - -With the :c:func:`poll() ` function applications can wait -for a request to complete. - -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 struct :c:type:`pollfd` -is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents`` -when the request was completed. When the function times out it returns -a value of zero, on failure it returns -1 and the ``errno`` variable is -set appropriately. - -Attempting to poll for a request that is not yet queued will -set the ``POLLERR`` flag in ``revents``. - - -Return Value -============ - -On success, :c:func:`poll() ` returns the number of -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`` value exceeds the ``RLIMIT_NOFILE`` value. Use - ``getrlimit()`` to obtain this value. diff --git a/Documentation/media/uapi/rc/keytable.c.rst b/Documentation/media/uapi/rc/keytable.c.rst deleted file mode 100644 index 46f98569e999..000000000000 --- a/Documentation/media/uapi/rc/keytable.c.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -file: uapi/v4l/keytable.c -========================= - -.. code-block:: c - - /* keytable.c - This program allows checking/replacing keys at IR - - Copyright (C) 2006-2009 Mauro Carvalho Chehab - - This program 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. - */ - - #include - #include - #include - #include - #include - #include - #include - #include - - #include "parse.h" - - void prtcode (int *codes) - { - struct parse_key *p; - - for (p=keynames;p->name!=NULL;p++) { - if (p->value == (unsigned)codes[1]) { - printf("scancode 0x%04x = %s (0x%02x)\\n", codes[0], p->name, codes[1]); - return; - } - } - - if (isprint (codes[1])) - printf("scancode %d = '%c' (0x%02x)\\n", codes[0], codes[1], codes[1]); - else - printf("scancode %d = 0x%02x\\n", codes[0], codes[1]); - } - - int parse_code(char *string) - { - struct parse_key *p; - - for (p=keynames;p->name!=NULL;p++) { - if (!strcasecmp(p->name, string)) { - return p->value; - } - } - return -1; - } - - int main (int argc, char *argv[]) - { - int fd; - unsigned int i, j; - int codes[2]; - - if (argc<2 || argc>4) { - printf ("usage: %s to get table; or\\n" - " %s \\n" - " %s n",*argv,*argv,*argv); - return -1; - } - - if ((fd = open(argv[1], O_RDONLY)) < 0) { - perror("Couldn't open input device"); - return(-1); - } - - if (argc==4) { - int value; - - value=parse_code(argv[3]); - - if (value==-1) { - value = strtol(argv[3], NULL, 0); - if (errno) - perror("value"); - } - - codes [0] = (unsigned) strtol(argv[2], NULL, 0); - codes [1] = (unsigned) value; - - if(ioctl(fd, EVIOCSKEYCODE, codes)) - perror ("EVIOCSKEYCODE"); - - if(ioctl(fd, EVIOCGKEYCODE, codes)==0) - prtcode(codes); - return 0; - } - - if (argc==3) { - FILE *fin; - int value; - char *scancode, *keycode, s[2048]; - - fin=fopen(argv[2],"r"); - if (fin==NULL) { - perror ("opening keycode file"); - return -1; - } - - /* Clears old table */ - for (j = 0; j < 256; j++) { - for (i = 0; i < 256; i++) { - codes[0] = (j << 8) | i; - codes[1] = KEY_RESERVED; - ioctl(fd, EVIOCSKEYCODE, codes); - } - } - - while (fgets(s,sizeof(s),fin)) { - scancode=strtok(s,"\\n\\t =:"); - if (!scancode) { - perror ("parsing input file scancode"); - return -1; - } - if (!strcasecmp(scancode, "scancode")) { - scancode = strtok(NULL,"\\n\\t =:"); - if (!scancode) { - perror ("parsing input file scancode"); - return -1; - } - } - - keycode=strtok(NULL,"\\n\\t =:("); - if (!keycode) { - perror ("parsing input file keycode"); - return -1; - } - - // printf ("parsing %s=%s:", scancode, keycode); - value=parse_code(keycode); - // printf ("\\tvalue=%d\\n",value); - - if (value==-1) { - value = strtol(keycode, NULL, 0); - if (errno) - perror("value"); - } - - codes [0] = (unsigned) strtol(scancode, NULL, 0); - codes [1] = (unsigned) value; - - // printf("\\t%04x=%04x\\n",codes[0], codes[1]); - if(ioctl(fd, EVIOCSKEYCODE, codes)) { - fprintf(stderr, "Setting scancode 0x%04x with 0x%04x via ",codes[0], codes[1]); - perror ("EVIOCSKEYCODE"); - } - - if(ioctl(fd, EVIOCGKEYCODE, codes)==0) - prtcode(codes); - } - return 0; - } - - /* Get scancode table */ - for (j = 0; j < 256; j++) { - for (i = 0; i < 256; i++) { - codes[0] = (j << 8) | i; - if (!ioctl(fd, EVIOCGKEYCODE, codes) && codes[1] != KEY_RESERVED) - prtcode(codes); - } - } - return 0; - } diff --git a/Documentation/media/uapi/rc/lirc-dev-intro.rst b/Documentation/media/uapi/rc/lirc-dev-intro.rst deleted file mode 100644 index b68c01693939..000000000000 --- a/Documentation/media/uapi/rc/lirc-dev-intro.rst +++ /dev/null @@ -1,171 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_dev_intro: - -************ -Introduction -************ - -LIRC stands for Linux Infrared Remote Control. The LIRC device interface is -a bi-directional interface for transporting raw IR and decoded scancodes -data between userspace and kernelspace. Fundamentally, it is just a chardev -(/dev/lircX, for X = 0, 1, 2, ...), with a number of standard struct -file_operations defined on it. With respect to transporting raw IR and -decoded scancodes to and fro, the essential fops are read, write and ioctl. - -It is also possible to attach a BPF program to a LIRC device for decoding -raw IR into scancodes. - -Example dmesg output upon a driver registering w/LIRC: - -.. code-block:: none - - $ dmesg |grep lirc_dev - rc rc0: lirc_dev: driver mceusb registered at minor = 0, raw IR receiver, raw IR transmitter - -What you should see for a chardev: - -.. code-block:: none - - $ ls -l /dev/lirc* - crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0 - -Note that the package `v4l-utils `_ -contains tools for working with LIRC devices: - - - ir-ctl: can receive raw IR and transmit IR, as well as query LIRC - device features. - - - ir-keytable: can load keymaps; allows you to set IR kernel protocols; load - BPF IR decoders and test IR decoding. Some BPF IR decoders are also - provided. - -.. _lirc_modes: - -********** -LIRC modes -********** - -LIRC supports some modes of receiving and sending IR codes, as shown -on the following table. - -.. _lirc-mode-scancode: -.. _lirc-scancode-flag-toggle: -.. _lirc-scancode-flag-repeat: - -``LIRC_MODE_SCANCODE`` - - This mode is for both sending and receiving IR. - - For transmitting (aka sending), create a ``struct lirc_scancode`` with - the desired scancode set in the ``scancode`` member, :c:type:`rc_proto` - set to the :ref:`IR protocol `, and all other - members set to 0. Write this struct to the lirc device. - - For receiving, you read ``struct lirc_scancode`` from the LIRC device. - The ``scancode`` field is set to the received scancode and the - :ref:`IR protocol ` is set in - :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set - in the ``keycode`` field, else it is set to ``KEY_RESERVED``. - - The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle - bit is set in protocols that support it (e.g. rc-5 and rc-6), or - ``LIRC_SCANCODE_FLAG_REPEAT`` for when a repeat is received for protocols - that support it (e.g. nec). - - In the Sanyo and NEC protocol, if you hold a button on remote, rather than - repeating the entire scancode, the remote sends a shorter message with - no scancode, which just means button is held, a "repeat". When this is - received, the ``LIRC_SCANCODE_FLAG_REPEAT`` is set and the scancode and - keycode is repeated. - - With nec, there is no way to distinguish "button hold" from "repeatedly - pressing the same button". The rc-5 and rc-6 protocols have a toggle bit. - When a button is released and pressed again, the toggle bit is inverted. - If the toggle bit is set, the ``LIRC_SCANCODE_FLAG_TOGGLE`` is set. - - The ``timestamp`` field is filled with the time nanoseconds - (in ``CLOCK_MONOTONIC``) when the scancode was decoded. - -.. _lirc-mode-mode2: - -``LIRC_MODE_MODE2`` - - The driver returns a sequence of pulse and space codes to userspace, - as a series of u32 values. - - This mode is used only for IR receive. - - The upper 8 bits determine the packet type, and the lower 24 bits - the payload. Use ``LIRC_VALUE()`` macro to get the payload, and - the macro ``LIRC_MODE2()`` will give you the type, which - is one of: - - ``LIRC_MODE2_PULSE`` - - Signifies the presence of IR in microseconds. - - ``LIRC_MODE2_SPACE`` - - Signifies absence of IR in microseconds. - - ``LIRC_MODE2_FREQUENCY`` - - If measurement of the carrier frequency was enabled with - :ref:`lirc_set_measure_carrier_mode` then this packet gives you - the carrier frequency in Hertz. - - ``LIRC_MODE2_TIMEOUT`` - - If timeout reports are enabled with - :ref:`lirc_set_rec_timeout_reports`, when the timeout set with - :ref:`lirc_set_rec_timeout` expires due to no IR being detected, - this packet will be sent, with the number of microseconds with - no IR. - -.. _lirc-mode-pulse: - -``LIRC_MODE_PULSE`` - - In pulse mode, a sequence of pulse/space integer values are written to the - lirc device using :ref:`lirc-write`. - - The values are alternating pulse and space lengths, in microseconds. The - first and last entry must be a pulse, so there must be an odd number - of entries. - - This mode is used only for IR send. - -******************** -BPF based IR decoder -******************** - -The kernel has support for decoding the most common -:ref:`IR protocols `, but there -are many protocols which are not supported. To support these, it is possible -to load an BPF program which does the decoding. This can only be done on -LIRC devices which support reading raw IR. - -First, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument, -program must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached -to the LIRC device, this program will be called for each pulse, space or -timeout event on the LIRC device. The context for the BPF program is a -pointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 ` -value. When the program has decoded the scancode, it can be submitted using -the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer -movements can be reported using ``bpf_rc_pointer_rel()``. - -Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF -program, it can be attached to the LIRC device using the `bpf(2)`_ syscall. -The target must be the file descriptor for the LIRC device, and the -attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be -attached to a single LIRC device at a time. - -.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html diff --git a/Documentation/media/uapi/rc/lirc-dev.rst b/Documentation/media/uapi/rc/lirc-dev.rst deleted file mode 100644 index 7058e0b2296a..000000000000 --- a/Documentation/media/uapi/rc/lirc-dev.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_dev: - -LIRC Device Interface -===================== - - -.. toctree:: - :maxdepth: 1 - - lirc-dev-intro - lirc-func - lirc-header diff --git a/Documentation/media/uapi/rc/lirc-func.rst b/Documentation/media/uapi/rc/lirc-func.rst deleted file mode 100644 index 25058369f724..000000000000 --- a/Documentation/media/uapi/rc/lirc-func.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_func: - -LIRC Function Reference -======================= - - -.. toctree:: - :maxdepth: 1 - - lirc-read - lirc-write - lirc-get-features - lirc-get-send-mode - lirc-get-rec-mode - lirc-get-rec-resolution - lirc-set-send-duty-cycle - lirc-get-timeout - lirc-set-rec-timeout - lirc-set-rec-carrier - lirc-set-rec-carrier-range - lirc-set-send-carrier - lirc-set-transmitter-mask - lirc-set-rec-timeout-reports - lirc-set-measure-carrier-mode - lirc-set-wideband-receiver diff --git a/Documentation/media/uapi/rc/lirc-get-features.rst b/Documentation/media/uapi/rc/lirc-get-features.rst deleted file mode 100644 index 1d590df8164a..000000000000 --- a/Documentation/media/uapi/rc/lirc-get-features.rst +++ /dev/null @@ -1,200 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_get_features: - -*********************** -ioctl LIRC_GET_FEATURES -*********************** - -Name -==== - -LIRC_GET_FEATURES - Get the underlying hardware device's features - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_FEATURES, __u32 *features) - :name: LIRC_GET_FEATURES - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``features`` - Bitmask with the LIRC features. - - -Description -=========== - - -Get the underlying hardware device's features. If a driver does not -announce support of certain features, calling of the corresponding ioctls -is undefined. - -LIRC features -============= - -.. _LIRC-CAN-REC-RAW: - -``LIRC_CAN_REC_RAW`` - - Unused. Kept just to avoid breaking uAPI. - -.. _LIRC-CAN-REC-PULSE: - -``LIRC_CAN_REC_PULSE`` - - Unused. Kept just to avoid breaking uAPI. - :ref:`LIRC_MODE_PULSE ` can only be used for transmitting. - -.. _LIRC-CAN-REC-MODE2: - -``LIRC_CAN_REC_MODE2`` - - This is raw IR driver for receiving. This means that - :ref:`LIRC_MODE_MODE2 ` is used. This also implies - that :ref:`LIRC_MODE_SCANCODE ` is also supported, - as long as the kernel is recent enough. Use the - :ref:`lirc_set_rec_mode` to switch modes. - -.. _LIRC-CAN-REC-LIRCCODE: - -``LIRC_CAN_REC_LIRCCODE`` - - Unused. Kept just to avoid breaking uAPI. - -.. _LIRC-CAN-REC-SCANCODE: - -``LIRC_CAN_REC_SCANCODE`` - - This is a scancode driver for receiving. This means that - :ref:`LIRC_MODE_SCANCODE ` is used. - -.. _LIRC-CAN-SET-SEND-CARRIER: - -``LIRC_CAN_SET_SEND_CARRIER`` - - The driver supports changing the modulation frequency via - :ref:`ioctl LIRC_SET_SEND_CARRIER `. - -.. _LIRC-CAN-SET-SEND-DUTY-CYCLE: - -``LIRC_CAN_SET_SEND_DUTY_CYCLE`` - - The driver supports changing the duty cycle using - :ref:`ioctl LIRC_SET_SEND_DUTY_CYCLE `. - -.. _LIRC-CAN-SET-TRANSMITTER-MASK: - -``LIRC_CAN_SET_TRANSMITTER_MASK`` - - The driver supports changing the active transmitter(s) using - :ref:`ioctl LIRC_SET_TRANSMITTER_MASK `. - -.. _LIRC-CAN-SET-REC-CARRIER: - -``LIRC_CAN_SET_REC_CARRIER`` - - The driver supports setting the receive carrier frequency using - :ref:`ioctl LIRC_SET_REC_CARRIER `. - -.. _LIRC-CAN-SET-REC-DUTY-CYCLE-RANGE: - -``LIRC_CAN_SET_REC_DUTY_CYCLE_RANGE`` - - Unused. Kept just to avoid breaking uAPI. - -.. _LIRC-CAN-SET-REC-CARRIER-RANGE: - -``LIRC_CAN_SET_REC_CARRIER_RANGE`` - - The driver supports - :ref:`ioctl LIRC_SET_REC_CARRIER_RANGE `. - -.. _LIRC-CAN-GET-REC-RESOLUTION: - -``LIRC_CAN_GET_REC_RESOLUTION`` - - The driver supports - :ref:`ioctl LIRC_GET_REC_RESOLUTION `. - -.. _LIRC-CAN-SET-REC-TIMEOUT: - -``LIRC_CAN_SET_REC_TIMEOUT`` - - The driver supports - :ref:`ioctl LIRC_SET_REC_TIMEOUT `. - -.. _LIRC-CAN-SET-REC-FILTER: - -``LIRC_CAN_SET_REC_FILTER`` - - Unused. Kept just to avoid breaking uAPI. - -.. _LIRC-CAN-MEASURE-CARRIER: - -``LIRC_CAN_MEASURE_CARRIER`` - - The driver supports measuring of the modulation frequency using - :ref:`ioctl LIRC_SET_MEASURE_CARRIER_MODE `. - -.. _LIRC-CAN-USE-WIDEBAND-RECEIVER: - -``LIRC_CAN_USE_WIDEBAND_RECEIVER`` - - The driver supports learning mode using - :ref:`ioctl LIRC_SET_WIDEBAND_RECEIVER `. - -.. _LIRC-CAN-NOTIFY-DECODE: - -``LIRC_CAN_NOTIFY_DECODE`` - - Unused. Kept just to avoid breaking uAPI. - -.. _LIRC-CAN-SEND-RAW: - -``LIRC_CAN_SEND_RAW`` - - Unused. Kept just to avoid breaking uAPI. - -.. _LIRC-CAN-SEND-PULSE: - -``LIRC_CAN_SEND_PULSE`` - - The driver supports sending (also called as IR blasting or IR TX) using - :ref:`LIRC_MODE_PULSE `. This implies that - :ref:`LIRC_MODE_SCANCODE ` is also supported for - transmit, as long as the kernel is recent enough. Use the - :ref:`lirc_set_send_mode` to switch modes. - -.. _LIRC-CAN-SEND-MODE2: - -``LIRC_CAN_SEND_MODE2`` - - Unused. Kept just to avoid breaking uAPI. - :ref:`LIRC_MODE_MODE2 ` can only be used for receiving. - -.. _LIRC-CAN-SEND-LIRCCODE: - -``LIRC_CAN_SEND_LIRCCODE`` - - Unused. Kept just to avoid breaking uAPI. - - -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 ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst b/Documentation/media/uapi/rc/lirc-get-rec-mode.rst deleted file mode 100644 index 0a3e02aca80e..000000000000 --- a/Documentation/media/uapi/rc/lirc-get-rec-mode.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_get_rec_mode: -.. _lirc_set_rec_mode: - -********************************************** -ioctls LIRC_GET_REC_MODE and LIRC_SET_REC_MODE -********************************************** - -Name -==== - -LIRC_GET_REC_MODE/LIRC_SET_REC_MODE - Get/set current receive mode. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_REC_MODE, __u32 *mode) - :name: LIRC_GET_REC_MODE - -.. c:function:: int ioctl( int fd, LIRC_SET_REC_MODE, __u32 *mode) - :name: LIRC_SET_REC_MODE - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``mode`` - Mode used for receive. - -Description -=========== - -Get and set the current receive mode. Only -:ref:`LIRC_MODE_MODE2 ` and -:ref:`LIRC_MODE_SCANCODE ` are supported. -Use :ref:`lirc_get_features` to find out which modes the driver supports. - -Return Value -============ - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``ENODEV`` - - - Device not available. - - - .. row 2 - - - ``ENOTTY`` - - - Device does not support receiving. - - - .. row 3 - - - ``EINVAL`` - - - Invalid mode or invalid mode for this device. diff --git a/Documentation/media/uapi/rc/lirc-get-rec-resolution.rst b/Documentation/media/uapi/rc/lirc-get-rec-resolution.rst deleted file mode 100644 index f560b694ccf2..000000000000 --- a/Documentation/media/uapi/rc/lirc-get-rec-resolution.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_get_rec_resolution: - -***************************** -ioctl LIRC_GET_REC_RESOLUTION -***************************** - -Name -==== - -LIRC_GET_REC_RESOLUTION - Obtain the value of receive resolution, in microseconds. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds) - :name: LIRC_GET_REC_RESOLUTION - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``microseconds`` - Resolution, in microseconds. - - -Description -=========== - -Some receivers 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 ioctl returns the integer value with such resolution, with can be -used by userspace applications like lircd to automatically adjust the -tolerance value. - - -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 ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-get-send-mode.rst b/Documentation/media/uapi/rc/lirc-get-send-mode.rst deleted file mode 100644 index 4f440c697052..000000000000 --- a/Documentation/media/uapi/rc/lirc-get-send-mode.rst +++ /dev/null @@ -1,78 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_get_send_mode: -.. _lirc_set_send_mode: - -************************************************ -ioctls LIRC_GET_SEND_MODE and LIRC_SET_SEND_MODE -************************************************ - -Name -==== - -LIRC_GET_SEND_MODE/LIRC_SET_SEND_MODE - Get/set current transmit mode. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_SEND_MODE, __u32 *mode ) - :name: LIRC_GET_SEND_MODE - -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_MODE, __u32 *mode ) - :name: LIRC_SET_SEND_MODE - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``mode`` - The mode used for transmitting. - - -Description -=========== - -Get/set current transmit mode. - -Only :ref:`LIRC_MODE_PULSE ` and -:ref:`LIRC_MODE_SCANCODE ` are supported by for IR send, -depending on the driver. Use :ref:`lirc_get_features` to find out which -modes the driver supports. - -Return Value -============ - - -.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - ``ENODEV`` - - - Device not available. - - - .. row 2 - - - ``ENOTTY`` - - - Device does not support transmitting. - - - .. row 3 - - - ``EINVAL`` - - - Invalid mode or invalid mode for this device. diff --git a/Documentation/media/uapi/rc/lirc-get-timeout.rst b/Documentation/media/uapi/rc/lirc-get-timeout.rst deleted file mode 100644 index 1de214529f27..000000000000 --- a/Documentation/media/uapi/rc/lirc-get-timeout.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_get_min_timeout: -.. _lirc_get_max_timeout: - -**************************************************** -ioctls LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT -**************************************************** - -Name -==== - -LIRC_GET_MIN_TIMEOUT / LIRC_GET_MAX_TIMEOUT - Obtain the possible timeout -range for IR receive. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout) - :name: LIRC_GET_MIN_TIMEOUT - -.. c:function:: int ioctl( int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout) - :name: LIRC_GET_MAX_TIMEOUT - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``timeout`` - Timeout, in microseconds. - - -Description -=========== - -Some devices have internal timers that can be used to detect when -there's no IR activity for a long time. This can help lircd in -detecting that a IR signal is finished and can speed up the decoding -process. Returns an integer value with the minimum/maximum timeout -that can be set. - -.. note:: - - Some devices have a fixed timeout, in that case - both ioctls will return the same value even though the timeout - cannot be changed via :ref:`LIRC_SET_REC_TIMEOUT`. - - -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 ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-header.rst b/Documentation/media/uapi/rc/lirc-header.rst deleted file mode 100644 index c9b4f33e1031..000000000000 --- a/Documentation/media/uapi/rc/lirc-header.rst +++ /dev/null @@ -1,17 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_header: - -**************** -LIRC Header File -**************** - -.. kernel-include:: $BUILDDIR/lirc.h.rst - diff --git a/Documentation/media/uapi/rc/lirc-read.rst b/Documentation/media/uapi/rc/lirc-read.rst deleted file mode 100644 index 256e520bc27e..000000000000 --- a/Documentation/media/uapi/rc/lirc-read.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc-read: - -*********** -LIRC read() -*********** - -Name -==== - -lirc-read - Read from a LIRC device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: ssize_t read( int fd, void *buf, size_t count ) - :name: lirc-read - - -Arguments -========= - -``fd`` - File descriptor returned by ``open()``. - -``buf`` - Buffer to be filled - -``count`` - Max number of bytes to read - -Description -=========== - -:ref:`read() ` attempts to read up to ``count`` bytes from file -descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero, -:ref:`read() ` returns zero and has no other results. If ``count`` -is greater than ``SSIZE_MAX``, the result is unspecified. - -The exact format of the data depends on what :ref:`lirc_modes` a driver -uses. Use :ref:`lirc_get_features` to get the supported mode, and use -:ref:`lirc_set_rec_mode` set the current active mode. - -The mode :ref:`LIRC_MODE_MODE2 ` is for raw IR, -in which packets containing an unsigned int value describing an IR signal are -read from the chardev. - -Alternatively, :ref:`LIRC_MODE_SCANCODE ` can be available, -in this mode scancodes which are either decoded by software decoders, or -by hardware decoders. The :c:type:`rc_proto` member is set to the -:ref:`IR protocol ` -used for transmission, and ``scancode`` to the decoded scancode, -and the ``keycode`` set to the keycode or ``KEY_RESERVED``. - - -Return Value -============ - -On success, the number of bytes read is returned. It is not an error if -this number is smaller than the number of bytes requested, or the amount -of data required for one frame. On error, -1 is returned, and the ``errno`` -variable is set appropriately. diff --git a/Documentation/media/uapi/rc/lirc-set-measure-carrier-mode.rst b/Documentation/media/uapi/rc/lirc-set-measure-carrier-mode.rst deleted file mode 100644 index c80acd85e369..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-measure-carrier-mode.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_measure_carrier_mode: - -*********************************** -ioctl LIRC_SET_MEASURE_CARRIER_MODE -*********************************** - -Name -==== - -LIRC_SET_MEASURE_CARRIER_MODE - enable or disable measure mode - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable ) - :name: LIRC_SET_MEASURE_CARRIER_MODE - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``enable`` - enable = 1 means enable measure mode, enable = 0 means disable measure - mode. - - -Description -=========== - -.. _lirc-mode2-frequency: - -Enable or disable measure mode. If enabled, from the next key -press on, the driver will send ``LIRC_MODE2_FREQUENCY`` packets. By -default this should be turned off. - - -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 ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst b/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst deleted file mode 100644 index 443681d5cc10..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-rec-carrier-range.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_rec_carrier_range: - -******************************** -ioctl LIRC_SET_REC_CARRIER_RANGE -******************************** - -Name -==== - -LIRC_SET_REC_CARRIER_RANGE - Set lower bound of the carrier used to modulate -IR receive. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency ) - :name: LIRC_SET_REC_CARRIER_RANGE - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``frequency`` - Frequency of the carrier that modulates PWM data, in Hz. - -Description -=========== - -This ioctl sets the upper range of carrier frequency that will be recognized -by the IR receiver. - -.. note:: - - To set a range use :ref:`LIRC_SET_REC_CARRIER_RANGE - ` with the lower bound first and later call - :ref:`LIRC_SET_REC_CARRIER ` with the upper bound. - -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 ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-rec-carrier.rst b/Documentation/media/uapi/rc/lirc-set-rec-carrier.rst deleted file mode 100644 index cbe1e48b2a4a..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-rec-carrier.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_rec_carrier: - -************************** -ioctl LIRC_SET_REC_CARRIER -************************** - -Name -==== - -LIRC_SET_REC_CARRIER - Set carrier used to modulate IR receive. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_REC_CARRIER, __u32 *frequency ) - :name: LIRC_SET_REC_CARRIER - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``frequency`` - Frequency of the carrier that modulates PWM data, in Hz. - -Description -=========== - -Set receive carrier used to modulate IR PWM pulses and spaces. - -.. note:: - - If called together with :ref:`LIRC_SET_REC_CARRIER_RANGE`, this ioctl - sets the upper bound frequency that will be recognized by the 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 ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst b/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst deleted file mode 100644 index d06d69414c1e..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-rec-timeout-reports.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_rec_timeout_reports: - -********************************** -ioctl LIRC_SET_REC_TIMEOUT_REPORTS -********************************** - -Name -==== - -LIRC_SET_REC_TIMEOUT_REPORTS - enable or disable timeout reports for IR receive - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT_REPORTS, __u32 *enable ) - :name: LIRC_SET_REC_TIMEOUT_REPORTS - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``enable`` - enable = 1 means enable timeout report, enable = 0 means disable timeout - reports. - - -Description -=========== - -.. _lirc-mode2-timeout: - -Enable or disable timeout reports for IR receive. By default, timeout reports -should be turned off. - -.. note:: - - This ioctl is only valid for :ref:`LIRC_MODE_MODE2 `. - - -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 ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst b/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst deleted file mode 100644 index 163ac6065737..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-rec-timeout.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_rec_timeout: -.. _lirc_get_rec_timeout: - -*************************************************** -ioctl LIRC_GET_REC_TIMEOUT and LIRC_SET_REC_TIMEOUT -*************************************************** - -Name -==== - -LIRC_GET_REC_TIMEOUT/LIRC_SET_REC_TIMEOUT - Get/set the integer value for IR inactivity timeout. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout ) - :name: LIRC_GET_REC_TIMEOUT - -.. c:function:: int ioctl( int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout ) - :name: LIRC_SET_REC_TIMEOUT - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``timeout`` - Timeout, in microseconds. - - -Description -=========== - -Get and set the integer value for IR inactivity timeout. - -If supported by the hardware, setting it to 0 disables all hardware timeouts -and data should be reported as soon as possible. If the exact value -cannot be set, then the next possible value _greater_ than the -given value should be set. - -.. note:: - - The range of supported timeout is given by :ref:`LIRC_GET_MIN_TIMEOUT`. - - -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 ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-send-carrier.rst b/Documentation/media/uapi/rc/lirc-set-send-carrier.rst deleted file mode 100644 index cffc6c1e15cc..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-send-carrier.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_send_carrier: - -*************************** -ioctl LIRC_SET_SEND_CARRIER -*************************** - -Name -==== - -LIRC_SET_SEND_CARRIER - Set send carrier used to modulate IR TX. - - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency ) - :name: LIRC_SET_SEND_CARRIER - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``frequency`` - Frequency of the carrier to be modulated, in Hz. - -Description -=========== - -Set send carrier used to modulate IR PWM pulses and spaces. - - -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 ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-send-duty-cycle.rst b/Documentation/media/uapi/rc/lirc-set-send-duty-cycle.rst deleted file mode 100644 index 08ab3d1a96cd..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-send-duty-cycle.rst +++ /dev/null @@ -1,54 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_send_duty_cycle: - -****************************** -ioctl LIRC_SET_SEND_DUTY_CYCLE -****************************** - -Name -==== - -LIRC_SET_SEND_DUTY_CYCLE - Set the duty cycle of the carrier signal for -IR transmit. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle) - :name: LIRC_SET_SEND_DUTY_CYCLE - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``duty_cycle`` - Duty cicle, describing the pulse width in percent (from 1 to 99) of - the total cycle. Values 0 and 100 are reserved. - - -Description -=========== - -Get/set the duty cycle of the carrier signal for IR transmit. - -Currently, no special meaning is defined for 0 or 100, but this -could be used to switch off carrier generation in the future, so -these values should be reserved. - - -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 ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-transmitter-mask.rst b/Documentation/media/uapi/rc/lirc-set-transmitter-mask.rst deleted file mode 100644 index 889a739eaf0d..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-transmitter-mask.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_transmitter_mask: - -******************************* -ioctl LIRC_SET_TRANSMITTER_MASK -******************************* - -Name -==== - -LIRC_SET_TRANSMITTER_MASK - Enables send codes on a given set of transmitters - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask ) - :name: LIRC_SET_TRANSMITTER_MASK - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``mask`` - Mask with channels to enable tx. Channel 0 is the least significant bit. - - -Description -=========== - -Some IR TX devices have multiple output channels, in such case, -:ref:`LIRC_CAN_SET_TRANSMITTER_MASK ` is -returned via :ref:`LIRC_GET_FEATURES` and this ioctl sets what channels will -send IR codes. - -This ioctl enables the given set of transmitters. The first transmitter is -encoded by the least significant bit and so on. - -When an invalid bit mask is given, i.e. a bit is set, even though the device -does not have so many transitters, then this ioctl returns the number of -available transitters and does nothing otherwise. - - -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 ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-set-wideband-receiver.rst b/Documentation/media/uapi/rc/lirc-set-wideband-receiver.rst deleted file mode 100644 index 592715452fce..000000000000 --- a/Documentation/media/uapi/rc/lirc-set-wideband-receiver.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc_set_wideband_receiver: - -******************************** -ioctl LIRC_SET_WIDEBAND_RECEIVER -******************************** - -Name -==== - -LIRC_SET_WIDEBAND_RECEIVER - enable wide band receiver. - -Synopsis -======== - -.. c:function:: int ioctl( int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable ) - :name: LIRC_SET_WIDEBAND_RECEIVER - -Arguments -========= - -``fd`` - File descriptor returned by open(). - -``enable`` - enable = 1 means enable wideband receiver, enable = 0 means disable - wideband receiver. - - -Description -=========== - -Some receivers are equipped with special wide band receiver which is -intended to be used to learn output of existing remote. This ioctl -allows enabling or disabling it. - -This might be useful of receivers that have otherwise narrow band receiver -that prevents them to be used with some remotes. Wide band receiver might -also be more precise. On the other hand its disadvantage it usually -reduced range of reception. - -.. note:: - - Wide band receiver might be implictly enabled if you enable - carrier reports. In that case it will be disabled as soon as you disable - carrier reports. Trying to disable wide band receiver while carrier - reports are active will do nothing. - - -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 ` chapter. diff --git a/Documentation/media/uapi/rc/lirc-write.rst b/Documentation/media/uapi/rc/lirc-write.rst deleted file mode 100644 index eafe13203ea3..000000000000 --- a/Documentation/media/uapi/rc/lirc-write.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _lirc-write: - -************ -LIRC write() -************ - -Name -==== - -lirc-write - Write to a LIRC device - - -Synopsis -======== - -.. code-block:: c - - #include - - -.. c:function:: ssize_t write( int fd, void *buf, size_t count ) - :name: lirc-write - -Arguments -========= - -``fd`` - File descriptor returned by ``open()``. - -``buf`` - Buffer with data to be written - -``count`` - Number of bytes at the buffer - -Description -=========== - -:ref:`write() ` writes up to ``count`` bytes to the device -referenced by the file descriptor ``fd`` from the buffer starting at -``buf``. - -The exact format of the data depends on what mode a driver is in, use -:ref:`lirc_get_features` to get the supported modes and use -:ref:`lirc_set_send_mode` set the mode. - -When in :ref:`LIRC_MODE_PULSE ` mode, the data written to -the chardev is a pulse/space sequence of integer values. Pulses and spaces -are only marked implicitly by their position. The data must start and end -with a pulse, therefore, the data must always include an uneven number of -samples. The write function blocks until the data has been transmitted -by the hardware. If more data is provided than the hardware can send, the -driver returns ``EINVAL``. - -When in :ref:`LIRC_MODE_SCANCODE ` mode, one -``struct lirc_scancode`` must be written to the chardev at a time, else -``EINVAL`` is returned. Set the desired scancode in the ``scancode`` member, -and the :ref:`IR protocol ` in the -:c:type:`rc_proto`: member. All other members must be -set to 0, else ``EINVAL`` is returned. If there is no protocol encoder -for the protocol or the scancode is not valid for the specified protocol, -``EINVAL`` is returned. The write function blocks until the scancode -is transmitted by the hardware. - - -Return Value -============ - -On success, the number of bytes written is returned. It is not an error if -this number is smaller than the number of bytes requested, or the amount -of data required for one frame. On error, -1 is returned, and the ``errno`` -variable is set appropriately. The generic error codes are described at the -:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/rc/rc-intro.rst b/Documentation/media/uapi/rc/rc-intro.rst deleted file mode 100644 index 37c5f90c76e7..000000000000 --- a/Documentation/media/uapi/rc/rc-intro.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _Remote_controllers_Intro: - -************ -Introduction -************ - -Currently, most analog and digital devices have a Infrared input for -remote controllers. Each manufacturer has their own type of control. It -is not rare for the same manufacturer to ship different types of -controls, depending on the device. - -A Remote Controller interface is mapped as a normal evdev/input -interface, just like a keyboard or a mouse. So, it uses all ioctls -already defined for any other input devices. - -However, remove controllers are more flexible than a normal input -device, as the IR receiver (and/or transmitter) can be used in -conjunction with a wide variety of different IR remotes. - -In order to allow flexibility, the Remote Controller subsystem allows -controlling the RC-specific attributes via -:ref:`the sysfs class nodes `. diff --git a/Documentation/media/uapi/rc/rc-protos.rst b/Documentation/media/uapi/rc/rc-protos.rst deleted file mode 100644 index b250ebe301d5..000000000000 --- a/Documentation/media/uapi/rc/rc-protos.rst +++ /dev/null @@ -1,456 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _Remote_controllers_Protocols: - -***************************************** -Remote Controller Protocols and Scancodes -***************************************** - -IR is encoded as a series of pulses and spaces, using a protocol. These -protocols can encode e.g. an address (which device should respond) and a -command: what it should do. The values for these are not always consistent -across different devices for a given protocol. - -Therefore out the output of the IR decoder is a scancode; a single u32 -value. Using keymap tables this can be mapped to linux key codes. - -Other things can be encoded too. Some IR protocols encode a toggle bit; this -is to distinguish whether the same button is being held down, or has been -released and pressed again. If has been released and pressed again, the -toggle bit will invert from one IR message to the next. - -Some remotes have a pointer-type device which can used to control the -mouse; some air conditioning systems can have their target temperature -target set in IR. - -The following are the protocols the kernel knows about and also lists -how scancodes are encoded for each protocol. - -rc-5 (RC_PROTO_RC5) -------------------- - -This IR protocol uses manchester encoding to encode 14 bits. There is a -detailed description here https://www.sbprojects.net/knowledge/ir/rc5.php. - -The scancode encoding is *not* consistent with the lirc daemon (lircd) rc5 -protocol, or the manchester BPF decoder. - -.. flat-table:: rc5 bits scancode mapping - :widths: 1 1 2 - - * - rc-5 bit - - - scancode bit - - - description - - * - 1 - - - none - - - Start bit, always set - - * - 1 - - - 6 (inverted) - - - 2nd start bit in rc5, re-used as 6th command bit - - * - 1 - - - none - - - Toggle bit - - * - 5 - - - 8 to 13 - - - Address - - * - 6 - - - 0 to 5 - - - Command - -There is a variant of rc5 called either rc5x or extended rc5 -where there the second stop bit is the 6th commmand bit, but inverted. -This is done so it the scancodes and encoding is compatible with existing -schemes. This bit is stored in bit 6 of the scancode, inverted. This is -done to keep it compatible with plain rc-5 where there are two start bits. - -rc-5-sz (RC_PROTO_RC5_SZ) -------------------------- -This is much like rc-5 but one bit longer. The scancode is encoded -differently. - -.. flat-table:: rc-5-sz bits scancode mapping - :widths: 1 1 2 - - * - rc-5-sz bits - - - scancode bit - - - description - - * - 1 - - - none - - - Start bit, always set - - * - 1 - - - 13 - - - Address bit - - * - 1 - - - none - - - Toggle bit - - * - 6 - - - 6 to 11 - - - Address - - * - 6 - - - 0 to 5 - - - Command - -rc-5x-20 (RC_PROTO_RC5X_20) ---------------------------- - -This rc-5 extended to encoded 20 bits. The is a 3555 microseconds space -after the 8th bit. - -.. flat-table:: rc-5x-20 bits scancode mapping - :widths: 1 1 2 - - * - rc-5-sz bits - - - scancode bit - - - description - - * - 1 - - - none - - - Start bit, always set - - * - 1 - - - 14 - - - Address bit - - * - 1 - - - none - - - Toggle bit - - * - 5 - - - 16 to 20 - - - Address - - * - 6 - - - 8 to 13 - - - Address - - * - 6 - - - 0 to 5 - - - Command - - -jvc (RC_PROTO_JVC) ------------------- - -The jvc protocol is much like nec, without the inverted values. It is -described here https://www.sbprojects.net/knowledge/ir/jvc.php. - -The scancode is a 16 bits value, where the address is the lower 8 bits -and the command the higher 8 bits; this is reversed from IR order. - -sony-12 (RC_PROTO_SONY12) -------------------------- - -The sony protocol is a pulse-width encoding. There are three variants, -which just differ in number of bits and scancode encoding. - -.. flat-table:: sony-12 bits scancode mapping - :widths: 1 1 2 - - * - sony-12 bits - - - scancode bit - - - description - - * - 5 - - - 16 to 20 - - - device - - * - 7 - - - 0 to 6 - - - function - -sony-15 (RC_PROTO_SONY15) -------------------------- - -The sony protocol is a pulse-width encoding. There are three variants, -which just differ in number of bits and scancode encoding. - -.. flat-table:: sony-12 bits scancode mapping - :widths: 1 1 2 - - * - sony-12 bits - - - scancode bit - - - description - - * - 8 - - - 16 to 23 - - - device - - * - 7 - - - 0 to 6 - - - function - -sony-20 (RC_PROTO_SONY20) -------------------------- - -The sony protocol is a pulse-width encoding. There are three variants, -which just differ in number of bits and scancode encoding. - -.. flat-table:: sony-20 bits scancode mapping - :widths: 1 1 2 - - * - sony-20 bits - - - scancode bit - - - description - - * - 5 - - - 16 to 20 - - - device - - * - 7 - - - 0 to 7 - - - device - - * - 8 - - - 8 to 15 - - - extended bits - -nec (RC_PROTO_NEC) ------------------- - -The nec protocol encodes an 8 bit address and an 8 bit command. It is -described here https://www.sbprojects.net/knowledge/ir/nec.php. Note -that the protocol sends least significant bit first. - -As a check, the nec protocol sends the address and command twice; the -second time it is inverted. This is done for verification. - -A plain nec IR message has 16 bits; the high 8 bits are the address -and the low 8 bits are the command. - -nec-x (RC_PROTO_NECX) ---------------------- - -Extended nec has a 16 bit address and a 8 bit command. This is encoded -as a 24 bit value as you would expect, with the lower 8 bits the command -and the upper 16 bits the address. - -nec-32 (RC_PROTO_NEC32) ------------------------ - -nec-32 does not send an inverted address or an inverted command; the -entire message, all 32 bits, are used. - -For this to be decoded correctly, the second 8 bits must not be the -inverted value of the first, and also the last 8 bits must not be the -inverted value of the third 8 bit value. - -The scancode has a somewhat unusual encoding. - -.. flat-table:: nec-32 bits scancode mapping - - * - nec-32 bits - - - scancode bit - - * - First 8 bits - - - 16 to 23 - - * - Second 8 bits - - - 24 to 31 - - * - Third 8 bits - - - 0 to 7 - - * - Fourth 8 bits - - - 8 to 15 - -sanyo (RC_PROTO_SANYO) ----------------------- - -The sanyo protocol is like the nec protocol, but with 13 bits address -rather than 8 bits. Both the address and the command are followed by -their inverted versions, but these are not present in the scancodes. - -Bis 8 to 20 of the scancode is the 13 bits address, and the lower 8 -bits are the command. - -mcir2-kbd (RC_PROTO_MCIR2_KBD) ------------------------------- - -This protocol is generated by the Microsoft MCE keyboard for keyboard -events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded. - -mcir2-mse (RC_PROTO_MCIR2_MSE) ------------------------------- - -This protocol is generated by the Microsoft MCE keyboard for pointer -events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded. - -rc-6-0 (RC_PROTO_RC6_0) ------------------------ - -This is the rc-6 in mode 0. rc-6 is described here -https://www.sbprojects.net/knowledge/ir/rc6.php. -The scancode is the exact 16 bits as in the protocol. There is also a -toggle bit. - -rc-6-6a-20 (RC_PROTO_RC6_6A_20) -------------------------------- - -This is the rc-6 in mode 6a, 20 bits. rc-6 is described here -https://www.sbprojects.net/knowledge/ir/rc6.php. -The scancode is the exact 20 bits -as in the protocol. There is also a toggle bit. - -rc-6-6a-24 (RC_PROTO_RC6_6A_24) -------------------------------- - -This is the rc-6 in mode 6a, 24 bits. rc-6 is described here -https://www.sbprojects.net/knowledge/ir/rc6.php. -The scancode is the exact 24 bits -as in the protocol. There is also a toggle bit. - -rc-6-6a-32 (RC_PROTO_RC6_6A_32) -------------------------------- - -This is the rc-6 in mode 6a, 32 bits. rc-6 is described here -https://www.sbprojects.net/knowledge/ir/rc6.php. -The upper 16 bits are the vendor, -and the lower 16 bits are the vendor-specific bits. This protocol is -for the non-Microsoft MCE variant (vendor != 0x800f). - - -rc-6-mce (RC_PROTO_RC6_MCE) ---------------------------- - -This is the rc-6 in mode 6a, 32 bits. The upper 16 bits are the vendor, -and the lower 16 bits are the vendor-specific bits. This protocol is -for the Microsoft MCE variant (vendor = 0x800f). The toggle bit in the -protocol itself is ignored, and the 16th bit should be takes as the toggle -bit. - -sharp (RC_PROTO_SHARP) ----------------------- - -This is a protocol used by Sharp VCRs, is described here -https://www.sbprojects.net/knowledge/ir/sharp.php. There is a very long -(40ms) space between the normal and inverted values, and some IR receivers -cannot decode this. - -There is a 5 bit address and a 8 bit command. In the scancode the address is -in bits 8 to 12, and the command in bits 0 to 7. - -xmp (RC_PROTO_XMP) ------------------- - -This protocol has several versions and only version 1 is supported. Refer -to the decoder (ir-xmp-decoder.c) to see how it is encoded. - - -cec (RC_PROTO_CEC) ------------------- - -This is not an IR protocol, this is a protocol over CEC. The CEC -infrastructure uses rc-core for handling CEC commands, so that they -can easily be remapped. - -imon (RC_PROTO_IMON) --------------------- - -This protocol is used by Antec Veris/SoundGraph iMON remotes. - -The protocol -describes both button presses and pointer movements. The protocol encodes -31 bits, and the scancode is simply the 31 bits with the top bit always 0. - -rc-mm-12 (RC_PROTO_RCMM12) --------------------------- - -The rc-mm protocol is described here -https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply -the 12 bits. - -rc-mm-24 (RC_PROTO_RCMM24) --------------------------- - -The rc-mm protocol is described here -https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply -the 24 bits. - -rc-mm-32 (RC_PROTO_RCMM32) --------------------------- - -The rc-mm protocol is described here -https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply -the 32 bits. - -xbox-dvd (RC_PROTO_XBOX_DVD) ----------------------------- - -This protocol is used by XBox DVD Remote, which was made for the original -XBox. There is no in-kernel decoder or encoder for this protocol. The usb -device decodes the protocol. There is a BPF decoder available in v4l-utils. diff --git a/Documentation/media/uapi/rc/rc-sysfs-nodes.rst b/Documentation/media/uapi/rc/rc-sysfs-nodes.rst deleted file mode 100644 index b8e8319e3317..000000000000 --- a/Documentation/media/uapi/rc/rc-sysfs-nodes.rst +++ /dev/null @@ -1,151 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _remote_controllers_sysfs_nodes: - -******************************* -Remote Controller's sysfs nodes -******************************* - -As defined at ``Documentation/ABI/testing/sysfs-class-rc``, those are -the sysfs nodes that control the Remote Controllers: - - -.. _sys_class_rc: - -/sys/class/rc/ -============== - -The ``/sys/class/rc/`` class sub-directory belongs to the Remote -Controller core and provides a sysfs interface for configuring infrared -remote controller receivers. - - -.. _sys_class_rc_rcN: - -/sys/class/rc/rcN/ -================== - -A ``/sys/class/rc/rcN`` directory is created for each remote control -receiver device where N is the number of the receiver. - - -.. _sys_class_rc_rcN_protocols: - -/sys/class/rc/rcN/protocols -=========================== - -Reading this file returns a list of available protocols, something like:: - - rc5 [rc6] nec jvc [sony] - -Enabled protocols are shown in [] brackets. - -Writing "+proto" will add a protocol to the list of enabled protocols. - -Writing "-proto" will remove a protocol from the list of enabled -protocols. - -Writing "proto" will enable only "proto". - -Writing "none" will disable all protocols. - -Write fails with ``EINVAL`` if an invalid protocol combination or unknown -protocol name is used. - - -.. _sys_class_rc_rcN_filter: - -/sys/class/rc/rcN/filter -======================== - -Sets the scancode filter expected value. - -Use in combination with ``/sys/class/rc/rcN/filter_mask`` to set the -expected value of the bits set in the filter mask. If the hardware -supports it then scancodes which do not match the filter will be -ignored. Otherwise the write will fail with an error. - -This value may be reset to 0 if the current protocol is altered. - - -.. _sys_class_rc_rcN_filter_mask: - -/sys/class/rc/rcN/filter_mask -============================= - -Sets the scancode filter mask of bits to compare. Use in combination -with ``/sys/class/rc/rcN/filter`` to set the bits of the scancode which -should be compared against the expected value. A value of 0 disables the -filter to allow all valid scancodes to be processed. - -If the hardware supports it then scancodes which do not match the filter -will be ignored. Otherwise the write will fail with an error. - -This value may be reset to 0 if the current protocol is altered. - - -.. _sys_class_rc_rcN_wakeup_protocols: - -/sys/class/rc/rcN/wakeup_protocols -================================== - -Reading this file returns a list of available protocols to use for the -wakeup filter, something like:: - - rc-5 nec nec-x rc-6-0 rc-6-6a-24 [rc-6-6a-32] rc-6-mce - -Note that protocol variants are listed, so ``nec``, ``sony``, ``rc-5``, ``rc-6`` -have their different bit length encodings listed if available. - -Note that all protocol variants are listed. - -The enabled wakeup protocol is shown in [] brackets. - -Only one protocol can be selected at a time. - -Writing "proto" will use "proto" for wakeup events. - -Writing "none" will disable wakeup. - -Write fails with ``EINVAL`` if an invalid protocol combination or unknown -protocol name is used, or if wakeup is not supported by the hardware. - - -.. _sys_class_rc_rcN_wakeup_filter: - -/sys/class/rc/rcN/wakeup_filter -=============================== - -Sets the scancode wakeup filter expected value. Use in combination with -``/sys/class/rc/rcN/wakeup_filter_mask`` to set the expected value of -the bits set in the wakeup filter mask to trigger a system wake event. - -If the hardware supports it and wakeup_filter_mask is not 0 then -scancodes which match the filter will wake the system from e.g. suspend -to RAM or power off. Otherwise the write will fail with an error. - -This value may be reset to 0 if the wakeup protocol is altered. - - -.. _sys_class_rc_rcN_wakeup_filter_mask: - -/sys/class/rc/rcN/wakeup_filter_mask -==================================== - -Sets the scancode wakeup filter mask of bits to compare. Use in -combination with ``/sys/class/rc/rcN/wakeup_filter`` to set the bits of -the scancode which should be compared against the expected value to -trigger a system wake event. - -If the hardware supports it and wakeup_filter_mask is not 0 then -scancodes which match the filter will wake the system from e.g. suspend -to RAM or power off. Otherwise the write will fail with an error. - -This value may be reset to 0 if the wakeup protocol is altered. diff --git a/Documentation/media/uapi/rc/rc-table-change.rst b/Documentation/media/uapi/rc/rc-table-change.rst deleted file mode 100644 index 4a2e601b89fb..000000000000 --- a/Documentation/media/uapi/rc/rc-table-change.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _Remote_controllers_table_change: - -******************************************* -Changing default Remote Controller mappings -******************************************* - -The event interface provides two ioctls to be used against the -/dev/input/event device, to allow changing the default keymapping. - -This program demonstrates how to replace the keymap tables. - - -.. toctree:: - :maxdepth: 1 - - keytable.c diff --git a/Documentation/media/uapi/rc/rc-tables.rst b/Documentation/media/uapi/rc/rc-tables.rst deleted file mode 100644 index 20d7c686922b..000000000000 --- a/Documentation/media/uapi/rc/rc-tables.rst +++ /dev/null @@ -1,766 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _Remote_controllers_tables: - -************************ -Remote controller tables -************************ - -Unfortunately, for several years, there was no effort to create uniform -IR keycodes for different devices. This caused the same IR keyname to be -mapped completely differently on different IR devices. This resulted -that the same IR keyname to be mapped completely different on different -IR's. Due to that, V4L2 API now specifies a standard for mapping Media -keys on IR. - -This standard should be used by both V4L/DVB drivers and userspace -applications - -The modules register the remote as keyboard within the linux input -layer. This means that the IR key strokes will look like normal keyboard -key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event -devices (CONFIG_INPUT_EVDEV) it is possible for applications to access -the remote via /dev/input/event devices. - - -.. _rc_standard_keymap: - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: IR default keymapping - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - - - .. row 1 - - - Key code - - - Meaning - - - Key examples on IR - - - .. row 2 - - - **Numeric keys** - - - .. row 3 - - - ``KEY_NUMERIC_0`` - - - Keyboard digit 0 - - - 0 - - - .. row 4 - - - ``KEY_NUMERIC_1`` - - - Keyboard digit 1 - - - 1 - - - .. row 5 - - - ``KEY_NUMERIC_2`` - - - Keyboard digit 2 - - - 2 - - - .. row 6 - - - ``KEY_NUMERIC_3`` - - - Keyboard digit 3 - - - 3 - - - .. row 7 - - - ``KEY_NUMERIC_4`` - - - Keyboard digit 4 - - - 4 - - - .. row 8 - - - ``KEY_NUMERIC_5`` - - - Keyboard digit 5 - - - 5 - - - .. row 9 - - - ``KEY_NUMERIC_6`` - - - Keyboard digit 6 - - - 6 - - - .. row 10 - - - ``KEY_NUMERIC_7`` - - - Keyboard digit 7 - - - 7 - - - .. row 11 - - - ``KEY_NUMERIC_8`` - - - Keyboard digit 8 - - - 8 - - - .. row 12 - - - ``KEY_NUMERIC_9`` - - - Keyboard digit 9 - - - 9 - - - .. row 13 - - - **Movie play control** - - - .. row 14 - - - ``KEY_FORWARD`` - - - Instantly advance in time - - - >> / FORWARD - - - .. row 15 - - - ``KEY_BACK`` - - - Instantly go back in time - - - <<< / BACK - - - .. row 16 - - - ``KEY_FASTFORWARD`` - - - Play movie faster - - - >>> / FORWARD - - - .. row 17 - - - ``KEY_REWIND`` - - - Play movie back - - - REWIND / BACKWARD - - - .. row 18 - - - ``KEY_NEXT`` - - - Select next chapter / sub-chapter / interval - - - NEXT / SKIP - - - .. row 19 - - - ``KEY_PREVIOUS`` - - - Select previous chapter / sub-chapter / interval - - - << / PREV / PREVIOUS - - - .. row 20 - - - ``KEY_AGAIN`` - - - Repeat the video or a video interval - - - REPEAT / LOOP / RECALL - - - .. row 21 - - - ``KEY_PAUSE`` - - - Pause stream - - - PAUSE / FREEZE - - - .. row 22 - - - ``KEY_PLAY`` - - - Play movie at the normal timeshift - - - NORMAL TIMESHIFT / LIVE / > - - - .. row 23 - - - ``KEY_PLAYPAUSE`` - - - Alternate between play and pause - - - PLAY / PAUSE - - - .. row 24 - - - ``KEY_STOP`` - - - Stop stream - - - STOP - - - .. row 25 - - - ``KEY_RECORD`` - - - Start/stop recording stream - - - CAPTURE / REC / RECORD/PAUSE - - - .. row 26 - - - ``KEY_CAMERA`` - - - Take a picture of the image - - - CAMERA ICON / CAPTURE / SNAPSHOT - - - .. row 27 - - - ``KEY_SHUFFLE`` - - - Enable shuffle mode - - - SHUFFLE - - - .. row 28 - - - ``KEY_TIME`` - - - Activate time shift mode - - - TIME SHIFT - - - .. row 29 - - - ``KEY_TITLE`` - - - Allow changing the chapter - - - CHAPTER - - - .. row 30 - - - ``KEY_SUBTITLE`` - - - Allow changing the subtitle - - - SUBTITLE - - - .. row 31 - - - **Image control** - - - .. row 32 - - - ``KEY_BRIGHTNESSDOWN`` - - - Decrease Brightness - - - BRIGHTNESS DECREASE - - - .. row 33 - - - ``KEY_BRIGHTNESSUP`` - - - Increase Brightness - - - BRIGHTNESS INCREASE - - - .. row 34 - - - ``KEY_ANGLE`` - - - Switch video camera angle (on videos with more than one angle - stored) - - - ANGLE / SWAP - - - .. row 35 - - - ``KEY_EPG`` - - - Open the Elecrowonic Play Guide (EPG) - - - EPG / GUIDE - - - .. row 36 - - - ``KEY_TEXT`` - - - Activate/change closed caption mode - - - CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX - - - .. row 37 - - - **Audio control** - - - .. row 38 - - - ``KEY_AUDIO`` - - - Change audio source - - - AUDIO SOURCE / AUDIO / MUSIC - - - .. row 39 - - - ``KEY_MUTE`` - - - Mute/unmute audio - - - MUTE / DEMUTE / UNMUTE - - - .. row 40 - - - ``KEY_VOLUMEDOWN`` - - - Decrease volume - - - VOLUME- / VOLUME DOWN - - - .. row 41 - - - ``KEY_VOLUMEUP`` - - - Increase volume - - - VOLUME+ / VOLUME UP - - - .. row 42 - - - ``KEY_MODE`` - - - Change sound mode - - - MONO/STEREO - - - .. row 43 - - - ``KEY_LANGUAGE`` - - - Select Language - - - 1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL - - - .. row 44 - - - **Channel control** - - - .. row 45 - - - ``KEY_CHANNEL`` - - - Go to the next favorite channel - - - ALT / CHANNEL / CH SURFING / SURF / FAV - - - .. row 46 - - - ``KEY_CHANNELDOWN`` - - - Decrease channel sequentially - - - CHANNEL - / CHANNEL DOWN / DOWN - - - .. row 47 - - - ``KEY_CHANNELUP`` - - - Increase channel sequentially - - - CHANNEL + / CHANNEL UP / UP - - - .. row 48 - - - ``KEY_DIGITS`` - - - Use more than one digit for channel - - - PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit - - - .. row 49 - - - ``KEY_SEARCH`` - - - Start channel autoscan - - - SCAN / AUTOSCAN - - - .. row 50 - - - **Colored keys** - - - .. row 51 - - - ``KEY_BLUE`` - - - IR Blue key - - - BLUE - - - .. row 52 - - - ``KEY_GREEN`` - - - IR Green Key - - - GREEN - - - .. row 53 - - - ``KEY_RED`` - - - IR Red key - - - RED - - - .. row 54 - - - ``KEY_YELLOW`` - - - IR Yellow key - - - YELLOW - - - .. row 55 - - - **Media selection** - - - .. row 56 - - - ``KEY_CD`` - - - Change input source to Compact Disc - - - CD - - - .. row 57 - - - ``KEY_DVD`` - - - Change input to DVD - - - DVD / DVD MENU - - - .. row 58 - - - ``KEY_EJECTCLOSECD`` - - - Open/close the CD/DVD player - - - -> ) / CLOSE / OPEN - - - .. row 59 - - - ``KEY_MEDIA`` - - - Turn on/off Media application - - - PC/TV / TURN ON/OFF APP - - - .. row 60 - - - ``KEY_PC`` - - - Selects from TV to PC - - - PC - - - .. row 61 - - - ``KEY_RADIO`` - - - Put into AM/FM radio mode - - - RADIO / TV/FM / TV/RADIO / FM / FM/RADIO - - - .. row 62 - - - ``KEY_TV`` - - - Select tv mode - - - TV / LIVE TV - - - .. row 63 - - - ``KEY_TV2`` - - - Select Cable mode - - - AIR/CBL - - - .. row 64 - - - ``KEY_VCR`` - - - Select VCR mode - - - VCR MODE / DTR - - - .. row 65 - - - ``KEY_VIDEO`` - - - Alternate between input modes - - - SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO - - - .. row 66 - - - **Power control** - - - .. row 67 - - - ``KEY_POWER`` - - - Turn on/off computer - - - SYSTEM POWER / COMPUTER POWER - - - .. row 68 - - - ``KEY_POWER2`` - - - Turn on/off application - - - TV ON/OFF / POWER - - - .. row 69 - - - ``KEY_SLEEP`` - - - Activate sleep timer - - - SLEEP / SLEEP TIMER - - - .. row 70 - - - ``KEY_SUSPEND`` - - - Put computer into suspend mode - - - STANDBY / SUSPEND - - - .. row 71 - - - **Window control** - - - .. row 72 - - - ``KEY_CLEAR`` - - - Stop stream and return to default input video/audio - - - CLEAR / RESET / BOSS KEY - - - .. row 73 - - - ``KEY_CYCLEWINDOWS`` - - - Minimize windows and move to the next one - - - ALT-TAB / MINIMIZE / DESKTOP - - - .. row 74 - - - ``KEY_FAVORITES`` - - - Open the favorites stream window - - - TV WALL / Favorites - - - .. row 75 - - - ``KEY_MENU`` - - - Call application menu - - - 2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL - - - .. row 76 - - - ``KEY_NEW`` - - - Open/Close Picture in Picture - - - PIP - - - .. row 77 - - - ``KEY_OK`` - - - Send a confirmation code to application - - - OK / ENTER / RETURN - - - .. row 78 - - - ``KEY_ASPECT_RATIO`` - - - Select screen aspect ratio - - - 4:3 16:9 SELECT - - - .. row 79 - - - ``KEY_FULL_SCREEN`` - - - Put device into zoom/full screen mode - - - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH - - - .. row 80 - - - **Navigation keys** - - - .. row 81 - - - ``KEY_ESC`` - - - Cancel current operation - - - CANCEL / BACK - - - .. row 82 - - - ``KEY_HELP`` - - - Open a Help window - - - HELP - - - .. row 83 - - - ``KEY_HOMEPAGE`` - - - Navigate to Homepage - - - HOME - - - .. row 84 - - - ``KEY_INFO`` - - - Open On Screen Display - - - DISPLAY INFORMATION / OSD - - - .. row 85 - - - ``KEY_WWW`` - - - Open the default browser - - - WEB - - - .. row 86 - - - ``KEY_UP`` - - - Up key - - - UP - - - .. row 87 - - - ``KEY_DOWN`` - - - Down key - - - DOWN - - - .. row 88 - - - ``KEY_LEFT`` - - - Left key - - - LEFT - - - .. row 89 - - - ``KEY_RIGHT`` - - - Right key - - - RIGHT - - - .. row 90 - - - **Miscellaneous keys** - - - .. row 91 - - - ``KEY_DOT`` - - - Return a dot - - - . - - - .. row 92 - - - ``KEY_FN`` - - - Select a function - - - FUNCTION - - -It should be noted that, sometimes, there some fundamental missing keys -at some cheaper IR's. Due to that, it is recommended to: - - -.. _rc_keymap_notes: - -.. flat-table:: Notes - :header-rows: 0 - :stub-columns: 0 - - - - .. row 1 - - - On simpler IR's, without separate channel keys, you need to map UP - as ``KEY_CHANNELUP`` - - - .. row 2 - - - On simpler IR's, without separate channel keys, you need to map - DOWN as ``KEY_CHANNELDOWN`` - - - .. row 3 - - - On simpler IR's, without separate volume keys, you need to map - LEFT as ``KEY_VOLUMEDOWN`` - - - .. row 4 - - - On simpler IR's, without separate volume keys, you need to map - RIGHT as ``KEY_VOLUMEUP`` diff --git a/Documentation/media/uapi/rc/remote_controllers.rst b/Documentation/media/uapi/rc/remote_controllers.rst deleted file mode 100644 index 20e0f986df49..000000000000 --- a/Documentation/media/uapi/rc/remote_controllers.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. include:: - -.. _remote_controllers: - -################################ -Part III - Remote Controller API -################################ - -.. only:: html - - .. class:: toc-title - - Table of Contents - -.. toctree:: - :maxdepth: 5 - :numbered: - - rc-intro - rc-sysfs-nodes - rc-protos - rc-tables - rc-table-change - lirc-dev - - -********************** -Revision and Copyright -********************** - -Authors: - -- Carvalho Chehab, Mauro - - - Initial version. - -**Copyright** |copy| 2009-2016 : Mauro Carvalho Chehab - -**************** -Revision History -**************** - -:revision: 3.15 / 2014-02-06 (*mcc*) - -Added the interface description and the RC sysfs class description. - - -:revision: 1.0 / 2009-09-06 (*mcc*) - -Initial revision diff --git a/Documentation/media/uapi/v4l/app-pri.rst b/Documentation/media/uapi/v4l/app-pri.rst deleted file mode 100644 index c25c1271b4f6..000000000000 --- a/Documentation/media/uapi/v4l/app-pri.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _app-pri: - -******************** -Application Priority -******************** - -When multiple applications share a device it may be desirable to assign -them different priorities. Contrary to the traditional "rm -rf /" school -of thought, a video recording application could for example block other -applications from changing video controls or switching the current TV -channel. Another objective is to permit low priority applications -working in background, which can be preempted by user controlled -applications and automatically regain control of the device at a later -time. - -Since these features cannot be implemented entirely in user space V4L2 -defines the :ref:`VIDIOC_G_PRIORITY ` and -:ref:`VIDIOC_S_PRIORITY ` ioctls to request and -query the access priority associate with a file descriptor. Opening a -device assigns a medium priority, compatible with earlier versions of -V4L2 and drivers not supporting these ioctls. Applications requiring a -different priority will usually call :ref:`VIDIOC_S_PRIORITY -` after verifying the device with the -:ref:`VIDIOC_QUERYCAP` ioctl. - -Ioctls changing driver properties, such as -:ref:`VIDIOC_S_INPUT `, return an ``EBUSY`` error code -after another application obtained higher priority. diff --git a/Documentation/media/uapi/v4l/async.rst b/Documentation/media/uapi/v4l/async.rst deleted file mode 100644 index be9539313f60..000000000000 --- a/Documentation/media/uapi/v4l/async.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _async: - -**************** -Asynchronous I/O -**************** - -This method is not defined yet. diff --git a/Documentation/media/uapi/v4l/audio.rst b/Documentation/media/uapi/v4l/audio.rst deleted file mode 100644 index 4c7fdbc8a860..000000000000 --- a/Documentation/media/uapi/v4l/audio.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _audio: - -************************ -Audio Inputs and Outputs -************************ - -Audio inputs and outputs are physical connectors of a device. Video -capture devices have inputs, output devices have outputs, zero or more -each. Radio devices have no audio inputs or outputs. They have exactly -one tuner which in fact *is* an audio source, but this API associates -tuners with video inputs or outputs only, and radio devices have none of -these. [#f1]_ A connector on a TV card to loop back the received audio -signal to a sound card is not considered an audio output. - -Audio and video inputs and outputs are associated. Selecting a video -source also selects an audio source. This is most evident when the video -and audio source is a tuner. Further audio connectors can combine with -more than one video input or output. Assumed two composite video inputs -and two audio inputs exist, there may be up to four valid combinations. -The relation of video and audio connectors is defined in the -``audioset`` field of the respective struct -:c:type:`v4l2_input` or struct -:c:type:`v4l2_output`, where each bit represents the index -number, starting at zero, of one audio input or output. - -To learn about the number and attributes of the available inputs and -outputs applications can enumerate them with the -:ref:`VIDIOC_ENUMAUDIO` and -:ref:`VIDIOC_ENUMAUDOUT ` ioctl, respectively. -The struct :c:type:`v4l2_audio` returned by the -:ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal -status information applicable when the current audio input is queried. - -The :ref:`VIDIOC_G_AUDIO ` and -:ref:`VIDIOC_G_AUDOUT ` ioctls report the current -audio input and output, respectively. - -.. note:: - - Note that, unlike :ref:`VIDIOC_G_INPUT ` and - :ref:`VIDIOC_G_OUTPUT ` these ioctls return a - structure as :ref:`VIDIOC_ENUMAUDIO` and - :ref:`VIDIOC_ENUMAUDOUT ` do, not just an index. - -To select an audio input and change its properties applications call the -:ref:`VIDIOC_S_AUDIO ` ioctl. To select an audio -output (which presently has no changeable properties) applications call -the :ref:`VIDIOC_S_AUDOUT ` ioctl. - -Drivers must implement all audio input ioctls when the device has -multiple selectable audio inputs, all audio output ioctls when the -device has multiple selectable audio outputs. When the device has any -audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag -in the struct :c:type:`v4l2_capability` returned by -the :ref:`VIDIOC_QUERYCAP` ioctl. - - -Example: Information about the current audio input -================================================== - -.. code-block:: c - - struct v4l2_audio audio; - - memset(&audio, 0, sizeof(audio)); - - if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) { - perror("VIDIOC_G_AUDIO"); - exit(EXIT_FAILURE); - } - - printf("Current input: %s\\n", audio.name); - - -Example: Switching to the first audio input -=========================================== - -.. code-block:: c - - struct v4l2_audio audio; - - memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */ - - audio.index = 0; - - if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) { - perror("VIDIOC_S_AUDIO"); - exit(EXIT_FAILURE); - } - -.. [#f1] - Actually struct :c:type:`v4l2_audio` ought to have a - ``tuner`` field like struct :c:type:`v4l2_input`, not - only making the API more consistent but also permitting radio devices - with multiple tuners. diff --git a/Documentation/media/uapi/v4l/bayer.svg b/Documentation/media/uapi/v4l/bayer.svg deleted file mode 100644 index c5bf85103901..000000000000 --- a/Documentation/media/uapi/v4l/bayer.svg +++ /dev/null @@ -1,56 +0,0 @@ - - -image/svg+xmlB -G -G -R -BGGR -B -G -G -R -GBRG -B -G -G -R -RGGB -B -G -G -R -GRBG - diff --git a/Documentation/media/uapi/v4l/biblio.rst b/Documentation/media/uapi/v4l/biblio.rst deleted file mode 100644 index 8095f57d3d75..000000000000 --- a/Documentation/media/uapi/v4l/biblio.rst +++ /dev/null @@ -1,416 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -********** -References -********** - - -.. _cea608: - -CEA 608-E -========= - - -:title: CEA-608-E R-2014 "Line 21 Data Services" - -:author: Consumer Electronics Association (http://www.ce.org) - -.. _en300294: - -EN 300 294 -========== - - -:title: EN 300 294 "625-line television Wide Screen Signalling (WSS)" - -:author: European Telecommunication Standards Institute (http://www.etsi.org) - -.. _ets300231: - -ETS 300 231 -=========== - - -:title: ETS 300 231 "Specification of the domestic video Programme Delivery Control system (PDC)" - -:author: European Telecommunication Standards Institute (http://www.etsi.org) - -.. _ets300706: - -ETS 300 706 -=========== - - -:title: ETS 300 706 "Enhanced Teletext specification" - -:author: European Telecommunication Standards Institute (http://www.etsi.org) - -.. _mpeg2part1: - -ISO 13818-1 -=========== - - -:title: ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information technology — Generic coding of moving pictures and associated audio information: Systems" - -:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) - -.. _mpeg2part2: - -ISO 13818-2 -=========== - - -:title: ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information technology — Generic coding of moving pictures and associated audio information: Video" - -:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) - -.. _itu470: - -ITU BT.470 -========== - - -:title: ITU-R Recommendation BT.470-6 "Conventional Television Systems" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _itu601: - -ITU BT.601 -========== - - -:title: ITU-R Recommendation BT.601-5 "Studio Encoding Parameters of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect Ratios" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _itu653: - -ITU BT.653 -========== - - -:title: ITU-R Recommendation BT.653-3 "Teletext systems" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _itu709: - -ITU BT.709 -========== - - -:title: ITU-R Recommendation BT.709-5 "Parameter values for the HDTV standards for production and international programme exchange" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _itu1119: - -ITU BT.1119 -=========== - - -:title: ITU-R Recommendation BT.1119 "625-line television Wide Screen Signalling (WSS)" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _h264: - -ITU-T Rec. H.264 Specification (04/2017 Edition) -================================================ - -:title: ITU-T Recommendation H.264 "Advanced Video Coding for Generic Audiovisual Services" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _hevc: - -ITU H.265/HEVC -============== - -:title: ITU-T Rec. H.265 | ISO/IEC 23008-2 "High Efficiency Video Coding" - -:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) - -.. _jfif: - -JFIF -==== - - -:title: JPEG File Interchange Format -:subtitle: Version 1.02 - -:author: Independent JPEG Group (http://www.ijg.org) - -.. _itu-t81: - -ITU-T.81 -======== - - -:title: ITU-T Recommendation T.81 "Information Technology — Digital Compression and Coding of Continous-Tone Still Images — Requirements and Guidelines" - -:author: International Telecommunication Union (http://www.itu.int) - -.. _w3c-jpeg-jfif: - -W3C JPEG JFIF -============= - - -:title: JPEG JFIF - -:author: The World Wide Web Consortium (http://www.w3.org) - -.. _smpte12m: - -SMPTE 12M -========= - - -:title: SMPTE 12M-1999 "Television, Audio and Film - Time and Control Code" - -:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) - -.. _smpte170m: - -SMPTE 170M -========== - - -:title: SMPTE 170M-1999 "Television - Composite Analog Video Signal - NTSC for Studio Applications" - -:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) - -.. _smpte240m: - -SMPTE 240M -========== - - -:title: SMPTE 240M-1999 "Television - Signal Parameters - 1125-Line High-Definition Production" - -:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) - -.. _smpte431: - -SMPTE RP 431-2 -============== - - -:title: SMPTE RP 431-2:2011 "D-Cinema Quality - Reference Projector and Environment" - -:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) - -.. _smpte2084: - -SMPTE ST 2084 -============= - - -:title: SMPTE ST 2084:2014 "High Dynamic Range Electro-Optical Transfer Function of Master Reference Displays" - -:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) - -.. _srgb: - -sRGB -==== - - -:title: IEC 61966-2-1 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB" - -:author: International Electrotechnical Commission (http://www.iec.ch) - -.. _sycc: - -sYCC -==== - - -:title: IEC 61966-2-1-am1 ed1.0 "Amendment 1 - Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB" - -:author: International Electrotechnical Commission (http://www.iec.ch) - -.. _xvycc: - -xvYCC -===== - - -:title: IEC 61966-2-4 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-4: Colour management - Extended-gamut YCC colour space for video applications - xvYCC" - -:author: International Electrotechnical Commission (http://www.iec.ch) - -.. _oprgb: - -opRGB -===== - - -:title: IEC 61966-2-5 "Multimedia systems and equipment - Colour measurement and management - Part 2-5: Colour management - Optional RGB colour space - opRGB" - -:author: International Electrotechnical Commission (http://www.iec.ch) - -.. _itu2020: - -ITU BT.2020 -=========== - - -:title: ITU-R Recommendation BT.2020 (08/2012) "Parameter values for ultra-high definition television systems for production and international programme exchange" - -:author: International Telecommunication Union (http://www.itu.ch) - -.. _tech3213: - -EBU Tech 3213 -============= - - -:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors" - -:author: European Broadcast Union (http://www.ebu.ch) - -.. _iec62106: - -IEC 62106 -========= - - -:title: Specification of the radio data system (RDS) for VHF/FM sound broadcasting in the frequency range from 87,5 to 108,0 MHz - -:author: International Electrotechnical Commission (http://www.iec.ch) - -.. _nrsc4: - -NRSC-4-B -======== - - -:title: NRSC-4-B: United States RBDS Standard - -:author: National Radio Systems Committee (http://www.nrscstandards.org) - -.. _iso12232: - -ISO 12232:2006 -============== - - -:title: Photography — Digital still cameras — Determination of exposure index, ISO speed ratings, standard output sensitivity, and recommended exposure index - -:author: International Organization for Standardization (http://www.iso.org) - -.. _cea861: - -CEA-861-E -========= - - -:title: A DTV Profile for Uncompressed High Speed Digital Interfaces - -:author: Consumer Electronics Association (http://www.ce.org) - -.. _vesadmt: - -VESA DMT -======== - - -:title: VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT) - -:author: Video Electronics Standards Association (http://www.vesa.org) - -.. _vesaedid: - -EDID -==== - - -:title: VESA Enhanced Extended Display Identification Data Standard -:subtitle: Release A, Revision 2 - -:author: Video Electronics Standards Association (http://www.vesa.org) - -.. _hdcp: - -HDCP -==== - - -:title: High-bandwidth Digital Content Protection System -:subtitle: Revision 1.3 - -:author: Digital Content Protection LLC (http://www.digital-cp.com) - -.. _hdmi: - -HDMI -==== - - -:title: High-Definition Multimedia Interface -:subtitle: Specification Version 1.4a - -:author: HDMI Licensing LLC (http://www.hdmi.org) - -.. _hdmi2: - -HDMI2 -===== - -:title: High-Definition Multimedia Interface -:subtitle: Specification Version 2.0 - -:author: HDMI Licensing LLC (http://www.hdmi.org) - -.. _dp: - -DP -== - - -:title: VESA DisplayPort Standard -:subtitle: Version 1, Revision 2 - -:author: Video Electronics Standards Association (http://www.vesa.org) - -.. _poynton: - -poynton -======= - - -:title: Digital Video and HDTV, Algorithms and Interfaces - -:author: Charles Poynton - -.. _colimg: - -colimg -====== - - -:title: Color Imaging: Fundamentals and Applications - -:author: Erik Reinhard et al. - -.. _vp8: - -VP8 -=== - - -:title: RFC 6386: "VP8 Data Format and Decoding Guide" - -:author: J. Bankoski et al. diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst deleted file mode 100644 index 3112300c2fa0..000000000000 --- a/Documentation/media/uapi/v4l/buffer.rst +++ /dev/null @@ -1,817 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _buffer: - -******* -Buffers -******* - -A buffer contains data exchanged by application and driver using one of -the Streaming I/O methods. In the multi-planar API, the data is held in -planes, while the buffer structure acts as a container for the planes. -Only pointers to buffers (planes) are exchanged, the data itself is not -copied. These pointers, together with meta-information like timestamps -or field parity, are stored in a struct :c:type:`v4l2_buffer`, -argument to the :ref:`VIDIOC_QUERYBUF`, -:ref:`VIDIOC_QBUF ` and -:ref:`VIDIOC_DQBUF ` ioctl. In the multi-planar API, -some plane-specific members of struct :c:type:`v4l2_buffer`, -such as pointers and sizes for each plane, are stored in struct -struct :c:type:`v4l2_plane` instead. In that case, struct -struct :c:type:`v4l2_buffer` contains an array of plane structures. - -Dequeued video buffers come with timestamps. The driver decides at which -part of the frame and with which clock the timestamp is taken. Please -see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and -``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags -are always valid and constant across all buffers during the whole video -stream. Changes in these flags may take place as a side effect of -:ref:`VIDIOC_S_INPUT ` or -:ref:`VIDIOC_S_OUTPUT ` however. The -``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on -mem-to-mem devices is an exception to the rule: the timestamp source -flags are copied from the OUTPUT video buffer to the CAPTURE video -buffer. - - -Interactions between formats, controls and buffers -================================================== - -V4L2 exposes parameters that influence the buffer size, or the way data is -laid out in the buffer. Those parameters are exposed through both formats and -controls. One example of such a control is the ``V4L2_CID_ROTATE`` control -that modifies the direction in which pixels are stored in the buffer, as well -as the buffer size when the selected format includes padding at the end of -lines. - -The set of information needed to interpret the content of a buffer (e.g. the -pixel format, the line stride, the tiling orientation or the rotation) is -collectively referred to in the rest of this section as the buffer layout. - -Controls that can modify the buffer layout shall set the -``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` flag. - -Modifying formats or controls that influence the buffer size or layout require -the stream to be stopped. Any attempt at such a modification while the stream -is active shall cause the ioctl setting the format or the control to return -the ``EBUSY`` error code. In that case drivers shall also set the -``V4L2_CTRL_FLAG_GRABBED`` flag when calling -:c:func:`VIDIOC_QUERYCTRL` or :c:func:`VIDIOC_QUERY_EXT_CTRL` for such a -control while the stream is active. - -.. note:: - - The :c:func:`VIDIOC_S_SELECTION` ioctl can, depending on the hardware (for - instance if the device doesn't include a scaler), modify the format in - addition to the selection rectangle. Similarly, the - :c:func:`VIDIOC_S_INPUT`, :c:func:`VIDIOC_S_OUTPUT`, :c:func:`VIDIOC_S_STD` - and :c:func:`VIDIOC_S_DV_TIMINGS` ioctls can also modify the format and - selection rectangles. When those ioctls result in a buffer size or layout - change, drivers shall handle that condition as they would handle it in the - :c:func:`VIDIOC_S_FMT` ioctl in all cases described in this section. - -Controls that only influence the buffer layout can be modified at any time -when the stream is stopped. As they don't influence the buffer size, no -special handling is needed to synchronize those controls with buffer -allocation and the ``V4L2_CTRL_FLAG_GRABBED`` flag is cleared once the -stream is stopped. - -Formats and controls that influence the buffer size interact with buffer -allocation. The simplest way to handle this is for drivers to always require -buffers to be reallocated in order to change those formats or controls. In -that case, to perform such changes, userspace applications shall first stop -the video stream with the :c:func:`VIDIOC_STREAMOFF` ioctl if it is running -and free all buffers with the :c:func:`VIDIOC_REQBUFS` ioctl if they are -allocated. After freeing all buffers the ``V4L2_CTRL_FLAG_GRABBED`` flag -for controls is cleared. The format or controls can then be modified, and -buffers shall then be reallocated and the stream restarted. A typical ioctl -sequence is - - #. VIDIOC_STREAMOFF - #. VIDIOC_REQBUFS(0) - #. VIDIOC_S_EXT_CTRLS - #. VIDIOC_S_FMT - #. VIDIOC_REQBUFS(n) - #. VIDIOC_QBUF - #. VIDIOC_STREAMON - -The second :c:func:`VIDIOC_REQBUFS` call will take the new format and control -value into account to compute the buffer size to allocate. Applications can -also retrieve the size by calling the :c:func:`VIDIOC_G_FMT` ioctl if needed. - -.. note:: - - The API doesn't mandate the above order for control (3.) and format (4.) - changes. Format and controls can be set in a different order, or even - interleaved, depending on the device and use case. For instance some - controls might behave differently for different pixel formats, in which - case the format might need to be set first. - -When reallocation is required, any attempt to modify format or controls that -influences the buffer size while buffers are allocated shall cause the format -or control set ioctl to return the ``EBUSY`` error. Any attempt to queue a -buffer too small for the current format or controls shall cause the -:c:func:`VIDIOC_QBUF` ioctl to return a ``EINVAL`` error. - -Buffer reallocation is an expensive operation. To avoid that cost, drivers can -(and are encouraged to) allow format or controls that influence the buffer -size to be changed with buffers allocated. In that case, a typical ioctl -sequence to modify format and controls is - - #. VIDIOC_STREAMOFF - #. VIDIOC_S_EXT_CTRLS - #. VIDIOC_S_FMT - #. VIDIOC_QBUF - #. VIDIOC_STREAMON - -For this sequence to operate correctly, queued buffers need to be large enough -for the new format or controls. Drivers shall return a ``ENOSPC`` error in -response to format change (:c:func:`VIDIOC_S_FMT`) or control changes -(:c:func:`VIDIOC_S_CTRL` or :c:func:`VIDIOC_S_EXT_CTRLS`) if buffers too small -for the new format are currently queued. As a simplification, drivers are -allowed to return a ``EBUSY`` error from these ioctls if any buffer is -currently queued, without checking the queued buffers sizes. - -Additionally, drivers shall return a ``EINVAL`` error from the -:c:func:`VIDIOC_QBUF` ioctl if the buffer being queued is too small for the -current format or controls. Together, these requirements ensure that queued -buffers will always be large enough for the configured format and controls. - -Userspace applications can query the buffer size required for a given format -and controls by first setting the desired control values and then trying the -desired format. The :c:func:`VIDIOC_TRY_FMT` ioctl will return the required -buffer size. - - #. VIDIOC_S_EXT_CTRLS(x) - #. VIDIOC_TRY_FMT() - #. VIDIOC_S_EXT_CTRLS(y) - #. VIDIOC_TRY_FMT() - -The :c:func:`VIDIOC_CREATE_BUFS` ioctl can then be used to allocate buffers -based on the queried sizes (for instance by allocating a set of buffers large -enough for all the desired formats and controls, or by allocating separate set -of appropriately sized buffers for each use case). - - -.. c:type:: v4l2_buffer - -struct v4l2_buffer -================== - -.. tabularcolumns:: |p{2.8cm}|p{2.5cm}|p{1.6cm}|p{10.2cm}| - -.. cssclass:: longtable - -.. flat-table:: struct v4l2_buffer - :header-rows: 0 - :stub-columns: 0 - :widths: 1 2 10 - - * - __u32 - - ``index`` - - Number of the buffer, set by the application except when calling - :ref:`VIDIOC_DQBUF `, then it is set by the - driver. This field can range from zero to the number of buffers - allocated with the :ref:`VIDIOC_REQBUFS` ioctl - (struct :c:type:`v4l2_requestbuffers` - ``count``), plus any buffers allocated with - :ref:`VIDIOC_CREATE_BUFS` minus one. - * - __u32 - - ``type`` - - Type of the buffer, same as struct - :c:type:`v4l2_format` ``type`` or struct - :c:type:`v4l2_requestbuffers` ``type``, set - by the application. See :c:type:`v4l2_buf_type` - * - __u32 - - ``bytesused`` - - The number of bytes occupied by the data in the buffer. It depends - on the negotiated data format and may change with each buffer for - compressed variable size data like JPEG images. Drivers must set - this field when ``type`` refers to a capture stream, applications - when it refers to an output stream. If the application sets this - to 0 for an output stream, then ``bytesused`` will be set to the - size of the buffer (see the ``length`` field of this struct) by - the driver. For multiplanar formats this field is ignored and the - ``planes`` pointer is used instead. - * - __u32 - - ``flags`` - - Flags set by the application or driver, see :ref:`buffer-flags`. - * - __u32 - - ``field`` - - Indicates the field order of the image in the buffer, see - :c:type:`v4l2_field`. This field is not used when the buffer - contains VBI data. Drivers must set it when ``type`` refers to a - capture stream, applications when it refers to an output stream. - * - struct timeval - - ``timestamp`` - - For capture streams this is time when the first data byte was - captured, as returned by the :c:func:`clock_gettime()` function - for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in - :ref:`buffer-flags`. For output streams the driver stores the - time at which the last data byte was actually sent out in the - ``timestamp`` field. This permits applications to monitor the - drift between the video and system clock. For output streams that - use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill - in the timestamp which will be copied by the driver to the capture - stream. - * - struct :c:type:`v4l2_timecode` - - ``timecode`` - - When the ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this - structure contains a frame timecode. In - :c:type:`V4L2_FIELD_ALTERNATE ` mode the top and - bottom field contain the same timecode. Timecodes are intended to - help video editing and are typically recorded on video tapes, but - also embedded in compressed formats like MPEG. This field is - independent of the ``timestamp`` and ``sequence`` fields. - * - __u32 - - ``sequence`` - - Set by the driver, counting the frames (not fields!) in sequence. - This field is set for both input and output devices. - * - :cspan:`2` - - In :c:type:`V4L2_FIELD_ALTERNATE ` mode the top and - bottom field have the same sequence number. The count starts at - zero and includes dropped or repeated frames. A dropped frame was - received by an input device but could not be stored due to lack of - free buffer space. A repeated frame was displayed again by an - output device because the application did not pass new data in - time. - - .. note:: - - This may count the frames received e.g. over USB, without - taking into account the frames dropped by the remote hardware due - to limited compression throughput or bus bandwidth. These devices - identify by not enumerating any video standards, see - :ref:`standard`. - - * - __u32 - - ``memory`` - - This field must be set by applications and/or drivers in - accordance with the selected I/O method. See :c:type:`v4l2_memory` - * - union { - - ``m`` - * - __u32 - - ``offset`` - - For the single-planar API and when ``memory`` is - ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the - start of the device memory. The value is returned by the driver - and apart of serving as parameter to the - :ref:`mmap() ` function not useful for applications. - See :ref:`mmap` for details - * - unsigned long - - ``userptr`` - - For the single-planar API and when ``memory`` is - ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to - unsigned long type) in virtual memory, set by the application. See - :ref:`userp` for details. - * - struct v4l2_plane - - ``*planes`` - - When using the multi-planar API, contains a userspace pointer to - an array of struct :c:type:`v4l2_plane`. The size of - the array should be put in the ``length`` field of this - struct :c:type:`v4l2_buffer` structure. - * - int - - ``fd`` - - For the single-plane API and when ``memory`` is - ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with - a DMABUF buffer. - * - } - - - * - __u32 - - ``length`` - - Size of the buffer (not the payload) in bytes for the - single-planar API. This is set by the driver based on the calls to - :ref:`VIDIOC_REQBUFS` and/or - :ref:`VIDIOC_CREATE_BUFS`. For the - multi-planar API the application sets this to the number of - elements in the ``planes`` array. The driver will fill in the - actual number of valid elements in that array. - * - __u32 - - ``reserved2`` - - A place holder for future extensions. Drivers and applications - must set this to 0. - * - __u32 - - ``request_fd`` - - The file descriptor of the request to queue the buffer to. If the flag - ``V4L2_BUF_FLAG_REQUEST_FD`` is set, then the buffer will be - queued to this request. If the flag is not set, then this field will - be ignored. - - The ``V4L2_BUF_FLAG_REQUEST_FD`` flag and this field are only used by - :ref:`ioctl VIDIOC_QBUF ` and ignored by other ioctls that - take a :c:type:`v4l2_buffer` as argument. - - Applications should not set ``V4L2_BUF_FLAG_REQUEST_FD`` for any ioctls - other than :ref:`VIDIOC_QBUF `. - - If the device does not support requests, then ``EBADR`` will be returned. - If requests are supported but an invalid request file descriptor is - given, then ``EINVAL`` will be returned. - - - -.. c:type:: v4l2_plane - -struct v4l2_plane -================= - -.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{3.5cm}|p{7.0cm}| - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``bytesused`` - - The number of bytes occupied by data in the plane (its payload). - Drivers must set this field when ``type`` refers to a capture - stream, applications when it refers to an output stream. If the - application sets this to 0 for an output stream, then - ``bytesused`` will be set to the size of the plane (see the - ``length`` field of this struct) by the driver. - - .. note:: - - Note that the actual image data starts at ``data_offset`` - which may not be 0. - * - __u32 - - ``length`` - - Size in bytes of the plane (not its payload). This is set by the - driver based on the calls to - :ref:`VIDIOC_REQBUFS` and/or - :ref:`VIDIOC_CREATE_BUFS`. - * - union { - - ``m`` - * - __u32 - - ``mem_offset`` - - When the memory type in the containing struct - :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this - is the value that should be passed to :ref:`mmap() `, - similar to the ``offset`` field in struct - :c:type:`v4l2_buffer`. - * - unsigned long - - ``userptr`` - - When the memory type in the containing struct - :c:type:`v4l2_buffer` is ``V4L2_MEMORY_USERPTR``, - this is a userspace pointer to the memory allocated for this plane - by an application. - * - int - - ``fd`` - - When the memory type in the containing struct - :c:type:`v4l2_buffer` is ``V4L2_MEMORY_DMABUF``, - this is a file descriptor associated with a DMABUF buffer, similar - to the ``fd`` field in struct :c:type:`v4l2_buffer`. - * - } - - - * - __u32 - - ``data_offset`` - - Offset in bytes to video data in the plane. Drivers must set this - field when ``type`` refers to a capture stream, applications when - it refers to an output stream. - - .. note:: - - That data_offset is included in ``bytesused``. So the - size of the image in the plane is ``bytesused``-``data_offset`` - at offset ``data_offset`` from the start of the plane. - * - __u32 - - ``reserved[11]`` - - Reserved for future use. Should be zeroed by drivers and - applications. - - - -.. c:type:: v4l2_buf_type - -enum v4l2_buf_type -================== - -.. cssclass:: longtable - -.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{9.1cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 4 1 9 - - * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` - - 1 - - Buffer of a single-planar video capture stream, see - :ref:`capture`. - * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` - - 9 - - Buffer of a multi-planar video capture stream, see - :ref:`capture`. - * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` - - 2 - - Buffer of a single-planar video output stream, see - :ref:`output`. - * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` - - 10 - - Buffer of a multi-planar video output stream, see :ref:`output`. - * - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` - - 3 - - Buffer for video overlay, see :ref:`overlay`. - * - ``V4L2_BUF_TYPE_VBI_CAPTURE`` - - 4 - - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`. - * - ``V4L2_BUF_TYPE_VBI_OUTPUT`` - - 5 - - Buffer of a raw VBI output stream, see :ref:`raw-vbi`. - * - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` - - 6 - - Buffer of a sliced VBI capture stream, see :ref:`sliced`. - * - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` - - 7 - - Buffer of a sliced VBI output stream, see :ref:`sliced`. - * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` - - 8 - - Buffer for video output overlay (OSD), see :ref:`osd`. - * - ``V4L2_BUF_TYPE_SDR_CAPTURE`` - - 11 - - Buffer for Software Defined Radio (SDR) capture stream, see - :ref:`sdr`. - * - ``V4L2_BUF_TYPE_SDR_OUTPUT`` - - 12 - - Buffer for Software Defined Radio (SDR) output stream, see - :ref:`sdr`. - * - ``V4L2_BUF_TYPE_META_CAPTURE`` - - 13 - - Buffer for metadata capture, see :ref:`metadata`. - * - ``V4L2_BUF_TYPE_META_OUTPUT`` - - 14 - - Buffer for metadata output, see :ref:`metadata`. - - - -.. _buffer-flags: - -Buffer Flags -============ - -.. raw:: latex - - \small - -.. tabularcolumns:: |p{7.0cm}|p{2.1cm}|p{8.4cm}| - -.. cssclass:: longtable - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * .. _`V4L2-BUF-FLAG-MAPPED`: - - - ``V4L2_BUF_FLAG_MAPPED`` - - 0x00000001 - - The buffer resides in device memory and has been mapped into the - application's address space, see :ref:`mmap` for details. - Drivers set or clear this flag when the - :ref:`VIDIOC_QUERYBUF`, - :ref:`VIDIOC_QBUF` or - :ref:`VIDIOC_DQBUF ` ioctl is called. Set by the - driver. - * .. _`V4L2-BUF-FLAG-QUEUED`: - - - ``V4L2_BUF_FLAG_QUEUED`` - - 0x00000002 - - Internally drivers maintain two buffer queues, an incoming and - outgoing queue. When this flag is set, the buffer is currently on - the incoming queue. It automatically moves to the outgoing queue - after the buffer has been filled (capture devices) or displayed - (output devices). Drivers set or clear this flag when the - ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling - the ``VIDIOC_QBUF``\ ioctl it is always set and after - ``VIDIOC_DQBUF`` always cleared. - * .. _`V4L2-BUF-FLAG-DONE`: - - - ``V4L2_BUF_FLAG_DONE`` - - 0x00000004 - - When this flag is set, the buffer is currently on the outgoing - queue, ready to be dequeued from the driver. Drivers set or clear - this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After - calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always - cleared. Of course a buffer cannot be on both queues at the same - time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag - are mutually exclusive. They can be both cleared however, then the - buffer is in "dequeued" state, in the application domain so to - say. - * .. _`V4L2-BUF-FLAG-ERROR`: - - - ``V4L2_BUF_FLAG_ERROR`` - - 0x00000040 - - When this flag is set, the buffer has been dequeued successfully, - although the data might have been corrupted. This is recoverable, - streaming may continue as normal and the buffer may be reused - normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is - called. - * .. _`V4L2-BUF-FLAG-IN-REQUEST`: - - - ``V4L2_BUF_FLAG_IN_REQUEST`` - - 0x00000080 - - This buffer is part of a request that hasn't been queued yet. - * .. _`V4L2-BUF-FLAG-KEYFRAME`: - - - ``V4L2_BUF_FLAG_KEYFRAME`` - - 0x00000008 - - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF`` - ioctl. It may be set by video capture devices when the buffer - contains a compressed image which is a key frame (or field), i. e. - can be decompressed on its own. Also known as an I-frame. - Applications can set this bit when ``type`` refers to an output - stream. - * .. _`V4L2-BUF-FLAG-PFRAME`: - - - ``V4L2_BUF_FLAG_PFRAME`` - - 0x00000010 - - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames - or fields which contain only differences to a previous key frame. - Applications can set this bit when ``type`` refers to an output - stream. - * .. _`V4L2-BUF-FLAG-BFRAME`: - - - ``V4L2_BUF_FLAG_BFRAME`` - - 0x00000020 - - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional - predicted frame or field which contains only the differences - between the current frame and both the preceding and following key - frames to specify its content. Applications can set this bit when - ``type`` refers to an output stream. - * .. _`V4L2-BUF-FLAG-TIMECODE`: - - - ``V4L2_BUF_FLAG_TIMECODE`` - - 0x00000100 - - The ``timecode`` field is valid. Drivers set or clear this flag - when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set - this bit and the corresponding ``timecode`` structure when - ``type`` refers to an output stream. - * .. _`V4L2-BUF-FLAG-PREPARED`: - - - ``V4L2_BUF_FLAG_PREPARED`` - - 0x00000400 - - The buffer has been prepared for I/O and can be queued by the - application. Drivers set or clear this flag when the - :ref:`VIDIOC_QUERYBUF`, - :ref:`VIDIOC_PREPARE_BUF `, - :ref:`VIDIOC_QBUF` or - :ref:`VIDIOC_DQBUF ` ioctl is called. - * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`: - - - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` - - 0x00000800 - - Caches do not have to be invalidated for this buffer. Typically - applications shall use this flag if the data captured in the - buffer is not going to be touched by the CPU, instead the buffer - will, probably, be passed on to a DMA-capable hardware unit for - further processing or output. - * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`: - - - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` - - 0x00001000 - - Caches do not have to be cleaned for this buffer. Typically - applications shall use this flag for output buffers if the data in - this buffer has not been created by the CPU but by some - DMA-capable unit, in which case caches have not been used. - * .. _`V4L2-BUF-FLAG-M2M-HOLD-CAPTURE-BUF`: - - - ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` - - 0x00000200 - - Only valid if ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is - set. It is typically used with stateless decoders where multiple - output buffers each decode to a slice of the decoded frame. - Applications can set this flag when queueing the output buffer - to prevent the driver from dequeueing the capture buffer after - the output buffer has been decoded (i.e. the capture buffer is - 'held'). If the timestamp of this output buffer differs from that - of the previous output buffer, then that indicates the start of a - new frame and the previously held capture buffer is dequeued. - * .. _`V4L2-BUF-FLAG-LAST`: - - - ``V4L2_BUF_FLAG_LAST`` - - 0x00100000 - - Last buffer produced by the hardware. mem2mem codec drivers set - this flag on the capture queue for the last buffer when the - :ref:`VIDIOC_QUERYBUF` or - :ref:`VIDIOC_DQBUF ` ioctl is called. Due to - hardware limitations, the last buffer may be empty. In this case - the driver will set the ``bytesused`` field to 0, regardless of - the format. Any Any subsequent call to the - :ref:`VIDIOC_DQBUF ` ioctl will not block anymore, - but return an ``EPIPE`` error code. - * .. _`V4L2-BUF-FLAG-REQUEST-FD`: - - - ``V4L2_BUF_FLAG_REQUEST_FD`` - - 0x00800000 - - The ``request_fd`` field contains a valid file descriptor. - * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`: - - - ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` - - 0x0000e000 - - Mask for timestamp types below. To test the timestamp type, mask - out bits not belonging to timestamp type by performing a logical - and operation with buffer flags and timestamp mask. - * .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`: - - - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN`` - - 0x00000000 - - Unknown timestamp type. This type is used by drivers before Linux - 3.9 and may be either monotonic (see below) or realtime (wall - clock). Monotonic clock has been favoured in embedded systems - whereas most of the drivers use the realtime clock. Either kinds - of timestamps are available in user space via - :c:func:`clock_gettime` using clock IDs ``CLOCK_MONOTONIC`` - and ``CLOCK_REALTIME``, respectively. - * .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`: - - - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC`` - - 0x00002000 - - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC`` - clock. To access the same clock outside V4L2, use - :c:func:`clock_gettime`. - * .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`: - - - ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` - - 0x00004000 - - The CAPTURE buffer timestamp has been taken from the corresponding - OUTPUT buffer. This flag applies only to mem2mem devices. - * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`: - - - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` - - 0x00070000 - - Mask for timestamp sources below. The timestamp source defines the - point of time the timestamp is taken in relation to the frame. - Logical 'and' operation between the ``flags`` field and - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the - timestamp source. Applications must set the timestamp source when - ``type`` refers to an output stream and - ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set. - * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`: - - - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF`` - - 0x00000000 - - End Of Frame. The buffer timestamp has been taken when the last - pixel of the frame has been received or the last pixel of the - frame has been transmitted. In practice, software generated - timestamps will typically be read from the clock a small amount of - time after the last pixel has been received or transmitten, - depending on the system and other activity in it. - * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`: - - - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE`` - - 0x00010000 - - Start Of Exposure. The buffer timestamp has been taken when the - exposure of the frame has begun. This is only valid for the - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type. - -.. raw:: latex - - \normalsize - - -.. c:type:: v4l2_memory - -enum v4l2_memory -================ - -.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.7cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``V4L2_MEMORY_MMAP`` - - 1 - - The buffer is used for :ref:`memory mapping ` I/O. - * - ``V4L2_MEMORY_USERPTR`` - - 2 - - The buffer is used for :ref:`user pointer ` I/O. - * - ``V4L2_MEMORY_OVERLAY`` - - 3 - - [to do] - * - ``V4L2_MEMORY_DMABUF`` - - 4 - - The buffer is used for :ref:`DMA shared buffer ` I/O. - - - -Timecodes -========= - -The :c:type:`v4l2_buffer_timecode` structure is designed to hold a -:ref:`smpte12m` or similar timecode. -(struct :c:type:`timeval` timestamps are stored in the struct -:c:type:`v4l2_buffer` ``timestamp`` field.) - - -.. c:type:: v4l2_timecode - -struct v4l2_timecode --------------------- - -.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{12.3cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 1 1 2 - - * - __u32 - - ``type`` - - Frame rate the timecodes are based on, see :ref:`timecode-type`. - * - __u32 - - ``flags`` - - Timecode flags, see :ref:`timecode-flags`. - * - __u8 - - ``frames`` - - Frame count, 0 ... 23/24/29/49/59, depending on the type of - timecode. - * - __u8 - - ``seconds`` - - Seconds count, 0 ... 59. This is a binary, not BCD number. - * - __u8 - - ``minutes`` - - Minutes count, 0 ... 59. This is a binary, not BCD number. - * - __u8 - - ``hours`` - - Hours count, 0 ... 29. This is a binary, not BCD number. - * - __u8 - - ``userbits``\ [4] - - The "user group" bits from the timecode. - - - -.. _timecode-type: - -Timecode Types --------------- - -.. tabularcolumns:: |p{5.6cm}|p{0.8cm}|p{11.1cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``V4L2_TC_TYPE_24FPS`` - - 1 - - 24 frames per second, i. e. film. - * - ``V4L2_TC_TYPE_25FPS`` - - 2 - - 25 frames per second, i. e. PAL or SECAM video. - * - ``V4L2_TC_TYPE_30FPS`` - - 3 - - 30 frames per second, i. e. NTSC video. - * - ``V4L2_TC_TYPE_50FPS`` - - 4 - - - * - ``V4L2_TC_TYPE_60FPS`` - - 5 - - - - - -.. _timecode-flags: - -Timecode Flags --------------- - -.. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.5cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 3 1 4 - - * - ``V4L2_TC_FLAG_DROPFRAME`` - - 0x0001 - - Indicates "drop frame" semantics for counting frames in 29.97 fps - material. When set, frame numbers 0 and 1 at the start of each - minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the - count. - * - ``V4L2_TC_FLAG_COLORFRAME`` - - 0x0002 - - The "color frame" flag. - * - ``V4L2_TC_USERBITS_field`` - - 0x000C - - Field mask for the "binary group flags". - * - ``V4L2_TC_USERBITS_USERDEFINED`` - - 0x0000 - - Unspecified format. - * - ``V4L2_TC_USERBITS_8BITCHARS`` - - 0x0008 - - 8-bit ISO characters. diff --git a/Documentation/media/uapi/v4l/capture-example.rst b/Documentation/media/uapi/v4l/capture-example.rst deleted file mode 100644 index 130ca47ef796..000000000000 --- a/Documentation/media/uapi/v4l/capture-example.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _capture-example: - -********************* -Video Capture Example -********************* - - -.. toctree:: - :maxdepth: 1 - - capture.c diff --git a/Documentation/media/uapi/v4l/capture.c.rst b/Documentation/media/uapi/v4l/capture.c.rst deleted file mode 100644 index b4652c2351f2..000000000000 --- a/Documentation/media/uapi/v4l/capture.c.rst +++ /dev/null @@ -1,671 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -file: media/v4l/capture.c -========================= - -.. code-block:: c - - /* - * V4L2 video capture example - * - * This program can be used and distributed without restrictions. - * - * This program is provided with the V4L2 API - * see https://linuxtv.org/docs.php for more information - */ - - #include - #include - #include - #include - - #include /* getopt_long() */ - - #include /* low-level i/o */ - #include - #include - #include - #include - #include - #include - #include - - #include - - #define CLEAR(x) memset(&(x), 0, sizeof(x)) - - enum io_method { - IO_METHOD_READ, - IO_METHOD_MMAP, - IO_METHOD_USERPTR, - }; - - struct buffer { - void *start; - size_t length; - }; - - static char *dev_name; - static enum io_method io = IO_METHOD_MMAP; - static int fd = -1; - struct buffer *buffers; - static unsigned int n_buffers; - static int out_buf; - static int force_format; - static int frame_count = 70; - - static void errno_exit(const char *s) - { - fprintf(stderr, "%s error %d, %s\\n", s, errno, strerror(errno)); - exit(EXIT_FAILURE); - } - - static int xioctl(int fh, int request, void *arg) - { - int r; - - do { - r = ioctl(fh, request, arg); - } while (-1 == r && EINTR == errno); - - return r; - } - - static void process_image(const void *p, int size) - { - if (out_buf) - fwrite(p, size, 1, stdout); - - fflush(stderr); - fprintf(stderr, "."); - fflush(stdout); - } - - static int read_frame(void) - { - struct v4l2_buffer buf; - unsigned int i; - - switch (io) { - case IO_METHOD_READ: - if (-1 == read(fd, buffers[0].start, buffers[0].length)) { - switch (errno) { - case EAGAIN: - return 0; - - case EIO: - /* Could ignore EIO, see spec. */ - - /* fall through */ - - default: - errno_exit("read"); - } - } - - process_image(buffers[0].start, buffers[0].length); - break; - - case IO_METHOD_MMAP: - CLEAR(buf); - - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_MMAP; - - if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) { - switch (errno) { - case EAGAIN: - return 0; - - case EIO: - /* Could ignore EIO, see spec. */ - - /* fall through */ - - default: - errno_exit("VIDIOC_DQBUF"); - } - } - - assert(buf.index < n_buffers); - - process_image(buffers[buf.index].start, buf.bytesused); - - if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) - errno_exit("VIDIOC_QBUF"); - break; - - case IO_METHOD_USERPTR: - CLEAR(buf); - - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_USERPTR; - - if (-1 == xioctl(fd, VIDIOC_DQBUF, &buf)) { - switch (errno) { - case EAGAIN: - return 0; - - case EIO: - /* Could ignore EIO, see spec. */ - - /* fall through */ - - default: - errno_exit("VIDIOC_DQBUF"); - } - } - - for (i = 0; i < n_buffers; ++i) - if (buf.m.userptr == (unsigned long)buffers[i].start - && buf.length == buffers[i].length) - break; - - assert(i < n_buffers); - - process_image((void *)buf.m.userptr, buf.bytesused); - - if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) - errno_exit("VIDIOC_QBUF"); - break; - } - - return 1; - } - - static void mainloop(void) - { - unsigned int count; - - count = frame_count; - - while (count-- > 0) { - for (;;) { - fd_set fds; - struct timeval tv; - int r; - - FD_ZERO(&fds); - FD_SET(fd, &fds); - - /* Timeout. */ - tv.tv_sec = 2; - tv.tv_usec = 0; - - r = select(fd + 1, &fds, NULL, NULL, &tv); - - if (-1 == r) { - if (EINTR == errno) - continue; - errno_exit("select"); - } - - if (0 == r) { - fprintf(stderr, "select timeout\\n"); - exit(EXIT_FAILURE); - } - - if (read_frame()) - break; - /* EAGAIN - continue select loop. */ - } - } - } - - static void stop_capturing(void) - { - enum v4l2_buf_type type; - - switch (io) { - case IO_METHOD_READ: - /* Nothing to do. */ - break; - - case IO_METHOD_MMAP: - case IO_METHOD_USERPTR: - type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (-1 == xioctl(fd, VIDIOC_STREAMOFF, &type)) - errno_exit("VIDIOC_STREAMOFF"); - break; - } - } - - static void start_capturing(void) - { - unsigned int i; - enum v4l2_buf_type type; - - switch (io) { - case IO_METHOD_READ: - /* Nothing to do. */ - break; - - case IO_METHOD_MMAP: - for (i = 0; i < n_buffers; ++i) { - struct v4l2_buffer buf; - - CLEAR(buf); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_MMAP; - buf.index = i; - - if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) - errno_exit("VIDIOC_QBUF"); - } - type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (-1 == xioctl(fd, VIDIOC_STREAMON, &type)) - errno_exit("VIDIOC_STREAMON"); - break; - - case IO_METHOD_USERPTR: - for (i = 0; i < n_buffers; ++i) { - struct v4l2_buffer buf; - - CLEAR(buf); - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_USERPTR; - buf.index = i; - buf.m.userptr = (unsigned long)buffers[i].start; - buf.length = buffers[i].length; - - if (-1 == xioctl(fd, VIDIOC_QBUF, &buf)) - errno_exit("VIDIOC_QBUF"); - } - type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (-1 == xioctl(fd, VIDIOC_STREAMON, &type)) - errno_exit("VIDIOC_STREAMON"); - break; - } - } - - static void uninit_device(void) - { - unsigned int i; - - switch (io) { - case IO_METHOD_READ: - free(buffers[0].start); - break; - - case IO_METHOD_MMAP: - for (i = 0; i < n_buffers; ++i) - if (-1 == munmap(buffers[i].start, buffers[i].length)) - errno_exit("munmap"); - break; - - case IO_METHOD_USERPTR: - for (i = 0; i < n_buffers; ++i) - free(buffers[i].start); - break; - } - - free(buffers); - } - - static void init_read(unsigned int buffer_size) - { - buffers = calloc(1, sizeof(*buffers)); - - if (!buffers) { - fprintf(stderr, "Out of memory\\n"); - exit(EXIT_FAILURE); - } - - buffers[0].length = buffer_size; - buffers[0].start = malloc(buffer_size); - - if (!buffers[0].start) { - fprintf(stderr, "Out of memory\\n"); - exit(EXIT_FAILURE); - } - } - - static void init_mmap(void) - { - struct v4l2_requestbuffers req; - - CLEAR(req); - - req.count = 4; - req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - req.memory = V4L2_MEMORY_MMAP; - - if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { - if (EINVAL == errno) { - fprintf(stderr, "%s does not support " - "memory mappingn", dev_name); - exit(EXIT_FAILURE); - } else { - errno_exit("VIDIOC_REQBUFS"); - } - } - - if (req.count < 2) { - fprintf(stderr, "Insufficient buffer memory on %s\\n", - dev_name); - exit(EXIT_FAILURE); - } - - buffers = calloc(req.count, sizeof(*buffers)); - - if (!buffers) { - fprintf(stderr, "Out of memory\\n"); - exit(EXIT_FAILURE); - } - - for (n_buffers = 0; n_buffers < req.count; ++n_buffers) { - struct v4l2_buffer buf; - - CLEAR(buf); - - buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - buf.memory = V4L2_MEMORY_MMAP; - buf.index = n_buffers; - - if (-1 == xioctl(fd, VIDIOC_QUERYBUF, &buf)) - errno_exit("VIDIOC_QUERYBUF"); - - buffers[n_buffers].length = buf.length; - buffers[n_buffers].start = - mmap(NULL /* start anywhere */, - buf.length, - PROT_READ | PROT_WRITE /* required */, - MAP_SHARED /* recommended */, - fd, buf.m.offset); - - if (MAP_FAILED == buffers[n_buffers].start) - errno_exit("mmap"); - } - } - - static void init_userp(unsigned int buffer_size) - { - struct v4l2_requestbuffers req; - - CLEAR(req); - - req.count = 4; - req.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - req.memory = V4L2_MEMORY_USERPTR; - - if (-1 == xioctl(fd, VIDIOC_REQBUFS, &req)) { - if (EINVAL == errno) { - fprintf(stderr, "%s does not support " - "user pointer i/on", dev_name); - exit(EXIT_FAILURE); - } else { - errno_exit("VIDIOC_REQBUFS"); - } - } - - buffers = calloc(4, sizeof(*buffers)); - - if (!buffers) { - fprintf(stderr, "Out of memory\\n"); - exit(EXIT_FAILURE); - } - - for (n_buffers = 0; n_buffers < 4; ++n_buffers) { - buffers[n_buffers].length = buffer_size; - buffers[n_buffers].start = malloc(buffer_size); - - if (!buffers[n_buffers].start) { - fprintf(stderr, "Out of memory\\n"); - exit(EXIT_FAILURE); - } - } - } - - static void init_device(void) - { - struct v4l2_capability cap; - struct v4l2_cropcap cropcap; - struct v4l2_crop crop; - struct v4l2_format fmt; - unsigned int min; - - if (-1 == xioctl(fd, VIDIOC_QUERYCAP, &cap)) { - if (EINVAL == errno) { - fprintf(stderr, "%s is no V4L2 device\\n", - dev_name); - exit(EXIT_FAILURE); - } else { - errno_exit("VIDIOC_QUERYCAP"); - } - } - - if (!(cap.capabilities & V4L2_CAP_VIDEO_CAPTURE)) { - fprintf(stderr, "%s is no video capture device\\n", - dev_name); - exit(EXIT_FAILURE); - } - - switch (io) { - case IO_METHOD_READ: - if (!(cap.capabilities & V4L2_CAP_READWRITE)) { - fprintf(stderr, "%s does not support read i/o\\n", - dev_name); - exit(EXIT_FAILURE); - } - break; - - case IO_METHOD_MMAP: - case IO_METHOD_USERPTR: - if (!(cap.capabilities & V4L2_CAP_STREAMING)) { - fprintf(stderr, "%s does not support streaming i/o\\n", - dev_name); - exit(EXIT_FAILURE); - } - break; - } - - - /* Select video input, video standard and tune here. */ - - - CLEAR(cropcap); - - cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (0 == xioctl(fd, VIDIOC_CROPCAP, &cropcap)) { - crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - crop.c = cropcap.defrect; /* reset to default */ - - if (-1 == xioctl(fd, VIDIOC_S_CROP, &crop)) { - switch (errno) { - case EINVAL: - /* Cropping not supported. */ - break; - default: - /* Errors ignored. */ - break; - } - } - } else { - /* Errors ignored. */ - } - - - CLEAR(fmt); - - fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - if (force_format) { - fmt.fmt.pix.width = 640; - fmt.fmt.pix.height = 480; - fmt.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; - fmt.fmt.pix.field = V4L2_FIELD_INTERLACED; - - if (-1 == xioctl(fd, VIDIOC_S_FMT, &fmt)) - errno_exit("VIDIOC_S_FMT"); - - /* Note VIDIOC_S_FMT may change width and height. */ - } else { - /* Preserve original settings as set by v4l2-ctl for example */ - if (-1 == xioctl(fd, VIDIOC_G_FMT, &fmt)) - errno_exit("VIDIOC_G_FMT"); - } - - /* Buggy driver paranoia. */ - min = fmt.fmt.pix.width * 2; - if (fmt.fmt.pix.bytesperline < min) - fmt.fmt.pix.bytesperline = min; - min = fmt.fmt.pix.bytesperline * fmt.fmt.pix.height; - if (fmt.fmt.pix.sizeimage < min) - fmt.fmt.pix.sizeimage = min; - - switch (io) { - case IO_METHOD_READ: - init_read(fmt.fmt.pix.sizeimage); - break; - - case IO_METHOD_MMAP: - init_mmap(); - break; - - case IO_METHOD_USERPTR: - init_userp(fmt.fmt.pix.sizeimage); - break; - } - } - - static void close_device(void) - { - if (-1 == close(fd)) - errno_exit("close"); - - fd = -1; - } - - static void open_device(void) - { - struct stat st; - - if (-1 == stat(dev_name, &st)) { - fprintf(stderr, "Cannot identify '%s': %d, %s\\n", - dev_name, errno, strerror(errno)); - exit(EXIT_FAILURE); - } - - if (!S_ISCHR(st.st_mode)) { - fprintf(stderr, "%s is no devicen", dev_name); - exit(EXIT_FAILURE); - } - - fd = open(dev_name, O_RDWR /* required */ | O_NONBLOCK, 0); - - if (-1 == fd) { - fprintf(stderr, "Cannot open '%s': %d, %s\\n", - dev_name, errno, strerror(errno)); - exit(EXIT_FAILURE); - } - } - - static void usage(FILE *fp, int argc, char **argv) - { - fprintf(fp, - "Usage: %s [options]\\n\\n" - "Version 1.3\\n" - "Options:\\n" - "-d | --device name Video device name [%s]n" - "-h | --help Print this messagen" - "-m | --mmap Use memory mapped buffers [default]n" - "-r | --read Use read() callsn" - "-u | --userp Use application allocated buffersn" - "-o | --output Outputs stream to stdoutn" - "-f | --format Force format to 640x480 YUYVn" - "-c | --count Number of frames to grab [%i]n" - "", - argv[0], dev_name, frame_count); - } - - static const char short_options[] = "d:hmruofc:"; - - static const struct option - long_options[] = { - { "device", required_argument, NULL, 'd' }, - { "help", no_argument, NULL, 'h' }, - { "mmap", no_argument, NULL, 'm' }, - { "read", no_argument, NULL, 'r' }, - { "userp", no_argument, NULL, 'u' }, - { "output", no_argument, NULL, 'o' }, - { "format", no_argument, NULL, 'f' }, - { "count", required_argument, NULL, 'c' }, - { 0, 0, 0, 0 } - }; - - int main(int argc, char **argv) - { - dev_name = "/dev/video0"; - - for (;;) { - int idx; - int c; - - c = getopt_long(argc, argv, - short_options, long_options, &idx); - - if (-1 == c) - break; - - switch (c) { - case 0: /* getopt_long() flag */ - break; - - case 'd': - dev_name = optarg; - break; - - case 'h': - usage(stdout, argc, argv); - exit(EXIT_SUCCESS); - - case 'm': - io = IO_METHOD_MMAP; - break; - - case 'r': - io = IO_METHOD_READ; - break; - - case 'u': - io = IO_METHOD_USERPTR; - break; - - case 'o': - out_buf++; - break; - - case 'f': - force_format++; - break; - - case 'c': - errno = 0; - frame_count = strtol(optarg, NULL, 0); - if (errno) - errno_exit(optarg); - break; - - default: - usage(stderr, argc, argv); - exit(EXIT_FAILURE); - } - } - - open_device(); - init_device(); - start_capturing(); - mainloop(); - stop_capturing(); - uninit_device(); - close_device(); - fprintf(stderr, "\\n"); - return 0; - } diff --git a/Documentation/media/uapi/v4l/colorspaces-defs.rst b/Documentation/media/uapi/v4l/colorspaces-defs.rst deleted file mode 100644 index e122bbe3d799..000000000000 --- a/Documentation/media/uapi/v4l/colorspaces-defs.rst +++ /dev/null @@ -1,183 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -**************************** -Defining Colorspaces in V4L2 -**************************** - -In V4L2 colorspaces are defined by four values. The first is the -colorspace identifier (enum :c:type:`v4l2_colorspace`) -which defines the chromaticities, the default transfer function, the -default Y'CbCr encoding and the default quantization method. The second -is the transfer function identifier (enum -:c:type:`v4l2_xfer_func`) to specify non-standard -transfer functions. The third is the Y'CbCr encoding identifier (enum -:c:type:`v4l2_ycbcr_encoding`) to specify -non-standard Y'CbCr encodings and the fourth is the quantization -identifier (enum :c:type:`v4l2_quantization`) to -specify non-standard quantization methods. Most of the time only the -colorspace field of struct :c:type:`v4l2_pix_format` -or struct :c:type:`v4l2_pix_format_mplane` -needs to be filled in. - -.. _hsv-colorspace: - -On :ref:`HSV formats ` the *Hue* is defined as the angle on -the cylindrical color representation. Usually this angle is measured in -degrees, i.e. 0-360. When we map this angle value into 8 bits, there are -two basic ways to do it: Divide the angular value by 2 (0-179), or use the -whole range, 0-255, dividing the angular value by 1.41. The enum -:c:type:`v4l2_hsv_encoding` specifies which encoding is used. - -.. note:: The default R'G'B' quantization is full range for all - colorspaces except for BT.2020 which uses limited range R'G'B' - quantization. - -.. tabularcolumns:: |p{6.7cm}|p{10.8cm}| - -.. c:type:: v4l2_colorspace - -.. flat-table:: V4L2 Colorspaces - :header-rows: 1 - :stub-columns: 0 - - * - Identifier - - Details - * - ``V4L2_COLORSPACE_DEFAULT`` - - The default colorspace. This can be used by applications to let - the driver fill in the colorspace. - * - ``V4L2_COLORSPACE_SMPTE170M`` - - See :ref:`col-smpte-170m`. - * - ``V4L2_COLORSPACE_REC709`` - - See :ref:`col-rec709`. - * - ``V4L2_COLORSPACE_SRGB`` - - See :ref:`col-srgb`. - * - ``V4L2_COLORSPACE_OPRGB`` - - See :ref:`col-oprgb`. - * - ``V4L2_COLORSPACE_BT2020`` - - See :ref:`col-bt2020`. - * - ``V4L2_COLORSPACE_DCI_P3`` - - See :ref:`col-dcip3`. - * - ``V4L2_COLORSPACE_SMPTE240M`` - - See :ref:`col-smpte-240m`. - * - ``V4L2_COLORSPACE_470_SYSTEM_M`` - - See :ref:`col-sysm`. - * - ``V4L2_COLORSPACE_470_SYSTEM_BG`` - - See :ref:`col-sysbg`. - * - ``V4L2_COLORSPACE_JPEG`` - - See :ref:`col-jpeg`. - * - ``V4L2_COLORSPACE_RAW`` - - The raw colorspace. This is used for raw image capture where the - image is minimally processed and is using the internal colorspace - of the device. The software that processes an image using this - 'colorspace' will have to know the internals of the capture - device. - - - -.. c:type:: v4l2_xfer_func - -.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| - -.. flat-table:: V4L2 Transfer Function - :header-rows: 1 - :stub-columns: 0 - - * - Identifier - - Details - * - ``V4L2_XFER_FUNC_DEFAULT`` - - Use the default transfer function as defined by the colorspace. - * - ``V4L2_XFER_FUNC_709`` - - Use the Rec. 709 transfer function. - * - ``V4L2_XFER_FUNC_SRGB`` - - Use the sRGB transfer function. - * - ``V4L2_XFER_FUNC_OPRGB`` - - Use the opRGB transfer function. - * - ``V4L2_XFER_FUNC_SMPTE240M`` - - Use the SMPTE 240M transfer function. - * - ``V4L2_XFER_FUNC_NONE`` - - Do not use a transfer function (i.e. use linear RGB values). - * - ``V4L2_XFER_FUNC_DCI_P3`` - - Use the DCI-P3 transfer function. - * - ``V4L2_XFER_FUNC_SMPTE2084`` - - Use the SMPTE 2084 transfer function. See :ref:`xf-smpte-2084`. - - - -.. c:type:: v4l2_ycbcr_encoding - -.. tabularcolumns:: |p{7.2cm}|p{10.3cm}| - -.. flat-table:: V4L2 Y'CbCr Encodings - :header-rows: 1 - :stub-columns: 0 - - * - Identifier - - Details - * - ``V4L2_YCBCR_ENC_DEFAULT`` - - Use the default Y'CbCr encoding as defined by the colorspace. - * - ``V4L2_YCBCR_ENC_601`` - - Use the BT.601 Y'CbCr encoding. - * - ``V4L2_YCBCR_ENC_709`` - - Use the Rec. 709 Y'CbCr encoding. - * - ``V4L2_YCBCR_ENC_XV601`` - - Use the extended gamut xvYCC BT.601 encoding. - * - ``V4L2_YCBCR_ENC_XV709`` - - Use the extended gamut xvYCC Rec. 709 encoding. - * - ``V4L2_YCBCR_ENC_BT2020`` - - Use the default non-constant luminance BT.2020 Y'CbCr encoding. - * - ``V4L2_YCBCR_ENC_BT2020_CONST_LUM`` - - Use the constant luminance BT.2020 Yc'CbcCrc encoding. - * - ``V4L2_YCBCR_ENC_SMPTE_240M`` - - Use the SMPTE 240M Y'CbCr encoding. - - - -.. c:type:: v4l2_hsv_encoding - -.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| - -.. flat-table:: V4L2 HSV Encodings - :header-rows: 1 - :stub-columns: 0 - - * - Identifier - - Details - * - ``V4L2_HSV_ENC_180`` - - For the Hue, each LSB is two degrees. - * - ``V4L2_HSV_ENC_256`` - - For the Hue, the 360 degrees are mapped into 8 bits, i.e. each - LSB is roughly 1.41 degrees. - - - -.. c:type:: v4l2_quantization - -.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| - -.. flat-table:: V4L2 Quantization Methods - :header-rows: 1 - :stub-columns: 0 - - * - Identifier - - Details - * - ``V4L2_QUANTIZATION_DEFAULT`` - - Use the default quantization encoding as defined by the - colorspace. This is always full range for R'G'B' (except for the - BT.2020 colorspace) and HSV. It is usually limited range for Y'CbCr. - * - ``V4L2_QUANTIZATION_FULL_RANGE`` - - Use the full range quantization encoding. I.e. the range [0…1] is - mapped to [0…255] (with possible clipping to [1…254] to avoid the - 0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to - [0…255] (with possible clipping to [1…254] to avoid the 0x00 and - 0xff values). - * - ``V4L2_QUANTIZATION_LIM_RANGE`` - - Use the limited range quantization encoding. I.e. the range [0…1] - is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to - [16…240]. diff --git a/Documentation/media/uapi/v4l/colorspaces-details.rst b/Documentation/media/uapi/v4l/colorspaces-details.rst deleted file mode 100644 index 8b0ba3668101..000000000000 --- a/Documentation/media/uapi/v4l/colorspaces-details.rst +++ /dev/null @@ -1,813 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -******************************** -Detailed Colorspace Descriptions -******************************** - - -.. _col-smpte-170m: - -Colorspace SMPTE 170M (V4L2_COLORSPACE_SMPTE170M) -================================================= - -The :ref:`smpte170m` standard defines the colorspace used by NTSC and -PAL and by SDTV in general. The default transfer function is -``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited -range. The chromaticities of the primary colors and the white reference -are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: SMPTE 170M Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.630 - - 0.340 - * - Green - - 0.310 - - 0.595 - * - Blue - - 0.155 - - 0.070 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - -The red, green and blue chromaticities are also often referred to as the -SMPTE C set, so this colorspace is sometimes called SMPTE C as well. - -The transfer function defined for SMPTE 170M is the same as the one -defined in Rec. 709. - -.. math:: - - L' = -1.099(-L)^{0.45} + 0.099 \text{, for } L \le-0.018 - - L' = 4.5L \text{, for } -0.018 < L < 0.018 - - L' = 1.099L^{0.45} - 0.099 \text{, for } L \ge 0.018 - -Inverse Transfer function: - -.. math:: - - L = -\left( \frac{L' - 0.099}{-1.099} \right) ^{\frac{1}{0.45}} \text{, for } L' \le -0.081 - - L = \frac{L'}{4.5} \text{, for } -0.081 < L' < 0.081 - - L = \left(\frac{L' + 0.099}{1.099}\right)^{\frac{1}{0.45} } \text{, for } L' \ge 0.081 - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_601`` encoding: - -.. math:: - - Y' = 0.2990R' + 0.5870G' + 0.1140B' - - Cb = -0.1687R' - 0.3313G' + 0.5B' - - Cr = 0.5R' - 0.4187G' - 0.0813B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. This conversion to Y'CbCr is identical to the one defined in -the :ref:`itu601` standard and this colorspace is sometimes called -BT.601 as well, even though BT.601 does not mention any color primaries. - -The default quantization is limited range, but full range is possible -although rarely seen. - - -.. _col-rec709: - -Colorspace Rec. 709 (V4L2_COLORSPACE_REC709) -============================================ - -The :ref:`itu709` standard defines the colorspace used by HDTV in -general. The default transfer function is ``V4L2_XFER_FUNC_709``. The -default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. The default Y'CbCr -quantization is limited range. The chromaticities of the primary colors -and the white reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: Rec. 709 Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.640 - - 0.330 - * - Green - - 0.300 - - 0.600 - * - Blue - - 0.150 - - 0.060 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - -The full name of this standard is Rec. ITU-R BT.709-5. - -Transfer function. Normally L is in the range [0…1], but for the -extended gamut xvYCC encoding values outside that range are allowed. - -.. math:: - - L' = -1.099(-L)^{0.45} + 0.099 \text{, for } L \le -0.018 - - L' = 4.5L \text{, for } -0.018 < L < 0.018 - - L' = 1.099L^{0.45} - 0.099 \text{, for } L \ge 0.018 - -Inverse Transfer function: - -.. math:: - - L = -\left( \frac{L' - 0.099}{-1.099} \right)^\frac{1}{0.45} \text{, for } L' \le -0.081 - - L = \frac{L'}{4.5}\text{, for } -0.081 < L' < 0.081 - - L = \left(\frac{L' + 0.099}{1.099}\right)^{\frac{1}{0.45} } \text{, for } L' \ge 0.081 - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_709`` encoding: - -.. math:: - - Y' = 0.2126R' + 0.7152G' + 0.0722B' - - Cb = -0.1146R' - 0.3854G' + 0.5B' - - Cr = 0.5R' - 0.4542G' - 0.0458B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. - -The default quantization is limited range, but full range is possible -although rarely seen. - -The ``V4L2_YCBCR_ENC_709`` encoding described above is the default for -this colorspace, but it can be overridden with ``V4L2_YCBCR_ENC_601``, -in which case the BT.601 Y'CbCr encoding is used. - -Two additional extended gamut Y'CbCr encodings are also possible with -this colorspace: - -The xvYCC 709 encoding (``V4L2_YCBCR_ENC_XV709``, :ref:`xvycc`) is -similar to the Rec. 709 encoding, but it allows for R', G' and B' values -that are outside the range [0…1]. The resulting Y', Cb and Cr values are -scaled and offset according to the limited range formula: - -.. math:: - - Y' = \frac{219}{256} * (0.2126R' + 0.7152G' + 0.0722B') + \frac{16}{256} - - Cb = \frac{224}{256} * (-0.1146R' - 0.3854G' + 0.5B') - - Cr = \frac{224}{256} * (0.5R' - 0.4542G' - 0.0458B') - -The xvYCC 601 encoding (``V4L2_YCBCR_ENC_XV601``, :ref:`xvycc`) is -similar to the BT.601 encoding, but it allows for R', G' and B' values -that are outside the range [0…1]. The resulting Y', Cb and Cr values are -scaled and offset according to the limited range formula: - -.. math:: - - Y' = \frac{219}{256} * (0.2990R' + 0.5870G' + 0.1140B') + \frac{16}{256} - - Cb = \frac{224}{256} * (-0.1687R' - 0.3313G' + 0.5B') - - Cr = \frac{224}{256} * (0.5R' - 0.4187G' - 0.0813B') - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5] and quantized without further scaling or offsets. -The non-standard xvYCC 709 or xvYCC 601 encodings can be -used by selecting ``V4L2_YCBCR_ENC_XV709`` or ``V4L2_YCBCR_ENC_XV601``. -As seen by the xvYCC formulas these encodings always use limited range quantization, -there is no full range variant. The whole point of these extended gamut encodings -is that values outside the limited range are still valid, although they -map to R', G' and B' values outside the [0…1] range and are therefore outside -the Rec. 709 colorspace gamut. - - -.. _col-srgb: - -Colorspace sRGB (V4L2_COLORSPACE_SRGB) -====================================== - -The :ref:`srgb` standard defines the colorspace used by most webcams -and computer graphics. The default transfer function is -``V4L2_XFER_FUNC_SRGB``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited range. - -Note that the :ref:`sycc` standard specifies full range quantization, -however all current capture hardware supported by the kernel convert -R'G'B' to limited range Y'CbCr. So choosing full range as the default -would break how applications interpret the quantization range. - -The chromaticities of the primary colors and the white reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: sRGB Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.640 - - 0.330 - * - Green - - 0.300 - - 0.600 - * - Blue - - 0.150 - - 0.060 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - -These chromaticities are identical to the Rec. 709 colorspace. - -Transfer function. Note that negative values for L are only used by the -Y'CbCr conversion. - -.. math:: - - L' = -1.055(-L)^{\frac{1}{2.4} } + 0.055\text{, for }L < -0.0031308 - - L' = 12.92L\text{, for }-0.0031308 \le L \le 0.0031308 - - L' = 1.055L ^{\frac{1}{2.4} } - 0.055\text{, for }0.0031308 < L \le 1 - -Inverse Transfer function: - -.. math:: - - L = -((-L' + 0.055) / 1.055) ^{2.4}\text{, for }L' < -0.04045 - - L = L' / 12.92\text{, for }-0.04045 \le L' \le 0.04045 - - L = ((L' + 0.055) / 1.055) ^{2.4}\text{, for }L' > 0.04045 - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_601`` encoding as defined by :ref:`sycc`: - -.. math:: - - Y' = 0.2990R' + 0.5870G' + 0.1140B' - - Cb = -0.1687R' - 0.3313G' + 0.5B' - - Cr = 0.5R' - 0.4187G' - 0.0813B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. This transform is identical to one defined in SMPTE -170M/BT.601. The Y'CbCr quantization is limited range. - - -.. _col-oprgb: - -Colorspace opRGB (V4L2_COLORSPACE_OPRGB) -=============================================== - -The :ref:`oprgb` standard defines the colorspace used by computer -graphics that use the opRGB colorspace. The default transfer function is -``V4L2_XFER_FUNC_OPRGB``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited -range. - -Note that the :ref:`oprgb` standard specifies full range quantization, -however all current capture hardware supported by the kernel convert -R'G'B' to limited range Y'CbCr. So choosing full range as the default -would break how applications interpret the quantization range. - -The chromaticities of the primary colors and the white reference are: - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: opRGB Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.6400 - - 0.3300 - * - Green - - 0.2100 - - 0.7100 - * - Blue - - 0.1500 - - 0.0600 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - - -Transfer function: - -.. math:: - - L' = L ^{\frac{1}{2.19921875}} - -Inverse Transfer function: - -.. math:: - - L = L'^{(2.19921875)} - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_601`` encoding: - -.. math:: - - Y' = 0.2990R' + 0.5870G' + 0.1140B' - - Cb = -0.1687R' - 0.3313G' + 0.5B' - - Cr = 0.5R' - 0.4187G' - 0.0813B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. This transform is identical to one defined in SMPTE -170M/BT.601. The Y'CbCr quantization is limited range. - - -.. _col-bt2020: - -Colorspace BT.2020 (V4L2_COLORSPACE_BT2020) -=========================================== - -The :ref:`itu2020` standard defines the colorspace used by Ultra-high -definition television (UHDTV). The default transfer function is -``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_BT2020``. The default R'G'B' quantization is limited -range (!), and so is the default Y'CbCr quantization. The chromaticities -of the primary colors and the white reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: BT.2020 Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.708 - - 0.292 - * - Green - - 0.170 - - 0.797 - * - Blue - - 0.131 - - 0.046 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - - -Transfer function (same as Rec. 709): - -.. math:: - - L' = 4.5L\text{, for }0 \le L < 0.018 - - L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1 - -Inverse Transfer function: - -.. math:: - - L = L' / 4.5\text{, for } L' < 0.081 - - L = \left( \frac{L' + 0.099}{1.099}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081 - -Please note that while Rec. 709 is defined as the default transfer function -by the :ref:`itu2020` standard, in practice this colorspace is often used -with the :ref:`xf-smpte-2084`. In particular Ultra HD Blu-ray discs use -this combination. - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_BT2020`` encoding: - -.. math:: - - Y' = 0.2627R' + 0.6780G' + 0.0593B' - - Cb = -0.1396R' - 0.3604G' + 0.5B' - - Cr = 0.5R' - 0.4598G' - 0.0402B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. The Y'CbCr quantization is limited range. - -There is also an alternate constant luminance R'G'B' to Yc'CbcCrc -(``V4L2_YCBCR_ENC_BT2020_CONST_LUM``) encoding: - -Luma: - -.. math:: - :nowrap: - - \begin{align*} - Yc' = (0.2627R + 0.6780G + 0.0593B)'& \\ - B' - Yc' \le 0:& \\ - &Cbc = (B' - Yc') / 1.9404 \\ - B' - Yc' > 0: & \\ - &Cbc = (B' - Yc') / 1.5816 \\ - R' - Yc' \le 0:& \\ - &Crc = (R' - Y') / 1.7184 \\ - R' - Yc' > 0:& \\ - &Crc = (R' - Y') / 0.9936 - \end{align*} - -Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the -range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range. - - -.. _col-dcip3: - -Colorspace DCI-P3 (V4L2_COLORSPACE_DCI_P3) -========================================== - -The :ref:`smpte431` standard defines the colorspace used by cinema -projectors that use the DCI-P3 colorspace. The default transfer function -is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_709``. The default Y'CbCr quantization is limited range. - -.. note:: - - Note that this colorspace standard does not specify a - Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this - default Y'CbCr encoding was picked because it is the HDTV encoding. - -The chromaticities of the primary colors and the white reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: DCI-P3 Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.6800 - - 0.3200 - * - Green - - 0.2650 - - 0.6900 - * - Blue - - 0.1500 - - 0.0600 - * - White Reference - - 0.3140 - - 0.3510 - - - -Transfer function: - -.. math:: - - L' = L^{\frac{1}{2.6}} - -Inverse Transfer function: - -.. math:: - - L = L'^{(2.6)} - -Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709. - - -.. _col-smpte-240m: - -Colorspace SMPTE 240M (V4L2_COLORSPACE_SMPTE240M) -================================================= - -The :ref:`smpte240m` standard was an interim standard used during the -early days of HDTV (1988-1998). It has been superseded by Rec. 709. The -default transfer function is ``V4L2_XFER_FUNC_SMPTE240M``. The default -Y'CbCr encoding is ``V4L2_YCBCR_ENC_SMPTE240M``. The default Y'CbCr -quantization is limited range. The chromaticities of the primary colors -and the white reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: SMPTE 240M Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.630 - - 0.340 - * - Green - - 0.310 - - 0.595 - * - Blue - - 0.155 - - 0.070 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - -These chromaticities are identical to the SMPTE 170M colorspace. - -Transfer function: - -.. math:: - - L' = 4L\text{, for } 0 \le L < 0.0228 - - L' = 1.1115L ^{0.45} - 0.1115\text{, for } 0.0228 \le L \le 1 - -Inverse Transfer function: - -.. math:: - - L = \frac{L'}{4}\text{, for } 0 \le L' < 0.0913 - - L = \left( \frac{L' + 0.1115}{1.1115}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.0913 - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_SMPTE240M`` encoding: - -.. math:: - - Y' = 0.2122R' + 0.7013G' + 0.0865B' - - Cb = -0.1161R' - 0.3839G' + 0.5B' - - Cr = 0.5R' - 0.4451G' - 0.0549B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the -range [-0.5…0.5]. The Y'CbCr quantization is limited range. - - -.. _col-sysm: - -Colorspace NTSC 1953 (V4L2_COLORSPACE_470_SYSTEM_M) -=================================================== - -This standard defines the colorspace used by NTSC in 1953. In practice -this colorspace is obsolete and SMPTE 170M should be used instead. The -default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr -encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is -limited range. The chromaticities of the primary colors and the white -reference are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: NTSC 1953 Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.67 - - 0.33 - * - Green - - 0.21 - - 0.71 - * - Blue - - 0.14 - - 0.08 - * - White Reference (C) - - 0.310 - - 0.316 - - -.. note:: - - This colorspace uses Illuminant C instead of D65 as the white - reference. To correctly convert an image in this colorspace to another - that uses D65 you need to apply a chromatic adaptation algorithm such as - the Bradford method. - -The transfer function was never properly defined for NTSC 1953. The Rec. -709 transfer function is recommended in the literature: - -.. math:: - - L' = 4.5L\text{, for } 0 \le L < 0.018 - - L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1 - -Inverse Transfer function: - -.. math:: - - L = \frac{L'}{4.5} \text{, for } L' < 0.081 - - L = \left( \frac{L' + 0.099}{1.099}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081 - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_601`` encoding: - -.. math:: - - Y' = 0.2990R' + 0.5870G' + 0.1140B' - - Cb = -0.1687R' - 0.3313G' + 0.5B' - - Cr = 0.5R' - 0.4187G' - 0.0813B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is -identical to one defined in SMPTE 170M/BT.601. - - -.. _col-sysbg: - -Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG) -========================================================= - -The :ref:`tech3213` standard defines the colorspace used by PAL/SECAM -in 1975. In practice this colorspace is obsolete and SMPTE 170M should -be used instead. The default transfer function is -``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is -``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited -range. The chromaticities of the primary colors and the white reference -are: - - - -.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. flat-table:: EBU Tech. 3213 Chromaticities - :header-rows: 1 - :stub-columns: 0 - :widths: 1 1 2 - - * - Color - - x - - y - * - Red - - 0.64 - - 0.33 - * - Green - - 0.29 - - 0.60 - * - Blue - - 0.15 - - 0.06 - * - White Reference (D65) - - 0.3127 - - 0.3290 - - - -The transfer function was never properly defined for this colorspace. -The Rec. 709 transfer function is recommended in the literature: - -.. math:: - - L' = 4.5L\text{, for } 0 \le L < 0.018 - - L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1 - -Inverse Transfer function: - -.. math:: - - L = \frac{L'}{4.5} \text{, for } L' < 0.081 - - L = \left(\frac{L' + 0.099}{1.099} \right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081 - -The luminance (Y') and color difference (Cb and Cr) are obtained with -the following ``V4L2_YCBCR_ENC_601`` encoding: - -.. math:: - - Y' = 0.2990R' + 0.5870G' + 0.1140B' - - Cb = -0.1687R' - 0.3313G' + 0.5B' - - Cr = 0.5R' - 0.4187G' - 0.0813B' - -Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range -[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is -identical to one defined in SMPTE 170M/BT.601. - - -.. _col-jpeg: - -Colorspace JPEG (V4L2_COLORSPACE_JPEG) -====================================== - -This colorspace defines the colorspace used by most (Motion-)JPEG -formats. The chromaticities of the primary colors and the white -reference are identical to sRGB. The transfer function use is -``V4L2_XFER_FUNC_SRGB``. The Y'CbCr encoding is ``V4L2_YCBCR_ENC_601`` -with full range quantization where Y' is scaled to [0…255] and Cb/Cr are -scaled to [-128…128] and then clipped to [-128…127]. - -.. note:: - - The JPEG standard does not actually store colorspace - information. So if something other than sRGB is used, then the driver - will have to set that information explicitly. Effectively - ``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for - ``V4L2_COLORSPACE_SRGB``, ``V4L2_YCBCR_ENC_601`` and - ``V4L2_QUANTIZATION_FULL_RANGE``. - -*************************************** -Detailed Transfer Function Descriptions -*************************************** - -.. _xf-smpte-2084: - -Transfer Function SMPTE 2084 (V4L2_XFER_FUNC_SMPTE2084) -======================================================= - -The :ref:`smpte2084` standard defines the transfer function used by -High Dynamic Range content. - -Constants: - m1 = (2610 / 4096) / 4 - - m2 = (2523 / 4096) * 128 - - c1 = 3424 / 4096 - - c2 = (2413 / 4096) * 32 - - c3 = (2392 / 4096) * 32 - -Transfer function: - L' = ((c1 + c2 * L\ :sup:`m1`) / (1 + c3 * L\ :sup:`m1`))\ :sup:`m2` - -Inverse Transfer function: - L = (max(L':sup:`1/m2` - c1, 0) / (c2 - c3 * - L'\ :sup:`1/m2`))\ :sup:`1/m1` - -Take care when converting between this transfer function and non-HDR transfer -functions: the linear RGB values [0…1] of HDR content map to a luminance range -of 0 to 10000 cd/m\ :sup:`2` whereas the linear RGB values of non-HDR (aka -Standard Dynamic Range or SDR) map to a luminance range of 0 to 100 cd/m\ :sup:`2`. - -To go from SDR to HDR you will have to divide L by 100 first. To go in the other -direction you will have to multiply L by 100. Of course, this clamps all -luminance values over 100 cd/m\ :sup:`2` to 100 cd/m\ :sup:`2`. - -There are better methods, see e.g. :ref:`colimg` for more in-depth information -about this. diff --git a/Documentation/media/uapi/v4l/colorspaces.rst b/Documentation/media/uapi/v4l/colorspaces.rst deleted file mode 100644 index 4f6c82fa057f..000000000000 --- a/Documentation/media/uapi/v4l/colorspaces.rst +++ /dev/null @@ -1,170 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _colorspaces: - -*********** -Colorspaces -*********** - -'Color' is a very complex concept and depends on physics, chemistry and -biology. Just because you have three numbers that describe the 'red', -'green' and 'blue' components of the color of a pixel does not mean that -you can accurately display that color. A colorspace defines what it -actually *means* to have an RGB value of e.g. (255, 0, 0). That is, -which color should be reproduced on the screen in a perfectly calibrated -environment. - -In order to do that we first need to have a good definition of color, -i.e. some way to uniquely and unambiguously define a color so that -someone else can reproduce it. Human color vision is trichromatic since -the human eye has color receptors that are sensitive to three different -wavelengths of light. Hence the need to use three numbers to describe -color. Be glad you are not a mantis shrimp as those are sensitive to 12 -different wavelengths, so instead of RGB we would be using the -ABCDEFGHIJKL colorspace... - -Color exists only in the eye and brain and is the result of how strongly -color receptors are stimulated. This is based on the Spectral Power -Distribution (SPD) which is a graph showing the intensity (radiant -power) of the light at wavelengths covering the visible spectrum as it -enters the eye. The science of colorimetry is about the relationship -between the SPD and color as perceived by the human brain. - -Since the human eye has only three color receptors it is perfectly -possible that different SPDs will result in the same stimulation of -those receptors and are perceived as the same color, even though the SPD -of the light is different. - -In the 1920s experiments were devised to determine the relationship -between SPDs and the perceived color and that resulted in the CIE 1931 -standard that defines spectral weighting functions that model the -perception of color. Specifically that standard defines functions that -can take an SPD and calculate the stimulus for each color receptor. -After some further mathematical transforms these stimuli are known as -the *CIE XYZ tristimulus* values and these X, Y and Z values describe a -color as perceived by a human unambiguously. These X, Y and Z values are -all in the range [0…1]. - -The Y value in the CIE XYZ colorspace corresponds to luminance. Often -the CIE XYZ colorspace is transformed to the normalized CIE xyY -colorspace: - - x = X / (X + Y + Z) - - y = Y / (X + Y + Z) - -The x and y values are the chromaticity coordinates and can be used to -define a color without the luminance component Y. It is very confusing -to have such similar names for these colorspaces. Just be aware that if -colors are specified with lower case 'x' and 'y', then the CIE xyY -colorspace is used. Upper case 'X' and 'Y' refer to the CIE XYZ -colorspace. Also, y has nothing to do with luminance. Together x and y -specify a color, and Y the luminance. That is really all you need to -remember from a practical point of view. At the end of this section you -will find reading resources that go into much more detail if you are -interested. - -A monitor or TV will reproduce colors by emitting light at three -different wavelengths, the combination of which will stimulate the color -receptors in the eye and thus cause the perception of color. -Historically these wavelengths were defined by the red, green and blue -phosphors used in the displays. These *color primaries* are part of what -defines a colorspace. - -Different display devices will have different primaries and some -primaries are more suitable for some display technologies than others. -This has resulted in a variety of colorspaces that are used for -different display technologies or uses. To define a colorspace you need -to define the three color primaries (these are typically defined as x, y -chromaticity coordinates from the CIE xyY colorspace) but also the white -reference: that is the color obtained when all three primaries are at -maximum power. This determines the relative power or energy of the -primaries. This is usually chosen to be close to daylight which has been -defined as the CIE D65 Illuminant. - -To recapitulate: the CIE XYZ colorspace uniquely identifies colors. -Other colorspaces are defined by three chromaticity coordinates defined -in the CIE xyY colorspace. Based on those a 3x3 matrix can be -constructed that transforms CIE XYZ colors to colors in the new -colorspace. - -Both the CIE XYZ and the RGB colorspace that are derived from the -specific chromaticity primaries are linear colorspaces. But neither the -eye, nor display technology is linear. Doubling the values of all -components in the linear colorspace will not be perceived as twice the -intensity of the color. So each colorspace also defines a transfer -function that takes a linear color component value and transforms it to -the non-linear component value, which is a closer match to the -non-linear performance of both the eye and displays. Linear component -values are denoted RGB, non-linear are denoted as R'G'B'. In general -colors used in graphics are all R'G'B', except in openGL which uses -linear RGB. Special care should be taken when dealing with openGL to -provide linear RGB colors or to use the built-in openGL support to apply -the inverse transfer function. - -The final piece that defines a colorspace is a function that transforms -non-linear R'G'B' to non-linear Y'CbCr. This function is determined by -the so-called luma coefficients. There may be multiple possible Y'CbCr -encodings allowed for the same colorspace. Many encodings of color -prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the -human eye is more sensitive to differences in luminance than in color -this encoding allows one to reduce the amount of color information -compared to the luma data. Note that the luma (Y') is unrelated to the Y -in the CIE XYZ colorspace. Also note that Y'CbCr is often called YCbCr -or YUV even though these are strictly speaking wrong. - -Sometimes people confuse Y'CbCr as being a colorspace. This is not -correct, it is just an encoding of an R'G'B' color into luma and chroma -values. The underlying colorspace that is associated with the R'G'B' -color is also associated with the Y'CbCr color. - -The final step is how the RGB, R'G'B' or Y'CbCr values are quantized. -The CIE XYZ colorspace where X, Y and Z are in the range [0…1] describes -all colors that humans can perceive, but the transform to another -colorspace will produce colors that are outside the [0…1] range. Once -clamped to the [0…1] range those colors can no longer be reproduced in -that colorspace. This clamping is what reduces the extent or gamut of -the colorspace. How the range of [0…1] is translated to integer values -in the range of [0…255] (or higher, depending on the color depth) is -called the quantization. This is *not* part of the colorspace -definition. In practice RGB or R'G'B' values are full range, i.e. they -use the full [0…255] range. Y'CbCr values on the other hand are limited -range with Y' using [16…235] and Cb and Cr using [16…240]. - -Unfortunately, in some cases limited range RGB is also used where the -components use the range [16…235]. And full range Y'CbCr also exists -using the [0…255] range. - -In order to correctly interpret a color you need to know the -quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr -encoding and the colorspace. From that information you can calculate the -corresponding CIE XYZ color and map that again to whatever colorspace -your display device uses. - -The colorspace definition itself consists of the three chromaticity -primaries, the white reference chromaticity, a transfer function and the -luma coefficients needed to transform R'G'B' to Y'CbCr. While some -colorspace standards correctly define all four, quite often the -colorspace standard only defines some, and you have to rely on other -standards for the missing pieces. The fact that colorspaces are often a -mix of different standards also led to very confusing naming conventions -where the name of a standard was used to name a colorspace when in fact -that standard was part of various other colorspaces as well. - -If you want to read more about colors and colorspaces, then the -following resources are useful: :ref:`poynton` is a good practical -book for video engineers, :ref:`colimg` has a much broader scope and -describes many more aspects of color (physics, chemistry, biology, -etc.). The -`http://www.brucelindbloom.com `__ -website is an excellent resource, especially with respect to the -mathematics behind colorspace conversions. The wikipedia -`CIE 1931 colorspace `__ -article is also very useful. diff --git a/Documentation/media/uapi/v4l/common-defs.rst b/Documentation/media/uapi/v4l/common-defs.rst deleted file mode 100644 index 504c6c93c9b0..000000000000 --- a/Documentation/media/uapi/v4l/common-defs.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _common-defs: - -****************************************************** -Common definitions for V4L2 and V4L2 subdev interfaces -****************************************************** - - -.. toctree:: - :maxdepth: 1 - - selections-common diff --git a/Documentation/media/uapi/v4l/common.rst b/Documentation/media/uapi/v4l/common.rst deleted file mode 100644 index 5e87ae24e4b4..000000000000 --- a/Documentation/media/uapi/v4l/common.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _common: - -################### -Common API Elements -################### -Programming a V4L2 device consists of these steps: - -- Opening the device - -- Changing device properties, selecting a video and audio input, video - standard, picture brightness a. o. - -- Negotiating a data format - -- Negotiating an input/output method - -- The actual input/output loop - -- Closing the device - -In practice most steps are optional and can be executed out of order. It -depends on the V4L2 device type, you can read about the details in -:ref:`devices`. In this chapter we will discuss the basic concepts -applicable to all devices. - - -.. toctree:: - :maxdepth: 1 - - open - querycap - app-pri - video - audio - tuner - standard - dv-timings - control - extended-controls - ext-ctrls-camera - ext-ctrls-flash - ext-ctrls-image-source - ext-ctrls-image-process - ext-ctrls-codec - ext-ctrls-jpeg - ext-ctrls-dv - ext-ctrls-rf-tuner - ext-ctrls-fm-tx - ext-ctrls-fm-rx - ext-ctrls-detect - format - planar-apis - selection-api - crop - streaming-par diff --git a/Documentation/media/uapi/v4l/compat.rst b/Documentation/media/uapi/v4l/compat.rst deleted file mode 100644 index f35575a300b4..000000000000 --- a/Documentation/media/uapi/v4l/compat.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _compat: - -******* -Changes -******* - -The following chapters document the evolution of the V4L2 API, errata or -extensions. They are also intended to help application and driver -writers to port or update their code. - - -.. toctree:: - :maxdepth: 1 - - diff-v4l - hist-v4l2 diff --git a/Documentation/media/uapi/v4l/constraints.svg b/Documentation/media/uapi/v4l/constraints.svg deleted file mode 100644 index 08f9f8b0985e..000000000000 --- a/Documentation/media/uapi/v4l/constraints.svg +++ /dev/null @@ -1,37 +0,0 @@ - - -image/svg+xmlV4L2_SEL_FLAG_GE -ORIGINAL -V4L2_SEL_FLAG_LE - diff --git a/Documentation/media/uapi/v4l/control.rst b/Documentation/media/uapi/v4l/control.rst deleted file mode 100644 index ef62e088ff7a..000000000000 --- a/Documentation/media/uapi/v4l/control.rst +++ /dev/null @@ -1,512 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _control: - -************* -User Controls -************* - -Devices typically have a number of user-settable controls such as -brightness, saturation and so on, which would be presented to the user -on a graphical user interface. But, different devices will have -different controls available, and furthermore, the range of possible -values, and the default value will vary from device to device. The -control ioctls provide the information and a mechanism to create a nice -user interface for these controls that will work correctly with any -device. - -All controls are accessed using an ID value. V4L2 defines several IDs -for specific purposes. Drivers can also implement their own custom -controls using ``V4L2_CID_PRIVATE_BASE`` [#f1]_ and higher values. The -pre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in -:ref:`control-id`. The ID is used when querying the attributes of a -control, and when getting or setting the current value. - -Generally applications should present controls to the user without -assumptions about their purpose. Each control comes with a name string -the user is supposed to understand. When the purpose is non-intuitive -the driver writer should provide a user manual, a user interface plug-in -or a driver specific panel application. Predefined IDs were introduced -to change a few controls programmatically, for example to mute a device -during a channel switch. - -Drivers may enumerate different controls after switching the current -video input or output, tuner or modulator, or audio input or output. -Different in the sense of other bounds, another default and current -value, step size or other menu items. A control with a certain *custom* -ID can also change name and type. - -If a control is not applicable to the current configuration of the -device (for example, it doesn't apply to the current video input) -drivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag. - -Control values are stored globally, they do not change when switching -except to stay within the reported bounds. They also do not change e. g. -when the device is opened or closed, when the tuner radio frequency is -changed or generally never without application request. - -V4L2 specifies an event mechanism to notify applications when controls -change value (see -:ref:`VIDIOC_SUBSCRIBE_EVENT`, event -``V4L2_EVENT_CTRL``), panel applications might want to make use of that -in order to always reflect the correct control value. - -All controls use machine endianness. - - -.. _control-id: - -Control IDs -=========== - -``V4L2_CID_BASE`` - First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``. - -``V4L2_CID_USER_BASE`` - Synonym of ``V4L2_CID_BASE``. - -``V4L2_CID_BRIGHTNESS`` ``(integer)`` - Picture brightness, or more precisely, the black level. - -``V4L2_CID_CONTRAST`` ``(integer)`` - Picture contrast or luma gain. - -``V4L2_CID_SATURATION`` ``(integer)`` - Picture color saturation or chroma gain. - -``V4L2_CID_HUE`` ``(integer)`` - Hue or color balance. - -``V4L2_CID_AUDIO_VOLUME`` ``(integer)`` - Overall audio volume. Note some drivers also provide an OSS or ALSA - mixer interface. - -``V4L2_CID_AUDIO_BALANCE`` ``(integer)`` - Audio stereo balance. Minimum corresponds to all the way left, - maximum to right. - -``V4L2_CID_AUDIO_BASS`` ``(integer)`` - Audio bass adjustment. - -``V4L2_CID_AUDIO_TREBLE`` ``(integer)`` - Audio treble adjustment. - -``V4L2_CID_AUDIO_MUTE`` ``(boolean)`` - Mute audio, i. e. set the volume to zero, however without affecting - ``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute - at load time to avoid excessive noise. Actually the entire device - should be reset to a low power consumption state. - -``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)`` - Loudness mode (bass boost). - -``V4L2_CID_BLACK_LEVEL`` ``(integer)`` - Another name for brightness (not a synonym of - ``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not - be used in new drivers and applications. - -``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)`` - Automatic white balance (cameras). - -``V4L2_CID_DO_WHITE_BALANCE`` ``(button)`` - This is an action control. When set (the value is ignored), the - device will do a white balance and then hold the current setting. - Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``, - which, when activated, keeps adjusting the white balance. - -``V4L2_CID_RED_BALANCE`` ``(integer)`` - Red chroma balance. - -``V4L2_CID_BLUE_BALANCE`` ``(integer)`` - Blue chroma balance. - -``V4L2_CID_GAMMA`` ``(integer)`` - Gamma adjust. - -``V4L2_CID_WHITENESS`` ``(integer)`` - Whiteness for grey-scale devices. This is a synonym for - ``V4L2_CID_GAMMA``. This control is deprecated and should not be - used in new drivers and applications. - -``V4L2_CID_EXPOSURE`` ``(integer)`` - Exposure (cameras). [Unit?] - -``V4L2_CID_AUTOGAIN`` ``(boolean)`` - Automatic gain/exposure control. - -``V4L2_CID_GAIN`` ``(integer)`` - Gain control. - - Primarily used to control gain on e.g. TV tuners but also on - webcams. Most devices control only digital gain with this control - but on some this could include analogue gain as well. Devices that - recognise the difference between digital and analogue gain use - controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``. - -``V4L2_CID_HFLIP`` ``(boolean)`` - Mirror the picture horizontally. - -``V4L2_CID_VFLIP`` ``(boolean)`` - Mirror the picture vertically. - -.. _v4l2-power-line-frequency: - -``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)`` - Enables a power line frequency filter to avoid flicker. Possible - values for ``enum v4l2_power_line_frequency`` are: - ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` (0), - ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` (1), - ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` (2) and - ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` (3). - -``V4L2_CID_HUE_AUTO`` ``(boolean)`` - Enables automatic hue control by the device. The effect of setting - ``V4L2_CID_HUE`` while automatic hue control is enabled is - undefined, drivers should ignore such request. - -``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)`` - This control specifies the white balance settings as a color - temperature in Kelvin. A driver should have a minimum of 2800 - (incandescent) to 6500 (daylight). For more information about color - temperature see - `Wikipedia `__. - -``V4L2_CID_SHARPNESS`` ``(integer)`` - Adjusts the sharpness filters in a camera. The minimum value - disables the filters, higher values give a sharper picture. - -``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)`` - Adjusts the backlight compensation in a camera. The minimum value - disables backlight compensation. - -``V4L2_CID_CHROMA_AGC`` ``(boolean)`` - Chroma automatic gain control. - -``V4L2_CID_CHROMA_GAIN`` ``(integer)`` - Adjusts the Chroma gain control (for use when chroma AGC is - disabled). - -``V4L2_CID_COLOR_KILLER`` ``(boolean)`` - Enable the color killer (i. e. force a black & white image in case - of a weak video signal). - -.. _v4l2-colorfx: - -``V4L2_CID_COLORFX`` ``(enum)`` - Selects a color effect. The following values are defined: - - - -.. tabularcolumns:: |p{5.5cm}|p{12cm}| - -.. flat-table:: - :header-rows: 0 - :stub-columns: 0 - :widths: 11 24 - - * - ``V4L2_COLORFX_NONE`` - - Color effect is disabled. - * - ``V4L2_COLORFX_ANTIQUE`` - - An aging (old photo) effect. - * - ``V4L2_COLORFX_ART_FREEZE`` - - Frost color effect. - * - ``V4L2_COLORFX_AQUA`` - - Water color, cool tone. - * - ``V4L2_COLORFX_BW`` - - Black and white. - * - ``V4L2_COLORFX_EMBOSS`` - - Emboss, the highlights and shadows replace light/dark boundaries - and low contrast areas are set to a gray background. - * - ``V4L2_COLORFX_GRASS_GREEN`` - - Grass green. - * - ``V4L2_COLORFX_NEGATIVE`` - - Negative. - * - ``V4L2_COLORFX_SEPIA`` - - Sepia tone. - * - ``V4L2_COLORFX_SKETCH`` - - Sketch. - * - ``V4L2_COLORFX_SKIN_WHITEN`` - - Skin whiten. - * - ``V4L2_COLORFX_SKY_BLUE`` - - Sky blue. - * - ``V4L2_COLORFX_SOLARIZATION`` - - Solarization, the image is partially reversed in tone, only color - values above or below a certain threshold are inverted. - * - ``V4L2_COLORFX_SILHOUETTE`` - - Silhouette (outline). - * - ``V4L2_COLORFX_VIVID`` - - Vivid colors. - * - ``V4L2_COLORFX_SET_CBCR`` - - The Cb and Cr chroma components are replaced by fixed coefficients - determined by ``V4L2_CID_COLORFX_CBCR`` control. - - - -``V4L2_CID_COLORFX_CBCR`` ``(integer)`` - Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR`` - color effect. Bits [7:0] of the supplied 32 bit value are - interpreted as Cr component, bits [15:8] as Cb component and bits - [31:16] must be zero. - -``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)`` - Enable Automatic Brightness. - -``V4L2_CID_ROTATE`` ``(integer)`` - Rotates the image by specified angle. Common angles are 90, 270 and - 180. Rotating the image to 90 and 270 will reverse the height and - width of the display window. It is necessary to set the new height - and width of the picture using the - :ref:`VIDIOC_S_FMT ` ioctl according to the - rotation angle selected. - -``V4L2_CID_BG_COLOR`` ``(integer)`` - Sets the background color on the current output device. Background - color needs to be specified in the RGB24 format. The supplied 32 bit - value is interpreted as bits 0-7 Red color information, bits 8-15 - Green color information, bits 16-23 Blue color information and bits - 24-31 must be zero. - -``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)`` - Switch on or off the illuminator 1 or 2 of the device (usually a - microscope). - -``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)`` - This is a read-only control that can be read by the application and - used as a hint to determine the number of CAPTURE buffers to pass to - REQBUFS. The value is the minimum number of CAPTURE buffers that is - necessary for hardware to work. - -``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)`` - This is a read-only control that can be read by the application and - used as a hint to determine the number of OUTPUT buffers to pass to - REQBUFS. The value is the minimum number of OUTPUT buffers that is - necessary for hardware to work. - -.. _v4l2-alpha-component: - -``V4L2_CID_ALPHA_COMPONENT`` ``(integer)`` - Sets the alpha color component. When a capture device (or capture - queue of a mem-to-mem device) produces a frame format that includes - an alpha component (e.g. - :ref:`packed RGB image formats `) and the alpha value - is not defined by the device or the mem-to-mem input data this - control lets you select the alpha component value of all pixels. - When an output device (or output queue of a mem-to-mem device) - consumes a frame format that doesn't include an alpha component and - the device supports alpha channel processing this control lets you - set the alpha component value of all pixels for further processing - in the device. - -``V4L2_CID_LASTP1`` - End of the predefined control IDs (currently - ``V4L2_CID_ALPHA_COMPONENT`` + 1). - -``V4L2_CID_PRIVATE_BASE`` - ID of the first custom (driver specific) control. Applications - depending on particular custom controls should check the driver name - and version, see :ref:`querycap`. - -Applications can enumerate the available controls with the -:ref:`VIDIOC_QUERYCTRL` and -:ref:`VIDIOC_QUERYMENU ` ioctls, get and set a -control value with the :ref:`VIDIOC_G_CTRL ` and -:ref:`VIDIOC_S_CTRL ` ioctls. Drivers must implement -``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the -device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or -more menu type controls. - - -.. _enum_all_controls: - -Example: Enumerating all controls -================================= - -.. code-block:: c - - struct v4l2_queryctrl queryctrl; - struct v4l2_querymenu querymenu; - - static void enumerate_menu(__u32 id) - { - printf(" Menu items:\\n"); - - memset(&querymenu, 0, sizeof(querymenu)); - querymenu.id = id; - - for (querymenu.index = queryctrl.minimum; - querymenu.index <= queryctrl.maximum; - querymenu.index++) { - if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) { - printf(" %s\\n", querymenu.name); - } - } - } - - memset(&queryctrl, 0, sizeof(queryctrl)); - - queryctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL; - while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { - if (!(queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)) { - printf("Control %s\\n", queryctrl.name); - - if (queryctrl.type == V4L2_CTRL_TYPE_MENU) - enumerate_menu(queryctrl.id); - } - - queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; - } - if (errno != EINVAL) { - perror("VIDIOC_QUERYCTRL"); - exit(EXIT_FAILURE); - } - -Example: Enumerating all controls including compound controls -============================================================= - -.. code-block:: c - - struct v4l2_query_ext_ctrl query_ext_ctrl; - - memset(&query_ext_ctrl, 0, sizeof(query_ext_ctrl)); - - query_ext_ctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND; - while (0 == ioctl(fd, VIDIOC_QUERY_EXT_CTRL, &query_ext_ctrl)) { - if (!(query_ext_ctrl.flags & V4L2_CTRL_FLAG_DISABLED)) { - printf("Control %s\\n", query_ext_ctrl.name); - - if (query_ext_ctrl.type == V4L2_CTRL_TYPE_MENU) - enumerate_menu(query_ext_ctrl.id); - } - - query_ext_ctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND; - } - if (errno != EINVAL) { - perror("VIDIOC_QUERY_EXT_CTRL"); - exit(EXIT_FAILURE); - } - -Example: Enumerating all user controls (old style) -================================================== - -.. code-block:: c - - - memset(&queryctrl, 0, sizeof(queryctrl)); - - for (queryctrl.id = V4L2_CID_BASE; - queryctrl.id < V4L2_CID_LASTP1; - queryctrl.id++) { - if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { - if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) - continue; - - printf("Control %s\\n", queryctrl.name); - - if (queryctrl.type == V4L2_CTRL_TYPE_MENU) - enumerate_menu(queryctrl.id); - } else { - if (errno == EINVAL) - continue; - - perror("VIDIOC_QUERYCTRL"); - exit(EXIT_FAILURE); - } - } - - for (queryctrl.id = V4L2_CID_PRIVATE_BASE;; - queryctrl.id++) { - if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { - if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) - continue; - - printf("Control %s\\n", queryctrl.name); - - if (queryctrl.type == V4L2_CTRL_TYPE_MENU) - enumerate_menu(queryctrl.id); - } else { - if (errno == EINVAL) - break; - - perror("VIDIOC_QUERYCTRL"); - exit(EXIT_FAILURE); - } - } - - -Example: Changing controls -========================== - -.. code-block:: c - - struct v4l2_queryctrl queryctrl; - struct v4l2_control control; - - memset(&queryctrl, 0, sizeof(queryctrl)); - queryctrl.id = V4L2_CID_BRIGHTNESS; - - if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { - if (errno != EINVAL) { - perror("VIDIOC_QUERYCTRL"); - exit(EXIT_FAILURE); - } else { - printf("V4L2_CID_BRIGHTNESS is not supportedn"); - } - } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) { - printf("V4L2_CID_BRIGHTNESS is not supportedn"); - } else { - memset(&control, 0, sizeof (control)); - control.id = V4L2_CID_BRIGHTNESS; - control.value = queryctrl.default_value; - - if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) { - perror("VIDIOC_S_CTRL"); - exit(EXIT_FAILURE); - } - } - - memset(&control, 0, sizeof(control)); - control.id = V4L2_CID_CONTRAST; - - if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) { - control.value += 1; - - /* The driver may clamp the value or return ERANGE, ignored here */ - - if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control) - && errno != ERANGE) { - perror("VIDIOC_S_CTRL"); - exit(EXIT_FAILURE); - } - /* Ignore if V4L2_CID_CONTRAST is unsupported */ - } else if (errno != EINVAL) { - perror("VIDIOC_G_CTRL"); - exit(EXIT_FAILURE); - } - - control.id = V4L2_CID_AUDIO_MUTE; - control.value = 1; /* silence */ - - /* Errors ignored */ - ioctl(fd, VIDIOC_S_CTRL, &control); - -.. [#f1] - The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different - drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different - controls. This makes it hard to programmatically set such controls - since the meaning of the control with that ID is driver dependent. In - order to resolve this drivers use unique IDs and the - ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the - kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to - the real IDs. - - Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs - instead of using :ref:`VIDIOC_QUERYCTRL` with - the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so - support for ``V4L2_CID_PRIVATE_BASE`` is still around. diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst deleted file mode 100644 index ada7c22e6291..000000000000 --- a/Documentation/media/uapi/v4l/crop.rst +++ /dev/null @@ -1,324 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _crop: - -***************************************************** -Image Cropping, Insertion and Scaling -- the CROP API -***************************************************** - -.. note:: - - The CROP API is mostly superseded by the newer :ref:`SELECTION API - `. The new API should be preferred in most cases, - with the exception of pixel aspect ratio detection, which is - implemented by :ref:`VIDIOC_CROPCAP ` and has no - equivalent in the SELECTION API. See :ref:`selection-vs-crop` for a - comparison of the two APIs. - -Some video capture devices can sample a subsection of the picture and -shrink or enlarge it to an image of arbitrary size. We call these -abilities cropping and scaling. Some video output devices can scale an -image up or down and insert it at an arbitrary scan line and horizontal -offset into a video signal. - -Applications can use the following API to select an area in the video -signal, query the default area and the hardware limits. - -.. note:: - - Despite their name, the :ref:`VIDIOC_CROPCAP `, - :ref:`VIDIOC_G_CROP ` and :ref:`VIDIOC_S_CROP - ` ioctls apply to input as well as output devices. - -Scaling requires a source and a target. On a video capture or overlay -device the source is the video signal, and the cropping ioctls determine -the area actually sampled. The target are images read by the application -or overlaid onto the graphics screen. Their size (and position for an -overlay) is negotiated with the :ref:`VIDIOC_G_FMT ` -and :ref:`VIDIOC_S_FMT ` ioctls. - -On a video output device the source are the images passed in by the -application, and their size is again negotiated with the -:ref:`VIDIOC_G_FMT ` and :ref:`VIDIOC_S_FMT ` -ioctls, or may be encoded in a compressed video stream. The target is -the video signal, and the cropping ioctls determine the area where the -images are inserted. - -Source and target rectangles are defined even if the device does not -support scaling or the :ref:`VIDIOC_G_CROP ` and -:ref:`VIDIOC_S_CROP ` ioctls. Their size (and position -where applicable) will be fixed in this case. - -.. note:: - - All capture and output devices that support the CROP or SELECTION - API will also support the :ref:`VIDIOC_CROPCAP ` - ioctl. - -Cropping Structures -=================== - - -.. _crop-scale: - -.. kernel-figure:: crop.svg - :alt: crop.svg - :align: center - - Image Cropping, Insertion and Scaling - - The cropping, insertion and scaling process - - - -For capture devices the coordinates of the top left corner, width and -height of the area which can be sampled is given by the ``bounds`` -substructure of the struct :c:type:`v4l2_cropcap` returned -by the :ref:`VIDIOC_CROPCAP ` ioctl. To support a wide -range of hardware this specification does not define an origin or units. -However by convention drivers should horizontally count unscaled samples -relative to 0H (the leading edge of the horizontal sync pulse, see -:ref:`vbi-hsync`). Vertically ITU-R line numbers of the first field -(see ITU R-525 line numbering for :ref:`525 lines ` and for -:ref:`625 lines `), multiplied by two if the driver -can capture both fields. - -The top left corner, width and height of the source rectangle, that is -the area actually sampled, is given by struct -:c:type:`v4l2_crop` using the same coordinate system as -struct :c:type:`v4l2_cropcap`. Applications can use the -:ref:`VIDIOC_G_CROP ` and :ref:`VIDIOC_S_CROP ` -ioctls to get and set this rectangle. It must lie completely within the -capture boundaries and the driver may further adjust the requested size -and/or position according to hardware limitations. - -Each capture device has a default source rectangle, given by the -``defrect`` substructure of struct -:c:type:`v4l2_cropcap`. The center of this rectangle -shall align with the center of the active picture area of the video -signal, and cover what the driver writer considers the complete picture. -Drivers shall reset the source rectangle to the default when the driver -is first loaded, but not later. - -For output devices these structures and ioctls are used accordingly, -defining the *target* rectangle where the images will be inserted into -the video signal. - - -Scaling Adjustments -=================== - -Video hardware can have various cropping, insertion and scaling -limitations. It may only scale up or down, support only discrete scaling -factors, or have different scaling abilities in horizontal and vertical -direction. Also it may not support scaling at all. At the same time the -struct :c:type:`v4l2_crop` rectangle may have to be aligned, -and both the source and target rectangles may have arbitrary upper and -lower size limits. In particular the maximum ``width`` and ``height`` in -struct :c:type:`v4l2_crop` may be smaller than the struct -:c:type:`v4l2_cropcap`. ``bounds`` area. Therefore, as -usual, drivers are expected to adjust the requested parameters and -return the actual values selected. - -Applications can change the source or the target rectangle first, as -they may prefer a particular image size or a certain area in the video -signal. If the driver has to adjust both to satisfy hardware -limitations, the last requested rectangle shall take priority, and the -driver should preferably adjust the opposite one. The -:ref:`VIDIOC_TRY_FMT ` ioctl however shall not change -the driver state and therefore only adjust the requested rectangle. - -Suppose scaling on a video capture device is restricted to a factor 1:1 -or 2:1 in either direction and the target image size must be a multiple -of 16 × 16 pixels. The source cropping rectangle is set to defaults, -which are also the upper limit in this example, of 640 × 400 pixels at -offset 0, 0. An application requests an image size of 300 × 225 pixels, -assuming video will be scaled down from the "full picture" accordingly. -The driver sets the image size to the closest possible values 304 × 224, -then chooses the cropping rectangle closest to the requested size, that -is 608 × 224 (224 × 2:1 would exceed the limit 400). The offset 0, 0 is -still valid, thus unmodified. Given the default cropping rectangle -reported by :ref:`VIDIOC_CROPCAP ` the application can -easily propose another offset to center the cropping rectangle. - -Now the application may insist on covering an area using a picture -aspect ratio closer to the original request, so it asks for a cropping -rectangle of 608 × 456 pixels. The present scaling factors limit -cropping to 640 × 384, so the driver returns the cropping size 608 × 384 -and adjusts the image size to closest possible 304 × 192. - - -Examples -======== - -Source and target rectangles shall remain unchanged across closing and -reopening a device, such that piping data into or out of a device will -work without special preparations. More advanced applications should -ensure the parameters are suitable before starting I/O. - -.. note:: - - On the next two examples, a video capture device is assumed; - change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device. - -Example: Resetting the cropping parameters -========================================== - -.. code-block:: c - - struct v4l2_cropcap cropcap; - struct v4l2_crop crop; - - memset (&cropcap, 0, sizeof (cropcap)); - cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) { - perror ("VIDIOC_CROPCAP"); - exit (EXIT_FAILURE); - } - - memset (&crop, 0, sizeof (crop)); - crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - crop.c = cropcap.defrect; - - /* Ignore if cropping is not supported (EINVAL). */ - - if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) - && errno != EINVAL) { - perror ("VIDIOC_S_CROP"); - exit (EXIT_FAILURE); - } - - -Example: Simple downscaling -=========================== - -.. code-block:: c - - struct v4l2_cropcap cropcap; - struct v4l2_format format; - - reset_cropping_parameters (); - - /* Scale down to 1/4 size of full picture. */ - - memset (&format, 0, sizeof (format)); /* defaults */ - - format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - format.fmt.pix.width = cropcap.defrect.width >> 1; - format.fmt.pix.height = cropcap.defrect.height >> 1; - format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; - - if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) { - perror ("VIDIOC_S_FORMAT"); - exit (EXIT_FAILURE); - } - - /* We could check the actual image size now, the actual scaling factor - or if the driver can scale at all. */ - -Example: Selecting an output area -================================= - -.. note:: This example assumes an output device. - -.. code-block:: c - - struct v4l2_cropcap cropcap; - struct v4l2_crop crop; - - memset (&cropcap, 0, sizeof (cropcap)); - cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; - - if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) { - perror ("VIDIOC_CROPCAP"); - exit (EXIT_FAILURE); - } - - memset (&crop, 0, sizeof (crop)); - - crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; - crop.c = cropcap.defrect; - - /* Scale the width and height to 50 % of their original size - and center the output. */ - - crop.c.width /= 2; - crop.c.height /= 2; - crop.c.left += crop.c.width / 2; - crop.c.top += crop.c.height / 2; - - /* Ignore if cropping is not supported (EINVAL). */ - - if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) - && errno != EINVAL) { - perror ("VIDIOC_S_CROP"); - exit (EXIT_FAILURE); - } - -Example: Current scaling factor and pixel aspect -================================================ - -.. note:: This example assumes a video capture device. - -.. code-block:: c - - struct v4l2_cropcap cropcap; - struct v4l2_crop crop; - struct v4l2_format format; - double hscale, vscale; - double aspect; - int dwidth, dheight; - - memset (&cropcap, 0, sizeof (cropcap)); - cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) { - perror ("VIDIOC_CROPCAP"); - exit (EXIT_FAILURE); - } - - memset (&crop, 0, sizeof (crop)); - crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) { - if (errno != EINVAL) { - perror ("VIDIOC_G_CROP"); - exit (EXIT_FAILURE); - } - - /* Cropping not supported. */ - crop.c = cropcap.defrect; - } - - memset (&format, 0, sizeof (format)); - format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; - - if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) { - perror ("VIDIOC_G_FMT"); - exit (EXIT_FAILURE); - } - - /* The scaling applied by the driver. */ - - hscale = format.fmt.pix.width / (double) crop.c.width; - vscale = format.fmt.pix.height / (double) crop.c.height; - - aspect = cropcap.pixelaspect.numerator / - (double) cropcap.pixelaspect.denominator; - aspect = aspect * hscale / vscale; - - /* Devices following ITU-R BT.601 do not capture - square pixels. For playback on a computer monitor - we should scale the images to this size. */ - - dwidth = format.fmt.pix.width / aspect; - dheight = format.fmt.pix.height; diff --git a/Documentation/media/uapi/v4l/crop.svg b/Documentation/media/uapi/v4l/crop.svg deleted file mode 100644 index 32d72598d135..000000000000 --- a/Documentation/media/uapi/v4l/crop.svg +++ /dev/null @@ -1,290 +0,0 @@ - - -image/svg+xmlv4l2_cropcap.bounds -v4l2_cropcap.defrect -v4l2_crop.c -v4l2_format - - diff --git a/Documentation/media/uapi/v4l/depth-formats.rst b/Documentation/media/uapi/v4l/depth-formats.rst deleted file mode 100644 index 1bfd0b82cb85..000000000000 --- a/Documentation/media/uapi/v4l/depth-formats.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _depth-formats: - -************* -Depth Formats -************* - -Depth data provides distance to points, mapped onto the image plane - - -.. toctree:: - :maxdepth: 1 - - pixfmt-inzi - pixfmt-z16 - pixfmt-cnf4 diff --git a/Documentation/media/uapi/v4l/dev-capture.rst b/Documentation/media/uapi/v4l/dev-capture.rst deleted file mode 100644 index 134e22b32338..000000000000 --- a/Documentation/media/uapi/v4l/dev-capture.rst +++ /dev/null @@ -1,111 +0,0 @@ -.. 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, with no Invariant Sections, no Front-Cover Texts -.. and no Back-Cover Texts. A copy of the license is included at -.. Documentation/media/uapi/fdl-appendix.rst. -.. -.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections - -.. _capture: - -*********************** -Video Capture Interface -*********************** - -Video capture devices sample an analog video signal and store the -digitized images in memory. Today nearly all devices can capture at full -25 or 30 frames/second. With this interface applications can control the -capture process and move images from the driver into user space. - -Conventionally V4L2 video capture devices are accessed through character -device special files named ``/dev/video`` and ``/dev/video0`` to -``/dev/video63`` with major number 81 and minor numbers 0 to 63. -``/dev/video`` is typically a symbolic link to the preferred video -device. - -.. note:: The same device file names are used for video output devices. - - -Querying Capabilities -===================== - -Devices supporting the video capture interface set the -``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` flag in -the ``capabilities`` field of struct -:c:type:`v4l2_capability` returned by the -:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device -functions they may also support the :ref:`video overlay ` -(``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture ` -(``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or -streaming I/O methods must be supported. Tuners and audio inputs are -optional. - - -Supplemental Functions -====================== - -Video capture devices shall support :ref:`audio input