From 60c2820d0f6d3497975b6488e2599f8f611d8b95 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 8 Jul 2016 11:40:06 -0300 Subject: doc_rst: rename the media Sphinx suff to Documentation/media The name of the subsystem is "media", and not "linux_tv". Also, as we plan to add other stuff there in the future, let's rename also the media uAPI book to media_uapi, to make it clearer. No functional changes. Signed-off-by: Mauro Carvalho Chehab --- .../uapi/dvb/audio-bilingual-channel-select.rst | 64 + .../media/uapi/dvb/audio-channel-select.rst | 63 + .../media/uapi/dvb/audio-clear-buffer.rst | 54 + Documentation/media/uapi/dvb/audio-continue.rst | 54 + Documentation/media/uapi/dvb/audio-fclose.rst | 54 + Documentation/media/uapi/dvb/audio-fopen.rst | 104 + Documentation/media/uapi/dvb/audio-fwrite.rst | 82 + .../media/uapi/dvb/audio-get-capabilities.rst | 60 + Documentation/media/uapi/dvb/audio-get-pts.rst | 69 + Documentation/media/uapi/dvb/audio-get-status.rst | 60 + Documentation/media/uapi/dvb/audio-pause.rst | 55 + Documentation/media/uapi/dvb/audio-play.rst | 54 + .../media/uapi/dvb/audio-select-source.rst | 62 + .../media/uapi/dvb/audio-set-attributes.rst | 71 + Documentation/media/uapi/dvb/audio-set-av-sync.rst | 70 + .../media/uapi/dvb/audio-set-bypass-mode.rst | 74 + Documentation/media/uapi/dvb/audio-set-ext-id.rst | 71 + Documentation/media/uapi/dvb/audio-set-id.rst | 65 + Documentation/media/uapi/dvb/audio-set-karaoke.rst | 70 + Documentation/media/uapi/dvb/audio-set-mixer.rst | 59 + Documentation/media/uapi/dvb/audio-set-mute.rst | 74 + .../media/uapi/dvb/audio-set-streamtype.rst | 74 + Documentation/media/uapi/dvb/audio-stop.rst | 54 + Documentation/media/uapi/dvb/audio.rst | 26 + Documentation/media/uapi/dvb/audio_data_types.rst | 176 + .../media/uapi/dvb/audio_function_calls.rst | 34 + Documentation/media/uapi/dvb/audio_h.rst | 9 + Documentation/media/uapi/dvb/ca-fclose.rst | 54 + Documentation/media/uapi/dvb/ca-fopen.rst | 109 + Documentation/media/uapi/dvb/ca-get-cap.rst | 59 + Documentation/media/uapi/dvb/ca-get-descr-info.rst | 59 + Documentation/media/uapi/dvb/ca-get-msg.rst | 59 + Documentation/media/uapi/dvb/ca-get-slot-info.rst | 59 + Documentation/media/uapi/dvb/ca-reset.rst | 53 + Documentation/media/uapi/dvb/ca-send-msg.rst | 59 + Documentation/media/uapi/dvb/ca-set-descr.rst | 59 + Documentation/media/uapi/dvb/ca-set-pid.rst | 59 + Documentation/media/uapi/dvb/ca.rst | 18 + Documentation/media/uapi/dvb/ca_data_types.rst | 110 + Documentation/media/uapi/dvb/ca_function_calls.rst | 21 + Documentation/media/uapi/dvb/ca_h.rst | 9 + Documentation/media/uapi/dvb/demux.rst | 18 + Documentation/media/uapi/dvb/dmx-add-pid.rst | 61 + Documentation/media/uapi/dvb/dmx-fclose.rst | 55 + Documentation/media/uapi/dvb/dmx-fopen.rst | 108 + Documentation/media/uapi/dvb/dmx-fread.rst | 108 + Documentation/media/uapi/dvb/dmx-fwrite.rst | 89 + Documentation/media/uapi/dvb/dmx-get-caps.rst | 59 + Documentation/media/uapi/dvb/dmx-get-event.rst | 76 + Documentation/media/uapi/dvb/dmx-get-pes-pids.rst | 59 + Documentation/media/uapi/dvb/dmx-get-stc.rst | 77 + Documentation/media/uapi/dvb/dmx-remove-pid.rst | 62 + .../media/uapi/dvb/dmx-set-buffer-size.rst | 62 + Documentation/media/uapi/dvb/dmx-set-filter.rst | 68 + .../media/uapi/dvb/dmx-set-pes-filter.rst | 78 + Documentation/media/uapi/dvb/dmx-set-source.rst | 59 + Documentation/media/uapi/dvb/dmx-start.rst | 77 + Documentation/media/uapi/dvb/dmx-stop.rst | 55 + Documentation/media/uapi/dvb/dmx_fcalls.rst | 27 + Documentation/media/uapi/dvb/dmx_h.rst | 9 + Documentation/media/uapi/dvb/dmx_types.rst | 242 + Documentation/media/uapi/dvb/dtv-fe-stats.rst | 17 + Documentation/media/uapi/dvb/dtv-properties.rst | 15 + Documentation/media/uapi/dvb/dtv-property.rst | 31 + Documentation/media/uapi/dvb/dtv-stats.rst | 18 + .../media/uapi/dvb/dvb-fe-read-status.rst | 22 + .../media/uapi/dvb/dvb-frontend-event.rst | 15 + .../media/uapi/dvb/dvb-frontend-parameters.rst | 119 + Documentation/media/uapi/dvb/dvbapi.rst | 98 + Documentation/media/uapi/dvb/dvbproperty-006.rst | 12 + Documentation/media/uapi/dvb/dvbproperty.rst | 111 + Documentation/media/uapi/dvb/examples.rst | 380 + Documentation/media/uapi/dvb/fe-bandwidth-t.rst | 77 + .../media/uapi/dvb/fe-diseqc-recv-slave-reply.rst | 83 + .../media/uapi/dvb/fe-diseqc-reset-overload.rst | 45 + .../media/uapi/dvb/fe-diseqc-send-burst.rst | 84 + .../media/uapi/dvb/fe-diseqc-send-master-cmd.rst | 73 + .../uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst | 54 + .../media/uapi/dvb/fe-enable-high-lnb-voltage.rst | 52 + Documentation/media/uapi/dvb/fe-get-event.rst | 87 + Documentation/media/uapi/dvb/fe-get-frontend.rst | 74 + Documentation/media/uapi/dvb/fe-get-info.rst | 428 + Documentation/media/uapi/dvb/fe-get-property.rst | 68 + Documentation/media/uapi/dvb/fe-read-ber.rst | 60 + .../media/uapi/dvb/fe-read-signal-strength.rst | 63 + Documentation/media/uapi/dvb/fe-read-snr.rst | 61 + Documentation/media/uapi/dvb/fe-read-status.rst | 135 + .../media/uapi/dvb/fe-read-uncorrected-blocks.rst | 65 + .../media/uapi/dvb/fe-set-frontend-tune-mode.rst | 55 + Documentation/media/uapi/dvb/fe-set-frontend.rst | 79 + Documentation/media/uapi/dvb/fe-set-tone.rst | 91 + Documentation/media/uapi/dvb/fe-set-voltage.rst | 63 + Documentation/media/uapi/dvb/fe-type-t.rst | 91 + .../media/uapi/dvb/fe_property_parameters.rst | 1967 ++++ .../uapi/dvb/frontend-property-cable-systems.rst | 75 + .../dvb/frontend-property-satellite-systems.rst | 103 + .../dvb/frontend-property-terrestrial-systems.rst | 294 + .../media/uapi/dvb/frontend-stat-properties.rst | 245 + Documentation/media/uapi/dvb/frontend.rst | 51 + Documentation/media/uapi/dvb/frontend_f_close.rst | 48 + Documentation/media/uapi/dvb/frontend_f_open.rst | 102 + Documentation/media/uapi/dvb/frontend_fcalls.rst | 24 + Documentation/media/uapi/dvb/frontend_h.rst | 9 + .../media/uapi/dvb/frontend_legacy_api.rst | 38 + .../media/uapi/dvb/frontend_legacy_dvbv3_api.rst | 18 + Documentation/media/uapi/dvb/intro.rst | 172 + .../media/uapi/dvb/intro_files/dvbstb.pdf | Bin 0 -> 1881 bytes .../media/uapi/dvb/intro_files/dvbstb.png | Bin 0 -> 22655 bytes Documentation/media/uapi/dvb/legacy_dvb_apis.rst | 20 + Documentation/media/uapi/dvb/net-add-if.rst | 91 + Documentation/media/uapi/dvb/net-get-if.rst | 50 + Documentation/media/uapi/dvb/net-remove-if.rst | 46 + Documentation/media/uapi/dvb/net.rst | 40 + Documentation/media/uapi/dvb/net_h.rst | 9 + .../media/uapi/dvb/query-dvb-frontend-info.rst | 13 + .../media/uapi/dvb/video-clear-buffer.rst | 54 + Documentation/media/uapi/dvb/video-command.rst | 66 + Documentation/media/uapi/dvb/video-continue.rst | 57 + .../media/uapi/dvb/video-fast-forward.rst | 74 + Documentation/media/uapi/dvb/video-fclose.rst | 54 + Documentation/media/uapi/dvb/video-fopen.rst | 112 + Documentation/media/uapi/dvb/video-freeze.rst | 61 + Documentation/media/uapi/dvb/video-fwrite.rst | 82 + .../media/uapi/dvb/video-get-capabilities.rst | 61 + Documentation/media/uapi/dvb/video-get-event.rst | 88 + .../media/uapi/dvb/video-get-frame-count.rst | 65 + .../media/uapi/dvb/video-get-frame-rate.rst | 59 + Documentation/media/uapi/dvb/video-get-navi.rst | 74 + Documentation/media/uapi/dvb/video-get-pts.rst | 69 + Documentation/media/uapi/dvb/video-get-size.rst | 59 + Documentation/media/uapi/dvb/video-get-status.rst | 60 + Documentation/media/uapi/dvb/video-play.rst | 57 + .../media/uapi/dvb/video-select-source.rst | 65 + .../media/uapi/dvb/video-set-attributes.rst | 75 + Documentation/media/uapi/dvb/video-set-blank.rst | 64 + .../media/uapi/dvb/video-set-display-format.rst | 60 + Documentation/media/uapi/dvb/video-set-format.rst | 74 + .../media/uapi/dvb/video-set-highlight.rst | 60 + Documentation/media/uapi/dvb/video-set-id.rst | 73 + .../media/uapi/dvb/video-set-spu-palette.rst | 72 + Documentation/media/uapi/dvb/video-set-spu.rst | 74 + .../media/uapi/dvb/video-set-streamtype.rst | 61 + Documentation/media/uapi/dvb/video-set-system.rst | 75 + Documentation/media/uapi/dvb/video-slowmotion.rst | 74 + .../media/uapi/dvb/video-stillpicture.rst | 61 + Documentation/media/uapi/dvb/video-stop.rst | 74 + Documentation/media/uapi/dvb/video-try-command.rst | 66 + Documentation/media/uapi/dvb/video.rst | 35 + .../media/uapi/dvb/video_function_calls.rst | 43 + Documentation/media/uapi/dvb/video_h.rst | 9 + Documentation/media/uapi/dvb/video_types.rst | 379 + Documentation/media/uapi/fdl-appendix.rst | 471 + Documentation/media/uapi/gen-errors.rst | 101 + .../media/uapi/mediactl/media-controller-intro.rst | 33 + .../media/uapi/mediactl/media-controller-model.rst | 35 + .../media/uapi/mediactl/media-controller.rst | 73 + .../media/uapi/mediactl/media-func-close.rst | 47 + .../media/uapi/mediactl/media-func-ioctl.rst | 67 + .../media/uapi/mediactl/media-func-open.rst | 69 + .../media/uapi/mediactl/media-ioc-device-info.rst | 142 + .../uapi/mediactl/media-ioc-enum-entities.rst | 197 + .../media/uapi/mediactl/media-ioc-enum-links.rst | 172 + .../media/uapi/mediactl/media-ioc-g-topology.rst | 377 + .../media/uapi/mediactl/media-ioc-setup-link.rst | 68 + Documentation/media/uapi/mediactl/media-types.rst | 422 + .../media/uapi/rc/Remote_controllers_Intro.rst | 24 + .../uapi/rc/Remote_controllers_table_change.rst | 18 + .../media/uapi/rc/Remote_controllers_tables.rst | 757 ++ Documentation/media/uapi/rc/keytable.c.rst | 176 + Documentation/media/uapi/rc/lirc_dev_intro.rst | 28 + .../media/uapi/rc/lirc_device_interface.rst | 15 + Documentation/media/uapi/rc/lirc_ioctl.rst | 156 + Documentation/media/uapi/rc/lirc_read.rst | 19 + Documentation/media/uapi/rc/lirc_write.rst | 14 + Documentation/media/uapi/rc/remote_controllers.rst | 52 + .../uapi/rc/remote_controllers_sysfs_nodes.rst | 143 + Documentation/media/uapi/v4l/app-pri.rst | 30 + Documentation/media/uapi/v4l/async.rst | 9 + Documentation/media/uapi/v4l/audio.rst | 90 + Documentation/media/uapi/v4l/biblio.rst | 381 + Documentation/media/uapi/v4l/buffer.rst | 979 ++ Documentation/media/uapi/v4l/capture-example.rst | 13 + Documentation/media/uapi/v4l/capture.c.rst | 664 ++ Documentation/media/uapi/v4l/colorspaces.rst | 163 + Documentation/media/uapi/v4l/common-defs.rst | 13 + Documentation/media/uapi/v4l/common.rst | 46 + Documentation/media/uapi/v4l/compat.rst | 18 + Documentation/media/uapi/v4l/control.rst | 533 + Documentation/media/uapi/v4l/crop.rst | 294 + Documentation/media/uapi/v4l/crop_files/crop.gif | Bin 0 -> 5967 bytes Documentation/media/uapi/v4l/crop_files/crop.pdf | Bin 0 -> 5846 bytes Documentation/media/uapi/v4l/depth-formats.rst | 15 + Documentation/media/uapi/v4l/dev-capture.rst | 102 + Documentation/media/uapi/v4l/dev-codec.rst | 32 + Documentation/media/uapi/v4l/dev-effect.rst | 22 + Documentation/media/uapi/v4l/dev-event.rst | 47 + Documentation/media/uapi/v4l/dev-osd.rst | 146 + Documentation/media/uapi/v4l/dev-output.rst | 99 + Documentation/media/uapi/v4l/dev-overlay.rst | 316 + Documentation/media/uapi/v4l/dev-radio.rst | 52 + Documentation/media/uapi/v4l/dev-raw-vbi.rst | 350 + .../media/uapi/v4l/dev-raw-vbi_files/vbi_525.gif | Bin 0 -> 4741 bytes .../media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf | Bin 0 -> 3395 bytes .../media/uapi/v4l/dev-raw-vbi_files/vbi_625.gif | Bin 0 -> 5095 bytes .../media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf | Bin 0 -> 3683 bytes .../media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif | Bin 0 -> 2400 bytes .../media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf | Bin 0 -> 7405 bytes Documentation/media/uapi/v4l/dev-rds.rst | 255 + Documentation/media/uapi/v4l/dev-sdr.rst | 120 + Documentation/media/uapi/v4l/dev-sliced-vbi.rst | 822 ++ Documentation/media/uapi/v4l/dev-subdev.rst | 491 + .../media/uapi/v4l/dev-subdev_files/pipeline.pdf | Bin 0 -> 20276 bytes .../media/uapi/v4l/dev-subdev_files/pipeline.png | Bin 0 -> 12130 bytes .../subdev-image-processing-crop.pdf | Bin 0 -> 20729 bytes .../subdev-image-processing-crop.svg | 63 + .../subdev-image-processing-full.pdf | Bin 0 -> 46311 bytes .../subdev-image-processing-full.svg | 163 + ...ubdev-image-processing-scaling-multi-source.pdf | Bin 0 -> 36714 bytes ...ubdev-image-processing-scaling-multi-source.svg | 116 + Documentation/media/uapi/v4l/dev-teletext.rst | 34 + Documentation/media/uapi/v4l/devices.rst | 26 + Documentation/media/uapi/v4l/diff-v4l.rst | 954 ++ Documentation/media/uapi/v4l/dmabuf.rst | 155 + Documentation/media/uapi/v4l/driver.rst | 9 + Documentation/media/uapi/v4l/dv-timings.rst | 38 + Documentation/media/uapi/v4l/extended-controls.rst | 4524 +++++++ Documentation/media/uapi/v4l/field-order.rst | 205 + .../uapi/v4l/field-order_files/fieldseq_bt.gif | Bin 0 -> 25430 bytes .../uapi/v4l/field-order_files/fieldseq_bt.pdf | Bin 0 -> 9185 bytes .../uapi/v4l/field-order_files/fieldseq_tb.gif | Bin 0 -> 25323 bytes .../uapi/v4l/field-order_files/fieldseq_tb.pdf | Bin 0 -> 9173 bytes Documentation/media/uapi/v4l/format.rst | 92 + Documentation/media/uapi/v4l/func-close.rst | 49 + Documentation/media/uapi/v4l/func-ioctl.rst | 62 + Documentation/media/uapi/v4l/func-mmap.rst | 134 + Documentation/media/uapi/v4l/func-munmap.rst | 58 + Documentation/media/uapi/v4l/func-open.rst | 83 + Documentation/media/uapi/v4l/func-poll.rst | 116 + Documentation/media/uapi/v4l/func-read.rst | 131 + Documentation/media/uapi/v4l/func-select.rst | 106 + Documentation/media/uapi/v4l/func-write.rst | 82 + Documentation/media/uapi/v4l/hist-v4l2.rst | 1480 +++ Documentation/media/uapi/v4l/io.rst | 51 + .../media/uapi/v4l/libv4l-introduction.rst | 169 + Documentation/media/uapi/v4l/libv4l.rst | 13 + Documentation/media/uapi/v4l/mmap.rst | 280 + Documentation/media/uapi/v4l/open.rst | 158 + Documentation/media/uapi/v4l/pixfmt-002.rst | 196 + Documentation/media/uapi/v4l/pixfmt-003.rst | 166 + Documentation/media/uapi/v4l/pixfmt-004.rst | 51 + Documentation/media/uapi/v4l/pixfmt-006.rst | 280 + Documentation/media/uapi/v4l/pixfmt-007.rst | 894 ++ Documentation/media/uapi/v4l/pixfmt-008.rst | 32 + Documentation/media/uapi/v4l/pixfmt-013.rst | 129 + Documentation/media/uapi/v4l/pixfmt-grey.rst | 77 + Documentation/media/uapi/v4l/pixfmt-indexed.rst | 73 + Documentation/media/uapi/v4l/pixfmt-m420.rst | 219 + Documentation/media/uapi/v4l/pixfmt-nv12.rst | 221 + Documentation/media/uapi/v4l/pixfmt-nv12m.rst | 238 + Documentation/media/uapi/v4l/pixfmt-nv12mt.rst | 62 + .../media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif | Bin 0 -> 2108 bytes .../v4l/pixfmt-nv12mt_files/nv12mt_example.gif | Bin 0 -> 6858 bytes Documentation/media/uapi/v4l/pixfmt-nv16.rst | 270 + Documentation/media/uapi/v4l/pixfmt-nv16m.rst | 277 + Documentation/media/uapi/v4l/pixfmt-nv24.rst | 171 + Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst | 1469 +++ Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst | 316 + Documentation/media/uapi/v4l/pixfmt-reserved.rst | 360 + Documentation/media/uapi/v4l/pixfmt-rgb.rst | 23 + Documentation/media/uapi/v4l/pixfmt-sbggr16.rst | 113 + Documentation/media/uapi/v4l/pixfmt-sbggr8.rst | 81 + Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst | 43 + Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst | 48 + Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst | 43 + Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst | 47 + Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst | 38 + Documentation/media/uapi/v4l/pixfmt-sgbrg8.rst | 81 + Documentation/media/uapi/v4l/pixfmt-sgrbg8.rst | 81 + Documentation/media/uapi/v4l/pixfmt-srggb10.rst | 120 + .../media/uapi/v4l/pixfmt-srggb10alaw8.rst | 26 + .../media/uapi/v4l/pixfmt-srggb10dpcm8.rst | 28 + Documentation/media/uapi/v4l/pixfmt-srggb10p.rst | 103 + Documentation/media/uapi/v4l/pixfmt-srggb12.rst | 121 + Documentation/media/uapi/v4l/pixfmt-srggb8.rst | 81 + Documentation/media/uapi/v4l/pixfmt-uv8.rst | 76 + Documentation/media/uapi/v4l/pixfmt-uyvy.rst | 197 + Documentation/media/uapi/v4l/pixfmt-vyuy.rst | 195 + Documentation/media/uapi/v4l/pixfmt-y10.rst | 110 + Documentation/media/uapi/v4l/pixfmt-y10b.rst | 45 + Documentation/media/uapi/v4l/pixfmt-y12.rst | 110 + Documentation/media/uapi/v4l/pixfmt-y12i.rst | 44 + Documentation/media/uapi/v4l/pixfmt-y16-be.rst | 111 + Documentation/media/uapi/v4l/pixfmt-y16.rst | 111 + Documentation/media/uapi/v4l/pixfmt-y41p.rst | 274 + Documentation/media/uapi/v4l/pixfmt-y8i.rst | 111 + Documentation/media/uapi/v4l/pixfmt-yuv410.rst | 208 + Documentation/media/uapi/v4l/pixfmt-yuv411p.rst | 214 + Documentation/media/uapi/v4l/pixfmt-yuv420.rst | 239 + Documentation/media/uapi/v4l/pixfmt-yuv420m.rst | 254 + Documentation/media/uapi/v4l/pixfmt-yuv422m.rst | 258 + Documentation/media/uapi/v4l/pixfmt-yuv422p.rst | 240 + Documentation/media/uapi/v4l/pixfmt-yuv444m.rst | 266 + Documentation/media/uapi/v4l/pixfmt-yuyv.rst | 205 + Documentation/media/uapi/v4l/pixfmt-yvyu.rst | 195 + Documentation/media/uapi/v4l/pixfmt-z16.rst | 111 + Documentation/media/uapi/v4l/pixfmt.rst | 35 + Documentation/media/uapi/v4l/planar-apis.rst | 61 + Documentation/media/uapi/v4l/querycap.rst | 34 + Documentation/media/uapi/v4l/rw.rst | 47 + Documentation/media/uapi/v4l/sdr-formats.rst | 19 + Documentation/media/uapi/v4l/selection-api-002.rst | 28 + Documentation/media/uapi/v4l/selection-api-003.rst | 20 + .../uapi/v4l/selection-api-003_files/selection.png | Bin 0 -> 11716 bytes Documentation/media/uapi/v4l/selection-api-004.rst | 137 + Documentation/media/uapi/v4l/selection-api-005.rst | 34 + Documentation/media/uapi/v4l/selection-api-006.rst | 81 + Documentation/media/uapi/v4l/selection-api.rst | 16 + Documentation/media/uapi/v4l/selections-common.rst | 23 + Documentation/media/uapi/v4l/standard.rst | 179 + Documentation/media/uapi/v4l/streaming-par.rst | 33 + Documentation/media/uapi/v4l/subdev-formats.rst | 11688 +++++++++++++++++++ .../media/uapi/v4l/subdev-formats_files/bayer.png | Bin 0 -> 9725 bytes Documentation/media/uapi/v4l/tuner.rst | 82 + Documentation/media/uapi/v4l/user-func.rst | 81 + Documentation/media/uapi/v4l/userp.rst | 117 + .../media/uapi/v4l/v4l2-selection-flags.rst | 71 + .../media/uapi/v4l/v4l2-selection-targets.rst | 135 + Documentation/media/uapi/v4l/v4l2.rst | 395 + Documentation/media/uapi/v4l/v4l2grab-example.rst | 17 + Documentation/media/uapi/v4l/v4l2grab.c.rst | 169 + Documentation/media/uapi/v4l/video.rst | 63 + Documentation/media/uapi/v4l/videodev.rst | 9 + .../media/uapi/v4l/vidioc-create-bufs.rst | 146 + Documentation/media/uapi/v4l/vidioc-cropcap.rst | 167 + .../media/uapi/v4l/vidioc-dbg-g-chip-info.rst | 204 + .../media/uapi/v4l/vidioc-dbg-g-register.rst | 209 + .../media/uapi/v4l/vidioc-decoder-cmd.rst | 271 + Documentation/media/uapi/v4l/vidioc-dqevent.rst | 573 + .../media/uapi/v4l/vidioc-dv-timings-cap.rst | 250 + .../media/uapi/v4l/vidioc-encoder-cmd.rst | 195 + .../media/uapi/v4l/vidioc-enum-dv-timings.rst | 119 + Documentation/media/uapi/v4l/vidioc-enum-fmt.rst | 164 + .../media/uapi/v4l/vidioc-enum-frameintervals.rst | 274 + .../media/uapi/v4l/vidioc-enum-framesizes.rst | 291 + .../media/uapi/v4l/vidioc-enum-freq-bands.rst | 190 + Documentation/media/uapi/v4l/vidioc-enumaudio.rst | 56 + .../media/uapi/v4l/vidioc-enumaudioout.rst | 59 + Documentation/media/uapi/v4l/vidioc-enuminput.rst | 367 + Documentation/media/uapi/v4l/vidioc-enumoutput.rst | 222 + Documentation/media/uapi/v4l/vidioc-enumstd.rst | 442 + Documentation/media/uapi/v4l/vidioc-expbuf.rst | 197 + Documentation/media/uapi/v4l/vidioc-g-audio.rst | 162 + Documentation/media/uapi/v4l/vidioc-g-audioout.rst | 122 + Documentation/media/uapi/v4l/vidioc-g-crop.rst | 113 + Documentation/media/uapi/v4l/vidioc-g-ctrl.rst | 105 + .../media/uapi/v4l/vidioc-g-dv-timings.rst | 417 + Documentation/media/uapi/v4l/vidioc-g-edid.rst | 158 + .../media/uapi/v4l/vidioc-g-enc-index.rst | 210 + .../media/uapi/v4l/vidioc-g-ext-ctrls.rst | 488 + Documentation/media/uapi/v4l/vidioc-g-fbuf.rst | 500 + Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 188 + .../media/uapi/v4l/vidioc-g-frequency.rst | 123 + Documentation/media/uapi/v4l/vidioc-g-input.rst | 62 + Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst | 184 + .../media/uapi/v4l/vidioc-g-modulator.rst | 255 + Documentation/media/uapi/v4l/vidioc-g-output.rst | 64 + Documentation/media/uapi/v4l/vidioc-g-parm.rst | 349 + Documentation/media/uapi/v4l/vidioc-g-priority.rst | 117 + .../media/uapi/v4l/vidioc-g-selection.rst | 209 + .../v4l/vidioc-g-selection_files/constraints.png | Bin 0 -> 3313 bytes .../media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst | 276 + Documentation/media/uapi/v4l/vidioc-g-std.rst | 68 + Documentation/media/uapi/v4l/vidioc-g-tuner.rst | 715 ++ Documentation/media/uapi/v4l/vidioc-log-status.rst | 46 + Documentation/media/uapi/v4l/vidioc-overlay.rst | 55 + .../media/uapi/v4l/vidioc-prepare-buf.rst | 62 + Documentation/media/uapi/v4l/vidioc-qbuf.rst | 150 + .../media/uapi/v4l/vidioc-query-dv-timings.rst | 83 + Documentation/media/uapi/v4l/vidioc-querybuf.rst | 81 + Documentation/media/uapi/v4l/vidioc-querycap.rst | 434 + Documentation/media/uapi/v4l/vidioc-queryctrl.rst | 780 ++ Documentation/media/uapi/v4l/vidioc-querystd.rst | 66 + Documentation/media/uapi/v4l/vidioc-reqbufs.rst | 125 + .../media/uapi/v4l/vidioc-s-hw-freq-seek.rst | 179 + Documentation/media/uapi/v4l/vidioc-streamon.rst | 103 + .../uapi/v4l/vidioc-subdev-enum-frame-interval.rst | 153 + .../uapi/v4l/vidioc-subdev-enum-frame-size.rst | 162 + .../uapi/v4l/vidioc-subdev-enum-mbus-code.rst | 115 + .../media/uapi/v4l/vidioc-subdev-g-crop.rst | 136 + .../media/uapi/v4l/vidioc-subdev-g-fmt.rst | 171 + .../uapi/v4l/vidioc-subdev-g-frame-interval.rst | 122 + .../media/uapi/v4l/vidioc-subdev-g-selection.rst | 144 + .../media/uapi/v4l/vidioc-subscribe-event.rst | 135 + Documentation/media/uapi/v4l/yuv-formats.rst | 55 + 394 files changed, 68278 insertions(+) create mode 100644 Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst create mode 100644 Documentation/media/uapi/dvb/audio-channel-select.rst create mode 100644 Documentation/media/uapi/dvb/audio-clear-buffer.rst create mode 100644 Documentation/media/uapi/dvb/audio-continue.rst create mode 100644 Documentation/media/uapi/dvb/audio-fclose.rst create mode 100644 Documentation/media/uapi/dvb/audio-fopen.rst create mode 100644 Documentation/media/uapi/dvb/audio-fwrite.rst create mode 100644 Documentation/media/uapi/dvb/audio-get-capabilities.rst create mode 100644 Documentation/media/uapi/dvb/audio-get-pts.rst create mode 100644 Documentation/media/uapi/dvb/audio-get-status.rst create mode 100644 Documentation/media/uapi/dvb/audio-pause.rst create mode 100644 Documentation/media/uapi/dvb/audio-play.rst create mode 100644 Documentation/media/uapi/dvb/audio-select-source.rst create mode 100644 Documentation/media/uapi/dvb/audio-set-attributes.rst create mode 100644 Documentation/media/uapi/dvb/audio-set-av-sync.rst create mode 100644 Documentation/media/uapi/dvb/audio-set-bypass-mode.rst create mode 100644 Documentation/media/uapi/dvb/audio-set-ext-id.rst create mode 100644 Documentation/media/uapi/dvb/audio-set-id.rst create mode 100644 Documentation/media/uapi/dvb/audio-set-karaoke.rst create mode 100644 Documentation/media/uapi/dvb/audio-set-mixer.rst create mode 100644 Documentation/media/uapi/dvb/audio-set-mute.rst create mode 100644 Documentation/media/uapi/dvb/audio-set-streamtype.rst create mode 100644 Documentation/media/uapi/dvb/audio-stop.rst create mode 100644 Documentation/media/uapi/dvb/audio.rst create mode 100644 Documentation/media/uapi/dvb/audio_data_types.rst create mode 100644 Documentation/media/uapi/dvb/audio_function_calls.rst create mode 100644 Documentation/media/uapi/dvb/audio_h.rst create mode 100644 Documentation/media/uapi/dvb/ca-fclose.rst create mode 100644 Documentation/media/uapi/dvb/ca-fopen.rst create mode 100644 Documentation/media/uapi/dvb/ca-get-cap.rst create mode 100644 Documentation/media/uapi/dvb/ca-get-descr-info.rst create mode 100644 Documentation/media/uapi/dvb/ca-get-msg.rst create mode 100644 Documentation/media/uapi/dvb/ca-get-slot-info.rst create mode 100644 Documentation/media/uapi/dvb/ca-reset.rst create mode 100644 Documentation/media/uapi/dvb/ca-send-msg.rst create mode 100644 Documentation/media/uapi/dvb/ca-set-descr.rst create mode 100644 Documentation/media/uapi/dvb/ca-set-pid.rst create mode 100644 Documentation/media/uapi/dvb/ca.rst create mode 100644 Documentation/media/uapi/dvb/ca_data_types.rst create mode 100644 Documentation/media/uapi/dvb/ca_function_calls.rst create mode 100644 Documentation/media/uapi/dvb/ca_h.rst create mode 100644 Documentation/media/uapi/dvb/demux.rst create mode 100644 Documentation/media/uapi/dvb/dmx-add-pid.rst create mode 100644 Documentation/media/uapi/dvb/dmx-fclose.rst create mode 100644 Documentation/media/uapi/dvb/dmx-fopen.rst create mode 100644 Documentation/media/uapi/dvb/dmx-fread.rst create mode 100644 Documentation/media/uapi/dvb/dmx-fwrite.rst create mode 100644 Documentation/media/uapi/dvb/dmx-get-caps.rst create mode 100644 Documentation/media/uapi/dvb/dmx-get-event.rst create mode 100644 Documentation/media/uapi/dvb/dmx-get-pes-pids.rst create mode 100644 Documentation/media/uapi/dvb/dmx-get-stc.rst create mode 100644 Documentation/media/uapi/dvb/dmx-remove-pid.rst create mode 100644 Documentation/media/uapi/dvb/dmx-set-buffer-size.rst create mode 100644 Documentation/media/uapi/dvb/dmx-set-filter.rst create mode 100644 Documentation/media/uapi/dvb/dmx-set-pes-filter.rst create mode 100644 Documentation/media/uapi/dvb/dmx-set-source.rst create mode 100644 Documentation/media/uapi/dvb/dmx-start.rst create mode 100644 Documentation/media/uapi/dvb/dmx-stop.rst create mode 100644 Documentation/media/uapi/dvb/dmx_fcalls.rst create mode 100644 Documentation/media/uapi/dvb/dmx_h.rst create mode 100644 Documentation/media/uapi/dvb/dmx_types.rst create mode 100644 Documentation/media/uapi/dvb/dtv-fe-stats.rst create mode 100644 Documentation/media/uapi/dvb/dtv-properties.rst create mode 100644 Documentation/media/uapi/dvb/dtv-property.rst create mode 100644 Documentation/media/uapi/dvb/dtv-stats.rst create mode 100644 Documentation/media/uapi/dvb/dvb-fe-read-status.rst create mode 100644 Documentation/media/uapi/dvb/dvb-frontend-event.rst create mode 100644 Documentation/media/uapi/dvb/dvb-frontend-parameters.rst create mode 100644 Documentation/media/uapi/dvb/dvbapi.rst create mode 100644 Documentation/media/uapi/dvb/dvbproperty-006.rst create mode 100644 Documentation/media/uapi/dvb/dvbproperty.rst create mode 100644 Documentation/media/uapi/dvb/examples.rst create mode 100644 Documentation/media/uapi/dvb/fe-bandwidth-t.rst create mode 100644 Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst create mode 100644 Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst create mode 100644 Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst create mode 100644 Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst create mode 100644 Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst create mode 100644 Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst create mode 100644 Documentation/media/uapi/dvb/fe-get-event.rst create mode 100644 Documentation/media/uapi/dvb/fe-get-frontend.rst create mode 100644 Documentation/media/uapi/dvb/fe-get-info.rst create mode 100644 Documentation/media/uapi/dvb/fe-get-property.rst create mode 100644 Documentation/media/uapi/dvb/fe-read-ber.rst create mode 100644 Documentation/media/uapi/dvb/fe-read-signal-strength.rst create mode 100644 Documentation/media/uapi/dvb/fe-read-snr.rst create mode 100644 Documentation/media/uapi/dvb/fe-read-status.rst create mode 100644 Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst create mode 100644 Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst create mode 100644 Documentation/media/uapi/dvb/fe-set-frontend.rst create mode 100644 Documentation/media/uapi/dvb/fe-set-tone.rst create mode 100644 Documentation/media/uapi/dvb/fe-set-voltage.rst create mode 100644 Documentation/media/uapi/dvb/fe-type-t.rst create mode 100644 Documentation/media/uapi/dvb/fe_property_parameters.rst create mode 100644 Documentation/media/uapi/dvb/frontend-property-cable-systems.rst create mode 100644 Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst create mode 100644 Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst create mode 100644 Documentation/media/uapi/dvb/frontend-stat-properties.rst create mode 100644 Documentation/media/uapi/dvb/frontend.rst create mode 100644 Documentation/media/uapi/dvb/frontend_f_close.rst create mode 100644 Documentation/media/uapi/dvb/frontend_f_open.rst create mode 100644 Documentation/media/uapi/dvb/frontend_fcalls.rst create mode 100644 Documentation/media/uapi/dvb/frontend_h.rst create mode 100644 Documentation/media/uapi/dvb/frontend_legacy_api.rst create mode 100644 Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst create mode 100644 Documentation/media/uapi/dvb/intro.rst create mode 100644 Documentation/media/uapi/dvb/intro_files/dvbstb.pdf create mode 100644 Documentation/media/uapi/dvb/intro_files/dvbstb.png create mode 100644 Documentation/media/uapi/dvb/legacy_dvb_apis.rst create mode 100644 Documentation/media/uapi/dvb/net-add-if.rst create mode 100644 Documentation/media/uapi/dvb/net-get-if.rst create mode 100644 Documentation/media/uapi/dvb/net-remove-if.rst create mode 100644 Documentation/media/uapi/dvb/net.rst create mode 100644 Documentation/media/uapi/dvb/net_h.rst create mode 100644 Documentation/media/uapi/dvb/query-dvb-frontend-info.rst create mode 100644 Documentation/media/uapi/dvb/video-clear-buffer.rst create mode 100644 Documentation/media/uapi/dvb/video-command.rst create mode 100644 Documentation/media/uapi/dvb/video-continue.rst create mode 100644 Documentation/media/uapi/dvb/video-fast-forward.rst create mode 100644 Documentation/media/uapi/dvb/video-fclose.rst create mode 100644 Documentation/media/uapi/dvb/video-fopen.rst create mode 100644 Documentation/media/uapi/dvb/video-freeze.rst create mode 100644 Documentation/media/uapi/dvb/video-fwrite.rst create mode 100644 Documentation/media/uapi/dvb/video-get-capabilities.rst create mode 100644 Documentation/media/uapi/dvb/video-get-event.rst create mode 100644 Documentation/media/uapi/dvb/video-get-frame-count.rst create mode 100644 Documentation/media/uapi/dvb/video-get-frame-rate.rst create mode 100644 Documentation/media/uapi/dvb/video-get-navi.rst create mode 100644 Documentation/media/uapi/dvb/video-get-pts.rst create mode 100644 Documentation/media/uapi/dvb/video-get-size.rst create mode 100644 Documentation/media/uapi/dvb/video-get-status.rst create mode 100644 Documentation/media/uapi/dvb/video-play.rst create mode 100644 Documentation/media/uapi/dvb/video-select-source.rst create mode 100644 Documentation/media/uapi/dvb/video-set-attributes.rst create mode 100644 Documentation/media/uapi/dvb/video-set-blank.rst create mode 100644 Documentation/media/uapi/dvb/video-set-display-format.rst create mode 100644 Documentation/media/uapi/dvb/video-set-format.rst create mode 100644 Documentation/media/uapi/dvb/video-set-highlight.rst create mode 100644 Documentation/media/uapi/dvb/video-set-id.rst create mode 100644 Documentation/media/uapi/dvb/video-set-spu-palette.rst create mode 100644 Documentation/media/uapi/dvb/video-set-spu.rst create mode 100644 Documentation/media/uapi/dvb/video-set-streamtype.rst create mode 100644 Documentation/media/uapi/dvb/video-set-system.rst create mode 100644 Documentation/media/uapi/dvb/video-slowmotion.rst create mode 100644 Documentation/media/uapi/dvb/video-stillpicture.rst create mode 100644 Documentation/media/uapi/dvb/video-stop.rst create mode 100644 Documentation/media/uapi/dvb/video-try-command.rst create mode 100644 Documentation/media/uapi/dvb/video.rst create mode 100644 Documentation/media/uapi/dvb/video_function_calls.rst create mode 100644 Documentation/media/uapi/dvb/video_h.rst create mode 100644 Documentation/media/uapi/dvb/video_types.rst create mode 100644 Documentation/media/uapi/fdl-appendix.rst create mode 100644 Documentation/media/uapi/gen-errors.rst create mode 100644 Documentation/media/uapi/mediactl/media-controller-intro.rst create mode 100644 Documentation/media/uapi/mediactl/media-controller-model.rst create mode 100644 Documentation/media/uapi/mediactl/media-controller.rst create mode 100644 Documentation/media/uapi/mediactl/media-func-close.rst create mode 100644 Documentation/media/uapi/mediactl/media-func-ioctl.rst create mode 100644 Documentation/media/uapi/mediactl/media-func-open.rst create mode 100644 Documentation/media/uapi/mediactl/media-ioc-device-info.rst create mode 100644 Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst create mode 100644 Documentation/media/uapi/mediactl/media-ioc-enum-links.rst create mode 100644 Documentation/media/uapi/mediactl/media-ioc-g-topology.rst create mode 100644 Documentation/media/uapi/mediactl/media-ioc-setup-link.rst create mode 100644 Documentation/media/uapi/mediactl/media-types.rst create mode 100644 Documentation/media/uapi/rc/Remote_controllers_Intro.rst create mode 100644 Documentation/media/uapi/rc/Remote_controllers_table_change.rst create mode 100644 Documentation/media/uapi/rc/Remote_controllers_tables.rst create mode 100644 Documentation/media/uapi/rc/keytable.c.rst create mode 100644 Documentation/media/uapi/rc/lirc_dev_intro.rst create mode 100644 Documentation/media/uapi/rc/lirc_device_interface.rst create mode 100644 Documentation/media/uapi/rc/lirc_ioctl.rst create mode 100644 Documentation/media/uapi/rc/lirc_read.rst create mode 100644 Documentation/media/uapi/rc/lirc_write.rst create mode 100644 Documentation/media/uapi/rc/remote_controllers.rst create mode 100644 Documentation/media/uapi/rc/remote_controllers_sysfs_nodes.rst create mode 100644 Documentation/media/uapi/v4l/app-pri.rst create mode 100644 Documentation/media/uapi/v4l/async.rst create mode 100644 Documentation/media/uapi/v4l/audio.rst create mode 100644 Documentation/media/uapi/v4l/biblio.rst create mode 100644 Documentation/media/uapi/v4l/buffer.rst create mode 100644 Documentation/media/uapi/v4l/capture-example.rst create mode 100644 Documentation/media/uapi/v4l/capture.c.rst create mode 100644 Documentation/media/uapi/v4l/colorspaces.rst create mode 100644 Documentation/media/uapi/v4l/common-defs.rst create mode 100644 Documentation/media/uapi/v4l/common.rst create mode 100644 Documentation/media/uapi/v4l/compat.rst create mode 100644 Documentation/media/uapi/v4l/control.rst create mode 100644 Documentation/media/uapi/v4l/crop.rst create mode 100644 Documentation/media/uapi/v4l/crop_files/crop.gif create mode 100644 Documentation/media/uapi/v4l/crop_files/crop.pdf create mode 100644 Documentation/media/uapi/v4l/depth-formats.rst create mode 100644 Documentation/media/uapi/v4l/dev-capture.rst create mode 100644 Documentation/media/uapi/v4l/dev-codec.rst create mode 100644 Documentation/media/uapi/v4l/dev-effect.rst create mode 100644 Documentation/media/uapi/v4l/dev-event.rst create mode 100644 Documentation/media/uapi/v4l/dev-osd.rst create mode 100644 Documentation/media/uapi/v4l/dev-output.rst create mode 100644 Documentation/media/uapi/v4l/dev-overlay.rst create mode 100644 Documentation/media/uapi/v4l/dev-radio.rst create mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi.rst create mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.gif create mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf create mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.gif create mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf create mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif create mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf create mode 100644 Documentation/media/uapi/v4l/dev-rds.rst create mode 100644 Documentation/media/uapi/v4l/dev-sdr.rst create mode 100644 Documentation/media/uapi/v4l/dev-sliced-vbi.rst create mode 100644 Documentation/media/uapi/v4l/dev-subdev.rst create mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf create mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/pipeline.png create mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf create mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg create mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf create mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg create mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf create mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg create mode 100644 Documentation/media/uapi/v4l/dev-teletext.rst create mode 100644 Documentation/media/uapi/v4l/devices.rst create mode 100644 Documentation/media/uapi/v4l/diff-v4l.rst create mode 100644 Documentation/media/uapi/v4l/dmabuf.rst create mode 100644 Documentation/media/uapi/v4l/driver.rst create mode 100644 Documentation/media/uapi/v4l/dv-timings.rst create mode 100644 Documentation/media/uapi/v4l/extended-controls.rst create mode 100644 Documentation/media/uapi/v4l/field-order.rst create mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.gif create mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf create mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.gif create mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf create mode 100644 Documentation/media/uapi/v4l/format.rst create mode 100644 Documentation/media/uapi/v4l/func-close.rst create mode 100644 Documentation/media/uapi/v4l/func-ioctl.rst create mode 100644 Documentation/media/uapi/v4l/func-mmap.rst create mode 100644 Documentation/media/uapi/v4l/func-munmap.rst create mode 100644 Documentation/media/uapi/v4l/func-open.rst create mode 100644 Documentation/media/uapi/v4l/func-poll.rst create mode 100644 Documentation/media/uapi/v4l/func-read.rst create mode 100644 Documentation/media/uapi/v4l/func-select.rst create mode 100644 Documentation/media/uapi/v4l/func-write.rst create mode 100644 Documentation/media/uapi/v4l/hist-v4l2.rst create mode 100644 Documentation/media/uapi/v4l/io.rst create mode 100644 Documentation/media/uapi/v4l/libv4l-introduction.rst create mode 100644 Documentation/media/uapi/v4l/libv4l.rst create mode 100644 Documentation/media/uapi/v4l/mmap.rst create mode 100644 Documentation/media/uapi/v4l/open.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-002.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-003.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-004.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-006.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-007.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-008.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-013.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-grey.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-indexed.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-m420.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12m.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv16.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv16m.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv24.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-packed-rgb.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-packed-yuv.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-reserved.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-rgb.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-sbggr16.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-sbggr8.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-cs08.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-cs14le.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-cu08.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-cu16le.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-sdr-ru12le.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-sgbrg8.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-sgrbg8.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10alaw8.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10dpcm8.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb10p.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb12.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-srggb8.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-uv8.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-uyvy.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-vyuy.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-y10.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-y10b.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-y12.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-y12i.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-y16-be.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-y16.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-y41p.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-y8i.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv410.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv411p.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv420.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv420m.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv422m.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv422p.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-yuv444m.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-yuyv.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-yvyu.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt-z16.rst create mode 100644 Documentation/media/uapi/v4l/pixfmt.rst create mode 100644 Documentation/media/uapi/v4l/planar-apis.rst create mode 100644 Documentation/media/uapi/v4l/querycap.rst create mode 100644 Documentation/media/uapi/v4l/rw.rst create mode 100644 Documentation/media/uapi/v4l/sdr-formats.rst create mode 100644 Documentation/media/uapi/v4l/selection-api-002.rst create mode 100644 Documentation/media/uapi/v4l/selection-api-003.rst create mode 100644 Documentation/media/uapi/v4l/selection-api-003_files/selection.png create mode 100644 Documentation/media/uapi/v4l/selection-api-004.rst create mode 100644 Documentation/media/uapi/v4l/selection-api-005.rst create mode 100644 Documentation/media/uapi/v4l/selection-api-006.rst create mode 100644 Documentation/media/uapi/v4l/selection-api.rst create mode 100644 Documentation/media/uapi/v4l/selections-common.rst create mode 100644 Documentation/media/uapi/v4l/standard.rst create mode 100644 Documentation/media/uapi/v4l/streaming-par.rst create mode 100644 Documentation/media/uapi/v4l/subdev-formats.rst create mode 100644 Documentation/media/uapi/v4l/subdev-formats_files/bayer.png create mode 100644 Documentation/media/uapi/v4l/tuner.rst create mode 100644 Documentation/media/uapi/v4l/user-func.rst create mode 100644 Documentation/media/uapi/v4l/userp.rst create mode 100644 Documentation/media/uapi/v4l/v4l2-selection-flags.rst create mode 100644 Documentation/media/uapi/v4l/v4l2-selection-targets.rst create mode 100644 Documentation/media/uapi/v4l/v4l2.rst create mode 100644 Documentation/media/uapi/v4l/v4l2grab-example.rst create mode 100644 Documentation/media/uapi/v4l/v4l2grab.c.rst create mode 100644 Documentation/media/uapi/v4l/video.rst create mode 100644 Documentation/media/uapi/v4l/videodev.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-create-bufs.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-cropcap.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-dbg-g-chip-info.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-dbg-g-register.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-decoder-cmd.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-dqevent.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-dv-timings-cap.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-encoder-cmd.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-enum-dv-timings.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-enum-fmt.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-enum-frameintervals.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-enum-framesizes.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-enumaudio.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-enumaudioout.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-enuminput.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-enumoutput.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-enumstd.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-expbuf.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-audio.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-audioout.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-crop.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-ctrl.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-dv-timings.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-edid.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-enc-index.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-ext-ctrls.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-fbuf.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-fmt.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-frequency.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-input.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-jpegcomp.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-modulator.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-output.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-parm.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-priority.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-selection.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.png create mode 100644 Documentation/media/uapi/v4l/vidioc-g-sliced-vbi-cap.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-std.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-g-tuner.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-log-status.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-overlay.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-prepare-buf.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-qbuf.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-query-dv-timings.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-querybuf.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-querycap.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-queryctrl.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-querystd.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-reqbufs.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-s-hw-freq-seek.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-streamon.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-interval.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-enum-frame-size.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-enum-mbus-code.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-g-crop.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-g-fmt.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-g-frame-interval.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-subdev-g-selection.rst create mode 100644 Documentation/media/uapi/v4l/vidioc-subscribe-event.rst create mode 100644 Documentation/media/uapi/v4l/yuv-formats.rst (limited to 'Documentation/media/uapi') diff --git a/Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst b/Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst new file mode 100644 index 000000000000..dbe20ff38e83 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-bilingual-channel-select.rst @@ -0,0 +1,64 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_BILINGUAL_CHANNEL_SELECT: + +============================== +AUDIO_BILINGUAL_CHANNEL_SELECT +============================== + +Name +---- + +AUDIO_BILINGUAL_CHANNEL_SELECT + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_BILINGUAL_CHANNEL_SELECT, audio_channel_select_t) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_BILINGUAL_CHANNEL_SELECT for this command. + + - .. row 3 + + - audio_channel_select_t ch + + - Select the output format of the audio (mono left/right, stereo). + + +Description +----------- + +This ioctl is obsolete. Do not use in new drivers. It has been replaced +by the V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK`` control +for MPEG decoders controlled through V4L2. + +This ioctl call asks the Audio Device to select the requested channel +for bilingual streams if possible. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-channel-select.rst b/Documentation/media/uapi/dvb/audio-channel-select.rst new file mode 100644 index 000000000000..69df4c0f2fb2 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-channel-select.rst @@ -0,0 +1,63 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_CHANNEL_SELECT: + +==================== +AUDIO_CHANNEL_SELECT +==================== + +Name +---- + +AUDIO_CHANNEL_SELECT + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_CHANNEL_SELECT, audio_channel_select_t) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_CHANNEL_SELECT for this command. + + - .. row 3 + + - audio_channel_select_t ch + + - Select the output format of the audio (mono left/right, stereo). + + +Description +----------- + +This ioctl is for DVB devices only. To control a V4L2 decoder use the +V4L2 ``V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK`` control instead. + +This ioctl call asks the Audio Device to select the requested channel if +possible. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-clear-buffer.rst b/Documentation/media/uapi/dvb/audio-clear-buffer.rst new file mode 100644 index 000000000000..a3dec29bdc69 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-clear-buffer.rst @@ -0,0 +1,54 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_CLEAR_BUFFER: + +================== +AUDIO_CLEAR_BUFFER +================== + +Name +---- + +AUDIO_CLEAR_BUFFER + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_CLEAR_BUFFER) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_CLEAR_BUFFER for this command. + + +Description +----------- + +This ioctl call asks the Audio Device to clear all software and hardware +buffers of the audio decoder device. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-continue.rst b/Documentation/media/uapi/dvb/audio-continue.rst new file mode 100644 index 000000000000..053627dd61e7 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-continue.rst @@ -0,0 +1,54 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_CONTINUE: + +============== +AUDIO_CONTINUE +============== + +Name +---- + +AUDIO_CONTINUE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_CONTINUE) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_CONTINUE for this command. + + +Description +----------- + +This ioctl restarts the decoding and playing process previously paused +with AUDIO_PAUSE command. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-fclose.rst b/Documentation/media/uapi/dvb/audio-fclose.rst new file mode 100644 index 000000000000..e5d4225cd9d7 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-fclose.rst @@ -0,0 +1,54 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _audio_fclose: + +================= +DVB audio close() +================= + +Name +---- + +DVB audio close() + + +Synopsis +-------- + +.. cpp:function:: int close(int fd) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + +Description +----------- + +This system call closes a previously opened audio device. + + +Return Value +------------ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``EBADF`` + + - fd is not a valid open file descriptor. diff --git a/Documentation/media/uapi/dvb/audio-fopen.rst b/Documentation/media/uapi/dvb/audio-fopen.rst new file mode 100644 index 000000000000..ec3b23aa79b3 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-fopen.rst @@ -0,0 +1,104 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _audio_fopen: + +================ +DVB audio open() +================ + +Name +---- + +DVB audio open() + + +Synopsis +-------- + +.. cpp:function:: int open(const char *deviceName, int flags) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - const char \*deviceName + + - Name of specific audio device. + + - .. row 2 + + - int flags + + - A bit-wise OR of the following flags: + + - .. row 3 + + - + - O_RDONLY read-only access + + - .. row 4 + + - + - O_RDWR read/write access + + - .. row 5 + + - + - O_NONBLOCK open in non-blocking mode + + - .. row 6 + + - + - (blocking mode is the default) + + +Description +----------- + +This system call opens a named audio device (e.g. +/dev/dvb/adapter0/audio0) for subsequent use. When an open() call has +succeeded, the device will be ready for use. The significance of +blocking or non-blocking mode is described in the documentation for +functions where there is a difference. It does not affect the semantics +of the open() call itself. A device opened in blocking mode can later be +put into non-blocking mode (and vice versa) using the F_SETFL command +of the fcntl system call. This is a standard system call, documented in +the Linux manual page for fcntl. Only one user can open the Audio Device +in O_RDWR mode. All other attempts to open the device in this mode will +fail, and an error code will be returned. If the Audio Device is opened +in O_RDONLY mode, the only ioctl call that can be used is +AUDIO_GET_STATUS. All other call will return with an error code. + + +Return Value +------------ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``ENODEV`` + + - Device driver not loaded/available. + + - .. row 2 + + - ``EBUSY`` + + - Device or resource busy. + + - .. row 3 + + - ``EINVAL`` + + - Invalid argument. diff --git a/Documentation/media/uapi/dvb/audio-fwrite.rst b/Documentation/media/uapi/dvb/audio-fwrite.rst new file mode 100644 index 000000000000..ca95b9be0c2a --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-fwrite.rst @@ -0,0 +1,82 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _audio_fwrite: + +================= +DVB audio write() +================= + +Name +---- + +DVB audio write() + + +Synopsis +-------- + +.. cpp:function:: size_t write(int fd, const void *buf, size_t count) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - void \*buf + + - Pointer to the buffer containing the PES data. + + - .. row 3 + + - size_t count + + - Size of buf. + + +Description +----------- + +This system call can only be used if AUDIO_SOURCE_MEMORY is selected +in the ioctl call AUDIO_SELECT_SOURCE. The data provided shall be in +PES format. If O_NONBLOCK is not specified the function will block +until buffer space is available. The amount of data to be transferred is +implied by count. + + +Return Value +------------ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``EPERM`` + + - Mode AUDIO_SOURCE_MEMORY not selected. + + - .. row 2 + + - ``ENOMEM`` + + - Attempted to write more data than the internal buffer can hold. + + - .. row 3 + + - ``EBADF`` + + - fd is not a valid open file descriptor. diff --git a/Documentation/media/uapi/dvb/audio-get-capabilities.rst b/Documentation/media/uapi/dvb/audio-get-capabilities.rst new file mode 100644 index 000000000000..e274a8d53785 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-get-capabilities.rst @@ -0,0 +1,60 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_GET_CAPABILITIES: + +====================== +AUDIO_GET_CAPABILITIES +====================== + +Name +---- + +AUDIO_GET_CAPABILITIES + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_CAPABILITIES, unsigned int *cap) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_GET_CAPABILITIES for this command. + + - .. row 3 + + - unsigned int \*cap + + - Returns a bit array of supported sound formats. + + +Description +----------- + +This ioctl call asks the Audio Device to tell us about the decoding +capabilities of the audio hardware. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-get-pts.rst b/Documentation/media/uapi/dvb/audio-get-pts.rst new file mode 100644 index 000000000000..5f875508b833 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-get-pts.rst @@ -0,0 +1,69 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_GET_PTS: + +============= +AUDIO_GET_PTS +============= + +Name +---- + +AUDIO_GET_PTS + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_PTS, __u64 *pts) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_GET_PTS for this command. + + - .. row 3 + + - __u64 \*pts + + - Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / + ISO/IEC 13818-1. + + The PTS should belong to the currently played frame if possible, + but may also be a value close to it like the PTS of the last + decoded frame or the last PTS extracted by the PES parser. + + +Description +----------- + +This ioctl is obsolete. Do not use in new drivers. If you need this +functionality, then please contact the linux-media mailing list +(`https://linuxtv.org/lists.php `__). + +This ioctl call asks the Audio Device to return the current PTS +timestamp. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-get-status.rst b/Documentation/media/uapi/dvb/audio-get-status.rst new file mode 100644 index 000000000000..cbd822773d85 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-get-status.rst @@ -0,0 +1,60 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_GET_STATUS: + +================ +AUDIO_GET_STATUS +================ + +Name +---- + +AUDIO_GET_STATUS + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_GET_STATUS, struct audio_status *status) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_GET_STATUS for this command. + + - .. row 3 + + - struct audio_status \*status + + - Returns the current state of Audio Device. + + +Description +----------- + +This ioctl call asks the Audio Device to return the current state of the +Audio Device. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-pause.rst b/Documentation/media/uapi/dvb/audio-pause.rst new file mode 100644 index 000000000000..9ca263e90c6c --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-pause.rst @@ -0,0 +1,55 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_PAUSE: + +=========== +AUDIO_PAUSE +=========== + +Name +---- + +AUDIO_PAUSE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_PAUSE) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_PAUSE for this command. + + +Description +----------- + +This ioctl call suspends the audio stream being played. Decoding and +playing are paused. It is then possible to restart again decoding and +playing process of the audio stream using AUDIO_CONTINUE command. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-play.rst b/Documentation/media/uapi/dvb/audio-play.rst new file mode 100644 index 000000000000..db4d7203acc5 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-play.rst @@ -0,0 +1,54 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_PLAY: + +========== +AUDIO_PLAY +========== + +Name +---- + +AUDIO_PLAY + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_PLAY) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_PLAY for this command. + + +Description +----------- + +This ioctl call asks the Audio Device to start playing an audio stream +from the selected source. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-select-source.rst b/Documentation/media/uapi/dvb/audio-select-source.rst new file mode 100644 index 000000000000..b806d806a46f --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-select-source.rst @@ -0,0 +1,62 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_SELECT_SOURCE: + +=================== +AUDIO_SELECT_SOURCE +=================== + +Name +---- + +AUDIO_SELECT_SOURCE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_SELECT_SOURCE, audio_stream_source_t source) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_SELECT_SOURCE for this command. + + - .. row 3 + + - audio_stream_source_t source + + - Indicates the source that shall be used for the Audio stream. + + +Description +----------- + +This ioctl call informs the audio device which source shall be used for +the input data. The possible sources are demux or memory. If +AUDIO_SOURCE_MEMORY is selected, the data is fed to the Audio Device +through the write command. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-attributes.rst b/Documentation/media/uapi/dvb/audio-set-attributes.rst new file mode 100644 index 000000000000..18667cea2cdf --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-set-attributes.rst @@ -0,0 +1,71 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_SET_ATTRIBUTES: + +==================== +AUDIO_SET_ATTRIBUTES +==================== + +Name +---- + +AUDIO_SET_ATTRIBUTES + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_ATTRIBUTES, audio_attributes_t attr ) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_SET_ATTRIBUTES for this command. + + - .. row 3 + + - audio_attributes_t attr + + - audio attributes according to section ?? + + +Description +----------- + +This ioctl is intended for DVD playback and allows you to set certain +information about the audio stream. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``EINVAL`` + + - attr is not a valid or supported attribute setting. diff --git a/Documentation/media/uapi/dvb/audio-set-av-sync.rst b/Documentation/media/uapi/dvb/audio-set-av-sync.rst new file mode 100644 index 000000000000..6f7e26fa4cd1 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-set-av-sync.rst @@ -0,0 +1,70 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_SET_AV_SYNC: + +================= +AUDIO_SET_AV_SYNC +================= + +Name +---- + +AUDIO_SET_AV_SYNC + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_AV_SYNC, boolean state) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_AV_SYNC for this command. + + - .. row 3 + + - boolean state + + - Tells the DVB subsystem if A/V synchronization shall be ON or OFF. + + - .. row 4 + + - + - TRUE AV-sync ON + + - .. row 5 + + - + - FALSE AV-sync OFF + + +Description +----------- + +This ioctl call asks the Audio Device to turn ON or OFF A/V +synchronization. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst b/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst new file mode 100644 index 000000000000..30bcaca14c3f --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-set-bypass-mode.rst @@ -0,0 +1,74 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_SET_BYPASS_MODE: + +===================== +AUDIO_SET_BYPASS_MODE +===================== + +Name +---- + +AUDIO_SET_BYPASS_MODE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_BYPASS_MODE, boolean mode) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_SET_BYPASS_MODE for this command. + + - .. row 3 + + - boolean mode + + - Enables or disables the decoding of the current Audio stream in + the DVB subsystem. + + - .. row 4 + + - + - TRUE Bypass is disabled + + - .. row 5 + + - + - FALSE Bypass is enabled + + +Description +----------- + +This ioctl call asks the Audio Device to bypass the Audio decoder and +forward the stream without decoding. This mode shall be used if streams +that can’t be handled by the DVB system shall be decoded. Dolby +DigitalTM streams are automatically forwarded by the DVB subsystem if +the hardware can handle it. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-ext-id.rst b/Documentation/media/uapi/dvb/audio-set-ext-id.rst new file mode 100644 index 000000000000..049414db8ef6 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-set-ext-id.rst @@ -0,0 +1,71 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_SET_EXT_ID: + +================ +AUDIO_SET_EXT_ID +================ + +Name +---- + +AUDIO_SET_EXT_ID + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_EXT_ID, int id) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_SET_EXT_ID for this command. + + - .. row 3 + + - int id + + - audio sub_stream_id + + +Description +----------- + +This ioctl can be used to set the extension id for MPEG streams in DVD +playback. Only the first 3 bits are recognized. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``EINVAL`` + + - id is not a valid id. diff --git a/Documentation/media/uapi/dvb/audio-set-id.rst b/Documentation/media/uapi/dvb/audio-set-id.rst new file mode 100644 index 000000000000..a664dc1955cb --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-set-id.rst @@ -0,0 +1,65 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_SET_ID: + +============ +AUDIO_SET_ID +============ + +Name +---- + +AUDIO_SET_ID + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_ID, int id) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_SET_ID for this command. + + - .. row 3 + + - int id + + - audio sub-stream id + + +Description +----------- + +This ioctl selects which sub-stream is to be decoded if a program or +system stream is sent to the video device. If no audio stream type is +set the id has to be in [0xC0,0xDF] for MPEG sound, in [0x80,0x87] for +AC3 and in [0xA0,0xA7] for LPCM. More specifications may follow for +other stream types. If the stream type is set the id just specifies the +substream id of the audio stream and only the first 5 bits are +recognized. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-karaoke.rst b/Documentation/media/uapi/dvb/audio-set-karaoke.rst new file mode 100644 index 000000000000..b55f8380b9cd --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-set-karaoke.rst @@ -0,0 +1,70 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_SET_KARAOKE: + +================= +AUDIO_SET_KARAOKE +================= + +Name +---- + +AUDIO_SET_KARAOKE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_KARAOKE, audio_karaoke_t *karaoke) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_SET_KARAOKE for this command. + + - .. row 3 + + - audio_karaoke_t \*karaoke + + - karaoke settings according to section ??. + + +Description +----------- + +This ioctl allows one to set the mixer settings for a karaoke DVD. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``EINVAL`` + + - karaoke is not a valid or supported karaoke setting. diff --git a/Documentation/media/uapi/dvb/audio-set-mixer.rst b/Documentation/media/uapi/dvb/audio-set-mixer.rst new file mode 100644 index 000000000000..67821729c2b6 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-set-mixer.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_SET_MIXER: + +=============== +AUDIO_SET_MIXER +=============== + +Name +---- + +AUDIO_SET_MIXER + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_MIXER, audio_mixer_t *mix) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_SET_ID for this command. + + - .. row 3 + + - audio_mixer_t \*mix + + - mixer settings. + + +Description +----------- + +This ioctl lets you adjust the mixer settings of the audio decoder. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-mute.rst b/Documentation/media/uapi/dvb/audio-set-mute.rst new file mode 100644 index 000000000000..ebaba95ee278 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-set-mute.rst @@ -0,0 +1,74 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_SET_MUTE: + +============== +AUDIO_SET_MUTE +============== + +Name +---- + +AUDIO_SET_MUTE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_SET_MUTE, boolean state) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_SET_MUTE for this command. + + - .. row 3 + + - boolean state + + - Indicates if audio device shall mute or not. + + - .. row 4 + + - + - TRUE Audio Mute + + - .. row 5 + + - + - FALSE Audio Un-mute + + +Description +----------- + +This ioctl is for DVB devices only. To control a V4L2 decoder use the +V4L2 :ref:`VIDIOC_DECODER_CMD` with the +``V4L2_DEC_CMD_START_MUTE_AUDIO`` flag instead. + +This ioctl call asks the audio device to mute the stream that is +currently being played. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/audio-set-streamtype.rst b/Documentation/media/uapi/dvb/audio-set-streamtype.rst new file mode 100644 index 000000000000..dfb9a6c00d88 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-set-streamtype.rst @@ -0,0 +1,74 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_SET_STREAMTYPE: + +==================== +AUDIO_SET_STREAMTYPE +==================== + +Name +---- + +AUDIO_SET_STREAMTYPE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = AUDIO_SET_STREAMTYPE, int type) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals AUDIO_SET_STREAMTYPE for this command. + + - .. row 3 + + - 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 new file mode 100644 index 000000000000..449127e3f2aa --- /dev/null +++ b/Documentation/media/uapi/dvb/audio-stop.rst @@ -0,0 +1,54 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _AUDIO_STOP: + +========== +AUDIO_STOP +========== + +Name +---- + +AUDIO_STOP + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = AUDIO_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 AUDIO_STOP for this command. + + +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 new file mode 100644 index 000000000000..155622185ea4 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio.rst @@ -0,0 +1,26 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dvb_audio: + +################ +DVB Audio Device +################ +The DVB audio device controls the MPEG2 audio decoder of the DVB +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 DVB 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 new file mode 100644 index 000000000000..4a53127eb13a --- /dev/null +++ b/Documentation/media/uapi/dvb/audio_data_types.rst @@ -0,0 +1,176 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _audio_data_types: + +**************** +Audio Data Types +**************** + +This section describes the structures, data types and defines used when +talking to the audio device. + + +.. _audio-stream-source-t: + +audio_stream_source_t +===================== + +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. + + +.. _audio-play-state-t: + +audio_play_state_t +================== + +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; + + +.. _audio-channel-select-t: + +audio_channel_select_t +====================== + +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; + + +.. _audio-status: + +struct 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; + + +.. _audio-mixer: + +struct 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 + + +.. _audio-karaoke: + +struct audio_karaoke +==================== + +The ioctl AUDIO_SET_KARAOKE uses the following format: + + +.. code-block:: c + + typedef + struct audio_karaoke { + int vocal1; + int vocal2; + int melody; + } audio_karaoke_t; + +If Vocal1 or Vocal2 are non-zero, they get mixed into left and right t +at 70% each. If both, Vocal1 and Vocal2 are non-zero, Vocal1 gets mixed +into the left channel and Vocal2 into the right channel at 100% each. Ff +Melody is non-zero, the melody channel gets mixed into left and right. + + +.. _audio-attributes-t: + +audio attributes +================ + +The following attributes can be set by a call to AUDIO_SET_ATTRIBUTES: + + +.. code-block:: c + + typedef uint16_t audio_attributes_t; + /* bits: descr. */ + /* 15-13 audio coding mode (0=ac3, 2=mpeg1, 3=mpeg2ext, 4=LPCM, 6=DTS, */ + /* 12 multichannel extension */ + /* 11-10 audio type (0=not spec, 1=language included) */ + /* 9- 8 audio application mode (0=not spec, 1=karaoke, 2=surround) */ + /* 7- 6 Quantization / DRC (mpeg audio: 1=DRC exists)(lpcm: 0=16bit, */ + /* 5- 4 Sample frequency fs (0=48kHz, 1=96kHz) */ + /* 2- 0 number of audio channels (n+1 channels) */ diff --git a/Documentation/media/uapi/dvb/audio_function_calls.rst b/Documentation/media/uapi/dvb/audio_function_calls.rst new file mode 100644 index 000000000000..0bb56f0cfed4 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio_function_calls.rst @@ -0,0 +1,34 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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-pts + audio-get-status + audio-get-capabilities + audio-clear-buffer + audio-set-id + audio-set-mixer + audio-set-streamtype + audio-set-ext-id + audio-set-attributes + audio-set-karaoke diff --git a/Documentation/media/uapi/dvb/audio_h.rst b/Documentation/media/uapi/dvb/audio_h.rst new file mode 100644 index 000000000000..e00c3010fdf9 --- /dev/null +++ b/Documentation/media/uapi/dvb/audio_h.rst @@ -0,0 +1,9 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _audio_h: + +********************* +DVB Audio Header File +********************* + +.. kernel-include:: $BUILDDIR/audio.h.rst diff --git a/Documentation/media/uapi/dvb/ca-fclose.rst b/Documentation/media/uapi/dvb/ca-fclose.rst new file mode 100644 index 000000000000..16d7a1e76193 --- /dev/null +++ b/Documentation/media/uapi/dvb/ca-fclose.rst @@ -0,0 +1,54 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _ca_fclose: + +============== +DVB CA close() +============== + +Name +---- + +DVB CA close() + + +Synopsis +-------- + +.. cpp:function:: int close(int fd) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + +Description +----------- + +This system call closes a previously opened audio device. + + +Return Value +------------ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``EBADF`` + + - fd is not a valid open file descriptor. diff --git a/Documentation/media/uapi/dvb/ca-fopen.rst b/Documentation/media/uapi/dvb/ca-fopen.rst new file mode 100644 index 000000000000..f284461cce20 --- /dev/null +++ b/Documentation/media/uapi/dvb/ca-fopen.rst @@ -0,0 +1,109 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _ca_fopen: + +============= +DVB CA open() +============= + +Name +---- + +DVB CA open() + + +Synopsis +-------- + +.. cpp:function:: int open(const char *deviceName, int flags) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - const char \*deviceName + + - Name of specific 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 ca device (e.g. /dev/ost/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 +------------ + +.. 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/ca-get-cap.rst b/Documentation/media/uapi/dvb/ca-get-cap.rst new file mode 100644 index 000000000000..891fbf2d9a84 --- /dev/null +++ b/Documentation/media/uapi/dvb/ca-get-cap.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _CA_GET_CAP: + +========== +CA_GET_CAP +========== + +Name +---- + +CA_GET_CAP + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = CA_GET_CAP, ca_caps_t *) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals CA_GET_CAP for this command. + + - .. row 3 + + - ca_caps_t * + + - Undocumented. + + +Description +----------- + +This ioctl is undocumented. Documentation is welcome. + + +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/ca-get-descr-info.rst b/Documentation/media/uapi/dvb/ca-get-descr-info.rst new file mode 100644 index 000000000000..cf8e8242db66 --- /dev/null +++ b/Documentation/media/uapi/dvb/ca-get-descr-info.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _CA_GET_DESCR_INFO: + +================= +CA_GET_DESCR_INFO +================= + +Name +---- + +CA_GET_DESCR_INFO + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = CA_GET_DESCR_INFO, ca_descr_info_t *) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals CA_GET_DESCR_INFO for this command. + + - .. row 3 + + - ca_descr_info_t \* + + - Undocumented. + + +Description +----------- + +This ioctl is undocumented. Documentation is welcome. + + +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/ca-get-msg.rst b/Documentation/media/uapi/dvb/ca-get-msg.rst new file mode 100644 index 000000000000..56004d5ea3ab --- /dev/null +++ b/Documentation/media/uapi/dvb/ca-get-msg.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _CA_GET_MSG: + +========== +CA_GET_MSG +========== + +Name +---- + +CA_GET_MSG + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = CA_GET_MSG, ca_msg_t *) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals CA_GET_MSG for this command. + + - .. row 3 + + - ca_msg_t \* + + - Undocumented. + + +Description +----------- + +This ioctl is undocumented. Documentation is welcome. + + +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/ca-get-slot-info.rst b/Documentation/media/uapi/dvb/ca-get-slot-info.rst new file mode 100644 index 000000000000..9fea28ccad0f --- /dev/null +++ b/Documentation/media/uapi/dvb/ca-get-slot-info.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _CA_GET_SLOT_INFO: + +================ +CA_GET_SLOT_INFO +================ + +Name +---- + +CA_GET_SLOT_INFO + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = CA_GET_SLOT_INFO, ca_slot_info_t *) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals CA_GET_SLOT_INFO for this command. + + - .. row 3 + + - ca_slot_info_t \* + + - Undocumented. + + +Description +----------- + +This ioctl is undocumented. Documentation is welcome. + + +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/ca-reset.rst b/Documentation/media/uapi/dvb/ca-reset.rst new file mode 100644 index 000000000000..d5a50088fc2d --- /dev/null +++ b/Documentation/media/uapi/dvb/ca-reset.rst @@ -0,0 +1,53 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _CA_RESET: + +======== +CA_RESET +======== + +Name +---- + +CA_RESET + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = CA_RESET) + + +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 CA_RESET for this command. + + +Description +----------- + +This ioctl is undocumented. Documentation is welcome. + + +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/ca-send-msg.rst b/Documentation/media/uapi/dvb/ca-send-msg.rst new file mode 100644 index 000000000000..18974e61e788 --- /dev/null +++ b/Documentation/media/uapi/dvb/ca-send-msg.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _CA_SEND_MSG: + +=========== +CA_SEND_MSG +=========== + +Name +---- + +CA_SEND_MSG + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = CA_SEND_MSG, ca_msg_t *) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals CA_SEND_MSG for this command. + + - .. row 3 + + - ca_msg_t \* + + - Undocumented. + + +Description +----------- + +This ioctl is undocumented. Documentation is welcome. + + +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/ca-set-descr.rst b/Documentation/media/uapi/dvb/ca-set-descr.rst new file mode 100644 index 000000000000..293e6da5059f --- /dev/null +++ b/Documentation/media/uapi/dvb/ca-set-descr.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _CA_SET_DESCR: + +============ +CA_SET_DESCR +============ + +Name +---- + +CA_SET_DESCR + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = CA_SET_DESCR, ca_descr_t *) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals CA_SET_DESCR for this command. + + - .. row 3 + + - ca_descr_t \* + + - Undocumented. + + +Description +----------- + +This ioctl is undocumented. Documentation is welcome. + + +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/ca-set-pid.rst b/Documentation/media/uapi/dvb/ca-set-pid.rst new file mode 100644 index 000000000000..5afa2fae3206 --- /dev/null +++ b/Documentation/media/uapi/dvb/ca-set-pid.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _CA_SET_PID: + +========== +CA_SET_PID +========== + +Name +---- + +CA_SET_PID + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = CA_SET_PID, ca_pid_t *) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals CA_SET_PID for this command. + + - .. row 3 + + - ca_pid_t \* + + - Undocumented. + + +Description +----------- + +This ioctl is undocumented. Documentation is welcome. + + +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/ca.rst b/Documentation/media/uapi/dvb/ca.rst new file mode 100644 index 000000000000..14b14abda1ae --- /dev/null +++ b/Documentation/media/uapi/dvb/ca.rst @@ -0,0 +1,18 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dvb_ca: + +############# +DVB CA Device +############# +The DVB 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. + + +.. toctree:: + :maxdepth: 1 + + ca_data_types + ca_function_calls diff --git a/Documentation/media/uapi/dvb/ca_data_types.rst b/Documentation/media/uapi/dvb/ca_data_types.rst new file mode 100644 index 000000000000..025f910ae945 --- /dev/null +++ b/Documentation/media/uapi/dvb/ca_data_types.rst @@ -0,0 +1,110 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _ca_data_types: + +************* +CA Data Types +************* + + +.. _ca-slot-info: + +ca_slot_info_t +============== + + +.. 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; + + +.. _ca-descr-info: + +ca_descr_info_t +=============== + + +.. code-block:: c + + typedef struct ca_descr_info { + unsigned int num; /* number of available descramblers (keys) */ + unsigned int type; /* type of supported scrambling system */ + #define CA_ECD 1 + #define CA_NDS 2 + #define CA_DSS 4 + } ca_descr_info_t; + + +.. _ca-caps: + +ca_caps_t +========= + + +.. code-block:: c + + typedef struct ca_caps { + unsigned int slot_num; /* total number of CA card and module slots */ + unsigned int slot_type; /* OR of all supported types */ + unsigned int descr_num; /* total number of descrambler slots (keys) */ + unsigned int descr_type;/* OR of all supported types */ + } ca_cap_t; + + +.. _ca-msg: + +ca_msg_t +======== + + +.. 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; + + +.. _ca-descr: + +ca_descr_t +========== + + +.. code-block:: c + + typedef struct ca_descr { + unsigned int index; + unsigned int parity; + unsigned char cw[8]; + } ca_descr_t; + + +.. _ca-pid: + +ca-pid +====== + + +.. code-block:: c + + typedef struct ca_pid { + unsigned int pid; + int index; /* -1 == disable*/ + } ca_pid_t; diff --git a/Documentation/media/uapi/dvb/ca_function_calls.rst b/Documentation/media/uapi/dvb/ca_function_calls.rst new file mode 100644 index 000000000000..c085a0ebbc05 --- /dev/null +++ b/Documentation/media/uapi/dvb/ca_function_calls.rst @@ -0,0 +1,21 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 + ca-set-pid diff --git a/Documentation/media/uapi/dvb/ca_h.rst b/Documentation/media/uapi/dvb/ca_h.rst new file mode 100644 index 000000000000..f513592ef529 --- /dev/null +++ b/Documentation/media/uapi/dvb/ca_h.rst @@ -0,0 +1,9 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _ca_h: + +********************************** +DVB Conditional Access Header File +********************************** + +.. kernel-include:: $BUILDDIR/ca.h.rst diff --git a/Documentation/media/uapi/dvb/demux.rst b/Documentation/media/uapi/dvb/demux.rst new file mode 100644 index 000000000000..b12b5a2dac94 --- /dev/null +++ b/Documentation/media/uapi/dvb/demux.rst @@ -0,0 +1,18 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dvb_demux: + +################ +DVB Demux Device +################ +The DVB demux device controls the filters of the DVB hardware/software. +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 new file mode 100644 index 000000000000..6343035653ac --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-add-pid.rst @@ -0,0 +1,61 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _DMX_ADD_PID: + +=========== +DMX_ADD_PID +=========== + +Name +---- + +DMX_ADD_PID + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = DMX_ADD_PID, __u16 *) + + +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 DMX_ADD_PID for this command. + + - .. row 3 + + - __u16 * + + - PID number to be filtered. + + +Description +----------- + +This ioctl call allows to add multiple PIDs to a transport stream filter +previously set up with DMX_SET_PES_FILTER and output equal to +DMX_OUT_TSDEMUX_TAP. + + +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/dmx-fclose.rst b/Documentation/media/uapi/dvb/dmx-fclose.rst new file mode 100644 index 000000000000..f54c2a1220c1 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-fclose.rst @@ -0,0 +1,55 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dmx_fclose: + +================= +DVB demux close() +================= + +Name +---- + +DVB demux close() + + +Synopsis +-------- + +.. cpp:function:: int close(int fd) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + +Description +----------- + +This system call deactivates and deallocates a filter that was +previously allocated via the open() call. + + +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/dmx-fopen.rst b/Documentation/media/uapi/dvb/dmx-fopen.rst new file mode 100644 index 000000000000..76dbb42713ad --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-fopen.rst @@ -0,0 +1,108 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dmx_fopen: + +================ +DVB demux open() +================ + +Name +---- + +DVB demux open() + + +Synopsis +-------- + +.. cpp:function:: int open(const char *deviceName, int flags) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - const char \*deviceName + + - Name of demux device. + + - .. row 2 + + - int flags + + - A bit-wise OR of the following flags: + + - .. row 3 + + - + - O_RDWR read/write access + + - .. row 4 + + - + - O_NONBLOCK open in non-blocking mode + + - .. row 5 + + - + - (blocking mode is the default) + + +Description +----------- + +This system call, used with a device name of /dev/dvb/adapter0/demux0, +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/adapter0/dvr0 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/adapter0/demux0) 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 +------------ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``ENODEV`` + + - Device driver not loaded/available. + + - .. row 2 + + - ``EINVAL`` + + - Invalid argument. + + - .. row 3 + + - ``EMFILE`` + + - “Too many open files”, i.e. no more filters available. + + - .. row 4 + + - ``ENOMEM`` + + - The driver failed to allocate enough memory. diff --git a/Documentation/media/uapi/dvb/dmx-fread.rst b/Documentation/media/uapi/dvb/dmx-fread.rst new file mode 100644 index 000000000000..d25b19e4f696 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-fread.rst @@ -0,0 +1,108 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dmx_fread: + +================ +DVB demux read() +================ + +Name +---- + +DVB demux read() + + +Synopsis +-------- + +.. cpp:function:: size_t read(int fd, 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 to be used for returned filtered data. + + - .. row 3 + + - size_t count + + - Size of buf. + + +Description +----------- + +This system call returns filtered data, which might be section or 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. + + +Return Value +------------ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``EWOULDBLOCK`` + + - No data to return and O_NONBLOCK was specified. + + - .. row 2 + + - ``EBADF`` + + - fd is not a valid open file descriptor. + + - .. row 3 + + - ``ECRC`` + + - Last section had a CRC error - no data returned. The buffer is + flushed. + + - .. row 4 + + - ``EOVERFLOW`` + + - + + - .. row 5 + + - + - The filtered data was not read from the buffer in due time, + resulting in non-read data being lost. The buffer is flushed. + + - .. row 6 + + - ``ETIMEDOUT`` + + - The section was not loaded within the stated timeout period. See + ioctl DMX_SET_FILTER for how to set a timeout. + + - .. row 7 + + - ``EFAULT`` + + - The driver failed to write to the callers buffer due to an invalid + \*buf pointer. diff --git a/Documentation/media/uapi/dvb/dmx-fwrite.rst b/Documentation/media/uapi/dvb/dmx-fwrite.rst new file mode 100644 index 000000000000..9efd81a1b5c8 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-fwrite.rst @@ -0,0 +1,89 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dmx_fwrite: + +================= +DVB demux write() +================= + +Name +---- + +DVB demux write() + + +Synopsis +-------- + +.. cpp:function:: ssize_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 Transport Stream. + + - .. row 3 + + - size_t count + + - Size of buf. + + +Description +----------- + +This system call is only provided by the logical device +/dev/dvb/adapter0/dvr0, 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/adapter0/demux0. +The amount of data to be transferred is implied by count. + + +Return Value +------------ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``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). + + - .. row 2 + + - ``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. + + - .. row 3 + + - ``EBADF`` + + - fd is not a valid open file descriptor. diff --git a/Documentation/media/uapi/dvb/dmx-get-caps.rst b/Documentation/media/uapi/dvb/dmx-get-caps.rst new file mode 100644 index 000000000000..d0549eb7fbd3 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-get-caps.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _DMX_GET_CAPS: + +============ +DMX_GET_CAPS +============ + +Name +---- + +DMX_GET_CAPS + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = DMX_GET_CAPS, dmx_caps_t *) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals DMX_GET_CAPS for this command. + + - .. row 3 + + - dmx_caps_t * + + - Undocumented. + + +Description +----------- + +This ioctl is undocumented. Documentation is welcome. + + +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/dmx-get-event.rst b/Documentation/media/uapi/dvb/dmx-get-event.rst new file mode 100644 index 000000000000..6a7550c63bb5 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-get-event.rst @@ -0,0 +1,76 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _DMX_GET_EVENT: + +============= +DMX_GET_EVENT +============= + +Name +---- + +DMX_GET_EVENT + + +Synopsis +-------- + +.. cpp:function:: int ioctl( int fd, int request = DMX_GET_EVENT, struct dmx_event *ev) + + +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 DMX_GET_EVENT for this command. + + - .. row 3 + + - struct dmx_event \*ev + + - Pointer to the location where the event is to be stored. + + +Description +----------- + +This ioctl call returns an 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 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. diff --git a/Documentation/media/uapi/dvb/dmx-get-pes-pids.rst b/Documentation/media/uapi/dvb/dmx-get-pes-pids.rst new file mode 100644 index 000000000000..ba5d30c913c8 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-get-pes-pids.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _DMX_GET_PES_PIDS: + +================ +DMX_GET_PES_PIDS +================ + +Name +---- + +DMX_GET_PES_PIDS + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = DMX_GET_PES_PIDS, __u16[5]) + + +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 DMX_GET_PES_PIDS for this command. + + - .. row 3 + + - __u16[5] + + - Undocumented. + + +Description +----------- + +This ioctl is undocumented. Documentation is welcome. + + +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/dmx-get-stc.rst b/Documentation/media/uapi/dvb/dmx-get-stc.rst new file mode 100644 index 000000000000..bd477bb67082 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-get-stc.rst @@ -0,0 +1,77 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _DMX_GET_STC: + +=========== +DMX_GET_STC +=========== + +Name +---- + +DMX_GET_STC + + +Synopsis +-------- + +.. cpp:function:: int ioctl( int fd, int request = DMX_GET_STC, struct dmx_stc *stc) + + +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 DMX_GET_STC for this command. + + - .. row 3 + + - struct dmx_stc \*stc + + - Pointer to the location where the stc 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 DMX_PES_PCR). Some hardware +supports more than one STC, so you must specify which one by setting the +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 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`` + + - Invalid stc number. diff --git a/Documentation/media/uapi/dvb/dmx-remove-pid.rst b/Documentation/media/uapi/dvb/dmx-remove-pid.rst new file mode 100644 index 000000000000..c8f038b40074 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-remove-pid.rst @@ -0,0 +1,62 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _DMX_REMOVE_PID: + +============== +DMX_REMOVE_PID +============== + +Name +---- + +DMX_REMOVE_PID + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = DMX_REMOVE_PID, __u16 *) + + +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 DMX_REMOVE_PID for this command. + + - .. row 3 + + - __u16 * + + - 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 DMX_OUT_TSDEMUX_TAP, created via either +DMX_SET_PES_FILTER or DMX_ADD_PID. + + +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/dmx-set-buffer-size.rst b/Documentation/media/uapi/dvb/dmx-set-buffer-size.rst new file mode 100644 index 000000000000..8ae48cf39cda --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-set-buffer-size.rst @@ -0,0 +1,62 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _DMX_SET_BUFFER_SIZE: + +=================== +DMX_SET_BUFFER_SIZE +=================== + +Name +---- + +DMX_SET_BUFFER_SIZE + + +Synopsis +-------- + +.. cpp:function:: int ioctl( int fd, int request = DMX_SET_BUFFER_SIZE, unsigned long 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 DMX_SET_BUFFER_SIZE for this command. + + - .. row 3 + + - unsigned long size + + - Size of circular buffer. + + +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 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 new file mode 100644 index 000000000000..8c929fa9b98c --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-set-filter.rst @@ -0,0 +1,68 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _DMX_SET_FILTER: + +============== +DMX_SET_FILTER +============== + +Name +---- + +DMX_SET_FILTER + + +Synopsis +-------- + +.. cpp:function:: int ioctl( int fd, int request = DMX_SET_FILTER, struct dmx_sct_filter_params *params) + + +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 DMX_SET_FILTER for this command. + + - .. row 3 + + - struct dmx_sct_filter_params \*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 +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 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 new file mode 100644 index 000000000000..addc321011ce --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-set-pes-filter.rst @@ -0,0 +1,78 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _DMX_SET_PES_FILTER: + +================== +DMX_SET_PES_FILTER +================== + +Name +---- + +DMX_SET_PES_FILTER + + +Synopsis +-------- + +.. cpp:function:: int ioctl( int fd, int request = DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params) + + +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 DMX_SET_PES_FILTER for this command. + + - .. row 3 + + - struct dmx_pes_filter_params \*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 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 + + - ``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. diff --git a/Documentation/media/uapi/dvb/dmx-set-source.rst b/Documentation/media/uapi/dvb/dmx-set-source.rst new file mode 100644 index 000000000000..99a8d5c82756 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-set-source.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _DMX_SET_SOURCE: + +============== +DMX_SET_SOURCE +============== + +Name +---- + +DMX_SET_SOURCE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = DMX_SET_SOURCE, dmx_source_t *) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals DMX_SET_SOURCE for this command. + + - .. row 3 + + - dmx_source_t * + + - Undocumented. + + +Description +----------- + +This ioctl is undocumented. Documentation is welcome. + + +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/dmx-start.rst b/Documentation/media/uapi/dvb/dmx-start.rst new file mode 100644 index 000000000000..9835d1e78400 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-start.rst @@ -0,0 +1,77 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _DMX_START: + +========= +DMX_START +========= + +Name +---- + +DMX_START + + +Synopsis +-------- + +.. cpp:function:: int ioctl( int fd, int request = DMX_START) + + +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 DMX_START for this command. + + +Description +----------- + +This ioctl call is used to start the actual filtering operation defined +via the ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER. + + +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`` + + - Invalid argument, i.e. no filtering parameters provided via the + DMX_SET_FILTER or DMX_SET_PES_FILTER functions. + + - .. 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. diff --git a/Documentation/media/uapi/dvb/dmx-stop.rst b/Documentation/media/uapi/dvb/dmx-stop.rst new file mode 100644 index 000000000000..7e4bf09fc83e --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx-stop.rst @@ -0,0 +1,55 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _DMX_STOP: + +======== +DMX_STOP +======== + +Name +---- + +DMX_STOP + + +Synopsis +-------- + +.. cpp:function:: int ioctl( int fd, int request = DMX_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 DMX_STOP for this command. + + +Description +----------- + +This ioctl call is used to stop the actual filtering operation defined +via the ioctl calls DMX_SET_FILTER or DMX_SET_PES_FILTER and +started via the DMX_START 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/dmx_fcalls.rst b/Documentation/media/uapi/dvb/dmx_fcalls.rst new file mode 100644 index 000000000000..77a1554d9834 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx_fcalls.rst @@ -0,0 +1,27 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dmx_fcalls: + +******************** +Demux Function Calls +******************** + +.. toctree:: + :maxdepth: 1 + + dmx-fopen + dmx-fclose + dmx-fread + dmx-fwrite + dmx-start + dmx-stop + dmx-set-filter + dmx-set-pes-filter + dmx-set-buffer-size + dmx-get-event + dmx-get-stc + dmx-get-pes-pids + dmx-get-caps + dmx-set-source + dmx-add-pid + dmx-remove-pid diff --git a/Documentation/media/uapi/dvb/dmx_h.rst b/Documentation/media/uapi/dvb/dmx_h.rst new file mode 100644 index 000000000000..4fd1704a0833 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx_h.rst @@ -0,0 +1,9 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dmx_h: + +********************* +DVB Demux Header File +********************* + +.. kernel-include:: $BUILDDIR/dmx.h.rst diff --git a/Documentation/media/uapi/dvb/dmx_types.rst b/Documentation/media/uapi/dvb/dmx_types.rst new file mode 100644 index 000000000000..7a8900af2680 --- /dev/null +++ b/Documentation/media/uapi/dvb/dmx_types.rst @@ -0,0 +1,242 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dmx_types: + +**************** +Demux Data Types +**************** + + +.. _dmx-output-t: + +Output for the demux +==================== + + +.. _dmx-output: + +.. flat-table:: enum dmx_output + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _DMX-OUT-DECODER: + + DMX_OUT_DECODER + + - Streaming directly to decoder. + + - .. row 3 + + - .. _DMX-OUT-TAP: + + DMX_OUT_TAP + + - Output going to a memory buffer (to be retrieved via the read + command). Delivers the stream output to the demux device on which + the ioctl is called. + + - .. row 4 + + - .. _DMX-OUT-TS-TAP: + + DMX_OUT_TS_TAP + + - Output multiplexed into a new TS (to be retrieved by reading from + the logical DVR device). Routes output to the logical DVR device + ``/dev/dvb/adapter?/dvr?``, which delivers a TS multiplexed from + all filters for which ``DMX_OUT_TS_TAP`` was specified. + + - .. row 5 + + - .. _DMX-OUT-TSDEMUX-TAP: + + DMX_OUT_TSDEMUX_TAP + + - Like :ref:`DMX_OUT_TS_TAP ` but retrieved + from the DMX device. + + + +.. _dmx-input-t: + +dmx_input_t +=========== + + +.. code-block:: c + + typedef enum + { + DMX_IN_FRONTEND, /* Input from a front-end device. */ + DMX_IN_DVR /* Input from the logical DVR device. */ + } dmx_input_t; + + +.. _dmx-pes-type-t: + +dmx_pes_type_t +============== + + +.. code-block:: c + + typedef enum + { + DMX_PES_AUDIO0, + DMX_PES_VIDEO0, + DMX_PES_TELETEXT0, + DMX_PES_SUBTITLE0, + DMX_PES_PCR0, + + DMX_PES_AUDIO1, + DMX_PES_VIDEO1, + DMX_PES_TELETEXT1, + DMX_PES_SUBTITLE1, + DMX_PES_PCR1, + + DMX_PES_AUDIO2, + DMX_PES_VIDEO2, + DMX_PES_TELETEXT2, + DMX_PES_SUBTITLE2, + DMX_PES_PCR2, + + DMX_PES_AUDIO3, + DMX_PES_VIDEO3, + DMX_PES_TELETEXT3, + DMX_PES_SUBTITLE3, + DMX_PES_PCR3, + + DMX_PES_OTHER + } dmx_pes_type_t; + + +.. _dmx-filter: + +struct dmx_filter +================= + + +.. code-block:: c + + typedef struct dmx_filter + { + __u8 filter[DMX_FILTER_SIZE]; + __u8 mask[DMX_FILTER_SIZE]; + __u8 mode[DMX_FILTER_SIZE]; + } dmx_filter_t; + + +.. _dmx-sct-filter-params: + +struct dmx_sct_filter_params +============================ + + +.. code-block:: c + + struct dmx_sct_filter_params + { + __u16 pid; + dmx_filter_t filter; + __u32 timeout; + __u32 flags; + #define DMX_CHECK_CRC 1 + #define DMX_ONESHOT 2 + #define DMX_IMMEDIATE_START 4 + #define DMX_KERNEL_CLIENT 0x8000 + }; + + +.. _dmx-pes-filter-params: + +struct dmx_pes_filter_params +============================ + + +.. code-block:: c + + struct dmx_pes_filter_params + { + __u16 pid; + dmx_input_t input; + dmx_output_t output; + dmx_pes_type_t pes_type; + __u32 flags; + }; + + +.. _dmx-event: + +struct dmx_event +================ + + +.. code-block:: c + + struct dmx_event + { + dmx_event_t event; + time_t timeStamp; + union + { + dmx_scrambling_status_t scrambling; + } u; + }; + + +.. _dmx-stc: + +struct dmx_stc +============== + + +.. code-block:: c + + struct dmx_stc { + unsigned int num; /* input : which STC? 0..N */ + unsigned int base; /* output: divisor for stc to get 90 kHz clock */ + __u64 stc; /* output: stc in 'base'*90 kHz units */ + }; + + +.. _dmx-caps: + +struct dmx_caps +=============== + + +.. code-block:: c + + typedef struct dmx_caps { + __u32 caps; + int num_decoders; + } dmx_caps_t; + + +.. _dmx-source-t: + +enum dmx_source_t +================= + + +.. code-block:: c + + typedef enum { + DMX_SOURCE_FRONT0 = 0, + DMX_SOURCE_FRONT1, + DMX_SOURCE_FRONT2, + DMX_SOURCE_FRONT3, + DMX_SOURCE_DVR0 = 16, + DMX_SOURCE_DVR1, + DMX_SOURCE_DVR2, + DMX_SOURCE_DVR3 + } dmx_source_t; diff --git a/Documentation/media/uapi/dvb/dtv-fe-stats.rst b/Documentation/media/uapi/dvb/dtv-fe-stats.rst new file mode 100644 index 000000000000..7c105e2ab27e --- /dev/null +++ b/Documentation/media/uapi/dvb/dtv-fe-stats.rst @@ -0,0 +1,17 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dtv-fe-stats: + +******************* +struct dtv_fe_stats +******************* + + +.. code-block:: c + + #define MAX_DTV_STATS 4 + + struct dtv_fe_stats { + __u8 len; + struct dtv_stats stat[MAX_DTV_STATS]; + } __packed; diff --git a/Documentation/media/uapi/dvb/dtv-properties.rst b/Documentation/media/uapi/dvb/dtv-properties.rst new file mode 100644 index 000000000000..c13be5de4302 --- /dev/null +++ b/Documentation/media/uapi/dvb/dtv-properties.rst @@ -0,0 +1,15 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dtv-properties: + +********************* +struct dtv_properties +********************* + + +.. code-block:: c + + struct dtv_properties { + __u32 num; + struct dtv_property *props; + }; diff --git a/Documentation/media/uapi/dvb/dtv-property.rst b/Documentation/media/uapi/dvb/dtv-property.rst new file mode 100644 index 000000000000..5073a49def2a --- /dev/null +++ b/Documentation/media/uapi/dvb/dtv-property.rst @@ -0,0 +1,31 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dtv-property: + +******************* +struct dtv_property +******************* + + +.. code-block:: c + + /* Reserved fields should be set to 0 */ + + struct dtv_property { + __u32 cmd; + __u32 reserved[3]; + union { + __u32 data; + struct dtv_fe_stats st; + struct { + __u8 data[32]; + __u32 len; + __u32 reserved1[3]; + void *reserved2; + } buffer; + } u; + int result; + } __attribute__ ((packed)); + + /* num of properties cannot exceed DTV_IOCTL_MAX_MSGS per ioctl */ + #define DTV_IOCTL_MAX_MSGS 64 diff --git a/Documentation/media/uapi/dvb/dtv-stats.rst b/Documentation/media/uapi/dvb/dtv-stats.rst new file mode 100644 index 000000000000..2cfdca00f164 --- /dev/null +++ b/Documentation/media/uapi/dvb/dtv-stats.rst @@ -0,0 +1,18 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dtv-stats: + +**************** +struct dtv_stats +**************** + + +.. code-block:: c + + struct dtv_stats { + __u8 scale; /* enum fecap_scale_params type */ + union { + __u64 uvalue; /* for counters and relative scales */ + __s64 svalue; /* for 1/1000 dB measures */ + }; + } __packed; diff --git a/Documentation/media/uapi/dvb/dvb-fe-read-status.rst b/Documentation/media/uapi/dvb/dvb-fe-read-status.rst new file mode 100644 index 000000000000..1c708c5e6bc0 --- /dev/null +++ b/Documentation/media/uapi/dvb/dvb-fe-read-status.rst @@ -0,0 +1,22 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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`. Please note that several +statistics require the demodulator to be fully locked (e. g. with +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 new file mode 100644 index 000000000000..78e72feaa178 --- /dev/null +++ b/Documentation/media/uapi/dvb/dvb-frontend-event.rst @@ -0,0 +1,15 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 new file mode 100644 index 000000000000..16cb581d5cff --- /dev/null +++ b/Documentation/media/uapi/dvb/dvb-frontend-parameters.rst @@ -0,0 +1,119 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 an 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 an union in the +FrontendParameters 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. + + +.. _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) */ + }; + + +.. _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) */ + }; + + +.. _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) */ + }; + + +.. _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 new file mode 100644 index 000000000000..60fb3d46b1d6 --- /dev/null +++ b/Documentation/media/uapi/dvb/dvbapi.rst @@ -0,0 +1,98 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. include:: + +.. _dvbapi: + +############## +Digital TV API +############## + +**NOTE:** This API is also known as **DVB API**, although it is generic +enough to support all digital TV standards. + +**Version 5.10** + +.. toctree:: + :maxdepth: 1 + :numbered: + + intro + frontend + demux + ca + net + legacy_dvb_apis + examples + audio_h + ca_h + dmx_h + frontend_h + net_h + video_h + + +********************** +Revision and Copyright +********************** + +Authors: + +- J. K. Metzler, Ralph + + - Original author of the DVB API documentation. + +- O. C. Metzler, Marcus + + - Original author of the DVB 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-2016 : Mauro Carvalho Chehab + +**************** +Revision History +**************** + +: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 +DVB API. + +:revision: 2.0.4 / 2011-05-06 (*mcc*) + +Add more information about DVB APIv5, 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-006.rst b/Documentation/media/uapi/dvb/dvbproperty-006.rst new file mode 100644 index 000000000000..3343a0f306fe --- /dev/null +++ b/Documentation/media/uapi/dvb/dvbproperty-006.rst @@ -0,0 +1,12 @@ +.. -*- coding: utf-8; mode: rst -*- + +************** +Property types +************** + +On :ref:`FE_GET_PROPERTY and FE_SET_PROPERTY `, +the actual action is determined by the dtv_property cmd/data pairs. +With one single ioctl, is possible to get/set up to 64 properties. The +actual meaning of each property is described on the next sections. + +The available frontend property types are shown on the next section. diff --git a/Documentation/media/uapi/dvb/dvbproperty.rst b/Documentation/media/uapi/dvb/dvbproperty.rst new file mode 100644 index 000000000000..9b3782c5bb44 --- /dev/null +++ b/Documentation/media/uapi/dvb/dvbproperty.rst @@ -0,0 +1,111 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _frontend-properties: + +DVB Frontend properties +======================= + +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, 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, +those structs were not big enough to contain the additional parameters. +Also, the union didn't have any space left to be expanded without +breaking userspace. So, the decision was to deprecate the legacy +union/struct based approach, in favor of a properties set approach. + +NOTE: on Linux DVB API version 3, setting a frontend were done via +:ref:`struct dvb_frontend_parameters `. +This got replaced on version 5 (also called "S2API", as this API were +added originally_enabled to provide support for DVB-S2), because the +old API has a very limited support to new standards and new hardware. +This section describes the new and recommended way to set the frontend, +with suppports all digital TV delivery systems. + +Example: with the properties based approach, in order to set the tuner +to 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 do the above is: + + +.. code-block:: c + + #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; + } + +NOTE: 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 + + dtv-stats + dtv-fe-stats + dtv-property + dtv-properties + dvbproperty-006 + fe_property_parameters + frontend-stat-properties + frontend-property-terrestrial-systems + frontend-property-cable-systems + frontend-property-satellite-systems diff --git a/Documentation/media/uapi/dvb/examples.rst b/Documentation/media/uapi/dvb/examples.rst new file mode 100644 index 000000000000..64e029ecd047 --- /dev/null +++ b/Documentation/media/uapi/dvb/examples.rst @@ -0,0 +1,380 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dvb_examples: + +******** +Examples +******** + +In this section we would like to present some examples for using the DVB +API. + +NOTE: This section is out of date, and the code below won't even +compile. Please refer to the +`libdvbv5 `__ for +updated/recommended examples. + + +.. _tuning: + +Tuning +====== + +We will start with a generic tuning subroutine that uses the frontend +and SEC, as well as the demux devices. The example is given for QPSK +tuners, but can easily be adjusted for QAM. + + +.. code-block:: c + + #include + #include + #include + #include + #include + #include + #include + #include + + #include + #include + #include + #include + + #define DMX "/dev/dvb/adapter0/demux1" + #define FRONT "/dev/dvb/adapter0/frontend1" + #define SEC "/dev/dvb/adapter0/sec1" + + /* routine for checking if we have a signal and other status information*/ + int FEReadStatus(int fd, fe_status_t *stat) + { + int ans; + + if ( (ans = ioctl(fd,FE_READ_STATUS,stat) < 0)){ + perror("FE READ STATUS: "); + return -1; + } + + if (*stat & FE_HAS_POWER) + printf("FE HAS POWER\\n"); + + if (*stat & FE_HAS_SIGNAL) + printf("FE HAS SIGNAL\\n"); + + if (*stat & FE_SPECTRUM_INV) + printf("SPEKTRUM INV\\n"); + + return 0; + } + + + /* tune qpsk */ + /* freq: frequency of transponder */ + /* vpid, apid, tpid: PIDs of video, audio and teletext TS packets */ + /* diseqc: DiSEqC address of the used LNB */ + /* pol: Polarisation */ + /* srate: Symbol Rate */ + /* fec. FEC */ + /* lnb_lof1: local frequency of lower LNB band */ + /* lnb_lof2: local frequency of upper LNB band */ + /* lnb_slof: switch frequency of LNB */ + + int set_qpsk_channel(int freq, int vpid, int apid, int tpid, + int diseqc, int pol, int srate, int fec, int lnb_lof1, + int lnb_lof2, int lnb_slof) + { + struct secCommand scmd; + struct secCmdSequence scmds; + struct dmx_pes_filter_params pesFilterParams; + FrontendParameters frp; + struct pollfd pfd[1]; + FrontendEvent event; + int demux1, demux2, demux3, front; + + frequency = (uint32_t) freq; + symbolrate = (uint32_t) srate; + + if((front = open(FRONT,O_RDWR)) < 0){ + perror("FRONTEND DEVICE: "); + return -1; + } + + if((sec = open(SEC,O_RDWR)) < 0){ + perror("SEC DEVICE: "); + return -1; + } + + if (demux1 < 0){ + if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (demux2 < 0){ + if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (demux3 < 0){ + if ((demux3=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (freq < lnb_slof) { + frp.Frequency = (freq - lnb_lof1); + scmds.continuousTone = SEC_TONE_OFF; + } else { + frp.Frequency = (freq - lnb_lof2); + scmds.continuousTone = SEC_TONE_ON; + } + frp.Inversion = INVERSION_AUTO; + if (pol) scmds.voltage = SEC_VOLTAGE_18; + else scmds.voltage = SEC_VOLTAGE_13; + + scmd.type=0; + scmd.u.diseqc.addr=0x10; + scmd.u.diseqc.cmd=0x38; + scmd.u.diseqc.numParams=1; + scmd.u.diseqc.params[0] = 0xF0 | ((diseqc * 4) & 0x0F) | + (scmds.continuousTone == SEC_TONE_ON ? 1 : 0) | + (scmds.voltage==SEC_VOLTAGE_18 ? 2 : 0); + + scmds.miniCommand=SEC_MINI_NONE; + scmds.numCommands=1; + scmds.commands=&scmd; + if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ + perror("SEC SEND: "); + return -1; + } + + if (ioctl(sec, SEC_SEND_SEQUENCE, &scmds) < 0){ + perror("SEC SEND: "); + return -1; + } + + frp.u.qpsk.SymbolRate = srate; + frp.u.qpsk.FEC_inner = fec; + + if (ioctl(front, FE_SET_FRONTEND, &frp) < 0){ + perror("QPSK TUNE: "); + return -1; + } + + pfd[0].fd = front; + pfd[0].events = POLLIN; + + if (poll(pfd,1,3000)){ + if (pfd[0].revents & POLLIN){ + printf("Getting QPSK event\\n"); + if ( ioctl(front, FE_GET_EVENT, &event) + + == -EOVERFLOW){ + perror("qpsk get event"); + return -1; + } + printf("Received "); + switch(event.type){ + case FE_UNEXPECTED_EV: + printf("unexpected event\\n"); + return -1; + case FE_FAILURE_EV: + printf("failure event\\n"); + return -1; + + case FE_COMPLETION_EV: + printf("completion event\\n"); + } + } + } + + + pesFilterParams.pid = vpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pes_type = DMX_PES_VIDEO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_vpid"); + return -1; + } + + pesFilterParams.pid = apid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pes_type = DMX_PES_AUDIO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_apid"); + return -1; + } + + pesFilterParams.pid = tpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_DECODER; + pesFilterParams.pes_type = DMX_PES_TELETEXT; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux3, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("set_tpid"); + return -1; + } + + return has_signal(fds); + } + +The program assumes that you are using a universal LNB and a standard +DiSEqC switch with up to 4 addresses. Of course, you could build in some +more checking if tuning was successful and maybe try to repeat the +tuning process. Depending on the external hardware, i.e. LNB and DiSEqC +switch, and weather conditions this may be necessary. + + +.. _the_dvr_device: + +The DVR device +============== + +The following program code shows how to use the DVR device for +recording. + + +.. code-block:: c + + #include + #include + #include + #include + #include + #include + #include + #include + + #include + #include + #include + #define DVR "/dev/dvb/adapter0/dvr1" + #define AUDIO "/dev/dvb/adapter0/audio1" + #define VIDEO "/dev/dvb/adapter0/video1" + + #define BUFFY (188*20) + #define MAX_LENGTH (1024*1024*5) /* record 5MB */ + + + /* switch the demuxes to recording, assuming the transponder is tuned */ + + /* demux1, demux2: file descriptor of video and audio filters */ + /* vpid, apid: PIDs of video and audio channels */ + + int switch_to_record(int demux1, int demux2, uint16_t vpid, uint16_t apid) + { + struct dmx_pes_filter_params pesFilterParams; + + if (demux1 < 0){ + if ((demux1=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + if (demux2 < 0){ + if ((demux2=open(DMX, O_RDWR|O_NONBLOCK)) + < 0){ + perror("DEMUX DEVICE: "); + return -1; + } + } + + pesFilterParams.pid = vpid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_TS_TAP; + pesFilterParams.pes_type = DMX_PES_VIDEO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux1, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("DEMUX DEVICE"); + return -1; + } + pesFilterParams.pid = apid; + pesFilterParams.input = DMX_IN_FRONTEND; + pesFilterParams.output = DMX_OUT_TS_TAP; + pesFilterParams.pes_type = DMX_PES_AUDIO; + pesFilterParams.flags = DMX_IMMEDIATE_START; + if (ioctl(demux2, DMX_SET_PES_FILTER, &pesFilterParams) < 0){ + perror("DEMUX DEVICE"); + return -1; + } + return 0; + } + + /* start recording MAX_LENGTH , assuming the transponder is tuned */ + + /* demux1, demux2: file descriptor of video and audio filters */ + /* vpid, apid: PIDs of video and audio channels */ + int record_dvr(int demux1, int demux2, uint16_t vpid, uint16_t apid) + { + int i; + int len; + int written; + uint8_t buf[BUFFY]; + uint64_t length; + struct pollfd pfd[1]; + int dvr, dvr_out; + + /* open dvr device */ + if ((dvr = open(DVR, O_RDONLY|O_NONBLOCK)) < 0){ + perror("DVR DEVICE"); + return -1; + } + + /* switch video and audio demuxes to dvr */ + printf ("Switching dvr on\\n"); + i = switch_to_record(demux1, demux2, vpid, apid); + printf("finished: "); + + printf("Recording %2.0f MB of test file in TS format\\n", + MAX_LENGTH/(1024.0*1024.0)); + length = 0; + + /* open output file */ + if ((dvr_out = open(DVR_FILE,O_WRONLY|O_CREAT + |O_TRUNC, S_IRUSR|S_IWUSR + |S_IRGRP|S_IWGRP|S_IROTH| + S_IWOTH)) < 0){ + perror("Can't open file for dvr test"); + return -1; + } + + pfd[0].fd = dvr; + pfd[0].events = POLLIN; + + /* poll for dvr data and write to file */ + while (length < MAX_LENGTH ) { + if (poll(pfd,1,1)){ + if (pfd[0].revents & POLLIN){ + len = read(dvr, buf, BUFFY); + if (len < 0){ + perror("recording"); + return -1; + } + if (len > 0){ + written = 0; + while (written < len) + written += + write (dvr_out, + buf, len); + length += len; + printf("written %2.0f MB\\r", + length/1024./1024.); + } + } + } + } + return 0; + } diff --git a/Documentation/media/uapi/dvb/fe-bandwidth-t.rst b/Documentation/media/uapi/dvb/fe-bandwidth-t.rst new file mode 100644 index 000000000000..8edaf1a8fbc8 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-bandwidth-t.rst @@ -0,0 +1,77 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _fe-bandwidth-t: + +****************** +Frontend bandwidth +****************** + + +.. _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 new file mode 100644 index 000000000000..7bd02ac7bff4 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-diseqc-recv-slave-reply.rst @@ -0,0 +1,83 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 +======== + +.. cpp:function:: int ioctl( int fd, int request, struct dvb_diseqc_slave_reply *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_DISEQC_RECV_SLAVE_REPLY + +``argp`` + pointer to struct + :ref:`dvb_diseqc_slave_reply ` + + +Description +=========== + +Receives reply from a DiSEqC 2.0 command. + +.. _dvb-diseqc-slave-reply: + +struct dvb_diseqc_slave_reply +----------------------------- + +.. flat-table:: struct dvb_diseqc_slave_reply + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - uint8_t + + - msg[4] + + - DiSEqC message (framing, data[3]) + + - .. row 2 + + - uint8_t + + - msg_len + + - Length of the DiSEqC message. Valid values are 0 to 4, where 0 + means no msg + + - .. row 3 + + - int + + - timeout + + - Return from ioctl after timeout ms with errorcode when no message + was received + + +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/fe-diseqc-reset-overload.rst b/Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst new file mode 100644 index 000000000000..cab157054c13 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-diseqc-reset-overload.rst @@ -0,0 +1,45 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 +======== + +.. cpp:function:: int ioctl( int fd, int request, NULL ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_DISEQC_RESET_OVERLOAD + + +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 DVB adapters support this ioctl. + + +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/fe-diseqc-send-burst.rst b/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst new file mode 100644 index 000000000000..9b476545ef89 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-diseqc-send-burst.rst @@ -0,0 +1,84 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 +======== + +.. cpp:function:: int ioctl( int fd, int request, enum fe_sec_mini_cmd *tone ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_DISEQC_SEND_BURST + +``tone`` + pointer to enum :ref:`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. `__ + +.. _fe-sec-mini-cmd-t: + +enum fe_sec_mini_cmd +==================== + +.. _fe-sec-mini-cmd: + +.. flat-table:: enum fe_sec_mini_cmd + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _SEC-MINI-A: + + ``SEC_MINI_A`` + + - Sends a mini-DiSEqC 22kHz '0' Tone Burst to select satellite-A + + - .. row 3 + + - .. _SEC-MINI-B: + + ``SEC_MINI_B`` + + - Sends a mini-DiSEqC 22kHz '1' Data Burst to select satellite-B + + +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/fe-diseqc-send-master-cmd.rst b/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst new file mode 100644 index 000000000000..58a5e6ac10bd --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-diseqc-send-master-cmd.rst @@ -0,0 +1,73 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _FE_DISEQC_SEND_MASTER_CMD: + +******************************* +ioctl FE_DISEQC_SEND_MASTER_CMD +******************************* + +Name +==== + +FE_DISEQC_SEND_MASTER_CMD - Sends a DiSEqC command + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct dvb_diseqc_master_cmd *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_DISEQC_SEND_MASTER_CMD + +``argp`` + pointer to struct + :ref:`dvb_diseqc_master_cmd ` + + +Description +=========== + +Sends a DiSEqC command to the antenna subsystem. + +.. _dvb-diseqc-master-cmd: + +struct dvb_diseqc_master_cmd +============================ + +.. flat-table:: struct dvb_diseqc_master_cmd + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - uint8_t + + - msg[6] + + - DiSEqC message (framing, address, command, data[3]) + + - .. row 2 + + - uint8_t + + - msg_len + + - Length of the DiSEqC message. Valid values are 3 to 6 + +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/fe-dishnetwork-send-legacy-cmd.rst b/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst new file mode 100644 index 000000000000..9f71b39de0c2 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-dishnetwork-send-legacy-cmd.rst @@ -0,0 +1,54 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _FE_DISHNETWORK_SEND_LEGACY_CMD: + +****************************** +FE_DISHNETWORK_SEND_LEGACY_CMD +****************************** + +Name +==== + +FE_DISHNETWORK_SEND_LEGACY_CMD + + +Synopsis +======== + +.. cpp:function:: int ioctl(int fd, int request = FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd) + + +Arguments +========= + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - unsigned long 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 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/fe-enable-high-lnb-voltage.rst b/Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst new file mode 100644 index 000000000000..de99bf5fbf0e --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-enable-high-lnb-voltage.rst @@ -0,0 +1,52 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 +======== + +.. cpp:function:: int ioctl( int fd, int request, unsigned int high ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_ENABLE_HIGH_LNB_VOLTAGE + +``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 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/fe-get-event.rst b/Documentation/media/uapi/dvb/fe-get-event.rst new file mode 100644 index 000000000000..ffa3d04c6bd4 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-get-event.rst @@ -0,0 +1,87 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _FE_GET_EVENT: + +************ +FE_GET_EVENT +************ + +Name +==== + +FE_GET_EVENT + + +Synopsis +======== + +.. cpp:function:: int ioctl(int fd, int request = QPSK_GET_EVENT, struct dvb_frontend_event *ev) + + +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 :ref:`FE_GET_EVENT` for this command. + + - .. row 3 + + - struct dvb_frontend_event \*ev + + - Points to the location where the event, + + - .. row 4 + + - + - 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 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/fe-get-frontend.rst b/Documentation/media/uapi/dvb/fe-get-frontend.rst new file mode 100644 index 000000000000..5d2df808df18 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-get-frontend.rst @@ -0,0 +1,74 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _FE_GET_FRONTEND: + +*************** +FE_GET_FRONTEND +*************** + +Name +==== + +FE_GET_FRONTEND + + +Synopsis +======== + +.. cpp:function:: int ioctl(int fd, int request = FE_GET_FRONTEND, struct dvb_frontend_parameters *p) + + +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 :ref:`FE_SET_FRONTEND` for this + command. + + - .. row 3 + + - struct dvb_frontend_parameters \*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 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`` + + - Maximum supported symbol rate reached. diff --git a/Documentation/media/uapi/dvb/fe-get-info.rst b/Documentation/media/uapi/dvb/fe-get-info.rst new file mode 100644 index 000000000000..9a9ddbcdb1ec --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-get-info.rst @@ -0,0 +1,428 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _FE_GET_INFO: + +***************** +ioctl FE_GET_INFO +***************** + +Name +==== + +FE_GET_INFO - Query DVB frontend capabilities and returns information about the - front-end. This call only requires read-only access to the device + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct dvb_frontend_info *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_GET_INFO + +``argp`` + pointer to struct struct + :ref:`dvb_frontend_info ` + + +Description +=========== + +All DVB frontend devices support the ``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. + +.. _dvb-frontend-info: + +struct dvb_frontend_info +======================== + +.. flat-table:: struct dvb_frontend_info + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - char + + - name[128] + + - Name of the frontend + + - .. row 2 + + - fe_type_t + + - type + + - **DEPRECATED**. DVBv3 type. Should not be used on modern programs, + as a frontend may have more than one type. So, the DVBv5 API + should be used instead to enumerate and select the frontend type. + + - .. row 3 + + - uint32_t + + - frequency_min + + - Minimal frequency supported by the frontend + + - .. row 4 + + - uint32_t + + - frequency_max + + - Maximal frequency supported by the frontend + + - .. row 5 + + - uint32_t + + - frequency_stepsize + + - Frequency step - all frequencies are multiple of this value + + - .. row 6 + + - uint32_t + + - frequency_tolerance + + - Tolerance of the frequency + + - .. row 7 + + - uint32_t + + - symbol_rate_min + + - Minimal symbol rate (for Cable/Satellite systems), in bauds + + - .. row 8 + + - uint32_t + + - symbol_rate_max + + - Maximal symbol rate (for Cable/Satellite systems), in bauds + + - .. row 9 + + - uint32_t + + - symbol_rate_tolerance + + - Maximal symbol rate tolerance, in ppm + + - .. row 10 + + - uint32_t + + - notifier_delay + + - **DEPRECATED**. Not used by any driver. + + - .. row 11 + + - enum :ref:`fe_caps ` + + - caps + + - Capabilities supported by the frontend + + +NOTE: The frequencies are specified in Hz for Terrestrial and Cable +systems. They're specified in kHz for Satellite systems + + +.. _fe-caps-t: + +frontend capabilities +===================== + +Capabilities describe what a frontend can do. Some capabilities are +supported only on some specific frontend types. + + +.. _fe-caps: + +.. flat-table:: enum fe_caps + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _FE-IS-STUPID: + + ``FE_IS_STUPID`` + + - There's something wrong at the frontend, and it can't report its + capabilities + + - .. row 3 + + - .. _FE-CAN-INVERSION-AUTO: + + ``FE_CAN_INVERSION_AUTO`` + + - The frontend is capable of auto-detecting inversion + + - .. row 4 + + - .. _FE-CAN-FEC-1-2: + + ``FE_CAN_FEC_1_2`` + + - The frontend supports FEC 1/2 + + - .. row 5 + + - .. _FE-CAN-FEC-2-3: + + ``FE_CAN_FEC_2_3`` + + - The frontend supports FEC 2/3 + + - .. row 6 + + - .. _FE-CAN-FEC-3-4: + + ``FE_CAN_FEC_3_4`` + + - The frontend supports FEC 3/4 + + - .. row 7 + + - .. _FE-CAN-FEC-4-5: + + ``FE_CAN_FEC_4_5`` + + - The frontend supports FEC 4/5 + + - .. row 8 + + - .. _FE-CAN-FEC-5-6: + + ``FE_CAN_FEC_5_6`` + + - The frontend supports FEC 5/6 + + - .. row 9 + + - .. _FE-CAN-FEC-6-7: + + ``FE_CAN_FEC_6_7`` + + - The frontend supports FEC 6/7 + + - .. row 10 + + - .. _FE-CAN-FEC-7-8: + + ``FE_CAN_FEC_7_8`` + + - The frontend supports FEC 7/8 + + - .. row 11 + + - .. _FE-CAN-FEC-8-9: + + ``FE_CAN_FEC_8_9`` + + - The frontend supports FEC 8/9 + + - .. row 12 + + - .. _FE-CAN-FEC-AUTO: + + ``FE_CAN_FEC_AUTO`` + + - The frontend can autodetect FEC. + + - .. row 13 + + - .. _FE-CAN-QPSK: + + ``FE_CAN_QPSK`` + + - The frontend supports QPSK modulation + + - .. row 14 + + - .. _FE-CAN-QAM-16: + + ``FE_CAN_QAM_16`` + + - The frontend supports 16-QAM modulation + + - .. row 15 + + - .. _FE-CAN-QAM-32: + + ``FE_CAN_QAM_32`` + + - The frontend supports 32-QAM modulation + + - .. row 16 + + - .. _FE-CAN-QAM-64: + + ``FE_CAN_QAM_64`` + + - The frontend supports 64-QAM modulation + + - .. row 17 + + - .. _FE-CAN-QAM-128: + + ``FE_CAN_QAM_128`` + + - The frontend supports 128-QAM modulation + + - .. row 18 + + - .. _FE-CAN-QAM-256: + + ``FE_CAN_QAM_256`` + + - The frontend supports 256-QAM modulation + + - .. row 19 + + - .. _FE-CAN-QAM-AUTO: + + ``FE_CAN_QAM_AUTO`` + + - The frontend can autodetect modulation + + - .. row 20 + + - .. _FE-CAN-TRANSMISSION-MODE-AUTO: + + ``FE_CAN_TRANSMISSION_MODE_AUTO`` + + - The frontend can autodetect the transmission mode + + - .. row 21 + + - .. _FE-CAN-BANDWIDTH-AUTO: + + ``FE_CAN_BANDWIDTH_AUTO`` + + - The frontend can autodetect the bandwidth + + - .. row 22 + + - .. _FE-CAN-GUARD-INTERVAL-AUTO: + + ``FE_CAN_GUARD_INTERVAL_AUTO`` + + - The frontend can autodetect the guard interval + + - .. row 23 + + - .. _FE-CAN-HIERARCHY-AUTO: + + ``FE_CAN_HIERARCHY_AUTO`` + + - The frontend can autodetect hierarch + + - .. row 24 + + - .. _FE-CAN-8VSB: + + ``FE_CAN_8VSB`` + + - The frontend supports 8-VSB modulation + + - .. row 25 + + - .. _FE-CAN-16VSB: + + ``FE_CAN_16VSB`` + + - The frontend supports 16-VSB modulation + + - .. row 26 + + - .. _FE-HAS-EXTENDED-CAPS: + + ``FE_HAS_EXTENDED_CAPS`` + + - Currently, unused + + - .. row 27 + + - .. _FE-CAN-MULTISTREAM: + + ``FE_CAN_MULTISTREAM`` + + - The frontend supports multistream filtering + + - .. row 28 + + - .. _FE-CAN-TURBO-FEC: + + ``FE_CAN_TURBO_FEC`` + + - The frontend supports turbo FEC modulation + + - .. row 29 + + - .. _FE-CAN-2G-MODULATION: + + ``FE_CAN_2G_MODULATION`` + + - The frontend supports "2nd generation modulation" (DVB-S2/T2)> + + - .. row 30 + + - .. _FE-NEEDS-BENDING: + + ``FE_NEEDS_BENDING`` + + - Not supported anymore, don't use it + + - .. row 31 + + - .. _FE-CAN-RECOVER: + + ``FE_CAN_RECOVER`` + + - The frontend can recover from a cable unplug automatically + + - .. row 32 + + - .. _FE-CAN-MUTE-TS: + + ``FE_CAN_MUTE_TS`` + + - The frontend can stop spurious TS data output + + +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/fe-get-property.rst b/Documentation/media/uapi/dvb/fe-get-property.rst new file mode 100644 index 000000000000..749daafe6b21 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-get-property.rst @@ -0,0 +1,68 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 +======== + +.. cpp:function:: int ioctl( int fd, int request, struct dtv_properties *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_SET_PROPERTY, FE_GET_PROPERTY + +``argp`` + pointer to struct :ref:`dtv_properties ` + + +Description +=========== + +All DVB 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. + + - At return, the values are updated to reflect the actual parameters + used. + +- ``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 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/fe-read-ber.rst b/Documentation/media/uapi/dvb/fe-read-ber.rst new file mode 100644 index 000000000000..c2b5b417f5fb --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-read-ber.rst @@ -0,0 +1,60 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _FE_READ_BER: + +*********** +FE_READ_BER +*********** + +Name +==== + +FE_READ_BER + +Synopsis +======== + +.. cpp:function:: int ioctl(int fd, int request = FE_READ_BER, uint32_t *ber) + + +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 :ref:`FE_READ_BER` for this command. + + - .. row 3 + + - uint32_t \*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 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/fe-read-signal-strength.rst b/Documentation/media/uapi/dvb/fe-read-signal-strength.rst new file mode 100644 index 000000000000..0cdee2effc97 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-read-signal-strength.rst @@ -0,0 +1,63 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _FE_READ_SIGNAL_STRENGTH: + +*********************** +FE_READ_SIGNAL_STRENGTH +*********************** + +Name +==== + +FE_READ_SIGNAL_STRENGTH + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request = FE_READ_SIGNAL_STRENGTH, uint16_t *strength) + + +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 + :ref:`FE_READ_SIGNAL_STRENGTH` + for this command. + + - .. row 3 + + - uint16_t \*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 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/fe-read-snr.rst b/Documentation/media/uapi/dvb/fe-read-snr.rst new file mode 100644 index 000000000000..5394f9ae90f4 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-read-snr.rst @@ -0,0 +1,61 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _FE_READ_SNR: + +*********** +FE_READ_SNR +*********** + +Name +==== + +FE_READ_SNR + + +Synopsis +======== + +.. cpp:function:: int ioctl(int fd, int request = FE_READ_SNR, int16_t *snr) + + +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 :ref:`FE_READ_SNR` for this command. + + - .. row 3 + + - uint16_t \*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 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/fe-read-status.rst b/Documentation/media/uapi/dvb/fe-read-status.rst new file mode 100644 index 000000000000..339955fbe133 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-read-status.rst @@ -0,0 +1,135 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 +======== + +.. cpp:function:: int ioctl( int fd, int request, unsigned int *status ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_READ_STATUS + +``status`` + pointer to a bitmask integer filled with the values defined by enum + :ref:`fe_status `. + + +Description +=========== + +All DVB 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. + + +.. _fe-status-t: + +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 +:ref:`fe_status ` values on a bitmask + + +.. _fe-status: + +.. flat-table:: enum fe_status + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _FE-HAS-SIGNAL: + + ``FE_HAS_SIGNAL`` + + - The frontend has found something above the noise level + + - .. row 3 + + - .. _FE-HAS-CARRIER: + + ``FE_HAS_CARRIER`` + + - The frontend has found a DVB signal + + - .. row 4 + + - .. _FE-HAS-VITERBI: + + ``FE_HAS_VITERBI`` + + - The frontend FEC inner coding (Viterbi, LDPC or other inner code) + is stable + + - .. row 5 + + - .. _FE-HAS-SYNC: + + ``FE_HAS_SYNC`` + + - Synchronization bytes was found + + - .. row 6 + + - .. _FE-HAS-LOCK: + + ``FE_HAS_LOCK`` + + - The DVB were locked and everything is working + + - .. row 7 + + - .. _FE-TIMEDOUT: + + ``FE_TIMEDOUT`` + + - no lock within the last about 2 seconds + + - .. row 8 + + - .. _FE-REINIT: + + ``FE_REINIT`` + + - The frontend was reinitialized, application is recommended to + reset DiSEqC, tone and parameters + + +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/fe-read-uncorrected-blocks.rst b/Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst new file mode 100644 index 000000000000..5c29c058dfdc --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-read-uncorrected-blocks.rst @@ -0,0 +1,65 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _FE_READ_UNCORRECTED_BLOCKS: + +************************** +FE_READ_UNCORRECTED_BLOCKS +************************** + +Name +==== + +FE_READ_UNCORRECTED_BLOCKS + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request =FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks) + + +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 + :ref:`FE_READ_UNCORRECTED_BLOCKS` + for this command. + + - .. row 3 + + - uint32_t \*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 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/fe-set-frontend-tune-mode.rst b/Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst new file mode 100644 index 000000000000..411abcf4de58 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-set-frontend-tune-mode.rst @@ -0,0 +1,55 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 +======== + +.. cpp:function:: int ioctl( int fd, int request, unsigned int flags ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_SET_FRONTEND_TUNE_MODE + +``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 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/fe-set-frontend.rst b/Documentation/media/uapi/dvb/fe-set-frontend.rst new file mode 100644 index 000000000000..7cb70c38d534 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-set-frontend.rst @@ -0,0 +1,79 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _FE_SET_FRONTEND: + +*************** +FE_SET_FRONTEND +*************** + +Name +==== + +FE_SET_FRONTEND + + +Synopsis +======== + +.. cpp:function:: int ioctl(int fd, int request = FE_SET_FRONTEND, struct dvb_frontend_parameters *p) + + +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 :ref:`FE_SET_FRONTEND` for this + command. + + - .. row 3 + + - struct dvb_frontend_parameters \*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 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`` + + - Maximum supported symbol rate reached. diff --git a/Documentation/media/uapi/dvb/fe-set-tone.rst b/Documentation/media/uapi/dvb/fe-set-tone.rst new file mode 100644 index 000000000000..763b61d91004 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-set-tone.rst @@ -0,0 +1,91 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _FE_SET_TONE: + +***************** +ioctl FE_SET_TONE +***************** + +Name +==== + +FE_SET_TONE - Sets/resets the generation of the continuous 22kHz tone. + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, enum fe_sec_tone_mode *tone ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_SET_TONE + +``tone`` + pointer to enum :ref:`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. + +NOTE: 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. + +.. _fe-sec-tone-mode-t: + +enum fe_sec_tone_mode +===================== + +.. _fe-sec-tone-mode: + +.. flat-table:: enum fe_sec_tone_mode + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _SEC-TONE-ON: + + ``SEC_TONE_ON`` + + - Sends a 22kHz tone burst to the antenna + + - .. row 3 + + - .. _SEC-TONE-OFF: + + ``SEC_TONE_OFF`` + + - Don't send a 22kHz tone to the antenna (except if the + FE_DISEQC_* ioctls are called) + + +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/fe-set-voltage.rst b/Documentation/media/uapi/dvb/fe-set-voltage.rst new file mode 100644 index 000000000000..517f79bdbb4b --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-set-voltage.rst @@ -0,0 +1,63 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _FE_SET_VOLTAGE: + +******************** +ioctl FE_SET_VOLTAGE +******************** + +Name +==== + +FE_SET_VOLTAGE - Allow setting the DC level sent to the antenna subsystem. + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, enum fe_sec_voltage *voltage ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_SET_VOLTAGE + +``voltage`` + pointer to enum :ref:`fe_sec_voltage ` + + Valid values are described at enum + :ref:`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. + +NOTE: 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 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/fe-type-t.rst b/Documentation/media/uapi/dvb/fe-type-t.rst new file mode 100644 index 000000000000..8ca762b42e4d --- /dev/null +++ b/Documentation/media/uapi/dvb/fe-type-t.rst @@ -0,0 +1,91 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _fe-type-t: + +************* +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: + + +.. _fe-type: + +.. 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 :ref:`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 +:ref:`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 new file mode 100644 index 000000000000..47eb29350717 --- /dev/null +++ b/Documentation/media/uapi/dvb/fe_property_parameters.rst @@ -0,0 +1,1967 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _fe_property_parameters: + +****************************** +Digital TV property parameters +****************************** + + +.. _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 +============= + +Central frequency of the channel. + +Notes: + +1)For satellite delivery systems, it is measured in kHz. For the other +ones, it is measured in Hz. + +2)For ISDB-T, the channels are usually transmitted with an offset of +143kHz. E.g. a valid frequency could be 474143 kHz. The stepping is +bound to the bandwidth of the channel which is 6MHz. + +3)As in ISDB-Tsb the channel consists of only one or three segments the +frequency step is 429kHz, 3*429 respectively. As for ISDB-T the central +frequency of the channel is expected. + + +.. _DTV-MODULATION: + +DTV_MODULATION +============== + +Specifies the frontend modulation type for delivery systems that +supports more than one modulation type. The modulation can be one of the +types defined by enum :ref:`fe_modulation `. + + +.. _fe-modulation-t: + +Modulation property +------------------- + +Most of the digital TV standards currently offers more than one possible +modulation (sometimes called as "constellation" on some standards). This +enum contains the values used by the Kernel. Please note that not all +modulations are supported by a given standard. + + +.. _fe-modulation: + +.. flat-table:: enum fe_modulation + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _QPSK: + + ``QPSK`` + + - QPSK modulation + + - .. row 3 + + - .. _QAM-16: + + ``QAM_16`` + + - 16-QAM modulation + + - .. row 4 + + - .. _QAM-32: + + ``QAM_32`` + + - 32-QAM modulation + + - .. row 5 + + - .. _QAM-64: + + ``QAM_64`` + + - 64-QAM modulation + + - .. row 6 + + - .. _QAM-128: + + ``QAM_128`` + + - 128-QAM modulation + + - .. row 7 + + - .. _QAM-256: + + ``QAM_256`` + + - 256-QAM modulation + + - .. row 8 + + - .. _QAM-AUTO: + + ``QAM_AUTO`` + + - Autodetect QAM modulation + + - .. row 9 + + - .. _VSB-8: + + ``VSB_8`` + + - 8-VSB modulation + + - .. row 10 + + - .. _VSB-16: + + ``VSB_16`` + + - 16-VSB modulation + + - .. row 11 + + - .. _PSK-8: + + ``PSK_8`` + + - 8-PSK modulation + + - .. row 12 + + - .. _APSK-16: + + ``APSK_16`` + + - 16-APSK modulation + + - .. row 13 + + - .. _APSK-32: + + ``APSK_32`` + + - 32-APSK modulation + + - .. row 14 + + - .. _DQPSK: + + ``DQPSK`` + + - DQPSK modulation + + - .. row 15 + + - .. _QAM-4-NR: + + ``QAM_4_NR`` + + - 4-QAM-NR modulation + + + +.. _DTV-BANDWIDTH-HZ: + +DTV_BANDWIDTH_HZ +================ + +Bandwidth for the channel, in HZ. + +Possible values: ``1712000``, ``5000000``, ``6000000``, ``7000000``, +``8000000``, ``10000000``. + +Notes: + +1) For ISDB-T it should be always 6000000Hz (6MHz) + +2) For ISDB-Tsb it can vary depending on the number of connected +segments + +3) Bandwidth doesn't apply for DVB-C transmissions, as the bandwidth for +DVB-C depends on the symbol rate + +4) Bandwidth in ISDB-T is fixed (6MHz) or can be easily derived from +other parameters (DTV_ISDBT_SB_SEGMENT_IDX, +DTV_ISDBT_SB_SEGMENT_COUNT). + +5) DVB-T supports 6, 7 and 8MHz. + +6) In addition, DVB-T2 supports 1.172, 5 and 10MHz. + + +.. _DTV-INVERSION: + +DTV_INVERSION +============= + +Specifies if the frontend should do spectral inversion or not. + + +.. _fe-spectral-inversion-t: + +enum fe_modulation: Frontend spectral inversion +----------------------------------------------- + +This parameter indicates if spectral inversion should be presumed or +not. In the automatic setting (``INVERSION_AUTO``) the hardware will try +to figure out the correct setting by itself. If the hardware doesn't +support, the DVB core will try to lock at the carrier first with +inversion off. If it fails, it will try to enable inversion. + + +.. _fe-spectral-inversion: + +.. flat-table:: enum fe_modulation + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _INVERSION-OFF: + + ``INVERSION_OFF`` + + - Don't do spectral band inversion. + + - .. row 3 + + - .. _INVERSION-ON: + + ``INVERSION_ON`` + + - Do spectral band inversion. + + - .. row 4 + + - .. _INVERSION-AUTO: + + ``INVERSION_AUTO`` + + - Autodetect spectral band inversion. + + + +.. _DTV-DISEQC-MASTER: + +DTV_DISEQC_MASTER +================= + +Currently not implemented. + + +.. _DTV-SYMBOL-RATE: + +DTV_SYMBOL_RATE +=============== + +Digital TV symbol rate, in bauds (symbols/second). Used on cable +standards. + + +.. _DTV-INNER-FEC: + +DTV_INNER_FEC +============= + +Used cable/satellite transmissions. The acceptable values are: + + +.. _fe-code-rate-t: + +enum fe_code_rate: type of the Forward Error Correction. +-------------------------------------------------------- + + +.. _fe-code-rate: + +.. flat-table:: enum fe_code_rate + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _FEC-NONE: + + ``FEC_NONE`` + + - No Forward Error Correction Code + + - .. row 3 + + - .. _FEC-AUTO: + + ``FEC_AUTO`` + + - Autodetect Error Correction Code + + - .. row 4 + + - .. _FEC-1-2: + + ``FEC_1_2`` + + - Forward Error Correction Code 1/2 + + - .. row 5 + + - .. _FEC-2-3: + + ``FEC_2_3`` + + - Forward Error Correction Code 2/3 + + - .. row 6 + + - .. _FEC-3-4: + + ``FEC_3_4`` + + - Forward Error Correction Code 3/4 + + - .. row 7 + + - .. _FEC-4-5: + + ``FEC_4_5`` + + - Forward Error Correction Code 4/5 + + - .. row 8 + + - .. _FEC-5-6: + + ``FEC_5_6`` + + - Forward Error Correction Code 5/6 + + - .. row 9 + + - .. _FEC-6-7: + + ``FEC_6_7`` + + - Forward Error Correction Code 6/7 + + - .. row 10 + + - .. _FEC-7-8: + + ``FEC_7_8`` + + - Forward Error Correction Code 7/8 + + - .. row 11 + + - .. _FEC-8-9: + + ``FEC_8_9`` + + - Forward Error Correction Code 8/9 + + - .. row 12 + + - .. _FEC-9-10: + + ``FEC_9_10`` + + - Forward Error Correction Code 9/10 + + - .. row 13 + + - .. _FEC-2-5: + + ``FEC_2_5`` + + - Forward Error Correction Code 2/5 + + - .. row 14 + + - .. _FEC-3-5: + + ``FEC_3_5`` + + - Forward Error Correction Code 3/5 + + + +.. _DTV-VOLTAGE: + +DTV_VOLTAGE +=========== + +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. + + +.. _fe-sec-voltage: + +.. flat-table:: enum fe_sec_voltage + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _SEC-VOLTAGE-13: + + ``SEC_VOLTAGE_13`` + + - Set DC voltage level to 13V + + - .. row 3 + + - .. _SEC-VOLTAGE-18: + + ``SEC_VOLTAGE_18`` + + - Set DC voltage level to 18V + + - .. row 4 + + - .. _SEC-VOLTAGE-OFF: + + ``SEC_VOLTAGE_OFF`` + + - Don't send any voltage to the antenna + + + +.. _DTV-TONE: + +DTV_TONE +======== + +Currently not used. + + +.. _DTV-PILOT: + +DTV_PILOT +========= + +Sets DVB-S2 pilot + + +.. _fe-pilot-t: + +fe_pilot type +------------- + + +.. _fe-pilot: + +.. flat-table:: enum fe_pilot + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _PILOT-ON: + + ``PILOT_ON`` + + - Pilot tones enabled + + - .. row 3 + + - .. _PILOT-OFF: + + ``PILOT_OFF`` + + - Pilot tones disabled + + - .. row 4 + + - .. _PILOT-AUTO: + + ``PILOT_AUTO`` + + - Autodetect pilot tones + + + +.. _DTV-ROLLOFF: + +DTV_ROLLOFF +=========== + +Sets DVB-S2 rolloff + + +.. _fe-rolloff-t: + +fe_rolloff type +--------------- + + +.. _fe-rolloff: + +.. flat-table:: enum fe_rolloff + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _ROLLOFF-35: + + ``ROLLOFF_35`` + + - Roloff factor: α=35% + + - .. row 3 + + - .. _ROLLOFF-20: + + ``ROLLOFF_20`` + + - Roloff factor: α=20% + + - .. row 4 + + - .. _ROLLOFF-25: + + ``ROLLOFF_25`` + + - Roloff factor: α=25% + + - .. row 5 + + - .. _ROLLOFF-AUTO: + + ``ROLLOFF_AUTO`` + + - Auto-detect the roloff factor. + + + +.. _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 Delivery system + + +.. _fe-delivery-system-t: + +fe_delivery_system type +----------------------- + +Possible values: + + +.. _fe-delivery-system: + +.. flat-table:: enum fe_delivery_system + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _SYS-UNDEFINED: + + ``SYS_UNDEFINED`` + + - Undefined standard. Generally, indicates an error + + - .. row 3 + + - .. _SYS-DVBC-ANNEX-A: + + ``SYS_DVBC_ANNEX_A`` + + - Cable TV: DVB-C following ITU-T J.83 Annex A spec + + - .. row 4 + + - .. _SYS-DVBC-ANNEX-B: + + ``SYS_DVBC_ANNEX_B`` + + - Cable TV: DVB-C following ITU-T J.83 Annex B spec (ClearQAM) + + - .. row 5 + + - .. _SYS-DVBC-ANNEX-C: + + ``SYS_DVBC_ANNEX_C`` + + - Cable TV: DVB-C following ITU-T J.83 Annex C spec + + - .. row 6 + + - .. _SYS-ISDBC: + + ``SYS_ISDBC`` + + - Cable TV: ISDB-C (no drivers yet) + + - .. row 7 + + - .. _SYS-DVBT: + + ``SYS_DVBT`` + + - Terrestral TV: DVB-T + + - .. row 8 + + - .. _SYS-DVBT2: + + ``SYS_DVBT2`` + + - Terrestral TV: DVB-T2 + + - .. row 9 + + - .. _SYS-ISDBT: + + ``SYS_ISDBT`` + + - Terrestral TV: ISDB-T + + - .. row 10 + + - .. _SYS-ATSC: + + ``SYS_ATSC`` + + - Terrestral TV: ATSC + + - .. row 11 + + - .. _SYS-ATSCMH: + + ``SYS_ATSCMH`` + + - Terrestral TV (mobile): ATSC-M/H + + - .. row 12 + + - .. _SYS-DTMB: + + ``SYS_DTMB`` + + - Terrestrial TV: DTMB + + - .. row 13 + + - .. _SYS-DVBS: + + ``SYS_DVBS`` + + - Satellite TV: DVB-S + + - .. row 14 + + - .. _SYS-DVBS2: + + ``SYS_DVBS2`` + + - Satellite TV: DVB-S2 + + - .. row 15 + + - .. _SYS-TURBO: + + ``SYS_TURBO`` + + - Satellite TV: DVB-S Turbo + + - .. row 16 + + - .. _SYS-ISDBS: + + ``SYS_ISDBS`` + + - Satellite TV: ISDB-S + + - .. row 17 + + - .. _SYS-DAB: + + ``SYS_DAB`` + + - Digital audio: DAB (not fully supported) + + - .. row 18 + + - .. _SYS-DSS: + + ``SYS_DSS`` + + - Satellite TV:"DSS (not fully supported) + + - .. row 19 + + - .. _SYS-CMMB: + + ``SYS_CMMB`` + + - Terrestral TV (mobile):CMMB (not fully supported) + + - .. row 20 + + - .. _SYS-DVBH: + + ``SYS_DVBH`` + + - Terrestral TV (mobile): DVB-H (standard deprecated) + + + +.. _DTV-ISDBT-PARTIAL-RECEPTION: + +DTV_ISDBT_PARTIAL_RECEPTION +=========================== + +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 +============================ + +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 +========================== + +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 +======================== + +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 +========================== + +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 +=============================== + +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 +----------------------- + +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 +------------------------ + +Possible values: ``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 +------------------------------- + +Possible values: ``QAM_AUTO``, QP\ ``SK, QAM_16``, ``QAM_64``, ``DQPSK`` + +Note: If layer C is ``DQPSK`` layer B has to be ``DQPSK``. If layer B is +``DQPSK`` and ``DTV_ISDBT_PARTIAL_RECEPTION``\ =0 layer has to be +``DQPSK``. + + +.. _DTV-ISDBT-LAYER-SEGMENT-COUNT: + +DTV_ISDBT_LAYER[A-C]_SEGMENT_COUNT +---------------------------------- + +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:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - PR + + - SB + + - 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 +-------------------------------------- + +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. + + +.. _isdbt-layer-interleaving-table: + +.. flat-table:: + :header-rows: 0 + :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 +------------------ + +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 +-------------------- + +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 +-------------- + +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 +--------------- + +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 +-------------- + +Start group number. + +Possible values: 0, 1, 2, 3, ..., 14, 15 + + +.. _DTV-ATSCMH-PRC: + +DTV_ATSCMH_PRC +-------------- + +Parade repetition cycle. + +Possible values: 1, 2, 3, 4, 5, 6, 7, 8 + + +.. _DTV-ATSCMH-RS-FRAME-MODE: + +DTV_ATSCMH_RS_FRAME_MODE +------------------------ + +Reed Solomon (RS) frame mode. + +Possible values are: + + +.. _atscmh-rs-frame-mode: + +.. flat-table:: enum atscmh_rs_frame_mode + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _ATSCMH-RSFRAME-PRI-ONLY: + + ``ATSCMH_RSFRAME_PRI_ONLY`` + + - Single Frame: There is only a primary RS Frame for all Group + Regions. + + - .. row 3 + + - .. _ATSCMH-RSFRAME-PRI-SEC: + + ``ATSCMH_RSFRAME_PRI_SEC`` + + - Dual Frame: There are two separate RS Frames: Primary RS Frame for + Group Region A and B and Secondary RS Frame for Group Region C and + D. + + + +.. _DTV-ATSCMH-RS-FRAME-ENSEMBLE: + +DTV_ATSCMH_RS_FRAME_ENSEMBLE +---------------------------- + +Reed Solomon(RS) frame ensemble. + +Possible values are: + + +.. _atscmh-rs-frame-ensemble: + +.. flat-table:: enum atscmh_rs_frame_ensemble + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _ATSCMH-RSFRAME-ENS-PRI: + + ``ATSCMH_RSFRAME_ENS_PRI`` + + - Primary Ensemble. + + - .. row 3 + + - .. _ATSCMH-RSFRAME-ENS-SEC: + + ``AATSCMH_RSFRAME_PRI_SEC`` + + - Secondary Ensemble. + + - .. row 4 + + - .. _ATSCMH-RSFRAME-RES: + + ``AATSCMH_RSFRAME_RES`` + + - Reserved. Shouldn't be used. + + + +.. _DTV-ATSCMH-RS-CODE-MODE-PRI: + +DTV_ATSCMH_RS_CODE_MODE_PRI +--------------------------- + +Reed Solomon (RS) code mode (primary). + +Possible values are: + + +.. _atscmh-rs-code-mode: + +.. flat-table:: enum atscmh_rs_code_mode + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _ATSCMH-RSCODE-211-187: + + ``ATSCMH_RSCODE_211_187`` + + - Reed Solomon code (211,187). + + - .. row 3 + + - .. _ATSCMH-RSCODE-223-187: + + ``ATSCMH_RSCODE_223_187`` + + - Reed Solomon code (223,187). + + - .. row 4 + + - .. _ATSCMH-RSCODE-235-187: + + ``ATSCMH_RSCODE_235_187`` + + - Reed Solomon code (235,187). + + - .. row 5 + + - .. _ATSCMH-RSCODE-RES: + + ``ATSCMH_RSCODE_RES`` + + - Reserved. Shouldn't be used. + + + +.. _DTV-ATSCMH-RS-CODE-MODE-SEC: + +DTV_ATSCMH_RS_CODE_MODE_SEC +--------------------------- + +Reed Solomon (RS) code mode (secondary). + +Possible values are the same as documented on enum +:ref:`atscmh_rs_code_mode `: + + +.. _DTV-ATSCMH-SCCC-BLOCK-MODE: + +DTV_ATSCMH_SCCC_BLOCK_MODE +-------------------------- + +Series Concatenated Convolutional Code Block Mode. + +Possible values are: + + +.. _atscmh-sccc-block-mode: + +.. flat-table:: enum atscmh_scc_block_mode + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _ATSCMH-SCCC-BLK-SEP: + + ``ATSCMH_SCCC_BLK_SEP`` + + - Separate SCCC: the SCCC outer code mode shall be set independently + for each Group Region (A, B, C, D) + + - .. row 3 + + - .. _ATSCMH-SCCC-BLK-COMB: + + ``ATSCMH_SCCC_BLK_COMB`` + + - Combined SCCC: all four Regions shall have the same SCCC outer + code mode. + + - .. row 4 + + - .. _ATSCMH-SCCC-BLK-RES: + + ``ATSCMH_SCCC_BLK_RES`` + + - Reserved. Shouldn't be used. + + + +.. _DTV-ATSCMH-SCCC-CODE-MODE-A: + +DTV_ATSCMH_SCCC_CODE_MODE_A +--------------------------- + +Series Concatenated Convolutional Code Rate. + +Possible values are: + + +.. _atscmh-sccc-code-mode: + +.. flat-table:: enum atscmh_sccc_code_mode + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _ATSCMH-SCCC-CODE-HLF: + + ``ATSCMH_SCCC_CODE_HLF`` + + - The outer code rate of a SCCC Block is 1/2 rate. + + - .. row 3 + + - .. _ATSCMH-SCCC-CODE-QTR: + + ``ATSCMH_SCCC_CODE_QTR`` + + - The outer code rate of a SCCC Block is 1/4 rate. + + - .. row 4 + + - .. _ATSCMH-SCCC-CODE-RES: + + ``ATSCMH_SCCC_CODE_RES`` + + - to be documented. + + + +.. _DTV-ATSCMH-SCCC-CODE-MODE-B: + +DTV_ATSCMH_SCCC_CODE_MODE_B +--------------------------- + +Series Concatenated Convolutional Code Rate. + +Possible values are the same as documented on enum +:ref:`atscmh_sccc_code_mode `. + + +.. _DTV-ATSCMH-SCCC-CODE-MODE-C: + +DTV_ATSCMH_SCCC_CODE_MODE_C +--------------------------- + +Series Concatenated Convolutional Code Rate. + +Possible values are the same as documented on enum +:ref:`atscmh_sccc_code_mode `. + + +.. _DTV-ATSCMH-SCCC-CODE-MODE-D: + +DTV_ATSCMH_SCCC_CODE_MODE_D +--------------------------- + +Series Concatenated Convolutional Code Rate. + +Possible values are the same as documented on enum +:ref:`atscmh_sccc_code_mode `. + + +.. _DTV-API-VERSION: + +DTV_API_VERSION +=============== + +Returns the major/minor version of the DVB API + + +.. _DTV-CODE-RATE-HP: + +DTV_CODE_RATE_HP +================ + +Used on terrestrial transmissions. The acceptable values are the ones +described at :ref:`fe_transmit_mode_t `. + + +.. _DTV-CODE-RATE-LP: + +DTV_CODE_RATE_LP +================ + +Used on terrestrial transmissions. The acceptable values are the ones +described at :ref:`fe_transmit_mode_t `. + + +.. _DTV-GUARD-INTERVAL: + +DTV_GUARD_INTERVAL +================== + +Possible values are: + + +.. _fe-guard-interval-t: + +Modulation guard interval +------------------------- + + +.. _fe-guard-interval: + +.. flat-table:: enum fe_guard_interval + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _GUARD-INTERVAL-AUTO: + + ``GUARD_INTERVAL_AUTO`` + + - Autodetect the guard interval + + - .. row 3 + + - .. _GUARD-INTERVAL-1-128: + + ``GUARD_INTERVAL_1_128`` + + - Guard interval 1/128 + + - .. row 4 + + - .. _GUARD-INTERVAL-1-32: + + ``GUARD_INTERVAL_1_32`` + + - Guard interval 1/32 + + - .. row 5 + + - .. _GUARD-INTERVAL-1-16: + + ``GUARD_INTERVAL_1_16`` + + - Guard interval 1/16 + + - .. row 6 + + - .. _GUARD-INTERVAL-1-8: + + ``GUARD_INTERVAL_1_8`` + + - Guard interval 1/8 + + - .. row 7 + + - .. _GUARD-INTERVAL-1-4: + + ``GUARD_INTERVAL_1_4`` + + - Guard interval 1/4 + + - .. row 8 + + - .. _GUARD-INTERVAL-19-128: + + ``GUARD_INTERVAL_19_128`` + + - Guard interval 19/128 + + - .. row 9 + + - .. _GUARD-INTERVAL-19-256: + + ``GUARD_INTERVAL_19_256`` + + - Guard interval 19/256 + + - .. row 10 + + - .. _GUARD-INTERVAL-PN420: + + ``GUARD_INTERVAL_PN420`` + + - PN length 420 (1/4) + + - .. row 11 + + - .. _GUARD-INTERVAL-PN595: + + ``GUARD_INTERVAL_PN595`` + + - PN length 595 (1/6) + + - .. row 12 + + - .. _GUARD-INTERVAL-PN945: + + ``GUARD_INTERVAL_PN945`` + + - PN length 945 (1/9) + + +Notes: + +1) 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. + +2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at +present + +3) DTMB specifies PN420, PN595 and PN945. + + +.. _DTV-TRANSMISSION-MODE: + +DTV_TRANSMISSION_MODE +===================== + +Specifies the number of carriers used by the standard. This is used only +on OFTM-based standards, e. g. DVB-T/T2, ISDB-T, DTMB + + +.. _fe-transmit-mode-t: + +enum fe_transmit_mode: Number of carriers per channel +----------------------------------------------------- + + +.. _fe-transmit-mode: + +.. flat-table:: enum fe_transmit_mode + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _TRANSMISSION-MODE-AUTO: + + ``TRANSMISSION_MODE_AUTO`` + + - Autodetect transmission mode. The hardware will try to find the + correct FFT-size (if capable) to fill in the missing parameters. + + - .. row 3 + + - .. _TRANSMISSION-MODE-1K: + + ``TRANSMISSION_MODE_1K`` + + - Transmission mode 1K + + - .. row 4 + + - .. _TRANSMISSION-MODE-2K: + + ``TRANSMISSION_MODE_2K`` + + - Transmission mode 2K + + - .. row 5 + + - .. _TRANSMISSION-MODE-8K: + + ``TRANSMISSION_MODE_8K`` + + - Transmission mode 8K + + - .. row 6 + + - .. _TRANSMISSION-MODE-4K: + + ``TRANSMISSION_MODE_4K`` + + - Transmission mode 4K + + - .. row 7 + + - .. _TRANSMISSION-MODE-16K: + + ``TRANSMISSION_MODE_16K`` + + - Transmission mode 16K + + - .. row 8 + + - .. _TRANSMISSION-MODE-32K: + + ``TRANSMISSION_MODE_32K`` + + - Transmission mode 32K + + - .. row 9 + + - .. _TRANSMISSION-MODE-C1: + + ``TRANSMISSION_MODE_C1`` + + - Single Carrier (C=1) transmission mode (DTMB) + + - .. row 10 + + - .. _TRANSMISSION-MODE-C3780: + + ``TRANSMISSION_MODE_C3780`` + + - Multi Carrier (C=3780) transmission mode (DTMB) + + +Notes: + +1) ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called +'mode' in the standard: Mode 1 is 2K, mode 2 is 4K, mode 3 is 8K + +2) 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. + +3) DVB-T specifies 2K and 8K as valid sizes. + +4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K. + +5) DTMB specifies C1 and C3780. + + +.. _DTV-HIERARCHY: + +DTV_HIERARCHY +============= + +Frontend hierarchy + + +.. _fe-hierarchy-t: + +Frontend hierarchy +------------------ + + +.. _fe-hierarchy: + +.. flat-table:: enum fe_hierarchy + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _HIERARCHY-NONE: + + ``HIERARCHY_NONE`` + + - No hierarchy + + - .. row 3 + + - .. _HIERARCHY-AUTO: + + ``HIERARCHY_AUTO`` + + - Autodetect hierarchy (if supported) + + - .. row 4 + + - .. _HIERARCHY-1: + + ``HIERARCHY_1`` + + - Hierarchy 1 + + - .. row 5 + + - .. _HIERARCHY-2: + + ``HIERARCHY_2`` + + - Hierarchy 2 + + - .. row 6 + + - .. _HIERARCHY-4: + + ``HIERARCHY_4`` + + - Hierarchy 4 + + + +.. _DTV-STREAM-ID: + +DTV_STREAM_ID +============= + +DVB-S2, DVB-T2 and ISDB-S support the transmission of several streams on +a single transport stream. This property enables the DVB 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 + + +.. _DTV-INTERLEAVING: + +DTV_INTERLEAVING +================ + +Time interleaving to be used. Currently, used only on DTMB. + + +.. _fe-interleaving: + +.. flat-table:: enum fe_interleaving + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _INTERLEAVING-NONE: + + ``INTERLEAVING_NONE`` + + - No interleaving. + + - .. row 3 + + - .. _INTERLEAVING-AUTO: + + ``INTERLEAVING_AUTO`` + + - Auto-detect interleaving. + + - .. row 4 + + - .. _INTERLEAVING-240: + + ``INTERLEAVING_240`` + + - Interleaving of 240 symbols. + + - .. row 5 + + - .. _INTERLEAVING-720: + + ``INTERLEAVING_720`` + + - Interleaving of 720 symbols. + + + +.. _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 diff --git a/Documentation/media/uapi/dvb/frontend-property-cable-systems.rst b/Documentation/media/uapi/dvb/frontend-property-cable-systems.rst new file mode 100644 index 000000000000..bf2328627af5 --- /dev/null +++ b/Documentation/media/uapi/dvb/frontend-property-cable-systems.rst @@ -0,0 +1,75 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 new file mode 100644 index 000000000000..1f40399c68ff --- /dev/null +++ b/Documentation/media/uapi/dvb/frontend-property-satellite-systems.rst @@ -0,0 +1,103 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 ` + +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 new file mode 100644 index 000000000000..dbc717cad9ee --- /dev/null +++ b/Documentation/media/uapi/dvb/frontend-property-terrestrial-systems.rst @@ -0,0 +1,294 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 DVB-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 new file mode 100644 index 000000000000..0fc4aaa304ff --- /dev/null +++ b/Documentation/media/uapi/dvb/frontend-stat-properties.rst @@ -0,0 +1,245 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 :ref:`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 new file mode 100644 index 000000000000..8c7e502bff1f --- /dev/null +++ b/Documentation/media/uapi/dvb/frontend.rst @@ -0,0 +1,51 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dvb_frontend: + +################ +DVB Frontend API +################ +The DVB frontend API was designed to support three types of delivery +systems: + +- 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), ISDB-C + +- Satellite systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS + +The DVB frontend controls several sub-devices including: + +- Tuner + +- Digital TV demodulator + +- Low noise amplifier (LNA) + +- Satellite Equipment Control (SEC) hardware (only for Satellite). + +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) is not yet handled by this +API but a future extension is possible. + +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 + frontend_legacy_dvbv3_api diff --git a/Documentation/media/uapi/dvb/frontend_f_close.rst b/Documentation/media/uapi/dvb/frontend_f_close.rst new file mode 100644 index 000000000000..5cce9262084c --- /dev/null +++ b/Documentation/media/uapi/dvb/frontend_f_close.rst @@ -0,0 +1,48 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _frontend_f_close: + +******************** +DVB frontend close() +******************** + +Name +==== + +fe-close - Close a frontend device + + +Synopsis +======== + +.. code-block:: c + + #include + + +.. cpp:function:: int close( int fd ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`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 +============ + +The function returns 0 on success, -1 on failure and the ``errno`` is +set appropriately. Possible error codes: + +EBADF + ``fd`` is not a valid open file descriptor. diff --git a/Documentation/media/uapi/dvb/frontend_f_open.rst b/Documentation/media/uapi/dvb/frontend_f_open.rst new file mode 100644 index 000000000000..e0c55345f524 --- /dev/null +++ b/Documentation/media/uapi/dvb/frontend_f_open.rst @@ -0,0 +1,102 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _frontend_f_open: + +******************* +DVB frontend open() +******************* + +Name +==== + +fe-open - Open a frontend device + + +Synopsis +======== + +.. code-block:: c + + #include + + +.. cpp:function:: int open( const char *device_name, int flags ) + + +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: + +EACCES + The caller has no permission to access the device. + +EBUSY + The the device driver is already in use. + +ENXIO + No device corresponding to this device special file exists. + +ENOMEM + Not enough kernel memory was available to complete the request. + +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. + +ENODEV + The device got removed. diff --git a/Documentation/media/uapi/dvb/frontend_fcalls.rst b/Documentation/media/uapi/dvb/frontend_fcalls.rst new file mode 100644 index 000000000000..b03f9cab6d5a --- /dev/null +++ b/Documentation/media/uapi/dvb/frontend_fcalls.rst @@ -0,0 +1,24 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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_h.rst b/Documentation/media/uapi/dvb/frontend_h.rst new file mode 100644 index 000000000000..15fca04d1c32 --- /dev/null +++ b/Documentation/media/uapi/dvb/frontend_h.rst @@ -0,0 +1,9 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _frontend_h: + +************************ +DVB Frontend Header File +************************ + +.. kernel-include:: $BUILDDIR/frontend.h.rst diff --git a/Documentation/media/uapi/dvb/frontend_legacy_api.rst b/Documentation/media/uapi/dvb/frontend_legacy_api.rst new file mode 100644 index 000000000000..759833d3eaa4 --- /dev/null +++ b/Documentation/media/uapi/dvb/frontend_legacy_api.rst @@ -0,0 +1,38 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 new file mode 100644 index 000000000000..7d4a091b7d7f --- /dev/null +++ b/Documentation/media/uapi/dvb/frontend_legacy_dvbv3_api.rst @@ -0,0 +1,18 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _frontend_legacy_dvbv3_api: + +**************************************** +DVB 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/intro.rst b/Documentation/media/uapi/dvb/intro.rst new file mode 100644 index 000000000000..b61081d00a9f --- /dev/null +++ b/Documentation/media/uapi/dvb/intro.rst @@ -0,0 +1,172 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 (DVB) 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 DVB standards documents are available from http://www.dvb.org +and/or http://www.etsi.org. + +It is also necessary to know how to access unix/linux devices and how to +use ioctl calls. This also includes the knowledge of C or C++. + + +.. _history: + +History +======= + +The first API for DVB 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 DVB +cards and their new features like recording MPEG streams and filtering +several section and PES data streams at the same time. + +In early 2000, we were approached by Nokia with a proposal for a new +standard Linux DVB 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. Convergence is the maintainer of the Linux DVB API. Together with +the LinuxTV community (i.e. you, the reader of this document), the Linux +DVB API will be constantly reviewed and improved. With the Linux driver +for the Siemens/Hauppauge DVB PCI card Convergence provides a first +implementation of the Linux DVB API. + + +.. _overview: + +Overview +======== + + +.. _stb_components: + +.. figure:: intro_files/dvbstb.* + :alt: dvbstb.pdf / dvbstb.png + :align: center + + Components of a DVB card/STB + +A DVB PCI card or DVB set-top-box (STB) usually consists of the +following main hardware components: + +- Frontend consisting of tuner and DVB demodulator + + Here the raw signal reaches the DVB 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. + +- Demultiplexer which filters the incoming DVB 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. + +- MPEG2 audio and video decoder + + The main targets of the demultiplexer are the MPEG2 audio and video + decoders. After decoding they pass on the uncompressed audio and + video to the computer screen or (through a PAL/NTSC encoder) to a TV + set. + +:ref:`stb_components` shows a crude schematic of the control and data +flow between those components. + +On a DVB PCI card not all of these have to be present since some +functionality can be provided by the main CPU of the PC (e.g. MPEG +picture and sound decoding) or is not needed (e.g. for data-only uses +like “internet over satellite”). Also not every card or STB provides +conditional access hardware. + + +.. _dvb_devices: + +Linux DVB Devices +================= + +The Linux DVB 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 DVB 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 DVB PCI 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 DVB devices a corresponding include file exists. The DVB +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/intro_files/dvbstb.pdf b/Documentation/media/uapi/dvb/intro_files/dvbstb.pdf new file mode 100644 index 000000000000..0fa75d90c3eb Binary files /dev/null and b/Documentation/media/uapi/dvb/intro_files/dvbstb.pdf differ diff --git a/Documentation/media/uapi/dvb/intro_files/dvbstb.png b/Documentation/media/uapi/dvb/intro_files/dvbstb.png new file mode 100644 index 000000000000..9b8f372e7afd Binary files /dev/null and b/Documentation/media/uapi/dvb/intro_files/dvbstb.png differ diff --git a/Documentation/media/uapi/dvb/legacy_dvb_apis.rst b/Documentation/media/uapi/dvb/legacy_dvb_apis.rst new file mode 100644 index 000000000000..2957f5a988b0 --- /dev/null +++ b/Documentation/media/uapi/dvb/legacy_dvb_apis.rst @@ -0,0 +1,20 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _legacy_dvb_apis: + +******************* +DVB Deprecated APIs +******************* + +The APIs described here are kept only for historical reasons. There's +just one driver for a very legacy hardware that uses this API. No modern +drivers should use it. Instead, audio and video should be using the V4L2 +and ALSA APIs, and the pipelines should be set using the Media +Controller API + + +.. toctree:: + :maxdepth: 1 + + video + audio diff --git a/Documentation/media/uapi/dvb/net-add-if.rst b/Documentation/media/uapi/dvb/net-add-if.rst new file mode 100644 index 000000000000..2b990d0e0fe1 --- /dev/null +++ b/Documentation/media/uapi/dvb/net-add-if.rst @@ -0,0 +1,91 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _NET_ADD_IF: + +**************** +ioctl NET_ADD_IF +**************** + +Name +==== + +NET_ADD_IF - Creates a new network interface for a given Packet ID. + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct dvb_net_if *net_if ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_SET_TONE + +``net_if`` + pointer to struct :ref:`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 :ref:`dvb_net_if `::ifnum field will be +filled with the number of the created interface. + + +.. _dvb-net-if-t: + +struct dvb_net_if description +============================= + +.. _dvb-net-if: + +.. flat-table:: struct dvb_net_if + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - pid + + - Packet ID (PID) of the MPEG-TS that contains data + + - .. row 3 + + - ifnum + + - number of the DVB interface. + + - .. row 4 + + - feedtype + + - Encapsulation type of the feed. It can be: + ``DVB_NET_FEEDTYPE_MPE`` for MPE encoding or + ``DVB_NET_FEEDTYPE_ULE`` for ULE encoding. + + +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/net-get-if.rst b/Documentation/media/uapi/dvb/net-get-if.rst new file mode 100644 index 000000000000..92b884143ccd --- /dev/null +++ b/Documentation/media/uapi/dvb/net-get-if.rst @@ -0,0 +1,50 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 +======== + +.. cpp:function:: int ioctl( int fd, int request, struct dvb_net_if *net_if ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_SET_TONE + +``net_if`` + pointer to struct :ref:`dvb_net_if ` + + +Description +=========== + +The NET_GET_IF ioctl uses the interface number given by the struct +:ref:`dvb_net_if `::ifnum field and fills the content of +struct :ref:`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, 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/net-remove-if.rst b/Documentation/media/uapi/dvb/net-remove-if.rst new file mode 100644 index 000000000000..d374c1d63d06 --- /dev/null +++ b/Documentation/media/uapi/dvb/net-remove-if.rst @@ -0,0 +1,46 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _NET_REMOVE_IF: + +******************* +ioctl NET_REMOVE_IF +******************* + +Name +==== + +NET_REMOVE_IF - Removes a network interface. + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, int ifnum ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + FE_SET_TONE + +``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, 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/net.rst b/Documentation/media/uapi/dvb/net.rst new file mode 100644 index 000000000000..eca42dd53261 --- /dev/null +++ b/Documentation/media/uapi/dvb/net.rst @@ -0,0 +1,40 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _net: + +############### +DVB Network API +############### +The DVB 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: + +###################### +DVB net Function Calls +###################### + +.. toctree:: + :maxdepth: 1 + + net-add-if + net-remove-if + net-get-if diff --git a/Documentation/media/uapi/dvb/net_h.rst b/Documentation/media/uapi/dvb/net_h.rst new file mode 100644 index 000000000000..7bcf5ba9d1eb --- /dev/null +++ b/Documentation/media/uapi/dvb/net_h.rst @@ -0,0 +1,9 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _net_h: + +*********************** +DVB Network Header File +*********************** + +.. kernel-include:: $BUILDDIR/net.h.rst diff --git a/Documentation/media/uapi/dvb/query-dvb-frontend-info.rst b/Documentation/media/uapi/dvb/query-dvb-frontend-info.rst new file mode 100644 index 000000000000..81cd9b92a36c --- /dev/null +++ b/Documentation/media/uapi/dvb/query-dvb-frontend-info.rst @@ -0,0 +1,13 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 +DVB 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 new file mode 100644 index 000000000000..7c85aa06f013 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-clear-buffer.rst @@ -0,0 +1,54 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_CLEAR_BUFFER: + +================== +VIDEO_CLEAR_BUFFER +================== + +Name +---- + +VIDEO_CLEAR_BUFFER + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = 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 new file mode 100644 index 000000000000..b1634f722cbd --- /dev/null +++ b/Documentation/media/uapi/dvb/video-command.rst @@ -0,0 +1,66 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_COMMAND: + +============= +VIDEO_COMMAND +============= + +Name +---- + +VIDEO_COMMAND + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = VIDEO_COMMAND, struct video_command *cmd) + + +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. + + +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 new file mode 100644 index 000000000000..c5acc094986f --- /dev/null +++ b/Documentation/media/uapi/dvb/video-continue.rst @@ -0,0 +1,57 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_CONTINUE: + +============== +VIDEO_CONTINUE +============== + +Name +---- + +VIDEO_CONTINUE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = 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 DVB 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 new file mode 100644 index 000000000000..db338e9f5379 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-fast-forward.rst @@ -0,0 +1,74 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_FAST_FORWARD: + +================== +VIDEO_FAST_FORWARD +================== + +Name +---- + +VIDEO_FAST_FORWARD + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_FAST_FORWARD, int nFrames) + + +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 new file mode 100644 index 000000000000..ebeaade0c351 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-fclose.rst @@ -0,0 +1,54 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _video_fclose: + +================= +dvb video close() +================= + +Name +---- + +dvb video close() + + +Synopsis +-------- + +.. cpp:function:: int close(int fd) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + +Description +----------- + +This system call closes a previously opened 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 new file mode 100644 index 000000000000..9e5471557b83 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-fopen.rst @@ -0,0 +1,112 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _video_fopen: + +================ +dvb video open() +================ + +Name +---- + +dvb video open() + + +Synopsis +-------- + +.. cpp:function:: int open(const char *deviceName, int flags) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - const char \*deviceName + + - Name of specific 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 +------------ + +.. 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 new file mode 100644 index 000000000000..d3d0dc31281a --- /dev/null +++ b/Documentation/media/uapi/dvb/video-freeze.rst @@ -0,0 +1,61 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_FREEZE: + +============ +VIDEO_FREEZE +============ + +Name +---- + +VIDEO_FREEZE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = 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 DVB 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 DVB 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 new file mode 100644 index 000000000000..045038f4181e --- /dev/null +++ b/Documentation/media/uapi/dvb/video-fwrite.rst @@ -0,0 +1,82 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _video_fwrite: + +================= +dvb video write() +================= + +Name +---- + +dvb video write() + + +Synopsis +-------- + +.. cpp:function:: size_t write(int fd, const void *buf, size_t count) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - void \*buf + + - Pointer to the buffer containing the PES data. + + - .. row 3 + + - size_t count + + - Size of buf. + + +Description +----------- + +This system call can only be used if 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 new file mode 100644 index 000000000000..94cbbba478a8 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-get-capabilities.rst @@ -0,0 +1,61 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_GET_CAPABILITIES: + +====================== +VIDEO_GET_CAPABILITIES +====================== + +Name +---- + +VIDEO_GET_CAPABILITIES + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_GET_CAPABILITIES, unsigned int *cap) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals 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 new file mode 100644 index 000000000000..a1484a226518 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-get-event.rst @@ -0,0 +1,88 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_GET_EVENT: + +=============== +VIDEO_GET_EVENT +=============== + +Name +---- + +VIDEO_GET_EVENT + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_GET_EVENT, struct video_event *ev) + + +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 DVB 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. + + +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 new file mode 100644 index 000000000000..4ff100c2ee95 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-get-frame-count.rst @@ -0,0 +1,65 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_GET_FRAME_COUNT: + +===================== +VIDEO_GET_FRAME_COUNT +===================== + +Name +---- + +VIDEO_GET_FRAME_COUNT + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = VIDEO_GET_FRAME_COUNT, __u64 *pts) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals 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-frame-rate.rst b/Documentation/media/uapi/dvb/video-get-frame-rate.rst new file mode 100644 index 000000000000..131def962305 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-get-frame-rate.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_GET_FRAME_RATE: + +==================== +VIDEO_GET_FRAME_RATE +==================== + +Name +---- + +VIDEO_GET_FRAME_RATE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = VIDEO_GET_FRAME_RATE, unsigned int *rate) + + +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_RATE for this command. + + - .. row 3 + + - unsigned int \*rate + + - Returns the framerate in number of frames per 1000 seconds. + + +Description +----------- + +This ioctl call asks the Video Device to return the current framerate. + + +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-navi.rst b/Documentation/media/uapi/dvb/video-get-navi.rst new file mode 100644 index 000000000000..6c3034fe5fa2 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-get-navi.rst @@ -0,0 +1,74 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_GET_NAVI: + +============== +VIDEO_GET_NAVI +============== + +Name +---- + +VIDEO_GET_NAVI + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_GET_NAVI , video_navi_pack_t *navipack) + + +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_NAVI for this command. + + - .. row 3 + + - video_navi_pack_t \*navipack + + - PCI or DSI pack (private stream 2) according to section ??. + + +Description +----------- + +This ioctl returns navigational information from the DVD stream. This is +especially needed if an encoded stream has to be decoded by the +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. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``EFAULT`` + + - driver is not able to return navigational information diff --git a/Documentation/media/uapi/dvb/video-get-pts.rst b/Documentation/media/uapi/dvb/video-get-pts.rst new file mode 100644 index 000000000000..082612243bbb --- /dev/null +++ b/Documentation/media/uapi/dvb/video-get-pts.rst @@ -0,0 +1,69 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_GET_PTS: + +============= +VIDEO_GET_PTS +============= + +Name +---- + +VIDEO_GET_PTS + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = VIDEO_GET_PTS, __u64 *pts) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals 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 new file mode 100644 index 000000000000..c75e3c47c471 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-get-size.rst @@ -0,0 +1,59 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_GET_SIZE: + +============== +VIDEO_GET_SIZE +============== + +Name +---- + +VIDEO_GET_SIZE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = VIDEO_GET_SIZE, video_size_t *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. + + +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 new file mode 100644 index 000000000000..ab9c2236df7e --- /dev/null +++ b/Documentation/media/uapi/dvb/video-get-status.rst @@ -0,0 +1,60 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_GET_STATUS: + +================ +VIDEO_GET_STATUS +================ + +Name +---- + +VIDEO_GET_STATUS + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_GET_STATUS, struct video_status *status) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals 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. + + +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 new file mode 100644 index 000000000000..943c4b755372 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-play.rst @@ -0,0 +1,57 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_PLAY: + +========== +VIDEO_PLAY +========== + +Name +---- + +VIDEO_PLAY + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = 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 DVB 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 new file mode 100644 index 000000000000..0ee0d03dbeb2 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-select-source.rst @@ -0,0 +1,65 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_SELECT_SOURCE: + +=================== +VIDEO_SELECT_SOURCE +=================== + +Name +---- + +VIDEO_SELECT_SOURCE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_SELECT_SOURCE, video_stream_source_t source) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals 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 DVB 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. + + +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-attributes.rst b/Documentation/media/uapi/dvb/video-set-attributes.rst new file mode 100644 index 000000000000..326c5c876e80 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-set-attributes.rst @@ -0,0 +1,75 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_SET_ATTRIBUTES: + +==================== +VIDEO_SET_ATTRIBUTES +==================== + +Name +---- + +VIDEO_SET_ATTRIBUTES + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_ATTRIBUTE ,video_attributes_t vattr) + + +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_ATTRIBUTE for this command. + + - .. row 3 + + - video_attributes_t vattr + + - video attributes according to section ??. + + +Description +----------- + +This ioctl is intended for DVD playback and allows you to set certain +information about the stream. Some hardware may not need this +information, but the call also tells the hardware to prepare for DVD +playback. + + +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`` + + - input is not a valid attribute setting. diff --git a/Documentation/media/uapi/dvb/video-set-blank.rst b/Documentation/media/uapi/dvb/video-set-blank.rst new file mode 100644 index 000000000000..142ea8817380 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-set-blank.rst @@ -0,0 +1,64 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_SET_BLANK: + +=============== +VIDEO_SET_BLANK +=============== + +Name +---- + +VIDEO_SET_BLANK + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_BLANK, boolean mode) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals 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 new file mode 100644 index 000000000000..2061ab064977 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-set-display-format.rst @@ -0,0 +1,60 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_SET_DISPLAY_FORMAT: + +======================== +VIDEO_SET_DISPLAY_FORMAT +======================== + +Name +---- + +VIDEO_SET_DISPLAY_FORMAT + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_DISPLAY_FORMAT, video_display_format_t 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 new file mode 100644 index 000000000000..53d66ec462ca --- /dev/null +++ b/Documentation/media/uapi/dvb/video-set-format.rst @@ -0,0 +1,74 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_SET_FORMAT: + +================ +VIDEO_SET_FORMAT +================ + +Name +---- + +VIDEO_SET_FORMAT + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_FORMAT, video_format_t 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. + + +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-highlight.rst b/Documentation/media/uapi/dvb/video-set-highlight.rst new file mode 100644 index 000000000000..374f5d895b4d --- /dev/null +++ b/Documentation/media/uapi/dvb/video-set-highlight.rst @@ -0,0 +1,60 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_SET_HIGHLIGHT: + +=================== +VIDEO_SET_HIGHLIGHT +=================== + +Name +---- + +VIDEO_SET_HIGHLIGHT + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_HIGHLIGHT ,video_highlight_t *vhilite) + + +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_HIGHLIGHT for this command. + + - .. row 3 + + - video_highlight_t \*vhilite + + - SPU Highlight information according to section ??. + + +Description +----------- + +This ioctl sets the SPU highlight information for the menu access of a +DVD. + + +Return Value +------------ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/media/uapi/dvb/video-set-id.rst b/Documentation/media/uapi/dvb/video-set-id.rst new file mode 100644 index 000000000000..9c002d5399ad --- /dev/null +++ b/Documentation/media/uapi/dvb/video-set-id.rst @@ -0,0 +1,73 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_SET_ID: + +============ +VIDEO_SET_ID +============ + +Name +---- + +VIDEO_SET_ID + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = VIDEO_SET_ID, int id) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals VIDEO_SET_ID for this command. + + - .. row 3 + + - int id + + - video 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. + + +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`` + + - Invalid sub-stream id. diff --git a/Documentation/media/uapi/dvb/video-set-spu-palette.rst b/Documentation/media/uapi/dvb/video-set-spu-palette.rst new file mode 100644 index 000000000000..4b80b6f56219 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-set-spu-palette.rst @@ -0,0 +1,72 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_SET_SPU_PALETTE: + +===================== +VIDEO_SET_SPU_PALETTE +===================== + +Name +---- + +VIDEO_SET_SPU_PALETTE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_SPU_PALETTE, video_spu_palette_t *palette ) + + +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_SPU_PALETTE for this command. + + - .. row 3 + + - video_spu_palette_t \*palette + + - SPU palette according to section ??. + + +Description +----------- + +This ioctl sets the SPU color palette. + + +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`` + + - input is not a valid palette or driver doesn’t handle SPU. diff --git a/Documentation/media/uapi/dvb/video-set-spu.rst b/Documentation/media/uapi/dvb/video-set-spu.rst new file mode 100644 index 000000000000..a6f6924f10c4 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-set-spu.rst @@ -0,0 +1,74 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_SET_SPU: + +============= +VIDEO_SET_SPU +============= + +Name +---- + +VIDEO_SET_SPU + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_SPU , video_spu_t *spu) + + +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_SPU for this command. + + - .. row 3 + + - video_spu_t \*spu + + - SPU decoding (de)activation and subid setting according to section + ??. + + +Description +----------- + +This ioctl activates or deactivates SPU decoding in a DVD input stream. +It can only be used, if the driver is able to handle a DVD 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. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``EINVAL`` + + - input is not a valid spu setting or driver cannot handle SPU. diff --git a/Documentation/media/uapi/dvb/video-set-streamtype.rst b/Documentation/media/uapi/dvb/video-set-streamtype.rst new file mode 100644 index 000000000000..75b2e7a6e829 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-set-streamtype.rst @@ -0,0 +1,61 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_SET_STREAMTYPE: + +==================== +VIDEO_SET_STREAMTYPE +==================== + +Name +---- + +VIDEO_SET_STREAMTYPE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_STREAMTYPE, int type) + + +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-set-system.rst b/Documentation/media/uapi/dvb/video-set-system.rst new file mode 100644 index 000000000000..9ae0df1f5813 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-set-system.rst @@ -0,0 +1,75 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_SET_SYSTEM: + +================ +VIDEO_SET_SYSTEM +================ + +Name +---- + +VIDEO_SET_SYSTEM + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_SET_SYSTEM , video_system_t system) + + +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_system_t system + + - video system of TV output. + + +Description +----------- + +This ioctl sets the television output format. The format (see section +??) may vary from the color format of the displayed MPEG stream. If the +hardware is not able to display the requested format the call will +return an 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. + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``EINVAL`` + + - system is not a valid or supported video system. diff --git a/Documentation/media/uapi/dvb/video-slowmotion.rst b/Documentation/media/uapi/dvb/video-slowmotion.rst new file mode 100644 index 000000000000..905712844f6a --- /dev/null +++ b/Documentation/media/uapi/dvb/video-slowmotion.rst @@ -0,0 +1,74 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_SLOWMOTION: + +================ +VIDEO_SLOWMOTION +================ + +Name +---- + +VIDEO_SLOWMOTION + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_SLOWMOTION, int nFrames) + + +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 new file mode 100644 index 000000000000..ed3a2f53b998 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-stillpicture.rst @@ -0,0 +1,61 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_STILLPICTURE: + +================== +VIDEO_STILLPICTURE +================== + +Name +---- + +VIDEO_STILLPICTURE + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_STILLPICTURE, struct video_still_picture *sp) + + +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 new file mode 100644 index 000000000000..ad8d59e06004 --- /dev/null +++ b/Documentation/media/uapi/dvb/video-stop.rst @@ -0,0 +1,74 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_STOP: + +========== +VIDEO_STOP +========== + +Name +---- + +VIDEO_STOP + + +Synopsis +-------- + +.. cpp:function:: int ioctl(fd, int request = VIDEO_STOP, boolean mode) + + +Arguments +--------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - int fd + + - File descriptor returned by a previous call to open(). + + - .. row 2 + + - int request + + - Equals 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 DVB 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 new file mode 100644 index 000000000000..df96c2d7fc6b --- /dev/null +++ b/Documentation/media/uapi/dvb/video-try-command.rst @@ -0,0 +1,66 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _VIDEO_TRY_COMMAND: + +================= +VIDEO_TRY_COMMAND +================= + +Name +---- + +VIDEO_TRY_COMMAND + + +Synopsis +-------- + +.. cpp:function:: int ioctl(int fd, int request = VIDEO_TRY_COMMAND, struct video_command *cmd) + + +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 new file mode 100644 index 000000000000..60d43fb7ce22 --- /dev/null +++ b/Documentation/media/uapi/dvb/video.rst @@ -0,0 +1,35 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _dvb_video: + +################ +DVB Video Device +################ +The DVB video device controls the MPEG2 video decoder of the DVB +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 DVB 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 DVB 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 new file mode 100644 index 000000000000..68588ac7fecb --- /dev/null +++ b/Documentation/media/uapi/dvb/video_function_calls.rst @@ -0,0 +1,43 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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-frame-rate + 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-set-id + video-clear-buffer + video-set-streamtype + video-set-format + video-set-system + video-set-highlight + video-set-spu + video-set-spu-palette + video-get-navi + video-set-attributes diff --git a/Documentation/media/uapi/dvb/video_h.rst b/Documentation/media/uapi/dvb/video_h.rst new file mode 100644 index 000000000000..3f39b0c4879c --- /dev/null +++ b/Documentation/media/uapi/dvb/video_h.rst @@ -0,0 +1,9 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _video_h: + +********************* +DVB Video Header File +********************* + +.. kernel-include:: $BUILDDIR/video.h.rst diff --git a/Documentation/media/uapi/dvb/video_types.rst b/Documentation/media/uapi/dvb/video_types.rst new file mode 100644 index 000000000000..671f365ceeb4 --- /dev/null +++ b/Documentation/media/uapi/dvb/video_types.rst @@ -0,0 +1,379 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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; + + +.. _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; + + +.. _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 + __kernel_time_t timestamp; + union { + video_size_t size; + unsigned int frame_rate; /* in frames per 1000sec */ + unsigned char vsync_field; /* unknown/odd/even/progressive */ + } u; + }; + + +.. _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 +seleted 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. + + +.. _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 + + +.. _video-system: + +video_system_t +============== + +A call to VIDEO_SET_SYSTEM sets the desired video system for TV +output. The following system types can be set: + + +.. code-block:: c + + typedef enum { + VIDEO_SYSTEM_PAL, + VIDEO_SYSTEM_NTSC, + VIDEO_SYSTEM_PALN, + VIDEO_SYSTEM_PALNc, + VIDEO_SYSTEM_PALM, + VIDEO_SYSTEM_NTSC60, + VIDEO_SYSTEM_PAL60, + VIDEO_SYSTEM_PALM60 + } video_system_t; + + +.. _video-highlight: + +struct video_highlight +====================== + +Calling the ioctl VIDEO_SET_HIGHLIGHTS posts the SPU highlight +information. The call expects the following format for that information: + + +.. code-block:: c + + typedef + struct video_highlight { + boolean active; /* 1=show highlight, 0=hide highlight */ + uint8_t contrast1; /* 7- 4 Pattern pixel contrast */ + /* 3- 0 Background pixel contrast */ + uint8_t contrast2; /* 7- 4 Emphasis pixel-2 contrast */ + /* 3- 0 Emphasis pixel-1 contrast */ + uint8_t color1; /* 7- 4 Pattern pixel color */ + /* 3- 0 Background pixel color */ + uint8_t color2; /* 7- 4 Emphasis pixel-2 color */ + /* 3- 0 Emphasis pixel-1 color */ + uint32_t ypos; /* 23-22 auto action mode */ + /* 21-12 start y */ + /* 9- 0 end y */ + uint32_t xpos; /* 23-22 button color number */ + /* 21-12 start x */ + /* 9- 0 end x */ + } video_highlight_t; + + +.. _video-spu: + +struct video_spu +================ + +Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according +to the following format: + + +.. code-block:: c + + typedef + struct video_spu { + boolean active; + int stream_id; + } video_spu_t; + + +.. _video-spu-palette: + +struct video_spu_palette +======================== + +The following structure is used to set the SPU palette by calling +VIDEO_SPU_PALETTE: + + +.. code-block:: c + + typedef + struct video_spu_palette { + int length; + uint8_t *palette; + } video_spu_palette_t; + + +.. _video-navi-pack: + +struct video_navi_pack +====================== + +In order to get the navigational data the following structure has to be +passed to the ioctl VIDEO_GET_NAVI: + + +.. code-block:: c + + typedef + struct video_navi_pack { + int length; /* 0 ... 1024 */ + uint8_t data[1024]; + } video_navi_pack_t; + + +.. _video-attributes-t: + +video_attributes_t +================== + +The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES: + + +.. code-block:: c + + typedef uint16_t video_attributes_t; + /* bits: descr. */ + /* 15-14 Video compression mode (0=MPEG-1, 1=MPEG-2) */ + /* 13-12 TV system (0=525/60, 1=625/50) */ + /* 11-10 Aspect ratio (0=4:3, 3=16:9) */ + /* 9- 8 permitted display mode on 4:3 monitor (0=both, 1=only pan-sca */ + /* 7 line 21-1 data present in GOP (1=yes, 0=no) */ + /* 6 line 21-2 data present in GOP (1=yes, 0=no) */ + /* 5- 3 source resolution (0=720x480/576, 1=704x480/576, 2=352x480/57 */ + /* 2 source letterboxed (1=yes, 0=no) */ + /* 0 film/camera mode (0=camera, 1=film (625/50 only)) */ diff --git a/Documentation/media/uapi/fdl-appendix.rst b/Documentation/media/uapi/fdl-appendix.rst new file mode 100644 index 000000000000..fd475180fed8 --- /dev/null +++ b/Documentation/media/uapi/fdl-appendix.rst @@ -0,0 +1,471 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 dispbibute +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 new file mode 100644 index 000000000000..6cd5d26f32ab --- /dev/null +++ b/Documentation/media/uapi/gen-errors.rst @@ -0,0 +1,101 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _gen_errors: + +******************* +Generic Error Codes +******************* + + +.. _gen-errors: + +.. flat-table:: Generic error codes + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + + - .. row 1 + + - ``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. + + - .. row 2 + + - ``EBADF`` + + - The file descriptor is not a valid. + + - .. row 3 + + - ``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). + + - .. row 4 + + - ``EFAULT`` + + - There was a failure while copying data from/to userspace, probably + caused by an invalid pointer reference. + + - .. row 5 + + - ``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. + + - .. row 6 + + - ``ENODEV`` + + - Device not found or was removed. + + - .. row 7 + + - ``ENOMEM`` + + - There's not enough memory to handle the desired operation. + + - .. row 8 + + - ``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. + + - .. row 9 + + - ``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). + + - .. row 10 + + - ``EPERM`` + + - Permission denied. Can be returned if the device needs write + permission, or some special capabilities is needed (e. g. root) + + +Note 1: ioctls may return other error codes. Since errors may have side +effects such as a driver reset, applications should abort on unexpected +errors. + +Note 2: 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 new file mode 100644 index 000000000000..3e776c0d8276 --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-controller-intro.rst @@ -0,0 +1,33 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 new file mode 100644 index 000000000000..558273cf9570 --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-controller-model.rst @@ -0,0 +1,35 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 new file mode 100644 index 000000000000..8758308997a7 --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-controller.rst @@ -0,0 +1,73 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. include:: + +.. _media_common: + +#################### +Media Controller API +#################### + +.. _media_controller: + +**************** +Media Controller +**************** + + +.. toctree:: + :maxdepth: 1 + :numbered: + + media-controller-intro + media-controller-model + media-types + + +.. _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 + + +********************** +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 new file mode 100644 index 000000000000..39ef70ac8656 --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-func-close.rst @@ -0,0 +1,47 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-func-close: + +************* +media close() +************* + +Name +==== + +media-close - Close a media device + + +Synopsis +======== + +.. code-block:: c + + #include + + +.. cpp:function:: int close( int fd ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`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 new file mode 100644 index 000000000000..9d1b23133edf --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-func-ioctl.rst @@ -0,0 +1,67 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-func-ioctl: + +************* +media ioctl() +************* + +Name +==== + +media-ioctl - Control a media device + + +Synopsis +======== + +.. code-block:: c + + #include + + +.. cpp:function:: int ioctl( int fd, int request, void *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`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 new file mode 100644 index 000000000000..2b2ecd85b995 --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-func-open.rst @@ -0,0 +1,69 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-func-open: + +************ +media open() +************ + +Name +==== + +media-open - Open a media device + + +Synopsis +======== + +.. code-block:: c + + #include + + +.. cpp:function:: int open( const char *device_name, int flags ) + + +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-ioc-device-info.rst b/Documentation/media/uapi/mediactl/media-ioc-device-info.rst new file mode 100644 index 000000000000..cee8312bde7d --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-ioc-device-info.rst @@ -0,0 +1,142 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-ioc-device-info: + +*************************** +ioctl MEDIA_IOC_DEVICE_INFO +*************************** + +Name +==== + +MEDIA_IOC_DEVICE_INFO - Query device information + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct media_device_info *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + MEDIA_IOC_DEVICE_INFO + +``argp`` + + +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 :ref:`media_device_info `. The driver +fills the structure and returns the information to the application. The +ioctl never fails. + + +.. _media-device-info: + +.. flat-table:: struct media_device_info + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - 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. + + - .. row 2 + + - 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. + + - .. row 3 + + - char + + - ``serial``\ [40] + + - Serial number as a NUL-terminated ASCII string. + + - .. row 4 + + - 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. + + - .. row 5 + + - __u32 + + - ``media_version`` + + - Media API version, formatted with the ``KERNEL_VERSION()`` macro. + + - .. row 6 + + - __u32 + + - ``hw_revision`` + + - Hardware device revision in a driver-specific format. + + - .. row 7 + + - __u32 + + - ``driver_version`` + + - Media device driver version, formatted with the + ``KERNEL_VERSION()`` macro. Together with the ``driver`` field + this identifies a particular driver. + + - .. row 8 + + - __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 new file mode 100644 index 000000000000..ae88f46b3a9e --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-ioc-enum-entities.rst @@ -0,0 +1,197 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-ioc-enum-entities: + +***************************** +ioctl MEDIA_IOC_ENUM_ENTITIES +***************************** + +Name +==== + +MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct media_entity_desc *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + MEDIA_IOC_ENUM_ENTITIES + +``argp`` + + +Description +=========== + +To query the attributes of an entity, applications set the id field of a +struct :ref:`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. + +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. + + +.. _media-entity-desc: + +.. flat-table:: struct media_entity_desc + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 1 8 + + + - .. row 1 + + - __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. + + - .. row 2 + + - char + + - ``name``\ [32] + + - + - + - Entity name as an UTF-8 NULL-terminated string. + + - .. row 3 + + - __u32 + + - ``type`` + + - + - + - Entity type, see :ref:`media-entity-type` for details. + + - .. row 4 + + - __u32 + + - ``revision`` + + - + - + - Entity revision. Always zero (obsolete) + + - .. row 5 + + - __u32 + + - ``flags`` + + - + - + - Entity flags, see :ref:`media-entity-flag` for details. + + - .. row 6 + + - __u32 + + - ``group_id`` + + - + - + - Entity group ID. Always zero (obsolete) + + - .. row 7 + + - __u16 + + - ``pads`` + + - + - + - Number of pads + + - .. row 8 + + - __u16 + + - ``links`` + + - + - + - Total number of outbound links. Inbound links are not counted in + this field. + + - .. row 9 + + - union + + - .. row 10 + + - + - struct + + - ``dev`` + + - + - Valid for (sub-)devices that create a single device node. + + - .. row 11 + + - + - + - __u32 + + - ``major`` + + - Device node major number. + + - .. row 12 + + - + - + - __u32 + + - ``minor`` + + - Device node minor number. + + - .. row 13 + + - + - __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 :ref:`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 new file mode 100644 index 000000000000..cc3cc3d2400b --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-ioc-enum-links.rst @@ -0,0 +1,172 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-ioc-enum-links: + +************************** +ioctl MEDIA_IOC_ENUM_LINKS +************************** + +Name +==== + +MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct media_links_enum *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + MEDIA_IOC_ENUM_LINKS + +``argp`` + + +Description +=========== + +To enumerate pads and/or links for a given entity, applications set the +entity field of a struct :ref:`media_links_enum ` +structure and initialize the struct +:ref:`media_pad_desc ` and struct +:ref:`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 the :ref:`MEDIA_IOC_ENUM_ENTITIES ` +ioctl. + +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 the +:ref:`MEDIA_IOC_ENUM_ENTITIES ` ioctl. + +Only forward links that originate at one of the entity's source pads are +returned during the enumeration process. + + +.. _media-links-enum: + +.. flat-table:: struct media_links_enum + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``entity`` + + - Entity id, set by the application. + + - .. row 2 + + - struct :ref:`media_pad_desc ` + + - \*\ ``pads`` + + - Pointer to a pads array allocated by the application. Ignored if + NULL. + + - .. row 3 + + - struct :ref:`media_link_desc ` + + - \*\ ``links`` + + - Pointer to a links array allocated by the application. Ignored if + NULL. + + + +.. _media-pad-desc: + +.. flat-table:: struct media_pad_desc + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``entity`` + + - ID of the entity this pad belongs to. + + - .. row 2 + + - __u16 + + - ``index`` + + - 0-based pad index. + + - .. row 3 + + - __u32 + + - ``flags`` + + - Pad flags, see :ref:`media-pad-flag` for more details. + + + +.. _media-link-desc: + +.. flat-table:: struct media_link_desc + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - struct :ref:`media_pad_desc ` + + - ``source`` + + - Pad at the origin of this link. + + - .. row 2 + + - struct :ref:`media_pad_desc ` + + - ``sink`` + + - Pad at the target of this link. + + - .. row 3 + + - __u32 + + - ``flags`` + + - Link flags, see :ref:`media-link-flag` for more details. + + +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 :ref:`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 new file mode 100644 index 000000000000..1f2d530aa284 --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-ioc-g-topology.rst @@ -0,0 +1,377 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-g-topology: + +************************** +ioctl MEDIA_IOC_G_TOPOLOGY +************************** + +Name +==== + +MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct media_v2_topology *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + MEDIA_IOC_G_TOPOLOGY + +``argp`` + + +Description +=========== + +The typical usage of this ioctl is to call it twice. On the first call, +the structure defined at struct +:ref:`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. + + +.. _media-v2-topology: + +.. flat-table:: struct media_v2_topology + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + + - .. row 1 + + - __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. + + - .. row 2 + + - __u64 + + - ``num_entities`` + + - Number of entities in the graph + + - .. row 3 + + - __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`` + + - .. row 4 + + - __u64 + + - ``num_interfaces`` + + - Number of interfaces in the graph + + - .. row 5 + + - __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`` + + - .. row 6 + + - __u64 + + - ``num_pads`` + + - Total number of pads in the graph + + - .. row 7 + + - __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`` + + - .. row 8 + + - __u64 + + - ``num_links`` + + - Total number of data and interface links in the graph + + - .. row 9 + + - __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`` + + + +.. _media-v2-entity: + +.. flat-table:: struct media_v2_entity + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + + - .. row 1 + + - __u32 + + - ``id`` + + - Unique ID for the entity. + + - .. row 2 + + - char + + - ``name``\ [64] + + - Entity name as an UTF-8 NULL-terminated string. + + - .. row 3 + + - __u32 + + - ``function`` + + - Entity main function, see :ref:`media-entity-type` for details. + + - .. row 4 + + - __u32 + + - ``reserved``\ [12] + + - Reserved for future extensions. Drivers and applications must set + this array to zero. + + + +.. _media-v2-interface: + +.. flat-table:: struct media_v2_interface + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + - .. row 1 + + - __u32 + + - ``id`` + + - Unique ID for the interface. + + - .. row 2 + + - __u32 + + - ``intf_type`` + + - Interface type, see :ref:`media-intf-type` for details. + + - .. row 3 + + - __u32 + + - ``flags`` + + - Interface flags. Currently unused. + + - .. row 4 + + - __u32 + + - ``reserved``\ [9] + + - Reserved for future extensions. Drivers and applications must set + this array to zero. + + - .. row 5 + + - struct media_v2_intf_devnode + + - ``devnode`` + + - Used only for device node interfaces. See + :ref:`media-v2-intf-devnode` for details.. + + + +.. _media-v2-intf-devnode: + +.. flat-table:: struct media_v2_interface + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + + - .. row 1 + + - __u32 + + - ``major`` + + - Device node major number. + + - .. row 2 + + - __u32 + + - ``minor`` + + - Device node minor number. + + + +.. _media-v2-pad: + +.. flat-table:: struct media_v2_pad + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + + - .. row 1 + + - __u32 + + - ``id`` + + - Unique ID for the pad. + + - .. row 2 + + - __u32 + + - ``entity_id`` + + - Unique ID for the entity where this pad belongs. + + - .. row 3 + + - __u32 + + - ``flags`` + + - Pad flags, see :ref:`media-pad-flag` for more details. + + - .. row 4 + + - __u32 + + - ``reserved``\ [9] + + - Reserved for future extensions. Drivers and applications must set + this array to zero. + + + +.. _media-v2-link: + +.. flat-table:: struct media_v2_pad + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + + - .. row 1 + + - __u32 + + - ``id`` + + - Unique ID for the pad. + + - .. row 2 + + - __u32 + + - ``source_id`` + + - On pad to pad links: unique ID for the source pad. + + On interface to entity links: unique ID for the interface. + + - .. row 3 + + - __u32 + + - ``sink_id`` + + - On pad to pad links: unique ID for the sink pad. + + On interface to entity links: unique ID for the entity. + + - .. row 4 + + - __u32 + + - ``flags`` + + - Link flags, see :ref:`media-link-flag` for more details. + + - .. row 5 + + - __u32 + + - ``reserved``\ [5] + + - 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-setup-link.rst b/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst new file mode 100644 index 000000000000..57ae5bcc646a --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-ioc-setup-link.rst @@ -0,0 +1,68 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-ioc-setup-link: + +************************** +ioctl MEDIA_IOC_SETUP_LINK +************************** + +Name +==== + +MEDIA_IOC_SETUP_LINK - Modify the properties of a link + + +Synopsis +======== + +.. cpp:function:: int ioctl( int fd, int request, struct media_link_desc *argp ) + + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`open() `. + +``request`` + MEDIA_IOC_SETUP_LINK + +``argp`` + + +Description +=========== + +To change link properties applications fill a struct +:ref:`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 :ref:`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-types.rst b/Documentation/media/uapi/mediactl/media-types.rst new file mode 100644 index 000000000000..a35fc15a3137 --- /dev/null +++ b/Documentation/media/uapi/mediactl/media-types.rst @@ -0,0 +1,422 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _media-controller-types: + +Types and flags used to represent the media graph elements +========================================================== + + +.. _media-entity-type: + +.. flat-table:: Media entity types + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``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, with is a Kernel bug + + - .. row 2 + + - ``MEDIA_ENT_F_IO_V4L`` + + - Data streaming input and/or output entity. + + - .. row 3 + + - ``MEDIA_ENT_F_IO_VBI`` + + - V4L VBI streaming input or output entity + + - .. row 4 + + - ``MEDIA_ENT_F_IO_SWRADIO`` + + - V4L Software Digital Radio (SDR) streaming input or output entity + + - .. row 5 + + - ``MEDIA_ENT_F_IO_DTV`` + + - DVB Digital TV streaming input or output entity + + - .. row 6 + + - ``MEDIA_ENT_F_DTV_DEMOD`` + + - Digital TV demodulator entity. + + - .. row 7 + + - ``MEDIA_ENT_F_TS_DEMUX`` + + - MPEG Transport stream demux entity. Could be implemented on + hardware or in Kernelspace by the Linux DVB subsystem. + + - .. row 8 + + - ``MEDIA_ENT_F_DTV_CA`` + + - Digital TV Conditional Access module (CAM) entity + + - .. row 9 + + - ``MEDIA_ENT_F_DTV_NET_DECAP`` + + - Digital TV network ULE/MLE desencapsulation entity. Could be + implemented on hardware or in Kernelspace + + - .. row 10 + + - ``MEDIA_ENT_F_CONN_RF`` + + - Connector for a Radio Frequency (RF) signal. + + - .. row 11 + + - ``MEDIA_ENT_F_CONN_SVIDEO`` + + - Connector for a S-Video signal. + + - .. row 12 + + - ``MEDIA_ENT_F_CONN_COMPOSITE`` + + - Connector for a RGB composite signal. + + - .. row 13 + + - ``MEDIA_ENT_F_CAM_SENSOR`` + + - Camera video sensor entity. + + - .. row 14 + + - ``MEDIA_ENT_F_FLASH`` + + - Flash controller entity. + + - .. row 15 + + - ``MEDIA_ENT_F_LENS`` + + - Lens controller entity. + + - .. row 16 + + - ``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. + + - .. row 17 + + - ``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. + + - .. row 18 + + - ``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. + + - .. row 19 + + - ``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. + + - .. row 20 + + - ``MEDIA_ENT_F_AUDIO_CAPTURE`` + + - Audio Capture Function Entity. + + - .. row 21 + + - ``MEDIA_ENT_F_AUDIO_PLAYBACK`` + + - Audio Playback Function Entity. + + - .. row 22 + + - ``MEDIA_ENT_F_AUDIO_MIXER`` + + - Audio Mixer Function Entity. + + + +.. _media-entity-flag: + +.. flat-table:: Media entity flags + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``MEDIA_ENT_FL_DEFAULT`` + + - Default entity for its type. Used to discover the default audio, + VBI and video devices, the default camera sensor, ... + + - .. row 2 + + - ``MEDIA_ENT_FL_CONNECTOR`` + + - The entity represents a data conector + + + +.. _media-intf-type: + +.. flat-table:: Media interface types + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``MEDIA_INTF_T_DVB_FE`` + + - Device node interface for the Digital TV frontend + + - typically, /dev/dvb/adapter?/frontend? + + - .. row 2 + + - ``MEDIA_INTF_T_DVB_DEMUX`` + + - Device node interface for the Digital TV demux + + - typically, /dev/dvb/adapter?/demux? + + - .. row 3 + + - ``MEDIA_INTF_T_DVB_DVR`` + + - Device node interface for the Digital TV DVR + + - typically, /dev/dvb/adapter?/dvr? + + - .. row 4 + + - ``MEDIA_INTF_T_DVB_CA`` + + - Device node interface for the Digital TV Conditional Access + + - typically, /dev/dvb/adapter?/ca? + + - .. row 5 + + - ``MEDIA_INTF_T_DVB_FE`` + + - Device node interface for the Digital TV network control + + - typically, /dev/dvb/adapter?/net? + + - .. row 6 + + - ``MEDIA_INTF_T_V4L_VIDEO`` + + - Device node interface for video (V4L) + + - typically, /dev/video? + + - .. row 7 + + - ``MEDIA_INTF_T_V4L_VBI`` + + - Device node interface for VBI (V4L) + + - typically, /dev/vbi? + + - .. row 8 + + - ``MEDIA_INTF_T_V4L_RADIO`` + + - Device node interface for radio (V4L) + + - typically, /dev/vbi? + + - .. row 9 + + - ``MEDIA_INTF_T_V4L_SUBDEV`` + + - Device node interface for a V4L subdevice + + - typically, /dev/v4l-subdev? + + - .. row 10 + + - ``MEDIA_INTF_T_V4L_SWRADIO`` + + - Device node interface for Software Defined Radio (V4L) + + - typically, /dev/swradio? + + - .. row 11 + + - ``MEDIA_INTF_T_ALSA_PCM_CAPTURE`` + + - Device node interface for ALSA PCM Capture + + - typically, /dev/snd/pcmC?D?c + + - .. row 12 + + - ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK`` + + - Device node interface for ALSA PCM Playback + + - typically, /dev/snd/pcmC?D?p + + - .. row 13 + + - ``MEDIA_INTF_T_ALSA_CONTROL`` + + - Device node interface for ALSA Control + + - typically, /dev/snd/controlC? + + - .. row 14 + + - ``MEDIA_INTF_T_ALSA_COMPRESS`` + + - Device node interface for ALSA Compress + + - typically, /dev/snd/compr? + + - .. row 15 + + - ``MEDIA_INTF_T_ALSA_RAWMIDI`` + + - Device node interface for ALSA Raw MIDI + + - typically, /dev/snd/midi? + + - .. row 16 + + - ``MEDIA_INTF_T_ALSA_HWDEP`` + + - Device node interface for ALSA Hardware Dependent + + - typically, /dev/snd/hwC?D? + + - .. row 17 + + - ``MEDIA_INTF_T_ALSA_SEQUENCER`` + + - Device node interface for ALSA Sequencer + + - typically, /dev/snd/seq + + - .. row 18 + + - ``MEDIA_INTF_T_ALSA_TIMER`` + + - Device node interface for ALSA Timer + + - typically, /dev/snd/timer + + + +.. _media-pad-flag: + +.. flat-table:: Media pad flags + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``MEDIA_PAD_FL_SINK`` + + - Input pad, relative to the entity. Input pads sink data and are + targets of links. + + - .. row 2 + + - ``MEDIA_PAD_FL_SOURCE`` + + - Output pad, relative to the entity. Output pads source data and + are origins of links. + + - .. row 3 + + - ``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. + + +.. _media-link-flag: + +.. flat-table:: Media link flags + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``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. + + - .. row 2 + + - ``MEDIA_LNK_FL_IMMUTABLE`` + + - The link enabled state can't be modified at runtime. An immutable + link is always enabled. + + - .. row 3 + + - ``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. + + - .. row 4 + + - ``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`` if the link is between two pads + + ``MEDIA_LNK_FL_INTERFACE_LINK`` if the link is between an + interface and an entity diff --git a/Documentation/media/uapi/rc/Remote_controllers_Intro.rst b/Documentation/media/uapi/rc/Remote_controllers_Intro.rst new file mode 100644 index 000000000000..3707c29d37ed --- /dev/null +++ b/Documentation/media/uapi/rc/Remote_controllers_Intro.rst @@ -0,0 +1,24 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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/Remote_controllers_table_change.rst b/Documentation/media/uapi/rc/Remote_controllers_table_change.rst new file mode 100644 index 000000000000..d604896bca87 --- /dev/null +++ b/Documentation/media/uapi/rc/Remote_controllers_table_change.rst @@ -0,0 +1,18 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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/Remote_controllers_tables.rst b/Documentation/media/uapi/rc/Remote_controllers_tables.rst new file mode 100644 index 000000000000..0bb16c4af27d --- /dev/null +++ b/Documentation/media/uapi/rc/Remote_controllers_tables.rst @@ -0,0 +1,757 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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: + +.. 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_0`` + + - Keyboard digit 0 + + - 0 + + - .. row 4 + + - ``KEY_1`` + + - Keyboard digit 1 + + - 1 + + - .. row 5 + + - ``KEY_2`` + + - Keyboard digit 2 + + - 2 + + - .. row 6 + + - ``KEY_3`` + + - Keyboard digit 3 + + - 3 + + - .. row 7 + + - ``KEY_4`` + + - Keyboard digit 4 + + - 4 + + - .. row 8 + + - ``KEY_5`` + + - Keyboard digit 5 + + - 5 + + - .. row 9 + + - ``KEY_6`` + + - Keyboard digit 6 + + - 6 + + - .. row 10 + + - ``KEY_7`` + + - Keyboard digit 7 + + - 7 + + - .. row 11 + + - ``KEY_8`` + + - Keyboard digit 8 + + - 8 + + - .. row 12 + + - ``KEY_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 sroweam + + - 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 sroweam + + - STOP + + - .. row 25 + + - ``KEY_RECORD`` + + - Start/stop recording sroweam + + - 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 sequencially + + - CHANNEL - / CHANNEL DOWN / DOWN + + - .. row 47 + + - ``KEY_CHANNELUP`` + + - Increase channel sequencially + + - 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 sroweam 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 sroweam 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_SCREEN`` + + - Select screen aspect ratio + + - 4:3 16:9 SELECT + + - .. row 79 + + - ``KEY_ZOOM`` + + - 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/keytable.c.rst b/Documentation/media/uapi/rc/keytable.c.rst new file mode 100644 index 000000000000..e6ce1e3f5a78 --- /dev/null +++ b/Documentation/media/uapi/rc/keytable.c.rst @@ -0,0 +1,176 @@ +.. -*- coding: utf-8; mode: rst -*- + +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 new file mode 100644 index 000000000000..9a784c8fe4ea --- /dev/null +++ b/Documentation/media/uapi/rc/lirc_dev_intro.rst @@ -0,0 +1,28 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _lirc_dev_intro: + +************ +Introduction +************ + +The LIRC device interface is a bi-directional interface for transporting +raw IR 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 data to and fro, the essential fops are read, write and ioctl. + +Example dmesg output upon a driver registering w/LIRC: + +.. code-block:: none + + $ dmesg |grep lirc_dev + lirc_dev: IR Remote Control driver registered, major 248 + rc rc0: lirc_dev: driver ir-lirc-codec (mceusb) registered at minor = 0 + +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 diff --git a/Documentation/media/uapi/rc/lirc_device_interface.rst b/Documentation/media/uapi/rc/lirc_device_interface.rst new file mode 100644 index 000000000000..a0c27ed5ad73 --- /dev/null +++ b/Documentation/media/uapi/rc/lirc_device_interface.rst @@ -0,0 +1,15 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _lirc_dev: + +LIRC Device Interface +===================== + + +.. toctree:: + :maxdepth: 1 + + lirc_dev_intro + lirc_read + lirc_write + lirc_ioctl diff --git a/Documentation/media/uapi/rc/lirc_ioctl.rst b/Documentation/media/uapi/rc/lirc_ioctl.rst new file mode 100644 index 000000000000..916d064476f1 --- /dev/null +++ b/Documentation/media/uapi/rc/lirc_ioctl.rst @@ -0,0 +1,156 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _lirc_ioctl: + +************** +LIRC ioctl fop +************** + +The LIRC device's ioctl definition is bound by the ioctl function +definition of struct file_operations, leaving us with an unsigned int +for the ioctl command and an unsigned long for the arg. For the purposes +of ioctl portability across 32-bit and 64-bit, these values are capped +to their 32-bit sizes. + +The following ioctls can be used to change specific hardware settings. +In general each driver should have a default set of settings. The driver +implementation is expected to re-apply the default settings when the +device is closed by user-space, so that every application opening the +device can rely on working with the default settings initially. + +LIRC_GET_FEATURES + Obviously, 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_GET_SEND_MODE + Get supported transmit mode. Only LIRC_MODE_PULSE is supported by + lircd. + +LIRC_GET_REC_MODE + Get supported receive modes. Only LIRC_MODE_MODE2 and + LIRC_MODE_LIRCCODE are supported by lircd. + +LIRC_GET_SEND_CARRIER + Get carrier frequency (in Hz) currently used for transmit. + +LIRC_GET_REC_CARRIER + Get carrier frequency (in Hz) currently used for IR reception. + +LIRC_{G,S}ET_{SEND,REC}_DUTY_CYCLE + Get/set the duty cycle (from 0 to 100) of the carrier signal. + 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. + +LIRC_GET_REC_RESOLUTION + Some receiver have maximum resolution which is defined by internal + sample rate or data format limitations. E.g. it's common that + signals can only be reported in 50 microsecond steps. This integer + value is used by lircd to automatically adjust the aeps tolerance + value in the lircd config file. + +LIRC_GET_M{IN,AX}_TIMEOUT + 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. Some devices have a fixed timeout, in that case + both ioctls will return the same value even though the timeout + cannot be changed. + +LIRC_GET_M{IN,AX}_FILTER_{PULSE,SPACE} + Some devices are able to filter out spikes in the incoming signal + using given filter rules. These ioctls return the hardware + capabilities that describe the bounds of the possible filters. + Filter settings depend on the IR protocols that are expected. lircd + derives the settings from all protocols definitions found in its + config file. + +LIRC_GET_LENGTH + Retrieves the code length in bits (only for LIRC_MODE_LIRCCODE). + Reads on the device must be done in blocks matching the bit count. + The bit could should be rounded up so that it matches full bytes. + +LIRC_SET_{SEND,REC}_MODE + Set send/receive mode. Largely obsolete for send, as only + LIRC_MODE_PULSE is supported. + +LIRC_SET_{SEND,REC}_CARRIER + Set send/receive carrier (in Hz). + +LIRC_SET_TRANSMITTER_MASK + This enables the given set of transmitters. The first transmitter is + encoded by the least significant bit, etc. 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. + +LIRC_SET_REC_TIMEOUT + Sets the integer value for IR inactivity timeout (cf. + LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT). A value of 0 + (if supported by the hardware) 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. + +LIRC_SET_REC_TIMEOUT_REPORTS + Enable (1) or disable (0) timeout reports in LIRC_MODE_MODE2. By + default, timeout reports should be turned off. + +LIRC_SET_REC_FILTER_{,PULSE,SPACE} + Pulses/spaces shorter than this are filtered out by hardware. If + filters cannot be set independently for pulse/space, the + corresponding ioctls must return an error and LIRC_SET_REC_FILTER + shall be used instead. + +LIRC_SET_MEASURE_CARRIER_MODE + Enable (1)/disable (0) 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. + +LIRC_SET_REC_{DUTY_CYCLE,CARRIER}_RANGE + To set a range use + LIRC_SET_REC_DUTY_CYCLE_RANGE/LIRC_SET_REC_CARRIER_RANGE + with the lower bound first and later + LIRC_SET_REC_DUTY_CYCLE/LIRC_SET_REC_CARRIER with the upper + bound. + +LIRC_NOTIFY_DECODE + This ioctl is called by lircd whenever a successful decoding of an + incoming IR signal could be done. This can be used by supporting + hardware to give visual feedback to the user e.g. by flashing a LED. + +LIRC_SETUP_{START,END} + Setting of several driver parameters can be optimized by + encapsulating the according ioctl calls with + LIRC_SETUP_START/LIRC_SETUP_END. When a driver receives a + LIRC_SETUP_START ioctl it can choose to not commit further setting + changes to the hardware until a LIRC_SETUP_END is received. But + this is open to the driver implementation and every driver must also + handle parameter changes which are not encapsulated by + LIRC_SETUP_START and LIRC_SETUP_END. Drivers can also choose to + ignore these ioctls. + +LIRC_SET_WIDEBAND_RECEIVER + Some receivers are equipped with special wide band receiver which is + intended to be used to learn output of existing remote. Calling that + ioctl with (1) will enable it, and with (0) disable 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. + + +.. _lirc_dev_errors: + +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_read.rst b/Documentation/media/uapi/rc/lirc_read.rst new file mode 100644 index 000000000000..b0b76c3d1d9a --- /dev/null +++ b/Documentation/media/uapi/rc/lirc_read.rst @@ -0,0 +1,19 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _lirc_read: + +************* +LIRC read fop +************* + +The lircd userspace daemon reads raw IR data from the LIRC chardev. The +exact format of the data depends on what modes a driver supports, and +what mode has been selected. lircd obtains supported modes and sets the +active mode via the ioctl interface, detailed at :ref:`lirc_ioctl`. +The generally preferred mode is LIRC_MODE_MODE2, in which packets +containing an int value describing an IR signal are read from the +chardev. + +See also +`http://www.lirc.org/html/technical.html `__ +for more info. diff --git a/Documentation/media/uapi/rc/lirc_write.rst b/Documentation/media/uapi/rc/lirc_write.rst new file mode 100644 index 000000000000..d19cb486ecc9 --- /dev/null +++ b/Documentation/media/uapi/rc/lirc_write.rst @@ -0,0 +1,14 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _lirc_write: + +************** +LIRC write fop +************** + +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 must +block until the data has been transmitted by the hardware. If more data +is provided than the hardware can send, the driver returns ``EINVAL``. diff --git a/Documentation/media/uapi/rc/remote_controllers.rst b/Documentation/media/uapi/rc/remote_controllers.rst new file mode 100644 index 000000000000..bccceb1e28c3 --- /dev/null +++ b/Documentation/media/uapi/rc/remote_controllers.rst @@ -0,0 +1,52 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. include:: + +.. _remotes: + +##################### +Remote Controller API +##################### + +.. _remote_controllers: + +****************** +Remote Controllers +****************** + + +.. toctree:: + :maxdepth: 1 + :numbered: + + Remote_controllers_Intro + remote_controllers_sysfs_nodes + Remote_controllers_tables + Remote_controllers_table_change + lirc_device_interface + + +********************** +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/rc/remote_controllers_sysfs_nodes.rst b/Documentation/media/uapi/rc/remote_controllers_sysfs_nodes.rst new file mode 100644 index 000000000000..6fb944fe21fd --- /dev/null +++ b/Documentation/media/uapi/rc/remote_controllers_sysfs_nodes.rst @@ -0,0 +1,143 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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: + +``rc5 rc6 nec jvc [sony]`` + +The enabled wakeup protocol is shown in [] brackets. + +Writing "+proto" will add a protocol to the list of enabled wakeup +protocols. + +Writing "-proto" will remove a protocol from the list of enabled wakeup +protocols. + +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/v4l/app-pri.rst b/Documentation/media/uapi/v4l/app-pri.rst new file mode 100644 index 000000000000..a8c41a7ec396 --- /dev/null +++ b/Documentation/media/uapi/v4l/app-pri.rst @@ -0,0 +1,30 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 new file mode 100644 index 000000000000..5affc0adb95b --- /dev/null +++ b/Documentation/media/uapi/v4l/async.rst @@ -0,0 +1,9 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 new file mode 100644 index 000000000000..71502f0bf8bd --- /dev/null +++ b/Documentation/media/uapi/v4l/audio.rst @@ -0,0 +1,90 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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. [1]_ 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 +:ref:`v4l2_input ` or struct +:ref:`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 :ref:`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 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 :ref:`v4l2_capability ` returned by +the :ref:`VIDIOC_QUERYCAP` ioctl. + + +.. code-block:: c + :caption: Example 1.3. Information about the current audio input + + 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); + + +.. code-block:: c + :caption: Example 1.4. Switching to the first audio input + + 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); + } + +.. [1] + Actually struct :ref:`v4l2_audio ` ought to have a + ``tuner`` field like struct :ref:`v4l2_input `, not + only making the API more consistent but also permitting radio devices + with multiple tuners. diff --git a/Documentation/media/uapi/v4l/biblio.rst b/Documentation/media/uapi/v4l/biblio.rst new file mode 100644 index 000000000000..e911df972d40 --- /dev/null +++ b/Documentation/media/uapi/v4l/biblio.rst @@ -0,0 +1,381 @@ +.. -*- coding: utf-8; mode: rst -*- + +********** +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) + +.. _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) + +.. _adobergb: + +AdobeRGB +======== + + +:title: Adobe© RGB (1998) Color Image Encoding Version 2005-05 + +:author: Adobe Systems Incorporated (http://www.adobe.com) + +.. _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) + +.. _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. diff --git a/Documentation/media/uapi/v4l/buffer.rst b/Documentation/media/uapi/v4l/buffer.rst new file mode 100644 index 000000000000..b195eb5b63a1 --- /dev/null +++ b/Documentation/media/uapi/v4l/buffer.rst @@ -0,0 +1,979 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 :ref:`struct 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 :ref:`struct v4l2_buffer `, +such as pointers and sizes for each plane, are stored in struct +:ref:`struct v4l2_plane ` instead. In that case, struct +:ref:`struct 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. + + +.. _v4l2-buffer: + +struct v4l2_buffer +================== + +.. flat-table:: struct v4l2_buffer + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 2 + + + - .. row 1 + + - __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 :ref:`v4l2_requestbuffers ` + ``count``), plus any buffers allocated with + :ref:`VIDIOC_CREATE_BUFS` minus one. + + - .. row 2 + + - __u32 + + - ``type`` + + - + - Type of the buffer, same as struct + :ref:`v4l2_format ` ``type`` or struct + :ref:`v4l2_requestbuffers ` ``type``, set + by the application. See :ref:`v4l2-buf-type` + + - .. row 3 + + - __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. + + - .. row 4 + + - __u32 + + - ``flags`` + + - + - Flags set by the application or driver, see :ref:`buffer-flags`. + + - .. row 5 + + - __u32 + + - ``field`` + + - + - Indicates the field order of the image in the buffer, see + :ref:`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. + + - .. row 6 + + - 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. + + - .. row 7 + + - struct :ref:`v4l2_timecode ` + + - ``timecode`` + + - + - When ``type`` is ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` and the + ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this + structure contains a frame timecode. In + :ref:`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. + + - .. row 8 + + - __u32 + + - ``sequence`` + + - + - Set by the driver, counting the frames (not fields!) in sequence. + This field is set for both input and output devices. + + - .. row 9 + + - :cspan:`3` + + In :ref:`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`. + + - .. row 10 + + - __u32 + + - ``memory`` + + - + - This field must be set by applications and/or drivers in + accordance with the selected I/O method. See :ref:`v4l2-memory` + + - .. row 11 + + - union + + - ``m`` + + - .. row 12 + + - + - __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 + + - .. row 13 + + - + - 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. + + - .. row 14 + + - + - struct v4l2_plane + + - ``*planes`` + + - When using the multi-planar API, contains a userspace pointer to + an array of struct :ref:`v4l2_plane `. The size of + the array should be put in the ``length`` field of this + :ref:`struct v4l2_buffer ` structure. + + - .. row 15 + + - + - int + + - ``fd`` + + - For the single-plane API and when ``memory`` is + ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with + a DMABUF buffer. + + - .. row 16 + + - __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. + + - .. row 17 + + - __u32 + + - ``reserved2`` + + - + - A place holder for future extensions. Drivers and applications + must set this to 0. + + - .. row 18 + + - __u32 + + - ``reserved`` + + - + - A place holder for future extensions. Drivers and applications + must set this to 0. + + + +.. _v4l2-plane: + +struct v4l2_plane +================= + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 1 2 + + + - .. row 1 + + - __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 that the + actual image data starts at ``data_offset`` which may not be 0. + + - .. row 2 + + - __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`. + + - .. row 3 + + - union + + - ``m`` + + - + - + + - .. row 4 + + - + - __u32 + + - ``mem_offset`` + + - When the memory type in the containing struct + :ref:`v4l2_buffer ` is ``V4L2_MEMORY_MMAP``, this + is the value that should be passed to :ref:`mmap() `, + similar to the ``offset`` field in struct + :ref:`v4l2_buffer `. + + - .. row 5 + + - + - unsigned long + + - ``userptr`` + + - When the memory type in the containing struct + :ref:`v4l2_buffer ` is ``V4L2_MEMORY_USERPTR``, + this is a userspace pointer to the memory allocated for this plane + by an application. + + - .. row 6 + + - + - int + + - ``fd`` + + - When the memory type in the containing struct + :ref:`v4l2_buffer ` is ``V4L2_MEMORY_DMABUF``, + this is a file descriptor associated with a DMABUF buffer, similar + to the ``fd`` field in struct :ref:`v4l2_buffer `. + + - .. row 7 + + - __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. + + - .. row 8 + + - __u32 + + - ``reserved[11]`` + + - + - Reserved for future use. Should be zeroed by drivers and + applications. + + + +.. _v4l2-buf-type: + +enum v4l2_buf_type +================== + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` + + - 1 + + - Buffer of a single-planar video capture stream, see + :ref:`capture`. + + - .. row 2 + + - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` + + - 9 + + - Buffer of a multi-planar video capture stream, see + :ref:`capture`. + + - .. row 3 + + - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` + + - 2 + + - Buffer of a single-planar video output stream, see + :ref:`output`. + + - .. row 4 + + - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` + + - 10 + + - Buffer of a multi-planar video output stream, see :ref:`output`. + + - .. row 5 + + - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` + + - 3 + + - Buffer for video overlay, see :ref:`overlay`. + + - .. row 6 + + - ``V4L2_BUF_TYPE_VBI_CAPTURE`` + + - 4 + + - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`. + + - .. row 7 + + - ``V4L2_BUF_TYPE_VBI_OUTPUT`` + + - 5 + + - Buffer of a raw VBI output stream, see :ref:`raw-vbi`. + + - .. row 8 + + - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` + + - 6 + + - Buffer of a sliced VBI capture stream, see :ref:`sliced`. + + - .. row 9 + + - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` + + - 7 + + - Buffer of a sliced VBI output stream, see :ref:`sliced`. + + - .. row 10 + + - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` + + - 8 + + - Buffer for video output overlay (OSD), see :ref:`osd`. + + - .. row 11 + + - ``V4L2_BUF_TYPE_SDR_CAPTURE`` + + - 11 + + - Buffer for Software Defined Radio (SDR) capture stream, see + :ref:`sdr`. + + - .. row 12 + + - ``V4L2_BUF_TYPE_SDR_OUTPUT`` + + - 12 + + - Buffer for Software Defined Radio (SDR) output stream, see + :ref:`sdr`. + + + +.. _buffer-flags: + +Buffer Flags +============ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``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. + + - .. row 2 + + - ``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. + + - .. row 3 + + - ``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. + + - .. row 4 + + - ``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. + + - .. row 5 + + - ``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. + + - .. row 6 + + - ``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. + + - .. row 7 + + - ``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. + + - .. row 8 + + - ``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. + + - .. row 9 + + - ``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. + + - .. row 10 + + - ``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. + + - .. row 11 + + - ``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. + + - .. row 12 + + - ``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. + + - .. row 13 + + - ``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. + + - .. row 14 + + - ``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(2)` using clock IDs ``CLOCK_MONOTONIC`` + and ``CLOCK_REALTIME``, respectively. + + - .. row 15 + + - ``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(2)`. + + - .. row 16 + + - ``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. + + - .. row 17 + + - ``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. + + - .. row 18 + + - ``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. + + - .. row 19 + + - ``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. + + + +.. _v4l2-memory: + +enum v4l2_memory +================ + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_MEMORY_MMAP`` + + - 1 + + - The buffer is used for :ref:`memory mapping ` I/O. + + - .. row 2 + + - ``V4L2_MEMORY_USERPTR`` + + - 2 + + - The buffer is used for :ref:`user pointer ` I/O. + + - .. row 3 + + - ``V4L2_MEMORY_OVERLAY`` + + - 3 + + - [to do] + + - .. row 4 + + - ``V4L2_MEMORY_DMABUF`` + + - 4 + + - The buffer is used for :ref:`DMA shared buffer ` I/O. + + + +Timecodes +========= + +The :ref:`struct v4l2_timecode ` structure is designed to hold a +:ref:`smpte12m` or similar timecode. (struct +:c:type:`struct timeval` timestamps are stored in struct +:ref:`v4l2_buffer ` field ``timestamp``.) + + +.. _v4l2-timecode: + +struct v4l2_timecode +-------------------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - __u32 + + - ``type`` + + - Frame rate the timecodes are based on, see :ref:`timecode-type`. + + - .. row 2 + + - __u32 + + - ``flags`` + + - Timecode flags, see :ref:`timecode-flags`. + + - .. row 3 + + - __u8 + + - ``frames`` + + - Frame count, 0 ... 23/24/29/49/59, depending on the type of + timecode. + + - .. row 4 + + - __u8 + + - ``seconds`` + + - Seconds count, 0 ... 59. This is a binary, not BCD number. + + - .. row 5 + + - __u8 + + - ``minutes`` + + - Minutes count, 0 ... 59. This is a binary, not BCD number. + + - .. row 6 + + - __u8 + + - ``hours`` + + - Hours count, 0 ... 29. This is a binary, not BCD number. + + - .. row 7 + + - __u8 + + - ``userbits``\ [4] + + - The "user group" bits from the timecode. + + + +.. _timecode-type: + +Timecode Types +-------------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``V4L2_TC_TYPE_24FPS`` + + - 1 + + - 24 frames per second, i. e. film. + + - .. row 2 + + - ``V4L2_TC_TYPE_25FPS`` + + - 2 + + - 25 frames per second, i. e. PAL or SECAM video. + + - .. row 3 + + - ``V4L2_TC_TYPE_30FPS`` + + - 3 + + - 30 frames per second, i. e. NTSC video. + + - .. row 4 + + - ``V4L2_TC_TYPE_50FPS`` + + - 4 + + - + + - .. row 5 + + - ``V4L2_TC_TYPE_60FPS`` + + - 5 + + - + + + +.. _timecode-flags: + +Timecode Flags +-------------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - ``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. + + - .. row 2 + + - ``V4L2_TC_FLAG_COLORFRAME`` + + - 0x0002 + + - The "color frame" flag. + + - .. row 3 + + - ``V4L2_TC_USERBITS_field`` + + - 0x000C + + - Field mask for the "binary group flags". + + - .. row 4 + + - ``V4L2_TC_USERBITS_USERDEFINED`` + + - 0x0000 + + - Unspecified format. + + - .. row 5 + + - ``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 new file mode 100644 index 000000000000..ac1cd057e25b --- /dev/null +++ b/Documentation/media/uapi/v4l/capture-example.rst @@ -0,0 +1,13 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 new file mode 100644 index 000000000000..56525a0fb2fa --- /dev/null +++ b/Documentation/media/uapi/v4l/capture.c.rst @@ -0,0 +1,664 @@ +.. -*- coding: utf-8; mode: rst -*- + +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.rst b/Documentation/media/uapi/v4l/colorspaces.rst new file mode 100644 index 000000000000..322eb94c1d44 --- /dev/null +++ b/Documentation/media/uapi/v4l/colorspaces.rst @@ -0,0 +1,163 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 new file mode 100644 index 000000000000..39058216b630 --- /dev/null +++ b/Documentation/media/uapi/v4l/common-defs.rst @@ -0,0 +1,13 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 new file mode 100644 index 000000000000..13f2ed3fc5a6 --- /dev/null +++ b/Documentation/media/uapi/v4l/common.rst @@ -0,0 +1,46 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 + format + planar-apis + crop + selection-api + streaming-par diff --git a/Documentation/media/uapi/v4l/compat.rst b/Documentation/media/uapi/v4l/compat.rst new file mode 100644 index 000000000000..8b5e1cebd8f4 --- /dev/null +++ b/Documentation/media/uapi/v4l/compat.rst @@ -0,0 +1,18 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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/control.rst b/Documentation/media/uapi/v4l/control.rst new file mode 100644 index 000000000000..6cf218ab36fb --- /dev/null +++ b/Documentation/media/uapi/v4l/control.rst @@ -0,0 +1,533 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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`` [1]_ 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. + +``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: + + + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - ``V4L2_COLORFX_NONE`` + + - Color effect is disabled. + + - .. row 2 + + - ``V4L2_COLORFX_ANTIQUE`` + + - An aging (old photo) effect. + + - .. row 3 + + - ``V4L2_COLORFX_ART_FREEZE`` + + - Frost color effect. + + - .. row 4 + + - ``V4L2_COLORFX_AQUA`` + + - Water color, cool tone. + + - .. row 5 + + - ``V4L2_COLORFX_BW`` + + - Black and white. + + - .. row 6 + + - ``V4L2_COLORFX_EMBOSS`` + + - Emboss, the highlights and shadows replace light/dark boundaries + and low contrast areas are set to a gray background. + + - .. row 7 + + - ``V4L2_COLORFX_GRASS_GREEN`` + + - Grass green. + + - .. row 8 + + - ``V4L2_COLORFX_NEGATIVE`` + + - Negative. + + - .. row 9 + + - ``V4L2_COLORFX_SEPIA`` + + - Sepia tone. + + - .. row 10 + + - ``V4L2_COLORFX_SKETCH`` + + - Sketch. + + - .. row 11 + + - ``V4L2_COLORFX_SKIN_WHITEN`` + + - Skin whiten. + + - .. row 12 + + - ``V4L2_COLORFX_SKY_BLUE`` + + - Sky blue. + + - .. row 13 + + - ``V4L2_COLORFX_SOLARIZATION`` + + - Solarization, the image is partially reversed in tone, only color + values above or below a certain threshold are inverted. + + - .. row 14 + + - ``V4L2_COLORFX_SILHOUETTE`` + + - Silhouette (outline). + + - .. row 15 + + - ``V4L2_COLORFX_VIVID`` + + - Vivid colors. + + - .. row 16 + + - ``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: + +.. code-block:: c + :caption: Example 1.8. Enumerating all user controls + + + struct v4l2_queryctrl queryctrl; + struct v4l2_querymenu querymenu; + + static void enumerate_menu(void) + { + printf(" Menu items:\\n"); + + memset(&querymenu, 0, sizeof(querymenu)); + querymenu.id = queryctrl.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)); + + 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(); + } 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(); + } else { + if (errno == EINVAL) + break; + + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); + } + } + + +.. code-block:: c + :caption: Example 1.9. Enumerating all user controls (alternative) + + memset(&queryctrl, 0, sizeof(queryctrl)); + + queryctrl.id = V4L2_CTRL_CLASS_USER | V4L2_CTRL_FLAG_NEXT_CTRL; + while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { + if (V4L2_CTRL_ID2CLASS(queryctrl.id) != V4L2_CTRL_CLASS_USER) + break; + 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 |= V4L2_CTRL_FLAG_NEXT_CTRL; + } + if (errno != EINVAL) { + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); + } + + +.. code-block:: c + :caption: Example 1.10. Changing controls + + 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); + +.. [1] + 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 programatically 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 new file mode 100644 index 000000000000..ed43b36c51d8 --- /dev/null +++ b/Documentation/media/uapi/v4l/crop.rst @@ -0,0 +1,294 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _crop: + +************************************* +Image Cropping, Insertion and Scaling +************************************* + +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 must support the +:ref:`VIDIOC_CROPCAP ` ioctl such that applications can +determine if scaling takes place. + + +Cropping Structures +=================== + + +.. _crop-scale: + +.. figure:: crop_files/crop.* + :alt: crop.pdf / crop.gif + :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 :ref:`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 +:ref:`v4l2_crop ` using the same coordinate system as +struct :ref:`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 +:ref:`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 :ref:`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 :ref:`v4l2_crop ` may be smaller than the struct +:ref:`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. + +.. code-block:: c + :caption: Example 1.11. Resetting the cropping parameters + + 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); + } + +.. code-block:: c + :caption: Example 1.12. Simple downscaling + + 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. */ + +**NOTE:** This example assumes an output device. + +.. code-block:: c + :caption: Example 1.13. Selecting an output area + + 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); + } + +**NOTE:** This example assumes a video capture device. + +.. code-block:: c + :caption: Example 1.14. Current scaling factor and pixel aspect + + 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_files/crop.gif b/Documentation/media/uapi/v4l/crop_files/crop.gif new file mode 100644 index 000000000000..3b9e7d836d4b Binary files /dev/null and b/Documentation/media/uapi/v4l/crop_files/crop.gif differ diff --git a/Documentation/media/uapi/v4l/crop_files/crop.pdf b/Documentation/media/uapi/v4l/crop_files/crop.pdf new file mode 100644 index 000000000000..c9fb81cd32f3 Binary files /dev/null and b/Documentation/media/uapi/v4l/crop_files/crop.pdf differ diff --git a/Documentation/media/uapi/v4l/depth-formats.rst b/Documentation/media/uapi/v4l/depth-formats.rst new file mode 100644 index 000000000000..82f183870aae --- /dev/null +++ b/Documentation/media/uapi/v4l/depth-formats.rst @@ -0,0 +1,15 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _depth-formats: + +************* +Depth Formats +************* + +Depth data provides distance to points, mapped onto the image plane + + +.. toctree:: + :maxdepth: 1 + + pixfmt-z16 diff --git a/Documentation/media/uapi/v4l/dev-capture.rst b/Documentation/media/uapi/v4l/dev-capture.rst new file mode 100644 index 000000000000..16030a8354fd --- /dev/null +++ b/Documentation/media/uapi/v4l/dev-capture.rst @@ -0,0 +1,102 @@ +.. -*- coding: utf-8; mode: rst -*- + +.. _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 files 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 +:ref:`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