--- zzzz-none-000/linux-3.10.107/Documentation/DocBook/media/v4l/io.xml 2017-06-27 09:49:32.000000000 +0000 +++ scorpion-7490-727/linux-3.10.107/Documentation/DocBook/media/v4l/io.xml 2021-02-04 17:41:59.000000000 +0000 @@ -125,7 +125,7 @@ m.offset and length returned in a &v4l2-buffer; are passed as sixth and second parameter to the mmap() function. When using the multi-planar API, -struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each +&v4l2-buffer; contains an array of &v4l2-plane; structures, each containing its own m.offset and length. When using the multi-planar API, every plane of every buffer has to be mapped separately, so the number of @@ -339,8 +339,8 @@ queues as a side effect. Since there is no notion of doing anything "now" on a multitasking system, if an application needs to synchronize with another event it should examine the &v4l2-buffer; -timestamp of captured buffers, or set the -field before enqueuing buffers for output. +timestamp of captured or outputted buffers. + Drivers implementing memory mapping I/O must support the VIDIOC_REQBUFS, @@ -457,7 +457,7 @@ notion of doing anything "now" on a multitasking system, if an application needs to synchronize with another event it should examine the &v4l2-buffer; timestamp of captured -buffers, or set the field before enqueuing buffers for output. +or outputted buffers. Drivers implementing user pointer I/O must support the VIDIOC_REQBUFS, @@ -620,8 +620,7 @@ unlocks all buffers as a side effect. Since there is no notion of doing anything "now" on a multitasking system, if an application needs to synchronize with another event it should examine the &v4l2-buffer; -timestamp of captured buffers, or set the field -before enqueuing buffers for output. +timestamp of captured or outputted buffers. Drivers implementing DMABUF importing I/O must support the VIDIOC_REQBUFS, VIDIOC_QBUF, @@ -654,38 +653,19 @@ In that case, struct v4l2_buffer contains an array of plane structures. - Nominally timestamps refer to the first data byte transmitted. -In practice however the wide range of hardware covered by the V4L2 API -limits timestamp accuracy. Often an interrupt routine will -sample the system clock shortly after the field or frame was stored -completely in memory. So applications must expect a constant -difference up to one field or frame period plus a small (few scan -lines) random error. The delay and error can be much -larger due to compression or transmission over an external bus when -the frames are not properly stamped by the sender. This is frequently -the case with USB cameras. Here timestamps refer to the instant the -field or frame was received by the driver, not the capture time. These -devices identify by not enumerating any video standards, see . - - Similar limitations apply to output timestamps. Typically -the video hardware locks to a clock controlling the video timing, the -horizontal and vertical synchronization pulses. At some point in the -line sequence, possibly the vertical blanking, an interrupt routine -samples the system clock, compares against the timestamp and programs -the hardware to repeat the previous field or frame, or to display the -buffer contents. - - Apart of limitations of the video device and natural -inaccuracies of all clocks, it should be noted system time itself is -not perfectly stable. It can be affected by power saving cycles, -warped to insert leap seconds, or even turned back or forth by the -system administrator affecting long term measurements. - Since no other Linux multimedia -API supports unadjusted time it would be foolish to introduce here. We -must use a universally supported clock to synchronize different media, -hence time of day. - + 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 . 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 &VIDIOC-S-INPUT; or + &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. struct <structname>v4l2_buffer</structname> @@ -696,10 +676,11 @@ __u32index - Number of the buffer, set by the application. This -field is only used for memory mapping I/O -and can range from zero to the number of buffers allocated -with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; count) minus one. + Number of the buffer, set by the application except +when calling &VIDIOC-DQBUF;, then it is set by the driver. +This field can range from zero to the number of buffers allocated +with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; count), +plus any buffers allocated with &VIDIOC-CREATE-BUFS; minus one. __u32 @@ -718,7 +699,12 @@ 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 an input stream, applications when an output stream. +refers to an input 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 @@ -735,7 +721,7 @@ buffer, see . This field is not used when the buffer contains VBI data. Drivers must set it when type refers to an input stream, -applications when an output stream. +applications when it refers to an output stream. struct timeval @@ -745,15 +731,13 @@ byte was captured, as returned by the clock_gettime() function for the relevant clock id; see V4L2_BUF_FLAG_TIMESTAMP_* in - . For output streams the data - will not be displayed before this time, secondary to the nominal - frame rate determined by the current video standard in enqueued - order. Applications can for example zero this field to display - frames as soon as possible. The driver stores the time at which - the first data byte was actually sent out in the - timestamp field. This permits + . 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. + 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. &v4l2-timecode; @@ -846,7 +830,8 @@ length Size of the buffer (not the payload) in bytes for the - single-planar API. For the multi-planar API the application sets + single-planar API. This is set by the driver based on the calls to + &VIDIOC-REQBUFS; and/or &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. @@ -856,15 +841,15 @@ __u32 reserved2 - A place holder for future extensions. Applications -should set this to 0. + A place holder for future extensions. Drivers and applications +must set this to 0. __u32 reserved - A place holder for future extensions. Applications -should set this to 0. + A place holder for future extensions. Drivers and applications +must set this to 0. @@ -880,13 +865,20 @@ bytesusedThe number of bytes occupied by data in the plane - (its payload). + (its payload). Drivers must set this field when type + refers to an input stream, applications when it refers to an output stream. + If the application sets this to 0 for an output stream, then + bytesused will be set to the size of the + plane (see the length field of this struct) + by the driver. Note that the actual image data starts at + data_offset which may not be 0. __u32 length - Size in bytes of the plane (not its payload). + Size in bytes of the plane (not its payload). This is set by the driver + based on the calls to &VIDIOC-REQBUFS; and/or &VIDIOC-CREATE-BUFS;. union @@ -925,15 +917,21 @@ __u32 data_offset - Offset in bytes to video data in the plane, if applicable. + Offset in bytes to video data in the plane. + Drivers must set this field when type + refers to an input 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 an - application. + Reserved for future use. Should be zeroed by drivers and + applications. @@ -1005,6 +1003,18 @@ Buffer for video output overlay (OSD), see . + + V4L2_BUF_TYPE_SDR_CAPTURE + 11 + Buffer for Software Defined Radio (SDR) capture stream, see + . + + + V4L2_BUF_TYPE_SDR_OUTPUT + 12 + Buffer for Software Defined Radio (SDR) output stream, see + . +
@@ -1016,7 +1026,7 @@ V4L2_BUF_FLAG_MAPPED - 0x0001 + 0x00000001 The buffer resides in device memory and has been mapped into the application's address space, see for details. Drivers set or clear this flag when the @@ -1026,7 +1036,7 @@ V4L2_BUF_FLAG_QUEUED - 0x0002 + 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 @@ -1039,7 +1049,7 @@ V4L2_BUF_FLAG_DONE - 0x0004 + 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 @@ -1049,11 +1059,11 @@ 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 to say so. +state, in the application domain so to say. V4L2_BUF_FLAG_ERROR - 0x0040 + 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 @@ -1063,35 +1073,43 @@ V4L2_BUF_FLAG_KEYFRAME - 0x0008 + 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), &ie; can be decompressed on its own. +key frame (or field), &ie; 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 - 0x0010 + 0x00000010 Similar to V4L2_BUF_FLAG_KEYFRAME this flags predicted frames or fields which contain only differences to a -previous key frame. +previous key frame. Applications can set this bit when type +refers to an output stream. V4L2_BUF_FLAG_BFRAME - 0x0020 - Similar to V4L2_BUF_FLAG_PFRAME - this is a bidirectional predicted frame or field. [ooc tbd] + 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 - 0x0100 + 0x00000100 The timecode field is valid. Drivers set or clear this flag when the VIDIOC_DQBUF -ioctl is called. +ioctl is called. Applications can set this bit and the corresponding +timecode structure when type +refers to an output stream. V4L2_BUF_FLAG_PREPARED - 0x0400 + 0x00000400 The buffer has been prepared for I/O and can be queued by the application. Drivers set or clear this flag when the VIDIOC_QUERYBUF, V4L2_BUF_FLAG_NO_CACHE_INVALIDATE - 0x0800 + 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 @@ -1110,15 +1128,27 @@ V4L2_BUF_FLAG_NO_CACHE_CLEAN - 0x1000 + 0x00001000 Caches do not have to be cleaned for this buffer. Typically applications shall use this flag for output buffers if the data in this buffer has not been created by the CPU but by some DMA-capable unit, in which case caches have not been used. + V4L2_BUF_FLAG_LAST + 0x00100000 + Last buffer produced by the hardware. mem2mem codec drivers +set this flag on the capture queue for the last buffer when the +VIDIOC_QUERYBUF or +VIDIOC_DQBUF ioctl is called. Due to hardware +limitations, the last buffer may be empty. In this case the driver will set the +bytesused field to 0, regardless of the format. Any +Any subsequent call to the VIDIOC_DQBUF ioctl +will not block anymore, but return an &EPIPE;. + + V4L2_BUF_FLAG_TIMESTAMP_MASK - 0xe000 + 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 @@ -1126,7 +1156,7 @@ V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN - 0x0000 + 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 @@ -1139,18 +1169,50 @@ V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC - 0x2000 + 0x00002000 The buffer timestamp has been taken from the CLOCK_MONOTONIC clock. To access the same clock outside V4L2, use - clock_gettime(2) . + clock_gettime(2). V4L2_BUF_FLAG_TIMESTAMP_COPY - 0x4000 + 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 + 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 + 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 + 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. + @@ -1378,7 +1440,10 @@ V4L2_FIELD_BOTTOM, or V4L2_FIELD_INTERLACED formats is acceptable. Drivers choose depending on hardware capabilities or e. g. the -requested image size, and return the actual field order. &v4l2-buffer; +requested image size, and return the actual field order. Drivers must +never return V4L2_FIELD_ANY. If multiple +field orders are possible the driver must choose one of the possible +field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;. &v4l2-buffer; field can never be V4L2_FIELD_ANY. @@ -1440,10 +1505,9 @@ V4L2_FIELD_BOTTOM. Any two successive fields pair to build a frame. If fields are successive, without any dropped fields between them (fields can drop individually), can be determined from -the &v4l2-buffer; sequence field. Image -sizes refer to the frame, not fields. This format cannot be selected -when using the read/write I/O method. +the &v4l2-buffer; sequence field. This format +cannot be selected when using the read/write I/O method since there +is no way to communicate if a field was a top or bottom field. V4L2_FIELD_INTERLACED_TB