diff options
Diffstat (limited to 'Documentation/media/uapi/v4l/vidioc-dqevent.rst')
| -rw-r--r-- | Documentation/media/uapi/v4l/vidioc-dqevent.rst | 722 |
1 files changed, 269 insertions, 453 deletions
diff --git a/Documentation/media/uapi/v4l/vidioc-dqevent.rst b/Documentation/media/uapi/v4l/vidioc-dqevent.rst index 73c0d5be62ee..8d663a73818e 100644 --- a/Documentation/media/uapi/v4l/vidioc-dqevent.rst +++ b/Documentation/media/uapi/v4l/vidioc-dqevent.rst @@ -15,7 +15,8 @@ VIDIOC_DQEVENT - Dequeue event Synopsis ======== -.. cpp:function:: int ioctl( int fd, int request, struct v4l2_event *argp ) +.. c:function:: int ioctl( int fd, VIDIOC_DQEVENT, struct v4l2_event *argp ) + :name: VIDIOC_DQEVENT Arguments @@ -24,9 +25,6 @@ Arguments ``fd`` File descriptor returned by :ref:`open() <func-open>`. -``request`` - VIDIOC_DQEVENT - ``argp`` @@ -34,146 +32,89 @@ Description =========== Dequeue an event from a video device. No input is required for this -ioctl. All the fields of the struct :ref:`v4l2_event <v4l2-event>` +ioctl. All the fields of the struct :c:type:`v4l2_event` structure are filled by the driver. The file handle will also receive exceptions which the application may get by e.g. using the select system call. -.. _v4l2-event: +.. tabularcolumns:: |p{3.0cm}|p{4.3cm}|p{2.5cm}|p{7.7cm}| + +.. c:type:: v4l2_event + +.. cssclass: longtable .. flat-table:: struct v4l2_event :header-rows: 0 :stub-columns: 0 :widths: 1 1 2 1 - - - .. row 1 - - - __u32 - - - ``type`` - - - - - Type of the event, see :ref:`event-type`. - - - .. row 2 - - - union - - - ``u`` - - - - - - - - .. row 3 - - - - - struct :ref:`v4l2_event_vsync <v4l2-event-vsync>` - - - ``vsync`` - - - Event data for event ``V4L2_EVENT_VSYNC``. - - - .. row 4 - - - - - struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` - - - ``ctrl`` - - - Event data for event ``V4L2_EVENT_CTRL``. - - - .. row 5 - - - - - struct :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` - - - ``frame_sync`` - - - Event data for event ``V4L2_EVENT_FRAME_SYNC``. - - - .. row 6 - - - - - struct :ref:`v4l2_event_motion_det <v4l2-event-motion-det>` - - - ``motion_det`` - - - Event data for event V4L2_EVENT_MOTION_DET. - - - .. row 7 - - - - - struct :ref:`v4l2_event_src_change <v4l2-event-src-change>` - - - ``src_change`` - - - Event data for event V4L2_EVENT_SOURCE_CHANGE. - - - .. row 8 - - - - - __u8 - - - ``data``\ [64] - - - Event data. Defined by the event type. The union should be used to - define easily accessible type for events. - - - .. row 9 - - - __u32 - - - ``pending`` - - - - - Number of pending events excluding this one. - - - .. row 10 - - - __u32 - - - ``sequence`` - - - - - Event sequence number. The sequence number is incremented for - every subscribed event that takes place. If sequence numbers are - not contiguous it means that events have been lost. - - - .. row 11 - - - struct timespec - - - ``timestamp`` - - - - - Event timestamp. The timestamp has been taken from the - ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2, - use :c:func:`clock_gettime(2)`. - - - .. row 12 - - - u32 - - - ``id`` - - - - - The ID associated with the event source. If the event does not - have an associated ID (this depends on the event type), then this - is 0. - - - .. row 13 - - - __u32 - - - ``reserved``\ [8] - - - - - Reserved for future extensions. Drivers must set the array to - zero. - - + * - __u32 + - ``type`` + - + - Type of the event, see :ref:`event-type`. + * - union + - ``u`` + - + - + * - + - struct :c:type:`v4l2_event_vsync` + - ``vsync`` + - Event data for event ``V4L2_EVENT_VSYNC``. + * - + - struct :c:type:`v4l2_event_ctrl` + - ``ctrl`` + - Event data for event ``V4L2_EVENT_CTRL``. + * - + - struct :c:type:`v4l2_event_frame_sync` + - ``frame_sync`` + - Event data for event ``V4L2_EVENT_FRAME_SYNC``. + * - + - struct :c:type:`v4l2_event_motion_det` + - ``motion_det`` + - Event data for event V4L2_EVENT_MOTION_DET. + * - + - struct :c:type:`v4l2_event_src_change` + - ``src_change`` + - Event data for event V4L2_EVENT_SOURCE_CHANGE. + * - + - __u8 + - ``data``\ [64] + - Event data. Defined by the event type. The union should be used to + define easily accessible type for events. + * - __u32 + - ``pending`` + - + - Number of pending events excluding this one. + * - __u32 + - ``sequence`` + - + - Event sequence number. The sequence number is incremented for + every subscribed event that takes place. If sequence numbers are + not contiguous it means that events have been lost. + * - struct timespec + - ``timestamp`` + - + - Event timestamp. The timestamp has been taken from the + ``CLOCK_MONOTONIC`` clock. To access the same clock outside V4L2, + use :c:func:`clock_gettime`. + * - u32 + - ``id`` + - + - The ID associated with the event source. If the event does not + have an associated ID (this depends on the event type), then this + is 0. + * - __u32 + - ``reserved``\ [8] + - + - Reserved for future extensions. Drivers must set the array to + zero. + + + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| + +.. cssclass:: longtable .. _event-type: @@ -182,330 +123,223 @@ call. :stub-columns: 0 :widths: 3 1 4 - - - .. row 1 - - - ``V4L2_EVENT_ALL`` - - - 0 - - - All events. V4L2_EVENT_ALL is valid only for - VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once. - - - .. row 2 - - - ``V4L2_EVENT_VSYNC`` - - - 1 - - - This event is triggered on the vertical sync. This event has a - struct :ref:`v4l2_event_vsync <v4l2-event-vsync>` associated - with it. - - - .. row 3 - - - ``V4L2_EVENT_EOS`` - - - 2 - - - This event is triggered when the end of a stream is reached. This - is typically used with MPEG decoders to report to the application - when the last of the MPEG stream has been decoded. - - - .. row 4 - - - ``V4L2_EVENT_CTRL`` - - - 3 - - - This event requires that the ``id`` matches the control ID from - which you want to receive events. This event is triggered if the - control's value changes, if a button control is pressed or if the - control's flags change. This event has a struct - :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` associated with it. - This struct contains much of the same information as struct - :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct - :ref:`v4l2_control <v4l2-control>`. - - If the event is generated due to a call to - :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` or - :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then the - event will *not* be sent to the file handle that called the ioctl - function. This prevents nasty feedback loops. If you *do* want to - get the event, then set the ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK`` - flag. - - This event type will ensure that no information is lost when more - events are raised than there is room internally. In that case the - struct :ref:`v4l2_event_ctrl <v4l2-event-ctrl>` of the - second-oldest event is kept, but the ``changes`` field of the - second-oldest event is ORed with the ``changes`` field of the - oldest event. - - - .. row 5 - - - ``V4L2_EVENT_FRAME_SYNC`` - - - 4 - - - Triggered immediately when the reception of a frame has begun. - This event has a struct - :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` - associated with it. - - If the hardware needs to be stopped in the case of a buffer - underrun it might not be able to generate this event. In such - cases the ``frame_sequence`` field in struct - :ref:`v4l2_event_frame_sync <v4l2-event-frame-sync>` will not - be incremented. This causes two consecutive frame sequence numbers - to have n times frame interval in between them. - - - .. row 6 - - - ``V4L2_EVENT_SOURCE_CHANGE`` - - - 5 - - - This event is triggered when a source parameter change is detected - during runtime by the video device. It can be a runtime resolution - change triggered by a video decoder or the format change happening - on an input connector. This event requires that the ``id`` matches - the input index (when used with a video device node) or the pad - index (when used with a subdevice node) from which you want to - receive events. - - This event has a struct - :ref:`v4l2_event_src_change <v4l2-event-src-change>` - associated with it. The ``changes`` bitfield denotes what has - changed for the subscribed pad. If multiple events occurred before - application could dequeue them, then the changes will have the - ORed value of all the events generated. - - - .. row 7 - - - ``V4L2_EVENT_MOTION_DET`` - - - 6 - - - Triggered whenever the motion detection state for one or more of - the regions changes. This event has a struct - :ref:`v4l2_event_motion_det <v4l2-event-motion-det>` - associated with it. - - - .. row 8 - - - ``V4L2_EVENT_PRIVATE_START`` - - - 0x08000000 - - - Base event number for driver-private events. - - - -.. _v4l2-event-vsync: + * - ``V4L2_EVENT_ALL`` + - 0 + - All events. V4L2_EVENT_ALL is valid only for + VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once. + * - ``V4L2_EVENT_VSYNC`` + - 1 + - This event is triggered on the vertical sync. This event has a + struct :c:type:`v4l2_event_vsync` associated + with it. + * - ``V4L2_EVENT_EOS`` + - 2 + - This event is triggered when the end of a stream is reached. This + is typically used with MPEG decoders to report to the application + when the last of the MPEG stream has been decoded. + * - ``V4L2_EVENT_CTRL`` + - 3 + - This event requires that the ``id`` matches the control ID from + which you want to receive events. This event is triggered if the + control's value changes, if a button control is pressed or if the + control's flags change. This event has a struct + :c:type:`v4l2_event_ctrl` associated with it. + This struct contains much of the same information as struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>` and struct + :c:type:`v4l2_control`. + + If the event is generated due to a call to + :ref:`VIDIOC_S_CTRL <VIDIOC_G_CTRL>` or + :ref:`VIDIOC_S_EXT_CTRLS <VIDIOC_G_EXT_CTRLS>`, then the + event will *not* be sent to the file handle that called the ioctl + function. This prevents nasty feedback loops. If you *do* want to + get the event, then set the ``V4L2_EVENT_SUB_FL_ALLOW_FEEDBACK`` + flag. + + This event type will ensure that no information is lost when more + events are raised than there is room internally. In that case the + struct :c:type:`v4l2_event_ctrl` of the + second-oldest event is kept, but the ``changes`` field of the + second-oldest event is ORed with the ``changes`` field of the + oldest event. + * - ``V4L2_EVENT_FRAME_SYNC`` + - 4 + - Triggered immediately when the reception of a frame has begun. + This event has a struct + :c:type:`v4l2_event_frame_sync` + associated with it. + + If the hardware needs to be stopped in the case of a buffer + underrun it might not be able to generate this event. In such + cases the ``frame_sequence`` field in struct + :c:type:`v4l2_event_frame_sync` will not + be incremented. This causes two consecutive frame sequence numbers + to have n times frame interval in between them. + * - ``V4L2_EVENT_SOURCE_CHANGE`` + - 5 + - This event is triggered when a source parameter change is detected + during runtime by the video device. It can be a runtime resolution + change triggered by a video decoder or the format change happening + on an input connector. This event requires that the ``id`` matches + the input index (when used with a video device node) or the pad + index (when used with a subdevice node) from which you want to + receive events. + + This event has a struct + :c:type:`v4l2_event_src_change` + associated with it. The ``changes`` bitfield denotes what has + changed for the subscribed pad. If multiple events occurred before + application could dequeue them, then the changes will have the + ORed value of all the events generated. + * - ``V4L2_EVENT_MOTION_DET`` + - 6 + - Triggered whenever the motion detection state for one or more of + the regions changes. This event has a struct + :c:type:`v4l2_event_motion_det` + associated with it. + * - ``V4L2_EVENT_PRIVATE_START`` + - 0x08000000 + - Base event number for driver-private events. + + + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| + +.. c:type:: v4l2_event_vsync .. flat-table:: struct v4l2_event_vsync :header-rows: 0 :stub-columns: 0 :widths: 1 1 2 + * - __u8 + - ``field`` + - The upcoming field. See enum :c:type:`v4l2_field`. - - .. row 1 - - - __u8 - - - ``field`` - - - The upcoming field. See enum :ref:`v4l2_field <v4l2-field>`. +.. tabularcolumns:: |p{3.5cm}|p{3.0cm}|p{1.8cm}|p{8.5cm}| -.. _v4l2-event-ctrl: +.. c:type:: v4l2_event_ctrl .. flat-table:: struct v4l2_event_ctrl :header-rows: 0 :stub-columns: 0 :widths: 1 1 2 1 - - - .. row 1 - - - __u32 - - - ``changes`` - - - - - A bitmask that tells what has changed. See - :ref:`ctrl-changes-flags`. - - - .. row 2 - - - __u32 - - - ``type`` - - - - - The type of the control. See enum - :ref:`v4l2_ctrl_type <v4l2-ctrl-type>`. - - - .. row 3 - - - union (anonymous) - - - - - - - - - - .. row 4 - - - - - __s32 - - - ``value`` - - - The 32-bit value of the control for 32-bit control types. This is - 0 for string controls since the value of a string cannot be passed - using :ref:`VIDIOC_DQEVENT`. - - - .. row 5 - - - - - __s64 - - - ``value64`` - - - The 64-bit value of the control for 64-bit control types. - - - .. row 6 - - - __u32 - - - ``flags`` - - - - - The control flags. See :ref:`control-flags`. - - - .. row 7 - - - __s32 - - - ``minimum`` - - - - - The minimum value of the control. See struct - :ref:`v4l2_queryctrl <v4l2-queryctrl>`. - - - .. row 8 - - - __s32 - - - ``maximum`` - - - - - The maximum value of the control. See struct - :ref:`v4l2_queryctrl <v4l2-queryctrl>`. - - - .. row 9 - - - __s32 - - - ``step`` - - - - - The step value of the control. See struct - :ref:`v4l2_queryctrl <v4l2-queryctrl>`. - - - .. row 10 - - - __s32 - - - ``default_value`` - - - - - The default value value of the control. See struct - :ref:`v4l2_queryctrl <v4l2-queryctrl>`. - - - -.. _v4l2-event-frame-sync: + * - __u32 + - ``changes`` + - + - A bitmask that tells what has changed. See + :ref:`ctrl-changes-flags`. + * - __u32 + - ``type`` + - + - The type of the control. See enum + :c:type:`v4l2_ctrl_type`. + * - union (anonymous) + - + - + - + * - + - __s32 + - ``value`` + - The 32-bit value of the control for 32-bit control types. This is + 0 for string controls since the value of a string cannot be passed + using :ref:`VIDIOC_DQEVENT`. + * - + - __s64 + - ``value64`` + - The 64-bit value of the control for 64-bit control types. + * - __u32 + - ``flags`` + - + - The control flags. See :ref:`control-flags`. + * - __s32 + - ``minimum`` + - + - The minimum value of the control. See struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>`. + * - __s32 + - ``maximum`` + - + - The maximum value of the control. See struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>`. + * - __s32 + - ``step`` + - + - The step value of the control. See struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>`. + * - __s32 + - ``default_value`` + - + - The default value value of the control. See struct + :ref:`v4l2_queryctrl <v4l2-queryctrl>`. + + + +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| + +.. c:type:: v4l2_event_frame_sync .. flat-table:: struct v4l2_event_frame_sync :header-rows: 0 :stub-columns: 0 :widths: 1 1 2 + * - __u32 + - ``frame_sequence`` + - The sequence number of the frame being received. - - .. row 1 - - - __u32 - - - ``frame_sequence`` - - The sequence number of the frame being received. +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. _v4l2-event-src-change: +.. c:type:: v4l2_event_src_change .. flat-table:: struct v4l2_event_src_change :header-rows: 0 :stub-columns: 0 :widths: 1 1 2 + * - __u32 + - ``changes`` + - A bitmask that tells what has changed. See + :ref:`src-changes-flags`. - - .. row 1 - - - __u32 - - - ``changes`` - - A bitmask that tells what has changed. See - :ref:`src-changes-flags`. +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}| - -.. _v4l2-event-motion-det: +.. c:type:: v4l2_event_motion_det .. flat-table:: struct v4l2_event_motion_det :header-rows: 0 :stub-columns: 0 :widths: 1 1 2 - - - .. row 1 - - - __u32 - - - ``flags`` - - - Currently only one flag is available: if - ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` is set, then the - ``frame_sequence`` field is valid, otherwise that field should be - ignored. - - - .. row 2 - - - __u32 - - - ``frame_sequence`` - - - The sequence number of the frame being received. Only valid if the - ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` flag was set. - - - .. row 3 - - - __u32 - - - ``region_mask`` - - - The bitmask of the regions that reported motion. There is at least - one region. If this field is 0, then no motion was detected at - all. If there is no ``V4L2_CID_DETECT_MD_REGION_GRID`` control - (see :ref:`detect-controls`) to assign a different region to - each cell in the motion detection grid, then that all cells are - automatically assigned to the default region 0. - - + * - __u32 + - ``flags`` + - Currently only one flag is available: if + ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` is set, then the + ``frame_sequence`` field is valid, otherwise that field should be + ignored. + * - __u32 + - ``frame_sequence`` + - The sequence number of the frame being received. Only valid if the + ``V4L2_EVENT_MD_FL_HAVE_FRAME_SEQ`` flag was set. + * - __u32 + - ``region_mask`` + - The bitmask of the regions that reported motion. There is at least + one region. If this field is 0, then no motion was detected at + all. If there is no ``V4L2_CID_DETECT_MD_REGION_GRID`` control + (see :ref:`detect-controls`) to assign a different region to + each cell in the motion detection grid, then that all cells are + automatically assigned to the default region 0. + + + +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _ctrl-changes-flags: @@ -514,37 +348,24 @@ call. :stub-columns: 0 :widths: 3 1 4 + * - ``V4L2_EVENT_CTRL_CH_VALUE`` + - 0x0001 + - This control event was triggered because the value of the control + changed. Special cases: Volatile controls do no generate this + event; If a control has the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` + flag set, then this event is sent as well, regardless its value. + * - ``V4L2_EVENT_CTRL_CH_FLAGS`` + - 0x0002 + - This control event was triggered because the control flags + changed. + * - ``V4L2_EVENT_CTRL_CH_RANGE`` + - 0x0004 + - This control event was triggered because the minimum, maximum, + step or the default value of the control changed. - - .. row 1 - - - ``V4L2_EVENT_CTRL_CH_VALUE`` - - - 0x0001 - - - This control event was triggered because the value of the control - changed. Special cases: Volatile controls do no generate this - event; If a control has the ``V4L2_CTRL_FLAG_EXECUTE_ON_WRITE`` - flag set, then this event is sent as well, regardless its value. - - - .. row 2 - - - ``V4L2_EVENT_CTRL_CH_FLAGS`` - - - 0x0002 - - - This control event was triggered because the control flags - changed. - - - .. row 3 - - - ``V4L2_EVENT_CTRL_CH_RANGE`` - - - 0x0004 - - - This control event was triggered because the minimum, maximum, - step or the default value of the control changed. +.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}| .. _src-changes-flags: @@ -553,16 +374,11 @@ call. :stub-columns: 0 :widths: 3 1 4 - - - .. row 1 - - - ``V4L2_EVENT_SRC_CH_RESOLUTION`` - - - 0x0001 - - - This event gets triggered when a resolution change is detected at - an input. This can come from an input connector or from a video - decoder. + * - ``V4L2_EVENT_SRC_CH_RESOLUTION`` + - 0x0001 + - This event gets triggered when a resolution change is detected at + an input. This can come from an input connector or from a video + decoder. Return Value |