From 2c3c1048746a4622d8c89a29670120dc8fab93c4 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 20:49:45 +0200 Subject: Adding upstream version 6.1.76. Signed-off-by: Daniel Baumann --- Documentation/userspace-api/accelerators/ocxl.rst | 176 + Documentation/userspace-api/ebpf/index.rst | 17 + Documentation/userspace-api/ebpf/syscall.rst | 24 + Documentation/userspace-api/futex2.rst | 86 + Documentation/userspace-api/index.rst | 39 + Documentation/userspace-api/ioctl/cdrom.rst | 1242 +++ Documentation/userspace-api/ioctl/hdio.rst | 547 ++ Documentation/userspace-api/ioctl/index.rst | 15 + .../userspace-api/ioctl/ioctl-decoding.rst | 31 + Documentation/userspace-api/ioctl/ioctl-number.rst | 381 + Documentation/userspace-api/iommu.rst | 209 + Documentation/userspace-api/landlock.rst | 447 ++ Documentation/userspace-api/media/Makefile | 63 + .../userspace-api/media/ca.h.rst.exceptions | 25 + .../userspace-api/media/cec.h.rst.exceptions | 577 ++ Documentation/userspace-api/media/cec/cec-api.rst | 46 + .../userspace-api/media/cec/cec-func-close.rst | 43 + .../userspace-api/media/cec/cec-func-ioctl.rst | 63 + .../userspace-api/media/cec/cec-func-open.rst | 74 + .../userspace-api/media/cec/cec-func-poll.rst | 74 + .../userspace-api/media/cec/cec-funcs.rst | 23 + .../userspace-api/media/cec/cec-header.rst | 10 + .../userspace-api/media/cec/cec-intro.rst | 42 + .../media/cec/cec-ioc-adap-g-caps.rst | 146 + .../media/cec/cec-ioc-adap-g-conn-info.rst | 106 + .../media/cec/cec-ioc-adap-g-log-addrs.rst | 367 + .../media/cec/cec-ioc-adap-g-phys-addr.rst | 94 + .../userspace-api/media/cec/cec-ioc-dqevent.rst | 245 + .../userspace-api/media/cec/cec-ioc-g-mode.rst | 294 + .../userspace-api/media/cec/cec-ioc-receive.rst | 385 + .../userspace-api/media/cec/cec-pin-error-inj.rst | 327 + Documentation/userspace-api/media/conf_nitpick.py | 111 + .../userspace-api/media/dmx.h.rst.exceptions | 66 + Documentation/userspace-api/media/drivers/ccs.rst | 110 + .../userspace-api/media/drivers/cx2341x-uapi.rst | 177 + .../userspace-api/media/drivers/dw100.rst | 84 + .../userspace-api/media/drivers/imx-uapi.rst | 125 + .../userspace-api/media/drivers/index.rst | 41 + .../userspace-api/media/drivers/max2175.rst | 64 + .../userspace-api/media/drivers/meye-uapi.rst | 53 + .../userspace-api/media/drivers/omap3isp-uapi.rst | 208 + .../userspace-api/media/drivers/uvcvideo.rst | 257 + .../userspace-api/media/dvb/ca-fclose.rst | 40 + Documentation/userspace-api/media/dvb/ca-fopen.rst | 72 + .../userspace-api/media/dvb/ca-get-cap.rst | 46 + .../userspace-api/media/dvb/ca-get-descr-info.rst | 43 + .../userspace-api/media/dvb/ca-get-msg.rst | 50 + .../userspace-api/media/dvb/ca-get-slot-info.rst | 56 + Documentation/userspace-api/media/dvb/ca-reset.rst | 43 + .../userspace-api/media/dvb/ca-send-msg.rst | 50 + .../userspace-api/media/dvb/ca-set-descr.rst | 46 + Documentation/userspace-api/media/dvb/ca.rst | 25 + .../userspace-api/media/dvb/ca_data_types.rst | 9 + .../userspace-api/media/dvb/ca_function_calls.rst | 20 + .../userspace-api/media/dvb/ca_high_level.rst | 157 + Documentation/userspace-api/media/dvb/demux.rst | 23 + .../userspace-api/media/dvb/dmx-add-pid.rst | 47 + .../userspace-api/media/dvb/dmx-expbuf.rst | 87 + .../userspace-api/media/dvb/dmx-fclose.rst | 42 + .../userspace-api/media/dvb/dmx-fopen.rst | 88 + .../userspace-api/media/dvb/dmx-fread.rst | 77 + .../userspace-api/media/dvb/dmx-fwrite.rst | 70 + .../userspace-api/media/dvb/dmx-get-pes-pids.rst | 62 + .../userspace-api/media/dvb/dmx-get-stc.rst | 64 + Documentation/userspace-api/media/dvb/dmx-mmap.rst | 115 + .../userspace-api/media/dvb/dmx-munmap.rst | 52 + Documentation/userspace-api/media/dvb/dmx-qbuf.rst | 85 + .../userspace-api/media/dvb/dmx-querybuf.rst | 64 + .../userspace-api/media/dvb/dmx-remove-pid.rst | 48 + .../userspace-api/media/dvb/dmx-reqbufs.rst | 75 + .../media/dvb/dmx-set-buffer-size.rst | 48 + .../userspace-api/media/dvb/dmx-set-filter.rst | 55 + .../userspace-api/media/dvb/dmx-set-pes-filter.rst | 64 + .../userspace-api/media/dvb/dmx-start.rst | 65 + Documentation/userspace-api/media/dvb/dmx-stop.rst | 44 + .../userspace-api/media/dvb/dmx_fcalls.rst | 30 + .../userspace-api/media/dvb/dmx_types.rst | 9 + .../userspace-api/media/dvb/dvb-fe-read-status.rst | 25 + .../userspace-api/media/dvb/dvb-frontend-event.rst | 15 + .../media/dvb/dvb-frontend-parameters.rst | 119 + Documentation/userspace-api/media/dvb/dvbapi.rst | 118 + .../userspace-api/media/dvb/dvbproperty.rst | 126 + Documentation/userspace-api/media/dvb/dvbstb.svg | 17 + Documentation/userspace-api/media/dvb/examples.rst | 16 + .../userspace-api/media/dvb/fe-bandwidth-t.rst | 74 + .../media/dvb/fe-diseqc-recv-slave-reply.rst | 47 + .../media/dvb/fe-diseqc-reset-overload.rst | 45 + .../media/dvb/fe-diseqc-send-burst.rst | 50 + .../media/dvb/fe-diseqc-send-master-cmd.rst | 48 + .../media/dvb/fe-dishnetwork-send-legacy-cmd.rst | 53 + .../media/dvb/fe-enable-high-lnb-voltage.rst | 52 + .../userspace-api/media/dvb/fe-get-event.rst | 67 + .../userspace-api/media/dvb/fe-get-frontend.rst | 58 + .../userspace-api/media/dvb/fe-get-info.rst | 59 + .../userspace-api/media/dvb/fe-get-property.rst | 75 + .../userspace-api/media/dvb/fe-read-ber.rst | 49 + .../media/dvb/fe-read-signal-strength.rst | 49 + .../userspace-api/media/dvb/fe-read-snr.rst | 49 + .../userspace-api/media/dvb/fe-read-status.rst | 62 + .../media/dvb/fe-read-uncorrected-blocks.rst | 51 + .../media/dvb/fe-set-frontend-tune-mode.rst | 55 + .../userspace-api/media/dvb/fe-set-frontend.rst | 68 + .../userspace-api/media/dvb/fe-set-tone.rst | 56 + .../userspace-api/media/dvb/fe-set-voltage.rst | 60 + .../userspace-api/media/dvb/fe-type-t.rst | 91 + .../media/dvb/fe_property_parameters.rst | 1007 +++ .../userspace-api/media/dvb/frontend-header.rst | 6 + .../media/dvb/frontend-property-cable-systems.rst | 75 + .../dvb/frontend-property-satellite-systems.rst | 105 + .../dvb/frontend-property-terrestrial-systems.rst | 294 + .../media/dvb/frontend-stat-properties.rst | 245 + Documentation/userspace-api/media/dvb/frontend.rst | 56 + .../userspace-api/media/dvb/frontend_f_close.rst | 46 + .../userspace-api/media/dvb/frontend_f_open.rst | 104 + .../userspace-api/media/dvb/frontend_fcalls.rst | 24 + .../media/dvb/frontend_legacy_api.rst | 38 + .../media/dvb/frontend_legacy_dvbv3_api.rst | 18 + Documentation/userspace-api/media/dvb/headers.rst | 16 + Documentation/userspace-api/media/dvb/intro.rst | 183 + .../userspace-api/media/dvb/legacy_dvb_apis.rst | 25 + .../userspace-api/media/dvb/net-add-if.rst | 52 + .../userspace-api/media/dvb/net-get-if.rst | 50 + .../userspace-api/media/dvb/net-remove-if.rst | 46 + .../userspace-api/media/dvb/net-types.rst | 9 + Documentation/userspace-api/media/dvb/net.rst | 41 + .../media/dvb/query-dvb-frontend-info.rst | 13 + Documentation/userspace-api/media/fdl-appendix.rst | 471 ++ .../userspace-api/media/frontend.h.rst.exceptions | 214 + Documentation/userspace-api/media/gen-errors.rst | 96 + Documentation/userspace-api/media/glossary.rst | 205 + Documentation/userspace-api/media/index.rst | 72 + Documentation/userspace-api/media/intro.rst | 46 + .../userspace-api/media/lirc.h.rst.exceptions | 87 + .../userspace-api/media/media.h.rst.exceptions | 32 + .../media/mediactl/media-controller-intro.rst | 33 + .../media/mediactl/media-controller-model.rst | 41 + .../media/mediactl/media-controller.rst | 54 + .../media/mediactl/media-func-close.rst | 43 + .../media/mediactl/media-func-ioctl.rst | 63 + .../media/mediactl/media-func-open.rst | 65 + .../userspace-api/media/mediactl/media-funcs.rst | 26 + .../userspace-api/media/mediactl/media-header.rst | 10 + .../media/mediactl/media-ioc-device-info.rst | 106 + .../media/mediactl/media-ioc-enum-entities.rst | 146 + .../media/mediactl/media-ioc-enum-links.rst | 145 + .../media/mediactl/media-ioc-g-topology.rst | 294 + .../media/mediactl/media-ioc-request-alloc.rst | 65 + .../media/mediactl/media-ioc-setup-link.rst | 65 + .../media/mediactl/media-request-ioc-queue.rst | 77 + .../media/mediactl/media-request-ioc-reinit.rst | 51 + .../userspace-api/media/mediactl/media-types.rst | 432 ++ .../userspace-api/media/mediactl/request-api.rst | 253 + .../media/mediactl/request-func-close.rst | 45 + .../media/mediactl/request-func-ioctl.rst | 63 + .../media/mediactl/request-func-poll.rst | 73 + .../userspace-api/media/net.h.rst.exceptions | 13 + .../userspace-api/media/rc/keytable.c.rst | 176 + .../userspace-api/media/rc/lirc-dev-intro.rst | 176 + Documentation/userspace-api/media/rc/lirc-dev.rst | 14 + Documentation/userspace-api/media/rc/lirc-func.rst | 26 + .../userspace-api/media/rc/lirc-get-features.rst | 174 + .../userspace-api/media/rc/lirc-get-rec-mode.rst | 69 + .../media/rc/lirc-get-rec-resolution.rst | 47 + .../userspace-api/media/rc/lirc-get-send-mode.rst | 71 + .../userspace-api/media/rc/lirc-get-timeout.rst | 57 + .../userspace-api/media/rc/lirc-header.rst | 10 + Documentation/userspace-api/media/rc/lirc-read.rst | 65 + .../media/rc/lirc-set-measure-carrier-mode.rst | 46 + .../media/rc/lirc-set-rec-carrier-range.rst | 49 + .../media/rc/lirc-set-rec-carrier.rst | 46 + .../media/rc/lirc-set-rec-timeout.rst | 55 + .../media/rc/lirc-set-send-carrier.rst | 41 + .../media/rc/lirc-set-send-duty-cycle.rst | 47 + .../media/rc/lirc-set-transmitter-mask.rst | 51 + .../media/rc/lirc-set-wideband-receiver.rst | 56 + .../userspace-api/media/rc/lirc-write.rst | 72 + Documentation/userspace-api/media/rc/rc-intro.rst | 24 + Documentation/userspace-api/media/rc/rc-protos.rst | 454 ++ .../userspace-api/media/rc/rc-sysfs-nodes.rst | 144 + .../userspace-api/media/rc/rc-table-change.rst | 18 + Documentation/userspace-api/media/rc/rc-tables.rst | 759 ++ .../userspace-api/media/rc/remote_controllers.rst | 51 + .../userspace-api/media/typical_media_device.svg | 107 + Documentation/userspace-api/media/v4l/app-pri.rst | 30 + Documentation/userspace-api/media/v4l/audio.rst | 97 + Documentation/userspace-api/media/v4l/bayer.svg | 30 + Documentation/userspace-api/media/v4l/biblio.rst | 429 ++ Documentation/userspace-api/media/v4l/buffer.rst | 841 ++ .../userspace-api/media/v4l/capture-example.rst | 13 + .../userspace-api/media/v4l/capture.c.rst | 664 ++ .../userspace-api/media/v4l/colorspaces-defs.rst | 175 + .../media/v4l/colorspaces-details.rst | 775 ++ .../userspace-api/media/v4l/colorspaces.rst | 163 + .../userspace-api/media/v4l/common-defs.rst | 13 + Documentation/userspace-api/media/v4l/common.rst | 60 + Documentation/userspace-api/media/v4l/compat.rst | 18 + .../userspace-api/media/v4l/constraints.svg | 11 + Documentation/userspace-api/media/v4l/control.rst | 517 ++ Documentation/userspace-api/media/v4l/crop.rst | 317 + Documentation/userspace-api/media/v4l/crop.svg | 281 + .../userspace-api/media/v4l/depth-formats.rst | 17 + .../userspace-api/media/v4l/dev-capture.rst | 101 + .../userspace-api/media/v4l/dev-decoder.rst | 1127 +++ .../userspace-api/media/v4l/dev-encoder.rst | 729 ++ .../userspace-api/media/v4l/dev-event.rst | 47 + .../userspace-api/media/v4l/dev-mem2mem.rst | 43 + Documentation/userspace-api/media/v4l/dev-meta.rst | 67 + Documentation/userspace-api/media/v4l/dev-osd.rst | 150 + .../userspace-api/media/v4l/dev-output.rst | 98 + .../userspace-api/media/v4l/dev-overlay.rst | 320 + .../userspace-api/media/v4l/dev-radio.rst | 52 + .../userspace-api/media/v4l/dev-raw-vbi.rst | 292 + Documentation/userspace-api/media/v4l/dev-rds.rst | 176 + Documentation/userspace-api/media/v4l/dev-sdr.rst | 107 + .../userspace-api/media/v4l/dev-sliced-vbi.rst | 661 ++ .../media/v4l/dev-stateless-decoder.rst | 424 + .../userspace-api/media/v4l/dev-subdev.rst | 503 ++ .../userspace-api/media/v4l/dev-touch.rst | 56 + Documentation/userspace-api/media/v4l/devices.rst | 26 + Documentation/userspace-api/media/v4l/diff-v4l.rst | 667 ++ Documentation/userspace-api/media/v4l/dmabuf.rst | 162 + .../userspace-api/media/v4l/dv-timings.rst | 38 + .../userspace-api/media/v4l/ext-ctrls-camera.rst | 663 ++ .../media/v4l/ext-ctrls-codec-stateless.rst | 2959 +++++++ .../userspace-api/media/v4l/ext-ctrls-codec.rst | 2660 +++++++ .../media/v4l/ext-ctrls-colorimetry.rst | 93 + .../userspace-api/media/v4l/ext-ctrls-detect.rst | 64 + .../userspace-api/media/v4l/ext-ctrls-dv.rst | 159 + .../userspace-api/media/v4l/ext-ctrls-flash.rst | 188 + .../userspace-api/media/v4l/ext-ctrls-fm-rx.rst | 88 + .../userspace-api/media/v4l/ext-ctrls-fm-tx.rst | 181 + .../media/v4l/ext-ctrls-image-process.rst | 57 + .../media/v4l/ext-ctrls-image-source.rst | 94 + .../userspace-api/media/v4l/ext-ctrls-jpeg.rst | 105 + .../userspace-api/media/v4l/ext-ctrls-rf-tuner.rst | 89 + .../userspace-api/media/v4l/extended-controls.rst | 173 + .../userspace-api/media/v4l/field-order.rst | 165 + .../userspace-api/media/v4l/fieldseq_bt.svg | 2612 +++++++ .../userspace-api/media/v4l/fieldseq_tb.svg | 2609 +++++++ Documentation/userspace-api/media/v4l/format.rst | 91 + Documentation/userspace-api/media/v4l/fourcc.rst | 32 + .../userspace-api/media/v4l/func-close.rst | 45 + .../userspace-api/media/v4l/func-ioctl.rst | 58 + .../userspace-api/media/v4l/func-mmap.rst | 137 + .../userspace-api/media/v4l/func-munmap.rst | 54 + .../userspace-api/media/v4l/func-open.rst | 79 + .../userspace-api/media/v4l/func-poll.rst | 113 + .../userspace-api/media/v4l/func-read.rst | 130 + .../userspace-api/media/v4l/func-select.rst | 116 + .../userspace-api/media/v4l/func-write.rst | 81 + .../userspace-api/media/v4l/hist-v4l2.rst | 1276 +++ .../userspace-api/media/v4l/hsv-formats.rst | 19 + Documentation/userspace-api/media/v4l/io.rst | 49 + .../media/v4l/libv4l-introduction.rst | 180 + Documentation/userspace-api/media/v4l/libv4l.rst | 13 + .../userspace-api/media/v4l/meta-formats.rst | 21 + Documentation/userspace-api/media/v4l/mmap.rst | 285 + Documentation/userspace-api/media/v4l/nv12mt.svg | 451 ++ .../userspace-api/media/v4l/nv12mt_example.svg | 1590 ++++ Documentation/userspace-api/media/v4l/open.rst | 238 + Documentation/userspace-api/media/v4l/pipeline.dot | 14 + .../userspace-api/media/v4l/pixfmt-bayer.rst | 32 + .../userspace-api/media/v4l/pixfmt-cnf4.rst | 31 + .../userspace-api/media/v4l/pixfmt-compressed.rst | 238 + .../userspace-api/media/v4l/pixfmt-indexed.rst | 47 + .../userspace-api/media/v4l/pixfmt-intro.rst | 51 + .../userspace-api/media/v4l/pixfmt-inzi.rst | 82 + .../userspace-api/media/v4l/pixfmt-m420.rst | 71 + .../userspace-api/media/v4l/pixfmt-meta-d4xx.rst | 213 + .../media/v4l/pixfmt-meta-intel-ipu3.rst | 81 + .../userspace-api/media/v4l/pixfmt-meta-rkisp1.rst | 50 + .../userspace-api/media/v4l/pixfmt-meta-uvc.rst | 51 + .../userspace-api/media/v4l/pixfmt-meta-vivid.rst | 36 + .../media/v4l/pixfmt-meta-vsp1-hgo.rst | 168 + .../media/v4l/pixfmt-meta-vsp1-hgt.rst | 129 + .../userspace-api/media/v4l/pixfmt-packed-hsv.rst | 157 + .../userspace-api/media/v4l/pixfmt-packed-yuv.rst | 409 + .../userspace-api/media/v4l/pixfmt-reserved.rst | 263 + .../userspace-api/media/v4l/pixfmt-rgb.rst | 991 +++ .../userspace-api/media/v4l/pixfmt-sdr-cs08.rst | 30 + .../userspace-api/media/v4l/pixfmt-sdr-cs14le.rst | 34 + .../userspace-api/media/v4l/pixfmt-sdr-cu08.rst | 30 + .../userspace-api/media/v4l/pixfmt-sdr-cu16le.rst | 34 + .../userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst | 55 + .../userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst | 55 + .../userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst | 55 + .../userspace-api/media/v4l/pixfmt-sdr-ru12le.rst | 32 + .../media/v4l/pixfmt-srggb10-ipu3.rst | 345 + .../userspace-api/media/v4l/pixfmt-srggb10.rst | 76 + .../media/v4l/pixfmt-srggb10alaw8.rst | 24 + .../media/v4l/pixfmt-srggb10dpcm8.rst | 28 + .../userspace-api/media/v4l/pixfmt-srggb10p.rst | 74 + .../userspace-api/media/v4l/pixfmt-srggb12.rst | 77 + .../userspace-api/media/v4l/pixfmt-srggb12p.rst | 87 + .../userspace-api/media/v4l/pixfmt-srggb14.rst | 77 + .../userspace-api/media/v4l/pixfmt-srggb14p.rst | 147 + .../userspace-api/media/v4l/pixfmt-srggb16.rst | 71 + .../userspace-api/media/v4l/pixfmt-srggb8.rst | 55 + .../userspace-api/media/v4l/pixfmt-tch-td08.rst | 52 + .../userspace-api/media/v4l/pixfmt-tch-td16.rst | 67 + .../userspace-api/media/v4l/pixfmt-tch-tu08.rst | 50 + .../userspace-api/media/v4l/pixfmt-tch-tu16.rst | 66 + .../userspace-api/media/v4l/pixfmt-uv8.rst | 47 + .../userspace-api/media/v4l/pixfmt-v4l2-mplane.rst | 123 + .../userspace-api/media/v4l/pixfmt-v4l2.rst | 240 + .../userspace-api/media/v4l/pixfmt-y12i.rst | 36 + .../userspace-api/media/v4l/pixfmt-y8i.rst | 66 + .../userspace-api/media/v4l/pixfmt-yuv-luma.rst | 148 + .../userspace-api/media/v4l/pixfmt-yuv-planar.rst | 1078 +++ .../userspace-api/media/v4l/pixfmt-z16.rst | 66 + Documentation/userspace-api/media/v4l/pixfmt.rst | 38 + .../userspace-api/media/v4l/planar-apis.rst | 61 + Documentation/userspace-api/media/v4l/querycap.rst | 34 + Documentation/userspace-api/media/v4l/rw.rst | 47 + .../userspace-api/media/v4l/sdr-formats.rst | 22 + .../media/v4l/selection-api-configuration.rst | 137 + .../media/v4l/selection-api-examples.rst | 84 + .../media/v4l/selection-api-intro.rst | 28 + .../media/v4l/selection-api-targets.rst | 20 + .../media/v4l/selection-api-vs-crop-api.rst | 39 + .../userspace-api/media/v4l/selection-api.rst | 16 + .../userspace-api/media/v4l/selection.svg | 1152 +++ .../userspace-api/media/v4l/selections-common.rst | 23 + Documentation/userspace-api/media/v4l/standard.rst | 185 + .../userspace-api/media/v4l/streaming-par.rst | 34 + .../userspace-api/media/v4l/subdev-formats.rst | 8088 ++++++++++++++++++++ .../media/v4l/subdev-image-processing-crop.svg | 303 + .../media/v4l/subdev-image-processing-full.svg | 743 ++ ...ubdev-image-processing-scaling-multi-source.svg | 541 ++ .../userspace-api/media/v4l/tch-formats.rst | 18 + Documentation/userspace-api/media/v4l/tuner.rst | 85 + .../userspace-api/media/v4l/user-func.rst | 82 + Documentation/userspace-api/media/v4l/userp.rst | 122 + .../media/v4l/v4l2-selection-flags.rst | 54 + .../media/v4l/v4l2-selection-targets.rst | 81 + Documentation/userspace-api/media/v4l/v4l2.rst | 418 + .../userspace-api/media/v4l/v4l2grab-example.rst | 17 + .../userspace-api/media/v4l/v4l2grab.c.rst | 169 + Documentation/userspace-api/media/v4l/vbi_525.svg | 812 ++ Documentation/userspace-api/media/v4l/vbi_625.svg | 861 +++ .../userspace-api/media/v4l/vbi_hsync.svg | 312 + Documentation/userspace-api/media/v4l/video.rst | 68 + Documentation/userspace-api/media/v4l/videodev.rst | 9 + .../userspace-api/media/v4l/vidioc-create-bufs.rst | 137 + .../userspace-api/media/v4l/vidioc-cropcap.rst | 133 + .../media/v4l/vidioc-dbg-g-chip-info.rst | 155 + .../media/v4l/vidioc-dbg-g-register.rst | 160 + .../userspace-api/media/v4l/vidioc-decoder-cmd.rst | 218 + .../userspace-api/media/v4l/vidioc-dqevent.rst | 377 + .../media/v4l/vidioc-dv-timings-cap.rst | 159 + .../userspace-api/media/v4l/vidioc-encoder-cmd.rst | 169 + .../media/v4l/vidioc-enum-dv-timings.rst | 105 + .../userspace-api/media/v4l/vidioc-enum-fmt.rst | 243 + .../media/v4l/vidioc-enum-frameintervals.rst | 186 + .../media/v4l/vidioc-enum-framesizes.rst | 194 + .../media/v4l/vidioc-enum-freq-bands.rst | 139 + .../userspace-api/media/v4l/vidioc-enumaudio.rst | 53 + .../media/v4l/vidioc-enumaudioout.rst | 58 + .../userspace-api/media/v4l/vidioc-enuminput.rst | 229 + .../userspace-api/media/v4l/vidioc-enumoutput.rst | 153 + .../userspace-api/media/v4l/vidioc-enumstd.rst | 351 + .../userspace-api/media/v4l/vidioc-expbuf.rst | 162 + .../userspace-api/media/v4l/vidioc-g-audio.rst | 124 + .../userspace-api/media/v4l/vidioc-g-audioout.rst | 99 + .../userspace-api/media/v4l/vidioc-g-crop.rst | 110 + .../userspace-api/media/v4l/vidioc-g-ctrl.rst | 100 + .../media/v4l/vidioc-g-dv-timings.rst | 317 + .../userspace-api/media/v4l/vidioc-g-edid.rst | 146 + .../userspace-api/media/v4l/vidioc-g-enc-index.rst | 144 + .../userspace-api/media/v4l/vidioc-g-ext-ctrls.rst | 503 ++ .../userspace-api/media/v4l/vidioc-g-fbuf.rst | 351 + .../userspace-api/media/v4l/vidioc-g-fmt.rst | 154 + .../userspace-api/media/v4l/vidioc-g-frequency.rst | 103 + .../userspace-api/media/v4l/vidioc-g-input.rst | 63 + .../userspace-api/media/v4l/vidioc-g-jpegcomp.rst | 124 + .../userspace-api/media/v4l/vidioc-g-modulator.rst | 193 + .../userspace-api/media/v4l/vidioc-g-output.rst | 65 + .../userspace-api/media/v4l/vidioc-g-parm.rst | 269 + .../userspace-api/media/v4l/vidioc-g-priority.rst | 91 + .../userspace-api/media/v4l/vidioc-g-selection.rst | 190 + .../media/v4l/vidioc-g-sliced-vbi-cap.rst | 202 + .../userspace-api/media/v4l/vidioc-g-std.rst | 82 + .../userspace-api/media/v4l/vidioc-g-tuner.rst | 464 ++ .../userspace-api/media/v4l/vidioc-log-status.rst | 47 + .../userspace-api/media/v4l/vidioc-overlay.rst | 52 + .../userspace-api/media/v4l/vidioc-prepare-buf.rst | 56 + .../userspace-api/media/v4l/vidioc-qbuf.rst | 197 + .../media/v4l/vidioc-query-dv-timings.rst | 86 + .../userspace-api/media/v4l/vidioc-querybuf.rst | 78 + .../userspace-api/media/v4l/vidioc-querycap.rst | 278 + .../userspace-api/media/v4l/vidioc-queryctrl.rst | 660 ++ .../userspace-api/media/v4l/vidioc-querystd.rst | 69 + .../userspace-api/media/v4l/vidioc-reqbufs.rst | 181 + .../media/v4l/vidioc-s-hw-freq-seek.rst | 137 + .../userspace-api/media/v4l/vidioc-streamon.rst | 105 + .../v4l/vidioc-subdev-enum-frame-interval.rst | 111 + .../media/v4l/vidioc-subdev-enum-frame-size.rst | 115 + .../media/v4l/vidioc-subdev-enum-mbus-code.rst | 146 + .../media/v4l/vidioc-subdev-g-crop.rst | 125 + .../media/v4l/vidioc-subdev-g-fmt.rst | 152 + .../media/v4l/vidioc-subdev-g-frame-interval.rst | 119 + .../media/v4l/vidioc-subdev-g-selection.rst | 123 + .../media/v4l/vidioc-subdev-querycap.rst | 104 + .../media/v4l/vidioc-subscribe-event.rst | 113 + .../userspace-api/media/v4l/yuv-formats.rst | 273 + .../userspace-api/media/videodev2.h.rst.exceptions | 599 ++ Documentation/userspace-api/netlink/index.rst | 12 + Documentation/userspace-api/netlink/intro.rst | 681 ++ Documentation/userspace-api/no_new_privs.rst | 63 + Documentation/userspace-api/seccomp_filter.rst | 376 + Documentation/userspace-api/spec_ctrl.rst | 116 + .../userspace-api/sysfs-platform_profile.rst | 42 + Documentation/userspace-api/unshare.rst | 332 + Documentation/userspace-api/vduse.rst | 233 + 414 files changed, 82495 insertions(+) create mode 100644 Documentation/userspace-api/accelerators/ocxl.rst create mode 100644 Documentation/userspace-api/ebpf/index.rst create mode 100644 Documentation/userspace-api/ebpf/syscall.rst create mode 100644 Documentation/userspace-api/futex2.rst create mode 100644 Documentation/userspace-api/index.rst create mode 100644 Documentation/userspace-api/ioctl/cdrom.rst create mode 100644 Documentation/userspace-api/ioctl/hdio.rst create mode 100644 Documentation/userspace-api/ioctl/index.rst create mode 100644 Documentation/userspace-api/ioctl/ioctl-decoding.rst create mode 100644 Documentation/userspace-api/ioctl/ioctl-number.rst create mode 100644 Documentation/userspace-api/iommu.rst create mode 100644 Documentation/userspace-api/landlock.rst create mode 100644 Documentation/userspace-api/media/Makefile create mode 100644 Documentation/userspace-api/media/ca.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/cec.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/cec/cec-api.rst create mode 100644 Documentation/userspace-api/media/cec/cec-func-close.rst create mode 100644 Documentation/userspace-api/media/cec/cec-func-ioctl.rst create mode 100644 Documentation/userspace-api/media/cec/cec-func-open.rst create mode 100644 Documentation/userspace-api/media/cec/cec-func-poll.rst create mode 100644 Documentation/userspace-api/media/cec/cec-funcs.rst create mode 100644 Documentation/userspace-api/media/cec/cec-header.rst create mode 100644 Documentation/userspace-api/media/cec/cec-intro.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst create mode 100644 Documentation/userspace-api/media/cec/cec-ioc-receive.rst create mode 100644 Documentation/userspace-api/media/cec/cec-pin-error-inj.rst create mode 100644 Documentation/userspace-api/media/conf_nitpick.py create mode 100644 Documentation/userspace-api/media/dmx.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/drivers/ccs.rst create mode 100644 Documentation/userspace-api/media/drivers/cx2341x-uapi.rst create mode 100644 Documentation/userspace-api/media/drivers/dw100.rst create mode 100644 Documentation/userspace-api/media/drivers/imx-uapi.rst create mode 100644 Documentation/userspace-api/media/drivers/index.rst create mode 100644 Documentation/userspace-api/media/drivers/max2175.rst create mode 100644 Documentation/userspace-api/media/drivers/meye-uapi.rst create mode 100644 Documentation/userspace-api/media/drivers/omap3isp-uapi.rst create mode 100644 Documentation/userspace-api/media/drivers/uvcvideo.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-fclose.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-fopen.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-get-cap.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-get-descr-info.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-get-msg.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-get-slot-info.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-reset.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-send-msg.rst create mode 100644 Documentation/userspace-api/media/dvb/ca-set-descr.rst create mode 100644 Documentation/userspace-api/media/dvb/ca.rst create mode 100644 Documentation/userspace-api/media/dvb/ca_data_types.rst create mode 100644 Documentation/userspace-api/media/dvb/ca_function_calls.rst create mode 100644 Documentation/userspace-api/media/dvb/ca_high_level.rst create mode 100644 Documentation/userspace-api/media/dvb/demux.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-add-pid.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-expbuf.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-fclose.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-fopen.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-fread.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-fwrite.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-get-stc.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-mmap.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-munmap.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-qbuf.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-querybuf.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-remove-pid.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-reqbufs.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-set-filter.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-start.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx-stop.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx_fcalls.rst create mode 100644 Documentation/userspace-api/media/dvb/dmx_types.rst create mode 100644 Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst create mode 100644 Documentation/userspace-api/media/dvb/dvb-frontend-event.rst create mode 100644 Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst create mode 100644 Documentation/userspace-api/media/dvb/dvbapi.rst create mode 100644 Documentation/userspace-api/media/dvb/dvbproperty.rst create mode 100644 Documentation/userspace-api/media/dvb/dvbstb.svg create mode 100644 Documentation/userspace-api/media/dvb/examples.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-get-event.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-get-frontend.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-get-info.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-get-property.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-read-ber.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-read-snr.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-read-status.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-set-frontend.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-set-tone.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-set-voltage.rst create mode 100644 Documentation/userspace-api/media/dvb/fe-type-t.rst create mode 100644 Documentation/userspace-api/media/dvb/fe_property_parameters.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend-header.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend-property-cable-systems.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend-property-satellite-systems.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend-property-terrestrial-systems.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend-stat-properties.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend_f_close.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend_f_open.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend_fcalls.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend_legacy_api.rst create mode 100644 Documentation/userspace-api/media/dvb/frontend_legacy_dvbv3_api.rst create mode 100644 Documentation/userspace-api/media/dvb/headers.rst create mode 100644 Documentation/userspace-api/media/dvb/intro.rst create mode 100644 Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst create mode 100644 Documentation/userspace-api/media/dvb/net-add-if.rst create mode 100644 Documentation/userspace-api/media/dvb/net-get-if.rst create mode 100644 Documentation/userspace-api/media/dvb/net-remove-if.rst create mode 100644 Documentation/userspace-api/media/dvb/net-types.rst create mode 100644 Documentation/userspace-api/media/dvb/net.rst create mode 100644 Documentation/userspace-api/media/dvb/query-dvb-frontend-info.rst create mode 100644 Documentation/userspace-api/media/fdl-appendix.rst create mode 100644 Documentation/userspace-api/media/frontend.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/gen-errors.rst create mode 100644 Documentation/userspace-api/media/glossary.rst create mode 100644 Documentation/userspace-api/media/index.rst create mode 100644 Documentation/userspace-api/media/intro.rst create mode 100644 Documentation/userspace-api/media/lirc.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/media.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/mediactl/media-controller-intro.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-controller-model.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-controller.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-func-close.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-func-ioctl.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-func-open.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-funcs.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-header.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst create mode 100644 Documentation/userspace-api/media/mediactl/media-types.rst create mode 100644 Documentation/userspace-api/media/mediactl/request-api.rst create mode 100644 Documentation/userspace-api/media/mediactl/request-func-close.rst create mode 100644 Documentation/userspace-api/media/mediactl/request-func-ioctl.rst create mode 100644 Documentation/userspace-api/media/mediactl/request-func-poll.rst create mode 100644 Documentation/userspace-api/media/net.h.rst.exceptions create mode 100644 Documentation/userspace-api/media/rc/keytable.c.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-dev-intro.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-dev.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-func.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-get-features.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-get-send-mode.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-get-timeout.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-header.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-read.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst create mode 100644 Documentation/userspace-api/media/rc/lirc-write.rst create mode 100644 Documentation/userspace-api/media/rc/rc-intro.rst create mode 100644 Documentation/userspace-api/media/rc/rc-protos.rst create mode 100644 Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst create mode 100644 Documentation/userspace-api/media/rc/rc-table-change.rst create mode 100644 Documentation/userspace-api/media/rc/rc-tables.rst create mode 100644 Documentation/userspace-api/media/rc/remote_controllers.rst create mode 100644 Documentation/userspace-api/media/typical_media_device.svg create mode 100644 Documentation/userspace-api/media/v4l/app-pri.rst create mode 100644 Documentation/userspace-api/media/v4l/audio.rst create mode 100644 Documentation/userspace-api/media/v4l/bayer.svg create mode 100644 Documentation/userspace-api/media/v4l/biblio.rst create mode 100644 Documentation/userspace-api/media/v4l/buffer.rst create mode 100644 Documentation/userspace-api/media/v4l/capture-example.rst create mode 100644 Documentation/userspace-api/media/v4l/capture.c.rst create mode 100644 Documentation/userspace-api/media/v4l/colorspaces-defs.rst create mode 100644 Documentation/userspace-api/media/v4l/colorspaces-details.rst create mode 100644 Documentation/userspace-api/media/v4l/colorspaces.rst create mode 100644 Documentation/userspace-api/media/v4l/common-defs.rst create mode 100644 Documentation/userspace-api/media/v4l/common.rst create mode 100644 Documentation/userspace-api/media/v4l/compat.rst create mode 100644 Documentation/userspace-api/media/v4l/constraints.svg create mode 100644 Documentation/userspace-api/media/v4l/control.rst create mode 100644 Documentation/userspace-api/media/v4l/crop.rst create mode 100644 Documentation/userspace-api/media/v4l/crop.svg create mode 100644 Documentation/userspace-api/media/v4l/depth-formats.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-capture.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-decoder.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-encoder.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-event.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-mem2mem.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-meta.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-osd.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-output.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-overlay.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-radio.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-raw-vbi.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-rds.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-sdr.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-sliced-vbi.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-stateless-decoder.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-subdev.rst create mode 100644 Documentation/userspace-api/media/v4l/dev-touch.rst create mode 100644 Documentation/userspace-api/media/v4l/devices.rst create mode 100644 Documentation/userspace-api/media/v4l/diff-v4l.rst create mode 100644 Documentation/userspace-api/media/v4l/dmabuf.rst create mode 100644 Documentation/userspace-api/media/v4l/dv-timings.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-camera.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-codec-stateless.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-codec.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-colorimetry.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-detect.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-dv.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-flash.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-fm-rx.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-fm-tx.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-image-process.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-image-source.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-jpeg.rst create mode 100644 Documentation/userspace-api/media/v4l/ext-ctrls-rf-tuner.rst create mode 100644 Documentation/userspace-api/media/v4l/extended-controls.rst create mode 100644 Documentation/userspace-api/media/v4l/field-order.rst create mode 100644 Documentation/userspace-api/media/v4l/fieldseq_bt.svg create mode 100644 Documentation/userspace-api/media/v4l/fieldseq_tb.svg create mode 100644 Documentation/userspace-api/media/v4l/format.rst create mode 100644 Documentation/userspace-api/media/v4l/fourcc.rst create mode 100644 Documentation/userspace-api/media/v4l/func-close.rst create mode 100644 Documentation/userspace-api/media/v4l/func-ioctl.rst create mode 100644 Documentation/userspace-api/media/v4l/func-mmap.rst create mode 100644 Documentation/userspace-api/media/v4l/func-munmap.rst create mode 100644 Documentation/userspace-api/media/v4l/func-open.rst create mode 100644 Documentation/userspace-api/media/v4l/func-poll.rst create mode 100644 Documentation/userspace-api/media/v4l/func-read.rst create mode 100644 Documentation/userspace-api/media/v4l/func-select.rst create mode 100644 Documentation/userspace-api/media/v4l/func-write.rst create mode 100644 Documentation/userspace-api/media/v4l/hist-v4l2.rst create mode 100644 Documentation/userspace-api/media/v4l/hsv-formats.rst create mode 100644 Documentation/userspace-api/media/v4l/io.rst create mode 100644 Documentation/userspace-api/media/v4l/libv4l-introduction.rst create mode 100644 Documentation/userspace-api/media/v4l/libv4l.rst create mode 100644 Documentation/userspace-api/media/v4l/meta-formats.rst create mode 100644 Documentation/userspace-api/media/v4l/mmap.rst create mode 100644 Documentation/userspace-api/media/v4l/nv12mt.svg create mode 100644 Documentation/userspace-api/media/v4l/nv12mt_example.svg create mode 100644 Documentation/userspace-api/media/v4l/open.rst create mode 100644 Documentation/userspace-api/media/v4l/pipeline.dot create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-bayer.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-cnf4.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-compressed.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-indexed.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-intro.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-inzi.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-m420.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-d4xx.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-intel-ipu3.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-rkisp1.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-uvc.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-vivid.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgo.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-meta-vsp1-hgt.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-packed-hsv.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-packed-yuv.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-reserved.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-rgb.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-cs08.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-cs14le.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-cu08.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-cu16le.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu16be.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu18be.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-pcu20be.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-sdr-ru12le.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb10-ipu3.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb10.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb10alaw8.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb10dpcm8.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb10p.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb12.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb12p.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb14.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb14p.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb16.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-srggb8.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-tch-td08.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-tch-td16.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-tch-tu08.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-tch-tu16.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-uv8.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-v4l2-mplane.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-v4l2.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y12i.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-y8i.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv-luma.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-yuv-planar.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt-z16.rst create mode 100644 Documentation/userspace-api/media/v4l/pixfmt.rst create mode 100644 Documentation/userspace-api/media/v4l/planar-apis.rst create mode 100644 Documentation/userspace-api/media/v4l/querycap.rst create mode 100644 Documentation/userspace-api/media/v4l/rw.rst create mode 100644 Documentation/userspace-api/media/v4l/sdr-formats.rst create mode 100644 Documentation/userspace-api/media/v4l/selection-api-configuration.rst create mode 100644 Documentation/userspace-api/media/v4l/selection-api-examples.rst create mode 100644 Documentation/userspace-api/media/v4l/selection-api-intro.rst create mode 100644 Documentation/userspace-api/media/v4l/selection-api-targets.rst create mode 100644 Documentation/userspace-api/media/v4l/selection-api-vs-crop-api.rst create mode 100644 Documentation/userspace-api/media/v4l/selection-api.rst create mode 100644 Documentation/userspace-api/media/v4l/selection.svg create mode 100644 Documentation/userspace-api/media/v4l/selections-common.rst create mode 100644 Documentation/userspace-api/media/v4l/standard.rst create mode 100644 Documentation/userspace-api/media/v4l/streaming-par.rst create mode 100644 Documentation/userspace-api/media/v4l/subdev-formats.rst create mode 100644 Documentation/userspace-api/media/v4l/subdev-image-processing-crop.svg create mode 100644 Documentation/userspace-api/media/v4l/subdev-image-processing-full.svg create mode 100644 Documentation/userspace-api/media/v4l/subdev-image-processing-scaling-multi-source.svg create mode 100644 Documentation/userspace-api/media/v4l/tch-formats.rst create mode 100644 Documentation/userspace-api/media/v4l/tuner.rst create mode 100644 Documentation/userspace-api/media/v4l/user-func.rst create mode 100644 Documentation/userspace-api/media/v4l/userp.rst create mode 100644 Documentation/userspace-api/media/v4l/v4l2-selection-flags.rst create mode 100644 Documentation/userspace-api/media/v4l/v4l2-selection-targets.rst create mode 100644 Documentation/userspace-api/media/v4l/v4l2.rst create mode 100644 Documentation/userspace-api/media/v4l/v4l2grab-example.rst create mode 100644 Documentation/userspace-api/media/v4l/v4l2grab.c.rst create mode 100644 Documentation/userspace-api/media/v4l/vbi_525.svg create mode 100644 Documentation/userspace-api/media/v4l/vbi_625.svg create mode 100644 Documentation/userspace-api/media/v4l/vbi_hsync.svg create mode 100644 Documentation/userspace-api/media/v4l/video.rst create mode 100644 Documentation/userspace-api/media/v4l/videodev.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-create-bufs.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-cropcap.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-dbg-g-chip-info.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-dbg-g-register.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-decoder-cmd.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-dqevent.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-dv-timings-cap.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-encoder-cmd.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enum-dv-timings.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enum-fmt.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enum-frameintervals.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enum-framesizes.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enum-freq-bands.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enumaudio.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enumaudioout.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enuminput.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enumoutput.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-enumstd.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-expbuf.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-audio.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-audioout.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-crop.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-ctrl.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-dv-timings.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-edid.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-enc-index.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-ext-ctrls.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-fbuf.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-fmt.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-frequency.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-input.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-jpegcomp.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-modulator.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-output.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-parm.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-priority.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-selection.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-sliced-vbi-cap.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-std.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-tuner.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-log-status.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-overlay.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-prepare-buf.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-qbuf.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-query-dv-timings.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-querybuf.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-querycap.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-queryctrl.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-querystd.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-reqbufs.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-s-hw-freq-seek.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-streamon.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-interval.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-enum-frame-size.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-enum-mbus-code.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-g-crop.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-g-fmt.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-g-frame-interval.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-g-selection.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subscribe-event.rst create mode 100644 Documentation/userspace-api/media/v4l/yuv-formats.rst create mode 100644 Documentation/userspace-api/media/videodev2.h.rst.exceptions create mode 100644 Documentation/userspace-api/netlink/index.rst create mode 100644 Documentation/userspace-api/netlink/intro.rst create mode 100644 Documentation/userspace-api/no_new_privs.rst create mode 100644 Documentation/userspace-api/seccomp_filter.rst create mode 100644 Documentation/userspace-api/spec_ctrl.rst create mode 100644 Documentation/userspace-api/sysfs-platform_profile.rst create mode 100644 Documentation/userspace-api/unshare.rst create mode 100644 Documentation/userspace-api/vduse.rst (limited to 'Documentation/userspace-api') diff --git a/Documentation/userspace-api/accelerators/ocxl.rst b/Documentation/userspace-api/accelerators/ocxl.rst new file mode 100644 index 000000000..db7570d5e --- /dev/null +++ b/Documentation/userspace-api/accelerators/ocxl.rst @@ -0,0 +1,176 @@ +======================================================== +OpenCAPI (Open Coherent Accelerator Processor Interface) +======================================================== + +OpenCAPI is an interface between processors and accelerators. It aims +at being low-latency and high-bandwidth. The specification is +developed by the `OpenCAPI Consortium `_. + +It allows an accelerator (which could be an FPGA, ASICs, ...) to access +the host memory coherently, using virtual addresses. An OpenCAPI +device can also host its own memory, that can be accessed from the +host. + +OpenCAPI is known in linux as 'ocxl', as the open, processor-agnostic +evolution of 'cxl' (the driver for the IBM CAPI interface for +powerpc), which was named that way to avoid confusion with the ISDN +CAPI subsystem. + + +High-level view +=============== + +OpenCAPI defines a Data Link Layer (DL) and Transaction Layer (TL), to +be implemented on top of a physical link. Any processor or device +implementing the DL and TL can start sharing memory. + +:: + + +-----------+ +-------------+ + | | | | + | | | Accelerated | + | Processor | | Function | + | | +--------+ | Unit | +--------+ + | |--| Memory | | (AFU) |--| Memory | + | | +--------+ | | +--------+ + +-----------+ +-------------+ + | | + +-----------+ +-------------+ + | TL | | TLX | + +-----------+ +-------------+ + | | + +-----------+ +-------------+ + | DL | | DLX | + +-----------+ +-------------+ + | | + | PHY | + +---------------------------------------+ + + + +Device discovery +================ + +OpenCAPI relies on a PCI-like configuration space, implemented on the +device. So the host can discover AFUs by querying the config space. + +OpenCAPI devices in Linux are treated like PCI devices (with a few +caveats). The firmware is expected to abstract the hardware as if it +was a PCI link. A lot of the existing PCI infrastructure is reused: +devices are scanned and BARs are assigned during the standard PCI +enumeration. Commands like 'lspci' can therefore be used to see what +devices are available. + +The configuration space defines the AFU(s) that can be found on the +physical adapter, such as its name, how many memory contexts it can +work with, the size of its MMIO areas, ... + + + +MMIO +==== + +OpenCAPI defines two MMIO areas for each AFU: + +* the global MMIO area, with registers pertinent to the whole AFU. +* a per-process MMIO area, which has a fixed size for each context. + + + +AFU interrupts +============== + +OpenCAPI includes the possibility for an AFU to send an interrupt to a +host process. It is done through a 'intrp_req' defined in the +Transaction Layer, specifying a 64-bit object handle which defines the +interrupt. + +The driver allows a process to allocate an interrupt and obtain its +64-bit object handle, that can be passed to the AFU. + + + +char devices +============ + +The driver creates one char device per AFU found on the physical +device. A physical device may have multiple functions and each +function can have multiple AFUs. At the time of this writing though, +it has only been tested with devices exporting only one AFU. + +Char devices can be found in /dev/ocxl/ and are named as: +/dev/ocxl/.. + +where is a max 20-character long name, as found in the +config space of the AFU. + is added by the driver and can help distinguish devices +when a system has more than one instance of the same OpenCAPI device. + is also to help distinguish AFUs in the unlikely case where a +device carries multiple copies of the same AFU. + + + +Sysfs class +=========== + +An ocxl class is added for the devices representing the AFUs. See +/sys/class/ocxl. The layout is described in +Documentation/ABI/testing/sysfs-class-ocxl + + + +User API +======== + +open +---- + +Based on the AFU definition found in the config space, an AFU may +support working with more than one memory context, in which case the +associated char device may be opened multiple times by different +processes. + + +ioctl +----- + +OCXL_IOCTL_ATTACH: + + Attach the memory context of the calling process to the AFU so that + the AFU can access its memory. + +OCXL_IOCTL_IRQ_ALLOC: + + Allocate an AFU interrupt and return an identifier. + +OCXL_IOCTL_IRQ_FREE: + + Free a previously allocated AFU interrupt. + +OCXL_IOCTL_IRQ_SET_FD: + + Associate an event fd to an AFU interrupt so that the user process + can be notified when the AFU sends an interrupt. + +OCXL_IOCTL_GET_METADATA: + + Obtains configuration information from the card, such at the size of + MMIO areas, the AFU version, and the PASID for the current context. + +OCXL_IOCTL_ENABLE_P9_WAIT: + + Allows the AFU to wake a userspace thread executing 'wait'. Returns + information to userspace to allow it to configure the AFU. Note that + this is only available on POWER9. + +OCXL_IOCTL_GET_FEATURES: + + Reports on which CPU features that affect OpenCAPI are usable from + userspace. + + +mmap +---- + +A process can mmap the per-process MMIO area for interactions with the +AFU. diff --git a/Documentation/userspace-api/ebpf/index.rst b/Documentation/userspace-api/ebpf/index.rst new file mode 100644 index 000000000..473dfba78 --- /dev/null +++ b/Documentation/userspace-api/ebpf/index.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0 + +eBPF Userspace API +================== + +eBPF is a kernel mechanism to provide a sandboxed runtime environment in the +Linux kernel for runtime extension and instrumentation without changing kernel +source code or loading kernel modules. eBPF programs can be attached to various +kernel subsystems, including networking, tracing and Linux security modules +(LSM). + +For internal kernel documentation on eBPF, see Documentation/bpf/index.rst. + +.. toctree:: + :maxdepth: 1 + + syscall diff --git a/Documentation/userspace-api/ebpf/syscall.rst b/Documentation/userspace-api/ebpf/syscall.rst new file mode 100644 index 000000000..ea9918084 --- /dev/null +++ b/Documentation/userspace-api/ebpf/syscall.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 + +eBPF Syscall +------------ + +:Authors: - Alexei Starovoitov + - Joe Stringer + - Michael Kerrisk + +The primary info for the bpf syscall is available in the `man-pages`_ +for `bpf(2)`_. + +bpf() subcommand reference +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. kernel-doc:: include/uapi/linux/bpf.h + :doc: eBPF Syscall Preamble + +.. kernel-doc:: include/uapi/linux/bpf.h + :doc: eBPF Syscall Commands + +.. Links: +.. _man-pages: https://www.kernel.org/doc/man-pages/ +.. _bpf(2): https://man7.org/linux/man-pages/man2/bpf.2.html diff --git a/Documentation/userspace-api/futex2.rst b/Documentation/userspace-api/futex2.rst new file mode 100644 index 000000000..9693f47a7 --- /dev/null +++ b/Documentation/userspace-api/futex2.rst @@ -0,0 +1,86 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====== +futex2 +====== + +:Author: AndrĂ© Almeida + +futex, or fast user mutex, is a set of syscalls to allow userspace to create +performant synchronization mechanisms, such as mutexes, semaphores and +conditional variables in userspace. C standard libraries, like glibc, uses it +as a means to implement more high level interfaces like pthreads. + +futex2 is a followup version of the initial futex syscall, designed to overcome +limitations of the original interface. + +User API +======== + +``futex_waitv()`` +----------------- + +Wait on an array of futexes, wake on any:: + + futex_waitv(struct futex_waitv *waiters, unsigned int nr_futexes, + unsigned int flags, struct timespec *timeout, clockid_t clockid) + + struct futex_waitv { + __u64 val; + __u64 uaddr; + __u32 flags; + __u32 __reserved; + }; + +Userspace sets an array of struct futex_waitv (up to a max of 128 entries), +using ``uaddr`` for the address to wait for, ``val`` for the expected value +and ``flags`` to specify the type (e.g. private) and size of futex. +``__reserved`` needs to be 0, but it can be used for future extension. The +pointer for the first item of the array is passed as ``waiters``. An invalid +address for ``waiters`` or for any ``uaddr`` returns ``-EFAULT``. + +If userspace has 32-bit pointers, it should do a explicit cast to make sure +the upper bits are zeroed. ``uintptr_t`` does the tricky and it works for +both 32/64-bit pointers. + +``nr_futexes`` specifies the size of the array. Numbers out of [1, 128] +interval will make the syscall return ``-EINVAL``. + +The ``flags`` argument of the syscall needs to be 0, but it can be used for +future extension. + +For each entry in ``waiters`` array, the current value at ``uaddr`` is compared +to ``val``. If it's different, the syscall undo all the work done so far and +return ``-EAGAIN``. If all tests and verifications succeeds, syscall waits until +one of the following happens: + +- The timeout expires, returning ``-ETIMEOUT``. +- A signal was sent to the sleeping task, returning ``-ERESTARTSYS``. +- Some futex at the list was woken, returning the index of some waked futex. + +An example of how to use the interface can be found at ``tools/testing/selftests/futex/functional/futex_waitv.c``. + +Timeout +------- + +``struct timespec *timeout`` argument is an optional argument that points to an +absolute timeout. You need to specify the type of clock being used at +``clockid`` argument. ``CLOCK_MONOTONIC`` and ``CLOCK_REALTIME`` are supported. +This syscall accepts only 64bit timespec structs. + +Types of futex +-------------- + +A futex can be either private or shared. Private is used for processes that +shares the same memory space and the virtual address of the futex will be the +same for all processes. This allows for optimizations in the kernel. To use +private futexes, it's necessary to specify ``FUTEX_PRIVATE_FLAG`` in the futex +flag. For processes that doesn't share the same memory space and therefore can +have different virtual addresses for the same futex (using, for instance, a +file-backed shared memory) requires different internal mechanisms to be get +properly enqueued. This is the default behavior, and it works with both private +and shared futexes. + +Futexes can be of different sizes: 8, 16, 32 or 64 bits. Currently, the only +supported one is 32 bit sized futex, and it need to be specified using +``FUTEX_32`` flag. diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst new file mode 100644 index 000000000..c78da9ce0 --- /dev/null +++ b/Documentation/userspace-api/index.rst @@ -0,0 +1,39 @@ +===================================== +The Linux kernel user-space API guide +===================================== + +.. _man-pages: https://www.kernel.org/doc/man-pages/ + +While much of the kernel's user-space API is documented elsewhere +(particularly in the man-pages_ project), some user-space information can +also be found in the kernel tree itself. This manual is intended to be the +place where this information is gathered. + +.. class:: toc-title + + Table of contents + +.. toctree:: + :maxdepth: 2 + + no_new_privs + seccomp_filter + landlock + unshare + spec_ctrl + accelerators/ocxl + ebpf/index + ioctl/index + iommu + media/index + netlink/index + sysfs-platform_profile + vduse + futex2 + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/userspace-api/ioctl/cdrom.rst b/Documentation/userspace-api/ioctl/cdrom.rst new file mode 100644 index 000000000..2ad91dbeb --- /dev/null +++ b/Documentation/userspace-api/ioctl/cdrom.rst @@ -0,0 +1,1242 @@ +============================ +Summary of CDROM ioctl calls +============================ + +- Edward A. Falk + +November, 2004 + +This document attempts to describe the ioctl(2) calls supported by +the CDROM layer. These are by-and-large implemented (as of Linux 2.6) +in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c + +ioctl values are listed in . As of this writing, they +are as follows: + + ======================== =============================================== + CDROMPAUSE Pause Audio Operation + CDROMRESUME Resume paused Audio Operation + CDROMPLAYMSF Play Audio MSF (struct cdrom_msf) + CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti) + CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr) + CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry) + CDROMSTOP Stop the cdrom drive + CDROMSTART Start the cdrom drive + CDROMEJECT Ejects the cdrom media + CDROMVOLCTRL Control output volume (struct cdrom_volctrl) + CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl) + CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes) + (struct cdrom_read) + CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes) + (struct cdrom_read) + CDROMREADAUDIO (struct cdrom_read_audio) + CDROMEJECT_SW enable(1)/disable(0) auto-ejecting + CDROMMULTISESSION Obtain the start-of-last-session + address of multi session disks + (struct cdrom_multisession) + CDROM_GET_MCN Obtain the "Universal Product Code" + if available (struct cdrom_mcn) + CDROM_GET_UPC Deprecated, use CDROM_GET_MCN instead. + CDROMRESET hard-reset the drive + CDROMVOLREAD Get the drive's volume setting + (struct cdrom_volctrl) + CDROMREADRAW read data in raw mode (2352 Bytes) + (struct cdrom_read) + CDROMREADCOOKED read data in cooked mode + CDROMSEEK seek msf address + CDROMPLAYBLK scsi-cd only, (struct cdrom_blk) + CDROMREADALL read all 2646 bytes + CDROMGETSPINDOWN return 4-bit spindown value + CDROMSETSPINDOWN set 4-bit spindown value + CDROMCLOSETRAY pendant of CDROMEJECT + CDROM_SET_OPTIONS Set behavior options + CDROM_CLEAR_OPTIONS Clear behavior options + CDROM_SELECT_SPEED Set the CD-ROM speed + CDROM_SELECT_DISC Select disc (for juke-boxes) + CDROM_MEDIA_CHANGED Check is media changed + CDROM_TIMED_MEDIA_CHANGE Check if media changed + since given time + (struct cdrom_timed_media_change_info) + CDROM_DRIVE_STATUS Get tray position, etc. + CDROM_DISC_STATUS Get disc type, etc. + CDROM_CHANGER_NSLOTS Get number of slots + CDROM_LOCKDOOR lock or unlock door + CDROM_DEBUG Turn debug messages on/off + CDROM_GET_CAPABILITY get capabilities + CDROMAUDIOBUFSIZ set the audio buffer size + DVD_READ_STRUCT Read structure + DVD_WRITE_STRUCT Write structure + DVD_AUTH Authentication + CDROM_SEND_PACKET send a packet to the drive + CDROM_NEXT_WRITABLE get next writable block + CDROM_LAST_WRITTEN get last block written on disc + ======================== =============================================== + + +The information that follows was determined from reading kernel source +code. It is likely that some corrections will be made over time. + +------------------------------------------------------------------------------ + +General: + + Unless otherwise specified, all ioctl calls return 0 on success + and -1 with errno set to an appropriate value on error. (Some + ioctls return non-negative data values.) + + Unless otherwise specified, all ioctl calls return -1 and set + errno to EFAULT on a failed attempt to copy data to or from user + address space. + + Individual drivers may return error codes not listed here. + + Unless otherwise specified, all data structures and constants + are defined in + +------------------------------------------------------------------------------ + + +CDROMPAUSE + Pause Audio Operation + + + usage:: + + ioctl(fd, CDROMPAUSE, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + +CDROMRESUME + Resume paused Audio Operation + + + usage:: + + ioctl(fd, CDROMRESUME, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + +CDROMPLAYMSF + Play Audio MSF + + (struct cdrom_msf) + + + usage:: + + struct cdrom_msf msf; + + ioctl(fd, CDROMPLAYMSF, &msf); + + inputs: + cdrom_msf structure, describing a segment of music to play + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + notes: + - MSF stands for minutes-seconds-frames + - LBA stands for logical block address + - Segment is described as start and end times, where each time + is described as minutes:seconds:frames. + A frame is 1/75 of a second. + + +CDROMPLAYTRKIND + Play Audio Track/index + + (struct cdrom_ti) + + + usage:: + + struct cdrom_ti ti; + + ioctl(fd, CDROMPLAYTRKIND, &ti); + + inputs: + cdrom_ti structure, describing a segment of music to play + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + notes: + - Segment is described as start and end times, where each time + is described as a track and an index. + + + +CDROMREADTOCHDR + Read TOC header + + (struct cdrom_tochdr) + + + usage:: + + cdrom_tochdr header; + + ioctl(fd, CDROMREADTOCHDR, &header); + + inputs: + cdrom_tochdr structure + + + outputs: + cdrom_tochdr structure + + + error return: + - ENOSYS cd drive not audio-capable. + + + +CDROMREADTOCENTRY + Read TOC entry + + (struct cdrom_tocentry) + + + usage:: + + struct cdrom_tocentry entry; + + ioctl(fd, CDROMREADTOCENTRY, &entry); + + inputs: + cdrom_tocentry structure + + + outputs: + cdrom_tocentry structure + + + error return: + - ENOSYS cd drive not audio-capable. + - EINVAL entry.cdte_format not CDROM_MSF or CDROM_LBA + - EINVAL requested track out of bounds + - EIO I/O error reading TOC + + notes: + - TOC stands for Table Of Contents + - MSF stands for minutes-seconds-frames + - LBA stands for logical block address + + + +CDROMSTOP + Stop the cdrom drive + + + usage:: + + ioctl(fd, CDROMSTOP, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + notes: + - Exact interpretation of this ioctl depends on the device, + but most seem to spin the drive down. + + +CDROMSTART + Start the cdrom drive + + + usage:: + + ioctl(fd, CDROMSTART, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + notes: + - Exact interpretation of this ioctl depends on the device, + but most seem to spin the drive up and/or close the tray. + Other devices ignore the ioctl completely. + + +CDROMEJECT + - Ejects the cdrom media + + + usage:: + + ioctl(fd, CDROMEJECT, 0); + + + inputs: + none + + + outputs: + none + + + error returns: + - ENOSYS cd drive not capable of ejecting + - EBUSY other processes are accessing drive, or door is locked + + notes: + - See CDROM_LOCKDOOR, below. + + + + +CDROMCLOSETRAY + pendant of CDROMEJECT + + + usage:: + + ioctl(fd, CDROMCLOSETRAY, 0); + + + inputs: + none + + + outputs: + none + + + error returns: + - ENOSYS cd drive not capable of closing the tray + - EBUSY other processes are accessing drive, or door is locked + + notes: + - See CDROM_LOCKDOOR, below. + + + + +CDROMVOLCTRL + Control output volume (struct cdrom_volctrl) + + + usage:: + + struct cdrom_volctrl volume; + + ioctl(fd, CDROMVOLCTRL, &volume); + + inputs: + cdrom_volctrl structure containing volumes for up to 4 + channels. + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + + +CDROMVOLREAD + Get the drive's volume setting + + (struct cdrom_volctrl) + + + usage:: + + struct cdrom_volctrl volume; + + ioctl(fd, CDROMVOLREAD, &volume); + + inputs: + none + + + outputs: + The current volume settings. + + + error return: + - ENOSYS cd drive not audio-capable. + + + +CDROMSUBCHNL + Read subchannel data + + (struct cdrom_subchnl) + + + usage:: + + struct cdrom_subchnl q; + + ioctl(fd, CDROMSUBCHNL, &q); + + inputs: + cdrom_subchnl structure + + + outputs: + cdrom_subchnl structure + + + error return: + - ENOSYS cd drive not audio-capable. + - EINVAL format not CDROM_MSF or CDROM_LBA + + notes: + - Format is converted to CDROM_MSF or CDROM_LBA + as per user request on return + + + +CDROMREADRAW + read data in raw mode (2352 Bytes) + + (struct cdrom_read) + + usage:: + + union { + + struct cdrom_msf msf; /* input */ + char buffer[CD_FRAMESIZE_RAW]; /* return */ + } arg; + ioctl(fd, CDROMREADRAW, &arg); + + inputs: + cdrom_msf structure indicating an address to read. + + Only the start values are significant. + + outputs: + Data written to address provided by user. + + + error return: + - EINVAL address less than 0, or msf less than 0:2:0 + - ENOMEM out of memory + + notes: + - As of 2.6.8.1, comments in indicate that this + ioctl accepts a cdrom_read structure, but actual source code + reads a cdrom_msf structure and writes a buffer of data to + the same address. + + - MSF values are converted to LBA values via this formula:: + + lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET; + + + + +CDROMREADMODE1 + Read CDROM mode 1 data (2048 Bytes) + + (struct cdrom_read) + + notes: + Identical to CDROMREADRAW except that block size is + CD_FRAMESIZE (2048) bytes + + + +CDROMREADMODE2 + Read CDROM mode 2 data (2336 Bytes) + + (struct cdrom_read) + + notes: + Identical to CDROMREADRAW except that block size is + CD_FRAMESIZE_RAW0 (2336) bytes + + + +CDROMREADAUDIO + (struct cdrom_read_audio) + + usage:: + + struct cdrom_read_audio ra; + + ioctl(fd, CDROMREADAUDIO, &ra); + + inputs: + cdrom_read_audio structure containing read start + point and length + + outputs: + audio data, returned to buffer indicated by ra + + + error return: + - EINVAL format not CDROM_MSF or CDROM_LBA + - EINVAL nframes not in range [1 75] + - ENXIO drive has no queue (probably means invalid fd) + - ENOMEM out of memory + + +CDROMEJECT_SW + enable(1)/disable(0) auto-ejecting + + + usage:: + + int val; + + ioctl(fd, CDROMEJECT_SW, val); + + inputs: + Flag specifying auto-eject flag. + + + outputs: + none + + + error return: + - ENOSYS Drive is not capable of ejecting. + - EBUSY Door is locked + + + + +CDROMMULTISESSION + Obtain the start-of-last-session address of multi session disks + + (struct cdrom_multisession) + + usage:: + + struct cdrom_multisession ms_info; + + ioctl(fd, CDROMMULTISESSION, &ms_info); + + inputs: + cdrom_multisession structure containing desired + + format. + + outputs: + cdrom_multisession structure is filled with last_session + information. + + error return: + - EINVAL format not CDROM_MSF or CDROM_LBA + + +CDROM_GET_MCN + Obtain the "Universal Product Code" + if available + + (struct cdrom_mcn) + + + usage:: + + struct cdrom_mcn mcn; + + ioctl(fd, CDROM_GET_MCN, &mcn); + + inputs: + none + + + outputs: + Universal Product Code + + + error return: + - ENOSYS Drive is not capable of reading MCN data. + + notes: + - Source code comments state:: + + The following function is implemented, although very few + audio discs give Universal Product Code information, which + should just be the Medium Catalog Number on the box. Note, + that the way the code is written on the CD is /not/ uniform + across all discs! + + + + +CDROM_GET_UPC + CDROM_GET_MCN (deprecated) + + + Not implemented, as of 2.6.8.1 + + + +CDROMRESET + hard-reset the drive + + + usage:: + + ioctl(fd, CDROMRESET, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - EACCES Access denied: requires CAP_SYS_ADMIN + - ENOSYS Drive is not capable of resetting. + + + + +CDROMREADCOOKED + read data in cooked mode + + + usage:: + + u8 buffer[CD_FRAMESIZE] + + ioctl(fd, CDROMREADCOOKED, buffer); + + inputs: + none + + + outputs: + 2048 bytes of data, "cooked" mode. + + + notes: + Not implemented on all drives. + + + + + +CDROMREADALL + read all 2646 bytes + + + Same as CDROMREADCOOKED, but reads 2646 bytes. + + + +CDROMSEEK + seek msf address + + + usage:: + + struct cdrom_msf msf; + + ioctl(fd, CDROMSEEK, &msf); + + inputs: + MSF address to seek to. + + + outputs: + none + + + + +CDROMPLAYBLK + scsi-cd only + + (struct cdrom_blk) + + + usage:: + + struct cdrom_blk blk; + + ioctl(fd, CDROMPLAYBLK, &blk); + + inputs: + Region to play + + + outputs: + none + + + + +CDROMGETSPINDOWN + Obsolete, was ide-cd only + + + usage:: + + char spindown; + + ioctl(fd, CDROMGETSPINDOWN, &spindown); + + inputs: + none + + + outputs: + The value of the current 4-bit spindown value. + + + + + +CDROMSETSPINDOWN + Obsolete, was ide-cd only + + + usage:: + + char spindown + + ioctl(fd, CDROMSETSPINDOWN, &spindown); + + inputs: + 4-bit value used to control spindown (TODO: more detail here) + + + outputs: + none + + + + + + +CDROM_SET_OPTIONS + Set behavior options + + + usage:: + + int options; + + ioctl(fd, CDROM_SET_OPTIONS, options); + + inputs: + New values for drive options. The logical 'or' of: + + ============== ================================== + CDO_AUTO_CLOSE close tray on first open(2) + CDO_AUTO_EJECT open tray on last release + CDO_USE_FFLAGS use O_NONBLOCK information on open + CDO_LOCK lock tray on open files + CDO_CHECK_TYPE check type on open for data + ============== ================================== + + outputs: + Returns the resulting options settings in the + ioctl return value. Returns -1 on error. + + error return: + - ENOSYS selected option(s) not supported by drive. + + + + +CDROM_CLEAR_OPTIONS + Clear behavior options + + + Same as CDROM_SET_OPTIONS, except that selected options are + turned off. + + + +CDROM_SELECT_SPEED + Set the CD-ROM speed + + + usage:: + + int speed; + + ioctl(fd, CDROM_SELECT_SPEED, speed); + + inputs: + New drive speed. + + + outputs: + none + + + error return: + - ENOSYS speed selection not supported by drive. + + + +CDROM_SELECT_DISC + Select disc (for juke-boxes) + + + usage:: + + int disk; + + ioctl(fd, CDROM_SELECT_DISC, disk); + + inputs: + Disk to load into drive. + + + outputs: + none + + + error return: + - EINVAL Disk number beyond capacity of drive + + + +CDROM_MEDIA_CHANGED + Check is media changed + + + usage:: + + int slot; + + ioctl(fd, CDROM_MEDIA_CHANGED, slot); + + inputs: + Slot number to be tested, always zero except for jukeboxes. + + May also be special values CDSL_NONE or CDSL_CURRENT + + outputs: + Ioctl return value is 0 or 1 depending on whether the media + + has been changed, or -1 on error. + + error returns: + - ENOSYS Drive can't detect media change + - EINVAL Slot number beyond capacity of drive + - ENOMEM Out of memory + + + +CDROM_DRIVE_STATUS + Get tray position, etc. + + + usage:: + + int slot; + + ioctl(fd, CDROM_DRIVE_STATUS, slot); + + inputs: + Slot number to be tested, always zero except for jukeboxes. + + May also be special values CDSL_NONE or CDSL_CURRENT + + outputs: + Ioctl return value will be one of the following values + + from : + + =================== ========================== + CDS_NO_INFO Information not available. + CDS_NO_DISC + CDS_TRAY_OPEN + CDS_DRIVE_NOT_READY + CDS_DISC_OK + -1 error + =================== ========================== + + error returns: + - ENOSYS Drive can't detect drive status + - EINVAL Slot number beyond capacity of drive + - ENOMEM Out of memory + + + + +CDROM_DISC_STATUS + Get disc type, etc. + + + usage:: + + ioctl(fd, CDROM_DISC_STATUS, 0); + + + inputs: + none + + + outputs: + Ioctl return value will be one of the following values + + from : + + - CDS_NO_INFO + - CDS_AUDIO + - CDS_MIXED + - CDS_XA_2_2 + - CDS_XA_2_1 + - CDS_DATA_1 + + error returns: + none at present + + notes: + - Source code comments state:: + + + Ok, this is where problems start. The current interface for + the CDROM_DISC_STATUS ioctl is flawed. It makes the false + assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc. + Unfortunately, while this is often the case, it is also + very common for CDs to have some tracks with data, and some + tracks with audio. Just because I feel like it, I declare + the following to be the best way to cope. If the CD has + ANY data tracks on it, it will be returned as a data CD. + If it has any XA tracks, I will return it as that. Now I + could simplify this interface by combining these returns with + the above, but this more clearly demonstrates the problem + with the current interface. Too bad this wasn't designed + to use bitmasks... -Erik + + Well, now we have the option CDS_MIXED: a mixed-type CD. + User level programmers might feel the ioctl is not very + useful. + ---david + + + + +CDROM_CHANGER_NSLOTS + Get number of slots + + + usage:: + + ioctl(fd, CDROM_CHANGER_NSLOTS, 0); + + + inputs: + none + + + outputs: + The ioctl return value will be the number of slots in a + CD changer. Typically 1 for non-multi-disk devices. + + error returns: + none + + + +CDROM_LOCKDOOR + lock or unlock door + + + usage:: + + int lock; + + ioctl(fd, CDROM_LOCKDOOR, lock); + + inputs: + Door lock flag, 1=lock, 0=unlock + + + outputs: + none + + + error returns: + - EDRIVE_CANT_DO_THIS + + Door lock function not supported. + - EBUSY + + Attempt to unlock when multiple users + have the drive open and not CAP_SYS_ADMIN + + notes: + As of 2.6.8.1, the lock flag is a global lock, meaning that + all CD drives will be locked or unlocked together. This is + probably a bug. + + The EDRIVE_CANT_DO_THIS value is defined in + and is currently (2.6.8.1) the same as EOPNOTSUPP + + + +CDROM_DEBUG + Turn debug messages on/off + + + usage:: + + int debug; + + ioctl(fd, CDROM_DEBUG, debug); + + inputs: + Cdrom debug flag, 0=disable, 1=enable + + + outputs: + The ioctl return value will be the new debug flag. + + + error return: + - EACCES Access denied: requires CAP_SYS_ADMIN + + + +CDROM_GET_CAPABILITY + get capabilities + + + usage:: + + ioctl(fd, CDROM_GET_CAPABILITY, 0); + + + inputs: + none + + + outputs: + The ioctl return value is the current device capability + flags. See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc. + + + +CDROMAUDIOBUFSIZ + set the audio buffer size + + + usage:: + + int arg; + + ioctl(fd, CDROMAUDIOBUFSIZ, val); + + inputs: + New audio buffer size + + + outputs: + The ioctl return value is the new audio buffer size, or -1 + on error. + + error return: + - ENOSYS Not supported by this driver. + + notes: + Not supported by all drivers. + + + + +DVD_READ_STRUCT Read structure + + usage:: + + dvd_struct s; + + ioctl(fd, DVD_READ_STRUCT, &s); + + inputs: + dvd_struct structure, containing: + + =================== ========================================== + type specifies the information desired, one of + DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT, + DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA, + DVD_STRUCT_MANUFACT + physical.layer_num desired layer, indexed from 0 + copyright.layer_num desired layer, indexed from 0 + disckey.agid + =================== ========================================== + + outputs: + dvd_struct structure, containing: + + =================== ================================ + physical for type == DVD_STRUCT_PHYSICAL + copyright for type == DVD_STRUCT_COPYRIGHT + disckey.value for type == DVD_STRUCT_DISCKEY + bca.{len,value} for type == DVD_STRUCT_BCA + manufact.{len,valu} for type == DVD_STRUCT_MANUFACT + =================== ================================ + + error returns: + - EINVAL physical.layer_num exceeds number of layers + - EIO Received invalid response from drive + + + +DVD_WRITE_STRUCT Write structure + + Not implemented, as of 2.6.8.1 + + + +DVD_AUTH Authentication + + usage:: + + dvd_authinfo ai; + + ioctl(fd, DVD_AUTH, &ai); + + inputs: + dvd_authinfo structure. See + + + outputs: + dvd_authinfo structure. + + + error return: + - ENOTTY ai.type not recognized. + + + +CDROM_SEND_PACKET + send a packet to the drive + + + usage:: + + struct cdrom_generic_command cgc; + + ioctl(fd, CDROM_SEND_PACKET, &cgc); + + inputs: + cdrom_generic_command structure containing the packet to send. + + + outputs: + none + + cdrom_generic_command structure containing results. + + error return: + - EIO + + command failed. + - EPERM + + Operation not permitted, either because a + write command was attempted on a drive which + is opened read-only, or because the command + requires CAP_SYS_RAWIO + - EINVAL + + cgc.data_direction not set + + + +CDROM_NEXT_WRITABLE + get next writable block + + + usage:: + + long next; + + ioctl(fd, CDROM_NEXT_WRITABLE, &next); + + inputs: + none + + + outputs: + The next writable block. + + + notes: + If the device does not support this ioctl directly, the + + ioctl will return CDROM_LAST_WRITTEN + 7. + + + +CDROM_LAST_WRITTEN + get last block written on disc + + + usage:: + + long last; + + ioctl(fd, CDROM_LAST_WRITTEN, &last); + + inputs: + none + + + outputs: + The last block written on disc + + + notes: + If the device does not support this ioctl directly, the + result is derived from the disc's table of contents. If the + table of contents can't be read, this ioctl returns an + error. diff --git a/Documentation/userspace-api/ioctl/hdio.rst b/Documentation/userspace-api/ioctl/hdio.rst new file mode 100644 index 000000000..6ee8fc886 --- /dev/null +++ b/Documentation/userspace-api/ioctl/hdio.rst @@ -0,0 +1,547 @@ +============================== +Summary of `HDIO_` ioctl calls +============================== + +- Edward A. Falk + +November, 2004 + +This document attempts to describe the ioctl(2) calls supported by +the HD/IDE layer. These are by-and-large implemented (as of Linux 5.11) +drivers/ata/libata-scsi.c. + +ioctl values are listed in . As of this writing, they +are as follows: + + ioctls that pass argument pointers to user space: + + ======================= ======================================= + HDIO_GETGEO get device geometry + HDIO_GET_32BIT get current io_32bit setting + HDIO_GET_IDENTITY get IDE identification info + HDIO_DRIVE_TASKFILE execute raw taskfile + HDIO_DRIVE_TASK execute task and special drive command + HDIO_DRIVE_CMD execute a special drive command + ======================= ======================================= + + ioctls that pass non-pointer values: + + ======================= ======================================= + HDIO_SET_32BIT change io_32bit flags + ======================= ======================================= + + +The information that follows was determined from reading kernel source +code. It is likely that some corrections will be made over time. + +------------------------------------------------------------------------------ + +General: + + Unless otherwise specified, all ioctl calls return 0 on success + and -1 with errno set to an appropriate value on error. + + Unless otherwise specified, all ioctl calls return -1 and set + errno to EFAULT on a failed attempt to copy data to or from user + address space. + + Unless otherwise specified, all data structures and constants + are defined in + +------------------------------------------------------------------------------ + +HDIO_GETGEO + get device geometry + + + usage:: + + struct hd_geometry geom; + + ioctl(fd, HDIO_GETGEO, &geom); + + + inputs: + none + + + + outputs: + hd_geometry structure containing: + + + ========= ================================== + heads number of heads + sectors number of sectors/track + cylinders number of cylinders, mod 65536 + start starting sector of this partition. + ========= ================================== + + + error returns: + - EINVAL + + if the device is not a disk drive or floppy drive, + or if the user passes a null pointer + + + notes: + Not particularly useful with modern disk drives, whose geometry + is a polite fiction anyway. Modern drives are addressed + purely by sector number nowadays (lba addressing), and the + drive geometry is an abstraction which is actually subject + to change. Currently (as of Nov 2004), the geometry values + are the "bios" values -- presumably the values the drive had + when Linux first booted. + + In addition, the cylinders field of the hd_geometry is an + unsigned short, meaning that on most architectures, this + ioctl will not return a meaningful value on drives with more + than 65535 tracks. + + The start field is unsigned long, meaning that it will not + contain a meaningful value for disks over 219 Gb in size. + + + +HDIO_GET_IDENTITY + get IDE identification info + + + usage:: + + unsigned char identity[512]; + + ioctl(fd, HDIO_GET_IDENTITY, identity); + + inputs: + none + + + + outputs: + ATA drive identity information. For full description, see + the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in + the ATA specification. + + error returns: + - EINVAL Called on a partition instead of the whole disk device + - ENOMSG IDENTIFY DEVICE information not available + + notes: + Returns information that was obtained when the drive was + probed. Some of this information is subject to change, and + this ioctl does not re-probe the drive to update the + information. + + This information is also available from /proc/ide/hdX/identify + + + +HDIO_GET_32BIT + get current io_32bit setting + + + usage:: + + long val; + + ioctl(fd, HDIO_GET_32BIT, &val); + + inputs: + none + + + + outputs: + The value of the current io_32bit setting + + + + notes: + 0=16-bit, 1=32-bit, 2,3 = 32bit+sync + + + +HDIO_DRIVE_TASKFILE + execute raw taskfile + + + Note: + If you don't have a copy of the ANSI ATA specification + handy, you should probably ignore this ioctl. + + - Execute an ATA disk command directly by writing the "taskfile" + registers of the drive. Requires ADMIN and RAWIO access + privileges. + + usage:: + + struct { + + ide_task_request_t req_task; + u8 outbuf[OUTPUT_SIZE]; + u8 inbuf[INPUT_SIZE]; + } task; + memset(&task.req_task, 0, sizeof(task.req_task)); + task.req_task.out_size = sizeof(task.outbuf); + task.req_task.in_size = sizeof(task.inbuf); + ... + ioctl(fd, HDIO_DRIVE_TASKFILE, &task); + ... + + inputs: + + (See below for details on memory area passed to ioctl.) + + ============ =================================================== + io_ports[8] values to be written to taskfile registers + hob_ports[8] high-order bytes, for extended commands. + out_flags flags indicating which registers are valid + in_flags flags indicating which registers should be returned + data_phase see below + req_cmd command type to be executed + out_size size of output buffer + outbuf buffer of data to be transmitted to disk + inbuf buffer of data to be received from disk (see [1]) + ============ =================================================== + + outputs: + + =========== ==================================================== + io_ports[] values returned in the taskfile registers + hob_ports[] high-order bytes, for extended commands. + out_flags flags indicating which registers are valid (see [2]) + in_flags flags indicating which registers should be returned + outbuf buffer of data to be transmitted to disk (see [1]) + inbuf buffer of data to be received from disk + =========== ==================================================== + + error returns: + - EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set. + - ENOMSG Device is not a disk drive. + - ENOMEM Unable to allocate memory for task + - EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8) + - EPERM + + req_cmd == TASKFILE_MULTI_OUT and drive + multi-count not yet set. + - EIO Drive failed the command. + + notes: + + [1] READ THE FOLLOWING NOTES *CAREFULLY*. THIS IOCTL IS + FULL OF GOTCHAS. Extreme caution should be used with using + this ioctl. A mistake can easily corrupt data or hang the + system. + + [2] Both the input and output buffers are copied from the + user and written back to the user, even when not used. + + [3] If one or more bits are set in out_flags and in_flags is + zero, the following values are used for in_flags.all and + written back into in_flags on completion. + + * IDE_TASKFILE_STD_IN_FLAGS | (IDE_HOB_STD_IN_FLAGS << 8) + if LBA48 addressing is enabled for the drive + * IDE_TASKFILE_STD_IN_FLAGS + if CHS/LBA28 + + The association between in_flags.all and each enable + bitfield flips depending on endianness; fortunately, TASKFILE + only uses inflags.b.data bit and ignores all other bits. + The end result is that, on any endian machines, it has no + effect other than modifying in_flags on completion. + + [4] The default value of SELECT is (0xa0|DEV_bit|LBA_bit) + except for four drives per port chipsets. For four drives + per port chipsets, it's (0xa0|DEV_bit|LBA_bit) for the first + pair and (0x80|DEV_bit|LBA_bit) for the second pair. + + [5] The argument to the ioctl is a pointer to a region of + memory containing a ide_task_request_t structure, followed + by an optional buffer of data to be transmitted to the + drive, followed by an optional buffer to receive data from + the drive. + + Command is passed to the disk drive via the ide_task_request_t + structure, which contains these fields: + + ============ =============================================== + io_ports[8] values for the taskfile registers + hob_ports[8] high-order bytes, for extended commands + out_flags flags indicating which entries in the + io_ports[] and hob_ports[] arrays + contain valid values. Type ide_reg_valid_t. + in_flags flags indicating which entries in the + io_ports[] and hob_ports[] arrays + are expected to contain valid values + on return. + data_phase See below + req_cmd Command type, see below + out_size output (user->drive) buffer size, bytes + in_size input (drive->user) buffer size, bytes + ============ =============================================== + + When out_flags is zero, the following registers are loaded. + + ============ =============================================== + HOB_FEATURE If the drive supports LBA48 + HOB_NSECTOR If the drive supports LBA48 + HOB_SECTOR If the drive supports LBA48 + HOB_LCYL If the drive supports LBA48 + HOB_HCYL If the drive supports LBA48 + FEATURE + NSECTOR + SECTOR + LCYL + HCYL + SELECT First, masked with 0xE0 if LBA48, 0xEF + otherwise; then, or'ed with the default + value of SELECT. + ============ =============================================== + + If any bit in out_flags is set, the following registers are loaded. + + ============ =============================================== + HOB_DATA If out_flags.b.data is set. HOB_DATA will + travel on DD8-DD15 on little endian machines + and on DD0-DD7 on big endian machines. + DATA If out_flags.b.data is set. DATA will + travel on DD0-DD7 on little endian machines + and on DD8-DD15 on big endian machines. + HOB_NSECTOR If out_flags.b.nsector_hob is set + HOB_SECTOR If out_flags.b.sector_hob is set + HOB_LCYL If out_flags.b.lcyl_hob is set + HOB_HCYL If out_flags.b.hcyl_hob is set + FEATURE If out_flags.b.feature is set + NSECTOR If out_flags.b.nsector is set + SECTOR If out_flags.b.sector is set + LCYL If out_flags.b.lcyl is set + HCYL If out_flags.b.hcyl is set + SELECT Or'ed with the default value of SELECT and + loaded regardless of out_flags.b.select. + ============ =============================================== + + Taskfile registers are read back from the drive into + {io|hob}_ports[] after the command completes iff one of the + following conditions is met; otherwise, the original values + will be written back, unchanged. + + 1. The drive fails the command (EIO). + 2. One or more than one bits are set in out_flags. + 3. The requested data_phase is TASKFILE_NO_DATA. + + ============ =============================================== + HOB_DATA If in_flags.b.data is set. It will contain + DD8-DD15 on little endian machines and + DD0-DD7 on big endian machines. + DATA If in_flags.b.data is set. It will contain + DD0-DD7 on little endian machines and + DD8-DD15 on big endian machines. + HOB_FEATURE If the drive supports LBA48 + HOB_NSECTOR If the drive supports LBA48 + HOB_SECTOR If the drive supports LBA48 + HOB_LCYL If the drive supports LBA48 + HOB_HCYL If the drive supports LBA48 + NSECTOR + SECTOR + LCYL + HCYL + ============ =============================================== + + The data_phase field describes the data transfer to be + performed. Value is one of: + + =================== ======================================== + TASKFILE_IN + TASKFILE_MULTI_IN + TASKFILE_OUT + TASKFILE_MULTI_OUT + TASKFILE_IN_OUT + TASKFILE_IN_DMA + TASKFILE_IN_DMAQ == IN_DMA (queueing not supported) + TASKFILE_OUT_DMA + TASKFILE_OUT_DMAQ == OUT_DMA (queueing not supported) + TASKFILE_P_IN unimplemented + TASKFILE_P_IN_DMA unimplemented + TASKFILE_P_IN_DMAQ unimplemented + TASKFILE_P_OUT unimplemented + TASKFILE_P_OUT_DMA unimplemented + TASKFILE_P_OUT_DMAQ unimplemented + =================== ======================================== + + The req_cmd field classifies the command type. It may be + one of: + + ======================== ======================================= + IDE_DRIVE_TASK_NO_DATA + IDE_DRIVE_TASK_SET_XFER unimplemented + IDE_DRIVE_TASK_IN + IDE_DRIVE_TASK_OUT unimplemented + IDE_DRIVE_TASK_RAW_WRITE + ======================== ======================================= + + [6] Do not access {in|out}_flags->all except for resetting + all the bits. Always access individual bit fields. ->all + value will flip depending on endianness. For the same + reason, do not use IDE_{TASKFILE|HOB}_STD_{OUT|IN}_FLAGS + constants defined in hdreg.h. + + + +HDIO_DRIVE_CMD + execute a special drive command + + + Note: If you don't have a copy of the ANSI ATA specification + handy, you should probably ignore this ioctl. + + usage:: + + u8 args[4+XFER_SIZE]; + + ... + ioctl(fd, HDIO_DRIVE_CMD, args); + + inputs: + Commands other than WIN_SMART: + + ======= ======= + args[0] COMMAND + args[1] NSECTOR + args[2] FEATURE + args[3] NSECTOR + ======= ======= + + WIN_SMART: + + ======= ======= + args[0] COMMAND + args[1] SECTOR + args[2] FEATURE + args[3] NSECTOR + ======= ======= + + outputs: + args[] buffer is filled with register values followed by any + + + data returned by the disk. + + ======== ==================================================== + args[0] status + args[1] error + args[2] NSECTOR + args[3] undefined + args[4+] NSECTOR * 512 bytes of data returned by the command. + ======== ==================================================== + + error returns: + - EACCES Access denied: requires CAP_SYS_RAWIO + - ENOMEM Unable to allocate memory for task + - EIO Drive reports error + + notes: + + [1] For commands other than WIN_SMART, args[1] should equal + args[3]. SECTOR, LCYL and HCYL are undefined. For + WIN_SMART, 0x4f and 0xc2 are loaded into LCYL and HCYL + respectively. In both cases SELECT will contain the default + value for the drive. Please refer to HDIO_DRIVE_TASKFILE + notes for the default value of SELECT. + + [2] If NSECTOR value is greater than zero and the drive sets + DRQ when interrupting for the command, NSECTOR * 512 bytes + are read from the device into the area following NSECTOR. + In the above example, the area would be + args[4..4+XFER_SIZE]. 16bit PIO is used regardless of + HDIO_SET_32BIT setting. + + [3] If COMMAND == WIN_SETFEATURES && FEATURE == SETFEATURES_XFER + && NSECTOR >= XFER_SW_DMA_0 && the drive supports any DMA + mode, IDE driver will try to tune the transfer mode of the + drive accordingly. + + + +HDIO_DRIVE_TASK + execute task and special drive command + + + Note: If you don't have a copy of the ANSI ATA specification + handy, you should probably ignore this ioctl. + + usage:: + + u8 args[7]; + + ... + ioctl(fd, HDIO_DRIVE_TASK, args); + + inputs: + Taskfile register values: + + ======= ======= + args[0] COMMAND + args[1] FEATURE + args[2] NSECTOR + args[3] SECTOR + args[4] LCYL + args[5] HCYL + args[6] SELECT + ======= ======= + + outputs: + Taskfile register values: + + + ======= ======= + args[0] status + args[1] error + args[2] NSECTOR + args[3] SECTOR + args[4] LCYL + args[5] HCYL + args[6] SELECT + ======= ======= + + error returns: + - EACCES Access denied: requires CAP_SYS_RAWIO + - ENOMEM Unable to allocate memory for task + - ENOMSG Device is not a disk drive. + - EIO Drive failed the command. + + notes: + + [1] DEV bit (0x10) of SELECT register is ignored and the + appropriate value for the drive is used. All other bits + are used unaltered. + + + +HDIO_SET_32BIT + change io_32bit flags + + + usage:: + + int val; + + ioctl(fd, HDIO_SET_32BIT, val); + + inputs: + New value for io_32bit flag + + + + outputs: + none + + + + error return: + - EINVAL Called on a partition instead of the whole disk device + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 3] + - EBUSY Controller busy diff --git a/Documentation/userspace-api/ioctl/index.rst b/Documentation/userspace-api/ioctl/index.rst new file mode 100644 index 000000000..475675eae --- /dev/null +++ b/Documentation/userspace-api/ioctl/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====== +IOCTLs +====== + +.. toctree:: + :maxdepth: 1 + + ioctl-number + + ioctl-decoding + + cdrom + hdio diff --git a/Documentation/userspace-api/ioctl/ioctl-decoding.rst b/Documentation/userspace-api/ioctl/ioctl-decoding.rst new file mode 100644 index 000000000..380d6bb3e --- /dev/null +++ b/Documentation/userspace-api/ioctl/ioctl-decoding.rst @@ -0,0 +1,31 @@ +============================== +Decoding an IOCTL Magic Number +============================== + +To decode a hex IOCTL code: + +Most architectures use this generic format, but check +include/ARCH/ioctl.h for specifics, e.g. powerpc +uses 3 bits to encode read/write and 13 bits for size. + + ====== ================================== + bits meaning + ====== ================================== + 31-30 00 - no parameters: uses _IO macro + 10 - read: _IOR + 01 - write: _IOW + 11 - read/write: _IOWR + + 29-16 size of arguments + + 15-8 ascii character supposedly + unique to each driver + + 7-0 function # + ====== ================================== + + +So for example 0x82187201 is a read with arg length of 0x218, +character 'r' function 1. Grepping the source reveals this is:: + + #define VFAT_IOCTL_READDIR_BOTH _IOR('r', 1, struct dirent [2]) diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst new file mode 100644 index 000000000..5f81e2a24 --- /dev/null +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -0,0 +1,381 @@ +============= +Ioctl Numbers +============= + +19 October 1999 + +Michael Elizabeth Chastain + + +If you are adding new ioctl's to the kernel, you should use the _IO +macros defined in : + + ====== == ============================================ + _IO an ioctl with no parameters + _IOW an ioctl with write parameters (copy_from_user) + _IOR an ioctl with read parameters (copy_to_user) + _IOWR an ioctl with both write and read parameters. + ====== == ============================================ + +'Write' and 'read' are from the user's point of view, just like the +system calls 'write' and 'read'. For example, a SET_FOO ioctl would +be _IOW, although the kernel would actually read data from user space; +a GET_FOO ioctl would be _IOR, although the kernel would actually write +data to user space. + +The first argument to _IO, _IOW, _IOR, or _IOWR is an identifying letter +or number from the table below. Because of the large number of drivers, +many drivers share a partial letter with other drivers. + +If you are writing a driver for a new device and need a letter, pick an +unused block with enough room for expansion: 32 to 256 ioctl commands. +You can register the block by patching this file and submitting the +patch to Linus Torvalds. Or you can e-mail me at and +I'll register one for you. + +The second argument to _IO, _IOW, _IOR, or _IOWR is a sequence number +to distinguish ioctls from each other. The third argument to _IOW, +_IOR, or _IOWR is the type of the data going into the kernel or coming +out of the kernel (e.g. 'int' or 'struct foo'). NOTE! Do NOT use +sizeof(arg) as the third argument as this results in your ioctl thinking +it passes an argument of type size_t. + +Some devices use their major number as the identifier; this is OK, as +long as it is unique. Some devices are irregular and don't follow any +convention at all. + +Following this convention is good because: + +(1) Keeping the ioctl's globally unique helps error checking: + if a program calls an ioctl on the wrong device, it will get an + error rather than some unexpected behaviour. + +(2) The 'strace' build procedure automatically finds ioctl numbers + defined with _IO, _IOW, _IOR, or _IOWR. + +(3) 'strace' can decode numbers back into useful names when the + numbers are unique. + +(4) People looking for ioctls can grep for them more easily when + this convention is used to define the ioctl numbers. + +(5) When following the convention, the driver code can use generic + code to copy the parameters between user and kernel space. + +This table lists ioctls visible from user land for Linux/x86. It contains +most drivers up to 2.6.31, but I know I am missing some. There has been +no attempt to list non-X86 architectures or ioctls from drivers/staging/. + +==== ===== ======================================================= ================================================================ +Code Seq# Include File Comments + (hex) +==== ===== ======================================================= ================================================================ +0x00 00-1F linux/fs.h conflict! +0x00 00-1F scsi/scsi_ioctl.h conflict! +0x00 00-1F linux/fb.h conflict! +0x00 00-1F linux/wavefront.h conflict! +0x02 all linux/fd.h +0x03 all linux/hdreg.h +0x04 D2-DC linux/umsdos_fs.h Dead since 2.6.11, but don't reuse these. +0x06 all linux/lp.h +0x09 all linux/raid/md_u.h +0x10 00-0F drivers/char/s390/vmcp.h +0x10 10-1F arch/s390/include/uapi/sclp_ctl.h +0x10 20-2F arch/s390/include/uapi/asm/hypfs.h +0x12 all linux/fs.h + linux/blkpg.h +0x1b all InfiniBand Subsystem + +0x20 all drivers/cdrom/cm206.h +0x22 all scsi/sg.h +0x3E 00-0F linux/counter.h +'!' 00-1F uapi/linux/seccomp.h +'#' 00-3F IEEE 1394 Subsystem + Block for the entire subsystem +'$' 00-0F linux/perf_counter.h, linux/perf_event.h +'%' 00-0F include/uapi/linux/stm.h System Trace Module subsystem + +'&' 00-07 drivers/firewire/nosy-user.h +'1' 00-1F linux/timepps.h PPS kit from Ulrich Windl + +'2' 01-04 linux/i2o.h +'3' 00-0F drivers/s390/char/raw3270.h conflict! +'3' 00-1F linux/suspend_ioctls.h, conflict! + kernel/power/user.c +'8' all SNP8023 advanced NIC card + +';' 64-7F linux/vfio.h +'=' 00-3f uapi/linux/ptp_clock.h +'@' 00-0F linux/radeonfb.h conflict! +'@' 00-0F drivers/video/aty/aty128fb.c conflict! +'A' 00-1F linux/apm_bios.h conflict! +'A' 00-0F linux/agpgart.h, conflict! + drivers/char/agp/compat_ioctl.h +'A' 00-7F sound/asound.h conflict! +'B' 00-1F linux/cciss_ioctl.h conflict! +'B' 00-0F include/linux/pmu.h conflict! +'B' C0-FF advanced bbus +'B' 00-0F xen/xenbus_dev.h conflict! +'C' all linux/soundcard.h conflict! +'C' 01-2F linux/capi.h conflict! +'C' F0-FF drivers/net/wan/cosa.h conflict! +'D' all arch/s390/include/asm/dasd.h +'D' 40-5F drivers/scsi/dpt/dtpi_ioctl.h Dead since 2022 +'D' 05 drivers/scsi/pmcraid.h +'E' all linux/input.h conflict! +'E' 00-0F xen/evtchn.h conflict! +'F' all linux/fb.h conflict! +'F' 01-02 drivers/scsi/pmcraid.h conflict! +'F' 20 drivers/video/fsl-diu-fb.h conflict! +'F' 20 drivers/video/intelfb/intelfb.h conflict! +'F' 20 linux/ivtvfb.h conflict! +'F' 20 linux/matroxfb.h conflict! +'F' 20 drivers/video/aty/atyfb_base.c conflict! +'F' 00-0F video/da8xx-fb.h conflict! +'F' 80-8F linux/arcfb.h conflict! +'F' DD video/sstfb.h conflict! +'G' 00-3F drivers/misc/sgi-gru/grulib.h conflict! +'G' 00-0F xen/gntalloc.h, xen/gntdev.h conflict! +'H' 00-7F linux/hiddev.h conflict! +'H' 00-0F linux/hidraw.h conflict! +'H' 01 linux/mei.h conflict! +'H' 02 linux/mei.h conflict! +'H' 03 linux/mei.h conflict! +'H' 00-0F sound/asound.h conflict! +'H' 20-40 sound/asound_fm.h conflict! +'H' 80-8F sound/sfnt_info.h conflict! +'H' 10-8F sound/emu10k1.h conflict! +'H' 10-1F sound/sb16_csp.h conflict! +'H' 10-1F sound/hda_hwdep.h conflict! +'H' 40-4F sound/hdspm.h conflict! +'H' 40-4F sound/hdsp.h conflict! +'H' 90 sound/usb/usx2y/usb_stream.h +'H' 00-0F uapi/misc/habanalabs.h conflict! +'H' A0 uapi/linux/usb/cdc-wdm.h +'H' C0-F0 net/bluetooth/hci.h conflict! +'H' C0-DF net/bluetooth/hidp/hidp.h conflict! +'H' C0-DF net/bluetooth/cmtp/cmtp.h conflict! +'H' C0-DF net/bluetooth/bnep/bnep.h conflict! +'H' F1 linux/hid-roccat.h +'H' F8-FA sound/firewire.h +'I' all linux/isdn.h conflict! +'I' 00-0F drivers/isdn/divert/isdn_divert.h conflict! +'I' 40-4F linux/mISDNif.h conflict! +'K' all linux/kd.h +'L' 00-1F linux/loop.h conflict! +'L' 10-1F drivers/scsi/mpt3sas/mpt3sas_ctl.h conflict! +'L' E0-FF linux/ppdd.h encrypted disk device driver + +'M' all linux/soundcard.h conflict! +'M' 01-16 mtd/mtd-abi.h conflict! + and drivers/mtd/mtdchar.c +'M' 01-03 drivers/scsi/megaraid/megaraid_sas.h +'M' 00-0F drivers/video/fsl-diu-fb.h conflict! +'N' 00-1F drivers/usb/scanner.h +'N' 40-7F drivers/block/nvme.c +'O' 00-06 mtd/ubi-user.h UBI +'P' all linux/soundcard.h conflict! +'P' 60-6F sound/sscape_ioctl.h conflict! +'P' 00-0F drivers/usb/class/usblp.c conflict! +'P' 01-09 drivers/misc/pci_endpoint_test.c conflict! +'P' 00-0F xen/privcmd.h conflict! +'Q' all linux/soundcard.h +'R' 00-1F linux/random.h conflict! +'R' 01 linux/rfkill.h conflict! +'R' C0-DF net/bluetooth/rfcomm.h +'R' E0 uapi/linux/fsl_mc.h +'S' all linux/cdrom.h conflict! +'S' 80-81 scsi/scsi_ioctl.h conflict! +'S' 82-FF scsi/scsi.h conflict! +'S' 00-7F sound/asequencer.h conflict! +'T' all linux/soundcard.h conflict! +'T' 00-AF sound/asound.h conflict! +'T' all arch/x86/include/asm/ioctls.h conflict! +'T' C0-DF linux/if_tun.h conflict! +'U' all sound/asound.h conflict! +'U' 00-CF linux/uinput.h conflict! +'U' 00-EF linux/usbdevice_fs.h +'U' C0-CF drivers/bluetooth/hci_uart.h +'V' all linux/vt.h conflict! +'V' all linux/videodev2.h conflict! +'V' C0 linux/ivtvfb.h conflict! +'V' C0 linux/ivtv.h conflict! +'V' C0 media/davinci/vpfe_capture.h conflict! +'V' C0 media/si4713.h conflict! +'W' 00-1F linux/watchdog.h conflict! +'W' 00-1F linux/wanrouter.h conflict! (pre 3.9) +'W' 00-3F sound/asound.h conflict! +'W' 40-5F drivers/pci/switch/switchtec.c +'W' 60-61 linux/watch_queue.h +'X' all fs/xfs/xfs_fs.h, conflict! + fs/xfs/linux-2.6/xfs_ioctl32.h, + include/linux/falloc.h, + linux/fs.h, +'X' all fs/ocfs2/ocfs_fs.h conflict! +'X' 01 linux/pktcdvd.h conflict! +'Z' 14-15 drivers/message/fusion/mptctl.h +'[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices + +'a' all linux/atm*.h, linux/sonet.h ATM on linux + +'a' 00-0F drivers/crypto/qat/qat_common/adf_cfg_common.h conflict! qat driver +'b' 00-FF conflict! bit3 vme host bridge + +'c' all linux/cm4000_cs.h conflict! +'c' 00-7F linux/comstats.h conflict! +'c' 00-7F linux/coda.h conflict! +'c' 00-1F linux/chio.h conflict! +'c' 80-9F arch/s390/include/asm/chsc.h conflict! +'c' A0-AF arch/x86/include/asm/msr.h conflict! +'d' 00-FF linux/char/drm/drm.h conflict! +'d' 02-40 pcmcia/ds.h conflict! +'d' F0-FF linux/digi1.h +'e' all linux/digi1.h conflict! +'f' 00-1F linux/ext2_fs.h conflict! +'f' 00-1F linux/ext3_fs.h conflict! +'f' 00-0F fs/jfs/jfs_dinode.h conflict! +'f' 00-0F fs/ext4/ext4.h conflict! +'f' 00-0F linux/fs.h conflict! +'f' 00-0F fs/ocfs2/ocfs2_fs.h conflict! +'f' 13-27 linux/fscrypt.h +'f' 81-8F linux/fsverity.h +'g' 00-0F linux/usb/gadgetfs.h +'g' 20-2F linux/usb/g_printer.h +'h' 00-7F conflict! Charon filesystem + +'h' 00-1F linux/hpet.h conflict! +'h' 80-8F fs/hfsplus/ioctl.c +'i' 00-3F linux/i2o-dev.h conflict! +'i' 0B-1F linux/ipmi.h conflict! +'i' 80-8F linux/i8k.h +'i' 90-9F `linux/iio/*.h` IIO +'j' 00-3F linux/joystick.h +'k' 00-0F linux/spi/spidev.h conflict! +'k' 00-05 video/kyro.h conflict! +'k' 10-17 linux/hsi/hsi_char.h HSI character device +'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system + +'l' 40-7F linux/udf_fs_i.h in development: + +'m' 00-09 linux/mmtimer.h conflict! +'m' all linux/mtio.h conflict! +'m' all linux/soundcard.h conflict! +'m' all linux/synclink.h conflict! +'m' 00-19 drivers/message/fusion/mptctl.h conflict! +'m' 00 drivers/scsi/megaraid/megaraid_ioctl.h conflict! +'n' 00-7F linux/ncp_fs.h and fs/ncpfs/ioctl.c +'n' 80-8F uapi/linux/nilfs2_api.h NILFS2 +'n' E0-FF linux/matroxfb.h matroxfb +'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2 +'o' 00-03 mtd/ubi-user.h conflict! (OCFS2 and UBI overlaps) +'o' 40-41 mtd/ubi-user.h UBI +'o' 01-A1 `linux/dvb/*.h` DVB +'p' 00-0F linux/phantom.h conflict! (OpenHaptics needs this) +'p' 00-1F linux/rtc.h conflict! +'p' 40-7F linux/nvram.h +'p' 80-9F linux/ppdev.h user-space parport + +'p' A1-A5 linux/pps.h LinuxPPS + +'q' 00-1F linux/serio.h +'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK + linux/ixjuser.h +'r' 00-1F linux/msdos_fs.h and fs/fat/dir.c +'s' all linux/cdk.h +'t' 00-7F linux/ppp-ioctl.h +'t' 80-8F linux/isdn_ppp.h +'t' 90-91 linux/toshiba.h toshiba and toshiba_acpi SMM +'u' 00-1F linux/smb_fs.h gone +'u' 20-3F linux/uvcvideo.h USB video class host driver +'u' 40-4f linux/udmabuf.h userspace dma-buf misc device +'v' 00-1F linux/ext2_fs.h conflict! +'v' 00-1F linux/fs.h conflict! +'v' 00-0F linux/sonypi.h conflict! +'v' 00-0F media/v4l2-subdev.h conflict! +'v' 20-27 arch/powerpc/include/uapi/asm/vas-api.h VAS API +'v' C0-FF linux/meye.h conflict! +'w' all CERN SCI driver +'y' 00-1F packet based user level communications + +'z' 00-3F CAN bus card conflict! + +'z' 40-7F CAN bus card conflict! + +'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict! +'|' 00-7F linux/media.h +0x80 00-1F linux/fb.h +0x81 00-1F linux/vduse.h +0x89 00-06 arch/x86/include/asm/sockios.h +0x89 0B-DF linux/sockios.h +0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range +0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range +0x8B all linux/wireless.h +0x8C 00-3F WiNRADiO driver + +0x90 00 drivers/cdrom/sbpcd.h +0x92 00-0F drivers/usb/mon/mon_bin.c +0x93 60-7F linux/auto_fs.h +0x94 all fs/btrfs/ioctl.h Btrfs filesystem + and linux/fs.h some lifted to vfs/generic +0x97 00-7F fs/ceph/ioctl.h Ceph file system +0x99 00-0F 537-Addinboard driver + +0xA0 all linux/sdp/sdp.h Industrial Device Project + +0xA1 0 linux/vtpm_proxy.h TPM Emulator Proxy Driver +0xA2 all uapi/linux/acrn.h ACRN hypervisor +0xA3 80-8F Port ACL in development: + +0xA3 90-9F linux/dtlk.h +0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem +0xA4 00-1F uapi/asm/sgx.h +0xA5 01-05 linux/surface_aggregator/cdev.h Microsoft Surface Platform System Aggregator + +0xA5 20-2F linux/surface_aggregator/dtx.h Microsoft Surface DTX driver + +0xAA 00-3F linux/uapi/linux/userfaultfd.h +0xAB 00-1F linux/nbd.h +0xAC 00-1F linux/raw.h +0xAD 00 Netfilter device in development: + +0xAE 00-1F linux/kvm.h Kernel-based Virtual Machine + +0xAE 40-FF linux/kvm.h Kernel-based Virtual Machine + +0xAE 20-3F linux/nitro_enclaves.h Nitro Enclaves +0xAF 00-1F linux/fsl_hypervisor.h Freescale hypervisor +0xB0 all RATIO devices in development: + +0xB1 00-1F PPPoX + +0xB3 00 linux/mmc/ioctl.h +0xB4 00-0F linux/gpio.h +0xB5 00-0F uapi/linux/rpmsg.h +0xB6 all linux/fpga-dfl.h +0xB7 all uapi/linux/remoteproc_cdev.h +0xB7 all uapi/linux/nsfs.h > +0xC0 00-0F linux/usb/iowarrior.h +0xCA 00-0F uapi/misc/cxl.h +0xCA 10-2F uapi/misc/ocxl.h +0xCA 80-BF uapi/scsi/cxlflash_ioctl.h +0xCB 00-1F CBM serial IEC bus in development: + +0xCC 00-0F drivers/misc/ibmvmc.h pseries VMC driver +0xCD 01 linux/reiserfs_fs.h +0xCE 01-02 uapi/linux/cxl_mem.h Compute Express Link Memory Devices +0xCF 02 fs/cifs/ioctl.c +0xDB 00-0F drivers/char/mwave/mwavepub.h +0xDD 00-3F ZFCP device driver see drivers/s390/scsi/ + +0xE5 00-3F linux/fuse.h +0xEC 00-01 drivers/platform/chrome/cros_ec_dev.h ChromeOS EC driver +0xEE 00-09 uapi/linux/pfrut.h Platform Firmware Runtime Update and Telemetry +0xF3 00-3F drivers/usb/misc/sisusbvga/sisusb.h sisfb (in development) + +0xF6 all LTTng Linux Trace Toolkit Next Generation + +0xF8 all arch/x86/include/uapi/asm/amd_hsmp.h AMD HSMP EPYC system management interface driver + +0xFD all linux/dm-ioctl.h +0xFE all linux/isst_if.h +==== ===== ======================================================= ================================================================ diff --git a/Documentation/userspace-api/iommu.rst b/Documentation/userspace-api/iommu.rst new file mode 100644 index 000000000..d3108c151 --- /dev/null +++ b/Documentation/userspace-api/iommu.rst @@ -0,0 +1,209 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. iommu: + +===================================== +IOMMU Userspace API +===================================== + +IOMMU UAPI is used for virtualization cases where communications are +needed between physical and virtual IOMMU drivers. For baremetal +usage, the IOMMU is a system device which does not need to communicate +with userspace directly. + +The primary use cases are guest Shared Virtual Address (SVA) and +guest IO virtual address (IOVA), wherein the vIOMMU implementation +relies on the physical IOMMU and for this reason requires interactions +with the host driver. + +.. contents:: :local: + +Functionalities +=============== +Communications of user and kernel involve both directions. The +supported user-kernel APIs are as follows: + +1. Bind/Unbind guest PASID (e.g. Intel VT-d) +2. Bind/Unbind guest PASID table (e.g. ARM SMMU) +3. Invalidate IOMMU caches upon guest requests +4. Report errors to the guest and serve page requests + +Requirements +============ +The IOMMU UAPIs are generic and extensible to meet the following +requirements: + +1. Emulated and para-virtualised vIOMMUs +2. Multiple vendors (Intel VT-d, ARM SMMU, etc.) +3. Extensions to the UAPI shall not break existing userspace + +Interfaces +========== +Although the data structures defined in IOMMU UAPI are self-contained, +there are no user API functions introduced. Instead, IOMMU UAPI is +designed to work with existing user driver frameworks such as VFIO. + +Extension Rules & Precautions +----------------------------- +When IOMMU UAPI gets extended, the data structures can *only* be +modified in two ways: + +1. Adding new fields by re-purposing the padding[] field. No size change. +2. Adding new union members at the end. May increase the structure sizes. + +No new fields can be added *after* the variable sized union in that it +will break backward compatibility when offset moves. A new flag must +be introduced whenever a change affects the structure using either +method. The IOMMU driver processes the data based on flags which +ensures backward compatibility. + +Version field is only reserved for the unlikely event of UAPI upgrade +at its entirety. + +It's *always* the caller's responsibility to indicate the size of the +structure passed by setting argsz appropriately. +Though at the same time, argsz is user provided data which is not +trusted. The argsz field allows the user app to indicate how much data +it is providing; it's still the kernel's responsibility to validate +whether it's correct and sufficient for the requested operation. + +Compatibility Checking +---------------------- +When IOMMU UAPI extension results in some structure size increase, +IOMMU UAPI code shall handle the following cases: + +1. User and kernel has exact size match +2. An older user with older kernel header (smaller UAPI size) running on a + newer kernel (larger UAPI size) +3. A newer user with newer kernel header (larger UAPI size) running + on an older kernel. +4. A malicious/misbehaving user passing illegal/invalid size but within + range. The data may contain garbage. + +Feature Checking +---------------- +While launching a guest with vIOMMU, it is strongly advised to check +the compatibility upfront, as some subsequent errors happening during +vIOMMU operation, such as cache invalidation failures cannot be nicely +escalated to the guest due to IOMMU specifications. This can lead to +catastrophic failures for the users. + +User applications such as QEMU are expected to import kernel UAPI +headers. Backward compatibility is supported per feature flags. +For example, an older QEMU (with older kernel header) can run on newer +kernel. Newer QEMU (with new kernel header) may refuse to initialize +on an older kernel if new feature flags are not supported by older +kernel. Simply recompiling existing code with newer kernel header should +not be an issue in that only existing flags are used. + +IOMMU vendor driver should report the below features to IOMMU UAPI +consumers (e.g. via VFIO). + +1. IOMMU_NESTING_FEAT_SYSWIDE_PASID +2. IOMMU_NESTING_FEAT_BIND_PGTBL +3. IOMMU_NESTING_FEAT_BIND_PASID_TABLE +4. IOMMU_NESTING_FEAT_CACHE_INVLD +5. IOMMU_NESTING_FEAT_PAGE_REQUEST + +Take VFIO as example, upon request from VFIO userspace (e.g. QEMU), +VFIO kernel code shall query IOMMU vendor driver for the support of +the above features. Query result can then be reported back to the +userspace caller. Details can be found in +Documentation/driver-api/vfio.rst. + + +Data Passing Example with VFIO +------------------------------ +As the ubiquitous userspace driver framework, VFIO is already IOMMU +aware and shares many key concepts such as device model, group, and +protection domain. Other user driver frameworks can also be extended +to support IOMMU UAPI but it is outside the scope of this document. + +In this tight-knit VFIO-IOMMU interface, the ultimate consumer of the +IOMMU UAPI data is the host IOMMU driver. VFIO facilitates user-kernel +transport, capability checking, security, and life cycle management of +process address space ID (PASID). + +VFIO layer conveys the data structures down to the IOMMU driver. It +follows the pattern below:: + + struct { + __u32 argsz; + __u32 flags; + __u8 data[]; + }; + +Here data[] contains the IOMMU UAPI data structures. VFIO has the +freedom to bundle the data as well as parse data size based on its own flags. + +In order to determine the size and feature set of the user data, argsz +and flags (or the equivalent) are also embedded in the IOMMU UAPI data +structures. + +A "__u32 argsz" field is *always* at the beginning of each structure. + +For example: +:: + + struct iommu_cache_invalidate_info { + __u32 argsz; + #define IOMMU_CACHE_INVALIDATE_INFO_VERSION_1 1 + __u32 version; + /* IOMMU paging structure cache */ + #define IOMMU_CACHE_INV_TYPE_IOTLB (1 << 0) /* IOMMU IOTLB */ + #define IOMMU_CACHE_INV_TYPE_DEV_IOTLB (1 << 1) /* Device IOTLB */ + #define IOMMU_CACHE_INV_TYPE_PASID (1 << 2) /* PASID cache */ + #define IOMMU_CACHE_INV_TYPE_NR (3) + __u8 cache; + __u8 granularity; + __u8 padding[6]; + union { + struct iommu_inv_pasid_info pasid_info; + struct iommu_inv_addr_info addr_info; + } granu; + }; + +VFIO is responsible for checking its own argsz and flags. It then +invokes appropriate IOMMU UAPI functions. The user pointers are passed +to the IOMMU layer for further processing. The responsibilities are +divided as follows: + +- Generic IOMMU layer checks argsz range based on UAPI data in the + current kernel version. + +- Generic IOMMU layer checks content of the UAPI data for non-zero + reserved bits in flags, padding fields, and unsupported version. + This is to ensure not breaking userspace in the future when these + fields or flags are used. + +- Vendor IOMMU driver checks argsz based on vendor flags. UAPI data + is consumed based on flags. Vendor driver has access to + unadulterated argsz value in case of vendor specific future + extensions. Currently, it does not perform the copy_from_user() + itself. A __user pointer can be provided in some future scenarios + where there's vendor data outside of the structure definition. + +IOMMU code treats UAPI data in two categories: + +- structure contains vendor data + (Example: iommu_uapi_cache_invalidate()) + +- structure contains only generic data + (Example: iommu_uapi_sva_bind_gpasid()) + + + +Sharing UAPI with in-kernel users +--------------------------------- +For UAPIs that are shared with in-kernel users, a wrapper function is +provided to distinguish the callers. For example, + +Userspace caller :: + + int iommu_uapi_sva_unbind_gpasid(struct iommu_domain *domain, + struct device *dev, + void __user *udata) + +In-kernel caller :: + + int iommu_sva_unbind_gpasid(struct iommu_domain *domain, + struct device *dev, ioasid_t ioasid); diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst new file mode 100644 index 000000000..cec780c2f --- /dev/null +++ b/Documentation/userspace-api/landlock.rst @@ -0,0 +1,447 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. Copyright © 2017-2020 MickaĂ«l SalaĂ¼n +.. Copyright © 2019-2020 ANSSI +.. Copyright © 2021-2022 Microsoft Corporation + +===================================== +Landlock: unprivileged access control +===================================== + +:Author: MickaĂ«l SalaĂ¼n +:Date: September 2022 + +The goal of Landlock is to enable to restrict ambient rights (e.g. global +filesystem access) for a set of processes. Because Landlock is a stackable +LSM, it makes possible to create safe security sandboxes as new security layers +in addition to the existing system-wide access-controls. This kind of sandbox +is expected to help mitigate the security impact of bugs or +unexpected/malicious behaviors in user space applications. Landlock empowers +any process, including unprivileged ones, to securely restrict themselves. + +We can quickly make sure that Landlock is enabled in the running system by +looking for "landlock: Up and running" in kernel logs (as root): ``dmesg | grep +landlock || journalctl -kg landlock`` . Developers can also easily check for +Landlock support with a :ref:`related system call `. If +Landlock is not currently supported, we need to :ref:`configure the kernel +appropriately `. + +Landlock rules +============== + +A Landlock rule describes an action on an object. An object is currently a +file hierarchy, and the related filesystem actions are defined with `access +rights`_. A set of rules is aggregated in a ruleset, which can then restrict +the thread enforcing it, and its future children. + +Defining and enforcing a security policy +---------------------------------------- + +We first need to define the ruleset that will contain our rules. For this +example, the ruleset will contain rules that only allow read actions, but write +actions will be denied. The ruleset then needs to handle both of these kind of +actions. This is required for backward and forward compatibility (i.e. the +kernel and user space may not know each other's supported restrictions), hence +the need to be explicit about the denied-by-default access rights. + +.. code-block:: c + + struct landlock_ruleset_attr ruleset_attr = { + .handled_access_fs = + LANDLOCK_ACCESS_FS_EXECUTE | + LANDLOCK_ACCESS_FS_WRITE_FILE | + LANDLOCK_ACCESS_FS_READ_FILE | + LANDLOCK_ACCESS_FS_READ_DIR | + LANDLOCK_ACCESS_FS_REMOVE_DIR | + LANDLOCK_ACCESS_FS_REMOVE_FILE | + LANDLOCK_ACCESS_FS_MAKE_CHAR | + LANDLOCK_ACCESS_FS_MAKE_DIR | + LANDLOCK_ACCESS_FS_MAKE_REG | + LANDLOCK_ACCESS_FS_MAKE_SOCK | + LANDLOCK_ACCESS_FS_MAKE_FIFO | + LANDLOCK_ACCESS_FS_MAKE_BLOCK | + LANDLOCK_ACCESS_FS_MAKE_SYM | + LANDLOCK_ACCESS_FS_REFER, + }; + +Because we may not know on which kernel version an application will be +executed, it is safer to follow a best-effort security approach. Indeed, we +should try to protect users as much as possible whatever the kernel they are +using. To avoid binary enforcement (i.e. either all security features or +none), we can leverage a dedicated Landlock command to get the current version +of the Landlock ABI and adapt the handled accesses. Let's check if we should +remove the ``LANDLOCK_ACCESS_FS_REFER`` access right which is only supported +starting with the second version of the ABI. + +.. code-block:: c + + int abi; + + abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION); + if (abi < 2) { + ruleset_attr.handled_access_fs &= ~LANDLOCK_ACCESS_FS_REFER; + } + +This enables to create an inclusive ruleset that will contain our rules. + +.. code-block:: c + + int ruleset_fd; + + ruleset_fd = landlock_create_ruleset(&ruleset_attr, sizeof(ruleset_attr), 0); + if (ruleset_fd < 0) { + perror("Failed to create a ruleset"); + return 1; + } + +We can now add a new rule to this ruleset thanks to the returned file +descriptor referring to this ruleset. The rule will only allow reading the +file hierarchy ``/usr``. Without another rule, write actions would then be +denied by the ruleset. To add ``/usr`` to the ruleset, we open it with the +``O_PATH`` flag and fill the &struct landlock_path_beneath_attr with this file +descriptor. + +.. code-block:: c + + int err; + struct landlock_path_beneath_attr path_beneath = { + .allowed_access = + LANDLOCK_ACCESS_FS_EXECUTE | + LANDLOCK_ACCESS_FS_READ_FILE | + LANDLOCK_ACCESS_FS_READ_DIR, + }; + + path_beneath.parent_fd = open("/usr", O_PATH | O_CLOEXEC); + if (path_beneath.parent_fd < 0) { + perror("Failed to open file"); + close(ruleset_fd); + return 1; + } + err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_PATH_BENEATH, + &path_beneath, 0); + close(path_beneath.parent_fd); + if (err) { + perror("Failed to update ruleset"); + close(ruleset_fd); + return 1; + } + +It may also be required to create rules following the same logic as explained +for the ruleset creation, by filtering access rights according to the Landlock +ABI version. In this example, this is not required because +``LANDLOCK_ACCESS_FS_REFER`` is not allowed by any rule. + +We now have a ruleset with one rule allowing read access to ``/usr`` while +denying all other handled accesses for the filesystem. The next step is to +restrict the current thread from gaining more privileges (e.g. thanks to a SUID +binary). + +.. code-block:: c + + if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { + perror("Failed to restrict privileges"); + close(ruleset_fd); + return 1; + } + +The current thread is now ready to sandbox itself with the ruleset. + +.. code-block:: c + + if (landlock_restrict_self(ruleset_fd, 0)) { + perror("Failed to enforce ruleset"); + close(ruleset_fd); + return 1; + } + close(ruleset_fd); + +If the ``landlock_restrict_self`` system call succeeds, the current thread is +now restricted and this policy will be enforced on all its subsequently created +children as well. Once a thread is landlocked, there is no way to remove its +security policy; only adding more restrictions is allowed. These threads are +now in a new Landlock domain, merge of their parent one (if any) with the new +ruleset. + +Full working code can be found in `samples/landlock/sandboxer.c`_. + +Good practices +-------------- + +It is recommended setting access rights to file hierarchy leaves as much as +possible. For instance, it is better to be able to have ``~/doc/`` as a +read-only hierarchy and ``~/tmp/`` as a read-write hierarchy, compared to +``~/`` as a read-only hierarchy and ``~/tmp/`` as a read-write hierarchy. +Following this good practice leads to self-sufficient hierarchies that do not +depend on their location (i.e. parent directories). This is particularly +relevant when we want to allow linking or renaming. Indeed, having consistent +access rights per directory enables to change the location of such directory +without relying on the destination directory access rights (except those that +are required for this operation, see ``LANDLOCK_ACCESS_FS_REFER`` +documentation). +Having self-sufficient hierarchies also helps to tighten the required access +rights to the minimal set of data. This also helps avoid sinkhole directories, +i.e. directories where data can be linked to but not linked from. However, +this depends on data organization, which might not be controlled by developers. +In this case, granting read-write access to ``~/tmp/``, instead of write-only +access, would potentially allow to move ``~/tmp/`` to a non-readable directory +and still keep the ability to list the content of ``~/tmp/``. + +Layers of file path access rights +--------------------------------- + +Each time a thread enforces a ruleset on itself, it updates its Landlock domain +with a new layer of policy. Indeed, this complementary policy is stacked with +the potentially other rulesets already restricting this thread. A sandboxed +thread can then safely add more constraints to itself with a new enforced +ruleset. + +One policy layer grants access to a file path if at least one of its rules +encountered on the path grants the access. A sandboxed thread can only access +a file path if all its enforced policy layers grant the access as well as all +the other system access controls (e.g. filesystem DAC, other LSM policies, +etc.). + +Bind mounts and OverlayFS +------------------------- + +Landlock enables to restrict access to file hierarchies, which means that these +access rights can be propagated with bind mounts (cf. +Documentation/filesystems/sharedsubtree.rst) but not with +Documentation/filesystems/overlayfs.rst. + +A bind mount mirrors a source file hierarchy to a destination. The destination +hierarchy is then composed of the exact same files, on which Landlock rules can +be tied, either via the source or the destination path. These rules restrict +access when they are encountered on a path, which means that they can restrict +access to multiple file hierarchies at the same time, whether these hierarchies +are the result of bind mounts or not. + +An OverlayFS mount point consists of upper and lower layers. These layers are +combined in a merge directory, result of the mount point. This merge hierarchy +may include files from the upper and lower layers, but modifications performed +on the merge hierarchy only reflects on the upper layer. From a Landlock +policy point of view, each OverlayFS layers and merge hierarchies are +standalone and contains their own set of files and directories, which is +different from bind mounts. A policy restricting an OverlayFS layer will not +restrict the resulted merged hierarchy, and vice versa. Landlock users should +then only think about file hierarchies they want to allow access to, regardless +of the underlying filesystem. + +Inheritance +----------- + +Every new thread resulting from a :manpage:`clone(2)` inherits Landlock domain +restrictions from its parent. This is similar to the seccomp inheritance (cf. +Documentation/userspace-api/seccomp_filter.rst) or any other LSM dealing with +task's :manpage:`credentials(7)`. For instance, one process's thread may apply +Landlock rules to itself, but they will not be automatically applied to other +sibling threads (unlike POSIX thread credential changes, cf. +:manpage:`nptl(7)`). + +When a thread sandboxes itself, we have the guarantee that the related security +policy will stay enforced on all this thread's descendants. This allows +creating standalone and modular security policies per application, which will +automatically be composed between themselves according to their runtime parent +policies. + +Ptrace restrictions +------------------- + +A sandboxed process has less privileges than a non-sandboxed process and must +then be subject to additional restrictions when manipulating another process. +To be allowed to use :manpage:`ptrace(2)` and related syscalls on a target +process, a sandboxed process should have a subset of the target process rules, +which means the tracee must be in a sub-domain of the tracer. + +Compatibility +============= + +Backward and forward compatibility +---------------------------------- + +Landlock is designed to be compatible with past and future versions of the +kernel. This is achieved thanks to the system call attributes and the +associated bitflags, particularly the ruleset's ``handled_access_fs``. Making +handled access right explicit enables the kernel and user space to have a clear +contract with each other. This is required to make sure sandboxing will not +get stricter with a system update, which could break applications. + +Developers can subscribe to the `Landlock mailing list +`_ to knowingly update and +test their applications with the latest available features. In the interest of +users, and because they may use different kernel versions, it is strongly +encouraged to follow a best-effort security approach by checking the Landlock +ABI version at runtime and only enforcing the supported features. + +.. _landlock_abi_versions: + +Landlock ABI versions +--------------------- + +The Landlock ABI version can be read with the sys_landlock_create_ruleset() +system call: + +.. code-block:: c + + int abi; + + abi = landlock_create_ruleset(NULL, 0, LANDLOCK_CREATE_RULESET_VERSION); + if (abi < 0) { + switch (errno) { + case ENOSYS: + printf("Landlock is not supported by the current kernel.\n"); + break; + case EOPNOTSUPP: + printf("Landlock is currently disabled.\n"); + break; + } + return 0; + } + if (abi >= 2) { + printf("Landlock supports LANDLOCK_ACCESS_FS_REFER.\n"); + } + +The following kernel interfaces are implicitly supported by the first ABI +version. Features only supported from a specific version are explicitly marked +as such. + +Kernel interface +================ + +Access rights +------------- + +.. kernel-doc:: include/uapi/linux/landlock.h + :identifiers: fs_access + +Creating a new ruleset +---------------------- + +.. kernel-doc:: security/landlock/syscalls.c + :identifiers: sys_landlock_create_ruleset + +.. kernel-doc:: include/uapi/linux/landlock.h + :identifiers: landlock_ruleset_attr + +Extending a ruleset +------------------- + +.. kernel-doc:: security/landlock/syscalls.c + :identifiers: sys_landlock_add_rule + +.. kernel-doc:: include/uapi/linux/landlock.h + :identifiers: landlock_rule_type landlock_path_beneath_attr + +Enforcing a ruleset +------------------- + +.. kernel-doc:: security/landlock/syscalls.c + :identifiers: sys_landlock_restrict_self + +Current limitations +=================== + +Filesystem topology modification +-------------------------------- + +As for file renaming and linking, a sandboxed thread cannot modify its +filesystem topology, whether via :manpage:`mount(2)` or +:manpage:`pivot_root(2)`. However, :manpage:`chroot(2)` calls are not denied. + +Special filesystems +------------------- + +Access to regular files and directories can be restricted by Landlock, +according to the handled accesses of a ruleset. However, files that do not +come from a user-visible filesystem (e.g. pipe, socket), but can still be +accessed through ``/proc//fd/*``, cannot currently be explicitly +restricted. Likewise, some special kernel filesystems such as nsfs, which can +be accessed through ``/proc//ns/*``, cannot currently be explicitly +restricted. However, thanks to the `ptrace restrictions`_, access to such +sensitive ``/proc`` files are automatically restricted according to domain +hierarchies. Future Landlock evolutions could still enable to explicitly +restrict such paths with dedicated ruleset flags. + +Ruleset layers +-------------- + +There is a limit of 16 layers of stacked rulesets. This can be an issue for a +task willing to enforce a new ruleset in complement to its 16 inherited +rulesets. Once this limit is reached, sys_landlock_restrict_self() returns +E2BIG. It is then strongly suggested to carefully build rulesets once in the +life of a thread, especially for applications able to launch other applications +that may also want to sandbox themselves (e.g. shells, container managers, +etc.). + +Memory usage +------------ + +Kernel memory allocated to create rulesets is accounted and can be restricted +by the Documentation/admin-guide/cgroup-v1/memory.rst. + +Previous limitations +==================== + +File renaming and linking (ABI < 2) +----------------------------------- + +Because Landlock targets unprivileged access controls, it needs to properly +handle composition of rules. Such property also implies rules nesting. +Properly handling multiple layers of rulesets, each one of them able to +restrict access to files, also implies inheritance of the ruleset restrictions +from a parent to its hierarchy. Because files are identified and restricted by +their hierarchy, moving or linking a file from one directory to another implies +propagation of the hierarchy constraints, or restriction of these actions +according to the potentially lost constraints. To protect against privilege +escalations through renaming or linking, and for the sake of simplicity, +Landlock previously limited linking and renaming to the same directory. +Starting with the Landlock ABI version 2, it is now possible to securely +control renaming and linking thanks to the new ``LANDLOCK_ACCESS_FS_REFER`` +access right. + +.. _kernel_support: + +Kernel support +============== + +Landlock was first introduced in Linux 5.13 but it must be configured at build +time with ``CONFIG_SECURITY_LANDLOCK=y``. Landlock must also be enabled at boot +time as the other security modules. The list of security modules enabled by +default is set with ``CONFIG_LSM``. The kernel configuration should then +contains ``CONFIG_LSM=landlock,[...]`` with ``[...]`` as the list of other +potentially useful security modules for the running system (see the +``CONFIG_LSM`` help). + +If the running kernel does not have ``landlock`` in ``CONFIG_LSM``, then we can +still enable it by adding ``lsm=landlock,[...]`` to +Documentation/admin-guide/kernel-parameters.rst thanks to the bootloader +configuration. + +Questions and answers +===================== + +What about user space sandbox managers? +--------------------------------------- + +Using user space process to enforce restrictions on kernel resources can lead +to race conditions or inconsistent evaluations (i.e. `Incorrect mirroring of +the OS code and state +`_). + +What about namespaces and containers? +------------------------------------- + +Namespaces can help create sandboxes but they are not designed for +access-control and then miss useful features for such use case (e.g. no +fine-grained restrictions). Moreover, their complexity can lead to security +issues, especially when untrusted processes can manipulate them (cf. +`Controlling access to user namespaces `_). + +Additional documentation +======================== + +* Documentation/security/landlock.rst +* https://landlock.io + +.. Links +.. _samples/landlock/sandboxer.c: + https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/samples/landlock/sandboxer.c diff --git a/Documentation/userspace-api/media/Makefile b/Documentation/userspace-api/media/Makefile new file mode 100644 index 000000000..00922aa7e --- /dev/null +++ b/Documentation/userspace-api/media/Makefile @@ -0,0 +1,63 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Rules to convert a .h file to inline RST documentation + +SRC_DIR=$(srctree)/Documentation/userspace-api/media +PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl +UAPI = $(srctree)/include/uapi/linux +KAPI = $(srctree)/include/linux + +FILES = ca.h.rst dmx.h.rst frontend.h.rst net.h.rst \ + videodev2.h.rst media.h.rst cec.h.rst lirc.h.rst + +TARGETS := $(addprefix $(BUILDDIR)/, $(FILES)) + +gen_rst = \ + echo ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions; \ + ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions + +quiet_gen_rst = echo ' PARSE $(patsubst $(srctree)/%,%,$<)'; \ + ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions + +silent_gen_rst = ${gen_rst} + +$(BUILDDIR)/ca.h.rst: ${UAPI}/dvb/ca.h ${PARSER} $(SRC_DIR)/ca.h.rst.exceptions + @$($(quiet)gen_rst) + +$(BUILDDIR)/dmx.h.rst: ${UAPI}/dvb/dmx.h ${PARSER} $(SRC_DIR)/dmx.h.rst.exceptions + @$($(quiet)gen_rst) + +$(BUILDDIR)/frontend.h.rst: ${UAPI}/dvb/frontend.h ${PARSER} $(SRC_DIR)/frontend.h.rst.exceptions + @$($(quiet)gen_rst) + +$(BUILDDIR)/net.h.rst: ${UAPI}/dvb/net.h ${PARSER} $(SRC_DIR)/net.h.rst.exceptions + @$($(quiet)gen_rst) + +$(BUILDDIR)/videodev2.h.rst: ${UAPI}/videodev2.h ${PARSER} $(SRC_DIR)/videodev2.h.rst.exceptions + @$($(quiet)gen_rst) + +$(BUILDDIR)/media.h.rst: ${UAPI}/media.h ${PARSER} $(SRC_DIR)/media.h.rst.exceptions + @$($(quiet)gen_rst) + +$(BUILDDIR)/cec.h.rst: ${UAPI}/cec.h ${PARSER} $(SRC_DIR)/cec.h.rst.exceptions + @$($(quiet)gen_rst) + +$(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exceptions + @$($(quiet)gen_rst) + +# Media build rules + +.PHONY: all html epub xml latex + +all: $(IMGDOT) $(BUILDDIR) ${TARGETS} +html: all +epub: all +xml: all +latex: $(IMGPDF) all +linkcheck: + +clean: + -rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null + +$(BUILDDIR): + $(Q)mkdir -p $@ diff --git a/Documentation/userspace-api/media/ca.h.rst.exceptions b/Documentation/userspace-api/media/ca.h.rst.exceptions new file mode 100644 index 000000000..f6828238e --- /dev/null +++ b/Documentation/userspace-api/media/ca.h.rst.exceptions @@ -0,0 +1,25 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Ignore header name +ignore define _DVBCA_H_ + +# struct ca_slot_info defines +replace define CA_CI :c:type:`ca_slot_info` +replace define CA_CI_LINK :c:type:`ca_slot_info` +replace define CA_CI_PHYS :c:type:`ca_slot_info` +replace define CA_DESCR :c:type:`ca_slot_info` +replace define CA_SC :c:type:`ca_slot_info` +replace define CA_CI_MODULE_PRESENT :c:type:`ca_slot_info` +replace define CA_CI_MODULE_READY :c:type:`ca_slot_info` + +# struct ca_descr_info defines +replace define CA_ECD :c:type:`ca_descr_info` +replace define CA_NDS :c:type:`ca_descr_info` +replace define CA_DSS :c:type:`ca_descr_info` + +# some typedefs should point to struct/enums +replace typedef ca_slot_info_t :c:type:`ca_slot_info` +replace typedef ca_descr_info_t :c:type:`ca_descr_info` +replace typedef ca_caps_t :c:type:`ca_caps` +replace typedef ca_msg_t :c:type:`ca_msg` +replace typedef ca_descr_t :c:type:`ca_descr` diff --git a/Documentation/userspace-api/media/cec.h.rst.exceptions b/Documentation/userspace-api/media/cec.h.rst.exceptions new file mode 100644 index 000000000..15fa1752d --- /dev/null +++ b/Documentation/userspace-api/media/cec.h.rst.exceptions @@ -0,0 +1,577 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Ignore header name +ignore define _CEC_UAPI_H + +# define macros to ignore + +ignore define CEC_MAX_MSG_SIZE +ignore define CEC_MAX_LOG_ADDRS + +ignore define CEC_LOG_ADDR_MASK_TV +ignore define CEC_LOG_ADDR_MASK_RECORD +ignore define CEC_LOG_ADDR_MASK_TUNER +ignore define CEC_LOG_ADDR_MASK_PLAYBACK +ignore define CEC_LOG_ADDR_MASK_AUDIOSYSTEM +ignore define CEC_LOG_ADDR_MASK_BACKUP +ignore define CEC_LOG_ADDR_MASK_SPECIFIC +ignore define CEC_LOG_ADDR_MASK_UNREGISTERED + +# Shouldn't them be documented? +ignore define CEC_LOG_ADDR_INVALID +ignore define CEC_PHYS_ADDR_INVALID + +ignore define CEC_VENDOR_ID_NONE + +ignore define CEC_MODE_INITIATOR_MSK +ignore define CEC_MODE_FOLLOWER_MSK + +# Part of CEC 2.0 spec - shouldn't be documented too? +ignore define CEC_LOG_ADDR_TV +ignore define CEC_LOG_ADDR_RECORD_1 +ignore define CEC_LOG_ADDR_RECORD_2 +ignore define CEC_LOG_ADDR_TUNER_1 +ignore define CEC_LOG_ADDR_PLAYBACK_1 +ignore define CEC_LOG_ADDR_AUDIOSYSTEM +ignore define CEC_LOG_ADDR_TUNER_2 +ignore define CEC_LOG_ADDR_TUNER_3 +ignore define CEC_LOG_ADDR_PLAYBACK_2 +ignore define CEC_LOG_ADDR_RECORD_3 +ignore define CEC_LOG_ADDR_TUNER_4 +ignore define CEC_LOG_ADDR_PLAYBACK_3 +ignore define CEC_LOG_ADDR_BACKUP_1 +ignore define CEC_LOG_ADDR_BACKUP_2 +ignore define CEC_LOG_ADDR_SPECIFIC +ignore define CEC_LOG_ADDR_UNREGISTERED +ignore define CEC_LOG_ADDR_BROADCAST + +# IMHO, those should also be documented + +ignore define CEC_MSG_ACTIVE_SOURCE +ignore define CEC_MSG_IMAGE_VIEW_ON +ignore define CEC_MSG_TEXT_VIEW_ON + +ignore define CEC_MSG_INACTIVE_SOURCE +ignore define CEC_MSG_REQUEST_ACTIVE_SOURCE +ignore define CEC_MSG_ROUTING_CHANGE +ignore define CEC_MSG_ROUTING_INFORMATION +ignore define CEC_MSG_SET_STREAM_PATH + +ignore define CEC_MSG_STANDBY + +ignore define CEC_MSG_RECORD_OFF +ignore define CEC_MSG_RECORD_ON + +ignore define CEC_OP_RECORD_SRC_OWN +ignore define CEC_OP_RECORD_SRC_DIGITAL +ignore define CEC_OP_RECORD_SRC_ANALOG +ignore define CEC_OP_RECORD_SRC_EXT_PLUG +ignore define CEC_OP_RECORD_SRC_EXT_PHYS_ADDR + +ignore define CEC_OP_SERVICE_ID_METHOD_BY_DIG_ID +ignore define CEC_OP_SERVICE_ID_METHOD_BY_CHANNEL + +ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_GEN +ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_GEN +ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_GEN +ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_BS +ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_CS +ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ARIB_T +ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_CABLE +ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_SAT +ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_ATSC_T +ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_C +ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_S +ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_S2 +ignore define CEC_OP_DIG_SERVICE_BCAST_SYSTEM_DVB_T + +ignore define CEC_OP_ANA_BCAST_TYPE_CABLE +ignore define CEC_OP_ANA_BCAST_TYPE_SATELLITE +ignore define CEC_OP_ANA_BCAST_TYPE_TERRESTRIAL + +ignore define CEC_OP_BCAST_SYSTEM_PAL_BG +ignore define CEC_OP_BCAST_SYSTEM_SECAM_LQ +ignore define CEC_OP_BCAST_SYSTEM_PAL_M +ignore define CEC_OP_BCAST_SYSTEM_NTSC_M +ignore define CEC_OP_BCAST_SYSTEM_PAL_I +ignore define CEC_OP_BCAST_SYSTEM_SECAM_DK +ignore define CEC_OP_BCAST_SYSTEM_SECAM_BG +ignore define CEC_OP_BCAST_SYSTEM_SECAM_L +ignore define CEC_OP_BCAST_SYSTEM_PAL_DK +ignore define CEC_OP_BCAST_SYSTEM_OTHER + +ignore define CEC_OP_CHANNEL_NUMBER_FMT_1_PART +ignore define CEC_OP_CHANNEL_NUMBER_FMT_2_PART + +ignore define CEC_MSG_RECORD_STATUS + +ignore define CEC_OP_RECORD_STATUS_CUR_SRC +ignore define CEC_OP_RECORD_STATUS_DIG_SERVICE +ignore define CEC_OP_RECORD_STATUS_ANA_SERVICE +ignore define CEC_OP_RECORD_STATUS_EXT_INPUT +ignore define CEC_OP_RECORD_STATUS_NO_DIG_SERVICE +ignore define CEC_OP_RECORD_STATUS_NO_ANA_SERVICE +ignore define CEC_OP_RECORD_STATUS_NO_SERVICE +ignore define CEC_OP_RECORD_STATUS_INVALID_EXT_PLUG +ignore define CEC_OP_RECORD_STATUS_INVALID_EXT_PHYS_ADDR +ignore define CEC_OP_RECORD_STATUS_UNSUP_CA +ignore define CEC_OP_RECORD_STATUS_NO_CA_ENTITLEMENTS +ignore define CEC_OP_RECORD_STATUS_CANT_COPY_SRC +ignore define CEC_OP_RECORD_STATUS_NO_MORE_COPIES +ignore define CEC_OP_RECORD_STATUS_NO_MEDIA +ignore define CEC_OP_RECORD_STATUS_PLAYING +ignore define CEC_OP_RECORD_STATUS_ALREADY_RECORDING +ignore define CEC_OP_RECORD_STATUS_MEDIA_PROT +ignore define CEC_OP_RECORD_STATUS_NO_SIGNAL +ignore define CEC_OP_RECORD_STATUS_MEDIA_PROBLEM +ignore define CEC_OP_RECORD_STATUS_NO_SPACE +ignore define CEC_OP_RECORD_STATUS_PARENTAL_LOCK +ignore define CEC_OP_RECORD_STATUS_TERMINATED_OK +ignore define CEC_OP_RECORD_STATUS_ALREADY_TERM +ignore define CEC_OP_RECORD_STATUS_OTHER + +ignore define CEC_MSG_RECORD_TV_SCREEN + +ignore define CEC_MSG_CLEAR_ANALOGUE_TIMER + +ignore define CEC_OP_REC_SEQ_SUNDAY +ignore define CEC_OP_REC_SEQ_MONDAY +ignore define CEC_OP_REC_SEQ_TUESDAY +ignore define CEC_OP_REC_SEQ_WEDNESDAY +ignore define CEC_OP_REC_SEQ_THURSDAY +ignore define CEC_OP_REC_SEQ_FRIDAY +ignore define CEC_OP_REC_SEQ_SATURDAY +ignore define CEC_OP_REC_SEQ_ONCE_ONLY + +ignore define CEC_MSG_CLEAR_DIGITAL_TIMER + +ignore define CEC_MSG_CLEAR_EXT_TIMER + +ignore define CEC_OP_EXT_SRC_PLUG +ignore define CEC_OP_EXT_SRC_PHYS_ADDR + +ignore define CEC_MSG_SET_ANALOGUE_TIMER +ignore define CEC_MSG_SET_DIGITAL_TIMER +ignore define CEC_MSG_SET_EXT_TIMER + +ignore define CEC_MSG_SET_TIMER_PROGRAM_TITLE +ignore define CEC_MSG_TIMER_CLEARED_STATUS + +ignore define CEC_OP_TIMER_CLR_STAT_RECORDING +ignore define CEC_OP_TIMER_CLR_STAT_NO_MATCHING +ignore define CEC_OP_TIMER_CLR_STAT_NO_INFO +ignore define CEC_OP_TIMER_CLR_STAT_CLEARED + +ignore define CEC_MSG_TIMER_STATUS + +ignore define CEC_OP_TIMER_OVERLAP_WARNING_NO_OVERLAP +ignore define CEC_OP_TIMER_OVERLAP_WARNING_OVERLAP + +ignore define CEC_OP_MEDIA_INFO_UNPROT_MEDIA +ignore define CEC_OP_MEDIA_INFO_PROT_MEDIA +ignore define CEC_OP_MEDIA_INFO_NO_MEDIA + +ignore define CEC_OP_PROG_IND_NOT_PROGRAMMED +ignore define CEC_OP_PROG_IND_PROGRAMMED + +ignore define CEC_OP_PROG_INFO_ENOUGH_SPACE +ignore define CEC_OP_PROG_INFO_NOT_ENOUGH_SPACE +ignore define CEC_OP_PROG_INFO_MIGHT_NOT_BE_ENOUGH_SPACE +ignore define CEC_OP_PROG_INFO_NONE_AVAILABLE + +ignore define CEC_OP_PROG_ERROR_NO_FREE_TIMER +ignore define CEC_OP_PROG_ERROR_DATE_OUT_OF_RANGE +ignore define CEC_OP_PROG_ERROR_REC_SEQ_ERROR +ignore define CEC_OP_PROG_ERROR_INV_EXT_PLUG +ignore define CEC_OP_PROG_ERROR_INV_EXT_PHYS_ADDR +ignore define CEC_OP_PROG_ERROR_CA_UNSUPP +ignore define CEC_OP_PROG_ERROR_INSUF_CA_ENTITLEMENTS +ignore define CEC_OP_PROG_ERROR_RESOLUTION_UNSUPP +ignore define CEC_OP_PROG_ERROR_PARENTAL_LOCK +ignore define CEC_OP_PROG_ERROR_CLOCK_FAILURE +ignore define CEC_OP_PROG_ERROR_DUPLICATE + +ignore define CEC_MSG_CEC_VERSION + +ignore define CEC_OP_CEC_VERSION_1_3A +ignore define CEC_OP_CEC_VERSION_1_4 +ignore define CEC_OP_CEC_VERSION_2_0 + +ignore define CEC_MSG_GET_CEC_VERSION +ignore define CEC_MSG_GIVE_PHYSICAL_ADDR +ignore define CEC_MSG_GET_MENU_LANGUAGE +ignore define CEC_MSG_REPORT_PHYSICAL_ADDR + +ignore define CEC_OP_PRIM_DEVTYPE_TV +ignore define CEC_OP_PRIM_DEVTYPE_RECORD +ignore define CEC_OP_PRIM_DEVTYPE_TUNER +ignore define CEC_OP_PRIM_DEVTYPE_PLAYBACK +ignore define CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM +ignore define CEC_OP_PRIM_DEVTYPE_SWITCH +ignore define CEC_OP_PRIM_DEVTYPE_PROCESSOR + +ignore define CEC_MSG_SET_MENU_LANGUAGE +ignore define CEC_MSG_REPORT_FEATURES + +ignore define CEC_OP_ALL_DEVTYPE_TV +ignore define CEC_OP_ALL_DEVTYPE_RECORD +ignore define CEC_OP_ALL_DEVTYPE_TUNER +ignore define CEC_OP_ALL_DEVTYPE_PLAYBACK +ignore define CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM +ignore define CEC_OP_ALL_DEVTYPE_SWITCH + +ignore define CEC_OP_FEAT_EXT + +ignore define CEC_OP_FEAT_RC_TV_PROFILE_NONE +ignore define CEC_OP_FEAT_RC_TV_PROFILE_1 +ignore define CEC_OP_FEAT_RC_TV_PROFILE_2 +ignore define CEC_OP_FEAT_RC_TV_PROFILE_3 +ignore define CEC_OP_FEAT_RC_TV_PROFILE_4 +ignore define CEC_OP_FEAT_RC_SRC_HAS_DEV_ROOT_MENU +ignore define CEC_OP_FEAT_RC_SRC_HAS_DEV_SETUP_MENU +ignore define CEC_OP_FEAT_RC_SRC_HAS_CONTENTS_MENU +ignore define CEC_OP_FEAT_RC_SRC_HAS_MEDIA_TOP_MENU +ignore define CEC_OP_FEAT_RC_SRC_HAS_MEDIA_CONTEXT_MENU + +ignore define CEC_OP_FEAT_DEV_HAS_RECORD_TV_SCREEN +ignore define CEC_OP_FEAT_DEV_HAS_SET_OSD_STRING +ignore define CEC_OP_FEAT_DEV_HAS_DECK_CONTROL +ignore define CEC_OP_FEAT_DEV_HAS_SET_AUDIO_RATE +ignore define CEC_OP_FEAT_DEV_SINK_HAS_ARC_TX +ignore define CEC_OP_FEAT_DEV_SOURCE_HAS_ARC_RX +ignore define CEC_OP_FEAT_DEV_HAS_SET_AUDIO_VOLUME_LEVEL + +ignore define CEC_MSG_GIVE_FEATURES + +ignore define CEC_MSG_DECK_CONTROL + +ignore define CEC_OP_DECK_CTL_MODE_SKIP_FWD +ignore define CEC_OP_DECK_CTL_MODE_SKIP_REV +ignore define CEC_OP_DECK_CTL_MODE_STOP +ignore define CEC_OP_DECK_CTL_MODE_EJECT + +ignore define CEC_MSG_DECK_STATUS + +ignore define CEC_OP_DECK_INFO_PLAY +ignore define CEC_OP_DECK_INFO_RECORD +ignore define CEC_OP_DECK_INFO_PLAY_REV +ignore define CEC_OP_DECK_INFO_STILL +ignore define CEC_OP_DECK_INFO_SLOW +ignore define CEC_OP_DECK_INFO_SLOW_REV +ignore define CEC_OP_DECK_INFO_FAST_FWD +ignore define CEC_OP_DECK_INFO_FAST_REV +ignore define CEC_OP_DECK_INFO_NO_MEDIA +ignore define CEC_OP_DECK_INFO_STOP +ignore define CEC_OP_DECK_INFO_SKIP_FWD +ignore define CEC_OP_DECK_INFO_SKIP_REV +ignore define CEC_OP_DECK_INFO_INDEX_SEARCH_FWD +ignore define CEC_OP_DECK_INFO_INDEX_SEARCH_REV +ignore define CEC_OP_DECK_INFO_OTHER + +ignore define CEC_MSG_GIVE_DECK_STATUS + +ignore define CEC_OP_STATUS_REQ_ON +ignore define CEC_OP_STATUS_REQ_OFF +ignore define CEC_OP_STATUS_REQ_ONCE + +ignore define CEC_MSG_PLAY + +ignore define CEC_OP_PLAY_MODE_PLAY_FWD +ignore define CEC_OP_PLAY_MODE_PLAY_REV +ignore define CEC_OP_PLAY_MODE_PLAY_STILL +ignore define CEC_OP_PLAY_MODE_PLAY_FAST_FWD_MIN +ignore define CEC_OP_PLAY_MODE_PLAY_FAST_FWD_MED +ignore define CEC_OP_PLAY_MODE_PLAY_FAST_FWD_MAX +ignore define CEC_OP_PLAY_MODE_PLAY_FAST_REV_MIN +ignore define CEC_OP_PLAY_MODE_PLAY_FAST_REV_MED +ignore define CEC_OP_PLAY_MODE_PLAY_FAST_REV_MAX +ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_FWD_MIN +ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_FWD_MED +ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_FWD_MAX +ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_REV_MIN +ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_REV_MED +ignore define CEC_OP_PLAY_MODE_PLAY_SLOW_REV_MAX + +ignore define CEC_MSG_GIVE_TUNER_DEVICE_STATUS +ignore define CEC_MSG_SELECT_ANALOGUE_SERVICE +ignore define CEC_MSG_SELECT_DIGITAL_SERVICE +ignore define CEC_MSG_TUNER_DEVICE_STATUS + +ignore define CEC_OP_REC_FLAG_USED +ignore define CEC_OP_REC_FLAG_NOT_USED + +ignore define CEC_OP_TUNER_DISPLAY_INFO_DIGITAL +ignore define CEC_OP_TUNER_DISPLAY_INFO_NONE +ignore define CEC_OP_TUNER_DISPLAY_INFO_ANALOGUE + +ignore define CEC_MSG_TUNER_STEP_DECREMENT +ignore define CEC_MSG_TUNER_STEP_INCREMENT + +ignore define CEC_MSG_DEVICE_VENDOR_ID +ignore define CEC_MSG_GIVE_DEVICE_VENDOR_ID +ignore define CEC_MSG_VENDOR_COMMAND +ignore define CEC_MSG_VENDOR_COMMAND_WITH_ID +ignore define CEC_MSG_VENDOR_REMOTE_BUTTON_DOWN +ignore define CEC_MSG_VENDOR_REMOTE_BUTTON_UP + +ignore define CEC_MSG_SET_OSD_STRING + +ignore define CEC_OP_DISP_CTL_DEFAULT +ignore define CEC_OP_DISP_CTL_UNTIL_CLEARED +ignore define CEC_OP_DISP_CTL_CLEAR + +ignore define CEC_MSG_GIVE_OSD_NAME +ignore define CEC_MSG_SET_OSD_NAME + +ignore define CEC_MSG_MENU_REQUEST + +ignore define CEC_OP_MENU_REQUEST_ACTIVATE +ignore define CEC_OP_MENU_REQUEST_DEACTIVATE +ignore define CEC_OP_MENU_REQUEST_QUERY + +ignore define CEC_MSG_MENU_STATUS + +ignore define CEC_OP_MENU_STATE_ACTIVATED +ignore define CEC_OP_MENU_STATE_DEACTIVATED + +ignore define CEC_MSG_USER_CONTROL_PRESSED + +ignore define CEC_OP_UI_CMD_SELECT +ignore define CEC_OP_UI_CMD_UP +ignore define CEC_OP_UI_CMD_DOWN +ignore define CEC_OP_UI_CMD_LEFT +ignore define CEC_OP_UI_CMD_RIGHT +ignore define CEC_OP_UI_CMD_RIGHT_UP +ignore define CEC_OP_UI_CMD_RIGHT_DOWN +ignore define CEC_OP_UI_CMD_LEFT_UP +ignore define CEC_OP_UI_CMD_LEFT_DOWN +ignore define CEC_OP_UI_CMD_DEVICE_ROOT_MENU +ignore define CEC_OP_UI_CMD_DEVICE_SETUP_MENU +ignore define CEC_OP_UI_CMD_CONTENTS_MENU +ignore define CEC_OP_UI_CMD_FAVORITE_MENU +ignore define CEC_OP_UI_CMD_BACK +ignore define CEC_OP_UI_CMD_MEDIA_TOP_MENU +ignore define CEC_OP_UI_CMD_MEDIA_CONTEXT_SENSITIVE_MENU +ignore define CEC_OP_UI_CMD_NUMBER_ENTRY_MODE +ignore define CEC_OP_UI_CMD_NUMBER_11 +ignore define CEC_OP_UI_CMD_NUMBER_12 +ignore define CEC_OP_UI_CMD_NUMBER_0_OR_NUMBER_10 +ignore define CEC_OP_UI_CMD_NUMBER_1 +ignore define CEC_OP_UI_CMD_NUMBER_2 +ignore define CEC_OP_UI_CMD_NUMBER_3 +ignore define CEC_OP_UI_CMD_NUMBER_4 +ignore define CEC_OP_UI_CMD_NUMBER_5 +ignore define CEC_OP_UI_CMD_NUMBER_6 +ignore define CEC_OP_UI_CMD_NUMBER_7 +ignore define CEC_OP_UI_CMD_NUMBER_8 +ignore define CEC_OP_UI_CMD_NUMBER_9 +ignore define CEC_OP_UI_CMD_DOT +ignore define CEC_OP_UI_CMD_ENTER +ignore define CEC_OP_UI_CMD_CLEAR +ignore define CEC_OP_UI_CMD_NEXT_FAVORITE +ignore define CEC_OP_UI_CMD_CHANNEL_UP +ignore define CEC_OP_UI_CMD_CHANNEL_DOWN +ignore define CEC_OP_UI_CMD_PREVIOUS_CHANNEL +ignore define CEC_OP_UI_CMD_SOUND_SELECT +ignore define CEC_OP_UI_CMD_INPUT_SELECT +ignore define CEC_OP_UI_CMD_DISPLAY_INFORMATION +ignore define CEC_OP_UI_CMD_HELP +ignore define CEC_OP_UI_CMD_PAGE_UP +ignore define CEC_OP_UI_CMD_PAGE_DOWN +ignore define CEC_OP_UI_CMD_POWER +ignore define CEC_OP_UI_CMD_VOLUME_UP +ignore define CEC_OP_UI_CMD_VOLUME_DOWN +ignore define CEC_OP_UI_CMD_MUTE +ignore define CEC_OP_UI_CMD_PLAY +ignore define CEC_OP_UI_CMD_STOP +ignore define CEC_OP_UI_CMD_PAUSE +ignore define CEC_OP_UI_CMD_RECORD +ignore define CEC_OP_UI_CMD_REWIND +ignore define CEC_OP_UI_CMD_FAST_FORWARD +ignore define CEC_OP_UI_CMD_EJECT +ignore define CEC_OP_UI_CMD_SKIP_FORWARD +ignore define CEC_OP_UI_CMD_SKIP_BACKWARD +ignore define CEC_OP_UI_CMD_STOP_RECORD +ignore define CEC_OP_UI_CMD_PAUSE_RECORD +ignore define CEC_OP_UI_CMD_ANGLE +ignore define CEC_OP_UI_CMD_SUB_PICTURE +ignore define CEC_OP_UI_CMD_VIDEO_ON_DEMAND +ignore define CEC_OP_UI_CMD_ELECTRONIC_PROGRAM_GUIDE +ignore define CEC_OP_UI_CMD_TIMER_PROGRAMMING +ignore define CEC_OP_UI_CMD_INITIAL_CONFIGURATION +ignore define CEC_OP_UI_CMD_SELECT_BROADCAST_TYPE +ignore define CEC_OP_UI_CMD_SELECT_SOUND_PRESENTATION +ignore define CEC_OP_UI_CMD_AUDIO_DESCRIPTION +ignore define CEC_OP_UI_CMD_INTERNET +ignore define CEC_OP_UI_CMD_3D_MODE +ignore define CEC_OP_UI_CMD_PLAY_FUNCTION +ignore define CEC_OP_UI_CMD_PAUSE_PLAY_FUNCTION +ignore define CEC_OP_UI_CMD_RECORD_FUNCTION +ignore define CEC_OP_UI_CMD_PAUSE_RECORD_FUNCTION +ignore define CEC_OP_UI_CMD_STOP_FUNCTION +ignore define CEC_OP_UI_CMD_MUTE_FUNCTION +ignore define CEC_OP_UI_CMD_RESTORE_VOLUME_FUNCTION +ignore define CEC_OP_UI_CMD_TUNE_FUNCTION +ignore define CEC_OP_UI_CMD_SELECT_MEDIA_FUNCTION +ignore define CEC_OP_UI_CMD_SELECT_AV_INPUT_FUNCTION +ignore define CEC_OP_UI_CMD_SELECT_AUDIO_INPUT_FUNCTION +ignore define CEC_OP_UI_CMD_POWER_TOGGLE_FUNCTION +ignore define CEC_OP_UI_CMD_POWER_OFF_FUNCTION +ignore define CEC_OP_UI_CMD_POWER_ON_FUNCTION +ignore define CEC_OP_UI_CMD_F1_BLUE +ignore define CEC_OP_UI_CMD_F2_RED +ignore define CEC_OP_UI_CMD_F3_GREEN +ignore define CEC_OP_UI_CMD_F4_YELLOW +ignore define CEC_OP_UI_CMD_F5 +ignore define CEC_OP_UI_CMD_DATA + +ignore define CEC_OP_UI_BCAST_TYPE_TOGGLE_ALL +ignore define CEC_OP_UI_BCAST_TYPE_TOGGLE_DIG_ANA +ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE +ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE_T +ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE_CABLE +ignore define CEC_OP_UI_BCAST_TYPE_ANALOGUE_SAT +ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL +ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_T +ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_CABLE +ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_SAT +ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_COM_SAT +ignore define CEC_OP_UI_BCAST_TYPE_DIGITAL_COM_SAT2 +ignore define CEC_OP_UI_BCAST_TYPE_IP + +ignore define CEC_OP_UI_SND_PRES_CTL_DUAL_MONO +ignore define CEC_OP_UI_SND_PRES_CTL_KARAOKE +ignore define CEC_OP_UI_SND_PRES_CTL_DOWNMIX +ignore define CEC_OP_UI_SND_PRES_CTL_REVERB +ignore define CEC_OP_UI_SND_PRES_CTL_EQUALIZER +ignore define CEC_OP_UI_SND_PRES_CTL_BASS_UP +ignore define CEC_OP_UI_SND_PRES_CTL_BASS_NEUTRAL +ignore define CEC_OP_UI_SND_PRES_CTL_BASS_DOWN +ignore define CEC_OP_UI_SND_PRES_CTL_TREBLE_UP +ignore define CEC_OP_UI_SND_PRES_CTL_TREBLE_NEUTRAL +ignore define CEC_OP_UI_SND_PRES_CTL_TREBLE_DOWN + +ignore define CEC_MSG_USER_CONTROL_RELEASED + +ignore define CEC_MSG_GIVE_DEVICE_POWER_STATUS +ignore define CEC_MSG_REPORT_POWER_STATUS + +ignore define CEC_OP_POWER_STATUS_ON +ignore define CEC_OP_POWER_STATUS_STANDBY +ignore define CEC_OP_POWER_STATUS_TO_ON +ignore define CEC_OP_POWER_STATUS_TO_STANDBY + +ignore define CEC_MSG_FEATURE_ABORT + +ignore define CEC_OP_ABORT_UNRECOGNIZED_OP +ignore define CEC_OP_ABORT_INCORRECT_MODE +ignore define CEC_OP_ABORT_NO_SOURCE +ignore define CEC_OP_ABORT_INVALID_OP +ignore define CEC_OP_ABORT_REFUSED +ignore define CEC_OP_ABORT_UNDETERMINED + +ignore define CEC_MSG_ABORT + +ignore define CEC_MSG_GIVE_AUDIO_STATUS +ignore define CEC_MSG_GIVE_SYSTEM_AUDIO_MODE_STATUS +ignore define CEC_MSG_REPORT_AUDIO_STATUS + +ignore define CEC_OP_AUD_MUTE_STATUS_OFF +ignore define CEC_OP_AUD_MUTE_STATUS_ON + +ignore define CEC_MSG_REPORT_SHORT_AUDIO_DESCRIPTOR +ignore define CEC_MSG_REQUEST_SHORT_AUDIO_DESCRIPTOR +ignore define CEC_MSG_SET_SYSTEM_AUDIO_MODE + +ignore define CEC_OP_SYS_AUD_STATUS_OFF +ignore define CEC_OP_SYS_AUD_STATUS_ON + +ignore define CEC_MSG_SYSTEM_AUDIO_MODE_REQUEST +ignore define CEC_MSG_SYSTEM_AUDIO_MODE_STATUS +ignore define CEC_MSG_SET_AUDIO_VOLUME_LEVEL + +ignore define CEC_OP_AUD_FMT_ID_CEA861 +ignore define CEC_OP_AUD_FMT_ID_CEA861_CXT + +ignore define CEC_MSG_SET_AUDIO_RATE + +ignore define CEC_OP_AUD_RATE_OFF +ignore define CEC_OP_AUD_RATE_WIDE_STD +ignore define CEC_OP_AUD_RATE_WIDE_FAST +ignore define CEC_OP_AUD_RATE_WIDE_SLOW +ignore define CEC_OP_AUD_RATE_NARROW_STD +ignore define CEC_OP_AUD_RATE_NARROW_FAST +ignore define CEC_OP_AUD_RATE_NARROW_SLOW + +ignore define CEC_MSG_INITIATE_ARC +ignore define CEC_MSG_REPORT_ARC_INITIATED +ignore define CEC_MSG_REPORT_ARC_TERMINATED +ignore define CEC_MSG_REQUEST_ARC_INITIATION +ignore define CEC_MSG_REQUEST_ARC_TERMINATION +ignore define CEC_MSG_TERMINATE_ARC + +ignore define CEC_MSG_REQUEST_CURRENT_LATENCY +ignore define CEC_MSG_REPORT_CURRENT_LATENCY + +ignore define CEC_OP_LOW_LATENCY_MODE_OFF +ignore define CEC_OP_LOW_LATENCY_MODE_ON + +ignore define CEC_OP_AUD_OUT_COMPENSATED_NA +ignore define CEC_OP_AUD_OUT_COMPENSATED_DELAY +ignore define CEC_OP_AUD_OUT_COMPENSATED_NO_DELAY +ignore define CEC_OP_AUD_OUT_COMPENSATED_PARTIAL_DELAY + +ignore define CEC_MSG_CDC_MESSAGE + +ignore define CEC_MSG_CDC_HEC_INQUIRE_STATE +ignore define CEC_MSG_CDC_HEC_REPORT_STATE + +ignore define CEC_OP_HEC_FUNC_STATE_NOT_SUPPORTED +ignore define CEC_OP_HEC_FUNC_STATE_INACTIVE +ignore define CEC_OP_HEC_FUNC_STATE_ACTIVE +ignore define CEC_OP_HEC_FUNC_STATE_ACTIVATION_FIELD + +ignore define CEC_OP_HOST_FUNC_STATE_NOT_SUPPORTED +ignore define CEC_OP_HOST_FUNC_STATE_INACTIVE +ignore define CEC_OP_HOST_FUNC_STATE_ACTIVE + +ignore define CEC_OP_ENC_FUNC_STATE_EXT_CON_NOT_SUPPORTED +ignore define CEC_OP_ENC_FUNC_STATE_EXT_CON_INACTIVE +ignore define CEC_OP_ENC_FUNC_STATE_EXT_CON_ACTIVE + +ignore define CEC_OP_CDC_ERROR_CODE_NONE +ignore define CEC_OP_CDC_ERROR_CODE_CAP_UNSUPPORTED +ignore define CEC_OP_CDC_ERROR_CODE_WRONG_STATE +ignore define CEC_OP_CDC_ERROR_CODE_OTHER + +ignore define CEC_OP_HEC_SUPPORT_NO +ignore define CEC_OP_HEC_SUPPORT_YES + +ignore define CEC_OP_HEC_ACTIVATION_ON +ignore define CEC_OP_HEC_ACTIVATION_OFF + +ignore define CEC_MSG_CDC_HEC_SET_STATE_ADJACENT +ignore define CEC_MSG_CDC_HEC_SET_STATE + +ignore define CEC_OP_HEC_SET_STATE_DEACTIVATE +ignore define CEC_OP_HEC_SET_STATE_ACTIVATE + +ignore define CEC_MSG_CDC_HEC_REQUEST_DEACTIVATION +ignore define CEC_MSG_CDC_HEC_NOTIFY_ALIVE +ignore define CEC_MSG_CDC_HEC_DISCOVER + +ignore define CEC_MSG_CDC_HPD_SET_STATE + +ignore define CEC_OP_HPD_STATE_CP_EDID_DISABLE +ignore define CEC_OP_HPD_STATE_CP_EDID_ENABLE +ignore define CEC_OP_HPD_STATE_CP_EDID_DISABLE_ENABLE +ignore define CEC_OP_HPD_STATE_EDID_DISABLE +ignore define CEC_OP_HPD_STATE_EDID_ENABLE +ignore define CEC_OP_HPD_STATE_EDID_DISABLE_ENABLE +ignore define CEC_MSG_CDC_HPD_REPORT_STATE + +ignore define CEC_OP_HPD_ERROR_NONE +ignore define CEC_OP_HPD_ERROR_INITIATOR_NOT_CAPABLE +ignore define CEC_OP_HPD_ERROR_INITIATOR_WRONG_STATE +ignore define CEC_OP_HPD_ERROR_OTHER +ignore define CEC_OP_HPD_ERROR_NONE_NO_VIDEO diff --git a/Documentation/userspace-api/media/cec/cec-api.rst b/Documentation/userspace-api/media/cec/cec-api.rst new file mode 100644 index 000000000..4d229ed8a --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-api.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. include:: + +.. _cec: + +######################################### +Part V - Consumer Electronics Control API +######################################### + +This part describes the CEC: Consumer Electronics Control + + +.. only:: html + + .. class:: toc-title + + Table of Contents + +.. toctree:: + :maxdepth: 5 + :numbered: + + cec-intro + cec-funcs + cec-pin-error-inj + cec-header + + +********************** +Revision and Copyright +********************** +Authors: + +- Verkuil, Hans + + - Initial version. + +**Copyright** |copy| 2016 : Hans Verkuil + +**************** +Revision History +**************** + +:revision: 1.0.0 / 2016-03-17 (*hv*) + +Initial revision diff --git a/Documentation/userspace-api/media/cec/cec-func-close.rst b/Documentation/userspace-api/media/cec/cec-func-close.rst new file mode 100644 index 000000000..409e70a5f --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-func-close.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC + +.. _cec-func-close: + +*********** +cec close() +*********** + +Name +==== + +cec-close - Close a cec device + +Synopsis +======== + +.. code-block:: c + + #include + +.. c:function:: int close( int fd ) + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +Description +=========== + +Closes the cec device. Resources associated with the file descriptor are +freed. The device configuration remain unchanged. + +Return Value +============ + +:c:func:`close()` returns 0 on success. On error, -1 is returned, and +``errno`` is set appropriately. Possible error codes are: + +``EBADF`` + ``fd`` is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/cec/cec-func-ioctl.rst b/Documentation/userspace-api/media/cec/cec-func-ioctl.rst new file mode 100644 index 000000000..7c93f86de --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-func-ioctl.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC + +.. _cec-func-ioctl: + +*********** +cec ioctl() +*********** + +Name +==== + +cec-ioctl - Control a cec device + +Synopsis +======== + +.. code-block:: c + + #include + +``int ioctl(int fd, int request, void *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``request`` + CEC ioctl request code as defined in the cec.h header file, for + example :ref:`CEC_ADAP_G_CAPS `. + +``argp`` + Pointer to a request-specific structure. + +Description +=========== + +The :c:func:`ioctl()` function manipulates cec device parameters. The +argument ``fd`` must be an open file descriptor. + +The ioctl ``request`` code specifies the cec function to be called. It +has encoded in it whether the argument is an input, output or read/write +parameter, and the size of the argument ``argp`` in bytes. + +Macros and structures definitions specifying cec ioctl requests and +their parameters are located in the cec.h header file. All cec ioctl +requests, their respective function and parameters are specified in +:ref:`cec-user-func`. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +Request-specific error codes are listed in the individual requests +descriptions. + +When an ioctl that takes an output or read/write parameter fails, the +parameter remains unmodified. diff --git a/Documentation/userspace-api/media/cec/cec-func-open.rst b/Documentation/userspace-api/media/cec/cec-func-open.rst new file mode 100644 index 000000000..d86563a34 --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-func-open.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC + +.. _cec-func-open: + +********** +cec open() +********** + +Name +==== + +cec-open - Open a cec device + +Synopsis +======== + +.. code-block:: c + + #include + +.. c:function:: int open( const char *device_name, int flags ) + +Arguments +========= + +``device_name`` + Device to be opened. + +``flags`` + Open flags. Access mode must be ``O_RDWR``. + + When the ``O_NONBLOCK`` flag is given, the + :ref:`CEC_RECEIVE ` and :ref:`CEC_DQEVENT ` ioctls + will return the ``EAGAIN`` error code when no message or event is available, and + ioctls :ref:`CEC_TRANSMIT `, + :ref:`CEC_ADAP_S_PHYS_ADDR ` and + :ref:`CEC_ADAP_S_LOG_ADDRS ` + all return 0. + + Other flags have no effect. + +Description +=========== + +To open a cec device applications call :c:func:`open()` with the +desired device name. The function has no side effects; the device +configuration remain unchanged. + +When the device is opened in read-only mode, attempts to modify its +configuration will result in an error, and ``errno`` will be set to +EBADF. + +Return Value +============ + +:c:func:`open()` returns the new file descriptor on success. On error, +-1 is returned, and ``errno`` is set appropriately. Possible error codes +include: + +``EACCES`` + The requested access to the file is not allowed. + +``EMFILE`` + The process already has the maximum number of files open. + +``ENFILE`` + The system limit on the total number of open files has been reached. + +``ENOMEM`` + Insufficient kernel memory was available. + +``ENXIO`` + No device corresponding to this device special file exists. diff --git a/Documentation/userspace-api/media/cec/cec-func-poll.rst b/Documentation/userspace-api/media/cec/cec-func-poll.rst new file mode 100644 index 000000000..980bbfc0b --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-func-poll.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC + +.. _cec-func-poll: + +********** +cec poll() +********** + +Name +==== + +cec-poll - Wait for some event on a file descriptor + +Synopsis +======== + +.. code-block:: c + + #include + +.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) + +Arguments +========= + +``ufds`` + List of FD events to be watched + +``nfds`` + Number of FD events at the \*ufds array + +``timeout`` + Timeout to wait for events + +Description +=========== + +With the :c:func:`poll()` function applications can wait for CEC +events. + +On success :c:func:`poll()` returns the number of file descriptors +that have been selected (that is, file descriptors for which the +``revents`` field of the respective struct :c:type:`pollfd` +is non-zero). CEC devices set the ``POLLIN`` and ``POLLRDNORM`` flags in +the ``revents`` field if there are messages in the receive queue. If the +transmit queue has room for new messages, the ``POLLOUT`` and +``POLLWRNORM`` flags are set. If there are events in the event queue, +then the ``POLLPRI`` flag is set. When the function times out it returns +a value of zero, on failure it returns -1 and the ``errno`` variable is +set appropriately. + +For more details see the :c:func:`poll()` manual page. + +Return Value +============ + +On success, :c:func:`poll()` returns the number structures which have +non-zero ``revents`` fields, or zero if the call timed out. On error -1 +is returned, and the ``errno`` variable is set appropriately: + +``EBADF`` + One or more of the ``ufds`` members specify an invalid file + descriptor. + +``EFAULT`` + ``ufds`` references an inaccessible memory area. + +``EINTR`` + The call was interrupted by a signal. + +``EINVAL`` + The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use + ``getrlimit()`` to obtain this value. diff --git a/Documentation/userspace-api/media/cec/cec-funcs.rst b/Documentation/userspace-api/media/cec/cec-funcs.rst new file mode 100644 index 000000000..aa6b790e8 --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-funcs.rst @@ -0,0 +1,23 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _cec-user-func: + +****************** +Function Reference +****************** + + +.. toctree:: + :maxdepth: 1 + + cec-func-open + cec-func-close + cec-func-ioctl + cec-func-poll + cec-ioc-adap-g-caps + cec-ioc-adap-g-log-addrs + cec-ioc-adap-g-phys-addr + cec-ioc-adap-g-conn-info + cec-ioc-dqevent + cec-ioc-g-mode + cec-ioc-receive diff --git a/Documentation/userspace-api/media/cec/cec-header.rst b/Documentation/userspace-api/media/cec/cec-header.rst new file mode 100644 index 000000000..d70736ac2 --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-header.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _cec_header: + +*************** +CEC Header File +*************** + +.. kernel-include:: $BUILDDIR/cec.h.rst + diff --git a/Documentation/userspace-api/media/cec/cec-intro.rst b/Documentation/userspace-api/media/cec/cec-intro.rst new file mode 100644 index 000000000..1884ea090 --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-intro.rst @@ -0,0 +1,42 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _cec-intro: + +Introduction +============ + +HDMI connectors provide a single pin for use by the Consumer Electronics +Control protocol. This protocol allows different devices connected by an +HDMI cable to communicate. The protocol for CEC version 1.4 is defined +in supplements 1 (CEC) and 2 (HEAC or HDMI Ethernet and Audio Return +Channel) of the HDMI 1.4a (:ref:`hdmi`) specification and the +extensions added to CEC version 2.0 are defined in chapter 11 of the +HDMI 2.0 (:ref:`hdmi2`) specification. + +The bitrate is very slow (effectively no more than 36 bytes per second) +and is based on the ancient AV.link protocol used in old SCART +connectors. The protocol closely resembles a crazy Rube Goldberg +contraption and is an unholy mix of low and high level messages. Some +messages, especially those part of the HEAC protocol layered on top of +CEC, need to be handled by the kernel, others can be handled either by +the kernel or by userspace. + +In addition, CEC can be implemented in HDMI receivers, transmitters and +in USB devices that have an HDMI input and an HDMI output and that +control just the CEC pin. + +Drivers that support CEC will create a CEC device node (/dev/cecX) to +give userspace access to the CEC adapter. The +:ref:`CEC_ADAP_G_CAPS` ioctl will tell userspace what it is allowed to do. + +In order to check the support and test it, it is suggested to download +the `v4l-utils `_ package. It +provides three tools to handle CEC: + +- cec-ctl: the Swiss army knife of CEC. Allows you to configure, transmit + and monitor CEC messages. + +- cec-compliance: does a CEC compliance test of a remote CEC device to + determine how compliant the CEC implementation is. + +- cec-follower: emulates a CEC follower. diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst new file mode 100644 index 000000000..d5e014ce1 --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-caps.rst @@ -0,0 +1,146 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC + +.. _CEC_ADAP_G_CAPS: + +********************* +ioctl CEC_ADAP_G_CAPS +********************* + +Name +==== + +CEC_ADAP_G_CAPS - Query device capabilities + +Synopsis +======== + +.. c:macro:: CEC_ADAP_G_CAPS + +``int ioctl(int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + +Description +=========== + +All cec devices must support :ref:`ioctl CEC_ADAP_G_CAPS `. To query +device information, applications call the ioctl with a pointer to a +struct :c:type:`cec_caps`. The driver fills the structure and +returns the information to the application. The ioctl never fails. + +.. tabularcolumns:: |p{1.2cm}|p{2.5cm}|p{13.6cm}| + +.. c:type:: cec_caps + +.. flat-table:: struct cec_caps + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 16 + + * - char + - ``driver[32]`` + - The name of the cec adapter driver. + * - char + - ``name[32]`` + - The name of this CEC adapter. The combination ``driver`` and + ``name`` must be unique. + * - __u32 + - ``available_log_addrs`` + - The maximum number of logical addresses that can be configured. + * - __u32 + - ``capabilities`` + - The capabilities of the CEC adapter, see + :ref:`cec-capabilities`. + * - __u32 + - ``version`` + - CEC Framework API version, formatted with the ``KERNEL_VERSION()`` + macro. + +.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.4cm}| + +.. _cec-capabilities: + +.. flat-table:: CEC Capabilities Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 8 + + * .. _`CEC-CAP-PHYS-ADDR`: + + - ``CEC_CAP_PHYS_ADDR`` + - 0x00000001 + - Userspace has to configure the physical address by calling + :ref:`ioctl CEC_ADAP_S_PHYS_ADDR `. If + this capability isn't set, then setting the physical address is + handled by the kernel whenever the EDID is set (for an HDMI + receiver) or read (for an HDMI transmitter). + * .. _`CEC-CAP-LOG-ADDRS`: + + - ``CEC_CAP_LOG_ADDRS`` + - 0x00000002 + - Userspace has to configure the logical addresses by calling + :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `. If + this capability isn't set, then the kernel will have configured + this. + * .. _`CEC-CAP-TRANSMIT`: + + - ``CEC_CAP_TRANSMIT`` + - 0x00000004 + - Userspace can transmit CEC messages by calling + :ref:`ioctl CEC_TRANSMIT `. This implies that + userspace can be a follower as well, since being able to transmit + messages is a prerequisite of becoming a follower. If this + capability isn't set, then the kernel will handle all CEC + transmits and process all CEC messages it receives. + * .. _`CEC-CAP-PASSTHROUGH`: + + - ``CEC_CAP_PASSTHROUGH`` + - 0x00000008 + - Userspace can use the passthrough mode by calling + :ref:`ioctl CEC_S_MODE `. + * .. _`CEC-CAP-RC`: + + - ``CEC_CAP_RC`` + - 0x00000010 + - This adapter supports the remote control protocol. + * .. _`CEC-CAP-MONITOR-ALL`: + + - ``CEC_CAP_MONITOR_ALL`` + - 0x00000020 + - The CEC hardware can monitor all messages, not just directed and + broadcast messages. + * .. _`CEC-CAP-NEEDS-HPD`: + + - ``CEC_CAP_NEEDS_HPD`` + - 0x00000040 + - The CEC hardware is only active if the HDMI Hotplug Detect pin is + high. This makes it impossible to use CEC to wake up displays that + set the HPD pin low when in standby mode, but keep the CEC bus + alive. + * .. _`CEC-CAP-MONITOR-PIN`: + + - ``CEC_CAP_MONITOR_PIN`` + - 0x00000080 + - The CEC hardware can monitor CEC pin changes from low to high voltage + and vice versa. When in pin monitoring mode the application will + receive ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events. + * .. _`CEC-CAP-CONNECTOR-INFO`: + + - ``CEC_CAP_CONNECTOR_INFO`` + - 0x00000100 + - If this capability is set, then :ref:`CEC_ADAP_G_CONNECTOR_INFO` can + be used. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst new file mode 100644 index 000000000..0e1985573 --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-conn-info.rst @@ -0,0 +1,106 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. +.. Copyright 2019 Google LLC +.. +.. c:namespace:: CEC + +.. _CEC_ADAP_G_CONNECTOR_INFO: + +******************************* +ioctl CEC_ADAP_G_CONNECTOR_INFO +******************************* + +Name +==== + +CEC_ADAP_G_CONNECTOR_INFO - Query HDMI connector information + +Synopsis +======== + +.. c:macro:: CEC_ADAP_G_CONNECTOR_INFO + +``int ioctl(int fd, CEC_ADAP_G_CONNECTOR_INFO, struct cec_connector_info *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + +Description +=========== + +Using this ioctl an application can learn which HDMI connector this CEC +device corresponds to. While calling this ioctl the application should +provide a pointer to a cec_connector_info struct which will be populated +by the kernel with the info provided by the adapter's driver. This ioctl +is only available if the ``CEC_CAP_CONNECTOR_INFO`` capability is set. + +.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.2cm}| + +.. c:type:: cec_connector_info + +.. flat-table:: struct cec_connector_info + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 8 + + * - __u32 + - ``type`` + - The type of connector this adapter is associated with. + * - union { + - ``(anonymous)`` + * - ``struct cec_drm_connector_info`` + - drm + - :ref:`cec-drm-connector-info` + * - } + - + +.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.4cm}| + +.. _connector-type: + +.. flat-table:: Connector types + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 8 + + * .. _`CEC-CONNECTOR-TYPE-NO-CONNECTOR`: + + - ``CEC_CONNECTOR_TYPE_NO_CONNECTOR`` + - 0 + - No connector is associated with the adapter/the information is not + provided by the driver. + * .. _`CEC-CONNECTOR-TYPE-DRM`: + + - ``CEC_CONNECTOR_TYPE_DRM`` + - 1 + - Indicates that a DRM connector is associated with this adapter. + Information about the connector can be found in + :ref:`cec-drm-connector-info`. + +.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.4cm}| + +.. c:type:: cec_drm_connector_info + +.. _cec-drm-connector-info: + +.. flat-table:: struct cec_drm_connector_info + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 8 + + * .. _`CEC-DRM-CONNECTOR-TYPE-CARD-NO`: + + - __u32 + - ``card_no`` + - DRM card number: the number from a card's path, e.g. 0 in case of + /dev/card0. + * .. _`CEC-DRM-CONNECTOR-TYPE-CONNECTOR_ID`: + + - __u32 + - ``connector_id`` + - DRM connector ID. diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst new file mode 100644 index 000000000..f3293a589 --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst @@ -0,0 +1,367 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC + +.. _CEC_ADAP_LOG_ADDRS: +.. _CEC_ADAP_G_LOG_ADDRS: +.. _CEC_ADAP_S_LOG_ADDRS: + +**************************************************** +ioctls CEC_ADAP_G_LOG_ADDRS and CEC_ADAP_S_LOG_ADDRS +**************************************************** + +Name +==== + +CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses + +Synopsis +======== + +.. c:macro:: CEC_ADAP_G_LOG_ADDRS + +``int ioctl(int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp)`` + +.. c:macro:: CEC_ADAP_S_LOG_ADDRS + +``int ioctl(int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`cec_log_addrs`. + +Description +=========== + +To query the current CEC logical addresses, applications call +:ref:`ioctl CEC_ADAP_G_LOG_ADDRS ` with a pointer to a +struct :c:type:`cec_log_addrs` where the driver stores the logical addresses. + +To set new logical addresses, applications fill in +struct :c:type:`cec_log_addrs` and call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` +with a pointer to this struct. The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` +is only available if ``CEC_CAP_LOG_ADDRS`` is set (the ``ENOTTY`` error code is +returned otherwise). The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` +can only be called by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not +the ``EBUSY`` error code will be returned. + +To clear existing logical addresses set ``num_log_addrs`` to 0. All other fields +will be ignored in that case. The adapter will go to the unconfigured state and the +``cec_version``, ``vendor_id`` and ``osd_name`` fields are all reset to their default +values (CEC version 2.0, no vendor ID and an empty OSD name). + +If the physical address is valid (see :ref:`ioctl CEC_ADAP_S_PHYS_ADDR `), +then this ioctl will block until all requested logical +addresses have been claimed. If the file descriptor is in non-blocking mode then it will +not wait for the logical addresses to be claimed, instead it just returns 0. + +A :ref:`CEC_EVENT_STATE_CHANGE ` event is sent when the +logical addresses are claimed or cleared. + +Attempting to call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` when +logical address types are already defined will return with error ``EBUSY``. + +.. c:type:: cec_log_addrs + +.. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{8.0cm}| + +.. cssclass:: longtable + +.. flat-table:: struct cec_log_addrs + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 16 + + * - __u8 + - ``log_addr[CEC_MAX_LOG_ADDRS]`` + - The actual logical addresses that were claimed. This is set by the + driver. If no logical address could be claimed, then it is set to + ``CEC_LOG_ADDR_INVALID``. If this adapter is Unregistered, then + ``log_addr[0]`` is set to 0xf and all others to + ``CEC_LOG_ADDR_INVALID``. + * - __u16 + - ``log_addr_mask`` + - The bitmask of all logical addresses this adapter has claimed. If + this adapter is Unregistered then ``log_addr_mask`` sets bit 15 + and clears all other bits. If this adapter is not configured at + all, then ``log_addr_mask`` is set to 0. Set by the driver. + * - __u8 + - ``cec_version`` + - The CEC version that this adapter shall use. See + :ref:`cec-versions`. Used to implement the + ``CEC_MSG_CEC_VERSION`` and ``CEC_MSG_REPORT_FEATURES`` messages. + Note that :ref:`CEC_OP_CEC_VERSION_1_3A ` is not allowed by the CEC + framework. + * - __u8 + - ``num_log_addrs`` + - Number of logical addresses to set up. Must be ≤ + ``available_log_addrs`` as returned by + :ref:`CEC_ADAP_G_CAPS`. All arrays in + this structure are only filled up to index + ``available_log_addrs``-1. The remaining array elements will be + ignored. Note that the CEC 2.0 standard allows for a maximum of 2 + logical addresses, although some hardware has support for more. + ``CEC_MAX_LOG_ADDRS`` is 4. The driver will return the actual + number of logical addresses it could claim, which may be less than + what was requested. If this field is set to 0, then the CEC + adapter shall clear all claimed logical addresses and all other + fields will be ignored. + * - __u32 + - ``vendor_id`` + - The vendor ID is a 24-bit number that identifies the specific + vendor or entity. Based on this ID vendor specific commands may be + defined. If you do not want a vendor ID then set it to + ``CEC_VENDOR_ID_NONE``. + * - __u32 + - ``flags`` + - Flags. See :ref:`cec-log-addrs-flags` for a list of available flags. + * - char + - ``osd_name[15]`` + - The On-Screen Display name as is returned by the + ``CEC_MSG_SET_OSD_NAME`` message. + * - __u8 + - ``primary_device_type[CEC_MAX_LOG_ADDRS]`` + - Primary device type for each logical address. See + :ref:`cec-prim-dev-types` for possible types. + * - __u8 + - ``log_addr_type[CEC_MAX_LOG_ADDRS]`` + - Logical address types. See :ref:`cec-log-addr-types` for + possible types. The driver will update this with the actual + logical address type that it claimed (e.g. it may have to fallback + to :ref:`CEC_LOG_ADDR_TYPE_UNREGISTERED `). + * - __u8 + - ``all_device_types[CEC_MAX_LOG_ADDRS]`` + - CEC 2.0 specific: the bit mask of all device types. See + :ref:`cec-all-dev-types-flags`. It is used in the CEC 2.0 + ``CEC_MSG_REPORT_FEATURES`` message. For CEC 1.4 you can either leave + this field to 0, or fill it in according to the CEC 2.0 guidelines to + give the CEC framework more information about the device type, even + though the framework won't use it directly in the CEC message. + * - __u8 + - ``features[CEC_MAX_LOG_ADDRS][12]`` + - Features for each logical address. It is used in the CEC 2.0 + ``CEC_MSG_REPORT_FEATURES`` message. The 12 bytes include both the + RC Profile and the Device Features. For CEC 1.4 you can either leave + this field to all 0, or fill it in according to the CEC 2.0 guidelines to + give the CEC framework more information about the device type, even + though the framework won't use it directly in the CEC message. + +.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.5cm}| + +.. _cec-log-addrs-flags: + +.. flat-table:: Flags for struct cec_log_addrs + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * .. _`CEC-LOG-ADDRS-FL-ALLOW-UNREG-FALLBACK`: + + - ``CEC_LOG_ADDRS_FL_ALLOW_UNREG_FALLBACK`` + - 1 + - By default if no logical address of the requested type can be claimed, then + it will go back to the unconfigured state. If this flag is set, then it will + fallback to the Unregistered logical address. Note that if the Unregistered + logical address was explicitly requested, then this flag has no effect. + * .. _`CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU`: + + - ``CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU`` + - 2 + - By default the ``CEC_MSG_USER_CONTROL_PRESSED`` and ``CEC_MSG_USER_CONTROL_RELEASED`` + messages are only passed on to the follower(s), if any. If this flag is set, + then these messages are also passed on to the remote control input subsystem + and will appear as keystrokes. This features needs to be enabled explicitly. + If CEC is used to enter e.g. passwords, then you may not want to enable this + to avoid trivial snooping of the keystrokes. + * .. _`CEC-LOG-ADDRS-FL-CDC-ONLY`: + + - ``CEC_LOG_ADDRS_FL_CDC_ONLY`` + - 4 + - If this flag is set, then the device is CDC-Only. CDC-Only CEC devices + are CEC devices that can only handle CDC messages. + + All other messages are ignored. + +.. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.5cm}| + +.. _cec-versions: + +.. flat-table:: CEC Versions + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * .. _`CEC-OP-CEC-VERSION-1-3A`: + + - ``CEC_OP_CEC_VERSION_1_3A`` + - 4 + - CEC version according to the HDMI 1.3a standard. + * .. _`CEC-OP-CEC-VERSION-1-4B`: + + - ``CEC_OP_CEC_VERSION_1_4B`` + - 5 + - CEC version according to the HDMI 1.4b standard. + * .. _`CEC-OP-CEC-VERSION-2-0`: + + - ``CEC_OP_CEC_VERSION_2_0`` + - 6 + - CEC version according to the HDMI 2.0 standard. + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| + +.. _cec-prim-dev-types: + +.. flat-table:: CEC Primary Device Types + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * .. _`CEC-OP-PRIM-DEVTYPE-TV`: + + - ``CEC_OP_PRIM_DEVTYPE_TV`` + - 0 + - Use for a TV. + * .. _`CEC-OP-PRIM-DEVTYPE-RECORD`: + + - ``CEC_OP_PRIM_DEVTYPE_RECORD`` + - 1 + - Use for a recording device. + * .. _`CEC-OP-PRIM-DEVTYPE-TUNER`: + + - ``CEC_OP_PRIM_DEVTYPE_TUNER`` + - 3 + - Use for a device with a tuner. + * .. _`CEC-OP-PRIM-DEVTYPE-PLAYBACK`: + + - ``CEC_OP_PRIM_DEVTYPE_PLAYBACK`` + - 4 + - Use for a playback device. + * .. _`CEC-OP-PRIM-DEVTYPE-AUDIOSYSTEM`: + + - ``CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM`` + - 5 + - Use for an audio system (e.g. an audio/video receiver). + * .. _`CEC-OP-PRIM-DEVTYPE-SWITCH`: + + - ``CEC_OP_PRIM_DEVTYPE_SWITCH`` + - 6 + - Use for a CEC switch. + * .. _`CEC-OP-PRIM-DEVTYPE-VIDEOPROC`: + + - ``CEC_OP_PRIM_DEVTYPE_VIDEOPROC`` + - 7 + - Use for a video processor device. + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| + +.. _cec-log-addr-types: + +.. flat-table:: CEC Logical Address Types + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 16 + + * .. _`CEC-LOG-ADDR-TYPE-TV`: + + - ``CEC_LOG_ADDR_TYPE_TV`` + - 0 + - Use for a TV. + * .. _`CEC-LOG-ADDR-TYPE-RECORD`: + + - ``CEC_LOG_ADDR_TYPE_RECORD`` + - 1 + - Use for a recording device. + * .. _`CEC-LOG-ADDR-TYPE-TUNER`: + + - ``CEC_LOG_ADDR_TYPE_TUNER`` + - 2 + - Use for a tuner device. + * .. _`CEC-LOG-ADDR-TYPE-PLAYBACK`: + + - ``CEC_LOG_ADDR_TYPE_PLAYBACK`` + - 3 + - Use for a playback device. + * .. _`CEC-LOG-ADDR-TYPE-AUDIOSYSTEM`: + + - ``CEC_LOG_ADDR_TYPE_AUDIOSYSTEM`` + - 4 + - Use for an audio system device. + * .. _`CEC-LOG-ADDR-TYPE-SPECIFIC`: + + - ``CEC_LOG_ADDR_TYPE_SPECIFIC`` + - 5 + - Use for a second TV or for a video processor device. + * .. _`CEC-LOG-ADDR-TYPE-UNREGISTERED`: + + - ``CEC_LOG_ADDR_TYPE_UNREGISTERED`` + - 6 + - Use this if you just want to remain unregistered. Used for pure + CEC switches or CDC-only devices (CDC: Capability Discovery and + Control). + + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| + +.. _cec-all-dev-types-flags: + +.. flat-table:: CEC All Device Types Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * .. _`CEC-OP-ALL-DEVTYPE-TV`: + + - ``CEC_OP_ALL_DEVTYPE_TV`` + - 0x80 + - This supports the TV type. + * .. _`CEC-OP-ALL-DEVTYPE-RECORD`: + + - ``CEC_OP_ALL_DEVTYPE_RECORD`` + - 0x40 + - This supports the Recording type. + * .. _`CEC-OP-ALL-DEVTYPE-TUNER`: + + - ``CEC_OP_ALL_DEVTYPE_TUNER`` + - 0x20 + - This supports the Tuner type. + * .. _`CEC-OP-ALL-DEVTYPE-PLAYBACK`: + + - ``CEC_OP_ALL_DEVTYPE_PLAYBACK`` + - 0x10 + - This supports the Playback type. + * .. _`CEC-OP-ALL-DEVTYPE-AUDIOSYSTEM`: + + - ``CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM`` + - 0x08 + - This supports the Audio System type. + * .. _`CEC-OP-ALL-DEVTYPE-SWITCH`: + + - ``CEC_OP_ALL_DEVTYPE_SWITCH`` + - 0x04 + - This supports the CEC Switch or Video Processing type. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` can return the following +error codes: + +ENOTTY + The ``CEC_CAP_LOG_ADDRS`` capability wasn't set, so this ioctl is not supported. + +EBUSY + The CEC adapter is currently configuring itself, or it is already configured and + ``num_log_addrs`` is non-zero, or another filehandle is in exclusive follower or + initiator mode, or the filehandle is in mode ``CEC_MODE_NO_INITIATOR``. + +EINVAL + The contents of struct :c:type:`cec_log_addrs` is invalid. diff --git a/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst new file mode 100644 index 000000000..fb22f6894 --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-ioc-adap-g-phys-addr.rst @@ -0,0 +1,94 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC + +.. _CEC_ADAP_PHYS_ADDR: +.. _CEC_ADAP_G_PHYS_ADDR: +.. _CEC_ADAP_S_PHYS_ADDR: + +**************************************************** +ioctls CEC_ADAP_G_PHYS_ADDR and CEC_ADAP_S_PHYS_ADDR +**************************************************** + +Name +==== + +CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address + +Synopsis +======== + +.. c:macro:: CEC_ADAP_G_PHYS_ADDR + +``int ioctl(int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp)`` + +.. c:macro:: CEC_ADAP_S_PHYS_ADDR + +``int ioctl(int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to the CEC address. + +Description +=========== + +To query the current physical address applications call +:ref:`ioctl CEC_ADAP_G_PHYS_ADDR ` with a pointer to a __u16 where the +driver stores the physical address. + +To set a new physical address applications store the physical address in +a __u16 and call :ref:`ioctl CEC_ADAP_S_PHYS_ADDR ` with a pointer to +this integer. The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR ` is only available if +``CEC_CAP_PHYS_ADDR`` is set (the ``ENOTTY`` error code will be returned +otherwise). The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR ` can only be called +by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not +the ``EBUSY`` error code will be returned. + +To clear an existing physical address use ``CEC_PHYS_ADDR_INVALID``. +The adapter will go to the unconfigured state. + +If logical address types have been defined (see :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `), +then this ioctl will block until all +requested logical addresses have been claimed. If the file descriptor is in non-blocking mode +then it will not wait for the logical addresses to be claimed, instead it just returns 0. + +A :ref:`CEC_EVENT_STATE_CHANGE ` event is sent when the physical address +changes. + +The physical address is a 16-bit number where each group of 4 bits +represent a digit of the physical address a.b.c.d where the most +significant 4 bits represent 'a'. The CEC root device (usually the TV) +has address 0.0.0.0. Every device that is hooked up to an input of the +TV has address a.0.0.0 (where 'a' is ≥ 1), devices hooked up to those in +turn have addresses a.b.0.0, etc. So a topology of up to 5 devices deep +is supported. The physical address a device shall use is stored in the +EDID of the sink. + +For example, the EDID for each HDMI input of the TV will have a +different physical address of the form a.0.0.0 that the sources will +read out and use as their physical address. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR ` can return the following +error codes: + +ENOTTY + The ``CEC_CAP_PHYS_ADDR`` capability wasn't set, so this ioctl is not supported. + +EBUSY + Another filehandle is in exclusive follower or initiator mode, or the filehandle + is in mode ``CEC_MODE_NO_INITIATOR``. + +EINVAL + The physical address is malformed. diff --git a/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst new file mode 100644 index 000000000..71d6a9e81 --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst @@ -0,0 +1,245 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC + +.. _CEC_DQEVENT: + +***************** +ioctl CEC_DQEVENT +***************** + +Name +==== + +CEC_DQEVENT - Dequeue a CEC event + +Synopsis +======== + +.. c:macro:: CEC_DQEVENT + +``int ioctl(int fd, CEC_DQEVENT, struct cec_event *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + +Description +=========== + +CEC devices can send asynchronous events. These can be retrieved by +calling :c:func:`CEC_DQEVENT`. If the file descriptor is in +non-blocking mode and no event is pending, then it will return -1 and +set errno to the ``EAGAIN`` error code. + +The internal event queues are per-filehandle and per-event type. If +there is no more room in a queue then the last event is overwritten with +the new one. This means that intermediate results can be thrown away but +that the latest event is always available. This also means that is it +possible to read two successive events that have the same value (e.g. +two :ref:`CEC_EVENT_STATE_CHANGE ` events with +the same state). In that case the intermediate state changes were lost but +it is guaranteed that the state did change in between the two events. + +.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.2cm}| + +.. c:type:: cec_event_state_change + +.. flat-table:: struct cec_event_state_change + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 8 + + * - __u16 + - ``phys_addr`` + - The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no + valid physical address is set. + * - __u16 + - ``log_addr_mask`` + - The current set of claimed logical addresses. This is 0 if no logical + addresses are claimed or if ``phys_addr`` is ``CEC_PHYS_ADDR_INVALID``. + If bit 15 is set (``1 << CEC_LOG_ADDR_UNREGISTERED``) then this device + has the unregistered logical address. In that case all other bits are 0. + * - __u16 + - ``have_conn_info`` + - If non-zero, then HDMI connector information is available. + This field is only valid if ``CEC_CAP_CONNECTOR_INFO`` is set. If that + capability is set and ``have_conn_info`` is zero, then that indicates + that the HDMI connector device is not instantiated, either because + the HDMI driver is still configuring the device or because the HDMI + device was unbound. + +.. c:type:: cec_event_lost_msgs + +.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.3cm}| + +.. flat-table:: struct cec_event_lost_msgs + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 16 + + * - __u32 + - ``lost_msgs`` + - Set to the number of lost messages since the filehandle was opened + or since the last time this event was dequeued for this + filehandle. The messages lost are the oldest messages. So when a + new message arrives and there is no more room, then the oldest + message is discarded to make room for the new one. The internal + size of the message queue guarantees that all messages received in + the last two seconds will be stored. Since messages should be + replied to within a second according to the CEC specification, + this is more than enough. + +.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.2cm}| + +.. c:type:: cec_event + +.. flat-table:: struct cec_event + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 8 + + * - __u64 + - ``ts`` + - Timestamp of the event in ns. + + The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. + + To access the same clock from userspace use :c:func:`clock_gettime`. + * - __u32 + - ``event`` + - The CEC event type, see :ref:`cec-events`. + * - __u32 + - ``flags`` + - Event flags, see :ref:`cec-event-flags`. + * - union { + - (anonymous) + * - struct cec_event_state_change + - ``state_change`` + - The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE ` + event. + * - struct cec_event_lost_msgs + - ``lost_msgs`` + - The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS ` + event. + * - } + - + +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| + +.. _cec-events: + +.. flat-table:: CEC Events Types + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 16 + + * .. _`CEC-EVENT-STATE-CHANGE`: + + - ``CEC_EVENT_STATE_CHANGE`` + - 1 + - Generated when the CEC Adapter's state changes. When open() is + called an initial event will be generated for that filehandle with + the CEC Adapter's state at that time. + * .. _`CEC-EVENT-LOST-MSGS`: + + - ``CEC_EVENT_LOST_MSGS`` + - 2 + - Generated if one or more CEC messages were lost because the + application didn't dequeue CEC messages fast enough. + * .. _`CEC-EVENT-PIN-CEC-LOW`: + + - ``CEC_EVENT_PIN_CEC_LOW`` + - 3 + - Generated if the CEC pin goes from a high voltage to a low voltage. + Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` + capability set. + * .. _`CEC-EVENT-PIN-CEC-HIGH`: + + - ``CEC_EVENT_PIN_CEC_HIGH`` + - 4 + - Generated if the CEC pin goes from a low voltage to a high voltage. + Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` + capability set. + * .. _`CEC-EVENT-PIN-HPD-LOW`: + + - ``CEC_EVENT_PIN_HPD_LOW`` + - 5 + - Generated if the HPD pin goes from a high voltage to a low voltage. + Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` + capability set. When open() is called, the HPD pin can be read and + if the HPD is low, then an initial event will be generated for that + filehandle. + * .. _`CEC-EVENT-PIN-HPD-HIGH`: + + - ``CEC_EVENT_PIN_HPD_HIGH`` + - 6 + - Generated if the HPD pin goes from a low voltage to a high voltage. + Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` + capability set. When open() is called, the HPD pin can be read and + if the HPD is high, then an initial event will be generated for that + filehandle. + * .. _`CEC-EVENT-PIN-5V-LOW`: + + - ``CEC_EVENT_PIN_5V_LOW`` + - 6 + - Generated if the 5V pin goes from a high voltage to a low voltage. + Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` + capability set. When open() is called, the 5V pin can be read and + if the 5V is low, then an initial event will be generated for that + filehandle. + * .. _`CEC-EVENT-PIN-5V-HIGH`: + + - ``CEC_EVENT_PIN_5V_HIGH`` + - 7 + - Generated if the 5V pin goes from a low voltage to a high voltage. + Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN`` + capability set. When open() is called, the 5V pin can be read and + if the 5V is high, then an initial event will be generated for that + filehandle. + +.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.7cm}| + +.. _cec-event-flags: + +.. flat-table:: CEC Event Flags + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 8 + + * .. _`CEC-EVENT-FL-INITIAL-STATE`: + + - ``CEC_EVENT_FL_INITIAL_STATE`` + - 1 + - Set for the initial events that are generated when the device is + opened. See the table above for which events do this. This allows + applications to learn the initial state of the CEC adapter at + open() time. + * .. _`CEC-EVENT-FL-DROPPED-EVENTS`: + + - ``CEC_EVENT_FL_DROPPED_EVENTS`` + - 2 + - Set if one or more events of the given event type have been dropped. + This is an indication that the application cannot keep up. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +The :ref:`ioctl CEC_DQEVENT ` can return the following +error codes: + +EAGAIN + This is returned when the filehandle is in non-blocking mode and there + are no pending events. + +ERESTARTSYS + An interrupt (e.g. Ctrl-C) arrived while in blocking mode waiting for + events to arrive. diff --git a/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst new file mode 100644 index 000000000..5fe105a13 --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst @@ -0,0 +1,294 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC + +.. _CEC_MODE: +.. _CEC_G_MODE: +.. _CEC_S_MODE: + +******************************** +ioctls CEC_G_MODE and CEC_S_MODE +******************************** + +CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter + +Synopsis +======== + +.. c:macro:: CEC_G_MODE + +``int ioctl(int fd, CEC_G_MODE, __u32 *argp)`` + +.. c:macro:: CEC_S_MODE + +``int ioctl(int fd, CEC_S_MODE, __u32 *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to CEC mode. + +Description +=========== + +By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent +applications from stepping on each others toes it must be possible to +obtain exclusive access to the CEC adapter. This ioctl sets the +filehandle to initiator and/or follower mode which can be exclusive +depending on the chosen mode. The initiator is the filehandle that is +used to initiate messages, i.e. it commands other CEC devices. The +follower is the filehandle that receives messages sent to the CEC +adapter and processes them. The same filehandle can be both initiator +and follower, or this role can be taken by two different filehandles. + +When a CEC message is received, then the CEC framework will decide how +it will be processed. If the message is a reply to an earlier +transmitted message, then the reply is sent back to the filehandle that +is waiting for it. In addition the CEC framework will process it. + +If the message is not a reply, then the CEC framework will process it +first. If there is no follower, then the message is just discarded and a +feature abort is sent back to the initiator if the framework couldn't +process it. If there is a follower, then the message is passed on to the +follower who will use :ref:`ioctl CEC_RECEIVE ` to dequeue +the new message. The framework expects the follower to make the right +decisions. + +The CEC framework will process core messages unless requested otherwise +by the follower. The follower can enable the passthrough mode. In that +case, the CEC framework will pass on most core messages without +processing them and the follower will have to implement those messages. +There are some messages that the core will always process, regardless of +the passthrough mode. See :ref:`cec-core-processing` for details. + +If there is no initiator, then any CEC filehandle can use +:ref:`ioctl CEC_TRANSMIT `. If there is an exclusive +initiator then only that initiator can call +:ref:`CEC_TRANSMIT`. The follower can of course +always call :ref:`ioctl CEC_TRANSMIT `. + +Available initiator modes are: + +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| + +.. _cec-mode-initiator_e: + +.. flat-table:: Initiator Modes + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 16 + + * .. _`CEC-MODE-NO-INITIATOR`: + + - ``CEC_MODE_NO_INITIATOR`` + - 0x0 + - This is not an initiator, i.e. it cannot transmit CEC messages or + make any other changes to the CEC adapter. + * .. _`CEC-MODE-INITIATOR`: + + - ``CEC_MODE_INITIATOR`` + - 0x1 + - This is an initiator (the default when the device is opened) and + it can transmit CEC messages and make changes to the CEC adapter, + unless there is an exclusive initiator. + * .. _`CEC-MODE-EXCL-INITIATOR`: + + - ``CEC_MODE_EXCL_INITIATOR`` + - 0x2 + - This is an exclusive initiator and this file descriptor is the + only one that can transmit CEC messages and make changes to the + CEC adapter. If someone else is already the exclusive initiator + then an attempt to become one will return the ``EBUSY`` error code + error. + +Available follower modes are: + +.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{9.8cm}| + +.. _cec-mode-follower_e: + +.. cssclass:: longtable + +.. flat-table:: Follower Modes + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 16 + + * .. _`CEC-MODE-NO-FOLLOWER`: + + - ``CEC_MODE_NO_FOLLOWER`` + - 0x00 + - This is not a follower (the default when the device is opened). + * .. _`CEC-MODE-FOLLOWER`: + + - ``CEC_MODE_FOLLOWER`` + - 0x10 + - This is a follower and it will receive CEC messages unless there + is an exclusive follower. You cannot become a follower if + :ref:`CEC_CAP_TRANSMIT ` is not set or if :ref:`CEC_MODE_NO_INITIATOR ` + was specified, the ``EINVAL`` error code is returned in that case. + * .. _`CEC-MODE-EXCL-FOLLOWER`: + + - ``CEC_MODE_EXCL_FOLLOWER`` + - 0x20 + - This is an exclusive follower and only this file descriptor will + receive CEC messages for processing. If someone else is already + the exclusive follower then an attempt to become one will return + the ``EBUSY`` error code. You cannot become a follower if + :ref:`CEC_CAP_TRANSMIT ` is not set or if :ref:`CEC_MODE_NO_INITIATOR ` + was specified, the ``EINVAL`` error code is returned in that case. + * .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`: + + - ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU`` + - 0x30 + - This is an exclusive follower and only this file descriptor will + receive CEC messages for processing. In addition it will put the + CEC device into passthrough mode, allowing the exclusive follower + to handle most core messages instead of relying on the CEC + framework for that. If someone else is already the exclusive + follower then an attempt to become one will return the ``EBUSY`` error + code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT ` + is not set or if :ref:`CEC_MODE_NO_INITIATOR ` was specified, + the ``EINVAL`` error code is returned in that case. + * .. _`CEC-MODE-MONITOR-PIN`: + + - ``CEC_MODE_MONITOR_PIN`` + - 0xd0 + - Put the file descriptor into pin monitoring mode. Can only be used in + combination with :ref:`CEC_MODE_NO_INITIATOR `, + otherwise the ``EINVAL`` error code will be returned. + This mode requires that the :ref:`CEC_CAP_MONITOR_PIN ` + capability is set, otherwise the ``EINVAL`` error code is returned. + While in pin monitoring mode this file descriptor can receive the + ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events to see the + low-level CEC pin transitions. This is very useful for debugging. + This mode is only allowed if the process has the ``CAP_NET_ADMIN`` + capability. If that is not set, then the ``EPERM`` error code is returned. + * .. _`CEC-MODE-MONITOR`: + + - ``CEC_MODE_MONITOR`` + - 0xe0 + - Put the file descriptor into monitor mode. Can only be used in + combination with :ref:`CEC_MODE_NO_INITIATOR `, + otherwise the ``EINVAL`` error code will be returned. + In monitor mode all messages this CEC + device transmits and all messages it receives (both broadcast + messages and directed messages for one its logical addresses) will + be reported. This is very useful for debugging. This is only + allowed if the process has the ``CAP_NET_ADMIN`` capability. If + that is not set, then the ``EPERM`` error code is returned. + * .. _`CEC-MODE-MONITOR-ALL`: + + - ``CEC_MODE_MONITOR_ALL`` + - 0xf0 + - Put the file descriptor into 'monitor all' mode. Can only be used + in combination with :ref:`CEC_MODE_NO_INITIATOR `, otherwise + the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages + this CEC device transmits and all messages it receives, including + directed messages for other CEC devices, will be reported. This is + very useful for debugging, but not all devices support this. This + mode requires that the :ref:`CEC_CAP_MONITOR_ALL ` capability is set, + otherwise the ``EINVAL`` error code is returned. This is only allowed if + the process has the ``CAP_NET_ADMIN`` capability. If that is not + set, then the ``EPERM`` error code is returned. + +Core message processing details: + +.. tabularcolumns:: |p{6.6cm}|p{10.9cm}| + +.. _cec-core-processing: + +.. flat-table:: Core Message Processing + :header-rows: 0 + :stub-columns: 0 + :widths: 1 8 + + * .. _`CEC-MSG-GET-CEC-VERSION`: + + - ``CEC_MSG_GET_CEC_VERSION`` + - The core will return the CEC version that was set with + :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `, + except when in passthrough mode. In passthrough mode the core + does nothing and this message has to be handled by a follower + instead. + * .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`: + + - ``CEC_MSG_GIVE_DEVICE_VENDOR_ID`` + - The core will return the vendor ID that was set with + :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `, + except when in passthrough mode. In passthrough mode the core + does nothing and this message has to be handled by a follower + instead. + * .. _`CEC-MSG-ABORT`: + + - ``CEC_MSG_ABORT`` + - The core will return a Feature Abort message with reason + 'Feature Refused' as per the specification, except when in + passthrough mode. In passthrough mode the core does nothing + and this message has to be handled by a follower instead. + * .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`: + + - ``CEC_MSG_GIVE_PHYSICAL_ADDR`` + - The core will report the current physical address, except when + in passthrough mode. In passthrough mode the core does nothing + and this message has to be handled by a follower instead. + * .. _`CEC-MSG-GIVE-OSD-NAME`: + + - ``CEC_MSG_GIVE_OSD_NAME`` + - The core will report the current OSD name that was set with + :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `, + except when in passthrough mode. In passthrough mode the core + does nothing and this message has to be handled by a follower + instead. + * .. _`CEC-MSG-GIVE-FEATURES`: + + - ``CEC_MSG_GIVE_FEATURES`` + - The core will do nothing if the CEC version is older than 2.0, + otherwise it will report the current features that were set with + :ref:`ioctl CEC_ADAP_S_LOG_ADDRS `, + except when in passthrough mode. In passthrough mode the core + does nothing (for any CEC version) and this message has to be handled + by a follower instead. + * .. _`CEC-MSG-USER-CONTROL-PRESSED`: + + - ``CEC_MSG_USER_CONTROL_PRESSED`` + - If :ref:`CEC_CAP_RC ` is set and if + :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU ` + is set, then generate a remote control key + press. This message is always passed on to the follower(s). + * .. _`CEC-MSG-USER-CONTROL-RELEASED`: + + - ``CEC_MSG_USER_CONTROL_RELEASED`` + - If :ref:`CEC_CAP_RC ` is set and if + :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU ` + is set, then generate a remote control key + release. This message is always passed on to the follower(s). + * .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`: + + - ``CEC_MSG_REPORT_PHYSICAL_ADDR`` + - The CEC framework will make note of the reported physical address + and then just pass the message on to the follower(s). + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +The :ref:`ioctl CEC_S_MODE ` can return the following +error codes: + +EINVAL + The requested mode is invalid. + +EPERM + Monitor mode is requested, but the process does have the ``CAP_NET_ADMIN`` + capability. + +EBUSY + Someone else is already an exclusive follower or initiator. diff --git a/Documentation/userspace-api/media/cec/cec-ioc-receive.rst b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst new file mode 100644 index 000000000..364938ad3 --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-ioc-receive.rst @@ -0,0 +1,385 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: CEC + +.. _CEC_TRANSMIT: +.. _CEC_RECEIVE: + +*********************************** +ioctls CEC_RECEIVE and CEC_TRANSMIT +*********************************** + +Name +==== + +CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message + +Synopsis +======== + +.. c:macro:: CEC_RECEIVE + +``int ioctl(int fd, CEC_RECEIVE, struct cec_msg *argp)`` + +.. c:macro:: CEC_TRANSMIT + +``int ioctl(int fd, CEC_TRANSMIT, struct cec_msg *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct cec_msg. + +Description +=========== + +To receive a CEC message the application has to fill in the +``timeout`` field of struct :c:type:`cec_msg` and pass it to +:ref:`ioctl CEC_RECEIVE `. +If the file descriptor is in non-blocking mode and there are no received +messages pending, then it will return -1 and set errno to the ``EAGAIN`` +error code. If the file descriptor is in blocking mode and ``timeout`` +is non-zero and no message arrived within ``timeout`` milliseconds, then +it will return -1 and set errno to the ``ETIMEDOUT`` error code. + +A received message can be: + +1. a message received from another CEC device (the ``sequence`` field will + be 0, ``tx_status`` will be 0 and ``rx_status`` will be non-zero). +2. the transmit result of an earlier non-blocking transmit (the ``sequence`` + field will be non-zero, ``tx_status`` will be non-zero and ``rx_status`` + will be 0). +3. the reply to an earlier non-blocking transmit (the ``sequence`` field will + be non-zero, ``tx_status`` will be 0 and ``rx_status`` will be non-zero). + +To send a CEC message the application has to fill in the struct +:c:type:`cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT `. +The :ref:`ioctl CEC_TRANSMIT ` is only available if +``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit +queue, then it will return -1 and set errno to the ``EBUSY`` error code. +The transmit queue has enough room for 18 messages (about 1 second worth +of 2-byte messages). Note that the CEC kernel framework will also reply +to core messages (see :ref:`cec-core-processing`), so it is not a good +idea to fully fill up the transmit queue. + +If the file descriptor is in non-blocking mode then the transmit will +return 0 and the result of the transmit will be available via +:ref:`ioctl CEC_RECEIVE ` once the transmit has finished. +If a non-blocking transmit also specified waiting for a reply, then +the reply will arrive in a later message. The ``sequence`` field can +be used to associate both transmit results and replies with the original +transmit. + +Normally calling :ref:`ioctl CEC_TRANSMIT ` when the physical +address is invalid (due to e.g. a disconnect) will return ``ENONET``. + +However, the CEC specification allows sending messages from 'Unregistered' to +'TV' when the physical address is invalid since some TVs pull the hotplug detect +pin of the HDMI connector low when they go into standby, or when switching to +another input. + +When the hotplug detect pin goes low the EDID disappears, and thus the +physical address, but the cable is still connected and CEC still works. +In order to detect/wake up the device it is allowed to send poll and 'Image/Text +View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV'). + +.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{12.8cm}| + +.. c:type:: cec_msg + +.. cssclass:: longtable + +.. flat-table:: struct cec_msg + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 16 + + * - __u64 + - ``tx_ts`` + - Timestamp in ns of when the last byte of the message was transmitted. + The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access + the same clock from userspace use :c:func:`clock_gettime`. + * - __u64 + - ``rx_ts`` + - Timestamp in ns of when the last byte of the message was received. + The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access + the same clock from userspace use :c:func:`clock_gettime`. + * - __u32 + - ``len`` + - The length of the message. For :ref:`ioctl CEC_TRANSMIT ` this is filled in + by the application. The driver will fill this in for + :ref:`ioctl CEC_RECEIVE `. For :ref:`ioctl CEC_TRANSMIT ` it will be + filled in by the driver with the length of the reply message if ``reply`` was set. + * - __u32 + - ``timeout`` + - The timeout in milliseconds. This is the time the device will wait + for a message to be received before timing out. If it is set to 0, + then it will wait indefinitely when it is called by :ref:`ioctl CEC_RECEIVE `. + If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT `, + then it will be replaced by 1000 if the ``reply`` is non-zero or + ignored if ``reply`` is 0. + * - __u32 + - ``sequence`` + - A non-zero sequence number is automatically assigned by the CEC framework + for all transmitted messages. It is used by the CEC framework when it queues + the transmit result for a non-blocking transmit. This allows the application + to associate the received message with the original transmit. + + In addition, if a non-blocking transmit will wait for a reply (ii.e. ``timeout`` + was not 0), then the ``sequence`` field of the reply will be set to the sequence + value of the original transmit. This allows the application to associate the + received message with the original transmit. + * - __u32 + - ``flags`` + - Flags. See :ref:`cec-msg-flags` for a list of available flags. + * - __u8 + - ``msg[16]`` + - The message payload. For :ref:`ioctl CEC_TRANSMIT ` this is filled in by the + application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE `. + For :ref:`ioctl CEC_TRANSMIT ` it will be filled in by the driver with + the payload of the reply message if ``timeout`` was set. + * - __u8 + - ``reply`` + - Wait until this message is replied. If ``reply`` is 0 and the + ``timeout`` is 0, then don't wait for a reply but return after + transmitting the message. Ignored by :ref:`ioctl CEC_RECEIVE `. + The case where ``reply`` is 0 (this is the opcode for the Feature Abort + message) and ``timeout`` is non-zero is specifically allowed to make it + possible to send a message and wait up to ``timeout`` milliseconds for a + Feature Abort reply. In this case ``rx_status`` will either be set + to :ref:`CEC_RX_STATUS_TIMEOUT ` or + :ref:`CEC_RX_STATUS_FEATURE_ABORT `. + + If the transmitter message is ``CEC_MSG_INITIATE_ARC`` then the ``reply`` + values ``CEC_MSG_REPORT_ARC_INITIATED`` and ``CEC_MSG_REPORT_ARC_TERMINATED`` + are processed differently: either value will match both possible replies. + The reason is that the ``CEC_MSG_INITIATE_ARC`` message is the only CEC + message that has two possible replies other than Feature Abort. The + ``reply`` field will be updated with the actual reply so that it is + synchronized with the contents of the received message. + * - __u8 + - ``rx_status`` + - The status bits of the received message. See + :ref:`cec-rx-status` for the possible status values. + * - __u8 + - ``tx_status`` + - The status bits of the transmitted message. See + :ref:`cec-tx-status` for the possible status values. + When calling :ref:`ioctl CEC_TRANSMIT ` in non-blocking mode, + this field will be 0 if the transmit started, or non-0 if the transmit + result is known immediately. The latter would be the case when attempting + to transmit a Poll message to yourself. That results in a + :ref:`CEC_TX_STATUS_NACK ` without ever actually + transmitting the Poll message. + * - __u8 + - ``tx_arb_lost_cnt`` + - A counter of the number of transmit attempts that resulted in the + Arbitration Lost error. This is only set if the hardware supports + this, otherwise it is always 0. This counter is only valid if the + :ref:`CEC_TX_STATUS_ARB_LOST ` status bit is set. + * - __u8 + - ``tx_nack_cnt`` + - A counter of the number of transmit attempts that resulted in the + Not Acknowledged error. This is only set if the hardware supports + this, otherwise it is always 0. This counter is only valid if the + :ref:`CEC_TX_STATUS_NACK ` status bit is set. + * - __u8 + - ``tx_low_drive_cnt`` + - A counter of the number of transmit attempts that resulted in the + Arbitration Lost error. This is only set if the hardware supports + this, otherwise it is always 0. This counter is only valid if the + :ref:`CEC_TX_STATUS_LOW_DRIVE ` status bit is set. + * - __u8 + - ``tx_error_cnt`` + - A counter of the number of transmit errors other than Arbitration + Lost or Not Acknowledged. This is only set if the hardware + supports this, otherwise it is always 0. This counter is only + valid if the :ref:`CEC_TX_STATUS_ERROR ` status bit is set. + +.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.1cm}| + +.. _cec-msg-flags: + +.. flat-table:: Flags for struct cec_msg + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`: + + - ``CEC_MSG_FL_REPLY_TO_FOLLOWERS`` + - 1 + - If a CEC transmit expects a reply, then by default that reply is only sent to + the filehandle that called :ref:`ioctl CEC_TRANSMIT `. If this + flag is set, then the reply is also sent to all followers, if any. If the + filehandle that called :ref:`ioctl CEC_TRANSMIT ` is also a + follower, then that filehandle will receive the reply twice: once as the + result of the :ref:`ioctl CEC_TRANSMIT `, and once via + :ref:`ioctl CEC_RECEIVE `. + + * .. _`CEC-MSG-FL-RAW`: + + - ``CEC_MSG_FL_RAW`` + - 2 + - Normally CEC messages are validated before transmitting them. If this + flag is set when :ref:`ioctl CEC_TRANSMIT ` is called, + then no validation takes place and the message is transmitted as-is. + This is useful when debugging CEC issues. + This flag is only allowed if the process has the ``CAP_SYS_RAWIO`` + capability. If that is not set, then the ``EPERM`` error code is + returned. + +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| + +.. _cec-tx-status: + +.. flat-table:: CEC Transmit Status + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 16 + + * .. _`CEC-TX-STATUS-OK`: + + - ``CEC_TX_STATUS_OK`` + - 0x01 + - The message was transmitted successfully. This is mutually + exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES `. + Other bits can still be set if earlier attempts met with failure before + the transmit was eventually successful. + * .. _`CEC-TX-STATUS-ARB-LOST`: + + - ``CEC_TX_STATUS_ARB_LOST`` + - 0x02 + - CEC line arbitration was lost, i.e. another transmit started at the + same time with a higher priority. Optional status, not all hardware + can detect this error condition. + * .. _`CEC-TX-STATUS-NACK`: + + - ``CEC_TX_STATUS_NACK`` + - 0x04 + - Message was not acknowledged. Note that some hardware cannot tell apart + a 'Not Acknowledged' status from other error conditions, i.e. the result + of a transmit is just OK or FAIL. In that case this status will be + returned when the transmit failed. + * .. _`CEC-TX-STATUS-LOW-DRIVE`: + + - ``CEC_TX_STATUS_LOW_DRIVE`` + - 0x08 + - Low drive was detected on the CEC bus. This indicates that a + follower detected an error on the bus and requests a + retransmission. Optional status, not all hardware can detect this + error condition. + * .. _`CEC-TX-STATUS-ERROR`: + + - ``CEC_TX_STATUS_ERROR`` + - 0x10 + - Some error occurred. This is used for any errors that do not fit + ``CEC_TX_STATUS_ARB_LOST`` or ``CEC_TX_STATUS_LOW_DRIVE``, either because + the hardware could not tell which error occurred, or because the hardware + tested for other conditions besides those two. Optional status. + * .. _`CEC-TX-STATUS-MAX-RETRIES`: + + - ``CEC_TX_STATUS_MAX_RETRIES`` + - 0x20 + - The transmit failed after one or more retries. This status bit is + mutually exclusive with :ref:`CEC_TX_STATUS_OK `. + Other bits can still be set to explain which failures were seen. + * .. _`CEC-TX-STATUS-ABORTED`: + + - ``CEC_TX_STATUS_ABORTED`` + - 0x40 + - The transmit was aborted due to an HDMI disconnect, or the adapter + was unconfigured, or a transmit was interrupted, or the driver + returned an error when attempting to start a transmit. + * .. _`CEC-TX-STATUS-TIMEOUT`: + + - ``CEC_TX_STATUS_TIMEOUT`` + - 0x80 + - The transmit timed out. This should not normally happen and this + indicates a driver problem. + +.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| + +.. _cec-rx-status: + +.. flat-table:: CEC Receive Status + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 16 + + * .. _`CEC-RX-STATUS-OK`: + + - ``CEC_RX_STATUS_OK`` + - 0x01 + - The message was received successfully. + * .. _`CEC-RX-STATUS-TIMEOUT`: + + - ``CEC_RX_STATUS_TIMEOUT`` + - 0x02 + - The reply to an earlier transmitted message timed out. + * .. _`CEC-RX-STATUS-FEATURE-ABORT`: + + - ``CEC_RX_STATUS_FEATURE_ABORT`` + - 0x04 + - The message was received successfully but the reply was + ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message + was the reply to an earlier transmitted message. + * .. _`CEC-RX-STATUS-ABORTED`: + + - ``CEC_RX_STATUS_ABORTED`` + - 0x08 + - The wait for a reply to an earlier transmitted message was aborted + because the HDMI cable was disconnected, the adapter was unconfigured + or the :ref:`CEC_TRANSMIT ` that waited for a + reply was interrupted. + + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +The :ref:`ioctl CEC_RECEIVE ` can return the following +error codes: + +EAGAIN + No messages are in the receive queue, and the filehandle is in non-blocking mode. + +ETIMEDOUT + The ``timeout`` was reached while waiting for a message. + +ERESTARTSYS + The wait for a message was interrupted (e.g. by Ctrl-C). + +The :ref:`ioctl CEC_TRANSMIT ` can return the following +error codes: + +ENOTTY + The ``CEC_CAP_TRANSMIT`` capability wasn't set, so this ioctl is not supported. + +EPERM + The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` + has never been called, or ``CEC_MSG_FL_RAW`` was used from a process that + did not have the ``CAP_SYS_RAWIO`` capability. + +ENONET + The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS ` + was called, but the physical address is invalid so no logical address was claimed. + An exception is made in this case for transmits from initiator 0xf ('Unregistered') + to destination 0 ('TV'). In that case the transmit will proceed as usual. + +EBUSY + Another filehandle is in exclusive follower or initiator mode, or the filehandle + is in mode ``CEC_MODE_NO_INITIATOR``. This is also returned if the transmit + queue is full. + +EINVAL + The contents of struct :c:type:`cec_msg` is invalid. + +ERESTARTSYS + The wait for a successful transmit was interrupted (e.g. by Ctrl-C). diff --git a/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst new file mode 100644 index 000000000..b0efce404 --- /dev/null +++ b/Documentation/userspace-api/media/cec/cec-pin-error-inj.rst @@ -0,0 +1,327 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +CEC Pin Framework Error Injection +================================= + +The CEC Pin Framework is a core CEC framework for CEC hardware that only +has low-level support for the CEC bus. Most hardware today will have +high-level CEC support where the hardware deals with driving the CEC bus, +but some older devices aren't that fancy. However, this framework also +allows you to connect the CEC pin to a GPIO on e.g. a Raspberry Pi and +you have now made a CEC adapter. + +What makes doing this so interesting is that since we have full control +over the bus it is easy to support error injection. This is ideal to +test how well CEC adapters can handle error conditions. + +Currently only the cec-gpio driver (when the CEC line is directly +connected to a pull-up GPIO line) and the AllWinner A10/A20 drm driver +support this framework. + +If ``CONFIG_CEC_PIN_ERROR_INJ`` is enabled, then error injection is available +through debugfs. Specifically, in ``/sys/kernel/debug/cec/cecX/`` there is +now an ``error-inj`` file. + +.. note:: + + The error injection commands are not a stable ABI and may change in the + future. + +With ``cat error-inj`` you can see both the possible commands and the current +error injection status:: + + $ cat /sys/kernel/debug/cec/cec0/error-inj + # Clear error injections: + # clear clear all rx and tx error injections + # rx-clear clear all rx error injections + # tx-clear clear all tx error injections + # clear clear all rx and tx error injections for + # rx-clear clear all rx error injections for + # tx-clear clear all tx error injections for + # + # RX error injection: + # [,] rx-nack NACK the message instead of sending an ACK + # [,] rx-low-drive force a low-drive condition at this bit position + # [,] rx-add-byte add a spurious byte to the received CEC message + # [,] rx-remove-byte remove the last byte from the received CEC message + # any[,] rx-arb-lost [] generate a POLL message to trigger an arbitration lost + # + # TX error injection settings: + # tx-ignore-nack-until-eom ignore early NACKs until EOM + # tx-custom-low-usecs define the 'low' time for the custom pulse + # tx-custom-high-usecs define the 'high' time for the custom pulse + # tx-custom-pulse transmit the custom pulse once the bus is idle + # + # TX error injection: + # [,] tx-no-eom don't set the EOM bit + # [,] tx-early-eom set the EOM bit one byte too soon + # [,] tx-add-bytes append (1-255) spurious bytes to the message + # [,] tx-remove-byte drop the last byte from the message + # [,] tx-short-bit make this bit shorter than allowed + # [,] tx-long-bit make this bit longer than allowed + # [,] tx-custom-bit send the custom pulse instead of this bit + # [,] tx-short-start send a start pulse that's too short + # [,] tx-long-start send a start pulse that's too long + # [,] tx-custom-start send the custom pulse instead of the start pulse + # [,] tx-last-bit stop sending after this bit + # [,] tx-low-drive force a low-drive condition at this bit position + # + # CEC message opcode (0-255) or 'any' + # 'once' (default), 'always', 'toggle' or 'off' + # CEC message bit (0-159) + # 10 bits per 'byte': bits 0-7: data, bit 8: EOM, bit 9: ACK + # CEC poll message used to test arbitration lost (0x00-0xff, default 0x0f) + # microseconds (0-10000000, default 1000) + + clear + +You can write error injection commands to ``error-inj`` using +``echo 'cmd' >error-inj`` or ``cat cmd.txt >error-inj``. The ``cat error-inj`` +output contains the current error commands. You can save the output to a file +and use it as an input to ``error-inj`` later. + +Basic Syntax +------------ + +Leading spaces/tabs are ignored. If the next character is a ``#`` or the end +of the line was reached, then the whole line is ignored. Otherwise a command +is expected. + +The error injection commands fall in two main groups: those relating to +receiving CEC messages and those relating to transmitting CEC messages. In +addition, there are commands to clear existing error injection commands and +to create custom pulses on the CEC bus. + +Most error injection commands can be executed for specific CEC opcodes or for +all opcodes (``any``). Each command also has a 'mode' which can be ``off`` +(can be used to turn off an existing error injection command), ``once`` +(the default) which will trigger the error injection only once for the next +received or transmitted message, ``always`` to always trigger the error +injection and ``toggle`` to toggle the error injection on or off for every +transmit or receive. + +So '``any rx-nack``' will NACK the next received CEC message, +'``any,always rx-nack``' will NACK all received CEC messages and +'``0x82,toggle rx-nack``' will only NACK if an Active Source message was +received and do that only for every other received message. + +After an error was injected with mode ``once`` the error injection command +is cleared automatically, so ``once`` is a one-time deal. + +All combinations of ```` and error injection commands can co-exist. So +this is fine:: + + 0x9e tx-add-bytes 1 + 0x9e tx-early-eom + 0x9f tx-add-bytes 2 + any rx-nack + +All four error injection commands will be active simultaneously. + +However, if the same ```` and command combination is specified, +but with different arguments:: + + 0x9e tx-add-bytes 1 + 0x9e tx-add-bytes 2 + +Then the second will overwrite the first. + +Clear Error Injections +---------------------- + +``clear`` + Clear all error injections. + +``rx-clear`` + Clear all receive error injections + +``tx-clear`` + Clear all transmit error injections + +`` clear`` + Clear all error injections for the given opcode. + +`` rx-clear`` + Clear all receive error injections for the given opcode. + +`` tx-clear`` + Clear all transmit error injections for the given opcode. + +Receive Messages +---------------- + +``[,] rx-nack`` + NACK broadcast messages and messages directed to this CEC adapter. + Every byte of the message will be NACKed in case the transmitter + keeps transmitting after the first byte was NACKed. + +``[,] rx-low-drive `` + Force a Low Drive condition at this bit position. If specifies + a specific CEC opcode then the bit position must be at least 18, + otherwise the opcode hasn't been received yet. This tests if the + transmitter can handle the Low Drive condition correctly and reports + the error correctly. Note that a Low Drive in the first 4 bits can also + be interpreted as an Arbitration Lost condition by the transmitter. + This is implementation dependent. + +``[,] rx-add-byte`` + Add a spurious 0x55 byte to the received CEC message, provided + the message was 15 bytes long or less. This is useful to test + the high-level protocol since spurious bytes should be ignored. + +``[,] rx-remove-byte`` + Remove the last byte from the received CEC message, provided it + was at least 2 bytes long. This is useful to test the high-level + protocol since messages that are too short should be ignored. + +``[,] rx-arb-lost `` + Generate a POLL message to trigger an Arbitration Lost condition. + This command is only allowed for ```` values of ``next`` or ``all``. + As soon as a start bit has been received the CEC adapter will switch + to transmit mode and it will transmit a POLL message. By default this is + 0x0f, but it can also be specified explicitly via the ```` argument. + + This command can be used to test the Arbitration Lost condition in + the remote CEC transmitter. Arbitration happens when two CEC adapters + start sending a message at the same time. In that case the initiator + with the most leading zeroes wins and the other transmitter has to + stop transmitting ('Arbitration Lost'). This is very hard to test, + except by using this error injection command. + + This does not work if the remote CEC transmitter has logical address + 0 ('TV') since that will always win. + +Transmit Messages +----------------- + +``tx-ignore-nack-until-eom`` + This setting changes the behavior of transmitting CEC messages. Normally + as soon as the receiver NACKs a byte the transmit will stop, but the + specification also allows that the full message is transmitted and only + at the end will the transmitter look at the ACK bit. This is not + recommended behavior since there is no point in keeping the CEC bus busy + for longer than is strictly needed. Especially given how slow the bus is. + + This setting can be used to test how well a receiver deals with + transmitters that ignore NACKs until the very end of the message. + +``[,] tx-no-eom`` + Don't set the EOM bit. Normally the last byte of the message has the EOM + (End-Of-Message) bit set. With this command the transmit will just stop + without ever sending an EOM. This can be used to test how a receiver + handles this case. Normally receivers have a time-out after which + they will go back to the Idle state. + +``[,] tx-early-eom`` + Set the EOM bit one byte too soon. This obviously only works for messages + of two bytes or more. The EOM bit will be set for the second-to-last byte + and not for the final byte. The receiver should ignore the last byte in + this case. Since the resulting message is likely to be too short for this + same reason the whole message is typically ignored. The receiver should be + in Idle state after the last byte was transmitted. + +``[,] tx-add-bytes `` + Append ```` (1-255) spurious bytes to the message. The extra bytes + have the value of the byte position in the message. So if you transmit a + two byte message (e.g. a Get CEC Version message) and add 2 bytes, then + the full message received by the remote CEC adapter is + ``0x40 0x9f 0x02 0x03``. + + This command can be used to test buffer overflows in the receiver. E.g. + what does it do when it receives more than the maximum message size of 16 + bytes. + +``[,] tx-remove-byte`` + Drop the last byte from the message, provided the message is at least + two bytes long. The receiver should ignore messages that are too short. + +``[,] tx-short-bit `` + Make this bit period shorter than allowed. The bit position cannot be + an Ack bit. If specifies a specific CEC opcode then the bit position + must be at least 18, otherwise the opcode hasn't been received yet. + Normally the period of a data bit is between 2.05 and 2.75 milliseconds. + With this command the period of this bit is 1.8 milliseconds, this is + done by reducing the time the CEC bus is high. This bit period is less + than is allowed and the receiver should respond with a Low Drive + condition. + + This command is ignored for 0 bits in bit positions 0 to 3. This is + because the receiver also looks for an Arbitration Lost condition in + those first four bits and it is undefined what will happen if it + sees a too-short 0 bit. + +``[,] tx-long-bit `` + Make this bit period longer than is valid. The bit position cannot be + an Ack bit. If specifies a specific CEC opcode then the bit position + must be at least 18, otherwise the opcode hasn't been received yet. + Normally the period of a data bit is between 2.05 and 2.75 milliseconds. + With this command the period of this bit is 2.9 milliseconds, this is + done by increasing the time the CEC bus is high. + + Even though this bit period is longer than is valid it is undefined what + a receiver will do. It might just accept it, or it might time out and + return to Idle state. Unfortunately the CEC specification is silent about + this. + + This command is ignored for 0 bits in bit positions 0 to 3. This is + because the receiver also looks for an Arbitration Lost condition in + those first four bits and it is undefined what will happen if it + sees a too-long 0 bit. + +``[,] tx-short-start`` + Make this start bit period shorter than allowed. Normally the period of + a start bit is between 4.3 and 4.7 milliseconds. With this command the + period of the start bit is 4.1 milliseconds, this is done by reducing + the time the CEC bus is high. This start bit period is less than is + allowed and the receiver should return to Idle state when this is detected. + +``[,] tx-long-start`` + Make this start bit period longer than is valid. Normally the period of + a start bit is between 4.3 and 4.7 milliseconds. With this command the + period of the start bit is 5 milliseconds, this is done by increasing + the time the CEC bus is high. This start bit period is more than is + valid and the receiver should return to Idle state when this is detected. + + Even though this start bit period is longer than is valid it is undefined + what a receiver will do. It might just accept it, or it might time out and + return to Idle state. Unfortunately the CEC specification is silent about + this. + +``[,] tx-last-bit `` + Just stop transmitting after this bit. If specifies a specific CEC + opcode then the bit position must be at least 18, otherwise the opcode + hasn't been received yet. This command can be used to test how the receiver + reacts when a message just suddenly stops. It should time out and go back + to Idle state. + +``[,] tx-low-drive `` + Force a Low Drive condition at this bit position. If specifies a + specific CEC opcode then the bit position must be at least 18, otherwise + the opcode hasn't been received yet. This can be used to test how the + receiver handles Low Drive conditions. Note that if this happens at bit + positions 0-3 the receiver can interpret this as an Arbitration Lost + condition. This is implementation dependent. + +Custom Pulses +------------- + +``tx-custom-low-usecs `` + This defines the duration in microseconds that the custom pulse pulls + the CEC line low. The default is 1000 microseconds. + +``tx-custom-high-usecs `` + This defines the duration in microseconds that the custom pulse keeps the + CEC line high (unless another CEC adapter pulls it low in that time). + The default is 1000 microseconds. The total period of the custom pulse is + ``tx-custom-low-usecs + tx-custom-high-usecs``. + +``[,] tx-custom-bit `` + Send the custom bit instead of a regular data bit. The bit position cannot + be an Ack bit. If specifies a specific CEC opcode then the bit + position must be at least 18, otherwise the opcode hasn't been received yet. + +``[,] tx-custom-start`` + Send the custom bit instead of a regular start bit. + +``tx-custom-pulse`` + Transmit a single custom pulse as soon as the CEC bus is idle. diff --git a/Documentation/userspace-api/media/conf_nitpick.py b/Documentation/userspace-api/media/conf_nitpick.py new file mode 100644 index 000000000..0a8e236d0 --- /dev/null +++ b/Documentation/userspace-api/media/conf_nitpick.py @@ -0,0 +1,111 @@ +# -*- coding: utf-8; mode: python -*- + +# SPDX-License-Identifier: GPL-2.0 + +project = 'Linux Media Subsystem Documentation' + +# It is possible to run Sphinx in nickpick mode with: +nitpicky = True + +# within nit-picking build, do not refer to any intersphinx object +intersphinx_mapping = {} + +# In nickpick mode, it will complain about lots of missing references that +# +# 1) are just typedefs like: bool, __u32, etc; +# 2) It will complain for things like: enum, NULL; +# 3) It will complain for symbols that should be on different +# books (but currently aren't ported to ReST) +# +# The list below has a list of such symbols to be ignored in nitpick mode +# +nitpick_ignore = [ + ("c:func", "clock_gettime"), + ("c:func", "close"), + ("c:func", "container_of"), + ("c:func", "copy_from_user"), + ("c:func", "copy_to_user"), + ("c:func", "determine_valid_ioctls"), + ("c:func", "ERR_PTR"), + ("c:func", "i2c_new_client_device"), + ("c:func", "ioctl"), + ("c:func", "IS_ERR"), + ("c:func", "KERNEL_VERSION"), + ("c:func", "mmap"), + ("c:func", "open"), + ("c:func", "pci_name"), + ("c:func", "poll"), + ("c:func", "PTR_ERR"), + ("c:func", "read"), + ("c:func", "release"), + ("c:func", "set"), + ("c:func", "struct fd_set"), + ("c:func", "struct pollfd"), + ("c:func", "usb_make_path"), + ("c:func", "wait_finish"), + ("c:func", "wait_prepare"), + ("c:func", "write"), + + ("c:type", "atomic_t"), + ("c:type", "bool"), + ("c:type", "boolean"), + ("c:type", "buf_queue"), + ("c:type", "device"), + ("c:type", "device_driver"), + ("c:type", "device_node"), + ("c:type", "enum"), + ("c:type", "fd"), + ("c:type", "fd_set"), + ("c:type", "file"), + ("c:type", "i2c_adapter"), + ("c:type", "i2c_board_info"), + ("c:type", "i2c_client"), + ("c:type", "int16_t"), + ("c:type", "ktime_t"), + ("c:type", "led_classdev_flash"), + ("c:type", "list_head"), + ("c:type", "lock_class_key"), + ("c:type", "module"), + ("c:type", "mutex"), + ("c:type", "NULL"), + ("c:type", "off_t"), + ("c:type", "pci_dev"), + ("c:type", "pdvbdev"), + ("c:type", "poll_table"), + ("c:type", "platform_device"), + ("c:type", "pollfd"), + ("c:type", "poll_table_struct"), + ("c:type", "s32"), + ("c:type", "s64"), + ("c:type", "sd"), + ("c:type", "size_t"), + ("c:type", "spi_board_info"), + ("c:type", "spi_device"), + ("c:type", "spi_master"), + ("c:type", "ssize_t"), + ("c:type", "fb_fix_screeninfo"), + ("c:type", "pollfd"), + ("c:type", "timeval"), + ("c:type", "video_capability"), + ("c:type", "timeval"), + ("c:type", "__u16"), + ("c:type", "u16"), + ("c:type", "__u32"), + ("c:type", "u32"), + ("c:type", "__u64"), + ("c:type", "u64"), + ("c:type", "u8"), + ("c:type", "uint16_t"), + ("c:type", "uint32_t"), + ("c:type", "union"), + ("c:type", "__user"), + ("c:type", "usb_device"), + ("c:type", "usb_interface"), + ("c:type", "v4l2_std_id"), + ("c:type", "video_system_t"), + ("c:type", "vm_area_struct"), + + # Opaque structures + + ("c:type", "v4l2_m2m_dev"), +] diff --git a/Documentation/userspace-api/media/dmx.h.rst.exceptions b/Documentation/userspace-api/media/dmx.h.rst.exceptions new file mode 100644 index 000000000..afc14d384 --- /dev/null +++ b/Documentation/userspace-api/media/dmx.h.rst.exceptions @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Ignore header name +ignore define _UAPI_DVBDMX_H_ + +# Ignore limit constants +ignore define DMX_FILTER_SIZE + +# dmx_pes_type_t enum symbols +replace enum dmx_ts_pes :c:type:`dmx_pes_type` +replace symbol DMX_PES_AUDIO0 :c:type:`dmx_pes_type` +replace symbol DMX_PES_VIDEO0 :c:type:`dmx_pes_type` +replace symbol DMX_PES_TELETEXT0 :c:type:`dmx_pes_type` +replace symbol DMX_PES_SUBTITLE0 :c:type:`dmx_pes_type` +replace symbol DMX_PES_PCR0 :c:type:`dmx_pes_type` +replace symbol DMX_PES_AUDIO1 :c:type:`dmx_pes_type` +replace symbol DMX_PES_VIDEO1 :c:type:`dmx_pes_type` +replace symbol DMX_PES_TELETEXT1 :c:type:`dmx_pes_type` +replace symbol DMX_PES_SUBTITLE1 :c:type:`dmx_pes_type` +replace symbol DMX_PES_PCR1 :c:type:`dmx_pes_type` +replace symbol DMX_PES_AUDIO2 :c:type:`dmx_pes_type` +replace symbol DMX_PES_VIDEO2 :c:type:`dmx_pes_type` +replace symbol DMX_PES_TELETEXT2 :c:type:`dmx_pes_type` +replace symbol DMX_PES_SUBTITLE2 :c:type:`dmx_pes_type` +replace symbol DMX_PES_PCR2 :c:type:`dmx_pes_type` +replace symbol DMX_PES_AUDIO3 :c:type:`dmx_pes_type` +replace symbol DMX_PES_VIDEO3 :c:type:`dmx_pes_type` +replace symbol DMX_PES_TELETEXT3 :c:type:`dmx_pes_type` +replace symbol DMX_PES_SUBTITLE3 :c:type:`dmx_pes_type` +replace symbol DMX_PES_PCR3 :c:type:`dmx_pes_type` +replace symbol DMX_PES_OTHER :c:type:`dmx_pes_type` + +# Ignore obsolete symbols +ignore define DMX_PES_AUDIO +ignore define DMX_PES_VIDEO +ignore define DMX_PES_TELETEXT +ignore define DMX_PES_SUBTITLE +ignore define DMX_PES_PCR + +# dmx_input_t symbols +replace enum dmx_input :c:type:`dmx_input` +replace symbol DMX_IN_FRONTEND :c:type:`dmx_input` +replace symbol DMX_IN_DVR :c:type:`dmx_input` + +# Flags for struct dmx_sct_filter_params +replace define DMX_CHECK_CRC :c:type:`dmx_sct_filter_params` +replace define DMX_ONESHOT :c:type:`dmx_sct_filter_params` +replace define DMX_IMMEDIATE_START :c:type:`dmx_sct_filter_params` + +# some typedefs should point to struct/enums +replace typedef dmx_filter_t :c:type:`dmx_filter` +replace typedef dmx_pes_type_t :c:type:`dmx_pes_type` +replace typedef dmx_input_t :c:type:`dmx_input` + +replace symbol DMX_BUFFER_FLAG_HAD_CRC32_DISCARD :c:type:`dmx_buffer_flags` +replace symbol DMX_BUFFER_FLAG_TEI :c:type:`dmx_buffer_flags` +replace symbol DMX_BUFFER_PKT_COUNTER_MISMATCH :c:type:`dmx_buffer_flags` +replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_DETECTED :c:type:`dmx_buffer_flags` +replace symbol DMX_BUFFER_FLAG_DISCONTINUITY_INDICATOR :c:type:`dmx_buffer_flags` + +replace symbol DMX_OUT_DECODER :c:type:`dmx_output` +replace symbol DMX_OUT_TAP :c:type:`dmx_output` +replace symbol DMX_OUT_TS_TAP :c:type:`dmx_output` +replace symbol DMX_OUT_TSDEMUX_TAP :c:type:`dmx_output` + +replace ioctl DMX_DQBUF dmx_qbuf diff --git a/Documentation/userspace-api/media/drivers/ccs.rst b/Documentation/userspace-api/media/drivers/ccs.rst new file mode 100644 index 000000000..161cb65f4 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/ccs.rst @@ -0,0 +1,110 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +.. include:: + +MIPI CCS camera sensor driver +============================= + +The MIPI CCS camera sensor driver is a generic driver for `MIPI CCS +`_ compliant +camera sensors. It exposes three sub-devices representing the pixel array, +the binner and the scaler. + +As the capabilities of individual devices vary, the driver exposes +interfaces based on the capabilities that exist in hardware. + +Pixel Array sub-device +---------------------- + +The pixel array sub-device represents the camera sensor's pixel matrix, as well +as analogue crop functionality present in many compliant devices. The analogue +crop is configured using the ``V4L2_SEL_TGT_CROP`` on the source pad (0) of the +entity. The size of the pixel matrix can be obtained by getting the +``V4L2_SEL_TGT_NATIVE_SIZE`` target. + +Binner +------ + +The binner sub-device represents the binning functionality on the sensor. For +that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the +sink pad (0). + +Additionally, if a device has no scaler or digital crop functionality, the +source pad (1) expses another digital crop selection rectangle that can only +crop at the end of the lines and frames. + +Scaler +------ + +The scaler sub-device represents the digital crop and scaling functionality of +the sensor. The V4L2 selection target ``V4L2_SEL_TGT_CROP`` is used to +configure the digital crop on the sink pad (0) when digital crop is supported. +Scaling is configured using selection target ``V4L2_SEL_TGT_COMPOSE`` on the +sink pad (0) as well. + +Additionally, if the scaler sub-device exists, its source pad (1) exposes +another digital crop selection rectangle that can only crop at the end of the +lines and frames. + +Digital and analogue crop +------------------------- + +Digital crop functionality is referred to as cropping that effectively works by +dropping some data on the floor. Analogue crop, on the other hand, means that +the cropped information is never retrieved. In case of camera sensors, the +analogue data is never read from the pixel matrix that are outside the +configured selection rectangle that designates crop. The difference has an +effect in device timing and likely also in power consumption. + +Private controls +---------------- + +The MIPI CCS driver implements a number of private controls under +``V4L2_CID_USER_BASE_CCS`` to control the MIPI CCS compliant camera sensors. + +Analogue gain model +~~~~~~~~~~~~~~~~~~~ + +The CCS defines an analogue gain model where the gain can be calculated using +the following formula: + + gain = m0 * x + c0 / (m1 * x + c1) + +Either m0 or c0 will be zero. The constants that are device specific, can be +obtained from the following controls: + + V4L2_CID_CCS_ANALOGUE_GAIN_M0 + V4L2_CID_CCS_ANALOGUE_GAIN_M1 + V4L2_CID_CCS_ANALOGUE_GAIN_C0 + V4L2_CID_CCS_ANALOGUE_GAIN_C1 + +The analogue gain (``x`` in the formula) is controlled through +``V4L2_CID_ANALOGUE_GAIN`` in this case. + +Alternate analogue gain model +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The CCS defines another analogue gain model called alternate analogue gain. In +this case, the formula to calculate actual gain consists of linear and +exponential parts: + + gain = linear * 2 ^ exponent + +The ``linear`` and ``exponent`` factors can be set using the +``V4L2_CID_CCS_ANALOGUE_LINEAR_GAIN`` and +``V4L2_CID_CCS_ANALOGUE_EXPONENTIAL_GAIN`` controls, respectively + +Shading correction +~~~~~~~~~~~~~~~~~~ + +The CCS standard supports lens shading correction. The feature can be controlled +using ``V4L2_CID_CCS_SHADING_CORRECTION``. Additionally, the luminance +correction level may be changed using +``V4L2_CID_CCS_LUMINANCE_CORRECTION_LEVEL``, where value 0 indicates no +correction and 128 indicates correcting the luminance in corners to 10 % less +than in the centre. + +Shading correction needs to be enabled for luminance correction level to have an +effect. + +**Copyright** |copy| 2020 Intel Corporation diff --git a/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst b/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst new file mode 100644 index 000000000..debde65fb --- /dev/null +++ b/Documentation/userspace-api/media/drivers/cx2341x-uapi.rst @@ -0,0 +1,177 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The cx2341x driver +================== + +Non-compressed file format +-------------------------- + +The cx23416 can produce (and the cx23415 can also read) raw YUV output. The +format of a YUV frame is 16x16 linear tiled NV12 (V4L2_PIX_FMT_NV12_16L16). + +The format is YUV 4:2:0 which uses 1 Y byte per pixel and 1 U and V byte per +four pixels. + +The data is encoded as two macroblock planes, the first containing the Y +values, the second containing UV macroblocks. + +The Y plane is divided into blocks of 16x16 pixels from left to right +and from top to bottom. Each block is transmitted in turn, line-by-line. + +So the first 16 bytes are the first line of the top-left block, the +second 16 bytes are the second line of the top-left block, etc. After +transmitting this block the first line of the block on the right to the +first block is transmitted, etc. + +The UV plane is divided into blocks of 16x8 UV values going from left +to right, top to bottom. Each block is transmitted in turn, line-by-line. + +So the first 16 bytes are the first line of the top-left block and +contain 8 UV value pairs (16 bytes in total). The second 16 bytes are the +second line of 8 UV pairs of the top-left block, etc. After transmitting +this block the first line of the block on the right to the first block is +transmitted, etc. + +The code below is given as an example on how to convert V4L2_PIX_FMT_NV12_16L16 +to separate Y, U and V planes. This code assumes frames of 720x576 (PAL) pixels. + +The width of a frame is always 720 pixels, regardless of the actual specified +width. + +If the height is not a multiple of 32 lines, then the captured video is +missing macroblocks at the end and is unusable. So the height must be a +multiple of 32. + +Raw format c example +~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: c + + #include + #include + #include + + static unsigned char frame[576*720*3/2]; + static unsigned char framey[576*720]; + static unsigned char frameu[576*720 / 4]; + static unsigned char framev[576*720 / 4]; + + static void de_macro_y(unsigned char* dst, unsigned char *src, int dstride, int w, int h) + { + unsigned int y, x, i; + + // descramble Y plane + // dstride = 720 = w + // The Y plane is divided into blocks of 16x16 pixels + // Each block in transmitted in turn, line-by-line. + for (y = 0; y < h; y += 16) { + for (x = 0; x < w; x += 16) { + for (i = 0; i < 16; i++) { + memcpy(dst + x + (y + i) * dstride, src, 16); + src += 16; + } + } + } + } + + static void de_macro_uv(unsigned char *dstu, unsigned char *dstv, unsigned char *src, int dstride, int w, int h) + { + unsigned int y, x, i; + + // descramble U/V plane + // dstride = 720 / 2 = w + // The U/V values are interlaced (UVUV...). + // Again, the UV plane is divided into blocks of 16x16 UV values. + // Each block in transmitted in turn, line-by-line. + for (y = 0; y < h; y += 16) { + for (x = 0; x < w; x += 8) { + for (i = 0; i < 16; i++) { + int idx = x + (y + i) * dstride; + + dstu[idx+0] = src[0]; dstv[idx+0] = src[1]; + dstu[idx+1] = src[2]; dstv[idx+1] = src[3]; + dstu[idx+2] = src[4]; dstv[idx+2] = src[5]; + dstu[idx+3] = src[6]; dstv[idx+3] = src[7]; + dstu[idx+4] = src[8]; dstv[idx+4] = src[9]; + dstu[idx+5] = src[10]; dstv[idx+5] = src[11]; + dstu[idx+6] = src[12]; dstv[idx+6] = src[13]; + dstu[idx+7] = src[14]; dstv[idx+7] = src[15]; + src += 16; + } + } + } + } + + /*************************************************************************/ + int main(int argc, char **argv) + { + FILE *fin; + int i; + + if (argc == 1) fin = stdin; + else fin = fopen(argv[1], "r"); + + if (fin == NULL) { + fprintf(stderr, "cannot open input\n"); + exit(-1); + } + while (fread(frame, sizeof(frame), 1, fin) == 1) { + de_macro_y(framey, frame, 720, 720, 576); + de_macro_uv(frameu, framev, frame + 720 * 576, 720 / 2, 720 / 2, 576 / 2); + fwrite(framey, sizeof(framey), 1, stdout); + fwrite(framev, sizeof(framev), 1, stdout); + fwrite(frameu, sizeof(frameu), 1, stdout); + } + fclose(fin); + return 0; + } + + +Format of embedded V4L2_MPEG_STREAM_VBI_FMT_IVTV VBI data +--------------------------------------------------------- + +Author: Hans Verkuil + + +This section describes the V4L2_MPEG_STREAM_VBI_FMT_IVTV format of the VBI data +embedded in an MPEG-2 program stream. This format is in part dictated by some +hardware limitations of the ivtv driver (the driver for the Conexant cx23415/6 +chips), in particular a maximum size for the VBI data. Anything longer is cut +off when the MPEG stream is played back through the cx23415. + +The advantage of this format is it is very compact and that all VBI data for +all lines can be stored while still fitting within the maximum allowed size. + +The stream ID of the VBI data is 0xBD. The maximum size of the embedded data is +4 + 43 * 36, which is 4 bytes for a header and 2 * 18 VBI lines with a 1 byte +header and a 42 bytes payload each. Anything beyond this limit is cut off by +the cx23415/6 firmware. Besides the data for the VBI lines we also need 36 bits +for a bitmask determining which lines are captured and 4 bytes for a magic cookie, +signifying that this data package contains V4L2_MPEG_STREAM_VBI_FMT_IVTV VBI data. +If all lines are used, then there is no longer room for the bitmask. To solve this +two different magic numbers were introduced: + +'itv0': After this magic number two unsigned longs follow. Bits 0-17 of the first +unsigned long denote which lines of the first field are captured. Bits 18-31 of +the first unsigned long and bits 0-3 of the second unsigned long are used for the +second field. + +'ITV0': This magic number assumes all VBI lines are captured, i.e. it implicitly +implies that the bitmasks are 0xffffffff and 0xf. + +After these magic cookies (and the 8 byte bitmask in case of cookie 'itv0') the +captured VBI lines start: + +For each line the least significant 4 bits of the first byte contain the data type. +Possible values are shown in the table below. The payload is in the following 42 +bytes. + +Here is the list of possible data types: + +.. code-block:: c + + #define IVTV_SLICED_TYPE_TELETEXT 0x1 // Teletext (uses lines 6-22 for PAL) + #define IVTV_SLICED_TYPE_CC 0x4 // Closed Captions (line 21 NTSC) + #define IVTV_SLICED_TYPE_WSS 0x5 // Wide Screen Signal (line 23 PAL) + #define IVTV_SLICED_TYPE_VPS 0x7 // Video Programming System (PAL) (line 16) + diff --git a/Documentation/userspace-api/media/drivers/dw100.rst b/Documentation/userspace-api/media/drivers/dw100.rst new file mode 100644 index 000000000..fceea6ece --- /dev/null +++ b/Documentation/userspace-api/media/drivers/dw100.rst @@ -0,0 +1,84 @@ +.. SPDX-License-Identifier: GPL-2.0 + +DW100 dewarp driver +=================== + +The Vivante DW100 Dewarp Processor IP core found on i.MX8MP SoC applies a +programmable geometrical transformation on the input image to correct distortion +introduced by lenses. + +The transformation function is exposed by the hardware as a grid map with 16x16 +pixel macroblocks indexed using X, Y vertex coordinates. +:: + + Image width + <---------------------------------------> + + ^ .-------.-------.-------.-------.-------. + | | 16x16 | | | | | + I | | pixel | | | | | + m | | block | | | | | + a | .-------.-------.-------.-------.-------. + g | | | | | | | + e | | | | | | | + | | | | | | | + h | .-------.-------.-------.-------.-------. + e | | | | | | | + i | | | | | | | + g | | | | | | | + h | .-------.-------.-------.-------.-------. + t | | | | | | | + | | | | | | | + | | | | | | | + v '-------'-------'-------'-------'-------' + + Grid of Image Blocks for Dewarping Map + + +Each x, y coordinate register uses 16 bits to record the coordinate address in +an unsigned 12.4 fixed point format (UQ12.4). +:: + + .----------------------.--------..----------------------.--------. + | 31~20 | 19~16 || 15~4 | 3~0 | + | (integer) | (frac) || (integer) | (frac) | + '----------------------'--------''----------------------'--------' + <-------------------------------><-------------------------------> + Y coordinate X coordinate + + Remap Register Layout + +The dewarping map is set from applications using the +V4L2_CID_DW100_DEWARPING_16x16_VERTEX_MAP control. The control contains +an array of u32 values storing (x, y) destination coordinates for each +vertex of the grid. The x coordinate is stored in the 16 LSBs and the y +coordinate in the 16 MSBs. + +The number of elements in the array must match the image size: + +.. code-block:: C + + elems = (DIV_ROUND_UP(width, 16) + 1) * (DIV_ROUND_UP(height, 16) + 1); + +If the control has not been set by the application, the driver uses an identity +map. + +More details on the DW100 hardware operations can be found in +*chapter 13.15 DeWarp* of IMX8MP_ reference manual. + +The Vivante DW100 m2m driver implements the following driver-specific control: + +``V4L2_CID_DW100_DEWARPING_16x16_VERTEX_MAP (__u32 array)`` + Specifies to DW100 driver its dewarping map (aka LUT) blob as described in + *chapter 13.15.2.3 Dewarping Remap* of IMX8MP_ reference manual as an U32 + dynamic array. The image is divided into many small 16x16 blocks. If the + width/height of the image is not divisible by 16, the size of the + rightmost/bottommost block is the remainder. The dewarping map only saves + the vertex coordinates of the block. The dewarping grid map is comprised of + vertex coordinates for x and y. Each x, y coordinate register uses 16 bits + (UQ12.4) to record the coordinate address, with the Y coordinate in the + upper bits and X in the lower bits. The driver modifies the dimensions of + this control when the sink format is changed, to reflect the new input + resolution. + +.. _IMX8MP: https://www.nxp.com/webapp/Download?colCode=IMX8MPRM diff --git a/Documentation/userspace-api/media/drivers/imx-uapi.rst b/Documentation/userspace-api/media/drivers/imx-uapi.rst new file mode 100644 index 000000000..8d47712de --- /dev/null +++ b/Documentation/userspace-api/media/drivers/imx-uapi.rst @@ -0,0 +1,125 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +i.MX Video Capture Driver +========================= + +Events +====== + +.. _imx_api_ipuX_csiY: + +ipuX_csiY +--------- + +This subdev can generate the following event when enabling the second +IDMAC source pad: + +- V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR + +The user application can subscribe to this event from the ipuX_csiY +subdev node. This event is generated by the Frame Interval Monitor +(see below for more on the FIM). + +Controls +======== + +.. _imx_api_FIM: + +Frame Interval Monitor in ipuX_csiY +----------------------------------- + +The adv718x decoders can occasionally send corrupt fields during +NTSC/PAL signal re-sync (too little or too many video lines). When +this happens, the IPU triggers a mechanism to re-establish vertical +sync by adding 1 dummy line every frame, which causes a rolling effect +from image to image, and can last a long time before a stable image is +recovered. Or sometimes the mechanism doesn't work at all, causing a +permanent split image (one frame contains lines from two consecutive +captured images). + +From experiment it was found that during image rolling, the frame +intervals (elapsed time between two EOF's) drop below the nominal +value for the current standard, by about one frame time (60 usec), +and remain at that value until rolling stops. + +While the reason for this observation isn't known (the IPU dummy +line mechanism should show an increase in the intervals by 1 line +time every frame, not a fixed value), we can use it to detect the +corrupt fields using a frame interval monitor. If the FIM detects a +bad frame interval, the ipuX_csiY subdev will send the event +V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR. Userland can register with +the FIM event notification on the ipuX_csiY subdev device node. +Userland can issue a streaming restart when this event is received +to correct the rolling/split image. + +The ipuX_csiY subdev includes custom controls to tweak some dials for +FIM. If one of these controls is changed during streaming, the FIM will +be reset and will continue at the new settings. + +- V4L2_CID_IMX_FIM_ENABLE + +Enable/disable the FIM. + +- V4L2_CID_IMX_FIM_NUM + +How many frame interval measurements to average before comparing against +the nominal frame interval reported by the sensor. This can reduce noise +caused by interrupt latency. + +- V4L2_CID_IMX_FIM_TOLERANCE_MIN + +If the averaged intervals fall outside nominal by this amount, in +microseconds, the V4L2_EVENT_IMX_FRAME_INTERVAL_ERROR event is sent. + +- V4L2_CID_IMX_FIM_TOLERANCE_MAX + +If any intervals are higher than this value, those samples are +discarded and do not enter into the average. This can be used to +discard really high interval errors that might be due to interrupt +latency from high system load. + +- V4L2_CID_IMX_FIM_NUM_SKIP + +How many frames to skip after a FIM reset or stream restart before +FIM begins to average intervals. + +- V4L2_CID_IMX_FIM_ICAP_CHANNEL / V4L2_CID_IMX_FIM_ICAP_EDGE + +These controls will configure an input capture channel as the method +for measuring frame intervals. This is superior to the default method +of measuring frame intervals via EOF interrupt, since it is not subject +to uncertainty errors introduced by interrupt latency. + +Input capture requires hardware support. A VSYNC signal must be routed +to one of the i.MX6 input capture channel pads. + +V4L2_CID_IMX_FIM_ICAP_CHANNEL configures which i.MX6 input capture +channel to use. This must be 0 or 1. + +V4L2_CID_IMX_FIM_ICAP_EDGE configures which signal edge will trigger +input capture events. By default the input capture method is disabled +with a value of IRQ_TYPE_NONE. Set this control to IRQ_TYPE_EDGE_RISING, +IRQ_TYPE_EDGE_FALLING, or IRQ_TYPE_EDGE_BOTH to enable input capture, +triggered on the given signal edge(s). + +When input capture is disabled, frame intervals will be measured via +EOF interrupt. + + +File list +--------- + +drivers/staging/media/imx/ +include/media/imx.h +include/linux/imx-media.h + + +Authors +------- + +- Steve Longerbeam +- Philipp Zabel +- Russell King + +Copyright (C) 2012-2017 Mentor Graphics Inc. diff --git a/Documentation/userspace-api/media/drivers/index.rst b/Documentation/userspace-api/media/drivers/index.rst new file mode 100644 index 000000000..32f82aed4 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/index.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: + +.. _v4l-drivers_uapi: + +################################################ +Video4Linux (V4L) driver-specific documentation +################################################ + +**Copyright** |copy| 1999-2016 : LinuxTV Developers + +This documentation is free software; you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the Free +Software Foundation version 2 of the License. + +This program is distributed in the hope that it will be useful, but WITHOUT +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for +more details. + +For more details see the file COPYING in the source distribution of Linux. + +.. only:: html + + .. class:: toc-title + + Table of Contents + +.. toctree:: + :maxdepth: 5 + :numbered: + + ccs + cx2341x-uapi + dw100 + imx-uapi + max2175 + meye-uapi + omap3isp-uapi + uvcvideo diff --git a/Documentation/userspace-api/media/drivers/max2175.rst b/Documentation/userspace-api/media/drivers/max2175.rst new file mode 100644 index 000000000..35d3c4b41 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/max2175.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Maxim Integrated MAX2175 RF to bits tuner driver +================================================ + +The MAX2175 driver implements the following driver-specific controls: + +``V4L2_CID_MAX2175_I2S_ENABLE`` +------------------------------- + Enable/Disable I2S output of the tuner. This is a private control + that can be accessed only using the subdev interface. + Refer to Documentation/driver-api/media/v4l2-controls.rst for more details. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``(0)`` + - I2S output is disabled. + * - ``(1)`` + - I2S output is enabled. + +``V4L2_CID_MAX2175_HSLS`` +------------------------- + The high-side/low-side (HSLS) control of the tuner for a given band. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``(0)`` + - The LO frequency position is below the desired frequency. + * - ``(1)`` + - The LO frequency position is above the desired frequency. + +``V4L2_CID_MAX2175_RX_MODE (menu)`` +----------------------------------- + The Rx mode controls a number of preset parameters of the tuner like + sample clock (sck), sampling rate etc. These multiple settings are + provided under one single label called Rx mode in the datasheet. The + list below shows the supported modes with a brief description. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 4 + + * - ``"Europe modes"`` + * - ``"FM 1.2" (0)`` + - This configures FM band with a sample rate of 0.512 million + samples/sec with a 10.24 MHz sck. + * - ``"DAB 1.2" (1)`` + - This configures VHF band with a sample rate of 2.048 million + samples/sec with a 32.768 MHz sck. + + * - ``"North America modes"`` + * - ``"FM 1.0" (0)`` + - This configures FM band with a sample rate of 0.7441875 million + samples/sec with a 14.88375 MHz sck. + * - ``"DAB 1.2" (1)`` + - This configures FM band with a sample rate of 0.372 million + samples/sec with a 7.441875 MHz sck. diff --git a/Documentation/userspace-api/media/drivers/meye-uapi.rst b/Documentation/userspace-api/media/drivers/meye-uapi.rst new file mode 100644 index 000000000..66b1c142f --- /dev/null +++ b/Documentation/userspace-api/media/drivers/meye-uapi.rst @@ -0,0 +1,53 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: + +Vaio Picturebook Motion Eye Camera Driver +========================================= + +Copyright |copy| 2001-2004 Stelian Pop + +Copyright |copy| 2001-2002 AlcĂ´ve + +Copyright |copy| 2000 Andrew Tridgell + +Private API +----------- + +The driver supports frame grabbing with the video4linux API, +so all video4linux tools (like xawtv) should work with this driver. + +Besides the video4linux interface, the driver has a private interface +for accessing the Motion Eye extended parameters (camera sharpness, +agc, video framerate), the snapshot and the MJPEG capture facilities. + +This interface consists of several ioctls (prototypes and structures +can be found in include/linux/meye.h): + +MEYEIOC_G_PARAMS and MEYEIOC_S_PARAMS + Get and set the extended parameters of the motion eye camera. + The user should always query the current parameters with + MEYEIOC_G_PARAMS, change what he likes and then issue the + MEYEIOC_S_PARAMS call (checking for -EINVAL). The extended + parameters are described by the meye_params structure. + + +MEYEIOC_QBUF_CAPT + Queue a buffer for capture (the buffers must have been + obtained with a VIDIOCGMBUF call and mmap'ed by the + application). The argument to MEYEIOC_QBUF_CAPT is the + buffer number to queue (or -1 to end capture). The first + call to MEYEIOC_QBUF_CAPT starts the streaming capture. + +MEYEIOC_SYNC + Takes as an argument the buffer number you want to sync. + This ioctl blocks until the buffer is filled and ready + for the application to use. It returns the buffer size. + +MEYEIOC_STILLCAPT and MEYEIOC_STILLJCAPT + Takes a snapshot in an uncompressed or compressed jpeg format. + This ioctl blocks until the snapshot is done and returns (for + jpeg snapshot) the size of the image. The image data is + available from the first mmap'ed buffer. + +Look at the 'motioneye' application code for an actual example. diff --git a/Documentation/userspace-api/media/drivers/omap3isp-uapi.rst b/Documentation/userspace-api/media/drivers/omap3isp-uapi.rst new file mode 100644 index 000000000..5f966a874 --- /dev/null +++ b/Documentation/userspace-api/media/drivers/omap3isp-uapi.rst @@ -0,0 +1,208 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: + +OMAP 3 Image Signal Processor (ISP) driver +========================================== + +Copyright |copy| 2010 Nokia Corporation + +Copyright |copy| 2009 Texas Instruments, Inc. + +Contacts: Laurent Pinchart , +Sakari Ailus , David Cohen + + +Events +------ + +The OMAP 3 ISP driver does support the V4L2 event interface on CCDC and +statistics (AEWB, AF and histogram) subdevs. + +The CCDC subdev produces V4L2_EVENT_FRAME_SYNC type event on HS_VS +interrupt which is used to signal frame start. Earlier version of this +driver used V4L2_EVENT_OMAP3ISP_HS_VS for this purpose. The event is +triggered exactly when the reception of the first line of the frame starts +in the CCDC module. The event can be subscribed on the CCDC subdev. + +(When using parallel interface one must pay account to correct configuration +of the VS signal polarity. This is automatically correct when using the serial +receivers.) + +Each of the statistics subdevs is able to produce events. An event is +generated whenever a statistics buffer can be dequeued by a user space +application using the VIDIOC_OMAP3ISP_STAT_REQ IOCTL. The events available +are: + +- V4L2_EVENT_OMAP3ISP_AEWB +- V4L2_EVENT_OMAP3ISP_AF +- V4L2_EVENT_OMAP3ISP_HIST + +The type of the event data is struct omap3isp_stat_event_status for these +ioctls. If there is an error calculating the statistics, there will be an +event as usual, but no related statistics buffer. In this case +omap3isp_stat_event_status.buf_err is set to non-zero. + + +Private IOCTLs +-------------- + +The OMAP 3 ISP driver supports standard V4L2 IOCTLs and controls where +possible and practical. Much of the functions provided by the ISP, however, +does not fall under the standard IOCTLs --- gamma tables and configuration of +statistics collection are examples of such. + +In general, there is a private ioctl for configuring each of the blocks +containing hardware-dependent functions. + +The following private IOCTLs are supported: + +- VIDIOC_OMAP3ISP_CCDC_CFG +- VIDIOC_OMAP3ISP_PRV_CFG +- VIDIOC_OMAP3ISP_AEWB_CFG +- VIDIOC_OMAP3ISP_HIST_CFG +- VIDIOC_OMAP3ISP_AF_CFG +- VIDIOC_OMAP3ISP_STAT_REQ +- VIDIOC_OMAP3ISP_STAT_EN + +The parameter structures used by these ioctls are described in +include/linux/omap3isp.h. The detailed functions of the ISP itself related to +a given ISP block is described in the Technical Reference Manuals (TRMs) --- +see the end of the document for those. + +While it is possible to use the ISP driver without any use of these private +IOCTLs it is not possible to obtain optimal image quality this way. The AEWB, +AF and histogram modules cannot be used without configuring them using the +appropriate private IOCTLs. + + +CCDC and preview block IOCTLs +----------------------------- + +The VIDIOC_OMAP3ISP_CCDC_CFG and VIDIOC_OMAP3ISP_PRV_CFG IOCTLs are used to +configure, enable and disable functions in the CCDC and preview blocks, +respectively. Both IOCTLs control several functions in the blocks they +control. VIDIOC_OMAP3ISP_CCDC_CFG IOCTL accepts a pointer to struct +omap3isp_ccdc_update_config as its argument. Similarly VIDIOC_OMAP3ISP_PRV_CFG +accepts a pointer to struct omap3isp_prev_update_config. The definition of +both structures is available in [#]_. + +The update field in the structures tells whether to update the configuration +for the specific function and the flag tells whether to enable or disable the +function. + +The update and flag bit masks accept the following values. Each separate +functions in the CCDC and preview blocks is associated with a flag (either +disable or enable; part of the flag field in the structure) and a pointer to +configuration data for the function. + +Valid values for the update and flag fields are listed here for +VIDIOC_OMAP3ISP_CCDC_CFG. Values may be or'ed to configure more than one +function in the same IOCTL call. + +- OMAP3ISP_CCDC_ALAW +- OMAP3ISP_CCDC_LPF +- OMAP3ISP_CCDC_BLCLAMP +- OMAP3ISP_CCDC_BCOMP +- OMAP3ISP_CCDC_FPC +- OMAP3ISP_CCDC_CULL +- OMAP3ISP_CCDC_CONFIG_LSC +- OMAP3ISP_CCDC_TBL_LSC + +The corresponding values for the VIDIOC_OMAP3ISP_PRV_CFG are here: + +- OMAP3ISP_PREV_LUMAENH +- OMAP3ISP_PREV_INVALAW +- OMAP3ISP_PREV_HRZ_MED +- OMAP3ISP_PREV_CFA +- OMAP3ISP_PREV_CHROMA_SUPP +- OMAP3ISP_PREV_WB +- OMAP3ISP_PREV_BLKADJ +- OMAP3ISP_PREV_RGB2RGB +- OMAP3ISP_PREV_COLOR_CONV +- OMAP3ISP_PREV_YC_LIMIT +- OMAP3ISP_PREV_DEFECT_COR +- OMAP3ISP_PREV_GAMMABYPASS +- OMAP3ISP_PREV_DRK_FRM_CAPTURE +- OMAP3ISP_PREV_DRK_FRM_SUBTRACT +- OMAP3ISP_PREV_LENS_SHADING +- OMAP3ISP_PREV_NF +- OMAP3ISP_PREV_GAMMA + +The associated configuration pointer for the function may not be NULL when +enabling the function. When disabling a function the configuration pointer is +ignored. + + +Statistic blocks IOCTLs +----------------------- + +The statistics subdevs do offer more dynamic configuration options than the +other subdevs. They can be enabled, disable and reconfigured when the pipeline +is in streaming state. + +The statistics blocks always get the input image data from the CCDC (as the +histogram memory read isn't implemented). The statistics are dequeueable by +the user from the statistics subdev nodes using private IOCTLs. + +The private IOCTLs offered by the AEWB, AF and histogram subdevs are heavily +reflected by the register level interface offered by the ISP hardware. There +are aspects that are purely related to the driver implementation and these are +discussed next. + +VIDIOC_OMAP3ISP_STAT_EN +----------------------- + +This private IOCTL enables/disables a statistic module. If this request is +done before streaming, it will take effect as soon as the pipeline starts to +stream. If the pipeline is already streaming, it will take effect as soon as +the CCDC becomes idle. + +VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG +----------------------------------------------------------------------------- + +Those IOCTLs are used to configure the modules. They require user applications +to have an in-depth knowledge of the hardware. Most of the fields explanation +can be found on OMAP's TRMs. The two following fields common to all the above +configure private IOCTLs require explanation for better understanding as they +are not part of the TRM. + +omap3isp_[h3a_af/h3a_aewb/hist]\_config.buf_size: + +The modules handle their buffers internally. The necessary buffer size for the +module's data output depends on the requested configuration. Although the +driver supports reconfiguration while streaming, it does not support a +reconfiguration which requires bigger buffer size than what is already +internally allocated if the module is enabled. It will return -EBUSY on this +case. In order to avoid such condition, either disable/reconfigure/enable the +module or request the necessary buffer size during the first configuration +while the module is disabled. + +The internal buffer size allocation considers the requested configuration's +minimum buffer size and the value set on buf_size field. If buf_size field is +out of [minimum, maximum] buffer size range, it's clamped to fit in there. +The driver then selects the biggest value. The corrected buf_size value is +written back to user application. + +omap3isp_[h3a_af/h3a_aewb/hist]\_config.config_counter: + +As the configuration doesn't take effect synchronously to the request, the +driver must provide a way to track this information to provide more accurate +data. After a configuration is requested, the config_counter returned to user +space application will be an unique value associated to that request. When +user application receives an event for buffer availability or when a new +buffer is requested, this config_counter is used to match a buffer data and a +configuration. + +VIDIOC_OMAP3ISP_STAT_REQ +------------------------ + +Send to user space the oldest data available in the internal buffer queue and +discards such buffer afterwards. The field omap3isp_stat_data.frame_number +matches with the video buffer's field_count. + + +References +---------- + +.. [#] include/linux/omap3isp.h diff --git a/Documentation/userspace-api/media/drivers/uvcvideo.rst b/Documentation/userspace-api/media/drivers/uvcvideo.rst new file mode 100644 index 000000000..a290f9fad --- /dev/null +++ b/Documentation/userspace-api/media/drivers/uvcvideo.rst @@ -0,0 +1,257 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The Linux USB Video Class (UVC) driver +====================================== + +This file documents some driver-specific aspects of the UVC driver, such as +driver-specific ioctls and implementation notes. + +Questions and remarks can be sent to the Linux UVC development mailing list at +linux-media@vger.kernel.org. + + +Extension Unit (XU) support +--------------------------- + +Introduction +~~~~~~~~~~~~ + +The UVC specification allows for vendor-specific extensions through extension +units (XUs). The Linux UVC driver supports extension unit controls (XU controls) +through two separate mechanisms: + + - through mappings of XU controls to V4L2 controls + - through a driver-specific ioctl interface + +The first one allows generic V4L2 applications to use XU controls by mapping +certain XU controls onto V4L2 controls, which then show up during ordinary +control enumeration. + +The second mechanism requires uvcvideo-specific knowledge for the application to +access XU controls but exposes the entire UVC XU concept to user space for +maximum flexibility. + +Both mechanisms complement each other and are described in more detail below. + + +Control mappings +~~~~~~~~~~~~~~~~ + +The UVC driver provides an API for user space applications to define so-called +control mappings at runtime. These allow for individual XU controls or byte +ranges thereof to be mapped to new V4L2 controls. Such controls appear and +function exactly like normal V4L2 controls (i.e. the stock controls, such as +brightness, contrast, etc.). However, reading or writing of such a V4L2 controls +triggers a read or write of the associated XU control. + +The ioctl used to create these control mappings is called UVCIOC_CTRL_MAP. +Previous driver versions (before 0.2.0) required another ioctl to be used +beforehand (UVCIOC_CTRL_ADD) to pass XU control information to the UVC driver. +This is no longer necessary as newer uvcvideo versions query the information +directly from the device. + +For details on the UVCIOC_CTRL_MAP ioctl please refer to the section titled +"IOCTL reference" below. + + +3. Driver specific XU control interface + +For applications that need to access XU controls directly, e.g. for testing +purposes, firmware upload, or accessing binary controls, a second mechanism to +access XU controls is provided in the form of a driver-specific ioctl, namely +UVCIOC_CTRL_QUERY. + +A call to this ioctl allows applications to send queries to the UVC driver that +directly map to the low-level UVC control requests. + +In order to make such a request the UVC unit ID of the control's extension unit +and the control selector need to be known. This information either needs to be +hardcoded in the application or queried using other ways such as by parsing the +UVC descriptor or, if available, using the media controller API to enumerate a +device's entities. + +Unless the control size is already known it is necessary to first make a +UVC_GET_LEN requests in order to be able to allocate a sufficiently large buffer +and set the buffer size to the correct value. Similarly, to find out whether +UVC_GET_CUR or UVC_SET_CUR are valid requests for a given control, a +UVC_GET_INFO request should be made. The bits 0 (GET supported) and 1 (SET +supported) of the resulting byte indicate which requests are valid. + +With the addition of the UVCIOC_CTRL_QUERY ioctl the UVCIOC_CTRL_GET and +UVCIOC_CTRL_SET ioctls have become obsolete since their functionality is a +subset of the former ioctl. For the time being they are still supported but +application developers are encouraged to use UVCIOC_CTRL_QUERY instead. + +For details on the UVCIOC_CTRL_QUERY ioctl please refer to the section titled +"IOCTL reference" below. + + +Security +~~~~~~~~ + +The API doesn't currently provide a fine-grained access control facility. The +UVCIOC_CTRL_ADD and UVCIOC_CTRL_MAP ioctls require super user permissions. + +Suggestions on how to improve this are welcome. + + +Debugging +~~~~~~~~~ + +In order to debug problems related to XU controls or controls in general it is +recommended to enable the UVC_TRACE_CONTROL bit in the module parameter 'trace'. +This causes extra output to be written into the system log. + + +IOCTL reference +~~~~~~~~~~~~~~~ + +UVCIOC_CTRL_MAP - Map a UVC control to a V4L2 control +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Argument: struct uvc_xu_control_mapping + +**Description**: + + This ioctl creates a mapping between a UVC control or part of a UVC + control and a V4L2 control. Once mappings are defined, userspace + applications can access vendor-defined UVC control through the V4L2 + control API. + + To create a mapping, applications fill the uvc_xu_control_mapping + structure with information about an existing UVC control defined with + UVCIOC_CTRL_ADD and a new V4L2 control. + + A UVC control can be mapped to several V4L2 controls. For instance, + a UVC pan/tilt control could be mapped to separate pan and tilt V4L2 + controls. The UVC control is divided into non overlapping fields using + the 'size' and 'offset' fields and are then independently mapped to + V4L2 control. + + For signed integer V4L2 controls the data_type field should be set to + UVC_CTRL_DATA_TYPE_SIGNED. Other values are currently ignored. + +**Return value**: + + On success 0 is returned. On error -1 is returned and errno is set + appropriately. + + ENOMEM + Not enough memory to perform the operation. + EPERM + Insufficient privileges (super user privileges are required). + EINVAL + No such UVC control. + EOVERFLOW + The requested offset and size would overflow the UVC control. + EEXIST + Mapping already exists. + +**Data types**: + +.. code-block:: none + + * struct uvc_xu_control_mapping + + __u32 id V4L2 control identifier + __u8 name[32] V4L2 control name + __u8 entity[16] UVC extension unit GUID + __u8 selector UVC control selector + __u8 size V4L2 control size (in bits) + __u8 offset V4L2 control offset (in bits) + enum v4l2_ctrl_type + v4l2_type V4L2 control type + enum uvc_control_data_type + data_type UVC control data type + struct uvc_menu_info + *menu_info Array of menu entries (for menu controls only) + __u32 menu_count Number of menu entries (for menu controls only) + + * struct uvc_menu_info + + __u32 value Menu entry value used by the device + __u8 name[32] Menu entry name + + + * enum uvc_control_data_type + + UVC_CTRL_DATA_TYPE_RAW Raw control (byte array) + UVC_CTRL_DATA_TYPE_SIGNED Signed integer + UVC_CTRL_DATA_TYPE_UNSIGNED Unsigned integer + UVC_CTRL_DATA_TYPE_BOOLEAN Boolean + UVC_CTRL_DATA_TYPE_ENUM Enumeration + UVC_CTRL_DATA_TYPE_BITMASK Bitmask + + +UVCIOC_CTRL_QUERY - Query a UVC XU control +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Argument: struct uvc_xu_control_query + +**Description**: + + This ioctl queries a UVC XU control identified by its extension unit ID + and control selector. + + There are a number of different queries available that closely + correspond to the low-level control requests described in the UVC + specification. These requests are: + + UVC_GET_CUR + Obtain the current value of the control. + UVC_GET_MIN + Obtain the minimum value of the control. + UVC_GET_MAX + Obtain the maximum value of the control. + UVC_GET_DEF + Obtain the default value of the control. + UVC_GET_RES + Query the resolution of the control, i.e. the step size of the + allowed control values. + UVC_GET_LEN + Query the size of the control in bytes. + UVC_GET_INFO + Query the control information bitmap, which indicates whether + get/set requests are supported. + UVC_SET_CUR + Update the value of the control. + + Applications must set the 'size' field to the correct length for the + control. Exceptions are the UVC_GET_LEN and UVC_GET_INFO queries, for + which the size must be set to 2 and 1, respectively. The 'data' field + must point to a valid writable buffer big enough to hold the indicated + number of data bytes. + + Data is copied directly from the device without any driver-side + processing. Applications are responsible for data buffer formatting, + including little-endian/big-endian conversion. This is particularly + important for the result of the UVC_GET_LEN requests, which is always + returned as a little-endian 16-bit integer by the device. + +**Return value**: + + On success 0 is returned. On error -1 is returned and errno is set + appropriately. + + ENOENT + The device does not support the given control or the specified + extension unit could not be found. + ENOBUFS + The specified buffer size is incorrect (too big or too small). + EINVAL + An invalid request code was passed. + EBADRQC + The given request is not supported by the given control. + EFAULT + The data pointer references an inaccessible memory area. + +**Data types**: + +.. code-block:: none + + * struct uvc_xu_control_query + + __u8 unit Extension unit ID + __u8 selector Control selector + __u8 query Request code to send to the device + __u16 size Control data size (in bytes) + __u8 *data Control value diff --git a/Documentation/userspace-api/media/dvb/ca-fclose.rst b/Documentation/userspace-api/media/dvb/ca-fclose.rst new file mode 100644 index 000000000..27f217a35 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-fclose.rst @@ -0,0 +1,40 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _ca_fclose: + +===================== +Digital TV CA close() +===================== + +Name +---- + +Digital TV CA close() + +Synopsis +-------- + +.. c:function:: int close(int fd) + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +Description +----------- + +This system call closes a previously opened CA device. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-fopen.rst b/Documentation/userspace-api/media/dvb/ca-fopen.rst new file mode 100644 index 000000000..7f99908ff --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-fopen.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _ca_fopen: + +==================== +Digital TV CA open() +==================== + +Name +---- + +Digital TV CA open() + +Synopsis +-------- + +.. c:function:: int open(const char *name, int flags) + +Arguments +--------- + +``name`` + Name of specific Digital TV CA device. + +``flags`` + A bit-wise OR of the following flags: + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``O_RDONLY`` + - read-only access + + - - ``O_RDWR`` + - read/write access + + - - ``O_NONBLOCK`` + - open in non-blocking mode + (blocking mode is the default) + +Description +----------- + +This system call opens a named ca device (e.g. ``/dev/dvb/adapter?/ca?``) +for subsequent use. + +When an ``open()`` call has succeeded, the device will be ready for use. The +significance of blocking or non-blocking mode is described in the +documentation for functions where there is a difference. It does not +affect the semantics of the ``open()`` call itself. A device opened in +blocking mode can later be put into non-blocking mode (and vice versa) +using the ``F_SETFL`` command of the ``fcntl`` system call. This is a +standard system call, documented in the Linux manual page for fcntl. +Only one user can open the CA Device in ``O_RDWR`` mode. All other +attempts to open the device in this mode will fail, and an error code +will be returned. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-get-cap.rst b/Documentation/userspace-api/media/dvb/ca-get-cap.rst new file mode 100644 index 000000000..9b29513ee --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-get-cap.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_GET_CAP: + +========== +CA_GET_CAP +========== + +Name +---- + +CA_GET_CAP + +Synopsis +-------- + +.. c:macro:: CA_GET_CAP + +``int ioctl(fd, CA_GET_CAP, struct ca_caps *caps)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``caps`` + Pointer to struct :c:type:`ca_caps`. + +Description +----------- + +Queries the Kernel for information about the available CA and descrambler +slots, and their types. + +Return Value +------------ + +On success 0 is returned and :c:type:`ca_caps` is filled. + +On error, -1 is returned and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst b/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst new file mode 100644 index 000000000..0cfdcdab3 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-get-descr-info.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_GET_DESCR_INFO: + +================= +CA_GET_DESCR_INFO +================= + +Name +---- + +CA_GET_DESCR_INFO + +Synopsis +-------- + +.. c:macro:: CA_GET_DESCR_INFO + +``int ioctl(fd, CA_GET_DESCR_INFO, struct ca_descr_info *desc)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``desc`` + Pointer to struct :c:type:`ca_descr_info`. + +Description +----------- + +Returns information about all descrambler slots. + +Return Value +------------ + +On success 0 is returned, and :c:type:`ca_descr_info` is filled. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-get-msg.rst b/Documentation/userspace-api/media/dvb/ca-get-msg.rst new file mode 100644 index 000000000..7c9a8d197 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-get-msg.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_GET_MSG: + +========== +CA_GET_MSG +========== + +Name +---- + +CA_GET_MSG + +Synopsis +-------- + +.. c:macro:: CA_GET_MSG + +``int ioctl(fd, CA_GET_MSG, struct ca_msg *msg)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``msg`` + Pointer to struct :c:type:`ca_msg`. + +Description +----------- + +Receives a message via a CI CA module. + +.. note:: + + Please notice that, on most drivers, this is done by reading from + the /dev/adapter?/ca? device node. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst b/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst new file mode 100644 index 000000000..582444af7 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-get-slot-info.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_GET_SLOT_INFO: + +================ +CA_GET_SLOT_INFO +================ + +Name +---- + +CA_GET_SLOT_INFO + +Synopsis +-------- + +.. c:macro:: CA_GET_SLOT_INFO + +``int ioctl(fd, CA_GET_SLOT_INFO, struct ca_slot_info *info)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``info`` + Pointer to struct :c:type:`ca_slot_info`. + +Description +----------- + +Returns information about a CA slot identified by +:c:type:`ca_slot_info`.slot_num. + +Return Value +------------ + +On success 0 is returned, and :c:type:`ca_slot_info` is filled. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``ENODEV`` + - the slot is not available. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-reset.rst b/Documentation/userspace-api/media/dvb/ca-reset.rst new file mode 100644 index 000000000..b01ca48f0 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-reset.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_RESET: + +======== +CA_RESET +======== + +Name +---- + +CA_RESET + +Synopsis +-------- + +.. c:macro:: CA_RESET + +``int ioctl(fd, CA_RESET)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +Description +----------- + +Puts the Conditional Access hardware on its initial state. It should +be called before start using the CA hardware. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-send-msg.rst b/Documentation/userspace-api/media/dvb/ca-send-msg.rst new file mode 100644 index 000000000..7dd2ab4ef --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-send-msg.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_SEND_MSG: + +=========== +CA_SEND_MSG +=========== + +Name +---- + +CA_SEND_MSG + +Synopsis +-------- + +.. c:macro:: CA_SEND_MSG + +``int ioctl(fd, CA_SEND_MSG, struct ca_msg *msg)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``msg`` + Pointer to struct :c:type:`ca_msg`. + +Description +----------- + +Sends a message via a CI CA module. + +.. note:: + + Please notice that, on most drivers, this is done by writing + to the /dev/adapter?/ca? device node. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca-set-descr.rst b/Documentation/userspace-api/media/dvb/ca-set-descr.rst new file mode 100644 index 000000000..a740af34c --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca-set-descr.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.ca + +.. _CA_SET_DESCR: + +============ +CA_SET_DESCR +============ + +Name +---- + +CA_SET_DESCR + +Synopsis +-------- + +.. c:macro:: CA_SET_DESCR + +``int ioctl(fd, CA_SET_DESCR, struct ca_descr *desc)`` + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``msg`` + Pointer to struct :c:type:`ca_descr`. + +Description +----------- + +CA_SET_DESCR is used for feeding descrambler CA slots with descrambling +keys (referred as control words). + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/ca.rst b/Documentation/userspace-api/media/dvb/ca.rst new file mode 100644 index 000000000..0dc00e5e4 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dvb_ca: + +#################### +Digital TV CA Device +#################### + +The Digital TV CA device controls the conditional access hardware. It +can be accessed through ``/dev/dvb/adapter?/ca?``. Data types and ioctl +definitions can be accessed by including ``linux/dvb/ca.h`` in your +application. + +.. note:: + + There are three ioctls at this API that aren't documented: + :ref:`CA_GET_MSG`, :ref:`CA_SEND_MSG` and :ref:`CA_SET_DESCR`. + Documentation for them are welcome. + +.. toctree:: + :maxdepth: 1 + + ca_data_types + ca_function_calls + ca_high_level diff --git a/Documentation/userspace-api/media/dvb/ca_data_types.rst b/Documentation/userspace-api/media/dvb/ca_data_types.rst new file mode 100644 index 000000000..54ea2a987 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca_data_types.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _ca_data_types: + +************* +CA Data Types +************* + +.. kernel-doc:: include/uapi/linux/dvb/ca.h diff --git a/Documentation/userspace-api/media/dvb/ca_function_calls.rst b/Documentation/userspace-api/media/dvb/ca_function_calls.rst new file mode 100644 index 000000000..3b893fbd5 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca_function_calls.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _ca_function_calls: + +***************** +CA Function Calls +***************** + +.. toctree:: + :maxdepth: 1 + + ca-fopen + ca-fclose + ca-reset + ca-get-cap + ca-get-slot-info + ca-get-descr-info + ca-get-msg + ca-send-msg + ca-set-descr diff --git a/Documentation/userspace-api/media/dvb/ca_high_level.rst b/Documentation/userspace-api/media/dvb/ca_high_level.rst new file mode 100644 index 000000000..a73f3691c --- /dev/null +++ b/Documentation/userspace-api/media/dvb/ca_high_level.rst @@ -0,0 +1,157 @@ +.. SPDX-License-Identifier: GPL-2.0 + +The High level CI API +===================== + +.. note:: + + This documentation is outdated. + +This document describes the high level CI API as in accordance to the +Linux DVB API. + + +With the High Level CI approach any new card with almost any random +architecture can be implemented with this style, the definitions +inside the switch statement can be easily adapted for any card, thereby +eliminating the need for any additional ioctls. + +The disadvantage is that the driver/hardware has to manage the rest. For +the application programmer it would be as simple as sending/receiving an +array to/from the CI ioctls as defined in the Linux DVB API. No changes +have been made in the API to accommodate this feature. + + +Why the need for another CI interface? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is one of the most commonly asked question. Well a nice question. +Strictly speaking this is not a new interface. + +The CI interface is defined in the DVB API in ca.h as: + +.. code-block:: c + + typedef struct ca_slot_info { + int num; /* slot number */ + + int type; /* CA interface this slot supports */ + #define CA_CI 1 /* CI high level interface */ + #define CA_CI_LINK 2 /* CI link layer level interface */ + #define CA_CI_PHYS 4 /* CI physical layer level interface */ + #define CA_DESCR 8 /* built-in descrambler */ + #define CA_SC 128 /* simple smart card interface */ + + unsigned int flags; + #define CA_CI_MODULE_PRESENT 1 /* module (or card) inserted */ + #define CA_CI_MODULE_READY 2 + } ca_slot_info_t; + +This CI interface follows the CI high level interface, which is not +implemented by most applications. Hence this area is revisited. + +This CI interface is quite different in the case that it tries to +accommodate all other CI based devices, that fall into the other categories. + +This means that this CI interface handles the EN50221 style tags in the +Application layer only and no session management is taken care of by the +application. The driver/hardware will take care of all that. + +This interface is purely an EN50221 interface exchanging APDU's. This +means that no session management, link layer or a transport layer do +exist in this case in the application to driver communication. It is +as simple as that. The driver/hardware has to take care of that. + +With this High Level CI interface, the interface can be defined with the +regular ioctls. + +All these ioctls are also valid for the High level CI interface + +#define CA_RESET _IO('o', 128) +#define CA_GET_CAP _IOR('o', 129, ca_caps_t) +#define CA_GET_SLOT_INFO _IOR('o', 130, ca_slot_info_t) +#define CA_GET_DESCR_INFO _IOR('o', 131, ca_descr_info_t) +#define CA_GET_MSG _IOR('o', 132, ca_msg_t) +#define CA_SEND_MSG _IOW('o', 133, ca_msg_t) +#define CA_SET_DESCR _IOW('o', 134, ca_descr_t) + + +On querying the device, the device yields information thus: + +.. code-block:: none + + CA_GET_SLOT_INFO + ---------------------------- + Command = [info] + APP: Number=[1] + APP: Type=[1] + APP: flags=[1] + APP: CI High level interface + APP: CA/CI Module Present + + CA_GET_CAP + ---------------------------- + Command = [caps] + APP: Slots=[1] + APP: Type=[1] + APP: Descrambler keys=[16] + APP: Type=[1] + + CA_SEND_MSG + ---------------------------- + Descriptors(Program Level)=[ 09 06 06 04 05 50 ff f1] + Found CA descriptor @ program level + + (20) ES type=[2] ES pid=[201] ES length =[0 (0x0)] + (25) ES type=[4] ES pid=[301] ES length =[0 (0x0)] + ca_message length is 25 (0x19) bytes + EN50221 CA MSG=[ 9f 80 32 19 03 01 2d d1 f0 08 01 09 06 06 04 05 50 ff f1 02 e0 c9 00 00 04 e1 2d 00 00] + + +Not all ioctl's are implemented in the driver from the API, the other +features of the hardware that cannot be implemented by the API are achieved +using the CA_GET_MSG and CA_SEND_MSG ioctls. An EN50221 style wrapper is +used to exchange the data to maintain compatibility with other hardware. + +.. code-block:: c + + /* a message to/from a CI-CAM */ + typedef struct ca_msg { + unsigned int index; + unsigned int type; + unsigned int length; + unsigned char msg[256]; + } ca_msg_t; + + +The flow of data can be described thus, + +.. code-block:: none + + App (User) + ----- + parse + | + | + v + en50221 APDU (package) + -------------------------------------- + | | | High Level CI driver + | | | + | v | + | en50221 APDU (unpackage) | + | | | + | | | + | v | + | sanity checks | + | | | + | | | + | v | + | do (H/W dep) | + -------------------------------------- + | Hardware + | + v + +The High Level CI interface uses the EN50221 DVB standard, following a +standard ensures futureproofness. diff --git a/Documentation/userspace-api/media/dvb/demux.rst b/Documentation/userspace-api/media/dvb/demux.rst new file mode 100644 index 000000000..ef05abcf1 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/demux.rst @@ -0,0 +1,23 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dvb_demux: + +####################### +Digital TV Demux Device +####################### + +The Digital TV demux device controls the MPEG-TS filters for the +digital TV. If the driver and hardware supports, those filters are +implemented at the hardware. Otherwise, the Kernel provides a software +emulation. + +It can be accessed through ``/dev/adapter?/demux?``. Data types and +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/userspace-api/media/dvb/dmx-add-pid.rst b/Documentation/userspace-api/media/dvb/dmx-add-pid.rst new file mode 100644 index 000000000..ea0c7dd91 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-add-pid.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_ADD_PID: + +=========== +DMX_ADD_PID +=========== + +Name +---- + +DMX_ADD_PID + +Synopsis +-------- + +.. c:macro:: DMX_ADD_PID + +``int ioctl(fd, DMX_ADD_PID, __u16 *pid)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``pid`` + PID number to be filtered. + +Description +----------- + +This ioctl call allows to add multiple PIDs to a transport stream filter +previously set up with :ref:`DMX_SET_PES_FILTER` and output equal to +:c:type:`DMX_OUT_TSDEMUX_TAP `. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-expbuf.rst b/Documentation/userspace-api/media/dvb/dmx-expbuf.rst new file mode 100644 index 000000000..5cdc2035e --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-expbuf.rst @@ -0,0 +1,87 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_EXPBUF: + +**************** +ioctl DMX_EXPBUF +**************** + +Name +==== + +DMX_EXPBUF - Export a buffer as a DMABUF file descriptor. + +.. warning:: this API is still experimental + +Synopsis +======== + +.. c:macro:: DMX_EXPBUF + +``int ioctl(int fd, DMX_EXPBUF, struct dmx_exportbuffer *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`dmx_exportbuffer`. + +Description +=========== + +This ioctl is an extension to the memory mapping I/O method. +It can be used to export a buffer as a DMABUF file at any time after +buffers have been allocated with the :ref:`DMX_REQBUFS` ioctl. + +To export a buffer, applications fill struct :c:type:`dmx_exportbuffer`. +Applications must set the ``index`` field. Valid index numbers +range from zero to the number of buffers allocated with :ref:`DMX_REQBUFS` +(struct :c:type:`dmx_requestbuffers` ``count``) minus one. +Additional flags may be posted in the ``flags`` field. Refer to a manual +for open() for details. Currently only O_CLOEXEC, O_RDONLY, O_WRONLY, +and O_RDWR are supported. +All other fields must be set to zero. In the +case of multi-planar API, every plane is exported separately using +multiple :ref:`DMX_EXPBUF` calls. + +After calling :ref:`DMX_EXPBUF` the ``fd`` field will be set by a +driver, on success. This is a DMABUF file descriptor. The application may +pass it to other DMABUF-aware devices. It is recommended to close a DMABUF +file when it is no longer used to allow the associated memory to be reclaimed. + +Examples +======== + +.. code-block:: c + + int buffer_export(int v4lfd, enum dmx_buf_type bt, int index, int *dmafd) + { + struct dmx_exportbuffer expbuf; + + memset(&expbuf, 0, sizeof(expbuf)); + expbuf.type = bt; + expbuf.index = index; + if (ioctl(v4lfd, DMX_EXPBUF, &expbuf) == -1) { + perror("DMX_EXPBUF"); + return -1; + } + + *dmafd = expbuf.fd; + + return 0; + } + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EINVAL + A queue is not in MMAP mode or DMABUF exporting is not supported or + ``flags`` or ``index`` fields are invalid. diff --git a/Documentation/userspace-api/media/dvb/dmx-fclose.rst b/Documentation/userspace-api/media/dvb/dmx-fclose.rst new file mode 100644 index 000000000..719ac1d4f --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-fclose.rst @@ -0,0 +1,42 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _dmx_fclose: + +======================== +Digital TV demux close() +======================== + +Name +---- + +Digital TV demux close() + +Synopsis +-------- + +.. c:function:: int close(int fd) + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to + :c:func:`open()`. + +Description +----------- + +This system call deactivates and deallocates a filter that was +previously allocated via the :c:func:`open()` call. + +Return Value +------------ + +On success 0 is returned. + +On error, -1 is returned and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-fopen.rst b/Documentation/userspace-api/media/dvb/dmx-fopen.rst new file mode 100644 index 000000000..50b36eb43 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-fopen.rst @@ -0,0 +1,88 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _dmx_fopen: + +======================= +Digital TV demux open() +======================= + +Name +---- + +Digital TV demux open() + +Synopsis +-------- + +.. c:function:: int open(const char *deviceName, int flags) + +Arguments +--------- + +``name`` + Name of specific Digital TV demux device. + +``flags`` + A bit-wise OR of the following flags: + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - + - ``O_RDONLY`` + - read-only access + + - + - ``O_RDWR`` + - read/write access + + - + - ``O_NONBLOCK`` + - open in non-blocking mode + (blocking mode is the default) + +Description +----------- + +This system call, used with a device name of ``/dev/dvb/adapter?/demux?``, +allocates a new filter and returns a handle which can be used for +subsequent control of that filter. This call has to be made for each +filter to be used, i.e. every returned file descriptor is a reference to +a single filter. ``/dev/dvb/adapter?/dvr?`` is a logical device to be used +for retrieving Transport Streams for digital video recording. When +reading from this device a transport stream containing the packets from +all PES filters set in the corresponding demux device +(``/dev/dvb/adapter?/demux?``) having the output set to ``DMX_OUT_TS_TAP``. +A recorded Transport Stream is replayed by writing to this device. + +The significance of blocking or non-blocking mode is described in the +documentation for functions where there is a difference. It does not +affect the semantics of the ``open()`` call itself. A device opened +in blocking mode can later be put into non-blocking mode (and vice versa) +using the ``F_SETFL`` command of the fcntl system call. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``EMFILE`` + - "Too many open files", i.e. no more filters available. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-fread.rst b/Documentation/userspace-api/media/dvb/dmx-fread.rst new file mode 100644 index 000000000..88c4cddf7 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-fread.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _dmx_fread: + +======================= +Digital TV demux read() +======================= + +Name +---- + +Digital TV demux read() + +Synopsis +-------- + +.. c:function:: size_t read(int fd, void *buf, size_t count) + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + + ``buf`` + Buffer to be filled + +``count`` + Max number of bytes to read + +Description +----------- + +This system call returns filtered data, which might be section or Packetized +Elementary Stream (PES) data. The filtered data is transferred from +the driver's internal circular buffer to ``buf``. The maximum amount of data +to be transferred is implied by count. + +.. note:: + + if a section filter created with + :c:type:`DMX_CHECK_CRC ` flag set, + data that fails on CRC check will be silently ignored. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``EWOULDBLOCK`` + - No data to return and ``O_NONBLOCK`` was specified. + + - - ``EOVERFLOW`` + - The filtered data was not read from the buffer in due time, + resulting in non-read data being lost. The buffer is flushed. + + - - ``ETIMEDOUT`` + - The section was not loaded within the stated timeout period. + See ioctl :ref:`DMX_SET_FILTER` for how to set a timeout. + + - - ``EFAULT`` + - The driver failed to write to the callers buffer due to an + invalid \*buf pointer. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-fwrite.rst b/Documentation/userspace-api/media/dvb/dmx-fwrite.rst new file mode 100644 index 000000000..e11ee0ba8 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-fwrite.rst @@ -0,0 +1,70 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _dmx_fwrite: + +======================== +Digital TV demux write() +======================== + +Name +---- + +Digital TV demux write() + +Synopsis +-------- + +.. c:function:: ssize_t write(int fd, const void *buf, size_t count) + +Arguments +--------- + +``fd`` + File descriptor returned by a previous call to :c:func:`open()`. + +``buf`` + Buffer with data to be written + +``count`` + Number of bytes at the buffer + +Description +----------- + +This system call is only provided by the logical device +``/dev/dvb/adapter?/dvr?``, associated with the physical demux device that +provides the actual DVR functionality. It is used for replay of a +digitally recorded Transport Stream. Matching filters have to be defined +in the corresponding physical demux device, ``/dev/dvb/adapter?/demux?``. +The amount of data to be transferred is implied by count. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``EWOULDBLOCK`` + - No data was written. This might happen if ``O_NONBLOCK`` was + specified and there is no more buffer space available (if + ``O_NONBLOCK`` is not specified the function will block until buffer + space is available). + + - - ``EBUSY`` + - This error code indicates that there are conflicting requests. The + corresponding demux device is setup to receive data from the + front- end. Make sure that these filters are stopped and that the + filters with input set to ``DMX_IN_DVR`` are started. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst b/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst new file mode 100644 index 000000000..4f5f0505c --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-get-pes-pids.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_GET_PES_PIDS: + +================ +DMX_GET_PES_PIDS +================ + +Name +---- + +DMX_GET_PES_PIDS + +Synopsis +-------- + +.. c:macro:: DMX_GET_PES_PIDS + +``int ioctl(fd, DMX_GET_PES_PIDS, __u16 pids[5])`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``pids`` + Array used to store 5 Program IDs. + +Description +----------- + +This ioctl allows to query a DVB device to return the first PID used +by audio, video, textext, subtitle and PCR programs on a given service. +They're stored as: + +======================= ======== ======================================= +PID element position content +======================= ======== ======================================= +pids[DMX_PES_AUDIO] 0 first audio PID +pids[DMX_PES_VIDEO] 1 first video PID +pids[DMX_PES_TELETEXT] 2 first teletext PID +pids[DMX_PES_SUBTITLE] 3 first subtitle PID +pids[DMX_PES_PCR] 4 first Program Clock Reference PID +======================= ======== ======================================= + +.. note:: + + A value equal to 0xffff means that the PID was not filled by the + Kernel. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-get-stc.rst b/Documentation/userspace-api/media/dvb/dmx-get-stc.rst new file mode 100644 index 000000000..6ada74f6e --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-get-stc.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_GET_STC: + +=========== +DMX_GET_STC +=========== + +Name +---- + +DMX_GET_STC + +Synopsis +-------- + +.. c:macro:: DMX_GET_STC + +``int ioctl(int fd, DMX_GET_STC, struct dmx_stc *stc)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``stc`` + Pointer to :c:type:`dmx_stc` where the stc data is to be stored. + +Description +----------- + +This ioctl call returns the current value of the system time counter +(which is driven by a PES filter of type :c:type:`DMX_PES_PCR `). +Some hardware supports more than one STC, so you must specify which one by +setting the :c:type:`num ` field of stc before the ioctl (range 0...n). +The result is returned in form of a ratio with a 64 bit numerator +and a 32 bit denominator, so the real 90kHz STC value is +``stc->stc / stc->base``. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - .. row 1 + + - ``EINVAL`` + + - Invalid stc number. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-mmap.rst b/Documentation/userspace-api/media/dvb/dmx-mmap.rst new file mode 100644 index 000000000..8826c6226 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-mmap.rst @@ -0,0 +1,115 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _dmx-mmap: + +***************** +Digital TV mmap() +***************** + +Name +==== + +dmx-mmap - Map device memory into application address space + +.. warning:: this API is still experimental + +Synopsis +======== + +.. code-block:: c + + #include + #include + +.. c:function:: void *mmap( void *start, size_t length, int prot, int flags, int fd, off_t offset ) + +Arguments +========= + +``start`` + Map the buffer to this address in the application's address space. + When the ``MAP_FIXED`` flag is specified, ``start`` must be a + multiple of the pagesize and mmap will fail when the specified + address cannot be used. Use of this option is discouraged; + applications should just specify a ``NULL`` pointer here. + +``length`` + Length of the memory area to map. This must be a multiple of the + DVB packet length (188, on most drivers). + +``prot`` + The ``prot`` argument describes the desired memory protection. + Regardless of the device type and the direction of data exchange it + should be set to ``PROT_READ`` | ``PROT_WRITE``, permitting read + and write access to image buffers. Drivers should support at least + this combination of flags. + +``flags`` + The ``flags`` parameter specifies the type of the mapped object, + mapping options and whether modifications made to the mapped copy of + the page are private to the process or are to be shared with other + references. + + ``MAP_FIXED`` requests that the driver selects no other address than + the one specified. If the specified address cannot be used, + :c:func:`mmap()` will fail. If ``MAP_FIXED`` is specified, + ``start`` must be a multiple of the pagesize. Use of this option is + discouraged. + + One of the ``MAP_SHARED`` or ``MAP_PRIVATE`` flags must be set. + ``MAP_SHARED`` allows applications to share the mapped memory with + other (e. g. child-) processes. + + .. note:: + + The Linux Digital TV applications should not set the + ``MAP_PRIVATE``, ``MAP_DENYWRITE``, ``MAP_EXECUTABLE`` or ``MAP_ANON`` + flags. + +``fd`` + File descriptor returned by :c:func:`open()`. + +``offset`` + Offset of the buffer in device memory, as returned by + :ref:`DMX_QUERYBUF` ioctl. + +Description +=========== + +The :c:func:`mmap()` function asks to map ``length`` bytes starting at +``offset`` in the memory of the device specified by ``fd`` into the +application address space, preferably at address ``start``. This latter +address is a hint only, and is usually specified as 0. + +Suitable length and offset parameters are queried with the +:ref:`DMX_QUERYBUF` ioctl. Buffers must be allocated with the +:ref:`DMX_REQBUFS` ioctl before they can be queried. + +To unmap buffers the :c:func:`munmap()` function is used. + +Return Value +============ + +On success :c:func:`mmap()` returns a pointer to the mapped buffer. On +error ``MAP_FAILED`` (-1) is returned, and the ``errno`` variable is set +appropriately. Possible error codes are: + +EBADF + ``fd`` is not a valid file descriptor. + +EACCES + ``fd`` is not open for reading and writing. + +EINVAL + The ``start`` or ``length`` or ``offset`` are not suitable. (E. g. + they are too large, or not aligned on a ``PAGESIZE`` boundary.) + + The ``flags`` or ``prot`` value is not supported. + + No buffers have been allocated with the + :ref:`DMX_REQBUFS` ioctl. + +ENOMEM + Not enough physical or virtual memory was available to complete the + request. diff --git a/Documentation/userspace-api/media/dvb/dmx-munmap.rst b/Documentation/userspace-api/media/dvb/dmx-munmap.rst new file mode 100644 index 000000000..66bbc11e5 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-munmap.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _dmx-munmap: + +************ +DVB munmap() +************ + +Name +==== + +dmx-munmap - Unmap device memory + +.. warning:: This API is still experimental. + +Synopsis +======== + +.. code-block:: c + + #include + #include + +.. c:function:: int munmap( void *start, size_t length ) + +Arguments +========= + +``start`` + Address of the mapped buffer as returned by the + :c:func:`mmap()` function. + +``length`` + Length of the mapped buffer. This must be the same value as given to + :c:func:`mmap()`. + +Description +=========== + +Unmaps a previously with the :c:func:`mmap()` function mapped +buffer and frees it, if possible. + +Return Value +============ + +On success :c:func:`munmap()` returns 0, on failure -1 and the +``errno`` variable is set appropriately: + +EINVAL + The ``start`` or ``length`` is incorrect, or no buffers have been + mapped yet. diff --git a/Documentation/userspace-api/media/dvb/dmx-qbuf.rst b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst new file mode 100644 index 000000000..1a13a3383 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-qbuf.rst @@ -0,0 +1,85 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_QBUF: + +************************* +ioctl DMX_QBUF, DMX_DQBUF +************************* + +Name +==== + +DMX_QBUF - DMX_DQBUF - Exchange a buffer with the driver + +.. warning:: this API is still experimental + +Synopsis +======== + +.. c:macro:: DMX_QBUF + +``int ioctl(int fd, DMX_QBUF, struct dmx_buffer *argp)`` + +.. c:macro:: DMX_DQBUF + +``int ioctl(int fd, DMX_DQBUF, struct dmx_buffer *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`dmx_buffer`. + +Description +=========== + +Applications call the ``DMX_QBUF`` ioctl to enqueue an empty +(capturing) or filled (output) buffer in the driver's incoming queue. +The semantics depend on the selected I/O method. + +To enqueue a buffer applications set the ``index`` field. Valid index +numbers range from zero to the number of buffers allocated with +:ref:`DMX_REQBUFS` (struct :c:type:`dmx_requestbuffers` ``count``) minus +one. The contents of the struct :c:type:`dmx_buffer` returned +by a :ref:`DMX_QUERYBUF` ioctl will do as well. + +When ``DMX_QBUF`` is called with a pointer to this structure, it locks the +memory pages of the buffer in physical memory, so they cannot be swapped +out to disk. Buffers remain locked until dequeued, until the +device is closed. + +Applications call the ``DMX_DQBUF`` ioctl to dequeue a filled +(capturing) buffer from the driver's outgoing queue. +They just set the ``index`` field with the buffer ID to be queued. +When ``DMX_DQBUF`` is called with a pointer to struct :c:type:`dmx_buffer`, +the driver fills the remaining fields or returns an error code. + +By default ``DMX_DQBUF`` blocks when no buffer is in the outgoing +queue. When the ``O_NONBLOCK`` flag was given to the +:c:func:`open()` function, ``DMX_DQBUF`` returns +immediately with an ``EAGAIN`` error code when no buffer is available. + +The struct :c:type:`dmx_buffer` structure is specified in +:ref:`buffer`. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EAGAIN + Non-blocking I/O has been selected using ``O_NONBLOCK`` and no + buffer was in the outgoing queue. + +EINVAL + The ``index`` is out of bounds, or no buffers have been allocated yet. + +EIO + ``DMX_DQBUF`` failed due to an internal error. Can also indicate + temporary problems like signal loss or CRC errors. diff --git a/Documentation/userspace-api/media/dvb/dmx-querybuf.rst b/Documentation/userspace-api/media/dvb/dmx-querybuf.rst new file mode 100644 index 000000000..08ee9853d --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-querybuf.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_QUERYBUF: + +****************** +ioctl DMX_QUERYBUF +****************** + +Name +==== + +DMX_QUERYBUF - Query the status of a buffer + +.. warning:: this API is still experimental + +Synopsis +======== + +.. c:macro:: DMX_QUERYBUF + +``int ioctl(int fd, DMX_QUERYBUF, struct dvb_buffer *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`dvb_buffer`. + +Description +=========== + +This ioctl is part of the mmap streaming I/O method. It can +be used to query the status of a buffer at any time after buffers have +been allocated with the :ref:`DMX_REQBUFS` ioctl. + +Applications set the ``index`` field. Valid index numbers range from zero +to the number of buffers allocated with :ref:`DMX_REQBUFS` +(struct :c:type:`dvb_requestbuffers` ``count``) minus one. + +After calling :ref:`DMX_QUERYBUF` with a pointer to this structure, +drivers return an error code or fill the rest of the structure. + +On success, the ``offset`` will contain the offset of the buffer from the +start of the device memory, the ``length`` field its size, and the +``bytesused`` the number of bytes occupied by data in the buffer (payload). + +Return Value +============ + +On success 0 is returned, the ``offset`` will contain the offset of the +buffer from the start of the device memory, the ``length`` field its size, +and the ``bytesused`` the number of bytes occupied by data in the buffer +(payload). + +On error it returns -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EINVAL + The ``index`` is out of bounds. diff --git a/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst b/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst new file mode 100644 index 000000000..f75b33e5e --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-remove-pid.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_REMOVE_PID: + +============== +DMX_REMOVE_PID +============== + +Name +---- + +DMX_REMOVE_PID + +Synopsis +-------- + +.. c:macro:: DMX_REMOVE_PID + +``int ioctl(fd, DMX_REMOVE_PID, __u16 *pid)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``pid`` + PID of the PES filter to be removed. + +Description +----------- + +This ioctl call allows to remove a PID when multiple PIDs are set on a +transport stream filter, e. g. a filter previously set up with output +equal to :c:type:`DMX_OUT_TSDEMUX_TAP `, created via either +:ref:`DMX_SET_PES_FILTER` or :ref:`DMX_ADD_PID`. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst b/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst new file mode 100644 index 000000000..d2bb1909e --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-reqbufs.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_REQBUFS: + +***************** +ioctl DMX_REQBUFS +***************** + +Name +==== + +DMX_REQBUFS - Initiate Memory Mapping and/or DMA buffer I/O + +.. warning:: this API is still experimental + +Synopsis +======== + +.. c:macro:: DMX_REQBUFS + +``int ioctl(int fd, DMX_REQBUFS, struct dmx_requestbuffers *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`dmx_requestbuffers`. + +Description +=========== + +This ioctl is used to initiate a memory mapped or DMABUF based demux I/O. + +Memory mapped buffers are located in device memory and must be allocated +with this ioctl before they can be mapped into the application's address +space. User buffers are allocated by applications themselves, and this +ioctl is merely used to switch the driver into user pointer I/O mode and +to setup some internal structures. Similarly, DMABUF buffers are +allocated by applications through a device driver, and this ioctl only +configures the driver into DMABUF I/O mode without performing any direct +allocation. + +To allocate device buffers applications initialize all fields of the +struct :c:type:`dmx_requestbuffers` structure. They set the ``count`` field +to the desired number of buffers, and ``size`` to the size of each +buffer. + +When the ioctl is called with a pointer to this structure, the driver will +attempt to allocate the requested number of buffers and it stores the actual +number allocated in the ``count`` field. The ``count`` can be smaller than the number requested, even zero, when the driver runs out of free memory. A larger +number is also possible when the driver requires more buffers to +function correctly. The actual allocated buffer size can is returned +at ``size``, and can be smaller than what's requested. + +When this I/O method is not supported, the ioctl returns an ``EOPNOTSUPP`` +error code. + +Applications can call :ref:`DMX_REQBUFS` again to change the number of +buffers, however this cannot succeed when any buffers are still mapped. +A ``count`` value of zero frees all buffers, after aborting or finishing +any DMA in progress. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EOPNOTSUPP + The the requested I/O method is not supported. diff --git a/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst b/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst new file mode 100644 index 000000000..13ce4092c --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-set-buffer-size.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_SET_BUFFER_SIZE: + +=================== +DMX_SET_BUFFER_SIZE +=================== + +Name +---- + +DMX_SET_BUFFER_SIZE + +Synopsis +-------- + +.. c:macro:: DMX_SET_BUFFER_SIZE + +``int ioctl(int fd, DMX_SET_BUFFER_SIZE, unsigned long size)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``size`` + Unsigned long size + +Description +----------- + +This ioctl call is used to set the size of the circular buffer used for +filtered data. The default size is two maximum sized sections, i.e. if +this function is not called a buffer size of ``2 * 4096`` bytes will be +used. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-set-filter.rst b/Documentation/userspace-api/media/dvb/dmx-set-filter.rst new file mode 100644 index 000000000..1b8c8071b --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-set-filter.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_SET_FILTER: + +============== +DMX_SET_FILTER +============== + +Name +---- + +DMX_SET_FILTER + +Synopsis +-------- + +.. c:macro:: DMX_SET_FILTER + +``int ioctl(int fd, DMX_SET_FILTER, struct dmx_sct_filter_params *params)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``params`` + + Pointer to structure containing filter parameters. + +Description +----------- + +This ioctl call sets up a filter according to the filter and mask +parameters provided. A timeout may be defined stating number of seconds +to wait for a section to be loaded. A value of 0 means that no timeout +should be applied. Finally there is a flag field where it is possible to +state whether a section should be CRC-checked, whether the filter should +be a "one-shot" filter, i.e. if the filtering operation should be +stopped after the first section is received, and whether the filtering +operation should be started immediately (without waiting for a +:ref:`DMX_START` ioctl call). If a filter was previously set-up, this +filter will be canceled, and the receive buffer will be flushed. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst b/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst new file mode 100644 index 000000000..5bb682e4a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-set-pes-filter.rst @@ -0,0 +1,64 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_SET_PES_FILTER: + +================== +DMX_SET_PES_FILTER +================== + +Name +---- + +DMX_SET_PES_FILTER + +Synopsis +-------- + +.. c:macro:: DMX_SET_PES_FILTER + +``int ioctl(int fd, DMX_SET_PES_FILTER, struct dmx_pes_filter_params *params)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +``params`` + Pointer to structure containing filter parameters. + +Description +----------- + +This ioctl call sets up a PES filter according to the parameters +provided. By a PES filter is meant a filter that is based just on the +packet identifier (PID), i.e. no PES header or payload filtering +capability is supported. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - .. row 1 + + - ``EBUSY`` + + - This error code indicates that there are conflicting requests. + There are active filters filtering data from another input source. + Make sure that these filters are stopped before starting this + filter. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-start.rst b/Documentation/userspace-api/media/dvb/dmx-start.rst new file mode 100644 index 000000000..aedccf952 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-start.rst @@ -0,0 +1,65 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_START: + +========= +DMX_START +========= + +Name +---- + +DMX_START + +Synopsis +-------- + +.. c:macro:: DMX_START + +``int ioctl(int fd, DMX_START)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +Description +----------- + +This ioctl call is used to start the actual filtering operation defined +via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER`. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. row 1 + + - ``EINVAL`` + + - Invalid argument, i.e. no filtering parameters provided via the + :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` ioctls. + + - .. row 2 + + - ``EBUSY`` + + - This error code indicates that there are conflicting requests. + There are active filters filtering data from another input source. + Make sure that these filters are stopped before starting this + filter. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx-stop.rst b/Documentation/userspace-api/media/dvb/dmx-stop.rst new file mode 100644 index 000000000..8661e6772 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx-stop.rst @@ -0,0 +1,44 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.dmx + +.. _DMX_STOP: + +======== +DMX_STOP +======== + +Name +---- + +DMX_STOP + +Synopsis +-------- + +.. c:macro:: DMX_STOP + +``int ioctl(int fd, DMX_STOP)`` + +Arguments +--------- + +``fd`` + File descriptor returned by :c:func:`open()`. + +Description +----------- + +This ioctl call is used to stop the actual filtering operation defined +via the ioctl calls :ref:`DMX_SET_FILTER` or :ref:`DMX_SET_PES_FILTER` and +started via the :ref:`DMX_START` command. + +Return Value +------------ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/dmx_fcalls.rst b/Documentation/userspace-api/media/dvb/dmx_fcalls.rst new file mode 100644 index 000000000..a14e7a61f --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx_fcalls.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dmx_fcalls: + +******************** +Demux Function Calls +******************** + +.. toctree:: + :maxdepth: 1 + + dmx-fopen + dmx-fclose + dmx-fread + dmx-fwrite + dmx-mmap + dmx-munmap + dmx-start + dmx-stop + dmx-set-filter + dmx-set-pes-filter + dmx-set-buffer-size + dmx-get-stc + dmx-get-pes-pids + dmx-add-pid + dmx-remove-pid + dmx-reqbufs + dmx-querybuf + dmx-expbuf + dmx-qbuf diff --git a/Documentation/userspace-api/media/dvb/dmx_types.rst b/Documentation/userspace-api/media/dvb/dmx_types.rst new file mode 100644 index 000000000..33458fbb8 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dmx_types.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dmx_types: + +**************** +Demux Data Types +**************** + +.. kernel-doc:: include/uapi/linux/dvb/dmx.h diff --git a/Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst b/Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst new file mode 100644 index 000000000..fbd0548f5 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dvb-fe-read-status.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dvb-fe-read-status: + +*************************************** +Querying frontend status and statistics +*************************************** + +Once :ref:`FE_SET_PROPERTY ` is called, the +frontend will run a kernel thread that will periodically check for the +tuner lock status and provide statistics about the quality of the +signal. + +The information about the frontend tuner locking status can be queried +using :ref:`FE_READ_STATUS`. + +Signal statistics are provided via +:ref:`FE_GET_PROPERTY`. + +.. note:: + + Most statistics require the demodulator to be fully locked + (e. g. with :c:type:`FE_HAS_LOCK ` bit set). See + :ref:`Frontend statistics indicators ` for + more details. diff --git a/Documentation/userspace-api/media/dvb/dvb-frontend-event.rst b/Documentation/userspace-api/media/dvb/dvb-frontend-event.rst new file mode 100644 index 000000000..0e2fd3a0a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dvb-frontend-event.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. c:type:: dvb_frontend_event + +*************** +frontend events +*************** + + +.. code-block:: c + + struct dvb_frontend_event { + fe_status_t status; + struct dvb_frontend_parameters parameters; + }; diff --git a/Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst b/Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst new file mode 100644 index 000000000..9dd2f5424 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dvb-frontend-parameters.rst @@ -0,0 +1,119 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. c:type:: dvb_frontend_parameters + +******************* +frontend parameters +******************* + +The kind of parameters passed to the frontend device for tuning depend +on the kind of hardware you are using. + +The struct ``dvb_frontend_parameters`` uses a union with specific +per-system parameters. However, as newer delivery systems required more +data, the structure size weren't enough to fit, and just extending its +size would break the existing applications. So, those parameters were +replaced by the usage of +:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY ` +ioctl's. The new API is flexible enough to add new parameters to +existing delivery systems, and to add newer delivery systems. + +So, newer applications should use +:ref:`FE_GET_PROPERTY/FE_SET_PROPERTY ` +instead, in order to be able to support the newer System Delivery like +DVB-S2, DVB-T2, DVB-C2, ISDB, etc. + +All kinds of parameters are combined as a union in the +``dvb_frontend_parameters`` structure: + + +.. code-block:: c + + struct dvb_frontend_parameters { + uint32_t frequency; /* (absolute) frequency in Hz for QAM/OFDM */ + /* intermediate frequency in kHz for QPSK */ + fe_spectral_inversion_t inversion; + union { + struct dvb_qpsk_parameters qpsk; + struct dvb_qam_parameters qam; + struct dvb_ofdm_parameters ofdm; + struct dvb_vsb_parameters vsb; + } u; + }; + +In the case of QPSK frontends the ``frequency`` field specifies the +intermediate frequency, i.e. the offset which is effectively added to +the local oscillator frequency (LOF) of the LNB. The intermediate +frequency has to be specified in units of kHz. For QAM and OFDM +frontends the ``frequency`` specifies the absolute frequency and is +given in Hz. + + +.. c:type:: dvb_qpsk_parameters + +QPSK parameters +=============== + +For satellite QPSK frontends you have to use the ``dvb_qpsk_parameters`` +structure: + + +.. code-block:: c + + struct dvb_qpsk_parameters { + uint32_t symbol_rate; /* symbol rate in Symbols per second */ + fe_code_rate_t fec_inner; /* forward error correction (see above) */ + }; + + +.. c:type:: dvb_qam_parameters + +QAM parameters +============== + +for cable QAM frontend you use the ``dvb_qam_parameters`` structure: + + +.. code-block:: c + + struct dvb_qam_parameters { + uint32_t symbol_rate; /* symbol rate in Symbols per second */ + fe_code_rate_t fec_inner; /* forward error correction (see above) */ + fe_modulation_t modulation; /* modulation type (see above) */ + }; + + +.. c:type:: dvb_vsb_parameters + +VSB parameters +============== + +ATSC frontends are supported by the ``dvb_vsb_parameters`` structure: + + +.. code-block:: c + + struct dvb_vsb_parameters { + fe_modulation_t modulation; /* modulation type (see above) */ + }; + + +.. c:type:: dvb_ofdm_parameters + +OFDM parameters +=============== + +DVB-T frontends are supported by the ``dvb_ofdm_parameters`` structure: + + +.. code-block:: c + + struct dvb_ofdm_parameters { + fe_bandwidth_t bandwidth; + fe_code_rate_t code_rate_HP; /* high priority stream code rate */ + fe_code_rate_t code_rate_LP; /* low priority stream code rate */ + fe_modulation_t constellation; /* modulation type (see above) */ + fe_transmit_mode_t transmission_mode; + fe_guard_interval_t guard_interval; + fe_hierarchy_t hierarchy_information; + }; diff --git a/Documentation/userspace-api/media/dvb/dvbapi.rst b/Documentation/userspace-api/media/dvb/dvbapi.rst new file mode 100644 index 000000000..1dda69343 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dvbapi.rst @@ -0,0 +1,118 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. include:: + +.. _dvbapi: + +######################## +Part II - Digital TV API +######################## + +.. note:: + + This API is also known as Linux **DVB API**. + + It it was originally written to support the European digital TV + standard (DVB), and later extended to support all digital TV standards. + + In order to avoid confusion, within this document, it was opted to refer to + it, and to associated hardware as **Digital TV**. + + The word **DVB** is reserved to be used for: + + - the Digital TV API version + (e. g. DVB API version 3 or DVB API version 5); + - digital TV data types (enums, structs, defines, etc); + - digital TV device nodes (``/dev/dvb/...``); + - the European DVB standard. + +**Version 5.10** + +.. only:: html + + .. class:: toc-title + + Table of Contents + +.. toctree:: + :maxdepth: 5 + :numbered: + + intro + frontend + demux + ca + net + legacy_dvb_apis + examples + headers + + +********************** +Revision and Copyright +********************** + +Authors: + +- J. K. Metzler, Ralph + + - Original author of the Digital TV API documentation. + +- O. C. Metzler, Marcus + + - Original author of the Digital TV API documentation. + +- Carvalho Chehab, Mauro + + - Ported document to Docbook XML, addition of DVBv5 API, documentation gaps fix. + +**Copyright** |copy| 2002-2003 : Convergence GmbH + +**Copyright** |copy| 2009-2017 : Mauro Carvalho Chehab + +**************** +Revision History +**************** + +:revision: 2.2.0 / 2017-09-01 (*mcc*) + +Most gaps between the uAPI document and the Kernel implementation +got fixed for the non-legacy API. + +:revision: 2.1.0 / 2015-05-29 (*mcc*) + +DocBook improvements and cleanups, in order to document the system calls +on a more standard way and provide more description about the current +Digital TV API. + +:revision: 2.0.4 / 2011-05-06 (*mcc*) + +Add more information about DVBv5 API, better describing the frontend +GET/SET props ioctl's. + + +:revision: 2.0.3 / 2010-07-03 (*mcc*) + +Add some frontend capabilities flags, present on kernel, but missing at +the specs. + + +:revision: 2.0.2 / 2009-10-25 (*mcc*) + +documents FE_SET_FRONTEND_TUNE_MODE and +FE_DISHETWORK_SEND_LEGACY_CMD ioctls. + + +:revision: 2.0.1 / 2009-09-16 (*mcc*) + +Added ISDB-T test originally written by Patrick Boettcher + + +:revision: 2.0.0 / 2009-09-06 (*mcc*) + +Conversion from LaTex to DocBook XML. The contents is the same as the +original LaTex version. + + +:revision: 1.0.0 / 2003-07-24 (*rjkm*) + +Initial revision on LaTEX. diff --git a/Documentation/userspace-api/media/dvb/dvbproperty.rst b/Documentation/userspace-api/media/dvb/dvbproperty.rst new file mode 100644 index 000000000..981da20af --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dvbproperty.rst @@ -0,0 +1,126 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _frontend-properties: + +************** +Property types +************** + +Tuning into a Digital TV physical channel and starting decoding it +requires changing a set of parameters, in order to control the tuner, +the demodulator, the Linear Low-noise Amplifier (LNA) and to set the +antenna subsystem via Satellite Equipment Control - SEC (on satellite +systems). The actual parameters are specific to each particular digital +TV standards, and may change as the digital TV specs evolves. + +In the past (up to DVB API version 3 - DVBv3), the strategy used was to have a +union with the parameters needed to tune for DVB-S, DVB-C, DVB-T and +ATSC delivery systems grouped there. The problem is that, as the second +generation standards appeared, the size of such union was not big +enough to group the structs that would be required for those new +standards. Also, extending it would break userspace. + +So, the legacy union/struct based approach was deprecated, in favor +of a properties set approach. On such approach, +:ref:`FE_GET_PROPERTY and FE_SET_PROPERTY ` are used +to setup the frontend and read its status. + +The actual action is determined by a set of dtv_property cmd/data pairs. +With one single ioctl, is possible to get/set up to 64 properties. + +This section describes the new and recommended way to set the frontend, +with supports all digital TV delivery systems. + +.. note:: + + 1. On Linux DVB API version 3, setting a frontend was done via + struct :c:type:`dvb_frontend_parameters`. + + 2. Don't use DVB API version 3 calls on hardware with supports + newer standards. Such API provides no support or a very limited + support to new standards and/or new hardware. + + 3. Nowadays, most frontends support multiple delivery systems. + Only with DVB API version 5 calls it is possible to switch between + the multiple delivery systems supported by a frontend. + + 4. DVB API version 5 is also called *S2API*, as the first + new standard added to it was DVB-S2. + +**Example**: in order to set the hardware to tune into a DVB-C channel +at 651 kHz, modulated with 256-QAM, FEC 3/4 and symbol rate of 5.217 +Mbauds, those properties should be sent to +:ref:`FE_SET_PROPERTY ` ioctl: + + :ref:`DTV_DELIVERY_SYSTEM ` = SYS_DVBC_ANNEX_A + + :ref:`DTV_FREQUENCY ` = 651000000 + + :ref:`DTV_MODULATION ` = QAM_256 + + :ref:`DTV_INVERSION ` = INVERSION_AUTO + + :ref:`DTV_SYMBOL_RATE ` = 5217000 + + :ref:`DTV_INNER_FEC ` = FEC_3_4 + + :ref:`DTV_TUNE ` + +The code that would that would do the above is show in +:ref:`dtv-prop-example`. + +.. code-block:: c + :caption: Example: Setting digital TV frontend properties + :name: dtv-prop-example + + #include + #include + #include + #include + + static struct dtv_property props[] = { + { .cmd = DTV_DELIVERY_SYSTEM, .u.data = SYS_DVBC_ANNEX_A }, + { .cmd = DTV_FREQUENCY, .u.data = 651000000 }, + { .cmd = DTV_MODULATION, .u.data = QAM_256 }, + { .cmd = DTV_INVERSION, .u.data = INVERSION_AUTO }, + { .cmd = DTV_SYMBOL_RATE, .u.data = 5217000 }, + { .cmd = DTV_INNER_FEC, .u.data = FEC_3_4 }, + { .cmd = DTV_TUNE } + }; + + static struct dtv_properties dtv_prop = { + .num = 6, .props = props + }; + + int main(void) + { + int fd = open("/dev/dvb/adapter0/frontend0", O_RDWR); + + if (!fd) { + perror ("open"); + return -1; + } + if (ioctl(fd, FE_SET_PROPERTY, &dtv_prop) == -1) { + perror("ioctl"); + return -1; + } + printf("Frontend set\\n"); + return 0; + } + +.. attention:: While it is possible to directly call the Kernel code like the + above example, it is strongly recommended to use + `libdvbv5 `__, as it + provides abstraction to work with the supported digital TV standards and + provides methods for usual operations like program scanning and to + read/write channel descriptor files. + +.. toctree:: + :maxdepth: 1 + + fe_property_parameters + frontend-stat-properties + frontend-property-terrestrial-systems + frontend-property-cable-systems + frontend-property-satellite-systems + frontend-header diff --git a/Documentation/userspace-api/media/dvb/dvbstb.svg b/Documentation/userspace-api/media/dvb/dvbstb.svg new file mode 100644 index 000000000..6f0ba98f9 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/dvbstb.svg @@ -0,0 +1,17 @@ + + +image/svg+xmlAntenna +Frontend +CA +Demux +SEC +Audio +Video +TV +Decoder +Decoder + diff --git a/Documentation/userspace-api/media/dvb/examples.rst b/Documentation/userspace-api/media/dvb/examples.rst new file mode 100644 index 000000000..086587c65 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/examples.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dvb_examples: + +******** +Examples +******** + +In the past, we used to have a set of examples here. However, those +examples got out of date and doesn't even compile nowadays. + +Also, nowadays, the best is to use the libdvbv5 DVB API nowadays, +with is fully documented. + +Please refer to the `libdvbv5 `__ +for updated/recommended examples. diff --git a/Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst b/Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst new file mode 100644 index 000000000..904b0c33a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-bandwidth-t.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +****************** +Frontend bandwidth +****************** + +.. c:type:: fe_bandwidth + +.. flat-table:: enum fe_bandwidth + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ID + + - Description + + - .. row 2 + + - .. _BANDWIDTH-AUTO: + + ``BANDWIDTH_AUTO`` + + - Autodetect bandwidth (if supported) + + - .. row 3 + + - .. _BANDWIDTH-1-712-MHZ: + + ``BANDWIDTH_1_712_MHZ`` + + - 1.712 MHz + + - .. row 4 + + - .. _BANDWIDTH-5-MHZ: + + ``BANDWIDTH_5_MHZ`` + + - 5 MHz + + - .. row 5 + + - .. _BANDWIDTH-6-MHZ: + + ``BANDWIDTH_6_MHZ`` + + - 6 MHz + + - .. row 6 + + - .. _BANDWIDTH-7-MHZ: + + ``BANDWIDTH_7_MHZ`` + + - 7 MHz + + - .. row 7 + + - .. _BANDWIDTH-8-MHZ: + + ``BANDWIDTH_8_MHZ`` + + - 8 MHz + + - .. row 8 + + - .. _BANDWIDTH-10-MHZ: + + ``BANDWIDTH_10_MHZ`` + + - 10 MHz diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst new file mode 100644 index 000000000..d9be817f0 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-recv-slave-reply.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_DISEQC_RECV_SLAVE_REPLY: + +******************************** +ioctl FE_DISEQC_RECV_SLAVE_REPLY +******************************** + +Name +==== + +FE_DISEQC_RECV_SLAVE_REPLY - Receives reply from a DiSEqC 2.0 command + +Synopsis +======== + +.. c:macro:: FE_DISEQC_RECV_SLAVE_REPLY + +``int ioctl(int fd, FE_DISEQC_RECV_SLAVE_REPLY, struct dvb_diseqc_slave_reply *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + pointer to struct :c:type:`dvb_diseqc_slave_reply`. + +Description +=========== + +Receives reply from a DiSEqC 2.0 command. + +The received message is stored at the buffer pointed by ``argp``. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst new file mode 100644 index 000000000..d36f7d115 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-reset-overload.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_DISEQC_RESET_OVERLOAD: + +****************************** +ioctl FE_DISEQC_RESET_OVERLOAD +****************************** + +Name +==== + +FE_DISEQC_RESET_OVERLOAD - Restores the power to the antenna subsystem, if it was powered off due - to power overload. + +Synopsis +======== + +.. c:macro:: FE_DISEQC_RESET_OVERLOAD + +``int ioctl(int fd, FE_DISEQC_RESET_OVERLOAD, NULL)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +Description +=========== + +If the bus has been automatically powered off due to power overload, +this ioctl call restores the power to the bus. The call requires +read/write access to the device. This call has no effect if the device +is manually powered off. Not all Digital TV adapters support this ioctl. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst new file mode 100644 index 000000000..8fb73ee29 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-send-burst.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_DISEQC_SEND_BURST: + +************************** +ioctl FE_DISEQC_SEND_BURST +************************** + +Name +==== + +FE_DISEQC_SEND_BURST - Sends a 22KHz tone burst for 2x1 mini DiSEqC satellite selection. + +Synopsis +======== + +.. c:macro:: FE_DISEQC_SEND_BURST + +``int ioctl(int fd, FE_DISEQC_SEND_BURST, enum fe_sec_mini_cmd tone)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``tone`` + An integer enumered value described at :c:type:`fe_sec_mini_cmd`. + +Description +=========== + +This ioctl is used to set the generation of a 22kHz tone burst for mini +DiSEqC satellite selection for 2x1 switches. This call requires +read/write permissions. + +It provides support for what's specified at +`Digital Satellite Equipment Control (DiSEqC) - Simple "ToneBurst" Detection Circuit specification. `__ + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst b/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst new file mode 100644 index 000000000..c97029def --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-diseqc-send-master-cmd.rst @@ -0,0 +1,48 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_DISEQC_SEND_MASTER_CMD: + +******************************* +ioctl FE_DISEQC_SEND_MASTER_CMD +******************************* + +Name +==== + +FE_DISEQC_SEND_MASTER_CMD - Sends a DiSEqC command + +Synopsis +======== + +.. c:macro:: FE_DISEQC_SEND_MASTER_CMD + +``int ioctl(int fd, FE_DISEQC_SEND_MASTER_CMD, struct dvb_diseqc_master_cmd *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + pointer to struct + :c:type:`dvb_diseqc_master_cmd` + +Description +=========== + +Sends the DiSEqC command pointed by :c:type:`dvb_diseqc_master_cmd` +to the antenna subsystem. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + diff --git a/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst b/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst new file mode 100644 index 000000000..d1dba74c5 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-dishnetwork-send-legacy-cmd.rst @@ -0,0 +1,53 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_DISHNETWORK_SEND_LEGACY_CMD: + +****************************** +FE_DISHNETWORK_SEND_LEGACY_CMD +****************************** + +Name +==== + +FE_DISHNETWORK_SEND_LEGACY_CMD + +Synopsis +======== + +.. c:macro:: FE_DISHNETWORK_SEND_LEGACY_CMD + +``int ioctl(int fd, FE_DISHNETWORK_SEND_LEGACY_CMD, unsigned long cmd)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``cmd`` + Sends the specified raw cmd to the dish via DISEqC. + +Description +=========== + +.. warning:: + This is a very obscure legacy command, used only at stv0299 + driver. Should not be used on newer drivers. + +It provides a non-standard method for selecting Diseqc voltage on the +frontend, for Dish Network legacy switches. + +As support for this ioctl were added in 2004, this means that such +dishes were already legacy in 2004. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst b/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst new file mode 100644 index 000000000..40d7320f8 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-enable-high-lnb-voltage.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_ENABLE_HIGH_LNB_VOLTAGE: + +******************************** +ioctl FE_ENABLE_HIGH_LNB_VOLTAGE +******************************** + +Name +==== + +FE_ENABLE_HIGH_LNB_VOLTAGE - Select output DC level between normal LNBf voltages or higher LNBf - voltages. + +Synopsis +======== + +.. c:macro:: FE_ENABLE_HIGH_LNB_VOLTAGE + +``int ioctl(int fd, FE_ENABLE_HIGH_LNB_VOLTAGE, unsigned int high)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``high`` + Valid flags: + + - 0 - normal 13V and 18V. + + - >0 - enables slightly higher voltages instead of 13/18V, in order + to compensate for long antenna cables. + +Description +=========== + +Select output DC level between normal LNBf voltages or higher LNBf +voltages between 0 (normal) or a value grater than 0 for higher +voltages. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-get-event.rst b/Documentation/userspace-api/media/dvb/fe-get-event.rst new file mode 100644 index 000000000..f63029eca --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-get-event.rst @@ -0,0 +1,67 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_GET_EVENT: + +************ +FE_GET_EVENT +************ + +Name +==== + +FE_GET_EVENT + +.. attention:: This ioctl is deprecated. + +Synopsis +======== + +.. c:macro:: FE_GET_EVENT + +``int ioctl(int fd, FE_GET_EVENT, struct dvb_frontend_event *ev)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``ev`` + Points to the location where the event, if any, is to be stored. + +Description +=========== + +This ioctl call returns a frontend event if available. If an event is +not available, the behavior depends on whether the device is in blocking +or non-blocking mode. In the latter case, the call fails immediately +with errno set to ``EWOULDBLOCK``. In the former case, the call blocks until +an event becomes available. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. row 1 + + - ``EWOULDBLOCK`` + + - There is no event pending, and the device is in non-blocking mode. + + - .. row 2 + + - ``EOVERFLOW`` + + - Overflow in event queue - one or more events were lost. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-get-frontend.rst b/Documentation/userspace-api/media/dvb/fe-get-frontend.rst new file mode 100644 index 000000000..40700533e --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-get-frontend.rst @@ -0,0 +1,58 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_GET_FRONTEND: + +*************** +FE_GET_FRONTEND +*************** + +Name +==== + +FE_GET_FRONTEND + +.. attention:: This ioctl is deprecated. + +Synopsis +======== + +.. c:macro:: FE_GET_FRONTEND + +``int ioctl(int fd, FE_GET_FRONTEND, struct dvb_frontend_parameters *p)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``p`` + Points to parameters for tuning operation. + +Description +=========== + +This ioctl call queries the currently effective frontend parameters. For +this command, read-only access to the device is sufficient. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. row 1 + + - ``EINVAL`` + + - Maximum supported symbol rate reached. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-get-info.rst b/Documentation/userspace-api/media/dvb/fe-get-info.rst new file mode 100644 index 000000000..2e5f02098 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-get-info.rst @@ -0,0 +1,59 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_GET_INFO: + +***************** +ioctl FE_GET_INFO +***************** + +Name +==== + +FE_GET_INFO - Query Digital TV frontend capabilities and returns information +about the - front-end. This call only requires read-only access to the device. + +Synopsis +======== + +.. c:macro:: FE_GET_INFO + +``int ioctl(int fd, FE_GET_INFO, struct dvb_frontend_info *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + pointer to struct :c:type:`dvb_frontend_info` + +Description +=========== + +All Digital TV frontend devices support the :ref:`FE_GET_INFO` ioctl. It is +used to identify kernel devices compatible with this specification and to +obtain information about driver and hardware capabilities. The ioctl +takes a pointer to dvb_frontend_info which is filled by the driver. +When the driver is not compatible with this specification the ioctl +returns an error. + +frontend capabilities +===================== + +Capabilities describe what a frontend can do. Some capabilities are +supported only on some specific frontend types. + +The frontend capabilities are described at :c:type:`fe_caps`. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-get-property.rst b/Documentation/userspace-api/media/dvb/fe-get-property.rst new file mode 100644 index 000000000..29363dc4a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-get-property.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_GET_PROPERTY: + +************************************** +ioctl FE_SET_PROPERTY, FE_GET_PROPERTY +************************************** + +Name +==== + +FE_SET_PROPERTY - FE_GET_PROPERTY - FE_SET_PROPERTY sets one or more frontend properties. - FE_GET_PROPERTY returns one or more frontend properties. + +Synopsis +======== + +.. c:macro:: FE_GET_PROPERTY + +``int ioctl(int fd, FE_GET_PROPERTY, struct dtv_properties *argp)`` + +.. c:macro:: FE_SET_PROPERTY + +``int ioctl(int fd, FE_SET_PROPERTY, struct dtv_properties *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`dtv_properties`. + +Description +=========== + +All Digital TV frontend devices support the ``FE_SET_PROPERTY`` and +``FE_GET_PROPERTY`` ioctls. The supported properties and statistics +depends on the delivery system and on the device: + +- ``FE_SET_PROPERTY:`` + + - This ioctl is used to set one or more frontend properties. + + - This is the basic command to request the frontend to tune into + some frequency and to start decoding the digital TV signal. + + - This call requires read/write access to the device. + +.. note:: + + At return, the values aren't updated to reflect the actual + parameters used. If the actual parameters are needed, an explicit + call to ``FE_GET_PROPERTY`` is needed. + +- ``FE_GET_PROPERTY:`` + + - This ioctl is used to get properties and statistics from the + frontend. + + - No properties are changed, and statistics aren't reset. + + - This call only requires read-only access to the device. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-read-ber.rst b/Documentation/userspace-api/media/dvb/fe-read-ber.rst new file mode 100644 index 000000000..f33f1dd20 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-read-ber.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_READ_BER: + +*********** +FE_READ_BER +*********** + +Name +==== + +FE_READ_BER + +.. attention:: This ioctl is deprecated. + +Synopsis +======== + +.. c:macro:: FE_READ_BER + +``int ioctl(int fd, FE_READ_BER, uint32_t *ber)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``ber`` + The bit error rate is stored into \*ber. + +Description +=========== + +This ioctl call returns the bit error rate for the signal currently +received/demodulated by the front-end. For this command, read-only +access to the device is sufficient. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst b/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst new file mode 100644 index 000000000..2b7d06145 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-read-signal-strength.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_READ_SIGNAL_STRENGTH: + +*********************** +FE_READ_SIGNAL_STRENGTH +*********************** + +Name +==== + +FE_READ_SIGNAL_STRENGTH + +.. attention:: This ioctl is deprecated. + +Synopsis +======== + +.. c:macro:: FE_READ_SIGNAL_STRENGTH + +``int ioctl(int fd, FE_READ_SIGNAL_STRENGTH, uint16_t *strength)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``strength`` + The signal strength value is stored into \*strength. + +Description +=========== + +This ioctl call returns the signal strength value for the signal +currently received by the front-end. For this command, read-only access +to the device is sufficient. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-read-snr.rst b/Documentation/userspace-api/media/dvb/fe-read-snr.rst new file mode 100644 index 000000000..e44e559ab --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-read-snr.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_READ_SNR: + +*********** +FE_READ_SNR +*********** + +Name +==== + +FE_READ_SNR + +.. attention:: This ioctl is deprecated. + +Synopsis +======== + +.. c:macro:: FE_READ_SNR + +``int ioctl(int fd, FE_READ_SNR, int16_t *snr)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``snr`` + The signal-to-noise ratio is stored into \*snr. + +Description +=========== + +This ioctl call returns the signal-to-noise ratio for the signal +currently received by the front-end. For this command, read-only access +to the device is sufficient. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-read-status.rst b/Documentation/userspace-api/media/dvb/fe-read-status.rst new file mode 100644 index 000000000..75c6ee60a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-read-status.rst @@ -0,0 +1,62 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_READ_STATUS: + +******************** +ioctl FE_READ_STATUS +******************** + +Name +==== + +FE_READ_STATUS - Returns status information about the front-end. This call only requires - read-only access to the device + +Synopsis +======== + +.. c:macro:: FE_READ_STATUS + +``int ioctl(int fd, FE_READ_STATUS, unsigned int *status)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``status`` + pointer to a bitmask integer filled with the values defined by enum + :c:type:`fe_status`. + +Description +=========== + +All Digital TV frontend devices support the ``FE_READ_STATUS`` ioctl. It is +used to check about the locking status of the frontend after being +tuned. The ioctl takes a pointer to an integer where the status will be +written. + +.. note:: + + The size of status is actually sizeof(enum fe_status), with + varies according with the architecture. This needs to be fixed in the + future. + +int fe_status +============= + +The fe_status parameter is used to indicate the current state and/or +state changes of the frontend hardware. It is produced using the enum +:c:type:`fe_status` values on a bitmask + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst b/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst new file mode 100644 index 000000000..653cd99a6 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-read-uncorrected-blocks.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_READ_UNCORRECTED_BLOCKS: + +************************** +FE_READ_UNCORRECTED_BLOCKS +************************** + +Name +==== + +FE_READ_UNCORRECTED_BLOCKS + +.. attention:: This ioctl is deprecated. + +Synopsis +======== + +.. c:macro:: FE_READ_UNCORRECTED_BLOCKS + +``int ioctl(int fd, FE_READ_UNCORRECTED_BLOCKS, uint32_t *ublocks)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``ublocks`` + The total number of uncorrected blocks seen by the driver so far. + +Description +=========== + +This ioctl call returns the number of uncorrected blocks detected by the +device driver during its lifetime. For meaningful measurements, the +increment in block count during a specific time interval should be +calculated. For this command, read-only access to the device is +sufficient. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst b/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst new file mode 100644 index 000000000..56923c1a6 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-set-frontend-tune-mode.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_SET_FRONTEND_TUNE_MODE: + +******************************* +ioctl FE_SET_FRONTEND_TUNE_MODE +******************************* + +Name +==== + +FE_SET_FRONTEND_TUNE_MODE - Allow setting tuner mode flags to the frontend. + +Synopsis +======== + +.. c:macro:: FE_SET_FRONTEND_TUNE_MODE + +``int ioctl(int fd, FE_SET_FRONTEND_TUNE_MODE, unsigned int flags)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``flags`` + Valid flags: + + - 0 - normal tune mode + + - ``FE_TUNE_MODE_ONESHOT`` - When set, this flag will disable any + zigzagging or other "normal" tuning behaviour. Additionally, + there will be no automatic monitoring of the lock status, and + hence no frontend events will be generated. If a frontend device + is closed, this flag will be automatically turned off when the + device is reopened read-write. + +Description +=========== + +Allow setting tuner mode flags to the frontend, between 0 (normal) or +``FE_TUNE_MODE_ONESHOT`` mode + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-set-frontend.rst b/Documentation/userspace-api/media/dvb/fe-set-frontend.rst new file mode 100644 index 000000000..d1b857632 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-set-frontend.rst @@ -0,0 +1,68 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_SET_FRONTEND: + +*************** +FE_SET_FRONTEND +*************** + +.. attention:: This ioctl is deprecated. + +Name +==== + +FE_SET_FRONTEND + +Synopsis +======== + +.. c:macro:: FE_SET_FRONTEND + +``int ioctl(int fd, FE_SET_FRONTEND, struct dvb_frontend_parameters *p)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``p`` + Points to parameters for tuning operation. + +Description +=========== + +This ioctl call starts a tuning operation using specified parameters. +The result of this call will be successful if the parameters were valid +and the tuning could be initiated. The result of the tuning operation in +itself, however, will arrive asynchronously as an event (see +documentation for :ref:`FE_GET_EVENT` and +FrontendEvent.) If a new :ref:`FE_SET_FRONTEND` +operation is initiated before the previous one was completed, the +previous operation will be aborted in favor of the new one. This command +requires read/write access to the device. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - .. row 1 + + - ``EINVAL`` + + - Maximum supported symbol rate reached. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-set-tone.rst b/Documentation/userspace-api/media/dvb/fe-set-tone.rst new file mode 100644 index 000000000..9f44bf946 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-set-tone.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_SET_TONE: + +***************** +ioctl FE_SET_TONE +***************** + +Name +==== + +FE_SET_TONE - Sets/resets the generation of the continuous 22kHz tone. + +Synopsis +======== + +.. c:macro:: FE_SET_TONE + +``int ioctl(int fd, FE_SET_TONE, enum fe_sec_tone_mode tone)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``tone`` + an integer enumered value described at :c:type:`fe_sec_tone_mode` + +Description +=========== + +This ioctl is used to set the generation of the continuous 22kHz tone. +This call requires read/write permissions. + +Usually, satellite antenna subsystems require that the digital TV device +to send a 22kHz tone in order to select between high/low band on some +dual-band LNBf. It is also used to send signals to DiSEqC equipment, but +this is done using the DiSEqC ioctls. + +.. attention:: If more than one device is connected to the same antenna, + setting a tone may interfere on other devices, as they may lose the + capability of selecting the band. So, it is recommended that applications + would change to SEC_TONE_OFF when the device is not used. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-set-voltage.rst b/Documentation/userspace-api/media/dvb/fe-set-voltage.rst new file mode 100644 index 000000000..c66771830 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-set-voltage.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _FE_SET_VOLTAGE: + +******************** +ioctl FE_SET_VOLTAGE +******************** + +Name +==== + +FE_SET_VOLTAGE - Allow setting the DC level sent to the antenna subsystem. + +Synopsis +======== + +.. c:macro:: FE_SET_VOLTAGE + +``int ioctl(int fd, FE_SET_VOLTAGE, enum fe_sec_voltage voltage)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``voltage`` + an integer enumered value described at :c:type:`fe_sec_voltage` + +Description +=========== + +This ioctl allows to set the DC voltage level sent through the antenna +cable to 13V, 18V or off. + +Usually, a satellite antenna subsystems require that the digital TV +device to send a DC voltage to feed power to the LNBf. Depending on the +LNBf type, the polarization or the intermediate frequency (IF) of the +LNBf can controlled by the voltage level. Other devices (for example, +the ones that implement DISEqC and multipoint LNBf's don't need to +control the voltage level, provided that either 13V or 18V is sent to +power up the LNBf. + +.. attention:: if more than one device is connected to the same antenna, + setting a voltage level may interfere on other devices, as they may lose + the capability of setting polarization or IF. So, on those cases, setting + the voltage to SEC_VOLTAGE_OFF while the device is not is used is + recommended. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/fe-type-t.rst b/Documentation/userspace-api/media/dvb/fe-type-t.rst new file mode 100644 index 000000000..e89862548 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe-type-t.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +************* +Frontend type +************* + +For historical reasons, frontend types are named by the type of +modulation used in transmission. The fontend types are given by +fe_type_t type, defined as: + + +.. c:type:: fe_type + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}| + +.. flat-table:: Frontend types + :header-rows: 1 + :stub-columns: 0 + :widths: 3 1 4 + + + - .. row 1 + + - fe_type + + - Description + + - :ref:`DTV_DELIVERY_SYSTEM ` equivalent + type + + - .. row 2 + + - .. _FE-QPSK: + + ``FE_QPSK`` + + - For DVB-S standard + + - ``SYS_DVBS`` + + - .. row 3 + + - .. _FE-QAM: + + ``FE_QAM`` + + - For DVB-C annex A standard + + - ``SYS_DVBC_ANNEX_A`` + + - .. row 4 + + - .. _FE-OFDM: + + ``FE_OFDM`` + + - For DVB-T standard + + - ``SYS_DVBT`` + + - .. row 5 + + - .. _FE-ATSC: + + ``FE_ATSC`` + + - For ATSC standard (terrestrial) or for DVB-C Annex B (cable) used + in US. + + - ``SYS_ATSC`` (terrestrial) or ``SYS_DVBC_ANNEX_B`` (cable) + + +Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described +at the above, as they're supported via the new +:ref:`FE_GET_PROPERTY/FE_GET_SET_PROPERTY ` +ioctl's, using the :ref:`DTV_DELIVERY_SYSTEM ` +parameter. + +In the old days, struct :c:type:`dvb_frontend_info` +used to contain ``fe_type_t`` field to indicate the delivery systems, +filled with either ``FE_QPSK, FE_QAM, FE_OFDM`` or ``FE_ATSC``. While this +is still filled to keep backward compatibility, the usage of this field +is deprecated, as it can report just one delivery system, but some +devices support multiple delivery systems. Please use +:ref:`DTV_ENUM_DELSYS ` instead. + +On devices that support multiple delivery systems, struct +:c:type:`dvb_frontend_info`::``fe_type_t`` is +filled with the currently standard, as selected by the last call to +:ref:`FE_SET_PROPERTY ` using the +:ref:`DTV_DELIVERY_SYSTEM ` property. diff --git a/Documentation/userspace-api/media/dvb/fe_property_parameters.rst b/Documentation/userspace-api/media/dvb/fe_property_parameters.rst new file mode 100644 index 000000000..ecd84a879 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/fe_property_parameters.rst @@ -0,0 +1,1007 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _fe_property_parameters: + +****************************** +Digital TV property parameters +****************************** + +There are several different Digital TV parameters that can be used by +:ref:`FE_SET_PROPERTY and FE_GET_PROPERTY ioctls`. +This section describes each of them. Please notice, however, that only +a subset of them are needed to setup a frontend. + + +.. _DTV-UNDEFINED: + +DTV_UNDEFINED +============= + +Used internally. A GET/SET operation for it won't change or return +anything. + + +.. _DTV-TUNE: + +DTV_TUNE +======== + +Interpret the cache of data, build either a traditional frontend +tunerequest so we can pass validation in the ``FE_SET_FRONTEND`` ioctl. + + +.. _DTV-CLEAR: + +DTV_CLEAR +========= + +Reset a cache of data specific to the frontend here. This does not +effect hardware. + + +.. _DTV-FREQUENCY: + +DTV_FREQUENCY +============= + +Frequency of the digital TV transponder/channel. + +.. note:: + + #. For satellite delivery systems, the frequency is in kHz. + + #. For cable and terrestrial delivery systems, the frequency is in + Hz. + + #. On most delivery systems, the frequency is the center frequency + of the transponder/channel. The exception is for ISDB-T, where + the main carrier has a 1/7 offset from the center. + + #. For ISDB-T, the channels are usually transmitted with an offset of + about 143kHz. E.g. a valid frequency could be 474,143 kHz. The + stepping is bound to the bandwidth of the channel which is + typically 6MHz. + + #. In ISDB-Tsb, the channel consists of only one or three segments the + frequency step is 429kHz, 3*429 respectively. + + +.. _DTV-MODULATION: + +DTV_MODULATION +============== + +Specifies the frontend modulation type for delivery systems that +supports more multiple modulations. + +The modulation can be one of the types defined by enum :c:type:`fe_modulation`. + +Most of the digital TV standards offers more than one possible +modulation type. + +The table below presents a summary of the types of modulation types +supported by each delivery system, as currently defined by specs. + +======================= ======================================================= +Standard Modulation types +======================= ======================================================= +ATSC (version 1) 8-VSB and 16-VSB. +DMTB 4-QAM, 16-QAM, 32-QAM, 64-QAM and 4-QAM-NR. +DVB-C Annex A/C 16-QAM, 32-QAM, 64-QAM and 256-QAM. +DVB-C Annex B 64-QAM. +DVB-T QPSK, 16-QAM and 64-QAM. +DVB-T2 QPSK, 16-QAM, 64-QAM and 256-QAM. +DVB-S No need to set. It supports only QPSK. +DVB-S2 QPSK, 8-PSK, 16-APSK and 32-APSK. +ISDB-T QPSK, DQPSK, 16-QAM and 64-QAM. +ISDB-S 8-PSK, QPSK and BPSK. +======================= ======================================================= + +.. note:: + + Please notice that some of the above modulation types may not be + defined currently at the Kernel. The reason is simple: no driver + needed such definition yet. + + +.. _DTV-BANDWIDTH-HZ: + +DTV_BANDWIDTH_HZ +================ + +Bandwidth for the channel, in HZ. + +Should be set only for terrestrial delivery systems. + +Possible values: ``1712000``, ``5000000``, ``6000000``, ``7000000``, +``8000000``, ``10000000``. + +======================= ======================================================= +Terrestrial Standard Possible values for bandwidth +======================= ======================================================= +ATSC (version 1) No need to set. It is always 6MHz. +DMTB No need to set. It is always 8MHz. +DVB-T 6MHz, 7MHz and 8MHz. +DVB-T2 1.172 MHz, 5MHz, 6MHz, 7MHz, 8MHz and 10MHz +ISDB-T 5MHz, 6MHz, 7MHz and 8MHz, although most places + use 6MHz. +======================= ======================================================= + + +.. note:: + + + #. For ISDB-Tsb, the bandwidth can vary depending on the number of + connected segments. + + It can be easily derived from other parameters + (DTV_ISDBT_SB_SEGMENT_IDX, DTV_ISDBT_SB_SEGMENT_COUNT). + + #. On Satellite and Cable delivery systems, the bandwidth depends on + the symbol rate. So, the Kernel will silently ignore any setting + :ref:`DTV-BANDWIDTH-HZ`. I will however fill it back with a + bandwidth estimation. + + Such bandwidth estimation takes into account the symbol rate set with + :ref:`DTV-SYMBOL-RATE`, and the rolloff factor, with is fixed for + DVB-C and DVB-S. + + For DVB-S2, the rolloff should also be set via :ref:`DTV-ROLLOFF`. + + +.. _DTV-INVERSION: + +DTV_INVERSION +============= + +Specifies if the frontend should do spectral inversion or not. + +The acceptable values are defined by :c:type:`fe_spectral_inversion`. + + +.. _DTV-DISEQC-MASTER: + +DTV_DISEQC_MASTER +================= + +Currently not implemented. + + +.. _DTV-SYMBOL-RATE: + +DTV_SYMBOL_RATE +=============== + +Used on cable and satellite delivery systems. + +Digital TV symbol rate, in bauds (symbols/second). + + +.. _DTV-INNER-FEC: + +DTV_INNER_FEC +============= + +Used on cable and satellite delivery systems. + +The acceptable values are defined by :c:type:`fe_code_rate`. + + +.. _DTV-VOLTAGE: + +DTV_VOLTAGE +=========== + +Used on satellite delivery systems. + +The voltage is usually used with non-DiSEqC capable LNBs to switch the +polarzation (horizontal/vertical). When using DiSEqC epuipment this +voltage has to be switched consistently to the DiSEqC commands as +described in the DiSEqC spec. + +The acceptable values are defined by :c:type:`fe_sec_voltage`. + + +.. _DTV-TONE: + +DTV_TONE +======== + +Currently not used. + + +.. _DTV-PILOT: + +DTV_PILOT +========= + +Used on DVB-S2. + +Sets DVB-S2 pilot. + +The acceptable values are defined by :c:type:`fe_pilot`. + + +.. _DTV-ROLLOFF: + +DTV_ROLLOFF +=========== + +Used on DVB-S2. + +Sets DVB-S2 rolloff. + +The acceptable values are defined by :c:type:`fe_rolloff`. + + +.. _DTV-DISEQC-SLAVE-REPLY: + +DTV_DISEQC_SLAVE_REPLY +====================== + +Currently not implemented. + + +.. _DTV-FE-CAPABILITY-COUNT: + +DTV_FE_CAPABILITY_COUNT +======================= + +Currently not implemented. + + +.. _DTV-FE-CAPABILITY: + +DTV_FE_CAPABILITY +================= + +Currently not implemented. + + +.. _DTV-DELIVERY-SYSTEM: + +DTV_DELIVERY_SYSTEM +=================== + +Specifies the type of the delivery system. + +The acceptable values are defined by :c:type:`fe_delivery_system`. + + +.. _DTV-ISDBT-PARTIAL-RECEPTION: + +DTV_ISDBT_PARTIAL_RECEPTION +=========================== + +Used only on ISDB. + +If ``DTV_ISDBT_SOUND_BROADCASTING`` is '0' this bit-field represents +whether the channel is in partial reception mode or not. + +If '1' ``DTV_ISDBT_LAYERA_*`` values are assigned to the center segment +and ``DTV_ISDBT_LAYERA_SEGMENT_COUNT`` has to be '1'. + +If in addition ``DTV_ISDBT_SOUND_BROADCASTING`` is '1' +``DTV_ISDBT_PARTIAL_RECEPTION`` represents whether this ISDB-Tsb channel +is consisting of one segment and layer or three segments and two layers. + +Possible values: 0, 1, -1 (AUTO) + + +.. _DTV-ISDBT-SOUND-BROADCASTING: + +DTV_ISDBT_SOUND_BROADCASTING +============================ + +Used only on ISDB. + +This field represents whether the other DTV_ISDBT_*-parameters are +referring to an ISDB-T and an ISDB-Tsb channel. (See also +``DTV_ISDBT_PARTIAL_RECEPTION``). + +Possible values: 0, 1, -1 (AUTO) + + +.. _DTV-ISDBT-SB-SUBCHANNEL-ID: + +DTV_ISDBT_SB_SUBCHANNEL_ID +========================== + +Used only on ISDB. + +This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'. + +(Note of the author: This might not be the correct description of the +``SUBCHANNEL-ID`` in all details, but it is my understanding of the +technical background needed to program a device) + +An ISDB-Tsb channel (1 or 3 segments) can be broadcasted alone or in a +set of connected ISDB-Tsb channels. In this set of channels every +channel can be received independently. The number of connected ISDB-Tsb +segment can vary, e.g. depending on the frequency spectrum bandwidth +available. + +Example: Assume 8 ISDB-Tsb connected segments are broadcasted. The +broadcaster has several possibilities to put those channels in the air: +Assuming a normal 13-segment ISDB-T spectrum he can align the 8 segments +from position 1-8 to 5-13 or anything in between. + +The underlying layer of segments are subchannels: each segment is +consisting of several subchannels with a predefined IDs. A sub-channel +is used to help the demodulator to synchronize on the channel. + +An ISDB-T channel is always centered over all sub-channels. As for the +example above, in ISDB-Tsb it is no longer as simple as that. + +``The DTV_ISDBT_SB_SUBCHANNEL_ID`` parameter is used to give the +sub-channel ID of the segment to be demodulated. + +Possible values: 0 .. 41, -1 (AUTO) + + +.. _DTV-ISDBT-SB-SEGMENT-IDX: + +DTV_ISDBT_SB_SEGMENT_IDX +======================== + +Used only on ISDB. + +This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'. + +``DTV_ISDBT_SB_SEGMENT_IDX`` gives the index of the segment to be +demodulated for an ISDB-Tsb channel where several of them are +transmitted in the connected manner. + +Possible values: 0 .. ``DTV_ISDBT_SB_SEGMENT_COUNT`` - 1 + +Note: This value cannot be determined by an automatic channel search. + + +.. _DTV-ISDBT-SB-SEGMENT-COUNT: + +DTV_ISDBT_SB_SEGMENT_COUNT +========================== + +Used only on ISDB. + +This field only applies if ``DTV_ISDBT_SOUND_BROADCASTING`` is '1'. + +``DTV_ISDBT_SB_SEGMENT_COUNT`` gives the total count of connected +ISDB-Tsb channels. + +Possible values: 1 .. 13 + +Note: This value cannot be determined by an automatic channel search. + + +.. _isdb-hierq-layers: + +DTV-ISDBT-LAYER[A-C] parameters +=============================== + +Used only on ISDB. + +ISDB-T channels can be coded hierarchically. As opposed to DVB-T in +ISDB-T hierarchical layers can be decoded simultaneously. For that +reason a ISDB-T demodulator has 3 Viterbi and 3 Reed-Solomon decoders. + +ISDB-T has 3 hierarchical layers which each can use a part of the +available segments. The total number of segments over all layers has to +13 in ISDB-T. + +There are 3 parameter sets, for Layers A, B and C. + + +.. _DTV-ISDBT-LAYER-ENABLED: + +DTV_ISDBT_LAYER_ENABLED +----------------------- + +Used only on ISDB. + +Hierarchical reception in ISDB-T is achieved by enabling or disabling +layers in the decoding process. Setting all bits of +``DTV_ISDBT_LAYER_ENABLED`` to '1' forces all layers (if applicable) to +be demodulated. This is the default. + +If the channel is in the partial reception mode +(``DTV_ISDBT_PARTIAL_RECEPTION`` = 1) the central segment can be decoded +independently of the other 12 segments. In that mode layer A has to have +a ``SEGMENT_COUNT`` of 1. + +In ISDB-Tsb only layer A is used, it can be 1 or 3 in ISDB-Tsb according +to ``DTV_ISDBT_PARTIAL_RECEPTION``. ``SEGMENT_COUNT`` must be filled +accordingly. + +Only the values of the first 3 bits are used. Other bits will be silently ignored: + +``DTV_ISDBT_LAYER_ENABLED`` bit 0: layer A enabled + +``DTV_ISDBT_LAYER_ENABLED`` bit 1: layer B enabled + +``DTV_ISDBT_LAYER_ENABLED`` bit 2: layer C enabled + +``DTV_ISDBT_LAYER_ENABLED`` bits 3-31: unused + + +.. _DTV-ISDBT-LAYER-FEC: + +DTV_ISDBT_LAYER[A-C]_FEC +------------------------ + +Used only on ISDB. + +The Forward Error Correction mechanism used by a given ISDB Layer, as +defined by :c:type:`fe_code_rate`. + + +Possible values are: ``FEC_AUTO``, ``FEC_1_2``, ``FEC_2_3``, ``FEC_3_4``, +``FEC_5_6``, ``FEC_7_8`` + + +.. _DTV-ISDBT-LAYER-MODULATION: + +DTV_ISDBT_LAYER[A-C]_MODULATION +------------------------------- + +Used only on ISDB. + +The modulation used by a given ISDB Layer, as defined by +:c:type:`fe_modulation`. + +Possible values are: ``QAM_AUTO``, ``QPSK``, ``QAM_16``, ``QAM_64``, ``DQPSK`` + +.. note:: + + #. If layer C is ``DQPSK``, then layer B has to be ``DQPSK``. + + #. If layer B is ``DQPSK`` and ``DTV_ISDBT_PARTIAL_RECEPTION``\ = 0, + then layer has to be ``DQPSK``. + + +.. _DTV-ISDBT-LAYER-SEGMENT-COUNT: + +DTV_ISDBT_LAYER[A-C]_SEGMENT_COUNT +---------------------------------- + +Used only on ISDB. + +Possible values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, -1 (AUTO) + +Note: Truth table for ``DTV_ISDBT_SOUND_BROADCASTING`` and +``DTV_ISDBT_PARTIAL_RECEPTION`` and ``LAYER[A-C]_SEGMENT_COUNT`` + +.. _isdbt-layer_seg-cnt-table: + +.. flat-table:: Truth table for ISDB-T Sound Broadcasting + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - Partial Reception + + - Sound Broadcasting + + - Layer A width + + - Layer B width + + - Layer C width + + - total width + + - .. row 2 + + - 0 + + - 0 + + - 1 .. 13 + + - 1 .. 13 + + - 1 .. 13 + + - 13 + + - .. row 3 + + - 1 + + - 0 + + - 1 + + - 1 .. 13 + + - 1 .. 13 + + - 13 + + - .. row 4 + + - 0 + + - 1 + + - 1 + + - 0 + + - 0 + + - 1 + + - .. row 5 + + - 1 + + - 1 + + - 1 + + - 2 + + - 0 + + - 13 + + + +.. _DTV-ISDBT-LAYER-TIME-INTERLEAVING: + +DTV_ISDBT_LAYER[A-C]_TIME_INTERLEAVING +-------------------------------------- + +Used only on ISDB. + +Valid values: 0, 1, 2, 4, -1 (AUTO) + +when DTV_ISDBT_SOUND_BROADCASTING is active, value 8 is also valid. + +Note: The real time interleaving length depends on the mode (fft-size). +The values here are referring to what can be found in the +TMCC-structure, as shown in the table below. + + +.. c:type:: isdbt_layer_interleaving_table + +.. flat-table:: ISDB-T time interleaving modes + :header-rows: 1 + :stub-columns: 0 + + + - .. row 1 + + - ``DTV_ISDBT_LAYER[A-C]_TIME_INTERLEAVING`` + + - Mode 1 (2K FFT) + + - Mode 2 (4K FFT) + + - Mode 3 (8K FFT) + + - .. row 2 + + - 0 + + - 0 + + - 0 + + - 0 + + - .. row 3 + + - 1 + + - 4 + + - 2 + + - 1 + + - .. row 4 + + - 2 + + - 8 + + - 4 + + - 2 + + - .. row 5 + + - 4 + + - 16 + + - 8 + + - 4 + + + +.. _DTV-ATSCMH-FIC-VER: + +DTV_ATSCMH_FIC_VER +------------------ + +Used only on ATSC-MH. + +Version number of the FIC (Fast Information Channel) signaling data. + +FIC is used for relaying information to allow rapid service acquisition +by the receiver. + +Possible values: 0, 1, 2, 3, ..., 30, 31 + + +.. _DTV-ATSCMH-PARADE-ID: + +DTV_ATSCMH_PARADE_ID +-------------------- + +Used only on ATSC-MH. + +Parade identification number + +A parade is a collection of up to eight MH groups, conveying one or two +ensembles. + +Possible values: 0, 1, 2, 3, ..., 126, 127 + + +.. _DTV-ATSCMH-NOG: + +DTV_ATSCMH_NOG +-------------- + +Used only on ATSC-MH. + +Number of MH groups per MH subframe for a designated parade. + +Possible values: 1, 2, 3, 4, 5, 6, 7, 8 + + +.. _DTV-ATSCMH-TNOG: + +DTV_ATSCMH_TNOG +--------------- + +Used only on ATSC-MH. + +Total number of MH groups including all MH groups belonging to all MH +parades in one MH subframe. + +Possible values: 0, 1, 2, 3, ..., 30, 31 + + +.. _DTV-ATSCMH-SGN: + +DTV_ATSCMH_SGN +-------------- + +Used only on ATSC-MH. + +Start group number. + +Possible values: 0, 1, 2, 3, ..., 14, 15 + + +.. _DTV-ATSCMH-PRC: + +DTV_ATSCMH_PRC +-------------- + +Used only on ATSC-MH. + +Parade repetition cycle. + +Possible values: 1, 2, 3, 4, 5, 6, 7, 8 + + +.. _DTV-ATSCMH-RS-FRAME-MODE: + +DTV_ATSCMH_RS_FRAME_MODE +------------------------ + +Used only on ATSC-MH. + +Reed Solomon (RS) frame mode. + +The acceptable values are defined by :c:type:`atscmh_rs_frame_mode`. + + +.. _DTV-ATSCMH-RS-FRAME-ENSEMBLE: + +DTV_ATSCMH_RS_FRAME_ENSEMBLE +---------------------------- + +Used only on ATSC-MH. + +Reed Solomon(RS) frame ensemble. + +The acceptable values are defined by :c:type:`atscmh_rs_frame_ensemble`. + + +.. _DTV-ATSCMH-RS-CODE-MODE-PRI: + +DTV_ATSCMH_RS_CODE_MODE_PRI +--------------------------- + +Used only on ATSC-MH. + +Reed Solomon (RS) code mode (primary). + +The acceptable values are defined by :c:type:`atscmh_rs_code_mode`. + + +.. _DTV-ATSCMH-RS-CODE-MODE-SEC: + +DTV_ATSCMH_RS_CODE_MODE_SEC +--------------------------- + +Used only on ATSC-MH. + +Reed Solomon (RS) code mode (secondary). + +The acceptable values are defined by :c:type:`atscmh_rs_code_mode`. + + +.. _DTV-ATSCMH-SCCC-BLOCK-MODE: + +DTV_ATSCMH_SCCC_BLOCK_MODE +-------------------------- + +Used only on ATSC-MH. + +Series Concatenated Convolutional Code Block Mode. + +The acceptable values are defined by :c:type:`atscmh_sccc_block_mode`. + + +.. _DTV-ATSCMH-SCCC-CODE-MODE-A: + +DTV_ATSCMH_SCCC_CODE_MODE_A +--------------------------- + +Used only on ATSC-MH. + +Series Concatenated Convolutional Code Rate. + +The acceptable values are defined by :c:type:`atscmh_sccc_code_mode`. + +.. _DTV-ATSCMH-SCCC-CODE-MODE-B: + +DTV_ATSCMH_SCCC_CODE_MODE_B +--------------------------- + +Used only on ATSC-MH. + +Series Concatenated Convolutional Code Rate. + +Possible values are the same as documented on enum +:c:type:`atscmh_sccc_code_mode`. + + +.. _DTV-ATSCMH-SCCC-CODE-MODE-C: + +DTV_ATSCMH_SCCC_CODE_MODE_C +--------------------------- + +Used only on ATSC-MH. + +Series Concatenated Convolutional Code Rate. + +Possible values are the same as documented on enum +:c:type:`atscmh_sccc_code_mode`. + + +.. _DTV-ATSCMH-SCCC-CODE-MODE-D: + +DTV_ATSCMH_SCCC_CODE_MODE_D +--------------------------- + +Used only on ATSC-MH. + +Series Concatenated Convolutional Code Rate. + +Possible values are the same as documented on enum +:c:type:`atscmh_sccc_code_mode`. + + +.. _DTV-API-VERSION: + +DTV_API_VERSION +=============== + +Returns the major/minor version of the Digital TV API + + +.. _DTV-CODE-RATE-HP: + +DTV_CODE_RATE_HP +================ + +Used on terrestrial transmissions. + +The acceptable values are defined by :c:type:`fe_transmit_mode`. + + +.. _DTV-CODE-RATE-LP: + +DTV_CODE_RATE_LP +================ + +Used on terrestrial transmissions. + +The acceptable values are defined by :c:type:`fe_transmit_mode`. + + +.. _DTV-GUARD-INTERVAL: + +DTV_GUARD_INTERVAL +================== + +The acceptable values are defined by :c:type:`fe_guard_interval`. + +.. note:: + + #. If ``DTV_GUARD_INTERVAL`` is set the ``GUARD_INTERVAL_AUTO`` the + hardware will try to find the correct guard interval (if capable) and + will use TMCC to fill in the missing parameters. + #. Intervals ``GUARD_INTERVAL_1_128``, ``GUARD_INTERVAL_19_128`` + and ``GUARD_INTERVAL_19_256`` are used only for DVB-T2 at + present. + #. Intervals ``GUARD_INTERVAL_PN420``, ``GUARD_INTERVAL_PN595`` and + ``GUARD_INTERVAL_PN945`` are used only for DMTB at the present. + On such standard, only those intervals and ``GUARD_INTERVAL_AUTO`` + are valid. + +.. _DTV-TRANSMISSION-MODE: + +DTV_TRANSMISSION_MODE +===================== + + +Used only on OFTM-based standards, e. g. DVB-T/T2, ISDB-T, DTMB. + +Specifies the FFT size (with corresponds to the approximate number of +carriers) used by the standard. + +The acceptable values are defined by :c:type:`fe_transmit_mode`. + +.. note:: + + #. ISDB-T supports three carrier/symbol-size: 8K, 4K, 2K. It is called + **mode** on such standard, and are numbered from 1 to 3: + + ==== ======== ======================== + Mode FFT size Transmission mode + ==== ======== ======================== + 1 2K ``TRANSMISSION_MODE_2K`` + 2 4K ``TRANSMISSION_MODE_4K`` + 3 8K ``TRANSMISSION_MODE_8K`` + ==== ======== ======================== + + #. If ``DTV_TRANSMISSION_MODE`` is set the ``TRANSMISSION_MODE_AUTO`` + the hardware will try to find the correct FFT-size (if capable) and + will use TMCC to fill in the missing parameters. + + #. DVB-T specifies 2K and 8K as valid sizes. + + #. DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K. + + #. DTMB specifies C1 and C3780. + + +.. _DTV-HIERARCHY: + +DTV_HIERARCHY +============= + +Used only on DVB-T and DVB-T2. + +Frontend hierarchy. + +The acceptable values are defined by :c:type:`fe_hierarchy`. + + +.. _DTV-STREAM-ID: + +DTV_STREAM_ID +============= + +Used on DVB-S2, DVB-T2 and ISDB-S. + +DVB-S2, DVB-T2 and ISDB-S support the transmission of several streams on +a single transport stream. This property enables the digital TV driver to +handle substream filtering, when supported by the hardware. By default, +substream filtering is disabled. + +For DVB-S2 and DVB-T2, the valid substream id range is from 0 to 255. + +For ISDB, the valid substream id range is from 1 to 65535. + +To disable it, you should use the special macro NO_STREAM_ID_FILTER. + +Note: any value outside the id range also disables filtering. + + +.. _DTV-DVBT2-PLP-ID-LEGACY: + +DTV_DVBT2_PLP_ID_LEGACY +======================= + +Obsolete, replaced with DTV_STREAM_ID. + + +.. _DTV-ENUM-DELSYS: + +DTV_ENUM_DELSYS +=============== + +A Multi standard frontend needs to advertise the delivery systems +provided. Applications need to enumerate the provided delivery systems, +before using any other operation with the frontend. Prior to it's +introduction, FE_GET_INFO was used to determine a frontend type. A +frontend which provides more than a single delivery system, +FE_GET_INFO doesn't help much. Applications which intends to use a +multistandard frontend must enumerate the delivery systems associated +with it, rather than trying to use FE_GET_INFO. In the case of a +legacy frontend, the result is just the same as with FE_GET_INFO, but +in a more structured format + +The acceptable values are defined by :c:type:`fe_delivery_system`. + + +.. _DTV-INTERLEAVING: + +DTV_INTERLEAVING +================ + +Time interleaving to be used. + +The acceptable values are defined by :c:type:`fe_interleaving`. + + +.. _DTV-LNA: + +DTV_LNA +======= + +Low-noise amplifier. + +Hardware might offer controllable LNA which can be set manually using +that parameter. Usually LNA could be found only from terrestrial devices +if at all. + +Possible values: 0, 1, LNA_AUTO + +0, LNA off + +1, LNA on + +use the special macro LNA_AUTO to set LNA auto + + +.. _DTV-SCRAMBLING-SEQUENCE-INDEX: + +DTV_SCRAMBLING_SEQUENCE_INDEX +============================= + +Used on DVB-S2. + +This 18 bit field, when present, carries the index of the DVB-S2 physical +layer scrambling sequence as defined in clause 5.5.4 of EN 302 307. +There is no explicit signalling method to convey scrambling sequence index +to the receiver. If S2 satellite delivery system descriptor is available +it can be used to read the scrambling sequence index (EN 300 468 table 41). + +By default, gold scrambling sequence index 0 is used. + +The valid scrambling sequence index range is from 0 to 262142. diff --git a/Documentation/userspace-api/media/dvb/frontend-header.rst b/Documentation/userspace-api/media/dvb/frontend-header.rst new file mode 100644 index 000000000..77f403361 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend-header.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +Frontend uAPI data types +======================== + +.. kernel-doc:: include/uapi/linux/dvb/frontend.h diff --git a/Documentation/userspace-api/media/dvb/frontend-property-cable-systems.rst b/Documentation/userspace-api/media/dvb/frontend-property-cable-systems.rst new file mode 100644 index 000000000..92ef98964 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend-property-cable-systems.rst @@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _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/userspace-api/media/dvb/frontend-property-satellite-systems.rst b/Documentation/userspace-api/media/dvb/frontend-property-satellite-systems.rst new file mode 100644 index 000000000..13b344b28 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend-property-satellite-systems.rst @@ -0,0 +1,105 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _frontend-property-satellite-systems: + +********************************************* +Properties used on satellite delivery systems +********************************************* + + +.. _dvbs-params: + +DVB-S delivery system +===================== + +The following parameters are valid for DVB-S: + +- :ref:`DTV_API_VERSION ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_SYMBOL_RATE ` + +- :ref:`DTV_INNER_FEC ` + +- :ref:`DTV_VOLTAGE ` + +- :ref:`DTV_TONE ` + +In addition, the :ref:`DTV QoS statistics ` +are also valid. + +Future implementations might add those two missing parameters: + +- :ref:`DTV_DISEQC_MASTER ` + +- :ref:`DTV_DISEQC_SLAVE_REPLY ` + + +.. _dvbs2-params: + +DVB-S2 delivery system +====================== + +In addition to all parameters valid for DVB-S, DVB-S2 supports the +following parameters: + +- :ref:`DTV_MODULATION ` + +- :ref:`DTV_PILOT ` + +- :ref:`DTV_ROLLOFF ` + +- :ref:`DTV_STREAM_ID ` + +- :ref:`DTV_SCRAMBLING_SEQUENCE_INDEX ` + +In addition, the :ref:`DTV QoS statistics ` +are also valid. + + +.. _turbo-params: + +Turbo code delivery system +========================== + +In addition to all parameters valid for DVB-S, turbo code supports the +following parameters: + +- :ref:`DTV_MODULATION ` + + +.. _isdbs-params: + +ISDB-S delivery system +====================== + +The following parameters are valid for ISDB-S: + +- :ref:`DTV_API_VERSION ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_SYMBOL_RATE ` + +- :ref:`DTV_INNER_FEC ` + +- :ref:`DTV_VOLTAGE ` + +- :ref:`DTV_STREAM_ID ` diff --git a/Documentation/userspace-api/media/dvb/frontend-property-terrestrial-systems.rst b/Documentation/userspace-api/media/dvb/frontend-property-terrestrial-systems.rst new file mode 100644 index 000000000..8cd461cee --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend-property-terrestrial-systems.rst @@ -0,0 +1,294 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _frontend-property-terrestrial-systems: + +*********************************************** +Properties used on terrestrial delivery systems +*********************************************** + + +.. _dvbt-params: + +DVB-T delivery system +===================== + +The following parameters are valid for DVB-T: + +- :ref:`DTV_API_VERSION ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_MODULATION ` + +- :ref:`DTV_BANDWIDTH_HZ ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_CODE_RATE_HP ` + +- :ref:`DTV_CODE_RATE_LP ` + +- :ref:`DTV_GUARD_INTERVAL ` + +- :ref:`DTV_TRANSMISSION_MODE ` + +- :ref:`DTV_HIERARCHY ` + +- :ref:`DTV_LNA ` + +In addition, the :ref:`DTV QoS statistics ` +are also valid. + + +.. _dvbt2-params: + +DVB-T2 delivery system +====================== + +DVB-T2 support is currently in the early stages of development, so +expect that this section maygrow and become more detailed with time. + +The following parameters are valid for DVB-T2: + +- :ref:`DTV_API_VERSION ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_MODULATION ` + +- :ref:`DTV_BANDWIDTH_HZ ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_CODE_RATE_HP ` + +- :ref:`DTV_CODE_RATE_LP ` + +- :ref:`DTV_GUARD_INTERVAL ` + +- :ref:`DTV_TRANSMISSION_MODE ` + +- :ref:`DTV_HIERARCHY ` + +- :ref:`DTV_STREAM_ID ` + +- :ref:`DTV_LNA ` + +In addition, the :ref:`DTV QoS statistics ` +are also valid. + + +.. _isdbt: + +ISDB-T delivery system +====================== + +This ISDB-T/ISDB-Tsb API extension should reflect all information needed +to tune any ISDB-T/ISDB-Tsb hardware. Of course it is possible that some +very sophisticated devices won't need certain parameters to tune. + +The information given here should help application writers to know how +to handle ISDB-T and ISDB-Tsb hardware using the Linux Digital TV API. + +The details given here about ISDB-T and ISDB-Tsb are just enough to +basically show the dependencies between the needed parameter values, but +surely some information is left out. For more detailed information see +the following documents: + +ARIB STD-B31 - "Transmission System for Digital Terrestrial Television +Broadcasting" and + +ARIB TR-B14 - "Operational Guidelines for Digital Terrestrial Television +Broadcasting". + +In order to understand the ISDB specific parameters, one has to have +some knowledge the channel structure in ISDB-T and ISDB-Tsb. I.e. it has +to be known to the reader that an ISDB-T channel consists of 13 +segments, that it can have up to 3 layer sharing those segments, and +things like that. + +The following parameters are valid for ISDB-T: + +- :ref:`DTV_API_VERSION ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_BANDWIDTH_HZ ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_GUARD_INTERVAL ` + +- :ref:`DTV_TRANSMISSION_MODE ` + +- :ref:`DTV_ISDBT_LAYER_ENABLED ` + +- :ref:`DTV_ISDBT_PARTIAL_RECEPTION ` + +- :ref:`DTV_ISDBT_SOUND_BROADCASTING ` + +- :ref:`DTV_ISDBT_SB_SUBCHANNEL_ID ` + +- :ref:`DTV_ISDBT_SB_SEGMENT_IDX ` + +- :ref:`DTV_ISDBT_SB_SEGMENT_COUNT ` + +- :ref:`DTV_ISDBT_LAYERA_FEC ` + +- :ref:`DTV_ISDBT_LAYERA_MODULATION ` + +- :ref:`DTV_ISDBT_LAYERA_SEGMENT_COUNT ` + +- :ref:`DTV_ISDBT_LAYERA_TIME_INTERLEAVING ` + +- :ref:`DTV_ISDBT_LAYERB_FEC ` + +- :ref:`DTV_ISDBT_LAYERB_MODULATION ` + +- :ref:`DTV_ISDBT_LAYERB_SEGMENT_COUNT ` + +- :ref:`DTV_ISDBT_LAYERB_TIME_INTERLEAVING ` + +- :ref:`DTV_ISDBT_LAYERC_FEC ` + +- :ref:`DTV_ISDBT_LAYERC_MODULATION ` + +- :ref:`DTV_ISDBT_LAYERC_SEGMENT_COUNT ` + +- :ref:`DTV_ISDBT_LAYERC_TIME_INTERLEAVING ` + +In addition, the :ref:`DTV QoS statistics ` +are also valid. + + +.. _atsc-params: + +ATSC delivery system +==================== + +The following parameters are valid for ATSC: + +- :ref:`DTV_API_VERSION ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_MODULATION ` + +- :ref:`DTV_BANDWIDTH_HZ ` + +In addition, the :ref:`DTV QoS statistics ` +are also valid. + + +.. _atscmh-params: + +ATSC-MH delivery system +======================= + +The following parameters are valid for ATSC-MH: + +- :ref:`DTV_API_VERSION ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_BANDWIDTH_HZ ` + +- :ref:`DTV_ATSCMH_FIC_VER ` + +- :ref:`DTV_ATSCMH_PARADE_ID ` + +- :ref:`DTV_ATSCMH_NOG ` + +- :ref:`DTV_ATSCMH_TNOG ` + +- :ref:`DTV_ATSCMH_SGN ` + +- :ref:`DTV_ATSCMH_PRC ` + +- :ref:`DTV_ATSCMH_RS_FRAME_MODE ` + +- :ref:`DTV_ATSCMH_RS_FRAME_ENSEMBLE ` + +- :ref:`DTV_ATSCMH_RS_CODE_MODE_PRI ` + +- :ref:`DTV_ATSCMH_RS_CODE_MODE_SEC ` + +- :ref:`DTV_ATSCMH_SCCC_BLOCK_MODE ` + +- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_A ` + +- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_B ` + +- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_C ` + +- :ref:`DTV_ATSCMH_SCCC_CODE_MODE_D ` + +In addition, the :ref:`DTV QoS statistics ` +are also valid. + + +.. _dtmb-params: + +DTMB delivery system +==================== + +The following parameters are valid for DTMB: + +- :ref:`DTV_API_VERSION ` + +- :ref:`DTV_DELIVERY_SYSTEM ` + +- :ref:`DTV_TUNE ` + +- :ref:`DTV_CLEAR ` + +- :ref:`DTV_FREQUENCY ` + +- :ref:`DTV_MODULATION ` + +- :ref:`DTV_BANDWIDTH_HZ ` + +- :ref:`DTV_INVERSION ` + +- :ref:`DTV_INNER_FEC ` + +- :ref:`DTV_GUARD_INTERVAL ` + +- :ref:`DTV_TRANSMISSION_MODE ` + +- :ref:`DTV_INTERLEAVING ` + +- :ref:`DTV_LNA ` + +In addition, the :ref:`DTV QoS statistics ` +are also valid. diff --git a/Documentation/userspace-api/media/dvb/frontend-stat-properties.rst b/Documentation/userspace-api/media/dvb/frontend-stat-properties.rst new file mode 100644 index 000000000..223c1c56c --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend-stat-properties.rst @@ -0,0 +1,245 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _frontend-stat-properties: + +****************************** +Frontend statistics indicators +****************************** + +The values are returned via ``dtv_property.stat``. If the property is +supported, ``dtv_property.stat.len`` is bigger than zero. + +For most delivery systems, ``dtv_property.stat.len`` will be 1 if the +stats is supported, and the properties will return a single value for +each parameter. + +It should be noted, however, that new OFDM delivery systems like ISDB +can use different modulation types for each group of carriers. On such +standards, up to 3 groups of statistics can be provided, and +``dtv_property.stat.len`` is updated to reflect the "global" metrics, +plus one metric per each carrier group (called "layer" on ISDB). + +So, in order to be consistent with other delivery systems, the first +value at :c:type:`dtv_property.stat.dtv_stats ` array refers +to the global metric. The other elements of the array represent each +layer, starting from layer A(index 1), layer B (index 2) and so on. + +The number of filled elements are stored at ``dtv_property.stat.len``. + +Each element of the ``dtv_property.stat.dtv_stats`` array consists on +two elements: + +- ``svalue`` or ``uvalue``, where ``svalue`` is for signed values of + the measure (dB measures) and ``uvalue`` is for unsigned values + (counters, relative scale) + +- ``scale`` - Scale for the value. It can be: + + - ``FE_SCALE_NOT_AVAILABLE`` - The parameter is supported by the + frontend, but it was not possible to collect it (could be a + transitory or permanent condition) + + - ``FE_SCALE_DECIBEL`` - parameter is a signed value, measured in + 1/1000 dB + + - ``FE_SCALE_RELATIVE`` - parameter is a unsigned value, where 0 + means 0% and 65535 means 100%. + + - ``FE_SCALE_COUNTER`` - parameter is a unsigned value that counts + the occurrence of an event, like bit error, block error, or lapsed + time. + + +.. _DTV-STAT-SIGNAL-STRENGTH: + +DTV_STAT_SIGNAL_STRENGTH +======================== + +Indicates the signal strength level at the analog part of the tuner or +of the demod. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_DECIBEL`` - signal strength is in 0.001 dBm units, power + measured in miliwatts. This value is generally negative. + +- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100% + measurement for power (actually, 0 to 65535). + + +.. _DTV-STAT-CNR: + +DTV_STAT_CNR +============ + +Indicates the Signal to Noise ratio for the main carrier. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_DECIBEL`` - Signal/Noise ratio is in 0.001 dB units. + +- ``FE_SCALE_RELATIVE`` - The frontend provides a 0% to 100% + measurement for Signal/Noise (actually, 0 to 65535). + + +.. _DTV-STAT-PRE-ERROR-BIT-COUNT: + +DTV_STAT_PRE_ERROR_BIT_COUNT +============================ + +Measures the number of bit errors before the forward error correction +(FEC) on the inner coding block (before Viterbi, LDPC or other inner +code). + +This measure is taken during the same interval as +``DTV_STAT_PRE_TOTAL_BIT_COUNT``. + +In order to get the BER (Bit Error Rate) measurement, it should be +divided by +:ref:`DTV_STAT_PRE_TOTAL_BIT_COUNT `. + +This measurement is monotonically increased, as the frontend gets more +bit count measurements. The frontend may reset it when a +channel/transponder is tuned. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_COUNTER`` - Number of error bits counted before the inner + coding. + + +.. _DTV-STAT-PRE-TOTAL-BIT-COUNT: + +DTV_STAT_PRE_TOTAL_BIT_COUNT +============================ + +Measures the amount of bits received before the inner code block, during +the same period as +:ref:`DTV_STAT_PRE_ERROR_BIT_COUNT ` +measurement was taken. + +It should be noted that this measurement can be smaller than the total +amount of bits on the transport stream, as the frontend may need to +manually restart the measurement, losing some data between each +measurement interval. + +This measurement is monotonically increased, as the frontend gets more +bit count measurements. The frontend may reset it when a +channel/transponder is tuned. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring + :ref:`DTV_STAT_PRE_ERROR_BIT_COUNT `. + + +.. _DTV-STAT-POST-ERROR-BIT-COUNT: + +DTV_STAT_POST_ERROR_BIT_COUNT +============================= + +Measures the number of bit errors after the forward error correction +(FEC) done by inner code block (after Viterbi, LDPC or other inner +code). + +This measure is taken during the same interval as +``DTV_STAT_POST_TOTAL_BIT_COUNT``. + +In order to get the BER (Bit Error Rate) measurement, it should be +divided by +:ref:`DTV_STAT_POST_TOTAL_BIT_COUNT `. + +This measurement is monotonically increased, as the frontend gets more +bit count measurements. The frontend may reset it when a +channel/transponder is tuned. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_COUNTER`` - Number of error bits counted after the inner + coding. + + +.. _DTV-STAT-POST-TOTAL-BIT-COUNT: + +DTV_STAT_POST_TOTAL_BIT_COUNT +============================= + +Measures the amount of bits received after the inner coding, during the +same period as +:ref:`DTV_STAT_POST_ERROR_BIT_COUNT ` +measurement was taken. + +It should be noted that this measurement can be smaller than the total +amount of bits on the transport stream, as the frontend may need to +manually restart the measurement, losing some data between each +measurement interval. + +This measurement is monotonically increased, as the frontend gets more +bit count measurements. The frontend may reset it when a +channel/transponder is tuned. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_COUNTER`` - Number of bits counted while measuring + :ref:`DTV_STAT_POST_ERROR_BIT_COUNT `. + + +.. _DTV-STAT-ERROR-BLOCK-COUNT: + +DTV_STAT_ERROR_BLOCK_COUNT +========================== + +Measures the number of block errors after the outer forward error +correction coding (after Reed-Solomon or other outer code). + +This measurement is monotonically increased, as the frontend gets more +bit count measurements. The frontend may reset it when a +channel/transponder is tuned. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_COUNTER`` - Number of error blocks counted after the outer + coding. + + +.. _DTV-STAT-TOTAL-BLOCK-COUNT: + +DTV-STAT_TOTAL_BLOCK_COUNT +========================== + +Measures the total number of blocks received during the same period as +:ref:`DTV_STAT_ERROR_BLOCK_COUNT ` +measurement was taken. + +It can be used to calculate the PER indicator, by dividing +:ref:`DTV_STAT_ERROR_BLOCK_COUNT ` by +:ref:`DTV-STAT-TOTAL-BLOCK-COUNT`. + +Possible scales for this metric are: + +- ``FE_SCALE_NOT_AVAILABLE`` - it failed to measure it, or the + measurement was not complete yet. + +- ``FE_SCALE_COUNTER`` - Number of blocks counted while measuring + :ref:`DTV_STAT_ERROR_BLOCK_COUNT `. diff --git a/Documentation/userspace-api/media/dvb/frontend.rst b/Documentation/userspace-api/media/dvb/frontend.rst new file mode 100644 index 000000000..1df68730f --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dvb_frontend: + +####################### +Digital TV Frontend API +####################### + +The Digital TV frontend API was designed to support three groups of delivery +systems: Terrestrial, cable and Satellite. Currently, the following +delivery systems are supported: + +- Terrestrial systems: DVB-T, DVB-T2, ATSC, ATSC M/H, ISDB-T, DVB-H, + DTMB, CMMB + +- Cable systems: DVB-C Annex A/C, ClearQAM (DVB-C Annex B) + +- Satellite systems: DVB-S, DVB-S2, DVB Turbo, ISDB-S, DSS + +The Digital TV frontend controls several sub-devices including: + +- Tuner + +- Digital TV demodulator + +- Low noise amplifier (LNA) + +- Satellite Equipment Control (SEC) [#f1]_. + +The frontend can be accessed through ``/dev/dvb/adapter?/frontend?``. +Data types and ioctl definitions can be accessed by including +``linux/dvb/frontend.h`` in your application. + +.. note:: + + Transmission via the internet (DVB-IP) and MMT (MPEG Media Transport) + is not yet handled by this API but a future extension is possible. + +.. [#f1] + + On Satellite systems, the API support for the Satellite Equipment + Control (SEC) allows to power control and to send/receive signals to + control the antenna subsystem, selecting the polarization and choosing + the Intermediate Frequency IF) of the Low Noise Block Converter Feed + Horn (LNBf). It supports the DiSEqC and V-SEC protocols. The DiSEqC + (digital SEC) specification is available at + `Eutelsat `__. + + +.. toctree:: + :maxdepth: 1 + + query-dvb-frontend-info + dvb-fe-read-status + dvbproperty + frontend_fcalls diff --git a/Documentation/userspace-api/media/dvb/frontend_f_close.rst b/Documentation/userspace-api/media/dvb/frontend_f_close.rst new file mode 100644 index 000000000..52c323a85 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend_f_close.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _frontend_f_close: + +*************************** +Digital TV frontend close() +*************************** + +Name +==== + +fe-close - Close a frontend device + +Synopsis +======== + +.. code-block:: c + + #include + +.. c:function:: int close( int fd ) + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +Description +=========== + +This system call closes a previously opened front-end device. After +closing a front-end device, its corresponding hardware might be powered +down automatically. + +Return Value +============ + +On success 0 is returned. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +Generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/frontend_f_open.rst b/Documentation/userspace-api/media/dvb/frontend_f_open.rst new file mode 100644 index 000000000..bb37eded0 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend_f_open.rst @@ -0,0 +1,104 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.fe + +.. _frontend_f_open: + +*************************** +Digital TV frontend open() +*************************** + +Name +==== + +fe-open - Open a frontend device + +Synopsis +======== + +.. code-block:: c + + #include + +.. c:function:: int open( const char *device_name, int flags ) + +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 :c:func:`open()` returns the new file descriptor. +On error, -1 is returned, and the ``errno`` variable is set appropriately. + +Possible error codes are: + +On success 0 is returned, and :c:type:`ca_slot_info` is filled. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + - - ``EPERM`` + - The caller has no permission to access the device. + + - - ``EBUSY`` + - The the device driver is already in use. + + - - ``EMFILE`` + - The process already has the maximum number of files open. + + - - ``ENFILE`` + - The limit on the total number of files open on the system has been + reached. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/frontend_fcalls.rst b/Documentation/userspace-api/media/dvb/frontend_fcalls.rst new file mode 100644 index 000000000..1df27b6e8 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend_fcalls.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _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/userspace-api/media/dvb/frontend_legacy_api.rst b/Documentation/userspace-api/media/dvb/frontend_legacy_api.rst new file mode 100644 index 000000000..535828c00 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend_legacy_api.rst @@ -0,0 +1,38 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _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/userspace-api/media/dvb/frontend_legacy_dvbv3_api.rst b/Documentation/userspace-api/media/dvb/frontend_legacy_dvbv3_api.rst new file mode 100644 index 000000000..09de723c2 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/frontend_legacy_dvbv3_api.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _frontend_legacy_dvbv3_api: + +*********************************************** +Digital TV Frontend legacy API (a. k. a. DVBv3) +*********************************************** + +The usage of this API is deprecated, as it doesn't support all digital +TV standards, doesn't provide good statistics measurements and provides +incomplete information. This is kept only to support legacy +applications. + + +.. toctree:: + :maxdepth: 1 + + frontend_legacy_api diff --git a/Documentation/userspace-api/media/dvb/headers.rst b/Documentation/userspace-api/media/dvb/headers.rst new file mode 100644 index 000000000..88c3eb33a --- /dev/null +++ b/Documentation/userspace-api/media/dvb/headers.rst @@ -0,0 +1,16 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +**************************** +Digital TV uAPI header files +**************************** + +Digital TV uAPI headers +*********************** + +.. kernel-include:: $BUILDDIR/frontend.h.rst + +.. kernel-include:: $BUILDDIR/dmx.h.rst + +.. kernel-include:: $BUILDDIR/ca.h.rst + +.. kernel-include:: $BUILDDIR/net.h.rst diff --git a/Documentation/userspace-api/media/dvb/intro.rst b/Documentation/userspace-api/media/dvb/intro.rst new file mode 100644 index 000000000..6784ae796 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/intro.rst @@ -0,0 +1,183 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _dvb_introdution: + +************ +Introduction +************ + + +.. _requisites: + +What you need to know +===================== + +The reader of this document is required to have some knowledge in the +area of digital video broadcasting (Digital TV) and should be familiar with +part I of the MPEG2 specification ISO/IEC 13818 (aka ITU-T H.222), i.e +you should know what a program/transport stream (PS/TS) is and what is +meant by a packetized elementary stream (PES) or an I-frame. + +Various Digital TV standards documents are available for download at: + +- European standards (DVB): http://www.dvb.org and/or http://www.etsi.org. +- American standards (ATSC): https://www.atsc.org/standards/ +- Japanese standards (ISDB): http://www.dibeg.org/ + +It is also necessary to know how to access Linux devices and how to +use ioctl calls. This also includes the knowledge of C or C++. + + +.. _history: + +History +======= + +The first API for Digital TV cards we used at Convergence in late 1999 was an +extension of the Video4Linux API which was primarily developed for frame +grabber cards. As such it was not really well suited to be used for Digital +TV cards and their new features like recording MPEG streams and filtering +several section and PES data streams at the same time. + +In early 2000, Convergence was approached by Nokia with a proposal for a new +standard Linux Digital TV API. As a commitment to the development of terminals +based on open standards, Nokia and Convergence made it available to all +Linux developers and published it on https://linuxtv.org in September +2000. With the Linux driver for the Siemens/Hauppauge DVB PCI card, +Convergence provided a first implementation of the Linux Digital TV API. +Convergence was the maintainer of the Linux Digital TV API in the early +days. + +Now, the API is maintained by the LinuxTV community (i.e. you, the reader +of this document). The Linux Digital TV API is constantly reviewed and +improved together with the improvements at the subsystem's core at the +Kernel. + + +.. _overview: + +Overview +======== + + +.. _stb_components: + +.. kernel-figure:: dvbstb.svg + :alt: dvbstb.svg + :align: center + + Components of a Digital TV card/STB + +A Digital TV card or set-top-box (STB) usually consists of the +following main hardware components: + +Frontend consisting of tuner and digital TV demodulator + Here the raw signal reaches the digital TV hardware from a satellite dish or + antenna or directly from cable. The frontend down-converts and + demodulates this signal into an MPEG transport stream (TS). In case + of a satellite frontend, this includes a facility for satellite + equipment control (SEC), which allows control of LNB polarization, + multi feed switches or dish rotors. + +Conditional Access (CA) hardware like CI adapters and smartcard slots + The complete TS is passed through the CA hardware. Programs to which + the user has access (controlled by the smart card) are decoded in + real time and re-inserted into the TS. + + .. note:: + + Not every digital TV hardware provides conditional access hardware. + +Demultiplexer which filters the incoming Digital TV MPEG-TS stream + The demultiplexer splits the TS into its components like audio and + video streams. Besides usually several of such audio and video + streams it also contains data streams with information about the + programs offered in this or other streams of the same provider. + +Audio and video decoder + The main targets of the demultiplexer are audio and video + decoders. After decoding, they pass on the uncompressed audio and + video to the computer screen or to a TV set. + + .. note:: + + Modern hardware usually doesn't have a separate decoder hardware, as + such functionality can be provided by the main CPU, by the graphics + adapter of the system or by a signal processing hardware embedded on + a Systems on a Chip (SoC) integrated circuit. + + It may also not be needed for certain usages (e.g. for data-only + uses like "internet over satellite"). + +:ref:`stb_components` shows a crude schematic of the control and data +flow between those components. + + + +.. _dvb_devices: + +Linux Digital TV Devices +======================== + +The Linux Digital TV API lets you control these hardware components through +currently six Unix-style character devices for video, audio, frontend, +demux, CA and IP-over-DVB networking. The video and audio devices +control the MPEG2 decoder hardware, the frontend device the tuner and +the Digital TV demodulator. The demux device gives you control over the PES +and section filters of the hardware. If the hardware does not support +filtering these filters can be implemented in software. Finally, the CA +device controls all the conditional access capabilities of the hardware. +It can depend on the individual security requirements of the platform, +if and how many of the CA functions are made available to the +application through this device. + +All devices can be found in the ``/dev`` tree under ``/dev/dvb``. The +individual devices are called: + +- ``/dev/dvb/adapterN/audioM``, + +- ``/dev/dvb/adapterN/videoM``, + +- ``/dev/dvb/adapterN/frontendM``, + +- ``/dev/dvb/adapterN/netM``, + +- ``/dev/dvb/adapterN/demuxM``, + +- ``/dev/dvb/adapterN/dvrM``, + +- ``/dev/dvb/adapterN/caM``, + +where ``N`` enumerates the Digital TV cards in a system starting from 0, and +``M`` enumerates the devices of each type within each adapter, starting +from 0, too. We will omit the "``/dev/dvb/adapterN/``\ " in the further +discussion of these devices. + +More details about the data structures and function calls of all the +devices are described in the following chapters. + + +.. _include_files: + +API include files +================= + +For each of the Digital TV devices a corresponding include file exists. The +Digital TV API include files should be included in application sources with a +partial path like: + + +.. code-block:: c + + #include + + #include + + #include + + #include + + +To enable applications to support different API version, an additional +include file ``linux/dvb/version.h`` exists, which defines the constant +``DVB_API_VERSION``. This document describes ``DVB_API_VERSION 5.10``. diff --git a/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst new file mode 100644 index 000000000..b97d56ee5 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/legacy_dvb_apis.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _legacy_dvb_apis: + +*************************** +Digital TV Deprecated APIs +*************************** + +The APIs described here **should not** be used on new drivers or applications. + +The DVBv3 frontend API has issues with new delivery systems, including +DVB-S2, DVB-T2, ISDB, etc. + +.. attention:: + + The APIs described here doesn't necessarily reflect the current + code implementation, as this section of the document was written + for DVB version 1, while the code reflects DVB version 3 + implementation. + + +.. toctree:: + :maxdepth: 1 + + frontend_legacy_dvbv3_api diff --git a/Documentation/userspace-api/media/dvb/net-add-if.rst b/Documentation/userspace-api/media/dvb/net-add-if.rst new file mode 100644 index 000000000..022b4c626 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/net-add-if.rst @@ -0,0 +1,52 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.net + +.. _NET_ADD_IF: + +**************** +ioctl NET_ADD_IF +**************** + +Name +==== + +NET_ADD_IF - Creates a new network interface for a given Packet ID. + +Synopsis +======== + +.. c:macro:: NET_ADD_IF + +``int ioctl(int fd, NET_ADD_IF, struct dvb_net_if *net_if)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``net_if`` + pointer to struct :c:type:`dvb_net_if` + +Description +=========== + +The NET_ADD_IF ioctl system call selects the Packet ID (PID) that +contains a TCP/IP traffic, the type of encapsulation to be used (MPE or +ULE) and the interface number for the new interface to be created. When +the system call successfully returns, a new virtual network interface is +created. + +The struct :c:type:`dvb_net_if`::ifnum field will be +filled with the number of the created interface. + +Return Value +============ + +On success 0 is returned, and :c:type:`ca_slot_info` is filled. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/net-get-if.rst b/Documentation/userspace-api/media/dvb/net-get-if.rst new file mode 100644 index 000000000..e99696c9d --- /dev/null +++ b/Documentation/userspace-api/media/dvb/net-get-if.rst @@ -0,0 +1,50 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.net + +.. _NET_GET_IF: + +**************** +ioctl NET_GET_IF +**************** + +Name +==== + +NET_GET_IF - Read the configuration data of an interface created via - :ref:`NET_ADD_IF `. + +Synopsis +======== + +.. c:macro:: NET_GET_IF + +``int ioctl(int fd, NET_GET_IF, struct dvb_net_if *net_if)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``net_if`` + pointer to struct :c:type:`dvb_net_if` + +Description +=========== + +The NET_GET_IF ioctl uses the interface number given by the struct +:c:type:`dvb_net_if`::ifnum field and fills the content of +struct :c:type:`dvb_net_if` with the packet ID and +encapsulation type used on such interface. If the interface was not +created yet with :ref:`NET_ADD_IF `, it will return -1 and fill +the ``errno`` with ``EINVAL`` error code. + +Return Value +============ + +On success 0 is returned, and :c:type:`ca_slot_info` is filled. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/net-remove-if.rst b/Documentation/userspace-api/media/dvb/net-remove-if.rst new file mode 100644 index 000000000..ac88691c0 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/net-remove-if.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: DTV.net + +.. _NET_REMOVE_IF: + +******************* +ioctl NET_REMOVE_IF +******************* + +Name +==== + +NET_REMOVE_IF - Removes a network interface. + +Synopsis +======== + +.. c:macro:: NET_REMOVE_IF + +``int ioctl(int fd, NET_REMOVE_IF, int ifnum)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``net_if`` + number of the interface to be removed + +Description +=========== + +The NET_REMOVE_IF ioctl deletes an interface previously created via +:ref:`NET_ADD_IF `. + +Return Value +============ + +On success 0 is returned, and :c:type:`ca_slot_info` is filled. + +On error -1 is returned, and the ``errno`` variable is set +appropriately. + +The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/dvb/net-types.rst b/Documentation/userspace-api/media/dvb/net-types.rst new file mode 100644 index 000000000..075264bc0 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/net-types.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _net_types: + +************** +Net Data Types +************** + +.. kernel-doc:: include/uapi/linux/dvb/net.h diff --git a/Documentation/userspace-api/media/dvb/net.rst b/Documentation/userspace-api/media/dvb/net.rst new file mode 100644 index 000000000..020a023d3 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/net.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _net: + +###################### +Digital TV Network API +###################### + +The Digital TV net device controls the mapping of data packages that are part +of a transport stream to be mapped into a virtual network interface, +visible through the standard Linux network protocol stack. + +Currently, two encapsulations are supported: + +- `Multi Protocol Encapsulation (MPE) `__ + +- `Ultra Lightweight Encapsulation (ULE) `__ + +In order to create the Linux virtual network interfaces, an application +needs to tell to the Kernel what are the PIDs and the encapsulation +types that are present on the transport stream. This is done through +``/dev/dvb/adapter?/net?`` device node. The data will be available via +virtual ``dvb?_?`` network interfaces, and will be controlled/routed via +the standard ip tools (like ip, route, netstat, ifconfig, etc). + +Data types and ioctl definitions are defined via ``linux/dvb/net.h`` +header. + + +.. _net_fcalls: + +Digital TV net Function Calls +############################# + +.. toctree:: + :maxdepth: 1 + + net-types + net-add-if + net-remove-if + net-get-if diff --git a/Documentation/userspace-api/media/dvb/query-dvb-frontend-info.rst b/Documentation/userspace-api/media/dvb/query-dvb-frontend-info.rst new file mode 100644 index 000000000..f099b4935 --- /dev/null +++ b/Documentation/userspace-api/media/dvb/query-dvb-frontend-info.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _query-dvb-frontend-info: + +***************************** +Querying frontend information +***************************** + +Usually, the first thing to do when the frontend is opened is to check +the frontend capabilities. This is done using +:ref:`FE_GET_INFO`. This ioctl will enumerate the +Digital TV API version and other characteristics about the frontend, and can +be opened either in read only or read/write mode. diff --git a/Documentation/userspace-api/media/fdl-appendix.rst b/Documentation/userspace-api/media/fdl-appendix.rst new file mode 100644 index 000000000..b1bc725b4 --- /dev/null +++ b/Documentation/userspace-api/media/fdl-appendix.rst @@ -0,0 +1,471 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _fdl: + +****************************** +GNU Free Documentation License +****************************** + + +.. _fdl-preamble: + +0. PREAMBLE +=========== + +The purpose of this License is to make a manual, textbook, or other +written document "free" in the sense of freedom: to assure everyone the +effective freedom to copy and redistribute it, with or without modifying +it, either commercially or noncommercially. Secondarily, this License +preserves for the author and publisher a way to get credit for their +work, while not being considered responsible for modifications made by +others. + +This License is a kind of "copyleft", which means that derivative works +of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft license +designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free program +should come with manuals providing the same freedoms that the software +does. But this License is not limited to software manuals; it can be +used for any textual work, regardless of subject matter or whether it is +published as a printed book. We recommend this License principally for +works whose purpose is instruction or reference. + + +.. _fdl-section1: + +1. APPLICABILITY AND DEFINITIONS +================================ + + +.. _fdl-document: + +This License applies to any manual or other work that contains a notice +placed by the copyright holder saying it can be distributed under the +terms of this License. The "Document", below, refers to any such manual +or work. Any member of the public is a licensee, and is addressed as +"you". + + +.. _fdl-modified: + +A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + + +.. _fdl-secondary: + +A "Secondary Section" is a named appendix or a front-matter section of +the :ref:`Document ` that deals exclusively with the +relationship of the publishers or authors of the Document to the +Document's overall subject (or to related matters) and contains nothing +that could fall directly within that overall subject. (For example, if +the Document is in part a textbook of mathematics, a Secondary Section +may not explain any mathematics.) The relationship could be a matter of +historical connection with the subject or with related matters, or of +legal, commercial, philosophical, ethical or political position +regarding them. + + +.. _fdl-invariant: + +The "Invariant Sections" are certain +:ref:`Secondary Sections ` whose titles are designated, +as being those of Invariant Sections, in the notice that says that the +:ref:`Document ` is released under this License. + + +.. _fdl-cover-texts: + +The "Cover Texts" are certain short passages of text that are listed, as +Front-Cover Texts or Back-Cover Texts, in the notice that says that the +:ref:`Document ` is released under this License. + + +.. _fdl-transparent: + +A "Transparent" copy of the :ref:`Document ` means a +machine-readable copy, represented in a format whose specification is +available to the general public, whose contents can be viewed and edited +directly and straightforwardly with generic text editors or (for images +composed of pixels) generic paint programs or (for drawings) some widely +available drawing editor, and that is suitable for input to text +formatters or for automatic translation to a variety of formats suitable +for input to text formatters. A copy made in an otherwise Transparent +file format whose markup has been designed to thwart or discourage +subsequent modification by readers is not Transparent. A copy that is +not "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include plain ASCII +without markup, Texinfo input format, LaTeX input format, SGML or XML +using a publicly available DTD, and standard-conforming simple HTML +designed for human modification. Opaque formats include PostScript, PDF, +proprietary formats that can be read and edited only by proprietary word +processors, SGML or XML for which the DTD and/or processing tools are +not generally available, and the machine-generated HTML produced by some +word processors for output purposes only. + + +.. _fdl-title-page: + +The "Title Page" means, for a printed book, the title page itself, plus +such following pages as are needed to hold, legibly, the material this +License requires to appear in the title page. For works in formats which +do not have any title page as such, "Title Page" means the text near the +most prominent appearance of the work's title, preceding the beginning +of the body of the text. + + +.. _fdl-section2: + +2. VERBATIM COPYING +=================== + +You may copy and distribute the :ref:`Document ` in any +medium, either commercially or noncommercially, provided that this +License, the copyright notices, and the license notice saying this +License applies to the Document are reproduced in all copies, and that +you add no other conditions whatsoever to those of this License. You may +not use technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in +:ref:`section 3 `. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + + +.. _fdl-section3: + +3. COPYING IN QUANTITY +====================== + +If you publish printed copies of the :ref:`Document ` +numbering more than 100, and the Document's license notice requires +:ref:`Cover Texts `, you must enclose the copies in +covers that carry, clearly and legibly, all these Cover Texts: +Front-Cover Texts on the front cover, and Back-Cover Texts on the back +cover. Both covers must also clearly and legibly identify you as the +publisher of these copies. The front cover must present the full title +with all words of the title equally prominent and visible. You may add +other material on the covers in addition. Copying with changes limited +to the covers, as long as they preserve the title of the +:ref:`Document ` and satisfy these conditions, can be +treated as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute :ref:`Opaque ` copies of +the :ref:`Document ` numbering more than 100, you must +either include a machine-readable :ref:`Transparent ` +copy along with each Opaque copy, or state in or with each Opaque copy a +publicly-accessible computer-network location containing a complete +Transparent copy of the Document, free of added material, which the +general network-using public has access to download anonymously at no +charge using public-standard network protocols. If you use the latter +option, you must take reasonably prudent steps, when you begin +distribution of Opaque copies in quantity, to ensure that this +Transparent copy will remain thus accessible at the stated location +until at least one year after the last time you distribute an Opaque +copy (directly or through your agents or retailers) of that edition to +the public. + +It is requested, but not required, that you contact the authors of the +:ref:`Document ` well before redistributing any large +number of copies, to give them a chance to provide you with an updated +version of the Document. + + +.. _fdl-section4: + +4. MODIFICATIONS +================ + +You may copy and distribute a :ref:`Modified Version ` +of the :ref:`Document ` under the conditions of sections +:ref:`2 ` and :ref:`3 ` above, provided +that you release the Modified Version under precisely this License, with +the Modified Version filling the role of the Document, thus licensing +distribution and modification of the Modified Version to whoever +possesses a copy of it. In addition, you must do these things in the +Modified Version: + +- **A.** + Use in the :ref:`Title Page ` (and on the covers, + if any) a title distinct from that of the + :ref:`Document `, and from those of previous versions + (which should, if there were any, be listed in the History section of + the Document). You may use the same title as a previous version if + the original publisher of that version gives permission. + +- **B.** + List on the :ref:`Title Page `, as authors, one or + more persons or entities responsible for authorship of the + modifications in the :ref:`Modified Version `, + together with at least five of the principal authors of the + :ref:`Document ` (all of its principal authors, if it + has less than five). + +- **C.** + State on the :ref:`Title Page ` the name of the + publisher of the :ref:`Modified Version `, as the + publisher. + +- **D.** + Preserve all the copyright notices of the + :ref:`Document `. + +- **E.** + Add an appropriate copyright notice for your modifications adjacent + to the other copyright notices. + +- **F.** + Include, immediately after the copyright notices, a license notice + giving the public permission to use the + :ref:`Modified Version ` under the terms of this + License, in the form shown in the Addendum below. + +- **G.** + Preserve in that license notice the full lists of + :ref:`Invariant Sections ` and required + :ref:`Cover Texts ` given in the + :ref:`Document's ` license notice. + +- **H.** + Include an unaltered copy of this License. + +- **I.** + Preserve the section entitled "History", and its title, and add to it + an item stating at least the title, year, new authors, and publisher + of the :ref:`Modified Version ` as given on the + :ref:`Title Page `. If there is no section entitled + "History" in the :ref:`Document `, create one stating + the title, year, authors, and publisher of the Document as given on + its Title Page, then add an item describing the Modified Version as + stated in the previous sentence. + +- **J.** + Preserve the network location, if any, given in the + :ref:`Document ` for public access to a + :ref:`Transparent ` copy of the Document, and + likewise the network locations given in the Document for previous + versions it was based on. These may be placed in the "History" + section. You may omit a network location for a work that was + published at least four years before the Document itself, or if the + original publisher of the version it refers to gives permission. + +- **K.** + In any section entitled "Acknowledgements" or "Dedications", preserve + the section's title, and preserve in the section all the substance + and tone of each of the contributor acknowledgements and/or + dedications given therein. + +- **L.** + Preserve all the :ref:`Invariant Sections ` of the + :ref:`Document `, unaltered in their text and in + their titles. Section numbers or the equivalent are not considered + part of the section titles. + +- **M.** + Delete any section entitled "Endorsements". Such a section may not be + included in the :ref:`Modified Version `. + +- **N.** + Do not retitle any existing section as "Endorsements" or to conflict + in title with any :ref:`Invariant Section `. + +If the :ref:`Modified Version ` includes new +front-matter sections or appendices that qualify as +:ref:`Secondary Sections ` and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the list +of :ref:`Invariant Sections ` in the Modified Version's +license notice. These titles must be distinct from any other section +titles. + +You may add a section entitled "Endorsements", provided it contains +nothing but endorsements of your +:ref:`Modified Version ` by various parties--for +example, statements of peer review or that the text has been approved by +an organization as the authoritative definition of a standard. + +You may add a passage of up to five words as a +:ref:`Front-Cover Text `, and a passage of up to 25 +words as a :ref:`Back-Cover Text `, to the end of the +list of :ref:`Cover Texts ` in the +:ref:`Modified Version `. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or through +arrangements made by) any one entity. If the +:ref:`Document ` already includes a cover text for the +same cover, previously added by you or by arrangement made by the same +entity you are acting on behalf of, you may not add another; but you may +replace the old one, on explicit permission from the previous publisher +that added the old one. + +The author(s) and publisher(s) of the :ref:`Document ` +do not by this License give permission to use their names for publicity +for or to assert or imply endorsement of any +:ref:`Modified Version `. + + +.. _fdl-section5: + +5. COMBINING DOCUMENTS +====================== + +You may combine the :ref:`Document ` with other +documents released under this License, under the terms defined in +:ref:`section 4 ` above for modified versions, provided +that you include in the combination all of the +:ref:`Invariant Sections ` of all of the original +documents, unmodified, and list them all as Invariant Sections of your +combined work in its license notice. + +The combined work need only contain one copy of this License, and +multiple identical :ref:`Invariant Sections ` may be +replaced with a single copy. If there are multiple Invariant Sections +with the same name but different contents, make the title of each such +section unique by adding at the end of it, in parentheses, the name of +the original author or publisher of that section if known, or else a +unique number. Make the same adjustment to the section titles in the +list of Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections entitled "History" in +the various original documents, forming one section entitled "History"; +likewise combine any sections entitled "Acknowledgements", and any +sections entitled "Dedications". You must delete all sections entitled +"Endorsements." + + +.. _fdl-section6: + +6. COLLECTIONS OF DOCUMENTS +=========================== + +You may make a collection consisting of the +:ref:`Document ` and other documents released under this +License, and replace the individual copies of this License in the +various documents with a single copy that is included in the collection, +provided that you follow the rules of this License for verbatim copying +of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + + +.. _fdl-section7: + +7. AGGREGATION WITH INDEPENDENT WORKS +===================================== + +A compilation of the :ref:`Document ` or its derivatives +with other separate and independent documents or works, in or on a +volume of a storage or distribution medium, does not as a whole count as +a :ref:`Modified Version ` of the Document, provided no +compilation copyright is claimed for the compilation. Such a compilation +is called an "aggregate", and this License does not apply to the other +self-contained works thus compiled with the Document , on account of +their being thus compiled, if they are not themselves derivative works +of the Document. If the :ref:`Cover Text ` +requirement of :ref:`section 3 ` is applicable to these +copies of the Document, then if the Document is less than one quarter of +the entire aggregate, the Document's Cover Texts may be placed on covers +that surround only the Document within the aggregate. Otherwise they +must appear on covers around the whole aggregate. + + +.. _fdl-section8: + +8. TRANSLATION +============== + +Translation is considered a kind of modification, so you may distribute +translations of the :ref:`Document ` under the terms of +:ref:`section 4 `. Replacing +:ref:`Invariant Sections ` with translations requires +special permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License provided that you also include the original +English version of this License. In case of a disagreement between the +translation and the original English version of this License, the +original English version will prevail. + + +.. _fdl-section9: + +9. TERMINATION +============== + +You may not copy, modify, sublicense, or distribute the +:ref:`Document ` except as expressly provided for under +this License. Any other attempt to copy, modify, sublicense or +distribute the Document is void, and will automatically terminate your +rights under this License. However, parties who have received copies, or +rights, from you under this License will not have their licenses +terminated so long as such parties remain in full compliance. + + +.. _fdl-section10: + +10. FUTURE REVISIONS OF THIS LICENSE +==================================== + +The `Free Software Foundation `__ +may publish new, revised versions of the GNU Free Documentation License +from time to time. Such new versions will be similar in spirit to the +present version, but may differ in detail to address new problems or +concerns. See +`http://www.gnu.org/copyleft/ `__. + +Each version of the License is given a distinguishing version number. If +the :ref:`Document ` specifies that a particular +numbered version of this License "or any later version" applies to it, +you have the option of following the terms and conditions either of that +specified version or of any later version that has been published (not +as a draft) by the Free Software Foundation. If the Document does not +specify a version number of this License, you may choose any version +ever published (not as a draft) by the Free Software Foundation. + + +.. _fdl-using: + +Addendum +======== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright © YEAR YOUR NAME. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.1 or any later version published by the Free Software + Foundation; with the :ref:`Invariant Sections ` + being LIST THEIR TITLES, with the + :ref:`Front-Cover Texts ` being LIST, and with + the :ref:`Back-Cover Texts ` being LIST. A copy + of the license is included in the section entitled "GNU Free + Documentation License". + +If you have no :ref:`Invariant Sections `, write "with +no Invariant Sections" instead of saying which ones are invariant. If +you have no :ref:`Front-Cover Texts `, write "no +Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise +for :ref:`Back-Cover Texts `. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the +`GNU General Public License `__, +to permit their use in free software. diff --git a/Documentation/userspace-api/media/frontend.h.rst.exceptions b/Documentation/userspace-api/media/frontend.h.rst.exceptions new file mode 100644 index 000000000..6283702c0 --- /dev/null +++ b/Documentation/userspace-api/media/frontend.h.rst.exceptions @@ -0,0 +1,214 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Ignore header name +ignore define _DVBFRONTEND_H_ + +# Group layer A-C symbols together +replace define DTV_ISDBT_LAYERA_FEC dtv-isdbt-layer-fec +replace define DTV_ISDBT_LAYERB_FEC dtv-isdbt-layer-fec +replace define DTV_ISDBT_LAYERC_FEC dtv-isdbt-layer-fec +replace define DTV_ISDBT_LAYERA_MODULATION dtv-isdbt-layer-modulation +replace define DTV_ISDBT_LAYERB_MODULATION dtv-isdbt-layer-modulation +replace define DTV_ISDBT_LAYERC_MODULATION dtv-isdbt-layer-modulation +replace define DTV_ISDBT_LAYERA_SEGMENT_COUNT dtv-isdbt-layer-segment-count +replace define DTV_ISDBT_LAYERB_SEGMENT_COUNT dtv-isdbt-layer-segment-count +replace define DTV_ISDBT_LAYERC_SEGMENT_COUNT dtv-isdbt-layer-segment-count +replace define DTV_ISDBT_LAYERA_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving +replace define DTV_ISDBT_LAYERB_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving +replace define DTV_ISDBT_LAYERC_TIME_INTERLEAVING dtv-isdbt-layer-time-interleaving + +# Ignore legacy defines +ignore define DTV_ISDBS_TS_ID_LEGACY +ignore define SYS_DVBC_ANNEX_AC +ignore define SYS_DMBTH + +# Ignore limits +ignore define DTV_MAX_COMMAND +ignore define MAX_DTV_STATS +ignore define DTV_IOCTL_MAX_MSGS + +# the same reference is used for both get and set ioctls +replace ioctl FE_SET_PROPERTY :c:type:`FE_GET_PROPERTY` + +# Typedefs that use the enum reference +replace typedef fe_sec_voltage_t :c:type:`fe_sec_voltage` + +# Replaces for flag constants +replace define FE_TUNE_MODE_ONESHOT :c:func:`FE_SET_FRONTEND_TUNE_MODE` +replace define LNA_AUTO dtv-lna +replace define NO_STREAM_ID_FILTER dtv-stream-id + +# Those enums are defined at the frontend.h header, and not externally + +ignore symbol FE_IS_STUPID +ignore symbol FE_CAN_INVERSION_AUTO +ignore symbol FE_CAN_FEC_1_2 +ignore symbol FE_CAN_FEC_2_3 +ignore symbol FE_CAN_FEC_3_4 +ignore symbol FE_CAN_FEC_4_5 +ignore symbol FE_CAN_FEC_5_6 +ignore symbol FE_CAN_FEC_6_7 +ignore symbol FE_CAN_FEC_7_8 +ignore symbol FE_CAN_FEC_8_9 +ignore symbol FE_CAN_FEC_AUTO +ignore symbol FE_CAN_QPSK +ignore symbol FE_CAN_QAM_16 +ignore symbol FE_CAN_QAM_32 +ignore symbol FE_CAN_QAM_64 +ignore symbol FE_CAN_QAM_128 +ignore symbol FE_CAN_QAM_256 +ignore symbol FE_CAN_QAM_AUTO +ignore symbol FE_CAN_TRANSMISSION_MODE_AUTO +ignore symbol FE_CAN_BANDWIDTH_AUTO +ignore symbol FE_CAN_GUARD_INTERVAL_AUTO +ignore symbol FE_CAN_HIERARCHY_AUTO +ignore symbol FE_CAN_8VSB +ignore symbol FE_CAN_16VSB +ignore symbol FE_HAS_EXTENDED_CAPS +ignore symbol FE_CAN_MULTISTREAM +ignore symbol FE_CAN_TURBO_FEC +ignore symbol FE_CAN_2G_MODULATION +ignore symbol FE_NEEDS_BENDING +ignore symbol FE_CAN_RECOVER +ignore symbol FE_CAN_MUTE_TS + +ignore symbol QPSK +ignore symbol QAM_16 +ignore symbol QAM_32 +ignore symbol QAM_64 +ignore symbol QAM_128 +ignore symbol QAM_256 +ignore symbol QAM_AUTO +ignore symbol VSB_8 +ignore symbol VSB_16 +ignore symbol PSK_8 +ignore symbol APSK_16 +ignore symbol APSK_32 +ignore symbol DQPSK +ignore symbol QAM_4_NR + +ignore symbol SEC_VOLTAGE_13 +ignore symbol SEC_VOLTAGE_18 +ignore symbol SEC_VOLTAGE_OFF + +ignore symbol SEC_TONE_ON +ignore symbol SEC_TONE_OFF + +ignore symbol SEC_MINI_A +ignore symbol SEC_MINI_B + +ignore symbol FE_NONE +ignore symbol FE_HAS_SIGNAL +ignore symbol FE_HAS_CARRIER +ignore symbol FE_HAS_VITERBI +ignore symbol FE_HAS_SYNC +ignore symbol FE_HAS_LOCK +ignore symbol FE_REINIT +ignore symbol FE_TIMEDOUT + +ignore symbol FEC_NONE +ignore symbol FEC_1_2 +ignore symbol FEC_2_3 +ignore symbol FEC_3_4 +ignore symbol FEC_4_5 +ignore symbol FEC_5_6 +ignore symbol FEC_6_7 +ignore symbol FEC_7_8 +ignore symbol FEC_8_9 +ignore symbol FEC_AUTO +ignore symbol FEC_3_5 +ignore symbol FEC_9_10 +ignore symbol FEC_2_5 + +ignore symbol TRANSMISSION_MODE_AUTO +ignore symbol TRANSMISSION_MODE_1K +ignore symbol TRANSMISSION_MODE_2K +ignore symbol TRANSMISSION_MODE_8K +ignore symbol TRANSMISSION_MODE_4K +ignore symbol TRANSMISSION_MODE_16K +ignore symbol TRANSMISSION_MODE_32K +ignore symbol TRANSMISSION_MODE_C1 +ignore symbol TRANSMISSION_MODE_C3780 +ignore symbol TRANSMISSION_MODE_2K +ignore symbol TRANSMISSION_MODE_8K + +ignore symbol GUARD_INTERVAL_AUTO +ignore symbol GUARD_INTERVAL_1_128 +ignore symbol GUARD_INTERVAL_1_32 +ignore symbol GUARD_INTERVAL_1_16 +ignore symbol GUARD_INTERVAL_1_8 +ignore symbol GUARD_INTERVAL_1_4 +ignore symbol GUARD_INTERVAL_19_128 +ignore symbol GUARD_INTERVAL_19_256 +ignore symbol GUARD_INTERVAL_PN420 +ignore symbol GUARD_INTERVAL_PN595 +ignore symbol GUARD_INTERVAL_PN945 + +ignore symbol HIERARCHY_NONE +ignore symbol HIERARCHY_AUTO +ignore symbol HIERARCHY_1 +ignore symbol HIERARCHY_2 +ignore symbol HIERARCHY_4 + +ignore symbol INTERLEAVING_NONE +ignore symbol INTERLEAVING_AUTO +ignore symbol INTERLEAVING_240 +ignore symbol INTERLEAVING_720 + +ignore symbol PILOT_ON +ignore symbol PILOT_OFF +ignore symbol PILOT_AUTO + +ignore symbol ROLLOFF_35 +ignore symbol ROLLOFF_20 +ignore symbol ROLLOFF_25 +ignore symbol ROLLOFF_AUTO + +ignore symbol INVERSION_ON +ignore symbol INVERSION_OFF +ignore symbol INVERSION_AUTO + +ignore symbol SYS_UNDEFINED +ignore symbol SYS_DVBC_ANNEX_A +ignore symbol SYS_DVBC_ANNEX_B +ignore symbol SYS_DVBC_ANNEX_C +ignore symbol SYS_ISDBC +ignore symbol SYS_DVBT +ignore symbol SYS_DVBT2 +ignore symbol SYS_ISDBT +ignore symbol SYS_ATSC +ignore symbol SYS_ATSCMH +ignore symbol SYS_DTMB +ignore symbol SYS_DVBS +ignore symbol SYS_DVBS2 +ignore symbol SYS_TURBO +ignore symbol SYS_ISDBS +ignore symbol SYS_DAB +ignore symbol SYS_DSS +ignore symbol SYS_CMMB +ignore symbol SYS_DVBH + +ignore symbol ATSCMH_SCCC_BLK_SEP +ignore symbol ATSCMH_SCCC_BLK_COMB +ignore symbol ATSCMH_SCCC_BLK_RES + +ignore symbol ATSCMH_SCCC_CODE_HLF +ignore symbol ATSCMH_SCCC_CODE_QTR +ignore symbol ATSCMH_SCCC_CODE_RES + +ignore symbol ATSCMH_RSFRAME_ENS_PRI +ignore symbol ATSCMH_RSFRAME_ENS_SEC + +ignore symbol ATSCMH_RSFRAME_PRI_ONLY +ignore symbol ATSCMH_RSFRAME_PRI_SEC +ignore symbol ATSCMH_RSFRAME_RES + +ignore symbol ATSCMH_RSCODE_211_187 +ignore symbol ATSCMH_RSCODE_223_187 +ignore symbol ATSCMH_RSCODE_235_187 +ignore symbol ATSCMH_RSCODE_RES + +ignore symbol FE_SCALE_NOT_AVAILABLE +ignore symbol FE_SCALE_DECIBEL +ignore symbol FE_SCALE_RELATIVE +ignore symbol FE_SCALE_COUNTER diff --git a/Documentation/userspace-api/media/gen-errors.rst b/Documentation/userspace-api/media/gen-errors.rst new file mode 100644 index 000000000..e595d0bea --- /dev/null +++ b/Documentation/userspace-api/media/gen-errors.rst @@ -0,0 +1,96 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _gen_errors: + +******************* +Generic Error Codes +******************* + + +.. _gen-errors: + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: Generic error codes + :header-rows: 0 + :stub-columns: 0 + :widths: 1 16 + + + - - ``EAGAIN`` (aka ``EWOULDBLOCK``) + + - The ioctl can't be handled because the device is in state where it + can't perform it. This could happen for example in case where + device is sleeping and ioctl is performed to query statistics. It + is also returned when the ioctl would need to wait for an event, + but the device was opened in non-blocking mode. + + - - ``EBADF`` + + - The file descriptor is not a valid. + + - - ``EBUSY`` + + - The ioctl can't be handled because the device is busy. This is + typically return while device is streaming, and an ioctl tried to + change something that would affect the stream, or would require + the usage of a hardware resource that was already allocated. The + ioctl must not be retried without performing another action to fix + the problem first (typically: stop the stream before retrying). + + - - ``EFAULT`` + + - There was a failure while copying data from/to userspace, probably + caused by an invalid pointer reference. + + - - ``EINVAL`` + + - One or more of the ioctl parameters are invalid or out of the + allowed range. This is a widely used error code. See the + individual ioctl requests for specific causes. + + - - ``ENODEV`` + + - Device not found or was removed. + + - - ``ENOMEM`` + + - There's not enough memory to handle the desired operation. + + - - ``ENOTTY`` + + - The ioctl is not supported by the driver, actually meaning that + the required functionality is not available, or the file + descriptor is not for a media device. + + - - ``ENOSPC`` + + - On USB devices, the stream ioctl's can return this error, meaning + that this request would overcommit the usb bandwidth reserved for + periodic transfers (up to 80% of the USB bandwidth). + + - - ``EPERM`` + + - Permission denied. Can be returned if the device needs write + permission, or some special capabilities is needed (e. g. root) + + - - ``EIO`` + + - I/O error. Typically used when there are problems communicating with + a hardware device. This could indicate broken or flaky hardware. + It's a 'Something is wrong, I give up!' type of error. + + - - ``ENXIO`` + + - No device corresponding to this device special file exists. + + +.. note:: + + #. This list is not exhaustive; ioctls may return other error codes. + Since errors may have side effects such as a driver reset, + applications should abort on unexpected errors, or otherwise + assume that the device is in a bad state. + + #. Request-specific error codes are listed in the individual + requests descriptions. diff --git a/Documentation/userspace-api/media/glossary.rst b/Documentation/userspace-api/media/glossary.rst new file mode 100644 index 000000000..96a360edb --- /dev/null +++ b/Documentation/userspace-api/media/glossary.rst @@ -0,0 +1,205 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +======== +Glossary +======== + +.. note:: + + The goal of this section is to standardize the terms used within the media + userspace API documentation. This is Work In Progress. + +.. Please keep the glossary entries in alphabetical order + +.. glossary:: + + Bridge Driver + A :term:`Device Driver` that implements the main logic to talk with + media hardware. + + CEC API + **Consumer Electronics Control API** + + An API designed to receive and transmit data via an HDMI + CEC interface. + + See :ref:`cec`. + + Device Driver + Part of the Linux Kernel that implements support for a hardware + component. + + Device Node + A character device node in the file system used to control and + transfer data in and out of a Kernel driver. + + Digital TV API + **Previously known as DVB API** + + An API designed to control a subset of the :term:`Media Hardware` + that implements digital TV (e. g. DVB, ATSC, ISDB, etc). + + See :ref:`dvbapi`. + + DSP + **Digital Signal Processor** + + A specialized :term:`Microprocessor`, with its architecture + optimized for the operational needs of digital signal processing. + + FPGA + **Field-programmable Gate Array** + + An :term:`IC` circuit designed to be configured by a customer or + a designer after manufacturing. + + See https://en.wikipedia.org/wiki/Field-programmable_gate_array. + + Hardware Component + A subset of the :term:`Media Hardware`. For example an :term:`I²C` or + :term:`SPI` device, or an :term:`IP Block` inside an + :term:`SoC` or :term:`FPGA`. + + Hardware Peripheral + A group of :term:`hardware components ` that + together make a larger user-facing functional peripheral. For + instance, the :term:`SoC` :term:`ISP` :term:`IP Block` + and the external camera sensors together make a camera hardware + peripheral. + + Also known as :term:`Peripheral`. + + I²C + **Inter-Integrated Circuit** + + A multi-master, multi-slave, packet switched, single-ended, + serial computer bus used to control some hardware components + like sub-device hardware components. + + See http://www.nxp.com/docs/en/user-guide/UM10204.pdf. + + IC + **Integrated circuit** + + A set of electronic circuits on one small flat piece of + semiconductor material, normally silicon. + + Also known as chip. + + IP Block + **Intellectual property core** + + In electronic design a semiconductor intellectual property core, + is a reusable unit of logic, cell, or integrated circuit layout + design that is the intellectual property of one party. + IP Blocks may be licensed to another party or can be owned + and used by a single party alone. + + See https://en.wikipedia.org/wiki/Semiconductor_intellectual_property_core). + + ISP + **Image Signal Processor** + + A specialized processor that implements a set of algorithms for + processing image data. ISPs may implement algorithms for lens + shading correction, demosaicing, scaling and pixel format conversion + as well as produce statistics for the use of the control + algorithms (e.g. automatic exposure, white balance and focus). + + Media API + A set of userspace APIs used to control the media hardware. It is + composed by: + + - :term:`CEC API`; + - :term:`Digital TV API`; + - :term:`MC API`; + - :term:`RC API`; and + - :term:`V4L2 API`. + + See Documentation/userspace-api/media/index.rst. + + MC API + **Media Controller API** + + An API designed to expose and control the relationships between + multimedia devices and sub-devices. + + See :ref:`media_controller`. + + MC-centric + :term:`V4L2 Hardware` device driver that requires :term:`MC API`. + + Such drivers have ``V4L2_CAP_IO_MC`` device_caps field set + (see :ref:`VIDIOC_QUERYCAP`). + + See :ref:`v4l2_hardware_control` for more details. + + Media Hardware + Subset of the hardware that is supported by the Linux Media API. + + This includes audio and video capture and playback hardware, + digital and analog TV, camera sensors, ISPs, remote controllers, + codecs, HDMI Consumer Electronics Control, HDMI capture, etc. + + Microprocessor + Electronic circuitry that carries out the instructions of a + computer program by performing the basic arithmetic, logical, + control and input/output (I/O) operations specified by the + instructions on a single integrated circuit. + + Peripheral + The same as :term:`Hardware Peripheral`. + + RC API + **Remote Controller API** + + An API designed to receive and transmit data from remote + controllers. + + See :ref:`remote_controllers`. + + SMBus + A subset of I²C, which defines a stricter usage of the bus. + + SPI + **Serial Peripheral Interface Bus** + + Synchronous serial communication interface specification used for + short distance communication, primarily in embedded systems. + + SoC + **System on a Chip** + + An integrated circuit that integrates all components of a computer + or other electronic systems. + + V4L2 API + **V4L2 userspace API** + + The userspace API defined in :ref:`v4l2spec`, which is used to + control a V4L2 hardware. + + V4L2 Device Node + A :term:`Device Node` that is associated to a V4L driver. + + The V4L2 device node naming is specified at :ref:`v4l2_device_naming`. + + V4L2 Hardware + Part of the media hardware which is supported by the :term:`V4L2 API`. + + V4L2 Sub-device + V4L2 hardware components that aren't controlled by a + :term:`Bridge Driver`. See :ref:`subdev`. + + Video-node-centric + V4L2 device driver that doesn't require a media controller to be used. + + Such drivers have the ``V4L2_CAP_IO_MC`` device_caps field unset + (see :ref:`VIDIOC_QUERYCAP`). + + V4L2 Sub-device API + Part of the :term:`V4L2 API` which control + :term:`V4L2 sub-devices `, like sensors, + HDMI receivers, scalers, deinterlacers. + + See :ref:`v4l2_hardware_control` for more details. diff --git a/Documentation/userspace-api/media/index.rst b/Documentation/userspace-api/media/index.rst new file mode 100644 index 000000000..d839904be --- /dev/null +++ b/Documentation/userspace-api/media/index.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. include:: + +######################################## +Linux Media Infrastructure userspace API +######################################## + +This section contains the driver development information and Kernel APIs +used by media devices. + +Please see: + +Documentation/admin-guide/media/index.rst + + - for usage information about media subsystem and supported drivers; + +Documentation/driver-api/media/index.rst + + - for driver development information and Kernel APIs used by + media devices; + + +.. only:: html + + .. class:: toc-title + + Table of Contents + +.. toctree:: + :maxdepth: 1 + + intro + v4l/v4l2 + dvb/dvbapi + rc/remote_controllers + mediactl/media-controller + cec/cec-api + gen-errors + + glossary + + fdl-appendix + + drivers/index + +**Copyright** |copy| 2009-2020 : LinuxTV Developers + +:: + + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 or + any later version published by the Free Software Foundation, with no + Invariant Sections. A copy of the license is included in the chapter + entitled "GNU Free Documentation License". + +Please notice that some documents inside the media userspace API, +when explicitly mentioned on its source code, are dual-licensed +with GNU Free Documentation License Version 1.1 and with the +GNU General Public License:: + + This documentation is free software; you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by the Free + Software Foundation; either version 2 of the License, or (at your option) any + later version. + + This program is distributed in the hope that it will be useful, but WITHOUT + ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + more details. + + For more details see the file COPYING in the source distribution of Linux. diff --git a/Documentation/userspace-api/media/intro.rst b/Documentation/userspace-api/media/intro.rst new file mode 100644 index 000000000..4a6bd665b --- /dev/null +++ b/Documentation/userspace-api/media/intro.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +Introduction +============ + +This document covers the Linux Kernel to Userspace API's used by video +and radio streaming devices, including video cameras, analog and digital +TV receiver cards, AM/FM receiver cards, Software Defined Radio (SDR), +streaming capture and output devices, codec devices and remote controllers. + +A typical media device hardware is shown at :ref:`typical_media_device`. + +.. _typical_media_device: + +.. kernel-figure:: typical_media_device.svg + :alt: typical_media_device.svg + :align: center + + Typical Media Device + +The media infrastructure API was designed to control such devices. It is +divided into five parts. + +1. The :ref:`first part ` covers radio, video capture and output, + cameras, analog TV devices and codecs. + +2. The :ref:`second part ` covers the API used for digital TV and + Internet reception via one of the several digital tv standards. While it is + called as DVB API, in fact it covers several different video standards + including DVB-T/T2, DVB-S/S2, DVB-C, ATSC, ISDB-T, ISDB-S, DTMB, etc. The + complete list of supported standards can be found at + :c:type:`fe_delivery_system`. + +3. The :ref:`third part ` covers the Remote Controller API. + +4. The :ref:`fourth part ` covers the Media Controller API. + +5. The :ref:`fifth part ` covers the CEC (Consumer Electronics Control) API. + +It should also be noted that a media device may also have audio components, like +mixers, PCM capture, PCM playback, etc, which are controlled via ALSA API. For +additional information and for the latest development code, see: +`https://linuxtv.org `__. For discussing improvements, +reporting troubles, sending new drivers, etc, please mail to: `Linux Media +Mailing List (LMML) `__. diff --git a/Documentation/userspace-api/media/lirc.h.rst.exceptions b/Documentation/userspace-api/media/lirc.h.rst.exceptions new file mode 100644 index 000000000..1aeb7d7af --- /dev/null +++ b/Documentation/userspace-api/media/lirc.h.rst.exceptions @@ -0,0 +1,87 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Ignore header name +ignore define _LINUX_LIRC_H + +# Ignore helper macros + +ignore define lirc_t + +ignore define LIRC_SPACE +ignore define LIRC_PULSE +ignore define LIRC_FREQUENCY +ignore define LIRC_TIMEOUT +ignore define LIRC_OVERFLOW +ignore define LIRC_VALUE +ignore define LIRC_MODE2 +ignore define LIRC_IS_SPACE +ignore define LIRC_IS_PULSE +ignore define LIRC_IS_FREQUENCY +ignore define LIRC_IS_TIMEOUT +ignore define LIRC_IS_OVERFLOW + +ignore define LIRC_MODE2SEND +ignore define LIRC_SEND2MODE +ignore define LIRC_MODE2REC +ignore define LIRC_REC2MODE + +ignore define LIRC_CAN_SEND +ignore define LIRC_CAN_REC + +ignore define LIRC_CAN_SEND_MASK +ignore define LIRC_CAN_REC_MASK +ignore define LIRC_CAN_SET_REC_FILTER +ignore define LIRC_CAN_NOTIFY_DECODE + +# Obsolete ioctls + +ignore ioctl LIRC_GET_LENGTH +ignore ioctl LIRC_SET_REC_TIMEOUT_REPORTS + +# rc protocols + +ignore symbol RC_PROTO_UNKNOWN +ignore symbol RC_PROTO_OTHER +ignore symbol RC_PROTO_RC5 +ignore symbol RC_PROTO_RC5X_20 +ignore symbol RC_PROTO_RC5_SZ +ignore symbol RC_PROTO_JVC +ignore symbol RC_PROTO_SONY12 +ignore symbol RC_PROTO_SONY15 +ignore symbol RC_PROTO_SONY20 +ignore symbol RC_PROTO_NEC +ignore symbol RC_PROTO_NECX +ignore symbol RC_PROTO_NEC32 +ignore symbol RC_PROTO_SANYO +ignore symbol RC_PROTO_MCIR2_KBD +ignore symbol RC_PROTO_MCIR2_MSE +ignore symbol RC_PROTO_RC6_0 +ignore symbol RC_PROTO_RC6_6A_20 +ignore symbol RC_PROTO_RC6_6A_24 +ignore symbol RC_PROTO_RC6_6A_32 +ignore symbol RC_PROTO_RC6_MCE +ignore symbol RC_PROTO_SHARP +ignore symbol RC_PROTO_XMP +ignore symbol RC_PROTO_CEC +ignore symbol RC_PROTO_IMON +ignore symbol RC_PROTO_RCMM12 +ignore symbol RC_PROTO_RCMM24 +ignore symbol RC_PROTO_RCMM32 +ignore symbol RC_PROTO_XBOX_DVD +ignore symbol RC_PROTO_MAX + +# Undocumented macros + +ignore define PULSE_BIT +ignore define PULSE_MASK + +ignore define LIRC_MODE2_SPACE +ignore define LIRC_MODE2_PULSE +ignore define LIRC_MODE2_TIMEOUT +ignore define LIRC_MODE2_OVERFLOW + +ignore define LIRC_VALUE_MASK +ignore define LIRC_MODE2_MASK + +ignore define LIRC_MODE_RAW +ignore define LIRC_MODE_LIRCCODE diff --git a/Documentation/userspace-api/media/media.h.rst.exceptions b/Documentation/userspace-api/media/media.h.rst.exceptions new file mode 100644 index 000000000..9b4c26502 --- /dev/null +++ b/Documentation/userspace-api/media/media.h.rst.exceptions @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Ignore header name +ignore define __LINUX_MEDIA_H + +# Ignore macros +ignore define MEDIA_API_VERSION +ignore define MEDIA_ENT_F_BASE +ignore define MEDIA_ENT_F_OLD_BASE +ignore define MEDIA_ENT_F_OLD_SUBDEV_BASE +ignore define MEDIA_ENT_F_DTV_DECODER +ignore define MEDIA_INTF_T_DVB_BASE +ignore define MEDIA_INTF_T_V4L_BASE +ignore define MEDIA_INTF_T_ALSA_BASE +#ignore legacy entity type macros +ignore define MEDIA_ENT_TYPE_SHIFT +ignore define MEDIA_ENT_TYPE_MASK +ignore define MEDIA_ENT_SUBTYPE_MASK +ignore define MEDIA_ENT_T_DEVNODE_UNKNOWN +ignore define MEDIA_ENT_T_DEVNODE +ignore define MEDIA_ENT_T_DEVNODE_V4L +ignore define MEDIA_ENT_T_DEVNODE_FB +ignore define MEDIA_ENT_T_DEVNODE_ALSA +ignore define MEDIA_ENT_T_DEVNODE_DVB +ignore define MEDIA_ENT_T_UNKNOWN +ignore define MEDIA_ENT_T_V4L2_VIDEO +ignore define MEDIA_ENT_T_V4L2_SUBDEV +ignore define MEDIA_ENT_T_V4L2_SUBDEV_SENSOR +ignore define MEDIA_ENT_T_V4L2_SUBDEV_FLASH +ignore define MEDIA_ENT_T_V4L2_SUBDEV_LENS +ignore define MEDIA_ENT_T_V4L2_SUBDEV_DECODER +ignore define MEDIA_ENT_T_V4L2_SUBDEV_TUNER diff --git a/Documentation/userspace-api/media/mediactl/media-controller-intro.rst b/Documentation/userspace-api/media/mediactl/media-controller-intro.rst new file mode 100644 index 000000000..fce7eafc3 --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-controller-intro.rst @@ -0,0 +1,33 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _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/userspace-api/media/mediactl/media-controller-model.rst b/Documentation/userspace-api/media/mediactl/media-controller-model.rst new file mode 100644 index 000000000..78bfdfb2a --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-controller-model.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _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. + +- An **ancillary link** is a point-to-point connection denoting that two + entities form a single logical unit. For example this could represent the + fact that a particular camera sensor and lens controller form a single + physical module, meaning this lens controller drives the lens for this + camera sensor. \ No newline at end of file diff --git a/Documentation/userspace-api/media/mediactl/media-controller.rst b/Documentation/userspace-api/media/mediactl/media-controller.rst new file mode 100644 index 000000000..508dd693b --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-controller.rst @@ -0,0 +1,54 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. include:: + +.. _media_controller: + +############################## +Part IV - Media Controller API +############################## + +.. only:: html + + .. class:: toc-title + + Table of Contents + +.. toctree:: + :maxdepth: 5 + :numbered: + + media-controller-intro + media-controller-model + media-types + request-api + media-funcs + media-header + + +********************** +Revision and Copyright +********************** + +Authors: + +- Pinchart, Laurent + + - Initial version. + +- Carvalho Chehab, Mauro + + - MEDIA_IOC_G_TOPOLOGY documentation and documentation improvements. + +**Copyright** |copy| 2010 : Laurent Pinchart + +**Copyright** |copy| 2015-2016 : Mauro Carvalho Chehab + +**************** +Revision History +**************** + +:revision: 1.1.0 / 2015-12-12 (*mcc*) + +:revision: 1.0.0 / 2010-11-10 (*lp*) + +Initial revision diff --git a/Documentation/userspace-api/media/mediactl/media-func-close.rst b/Documentation/userspace-api/media/mediactl/media-func-close.rst new file mode 100644 index 000000000..8ac2443e7 --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-func-close.rst @@ -0,0 +1,43 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _media-func-close: + +************* +media close() +************* + +Name +==== + +media-close - Close a media device + +Synopsis +======== + +.. code-block:: c + + #include + +.. c:function:: int close( int fd ) + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +Description +=========== + +Closes the media device. Resources associated with the file descriptor +are freed. The device configuration remain unchanged. + +Return Value +============ + +:c:func:`close()` returns 0 on success. On error, -1 is returned, and +``errno`` is set appropriately. Possible error codes are: + +EBADF + ``fd`` is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst b/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst new file mode 100644 index 000000000..9e9a838f4 --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-func-ioctl.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _media-func-ioctl: + +************* +media ioctl() +************* + +Name +==== + +media-ioctl - Control a media device + +Synopsis +======== + +.. code-block:: c + + #include + +``int ioctl(int fd, int request, void *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``request`` + Media ioctl request code as defined in the media.h header file, for + example MEDIA_IOC_SETUP_LINK. + +``argp`` + Pointer to a request-specific structure. + +Description +=========== + +The :ref:`ioctl() ` function manipulates media device +parameters. The argument ``fd`` must be an open file descriptor. + +The ioctl ``request`` code specifies the media function to be called. It +has encoded in it whether the argument is an input, output or read/write +parameter, and the size of the argument ``argp`` in bytes. + +Macros and structures definitions specifying media ioctl requests and +their parameters are located in the media.h header file. All media ioctl +requests, their respective function and parameters are specified in +:ref:`media-user-func`. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +Request-specific error codes are listed in the individual requests +descriptions. + +When an ioctl that takes an output or read/write parameter fails, the +parameter remains unmodified. diff --git a/Documentation/userspace-api/media/mediactl/media-func-open.rst b/Documentation/userspace-api/media/mediactl/media-func-open.rst new file mode 100644 index 000000000..24487cb0a --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-func-open.rst @@ -0,0 +1,65 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _media-func-open: + +************ +media open() +************ + +Name +==== + +media-open - Open a media device + +Synopsis +======== + +.. code-block:: c + + #include + +.. c:function:: int open( const char *device_name, int flags ) + +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 :c:func:`open()` with the +desired device name. The function has no side effects; the device +configuration remain unchanged. + +When the device is opened in read-only mode, attempts to modify its +configuration will result in an error, and ``errno`` will be set to +EBADF. + +Return Value +============ + +:c:func:`open()` returns the new file descriptor on success. On error, +-1 is returned, and ``errno`` is set appropriately. Possible error codes +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/userspace-api/media/mediactl/media-funcs.rst b/Documentation/userspace-api/media/mediactl/media-funcs.rst new file mode 100644 index 000000000..e89629681 --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-funcs.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _media-user-func: + +****************** +Function Reference +****************** + + +.. toctree:: + :maxdepth: 1 + + media-func-open + media-func-close + media-func-ioctl + media-ioc-device-info + media-ioc-g-topology + media-ioc-enum-entities + media-ioc-enum-links + media-ioc-setup-link + media-ioc-request-alloc + request-func-close + request-func-ioctl + request-func-poll + media-request-ioc-queue + media-request-ioc-reinit diff --git a/Documentation/userspace-api/media/mediactl/media-header.rst b/Documentation/userspace-api/media/mediactl/media-header.rst new file mode 100644 index 000000000..c674271c9 --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-header.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _media_header: + +**************************** +Media Controller Header File +**************************** + +.. kernel-include:: $BUILDDIR/media.h.rst + diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst new file mode 100644 index 000000000..d56ee6669 --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-ioc-device-info.rst @@ -0,0 +1,106 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _media_ioc_device_info: + +*************************** +ioctl MEDIA_IOC_DEVICE_INFO +*************************** + +Name +==== + +MEDIA_IOC_DEVICE_INFO - Query device information + +Synopsis +======== + +.. c:macro:: MEDIA_IOC_DEVICE_INFO + +``int ioctl(int fd, MEDIA_IOC_DEVICE_INFO, struct media_device_info *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`media_device_info`. + +Description +=========== + +All media devices must support the ``MEDIA_IOC_DEVICE_INFO`` ioctl. To +query device information, applications call the ioctl with a pointer to +a struct :c:type:`media_device_info`. The driver +fills the structure and returns the information to the application. The +ioctl never fails. + +.. c:type:: media_device_info + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. flat-table:: struct media_device_info + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - char + - ``driver``\ [16] + - Name of the driver implementing the media API as a NUL-terminated + ASCII string. The driver version is stored in the + ``driver_version`` field. + + Driver specific applications can use this information to verify + the driver identity. It is also useful to work around known bugs, + or to identify drivers in error reports. + + * - char + - ``model``\ [32] + - Device model name as a NUL-terminated UTF-8 string. The device + version is stored in the ``device_version`` field and is not be + appended to the model name. + + * - char + - ``serial``\ [40] + - Serial number as a NUL-terminated ASCII string. + + * - char + - ``bus_info``\ [32] + - Location of the device in the system as a NUL-terminated ASCII + string. This includes the bus type name (PCI, USB, ...) and a + bus-specific identifier. + + * - __u32 + - ``media_version`` + - Media API version, formatted with the ``KERNEL_VERSION()`` macro. + + * - __u32 + - ``hw_revision`` + - Hardware device revision in a driver-specific format. + + * - __u32 + - ``driver_version`` + - Media device driver version, formatted with the + ``KERNEL_VERSION()`` macro. Together with the ``driver`` field + this identifies a particular driver. + + * - __u32 + - ``reserved``\ [31] + - Reserved for future extensions. Drivers and applications must set + this array to zero. + +The ``serial`` and ``bus_info`` fields can be used to distinguish +between multiple instances of otherwise identical hardware. The serial +number takes precedence when provided and can be assumed to be unique. +If the serial number is an empty string, the ``bus_info`` field can be +used instead. The ``bus_info`` field is guaranteed to be unique, but can +vary across reboots or device unplug/replug. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst new file mode 100644 index 000000000..73bda0249 --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-entities.rst @@ -0,0 +1,146 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _media_ioc_enum_entities: + +***************************** +ioctl MEDIA_IOC_ENUM_ENTITIES +***************************** + +Name +==== + +MEDIA_IOC_ENUM_ENTITIES - Enumerate entities and their properties + +Synopsis +======== + +.. c:macro:: MEDIA_IOC_ENUM_ENTITIES + +``int ioctl(int fd, MEDIA_IOC_ENUM_ENTITIES, struct media_entity_desc *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`media_entity_desc`. + +Description +=========== + +To query the attributes of an entity, applications set the id field of a +struct :c:type:`media_entity_desc` structure and +call the MEDIA_IOC_ENUM_ENTITIES ioctl with a pointer to this +structure. The driver fills the rest of the structure or returns an +EINVAL error code when the id is invalid. + +.. _media-ent-id-flag-next: + +Entities can be enumerated by or'ing the id with the +``MEDIA_ENT_ID_FLAG_NEXT`` flag. The driver will return information +about the entity with the smallest id strictly larger than the requested +one ('next entity'), or the ``EINVAL`` error code if there is none. + +Entity IDs can be non-contiguous. Applications must *not* try to +enumerate entities by calling MEDIA_IOC_ENUM_ENTITIES with increasing +id's until they get an error. + +.. c:type:: media_entity_desc + +.. tabularcolumns:: |p{1.5cm}|p{1.7cm}|p{1.6cm}|p{1.5cm}|p{10.6cm}| + +.. flat-table:: struct media_entity_desc + :header-rows: 0 + :stub-columns: 0 + :widths: 2 2 1 8 + + * - __u32 + - ``id`` + - + - Entity ID, set by the application. When the ID is or'ed with + ``MEDIA_ENT_ID_FLAG_NEXT``, the driver clears the flag and returns + the first entity with a larger ID. Do not expect that the ID will + always be the same for each instance of the device. In other words, + do not hardcode entity IDs in an application. + + * - char + - ``name``\ [32] + - + - Entity name as an UTF-8 NULL-terminated string. This name must be unique + within the media topology. + + * - __u32 + - ``type`` + - + - Entity type, see :ref:`media-entity-functions` for details. + + * - __u32 + - ``revision`` + - + - Entity revision. Always zero (obsolete) + + * - __u32 + - ``flags`` + - + - Entity flags, see :ref:`media-entity-flag` for details. + + * - __u32 + - ``group_id`` + - + - Entity group ID. Always zero (obsolete) + + * - __u16 + - ``pads`` + - + - Number of pads + + * - __u16 + - ``links`` + - + - Total number of outbound links. Inbound links are not counted in + this field. + + * - __u32 + - ``reserved[4]`` + - + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + * - union { + - (anonymous) + + * - struct + - ``dev`` + - + - Valid for (sub-)devices that create a single device node. + + * - + - __u32 + - ``major`` + - Device node major number. + + * - + - __u32 + - ``minor`` + - Device node minor number. + + * - __u8 + - ``raw``\ [184] + - + - + * - } + - + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EINVAL + The struct :c:type:`media_entity_desc` ``id`` + references a non-existing entity. diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst new file mode 100644 index 000000000..381804a91 --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-ioc-enum-links.rst @@ -0,0 +1,145 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _media_ioc_enum_links: + +************************** +ioctl MEDIA_IOC_ENUM_LINKS +************************** + +Name +==== + +MEDIA_IOC_ENUM_LINKS - Enumerate all pads and links for a given entity + +Synopsis +======== + +.. c:macro:: MEDIA_IOC_ENUM_LINKS + +``int ioctl(int fd, MEDIA_IOC_ENUM_LINKS, struct media_links_enum *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`media_links_enum`. + +Description +=========== + +To enumerate pads and/or links for a given entity, applications set the +entity field of a struct :c:type:`media_links_enum` +structure and initialize the struct +:c:type:`media_pad_desc` and struct +:c:type:`media_link_desc` structure arrays pointed by +the ``pads`` and ``links`` fields. They then call the +MEDIA_IOC_ENUM_LINKS ioctl with a pointer to this structure. + +If the ``pads`` field is not NULL, the driver fills the ``pads`` array +with information about the entity's pads. The array must have enough +room to store all the entity's pads. The number of pads can be retrieved +with :ref:`MEDIA_IOC_ENUM_ENTITIES`. + +If the ``links`` field is not NULL, the driver fills the ``links`` array +with information about the entity's outbound links. The array must have +enough room to store all the entity's outbound links. The number of +outbound links can be retrieved with :ref:`MEDIA_IOC_ENUM_ENTITIES`. + +Only forward links that originate at one of the entity's source pads are +returned during the enumeration process. + +.. c:type:: media_links_enum + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. flat-table:: struct media_links_enum + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``entity`` + - Entity id, set by the application. + + * - struct :c:type:`media_pad_desc` + - \*\ ``pads`` + - Pointer to a pads array allocated by the application. Ignored if + NULL. + + * - struct :c:type:`media_link_desc` + - \*\ ``links`` + - Pointer to a links array allocated by the application. Ignored if + NULL. + + * - __u32 + - ``reserved[4]`` + - Reserved for future extensions. Drivers and applications must set + the array to zero. + +.. c:type:: media_pad_desc + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. flat-table:: struct media_pad_desc + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``entity`` + - ID of the entity this pad belongs to. + + * - __u16 + - ``index`` + - Pad index, starts at 0. + + * - __u32 + - ``flags`` + - Pad flags, see :ref:`media-pad-flag` for more details. + + * - __u32 + - ``reserved[2]`` + - Reserved for future extensions. Drivers and applications must set + the array to zero. + + +.. c:type:: media_link_desc + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. flat-table:: struct media_link_desc + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - struct :c:type:`media_pad_desc` + - ``source`` + - Pad at the origin of this link. + + * - struct :c:type:`media_pad_desc` + - ``sink`` + - Pad at the target of this link. + + * - __u32 + - ``flags`` + - Link flags, see :ref:`media-link-flag` for more details. + + * - __u32 + - ``reserved[2]`` + - Reserved for future extensions. Drivers and applications must set + the array to zero. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EINVAL + The struct :c:type:`media_links_enum` ``id`` + references a non-existing entity. diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst new file mode 100644 index 000000000..77ea5c5e9 --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-ioc-g-topology.rst @@ -0,0 +1,294 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _media_ioc_g_topology: + +************************** +ioctl MEDIA_IOC_G_TOPOLOGY +************************** + +Name +==== + +MEDIA_IOC_G_TOPOLOGY - Enumerate the graph topology and graph element properties + +Synopsis +======== + +.. c:macro:: MEDIA_IOC_G_TOPOLOGY + +``int ioctl(int fd, MEDIA_IOC_G_TOPOLOGY, struct media_v2_topology *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`media_v2_topology`. + +Description +=========== + +The typical usage of this ioctl is to call it twice. On the first call, +the structure defined at struct +:c:type:`media_v2_topology` should be zeroed. At +return, if no errors happen, this ioctl will return the +``topology_version`` and the total number of entities, interfaces, pads +and links. + +Before the second call, the userspace should allocate arrays to store +the graph elements that are desired, putting the pointers to them at the +ptr_entities, ptr_interfaces, ptr_links and/or ptr_pads, keeping the +other values untouched. + +If the ``topology_version`` remains the same, the ioctl should fill the +desired arrays with the media graph elements. + +.. tabularcolumns:: |p{1.6cm}|p{3.4cm}|p{12.3cm}| + +.. c:type:: media_v2_topology + +.. flat-table:: struct media_v2_topology + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + * - __u64 + - ``topology_version`` + - Version of the media graph topology. When the graph is created, + this field starts with zero. Every time a graph element is added + or removed, this field is incremented. + + * - __u32 + - ``num_entities`` + - Number of entities in the graph + + * - __u32 + - ``reserved1`` + - Applications and drivers shall set this to 0. + + * - __u64 + - ``ptr_entities`` + - A pointer to a memory area where the entities array will be + stored, converted to a 64-bits integer. It can be zero. if zero, + the ioctl won't store the entities. It will just update + ``num_entities`` + + * - __u32 + - ``num_interfaces`` + - Number of interfaces in the graph + + * - __u32 + - ``reserved2`` + - Applications and drivers shall set this to 0. + + * - __u64 + - ``ptr_interfaces`` + - A pointer to a memory area where the interfaces array will be + stored, converted to a 64-bits integer. It can be zero. if zero, + the ioctl won't store the interfaces. It will just update + ``num_interfaces`` + + * - __u32 + - ``num_pads`` + - Total number of pads in the graph + + * - __u32 + - ``reserved3`` + - Applications and drivers shall set this to 0. + + * - __u64 + - ``ptr_pads`` + - A pointer to a memory area where the pads array will be stored, + converted to a 64-bits integer. It can be zero. if zero, the ioctl + won't store the pads. It will just update ``num_pads`` + + * - __u32 + - ``num_links`` + - Total number of data and interface links in the graph + + * - __u32 + - ``reserved4`` + - Applications and drivers shall set this to 0. + + * - __u64 + - ``ptr_links`` + - A pointer to a memory area where the links array will be stored, + converted to a 64-bits integer. It can be zero. if zero, the ioctl + won't store the links. It will just update ``num_links`` + +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| + +.. c:type:: media_v2_entity + +.. flat-table:: struct media_v2_entity + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + * - __u32 + - ``id`` + - Unique ID for the entity. Do not expect that the ID will + always be the same for each instance of the device. In other words, + do not hardcode entity IDs in an application. + + * - char + - ``name``\ [64] + - Entity name as an UTF-8 NULL-terminated string. This name must be unique + within the media topology. + + * - __u32 + - ``function`` + - Entity main function, see :ref:`media-entity-functions` for details. + + * - __u32 + - ``flags`` + - Entity flags, see :ref:`media-entity-flag` for details. + Only valid if ``MEDIA_V2_ENTITY_HAS_FLAGS(media_version)`` + returns true. The ``media_version`` is defined in struct + :c:type:`media_device_info` and can be retrieved using + :ref:`MEDIA_IOC_DEVICE_INFO`. + + * - __u32 + - ``reserved``\ [5] + - Reserved for future extensions. Drivers and applications must set + this array to zero. + +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| + +.. c:type:: media_v2_interface + +.. flat-table:: struct media_v2_interface + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + * - __u32 + - ``id`` + - Unique ID for the interface. Do not expect that the ID will + always be the same for each instance of the device. In other words, + do not hardcode interface IDs in an application. + + * - __u32 + - ``intf_type`` + - Interface type, see :ref:`media-intf-type` for details. + + * - __u32 + - ``flags`` + - Interface flags. Currently unused. + + * - __u32 + - ``reserved``\ [9] + - Reserved for future extensions. Drivers and applications must set + this array to zero. + + * - struct media_v2_intf_devnode + - ``devnode`` + - Used only for device node interfaces. See + :c:type:`media_v2_intf_devnode` for details. + +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| + +.. c:type:: media_v2_intf_devnode + +.. flat-table:: struct media_v2_intf_devnode + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + * - __u32 + - ``major`` + - Device node major number. + + * - __u32 + - ``minor`` + - Device node minor number. + +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| + +.. c:type:: media_v2_pad + +.. flat-table:: struct media_v2_pad + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + * - __u32 + - ``id`` + - Unique ID for the pad. Do not expect that the ID will + always be the same for each instance of the device. In other words, + do not hardcode pad IDs in an application. + + * - __u32 + - ``entity_id`` + - Unique ID for the entity where this pad belongs. + + * - __u32 + - ``flags`` + - Pad flags, see :ref:`media-pad-flag` for more details. + + * - __u32 + - ``index`` + - Pad index, starts at 0. Only valid if ``MEDIA_V2_PAD_HAS_INDEX(media_version)`` + returns true. The ``media_version`` is defined in struct + :c:type:`media_device_info` and can be retrieved using + :ref:`MEDIA_IOC_DEVICE_INFO`. + + * - __u32 + - ``reserved``\ [4] + - Reserved for future extensions. Drivers and applications must set + this array to zero. + +.. tabularcolumns:: |p{1.6cm}|p{3.2cm}|p{12.5cm}| + +.. c:type:: media_v2_link + +.. flat-table:: struct media_v2_link + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 8 + + * - __u32 + - ``id`` + - Unique ID for the link. Do not expect that the ID will + always be the same for each instance of the device. In other words, + do not hardcode link IDs in an application. + + * - __u32 + - ``source_id`` + - On pad to pad links: unique ID for the source pad. + + On interface to entity links: unique ID for the interface. + + * - __u32 + - ``sink_id`` + - On pad to pad links: unique ID for the sink pad. + + On interface to entity links: unique ID for the entity. + + * - __u32 + - ``flags`` + - Link flags, see :ref:`media-link-flag` for more details. + + * - __u32 + - ``reserved``\ [6] + - Reserved for future extensions. Drivers and applications must set + this array to zero. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +ENOSPC + This is returned when either one or more of the num_entities, + num_interfaces, num_links or num_pads are non-zero and are + smaller than the actual number of elements inside the graph. This + may happen if the ``topology_version`` changed when compared to the + last time this ioctl was called. Userspace should usually free the + area for the pointers, zero the struct elements and call this ioctl + again. diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst b/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst new file mode 100644 index 000000000..9195b4b8b --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-ioc-request-alloc.rst @@ -0,0 +1,65 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _media_ioc_request_alloc: + +***************************** +ioctl MEDIA_IOC_REQUEST_ALLOC +***************************** + +Name +==== + +MEDIA_IOC_REQUEST_ALLOC - Allocate a request + +Synopsis +======== + +.. c:macro:: MEDIA_IOC_REQUEST_ALLOC + +``int ioctl(int fd, MEDIA_IOC_REQUEST_ALLOC, int *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to an integer. + +Description +=========== + +If the media device supports :ref:`requests `, then +this ioctl can be used to allocate a request. If it is not supported, then +``errno`` is set to ``ENOTTY``. A request is accessed through a file descriptor +that is returned in ``*argp``. + +If the request was successfully allocated, then the request file descriptor +can be passed to the :ref:`VIDIOC_QBUF `, +:ref:`VIDIOC_G_EXT_CTRLS `, +:ref:`VIDIOC_S_EXT_CTRLS ` and +:ref:`VIDIOC_TRY_EXT_CTRLS ` ioctls. + +In addition, the request can be queued by calling +:ref:`MEDIA_REQUEST_IOC_QUEUE` and re-initialized by calling +:ref:`MEDIA_REQUEST_IOC_REINIT`. + +Finally, the file descriptor can be :ref:`polled ` to wait +for the request to complete. + +The request will remain allocated until all the file descriptors associated +with it are closed by :c:func:`close()` and the driver no +longer uses the request internally. See also +:ref:`here ` for more information. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +ENOTTY + The driver has no support for requests. diff --git a/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst b/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst new file mode 100644 index 000000000..23208300c --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-ioc-setup-link.rst @@ -0,0 +1,65 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _media_ioc_setup_link: + +************************** +ioctl MEDIA_IOC_SETUP_LINK +************************** + +Name +==== + +MEDIA_IOC_SETUP_LINK - Modify the properties of a link + +Synopsis +======== + +.. c:macro:: MEDIA_IOC_SETUP_LINK + +``int ioctl(int fd, MEDIA_IOC_SETUP_LINK, struct media_link_desc *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :c:func:`open()`. + +``argp`` + Pointer to struct :c:type:`media_link_desc`. + +Description +=========== + +To change link properties applications fill a struct +:c:type:`media_link_desc` with link identification +information (source and sink pad) and the new requested link flags. They +then call the MEDIA_IOC_SETUP_LINK ioctl with a pointer to that +structure. + +The only configurable property is the ``ENABLED`` link flag to +enable/disable a link. Links marked with the ``IMMUTABLE`` link flag can +not be enabled or disabled. + +Link configuration has no side effect on other links. If an enabled link +at the sink pad prevents the link from being enabled, the driver returns +with an ``EBUSY`` error code. + +Only links marked with the ``DYNAMIC`` link flag can be enabled/disabled +while streaming media data. Attempting to enable or disable a streaming +non-dynamic link will return an ``EBUSY`` error code. + +If the specified link can't be found the driver returns with an ``EINVAL`` +error code. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EINVAL + The struct :c:type:`media_link_desc` references a + non-existing link, or the link is immutable and an attempt to modify + its configuration was made. diff --git a/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst b/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst new file mode 100644 index 000000000..04b33db2b --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-request-ioc-queue.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _media_request_ioc_queue: + +***************************** +ioctl MEDIA_REQUEST_IOC_QUEUE +***************************** + +Name +==== + +MEDIA_REQUEST_IOC_QUEUE - Queue a request + +Synopsis +======== + +.. c:macro:: MEDIA_REQUEST_IOC_QUEUE + +``int ioctl(int request_fd, MEDIA_REQUEST_IOC_QUEUE)`` + +Arguments +========= + +``request_fd`` + File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. + +Description +=========== + +If the media device supports :ref:`requests `, then +this request ioctl can be used to queue a previously allocated request. + +If the request was successfully queued, then the file descriptor can be +:ref:`polled ` to wait for the request to complete. + +If the request was already queued before, then ``EBUSY`` is returned. +Other errors can be returned if the contents of the request contained +invalid or inconsistent data, see the next section for a list of +common error codes. On error both the request and driver state are unchanged. + +Once a request is queued, then the driver is required to gracefully handle +errors that occur when the request is applied to the hardware. The +exception is the ``EIO`` error which signals a fatal error that requires +the application to stop streaming to reset the hardware state. + +It is not allowed to mix queuing requests with queuing buffers directly +(without a request). ``EBUSY`` will be returned if the first buffer was +queued directly and you next try to queue a request, or vice versa. + +A request must contain at least one buffer, otherwise this ioctl will +return an ``ENOENT`` error. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +EBUSY + The request was already queued or the application queued the first + buffer directly, but later attempted to use a request. It is not permitted + to mix the two APIs. +ENOENT + The request did not contain any buffers. All requests are required + to have at least one buffer. This can also be returned if some required + configuration is missing in the request. +ENOMEM + Out of memory when allocating internal data structures for this + request. +EINVAL + The request has invalid data. +EIO + The hardware is in a bad state. To recover, the application needs to + stop streaming to reset the hardware state and then try to restart + streaming. diff --git a/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst b/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst new file mode 100644 index 000000000..57567b87b --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-request-ioc-reinit.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _media_request_ioc_reinit: + +****************************** +ioctl MEDIA_REQUEST_IOC_REINIT +****************************** + +Name +==== + +MEDIA_REQUEST_IOC_REINIT - Re-initialize a request + +Synopsis +======== + +.. c:macro:: MEDIA_REQUEST_IOC_REINIT + +``int ioctl(int request_fd, MEDIA_REQUEST_IOC_REINIT)`` + +Arguments +========= + +``request_fd`` + File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. + +Description +=========== + +If the media device supports :ref:`requests `, then +this request ioctl can be used to re-initialize a previously allocated +request. + +Re-initializing a request will clear any existing data from the request. +This avoids having to :c:func:`close()` a completed +request and allocate a new request. Instead the completed request can just +be re-initialized and it is ready to be used again. + +A request can only be re-initialized if it either has not been queued +yet, or if it was queued and completed. Otherwise it will set ``errno`` +to ``EBUSY``. No other error codes can be returned. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. + +EBUSY + The request is queued but not yet completed. diff --git a/Documentation/userspace-api/media/mediactl/media-types.rst b/Documentation/userspace-api/media/mediactl/media-types.rst new file mode 100644 index 000000000..0ffeece1e --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/media-types.rst @@ -0,0 +1,432 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _media-controller-types: + +Types and flags used to represent the media graph elements +========================================================== + +.. tabularcolumns:: |p{8.2cm}|p{9.3cm}| + +.. _media-entity-functions: +.. _MEDIA-ENT-F-UNKNOWN: +.. _MEDIA-ENT-F-V4L2-SUBDEV-UNKNOWN: +.. _MEDIA-ENT-F-IO-V4L: +.. _MEDIA-ENT-F-IO-VBI: +.. _MEDIA-ENT-F-IO-SWRADIO: +.. _MEDIA-ENT-F-IO-DTV: +.. _MEDIA-ENT-F-DTV-DEMOD: +.. _MEDIA-ENT-F-TS-DEMUX: +.. _MEDIA-ENT-F-DTV-CA: +.. _MEDIA-ENT-F-DTV-NET-DECAP: +.. _MEDIA-ENT-F-CONN-RF: +.. _MEDIA-ENT-F-CONN-SVIDEO: +.. _MEDIA-ENT-F-CONN-COMPOSITE: +.. _MEDIA-ENT-F-CAM-SENSOR: +.. _MEDIA-ENT-F-FLASH: +.. _MEDIA-ENT-F-LENS: +.. _MEDIA-ENT-F-ATV-DECODER: +.. _MEDIA-ENT-F-TUNER: +.. _MEDIA-ENT-F-IF-VID-DECODER: +.. _MEDIA-ENT-F-IF-AUD-DECODER: +.. _MEDIA-ENT-F-AUDIO-CAPTURE: +.. _MEDIA-ENT-F-AUDIO-PLAYBACK: +.. _MEDIA-ENT-F-AUDIO-MIXER: +.. _MEDIA-ENT-F-PROC-VIDEO-COMPOSER: +.. _MEDIA-ENT-F-PROC-VIDEO-PIXEL-FORMATTER: +.. _MEDIA-ENT-F-PROC-VIDEO-PIXEL-ENC-CONV: +.. _MEDIA-ENT-F-PROC-VIDEO-LUT: +.. _MEDIA-ENT-F-PROC-VIDEO-SCALER: +.. _MEDIA-ENT-F-PROC-VIDEO-STATISTICS: +.. _MEDIA-ENT-F-PROC-VIDEO-ENCODER: +.. _MEDIA-ENT-F-PROC-VIDEO-DECODER: +.. _MEDIA-ENT-F-PROC-VIDEO-ISP: +.. _MEDIA-ENT-F-VID-MUX: +.. _MEDIA-ENT-F-VID-IF-BRIDGE: +.. _MEDIA-ENT-F-DV-DECODER: +.. _MEDIA-ENT-F-DV-ENCODER: + +.. cssclass:: longtable + +.. flat-table:: Media entity functions + :header-rows: 0 + :stub-columns: 0 + + * - ``MEDIA_ENT_F_UNKNOWN`` and + ``MEDIA_ENT_F_V4L2_SUBDEV_UNKNOWN`` + - Unknown entity. That generally indicates that a driver didn't + initialize properly the entity, which is a Kernel bug + + * - ``MEDIA_ENT_F_IO_V4L`` + - Data streaming input and/or output entity. + + * - ``MEDIA_ENT_F_IO_VBI`` + - V4L VBI streaming input or output entity + + * - ``MEDIA_ENT_F_IO_SWRADIO`` + - V4L Software Digital Radio (SDR) streaming input or output entity + + * - ``MEDIA_ENT_F_IO_DTV`` + - DVB Digital TV streaming input or output entity + + * - ``MEDIA_ENT_F_DTV_DEMOD`` + - Digital TV demodulator entity. + + * - ``MEDIA_ENT_F_TS_DEMUX`` + - MPEG Transport stream demux entity. Could be implemented on + hardware or in Kernelspace by the Linux DVB subsystem. + + * - ``MEDIA_ENT_F_DTV_CA`` + - Digital TV Conditional Access module (CAM) entity + + * - ``MEDIA_ENT_F_DTV_NET_DECAP`` + - Digital TV network ULE/MLE desencapsulation entity. Could be + implemented on hardware or in Kernelspace + + * - ``MEDIA_ENT_F_CONN_RF`` + - Connector for a Radio Frequency (RF) signal. + + * - ``MEDIA_ENT_F_CONN_SVIDEO`` + - Connector for a S-Video signal. + + * - ``MEDIA_ENT_F_CONN_COMPOSITE`` + - Connector for a RGB composite signal. + + * - ``MEDIA_ENT_F_CAM_SENSOR`` + - Camera video sensor entity. + + * - ``MEDIA_ENT_F_FLASH`` + - Flash controller entity. + + * - ``MEDIA_ENT_F_LENS`` + - Lens controller entity. + + * - ``MEDIA_ENT_F_ATV_DECODER`` + - Analog video decoder, the basic function of the video decoder is + to accept analogue video from a wide variety of sources such as + broadcast, DVD players, cameras and video cassette recorders, in + either NTSC, PAL, SECAM or HD format, separating the stream into + its component parts, luminance and chrominance, and output it in + some digital video standard, with appropriate timing signals. + + * - ``MEDIA_ENT_F_TUNER`` + - Digital TV, analog TV, radio and/or software radio tuner, with + consists on a PLL tuning stage that converts radio frequency (RF) + signal into an Intermediate Frequency (IF). Modern tuners have + internally IF-PLL decoders for audio and video, but older models + have those stages implemented on separate entities. + + * - ``MEDIA_ENT_F_IF_VID_DECODER`` + - IF-PLL video decoder. It receives the IF from a PLL and decodes + the analog TV video signal. This is commonly found on some very + old analog tuners, like Philips MK3 designs. They all contain a + tda9887 (or some software compatible similar chip, like tda9885). + Those devices use a different I2C address than the tuner PLL. + + * - ``MEDIA_ENT_F_IF_AUD_DECODER`` + - IF-PLL sound decoder. It receives the IF from a PLL and decodes + the analog TV audio signal. This is commonly found on some very + old analog hardware, like Micronas msp3400, Philips tda9840, + tda985x, etc. Those devices use a different I2C address than the + tuner PLL and should be controlled together with the IF-PLL video + decoder. + + * - ``MEDIA_ENT_F_AUDIO_CAPTURE`` + - Audio Capture Function Entity. + + * - ``MEDIA_ENT_F_AUDIO_PLAYBACK`` + - Audio Playback Function Entity. + + * - ``MEDIA_ENT_F_AUDIO_MIXER`` + - Audio Mixer Function Entity. + + * - ``MEDIA_ENT_F_PROC_VIDEO_COMPOSER`` + - Video composer (blender). An entity capable of video + composing must have at least two sink pads and one source + pad, and composes input video frames onto output video + frames. Composition can be performed using alpha blending, + color keying, raster operations (ROP), stitching or any other + means. + + * - ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_FORMATTER`` + - Video pixel formatter. An entity capable of pixel formatting + must have at least one sink pad and one source pad. Read + pixel formatters read pixels from memory and perform a subset + of unpacking, cropping, color keying, alpha multiplication + and pixel encoding conversion. Write pixel formatters perform + a subset of dithering, pixel encoding conversion and packing + and write pixels to memory. + + * - ``MEDIA_ENT_F_PROC_VIDEO_PIXEL_ENC_CONV`` + - Video pixel encoding converter. An entity capable of pixel + encoding conversion must have at least one sink pad and one + source pad, and convert the encoding of pixels received on + its sink pad(s) to a different encoding output on its source + pad(s). Pixel encoding conversion includes but isn't limited + to RGB to/from HSV, RGB to/from YUV and CFA (Bayer) to RGB + conversions. + + * - ``MEDIA_ENT_F_PROC_VIDEO_LUT`` + - Video look-up table. An entity capable of video lookup table + processing must have one sink pad and one source pad. It uses + the values of the pixels received on its sink pad to look up + entries in internal tables and output them on its source pad. + The lookup processing can be performed on all components + separately or combine them for multi-dimensional table + lookups. + + * - ``MEDIA_ENT_F_PROC_VIDEO_SCALER`` + - Video scaler. An entity capable of video scaling must have + at least one sink pad and one source pad, and scale the + video frame(s) received on its sink pad(s) to a different + resolution output on its source pad(s). The range of + supported scaling ratios is entity-specific and can differ + between the horizontal and vertical directions (in particular + scaling can be supported in one direction only). Binning and + sub-sampling (occasionally also referred to as skipping) are + considered as scaling. + + * - ``MEDIA_ENT_F_PROC_VIDEO_STATISTICS`` + - Video statistics computation (histogram, 3A, etc.). An entity + capable of statistics computation must have one sink pad and + one source pad. It computes statistics over the frames + received on its sink pad and outputs the statistics data on + its source pad. + + * - ``MEDIA_ENT_F_PROC_VIDEO_ENCODER`` + - Video (MPEG, HEVC, VPx, etc.) encoder. An entity capable of + compressing video frames. Must have one sink pad and at least + one source pad. + + * - ``MEDIA_ENT_F_PROC_VIDEO_DECODER`` + - Video (MPEG, HEVC, VPx, etc.) decoder. An entity capable of + decompressing a compressed video stream into uncompressed video + frames. Must have one sink pad and at least one source pad. + + * - ``MEDIA_ENT_F_PROC_VIDEO_ISP`` + - An Image Signal Processor (ISP) device. ISPs generally are one of a + kind devices that have their specific control interfaces using a + combination of custom V4L2 controls and IOCTLs, and parameters + supplied in a metadata buffer. + + * - ``MEDIA_ENT_F_VID_MUX`` + - Video multiplexer. An entity capable of multiplexing must have at + least two sink pads and one source pad, and must pass the video + frame(s) received from the active sink pad to the source pad. + + * - ``MEDIA_ENT_F_VID_IF_BRIDGE`` + - Video interface bridge. A video interface bridge entity must have at + least one sink pad and at least one source pad. It receives video + frames on its sink pad from an input video bus of one type (HDMI, eDP, + MIPI CSI-2, etc.), and outputs them on its source pad to an output + video bus of another type (eDP, MIPI CSI-2, parallel, etc.). + + * - ``MEDIA_ENT_F_DV_DECODER`` + - Digital video decoder. The basic function of the video decoder is + to accept digital video from a wide variety of sources + and output it in some digital video standard, with appropriate + timing signals. + + * - ``MEDIA_ENT_F_DV_ENCODER`` + - Digital video encoder. The basic function of the video encoder is + to accept digital video from some digital video standard with + appropriate timing signals (usually a parallel video bus with sync + signals) and output this to a digital video output connector such + as HDMI or DisplayPort. + +.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| + +.. _media-entity-flag: +.. _MEDIA-ENT-FL-DEFAULT: +.. _MEDIA-ENT-FL-CONNECTOR: + +.. flat-table:: Media entity flags + :header-rows: 0 + :stub-columns: 0 + + * - ``MEDIA_ENT_FL_DEFAULT`` + - Default entity for its type. Used to discover the default audio, + VBI and video devices, the default camera sensor, etc. + + * - ``MEDIA_ENT_FL_CONNECTOR`` + - The entity represents a connector. + + +.. tabularcolumns:: |p{6.5cm}|p{6.0cm}|p{4.8cm}| + +.. _media-intf-type: +.. _MEDIA-INTF-T-DVB-FE: +.. _MEDIA-INTF-T-DVB-DEMUX: +.. _MEDIA-INTF-T-DVB-DVR: +.. _MEDIA-INTF-T-DVB-CA: +.. _MEDIA-INTF-T-DVB-NET: +.. _MEDIA-INTF-T-V4L-VIDEO: +.. _MEDIA-INTF-T-V4L-VBI: +.. _MEDIA-INTF-T-V4L-RADIO: +.. _MEDIA-INTF-T-V4L-SUBDEV: +.. _MEDIA-INTF-T-V4L-SWRADIO: +.. _MEDIA-INTF-T-V4L-TOUCH: +.. _MEDIA-INTF-T-ALSA-PCM-CAPTURE: +.. _MEDIA-INTF-T-ALSA-PCM-PLAYBACK: +.. _MEDIA-INTF-T-ALSA-CONTROL: +.. _MEDIA-INTF-T-ALSA-COMPRESS: +.. _MEDIA-INTF-T-ALSA-RAWMIDI: +.. _MEDIA-INTF-T-ALSA-HWDEP: +.. _MEDIA-INTF-T-ALSA-SEQUENCER: +.. _MEDIA-INTF-T-ALSA-TIMER: + +.. flat-table:: Media interface types + :header-rows: 0 + :stub-columns: 0 + + * - ``MEDIA_INTF_T_DVB_FE`` + - Device node interface for the Digital TV frontend + - typically, /dev/dvb/adapter?/frontend? + + * - ``MEDIA_INTF_T_DVB_DEMUX`` + - Device node interface for the Digital TV demux + - typically, /dev/dvb/adapter?/demux? + + * - ``MEDIA_INTF_T_DVB_DVR`` + - Device node interface for the Digital TV DVR + - typically, /dev/dvb/adapter?/dvr? + + * - ``MEDIA_INTF_T_DVB_CA`` + - Device node interface for the Digital TV Conditional Access + - typically, /dev/dvb/adapter?/ca? + + * - ``MEDIA_INTF_T_DVB_NET`` + - Device node interface for the Digital TV network control + - typically, /dev/dvb/adapter?/net? + + * - ``MEDIA_INTF_T_V4L_VIDEO`` + - Device node interface for video (V4L) + - typically, /dev/video? + + * - ``MEDIA_INTF_T_V4L_VBI`` + - Device node interface for VBI (V4L) + - typically, /dev/vbi? + + * - ``MEDIA_INTF_T_V4L_RADIO`` + - Device node interface for radio (V4L) + - typically, /dev/radio? + + * - ``MEDIA_INTF_T_V4L_SUBDEV`` + - Device node interface for a V4L subdevice + - typically, /dev/v4l-subdev? + + * - ``MEDIA_INTF_T_V4L_SWRADIO`` + - Device node interface for Software Defined Radio (V4L) + - typically, /dev/swradio? + + * - ``MEDIA_INTF_T_V4L_TOUCH`` + - Device node interface for Touch device (V4L) + - typically, /dev/v4l-touch? + + * - ``MEDIA_INTF_T_ALSA_PCM_CAPTURE`` + - Device node interface for ALSA PCM Capture + - typically, /dev/snd/pcmC?D?c + + * - ``MEDIA_INTF_T_ALSA_PCM_PLAYBACK`` + - Device node interface for ALSA PCM Playback + - typically, /dev/snd/pcmC?D?p + + * - ``MEDIA_INTF_T_ALSA_CONTROL`` + - Device node interface for ALSA Control + - typically, /dev/snd/controlC? + + * - ``MEDIA_INTF_T_ALSA_COMPRESS`` + - Device node interface for ALSA Compress + - typically, /dev/snd/compr? + + * - ``MEDIA_INTF_T_ALSA_RAWMIDI`` + - Device node interface for ALSA Raw MIDI + - typically, /dev/snd/midi? + + * - ``MEDIA_INTF_T_ALSA_HWDEP`` + - Device node interface for ALSA Hardware Dependent + - typically, /dev/snd/hwC?D? + + * - ``MEDIA_INTF_T_ALSA_SEQUENCER`` + - Device node interface for ALSA Sequencer + - typically, /dev/snd/seq + + * - ``MEDIA_INTF_T_ALSA_TIMER`` + - Device node interface for ALSA Timer + - typically, /dev/snd/timer + + +.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| + +.. _media-pad-flag: +.. _MEDIA-PAD-FL-SINK: +.. _MEDIA-PAD-FL-SOURCE: +.. _MEDIA-PAD-FL-MUST-CONNECT: + +.. flat-table:: Media pad flags + :header-rows: 0 + :stub-columns: 0 + + * - ``MEDIA_PAD_FL_SINK`` + - Input pad, relative to the entity. Input pads sink data and are + targets of links. + + * - ``MEDIA_PAD_FL_SOURCE`` + - Output pad, relative to the entity. Output pads source data and + are origins of links. + + * - ``MEDIA_PAD_FL_MUST_CONNECT`` + - If this flag is set and the pad is linked to any other pad, then + at least one of those links must be enabled for the entity to be + able to stream. There could be temporary reasons (e.g. device + configuration dependent) for the pad to need enabled links even + when this flag isn't set; the absence of the flag doesn't imply + there is none. + + +One and only one of ``MEDIA_PAD_FL_SINK`` and ``MEDIA_PAD_FL_SOURCE`` +must be set for every pad. + +.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| + +.. _media-link-flag: +.. _MEDIA-LNK-FL-ENABLED: +.. _MEDIA-LNK-FL-IMMUTABLE: +.. _MEDIA-LNK-FL-DYNAMIC: +.. _MEDIA-LNK-FL-LINK-TYPE: + +.. flat-table:: Media link flags + :header-rows: 0 + :stub-columns: 0 + + * - ``MEDIA_LNK_FL_ENABLED`` + - The link is enabled and can be used to transfer media data. When + two or more links target a sink pad, only one of them can be + enabled at a time. + + * - ``MEDIA_LNK_FL_IMMUTABLE`` + - The link enabled state can't be modified at runtime. An immutable + link is always enabled. + + * - ``MEDIA_LNK_FL_DYNAMIC`` + - The link enabled state can be modified during streaming. This flag + is set by drivers and is read-only for applications. + + * - ``MEDIA_LNK_FL_LINK_TYPE`` + - This is a bitmask that defines the type of the link. The following + link types are currently supported: + + .. _MEDIA-LNK-FL-DATA-LINK: + + ``MEDIA_LNK_FL_DATA_LINK`` for links that represent a data connection + between two pads. + + .. _MEDIA-LNK-FL-INTERFACE-LINK: + + ``MEDIA_LNK_FL_INTERFACE_LINK`` for links that associate an entity to its + interface. + + .. _MEDIA-LNK-FL-ANCILLARY-LINK: + + ``MEDIA_LNK_FL_ANCILLARY_LINK`` for links that represent a physical + relationship between two entities. The link may or may not be + immutable, so applications must not assume either case. diff --git a/Documentation/userspace-api/media/mediactl/request-api.rst b/Documentation/userspace-api/media/mediactl/request-api.rst new file mode 100644 index 000000000..6c4cbd9f0 --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/request-api.rst @@ -0,0 +1,253 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _media-request-api: + +Request API +=========== + +The Request API has been designed to allow V4L2 to deal with requirements of +modern devices (stateless codecs, complex camera pipelines, ...) and APIs +(Android Codec v2). One such requirement is the ability for devices belonging to +the same pipeline to reconfigure and collaborate closely on a per-frame basis. +Another is support of stateless codecs, which require controls to be applied +to specific frames (aka 'per-frame controls') in order to be used efficiently. + +While the initial use-case was V4L2, it can be extended to other subsystems +as well, as long as they use the media controller. + +Supporting these features without the Request API is not always possible and if +it is, it is terribly inefficient: user-space would have to flush all activity +on the media pipeline, reconfigure it for the next frame, queue the buffers to +be processed with that configuration, and wait until they are all available for +dequeuing before considering the next frame. This defeats the purpose of having +buffer queues since in practice only one buffer would be queued at a time. + +The Request API allows a specific configuration of the pipeline (media +controller topology + configuration for each media entity) to be associated with +specific buffers. This allows user-space to schedule several tasks ("requests") +with different configurations in advance, knowing that the configuration will be +applied when needed to get the expected result. Configuration values at the time +of request completion are also available for reading. + +General Usage +------------- + +The Request API extends the Media Controller API and cooperates with +subsystem-specific APIs to support request usage. At the Media Controller +level, requests are allocated from the supporting Media Controller device +node. Their life cycle is then managed through the request file descriptors in +an opaque way. Configuration data, buffer handles and processing results +stored in requests are accessed through subsystem-specific APIs extended for +request support, such as V4L2 APIs that take an explicit ``request_fd`` +parameter. + +Request Allocation +------------------ + +User-space allocates requests using :ref:`MEDIA_IOC_REQUEST_ALLOC` +for the media device node. This returns a file descriptor representing the +request. Typically, several such requests will be allocated. + +Request Preparation +------------------- + +Standard V4L2 ioctls can then receive a request file descriptor to express the +fact that the ioctl is part of said request, and is not to be applied +immediately. See :ref:`MEDIA_IOC_REQUEST_ALLOC` for a list of ioctls that +support this. Configurations set with a ``request_fd`` parameter are stored +instead of being immediately applied, and buffers queued to a request do not +enter the regular buffer queue until the request itself is queued. + +Request Submission +------------------ + +Once the configuration and buffers of the request are specified, it can be +queued by calling :ref:`MEDIA_REQUEST_IOC_QUEUE` on the request file descriptor. +A request must contain at least one buffer, otherwise ``ENOENT`` is returned. +A queued request cannot be modified anymore. + +.. caution:: + For :ref:`memory-to-memory devices ` you can use requests only for + output buffers, not for capture buffers. Attempting to add a capture buffer + to a request will result in an ``EBADR`` error. + +If the request contains configurations for multiple entities, individual drivers +may synchronize so the requested pipeline's topology is applied before the +buffers are processed. Media controller drivers do a best effort implementation +since perfect atomicity may not be possible due to hardware limitations. + +.. caution:: + + It is not allowed to mix queuing requests with directly queuing buffers: + whichever method is used first locks this in place until + :ref:`VIDIOC_STREAMOFF ` is called or the device is + :ref:`closed `. Attempts to directly queue a buffer when earlier + a buffer was queued via a request or vice versa will result in an ``EBUSY`` + error. + +Controls can still be set without a request and are applied immediately, +regardless of whether a request is in use or not. + +.. caution:: + + Setting the same control through a request and also directly can lead to + undefined behavior! + +User-space can :c:func:`poll()` a request file descriptor in +order to wait until the request completes. A request is considered complete +once all its associated buffers are available for dequeuing and all the +associated controls have been updated with the values at the time of completion. +Note that user-space does not need to wait for the request to complete to +dequeue its buffers: buffers that are available halfway through a request can +be dequeued independently of the request's state. + +A completed request contains the state of the device after the request was +executed. User-space can query that state by calling +:ref:`ioctl VIDIOC_G_EXT_CTRLS ` with the request file +descriptor. Calling :ref:`ioctl VIDIOC_G_EXT_CTRLS ` for a +request that has been queued but not yet completed will return ``EBUSY`` +since the control values might be changed at any time by the driver while the +request is in flight. + +.. _media-request-life-time: + +Recycling and Destruction +------------------------- + +Finally, a completed request can either be discarded or be reused. Calling +:c:func:`close()` on a request file descriptor will make +that file descriptor unusable and the request will be freed once it is no +longer in use by the kernel. That is, if the request is queued and then the +file descriptor is closed, then it won't be freed until the driver completed +the request. + +The :ref:`MEDIA_REQUEST_IOC_REINIT` will clear a request's state and make it +available again. No state is retained by this operation: the request is as +if it had just been allocated. + +Example for a Codec Device +-------------------------- + +For use-cases such as :ref:`codecs `, the request API can be used +to associate specific controls to +be applied by the driver for the OUTPUT buffer, allowing user-space +to queue many such buffers in advance. It can also take advantage of requests' +ability to capture the state of controls when the request completes to read back +information that may be subject to change. + +Put into code, after obtaining a request, user-space can assign controls and one +OUTPUT buffer to it: + +.. code-block:: c + + struct v4l2_buffer buf; + struct v4l2_ext_controls ctrls; + int req_fd; + ... + if (ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd)) + return errno; + ... + ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; + ctrls.request_fd = req_fd; + if (ioctl(codec_fd, VIDIOC_S_EXT_CTRLS, &ctrls)) + return errno; + ... + buf.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; + buf.flags |= V4L2_BUF_FLAG_REQUEST_FD; + buf.request_fd = req_fd; + if (ioctl(codec_fd, VIDIOC_QBUF, &buf)) + return errno; + +Note that it is not allowed to use the Request API for CAPTURE buffers +since there are no per-frame settings to report there. + +Once the request is fully prepared, it can be queued to the driver: + +.. code-block:: c + + if (ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE)) + return errno; + +User-space can then either wait for the request to complete by calling poll() on +its file descriptor, or start dequeuing CAPTURE buffers. Most likely, it will +want to get CAPTURE buffers as soon as possible and this can be done using a +regular :ref:`VIDIOC_DQBUF `: + +.. code-block:: c + + struct v4l2_buffer buf; + + memset(&buf, 0, sizeof(buf)); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + if (ioctl(codec_fd, VIDIOC_DQBUF, &buf)) + return errno; + +Note that this example assumes for simplicity that for every OUTPUT buffer +there will be one CAPTURE buffer, but this does not have to be the case. + +We can then, after ensuring that the request is completed via polling the +request file descriptor, query control values at the time of its completion via +a call to :ref:`VIDIOC_G_EXT_CTRLS `. +This is particularly useful for volatile controls for which we want to +query values as soon as the capture buffer is produced. + +.. code-block:: c + + struct pollfd pfd = { .events = POLLPRI, .fd = req_fd }; + poll(&pfd, 1, -1); + ... + ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; + ctrls.request_fd = req_fd; + if (ioctl(codec_fd, VIDIOC_G_EXT_CTRLS, &ctrls)) + return errno; + +Once we don't need the request anymore, we can either recycle it for reuse with +:ref:`MEDIA_REQUEST_IOC_REINIT`... + +.. code-block:: c + + if (ioctl(req_fd, MEDIA_REQUEST_IOC_REINIT)) + return errno; + +... or close its file descriptor to completely dispose of it. + +.. code-block:: c + + close(req_fd); + +Example for a Simple Capture Device +----------------------------------- + +With a simple capture device, requests can be used to specify controls to apply +for a given CAPTURE buffer. + +.. code-block:: c + + struct v4l2_buffer buf; + struct v4l2_ext_controls ctrls; + int req_fd; + ... + if (ioctl(media_fd, MEDIA_IOC_REQUEST_ALLOC, &req_fd)) + return errno; + ... + ctrls.which = V4L2_CTRL_WHICH_REQUEST_VAL; + ctrls.request_fd = req_fd; + if (ioctl(camera_fd, VIDIOC_S_EXT_CTRLS, &ctrls)) + return errno; + ... + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.flags |= V4L2_BUF_FLAG_REQUEST_FD; + buf.request_fd = req_fd; + if (ioctl(camera_fd, VIDIOC_QBUF, &buf)) + return errno; + +Once the request is fully prepared, it can be queued to the driver: + +.. code-block:: c + + if (ioctl(req_fd, MEDIA_REQUEST_IOC_QUEUE)) + return errno; + +User-space can then dequeue buffers, wait for the request completion, query +controls and recycle the request as in the M2M example above. diff --git a/Documentation/userspace-api/media/mediactl/request-func-close.rst b/Documentation/userspace-api/media/mediactl/request-func-close.rst new file mode 100644 index 000000000..f4b8eb385 --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/request-func-close.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC.request + +.. _request-func-close: + +*************** +request close() +*************** + +Name +==== + +request-close - Close a request file descriptor + +Synopsis +======== + +.. code-block:: c + + #include + +.. c:function:: int close( int fd ) + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. + +Description +=========== + +Closes the request file descriptor. Resources associated with the request +are freed once all file descriptors associated with the request are closed +and the driver has completed the request. +See :ref:`here ` for more information. + +Return Value +============ + +:c:func:`close()` returns 0 on success. On error, -1 is +returned, and ``errno`` is set appropriately. Possible error codes are: + +EBADF + ``fd`` is not a valid open file descriptor. diff --git a/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst b/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst new file mode 100644 index 000000000..4fb3d2ef3 --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/request-func-ioctl.rst @@ -0,0 +1,63 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _request-func-ioctl: + +*************** +request ioctl() +*************** + +Name +==== + +request-ioctl - Control a request file descriptor + +Synopsis +======== + +.. code-block:: c + + #include + +``int ioctl(int fd, int cmd, void *argp)`` + +Arguments +========= + +``fd`` + File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. + +``cmd`` + The request ioctl command code as defined in the media.h header file, for + example :ref:`MEDIA_REQUEST_IOC_QUEUE`. + +``argp`` + Pointer to a request-specific structure. + +Description +=========== + +The :ref:`ioctl() ` function manipulates request +parameters. The argument ``fd`` must be an open file descriptor. + +The ioctl ``cmd`` code specifies the request function to be called. It +has encoded in it whether the argument is an input, output or read/write +parameter, and the size of the argument ``argp`` in bytes. + +Macros and structures definitions specifying request ioctl commands and +their parameters are located in the media.h header file. All request ioctl +commands, their respective function and parameters are specified in +:ref:`media-user-func`. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. + +Command-specific error codes are listed in the individual command +descriptions. + +When an ioctl that takes an output or read/write parameter fails, the +parameter remains unmodified. diff --git a/Documentation/userspace-api/media/mediactl/request-func-poll.rst b/Documentation/userspace-api/media/mediactl/request-func-poll.rst new file mode 100644 index 000000000..ce0043dbe --- /dev/null +++ b/Documentation/userspace-api/media/mediactl/request-func-poll.rst @@ -0,0 +1,73 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: MC + +.. _request-func-poll: + +************** +request poll() +************** + +Name +==== + +request-poll - Wait for some event on a file descriptor + +Synopsis +======== + +.. code-block:: c + + #include + +.. c:function:: int poll( struct pollfd *ufds, unsigned int nfds, int timeout ) + +Arguments +========= + +``ufds`` + List of file descriptor events to be watched + +``nfds`` + Number of file descriptor events at the \*ufds array + +``timeout`` + Timeout to wait for events + +Description +=========== + +With the :c:func:`poll()` function applications can wait +for a request to complete. + +On success :c:func:`poll()` returns the number of file +descriptors that have been selected (that is, file descriptors for which the +``revents`` field of the respective struct :c:type:`pollfd` +is non-zero). Request file descriptor set the ``POLLPRI`` flag in ``revents`` +when the request was completed. When the function times out it returns +a value of zero, on failure it returns -1 and the ``errno`` variable is +set appropriately. + +Attempting to poll for a request that is not yet queued will +set the ``POLLERR`` flag in ``revents``. + +Return Value +============ + +On success, :c:func:`poll()` returns the number of +structures which have non-zero ``revents`` fields, or zero if the call +timed out. On error -1 is returned, and the ``errno`` variable is set +appropriately: + +``EBADF`` + One or more of the ``ufds`` members specify an invalid file + descriptor. + +``EFAULT`` + ``ufds`` references an inaccessible memory area. + +``EINTR`` + The call was interrupted by a signal. + +``EINVAL`` + The ``nfds`` value exceeds the ``RLIMIT_NOFILE`` value. Use + ``getrlimit()`` to obtain this value. diff --git a/Documentation/userspace-api/media/net.h.rst.exceptions b/Documentation/userspace-api/media/net.h.rst.exceptions new file mode 100644 index 000000000..5159aa4bb --- /dev/null +++ b/Documentation/userspace-api/media/net.h.rst.exceptions @@ -0,0 +1,13 @@ +# SPDX-License-Identifier: GPL-2.0 + +# Ignore header name +ignore define _DVBNET_H_ + +# Ignore old ioctls/structs +ignore ioctl __NET_ADD_IF_OLD +ignore ioctl __NET_GET_IF_OLD +ignore struct __dvb_net_if_old + +# Macros used at struct dvb_net_if +replace define DVB_NET_FEEDTYPE_MPE :c:type:`dvb_net_if` +replace define DVB_NET_FEEDTYPE_ULE :c:type:`dvb_net_if` diff --git a/Documentation/userspace-api/media/rc/keytable.c.rst b/Documentation/userspace-api/media/rc/keytable.c.rst new file mode 100644 index 000000000..243e02d26 --- /dev/null +++ b/Documentation/userspace-api/media/rc/keytable.c.rst @@ -0,0 +1,176 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +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/userspace-api/media/rc/lirc-dev-intro.rst b/Documentation/userspace-api/media/rc/lirc-dev-intro.rst new file mode 100644 index 000000000..d899331b9 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-dev-intro.rst @@ -0,0 +1,176 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +.. _lirc_dev_intro: + +************ +Introduction +************ + +LIRC stands for Linux Infrared Remote Control. The LIRC device interface is +a bi-directional interface for transporting raw IR and decoded scancodes +data between userspace and kernelspace. Fundamentally, it is just a chardev +(/dev/lircX, for X = 0, 1, 2, ...), with a number of standard struct +file_operations defined on it. With respect to transporting raw IR and +decoded scancodes to and fro, the essential fops are read, write and ioctl. + +It is also possible to attach a BPF program to a LIRC device for decoding +raw IR into scancodes. + +Example dmesg output upon a driver registering w/LIRC: + +.. code-block:: none + + $ dmesg |grep lirc_dev + rc rc0: lirc_dev: driver mceusb registered at minor = 0, raw IR receiver, raw IR transmitter + +What you should see for a chardev: + +.. code-block:: none + + $ ls -l /dev/lirc* + crw-rw---- 1 root root 248, 0 Jul 2 22:20 /dev/lirc0 + +Note that the package `v4l-utils `_ +contains tools for working with LIRC devices: + + - ir-ctl: can receive raw IR and transmit IR, as well as query LIRC + device features. + + - ir-keytable: can load keymaps; allows you to set IR kernel protocols; load + BPF IR decoders and test IR decoding. Some BPF IR decoders are also + provided. + +.. _lirc_modes: + +********** +LIRC modes +********** + +LIRC supports some modes of receiving and sending IR codes, as shown +on the following table. + +.. _lirc-mode-scancode: +.. _lirc-scancode-flag-toggle: +.. _lirc-scancode-flag-repeat: + +``LIRC_MODE_SCANCODE`` + + This mode is for both sending and receiving IR. + + For transmitting (aka sending), create a struct lirc_scancode with + the desired scancode set in the ``scancode`` member, :c:type:`rc_proto` + set to the :ref:`IR protocol `, and all other + members set to 0. Write this struct to the lirc device. + + For receiving, you read struct lirc_scancode from the LIRC device. + The ``scancode`` field is set to the received scancode and the + :ref:`IR protocol ` is set in + :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set + in the ``keycode`` field, else it is set to ``KEY_RESERVED``. + + The ``flags`` can have ``LIRC_SCANCODE_FLAG_TOGGLE`` set if the toggle + bit is set in protocols that support it (e.g. rc-5 and rc-6), or + ``LIRC_SCANCODE_FLAG_REPEAT`` for when a repeat is received for protocols + that support it (e.g. nec). + + In the Sanyo and NEC protocol, if you hold a button on remote, rather than + repeating the entire scancode, the remote sends a shorter message with + no scancode, which just means button is held, a "repeat". When this is + received, the ``LIRC_SCANCODE_FLAG_REPEAT`` is set and the scancode and + keycode is repeated. + + With nec, there is no way to distinguish "button hold" from "repeatedly + pressing the same button". The rc-5 and rc-6 protocols have a toggle bit. + When a button is released and pressed again, the toggle bit is inverted. + If the toggle bit is set, the ``LIRC_SCANCODE_FLAG_TOGGLE`` is set. + + The ``timestamp`` field is filled with the time nanoseconds + (in ``CLOCK_MONOTONIC``) when the scancode was decoded. + +.. _lirc-mode-mode2: + +``LIRC_MODE_MODE2`` + + The driver returns a sequence of pulse and space codes to userspace, + as a series of u32 values. + + This mode is used only for IR receive. + + The upper 8 bits determine the packet type, and the lower 24 bits + the payload. Use ``LIRC_VALUE()`` macro to get the payload, and + the macro ``LIRC_MODE2()`` will give you the type, which + is one of: + + ``LIRC_MODE2_PULSE`` + + Signifies the presence of IR in microseconds, also known as *flash*. + + ``LIRC_MODE2_SPACE`` + + Signifies absence of IR in microseconds, also known as *gap*. + + ``LIRC_MODE2_FREQUENCY`` + + If measurement of the carrier frequency was enabled with + :ref:`lirc_set_measure_carrier_mode` then this packet gives you + the carrier frequency in Hertz. + + ``LIRC_MODE2_TIMEOUT`` + + When the timeout set with :ref:`lirc_set_rec_timeout` expires due + to no IR being detected, this packet will be sent, with the number + of microseconds with no IR. + + ``LIRC_MODE2_OVERFLOW`` + + Signifies that the IR receiver encounter an overflow, and some IR + is missing. The IR data after this should be correct again. The + actual value is not important, but this is set to 0xffffff by the + kernel for compatibility with lircd. + +.. _lirc-mode-pulse: + +``LIRC_MODE_PULSE`` + + In pulse mode, a sequence of pulse/space integer values are written to the + lirc device using :ref:`lirc-write`. + + The values are alternating pulse and space lengths, in microseconds. The + first and last entry must be a pulse, so there must be an odd number + of entries. + + This mode is used only for IR send. + +************************************* +Data types used by LIRC_MODE_SCANCODE +************************************* + +.. kernel-doc:: include/uapi/linux/lirc.h + :identifiers: lirc_scancode rc_proto + +******************** +BPF based IR decoder +******************** + +The kernel has support for decoding the most common +:ref:`IR protocols `, but there +are many protocols which are not supported. To support these, it is possible +to load an BPF program which does the decoding. This can only be done on +LIRC devices which support reading raw IR. + +First, using the `bpf(2)`_ syscall with the ``BPF_LOAD_PROG`` argument, +program must be loaded of type ``BPF_PROG_TYPE_LIRC_MODE2``. Once attached +to the LIRC device, this program will be called for each pulse, space or +timeout event on the LIRC device. The context for the BPF program is a +pointer to a unsigned int, which is a :ref:`LIRC_MODE_MODE2 ` +value. When the program has decoded the scancode, it can be submitted using +the BPF functions ``bpf_rc_keydown()`` or ``bpf_rc_repeat()``. Mouse or pointer +movements can be reported using ``bpf_rc_pointer_rel()``. + +Once you have the file descriptor for the ``BPF_PROG_TYPE_LIRC_MODE2`` BPF +program, it can be attached to the LIRC device using the `bpf(2)`_ syscall. +The target must be the file descriptor for the LIRC device, and the +attach type must be ``BPF_LIRC_MODE2``. No more than 64 BPF programs can be +attached to a single LIRC device at a time. + +.. _bpf(2): http://man7.org/linux/man-pages/man2/bpf.2.html diff --git a/Documentation/userspace-api/media/rc/lirc-dev.rst b/Documentation/userspace-api/media/rc/lirc-dev.rst new file mode 100644 index 000000000..978f86d30 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-dev.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +.. _lirc_dev: + +LIRC Device Interface +===================== + + +.. toctree:: + :maxdepth: 1 + + lirc-dev-intro + lirc-func + lirc-header diff --git a/Documentation/userspace-api/media/rc/lirc-func.rst b/Documentation/userspace-api/media/rc/lirc-func.rst new file mode 100644 index 000000000..5c84888f1 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-func.rst @@ -0,0 +1,26 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +.. _lirc_func: + +LIRC Function Reference +======================= + + +.. toctree:: + :maxdepth: 1 + + lirc-read + lirc-write + lirc-get-features + lirc-get-send-mode + lirc-get-rec-mode + lirc-get-rec-resolution + lirc-set-send-duty-cycle + lirc-get-timeout + lirc-set-rec-timeout + lirc-set-rec-carrier + lirc-set-rec-carrier-range + lirc-set-send-carrier + lirc-set-transmitter-mask + lirc-set-measure-carrier-mode + lirc-set-wideband-receiver diff --git a/Documentation/userspace-api/media/rc/lirc-get-features.rst b/Documentation/userspace-api/media/rc/lirc-get-features.rst new file mode 100644 index 000000000..545137620 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-get-features.rst @@ -0,0 +1,174 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc_get_features: + +*********************** +ioctl LIRC_GET_FEATURES +*********************** + +Name +==== + +LIRC_GET_FEATURES - Get the underlying hardware device's features + +Synopsis +======== + +.. c:macro:: LIRC_GET_FEATURES + +``int ioctl(int fd, LIRC_GET_FEATURES, __u32 *features)`` + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``features`` + Bitmask with the LIRC features. + +Description +=========== + +Get the underlying hardware device's features. If a driver does not +announce support of certain features, calling of the corresponding ioctls +is undefined. + +LIRC features +============= + +.. _LIRC-CAN-REC-RAW: + +``LIRC_CAN_REC_RAW`` + + Unused. Kept just to avoid breaking uAPI. + +.. _LIRC-CAN-REC-PULSE: + +``LIRC_CAN_REC_PULSE`` + + Unused. Kept just to avoid breaking uAPI. + :ref:`LIRC_MODE_PULSE ` can only be used for transmitting. + +.. _LIRC-CAN-REC-MODE2: + +``LIRC_CAN_REC_MODE2`` + + This is raw IR driver for receiving. This means that + :ref:`LIRC_MODE_MODE2 ` is used. This also implies + that :ref:`LIRC_MODE_SCANCODE ` is also supported, + as long as the kernel is recent enough. Use the + :ref:`lirc_set_rec_mode` to switch modes. + +.. _LIRC-CAN-REC-LIRCCODE: + +``LIRC_CAN_REC_LIRCCODE`` + + Unused. Kept just to avoid breaking uAPI. + +.. _LIRC-CAN-REC-SCANCODE: + +``LIRC_CAN_REC_SCANCODE`` + + This is a scancode driver for receiving. This means that + :ref:`LIRC_MODE_SCANCODE ` is used. + +.. _LIRC-CAN-SET-SEND-CARRIER: + +``LIRC_CAN_SET_SEND_CARRIER`` + + The driver supports changing the modulation frequency via + :ref:`ioctl LIRC_SET_SEND_CARRIER `. + +.. _LIRC-CAN-SET-SEND-DUTY-CYCLE: + +``LIRC_CAN_SET_SEND_DUTY_CYCLE`` + + The driver supports changing the duty cycle using + :ref:`ioctl LIRC_SET_SEND_DUTY_CYCLE `. + +.. _LIRC-CAN-SET-TRANSMITTER-MASK: + +``LIRC_CAN_SET_TRANSMITTER_MASK`` + + The driver supports changing the active transmitter(s) using + :ref:`ioctl LIRC_SET_TRANSMITTER_MASK `. + +.. _LIRC-CAN-SET-REC-CARRIER: + +``LIRC_CAN_SET_REC_CARRIER`` + + The driver supports setting the receive carrier frequency using + :ref:`ioctl LIRC_SET_REC_CARRIER `. + +.. _LIRC-CAN-SET-REC-CARRIER-RANGE: + +``LIRC_CAN_SET_REC_CARRIER_RANGE`` + + The driver supports + :ref:`ioctl LIRC_SET_REC_CARRIER_RANGE `. + +.. _LIRC-CAN-GET-REC-RESOLUTION: + +``LIRC_CAN_GET_REC_RESOLUTION`` + + The driver supports + :ref:`ioctl LIRC_GET_REC_RESOLUTION `. + +.. _LIRC-CAN-SET-REC-TIMEOUT: + +``LIRC_CAN_SET_REC_TIMEOUT`` + + The driver supports + :ref:`ioctl LIRC_SET_REC_TIMEOUT `. + +.. _LIRC-CAN-MEASURE-CARRIER: + +``LIRC_CAN_MEASURE_CARRIER`` + + The driver supports measuring of the modulation frequency using + :ref:`ioctl LIRC_SET_MEASURE_CARRIER_MODE `. + +.. _LIRC-CAN-USE-WIDEBAND-RECEIVER: + +``LIRC_CAN_USE_WIDEBAND_RECEIVER`` + + The driver supports learning mode using + :ref:`ioctl LIRC_SET_WIDEBAND_RECEIVER `. + +.. _LIRC-CAN-SEND-RAW: + +``LIRC_CAN_SEND_RAW`` + + Unused. Kept just to avoid breaking uAPI. + +.. _LIRC-CAN-SEND-PULSE: + +``LIRC_CAN_SEND_PULSE`` + + The driver supports sending (also called as IR blasting or IR TX) using + :ref:`LIRC_MODE_PULSE `. This implies that + :ref:`LIRC_MODE_SCANCODE ` is also supported for + transmit, as long as the kernel is recent enough. Use the + :ref:`lirc_set_send_mode` to switch modes. + +.. _LIRC-CAN-SEND-MODE2: + +``LIRC_CAN_SEND_MODE2`` + + Unused. Kept just to avoid breaking uAPI. + :ref:`LIRC_MODE_MODE2 ` can only be used for receiving. + +.. _LIRC-CAN-SEND-LIRCCODE: + +``LIRC_CAN_SEND_LIRCCODE`` + + Unused. Kept just to avoid breaking uAPI. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst new file mode 100644 index 000000000..628fe3179 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst @@ -0,0 +1,69 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc_get_rec_mode: +.. _lirc_set_rec_mode: + +********************************************** +ioctls LIRC_GET_REC_MODE and LIRC_SET_REC_MODE +********************************************** + +Name +==== + +LIRC_GET_REC_MODE/LIRC_SET_REC_MODE - Get/set current receive mode. + +Synopsis +======== + +.. c:macro:: LIRC_GET_REC_MODE + +``int ioctl(int fd, LIRC_GET_REC_MODE, __u32 *mode)`` + +.. c:macro:: LIRC_SET_REC_MODE + +``int ioctl(int fd, LIRC_SET_REC_MODE, __u32 *mode)`` + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``mode`` + Mode used for receive. + +Description +=========== + +Get and set the current receive mode. Only +:ref:`LIRC_MODE_MODE2 ` and +:ref:`LIRC_MODE_SCANCODE ` are supported. +Use :ref:`lirc_get_features` to find out which modes the driver supports. + +Return Value +============ + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. row 1 + + - ``ENODEV`` + + - Device not available. + + - .. row 2 + + - ``ENOTTY`` + + - Device does not support receiving. + + - .. row 3 + + - ``EINVAL`` + + - Invalid mode or invalid mode for this device. diff --git a/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst new file mode 100644 index 000000000..4dfa9c236 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc_get_rec_resolution: + +***************************** +ioctl LIRC_GET_REC_RESOLUTION +***************************** + +Name +==== + +LIRC_GET_REC_RESOLUTION - Obtain the value of receive resolution, in microseconds. + +Synopsis +======== + +.. c:macro:: LIRC_GET_REC_RESOLUTION + +``int ioctl(int fd, LIRC_GET_REC_RESOLUTION, __u32 *microseconds)`` + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``microseconds`` + Resolution, in microseconds. + +Description +=========== + +Some receivers have maximum resolution which is defined by internal +sample rate or data format limitations. E.g. it's common that +signals can only be reported in 50 microsecond steps. + +This ioctl returns the integer value with such resolution, with can be +used by userspace applications like lircd to automatically adjust the +tolerance value. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst new file mode 100644 index 000000000..637871805 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-get-send-mode.rst @@ -0,0 +1,71 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc_get_send_mode: +.. _lirc_set_send_mode: + +************************************************ +ioctls LIRC_GET_SEND_MODE and LIRC_SET_SEND_MODE +************************************************ + +Name +==== + +LIRC_GET_SEND_MODE/LIRC_SET_SEND_MODE - Get/set current transmit mode. + +Synopsis +======== + +.. c:macro:: LIRC_GET_SEND_MODE + +``int ioctl(int fd, LIRC_GET_SEND_MODE, __u32 *mode)`` + +.. c:macro:: LIRC_SET_SEND_MODE + +``int ioctl(int fd, LIRC_SET_SEND_MODE, __u32 *mode)`` + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``mode`` + The mode used for transmitting. + +Description +=========== + +Get/set current transmit mode. + +Only :ref:`LIRC_MODE_PULSE ` and +:ref:`LIRC_MODE_SCANCODE ` are supported by for IR send, +depending on the driver. Use :ref:`lirc_get_features` to find out which +modes the driver supports. + +Return Value +============ + +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + + - .. row 1 + + - ``ENODEV`` + + - Device not available. + + - .. row 2 + + - ``ENOTTY`` + + - Device does not support transmitting. + + - .. row 3 + + - ``EINVAL`` + + - Invalid mode or invalid mode for this device. diff --git a/Documentation/userspace-api/media/rc/lirc-get-timeout.rst b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst new file mode 100644 index 000000000..597c3282a --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-get-timeout.rst @@ -0,0 +1,57 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc_get_min_timeout: +.. _lirc_get_max_timeout: + +**************************************************** +ioctls LIRC_GET_MIN_TIMEOUT and LIRC_GET_MAX_TIMEOUT +**************************************************** + +Name +==== + +LIRC_GET_MIN_TIMEOUT / LIRC_GET_MAX_TIMEOUT - Obtain the possible timeout +range for IR receive. + +Synopsis +======== + +.. c:macro:: LIRC_GET_MIN_TIMEOUT + +``int ioctl(int fd, LIRC_GET_MIN_TIMEOUT, __u32 *timeout)`` + +.. c:macro:: LIRC_GET_MAX_TIMEOUT + +``int ioctl(int fd, LIRC_GET_MAX_TIMEOUT, __u32 *timeout)`` + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``timeout`` + Timeout, in microseconds. + +Description +=========== + +Some devices have internal timers that can be used to detect when +there's no IR activity for a long time. This can help lircd in +detecting that a IR signal is finished and can speed up the decoding +process. Returns an integer value with the minimum/maximum timeout +that can be set. + +.. note:: + + Some devices have a fixed timeout, in that case + both ioctls will return the same value even though the timeout + cannot be changed via :ref:`LIRC_SET_REC_TIMEOUT`. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/rc/lirc-header.rst b/Documentation/userspace-api/media/rc/lirc-header.rst new file mode 100644 index 000000000..54cb40b8a --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-header.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +.. _lirc_header: + +**************** +LIRC Header File +**************** + +.. kernel-include:: $BUILDDIR/lirc.h.rst + diff --git a/Documentation/userspace-api/media/rc/lirc-read.rst b/Documentation/userspace-api/media/rc/lirc-read.rst new file mode 100644 index 000000000..ce3431869 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-read.rst @@ -0,0 +1,65 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc-read: + +*********** +LIRC read() +*********** + +Name +==== + +lirc-read - Read from a LIRC device + +Synopsis +======== + +.. code-block:: c + + #include + +.. c:function:: ssize_t read( int fd, void *buf, size_t count ) + +Arguments +========= + +``fd`` + File descriptor returned by ``open()``. + +``buf`` + Buffer to be filled + +``count`` + Max number of bytes to read + +Description +=========== + +:c:func:`read()` attempts to read up to ``count`` bytes from file +descriptor ``fd`` into the buffer starting at ``buf``. If ``count`` is zero, +:c:func:`read()` returns zero and has no other results. If ``count`` +is greater than ``SSIZE_MAX``, the result is unspecified. + +The exact format of the data depends on what :ref:`lirc_modes` a driver +uses. Use :ref:`lirc_get_features` to get the supported mode, and use +:ref:`lirc_set_rec_mode` set the current active mode. + +The mode :ref:`LIRC_MODE_MODE2 ` is for raw IR, +in which packets containing an unsigned int value describing an IR signal are +read from the chardev. + +Alternatively, :ref:`LIRC_MODE_SCANCODE ` can be available, +in this mode scancodes which are either decoded by software decoders, or +by hardware decoders. The :c:type:`rc_proto` member is set to the +:ref:`IR protocol ` +used for transmission, and ``scancode`` to the decoded scancode, +and the ``keycode`` set to the keycode or ``KEY_RESERVED``. + +Return Value +============ + +On success, the number of bytes read is returned. It is not an error if +this number is smaller than the number of bytes requested, or the amount +of data required for one frame. On error, -1 is returned, and the ``errno`` +variable is set appropriately. diff --git a/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst new file mode 100644 index 000000000..04ced1aa6 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc_set_measure_carrier_mode: + +*********************************** +ioctl LIRC_SET_MEASURE_CARRIER_MODE +*********************************** + +Name +==== + +LIRC_SET_MEASURE_CARRIER_MODE - enable or disable measure mode + +Synopsis +======== + +.. c:macro:: LIRC_SET_MEASURE_CARRIER_MODE + +``int ioctl(int fd, LIRC_SET_MEASURE_CARRIER_MODE, __u32 *enable)`` + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``enable`` + enable = 1 means enable measure mode, enable = 0 means disable measure + mode. + +Description +=========== + +.. _lirc-mode2-frequency: + +Enable or disable measure mode. If enabled, from the next key +press on, the driver will send ``LIRC_MODE2_FREQUENCY`` packets. By +default this should be turned off. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst new file mode 100644 index 000000000..7512dc86b --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc_set_rec_carrier_range: + +******************************** +ioctl LIRC_SET_REC_CARRIER_RANGE +******************************** + +Name +==== + +LIRC_SET_REC_CARRIER_RANGE - Set lower bound of the carrier used to modulate +IR receive. + +Synopsis +======== + +.. c:macro:: LIRC_SET_REC_CARRIER_RANGE + +``int ioctl(int fd, LIRC_SET_REC_CARRIER_RANGE, __u32 *frequency)`` + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``frequency`` + Frequency of the carrier that modulates PWM data, in Hz. + +Description +=========== + +This ioctl sets the upper range of carrier frequency that will be recognized +by the IR receiver. + +.. note:: + + To set a range use :ref:`LIRC_SET_REC_CARRIER_RANGE + ` with the lower bound first and later call + :ref:`LIRC_SET_REC_CARRIER ` with the upper bound. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst new file mode 100644 index 000000000..60e321446 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst @@ -0,0 +1,46 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc_set_rec_carrier: + +************************** +ioctl LIRC_SET_REC_CARRIER +************************** + +Name +==== + +LIRC_SET_REC_CARRIER - Set carrier used to modulate IR receive. + +Synopsis +======== + +.. c:macro:: LIRC_SET_REC_CARRIER + +``int ioctl(int fd, LIRC_SET_REC_CARRIER, __u32 *frequency)`` + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``frequency`` + Frequency of the carrier that modulates PWM data, in Hz. + +Description +=========== + +Set receive carrier used to modulate IR PWM pulses and spaces. + +.. note:: + + If called together with :ref:`LIRC_SET_REC_CARRIER_RANGE`, this ioctl + sets the upper bound frequency that will be recognized by the device. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst new file mode 100644 index 000000000..bf9fb2cc6 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst @@ -0,0 +1,55 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc_set_rec_timeout: +.. _lirc_get_rec_timeout: + +*************************************************** +ioctl LIRC_GET_REC_TIMEOUT and LIRC_SET_REC_TIMEOUT +*************************************************** + +Name +==== + +LIRC_GET_REC_TIMEOUT/LIRC_SET_REC_TIMEOUT - Get/set the integer value for IR inactivity timeout. + +Synopsis +======== + +.. c:macro:: LIRC_GET_REC_TIMEOUT + +``int ioctl(int fd, LIRC_GET_REC_TIMEOUT, __u32 *timeout)`` + +.. c:macro:: LIRC_SET_REC_TIMEOUT + +``int ioctl(int fd, LIRC_SET_REC_TIMEOUT, __u32 *timeout)`` + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``timeout`` + Timeout, in microseconds. + +Description +=========== + +Get and set the integer value for IR inactivity timeout. + +If supported by the hardware, setting it to 0 disables all hardware timeouts +and data should be reported as soon as possible. If the exact value +cannot be set, then the next possible value _greater_ than the +given value should be set. + +.. note:: + + The range of supported timeout is given by :ref:`LIRC_GET_MIN_TIMEOUT`. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst new file mode 100644 index 000000000..a003f9447 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst @@ -0,0 +1,41 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc_set_send_carrier: + +*************************** +ioctl LIRC_SET_SEND_CARRIER +*************************** + +Name +==== + +LIRC_SET_SEND_CARRIER - Set send carrier used to modulate IR TX. + +Synopsis +======== + +.. c:macro:: LIRC_SET_SEND_CARRIER + +``int ioctl(int fd, LIRC_SET_SEND_CARRIER, __u32 *frequency)`` + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``frequency`` + Frequency of the carrier to be modulated, in Hz. + +Description +=========== + +Set send carrier used to modulate IR PWM pulses and spaces. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst new file mode 100644 index 000000000..2979752ac --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst @@ -0,0 +1,47 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc_set_send_duty_cycle: + +****************************** +ioctl LIRC_SET_SEND_DUTY_CYCLE +****************************** + +Name +==== + +LIRC_SET_SEND_DUTY_CYCLE - Set the duty cycle of the carrier signal for +IR transmit. + +Synopsis +======== + +.. c:macro:: LIRC_SET_SEND_DUTY_CYCLE + +``int ioctl(int fd, LIRC_SET_SEND_DUTY_CYCLE, __u32 *duty_cycle)`` + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``duty_cycle`` + Duty cicle, describing the pulse width in percent (from 1 to 99) of + the total cycle. Values 0 and 100 are reserved. + +Description +=========== + +Get/set the duty cycle of the carrier signal for IR transmit. + +Currently, no special meaning is defined for 0 or 100, but this +could be used to switch off carrier generation in the future, so +these values should be reserved. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst new file mode 100644 index 000000000..38acbcd6e --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc_set_transmitter_mask: + +******************************* +ioctl LIRC_SET_TRANSMITTER_MASK +******************************* + +Name +==== + +LIRC_SET_TRANSMITTER_MASK - Enables send codes on a given set of transmitters + +Synopsis +======== + +.. c:macro:: LIRC_SET_TRANSMITTER_MASK + +``int ioctl(int fd, LIRC_SET_TRANSMITTER_MASK, __u32 *mask)`` + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``mask`` + Mask with channels to enable tx. Channel 0 is the least significant bit. + +Description +=========== + +Some IR TX devices have multiple output channels, in such case, +:ref:`LIRC_CAN_SET_TRANSMITTER_MASK ` is +returned via :ref:`LIRC_GET_FEATURES` and this ioctl sets what channels will +send IR codes. + +This ioctl enables the given set of transmitters. The first transmitter is +encoded by the least significant bit and so on. + +When an invalid bit mask is given, i.e. a bit is set, even though the device +does not have so many transitters, then this ioctl returns the number of +available transitters and does nothing otherwise. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst new file mode 100644 index 000000000..c9d578e29 --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst @@ -0,0 +1,56 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc_set_wideband_receiver: + +******************************** +ioctl LIRC_SET_WIDEBAND_RECEIVER +******************************** + +Name +==== + +LIRC_SET_WIDEBAND_RECEIVER - enable wide band receiver. + +Synopsis +======== + +.. c:macro:: LIRC_SET_WIDEBAND_RECEIVER + +``int ioctl(int fd, LIRC_SET_WIDEBAND_RECEIVER, __u32 *enable)`` + +Arguments +========= + +``fd`` + File descriptor returned by open(). + +``enable`` + enable = 1 means enable wideband receiver, enable = 0 means disable + wideband receiver. + +Description +=========== + +Some receivers are equipped with special wide band receiver which is +intended to be used to learn output of existing remote. This ioctl +allows enabling or disabling it. + +This might be useful of receivers that have otherwise narrow band receiver +that prevents them to be used with some remotes. Wide band receiver might +also be more precise. On the other hand its disadvantage it usually +reduced range of reception. + +.. note:: + + Wide band receiver might be implictly enabled if you enable + carrier reports. In that case it will be disabled as soon as you disable + carrier reports. Trying to disable wide band receiver while carrier + reports are active will do nothing. + +Return Value +============ + +On success 0 is returned, on error -1 and the ``errno`` variable is set +appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/rc/lirc-write.rst b/Documentation/userspace-api/media/rc/lirc-write.rst new file mode 100644 index 000000000..970a8b3fa --- /dev/null +++ b/Documentation/userspace-api/media/rc/lirc-write.rst @@ -0,0 +1,72 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. c:namespace:: RC + +.. _lirc-write: + +************ +LIRC write() +************ + +Name +==== + +lirc-write - Write to a LIRC device + +Synopsis +======== + +.. code-block:: c + + #include + +.. c:function:: ssize_t write( int fd, void *buf, size_t count ) + +Arguments +========= + +``fd`` + File descriptor returned by ``open()``. + +``buf`` + Buffer with data to be written + +``count`` + Number of bytes at the buffer + +Description +=========== + +:c:func:`write()` writes up to ``count`` bytes to the device +referenced by the file descriptor ``fd`` from the buffer starting at +``buf``. + +The exact format of the data depends on what mode a driver is in, use +:ref:`lirc_get_features` to get the supported modes and use +:ref:`lirc_set_send_mode` set the mode. + +When in :ref:`LIRC_MODE_PULSE ` mode, the data written to +the chardev is a pulse/space sequence of integer values. Pulses and spaces +are only marked implicitly by their position. The data must start and end +with a pulse, therefore, the data must always include an uneven number of +samples. The write function blocks until the data has been transmitted +by the hardware. If more data is provided than the hardware can send, the +driver returns ``EINVAL``. + +When in :ref:`LIRC_MODE_SCANCODE ` mode, one +``struct lirc_scancode`` must be written to the chardev at a time, else +``EINVAL`` is returned. Set the desired scancode in the ``scancode`` member, +and the :ref:`IR protocol ` in the +:c:type:`rc_proto`: member. All other members must be +set to 0, else ``EINVAL`` is returned. If there is no protocol encoder +for the protocol or the scancode is not valid for the specified protocol, +``EINVAL`` is returned. The write function blocks until the scancode +is transmitted by the hardware. + +Return Value +============ + +On success, the number of bytes written is returned. It is not an error if +this number is smaller than the number of bytes requested, or the amount +of data required for one frame. On error, -1 is returned, and the ``errno`` +variable is set appropriately. The generic error codes are described at the +:ref:`Generic Error Codes ` chapter. diff --git a/Documentation/userspace-api/media/rc/rc-intro.rst b/Documentation/userspace-api/media/rc/rc-intro.rst new file mode 100644 index 000000000..2ba62cde2 --- /dev/null +++ b/Documentation/userspace-api/media/rc/rc-intro.rst @@ -0,0 +1,24 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +.. _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/userspace-api/media/rc/rc-protos.rst b/Documentation/userspace-api/media/rc/rc-protos.rst new file mode 100644 index 000000000..a2eab3b45 --- /dev/null +++ b/Documentation/userspace-api/media/rc/rc-protos.rst @@ -0,0 +1,454 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +.. _Remote_controllers_Protocols: + +***************************************** +Remote Controller Protocols and Scancodes +***************************************** + +IR is encoded as a series of pulses and spaces, using a protocol. These +protocols can encode e.g. an address (which device should respond) and a +command: what it should do. The values for these are not always consistent +across different devices for a given protocol. + +Therefore out the output of the IR decoder is a scancode; a single u32 +value. Using keymap tables this can be mapped to linux key codes. + +Other things can be encoded too. Some IR protocols encode a toggle bit; this +is to distinguish whether the same button is being held down, or has been +released and pressed again. If has been released and pressed again, the +toggle bit will invert from one IR message to the next. + +Some remotes have a pointer-type device which can used to control the +mouse; some air conditioning systems can have their target temperature +target set in IR. + +The following are the protocols the kernel knows about and also lists +how scancodes are encoded for each protocol. + +rc-5 (RC_PROTO_RC5) +------------------- + +This IR protocol uses manchester encoding to encode 14 bits. There is a +detailed description here https://www.sbprojects.net/knowledge/ir/rc5.php. + +The scancode encoding is *not* consistent with the lirc daemon (lircd) rc5 +protocol, or the manchester BPF decoder. + +.. flat-table:: rc5 bits scancode mapping + :widths: 1 1 2 + + * - rc-5 bit + + - scancode bit + + - description + + * - 1 + + - none + + - Start bit, always set + + * - 1 + + - 6 (inverted) + + - 2nd start bit in rc5, re-used as 6th command bit + + * - 1 + + - none + + - Toggle bit + + * - 5 + + - 8 to 13 + + - Address + + * - 6 + + - 0 to 5 + + - Command + +There is a variant of rc5 called either rc5x or extended rc5 +where there the second stop bit is the 6th commmand bit, but inverted. +This is done so it the scancodes and encoding is compatible with existing +schemes. This bit is stored in bit 6 of the scancode, inverted. This is +done to keep it compatible with plain rc-5 where there are two start bits. + +rc-5-sz (RC_PROTO_RC5_SZ) +------------------------- +This is much like rc-5 but one bit longer. The scancode is encoded +differently. + +.. flat-table:: rc-5-sz bits scancode mapping + :widths: 1 1 2 + + * - rc-5-sz bits + + - scancode bit + + - description + + * - 1 + + - none + + - Start bit, always set + + * - 1 + + - 13 + + - Address bit + + * - 1 + + - none + + - Toggle bit + + * - 6 + + - 6 to 11 + + - Address + + * - 6 + + - 0 to 5 + + - Command + +rc-5x-20 (RC_PROTO_RC5X_20) +--------------------------- + +This rc-5 extended to encoded 20 bits. The is a 3555 microseconds space +after the 8th bit. + +.. flat-table:: rc-5x-20 bits scancode mapping + :widths: 1 1 2 + + * - rc-5-sz bits + + - scancode bit + + - description + + * - 1 + + - none + + - Start bit, always set + + * - 1 + + - 14 + + - Address bit + + * - 1 + + - none + + - Toggle bit + + * - 5 + + - 16 to 20 + + - Address + + * - 6 + + - 8 to 13 + + - Address + + * - 6 + + - 0 to 5 + + - Command + + +jvc (RC_PROTO_JVC) +------------------ + +The jvc protocol is much like nec, without the inverted values. It is +described here https://www.sbprojects.net/knowledge/ir/jvc.php. + +The scancode is a 16 bits value, where the address is the lower 8 bits +and the command the higher 8 bits; this is reversed from IR order. + +sony-12 (RC_PROTO_SONY12) +------------------------- + +The sony protocol is a pulse-width encoding. There are three variants, +which just differ in number of bits and scancode encoding. + +.. flat-table:: sony-12 bits scancode mapping + :widths: 1 1 2 + + * - sony-12 bits + + - scancode bit + + - description + + * - 5 + + - 16 to 20 + + - device + + * - 7 + + - 0 to 6 + + - function + +sony-15 (RC_PROTO_SONY15) +------------------------- + +The sony protocol is a pulse-width encoding. There are three variants, +which just differ in number of bits and scancode encoding. + +.. flat-table:: sony-12 bits scancode mapping + :widths: 1 1 2 + + * - sony-12 bits + + - scancode bit + + - description + + * - 8 + + - 16 to 23 + + - device + + * - 7 + + - 0 to 6 + + - function + +sony-20 (RC_PROTO_SONY20) +------------------------- + +The sony protocol is a pulse-width encoding. There are three variants, +which just differ in number of bits and scancode encoding. + +.. flat-table:: sony-20 bits scancode mapping + :widths: 1 1 2 + + * - sony-20 bits + + - scancode bit + + - description + + * - 5 + + - 16 to 20 + + - device + + * - 7 + + - 0 to 7 + + - device + + * - 8 + + - 8 to 15 + + - extended bits + +nec (RC_PROTO_NEC) +------------------ + +The nec protocol encodes an 8 bit address and an 8 bit command. It is +described here https://www.sbprojects.net/knowledge/ir/nec.php. Note +that the protocol sends least significant bit first. + +As a check, the nec protocol sends the address and command twice; the +second time it is inverted. This is done for verification. + +A plain nec IR message has 16 bits; the high 8 bits are the address +and the low 8 bits are the command. + +nec-x (RC_PROTO_NECX) +--------------------- + +Extended nec has a 16 bit address and a 8 bit command. This is encoded +as a 24 bit value as you would expect, with the lower 8 bits the command +and the upper 16 bits the address. + +nec-32 (RC_PROTO_NEC32) +----------------------- + +nec-32 does not send an inverted address or an inverted command; the +entire message, all 32 bits, are used. + +For this to be decoded correctly, the second 8 bits must not be the +inverted value of the first, and also the last 8 bits must not be the +inverted value of the third 8 bit value. + +The scancode has a somewhat unusual encoding. + +.. flat-table:: nec-32 bits scancode mapping + + * - nec-32 bits + + - scancode bit + + * - First 8 bits + + - 16 to 23 + + * - Second 8 bits + + - 24 to 31 + + * - Third 8 bits + + - 0 to 7 + + * - Fourth 8 bits + + - 8 to 15 + +sanyo (RC_PROTO_SANYO) +---------------------- + +The sanyo protocol is like the nec protocol, but with 13 bits address +rather than 8 bits. Both the address and the command are followed by +their inverted versions, but these are not present in the scancodes. + +Bis 8 to 20 of the scancode is the 13 bits address, and the lower 8 +bits are the command. + +mcir2-kbd (RC_PROTO_MCIR2_KBD) +------------------------------ + +This protocol is generated by the Microsoft MCE keyboard for keyboard +events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded. + +mcir2-mse (RC_PROTO_MCIR2_MSE) +------------------------------ + +This protocol is generated by the Microsoft MCE keyboard for pointer +events. Refer to the ir-mce_kbd-decoder.c to see how it is encoded. + +rc-6-0 (RC_PROTO_RC6_0) +----------------------- + +This is the rc-6 in mode 0. rc-6 is described here +https://www.sbprojects.net/knowledge/ir/rc6.php. +The scancode is the exact 16 bits as in the protocol. There is also a +toggle bit. + +rc-6-6a-20 (RC_PROTO_RC6_6A_20) +------------------------------- + +This is the rc-6 in mode 6a, 20 bits. rc-6 is described here +https://www.sbprojects.net/knowledge/ir/rc6.php. +The scancode is the exact 20 bits +as in the protocol. There is also a toggle bit. + +rc-6-6a-24 (RC_PROTO_RC6_6A_24) +------------------------------- + +This is the rc-6 in mode 6a, 24 bits. rc-6 is described here +https://www.sbprojects.net/knowledge/ir/rc6.php. +The scancode is the exact 24 bits +as in the protocol. There is also a toggle bit. + +rc-6-6a-32 (RC_PROTO_RC6_6A_32) +------------------------------- + +This is the rc-6 in mode 6a, 32 bits. rc-6 is described here +https://www.sbprojects.net/knowledge/ir/rc6.php. +The upper 16 bits are the vendor, +and the lower 16 bits are the vendor-specific bits. This protocol is +for the non-Microsoft MCE variant (vendor != 0x800f). + + +rc-6-mce (RC_PROTO_RC6_MCE) +--------------------------- + +This is the rc-6 in mode 6a, 32 bits. The upper 16 bits are the vendor, +and the lower 16 bits are the vendor-specific bits. This protocol is +for the Microsoft MCE variant (vendor = 0x800f). The toggle bit in the +protocol itself is ignored, and the 16th bit should be takes as the toggle +bit. + +sharp (RC_PROTO_SHARP) +---------------------- + +This is a protocol used by Sharp VCRs, is described here +https://www.sbprojects.net/knowledge/ir/sharp.php. There is a very long +(40ms) space between the normal and inverted values, and some IR receivers +cannot decode this. + +There is a 5 bit address and a 8 bit command. In the scancode the address is +in bits 8 to 12, and the command in bits 0 to 7. + +xmp (RC_PROTO_XMP) +------------------ + +This protocol has several versions and only version 1 is supported. Refer +to the decoder (ir-xmp-decoder.c) to see how it is encoded. + + +cec (RC_PROTO_CEC) +------------------ + +This is not an IR protocol, this is a protocol over CEC. The CEC +infrastructure uses rc-core for handling CEC commands, so that they +can easily be remapped. + +imon (RC_PROTO_IMON) +-------------------- + +This protocol is used by Antec Veris/SoundGraph iMON remotes. + +The protocol +describes both button presses and pointer movements. The protocol encodes +31 bits, and the scancode is simply the 31 bits with the top bit always 0. + +rc-mm-12 (RC_PROTO_RCMM12) +-------------------------- + +The rc-mm protocol is described here +https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply +the 12 bits. + +rc-mm-24 (RC_PROTO_RCMM24) +-------------------------- + +The rc-mm protocol is described here +https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply +the 24 bits. + +rc-mm-32 (RC_PROTO_RCMM32) +-------------------------- + +The rc-mm protocol is described here +https://www.sbprojects.net/knowledge/ir/rcmm.php. The scancode is simply +the 32 bits. + +xbox-dvd (RC_PROTO_XBOX_DVD) +---------------------------- + +This protocol is used by XBox DVD Remote, which was made for the original +XBox. There is no in-kernel decoder or encoder for this protocol. The usb +device decodes the protocol. There is a BPF decoder available in v4l-utils. diff --git a/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst new file mode 100644 index 000000000..34d6a0a1f --- /dev/null +++ b/Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst @@ -0,0 +1,144 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +.. _remote_controllers_sysfs_nodes: + +******************************* +Remote Controller's sysfs nodes +******************************* + +As defined at ``Documentation/ABI/testing/sysfs-class-rc``, those are +the sysfs nodes that control the Remote Controllers: + + +.. _sys_class_rc: + +/sys/class/rc/ +============== + +The ``/sys/class/rc/`` class sub-directory belongs to the Remote +Controller core and provides a sysfs interface for configuring infrared +remote controller receivers. + + +.. _sys_class_rc_rcN: + +/sys/class/rc/rcN/ +================== + +A ``/sys/class/rc/rcN`` directory is created for each remote control +receiver device where N is the number of the receiver. + + +.. _sys_class_rc_rcN_protocols: + +/sys/class/rc/rcN/protocols +=========================== + +Reading this file returns a list of available protocols, something like:: + + rc5 [rc6] nec jvc [sony] + +Enabled protocols are shown in [] brackets. + +Writing "+proto" will add a protocol to the list of enabled protocols. + +Writing "-proto" will remove a protocol from the list of enabled +protocols. + +Writing "proto" will enable only "proto". + +Writing "none" will disable all protocols. + +Write fails with ``EINVAL`` if an invalid protocol combination or unknown +protocol name is used. + + +.. _sys_class_rc_rcN_filter: + +/sys/class/rc/rcN/filter +======================== + +Sets the scancode filter expected value. + +Use in combination with ``/sys/class/rc/rcN/filter_mask`` to set the +expected value of the bits set in the filter mask. If the hardware +supports it then scancodes which do not match the filter will be +ignored. Otherwise the write will fail with an error. + +This value may be reset to 0 if the current protocol is altered. + + +.. _sys_class_rc_rcN_filter_mask: + +/sys/class/rc/rcN/filter_mask +============================= + +Sets the scancode filter mask of bits to compare. Use in combination +with ``/sys/class/rc/rcN/filter`` to set the bits of the scancode which +should be compared against the expected value. A value of 0 disables the +filter to allow all valid scancodes to be processed. + +If the hardware supports it then scancodes which do not match the filter +will be ignored. Otherwise the write will fail with an error. + +This value may be reset to 0 if the current protocol is altered. + + +.. _sys_class_rc_rcN_wakeup_protocols: + +/sys/class/rc/rcN/wakeup_protocols +================================== + +Reading this file returns a list of available protocols to use for the +wakeup filter, something like:: + + rc-5 nec nec-x rc-6-0 rc-6-6a-24 [rc-6-6a-32] rc-6-mce + +Note that protocol variants are listed, so ``nec``, ``sony``, ``rc-5``, ``rc-6`` +have their different bit length encodings listed if available. + +Note that all protocol variants are listed. + +The enabled wakeup protocol is shown in [] brackets. + +Only one protocol can be selected at a time. + +Writing "proto" will use "proto" for wakeup events. + +Writing "none" will disable wakeup. + +Write fails with ``EINVAL`` if an invalid protocol combination or unknown +protocol name is used, or if wakeup is not supported by the hardware. + + +.. _sys_class_rc_rcN_wakeup_filter: + +/sys/class/rc/rcN/wakeup_filter +=============================== + +Sets the scancode wakeup filter expected value. Use in combination with +``/sys/class/rc/rcN/wakeup_filter_mask`` to set the expected value of +the bits set in the wakeup filter mask to trigger a system wake event. + +If the hardware supports it and wakeup_filter_mask is not 0 then +scancodes which match the filter will wake the system from e.g. suspend +to RAM or power off. Otherwise the write will fail with an error. + +This value may be reset to 0 if the wakeup protocol is altered. + + +.. _sys_class_rc_rcN_wakeup_filter_mask: + +/sys/class/rc/rcN/wakeup_filter_mask +==================================== + +Sets the scancode wakeup filter mask of bits to compare. Use in +combination with ``/sys/class/rc/rcN/wakeup_filter`` to set the bits of +the scancode which should be compared against the expected value to +trigger a system wake event. + +If the hardware supports it and wakeup_filter_mask is not 0 then +scancodes which match the filter will wake the system from e.g. suspend +to RAM or power off. Otherwise the write will fail with an error. + +This value may be reset to 0 if the wakeup protocol is altered. diff --git a/Documentation/userspace-api/media/rc/rc-table-change.rst b/Documentation/userspace-api/media/rc/rc-table-change.rst new file mode 100644 index 000000000..d7de8a56d --- /dev/null +++ b/Documentation/userspace-api/media/rc/rc-table-change.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +.. _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/userspace-api/media/rc/rc-tables.rst b/Documentation/userspace-api/media/rc/rc-tables.rst new file mode 100644 index 000000000..28ed94088 --- /dev/null +++ b/Documentation/userspace-api/media/rc/rc-tables.rst @@ -0,0 +1,759 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later + +.. _Remote_controllers_tables: + +************************ +Remote controller tables +************************ + +Unfortunately, for several years, there was no effort to create uniform +IR keycodes for different devices. This caused the same IR keyname to be +mapped completely differently on different IR devices. This resulted +that the same IR keyname to be mapped completely different on different +IR's. Due to that, V4L2 API now specifies a standard for mapping Media +keys on IR. + +This standard should be used by both V4L/DVB drivers and userspace +applications + +The modules register the remote as keyboard within the linux input +layer. This means that the IR key strokes will look like normal keyboard +key strokes (if CONFIG_INPUT_KEYBOARD is enabled). Using the event +devices (CONFIG_INPUT_EVDEV) it is possible for applications to access +the remote via /dev/input/event devices. + + +.. _rc_standard_keymap: + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.5cm}| + +.. flat-table:: IR default keymapping + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + + - .. row 1 + + - Key code + + - Meaning + + - Key examples on IR + + - .. row 2 + + - **Numeric keys** + + - .. row 3 + + - ``KEY_NUMERIC_0`` + + - Keyboard digit 0 + + - 0 + + - .. row 4 + + - ``KEY_NUMERIC_1`` + + - Keyboard digit 1 + + - 1 + + - .. row 5 + + - ``KEY_NUMERIC_2`` + + - Keyboard digit 2 + + - 2 + + - .. row 6 + + - ``KEY_NUMERIC_3`` + + - Keyboard digit 3 + + - 3 + + - .. row 7 + + - ``KEY_NUMERIC_4`` + + - Keyboard digit 4 + + - 4 + + - .. row 8 + + - ``KEY_NUMERIC_5`` + + - Keyboard digit 5 + + - 5 + + - .. row 9 + + - ``KEY_NUMERIC_6`` + + - Keyboard digit 6 + + - 6 + + - .. row 10 + + - ``KEY_NUMERIC_7`` + + - Keyboard digit 7 + + - 7 + + - .. row 11 + + - ``KEY_NUMERIC_8`` + + - Keyboard digit 8 + + - 8 + + - .. row 12 + + - ``KEY_NUMERIC_9`` + + - Keyboard digit 9 + + - 9 + + - .. row 13 + + - **Movie play control** + + - .. row 14 + + - ``KEY_FORWARD`` + + - Instantly advance in time + + - >> / FORWARD + + - .. row 15 + + - ``KEY_BACK`` + + - Instantly go back in time + + - <<< / BACK + + - .. row 16 + + - ``KEY_FASTFORWARD`` + + - Play movie faster + + - >>> / FORWARD + + - .. row 17 + + - ``KEY_REWIND`` + + - Play movie back + + - REWIND / BACKWARD + + - .. row 18 + + - ``KEY_NEXT`` + + - Select next chapter / sub-chapter / interval + + - NEXT / SKIP + + - .. row 19 + + - ``KEY_PREVIOUS`` + + - Select previous chapter / sub-chapter / interval + + - << / PREV / PREVIOUS + + - .. row 20 + + - ``KEY_AGAIN`` + + - Repeat the video or a video interval + + - REPEAT / LOOP / RECALL + + - .. row 21 + + - ``KEY_PAUSE`` + + - Pause stream + + - PAUSE / FREEZE + + - .. row 22 + + - ``KEY_PLAY`` + + - Play movie at the normal timeshift + + - NORMAL TIMESHIFT / LIVE / > + + - .. row 23 + + - ``KEY_PLAYPAUSE`` + + - Alternate between play and pause + + - PLAY / PAUSE + + - .. row 24 + + - ``KEY_STOP`` + + - Stop stream + + - STOP + + - .. row 25 + + - ``KEY_RECORD`` + + - Start/stop recording stream + + - CAPTURE / REC / RECORD/PAUSE + + - .. row 26 + + - ``KEY_CAMERA`` + + - Take a picture of the image + + - CAMERA ICON / CAPTURE / SNAPSHOT + + - .. row 27 + + - ``KEY_SHUFFLE`` + + - Enable shuffle mode + + - SHUFFLE + + - .. row 28 + + - ``KEY_TIME`` + + - Activate time shift mode + + - TIME SHIFT + + - .. row 29 + + - ``KEY_TITLE`` + + - Allow changing the chapter + + - CHAPTER + + - .. row 30 + + - ``KEY_SUBTITLE`` + + - Allow changing the subtitle + + - SUBTITLE + + - .. row 31 + + - **Image control** + + - .. row 32 + + - ``KEY_BRIGHTNESSDOWN`` + + - Decrease Brightness + + - BRIGHTNESS DECREASE + + - .. row 33 + + - ``KEY_BRIGHTNESSUP`` + + - Increase Brightness + + - BRIGHTNESS INCREASE + + - .. row 34 + + - ``KEY_ANGLE`` + + - Switch video camera angle (on videos with more than one angle + stored) + + - ANGLE / SWAP + + - .. row 35 + + - ``KEY_EPG`` + + - Open the Elecrowonic Play Guide (EPG) + + - EPG / GUIDE + + - .. row 36 + + - ``KEY_TEXT`` + + - Activate/change closed caption mode + + - CLOSED CAPTION/TELETEXT / DVD TEXT / TELETEXT / TTX + + - .. row 37 + + - **Audio control** + + - .. row 38 + + - ``KEY_AUDIO`` + + - Change audio source + + - AUDIO SOURCE / AUDIO / MUSIC + + - .. row 39 + + - ``KEY_MUTE`` + + - Mute/unmute audio + + - MUTE / DEMUTE / UNMUTE + + - .. row 40 + + - ``KEY_VOLUMEDOWN`` + + - Decrease volume + + - VOLUME- / VOLUME DOWN + + - .. row 41 + + - ``KEY_VOLUMEUP`` + + - Increase volume + + - VOLUME+ / VOLUME UP + + - .. row 42 + + - ``KEY_MODE`` + + - Change sound mode + + - MONO/STEREO + + - .. row 43 + + - ``KEY_LANGUAGE`` + + - Select Language + + - 1ST / 2ND LANGUAGE / DVD LANG / MTS/SAP / MTS SEL + + - .. row 44 + + - **Channel control** + + - .. row 45 + + - ``KEY_CHANNEL`` + + - Go to the next favorite channel + + - ALT / CHANNEL / CH SURFING / SURF / FAV + + - .. row 46 + + - ``KEY_CHANNELDOWN`` + + - Decrease channel sequentially + + - CHANNEL - / CHANNEL DOWN / DOWN + + - .. row 47 + + - ``KEY_CHANNELUP`` + + - Increase channel sequentially + + - CHANNEL + / CHANNEL UP / UP + + - .. row 48 + + - ``KEY_DIGITS`` + + - Use more than one digit for channel + + - PLUS / 100/ 1xx / xxx / -/-- / Single Double Triple Digit + + - .. row 49 + + - ``KEY_SEARCH`` + + - Start channel autoscan + + - SCAN / AUTOSCAN + + - .. row 50 + + - **Colored keys** + + - .. row 51 + + - ``KEY_BLUE`` + + - IR Blue key + + - BLUE + + - .. row 52 + + - ``KEY_GREEN`` + + - IR Green Key + + - GREEN + + - .. row 53 + + - ``KEY_RED`` + + - IR Red key + + - RED + + - .. row 54 + + - ``KEY_YELLOW`` + + - IR Yellow key + + - YELLOW + + - .. row 55 + + - **Media selection** + + - .. row 56 + + - ``KEY_CD`` + + - Change input source to Compact Disc + + - CD + + - .. row 57 + + - ``KEY_DVD`` + + - Change input to DVD + + - DVD / DVD MENU + + - .. row 58 + + - ``KEY_EJECTCLOSECD`` + + - Open/close the CD/DVD player + + - -> ) / CLOSE / OPEN + + - .. row 59 + + - ``KEY_MEDIA`` + + - Turn on/off Media application + + - PC/TV / TURN ON/OFF APP + + - .. row 60 + + - ``KEY_PC`` + + - Selects from TV to PC + + - PC + + - .. row 61 + + - ``KEY_RADIO`` + + - Put into AM/FM radio mode + + - RADIO / TV/FM / TV/RADIO / FM / FM/RADIO + + - .. row 62 + + - ``KEY_TV`` + + - Select tv mode + + - TV / LIVE TV + + - .. row 63 + + - ``KEY_TV2`` + + - Select Cable mode + + - AIR/CBL + + - .. row 64 + + - ``KEY_VCR`` + + - Select VCR mode + + - VCR MODE / DTR + + - .. row 65 + + - ``KEY_VIDEO`` + + - Alternate between input modes + + - SOURCE / SELECT / DISPLAY / SWITCH INPUTS / VIDEO + + - .. row 66 + + - **Power control** + + - .. row 67 + + - ``KEY_POWER`` + + - Turn on/off computer + + - SYSTEM POWER / COMPUTER POWER + + - .. row 68 + + - ``KEY_POWER2`` + + - Turn on/off application + + - TV ON/OFF / POWER + + - .. row 69 + + - ``KEY_SLEEP`` + + - Activate sleep timer + + - SLEEP / SLEEP TIMER + + - .. row 70 + + - ``KEY_SUSPEND`` + + - Put computer into suspend mode + + - STANDBY / SUSPEND + + - .. row 71 + + - **Window control** + + - .. row 72 + + - ``KEY_CLEAR`` + + - Stop stream and return to default input video/audio + + - CLEAR / RESET / BOSS KEY + + - .. row 73 + + - ``KEY_CYCLEWINDOWS`` + + - Minimize windows and move to the next one + + - ALT-TAB / MINIMIZE / DESKTOP + + - .. row 74 + + - ``KEY_FAVORITES`` + + - Open the favorites stream window + + - TV WALL / Favorites + + - .. row 75 + + - ``KEY_MENU`` + + - Call application menu + + - 2ND CONTROLS (USA: MENU) / DVD/MENU / SHOW/HIDE CTRL + + - .. row 76 + + - ``KEY_NEW`` + + - Open/Close Picture in Picture + + - PIP + + - .. row 77 + + - ``KEY_OK`` + + - Send a confirmation code to application + + - OK / ENTER / RETURN + + - .. row 78 + + - ``KEY_ASPECT_RATIO`` + + - Select screen aspect ratio + + - 4:3 16:9 SELECT + + - .. row 79 + + - ``KEY_FULL_SCREEN`` + + - Put device into zoom/full screen mode + + - ZOOM / FULL SCREEN / ZOOM+ / HIDE PANNEL / SWITCH + + - .. row 80 + + - **Navigation keys** + + - .. row 81 + + - ``KEY_ESC`` + + - Cancel current operation + + - CANCEL / BACK + + - .. row 82 + + - ``KEY_HELP`` + + - Open a Help window + + - HELP + + - .. row 83 + + - ``KEY_HOMEPAGE`` + + - Navigate to Homepage + + - HOME + + - .. row 84 + + - ``KEY_INFO`` + + - Open On Screen Display + + - DISPLAY INFORMATION / OSD + + - .. row 85 + + - ``KEY_WWW`` + + - Open the default browser + + - WEB + + - .. row 86 + + - ``KEY_UP`` + + - Up key + + - UP + + - .. row 87 + + - ``KEY_DOWN`` + + - Down key + + - DOWN + + - .. row 88 + + - ``KEY_LEFT`` + + - Left key + + - LEFT + + - .. row 89 + + - ``KEY_RIGHT`` + + - Right key + + - RIGHT + + - .. row 90 + + - **Miscellaneous keys** + + - .. row 91 + + - ``KEY_DOT`` + + - Return a dot + + - . + + - .. row 92 + + - ``KEY_FN`` + + - Select a function + + - FUNCTION + + +It should be noted that, sometimes, there some fundamental missing keys +at some cheaper IR's. Due to that, it is recommended to: + + +.. _rc_keymap_notes: + +.. flat-table:: Notes + :header-rows: 0 + :stub-columns: 0 + + + - .. row 1 + + - On simpler IR's, without separate channel keys, you need to map UP + as ``KEY_CHANNELUP`` + + - .. row 2 + + - On simpler IR's, without separate channel keys, you need to map + DOWN as ``KEY_CHANNELDOWN`` + + - .. row 3 + + - On simpler IR's, without separate volume keys, you need to map + LEFT as ``KEY_VOLUMEDOWN`` + + - .. row 4 + + - On simpler IR's, without separate volume keys, you need to map + RIGHT as ``KEY_VOLUMEUP`` diff --git a/Documentation/userspace-api/media/rc/remote_controllers.rst b/Documentation/userspace-api/media/rc/remote_controllers.rst new file mode 100644 index 000000000..f89291838 --- /dev/null +++ b/Documentation/userspace-api/media/rc/remote_controllers.rst @@ -0,0 +1,51 @@ +.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later +.. include:: + +.. _remote_controllers: + +################################ +Part III - Remote Controller API +################################ + +.. only:: html + + .. class:: toc-title + + Table of Contents + +.. toctree:: + :maxdepth: 5 + :numbered: + + rc-intro + rc-sysfs-nodes + rc-protos + rc-tables + rc-table-change + lirc-dev + + +********************** +Revision and Copyright +********************** + +Authors: + +- Carvalho Chehab, Mauro + + - Initial version. + +**Copyright** |copy| 2009-2016 : Mauro Carvalho Chehab + +**************** +Revision History +**************** + +:revision: 3.15 / 2014-02-06 (*mcc*) + +Added the interface description and the RC sysfs class description. + + +:revision: 1.0 / 2009-09-06 (*mcc*) + +Initial revision diff --git a/Documentation/userspace-api/media/typical_media_device.svg b/Documentation/userspace-api/media/typical_media_device.svg new file mode 100644 index 000000000..fca7af8e4 --- /dev/null +++ b/Documentation/userspace-api/media/typical_media_device.svg @@ -0,0 +1,107 @@ + + +image/svg+xmlAudio decoder +Video decoder +Audio encoder +Button Key/IR input logic +EEPROM +Sensor +System Bus +Demux +Conditional Access Module +Video encoder +Radio / Analog TV +Digital TV +PS.: picture is not complete: other blocks may be present +Webcam +Processing blocks +Smartcard +TunerFM/TV +Satellite Equipment Control (SEC) +Demod +I2C Bus (control bus) +Digital TV Frontend + +CPU +PCI, USB, SPI, I2C, ... +Bridge + DMA + diff --git a/Documentation/userspace-api/media/v4l/app-pri.rst b/Documentation/userspace-api/media/v4l/app-pri.rst new file mode 100644 index 000000000..626a42f2e --- /dev/null +++ b/Documentation/userspace-api/media/v4l/app-pri.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _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/userspace-api/media/v4l/audio.rst b/Documentation/userspace-api/media/v4l/audio.rst new file mode 100644 index 000000000..17f0b1c89 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/audio.rst @@ -0,0 +1,97 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _audio: + +************************ +Audio Inputs and Outputs +************************ + +Audio inputs and outputs are physical connectors of a device. Video +capture devices have inputs, output devices have outputs, zero or more +each. Radio devices have no audio inputs or outputs. They have exactly +one tuner which in fact *is* an audio source, but this API associates +tuners with video inputs or outputs only, and radio devices have none of +these. [#f1]_ A connector on a TV card to loop back the received audio +signal to a sound card is not considered an audio output. + +Audio and video inputs and outputs are associated. Selecting a video +source also selects an audio source. This is most evident when the video +and audio source is a tuner. Further audio connectors can combine with +more than one video input or output. Assumed two composite video inputs +and two audio inputs exist, there may be up to four valid combinations. +The relation of video and audio connectors is defined in the +``audioset`` field of the respective struct +:c:type:`v4l2_input` or struct +:c:type:`v4l2_output`, where each bit represents the index +number, starting at zero, of one audio input or output. + +To learn about the number and attributes of the available inputs and +outputs applications can enumerate them with the +:ref:`VIDIOC_ENUMAUDIO` and +:ref:`VIDIOC_ENUMAUDOUT ` ioctl, respectively. +The struct :c:type:`v4l2_audio` returned by the +:ref:`VIDIOC_ENUMAUDIO` ioctl also contains signal +status information applicable when the current audio input is queried. + +The :ref:`VIDIOC_G_AUDIO ` and +:ref:`VIDIOC_G_AUDOUT ` ioctls report the current +audio input and output, respectively. + +.. note:: + + Note that, unlike :ref:`VIDIOC_G_INPUT ` and + :ref:`VIDIOC_G_OUTPUT ` these ioctls return a + structure as :ref:`VIDIOC_ENUMAUDIO` and + :ref:`VIDIOC_ENUMAUDOUT ` do, not just an index. + +To select an audio input and change its properties applications call the +:ref:`VIDIOC_S_AUDIO ` ioctl. To select an audio +output (which presently has no changeable properties) applications call +the :ref:`VIDIOC_S_AUDOUT ` ioctl. + +Drivers must implement all audio input ioctls when the device has +multiple selectable audio inputs, all audio output ioctls when the +device has multiple selectable audio outputs. When the device has any +audio inputs or outputs the driver must set the ``V4L2_CAP_AUDIO`` flag +in the struct :c:type:`v4l2_capability` returned by +the :ref:`VIDIOC_QUERYCAP` ioctl. + + +Example: Information about the current audio input +================================================== + +.. code-block:: c + + struct v4l2_audio audio; + + memset(&audio, 0, sizeof(audio)); + + if (-1 == ioctl(fd, VIDIOC_G_AUDIO, &audio)) { + perror("VIDIOC_G_AUDIO"); + exit(EXIT_FAILURE); + } + + printf("Current input: %s\\n", audio.name); + + +Example: Switching to the first audio input +=========================================== + +.. code-block:: c + + struct v4l2_audio audio; + + memset(&audio, 0, sizeof(audio)); /* clear audio.mode, audio.reserved */ + + audio.index = 0; + + if (-1 == ioctl(fd, VIDIOC_S_AUDIO, &audio)) { + perror("VIDIOC_S_AUDIO"); + exit(EXIT_FAILURE); + } + +.. [#f1] + Actually struct :c:type:`v4l2_audio` ought to have a + ``tuner`` field like struct :c:type:`v4l2_input`, not + only making the API more consistent but also permitting radio devices + with multiple tuners. diff --git a/Documentation/userspace-api/media/v4l/bayer.svg b/Documentation/userspace-api/media/v4l/bayer.svg new file mode 100644 index 000000000..c500a28f0 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/bayer.svg @@ -0,0 +1,30 @@ + + +image/svg+xmlB +G +G +R +BGGR +B +G +G +R +GBRG +B +G +G +R +RGGB +B +G +G +R +GRBG + diff --git a/Documentation/userspace-api/media/v4l/biblio.rst b/Documentation/userspace-api/media/v4l/biblio.rst new file mode 100644 index 000000000..9cd18c153 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/biblio.rst @@ -0,0 +1,429 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +********** +References +********** + + +.. _cea608: + +CEA 608-E +========= + + +:title: CEA-608-E R-2014 "Line 21 Data Services" + +:author: Consumer Electronics Association (http://www.ce.org) + +.. _en300294: + +EN 300 294 +========== + + +:title: EN 300 294 "625-line television Wide Screen Signalling (WSS)" + +:author: European Telecommunication Standards Institute (http://www.etsi.org) + +.. _ets300231: + +ETS 300 231 +=========== + + +:title: ETS 300 231 "Specification of the domestic video Programme Delivery Control system (PDC)" + +:author: European Telecommunication Standards Institute (http://www.etsi.org) + +.. _ets300706: + +ETS 300 706 +=========== + + +:title: ETS 300 706 "Enhanced Teletext specification" + +:author: European Telecommunication Standards Institute (http://www.etsi.org) + +.. _mpeg2part1: + +ISO 13818-1 +=========== + + +:title: ITU-T Rec. H.222.0 | ISO/IEC 13818-1 "Information technology --- Generic coding of moving pictures and associated audio information: Systems" + +:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) + +.. _mpeg2part2: + +ISO 13818-2 +=========== + + +:title: ITU-T Rec. H.262 | ISO/IEC 13818-2 "Information technology --- Generic coding of moving pictures and associated audio information: Video" + +:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) + +.. _itu470: + +ITU BT.470 +========== + + +:title: ITU-R Recommendation BT.470-6 "Conventional Television Systems" + +:author: International Telecommunication Union (http://www.itu.ch) + +.. _itu601: + +ITU BT.601 +========== + + +:title: ITU-R Recommendation BT.601-5 "Studio Encoding Parameters of Digital Television for Standard 4:3 and Wide-Screen 16:9 Aspect Ratios" + +:author: International Telecommunication Union (http://www.itu.ch) + +.. _itu653: + +ITU BT.653 +========== + + +:title: ITU-R Recommendation BT.653-3 "Teletext systems" + +:author: International Telecommunication Union (http://www.itu.ch) + +.. _itu709: + +ITU BT.709 +========== + + +:title: ITU-R Recommendation BT.709-5 "Parameter values for the HDTV standards for production and international programme exchange" + +:author: International Telecommunication Union (http://www.itu.ch) + +.. _itu1119: + +ITU BT.1119 +=========== + + +:title: ITU-R Recommendation BT.1119 "625-line television Wide Screen Signalling (WSS)" + +:author: International Telecommunication Union (http://www.itu.ch) + +.. _h264: + +ITU-T Rec. H.264 Specification (04/2017 Edition) +================================================ + +:title: ITU-T Recommendation H.264 "Advanced Video Coding for Generic Audiovisual Services" + +:author: International Telecommunication Union (http://www.itu.ch) + +.. _hevc: + +ITU H.265/HEVC +============== + +:title: ITU-T Rec. H.265 | ISO/IEC 23008-2 "High Efficiency Video Coding" + +:author: International Telecommunication Union (http://www.itu.ch), International Organisation for Standardisation (http://www.iso.ch) + +.. _jfif: + +JFIF +==== + + +:title: JPEG File Interchange Format +:subtitle: Version 1.02 + +:author: Independent JPEG Group (http://www.ijg.org) + +.. _itu-t81: + +ITU-T.81 +======== + + +:title: ITU-T Recommendation T.81 "Information Technology --- Digital Compression and Coding of Continous-Tone Still Images --- Requirements and Guidelines" + +:author: International Telecommunication Union (http://www.itu.int) + +.. _w3c-jpeg-jfif: + +W3C JPEG JFIF +============= + + +:title: JPEG JFIF + +:author: The World Wide Web Consortium (http://www.w3.org) + +.. _smpte12m: + +SMPTE 12M +========= + + +:title: SMPTE 12M-1999 "Television, Audio and Film - Time and Control Code" + +:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) + +.. _smpte170m: + +SMPTE 170M +========== + + +:title: SMPTE 170M-1999 "Television - Composite Analog Video Signal - NTSC for Studio Applications" + +:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) + +.. _smpte240m: + +SMPTE 240M +========== + + +:title: SMPTE 240M-1999 "Television - Signal Parameters - 1125-Line High-Definition Production" + +:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) + +.. _smpte431: + +SMPTE RP 431-2 +============== + + +:title: SMPTE RP 431-2:2011 "D-Cinema Quality - Reference Projector and Environment" + +:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) + +.. _smpte2084: + +SMPTE ST 2084 +============= + + +:title: SMPTE ST 2084:2014 "High Dynamic Range Electro-Optical Transfer Function of Master Reference Displays" + +:author: Society of Motion Picture and Television Engineers (http://www.smpte.org) + +.. _srgb: + +sRGB +==== + + +:title: IEC 61966-2-1 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB" + +:author: International Electrotechnical Commission (http://www.iec.ch) + +.. _sycc: + +sYCC +==== + + +:title: IEC 61966-2-1-am1 ed1.0 "Amendment 1 - Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB" + +:author: International Electrotechnical Commission (http://www.iec.ch) + +.. _xvycc: + +xvYCC +===== + + +:title: IEC 61966-2-4 ed1.0 "Multimedia systems and equipment - Colour measurement and management - Part 2-4: Colour management - Extended-gamut YCC colour space for video applications - xvYCC" + +:author: International Electrotechnical Commission (http://www.iec.ch) + +.. _oprgb: + +opRGB +===== + + +:title: IEC 61966-2-5 "Multimedia systems and equipment - Colour measurement and management - Part 2-5: Colour management - Optional RGB colour space - opRGB" + +:author: International Electrotechnical Commission (http://www.iec.ch) + +.. _itu2020: + +ITU BT.2020 +=========== + + +:title: ITU-R Recommendation BT.2020 (08/2012) "Parameter values for ultra-high definition television systems for production and international programme exchange" + +:author: International Telecommunication Union (http://www.itu.ch) + +.. _tech3213: + +EBU Tech 3213 +============= + + +:title: E.B.U. Standard for Chromaticity Tolerances for Studio Monitors + +:author: European Broadcast Union (http://www.ebu.ch) + +.. _tech3321: + +EBU Tech 3321 +============= + + +:title: E.B.U. guidelines for Consumer Flat Panel Displays (FPDs) + +:author: European Broadcast Union (http://www.ebu.ch) + +.. _iec62106: + +IEC 62106 +========= + + +:title: Specification of the radio data system (RDS) for VHF/FM sound broadcasting in the frequency range from 87,5 to 108,0 MHz + +:author: International Electrotechnical Commission (http://www.iec.ch) + +.. _nrsc4: + +NRSC-4-B +======== + + +:title: NRSC-4-B: United States RBDS Standard + +:author: National Radio Systems Committee (http://www.nrscstandards.org) + +.. _iso12232: + +ISO 12232:2006 +============== + + +:title: Photography --- Digital still cameras --- Determination of exposure index, ISO speed ratings, standard output sensitivity, and recommended exposure index + +:author: International Organization for Standardization (http://www.iso.org) + +.. _cea861: + +CEA-861-E +========= + + +:title: A DTV Profile for Uncompressed High Speed Digital Interfaces + +:author: Consumer Electronics Association (http://www.ce.org) + +.. _vesadmt: + +VESA DMT +======== + + +:title: VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT) + +:author: Video Electronics Standards Association (http://www.vesa.org) + +.. _vesaedid: + +EDID +==== + + +:title: VESA Enhanced Extended Display Identification Data Standard +:subtitle: Release A, Revision 2 + +:author: Video Electronics Standards Association (http://www.vesa.org) + +.. _hdcp: + +HDCP +==== + + +:title: High-bandwidth Digital Content Protection System +:subtitle: Revision 1.3 + +:author: Digital Content Protection LLC (http://www.digital-cp.com) + +.. _hdmi: + +HDMI +==== + + +:title: High-Definition Multimedia Interface +:subtitle: Specification Version 1.4a + +:author: HDMI Licensing LLC (http://www.hdmi.org) + +.. _hdmi2: + +HDMI2 +===== + +:title: High-Definition Multimedia Interface +:subtitle: Specification Version 2.0 + +:author: HDMI Licensing LLC (http://www.hdmi.org) + +.. _dp: + +DP +== + + +:title: VESA DisplayPort Standard +:subtitle: Version 1, Revision 2 + +:author: Video Electronics Standards Association (http://www.vesa.org) + +.. _poynton: + +poynton +======= + + +:title: Digital Video and HDTV, Algorithms and Interfaces + +:author: Charles Poynton + +.. _colimg: + +colimg +====== + + +:title: Color Imaging: Fundamentals and Applications + +:author: Erik Reinhard et al. + +.. _vp8: + +VP8 +=== + + +:title: RFC 6386: "VP8 Data Format and Decoding Guide" + +:author: J. Bankoski et al. + +.. _vp9: + +VP9 +=== + + +:title: VP9 Bitstream & Decoding Process Specification + +:author: Adrian Grange (Google), Peter de Rivaz (Argon Design), Jonathan Hunt (Argon Design) diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst new file mode 100644 index 000000000..4638ec64d --- /dev/null +++ b/Documentation/userspace-api/media/v4l/buffer.rst @@ -0,0 +1,841 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L + +.. _buffer: + +******* +Buffers +******* + +A buffer contains data exchanged by application and driver using one of +the Streaming I/O methods. In the multi-planar API, the data is held in +planes, while the buffer structure acts as a container for the planes. +Only pointers to buffers (planes) are exchanged, the data itself is not +copied. These pointers, together with meta-information like timestamps +or field parity, are stored in a struct :c:type:`v4l2_buffer`, +argument to the :ref:`VIDIOC_QUERYBUF`, +:ref:`VIDIOC_QBUF ` and +:ref:`VIDIOC_DQBUF ` ioctl. In the multi-planar API, +some plane-specific members of struct :c:type:`v4l2_buffer`, +such as pointers and sizes for each plane, are stored in +struct :c:type:`v4l2_plane` instead. In that case, +struct :c:type:`v4l2_buffer` contains an array of plane structures. + +Dequeued video buffers come with timestamps. The driver decides at which +part of the frame and with which clock the timestamp is taken. Please +see flags in the masks ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` and +``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` in :ref:`buffer-flags`. These flags +are always valid and constant across all buffers during the whole video +stream. Changes in these flags may take place as a side effect of +:ref:`VIDIOC_S_INPUT ` or +:ref:`VIDIOC_S_OUTPUT ` however. The +``V4L2_BUF_FLAG_TIMESTAMP_COPY`` timestamp type which is used by e.g. on +mem-to-mem devices is an exception to the rule: the timestamp source +flags are copied from the OUTPUT video buffer to the CAPTURE video +buffer. + +Interactions between formats, controls and buffers +================================================== + +V4L2 exposes parameters that influence the buffer size, or the way data is +laid out in the buffer. Those parameters are exposed through both formats and +controls. One example of such a control is the ``V4L2_CID_ROTATE`` control +that modifies the direction in which pixels are stored in the buffer, as well +as the buffer size when the selected format includes padding at the end of +lines. + +The set of information needed to interpret the content of a buffer (e.g. the +pixel format, the line stride, the tiling orientation or the rotation) is +collectively referred to in the rest of this section as the buffer layout. + +Controls that can modify the buffer layout shall set the +``V4L2_CTRL_FLAG_MODIFY_LAYOUT`` flag. + +Modifying formats or controls that influence the buffer size or layout require +the stream to be stopped. Any attempt at such a modification while the stream +is active shall cause the ioctl setting the format or the control to return +the ``EBUSY`` error code. In that case drivers shall also set the +``V4L2_CTRL_FLAG_GRABBED`` flag when calling +:c:func:`VIDIOC_QUERYCTRL` or :c:func:`VIDIOC_QUERY_EXT_CTRL` for such a +control while the stream is active. + +.. note:: + + The :c:func:`VIDIOC_S_SELECTION` ioctl can, depending on the hardware (for + instance if the device doesn't include a scaler), modify the format in + addition to the selection rectangle. Similarly, the + :c:func:`VIDIOC_S_INPUT`, :c:func:`VIDIOC_S_OUTPUT`, :c:func:`VIDIOC_S_STD` + and :c:func:`VIDIOC_S_DV_TIMINGS` ioctls can also modify the format and + selection rectangles. When those ioctls result in a buffer size or layout + change, drivers shall handle that condition as they would handle it in the + :c:func:`VIDIOC_S_FMT` ioctl in all cases described in this section. + +Controls that only influence the buffer layout can be modified at any time +when the stream is stopped. As they don't influence the buffer size, no +special handling is needed to synchronize those controls with buffer +allocation and the ``V4L2_CTRL_FLAG_GRABBED`` flag is cleared once the +stream is stopped. + +Formats and controls that influence the buffer size interact with buffer +allocation. The simplest way to handle this is for drivers to always require +buffers to be reallocated in order to change those formats or controls. In +that case, to perform such changes, userspace applications shall first stop +the video stream with the :c:func:`VIDIOC_STREAMOFF` ioctl if it is running +and free all buffers with the :c:func:`VIDIOC_REQBUFS` ioctl if they are +allocated. After freeing all buffers the ``V4L2_CTRL_FLAG_GRABBED`` flag +for controls is cleared. The format or controls can then be modified, and +buffers shall then be reallocated and the stream restarted. A typical ioctl +sequence is + + #. VIDIOC_STREAMOFF + #. VIDIOC_REQBUFS(0) + #. VIDIOC_S_EXT_CTRLS + #. VIDIOC_S_FMT + #. VIDIOC_REQBUFS(n) + #. VIDIOC_QBUF + #. VIDIOC_STREAMON + +The second :c:func:`VIDIOC_REQBUFS` call will take the new format and control +value into account to compute the buffer size to allocate. Applications can +also retrieve the size by calling the :c:func:`VIDIOC_G_FMT` ioctl if needed. + +.. note:: + + The API doesn't mandate the above order for control (3.) and format (4.) + changes. Format and controls can be set in a different order, or even + interleaved, depending on the device and use case. For instance some + controls might behave differently for different pixel formats, in which + case the format might need to be set first. + +When reallocation is required, any attempt to modify format or controls that +influences the buffer size while buffers are allocated shall cause the format +or control set ioctl to return the ``EBUSY`` error. Any attempt to queue a +buffer too small for the current format or controls shall cause the +:c:func:`VIDIOC_QBUF` ioctl to return a ``EINVAL`` error. + +Buffer reallocation is an expensive operation. To avoid that cost, drivers can +(and are encouraged to) allow format or controls that influence the buffer +size to be changed with buffers allocated. In that case, a typical ioctl +sequence to modify format and controls is + + #. VIDIOC_STREAMOFF + #. VIDIOC_S_EXT_CTRLS + #. VIDIOC_S_FMT + #. VIDIOC_QBUF + #. VIDIOC_STREAMON + +For this sequence to operate correctly, queued buffers need to be large enough +for the new format or controls. Drivers shall return a ``ENOSPC`` error in +response to format change (:c:func:`VIDIOC_S_FMT`) or control changes +(:c:func:`VIDIOC_S_CTRL` or :c:func:`VIDIOC_S_EXT_CTRLS`) if buffers too small +for the new format are currently queued. As a simplification, drivers are +allowed to return a ``EBUSY`` error from these ioctls if any buffer is +currently queued, without checking the queued buffers sizes. + +Additionally, drivers shall return a ``EINVAL`` error from the +:c:func:`VIDIOC_QBUF` ioctl if the buffer being queued is too small for the +current format or controls. Together, these requirements ensure that queued +buffers will always be large enough for the configured format and controls. + +Userspace applications can query the buffer size required for a given format +and controls by first setting the desired control values and then trying the +desired format. The :c:func:`VIDIOC_TRY_FMT` ioctl will return the required +buffer size. + + #. VIDIOC_S_EXT_CTRLS(x) + #. VIDIOC_TRY_FMT() + #. VIDIOC_S_EXT_CTRLS(y) + #. VIDIOC_TRY_FMT() + +The :c:func:`VIDIOC_CREATE_BUFS` ioctl can then be used to allocate buffers +based on the queried sizes (for instance by allocating a set of buffers large +enough for all the desired formats and controls, or by allocating separate set +of appropriately sized buffers for each use case). + +.. c:type:: v4l2_buffer + +struct v4l2_buffer +================== + +.. tabularcolumns:: |p{2.9cm}|p{2.4cm}|p{12.0cm}| + +.. cssclass:: longtable + +.. flat-table:: struct v4l2_buffer + :header-rows: 0 + :stub-columns: 0 + :widths: 1 2 10 + + * - __u32 + - ``index`` + - Number of the buffer, set by the application except when calling + :ref:`VIDIOC_DQBUF `, then it is set by the + driver. This field can range from zero to the number of buffers + allocated with the :ref:`VIDIOC_REQBUFS` ioctl + (struct :c:type:`v4l2_requestbuffers` + ``count``), plus any buffers allocated with + :ref:`VIDIOC_CREATE_BUFS` minus one. + * - __u32 + - ``type`` + - Type of the buffer, same as struct + :c:type:`v4l2_format` ``type`` or struct + :c:type:`v4l2_requestbuffers` ``type``, set + by the application. See :c:type:`v4l2_buf_type` + * - __u32 + - ``bytesused`` + - The number of bytes occupied by the data in the buffer. It depends + on the negotiated data format and may change with each buffer for + compressed variable size data like JPEG images. Drivers must set + this field when ``type`` refers to a capture stream, applications + when it refers to an output stream. If the application sets this + to 0 for an output stream, then ``bytesused`` will be set to the + size of the buffer (see the ``length`` field of this struct) by + the driver. For multiplanar formats this field is ignored and the + ``planes`` pointer is used instead. + * - __u32 + - ``flags`` + - Flags set by the application or driver, see :ref:`buffer-flags`. + * - __u32 + - ``field`` + - Indicates the field order of the image in the buffer, see + :c:type:`v4l2_field`. This field is not used when the buffer + contains VBI data. Drivers must set it when ``type`` refers to a + capture stream, applications when it refers to an output stream. + * - struct timeval + - ``timestamp`` + - For capture streams this is time when the first data byte was + captured, as returned by the :c:func:`clock_gettime()` function + for the relevant clock id; see ``V4L2_BUF_FLAG_TIMESTAMP_*`` in + :ref:`buffer-flags`. For output streams the driver stores the + time at which the last data byte was actually sent out in the + ``timestamp`` field. This permits applications to monitor the + drift between the video and system clock. For output streams that + use ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` the application has to fill + in the timestamp which will be copied by the driver to the capture + stream. + * - struct :c:type:`v4l2_timecode` + - ``timecode`` + - When the ``V4L2_BUF_FLAG_TIMECODE`` flag is set in ``flags``, this + structure contains a frame timecode. In + :c:type:`V4L2_FIELD_ALTERNATE ` mode the top and + bottom field contain the same timecode. Timecodes are intended to + help video editing and are typically recorded on video tapes, but + also embedded in compressed formats like MPEG. This field is + independent of the ``timestamp`` and ``sequence`` fields. + * - __u32 + - ``sequence`` + - Set by the driver, counting the frames (not fields!) in sequence. + This field is set for both input and output devices. + * - :cspan:`2` + + In :c:type:`V4L2_FIELD_ALTERNATE ` mode the top and + bottom field have the same sequence number. The count starts at + zero and includes dropped or repeated frames. A dropped frame was + received by an input device but could not be stored due to lack of + free buffer space. A repeated frame was displayed again by an + output device because the application did not pass new data in + time. + + .. note:: + + This may count the frames received e.g. over USB, without + taking into account the frames dropped by the remote hardware due + to limited compression throughput or bus bandwidth. These devices + identify by not enumerating any video standards, see + :ref:`standard`. + + * - __u32 + - ``memory`` + - This field must be set by applications and/or drivers in + accordance with the selected I/O method. See :c:type:`v4l2_memory` + * - union { + - ``m`` + * - __u32 + - ``offset`` + - For the single-planar API and when ``memory`` is + ``V4L2_MEMORY_MMAP`` this is the offset of the buffer from the + start of the device memory. The value is returned by the driver + and apart of serving as parameter to the + :c:func:`mmap()` function not useful for applications. + See :ref:`mmap` for details + * - unsigned long + - ``userptr`` + - For the single-planar API and when ``memory`` is + ``V4L2_MEMORY_USERPTR`` this is a pointer to the buffer (casted to + unsigned long type) in virtual memory, set by the application. See + :ref:`userp` for details. + * - struct v4l2_plane + - ``*planes`` + - When using the multi-planar API, contains a userspace pointer to + an array of struct :c:type:`v4l2_plane`. The size of + the array should be put in the ``length`` field of this + struct :c:type:`v4l2_buffer` structure. + * - int + - ``fd`` + - For the single-plane API and when ``memory`` is + ``V4L2_MEMORY_DMABUF`` this is the file descriptor associated with + a DMABUF buffer. + * - } + - + * - __u32 + - ``length`` + - Size of the buffer (not the payload) in bytes for the + single-planar API. This is set by the driver based on the calls to + :ref:`VIDIOC_REQBUFS` and/or + :ref:`VIDIOC_CREATE_BUFS`. For the + multi-planar API the application sets this to the number of + elements in the ``planes`` array. The driver will fill in the + actual number of valid elements in that array. + * - __u32 + - ``reserved2`` + - A place holder for future extensions. Drivers and applications + must set this to 0. + * - __u32 + - ``request_fd`` + - The file descriptor of the request to queue the buffer to. If the flag + ``V4L2_BUF_FLAG_REQUEST_FD`` is set, then the buffer will be + queued to this request. If the flag is not set, then this field will + be ignored. + + The ``V4L2_BUF_FLAG_REQUEST_FD`` flag and this field are only used by + :ref:`ioctl VIDIOC_QBUF ` and ignored by other ioctls that + take a :c:type:`v4l2_buffer` as argument. + + Applications should not set ``V4L2_BUF_FLAG_REQUEST_FD`` for any ioctls + other than :ref:`VIDIOC_QBUF `. + + If the device does not support requests, then ``EBADR`` will be returned. + If requests are supported but an invalid request file descriptor is + given, then ``EINVAL`` will be returned. + + +.. c:type:: v4l2_plane + +struct v4l2_plane +================= + +.. tabularcolumns:: |p{3.5cm}|p{3.5cm}|p{10.3cm}| + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``bytesused`` + - The number of bytes occupied by data in the plane (its payload). + Drivers must set this field when ``type`` refers to a capture + stream, applications when it refers to an output stream. If the + application sets this to 0 for an output stream, then + ``bytesused`` will be set to the size of the plane (see the + ``length`` field of this struct) by the driver. + + .. note:: + + Note that the actual image data starts at ``data_offset`` + which may not be 0. + * - __u32 + - ``length`` + - Size in bytes of the plane (not its payload). This is set by the + driver based on the calls to + :ref:`VIDIOC_REQBUFS` and/or + :ref:`VIDIOC_CREATE_BUFS`. + * - union { + - ``m`` + * - __u32 + - ``mem_offset`` + - When the memory type in the containing struct + :c:type:`v4l2_buffer` is ``V4L2_MEMORY_MMAP``, this + is the value that should be passed to :c:func:`mmap()`, + similar to the ``offset`` field in struct + :c:type:`v4l2_buffer`. + * - unsigned long + - ``userptr`` + - When the memory type in the containing struct + :c:type:`v4l2_buffer` is ``V4L2_MEMORY_USERPTR``, + this is a userspace pointer to the memory allocated for this plane + by an application. + * - int + - ``fd`` + - When the memory type in the containing struct + :c:type:`v4l2_buffer` is ``V4L2_MEMORY_DMABUF``, + this is a file descriptor associated with a DMABUF buffer, similar + to the ``fd`` field in struct :c:type:`v4l2_buffer`. + * - } + - + * - __u32 + - ``data_offset`` + - Offset in bytes to video data in the plane. Drivers must set this + field when ``type`` refers to a capture stream, applications when + it refers to an output stream. + + .. note:: + + That data_offset is included in ``bytesused``. So the + size of the image in the plane is ``bytesused``-``data_offset`` + at offset ``data_offset`` from the start of the plane. + * - __u32 + - ``reserved[11]`` + - Reserved for future use. Should be zeroed by drivers and + applications. + + +.. c:type:: v4l2_buf_type + +enum v4l2_buf_type +================== + +.. cssclass:: longtable + +.. tabularcolumns:: |p{7.8cm}|p{0.6cm}|p{8.9cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 4 1 9 + + * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` + - 1 + - Buffer of a single-planar video capture stream, see + :ref:`capture`. + * - ``V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE`` + - 9 + - Buffer of a multi-planar video capture stream, see + :ref:`capture`. + * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT`` + - 2 + - Buffer of a single-planar video output stream, see + :ref:`output`. + * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE`` + - 10 + - Buffer of a multi-planar video output stream, see :ref:`output`. + * - ``V4L2_BUF_TYPE_VIDEO_OVERLAY`` + - 3 + - Buffer for video overlay, see :ref:`overlay`. + * - ``V4L2_BUF_TYPE_VBI_CAPTURE`` + - 4 + - Buffer of a raw VBI capture stream, see :ref:`raw-vbi`. + * - ``V4L2_BUF_TYPE_VBI_OUTPUT`` + - 5 + - Buffer of a raw VBI output stream, see :ref:`raw-vbi`. + * - ``V4L2_BUF_TYPE_SLICED_VBI_CAPTURE`` + - 6 + - Buffer of a sliced VBI capture stream, see :ref:`sliced`. + * - ``V4L2_BUF_TYPE_SLICED_VBI_OUTPUT`` + - 7 + - Buffer of a sliced VBI output stream, see :ref:`sliced`. + * - ``V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY`` + - 8 + - Buffer for video output overlay (OSD), see :ref:`osd`. + * - ``V4L2_BUF_TYPE_SDR_CAPTURE`` + - 11 + - Buffer for Software Defined Radio (SDR) capture stream, see + :ref:`sdr`. + * - ``V4L2_BUF_TYPE_SDR_OUTPUT`` + - 12 + - Buffer for Software Defined Radio (SDR) output stream, see + :ref:`sdr`. + * - ``V4L2_BUF_TYPE_META_CAPTURE`` + - 13 + - Buffer for metadata capture, see :ref:`metadata`. + * - ``V4L2_BUF_TYPE_META_OUTPUT`` + - 14 + - Buffer for metadata output, see :ref:`metadata`. + + +.. _buffer-flags: + +Buffer Flags +============ + +.. raw:: latex + + \footnotesize + +.. tabularcolumns:: |p{6.5cm}|p{1.8cm}|p{9.0cm}| + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 65 18 70 + + * .. _`V4L2-BUF-FLAG-MAPPED`: + + - ``V4L2_BUF_FLAG_MAPPED`` + - 0x00000001 + - The buffer resides in device memory and has been mapped into the + application's address space, see :ref:`mmap` for details. + Drivers set or clear this flag when the + :ref:`VIDIOC_QUERYBUF`, + :ref:`VIDIOC_QBUF` or + :ref:`VIDIOC_DQBUF ` ioctl is called. Set by the + driver. + * .. _`V4L2-BUF-FLAG-QUEUED`: + + - ``V4L2_BUF_FLAG_QUEUED`` + - 0x00000002 + - Internally drivers maintain two buffer queues, an incoming and + outgoing queue. When this flag is set, the buffer is currently on + the incoming queue. It automatically moves to the outgoing queue + after the buffer has been filled (capture devices) or displayed + (output devices). Drivers set or clear this flag when the + ``VIDIOC_QUERYBUF`` ioctl is called. After (successful) calling + the ``VIDIOC_QBUF``\ ioctl it is always set and after + ``VIDIOC_DQBUF`` always cleared. + * .. _`V4L2-BUF-FLAG-DONE`: + + - ``V4L2_BUF_FLAG_DONE`` + - 0x00000004 + - When this flag is set, the buffer is currently on the outgoing + queue, ready to be dequeued from the driver. Drivers set or clear + this flag when the ``VIDIOC_QUERYBUF`` ioctl is called. After + calling the ``VIDIOC_QBUF`` or ``VIDIOC_DQBUF`` it is always + cleared. Of course a buffer cannot be on both queues at the same + time, the ``V4L2_BUF_FLAG_QUEUED`` and ``V4L2_BUF_FLAG_DONE`` flag + are mutually exclusive. They can be both cleared however, then the + buffer is in "dequeued" state, in the application domain so to + say. + * .. _`V4L2-BUF-FLAG-ERROR`: + + - ``V4L2_BUF_FLAG_ERROR`` + - 0x00000040 + - When this flag is set, the buffer has been dequeued successfully, + although the data might have been corrupted. This is recoverable, + streaming may continue as normal and the buffer may be reused + normally. Drivers set this flag when the ``VIDIOC_DQBUF`` ioctl is + called. + * .. _`V4L2-BUF-FLAG-IN-REQUEST`: + + - ``V4L2_BUF_FLAG_IN_REQUEST`` + - 0x00000080 + - This buffer is part of a request that hasn't been queued yet. + * .. _`V4L2-BUF-FLAG-KEYFRAME`: + + - ``V4L2_BUF_FLAG_KEYFRAME`` + - 0x00000008 + - Drivers set or clear this flag when calling the ``VIDIOC_DQBUF`` + ioctl. It may be set by video capture devices when the buffer + contains a compressed image which is a key frame (or field), i. e. + can be decompressed on its own. Also known as an I-frame. + Applications can set this bit when ``type`` refers to an output + stream. + * .. _`V4L2-BUF-FLAG-PFRAME`: + + - ``V4L2_BUF_FLAG_PFRAME`` + - 0x00000010 + - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags predicted frames + or fields which contain only differences to a previous key frame. + Applications can set this bit when ``type`` refers to an output + stream. + * .. _`V4L2-BUF-FLAG-BFRAME`: + + - ``V4L2_BUF_FLAG_BFRAME`` + - 0x00000020 + - Similar to ``V4L2_BUF_FLAG_KEYFRAME`` this flags a bi-directional + predicted frame or field which contains only the differences + between the current frame and both the preceding and following key + frames to specify its content. Applications can set this bit when + ``type`` refers to an output stream. + * .. _`V4L2-BUF-FLAG-TIMECODE`: + + - ``V4L2_BUF_FLAG_TIMECODE`` + - 0x00000100 + - The ``timecode`` field is valid. Drivers set or clear this flag + when the ``VIDIOC_DQBUF`` ioctl is called. Applications can set + this bit and the corresponding ``timecode`` structure when + ``type`` refers to an output stream. + * .. _`V4L2-BUF-FLAG-PREPARED`: + + - ``V4L2_BUF_FLAG_PREPARED`` + - 0x00000400 + - The buffer has been prepared for I/O and can be queued by the + application. Drivers set or clear this flag when the + :ref:`VIDIOC_QUERYBUF`, + :ref:`VIDIOC_PREPARE_BUF `, + :ref:`VIDIOC_QBUF` or + :ref:`VIDIOC_DQBUF ` ioctl is called. + * .. _`V4L2-BUF-FLAG-NO-CACHE-INVALIDATE`: + + - ``V4L2_BUF_FLAG_NO_CACHE_INVALIDATE`` + - 0x00000800 + - Caches do not have to be invalidated for this buffer. Typically + applications shall use this flag if the data captured in the + buffer is not going to be touched by the CPU, instead the buffer + will, probably, be passed on to a DMA-capable hardware unit for + further processing or output. This flag is ignored unless the + queue is used for :ref:`memory mapping ` streaming I/O and + reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + ` capability. + * .. _`V4L2-BUF-FLAG-NO-CACHE-CLEAN`: + + - ``V4L2_BUF_FLAG_NO_CACHE_CLEAN`` + - 0x00001000 + - Caches do not have to be cleaned for this buffer. Typically + applications shall use this flag for output buffers if the data in + this buffer has not been created by the CPU but by some + DMA-capable unit, in which case caches have not been used. This flag + is ignored unless the queue is used for :ref:`memory mapping ` + streaming I/O and reports :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + ` capability. + * .. _`V4L2-BUF-FLAG-M2M-HOLD-CAPTURE-BUF`: + + - ``V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF`` + - 0x00000200 + - Only valid if struct :c:type:`v4l2_requestbuffers` flag ``V4L2_BUF_CAP_SUPPORTS_M2M_HOLD_CAPTURE_BUF`` is + set. It is typically used with stateless decoders where multiple + output buffers each decode to a slice of the decoded frame. + Applications can set this flag when queueing the output buffer + to prevent the driver from dequeueing the capture buffer after + the output buffer has been decoded (i.e. the capture buffer is + 'held'). If the timestamp of this output buffer differs from that + of the previous output buffer, then that indicates the start of a + new frame and the previously held capture buffer is dequeued. + * .. _`V4L2-BUF-FLAG-LAST`: + + - ``V4L2_BUF_FLAG_LAST`` + - 0x00100000 + - Last buffer produced by the hardware. mem2mem codec drivers set + this flag on the capture queue for the last buffer when the + :ref:`VIDIOC_QUERYBUF` or + :ref:`VIDIOC_DQBUF ` ioctl is called. Due to + hardware limitations, the last buffer may be empty. In this case + the driver will set the ``bytesused`` field to 0, regardless of + the format. Any subsequent call to the + :ref:`VIDIOC_DQBUF ` ioctl will not block anymore, + but return an ``EPIPE`` error code. + * .. _`V4L2-BUF-FLAG-REQUEST-FD`: + + - ``V4L2_BUF_FLAG_REQUEST_FD`` + - 0x00800000 + - The ``request_fd`` field contains a valid file descriptor. + * .. _`V4L2-BUF-FLAG-TIMESTAMP-MASK`: + + - ``V4L2_BUF_FLAG_TIMESTAMP_MASK`` + - 0x0000e000 + - Mask for timestamp types below. To test the timestamp type, mask + out bits not belonging to timestamp type by performing a logical + and operation with buffer flags and timestamp mask. + * .. _`V4L2-BUF-FLAG-TIMESTAMP-UNKNOWN`: + + - ``V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN`` + - 0x00000000 + - Unknown timestamp type. This type is used by drivers before Linux + 3.9 and may be either monotonic (see below) or realtime (wall + clock). Monotonic clock has been favoured in embedded systems + whereas most of the drivers use the realtime clock. Either kinds + of timestamps are available in user space via + :c:func:`clock_gettime` using clock IDs ``CLOCK_MONOTONIC`` + and ``CLOCK_REALTIME``, respectively. + * .. _`V4L2-BUF-FLAG-TIMESTAMP-MONOTONIC`: + + - ``V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC`` + - 0x00002000 + - The buffer timestamp has been taken from the ``CLOCK_MONOTONIC`` + clock. To access the same clock outside V4L2, use + :c:func:`clock_gettime`. + * .. _`V4L2-BUF-FLAG-TIMESTAMP-COPY`: + + - ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` + - 0x00004000 + - The CAPTURE buffer timestamp has been taken from the corresponding + OUTPUT buffer. This flag applies only to mem2mem devices. + * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-MASK`: + + - ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` + - 0x00070000 + - Mask for timestamp sources below. The timestamp source defines the + point of time the timestamp is taken in relation to the frame. + Logical 'and' operation between the ``flags`` field and + ``V4L2_BUF_FLAG_TSTAMP_SRC_MASK`` produces the value of the + timestamp source. Applications must set the timestamp source when + ``type`` refers to an output stream and + ``V4L2_BUF_FLAG_TIMESTAMP_COPY`` is set. + * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-EOF`: + + - ``V4L2_BUF_FLAG_TSTAMP_SRC_EOF`` + - 0x00000000 + - End Of Frame. The buffer timestamp has been taken when the last + pixel of the frame has been received or the last pixel of the + frame has been transmitted. In practice, software generated + timestamps will typically be read from the clock a small amount of + time after the last pixel has been received or transmitten, + depending on the system and other activity in it. + * .. _`V4L2-BUF-FLAG-TSTAMP-SRC-SOE`: + + - ``V4L2_BUF_FLAG_TSTAMP_SRC_SOE`` + - 0x00010000 + - Start Of Exposure. The buffer timestamp has been taken when the + exposure of the frame has begun. This is only valid for the + ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` buffer type. + +.. raw:: latex + + \normalsize + +enum v4l2_memory +================ + +.. tabularcolumns:: |p{5.0cm}|p{0.8cm}|p{11.5cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_MEMORY_MMAP`` + - 1 + - The buffer is used for :ref:`memory mapping ` I/O. + * - ``V4L2_MEMORY_USERPTR`` + - 2 + - The buffer is used for :ref:`user pointer ` I/O. + * - ``V4L2_MEMORY_OVERLAY`` + - 3 + - [to do] + * - ``V4L2_MEMORY_DMABUF`` + - 4 + - The buffer is used for :ref:`DMA shared buffer ` I/O. + +.. _memory-flags: + +Memory Consistency Flags +------------------------ + +.. raw:: latex + + \small + +.. tabularcolumns:: |p{7.0cm}|p{2.1cm}|p{8.4cm}| + +.. cssclass:: longtable + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * .. _`V4L2-MEMORY-FLAG-NON-COHERENT`: + + - ``V4L2_MEMORY_FLAG_NON_COHERENT`` + - 0x00000001 + - A buffer is allocated either in coherent (it will be automatically + coherent between the CPU and the bus) or non-coherent memory. The + latter can provide performance gains, for instance the CPU cache + sync/flush operations can be avoided if the buffer is accessed by the + corresponding device only and the CPU does not read/write to/from that + buffer. However, this requires extra care from the driver -- it must + guarantee memory consistency by issuing a cache flush/sync when + consistency is needed. If this flag is set V4L2 will attempt to + allocate the buffer in non-coherent memory. The flag takes effect + only if the buffer is used for :ref:`memory mapping ` I/O and the + queue reports the :ref:`V4L2_BUF_CAP_SUPPORTS_MMAP_CACHE_HINTS + ` capability. + +.. raw:: latex + + \normalsize + +Timecodes +========= + +The :c:type:`v4l2_buffer_timecode` structure is designed to hold a +:ref:`smpte12m` or similar timecode. +(struct :c:type:`timeval` timestamps are stored in the struct +:c:type:`v4l2_buffer` ``timestamp`` field.) + +.. c:type:: v4l2_timecode + +struct v4l2_timecode +-------------------- + +.. tabularcolumns:: |p{1.4cm}|p{2.8cm}|p{13.1cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 1 1 2 + + * - __u32 + - ``type`` + - Frame rate the timecodes are based on, see :ref:`timecode-type`. + * - __u32 + - ``flags`` + - Timecode flags, see :ref:`timecode-flags`. + * - __u8 + - ``frames`` + - Frame count, 0 ... 23/24/29/49/59, depending on the type of + timecode. + * - __u8 + - ``seconds`` + - Seconds count, 0 ... 59. This is a binary, not BCD number. + * - __u8 + - ``minutes`` + - Minutes count, 0 ... 59. This is a binary, not BCD number. + * - __u8 + - ``hours`` + - Hours count, 0 ... 29. This is a binary, not BCD number. + * - __u8 + - ``userbits``\ [4] + - The "user group" bits from the timecode. + + +.. _timecode-type: + +Timecode Types +-------------- + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_TC_TYPE_24FPS`` + - 1 + - 24 frames per second, i. e. film. + * - ``V4L2_TC_TYPE_25FPS`` + - 2 + - 25 frames per second, i. e. PAL or SECAM video. + * - ``V4L2_TC_TYPE_30FPS`` + - 3 + - 30 frames per second, i. e. NTSC video. + * - ``V4L2_TC_TYPE_50FPS`` + - 4 + - + * - ``V4L2_TC_TYPE_60FPS`` + - 5 + - + + +.. _timecode-flags: + +Timecode Flags +-------------- + +.. tabularcolumns:: |p{6.6cm}|p{1.4cm}|p{9.3cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 3 1 4 + + * - ``V4L2_TC_FLAG_DROPFRAME`` + - 0x0001 + - Indicates "drop frame" semantics for counting frames in 29.97 fps + material. When set, frame numbers 0 and 1 at the start of each + minute, except minutes 0, 10, 20, 30, 40, 50 are omitted from the + count. + * - ``V4L2_TC_FLAG_COLORFRAME`` + - 0x0002 + - The "color frame" flag. + * - ``V4L2_TC_USERBITS_field`` + - 0x000C + - Field mask for the "binary group flags". + * - ``V4L2_TC_USERBITS_USERDEFINED`` + - 0x0000 + - Unspecified format. + * - ``V4L2_TC_USERBITS_8BITCHARS`` + - 0x0008 + - 8-bit ISO characters. diff --git a/Documentation/userspace-api/media/v4l/capture-example.rst b/Documentation/userspace-api/media/v4l/capture-example.rst new file mode 100644 index 000000000..25891320b --- /dev/null +++ b/Documentation/userspace-api/media/v4l/capture-example.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _capture-example: + +********************* +Video Capture Example +********************* + + +.. toctree:: + :maxdepth: 1 + + capture.c diff --git a/Documentation/userspace-api/media/v4l/capture.c.rst b/Documentation/userspace-api/media/v4l/capture.c.rst new file mode 100644 index 000000000..eef677296 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/capture.c.rst @@ -0,0 +1,664 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +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 message\n" + "-m | --mmap Use memory mapped buffers [default]\n" + "-r | --read Use read() calls\n" + "-u | --userp Use application allocated buffers\n" + "-o | --output Outputs stream to stdout\n" + "-f | --format Force format to 640x480 YUYV\n" + "-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/userspace-api/media/v4l/colorspaces-defs.rst b/Documentation/userspace-api/media/v4l/colorspaces-defs.rst new file mode 100644 index 000000000..fe9f8aa8a --- /dev/null +++ b/Documentation/userspace-api/media/v4l/colorspaces-defs.rst @@ -0,0 +1,175 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +**************************** +Defining Colorspaces in V4L2 +**************************** + +In V4L2 colorspaces are defined by four values. The first is the +colorspace identifier (enum :c:type:`v4l2_colorspace`) +which defines the chromaticities, the default transfer function, the +default Y'CbCr encoding and the default quantization method. The second +is the transfer function identifier (enum +:c:type:`v4l2_xfer_func`) to specify non-standard +transfer functions. The third is the Y'CbCr encoding identifier (enum +:c:type:`v4l2_ycbcr_encoding`) to specify +non-standard Y'CbCr encodings and the fourth is the quantization +identifier (enum :c:type:`v4l2_quantization`) to +specify non-standard quantization methods. Most of the time only the +colorspace field of struct :c:type:`v4l2_pix_format` +or struct :c:type:`v4l2_pix_format_mplane` +needs to be filled in. + +.. _hsv-colorspace: + +On :ref:`HSV formats ` the *Hue* is defined as the angle on +the cylindrical color representation. Usually this angle is measured in +degrees, i.e. 0-360. When we map this angle value into 8 bits, there are +two basic ways to do it: Divide the angular value by 2 (0-179), or use the +whole range, 0-255, dividing the angular value by 1.41. The enum +:c:type:`v4l2_hsv_encoding` specifies which encoding is used. + +.. note:: The default R'G'B' quantization is full range for all + colorspaces. HSV formats are always full range. + +.. tabularcolumns:: |p{6.7cm}|p{10.8cm}| + +.. c:type:: v4l2_colorspace + +.. flat-table:: V4L2 Colorspaces + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Details + * - ``V4L2_COLORSPACE_DEFAULT`` + - The default colorspace. This can be used by applications to let + the driver fill in the colorspace. + * - ``V4L2_COLORSPACE_SMPTE170M`` + - See :ref:`col-smpte-170m`. + * - ``V4L2_COLORSPACE_REC709`` + - See :ref:`col-rec709`. + * - ``V4L2_COLORSPACE_SRGB`` + - See :ref:`col-srgb`. + * - ``V4L2_COLORSPACE_OPRGB`` + - See :ref:`col-oprgb`. + * - ``V4L2_COLORSPACE_BT2020`` + - See :ref:`col-bt2020`. + * - ``V4L2_COLORSPACE_DCI_P3`` + - See :ref:`col-dcip3`. + * - ``V4L2_COLORSPACE_SMPTE240M`` + - See :ref:`col-smpte-240m`. + * - ``V4L2_COLORSPACE_470_SYSTEM_M`` + - See :ref:`col-sysm`. + * - ``V4L2_COLORSPACE_470_SYSTEM_BG`` + - See :ref:`col-sysbg`. + * - ``V4L2_COLORSPACE_JPEG`` + - See :ref:`col-jpeg`. + * - ``V4L2_COLORSPACE_RAW`` + - The raw colorspace. This is used for raw image capture where the + image is minimally processed and is using the internal colorspace + of the device. The software that processes an image using this + 'colorspace' will have to know the internals of the capture + device. + + + +.. c:type:: v4l2_xfer_func + +.. tabularcolumns:: |p{5.5cm}|p{12.0cm}| + +.. flat-table:: V4L2 Transfer Function + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Details + * - ``V4L2_XFER_FUNC_DEFAULT`` + - Use the default transfer function as defined by the colorspace. + * - ``V4L2_XFER_FUNC_709`` + - Use the Rec. 709 transfer function. + * - ``V4L2_XFER_FUNC_SRGB`` + - Use the sRGB transfer function. + * - ``V4L2_XFER_FUNC_OPRGB`` + - Use the opRGB transfer function. + * - ``V4L2_XFER_FUNC_SMPTE240M`` + - Use the SMPTE 240M transfer function. + * - ``V4L2_XFER_FUNC_NONE`` + - Do not use a transfer function (i.e. use linear RGB values). + * - ``V4L2_XFER_FUNC_DCI_P3`` + - Use the DCI-P3 transfer function. + * - ``V4L2_XFER_FUNC_SMPTE2084`` + - Use the SMPTE 2084 transfer function. See :ref:`xf-smpte-2084`. + + + +.. c:type:: v4l2_ycbcr_encoding + +.. tabularcolumns:: |p{7.2cm}|p{10.3cm}| + +.. flat-table:: V4L2 Y'CbCr Encodings + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Details + * - ``V4L2_YCBCR_ENC_DEFAULT`` + - Use the default Y'CbCr encoding as defined by the colorspace. + * - ``V4L2_YCBCR_ENC_601`` + - Use the BT.601 Y'CbCr encoding. + * - ``V4L2_YCBCR_ENC_709`` + - Use the Rec. 709 Y'CbCr encoding. + * - ``V4L2_YCBCR_ENC_XV601`` + - Use the extended gamut xvYCC BT.601 encoding. + * - ``V4L2_YCBCR_ENC_XV709`` + - Use the extended gamut xvYCC Rec. 709 encoding. + * - ``V4L2_YCBCR_ENC_BT2020`` + - Use the default non-constant luminance BT.2020 Y'CbCr encoding. + * - ``V4L2_YCBCR_ENC_BT2020_CONST_LUM`` + - Use the constant luminance BT.2020 Yc'CbcCrc encoding. + * - ``V4L2_YCBCR_ENC_SMPTE_240M`` + - Use the SMPTE 240M Y'CbCr encoding. + + + +.. c:type:: v4l2_hsv_encoding + +.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| + +.. flat-table:: V4L2 HSV Encodings + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Details + * - ``V4L2_HSV_ENC_180`` + - For the Hue, each LSB is two degrees. + * - ``V4L2_HSV_ENC_256`` + - For the Hue, the 360 degrees are mapped into 8 bits, i.e. each + LSB is roughly 1.41 degrees. + + + +.. c:type:: v4l2_quantization + +.. tabularcolumns:: |p{6.5cm}|p{11.0cm}| + +.. flat-table:: V4L2 Quantization Methods + :header-rows: 1 + :stub-columns: 0 + + * - Identifier + - Details + * - ``V4L2_QUANTIZATION_DEFAULT`` + - Use the default quantization encoding as defined by the + colorspace. This is always full range for R'G'B' and HSV. + It is usually limited range for Y'CbCr. + * - ``V4L2_QUANTIZATION_FULL_RANGE`` + - Use the full range quantization encoding. I.e. the range [0…1] is + mapped to [0…255] (with possible clipping to [1…254] to avoid the + 0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to + [0…255] (with possible clipping to [1…254] to avoid the 0x00 and + 0xff values). + * - ``V4L2_QUANTIZATION_LIM_RANGE`` + - Use the limited range quantization encoding. I.e. the range [0…1] + is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to + [16…240]. Limited Range cannot be used with HSV. diff --git a/Documentation/userspace-api/media/v4l/colorspaces-details.rst b/Documentation/userspace-api/media/v4l/colorspaces-details.rst new file mode 100644 index 000000000..26a4ace42 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/colorspaces-details.rst @@ -0,0 +1,775 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +******************************** +Detailed Colorspace Descriptions +******************************** + + +.. _col-smpte-170m: + +Colorspace SMPTE 170M (V4L2_COLORSPACE_SMPTE170M) +================================================= + +The :ref:`smpte170m` standard defines the colorspace used by NTSC and +PAL and by SDTV in general. The default transfer function is +``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is +``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited +range. The chromaticities of the primary colors and the white reference +are: + +.. flat-table:: SMPTE 170M Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + * - Color + - x + - y + * - Red + - 0.630 + - 0.340 + * - Green + - 0.310 + - 0.595 + * - Blue + - 0.155 + - 0.070 + * - White Reference (D65) + - 0.3127 + - 0.3290 + + +The red, green and blue chromaticities are also often referred to as the +SMPTE C set, so this colorspace is sometimes called SMPTE C as well. + +The transfer function defined for SMPTE 170M is the same as the one +defined in Rec. 709. + +.. math:: + + L' = -1.099(-L)^{0.45} + 0.099 \text{, for } L \le-0.018 + + L' = 4.5L \text{, for } -0.018 < L < 0.018 + + L' = 1.099L^{0.45} - 0.099 \text{, for } L \ge 0.018 + +Inverse Transfer function: + +.. math:: + + L = -\left( \frac{L' - 0.099}{-1.099} \right) ^{\frac{1}{0.45}} \text{, for } L' \le -0.081 + + L = \frac{L'}{4.5} \text{, for } -0.081 < L' < 0.081 + + L = \left(\frac{L' + 0.099}{1.099}\right)^{\frac{1}{0.45} } \text{, for } L' \ge 0.081 + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_601`` encoding: + +.. math:: + + Y' = 0.2990R' + 0.5870G' + 0.1140B' + + Cb = -0.1687R' - 0.3313G' + 0.5B' + + Cr = 0.5R' - 0.4187G' - 0.0813B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. This conversion to Y'CbCr is identical to the one defined in +the :ref:`itu601` standard and this colorspace is sometimes called +BT.601 as well, even though BT.601 does not mention any color primaries. + +The default quantization is limited range, but full range is possible +although rarely seen. + + +.. _col-rec709: + +Colorspace Rec. 709 (V4L2_COLORSPACE_REC709) +============================================ + +The :ref:`itu709` standard defines the colorspace used by HDTV in +general. The default transfer function is ``V4L2_XFER_FUNC_709``. The +default Y'CbCr encoding is ``V4L2_YCBCR_ENC_709``. The default Y'CbCr +quantization is limited range. The chromaticities of the primary colors +and the white reference are: + +.. flat-table:: Rec. 709 Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + * - Color + - x + - y + * - Red + - 0.640 + - 0.330 + * - Green + - 0.300 + - 0.600 + * - Blue + - 0.150 + - 0.060 + * - White Reference (D65) + - 0.3127 + - 0.3290 + + +The full name of this standard is Rec. ITU-R BT.709-5. + +Transfer function. Normally L is in the range [0…1], but for the +extended gamut xvYCC encoding values outside that range are allowed. + +.. math:: + + L' = -1.099(-L)^{0.45} + 0.099 \text{, for } L \le -0.018 + + L' = 4.5L \text{, for } -0.018 < L < 0.018 + + L' = 1.099L^{0.45} - 0.099 \text{, for } L \ge 0.018 + +Inverse Transfer function: + +.. math:: + + L = -\left( \frac{L' - 0.099}{-1.099} \right)^\frac{1}{0.45} \text{, for } L' \le -0.081 + + L = \frac{L'}{4.5}\text{, for } -0.081 < L' < 0.081 + + L = \left(\frac{L' + 0.099}{1.099}\right)^{\frac{1}{0.45} } \text{, for } L' \ge 0.081 + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_709`` encoding: + +.. math:: + + Y' = 0.2126R' + 0.7152G' + 0.0722B' + + Cb = -0.1146R' - 0.3854G' + 0.5B' + + Cr = 0.5R' - 0.4542G' - 0.0458B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. + +The default quantization is limited range, but full range is possible +although rarely seen. + +The ``V4L2_YCBCR_ENC_709`` encoding described above is the default for +this colorspace, but it can be overridden with ``V4L2_YCBCR_ENC_601``, +in which case the BT.601 Y'CbCr encoding is used. + +Two additional extended gamut Y'CbCr encodings are also possible with +this colorspace: + +The xvYCC 709 encoding (``V4L2_YCBCR_ENC_XV709``, :ref:`xvycc`) is +similar to the Rec. 709 encoding, but it allows for R', G' and B' values +that are outside the range [0…1]. The resulting Y', Cb and Cr values are +scaled and offset according to the limited range formula: + +.. math:: + + Y' = \frac{219}{256} * (0.2126R' + 0.7152G' + 0.0722B') + \frac{16}{256} + + Cb = \frac{224}{256} * (-0.1146R' - 0.3854G' + 0.5B') + + Cr = \frac{224}{256} * (0.5R' - 0.4542G' - 0.0458B') + +The xvYCC 601 encoding (``V4L2_YCBCR_ENC_XV601``, :ref:`xvycc`) is +similar to the BT.601 encoding, but it allows for R', G' and B' values +that are outside the range [0…1]. The resulting Y', Cb and Cr values are +scaled and offset according to the limited range formula: + +.. math:: + + Y' = \frac{219}{256} * (0.2990R' + 0.5870G' + 0.1140B') + \frac{16}{256} + + Cb = \frac{224}{256} * (-0.1687R' - 0.3313G' + 0.5B') + + Cr = \frac{224}{256} * (0.5R' - 0.4187G' - 0.0813B') + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5] and quantized without further scaling or offsets. +The non-standard xvYCC 709 or xvYCC 601 encodings can be +used by selecting ``V4L2_YCBCR_ENC_XV709`` or ``V4L2_YCBCR_ENC_XV601``. +As seen by the xvYCC formulas these encodings always use limited range quantization, +there is no full range variant. The whole point of these extended gamut encodings +is that values outside the limited range are still valid, although they +map to R', G' and B' values outside the [0…1] range and are therefore outside +the Rec. 709 colorspace gamut. + + +.. _col-srgb: + +Colorspace sRGB (V4L2_COLORSPACE_SRGB) +====================================== + +The :ref:`srgb` standard defines the colorspace used by most webcams +and computer graphics. The default transfer function is +``V4L2_XFER_FUNC_SRGB``. The default Y'CbCr encoding is +``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited range. + +Note that the :ref:`sycc` standard specifies full range quantization, +however all current capture hardware supported by the kernel convert +R'G'B' to limited range Y'CbCr. So choosing full range as the default +would break how applications interpret the quantization range. + +The chromaticities of the primary colors and the white reference are: + +.. flat-table:: sRGB Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + * - Color + - x + - y + * - Red + - 0.640 + - 0.330 + * - Green + - 0.300 + - 0.600 + * - Blue + - 0.150 + - 0.060 + * - White Reference (D65) + - 0.3127 + - 0.3290 + + +These chromaticities are identical to the Rec. 709 colorspace. + +Transfer function. Note that negative values for L are only used by the +Y'CbCr conversion. + +.. math:: + + L' = -1.055(-L)^{\frac{1}{2.4} } + 0.055\text{, for }L < -0.0031308 + + L' = 12.92L\text{, for }-0.0031308 \le L \le 0.0031308 + + L' = 1.055L ^{\frac{1}{2.4} } - 0.055\text{, for }0.0031308 < L \le 1 + +Inverse Transfer function: + +.. math:: + + L = -((-L' + 0.055) / 1.055) ^{2.4}\text{, for }L' < -0.04045 + + L = L' / 12.92\text{, for }-0.04045 \le L' \le 0.04045 + + L = ((L' + 0.055) / 1.055) ^{2.4}\text{, for }L' > 0.04045 + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_601`` encoding as defined by :ref:`sycc`: + +.. math:: + + Y' = 0.2990R' + 0.5870G' + 0.1140B' + + Cb = -0.1687R' - 0.3313G' + 0.5B' + + Cr = 0.5R' - 0.4187G' - 0.0813B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. This transform is identical to one defined in SMPTE +170M/BT.601. The Y'CbCr quantization is limited range. + + +.. _col-oprgb: + +Colorspace opRGB (V4L2_COLORSPACE_OPRGB) +=============================================== + +The :ref:`oprgb` standard defines the colorspace used by computer +graphics that use the opRGB colorspace. The default transfer function is +``V4L2_XFER_FUNC_OPRGB``. The default Y'CbCr encoding is +``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited +range. + +Note that the :ref:`oprgb` standard specifies full range quantization, +however all current capture hardware supported by the kernel convert +R'G'B' to limited range Y'CbCr. So choosing full range as the default +would break how applications interpret the quantization range. + +The chromaticities of the primary colors and the white reference are: + +.. flat-table:: opRGB Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + * - Color + - x + - y + * - Red + - 0.6400 + - 0.3300 + * - Green + - 0.2100 + - 0.7100 + * - Blue + - 0.1500 + - 0.0600 + * - White Reference (D65) + - 0.3127 + - 0.3290 + + + +Transfer function: + +.. math:: + + L' = L ^{\frac{1}{2.19921875}} + +Inverse Transfer function: + +.. math:: + + L = L'^{(2.19921875)} + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_601`` encoding: + +.. math:: + + Y' = 0.2990R' + 0.5870G' + 0.1140B' + + Cb = -0.1687R' - 0.3313G' + 0.5B' + + Cr = 0.5R' - 0.4187G' - 0.0813B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. This transform is identical to one defined in SMPTE +170M/BT.601. The Y'CbCr quantization is limited range. + + +.. _col-bt2020: + +Colorspace BT.2020 (V4L2_COLORSPACE_BT2020) +=========================================== + +The :ref:`itu2020` standard defines the colorspace used by Ultra-high +definition television (UHDTV). The default transfer function is +``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is +``V4L2_YCBCR_ENC_BT2020``. The default Y'CbCr quantization is limited range. +The chromaticities of the primary colors and the white reference are: + +.. flat-table:: BT.2020 Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + * - Color + - x + - y + * - Red + - 0.708 + - 0.292 + * - Green + - 0.170 + - 0.797 + * - Blue + - 0.131 + - 0.046 + * - White Reference (D65) + - 0.3127 + - 0.3290 + + + +Transfer function (same as Rec. 709): + +.. math:: + + L' = 4.5L\text{, for }0 \le L < 0.018 + + L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1 + +Inverse Transfer function: + +.. math:: + + L = L' / 4.5\text{, for } L' < 0.081 + + L = \left( \frac{L' + 0.099}{1.099}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081 + +Please note that while Rec. 709 is defined as the default transfer function +by the :ref:`itu2020` standard, in practice this colorspace is often used +with the :ref:`xf-smpte-2084`. In particular Ultra HD Blu-ray discs use +this combination. + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_BT2020`` encoding: + +.. math:: + + Y' = 0.2627R' + 0.6780G' + 0.0593B' + + Cb = -0.1396R' - 0.3604G' + 0.5B' + + Cr = 0.5R' - 0.4598G' - 0.0402B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. The Y'CbCr quantization is limited range. + +There is also an alternate constant luminance R'G'B' to Yc'CbcCrc +(``V4L2_YCBCR_ENC_BT2020_CONST_LUM``) encoding: + +Luma: + +.. math:: + :nowrap: + + \begin{align*} + Yc' = (0.2627R + 0.6780G + 0.0593B)'& \\ + B' - Yc' \le 0:& \\ + &Cbc = (B' - Yc') / 1.9404 \\ + B' - Yc' > 0: & \\ + &Cbc = (B' - Yc') / 1.5816 \\ + R' - Yc' \le 0:& \\ + &Crc = (R' - Y') / 1.7184 \\ + R' - Yc' > 0:& \\ + &Crc = (R' - Y') / 0.9936 + \end{align*} + +Yc' is clamped to the range [0…1] and Cbc and Crc are clamped to the +range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range. + + +.. _col-dcip3: + +Colorspace DCI-P3 (V4L2_COLORSPACE_DCI_P3) +========================================== + +The :ref:`smpte431` standard defines the colorspace used by cinema +projectors that use the DCI-P3 colorspace. The default transfer function +is ``V4L2_XFER_FUNC_DCI_P3``. The default Y'CbCr encoding is +``V4L2_YCBCR_ENC_709``. The default Y'CbCr quantization is limited range. + +.. note:: + + Note that this colorspace standard does not specify a + Y'CbCr encoding since it is not meant to be encoded to Y'CbCr. So this + default Y'CbCr encoding was picked because it is the HDTV encoding. + +The chromaticities of the primary colors and the white reference are: + + +.. flat-table:: DCI-P3 Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + * - Color + - x + - y + * - Red + - 0.6800 + - 0.3200 + * - Green + - 0.2650 + - 0.6900 + * - Blue + - 0.1500 + - 0.0600 + * - White Reference + - 0.3140 + - 0.3510 + + + +Transfer function: + +.. math:: + + L' = L^{\frac{1}{2.6}} + +Inverse Transfer function: + +.. math:: + + L = L'^{(2.6)} + +Y'CbCr encoding is not specified. V4L2 defaults to Rec. 709. + + +.. _col-smpte-240m: + +Colorspace SMPTE 240M (V4L2_COLORSPACE_SMPTE240M) +================================================= + +The :ref:`smpte240m` standard was an interim standard used during the +early days of HDTV (1988-1998). It has been superseded by Rec. 709. The +default transfer function is ``V4L2_XFER_FUNC_SMPTE240M``. The default +Y'CbCr encoding is ``V4L2_YCBCR_ENC_SMPTE240M``. The default Y'CbCr +quantization is limited range. The chromaticities of the primary colors +and the white reference are: + + +.. flat-table:: SMPTE 240M Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + * - Color + - x + - y + * - Red + - 0.630 + - 0.340 + * - Green + - 0.310 + - 0.595 + * - Blue + - 0.155 + - 0.070 + * - White Reference (D65) + - 0.3127 + - 0.3290 + + +These chromaticities are identical to the SMPTE 170M colorspace. + +Transfer function: + +.. math:: + + L' = 4L\text{, for } 0 \le L < 0.0228 + + L' = 1.1115L ^{0.45} - 0.1115\text{, for } 0.0228 \le L \le 1 + +Inverse Transfer function: + +.. math:: + + L = \frac{L'}{4}\text{, for } 0 \le L' < 0.0913 + + L = \left( \frac{L' + 0.1115}{1.1115}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.0913 + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_SMPTE240M`` encoding: + +.. math:: + + Y' = 0.2122R' + 0.7013G' + 0.0865B' + + Cb = -0.1161R' - 0.3839G' + 0.5B' + + Cr = 0.5R' - 0.4451G' - 0.0549B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the +range [-0.5…0.5]. The Y'CbCr quantization is limited range. + + +.. _col-sysm: + +Colorspace NTSC 1953 (V4L2_COLORSPACE_470_SYSTEM_M) +=================================================== + +This standard defines the colorspace used by NTSC in 1953. In practice +this colorspace is obsolete and SMPTE 170M should be used instead. The +default transfer function is ``V4L2_XFER_FUNC_709``. The default Y'CbCr +encoding is ``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is +limited range. The chromaticities of the primary colors and the white +reference are: + + +.. flat-table:: NTSC 1953 Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + * - Color + - x + - y + * - Red + - 0.67 + - 0.33 + * - Green + - 0.21 + - 0.71 + * - Blue + - 0.14 + - 0.08 + * - White Reference (C) + - 0.310 + - 0.316 + + +.. note:: + + This colorspace uses Illuminant C instead of D65 as the white + reference. To correctly convert an image in this colorspace to another + that uses D65 you need to apply a chromatic adaptation algorithm such as + the Bradford method. + +The transfer function was never properly defined for NTSC 1953. The Rec. +709 transfer function is recommended in the literature: + +.. math:: + + L' = 4.5L\text{, for } 0 \le L < 0.018 + + L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1 + +Inverse Transfer function: + +.. math:: + + L = \frac{L'}{4.5} \text{, for } L' < 0.081 + + L = \left( \frac{L' + 0.099}{1.099}\right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081 + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_601`` encoding: + +.. math:: + + Y' = 0.2990R' + 0.5870G' + 0.1140B' + + Cb = -0.1687R' - 0.3313G' + 0.5B' + + Cr = 0.5R' - 0.4187G' - 0.0813B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is +identical to one defined in SMPTE 170M/BT.601. + + +.. _col-sysbg: + +Colorspace EBU Tech. 3213 (V4L2_COLORSPACE_470_SYSTEM_BG) +========================================================= + +The :ref:`tech3213` standard defines the colorspace used by PAL/SECAM +in 1975. Note that this colorspace is not supported by the HDMI interface. +Instead :ref:`tech3321` recommends that Rec. 709 is used instead for HDMI. +The default transfer function is +``V4L2_XFER_FUNC_709``. The default Y'CbCr encoding is +``V4L2_YCBCR_ENC_601``. The default Y'CbCr quantization is limited +range. The chromaticities of the primary colors and the white reference +are: + + +.. flat-table:: EBU Tech. 3213 Chromaticities + :header-rows: 1 + :stub-columns: 0 + :widths: 1 1 2 + + * - Color + - x + - y + * - Red + - 0.64 + - 0.33 + * - Green + - 0.29 + - 0.60 + * - Blue + - 0.15 + - 0.06 + * - White Reference (D65) + - 0.3127 + - 0.3290 + + + +The transfer function was never properly defined for this colorspace. +The Rec. 709 transfer function is recommended in the literature: + +.. math:: + + L' = 4.5L\text{, for } 0 \le L < 0.018 + + L' = 1.099L ^{0.45} - 0.099\text{, for } 0.018 \le L \le 1 + +Inverse Transfer function: + +.. math:: + + L = \frac{L'}{4.5} \text{, for } L' < 0.081 + + L = \left(\frac{L' + 0.099}{1.099} \right) ^{\frac{1}{0.45} }\text{, for } L' \ge 0.081 + +The luminance (Y') and color difference (Cb and Cr) are obtained with +the following ``V4L2_YCBCR_ENC_601`` encoding: + +.. math:: + + Y' = 0.2990R' + 0.5870G' + 0.1140B' + + Cb = -0.1687R' - 0.3313G' + 0.5B' + + Cr = 0.5R' - 0.4187G' - 0.0813B' + +Y' is clamped to the range [0…1] and Cb and Cr are clamped to the range +[-0.5…0.5]. The Y'CbCr quantization is limited range. This transform is +identical to one defined in SMPTE 170M/BT.601. + + +.. _col-jpeg: + +Colorspace JPEG (V4L2_COLORSPACE_JPEG) +====================================== + +This colorspace defines the colorspace used by most (Motion-)JPEG +formats. The chromaticities of the primary colors and the white +reference are identical to sRGB. The transfer function use is +``V4L2_XFER_FUNC_SRGB``. The Y'CbCr encoding is ``V4L2_YCBCR_ENC_601`` +with full range quantization where Y' is scaled to [0…255] and Cb/Cr are +scaled to [-128…128] and then clipped to [-128…127]. + +.. note:: + + The JPEG standard does not actually store colorspace + information. So if something other than sRGB is used, then the driver + will have to set that information explicitly. Effectively + ``V4L2_COLORSPACE_JPEG`` can be considered to be an abbreviation for + ``V4L2_COLORSPACE_SRGB``, ``V4L2_XFER_FUNC_SRGB``, ``V4L2_YCBCR_ENC_601`` + and ``V4L2_QUANTIZATION_FULL_RANGE``. + +*************************************** +Detailed Transfer Function Descriptions +*************************************** + +.. _xf-smpte-2084: + +Transfer Function SMPTE 2084 (V4L2_XFER_FUNC_SMPTE2084) +======================================================= + +The :ref:`smpte2084` standard defines the transfer function used by +High Dynamic Range content. + +Constants: + m1 = (2610 / 4096) / 4 + + m2 = (2523 / 4096) * 128 + + c1 = 3424 / 4096 + + c2 = (2413 / 4096) * 32 + + c3 = (2392 / 4096) * 32 + +Transfer function: + L' = ((c1 + c2 * L\ :sup:`m1`) / (1 + c3 * L\ :sup:`m1`))\ :sup:`m2` + +Inverse Transfer function: + L = (max(L':sup:`1/m2` - c1, 0) / (c2 - c3 * + L'\ :sup:`1/m2`))\ :sup:`1/m1` + +Take care when converting between this transfer function and non-HDR transfer +functions: the linear RGB values [0…1] of HDR content map to a luminance range +of 0 to 10000 cd/m\ :sup:`2` whereas the linear RGB values of non-HDR (aka +Standard Dynamic Range or SDR) map to a luminance range of 0 to 100 cd/m\ :sup:`2`. + +To go from SDR to HDR you will have to divide L by 100 first. To go in the other +direction you will have to multiply L by 100. Of course, this clamps all +luminance values over 100 cd/m\ :sup:`2` to 100 cd/m\ :sup:`2`. + +There are better methods, see e.g. :ref:`colimg` for more in-depth information +about this. diff --git a/Documentation/userspace-api/media/v4l/colorspaces.rst b/Documentation/userspace-api/media/v4l/colorspaces.rst new file mode 100644 index 000000000..2aa0dda4f --- /dev/null +++ b/Documentation/userspace-api/media/v4l/colorspaces.rst @@ -0,0 +1,163 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _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/userspace-api/media/v4l/common-defs.rst b/Documentation/userspace-api/media/v4l/common-defs.rst new file mode 100644 index 000000000..6ae42ac7d --- /dev/null +++ b/Documentation/userspace-api/media/v4l/common-defs.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _common-defs: + +****************************************************** +Common definitions for V4L2 and V4L2 subdev interfaces +****************************************************** + + +.. toctree:: + :maxdepth: 1 + + selections-common diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst new file mode 100644 index 000000000..ea0435182 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/common.rst @@ -0,0 +1,60 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _common: + +################### +Common API Elements +################### +Programming a V4L2 device consists of these steps: + +- Opening the device + +- Changing device properties, selecting a video and audio input, video + standard, picture brightness a. o. + +- Negotiating a data format + +- Negotiating an input/output method + +- The actual input/output loop + +- Closing the device + +In practice most steps are optional and can be executed out of order. It +depends on the V4L2 device type, you can read about the details in +:ref:`devices`. In this chapter we will discuss the basic concepts +applicable to all devices. + + +.. toctree:: + :maxdepth: 1 + + open + querycap + app-pri + video + audio + tuner + standard + dv-timings + control + extended-controls + ext-ctrls-camera + ext-ctrls-flash + ext-ctrls-image-source + ext-ctrls-image-process + ext-ctrls-codec + ext-ctrls-codec-stateless + ext-ctrls-jpeg + ext-ctrls-dv + ext-ctrls-rf-tuner + ext-ctrls-fm-tx + ext-ctrls-fm-rx + ext-ctrls-detect + ext-ctrls-colorimetry + fourcc + format + planar-apis + selection-api + crop + streaming-par diff --git a/Documentation/userspace-api/media/v4l/compat.rst b/Documentation/userspace-api/media/v4l/compat.rst new file mode 100644 index 000000000..b63b8392d --- /dev/null +++ b/Documentation/userspace-api/media/v4l/compat.rst @@ -0,0 +1,18 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _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/userspace-api/media/v4l/constraints.svg b/Documentation/userspace-api/media/v4l/constraints.svg new file mode 100644 index 000000000..ac5f82bc6 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/constraints.svg @@ -0,0 +1,11 @@ + + +image/svg+xmlV4L2_SEL_FLAG_GE +ORIGINAL +V4L2_SEL_FLAG_LE + diff --git a/Documentation/userspace-api/media/v4l/control.rst b/Documentation/userspace-api/media/v4l/control.rst new file mode 100644 index 000000000..4463fce69 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/control.rst @@ -0,0 +1,517 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _control: + +************* +User Controls +************* + +Devices typically have a number of user-settable controls such as +brightness, saturation and so on, which would be presented to the user +on a graphical user interface. But, different devices will have +different controls available, and furthermore, the range of possible +values, and the default value will vary from device to device. The +control ioctls provide the information and a mechanism to create a nice +user interface for these controls that will work correctly with any +device. + +All controls are accessed using an ID value. V4L2 defines several IDs +for specific purposes. Drivers can also implement their own custom +controls using ``V4L2_CID_PRIVATE_BASE`` [#f1]_ and higher values. The +pre-defined control IDs have the prefix ``V4L2_CID_``, and are listed in +:ref:`control-id`. The ID is used when querying the attributes of a +control, and when getting or setting the current value. + +Generally applications should present controls to the user without +assumptions about their purpose. Each control comes with a name string +the user is supposed to understand. When the purpose is non-intuitive +the driver writer should provide a user manual, a user interface plug-in +or a driver specific panel application. Predefined IDs were introduced +to change a few controls programmatically, for example to mute a device +during a channel switch. + +Drivers may enumerate different controls after switching the current +video input or output, tuner or modulator, or audio input or output. +Different in the sense of other bounds, another default and current +value, step size or other menu items. A control with a certain *custom* +ID can also change name and type. + +If a control is not applicable to the current configuration of the +device (for example, it doesn't apply to the current video input) +drivers set the ``V4L2_CTRL_FLAG_INACTIVE`` flag. + +Control values are stored globally, they do not change when switching +except to stay within the reported bounds. They also do not change e. g. +when the device is opened or closed, when the tuner radio frequency is +changed or generally never without application request. + +V4L2 specifies an event mechanism to notify applications when controls +change value (see +:ref:`VIDIOC_SUBSCRIBE_EVENT`, event +``V4L2_EVENT_CTRL``), panel applications might want to make use of that +in order to always reflect the correct control value. + +All controls use machine endianness. + + +.. _control-id: + +Control IDs +=========== + +``V4L2_CID_BASE`` + First predefined ID, equal to ``V4L2_CID_BRIGHTNESS``. + +``V4L2_CID_USER_BASE`` + Synonym of ``V4L2_CID_BASE``. + +``V4L2_CID_BRIGHTNESS`` ``(integer)`` + Picture brightness, or more precisely, the black level. + +``V4L2_CID_CONTRAST`` ``(integer)`` + Picture contrast or luma gain. + +``V4L2_CID_SATURATION`` ``(integer)`` + Picture color saturation or chroma gain. + +``V4L2_CID_HUE`` ``(integer)`` + Hue or color balance. + +``V4L2_CID_AUDIO_VOLUME`` ``(integer)`` + Overall audio volume. Note some drivers also provide an OSS or ALSA + mixer interface. + +``V4L2_CID_AUDIO_BALANCE`` ``(integer)`` + Audio stereo balance. Minimum corresponds to all the way left, + maximum to right. + +``V4L2_CID_AUDIO_BASS`` ``(integer)`` + Audio bass adjustment. + +``V4L2_CID_AUDIO_TREBLE`` ``(integer)`` + Audio treble adjustment. + +``V4L2_CID_AUDIO_MUTE`` ``(boolean)`` + Mute audio, i. e. set the volume to zero, however without affecting + ``V4L2_CID_AUDIO_VOLUME``. Like ALSA drivers, V4L2 drivers must mute + at load time to avoid excessive noise. Actually the entire device + should be reset to a low power consumption state. + +``V4L2_CID_AUDIO_LOUDNESS`` ``(boolean)`` + Loudness mode (bass boost). + +``V4L2_CID_BLACK_LEVEL`` ``(integer)`` + Another name for brightness (not a synonym of + ``V4L2_CID_BRIGHTNESS``). This control is deprecated and should not + be used in new drivers and applications. + +``V4L2_CID_AUTO_WHITE_BALANCE`` ``(boolean)`` + Automatic white balance (cameras). + +``V4L2_CID_DO_WHITE_BALANCE`` ``(button)`` + This is an action control. When set (the value is ignored), the + device will do a white balance and then hold the current setting. + Contrast this with the boolean ``V4L2_CID_AUTO_WHITE_BALANCE``, + which, when activated, keeps adjusting the white balance. + +``V4L2_CID_RED_BALANCE`` ``(integer)`` + Red chroma balance. + +``V4L2_CID_BLUE_BALANCE`` ``(integer)`` + Blue chroma balance. + +``V4L2_CID_GAMMA`` ``(integer)`` + Gamma adjust. + +``V4L2_CID_WHITENESS`` ``(integer)`` + Whiteness for grey-scale devices. This is a synonym for + ``V4L2_CID_GAMMA``. This control is deprecated and should not be + used in new drivers and applications. + +``V4L2_CID_EXPOSURE`` ``(integer)`` + Exposure (cameras). [Unit?] + +``V4L2_CID_AUTOGAIN`` ``(boolean)`` + Automatic gain/exposure control. + +``V4L2_CID_GAIN`` ``(integer)`` + Gain control. + + Primarily used to control gain on e.g. TV tuners but also on + webcams. Most devices control only digital gain with this control + but on some this could include analogue gain as well. Devices that + recognise the difference between digital and analogue gain use + controls ``V4L2_CID_DIGITAL_GAIN`` and ``V4L2_CID_ANALOGUE_GAIN``. + +``V4L2_CID_HFLIP`` ``(boolean)`` + Mirror the picture horizontally. + +``V4L2_CID_VFLIP`` ``(boolean)`` + Mirror the picture vertically. + +.. _v4l2-power-line-frequency: + +``V4L2_CID_POWER_LINE_FREQUENCY`` ``(enum)`` + Enables a power line frequency filter to avoid flicker. Possible + values for ``enum v4l2_power_line_frequency`` are: + + ========================================== == + ``V4L2_CID_POWER_LINE_FREQUENCY_DISABLED`` 0 + ``V4L2_CID_POWER_LINE_FREQUENCY_50HZ`` 1 + ``V4L2_CID_POWER_LINE_FREQUENCY_60HZ`` 2 + ``V4L2_CID_POWER_LINE_FREQUENCY_AUTO`` 3 + ========================================== == + +``V4L2_CID_HUE_AUTO`` ``(boolean)`` + Enables automatic hue control by the device. The effect of setting + ``V4L2_CID_HUE`` while automatic hue control is enabled is + undefined, drivers should ignore such request. + +``V4L2_CID_WHITE_BALANCE_TEMPERATURE`` ``(integer)`` + This control specifies the white balance settings as a color + temperature in Kelvin. A driver should have a minimum of 2800 + (incandescent) to 6500 (daylight). For more information about color + temperature see + `Wikipedia `__. + +``V4L2_CID_SHARPNESS`` ``(integer)`` + Adjusts the sharpness filters in a camera. The minimum value + disables the filters, higher values give a sharper picture. + +``V4L2_CID_BACKLIGHT_COMPENSATION`` ``(integer)`` + Adjusts the backlight compensation in a camera. The minimum value + disables backlight compensation. + +``V4L2_CID_CHROMA_AGC`` ``(boolean)`` + Chroma automatic gain control. + +``V4L2_CID_CHROMA_GAIN`` ``(integer)`` + Adjusts the Chroma gain control (for use when chroma AGC is + disabled). + +``V4L2_CID_COLOR_KILLER`` ``(boolean)`` + Enable the color killer (i. e. force a black & white image in case + of a weak video signal). + +.. _v4l2-colorfx: + +``V4L2_CID_COLORFX`` ``(enum)`` + Selects a color effect. The following values are defined: + + + +.. tabularcolumns:: |p{5.7cm}|p{11.8cm}| + +.. flat-table:: + :header-rows: 0 + :stub-columns: 0 + :widths: 11 24 + + * - ``V4L2_COLORFX_NONE`` + - Color effect is disabled. + * - ``V4L2_COLORFX_ANTIQUE`` + - An aging (old photo) effect. + * - ``V4L2_COLORFX_ART_FREEZE`` + - Frost color effect. + * - ``V4L2_COLORFX_AQUA`` + - Water color, cool tone. + * - ``V4L2_COLORFX_BW`` + - Black and white. + * - ``V4L2_COLORFX_EMBOSS`` + - Emboss, the highlights and shadows replace light/dark boundaries + and low contrast areas are set to a gray background. + * - ``V4L2_COLORFX_GRASS_GREEN`` + - Grass green. + * - ``V4L2_COLORFX_NEGATIVE`` + - Negative. + * - ``V4L2_COLORFX_SEPIA`` + - Sepia tone. + * - ``V4L2_COLORFX_SKETCH`` + - Sketch. + * - ``V4L2_COLORFX_SKIN_WHITEN`` + - Skin whiten. + * - ``V4L2_COLORFX_SKY_BLUE`` + - Sky blue. + * - ``V4L2_COLORFX_SOLARIZATION`` + - Solarization, the image is partially reversed in tone, only color + values above or below a certain threshold are inverted. + * - ``V4L2_COLORFX_SILHOUETTE`` + - Silhouette (outline). + * - ``V4L2_COLORFX_VIVID`` + - Vivid colors. + * - ``V4L2_COLORFX_SET_CBCR`` + - The Cb and Cr chroma components are replaced by fixed coefficients + determined by ``V4L2_CID_COLORFX_CBCR`` control. + * - ``V4L2_COLORFX_SET_RGB`` + - The RGB components are replaced by the fixed RGB components determined + by ``V4L2_CID_COLORFX_RGB`` control. + + +``V4L2_CID_COLORFX_RGB`` ``(integer)`` + Determines the Red, Green, and Blue coefficients for + ``V4L2_COLORFX_SET_RGB`` color effect. + Bits [7:0] of the supplied 32 bit value are interpreted as Blue component, + bits [15:8] as Green component, bits [23:16] as Red component, and + bits [31:24] must be zero. + +``V4L2_CID_COLORFX_CBCR`` ``(integer)`` + Determines the Cb and Cr coefficients for ``V4L2_COLORFX_SET_CBCR`` + color effect. Bits [7:0] of the supplied 32 bit value are + interpreted as Cr component, bits [15:8] as Cb component and bits + [31:16] must be zero. + +``V4L2_CID_AUTOBRIGHTNESS`` ``(boolean)`` + Enable Automatic Brightness. + +``V4L2_CID_ROTATE`` ``(integer)`` + Rotates the image by specified angle. Common angles are 90, 270 and + 180. Rotating the image to 90 and 270 will reverse the height and + width of the display window. It is necessary to set the new height + and width of the picture using the + :ref:`VIDIOC_S_FMT ` ioctl according to the + rotation angle selected. + +``V4L2_CID_BG_COLOR`` ``(integer)`` + Sets the background color on the current output device. Background + color needs to be specified in the RGB24 format. The supplied 32 bit + value is interpreted as bits 0-7 Red color information, bits 8-15 + Green color information, bits 16-23 Blue color information and bits + 24-31 must be zero. + +``V4L2_CID_ILLUMINATORS_1 V4L2_CID_ILLUMINATORS_2`` ``(boolean)`` + Switch on or off the illuminator 1 or 2 of the device (usually a + microscope). + +``V4L2_CID_MIN_BUFFERS_FOR_CAPTURE`` ``(integer)`` + This is a read-only control that can be read by the application and + used as a hint to determine the number of CAPTURE buffers to pass to + REQBUFS. The value is the minimum number of CAPTURE buffers that is + necessary for hardware to work. + +``V4L2_CID_MIN_BUFFERS_FOR_OUTPUT`` ``(integer)`` + This is a read-only control that can be read by the application and + used as a hint to determine the number of OUTPUT buffers to pass to + REQBUFS. The value is the minimum number of OUTPUT buffers that is + necessary for hardware to work. + +.. _v4l2-alpha-component: + +``V4L2_CID_ALPHA_COMPONENT`` ``(integer)`` + Sets the alpha color component. When a capture device (or capture + queue of a mem-to-mem device) produces a frame format that includes + an alpha component (e.g. + :ref:`packed RGB image formats `) and the alpha value + is not defined by the device or the mem-to-mem input data this + control lets you select the alpha component value of all pixels. + When an output device (or output queue of a mem-to-mem device) + consumes a frame format that doesn't include an alpha component and + the device supports alpha channel processing this control lets you + set the alpha component value of all pixels for further processing + in the device. + +``V4L2_CID_LASTP1`` + End of the predefined control IDs (currently + ``V4L2_CID_ALPHA_COMPONENT`` + 1). + +``V4L2_CID_PRIVATE_BASE`` + ID of the first custom (driver specific) control. Applications + depending on particular custom controls should check the driver name + and version, see :ref:`querycap`. + +Applications can enumerate the available controls with the +:ref:`VIDIOC_QUERYCTRL` and +:ref:`VIDIOC_QUERYMENU ` ioctls, get and set a +control value with the :ref:`VIDIOC_G_CTRL ` and +:ref:`VIDIOC_S_CTRL ` ioctls. Drivers must implement +``VIDIOC_QUERYCTRL``, ``VIDIOC_G_CTRL`` and ``VIDIOC_S_CTRL`` when the +device has one or more controls, ``VIDIOC_QUERYMENU`` when it has one or +more menu type controls. + + +.. _enum_all_controls: + +Example: Enumerating all controls +================================= + +.. code-block:: c + + struct v4l2_queryctrl queryctrl; + struct v4l2_querymenu querymenu; + + static void enumerate_menu(__u32 id) + { + printf(" Menu items:\\n"); + + memset(&querymenu, 0, sizeof(querymenu)); + querymenu.id = id; + + for (querymenu.index = queryctrl.minimum; + querymenu.index <= queryctrl.maximum; + querymenu.index++) { + if (0 == ioctl(fd, VIDIOC_QUERYMENU, &querymenu)) { + printf(" %s\\n", querymenu.name); + } + } + } + + memset(&queryctrl, 0, sizeof(queryctrl)); + + queryctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL; + while (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { + if (!(queryctrl.flags & V4L2_CTRL_FLAG_DISABLED)) { + printf("Control %s\\n", queryctrl.name); + + if (queryctrl.type == V4L2_CTRL_TYPE_MENU) + enumerate_menu(queryctrl.id); + } + + queryctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL; + } + if (errno != EINVAL) { + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); + } + +Example: Enumerating all controls including compound controls +============================================================= + +.. code-block:: c + + struct v4l2_query_ext_ctrl query_ext_ctrl; + + memset(&query_ext_ctrl, 0, sizeof(query_ext_ctrl)); + + query_ext_ctrl.id = V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND; + while (0 == ioctl(fd, VIDIOC_QUERY_EXT_CTRL, &query_ext_ctrl)) { + if (!(query_ext_ctrl.flags & V4L2_CTRL_FLAG_DISABLED)) { + printf("Control %s\\n", query_ext_ctrl.name); + + if (query_ext_ctrl.type == V4L2_CTRL_TYPE_MENU) + enumerate_menu(query_ext_ctrl.id); + } + + query_ext_ctrl.id |= V4L2_CTRL_FLAG_NEXT_CTRL | V4L2_CTRL_FLAG_NEXT_COMPOUND; + } + if (errno != EINVAL) { + perror("VIDIOC_QUERY_EXT_CTRL"); + exit(EXIT_FAILURE); + } + +Example: Enumerating all user controls (old style) +================================================== + +.. code-block:: c + + + memset(&queryctrl, 0, sizeof(queryctrl)); + + for (queryctrl.id = V4L2_CID_BASE; + queryctrl.id < V4L2_CID_LASTP1; + queryctrl.id++) { + if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { + if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) + continue; + + printf("Control %s\\n", queryctrl.name); + + if (queryctrl.type == V4L2_CTRL_TYPE_MENU) + enumerate_menu(queryctrl.id); + } else { + if (errno == EINVAL) + continue; + + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); + } + } + + for (queryctrl.id = V4L2_CID_PRIVATE_BASE;; + queryctrl.id++) { + if (0 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { + if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) + continue; + + printf("Control %s\\n", queryctrl.name); + + if (queryctrl.type == V4L2_CTRL_TYPE_MENU) + enumerate_menu(queryctrl.id); + } else { + if (errno == EINVAL) + break; + + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); + } + } + + +Example: Changing controls +========================== + +.. code-block:: c + + struct v4l2_queryctrl queryctrl; + struct v4l2_control control; + + memset(&queryctrl, 0, sizeof(queryctrl)); + queryctrl.id = V4L2_CID_BRIGHTNESS; + + if (-1 == ioctl(fd, VIDIOC_QUERYCTRL, &queryctrl)) { + if (errno != EINVAL) { + perror("VIDIOC_QUERYCTRL"); + exit(EXIT_FAILURE); + } else { + printf("V4L2_CID_BRIGHTNESS is not supported\n"); + } + } else if (queryctrl.flags & V4L2_CTRL_FLAG_DISABLED) { + printf("V4L2_CID_BRIGHTNESS is not supported\n"); + } else { + memset(&control, 0, sizeof (control)); + control.id = V4L2_CID_BRIGHTNESS; + control.value = queryctrl.default_value; + + if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control)) { + perror("VIDIOC_S_CTRL"); + exit(EXIT_FAILURE); + } + } + + memset(&control, 0, sizeof(control)); + control.id = V4L2_CID_CONTRAST; + + if (0 == ioctl(fd, VIDIOC_G_CTRL, &control)) { + control.value += 1; + + /* The driver may clamp the value or return ERANGE, ignored here */ + + if (-1 == ioctl(fd, VIDIOC_S_CTRL, &control) + && errno != ERANGE) { + perror("VIDIOC_S_CTRL"); + exit(EXIT_FAILURE); + } + /* Ignore if V4L2_CID_CONTRAST is unsupported */ + } else if (errno != EINVAL) { + perror("VIDIOC_G_CTRL"); + exit(EXIT_FAILURE); + } + + control.id = V4L2_CID_AUDIO_MUTE; + control.value = 1; /* silence */ + + /* Errors ignored */ + ioctl(fd, VIDIOC_S_CTRL, &control); + +.. [#f1] + The use of ``V4L2_CID_PRIVATE_BASE`` is problematic because different + drivers may use the same ``V4L2_CID_PRIVATE_BASE`` ID for different + controls. This makes it hard to programmatically set such controls + since the meaning of the control with that ID is driver dependent. In + order to resolve this drivers use unique IDs and the + ``V4L2_CID_PRIVATE_BASE`` IDs are mapped to those unique IDs by the + kernel. Consider these ``V4L2_CID_PRIVATE_BASE`` IDs as aliases to + the real IDs. + + Many applications today still use the ``V4L2_CID_PRIVATE_BASE`` IDs + instead of using :ref:`VIDIOC_QUERYCTRL` with + the ``V4L2_CTRL_FLAG_NEXT_CTRL`` flag to enumerate all IDs, so + support for ``V4L2_CID_PRIVATE_BASE`` is still around. diff --git a/Documentation/userspace-api/media/v4l/crop.rst b/Documentation/userspace-api/media/v4l/crop.rst new file mode 100644 index 000000000..3fe185e25 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/crop.rst @@ -0,0 +1,317 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _crop: + +***************************************************** +Image Cropping, Insertion and Scaling -- the CROP API +***************************************************** + +.. note:: + + The CROP API is mostly superseded by the newer :ref:`SELECTION API + `. The new API should be preferred in most cases, + with the exception of pixel aspect ratio detection, which is + implemented by :ref:`VIDIOC_CROPCAP ` and has no + equivalent in the SELECTION API. See :ref:`selection-vs-crop` for a + comparison of the two APIs. + +Some video capture devices can sample a subsection of the picture and +shrink or enlarge it to an image of arbitrary size. We call these +abilities cropping and scaling. Some video output devices can scale an +image up or down and insert it at an arbitrary scan line and horizontal +offset into a video signal. + +Applications can use the following API to select an area in the video +signal, query the default area and the hardware limits. + +.. note:: + + Despite their name, the :ref:`VIDIOC_CROPCAP `, + :ref:`VIDIOC_G_CROP ` and :ref:`VIDIOC_S_CROP + ` ioctls apply to input as well as output devices. + +Scaling requires a source and a target. On a video capture or overlay +device the source is the video signal, and the cropping ioctls determine +the area actually sampled. The target are images read by the application +or overlaid onto the graphics screen. Their size (and position for an +overlay) is negotiated with the :ref:`VIDIOC_G_FMT ` +and :ref:`VIDIOC_S_FMT ` ioctls. + +On a video output device the source are the images passed in by the +application, and their size is again negotiated with the +:ref:`VIDIOC_G_FMT ` and :ref:`VIDIOC_S_FMT ` +ioctls, or may be encoded in a compressed video stream. The target is +the video signal, and the cropping ioctls determine the area where the +images are inserted. + +Source and target rectangles are defined even if the device does not +support scaling or the :ref:`VIDIOC_G_CROP ` and +:ref:`VIDIOC_S_CROP ` ioctls. Their size (and position +where applicable) will be fixed in this case. + +.. note:: + + All capture and output devices that support the CROP or SELECTION + API will also support the :ref:`VIDIOC_CROPCAP ` + ioctl. + +Cropping Structures +=================== + + +.. _crop-scale: + +.. kernel-figure:: crop.svg + :alt: crop.svg + :align: center + + Image Cropping, Insertion and Scaling + + The cropping, insertion and scaling process + + + +For capture devices the coordinates of the top left corner, width and +height of the area which can be sampled is given by the ``bounds`` +substructure of the struct :c:type:`v4l2_cropcap` returned +by the :ref:`VIDIOC_CROPCAP ` ioctl. To support a wide +range of hardware this specification does not define an origin or units. +However by convention drivers should horizontally count unscaled samples +relative to 0H (the leading edge of the horizontal sync pulse, see +:ref:`vbi-hsync`). Vertically ITU-R line numbers of the first field +(see ITU R-525 line numbering for :ref:`525 lines ` and for +:ref:`625 lines `), multiplied by two if the driver +can capture both fields. + +The top left corner, width and height of the source rectangle, that is +the area actually sampled, is given by struct +:c:type:`v4l2_crop` using the same coordinate system as +struct :c:type:`v4l2_cropcap`. Applications can use the +:ref:`VIDIOC_G_CROP ` and :ref:`VIDIOC_S_CROP ` +ioctls to get and set this rectangle. It must lie completely within the +capture boundaries and the driver may further adjust the requested size +and/or position according to hardware limitations. + +Each capture device has a default source rectangle, given by the +``defrect`` substructure of struct +:c:type:`v4l2_cropcap`. The center of this rectangle +shall align with the center of the active picture area of the video +signal, and cover what the driver writer considers the complete picture. +Drivers shall reset the source rectangle to the default when the driver +is first loaded, but not later. + +For output devices these structures and ioctls are used accordingly, +defining the *target* rectangle where the images will be inserted into +the video signal. + + +Scaling Adjustments +=================== + +Video hardware can have various cropping, insertion and scaling +limitations. It may only scale up or down, support only discrete scaling +factors, or have different scaling abilities in horizontal and vertical +direction. Also it may not support scaling at all. At the same time the +struct :c:type:`v4l2_crop` rectangle may have to be aligned, +and both the source and target rectangles may have arbitrary upper and +lower size limits. In particular the maximum ``width`` and ``height`` in +struct :c:type:`v4l2_crop` may be smaller than the struct +:c:type:`v4l2_cropcap`. ``bounds`` area. Therefore, as +usual, drivers are expected to adjust the requested parameters and +return the actual values selected. + +Applications can change the source or the target rectangle first, as +they may prefer a particular image size or a certain area in the video +signal. If the driver has to adjust both to satisfy hardware +limitations, the last requested rectangle shall take priority, and the +driver should preferably adjust the opposite one. The +:ref:`VIDIOC_TRY_FMT ` ioctl however shall not change +the driver state and therefore only adjust the requested rectangle. + +Suppose scaling on a video capture device is restricted to a factor 1:1 +or 2:1 in either direction and the target image size must be a multiple +of 16 Ă— 16 pixels. The source cropping rectangle is set to defaults, +which are also the upper limit in this example, of 640 Ă— 400 pixels at +offset 0, 0. An application requests an image size of 300 Ă— 225 pixels, +assuming video will be scaled down from the "full picture" accordingly. +The driver sets the image size to the closest possible values 304 Ă— 224, +then chooses the cropping rectangle closest to the requested size, that +is 608 Ă— 224 (224 Ă— 2:1 would exceed the limit 400). The offset 0, 0 is +still valid, thus unmodified. Given the default cropping rectangle +reported by :ref:`VIDIOC_CROPCAP ` the application can +easily propose another offset to center the cropping rectangle. + +Now the application may insist on covering an area using a picture +aspect ratio closer to the original request, so it asks for a cropping +rectangle of 608 Ă— 456 pixels. The present scaling factors limit +cropping to 640 Ă— 384, so the driver returns the cropping size 608 Ă— 384 +and adjusts the image size to closest possible 304 Ă— 192. + + +Examples +======== + +Source and target rectangles shall remain unchanged across closing and +reopening a device, such that piping data into or out of a device will +work without special preparations. More advanced applications should +ensure the parameters are suitable before starting I/O. + +.. note:: + + On the next two examples, a video capture device is assumed; + change ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` for other types of device. + +Example: Resetting the cropping parameters +========================================== + +.. code-block:: c + + struct v4l2_cropcap cropcap; + struct v4l2_crop crop; + + memset (&cropcap, 0, sizeof (cropcap)); + cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) { + perror ("VIDIOC_CROPCAP"); + exit (EXIT_FAILURE); + } + + memset (&crop, 0, sizeof (crop)); + crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + crop.c = cropcap.defrect; + + /* Ignore if cropping is not supported (EINVAL). */ + + if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) + && errno != EINVAL) { + perror ("VIDIOC_S_CROP"); + exit (EXIT_FAILURE); + } + + +Example: Simple downscaling +=========================== + +.. code-block:: c + + struct v4l2_cropcap cropcap; + struct v4l2_format format; + + reset_cropping_parameters (); + + /* Scale down to 1/4 size of full picture. */ + + memset (&format, 0, sizeof (format)); /* defaults */ + + format.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + format.fmt.pix.width = cropcap.defrect.width >> 1; + format.fmt.pix.height = cropcap.defrect.height >> 1; + format.fmt.pix.pixelformat = V4L2_PIX_FMT_YUYV; + + if (-1 == ioctl (fd, VIDIOC_S_FMT, &format)) { + perror ("VIDIOC_S_FORMAT"); + exit (EXIT_FAILURE); + } + + /* We could check the actual image size now, the actual scaling factor + or if the driver can scale at all. */ + +Example: Selecting an output area +================================= + +.. note:: This example assumes an output device. + +.. code-block:: c + + struct v4l2_cropcap cropcap; + struct v4l2_crop crop; + + memset (&cropcap, 0, sizeof (cropcap)); + cropcap.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; + + if (-1 == ioctl (fd, VIDIOC_CROPCAP;, &cropcap)) { + perror ("VIDIOC_CROPCAP"); + exit (EXIT_FAILURE); + } + + memset (&crop, 0, sizeof (crop)); + + crop.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; + crop.c = cropcap.defrect; + + /* Scale the width and height to 50 % of their original size + and center the output. */ + + crop.c.width /= 2; + crop.c.height /= 2; + crop.c.left += crop.c.width / 2; + crop.c.top += crop.c.height / 2; + + /* Ignore if cropping is not supported (EINVAL). */ + + if (-1 == ioctl (fd, VIDIOC_S_CROP, &crop) + && errno != EINVAL) { + perror ("VIDIOC_S_CROP"); + exit (EXIT_FAILURE); + } + +Example: Current scaling factor and pixel aspect +================================================ + +.. note:: This example assumes a video capture device. + +.. code-block:: c + + struct v4l2_cropcap cropcap; + struct v4l2_crop crop; + struct v4l2_format format; + double hscale, vscale; + double aspect; + int dwidth, dheight; + + memset (&cropcap, 0, sizeof (cropcap)); + cropcap.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + if (-1 == ioctl (fd, VIDIOC_CROPCAP, &cropcap)) { + perror ("VIDIOC_CROPCAP"); + exit (EXIT_FAILURE); + } + + memset (&crop, 0, sizeof (crop)); + crop.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + if (-1 == ioctl (fd, VIDIOC_G_CROP, &crop)) { + if (errno != EINVAL) { + perror ("VIDIOC_G_CROP"); + exit (EXIT_FAILURE); + } + + /* Cropping not supported. */ + crop.c = cropcap.defrect; + } + + memset (&format, 0, sizeof (format)); + format.fmt.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + + if (-1 == ioctl (fd, VIDIOC_G_FMT, &format)) { + perror ("VIDIOC_G_FMT"); + exit (EXIT_FAILURE); + } + + /* The scaling applied by the driver. */ + + hscale = format.fmt.pix.width / (double) crop.c.width; + vscale = format.fmt.pix.height / (double) crop.c.height; + + aspect = cropcap.pixelaspect.numerator / + (double) cropcap.pixelaspect.denominator; + aspect = aspect * hscale / vscale; + + /* Devices following ITU-R BT.601 do not capture + square pixels. For playback on a computer monitor + we should scale the images to this size. */ + + dwidth = format.fmt.pix.width / aspect; + dheight = format.fmt.pix.height; diff --git a/Documentation/userspace-api/media/v4l/crop.svg b/Documentation/userspace-api/media/v4l/crop.svg new file mode 100644 index 000000000..548322775 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/crop.svg @@ -0,0 +1,281 @@ + + +image/svg+xmlv4l2_cropcap.bounds +v4l2_cropcap.defrect +v4l2_crop.c +v4l2_format + + diff --git a/Documentation/userspace-api/media/v4l/depth-formats.rst b/Documentation/userspace-api/media/v4l/depth-formats.rst new file mode 100644 index 000000000..b4f3fc229 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/depth-formats.rst @@ -0,0 +1,17 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later + +.. _depth-formats: + +************* +Depth Formats +************* + +Depth data provides distance to points, mapped onto the image plane + + +.. toctree:: + :maxdepth: 1 + + pixfmt-inzi + pixfmt-z16 + pixfmt-cnf4 diff --git a/Documentation/userspace-api/media/v4l/dev-capture.rst b/Documentation/userspace-api/media/v4l/dev-capture.rst new file mode 100644 index 000000000..fe58fd450 --- /dev/null +++ b/Documentation/userspace-api/media/v4l/dev-capture.rst @@ -0,0 +1,101 @@ +.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later +.. c:namespace:: V4L + +.. _capture: + +*********************** +Video Capture Interface +*********************** + +Video capture devices sample an analog video signal and store the +digitized images in memory. Today nearly all devices can capture at full +25 or 30 frames/second. With this interface applications can control the +capture process and move images from the driver into user space. + +Conventionally V4L2 video capture devices are accessed through character +device special files named ``/dev/video`` and ``/dev/video0`` to +``/dev/video63`` with major number 81 and minor numbers 0 to 63. +``/dev/video`` is typically a symbolic link to the preferred video +device. + +.. note:: The same device file names are used for video output devices. + +Querying Capabilities +===================== + +Devices supporting the video capture interface set the +``V4L2_CAP_VIDEO_CAPTURE`` or ``V4L2_CAP_VIDEO_CAPTURE_MPLANE`` flag in +the ``capabilities`` field of struct +:c:type:`v4l2_capability` returned by the +:ref:`VIDIOC_QUERYCAP` ioctl. As secondary device +functions they may also support the :ref:`video overlay ` +(``V4L2_CAP_VIDEO_OVERLAY``) and the :ref:`raw VBI capture ` +(``V4L2_CAP_VBI_CAPTURE``) interface. At least one of the read/write or +streaming I/O methods must be supported. Tuners and audio inputs are +optional. + +Supplemental Functions +====================== + +Video capture devices shall support :ref:`audio input