| Message ID | 20200804192939.2251988-1-helen.koike@collabora.com |
|---|---|
| Headers | show |
| Series | media: v4l2: Add extended fmt and buffer ioctls | expand |
Hi Hans, On 9/9/20 8:41 AM, Hans Verkuil wrote: > Hi Helen, > > Some review comments, concentrating on the uAPI. > > On 04/08/2020 21:29, Helen Koike wrote: >> This is part of the multiplanar and singleplanar unification process. >> v4l2_ext_pix_format is supposed to work for both cases. >> >> We also add the concept of modifiers already employed in DRM to expose >> HW-specific formats (like tiled or compressed formats) and allow >> exchanging this information with the DRM subsystem in a consistent way. >> >> Note that only V4L2_BUF_TYPE_VIDEO_[OUTPUT,CAPTURE] are accepted in >> v4l2_ext_format, other types will be rejected if you use the >> {G,S,TRY}_EXT_PIX_FMT ioctls. >> >> New hooks have been added to v4l2_ioctl_ops to support those new ioctls >> in drivers, but, in the meantime, the core takes care of converting >> {S,G,TRY}_EXT_PIX_FMT requests into {S,G,TRY}_FMT so that old drivers can >> still work if the userspace app/lib uses the new ioctls. >> The conversion is also done the other around to allow userspace >> apps/libs using {S,G,TRY}_FMT to work with drivers implementing the >> _ext_ hooks. >> >> Signed-off-by: Boris Brezillon <boris.brezillon@collabora.com> >> Signed-off-by: Helen Koike <helen.koike@collabora.com> >> --- >> Changes in v5: >> - change sizes and reorder fields to avoid holes in the struct and make >> it the same for 32 and 64 bits >> - removed __attribute__ ((packed)) from uapi structs >> - Fix doc warning from make htmldocs >> - Updated commit message with EXT_PIX prefix for the ioctls. >> >> Changes in v4: >> - Use v4l2_ext_pix_format directly in the ioctl, drop v4l2_ext_format, >> making V4L2_BUF_TYPE_VIDEO_[OUTPUT,CAPTURE] the only valid types. >> - Add reserved fields >> - Removed num_planes from struct v4l2_ext_pix_format >> - Removed flag field from struct v4l2_ext_pix_format, since the only >> defined value is V4L2_PIX_FMT_FLAG_PREMUL_ALPHA only used by vsp1, >> where we can use modifiers, or add it back later through the reserved >> bits. >> - In v4l2_ext_format_to_format(), check if modifier is != MOD_LINEAR && >> != MOD_INVALID >> - Fix type assignment in v4l_g_fmt_ext_pix() >> - Rebased on top of media/master (post 5.8-rc1) >> >> Changes in v3: >> - Rebased on top of media/master (post 5.4-rc1) >> >> Changes in v2: >> - Move the modifier in v4l2_ext_format (was formerly placed in >> v4l2_ext_plane) >> - Fix a few bugs in the converters and add a strict parameter to >> allow conversion of uninitialized/mis-initialized objects >> --- >> drivers/media/v4l2-core/v4l2-dev.c | 21 +- >> drivers/media/v4l2-core/v4l2-ioctl.c | 585 +++++++++++++++++++++++---- >> include/media/v4l2-ioctl.h | 34 ++ >> include/uapi/linux/videodev2.h | 56 +++ >> 4 files changed, 615 insertions(+), 81 deletions(-) >> > > <snip> > >> diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h >> index c7b70ff53bc1d..7123c6a4d9569 100644 >> --- a/include/uapi/linux/videodev2.h >> +++ b/include/uapi/linux/videodev2.h >> @@ -2254,6 +2254,58 @@ struct v4l2_pix_format_mplane { >> __u8 reserved[7]; >> } __attribute__ ((packed)); >> >> +/** >> + * struct v4l2_plane_ext_pix_format - additional, per-plane format definition >> + * @sizeimage: maximum size in bytes required for data, for which >> + * this plane will be used. >> + * Should be set to zero for unused planes. >> + * @bytesperline: distance in bytes between the leftmost pixels in two >> + * adjacent lines >> + * @reserved: extra space reserved for future fields, must be set to 0 >> + */ >> +struct v4l2_plane_ext_pix_format { >> + __u32 sizeimage; >> + __u32 bytesperline; >> + __u32 reserved; > > I'd use reserved[4] here. > >> +}; >> + >> +/** >> + * struct v4l2_ext_pix_format - extended single/multiplanar format definition >> + * @type: type of the data stream; V4L2_BUF_TYPE_VIDEO_CAPTURE or >> + * V4L2_BUF_TYPE_VIDEO_OUTPUT >> + * @width: image width in pixels >> + * @height: image height in pixels >> + * @field: enum v4l2_field; field order (for interlaced video) >> + * @pixelformat: little endian four character code (fourcc) >> + * @modifier: modifier applied to the format (used for tiled formats >> + * and other kind of HW-specific formats, like compressed >> + * formats) > > This should refer to the drm.h header since we're reusing the DRM modifiers. > >> + * @colorspace: enum v4l2_colorspace; supplemental to pixelformat >> + * @plane_fmt: per-plane information >> + * @ycbcr_enc: enum v4l2_ycbcr_encoding, Y'CbCr encoding >> + * @hsv_enc: enum v4l2_hsv_encoding, HSV encoding >> + * @quantization: enum v4l2_quantization, colorspace quantization >> + * @xfer_func: enum v4l2_xfer_func, colorspace transfer function >> + * @reserved: extra space reserved for future fields, must be set to 0 >> + */ >> +struct v4l2_ext_pix_format { >> + __u32 type; >> + __u32 width; >> + __u32 height; >> + __u32 field; >> + __u64 modifier; >> + __u32 pixelformat; >> + __u32 colorspace; >> + struct v4l2_plane_ext_pix_format plane_fmt[VIDEO_MAX_PLANES]; >> + union { >> + __u32 ycbcr_enc; >> + __u32 hsv_enc; >> + }; >> + __u32 quantization; >> + __u32 xfer_func; > > I'd reorder this: > > struct v4l2_plane_ext_pix_format plane_fmt[VIDEO_MAX_PLANES]; > __u32 pixelformat; > __u32 colorspace; > __u32 xfer_func; > union { > __u32 ycbcr_enc; > __u32 hsv_enc; > }; > __u32 quantization; > > The reason for reordering is that I like to keep the colorimetry fields in > that order since that is how these fields are processed mathematically: you > apply the colorspace matrix first, then the transfer function, then optionally > convert to Y'CbCr or HSV and finally you quantize the result. > > There is also a __u32 flags; field missing (needed for V4L2_PIX_FMT_FLAG_PREMUL_ALPHA > and for the upcoming CSC support). We discussed this on v4 https://patchwork.linuxtv.org/project/linux-media/cover/20200717115435.2632623-1-helen.koike@collabora.com/ The idea is to replace V4L2_PIX_FMT_FLAG_PREMUL_ALPHA by a modifier, and this API won't need CSC, since the colorspace fields are read-write. Regards, Helen > >> + __u32 reserved[9]; >> +}; >> + >> /** >> * struct v4l2_sdr_format - SDR format definition >> * @pixelformat: little endian four character code (fourcc) >> @@ -2571,6 +2623,10 @@ struct v4l2_create_buffers { >> >> #define VIDIOC_QUERY_EXT_CTRL _IOWR('V', 103, struct v4l2_query_ext_ctrl) >> >> +#define VIDIOC_G_EXT_PIX_FMT _IOWR('V', 104, struct v4l2_ext_pix_format) >> +#define VIDIOC_S_EXT_PIX_FMT _IOWR('V', 105, struct v4l2_ext_pix_format) >> +#define VIDIOC_TRY_EXT_PIX_FMT _IOWR('V', 106, struct v4l2_ext_pix_format) >> + >> /* Reminder: when adding new ioctls please add support for them to >> drivers/media/v4l2-core/v4l2-compat-ioctl32.c as well! */ >> >> > > Regards, > > Hans >
Hi Helen, On Tue, Aug 04, 2020 at 04:29:33PM -0300, Helen Koike wrote: > This is part of the multiplanar and singleplanar unification process. > v4l2_ext_pix_format is supposed to work for both cases. > > We also add the concept of modifiers already employed in DRM to expose > HW-specific formats (like tiled or compressed formats) and allow > exchanging this information with the DRM subsystem in a consistent way. > > Note that only V4L2_BUF_TYPE_VIDEO_[OUTPUT,CAPTURE] are accepted in > v4l2_ext_format, other types will be rejected if you use the > {G,S,TRY}_EXT_PIX_FMT ioctls. > > New hooks have been added to v4l2_ioctl_ops to support those new ioctls > in drivers, but, in the meantime, the core takes care of converting > {S,G,TRY}_EXT_PIX_FMT requests into {S,G,TRY}_FMT so that old drivers can > still work if the userspace app/lib uses the new ioctls. > The conversion is also done the other around to allow userspace > apps/libs using {S,G,TRY}_FMT to work with drivers implementing the > _ext_ hooks. > Thank you for the patch. Please see my comments inline. > Signed-off-by: Boris Brezillon <boris.brezillon@collabora.com> > Signed-off-by: Helen Koike <helen.koike@collabora.com> > --- > Changes in v5: > - change sizes and reorder fields to avoid holes in the struct and make > it the same for 32 and 64 bits > - removed __attribute__ ((packed)) from uapi structs > - Fix doc warning from make htmldocs > - Updated commit message with EXT_PIX prefix for the ioctls. > > Changes in v4: > - Use v4l2_ext_pix_format directly in the ioctl, drop v4l2_ext_format, > making V4L2_BUF_TYPE_VIDEO_[OUTPUT,CAPTURE] the only valid types. > - Add reserved fields > - Removed num_planes from struct v4l2_ext_pix_format > - Removed flag field from struct v4l2_ext_pix_format, since the only > defined value is V4L2_PIX_FMT_FLAG_PREMUL_ALPHA only used by vsp1, > where we can use modifiers, or add it back later through the reserved > bits. > - In v4l2_ext_format_to_format(), check if modifier is != MOD_LINEAR && > != MOD_INVALID > - Fix type assignment in v4l_g_fmt_ext_pix() > - Rebased on top of media/master (post 5.8-rc1) > > Changes in v3: > - Rebased on top of media/master (post 5.4-rc1) > > Changes in v2: > - Move the modifier in v4l2_ext_format (was formerly placed in > v4l2_ext_plane) > - Fix a few bugs in the converters and add a strict parameter to > allow conversion of uninitialized/mis-initialized objects > --- > drivers/media/v4l2-core/v4l2-dev.c | 21 +- > drivers/media/v4l2-core/v4l2-ioctl.c | 585 +++++++++++++++++++++++---- > include/media/v4l2-ioctl.h | 34 ++ > include/uapi/linux/videodev2.h | 56 +++ > 4 files changed, 615 insertions(+), 81 deletions(-) > > diff --git a/drivers/media/v4l2-core/v4l2-dev.c b/drivers/media/v4l2-core/v4l2-dev.c > index a593ea0598b55..e1829906bc086 100644 > --- a/drivers/media/v4l2-core/v4l2-dev.c > +++ b/drivers/media/v4l2-core/v4l2-dev.c > @@ -607,25 +607,37 @@ static void determine_valid_ioctls(struct video_device *vdev) > set_bit(_IOC_NR(VIDIOC_ENUM_FMT), valid_ioctls); > if ((is_rx && (ops->vidioc_g_fmt_vid_cap || > ops->vidioc_g_fmt_vid_cap_mplane || > + ops->vidioc_g_ext_pix_fmt_vid_cap || > ops->vidioc_g_fmt_vid_overlay)) || > (is_tx && (ops->vidioc_g_fmt_vid_out || > ops->vidioc_g_fmt_vid_out_mplane || > - ops->vidioc_g_fmt_vid_out_overlay))) > + ops->vidioc_g_ext_pix_fmt_vid_out || > + ops->vidioc_g_fmt_vid_out_overlay))) { > set_bit(_IOC_NR(VIDIOC_G_FMT), valid_ioctls); > + set_bit(_IOC_NR(VIDIOC_G_EXT_PIX_FMT), valid_ioctls); Is it expected to allow the new ioctls for drivers which implement the old vid_out_overlay callbacks? > + } > if ((is_rx && (ops->vidioc_s_fmt_vid_cap || > ops->vidioc_s_fmt_vid_cap_mplane || > + ops->vidioc_s_ext_pix_fmt_vid_cap || > ops->vidioc_s_fmt_vid_overlay)) || > (is_tx && (ops->vidioc_s_fmt_vid_out || > ops->vidioc_s_fmt_vid_out_mplane || > - ops->vidioc_s_fmt_vid_out_overlay))) > + ops->vidioc_s_ext_pix_fmt_vid_out || > + ops->vidioc_s_fmt_vid_out_overlay))) { > set_bit(_IOC_NR(VIDIOC_S_FMT), valid_ioctls); > + set_bit(_IOC_NR(VIDIOC_S_EXT_PIX_FMT), valid_ioctls); > + } > if ((is_rx && (ops->vidioc_try_fmt_vid_cap || > ops->vidioc_try_fmt_vid_cap_mplane || > + ops->vidioc_try_ext_pix_fmt_vid_cap || > ops->vidioc_try_fmt_vid_overlay)) || > (is_tx && (ops->vidioc_try_fmt_vid_out || > ops->vidioc_try_fmt_vid_out_mplane || > - ops->vidioc_try_fmt_vid_out_overlay))) > + ops->vidioc_try_ext_pix_fmt_vid_out || > + ops->vidioc_try_fmt_vid_out_overlay))) { > set_bit(_IOC_NR(VIDIOC_TRY_FMT), valid_ioctls); > + set_bit(_IOC_NR(VIDIOC_TRY_EXT_PIX_FMT), valid_ioctls); > + } > SET_VALID_IOCTL(ops, VIDIOC_OVERLAY, vidioc_overlay); > SET_VALID_IOCTL(ops, VIDIOC_G_FBUF, vidioc_g_fbuf); > SET_VALID_IOCTL(ops, VIDIOC_S_FBUF, vidioc_s_fbuf); > @@ -682,8 +694,11 @@ static void determine_valid_ioctls(struct video_device *vdev) > /* touch specific ioctls */ > SET_VALID_IOCTL(ops, VIDIOC_ENUM_FMT, vidioc_enum_fmt_vid_cap); > SET_VALID_IOCTL(ops, VIDIOC_G_FMT, vidioc_g_fmt_vid_cap); > + SET_VALID_IOCTL(ops, VIDIOC_G_EXT_PIX_FMT, vidioc_g_fmt_vid_cap); > SET_VALID_IOCTL(ops, VIDIOC_S_FMT, vidioc_s_fmt_vid_cap); > + SET_VALID_IOCTL(ops, VIDIOC_S_EXT_PIX_FMT, vidioc_s_fmt_vid_cap); > SET_VALID_IOCTL(ops, VIDIOC_TRY_FMT, vidioc_try_fmt_vid_cap); > + SET_VALID_IOCTL(ops, VIDIOC_TRY_EXT_PIX_FMT, vidioc_try_fmt_vid_cap); > SET_VALID_IOCTL(ops, VIDIOC_ENUM_FRAMESIZES, vidioc_enum_framesizes); > SET_VALID_IOCTL(ops, VIDIOC_ENUM_FRAMEINTERVALS, vidioc_enum_frameintervals); > SET_VALID_IOCTL(ops, VIDIOC_ENUMINPUT, vidioc_enum_input); > diff --git a/drivers/media/v4l2-core/v4l2-ioctl.c b/drivers/media/v4l2-core/v4l2-ioctl.c > index a556880f225a5..14a0def50f8ea 100644 > --- a/drivers/media/v4l2-core/v4l2-ioctl.c > +++ b/drivers/media/v4l2-core/v4l2-ioctl.c > @@ -17,6 +17,8 @@ > > #include <linux/videodev2.h> > > +#include <drm/drm_fourcc.h> > + > #include <media/v4l2-common.h> > #include <media/v4l2-ioctl.h> > #include <media/v4l2-ctrls.h> > @@ -378,6 +380,27 @@ static void v4l_print_format(const void *arg, bool write_only) > } > } > > +static void v4l_print_ext_pix_format(const void *arg, bool write_only) > +{ > + const struct v4l2_ext_pix_format *pix = arg; > + unsigned int i; > + > + pr_cont("type=%s, width=%u, height=%u, format=%c%c%c%c, modifier %llx, field=%s, colorspace=%d, ycbcr_enc=%u, quantization=%u, xfer_func=%u\n", > + prt_names(pix->type, v4l2_type_names), > + pix->width, pix->height, > + (pix->pixelformat & 0xff), > + (pix->pixelformat >> 8) & 0xff, > + (pix->pixelformat >> 16) & 0xff, > + (pix->pixelformat >> 24) & 0xff, > + pix->modifier, prt_names(pix->field, v4l2_field_names), > + pix->colorspace, pix->ycbcr_enc, > + pix->quantization, pix->xfer_func); > + for (i = 0; i < VIDEO_MAX_PLANES && pix->plane_fmt[i].sizeimage; i++) This is going to print 8 lines every time. Maybe we could skip 0-sized planes or something? > + pr_debug("plane %u: bytesperline=%u sizeimage=%u\n", > + i, pix->plane_fmt[i].bytesperline, > + pix->plane_fmt[i].sizeimage); > +} > + > static void v4l_print_framebuffer(const void *arg, bool write_only) > { > const struct v4l2_framebuffer *p = arg; > @@ -964,11 +987,15 @@ static int check_fmt(struct file *file, enum v4l2_buf_type type) > switch (type) { > case V4L2_BUF_TYPE_VIDEO_CAPTURE: > if ((is_vid || is_tch) && is_rx && > - (ops->vidioc_g_fmt_vid_cap || ops->vidioc_g_fmt_vid_cap_mplane)) > + (ops->vidioc_g_fmt_vid_cap || > + ops->vidioc_g_ext_pix_fmt_vid_cap || > + ops->vidioc_g_fmt_vid_cap_mplane)) > return 0; > break; > case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: > - if ((is_vid || is_tch) && is_rx && ops->vidioc_g_fmt_vid_cap_mplane) > + if ((is_vid || is_tch) && is_rx && > + (ops->vidioc_g_fmt_vid_cap_mplane || > + ops->vidioc_g_ext_pix_fmt_vid_cap)) > return 0; > break; > case V4L2_BUF_TYPE_VIDEO_OVERLAY: > @@ -977,11 +1004,15 @@ static int check_fmt(struct file *file, enum v4l2_buf_type type) > break; > case V4L2_BUF_TYPE_VIDEO_OUTPUT: > if (is_vid && is_tx && > - (ops->vidioc_g_fmt_vid_out || ops->vidioc_g_fmt_vid_out_mplane)) > + (ops->vidioc_g_fmt_vid_out || > + ops->vidioc_g_ext_pix_fmt_vid_out || > + ops->vidioc_g_fmt_vid_out_mplane)) > return 0; > break; > case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: > - if (is_vid && is_tx && ops->vidioc_g_fmt_vid_out_mplane) > + if (is_vid && is_tx && > + (ops->vidioc_g_ext_pix_fmt_vid_out || > + ops->vidioc_g_fmt_vid_out_mplane)) > return 0; > break; > case V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY: > @@ -1061,6 +1092,134 @@ static void v4l_sanitize_format(struct v4l2_format *fmt) > sizeof(fmt->fmt.pix) - offset); > } > > +int v4l2_ext_pix_format_to_format(const struct v4l2_ext_pix_format *e, > + struct v4l2_format *f, bool mplane_cap, > + bool strict) > +{ > + const struct v4l2_plane_ext_pix_format *pe; > + struct v4l2_plane_pix_format *p; > + unsigned int i; > + > + memset(f, 0, sizeof(*f)); > + > + /* > + * Make sure no modifier is required before doing the > + * conversion. > + */ > + if (e->modifier && strict && Do we need the explicit check for e->modifier != 0 if we have to check for the 2 specific values below anyway? > + e->modifier != DRM_FORMAT_MOD_LINEAR && > + e->modifier != DRM_FORMAT_MOD_INVALID) > + return -EINVAL; > + > + if (!e->plane_fmt[0].sizeimage && strict) > + return -EINVAL; Why is this incorrect? > + > + if (e->plane_fmt[1].sizeimage && !mplane_cap && strict) > + return 0; Again this seems to be different from what we discussed before. In the ext API, the planes would mean color planes and would be all filled in with the right values. So for this conversion, if !mplane cap, then we should check if bytesperline of planes >= 1 match the format definition and use the sum of all planes sizeimage as the sizeimage of the legacy struct. > + > + if (!mplane_cap) { > + f->fmt.pix.width = e->width; > + f->fmt.pix.height = e->height; > + f->fmt.pix.pixelformat = e->pixelformat; > + f->fmt.pix.field = e->field; > + f->fmt.pix.colorspace = e->colorspace; > + f->fmt.pix.ycbcr_enc = e->ycbcr_enc; > + f->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > + f->fmt.pix.quantization = e->quantization; > + pe = &e->plane_fmt[0]; > + f->fmt.pix.bytesperline = pe->bytesperline; > + f->fmt.pix.sizeimage = pe->sizeimage; See above for how these two should be filled in. > + f->type = e->type; > + return 0; > + } > + > + f->fmt.pix_mp.width = e->width; > + f->fmt.pix_mp.height = e->height; > + f->fmt.pix_mp.pixelformat = e->pixelformat; > + f->fmt.pix_mp.field = e->field; > + f->fmt.pix_mp.colorspace = e->colorspace; > + f->fmt.pix_mp.ycbcr_enc = e->ycbcr_enc; > + f->fmt.pix_mp.quantization = e->quantization; > + if (e->type == V4L2_BUF_TYPE_VIDEO_CAPTURE) > + f->type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; > + else > + f->type = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE; > + > + for (i = 0; i < VIDEO_MAX_PLANES; i++) { > + pe = &e->plane_fmt[i]; > + p = &f->fmt.pix_mp.plane_fmt[i]; > + p->bytesperline = pe->bytesperline; > + p->sizeimage = pe->sizeimage; This is similar to the above, but the behavior depends on whether the pixelformat is an M or non-M variant. > + } > + > + return 0; > +} > +EXPORT_SYMBOL_GPL(v4l2_ext_pix_format_to_format); > + > +int v4l2_format_to_ext_pix_format(const struct v4l2_format *f, > + struct v4l2_ext_pix_format *e, bool strict) In other functions "ef" is used for the extended format. Let's make it consistent. > +{ > + const struct v4l2_plane_pix_format *p; > + struct v4l2_plane_ext_pix_format *pe; > + unsigned int i; > + > + memset(e, 0, sizeof(*e)); > + > + switch (f->type) { > + case V4L2_BUF_TYPE_VIDEO_CAPTURE: > + case V4L2_BUF_TYPE_VIDEO_OUTPUT: > + e->width = f->fmt.pix.width; > + e->height = f->fmt.pix.height; > + e->pixelformat = f->fmt.pix.pixelformat; > + e->field = f->fmt.pix.field; > + e->colorspace = f->fmt.pix.colorspace; > + if (f->fmt.pix.flags) > + pr_warn("Ignoring pixelformat flags 0x%x\n", > + f->fmt.pix.flags); Would it make sense to print something like video node name and/or function name to explain where this warning comes from? > + e->ycbcr_enc = f->fmt.pix.ycbcr_enc; > + e->quantization = f->fmt.pix.quantization; Missing xfer_func? > + e->plane_fmt[0].bytesperline = f->fmt.pix.bytesperline; > + e->plane_fmt[0].sizeimage = f->fmt.pix.sizeimage; This doesn't look right. In the ext API we expected the planes to describe color planes, which means that bytesperline needs to be computed for planes >= 1 and sizeimage replaced with per-plane sizes, according to the >pixelformat. > + e->type = f->type; > + break; > + > + case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: > + case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: > + if ((f->fmt.pix_mp.num_planes > VIDEO_MAX_PLANES || > + !f->fmt.pix_mp.num_planes) && strict) > + return -EINVAL; > + > + e->width = f->fmt.pix_mp.width; > + e->height = f->fmt.pix_mp.height; > + e->pixelformat = f->fmt.pix_mp.pixelformat; > + e->field = f->fmt.pix_mp.field; > + e->colorspace = f->fmt.pix_mp.colorspace; > + if (f->fmt.pix.flags) > + pr_warn("Ignoring pixelformat flags 0x%x\n", > + f->fmt.pix.flags); > + e->ycbcr_enc = f->fmt.pix_mp.ycbcr_enc; > + e->quantization = f->fmt.pix_mp.quantization; Missing xfer_func? > + if (f->type == V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE) > + e->type = V4L2_BUF_TYPE_VIDEO_CAPTURE; > + else > + e->type = V4L2_BUF_TYPE_VIDEO_OUTPUT; > + > + for (i = 0; i < VIDEO_MAX_PLANES; i++) { > + pe = &e->plane_fmt[i]; > + p = &f->fmt.pix_mp.plane_fmt[i]; > + pe->bytesperline = p->bytesperline; > + pe->sizeimage = p->sizeimage; > + } Same here. A blind copy is not enough. For non-M formats, the plane parameters need to be filled according to the pixelformat. > + break; > + > + default: > + return -EINVAL; > + } > + > + return 0; > +} > +EXPORT_SYMBOL_GPL(v4l2_format_to_ext_pix_format); > + > static int v4l_querycap(const struct v4l2_ioctl_ops *ops, > struct file *file, void *fh, void *arg) > { > @@ -1564,6 +1723,38 @@ static void v4l_pix_format_touch(struct v4l2_pix_format *p) > p->xfer_func = 0; > } > > +static int v4l_g_fmt_ext_pix(const struct v4l2_ioctl_ops *ops, > + struct file *file, void *fh, > + struct v4l2_format *f) > +{ > + struct v4l2_ext_pix_format ef; > + int ret; > + > + switch (f->type) { > + case V4L2_BUF_TYPE_VIDEO_CAPTURE: > + case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: > + ef.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; > + ret = ops->vidioc_g_ext_pix_fmt_vid_cap(file, fh, &ef); > + break; > + > + case V4L2_BUF_TYPE_VIDEO_OUTPUT: > + case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: > + ef.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; > + ret = ops->vidioc_g_ext_pix_fmt_vid_out(file, fh, &ef); > + break; > + > + default: > + return -EINVAL; > + } > + > + if (ret) > + return ret; > + > + return v4l2_ext_pix_format_to_format(&ef, f, > + V4L2_TYPE_IS_MULTIPLANAR(f->type), > + true); > +} > + > static int v4l_g_fmt(const struct v4l2_ioctl_ops *ops, > struct file *file, void *fh, void *arg) > { > @@ -1600,17 +1791,27 @@ static int v4l_g_fmt(const struct v4l2_ioctl_ops *ops, > > switch (p->type) { > case V4L2_BUF_TYPE_VIDEO_CAPTURE: > - if (unlikely(!ops->vidioc_g_fmt_vid_cap)) > - break; > - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > - ret = ops->vidioc_g_fmt_vid_cap(file, fh, arg); > - /* just in case the driver zeroed it again */ > - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > - if (vfd->vfl_type == VFL_TYPE_TOUCH) > - v4l_pix_format_touch(&p->fmt.pix); > - return ret; > + if (ops->vidioc_g_fmt_vid_cap) { > + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > + ret = ops->vidioc_g_fmt_vid_cap(file, fh, arg); > + /* just in case the driver zeroed it again */ > + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > + if (vfd->vfl_type == VFL_TYPE_TOUCH) > + v4l_pix_format_touch(&p->fmt.pix); > + return ret; > + } else if (ops->vidioc_g_ext_pix_fmt_vid_cap) { > + ret = v4l_g_fmt_ext_pix(ops, file, fh, p); > + if (vfd->vfl_type == VFL_TYPE_TOUCH) > + v4l_pix_format_touch(&p->fmt.pix); > + return ret; > + } > + break; > case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: > - return ops->vidioc_g_fmt_vid_cap_mplane(file, fh, arg); > + if (ops->vidioc_g_fmt_vid_cap_mplane) > + return ops->vidioc_g_fmt_vid_cap_mplane(file, fh, arg); > + else if (ops->vidioc_g_ext_pix_fmt_vid_cap) > + return v4l_g_fmt_ext_pix(ops, file, fh, p); > + break; > case V4L2_BUF_TYPE_VIDEO_OVERLAY: > return ops->vidioc_g_fmt_vid_overlay(file, fh, arg); > case V4L2_BUF_TYPE_VBI_CAPTURE: > @@ -1618,15 +1819,22 @@ static int v4l_g_fmt(const struct v4l2_ioctl_ops *ops, > case V4L2_BUF_TYPE_SLICED_VBI_CAPTURE: > return ops->vidioc_g_fmt_sliced_vbi_cap(file, fh, arg); > case V4L2_BUF_TYPE_VIDEO_OUTPUT: > - if (unlikely(!ops->vidioc_g_fmt_vid_out)) > - break; > - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > - ret = ops->vidioc_g_fmt_vid_out(file, fh, arg); > - /* just in case the driver zeroed it again */ > - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > - return ret; > + if (ops->vidioc_g_fmt_vid_out) { > + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > + ret = ops->vidioc_g_fmt_vid_out(file, fh, arg); > + /* just in case the driver zeroed it again */ > + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > + return ret; > + } else if (ops->vidioc_g_ext_pix_fmt_vid_out) { > + return v4l_g_fmt_ext_pix(ops, file, fh, p); > + } > + break; > case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: > - return ops->vidioc_g_fmt_vid_out_mplane(file, fh, arg); > + if (ops->vidioc_g_fmt_vid_out_mplane) > + return ops->vidioc_g_fmt_vid_out_mplane(file, fh, arg); > + else if (ops->vidioc_g_ext_pix_fmt_vid_out) > + return v4l_g_fmt_ext_pix(ops, file, fh, p); > + break; > case V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY: > return ops->vidioc_g_fmt_vid_out_overlay(file, fh, arg); > case V4L2_BUF_TYPE_VBI_OUTPUT: > @@ -1645,6 +1853,76 @@ static int v4l_g_fmt(const struct v4l2_ioctl_ops *ops, > return -EINVAL; > } > > +static int v4l_g_ext_pix_fmt(const struct v4l2_ioctl_ops *ops, > + struct file *file, void *fh, void *arg) > +{ > + struct v4l2_ext_pix_format *ef = arg; > + struct v4l2_format f = { > + .type = ef->type, > + }; > + int ret; > + > + ret = check_fmt(file, ef->type); > + if (ret) > + return ret; > + > + memset(ef, 0, sizeof(*ef)); > + ef->type = f.type; > + > + switch (f.type) { > + case V4L2_BUF_TYPE_VIDEO_CAPTURE: > + if (ops->vidioc_g_ext_pix_fmt_vid_cap) > + return ops->vidioc_g_ext_pix_fmt_vid_cap(file, fh, ef); > + break; > + case V4L2_BUF_TYPE_VIDEO_OUTPUT: > + if (ops->vidioc_g_ext_pix_fmt_vid_out) > + return ops->vidioc_g_ext_pix_fmt_vid_out(file, fh, ef); > + break; > + default: > + return -EINVAL; > + } > + > + ret = v4l_g_fmt(ops, file, fh, &f); > + if (ret) > + return ret; > + > + return v4l2_format_to_ext_pix_format(&f, ef, true); > +} > + > +static int v4l_s_fmt_ext_pix(const struct v4l2_ioctl_ops *ops, > + struct file *file, void *fh, > + struct v4l2_format *f) > +{ > + struct v4l2_ext_pix_format ef; > + int ret; > + > + ret = v4l2_format_to_ext_pix_format(f, &ef, false); > + if (ret) > + return ret; > + > + switch (f->type) { > + case V4L2_BUF_TYPE_VIDEO_CAPTURE: > + case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: > + ret = ops->vidioc_s_ext_pix_fmt_vid_cap(file, fh, &ef); > + break; > + > + case V4L2_BUF_TYPE_VIDEO_OUTPUT: > + case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: > + ret = ops->vidioc_s_ext_pix_fmt_vid_out(file, fh, &ef); > + break; > + > + default: > + return -EINVAL; > + } > + > + if (ret) > + return ret; > + > + return v4l2_ext_pix_format_to_format(&ef, f, > + V4L2_TYPE_IS_MULTIPLANAR(f->type), > + true); > +} > + > static int v4l_s_fmt(const struct v4l2_ioctl_ops *ops, > struct file *file, void *fh, void *arg) > { > @@ -1663,23 +1941,31 @@ static int v4l_s_fmt(const struct v4l2_ioctl_ops *ops, > > switch (p->type) { > case V4L2_BUF_TYPE_VIDEO_CAPTURE: > - if (unlikely(!ops->vidioc_s_fmt_vid_cap)) > + if (ops->vidioc_s_fmt_vid_cap) { > + CLEAR_AFTER_FIELD(p, fmt.pix); > + ret = ops->vidioc_s_fmt_vid_cap(file, fh, arg); > + /* just in case the driver zeroed it again */ > + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > + } else if (ops->vidioc_s_ext_pix_fmt_vid_cap) { > + ret = v4l_s_fmt_ext_pix(ops, file, fh, arg); > + } else { > break; > - CLEAR_AFTER_FIELD(p, fmt.pix); > - ret = ops->vidioc_s_fmt_vid_cap(file, fh, arg); > - /* just in case the driver zeroed it again */ > - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > + } > + > if (vfd->vfl_type == VFL_TYPE_TOUCH) > v4l_pix_format_touch(&p->fmt.pix); > return ret; > case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: > - if (unlikely(!ops->vidioc_s_fmt_vid_cap_mplane)) > - break; > - CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); > - for (i = 0; i < p->fmt.pix_mp.num_planes; i++) > - CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], > - bytesperline); > - return ops->vidioc_s_fmt_vid_cap_mplane(file, fh, arg); > + if (ops->vidioc_s_fmt_vid_cap_mplane) { > + CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); > + for (i = 0; i < p->fmt.pix_mp.num_planes; i++) > + CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], > + bytesperline); > + return ops->vidioc_s_fmt_vid_cap_mplane(file, fh, arg); > + } else if (ops->vidioc_s_ext_pix_fmt_vid_cap) { > + return v4l_s_fmt_ext_pix(ops, file, fh, arg); > + } > + break; > case V4L2_BUF_TYPE_VIDEO_OVERLAY: > if (unlikely(!ops->vidioc_s_fmt_vid_overlay)) > break; > @@ -1696,21 +1982,27 @@ static int v4l_s_fmt(const struct v4l2_ioctl_ops *ops, > CLEAR_AFTER_FIELD(p, fmt.sliced.io_size); > return ops->vidioc_s_fmt_sliced_vbi_cap(file, fh, arg); > case V4L2_BUF_TYPE_VIDEO_OUTPUT: > - if (unlikely(!ops->vidioc_s_fmt_vid_out)) > - break; > - CLEAR_AFTER_FIELD(p, fmt.pix); > - ret = ops->vidioc_s_fmt_vid_out(file, fh, arg); > - /* just in case the driver zeroed it again */ > - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > - return ret; > + if (ops->vidioc_s_fmt_vid_out) { > + CLEAR_AFTER_FIELD(p, fmt.pix); > + ret = ops->vidioc_s_fmt_vid_out(file, fh, arg); > + /* just in case the driver zeroed it again */ > + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > + return ret; > + } else if (ops->vidioc_s_ext_pix_fmt_vid_out) { > + return v4l_s_fmt_ext_pix(ops, file, fh, arg); > + } > + break; > case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: > - if (unlikely(!ops->vidioc_s_fmt_vid_out_mplane)) > - break; > - CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); > - for (i = 0; i < p->fmt.pix_mp.num_planes; i++) > - CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], > - bytesperline); > - return ops->vidioc_s_fmt_vid_out_mplane(file, fh, arg); > + if (ops->vidioc_s_fmt_vid_out_mplane) { > + CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); > + for (i = 0; i < p->fmt.pix_mp.num_planes; i++) > + CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], > + bytesperline); > + return ops->vidioc_s_fmt_vid_out_mplane(file, fh, arg); > + } else if (ops->vidioc_s_ext_pix_fmt_vid_out) { > + return v4l_s_fmt_ext_pix(ops, file, fh, arg); > + } > + break; > case V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY: > if (unlikely(!ops->vidioc_s_fmt_vid_out_overlay)) > break; > @@ -1750,6 +2042,82 @@ static int v4l_s_fmt(const struct v4l2_ioctl_ops *ops, > return -EINVAL; > } > > +static int v4l_s_ext_pix_fmt(const struct v4l2_ioctl_ops *ops, > + struct file *file, void *fh, void *arg) > +{ > + struct video_device *vfd = video_devdata(file); > + struct v4l2_ext_pix_format *ef = arg; > + struct v4l2_format f; > + int ret; > + > + ret = check_fmt(file, ef->type); > + if (ret) > + return ret; > + Should we zero the reserved fields as it's done with the current structs? > + switch (ef->type) { > + case V4L2_BUF_TYPE_VIDEO_CAPTURE: > + if (ops->vidioc_s_ext_pix_fmt_vid_cap) > + return ops->vidioc_s_ext_pix_fmt_vid_cap(file, fh, ef); > + break; > + case V4L2_BUF_TYPE_VIDEO_OUTPUT: > + if (ops->vidioc_s_ext_pix_fmt_vid_out) > + return ops->vidioc_s_ext_pix_fmt_vid_out(file, fh, ef); > + break; > + default: > + return -EINVAL; > + } > + > + ret = v4l2_ext_pix_format_to_format(ef, &f, > + vfd->device_caps & > + (V4L2_CAP_VIDEO_CAPTURE_MPLANE | > + V4L2_CAP_VIDEO_OUTPUT_MPLANE | > + V4L2_CAP_VIDEO_M2M_MPLANE), > + false); > + if (ret) > + return ret; > + > + ret = v4l_s_fmt(ops, file, fh, &f); > + if (ret) > + return ret; > + > + return v4l2_format_to_ext_pix_format(&f, ef, true); > +} > + > +static int v4l_try_fmt_ext_pix(const struct v4l2_ioctl_ops *ops, > + struct file *file, void *fh, > + struct v4l2_format *f) > +{ > + struct v4l2_ext_pix_format ef; > + int ret; > + > + ret = v4l2_format_to_ext_pix_format(f, &ef, false); > + if (ret) > + return ret; > + > + switch (f->type) { > + case V4L2_BUF_TYPE_VIDEO_CAPTURE: > + case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: > + ret = ops->vidioc_try_ext_pix_fmt_vid_cap(file, fh, &ef); > + break; > + > + case V4L2_BUF_TYPE_VIDEO_OUTPUT: > + case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: > + ret = ops->vidioc_try_ext_pix_fmt_vid_out(file, fh, &ef); > + break; > + > + default: > + return -EINVAL; > + } > + > + if (ret) > + return ret; > + > + return v4l2_ext_pix_format_to_format(&ef, f, > + V4L2_TYPE_IS_MULTIPLANAR(f->type), > + true); > +} > + > + > static int v4l_try_fmt(const struct v4l2_ioctl_ops *ops, > struct file *file, void *fh, void *arg) > { > @@ -1765,23 +2133,32 @@ static int v4l_try_fmt(const struct v4l2_ioctl_ops *ops, > > switch (p->type) { > case V4L2_BUF_TYPE_VIDEO_CAPTURE: > - if (unlikely(!ops->vidioc_try_fmt_vid_cap)) > - break; > - CLEAR_AFTER_FIELD(p, fmt.pix); > - ret = ops->vidioc_try_fmt_vid_cap(file, fh, arg); > - /* just in case the driver zeroed it again */ > - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > - if (vfd->vfl_type == VFL_TYPE_TOUCH) > - v4l_pix_format_touch(&p->fmt.pix); > - return ret; > + if (ops->vidioc_try_fmt_vid_cap) { > + CLEAR_AFTER_FIELD(p, fmt.pix); > + ret = ops->vidioc_try_fmt_vid_cap(file, fh, arg); > + /* just in case the driver zeroed it again */ > + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > + if (vfd->vfl_type == VFL_TYPE_TOUCH) > + v4l_pix_format_touch(&p->fmt.pix); > + return ret; > + } else if (ops->vidioc_try_ext_pix_fmt_vid_cap) { > + ret = v4l_try_fmt_ext_pix(ops, file, fh, p); > + if (vfd->vfl_type == VFL_TYPE_TOUCH) > + v4l_pix_format_touch(&p->fmt.pix); > + return ret; Should the 3 lines above be outside of the if/else block? > + } > + break; > case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: > - if (unlikely(!ops->vidioc_try_fmt_vid_cap_mplane)) > - break; > - CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); > - for (i = 0; i < p->fmt.pix_mp.num_planes; i++) > - CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], > - bytesperline); > - return ops->vidioc_try_fmt_vid_cap_mplane(file, fh, arg); > + if (ops->vidioc_try_fmt_vid_cap_mplane) { > + CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); > + for (i = 0; i < p->fmt.pix_mp.num_planes; i++) > + CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], > + bytesperline); > + return ops->vidioc_try_fmt_vid_cap_mplane(file, fh, arg); > + } else if (ops->vidioc_try_ext_pix_fmt_vid_cap) { > + return v4l_try_fmt_ext_pix(ops, file, fh, p); > + } > + break; > case V4L2_BUF_TYPE_VIDEO_OVERLAY: > if (unlikely(!ops->vidioc_try_fmt_vid_overlay)) > break; > @@ -1798,21 +2175,27 @@ static int v4l_try_fmt(const struct v4l2_ioctl_ops *ops, > CLEAR_AFTER_FIELD(p, fmt.sliced.io_size); > return ops->vidioc_try_fmt_sliced_vbi_cap(file, fh, arg); > case V4L2_BUF_TYPE_VIDEO_OUTPUT: > - if (unlikely(!ops->vidioc_try_fmt_vid_out)) > - break; > - CLEAR_AFTER_FIELD(p, fmt.pix); > - ret = ops->vidioc_try_fmt_vid_out(file, fh, arg); > - /* just in case the driver zeroed it again */ > - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > - return ret; > + if (ops->vidioc_try_fmt_vid_out) { > + CLEAR_AFTER_FIELD(p, fmt.pix); > + ret = ops->vidioc_try_fmt_vid_out(file, fh, arg); > + /* just in case the driver zeroed it again */ > + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; > + return ret; > + } else if (ops->vidioc_try_ext_pix_fmt_vid_cap) { > + return v4l_try_fmt_ext_pix(ops, file, fh, p); > + } > + break; > case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: > - if (unlikely(!ops->vidioc_try_fmt_vid_out_mplane)) > - break; > - CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); > - for (i = 0; i < p->fmt.pix_mp.num_planes; i++) > - CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], > - bytesperline); > - return ops->vidioc_try_fmt_vid_out_mplane(file, fh, arg); > + if (ops->vidioc_try_fmt_vid_out_mplane) { > + CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); > + for (i = 0; i < p->fmt.pix_mp.num_planes; i++) > + CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], > + bytesperline); > + return ops->vidioc_try_fmt_vid_out_mplane(file, fh, arg); > + } else if (ops->vidioc_try_ext_pix_fmt_vid_cap) { > + return v4l_try_fmt_ext_pix(ops, file, fh, p); > + } > + break; > case V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY: > if (unlikely(!ops->vidioc_try_fmt_vid_out_overlay)) > break; > @@ -1852,6 +2235,49 @@ static int v4l_try_fmt(const struct v4l2_ioctl_ops *ops, > return -EINVAL; > } > > +static int v4l_try_ext_pix_fmt(const struct v4l2_ioctl_ops *ops, > + struct file *file, void *fh, void *arg) > +{ > + struct video_device *vfd = video_devdata(file); > + struct v4l2_ext_pix_format *ef = arg; > + struct v4l2_format f; > + int ret; > + > + ret = check_fmt(file, ef->type); > + if (ret) > + return ret; Should we zero the reserved fields as it's done with the current structs? > + > + switch (ef->type) { > + case V4L2_BUF_TYPE_VIDEO_CAPTURE: > + if (ops->vidioc_try_ext_pix_fmt_vid_cap) > + return ops->vidioc_try_ext_pix_fmt_vid_cap(file, fh, > + ef); > + break; > + case V4L2_BUF_TYPE_VIDEO_OUTPUT: > + if (ops->vidioc_try_ext_pix_fmt_vid_out) > + return ops->vidioc_try_ext_pix_fmt_vid_out(file, fh, > + ef); > + break; > + default: > + return -EINVAL; > + } > + > + ret = v4l2_ext_pix_format_to_format(ef, &f, > + vfd->device_caps & > + (V4L2_CAP_VIDEO_CAPTURE_MPLANE | > + V4L2_CAP_VIDEO_OUTPUT_MPLANE | > + V4L2_CAP_VIDEO_M2M_MPLANE), > + false); > + if (ret) > + return ret; > + > + ret = v4l_try_fmt(ops, file, fh, &f); > + if (ret) > + return ret; > + > + return v4l2_format_to_ext_pix_format(&f, ef, true); > +} > + > static int v4l_streamon(const struct v4l2_ioctl_ops *ops, > struct file *file, void *fh, void *arg) > { > @@ -2771,7 +3197,9 @@ static const struct v4l2_ioctl_info v4l2_ioctls[] = { > IOCTL_INFO(VIDIOC_QUERYCAP, v4l_querycap, v4l_print_querycap, 0), > IOCTL_INFO(VIDIOC_ENUM_FMT, v4l_enum_fmt, v4l_print_fmtdesc, 0), > IOCTL_INFO(VIDIOC_G_FMT, v4l_g_fmt, v4l_print_format, 0), > + IOCTL_INFO(VIDIOC_G_EXT_PIX_FMT, v4l_g_ext_pix_fmt, v4l_print_ext_pix_format, 0), > IOCTL_INFO(VIDIOC_S_FMT, v4l_s_fmt, v4l_print_format, INFO_FL_PRIO), > + IOCTL_INFO(VIDIOC_S_EXT_PIX_FMT, v4l_s_ext_pix_fmt, v4l_print_ext_pix_format, INFO_FL_PRIO), > IOCTL_INFO(VIDIOC_REQBUFS, v4l_reqbufs, v4l_print_requestbuffers, INFO_FL_PRIO | INFO_FL_QUEUE), > IOCTL_INFO(VIDIOC_QUERYBUF, v4l_querybuf, v4l_print_buffer, INFO_FL_QUEUE | INFO_FL_CLEAR(v4l2_buffer, length)), > IOCTL_INFO(VIDIOC_G_FBUF, v4l_stub_g_fbuf, v4l_print_framebuffer, 0), > @@ -2818,6 +3246,7 @@ static const struct v4l2_ioctl_info v4l2_ioctls[] = { > IOCTL_INFO(VIDIOC_S_JPEGCOMP, v4l_stub_s_jpegcomp, v4l_print_jpegcompression, INFO_FL_PRIO), > IOCTL_INFO(VIDIOC_QUERYSTD, v4l_querystd, v4l_print_std, 0), > IOCTL_INFO(VIDIOC_TRY_FMT, v4l_try_fmt, v4l_print_format, 0), > + IOCTL_INFO(VIDIOC_TRY_EXT_PIX_FMT, v4l_try_ext_pix_fmt, v4l_print_ext_pix_format, 0), > IOCTL_INFO(VIDIOC_ENUMAUDIO, v4l_stub_enumaudio, v4l_print_audio, INFO_FL_CLEAR(v4l2_audio, index)), > IOCTL_INFO(VIDIOC_ENUMAUDOUT, v4l_stub_enumaudout, v4l_print_audioout, INFO_FL_CLEAR(v4l2_audioout, index)), > IOCTL_INFO(VIDIOC_G_PRIORITY, v4l_g_priority, v4l_print_u32, 0), > diff --git a/include/media/v4l2-ioctl.h b/include/media/v4l2-ioctl.h > index 86878fba332b0..8bbcb74d8ee31 100644 > --- a/include/media/v4l2-ioctl.h > +++ b/include/media/v4l2-ioctl.h > @@ -48,11 +48,17 @@ struct v4l2_fh; > * @vidioc_g_fmt_vid_cap: pointer to the function that implements > * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video capture > * in single plane mode > + * @vidioc_g_ext_pix_fmt_vid_cap: pointer to the function that implements > + * :ref:`VIDIOC_G_EXT_PIX_FMT <vidioc_g_ext_pix_fmt>` ioctl logic for video > + * capture > * @vidioc_g_fmt_vid_overlay: pointer to the function that implements > * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video overlay > * @vidioc_g_fmt_vid_out: pointer to the function that implements > * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video out > * in single plane mode > + * @vidioc_g_ext_pix_fmt_vid_out: pointer to the function that implements > + * :ref:`VIDIOC_G_EXT_PIX_FMT <vidioc_g_ext_pix_fmt>` ioctl logic for video > + * out > * @vidioc_g_fmt_vid_out_overlay: pointer to the function that implements > * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video overlay output > * @vidioc_g_fmt_vbi_cap: pointer to the function that implements > @@ -82,11 +88,16 @@ struct v4l2_fh; > * @vidioc_s_fmt_vid_cap: pointer to the function that implements > * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video capture > * in single plane mode > + * @vidioc_s_ext_pix_fmt_vid_cap: pointer to the function that implements > + * :ref:`VIDIOC_S_EXT_PIX_FMT <vidioc_g_ext_pix_fmt>` ioctl logic for video > + * capture > * @vidioc_s_fmt_vid_overlay: pointer to the function that implements > * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video overlay > * @vidioc_s_fmt_vid_out: pointer to the function that implements > * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video out > * in single plane mode > + * @vidioc_s_ext_pix_fmt_vid_out: pointer to the function that implements > + * :ref:`VIDIOC_S_EXT_PIX_FMT <vidioc_g_fmt>` ioctl logic for video out > * @vidioc_s_fmt_vid_out_overlay: pointer to the function that implements > * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video overlay output > * @vidioc_s_fmt_vbi_cap: pointer to the function that implements > @@ -116,11 +127,16 @@ struct v4l2_fh; > * @vidioc_try_fmt_vid_cap: pointer to the function that implements > * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video capture > * in single plane mode > + * @vidioc_try_ext_pix_fmt_vid_cap: pointer to the function that implements > + * :ref:`VIDIOC_TRY_EXT_PIX_FMT <vidioc_g_ext_pix_fmt>` ioctl logic for > + video capture > * @vidioc_try_fmt_vid_overlay: pointer to the function that implements > * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video overlay > * @vidioc_try_fmt_vid_out: pointer to the function that implements > * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video out > * in single plane mode > + * @vidioc_try_ext_pix_fmt_vid_out: pointer to the function that implements > + * :ref:`VIDIOC_TRY_EXT_PIX_FMT <vidioc_g_fmt>` ioctl logic for video out > * @vidioc_try_fmt_vid_out_overlay: pointer to the function that implements > * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video overlay > * output > @@ -319,10 +335,14 @@ struct v4l2_ioctl_ops { > /* VIDIOC_G_FMT handlers */ > int (*vidioc_g_fmt_vid_cap)(struct file *file, void *fh, > struct v4l2_format *f); > + int (*vidioc_g_ext_pix_fmt_vid_cap)(struct file *file, void *fh, > + struct v4l2_ext_pix_format *f); > int (*vidioc_g_fmt_vid_overlay)(struct file *file, void *fh, > struct v4l2_format *f); > int (*vidioc_g_fmt_vid_out)(struct file *file, void *fh, > struct v4l2_format *f); > + int (*vidioc_g_ext_pix_fmt_vid_out)(struct file *file, void *fh, > + struct v4l2_ext_pix_format *f); > int (*vidioc_g_fmt_vid_out_overlay)(struct file *file, void *fh, > struct v4l2_format *f); > int (*vidioc_g_fmt_vbi_cap)(struct file *file, void *fh, > @@ -349,10 +369,14 @@ struct v4l2_ioctl_ops { > /* VIDIOC_S_FMT handlers */ > int (*vidioc_s_fmt_vid_cap)(struct file *file, void *fh, > struct v4l2_format *f); > + int (*vidioc_s_ext_pix_fmt_vid_cap)(struct file *file, void *fh, > + struct v4l2_ext_pix_format *f); > int (*vidioc_s_fmt_vid_overlay)(struct file *file, void *fh, > struct v4l2_format *f); > int (*vidioc_s_fmt_vid_out)(struct file *file, void *fh, > struct v4l2_format *f); > + int (*vidioc_s_ext_pix_fmt_vid_out)(struct file *file, void *fh, > + struct v4l2_ext_pix_format *f); > int (*vidioc_s_fmt_vid_out_overlay)(struct file *file, void *fh, > struct v4l2_format *f); > int (*vidioc_s_fmt_vbi_cap)(struct file *file, void *fh, > @@ -379,10 +403,14 @@ struct v4l2_ioctl_ops { > /* VIDIOC_TRY_FMT handlers */ > int (*vidioc_try_fmt_vid_cap)(struct file *file, void *fh, > struct v4l2_format *f); > + int (*vidioc_try_ext_pix_fmt_vid_cap)(struct file *file, void *fh, > + struct v4l2_ext_pix_format *f); > int (*vidioc_try_fmt_vid_overlay)(struct file *file, void *fh, > struct v4l2_format *f); > int (*vidioc_try_fmt_vid_out)(struct file *file, void *fh, > struct v4l2_format *f); > + int (*vidioc_try_ext_pix_fmt_vid_out)(struct file *file, void *fh, > + struct v4l2_ext_pix_format *f); > int (*vidioc_try_fmt_vid_out_overlay)(struct file *file, void *fh, > struct v4l2_format *f); > int (*vidioc_try_fmt_vbi_cap)(struct file *file, void *fh, > @@ -724,6 +752,12 @@ long int video_usercopy(struct file *file, unsigned int cmd, > long int video_ioctl2(struct file *file, > unsigned int cmd, unsigned long int arg); > > +int v4l2_format_to_ext_pix_format(const struct v4l2_format *f, > + struct v4l2_ext_pix_format *e, bool strict); > +int v4l2_ext_pix_format_to_format(const struct v4l2_ext_pix_format *e, > + struct v4l2_format *f, > + bool mplane_cap, bool strict); > + > /* > * The user space interpretation of the 'v4l2_event' differs > * based on the 'time_t' definition on 32-bit architectures, so > diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h > index c7b70ff53bc1d..7123c6a4d9569 100644 > --- a/include/uapi/linux/videodev2.h > +++ b/include/uapi/linux/videodev2.h > @@ -2254,6 +2254,58 @@ struct v4l2_pix_format_mplane { > __u8 reserved[7]; > } __attribute__ ((packed)); > > +/** > + * struct v4l2_plane_ext_pix_format - additional, per-plane format definition > + * @sizeimage: maximum size in bytes required for data, for which > + * this plane will be used. > + * Should be set to zero for unused planes. > + * @bytesperline: distance in bytes between the leftmost pixels in two > + * adjacent lines > + * @reserved: extra space reserved for future fields, must be set to 0 > + */ > +struct v4l2_plane_ext_pix_format { nit: Maybe v4l2_ext_plane_pix_format, since the struct describes an ext variant of a plane_pix_format? > + __u32 sizeimage; > + __u32 bytesperline; > + __u32 reserved; > +}; Actually, this seems to be exactly the same as the existing v4l2_plane_pix_format, except actually having less reserved space. Could it make sense to just reuse the existing struct? Best regards, Tomasz
Hi Tomasz, On 10/2/20 4:49 PM, Tomasz Figa wrote: > Hi Helen, > > On Tue, Aug 04, 2020 at 04:29:33PM -0300, Helen Koike wrote: >> This is part of the multiplanar and singleplanar unification process. >> v4l2_ext_pix_format is supposed to work for both cases. >> >> We also add the concept of modifiers already employed in DRM to expose >> HW-specific formats (like tiled or compressed formats) and allow >> exchanging this information with the DRM subsystem in a consistent way. >> >> Note that only V4L2_BUF_TYPE_VIDEO_[OUTPUT,CAPTURE] are accepted in >> v4l2_ext_format, other types will be rejected if you use the >> {G,S,TRY}_EXT_PIX_FMT ioctls. >> >> New hooks have been added to v4l2_ioctl_ops to support those new ioctls >> in drivers, but, in the meantime, the core takes care of converting >> {S,G,TRY}_EXT_PIX_FMT requests into {S,G,TRY}_FMT so that old drivers can >> still work if the userspace app/lib uses the new ioctls. >> The conversion is also done the other around to allow userspace >> apps/libs using {S,G,TRY}_FMT to work with drivers implementing the >> _ext_ hooks. >> > > Thank you for the patch. Please see my comments inline. Thanks for reviewing. > >> Signed-off-by: Boris Brezillon <boris.brezillon@collabora.com> >> Signed-off-by: Helen Koike <helen.koike@collabora.com> >> --- >> Changes in v5: >> - change sizes and reorder fields to avoid holes in the struct and make >> it the same for 32 and 64 bits >> - removed __attribute__ ((packed)) from uapi structs >> - Fix doc warning from make htmldocs >> - Updated commit message with EXT_PIX prefix for the ioctls. >> >> Changes in v4: >> - Use v4l2_ext_pix_format directly in the ioctl, drop v4l2_ext_format, >> making V4L2_BUF_TYPE_VIDEO_[OUTPUT,CAPTURE] the only valid types. >> - Add reserved fields >> - Removed num_planes from struct v4l2_ext_pix_format >> - Removed flag field from struct v4l2_ext_pix_format, since the only >> defined value is V4L2_PIX_FMT_FLAG_PREMUL_ALPHA only used by vsp1, >> where we can use modifiers, or add it back later through the reserved >> bits. >> - In v4l2_ext_format_to_format(), check if modifier is != MOD_LINEAR && >> != MOD_INVALID >> - Fix type assignment in v4l_g_fmt_ext_pix() >> - Rebased on top of media/master (post 5.8-rc1) >> >> Changes in v3: >> - Rebased on top of media/master (post 5.4-rc1) >> >> Changes in v2: >> - Move the modifier in v4l2_ext_format (was formerly placed in >> v4l2_ext_plane) >> - Fix a few bugs in the converters and add a strict parameter to >> allow conversion of uninitialized/mis-initialized objects >> --- >> drivers/media/v4l2-core/v4l2-dev.c | 21 +- >> drivers/media/v4l2-core/v4l2-ioctl.c | 585 +++++++++++++++++++++++---- >> include/media/v4l2-ioctl.h | 34 ++ >> include/uapi/linux/videodev2.h | 56 +++ >> 4 files changed, 615 insertions(+), 81 deletions(-) >> >> diff --git a/drivers/media/v4l2-core/v4l2-dev.c b/drivers/media/v4l2-core/v4l2-dev.c >> index a593ea0598b55..e1829906bc086 100644 >> --- a/drivers/media/v4l2-core/v4l2-dev.c >> +++ b/drivers/media/v4l2-core/v4l2-dev.c >> @@ -607,25 +607,37 @@ static void determine_valid_ioctls(struct video_device *vdev) >> set_bit(_IOC_NR(VIDIOC_ENUM_FMT), valid_ioctls); >> if ((is_rx && (ops->vidioc_g_fmt_vid_cap || >> ops->vidioc_g_fmt_vid_cap_mplane || >> + ops->vidioc_g_ext_pix_fmt_vid_cap || >> ops->vidioc_g_fmt_vid_overlay)) || >> (is_tx && (ops->vidioc_g_fmt_vid_out || >> ops->vidioc_g_fmt_vid_out_mplane || >> - ops->vidioc_g_fmt_vid_out_overlay))) >> + ops->vidioc_g_ext_pix_fmt_vid_out || >> + ops->vidioc_g_fmt_vid_out_overlay))) { >> set_bit(_IOC_NR(VIDIOC_G_FMT), valid_ioctls); >> + set_bit(_IOC_NR(VIDIOC_G_EXT_PIX_FMT), valid_ioctls); > > Is it expected to allow the new ioctls for drivers which implement the old > vid_out_overlay callbacks? Thanks for noticing it, I don't think so, I'll update this in next version. > >> + } >> if ((is_rx && (ops->vidioc_s_fmt_vid_cap || >> ops->vidioc_s_fmt_vid_cap_mplane || >> + ops->vidioc_s_ext_pix_fmt_vid_cap || >> ops->vidioc_s_fmt_vid_overlay)) || >> (is_tx && (ops->vidioc_s_fmt_vid_out || >> ops->vidioc_s_fmt_vid_out_mplane || >> - ops->vidioc_s_fmt_vid_out_overlay))) >> + ops->vidioc_s_ext_pix_fmt_vid_out || >> + ops->vidioc_s_fmt_vid_out_overlay))) { >> set_bit(_IOC_NR(VIDIOC_S_FMT), valid_ioctls); >> + set_bit(_IOC_NR(VIDIOC_S_EXT_PIX_FMT), valid_ioctls); >> + } >> if ((is_rx && (ops->vidioc_try_fmt_vid_cap || >> ops->vidioc_try_fmt_vid_cap_mplane || >> + ops->vidioc_try_ext_pix_fmt_vid_cap || >> ops->vidioc_try_fmt_vid_overlay)) || >> (is_tx && (ops->vidioc_try_fmt_vid_out || >> ops->vidioc_try_fmt_vid_out_mplane || >> - ops->vidioc_try_fmt_vid_out_overlay))) >> + ops->vidioc_try_ext_pix_fmt_vid_out || >> + ops->vidioc_try_fmt_vid_out_overlay))) { >> set_bit(_IOC_NR(VIDIOC_TRY_FMT), valid_ioctls); >> + set_bit(_IOC_NR(VIDIOC_TRY_EXT_PIX_FMT), valid_ioctls); >> + } >> SET_VALID_IOCTL(ops, VIDIOC_OVERLAY, vidioc_overlay); >> SET_VALID_IOCTL(ops, VIDIOC_G_FBUF, vidioc_g_fbuf); >> SET_VALID_IOCTL(ops, VIDIOC_S_FBUF, vidioc_s_fbuf); >> @@ -682,8 +694,11 @@ static void determine_valid_ioctls(struct video_device *vdev) >> /* touch specific ioctls */ >> SET_VALID_IOCTL(ops, VIDIOC_ENUM_FMT, vidioc_enum_fmt_vid_cap); >> SET_VALID_IOCTL(ops, VIDIOC_G_FMT, vidioc_g_fmt_vid_cap); >> + SET_VALID_IOCTL(ops, VIDIOC_G_EXT_PIX_FMT, vidioc_g_fmt_vid_cap); >> SET_VALID_IOCTL(ops, VIDIOC_S_FMT, vidioc_s_fmt_vid_cap); >> + SET_VALID_IOCTL(ops, VIDIOC_S_EXT_PIX_FMT, vidioc_s_fmt_vid_cap); >> SET_VALID_IOCTL(ops, VIDIOC_TRY_FMT, vidioc_try_fmt_vid_cap); >> + SET_VALID_IOCTL(ops, VIDIOC_TRY_EXT_PIX_FMT, vidioc_try_fmt_vid_cap); >> SET_VALID_IOCTL(ops, VIDIOC_ENUM_FRAMESIZES, vidioc_enum_framesizes); >> SET_VALID_IOCTL(ops, VIDIOC_ENUM_FRAMEINTERVALS, vidioc_enum_frameintervals); >> SET_VALID_IOCTL(ops, VIDIOC_ENUMINPUT, vidioc_enum_input); >> diff --git a/drivers/media/v4l2-core/v4l2-ioctl.c b/drivers/media/v4l2-core/v4l2-ioctl.c >> index a556880f225a5..14a0def50f8ea 100644 >> --- a/drivers/media/v4l2-core/v4l2-ioctl.c >> +++ b/drivers/media/v4l2-core/v4l2-ioctl.c >> @@ -17,6 +17,8 @@ >> >> #include <linux/videodev2.h> >> >> +#include <drm/drm_fourcc.h> >> + >> #include <media/v4l2-common.h> >> #include <media/v4l2-ioctl.h> >> #include <media/v4l2-ctrls.h> >> @@ -378,6 +380,27 @@ static void v4l_print_format(const void *arg, bool write_only) >> } >> } >> >> +static void v4l_print_ext_pix_format(const void *arg, bool write_only) >> +{ >> + const struct v4l2_ext_pix_format *pix = arg; >> + unsigned int i; >> + >> + pr_cont("type=%s, width=%u, height=%u, format=%c%c%c%c, modifier %llx, field=%s, colorspace=%d, ycbcr_enc=%u, quantization=%u, xfer_func=%u\n", >> + prt_names(pix->type, v4l2_type_names), >> + pix->width, pix->height, >> + (pix->pixelformat & 0xff), >> + (pix->pixelformat >> 8) & 0xff, >> + (pix->pixelformat >> 16) & 0xff, >> + (pix->pixelformat >> 24) & 0xff, >> + pix->modifier, prt_names(pix->field, v4l2_field_names), >> + pix->colorspace, pix->ycbcr_enc, >> + pix->quantization, pix->xfer_func); >> + for (i = 0; i < VIDEO_MAX_PLANES && pix->plane_fmt[i].sizeimage; i++) > > This is going to print 8 lines every time. Maybe we could skip 0-sized > planes or something? I'm already checking pix->plane_fmt[i].sizeimage in the loop, it shouldn't print 8 lines every time. > >> + pr_debug("plane %u: bytesperline=%u sizeimage=%u\n", >> + i, pix->plane_fmt[i].bytesperline, >> + pix->plane_fmt[i].sizeimage); >> +} >> + >> static void v4l_print_framebuffer(const void *arg, bool write_only) >> { >> const struct v4l2_framebuffer *p = arg; >> @@ -964,11 +987,15 @@ static int check_fmt(struct file *file, enum v4l2_buf_type type) >> switch (type) { >> case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> if ((is_vid || is_tch) && is_rx && >> - (ops->vidioc_g_fmt_vid_cap || ops->vidioc_g_fmt_vid_cap_mplane)) >> + (ops->vidioc_g_fmt_vid_cap || >> + ops->vidioc_g_ext_pix_fmt_vid_cap || >> + ops->vidioc_g_fmt_vid_cap_mplane)) >> return 0; >> break; >> case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> - if ((is_vid || is_tch) && is_rx && ops->vidioc_g_fmt_vid_cap_mplane) >> + if ((is_vid || is_tch) && is_rx && >> + (ops->vidioc_g_fmt_vid_cap_mplane || >> + ops->vidioc_g_ext_pix_fmt_vid_cap)) >> return 0; >> break; >> case V4L2_BUF_TYPE_VIDEO_OVERLAY: >> @@ -977,11 +1004,15 @@ static int check_fmt(struct file *file, enum v4l2_buf_type type) >> break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> if (is_vid && is_tx && >> - (ops->vidioc_g_fmt_vid_out || ops->vidioc_g_fmt_vid_out_mplane)) >> + (ops->vidioc_g_fmt_vid_out || >> + ops->vidioc_g_ext_pix_fmt_vid_out || >> + ops->vidioc_g_fmt_vid_out_mplane)) >> return 0; >> break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> - if (is_vid && is_tx && ops->vidioc_g_fmt_vid_out_mplane) >> + if (is_vid && is_tx && >> + (ops->vidioc_g_ext_pix_fmt_vid_out || >> + ops->vidioc_g_fmt_vid_out_mplane)) >> return 0; >> break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY: >> @@ -1061,6 +1092,134 @@ static void v4l_sanitize_format(struct v4l2_format *fmt) >> sizeof(fmt->fmt.pix) - offset); >> } >> >> +int v4l2_ext_pix_format_to_format(const struct v4l2_ext_pix_format *e, >> + struct v4l2_format *f, bool mplane_cap, >> + bool strict) >> +{ >> + const struct v4l2_plane_ext_pix_format *pe; >> + struct v4l2_plane_pix_format *p; >> + unsigned int i; >> + >> + memset(f, 0, sizeof(*f)); >> + >> + /* >> + * Make sure no modifier is required before doing the >> + * conversion. >> + */ >> + if (e->modifier && strict && > > Do we need the explicit check for e->modifier != 0 if we have to check for > the 2 specific values below anyway? We don't, since DRM_FORMAT_MOD_LINEAR is zero. But I wanted to make it explicit we don't support modifiers in this conversion. But I can remove this check, no problem. > >> + e->modifier != DRM_FORMAT_MOD_LINEAR && >> + e->modifier != DRM_FORMAT_MOD_INVALID) >> + return -EINVAL; >> + >> + if (!e->plane_fmt[0].sizeimage && strict) >> + return -EINVAL; > > Why is this incorrect? !sizeimage for the first plane means that there are no planes in ef. strict is true if the result for the conversion should be returned to userspace and it is not some internal handling. So if there are no planes, we would return an incomplete v4l2_format struct to userspace. But this is not very clear, I'll improve this for the next version. > >> + >> + if (e->plane_fmt[1].sizeimage && !mplane_cap && strict) >> + return 0; > > Again this seems to be different from what we discussed before. In the ext > API, the planes would mean color planes and would be all filled in with the > right values. So for this conversion, if !mplane cap, then we should check > if bytesperline of planes >= 1 match the format definition and use the sum > of all planes sizeimage as the sizeimage of the legacy struct. Agreed, I'll update for next version. > >> + >> + if (!mplane_cap) { >> + f->fmt.pix.width = e->width; >> + f->fmt.pix.height = e->height; >> + f->fmt.pix.pixelformat = e->pixelformat; >> + f->fmt.pix.field = e->field; >> + f->fmt.pix.colorspace = e->colorspace; >> + f->fmt.pix.ycbcr_enc = e->ycbcr_enc; >> + f->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + f->fmt.pix.quantization = e->quantization; >> + pe = &e->plane_fmt[0]; >> + f->fmt.pix.bytesperline = pe->bytesperline; >> + f->fmt.pix.sizeimage = pe->sizeimage; > > See above for how these two should be filled in. Ack. > >> + f->type = e->type; >> + return 0; >> + } >> + >> + f->fmt.pix_mp.width = e->width; >> + f->fmt.pix_mp.height = e->height; >> + f->fmt.pix_mp.pixelformat = e->pixelformat; >> + f->fmt.pix_mp.field = e->field; >> + f->fmt.pix_mp.colorspace = e->colorspace; >> + f->fmt.pix_mp.ycbcr_enc = e->ycbcr_enc; >> + f->fmt.pix_mp.quantization = e->quantization; >> + if (e->type == V4L2_BUF_TYPE_VIDEO_CAPTURE) >> + f->type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; >> + else >> + f->type = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE; >> + >> + for (i = 0; i < VIDEO_MAX_PLANES; i++) { >> + pe = &e->plane_fmt[i]; >> + p = &f->fmt.pix_mp.plane_fmt[i]; >> + p->bytesperline = pe->bytesperline; >> + p->sizeimage = pe->sizeimage; > > This is similar to the above, but the behavior depends on whether the > pixelformat is an M or non-M variant. Ack. > >> + } >> + >> + return 0; >> +} >> +EXPORT_SYMBOL_GPL(v4l2_ext_pix_format_to_format); >> + >> +int v4l2_format_to_ext_pix_format(const struct v4l2_format *f, >> + struct v4l2_ext_pix_format *e, bool strict) > > In other functions "ef" is used for the extended format. Let's make it > consistent. Ack. > >> +{ >> + const struct v4l2_plane_pix_format *p; >> + struct v4l2_plane_ext_pix_format *pe; >> + unsigned int i; >> + >> + memset(e, 0, sizeof(*e)); >> + >> + switch (f->type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + e->width = f->fmt.pix.width; >> + e->height = f->fmt.pix.height; >> + e->pixelformat = f->fmt.pix.pixelformat; >> + e->field = f->fmt.pix.field; >> + e->colorspace = f->fmt.pix.colorspace; >> + if (f->fmt.pix.flags) >> + pr_warn("Ignoring pixelformat flags 0x%x\n", >> + f->fmt.pix.flags); > > Would it make sense to print something like video node name and/or function > name to explain where this warning comes from? I would need to update the function to receive this information, I can try but I'm not sure if it is worthy. > >> + e->ycbcr_enc = f->fmt.pix.ycbcr_enc; >> + e->quantization = f->fmt.pix.quantization; > > Missing xfer_func? Yes, thanks for catching this. > >> + e->plane_fmt[0].bytesperline = f->fmt.pix.bytesperline; >> + e->plane_fmt[0].sizeimage = f->fmt.pix.sizeimage; > > This doesn't look right. In the ext API we expected the planes to describe > color planes, which means that bytesperline needs to be computed for planes >> = 1 and sizeimage replaced with per-plane sizes, according to the >> pixelformat. Ack. Just to be clear, even if we are using a planar format that isn't a V4L2_PIX_FMT_*M variant, we should describe every plane separatly. For instance, if V4L2_PIX_FMT_YVU420 is being used, then f->fmt.pix.bytesperline will have data, and we need to calculate bytesperline for all 3 planes, so we'll fill out: f->plane_fmt[0].bytesperline = f->fmt.pix.bytesperline; f->plane_fmt[1].bytesperline = f->fmt.pix.bytesperline / hdiv; f->plane_fmt[2].bytesperline = f->fmt.pix.bytesperline / hdiv; I'll update this for the next version. > >> + e->type = f->type; >> + break; >> + >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> + if ((f->fmt.pix_mp.num_planes > VIDEO_MAX_PLANES || >> + !f->fmt.pix_mp.num_planes) && strict) >> + return -EINVAL; >> + >> + e->width = f->fmt.pix_mp.width; >> + e->height = f->fmt.pix_mp.height; >> + e->pixelformat = f->fmt.pix_mp.pixelformat; >> + e->field = f->fmt.pix_mp.field; >> + e->colorspace = f->fmt.pix_mp.colorspace; >> + if (f->fmt.pix.flags) >> + pr_warn("Ignoring pixelformat flags 0x%x\n", >> + f->fmt.pix.flags); >> + e->ycbcr_enc = f->fmt.pix_mp.ycbcr_enc; >> + e->quantization = f->fmt.pix_mp.quantization; > > Missing xfer_func? Yes, thanks for catching this. > >> + if (f->type == V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE) >> + e->type = V4L2_BUF_TYPE_VIDEO_CAPTURE; >> + else >> + e->type = V4L2_BUF_TYPE_VIDEO_OUTPUT; >> + >> + for (i = 0; i < VIDEO_MAX_PLANES; i++) { >> + pe = &e->plane_fmt[i]; >> + p = &f->fmt.pix_mp.plane_fmt[i]; >> + pe->bytesperline = p->bytesperline; >> + pe->sizeimage = p->sizeimage; >> + } > > Same here. A blind copy is not enough. For non-M formats, the plane > parameters need to be filled according to the pixelformat. Right, following the idea above, we need a different handling if we aren't using a M-variant of the pixelformat, and we also need to convert the pixelformat from the M-variant to non-M-variant. I'll also need to save that the original format was a M-variant or not, so I can convert it back as expected. I'll change this and submit for review. > >> + break; >> + >> + default: >> + return -EINVAL; >> + } >> + >> + return 0; >> +} >> +EXPORT_SYMBOL_GPL(v4l2_format_to_ext_pix_format); >> + >> static int v4l_querycap(const struct v4l2_ioctl_ops *ops, >> struct file *file, void *fh, void *arg) >> { >> @@ -1564,6 +1723,38 @@ static void v4l_pix_format_touch(struct v4l2_pix_format *p) >> p->xfer_func = 0; >> } >> >> +static int v4l_g_fmt_ext_pix(const struct v4l2_ioctl_ops *ops, >> + struct file *file, void *fh, >> + struct v4l2_format *f) >> +{ >> + struct v4l2_ext_pix_format ef; >> + int ret; >> + >> + switch (f->type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> + ef.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; >> + ret = ops->vidioc_g_ext_pix_fmt_vid_cap(file, fh, &ef); >> + break; >> + >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> + ef.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; >> + ret = ops->vidioc_g_ext_pix_fmt_vid_out(file, fh, &ef); >> + break; >> + >> + default: >> + return -EINVAL; >> + } >> + >> + if (ret) >> + return ret; >> + >> + return v4l2_ext_pix_format_to_format(&ef, f, >> + V4L2_TYPE_IS_MULTIPLANAR(f->type), >> + true); >> +} >> + >> static int v4l_g_fmt(const struct v4l2_ioctl_ops *ops, >> struct file *file, void *fh, void *arg) >> { >> @@ -1600,17 +1791,27 @@ static int v4l_g_fmt(const struct v4l2_ioctl_ops *ops, >> >> switch (p->type) { >> case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> - if (unlikely(!ops->vidioc_g_fmt_vid_cap)) >> - break; >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - ret = ops->vidioc_g_fmt_vid_cap(file, fh, arg); >> - /* just in case the driver zeroed it again */ >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - if (vfd->vfl_type == VFL_TYPE_TOUCH) >> - v4l_pix_format_touch(&p->fmt.pix); >> - return ret; >> + if (ops->vidioc_g_fmt_vid_cap) { >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + ret = ops->vidioc_g_fmt_vid_cap(file, fh, arg); >> + /* just in case the driver zeroed it again */ >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + if (vfd->vfl_type == VFL_TYPE_TOUCH) >> + v4l_pix_format_touch(&p->fmt.pix); >> + return ret; >> + } else if (ops->vidioc_g_ext_pix_fmt_vid_cap) { >> + ret = v4l_g_fmt_ext_pix(ops, file, fh, p); >> + if (vfd->vfl_type == VFL_TYPE_TOUCH) >> + v4l_pix_format_touch(&p->fmt.pix); >> + return ret; >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> - return ops->vidioc_g_fmt_vid_cap_mplane(file, fh, arg); >> + if (ops->vidioc_g_fmt_vid_cap_mplane) >> + return ops->vidioc_g_fmt_vid_cap_mplane(file, fh, arg); >> + else if (ops->vidioc_g_ext_pix_fmt_vid_cap) >> + return v4l_g_fmt_ext_pix(ops, file, fh, p); >> + break; >> case V4L2_BUF_TYPE_VIDEO_OVERLAY: >> return ops->vidioc_g_fmt_vid_overlay(file, fh, arg); >> case V4L2_BUF_TYPE_VBI_CAPTURE: >> @@ -1618,15 +1819,22 @@ static int v4l_g_fmt(const struct v4l2_ioctl_ops *ops, >> case V4L2_BUF_TYPE_SLICED_VBI_CAPTURE: >> return ops->vidioc_g_fmt_sliced_vbi_cap(file, fh, arg); >> case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> - if (unlikely(!ops->vidioc_g_fmt_vid_out)) >> - break; >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - ret = ops->vidioc_g_fmt_vid_out(file, fh, arg); >> - /* just in case the driver zeroed it again */ >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - return ret; >> + if (ops->vidioc_g_fmt_vid_out) { >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + ret = ops->vidioc_g_fmt_vid_out(file, fh, arg); >> + /* just in case the driver zeroed it again */ >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + return ret; >> + } else if (ops->vidioc_g_ext_pix_fmt_vid_out) { >> + return v4l_g_fmt_ext_pix(ops, file, fh, p); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> - return ops->vidioc_g_fmt_vid_out_mplane(file, fh, arg); >> + if (ops->vidioc_g_fmt_vid_out_mplane) >> + return ops->vidioc_g_fmt_vid_out_mplane(file, fh, arg); >> + else if (ops->vidioc_g_ext_pix_fmt_vid_out) >> + return v4l_g_fmt_ext_pix(ops, file, fh, p); >> + break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY: >> return ops->vidioc_g_fmt_vid_out_overlay(file, fh, arg); >> case V4L2_BUF_TYPE_VBI_OUTPUT: >> @@ -1645,6 +1853,76 @@ static int v4l_g_fmt(const struct v4l2_ioctl_ops *ops, >> return -EINVAL; >> } >> >> +static int v4l_g_ext_pix_fmt(const struct v4l2_ioctl_ops *ops, >> + struct file *file, void *fh, void *arg) >> +{ >> + struct v4l2_ext_pix_format *ef = arg; >> + struct v4l2_format f = { >> + .type = ef->type, >> + }; >> + int ret; >> + >> + ret = check_fmt(file, ef->type); >> + if (ret) >> + return ret; >> + >> + memset(ef, 0, sizeof(*ef)); >> + ef->type = f.type; >> + >> + switch (f.type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + if (ops->vidioc_g_ext_pix_fmt_vid_cap) >> + return ops->vidioc_g_ext_pix_fmt_vid_cap(file, fh, ef); >> + break; >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + if (ops->vidioc_g_ext_pix_fmt_vid_out) >> + return ops->vidioc_g_ext_pix_fmt_vid_out(file, fh, ef); >> + break; >> + default: >> + return -EINVAL; >> + } >> + >> + ret = v4l_g_fmt(ops, file, fh, &f); >> + if (ret) >> + return ret; >> + >> + return v4l2_format_to_ext_pix_format(&f, ef, true); >> +} >> + >> +static int v4l_s_fmt_ext_pix(const struct v4l2_ioctl_ops *ops, >> + struct file *file, void *fh, >> + struct v4l2_format *f) >> +{ >> + struct v4l2_ext_pix_format ef; >> + int ret; >> + >> + ret = v4l2_format_to_ext_pix_format(f, &ef, false); >> + if (ret) >> + return ret; >> + >> + switch (f->type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> + ret = ops->vidioc_s_ext_pix_fmt_vid_cap(file, fh, &ef); >> + break; >> + >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> + ret = ops->vidioc_s_ext_pix_fmt_vid_out(file, fh, &ef); >> + break; >> + >> + default: >> + return -EINVAL; >> + } >> + >> + if (ret) >> + return ret; >> + >> + return v4l2_ext_pix_format_to_format(&ef, f, >> + V4L2_TYPE_IS_MULTIPLANAR(f->type), >> + true); >> +} >> + >> static int v4l_s_fmt(const struct v4l2_ioctl_ops *ops, >> struct file *file, void *fh, void *arg) >> { >> @@ -1663,23 +1941,31 @@ static int v4l_s_fmt(const struct v4l2_ioctl_ops *ops, >> >> switch (p->type) { >> case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> - if (unlikely(!ops->vidioc_s_fmt_vid_cap)) >> + if (ops->vidioc_s_fmt_vid_cap) { >> + CLEAR_AFTER_FIELD(p, fmt.pix); >> + ret = ops->vidioc_s_fmt_vid_cap(file, fh, arg); >> + /* just in case the driver zeroed it again */ >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + } else if (ops->vidioc_s_ext_pix_fmt_vid_cap) { >> + ret = v4l_s_fmt_ext_pix(ops, file, fh, arg); >> + } else { >> break; >> - CLEAR_AFTER_FIELD(p, fmt.pix); >> - ret = ops->vidioc_s_fmt_vid_cap(file, fh, arg); >> - /* just in case the driver zeroed it again */ >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + } >> + >> if (vfd->vfl_type == VFL_TYPE_TOUCH) >> v4l_pix_format_touch(&p->fmt.pix); >> return ret; >> case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> - if (unlikely(!ops->vidioc_s_fmt_vid_cap_mplane)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> - for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> - CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> - bytesperline); >> - return ops->vidioc_s_fmt_vid_cap_mplane(file, fh, arg); >> + if (ops->vidioc_s_fmt_vid_cap_mplane) { >> + CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> + for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> + CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> + bytesperline); >> + return ops->vidioc_s_fmt_vid_cap_mplane(file, fh, arg); >> + } else if (ops->vidioc_s_ext_pix_fmt_vid_cap) { >> + return v4l_s_fmt_ext_pix(ops, file, fh, arg); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OVERLAY: >> if (unlikely(!ops->vidioc_s_fmt_vid_overlay)) >> break; >> @@ -1696,21 +1982,27 @@ static int v4l_s_fmt(const struct v4l2_ioctl_ops *ops, >> CLEAR_AFTER_FIELD(p, fmt.sliced.io_size); >> return ops->vidioc_s_fmt_sliced_vbi_cap(file, fh, arg); >> case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> - if (unlikely(!ops->vidioc_s_fmt_vid_out)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix); >> - ret = ops->vidioc_s_fmt_vid_out(file, fh, arg); >> - /* just in case the driver zeroed it again */ >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - return ret; >> + if (ops->vidioc_s_fmt_vid_out) { >> + CLEAR_AFTER_FIELD(p, fmt.pix); >> + ret = ops->vidioc_s_fmt_vid_out(file, fh, arg); >> + /* just in case the driver zeroed it again */ >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + return ret; >> + } else if (ops->vidioc_s_ext_pix_fmt_vid_out) { >> + return v4l_s_fmt_ext_pix(ops, file, fh, arg); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> - if (unlikely(!ops->vidioc_s_fmt_vid_out_mplane)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> - for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> - CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> - bytesperline); >> - return ops->vidioc_s_fmt_vid_out_mplane(file, fh, arg); >> + if (ops->vidioc_s_fmt_vid_out_mplane) { >> + CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> + for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> + CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> + bytesperline); >> + return ops->vidioc_s_fmt_vid_out_mplane(file, fh, arg); >> + } else if (ops->vidioc_s_ext_pix_fmt_vid_out) { >> + return v4l_s_fmt_ext_pix(ops, file, fh, arg); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY: >> if (unlikely(!ops->vidioc_s_fmt_vid_out_overlay)) >> break; >> @@ -1750,6 +2042,82 @@ static int v4l_s_fmt(const struct v4l2_ioctl_ops *ops, >> return -EINVAL; >> } >> >> +static int v4l_s_ext_pix_fmt(const struct v4l2_ioctl_ops *ops, >> + struct file *file, void *fh, void *arg) >> +{ >> + struct video_device *vfd = video_devdata(file); >> + struct v4l2_ext_pix_format *ef = arg; >> + struct v4l2_format f; >> + int ret; >> + >> + ret = check_fmt(file, ef->type); >> + if (ret) >> + return ret; >> + > > Should we zero the reserved fields as it's done with the current structs? Yes, I'll update this. > >> + switch (ef->type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + if (ops->vidioc_s_ext_pix_fmt_vid_cap) >> + return ops->vidioc_s_ext_pix_fmt_vid_cap(file, fh, ef); >> + break; >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + if (ops->vidioc_s_ext_pix_fmt_vid_out) >> + return ops->vidioc_s_ext_pix_fmt_vid_out(file, fh, ef); >> + break; >> + default: >> + return -EINVAL; >> + } >> + >> + ret = v4l2_ext_pix_format_to_format(ef, &f, >> + vfd->device_caps & >> + (V4L2_CAP_VIDEO_CAPTURE_MPLANE | >> + V4L2_CAP_VIDEO_OUTPUT_MPLANE | >> + V4L2_CAP_VIDEO_M2M_MPLANE), >> + false); >> + if (ret) >> + return ret; >> + >> + ret = v4l_s_fmt(ops, file, fh, &f); >> + if (ret) >> + return ret; >> + >> + return v4l2_format_to_ext_pix_format(&f, ef, true); >> +} >> + >> +static int v4l_try_fmt_ext_pix(const struct v4l2_ioctl_ops *ops, >> + struct file *file, void *fh, >> + struct v4l2_format *f) >> +{ >> + struct v4l2_ext_pix_format ef; >> + int ret; >> + >> + ret = v4l2_format_to_ext_pix_format(f, &ef, false); >> + if (ret) >> + return ret; >> + >> + switch (f->type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> + ret = ops->vidioc_try_ext_pix_fmt_vid_cap(file, fh, &ef); >> + break; >> + >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> + ret = ops->vidioc_try_ext_pix_fmt_vid_out(file, fh, &ef); >> + break; >> + >> + default: >> + return -EINVAL; >> + } >> + >> + if (ret) >> + return ret; >> + >> + return v4l2_ext_pix_format_to_format(&ef, f, >> + V4L2_TYPE_IS_MULTIPLANAR(f->type), >> + true); >> +} >> + >> + >> static int v4l_try_fmt(const struct v4l2_ioctl_ops *ops, >> struct file *file, void *fh, void *arg) >> { >> @@ -1765,23 +2133,32 @@ static int v4l_try_fmt(const struct v4l2_ioctl_ops *ops, >> >> switch (p->type) { >> case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> - if (unlikely(!ops->vidioc_try_fmt_vid_cap)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix); >> - ret = ops->vidioc_try_fmt_vid_cap(file, fh, arg); >> - /* just in case the driver zeroed it again */ >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - if (vfd->vfl_type == VFL_TYPE_TOUCH) >> - v4l_pix_format_touch(&p->fmt.pix); >> - return ret; >> + if (ops->vidioc_try_fmt_vid_cap) { >> + CLEAR_AFTER_FIELD(p, fmt.pix); >> + ret = ops->vidioc_try_fmt_vid_cap(file, fh, arg); >> + /* just in case the driver zeroed it again */ >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + if (vfd->vfl_type == VFL_TYPE_TOUCH) >> + v4l_pix_format_touch(&p->fmt.pix); >> + return ret; >> + } else if (ops->vidioc_try_ext_pix_fmt_vid_cap) { >> + ret = v4l_try_fmt_ext_pix(ops, file, fh, p); >> + if (vfd->vfl_type == VFL_TYPE_TOUCH) >> + v4l_pix_format_touch(&p->fmt.pix); >> + return ret; > > Should the 3 lines above be outside of the if/else block? I can move them out, I just need to add an else condition for the break below. I'll update this in the next version. > >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> - if (unlikely(!ops->vidioc_try_fmt_vid_cap_mplane)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> - for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> - CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> - bytesperline); >> - return ops->vidioc_try_fmt_vid_cap_mplane(file, fh, arg); >> + if (ops->vidioc_try_fmt_vid_cap_mplane) { >> + CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> + for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> + CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> + bytesperline); >> + return ops->vidioc_try_fmt_vid_cap_mplane(file, fh, arg); >> + } else if (ops->vidioc_try_ext_pix_fmt_vid_cap) { >> + return v4l_try_fmt_ext_pix(ops, file, fh, p); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OVERLAY: >> if (unlikely(!ops->vidioc_try_fmt_vid_overlay)) >> break; >> @@ -1798,21 +2175,27 @@ static int v4l_try_fmt(const struct v4l2_ioctl_ops *ops, >> CLEAR_AFTER_FIELD(p, fmt.sliced.io_size); >> return ops->vidioc_try_fmt_sliced_vbi_cap(file, fh, arg); >> case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> - if (unlikely(!ops->vidioc_try_fmt_vid_out)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix); >> - ret = ops->vidioc_try_fmt_vid_out(file, fh, arg); >> - /* just in case the driver zeroed it again */ >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - return ret; >> + if (ops->vidioc_try_fmt_vid_out) { >> + CLEAR_AFTER_FIELD(p, fmt.pix); >> + ret = ops->vidioc_try_fmt_vid_out(file, fh, arg); >> + /* just in case the driver zeroed it again */ >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + return ret; >> + } else if (ops->vidioc_try_ext_pix_fmt_vid_cap) { >> + return v4l_try_fmt_ext_pix(ops, file, fh, p); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> - if (unlikely(!ops->vidioc_try_fmt_vid_out_mplane)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> - for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> - CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> - bytesperline); >> - return ops->vidioc_try_fmt_vid_out_mplane(file, fh, arg); >> + if (ops->vidioc_try_fmt_vid_out_mplane) { >> + CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> + for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> + CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> + bytesperline); >> + return ops->vidioc_try_fmt_vid_out_mplane(file, fh, arg); >> + } else if (ops->vidioc_try_ext_pix_fmt_vid_cap) { >> + return v4l_try_fmt_ext_pix(ops, file, fh, p); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY: >> if (unlikely(!ops->vidioc_try_fmt_vid_out_overlay)) >> break; >> @@ -1852,6 +2235,49 @@ static int v4l_try_fmt(const struct v4l2_ioctl_ops *ops, >> return -EINVAL; >> } >> >> +static int v4l_try_ext_pix_fmt(const struct v4l2_ioctl_ops *ops, >> + struct file *file, void *fh, void *arg) >> +{ >> + struct video_device *vfd = video_devdata(file); >> + struct v4l2_ext_pix_format *ef = arg; >> + struct v4l2_format f; >> + int ret; >> + >> + ret = check_fmt(file, ef->type); >> + if (ret) >> + return ret; > > Should we zero the reserved fields as it's done with the current structs? Yes, I'll update this in the next version. > >> + >> + switch (ef->type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + if (ops->vidioc_try_ext_pix_fmt_vid_cap) >> + return ops->vidioc_try_ext_pix_fmt_vid_cap(file, fh, >> + ef); >> + break; >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + if (ops->vidioc_try_ext_pix_fmt_vid_out) >> + return ops->vidioc_try_ext_pix_fmt_vid_out(file, fh, >> + ef); >> + break; >> + default: >> + return -EINVAL; >> + } >> + >> + ret = v4l2_ext_pix_format_to_format(ef, &f, >> + vfd->device_caps & >> + (V4L2_CAP_VIDEO_CAPTURE_MPLANE | >> + V4L2_CAP_VIDEO_OUTPUT_MPLANE | >> + V4L2_CAP_VIDEO_M2M_MPLANE), >> + false); >> + if (ret) >> + return ret; >> + >> + ret = v4l_try_fmt(ops, file, fh, &f); >> + if (ret) >> + return ret; >> + >> + return v4l2_format_to_ext_pix_format(&f, ef, true); >> +} >> + >> static int v4l_streamon(const struct v4l2_ioctl_ops *ops, >> struct file *file, void *fh, void *arg) >> { >> @@ -2771,7 +3197,9 @@ static const struct v4l2_ioctl_info v4l2_ioctls[] = { >> IOCTL_INFO(VIDIOC_QUERYCAP, v4l_querycap, v4l_print_querycap, 0), >> IOCTL_INFO(VIDIOC_ENUM_FMT, v4l_enum_fmt, v4l_print_fmtdesc, 0), >> IOCTL_INFO(VIDIOC_G_FMT, v4l_g_fmt, v4l_print_format, 0), >> + IOCTL_INFO(VIDIOC_G_EXT_PIX_FMT, v4l_g_ext_pix_fmt, v4l_print_ext_pix_format, 0), >> IOCTL_INFO(VIDIOC_S_FMT, v4l_s_fmt, v4l_print_format, INFO_FL_PRIO), >> + IOCTL_INFO(VIDIOC_S_EXT_PIX_FMT, v4l_s_ext_pix_fmt, v4l_print_ext_pix_format, INFO_FL_PRIO), >> IOCTL_INFO(VIDIOC_REQBUFS, v4l_reqbufs, v4l_print_requestbuffers, INFO_FL_PRIO | INFO_FL_QUEUE), >> IOCTL_INFO(VIDIOC_QUERYBUF, v4l_querybuf, v4l_print_buffer, INFO_FL_QUEUE | INFO_FL_CLEAR(v4l2_buffer, length)), >> IOCTL_INFO(VIDIOC_G_FBUF, v4l_stub_g_fbuf, v4l_print_framebuffer, 0), >> @@ -2818,6 +3246,7 @@ static const struct v4l2_ioctl_info v4l2_ioctls[] = { >> IOCTL_INFO(VIDIOC_S_JPEGCOMP, v4l_stub_s_jpegcomp, v4l_print_jpegcompression, INFO_FL_PRIO), >> IOCTL_INFO(VIDIOC_QUERYSTD, v4l_querystd, v4l_print_std, 0), >> IOCTL_INFO(VIDIOC_TRY_FMT, v4l_try_fmt, v4l_print_format, 0), >> + IOCTL_INFO(VIDIOC_TRY_EXT_PIX_FMT, v4l_try_ext_pix_fmt, v4l_print_ext_pix_format, 0), >> IOCTL_INFO(VIDIOC_ENUMAUDIO, v4l_stub_enumaudio, v4l_print_audio, INFO_FL_CLEAR(v4l2_audio, index)), >> IOCTL_INFO(VIDIOC_ENUMAUDOUT, v4l_stub_enumaudout, v4l_print_audioout, INFO_FL_CLEAR(v4l2_audioout, index)), >> IOCTL_INFO(VIDIOC_G_PRIORITY, v4l_g_priority, v4l_print_u32, 0), >> diff --git a/include/media/v4l2-ioctl.h b/include/media/v4l2-ioctl.h >> index 86878fba332b0..8bbcb74d8ee31 100644 >> --- a/include/media/v4l2-ioctl.h >> +++ b/include/media/v4l2-ioctl.h >> @@ -48,11 +48,17 @@ struct v4l2_fh; >> * @vidioc_g_fmt_vid_cap: pointer to the function that implements >> * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video capture >> * in single plane mode >> + * @vidioc_g_ext_pix_fmt_vid_cap: pointer to the function that implements >> + * :ref:`VIDIOC_G_EXT_PIX_FMT <vidioc_g_ext_pix_fmt>` ioctl logic for video >> + * capture >> * @vidioc_g_fmt_vid_overlay: pointer to the function that implements >> * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video overlay >> * @vidioc_g_fmt_vid_out: pointer to the function that implements >> * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video out >> * in single plane mode >> + * @vidioc_g_ext_pix_fmt_vid_out: pointer to the function that implements >> + * :ref:`VIDIOC_G_EXT_PIX_FMT <vidioc_g_ext_pix_fmt>` ioctl logic for video >> + * out >> * @vidioc_g_fmt_vid_out_overlay: pointer to the function that implements >> * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video overlay output >> * @vidioc_g_fmt_vbi_cap: pointer to the function that implements >> @@ -82,11 +88,16 @@ struct v4l2_fh; >> * @vidioc_s_fmt_vid_cap: pointer to the function that implements >> * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video capture >> * in single plane mode >> + * @vidioc_s_ext_pix_fmt_vid_cap: pointer to the function that implements >> + * :ref:`VIDIOC_S_EXT_PIX_FMT <vidioc_g_ext_pix_fmt>` ioctl logic for video >> + * capture >> * @vidioc_s_fmt_vid_overlay: pointer to the function that implements >> * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video overlay >> * @vidioc_s_fmt_vid_out: pointer to the function that implements >> * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video out >> * in single plane mode >> + * @vidioc_s_ext_pix_fmt_vid_out: pointer to the function that implements >> + * :ref:`VIDIOC_S_EXT_PIX_FMT <vidioc_g_fmt>` ioctl logic for video out >> * @vidioc_s_fmt_vid_out_overlay: pointer to the function that implements >> * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video overlay output >> * @vidioc_s_fmt_vbi_cap: pointer to the function that implements >> @@ -116,11 +127,16 @@ struct v4l2_fh; >> * @vidioc_try_fmt_vid_cap: pointer to the function that implements >> * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video capture >> * in single plane mode >> + * @vidioc_try_ext_pix_fmt_vid_cap: pointer to the function that implements >> + * :ref:`VIDIOC_TRY_EXT_PIX_FMT <vidioc_g_ext_pix_fmt>` ioctl logic for >> + video capture >> * @vidioc_try_fmt_vid_overlay: pointer to the function that implements >> * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video overlay >> * @vidioc_try_fmt_vid_out: pointer to the function that implements >> * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video out >> * in single plane mode >> + * @vidioc_try_ext_pix_fmt_vid_out: pointer to the function that implements >> + * :ref:`VIDIOC_TRY_EXT_PIX_FMT <vidioc_g_fmt>` ioctl logic for video out >> * @vidioc_try_fmt_vid_out_overlay: pointer to the function that implements >> * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video overlay >> * output >> @@ -319,10 +335,14 @@ struct v4l2_ioctl_ops { >> /* VIDIOC_G_FMT handlers */ >> int (*vidioc_g_fmt_vid_cap)(struct file *file, void *fh, >> struct v4l2_format *f); >> + int (*vidioc_g_ext_pix_fmt_vid_cap)(struct file *file, void *fh, >> + struct v4l2_ext_pix_format *f); >> int (*vidioc_g_fmt_vid_overlay)(struct file *file, void *fh, >> struct v4l2_format *f); >> int (*vidioc_g_fmt_vid_out)(struct file *file, void *fh, >> struct v4l2_format *f); >> + int (*vidioc_g_ext_pix_fmt_vid_out)(struct file *file, void *fh, >> + struct v4l2_ext_pix_format *f); >> int (*vidioc_g_fmt_vid_out_overlay)(struct file *file, void *fh, >> struct v4l2_format *f); >> int (*vidioc_g_fmt_vbi_cap)(struct file *file, void *fh, >> @@ -349,10 +369,14 @@ struct v4l2_ioctl_ops { >> /* VIDIOC_S_FMT handlers */ >> int (*vidioc_s_fmt_vid_cap)(struct file *file, void *fh, >> struct v4l2_format *f); >> + int (*vidioc_s_ext_pix_fmt_vid_cap)(struct file *file, void *fh, >> + struct v4l2_ext_pix_format *f); >> int (*vidioc_s_fmt_vid_overlay)(struct file *file, void *fh, >> struct v4l2_format *f); >> int (*vidioc_s_fmt_vid_out)(struct file *file, void *fh, >> struct v4l2_format *f); >> + int (*vidioc_s_ext_pix_fmt_vid_out)(struct file *file, void *fh, >> + struct v4l2_ext_pix_format *f); >> int (*vidioc_s_fmt_vid_out_overlay)(struct file *file, void *fh, >> struct v4l2_format *f); >> int (*vidioc_s_fmt_vbi_cap)(struct file *file, void *fh, >> @@ -379,10 +403,14 @@ struct v4l2_ioctl_ops { >> /* VIDIOC_TRY_FMT handlers */ >> int (*vidioc_try_fmt_vid_cap)(struct file *file, void *fh, >> struct v4l2_format *f); >> + int (*vidioc_try_ext_pix_fmt_vid_cap)(struct file *file, void *fh, >> + struct v4l2_ext_pix_format *f); >> int (*vidioc_try_fmt_vid_overlay)(struct file *file, void *fh, >> struct v4l2_format *f); >> int (*vidioc_try_fmt_vid_out)(struct file *file, void *fh, >> struct v4l2_format *f); >> + int (*vidioc_try_ext_pix_fmt_vid_out)(struct file *file, void *fh, >> + struct v4l2_ext_pix_format *f); >> int (*vidioc_try_fmt_vid_out_overlay)(struct file *file, void *fh, >> struct v4l2_format *f); >> int (*vidioc_try_fmt_vbi_cap)(struct file *file, void *fh, >> @@ -724,6 +752,12 @@ long int video_usercopy(struct file *file, unsigned int cmd, >> long int video_ioctl2(struct file *file, >> unsigned int cmd, unsigned long int arg); >> >> +int v4l2_format_to_ext_pix_format(const struct v4l2_format *f, >> + struct v4l2_ext_pix_format *e, bool strict); >> +int v4l2_ext_pix_format_to_format(const struct v4l2_ext_pix_format *e, >> + struct v4l2_format *f, >> + bool mplane_cap, bool strict); >> + >> /* >> * The user space interpretation of the 'v4l2_event' differs >> * based on the 'time_t' definition on 32-bit architectures, so >> diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h >> index c7b70ff53bc1d..7123c6a4d9569 100644 >> --- a/include/uapi/linux/videodev2.h >> +++ b/include/uapi/linux/videodev2.h >> @@ -2254,6 +2254,58 @@ struct v4l2_pix_format_mplane { >> __u8 reserved[7]; >> } __attribute__ ((packed)); >> >> +/** >> + * struct v4l2_plane_ext_pix_format - additional, per-plane format definition >> + * @sizeimage: maximum size in bytes required for data, for which >> + * this plane will be used. >> + * Should be set to zero for unused planes. >> + * @bytesperline: distance in bytes between the leftmost pixels in two >> + * adjacent lines >> + * @reserved: extra space reserved for future fields, must be set to 0 >> + */ >> +struct v4l2_plane_ext_pix_format { > > nit: Maybe v4l2_ext_plane_pix_format, since the struct describes an > ext variant of a plane_pix_format? I'm removing this struct as mentioned below. > >> + __u32 sizeimage; >> + __u32 bytesperline; >> + __u32 reserved; >> +}; > > Actually, this seems to be exactly the same as the existing > v4l2_plane_pix_format, except actually having less reserved space. Could it > make sense to just reuse the existing struct? I think so, I'm removing this struct for the next version. Regards, Helen > > Best regards, > Tomasz >
On Sat, Nov 14, 2020 at 11:21:26AM -0300, Helen Koike wrote: > Hi Tomasz, > > On 10/2/20 4:49 PM, Tomasz Figa wrote: > > Hi Helen, > > > > On Tue, Aug 04, 2020 at 04:29:33PM -0300, Helen Koike wrote: [snip] > >> +static void v4l_print_ext_pix_format(const void *arg, bool write_only) > >> +{ > >> + const struct v4l2_ext_pix_format *pix = arg; > >> + unsigned int i; > >> + > >> + pr_cont("type=%s, width=%u, height=%u, format=%c%c%c%c, modifier %llx, field=%s, colorspace=%d, ycbcr_enc=%u, quantization=%u, xfer_func=%u\n", > >> + prt_names(pix->type, v4l2_type_names), > >> + pix->width, pix->height, > >> + (pix->pixelformat & 0xff), > >> + (pix->pixelformat >> 8) & 0xff, > >> + (pix->pixelformat >> 16) & 0xff, > >> + (pix->pixelformat >> 24) & 0xff, > >> + pix->modifier, prt_names(pix->field, v4l2_field_names), > >> + pix->colorspace, pix->ycbcr_enc, > >> + pix->quantization, pix->xfer_func); > >> + for (i = 0; i < VIDEO_MAX_PLANES && pix->plane_fmt[i].sizeimage; i++) > > > > This is going to print 8 lines every time. Maybe we could skip 0-sized > > planes or something? > > I'm already checking pix->plane_fmt[i].sizeimage in the loop, it shouldn't > print 8 lines every time. > Oops, how could I not notice it. Sorry for the noise. [snip] > >> +int v4l2_ext_pix_format_to_format(const struct v4l2_ext_pix_format *e, > >> + struct v4l2_format *f, bool mplane_cap, > >> + bool strict) > >> +{ > >> + const struct v4l2_plane_ext_pix_format *pe; > >> + struct v4l2_plane_pix_format *p; > >> + unsigned int i; > >> + > >> + memset(f, 0, sizeof(*f)); > >> + > >> + /* > >> + * Make sure no modifier is required before doing the > >> + * conversion. > >> + */ > >> + if (e->modifier && strict && > > > > Do we need the explicit check for e->modifier != 0 if we have to check for > > the 2 specific values below anyway? > > We don't, since DRM_FORMAT_MOD_LINEAR is zero. > > But I wanted to make it explicit we don't support modifiers in this conversion. > But I can remove this check, no problem. > Yes, please. I think the double checking is confusing for the reader. > > > >> + e->modifier != DRM_FORMAT_MOD_LINEAR && > >> + e->modifier != DRM_FORMAT_MOD_INVALID) > >> + return -EINVAL; > >> + > >> + if (!e->plane_fmt[0].sizeimage && strict) > >> + return -EINVAL; > > > > Why is this incorrect? > > !sizeimage for the first plane means that there are no planes in ef. > strict is true if the result for the conversion should be returned to userspace > and it is not some internal handling. > > So if there are no planes, we would return an incomplete v4l2_format struct > to userspace. > > But this is not very clear, I'll improve this for the next version. > So I can see 2 cases here: 1) Userspace gives ext struct and driver accepts legacy. In this case, the kernel needs to adjust the structure to be correct. -EINVAL is only valid if "The struct v4l2_format type field is invalid or the requested buffer type not supported." as per the current uAPI documentation. 2) Driver gives ext struct and userspace accepts legacy. If at this point we get a struct with no planes, that sounds like a driver bug, so rather than signaling -EINVAL to the userspace, we should probably WARN()? Or am I getting something wrong? :) [snip] > >> +{ > >> + const struct v4l2_plane_pix_format *p; > >> + struct v4l2_plane_ext_pix_format *pe; > >> + unsigned int i; > >> + > >> + memset(e, 0, sizeof(*e)); > >> + > >> + switch (f->type) { > >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: > >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: > >> + e->width = f->fmt.pix.width; > >> + e->height = f->fmt.pix.height; > >> + e->pixelformat = f->fmt.pix.pixelformat; > >> + e->field = f->fmt.pix.field; > >> + e->colorspace = f->fmt.pix.colorspace; > >> + if (f->fmt.pix.flags) > >> + pr_warn("Ignoring pixelformat flags 0x%x\n", > >> + f->fmt.pix.flags); > > > > Would it make sense to print something like video node name and/or function > > name to explain where this warning comes from? > > I would need to update the function to receive this information, I can try but > I'm not sure if it is worthy. > I don't have a strong opinion on this, so maybe let's see if others have any comments. > > > >> + e->ycbcr_enc = f->fmt.pix.ycbcr_enc; > >> + e->quantization = f->fmt.pix.quantization; > > > > Missing xfer_func? > > Yes, thanks for catching this. > > > > >> + e->plane_fmt[0].bytesperline = f->fmt.pix.bytesperline; > >> + e->plane_fmt[0].sizeimage = f->fmt.pix.sizeimage; > > > > This doesn't look right. In the ext API we expected the planes to describe > > color planes, which means that bytesperline needs to be computed for planes > >> = 1 and sizeimage replaced with per-plane sizes, according to the > >> pixelformat. > > Ack. > > Just to be clear, even if we are using a planar format that isn't a V4L2_PIX_FMT_*M > variant, we should describe every plane separatly. > > For instance, if V4L2_PIX_FMT_YVU420 is being used, then f->fmt.pix.bytesperline > will have data, and we need to calculate bytesperline for all 3 planes, so we'll fill > out: > > f->plane_fmt[0].bytesperline = f->fmt.pix.bytesperline; > f->plane_fmt[1].bytesperline = f->fmt.pix.bytesperline / hdiv; > f->plane_fmt[2].bytesperline = f->fmt.pix.bytesperline / hdiv; > > I'll update this for the next version. > Yes. This basically gives us a unified representation across all pixelformats and allows userspace to handle them in a uniform way, as opposed to current uAPI. [snip] > >> + if (f->type == V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE) > >> + e->type = V4L2_BUF_TYPE_VIDEO_CAPTURE; > >> + else > >> + e->type = V4L2_BUF_TYPE_VIDEO_OUTPUT; > >> + > >> + for (i = 0; i < VIDEO_MAX_PLANES; i++) { > >> + pe = &e->plane_fmt[i]; > >> + p = &f->fmt.pix_mp.plane_fmt[i]; > >> + pe->bytesperline = p->bytesperline; > >> + pe->sizeimage = p->sizeimage; > >> + } > > > > Same here. A blind copy is not enough. For non-M formats, the plane > > parameters need to be filled according to the pixelformat. > > > Right, following the idea above, we need a different handling if we > aren't using a M-variant of the pixelformat, and we also need to > convert the pixelformat from the M-variant to non-M-variant. > > I'll also need to save that the original format was a > M-variant or not, so I can convert it back as expected. I'm still reading the rest of the series, so it might be answered already, but did we decide to do anything about the pixelformat codes themselves? If both M and non-M variants would be allowed with the new API, then I guess there isn't anything to save, because the original format would be preserved? > > I'll change this and submit for review. > Cool, thanks. Best regards, Tomasz
Hi Tomasz, On 11/19/20 2:45 AM, Tomasz Figa wrote: > On Sat, Nov 14, 2020 at 11:21:26AM -0300, Helen Koike wrote: >> Hi Tomasz, >> >> On 10/2/20 4:49 PM, Tomasz Figa wrote: >>> Hi Helen, >>> >>> On Tue, Aug 04, 2020 at 04:29:33PM -0300, Helen Koike wrote: > [snip] >>>> +static void v4l_print_ext_pix_format(const void *arg, bool write_only) >>>> +{ >>>> + const struct v4l2_ext_pix_format *pix = arg; >>>> + unsigned int i; >>>> + >>>> + pr_cont("type=%s, width=%u, height=%u, format=%c%c%c%c, modifier %llx, field=%s, colorspace=%d, ycbcr_enc=%u, quantization=%u, xfer_func=%u\n", >>>> + prt_names(pix->type, v4l2_type_names), >>>> + pix->width, pix->height, >>>> + (pix->pixelformat & 0xff), >>>> + (pix->pixelformat >> 8) & 0xff, >>>> + (pix->pixelformat >> 16) & 0xff, >>>> + (pix->pixelformat >> 24) & 0xff, >>>> + pix->modifier, prt_names(pix->field, v4l2_field_names), >>>> + pix->colorspace, pix->ycbcr_enc, >>>> + pix->quantization, pix->xfer_func); >>>> + for (i = 0; i < VIDEO_MAX_PLANES && pix->plane_fmt[i].sizeimage; i++) >>> >>> This is going to print 8 lines every time. Maybe we could skip 0-sized >>> planes or something? >> >> I'm already checking pix->plane_fmt[i].sizeimage in the loop, it shouldn't >> print 8 lines every time. >> > > Oops, how could I not notice it. Sorry for the noise. > > [snip] >>>> +int v4l2_ext_pix_format_to_format(const struct v4l2_ext_pix_format *e, >>>> + struct v4l2_format *f, bool mplane_cap, >>>> + bool strict) >>>> +{ >>>> + const struct v4l2_plane_ext_pix_format *pe; >>>> + struct v4l2_plane_pix_format *p; >>>> + unsigned int i; >>>> + >>>> + memset(f, 0, sizeof(*f)); >>>> + >>>> + /* >>>> + * Make sure no modifier is required before doing the >>>> + * conversion. >>>> + */ >>>> + if (e->modifier && strict && >>> >>> Do we need the explicit check for e->modifier != 0 if we have to check for >>> the 2 specific values below anyway? >> >> We don't, since DRM_FORMAT_MOD_LINEAR is zero. >> >> But I wanted to make it explicit we don't support modifiers in this conversion. >> But I can remove this check, no problem. >> > > Yes, please. I think the double checking is confusing for the reader. ok. > >>> >>>> + e->modifier != DRM_FORMAT_MOD_LINEAR && >>>> + e->modifier != DRM_FORMAT_MOD_INVALID) >>>> + return -EINVAL; >>>> + >>>> + if (!e->plane_fmt[0].sizeimage && strict) >>>> + return -EINVAL; >>> >>> Why is this incorrect? >> >> !sizeimage for the first plane means that there are no planes in ef. >> strict is true if the result for the conversion should be returned to userspace >> and it is not some internal handling. >> >> So if there are no planes, we would return an incomplete v4l2_format struct >> to userspace. >> >> But this is not very clear, I'll improve this for the next version. >> > > So I can see 2 cases here: > > 1) Userspace gives ext struct and driver accepts legacy. > > In this case, the kernel needs to adjust the structure to be correct. > -EINVAL is only valid if > > "The struct v4l2_format type field is invalid or the requested buffer type not supported." > > as per the current uAPI documentation. > > 2) Driver gives ext struct and userspace accepts legacy. > > If at this point we get a struct with no planes, that sounds like a > driver bug, so rather than signaling -EINVAL to the userspace, we should > probably WARN()? > > Or am I getting something wrong? :) Make sense, I'll restructure this for the next version. > > [snip] >>>> +{ >>>> + const struct v4l2_plane_pix_format *p; >>>> + struct v4l2_plane_ext_pix_format *pe; >>>> + unsigned int i; >>>> + >>>> + memset(e, 0, sizeof(*e)); >>>> + >>>> + switch (f->type) { >>>> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >>>> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >>>> + e->width = f->fmt.pix.width; >>>> + e->height = f->fmt.pix.height; >>>> + e->pixelformat = f->fmt.pix.pixelformat; >>>> + e->field = f->fmt.pix.field; >>>> + e->colorspace = f->fmt.pix.colorspace; >>>> + if (f->fmt.pix.flags) >>>> + pr_warn("Ignoring pixelformat flags 0x%x\n", >>>> + f->fmt.pix.flags); >>> >>> Would it make sense to print something like video node name and/or function >>> name to explain where this warning comes from? >> >> I would need to update the function to receive this information, I can try but >> I'm not sure if it is worthy. >> > > I don't have a strong opinion on this, so maybe let's see if others have > any comments. > >>> >>>> + e->ycbcr_enc = f->fmt.pix.ycbcr_enc; >>>> + e->quantization = f->fmt.pix.quantization; >>> >>> Missing xfer_func? >> >> Yes, thanks for catching this. >> >>> >>>> + e->plane_fmt[0].bytesperline = f->fmt.pix.bytesperline; >>>> + e->plane_fmt[0].sizeimage = f->fmt.pix.sizeimage; >>> >>> This doesn't look right. In the ext API we expected the planes to describe >>> color planes, which means that bytesperline needs to be computed for planes >>>> = 1 and sizeimage replaced with per-plane sizes, according to the >>>> pixelformat. >> >> Ack. >> >> Just to be clear, even if we are using a planar format that isn't a V4L2_PIX_FMT_*M >> variant, we should describe every plane separatly. >> >> For instance, if V4L2_PIX_FMT_YVU420 is being used, then f->fmt.pix.bytesperline >> will have data, and we need to calculate bytesperline for all 3 planes, so we'll fill >> out: >> >> f->plane_fmt[0].bytesperline = f->fmt.pix.bytesperline; >> f->plane_fmt[1].bytesperline = f->fmt.pix.bytesperline / hdiv; >> f->plane_fmt[2].bytesperline = f->fmt.pix.bytesperline / hdiv; >> >> I'll update this for the next version. >> > > Yes. This basically gives us a unified representation across all > pixelformats and allows userspace to handle them in a uniform way, as > opposed to current uAPI. Right, I already updated this in my wip branch for next version. > > [snip] >>>> + if (f->type == V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE) >>>> + e->type = V4L2_BUF_TYPE_VIDEO_CAPTURE; >>>> + else >>>> + e->type = V4L2_BUF_TYPE_VIDEO_OUTPUT; >>>> + >>>> + for (i = 0; i < VIDEO_MAX_PLANES; i++) { >>>> + pe = &e->plane_fmt[i]; >>>> + p = &f->fmt.pix_mp.plane_fmt[i]; >>>> + pe->bytesperline = p->bytesperline; >>>> + pe->sizeimage = p->sizeimage; >>>> + } >>> >>> Same here. A blind copy is not enough. For non-M formats, the plane >>> parameters need to be filled according to the pixelformat. >> >> >> Right, following the idea above, we need a different handling if we >> aren't using a M-variant of the pixelformat, and we also need to >> convert the pixelformat from the M-variant to non-M-variant. >> >> I'll also need to save that the original format was a >> M-variant or not, so I can convert it back as expected. > > I'm still reading the rest of the series, so it might be answered > already, but did we decide to do anything about the pixelformat codes > themselves? If both M and non-M variants would be allowed with the new > API, then I guess there isn't anything to save, because the original > format would be preserved? I was working with the idea that M-variants wouldn't be allowed. But then, we have cases where non-M-variant don't exist, such as: V4L2_PIX_FMT_YVU422M V4L2_PIX_FMT_YVU444M (at least, I couldn't find non-M-variant equivalent for those) But actually, I don't think we formally decided this (and it seems easier to implement if both are allowed). Should we allow both variants in the Ext API ? Thanks Helen > >> >> I'll change this and submit for review. >> > > Cool, thanks. > > Best regards, > Tomasz >
On 8/4/20 4:29 PM, Helen Koike wrote: > Add documentation and update references in current documentation for the > Extended API. > > Signed-off-by: Helen Koike <helen.koike@collabora.com> > --- > Changes in v5: > - new patch > > .../userspace-api/media/v4l/buffer.rst | 5 + > .../userspace-api/media/v4l/common.rst | 1 + > .../userspace-api/media/v4l/dev-capture.rst | 5 + > .../userspace-api/media/v4l/dev-output.rst | 5 + > .../userspace-api/media/v4l/ext-api.rst | 107 +++++++++ > .../userspace-api/media/v4l/format.rst | 16 +- > .../userspace-api/media/v4l/user-func.rst | 5 + > .../media/v4l/vidioc-ext-create-bufs.rst | 95 ++++++++ > .../media/v4l/vidioc-ext-prepare-buf.rst | 62 ++++++ > .../media/v4l/vidioc-ext-qbuf.rst | 204 ++++++++++++++++++ > .../media/v4l/vidioc-ext-querybuf.rst | 79 +++++++ > .../media/v4l/vidioc-g-ext-pix-fmt.rst | 117 ++++++++++ > 12 files changed, 697 insertions(+), 4 deletions(-) > create mode 100644 Documentation/userspace-api/media/v4l/ext-api.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst > > diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst > index 57e752aaf414a..c832bedd64e4c 100644 > --- a/Documentation/userspace-api/media/v4l/buffer.rst > +++ b/Documentation/userspace-api/media/v4l/buffer.rst > @@ -27,6 +27,11 @@ 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. > > +.. note:: > + > + The :ref:`ext_api` version can also be used, and it is > + preferable when applicable. > + > 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 > diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst > index 7d81c58a13cd7..3430e0bdad667 100644 > --- a/Documentation/userspace-api/media/v4l/common.rst > +++ b/Documentation/userspace-api/media/v4l/common.rst > @@ -59,6 +59,7 @@ applicable to all devices. > ext-ctrls-detect > fourcc > format > + ext-api > planar-apis > selection-api > crop > diff --git a/Documentation/userspace-api/media/v4l/dev-capture.rst b/Documentation/userspace-api/media/v4l/dev-capture.rst > index 44d3094093ab6..5077639787d92 100644 > --- a/Documentation/userspace-api/media/v4l/dev-capture.rst > +++ b/Documentation/userspace-api/media/v4l/dev-capture.rst > @@ -102,6 +102,11 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC > requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. > :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. > > +.. note:: > + > + The :ref:`ext_api` version can also be used, and it is > + preferable when applicable. > + > > Reading Images > ============== > diff --git a/Documentation/userspace-api/media/v4l/dev-output.rst b/Documentation/userspace-api/media/v4l/dev-output.rst > index e4f2a1d8b0fc7..f8f40c708e49f 100644 > --- a/Documentation/userspace-api/media/v4l/dev-output.rst > +++ b/Documentation/userspace-api/media/v4l/dev-output.rst > @@ -99,6 +99,11 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC > requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. > :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. > > +.. note:: > + > + The :ref:`ext_api` version can also be used, and it is > + preferable when applicable. > + > > Writing Images > ============== > diff --git a/Documentation/userspace-api/media/v4l/ext-api.rst b/Documentation/userspace-api/media/v4l/ext-api.rst > new file mode 100644 > index 0000000000000..da2a82960d22f > --- /dev/null > +++ b/Documentation/userspace-api/media/v4l/ext-api.rst > @@ -0,0 +1,107 @@ > +.. Permission is granted to copy, distribute and/or modify this > +.. document under the terms of the GNU Free Documentation License, > +.. Version 1.1 or any later version published by the Free Software > +.. Foundation, with no Invariant Sections, no Front-Cover Texts > +.. and no Back-Cover Texts. A copy of the license is included at > +.. Documentation/userspace-api/media/fdl-appendix.rst. > +.. > +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > + > +.. _ext_api: > + > +************* > +Extendend API > +************* > + > +Introduction > +============ > + > +The Extended Format API was conceived to extend V4L2 capabilities and > +to simplify certain mechanisms. > +It unifies single- vs multi- planar handling, > +brings the concept of pixelformat + modifiers, allows planes to be placed > +in any offset inside a buffer and let userspace to change colorspace > +attributes if supported by the driver. > + > +Data format negotiation and buffer handling works very similar to the classical > +version, thus in this document we'll just mention the main differences. > + > +Data Format Negotiation > +======================= > + > +The API replaces the classical ioctls: > + > +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, > +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` > +(with :c:type:`v4l2_format` as the main parameter). > + > +By the extended versions: > + > +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>`, > +:ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>`, > +:ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` > +(with :c:type:`v4l2_ext_pix_format` as the main parameter). > + > +For CAPTURE and OUTPUT queues only. > + > +The ``type`` field of struct :c:type:`v4l2_ext_pix_format` only accepts > +``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, and it > +supports multiplanar format through a combination of ``pixelfomat`` and > +``modifier`` fields. > + > +Only the single-planar variants of the pixel formats are valid in the > +``pixelformat`` field. Just a correction, here I meant s/single-planar/non-M-variant. But this is under discussion, see patch 1/7. > +To support multi-planar, a modifier should be set in the ``modifier`` field to > +provide more information regarding the memory layout of pixels and number of > +planes. This is wrong too. Or we don't use the M-variant, or we say both variants are valid and equivalent. This is under discussion, see patch 1/7. I'll update in the next version. Regards, Helen > + > +The ``plane_fmt`` field is an array which holds information by plane using > +the :c:type:`v4l2_plane_ext_pix_format`. When this struct is filled, its > +``sizeimage`` field should be non-zero for all valid planes for a given > +``pixelformat`` + ``modifier`` combination, and zeroed for the invalid ones. > + > +Colospace attributes are not read-only as in the classical version, i.e, they > +can be set by application and drivers will adjust accordingly depending on what > +is supported by the underlying hardware. > + > +Buffers > +======= > + > +The API replaces the classical ioctls: > + > +:ref:`VIDIOC_CREATE_BUFS <VIDIOC_CREATE_BUFS>` > +(with :c:type:`v4l2_create_buffers` as the main parameter), > +:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, > +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_PREPARE_BUF <VIDIOC_PREPARE_BUF>` > +(with :c:type:`v4l2_buffer` as the main parameter) > + > +By the extended versions: > + > +:ref:`VIDIOC_EXT_CREATE_BUFS <VIDIOC_EXT_CREATE_BUFS>` > +(with :c:type:`v4l2_ext_create_buffers` as the main parameter), > +:ref:`VIDIOC_EXT_QUERYBUF <VIDIOC_EXT_QUERYBUF>`, > +:ref:`VIDIOC_EXT_QBUF <VIDIOC_EXT_QBUF>`, > +:ref:`VIDIOC_EXT_DQBUF <VIDIOC_EXT_QBUF>`, > +:ref:`VIDIOC_EXT_PREPARE_BUF <VIDIOC_EXT_PREPARE_BUF>` > +(with :c:type:`v4l2_ext_buffer` as the main parameter) > + > +The basic difference between :c:type:`v4l2_create_buffers` and > +:c:type:`v4l2_ext_create_buffers` is that the later have a > +:c:type:`v4l2_ext_pix_format` as the type of the ``format`` field. > + > +Comparing :c:type:`v4l2_ext_buffer` with :c:type:`v4l2_buffer`, in the > +extended version there is a unification of the single-/multi- planar handling > +through the ``planes`` field of type :c:type:`v4l2_ext_plane`. > + > +The :c:type:`v4l2_ext_plane also allows planes to be placed in a given offset > +inside a buffer. > +Planes can be placed in different locations inside the same buffer, or in > +different buffers. > + > + > +.. kernel-doc:: include/uapi/linux/videodev2.h > + :functions: v4l2_ext_plane > + > + > +.. kernel-doc:: include/uapi/linux/videodev2.h > + :functions: v4l2_ext_buffer > diff --git a/Documentation/userspace-api/media/v4l/format.rst b/Documentation/userspace-api/media/v4l/format.rst > index e47fc0505727c..b96d26f26793c 100644 > --- a/Documentation/userspace-api/media/v4l/format.rst > +++ b/Documentation/userspace-api/media/v4l/format.rst > @@ -28,13 +28,19 @@ format and the driver selects and reports the best the hardware can do > to satisfy the request. Of course applications can also just query the > current selection. > > -A single mechanism exists to negotiate all data formats using the > -aggregate struct :c:type:`v4l2_format` and the > +There are two mechanism to negociate data formats: > + > +The first one is using the aggregate struct :c:type:`v4l2_format` and the > :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and > :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the > :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine > what the hardware *could* do, without actually selecting a new data > -format. The data formats supported by the V4L2 API are covered in the > +format. > + > +The second is through the :ref:`ext_api`, please refer to its documentation > +for more information. > + > +The data formats supported by the V4L2 API are covered in the > respective device section in :ref:`devices`. For a closer look at > image formats see :ref:`pixfmt`. > > @@ -71,7 +77,9 @@ earlier versions of V4L2. Switching the logical stream or returning into > *may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. > > All drivers exchanging data with applications must support the > -:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the > +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl > +or the Extended respective versions (TODO: link). > +Implementation of the > :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. > > > diff --git a/Documentation/userspace-api/media/v4l/user-func.rst b/Documentation/userspace-api/media/v4l/user-func.rst > index bf77c842718e5..67b254812791c 100644 > --- a/Documentation/userspace-api/media/v4l/user-func.rst > +++ b/Documentation/userspace-api/media/v4l/user-func.rst > @@ -20,6 +20,7 @@ Function Reference > func-close > func-ioctl > vidioc-create-bufs > + vidioc-ext-create-bufs > vidioc-cropcap > vidioc-dbg-g-chip-info > vidioc-dbg-g-register > @@ -48,6 +49,7 @@ Function Reference > vidioc-g-ext-ctrls > vidioc-g-fbuf > vidioc-g-fmt > + vidioc-g-ext-pix-fmt > vidioc-g-frequency > vidioc-g-input > vidioc-g-jpegcomp > @@ -62,8 +64,11 @@ Function Reference > vidioc-log-status > vidioc-overlay > vidioc-prepare-buf > + vidioc-ext-prepare-buf > vidioc-qbuf > + vidioc-ext-qbuf > vidioc-querybuf > + vidioc-ext-querybuf > vidioc-querycap > vidioc-queryctrl > vidioc-query-dv-timings > diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst > new file mode 100644 > index 0000000000000..67f2c541e4d79 > --- /dev/null > +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst > @@ -0,0 +1,95 @@ > +.. Permission is granted to copy, distribute and/or modify this > +.. document under the terms of the GNU Free Documentation License, > +.. Version 1.1 or any later version published by the Free Software > +.. Foundation, with no Invariant Sections, no Front-Cover Texts > +.. and no Back-Cover Texts. A copy of the license is included at > +.. Documentation/userspace-api/media/fdl-appendix.rst. > +.. > +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > + > +.. _VIDIOC_EXT_CREATE_BUFS: > + > +**************************** > +ioctl VIDIOC_EXT_CREATE_BUFS > +**************************** > + > +Name > +==== > + > +VIDIOC_EXT_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O > + > + > +Synopsis > +======== > + > +.. c:function:: int ioctl( int fd, VIDIOC_EXT_CREATE_BUFS, struct v4l2_ext_create_buffers *argp ) > + :name: VIDIOC_EXT_CREATE_BUFS > + > + > +Arguments > +========= > + > +``fd`` > + File descriptor returned by :ref:`open() <func-open>`. > + > +``argp`` > + Pointer to struct :c:type:`v4l2_ext_create_buffers`. > + > + > +Description > +=========== > + > +This ioctl is used to create buffers for :ref:`memory mapped <mmap>` > +or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. > +This ioctl can be called multiple times to > +create buffers of different sizes. > + > +To allocate the device buffers applications must initialize the relevant > +fields of the struct :c:type:`v4l2_ext_create_buffers` structure. The > +``count`` field must be set to the number of requested buffers, the > +``memory`` field specifies the requested I/O method and the ``reserved`` > +array must be zeroed. > + > +The ``format`` field specifies the image format that the buffers must be > +able to handle. The application has to fill in this struct > +:c:type:`v4l2_format`. Usually this will be done using the > +:ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` or > +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctls to ensure that the > +requested format is supported by the driver. > +The driver may return an error if the size(s) are not supported by the > +hardware (usually because they are too small). > + > +The driver can create a memory buffer per plane, or a single memory buffer > +containing all the planes, with a minimum size according to the size > +defined by the ``format.plane_fmt[i].sizeimage`` field. > +Usually if the ``format.plane_fmt[i].sizeimage`` > +field is less than the minimum required for the given format, then an > +error will be returned since drivers will typically not allow this. If > +it is larger, then the value will be used as-is. In other words, the > +driver may reject the requested size, but if it is accepted the driver > +will use it unchanged. > + > +When the ioctl is called with a pointer to this structure the driver > +will attempt to allocate up to the requested number of buffers and store > +the actual number allocated and the starting index in the ``count`` and > +the ``index`` fields respectively. On return ``count`` can be smaller > +than the number requested. > + > + > +.. kernel-doc:: include/uapi/linux/videodev2.h > + :functions: v4l2_ext_create_buffers > + > + > +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 <gen-errors>` chapter. > + > +ENOMEM > + No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O. > + > +EINVAL > + The buffer type (``format.type`` field), requested I/O method > + (``memory``) or format (``format`` field) is not valid. > diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst > new file mode 100644 > index 0000000000000..88e4b57121254 > --- /dev/null > +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst > @@ -0,0 +1,62 @@ > +.. Permission is granted to copy, distribute and/or modify this > +.. document under the terms of the GNU Free Documentation License, > +.. Version 1.1 or any later version published by the Free Software > +.. Foundation, with no Invariant Sections, no Front-Cover Texts > +.. and no Back-Cover Texts. A copy of the license is included at > +.. Documentation/userspace-api/media/fdl-appendix.rst. > +.. > +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > + > +.. _VIDIOC_EXT_PREPARE_BUF: > + > +**************************** > +ioctl VIDIOC_EXT_PREPARE_BUF > +**************************** > + > +Name > +==== > + > +VIDIOC_EXT_PREPARE_BUF - Prepare a buffer for I/O > + > + > +Synopsis > +======== > + > +.. c:function:: int ioctl( int fd, VIDIOC_EXT_PREPARE_BUF, struct v4l2_ext_buffer *argp ) > + :name: VIDIOC_EXT_PREPARE_BUF > + > + > +Arguments > +========= > + > +``fd`` > + File descriptor returned by :ref:`open() <func-open>`. > + > +``argp`` > + Pointer to struct :c:type:`v4l2_ext_buffer`. > + > + > +Description > +=========== > + > +Applications can optionally call the :ref:`VIDIOC_EXT_PREPARE_BUF` ioctl to > +pass ownership of the buffer to the driver before actually enqueuing it, > +using the :ref:`VIDIOC_EXT_QBUF <VIDIOC_EXT_QBUF>` ioctl, and to prepare it for future I/O. Such > +preparations may include cache invalidation or cleaning. Performing them > +in advance saves time during the actual I/O. > + > + > +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 <gen-errors>` chapter. > + > +EBUSY > + File I/O is in progress. > + > +EINVAL > + The buffer ``type`` is not supported, or the ``index`` is out of > + bounds, or no buffers have been allocated yet, or the ``userptr`` or > + ``length`` are invalid. > diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst > new file mode 100644 > index 0000000000000..083e106cf6bad > --- /dev/null > +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst > @@ -0,0 +1,204 @@ > +.. Permission is granted to copy, distribute and/or modify this > +.. document under the terms of the GNU Free Documentation License, > +.. Version 1.1 or any later version published by the Free Software > +.. Foundation, with no Invariant Sections, no Front-Cover Texts > +.. and no Back-Cover Texts. A copy of the license is included at > +.. Documentation/userspace-api/media/fdl-appendix.rst. > +.. > +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > + > +.. _VIDIOC_EXT_QBUF: > + > +*************************************** > +ioctl VIDIOC_EXT_QBUF, VIDIOC_EXT_DQBUF > +*************************************** > + > +Name > +==== > + > +VIDIOC_EXT_QBUF - VIDIOC_EXT_DQBUF - Exchange a buffer with the driver > + > + > +Synopsis > +======== > + > +.. c:function:: int ioctl( int fd, VIDIOC_EXT_QBUF, struct v4l2_ext_buffer *argp ) > + :name: VIDIOC_EXT_QBUF > + > +.. c:function:: int ioctl( int fd, VIDIOC_EXT_DQBUF, struct v4l2_ext_buffer *argp ) > + :name: VIDIOC_EXT_DQBUF > + > + > +Arguments > +========= > + > +``fd`` > + File descriptor returned by :ref:`open() <func-open>`. > + > +``argp`` > + Pointer to struct :c:type:`v4l2_ext_buffer`. > + > + > +Description > +=========== > + > +Applications call the ``VIDIOC_EXT_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 ``type`` field of a struct > +:c:type:`v4l2_ext_buffer` to the same buffer type as was > +previously used with struct :c:type:`v4l2_ext_pix_format` ``type``. > +Applications must also set the ``index`` field. Valid index numbers > +range from zero to the number of buffers allocated with > +:ref:`VIDIOC_EXT_CREATE_BUFS` (struct > +:c:type:`v4l2_ext_create_buffers` ``count``) minus > +one. The contents of the struct :c:type:`v4l2_ext_buffer` returned > +by a :ref:`VIDIOC_EXT_QUERYBUF` ioctl will do as well. > +When the buffer is intended for output (``type`` is > +``V4L2_BUF_TYPE_VIDEO_OUTPUT``) applications must also initialize the > +``timestamp`` fields and the ``planes[i].plane_length`` for each valid plane, > +and invalid ones must be set as zero. > +see :ref:`buffer` for details. Applications must also set ``flags`` to 0. The > +``reserved`` field must be set to 0. > + > +To enqueue a :ref:`memory mapped <mmap>` buffer applications set the > +``planes[i].memory`` field to ``V4L2_MEMORY_MMAP`` in all the valid planes, > +and invalid ones must be set as zero. > +When ``VIDIOC_EXT_QBUF`` is called > +with a pointer to this structure the driver sets the > +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears > +the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an > +``EINVAL`` error code. > + > +To enqueue a :ref:`user pointer <userp>` buffer applications set the > +``planes[i].memory`` field to ``V4L2_MEMORY_USERPTR`` in all the valid planes, > +and invalid ones must be set as zero, the ``planes[i].m.userptr`` field to the > +address of the buffer,``planes[i].buffer_length`` to the size of the memory > +buffer, ``planes[i].plane_length`` to the size that should be used by the plane, > +and ``planes[i].offset`` of the plane in the memory buffer. > + > +When ``VIDIOC_EXT_QBUF`` is called with a pointer to this structure > +the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the > +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the > +``flags`` field, or it returns an error code. This ioctl locks the > +memory pages of the buffer in physical memory, they cannot be swapped > +out to disk. Buffers remain locked until dequeued, until the > +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or > +:ref:`VIDIOC_EXT_CREATE_BUFS` ioctl is called, or until the > +device is closed. > + > +To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the > +``planes[i].memory`` field to ``V4L2_MEMORY_DMABUF`` in all the valid planes, > +and invalid ones must be set as zero, the ``planes[i].m.fd`` field to a > +file descriptor associated with a DMABUF buffer.,``planes[i].buffer_length`` to > +the size of the memory buffer, ``planes[i].plane_length`` to the size that > +should be used by the plane, and ``planes[i].offset`` of the plane in the memory buffer. > +When ``VIDIOC_EXT_QBUF`` is called with a pointer to this structure the driver > +sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the > +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the > +``flags`` field, or it returns an error code. This ioctl locks the > +buffer. Locking a buffer means passing it to a driver for a hardware > +access (usually DMA). If an application accesses (reads/writes) a locked > +buffer then the result is undefined. Buffers remain locked until > +dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or > +:ref:`VIDIOC_EXT_CREATE_BUFS` ioctl is called, or until the > +device is closed. > + > +The ``request_fd`` field can be used with the ``VIDIOC_EXT_QBUF`` ioctl to specify > +the file descriptor of a :ref:`request <media-request-api>`, if requests are > +in use. Setting it means that the buffer will not be passed to the driver > +until the request itself is queued. Also, the driver will apply any > +settings associated with the request for this buffer. This field will > +be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set. > +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. > + > +.. caution:: > + It is not allowed to mix queuing requests with queuing buffers directly. > + ``EBUSY`` will be returned if the first buffer was queued directly and > + then the application tries to queue a request, or vice versa. After > + closing the file descriptor, calling > + :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_EXT_CREATE_BUFS` > + the check for this will be reset. > + > + For :ref:`memory-to-memory devices <mem2mem>` you can specify the > + ``request_fd`` only for output buffers, not for capture buffers. Attempting > + to specify this for a capture buffer will result in an ``EBADR`` error. > + > +Applications call the ``VIDIOC_EXT_DQBUF`` ioctl to dequeue a filled > +(capturing) or displayed (output) buffer from the driver's outgoing > +queue. They just set the ``type``, ``planes[i].memory`` and ``reserved`` fields of > +a struct :c:type:`v4l2_ext_buffer` as above, when > +``VIDIOC_EXT_DQBUF`` is called with a pointer to this structure the driver > +fills the remaining fields or returns an error code. The driver may also > +set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a > +non-critical (recoverable) streaming error. In such case the application > +may continue as normal, but should be aware that data in the dequeued > +buffer might be corrupted. When using the multi-planar API, the planes > +array must be passed in as well. > + > +If the application sets the ``memory`` field to ``V4L2_MEMORY_DMABUF`` to > +dequeue a :ref:`DMABUF <dmabuf>` buffer, the driver fills the ``m.fd`` field > +with a file descriptor numerically the same as the one given to ``VIDIOC_EXT_QBUF`` > +when the buffer was enqueued. No new file descriptor is created at dequeue time > +and the value is only for the application convenience. > + > +By default ``VIDIOC_EXT_DQBUF`` blocks when no buffer is in the outgoing > +queue. When the ``O_NONBLOCK`` flag was given to the > +:ref:`open() <func-open>` function, ``VIDIOC_EXT_DQBUF`` returns > +immediately with an ``EAGAIN`` error code when no buffer is available. > + > + > +.. kernel-doc:: include/uapi/linux/videodev2.h > + :functions: v4l2_ext_buffers > + > + > +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 <gen-errors>` chapter. > + > +EAGAIN > + Non-blocking I/O has been selected using ``O_NONBLOCK`` and no > + buffer was in the outgoing queue. > + > +EINVAL > + The buffer ``type`` is not supported, or the ``index`` is out of > + bounds, or no buffers have been allocated yet, or the ``userptr`` or > + ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was > + set but the the given ``request_fd`` was invalid, or ``m.fd`` was > + an invalid DMABUF file descriptor. > + > +EIO > + ``VIDIOC_EXT_DQBUF`` failed due to an internal error. Can also indicate > + temporary problems like signal loss. > + > + .. note:: > + > + The driver might dequeue an (empty) buffer despite returning > + an error, or even stop capturing. Reusing such buffer may be unsafe > + though and its details (e.g. ``index``) may not be returned either. > + It is recommended that drivers indicate recoverable errors by setting > + the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the > + application should be able to safely reuse the buffer and continue > + streaming. > + > +EPIPE > + ``VIDIOC_EXT_DQBUF`` returns this on an empty capture queue for mem2mem > + codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already > + dequeued and no new buffers are expected to become available. > + > +EBADR > + The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not > + support requests for the given buffer type, or > + the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was not set but the device requires > + that the buffer is part of a request. > + > +EBUSY > + The first buffer was queued via a request, but the application now tries > + to queue it directly, or vice versa (it is not permitted to mix the two > + APIs). > diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst > new file mode 100644 > index 0000000000000..f2a12017253f6 > --- /dev/null > +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst > @@ -0,0 +1,79 @@ > +.. Permission is granted to copy, distribute and/or modify this > +.. document under the terms of the GNU Free Documentation License, > +.. Version 1.1 or any later version published by the Free Software > +.. Foundation, with no Invariant Sections, no Front-Cover Texts > +.. and no Back-Cover Texts. A copy of the license is included at > +.. Documentation/userspace-api/media/fdl-appendix.rst. > +.. > +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > + > +.. _VIDIOC_EXT_QUERYBUF: > + > +************************* > +ioctl VIDIOC_EXT_QUERYBUF > +************************* > + > +Name > +==== > + > +VIDIOC_EXT_QUERYBUF - Query the status of a buffer > + > + > +Synopsis > +======== > + > +.. c:function:: int ioctl( int fd, VIDIOC_EXT_QUERYBUF, struct v4l2_ext_buffer *argp ) > + :name: VIDIOC_EXT_QUERYBUF > + > + > +Arguments > +========= > + > +``fd`` > + File descriptor returned by :ref:`open() <func-open>`. > + > +``argp`` > + Pointer to struct :c:type:`v4l2_ext_buffer`. > + > + > +Description > +=========== > + > +This ioctl is part of the :ref:`streaming <mmap>` 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:`VIDIOC_EXT_CREATE_BUFS` ioctl. > + > +Applications set the ``type`` field of a struct > +:c:type:`v4l2_ext_buffer` to the same buffer type as was > +previously used with struct :c:type:`v4l2_ext_pix_format` ``type``, > +and the ``index`` field. Valid index numbers range from zero to the > +number of buffers allocated with > +:ref:`VIDIOC_EXT_CREATE_BUFS` (struct > +:c:type:`v4l2_ext_create_buffers` ``count``) minus > +one. The ``reserved`` field must be set to 0. > + > +In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``, > +``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and > +``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``planes.memory`` fields will be > +set to the current I/O method for each plane. > + > +For every valid plane, an entry in ``planes`` will be filled, and zeroed for > +invalid ones. ``planes[i].buffer_length`` is the size of the memory buffer > +which contains the plane, ``planes[i].plane_length`` is the length of the plane, > +and ``planes[i].offset` is where the plane is placed in the memory buffer. > + > +The size of the ``planes`` array can be calculated by the number of sequential > +planes with ``planes[i].buffer_length`` that differs from zero up to the max > +size of the array. > + > + > +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 <gen-errors>` chapter. > + > +EINVAL > + The buffer ``type`` is not supported, or the ``index`` is out of > + bounds. > diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst > new file mode 100644 > index 0000000000000..008e6c98a88a5 > --- /dev/null > +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst > @@ -0,0 +1,117 @@ > +.. Permission is granted to copy, distribute and/or modify this > +.. document under the terms of the GNU Free Documentation License, > +.. Version 1.1 or any later version published by the Free Software > +.. Foundation, with no Invariant Sections, no Front-Cover Texts > +.. and no Back-Cover Texts. A copy of the license is included at > +.. Documentation/userspace-api/media/fdl-appendix.rst. > +.. > +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > + > +.. _VIDIOC_G_EXT_PIX_FMT: > + > +************************************************************************ > +ioctl VIDIOC_G_EXT_PIX_FMT, VIDIOC_S_EXT_PIX_FMT, VIDIOC_TRY_EXT_PIX_FMT > +************************************************************************ > + > +Name > +==== > + > +VIDIOC_G_EXT_PIX_FMT - VIDIOC_S_EXT_PIX_FMT - VIDIOC_TRY_EXT_PIX_FMT - Get or set the data format, try a format > + > + > +Synopsis > +======== > + > +.. c:function:: int ioctl( int fd, VIDIOC_G_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) > + :name: VIDIOC_G_EXT_PIX_FMT > + > +.. c:function:: int ioctl( int fd, VIDIOC_S_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) > + :name: VIDIOC_S_EXT_PIX_FMT > + > +.. c:function:: int ioctl( int fd, VIDIOC_TRY_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) > + :name: VIDIOC_TRY_EXT_PIX_FMT > + > +Arguments > +========= > + > +``fd`` > + File descriptor returned by :ref:`open() <func-open>`. > + > +``argp`` > + Pointer to struct :c:type:`v4l2_ext_pix_format`. > + > + > +Description > +=========== > + > +These ioctls are used to negotiate the format of data (typically image > +format) exchanged between driver and application. > + > +To query the current parameters applications set the ``type`` field of a > +struct :c:type:`v4l2_ext_pix_format` to ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or > +``V4L2_BUF_TYPE_VIDEO_OUTPUT``, all the other types are invalid in this API, > +and multiplanar is supported through modifiers. > + > +When the application calls the > +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl with a pointer to this > +structure the driver fills the other members. > +When the requested buffer type is not supported drivers return > +an ``EINVAL`` error code. > + > +To change the current format parameters applications initialize all > +the fields in the struct. > +For details see the documentation of the various devices types in > +:ref:`devices`. Good practice is to query the current parameters > +first, and to modify only those parameters not suitable for the > +application. When the application calls the :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl with > +a pointer to a struct :c:type:`v4l2_ext_pix_format` structure the driver > +checks and adjusts the parameters against hardware abilities. Drivers > +should not return an error code unless the ``type`` field is invalid, > +this is a mechanism to fathom device capabilities and to approach > +parameters acceptable for both the application and driver. On success > +the driver may program the hardware, allocate resources and generally > +prepare for data exchange. Finally the :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl returns > +the current format parameters as :ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` does. Very simple, > +inflexible devices may even ignore all input and always return the > +default parameters. However all V4L2 devices exchanging data with the > +application must implement the :ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` and :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` > +ioctl. When the requested buffer type is not supported drivers return an > +EINVAL error code on a :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` attempt. When I/O is already in > +progress or the resource is not available for other reasons drivers > +return the ``EBUSY`` error code. > + > +The :ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` with one > +exception: it does not change driver state. It can also be called at any > +time, never returning ``EBUSY``. This function is provided to negotiate > +parameters, to learn about hardware limitations, without disabling I/O > +or possibly time consuming hardware preparations. Although strongly > +recommended drivers are not required to implement this ioctl. > + > +The format as returned by :ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` must be identical to what > +:ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` returns for the same input or output. > + > + > +.. kernel-doc:: include/uapi/linux/videodev2.h > + :functions: v4l2_plane_ext_pix_format > + > + > +.. kernel-doc:: include/uapi/linux/videodev2.h > + :functions: v4l2_ext_pix_format > + > + > +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 <gen-errors>` chapter. > + > +EINVAL > + The struct :c:type:`v4l2_ext_pix_format` ``type`` field is > + invalid or the requested buffer type not supported. > + > +EBUSY > + The device is busy and cannot change the format. This could be > + because or the device is streaming or buffers are allocated or > + queued to the driver. Relevant for :ref:`VIDIOC_S_EXT_PIX_FMT > + <VIDIOC_G_EXT_PIX_FMT>` only. >
On 11/19/20 7:08 AM, Helen Koike wrote: > Hi Tomasz, > > On 11/19/20 2:45 AM, Tomasz Figa wrote: >> On Sat, Nov 14, 2020 at 11:21:26AM -0300, Helen Koike wrote: >>> Hi Tomasz, >>> >>> On 10/2/20 4:49 PM, Tomasz Figa wrote: >>>> Hi Helen, >>>> >>>> On Tue, Aug 04, 2020 at 04:29:33PM -0300, Helen Koike wrote: >> [snip] >>>>> +static void v4l_print_ext_pix_format(const void *arg, bool write_only) >>>>> +{ >>>>> + const struct v4l2_ext_pix_format *pix = arg; >>>>> + unsigned int i; >>>>> + >>>>> + pr_cont("type=%s, width=%u, height=%u, format=%c%c%c%c, modifier %llx, field=%s, colorspace=%d, ycbcr_enc=%u, quantization=%u, xfer_func=%u\n", >>>>> + prt_names(pix->type, v4l2_type_names), >>>>> + pix->width, pix->height, >>>>> + (pix->pixelformat & 0xff), >>>>> + (pix->pixelformat >> 8) & 0xff, >>>>> + (pix->pixelformat >> 16) & 0xff, >>>>> + (pix->pixelformat >> 24) & 0xff, >>>>> + pix->modifier, prt_names(pix->field, v4l2_field_names), >>>>> + pix->colorspace, pix->ycbcr_enc, >>>>> + pix->quantization, pix->xfer_func); >>>>> + for (i = 0; i < VIDEO_MAX_PLANES && pix->plane_fmt[i].sizeimage; i++) >>>> >>>> This is going to print 8 lines every time. Maybe we could skip 0-sized >>>> planes or something? >>> >>> I'm already checking pix->plane_fmt[i].sizeimage in the loop, it shouldn't >>> print 8 lines every time. >>> >> >> Oops, how could I not notice it. Sorry for the noise. >> >> [snip] >>>>> +int v4l2_ext_pix_format_to_format(const struct v4l2_ext_pix_format *e, >>>>> + struct v4l2_format *f, bool mplane_cap, >>>>> + bool strict) >>>>> +{ >>>>> + const struct v4l2_plane_ext_pix_format *pe; >>>>> + struct v4l2_plane_pix_format *p; >>>>> + unsigned int i; >>>>> + >>>>> + memset(f, 0, sizeof(*f)); >>>>> + >>>>> + /* >>>>> + * Make sure no modifier is required before doing the >>>>> + * conversion. >>>>> + */ >>>>> + if (e->modifier && strict && >>>> >>>> Do we need the explicit check for e->modifier != 0 if we have to check for >>>> the 2 specific values below anyway? >>> >>> We don't, since DRM_FORMAT_MOD_LINEAR is zero. >>> >>> But I wanted to make it explicit we don't support modifiers in this conversion. >>> But I can remove this check, no problem. >>> >> >> Yes, please. I think the double checking is confusing for the reader. > > ok. > >> >>>> >>>>> + e->modifier != DRM_FORMAT_MOD_LINEAR && >>>>> + e->modifier != DRM_FORMAT_MOD_INVALID) >>>>> + return -EINVAL; >>>>> + >>>>> + if (!e->plane_fmt[0].sizeimage && strict) >>>>> + return -EINVAL; >>>> >>>> Why is this incorrect? >>> >>> !sizeimage for the first plane means that there are no planes in ef. >>> strict is true if the result for the conversion should be returned to userspace >>> and it is not some internal handling. >>> >>> So if there are no planes, we would return an incomplete v4l2_format struct >>> to userspace. >>> >>> But this is not very clear, I'll improve this for the next version. >>> >> >> So I can see 2 cases here: >> >> 1) Userspace gives ext struct and driver accepts legacy. >> >> In this case, the kernel needs to adjust the structure to be correct. >> -EINVAL is only valid if >> >> "The struct v4l2_format type field is invalid or the requested buffer type not supported." >> >> as per the current uAPI documentation. >> >> 2) Driver gives ext struct and userspace accepts legacy. >> >> If at this point we get a struct with no planes, that sounds like a >> driver bug, so rather than signaling -EINVAL to the userspace, we should >> probably WARN()? >> >> Or am I getting something wrong? :) > > Make sense, I'll restructure this for the next version. > >> >> [snip] >>>>> +{ >>>>> + const struct v4l2_plane_pix_format *p; >>>>> + struct v4l2_plane_ext_pix_format *pe; >>>>> + unsigned int i; >>>>> + >>>>> + memset(e, 0, sizeof(*e)); >>>>> + >>>>> + switch (f->type) { >>>>> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >>>>> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >>>>> + e->width = f->fmt.pix.width; >>>>> + e->height = f->fmt.pix.height; >>>>> + e->pixelformat = f->fmt.pix.pixelformat; >>>>> + e->field = f->fmt.pix.field; >>>>> + e->colorspace = f->fmt.pix.colorspace; >>>>> + if (f->fmt.pix.flags) >>>>> + pr_warn("Ignoring pixelformat flags 0x%x\n", >>>>> + f->fmt.pix.flags); >>>> >>>> Would it make sense to print something like video node name and/or function >>>> name to explain where this warning comes from? >>> >>> I would need to update the function to receive this information, I can try but >>> I'm not sure if it is worthy. >>> >> >> I don't have a strong opinion on this, so maybe let's see if others have >> any comments. >> >>>> >>>>> + e->ycbcr_enc = f->fmt.pix.ycbcr_enc; >>>>> + e->quantization = f->fmt.pix.quantization; >>>> >>>> Missing xfer_func? >>> >>> Yes, thanks for catching this. >>> >>>> >>>>> + e->plane_fmt[0].bytesperline = f->fmt.pix.bytesperline; >>>>> + e->plane_fmt[0].sizeimage = f->fmt.pix.sizeimage; >>>> >>>> This doesn't look right. In the ext API we expected the planes to describe >>>> color planes, which means that bytesperline needs to be computed for planes >>>>> = 1 and sizeimage replaced with per-plane sizes, according to the >>>>> pixelformat. >>> >>> Ack. >>> >>> Just to be clear, even if we are using a planar format that isn't a V4L2_PIX_FMT_*M >>> variant, we should describe every plane separatly. >>> >>> For instance, if V4L2_PIX_FMT_YVU420 is being used, then f->fmt.pix.bytesperline >>> will have data, and we need to calculate bytesperline for all 3 planes, so we'll fill >>> out: >>> >>> f->plane_fmt[0].bytesperline = f->fmt.pix.bytesperline; >>> f->plane_fmt[1].bytesperline = f->fmt.pix.bytesperline / hdiv; >>> f->plane_fmt[2].bytesperline = f->fmt.pix.bytesperline / hdiv; >>> >>> I'll update this for the next version. >>> >> >> Yes. This basically gives us a unified representation across all >> pixelformats and allows userspace to handle them in a uniform way, as >> opposed to current uAPI. > > Right, I already updated this in my wip branch for next version. > >> >> [snip] >>>>> + if (f->type == V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE) >>>>> + e->type = V4L2_BUF_TYPE_VIDEO_CAPTURE; >>>>> + else >>>>> + e->type = V4L2_BUF_TYPE_VIDEO_OUTPUT; >>>>> + >>>>> + for (i = 0; i < VIDEO_MAX_PLANES; i++) { >>>>> + pe = &e->plane_fmt[i]; >>>>> + p = &f->fmt.pix_mp.plane_fmt[i]; >>>>> + pe->bytesperline = p->bytesperline; >>>>> + pe->sizeimage = p->sizeimage; >>>>> + } >>>> >>>> Same here. A blind copy is not enough. For non-M formats, the plane >>>> parameters need to be filled according to the pixelformat. >>> >>> >>> Right, following the idea above, we need a different handling if we >>> aren't using a M-variant of the pixelformat, and we also need to >>> convert the pixelformat from the M-variant to non-M-variant. >>> >>> I'll also need to save that the original format was a >>> M-variant or not, so I can convert it back as expected. >> >> I'm still reading the rest of the series, so it might be answered >> already, but did we decide to do anything about the pixelformat codes >> themselves? If both M and non-M variants would be allowed with the new >> API, then I guess there isn't anything to save, because the original >> format would be preserved? > > I was working with the idea that M-variants wouldn't be allowed. > But then, we have cases where non-M-variant don't exist, such as: > > V4L2_PIX_FMT_YVU422M > V4L2_PIX_FMT_YVU444M > > (at least, I couldn't find non-M-variant equivalent for those) > > But actually, I don't think we formally decided this (and it seems > easier to implement if both are allowed). > > Should we allow both variants in the Ext API ? I see 3 options: 1) Ext API doesn't accept M-variants and return -EINVAL. But this doesn't seem to be the v4l2 way, where we avoid returning errors and try to adjust to what we think it is better. At the same time, this could allow us, in a very remote hypothetical future situation, to remove the M-variants from the kernel when/if the old API gets obsolete. Future ENUM_EXT_FMT won't enumerate M-variants in this option. 2) Ext API accept M-variants without normalization. The driver can receive both variants, and need to handle both as equivalents, i.e. if (V4L2_PIX_FMT_YUV420M || V4L2_PIX_FMT_YUV420) Both can be returned to userspace. Future ENUM_EXT_FMT can enumerate M-variants in this option. 3) Ext API accept M-variants with normalization. If userspace uses V4L2_PIX_FMT_YUV420M, the framework converts to V4L2_PIX_FMT_YUV420 before passing it to the driver. Only V4L2_PIX_FMT_YUV420 is sent back to userspace (even if userspace used the M variant, the kernel normalizes it, which is a similar behavior when userspace try to use a non-supported resolution and the kernel adjusts it). (we could also leave this pixelformat normalization to the driver, but I don't see a reason to that) Future ENUM_EXT_FMT won't enumerate M-variants in this option. I'm leaning towards option 3, please let me know your thoughts. Thanks Helen > > Thanks > Helen > >> >>> >>> I'll change this and submit for review. >>> >> >> Cool, thanks. >> >> Best regards, >> Tomasz >>
Hi Alexandre, Thanks for your review. On 8/14/20 4:49 AM, Alexandre Courbot wrote: > On Wed, Aug 5, 2020 at 4:32 AM Helen Koike <helen.koike@collabora.com> wrote: >> >> This is part of the multiplanar and singleplanar unification process. >> v4l2_ext_pix_format is supposed to work for both cases. >> >> We also add the concept of modifiers already employed in DRM to expose >> HW-specific formats (like tiled or compressed formats) and allow >> exchanging this information with the DRM subsystem in a consistent way. >> >> Note that only V4L2_BUF_TYPE_VIDEO_[OUTPUT,CAPTURE] are accepted in >> v4l2_ext_format, other types will be rejected if you use the >> {G,S,TRY}_EXT_PIX_FMT ioctls. >> >> New hooks have been added to v4l2_ioctl_ops to support those new ioctls >> in drivers, but, in the meantime, the core takes care of converting >> {S,G,TRY}_EXT_PIX_FMT requests into {S,G,TRY}_FMT so that old drivers can >> still work if the userspace app/lib uses the new ioctls. >> The conversion is also done the other around to allow userspace >> apps/libs using {S,G,TRY}_FMT to work with drivers implementing the >> _ext_ hooks. >> >> Signed-off-by: Boris Brezillon <boris.brezillon@collabora.com> >> Signed-off-by: Helen Koike <helen.koike@collabora.com> >> --- >> Changes in v5: >> - change sizes and reorder fields to avoid holes in the struct and make >> it the same for 32 and 64 bits >> - removed __attribute__ ((packed)) from uapi structs >> - Fix doc warning from make htmldocs >> - Updated commit message with EXT_PIX prefix for the ioctls. >> >> Changes in v4: >> - Use v4l2_ext_pix_format directly in the ioctl, drop v4l2_ext_format, >> making V4L2_BUF_TYPE_VIDEO_[OUTPUT,CAPTURE] the only valid types. >> - Add reserved fields >> - Removed num_planes from struct v4l2_ext_pix_format >> - Removed flag field from struct v4l2_ext_pix_format, since the only >> defined value is V4L2_PIX_FMT_FLAG_PREMUL_ALPHA only used by vsp1, >> where we can use modifiers, or add it back later through the reserved >> bits. >> - In v4l2_ext_format_to_format(), check if modifier is != MOD_LINEAR && >> != MOD_INVALID >> - Fix type assignment in v4l_g_fmt_ext_pix() >> - Rebased on top of media/master (post 5.8-rc1) >> >> Changes in v3: >> - Rebased on top of media/master (post 5.4-rc1) >> >> Changes in v2: >> - Move the modifier in v4l2_ext_format (was formerly placed in >> v4l2_ext_plane) >> - Fix a few bugs in the converters and add a strict parameter to >> allow conversion of uninitialized/mis-initialized objects >> --- >> drivers/media/v4l2-core/v4l2-dev.c | 21 +- >> drivers/media/v4l2-core/v4l2-ioctl.c | 585 +++++++++++++++++++++++---- >> include/media/v4l2-ioctl.h | 34 ++ >> include/uapi/linux/videodev2.h | 56 +++ >> 4 files changed, 615 insertions(+), 81 deletions(-) >> >> diff --git a/drivers/media/v4l2-core/v4l2-dev.c b/drivers/media/v4l2-core/v4l2-dev.c >> index a593ea0598b55..e1829906bc086 100644 >> --- a/drivers/media/v4l2-core/v4l2-dev.c >> +++ b/drivers/media/v4l2-core/v4l2-dev.c >> @@ -607,25 +607,37 @@ static void determine_valid_ioctls(struct video_device *vdev) >> set_bit(_IOC_NR(VIDIOC_ENUM_FMT), valid_ioctls); >> if ((is_rx && (ops->vidioc_g_fmt_vid_cap || >> ops->vidioc_g_fmt_vid_cap_mplane || >> + ops->vidioc_g_ext_pix_fmt_vid_cap || >> ops->vidioc_g_fmt_vid_overlay)) || >> (is_tx && (ops->vidioc_g_fmt_vid_out || >> ops->vidioc_g_fmt_vid_out_mplane || >> - ops->vidioc_g_fmt_vid_out_overlay))) >> + ops->vidioc_g_ext_pix_fmt_vid_out || >> + ops->vidioc_g_fmt_vid_out_overlay))) { >> set_bit(_IOC_NR(VIDIOC_G_FMT), valid_ioctls); >> + set_bit(_IOC_NR(VIDIOC_G_EXT_PIX_FMT), valid_ioctls); >> + } >> if ((is_rx && (ops->vidioc_s_fmt_vid_cap || >> ops->vidioc_s_fmt_vid_cap_mplane || >> + ops->vidioc_s_ext_pix_fmt_vid_cap || >> ops->vidioc_s_fmt_vid_overlay)) || >> (is_tx && (ops->vidioc_s_fmt_vid_out || >> ops->vidioc_s_fmt_vid_out_mplane || >> - ops->vidioc_s_fmt_vid_out_overlay))) >> + ops->vidioc_s_ext_pix_fmt_vid_out || >> + ops->vidioc_s_fmt_vid_out_overlay))) { >> set_bit(_IOC_NR(VIDIOC_S_FMT), valid_ioctls); >> + set_bit(_IOC_NR(VIDIOC_S_EXT_PIX_FMT), valid_ioctls); >> + } >> if ((is_rx && (ops->vidioc_try_fmt_vid_cap || >> ops->vidioc_try_fmt_vid_cap_mplane || >> + ops->vidioc_try_ext_pix_fmt_vid_cap || >> ops->vidioc_try_fmt_vid_overlay)) || >> (is_tx && (ops->vidioc_try_fmt_vid_out || >> ops->vidioc_try_fmt_vid_out_mplane || >> - ops->vidioc_try_fmt_vid_out_overlay))) >> + ops->vidioc_try_ext_pix_fmt_vid_out || >> + ops->vidioc_try_fmt_vid_out_overlay))) { >> set_bit(_IOC_NR(VIDIOC_TRY_FMT), valid_ioctls); >> + set_bit(_IOC_NR(VIDIOC_TRY_EXT_PIX_FMT), valid_ioctls); >> + } >> SET_VALID_IOCTL(ops, VIDIOC_OVERLAY, vidioc_overlay); >> SET_VALID_IOCTL(ops, VIDIOC_G_FBUF, vidioc_g_fbuf); >> SET_VALID_IOCTL(ops, VIDIOC_S_FBUF, vidioc_s_fbuf); >> @@ -682,8 +694,11 @@ static void determine_valid_ioctls(struct video_device *vdev) >> /* touch specific ioctls */ >> SET_VALID_IOCTL(ops, VIDIOC_ENUM_FMT, vidioc_enum_fmt_vid_cap); >> SET_VALID_IOCTL(ops, VIDIOC_G_FMT, vidioc_g_fmt_vid_cap); >> + SET_VALID_IOCTL(ops, VIDIOC_G_EXT_PIX_FMT, vidioc_g_fmt_vid_cap); >> SET_VALID_IOCTL(ops, VIDIOC_S_FMT, vidioc_s_fmt_vid_cap); >> + SET_VALID_IOCTL(ops, VIDIOC_S_EXT_PIX_FMT, vidioc_s_fmt_vid_cap); >> SET_VALID_IOCTL(ops, VIDIOC_TRY_FMT, vidioc_try_fmt_vid_cap); >> + SET_VALID_IOCTL(ops, VIDIOC_TRY_EXT_PIX_FMT, vidioc_try_fmt_vid_cap); >> SET_VALID_IOCTL(ops, VIDIOC_ENUM_FRAMESIZES, vidioc_enum_framesizes); >> SET_VALID_IOCTL(ops, VIDIOC_ENUM_FRAMEINTERVALS, vidioc_enum_frameintervals); >> SET_VALID_IOCTL(ops, VIDIOC_ENUMINPUT, vidioc_enum_input); >> diff --git a/drivers/media/v4l2-core/v4l2-ioctl.c b/drivers/media/v4l2-core/v4l2-ioctl.c >> index a556880f225a5..14a0def50f8ea 100644 >> --- a/drivers/media/v4l2-core/v4l2-ioctl.c >> +++ b/drivers/media/v4l2-core/v4l2-ioctl.c >> @@ -17,6 +17,8 @@ >> >> #include <linux/videodev2.h> >> >> +#include <drm/drm_fourcc.h> >> + >> #include <media/v4l2-common.h> >> #include <media/v4l2-ioctl.h> >> #include <media/v4l2-ctrls.h> >> @@ -378,6 +380,27 @@ static void v4l_print_format(const void *arg, bool write_only) >> } >> } >> >> +static void v4l_print_ext_pix_format(const void *arg, bool write_only) >> +{ >> + const struct v4l2_ext_pix_format *pix = arg; >> + unsigned int i; >> + >> + pr_cont("type=%s, width=%u, height=%u, format=%c%c%c%c, modifier %llx, field=%s, colorspace=%d, ycbcr_enc=%u, quantization=%u, xfer_func=%u\n", >> + prt_names(pix->type, v4l2_type_names), >> + pix->width, pix->height, >> + (pix->pixelformat & 0xff), >> + (pix->pixelformat >> 8) & 0xff, >> + (pix->pixelformat >> 16) & 0xff, >> + (pix->pixelformat >> 24) & 0xff, >> + pix->modifier, prt_names(pix->field, v4l2_field_names), >> + pix->colorspace, pix->ycbcr_enc, >> + pix->quantization, pix->xfer_func); >> + for (i = 0; i < VIDEO_MAX_PLANES && pix->plane_fmt[i].sizeimage; i++) >> + pr_debug("plane %u: bytesperline=%u sizeimage=%u\n", >> + i, pix->plane_fmt[i].bytesperline, >> + pix->plane_fmt[i].sizeimage); >> +} >> + >> static void v4l_print_framebuffer(const void *arg, bool write_only) >> { >> const struct v4l2_framebuffer *p = arg; >> @@ -964,11 +987,15 @@ static int check_fmt(struct file *file, enum v4l2_buf_type type) >> switch (type) { >> case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> if ((is_vid || is_tch) && is_rx && >> - (ops->vidioc_g_fmt_vid_cap || ops->vidioc_g_fmt_vid_cap_mplane)) >> + (ops->vidioc_g_fmt_vid_cap || >> + ops->vidioc_g_ext_pix_fmt_vid_cap || >> + ops->vidioc_g_fmt_vid_cap_mplane)) >> return 0; >> break; >> case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> - if ((is_vid || is_tch) && is_rx && ops->vidioc_g_fmt_vid_cap_mplane) >> + if ((is_vid || is_tch) && is_rx && >> + (ops->vidioc_g_fmt_vid_cap_mplane || >> + ops->vidioc_g_ext_pix_fmt_vid_cap)) >> return 0; >> break; >> case V4L2_BUF_TYPE_VIDEO_OVERLAY: >> @@ -977,11 +1004,15 @@ static int check_fmt(struct file *file, enum v4l2_buf_type type) >> break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> if (is_vid && is_tx && >> - (ops->vidioc_g_fmt_vid_out || ops->vidioc_g_fmt_vid_out_mplane)) >> + (ops->vidioc_g_fmt_vid_out || >> + ops->vidioc_g_ext_pix_fmt_vid_out || >> + ops->vidioc_g_fmt_vid_out_mplane)) >> return 0; >> break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> - if (is_vid && is_tx && ops->vidioc_g_fmt_vid_out_mplane) >> + if (is_vid && is_tx && >> + (ops->vidioc_g_ext_pix_fmt_vid_out || >> + ops->vidioc_g_fmt_vid_out_mplane)) >> return 0; >> break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY: >> @@ -1061,6 +1092,134 @@ static void v4l_sanitize_format(struct v4l2_format *fmt) >> sizeof(fmt->fmt.pix) - offset); >> } >> >> +int v4l2_ext_pix_format_to_format(const struct v4l2_ext_pix_format *e, >> + struct v4l2_format *f, bool mplane_cap, >> + bool strict) >> +{ >> + const struct v4l2_plane_ext_pix_format *pe; >> + struct v4l2_plane_pix_format *p; >> + unsigned int i; >> + >> + memset(f, 0, sizeof(*f)); >> + >> + /* >> + * Make sure no modifier is required before doing the >> + * conversion. >> + */ >> + if (e->modifier && strict && >> + e->modifier != DRM_FORMAT_MOD_LINEAR && >> + e->modifier != DRM_FORMAT_MOD_INVALID) >> + return -EINVAL; >> + >> + if (!e->plane_fmt[0].sizeimage && strict) >> + return -EINVAL; >> + >> + if (e->plane_fmt[1].sizeimage && !mplane_cap && strict) >> + return 0; >> + >> + if (!mplane_cap) { >> + f->fmt.pix.width = e->width; >> + f->fmt.pix.height = e->height; >> + f->fmt.pix.pixelformat = e->pixelformat; >> + f->fmt.pix.field = e->field; >> + f->fmt.pix.colorspace = e->colorspace; >> + f->fmt.pix.ycbcr_enc = e->ycbcr_enc; >> + f->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + f->fmt.pix.quantization = e->quantization; >> + pe = &e->plane_fmt[0]; >> + f->fmt.pix.bytesperline = pe->bytesperline; >> + f->fmt.pix.sizeimage = pe->sizeimage; >> + f->type = e->type; >> + return 0; >> + } >> + >> + f->fmt.pix_mp.width = e->width; >> + f->fmt.pix_mp.height = e->height; >> + f->fmt.pix_mp.pixelformat = e->pixelformat; >> + f->fmt.pix_mp.field = e->field; >> + f->fmt.pix_mp.colorspace = e->colorspace; >> + f->fmt.pix_mp.ycbcr_enc = e->ycbcr_enc; >> + f->fmt.pix_mp.quantization = e->quantization; >> + if (e->type == V4L2_BUF_TYPE_VIDEO_CAPTURE) >> + f->type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; >> + else >> + f->type = V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE; >> + >> + for (i = 0; i < VIDEO_MAX_PLANES; i++) { >> + pe = &e->plane_fmt[i]; >> + p = &f->fmt.pix_mp.plane_fmt[i]; >> + p->bytesperline = pe->bytesperline; >> + p->sizeimage = pe->sizeimage; >> + } >> + >> + return 0; >> +} >> +EXPORT_SYMBOL_GPL(v4l2_ext_pix_format_to_format); >> + >> +int v4l2_format_to_ext_pix_format(const struct v4l2_format *f, >> + struct v4l2_ext_pix_format *e, bool strict) >> +{ >> + const struct v4l2_plane_pix_format *p; >> + struct v4l2_plane_ext_pix_format *pe; >> + unsigned int i; >> + >> + memset(e, 0, sizeof(*e)); >> + >> + switch (f->type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + e->width = f->fmt.pix.width; >> + e->height = f->fmt.pix.height; >> + e->pixelformat = f->fmt.pix.pixelformat; >> + e->field = f->fmt.pix.field; >> + e->colorspace = f->fmt.pix.colorspace; >> + if (f->fmt.pix.flags) >> + pr_warn("Ignoring pixelformat flags 0x%x\n", >> + f->fmt.pix.flags); >> + e->ycbcr_enc = f->fmt.pix.ycbcr_enc; >> + e->quantization = f->fmt.pix.quantization; >> + e->plane_fmt[0].bytesperline = f->fmt.pix.bytesperline; >> + e->plane_fmt[0].sizeimage = f->fmt.pix.sizeimage; >> + e->type = f->type; >> + break; >> + >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> + if ((f->fmt.pix_mp.num_planes > VIDEO_MAX_PLANES || >> + !f->fmt.pix_mp.num_planes) && strict) >> + return -EINVAL; >> + >> + e->width = f->fmt.pix_mp.width; >> + e->height = f->fmt.pix_mp.height; >> + e->pixelformat = f->fmt.pix_mp.pixelformat; >> + e->field = f->fmt.pix_mp.field; >> + e->colorspace = f->fmt.pix_mp.colorspace; >> + if (f->fmt.pix.flags) >> + pr_warn("Ignoring pixelformat flags 0x%x\n", >> + f->fmt.pix.flags); >> + e->ycbcr_enc = f->fmt.pix_mp.ycbcr_enc; >> + e->quantization = f->fmt.pix_mp.quantization; >> + if (f->type == V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE) >> + e->type = V4L2_BUF_TYPE_VIDEO_CAPTURE; >> + else >> + e->type = V4L2_BUF_TYPE_VIDEO_OUTPUT; >> + >> + for (i = 0; i < VIDEO_MAX_PLANES; i++) { >> + pe = &e->plane_fmt[i]; >> + p = &f->fmt.pix_mp.plane_fmt[i]; >> + pe->bytesperline = p->bytesperline; >> + pe->sizeimage = p->sizeimage; >> + } >> + break; >> + >> + default: >> + return -EINVAL; >> + } >> + >> + return 0; >> +} >> +EXPORT_SYMBOL_GPL(v4l2_format_to_ext_pix_format); >> + >> static int v4l_querycap(const struct v4l2_ioctl_ops *ops, >> struct file *file, void *fh, void *arg) >> { >> @@ -1564,6 +1723,38 @@ static void v4l_pix_format_touch(struct v4l2_pix_format *p) >> p->xfer_func = 0; >> } >> >> +static int v4l_g_fmt_ext_pix(const struct v4l2_ioctl_ops *ops, >> + struct file *file, void *fh, >> + struct v4l2_format *f) >> +{ >> + struct v4l2_ext_pix_format ef; >> + int ret; >> + >> + switch (f->type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> + ef.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; >> + ret = ops->vidioc_g_ext_pix_fmt_vid_cap(file, fh, &ef); >> + break; >> + >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> + ef.type = V4L2_BUF_TYPE_VIDEO_OUTPUT; >> + ret = ops->vidioc_g_ext_pix_fmt_vid_out(file, fh, &ef); >> + break; >> + >> + default: >> + return -EINVAL; >> + } >> + >> + if (ret) >> + return ret; >> + >> + return v4l2_ext_pix_format_to_format(&ef, f, >> + V4L2_TYPE_IS_MULTIPLANAR(f->type), >> + true); >> +} >> + >> static int v4l_g_fmt(const struct v4l2_ioctl_ops *ops, >> struct file *file, void *fh, void *arg) >> { >> @@ -1600,17 +1791,27 @@ static int v4l_g_fmt(const struct v4l2_ioctl_ops *ops, >> >> switch (p->type) { >> case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> - if (unlikely(!ops->vidioc_g_fmt_vid_cap)) >> - break; >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - ret = ops->vidioc_g_fmt_vid_cap(file, fh, arg); >> - /* just in case the driver zeroed it again */ >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - if (vfd->vfl_type == VFL_TYPE_TOUCH) >> - v4l_pix_format_touch(&p->fmt.pix); >> - return ret; >> + if (ops->vidioc_g_fmt_vid_cap) { >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + ret = ops->vidioc_g_fmt_vid_cap(file, fh, arg); >> + /* just in case the driver zeroed it again */ >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + if (vfd->vfl_type == VFL_TYPE_TOUCH) >> + v4l_pix_format_touch(&p->fmt.pix); >> + return ret; >> + } else if (ops->vidioc_g_ext_pix_fmt_vid_cap) { >> + ret = v4l_g_fmt_ext_pix(ops, file, fh, p); >> + if (vfd->vfl_type == VFL_TYPE_TOUCH) >> + v4l_pix_format_touch(&p->fmt.pix); >> + return ret; >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> - return ops->vidioc_g_fmt_vid_cap_mplane(file, fh, arg); >> + if (ops->vidioc_g_fmt_vid_cap_mplane) >> + return ops->vidioc_g_fmt_vid_cap_mplane(file, fh, arg); >> + else if (ops->vidioc_g_ext_pix_fmt_vid_cap) >> + return v4l_g_fmt_ext_pix(ops, file, fh, p); >> + break; >> case V4L2_BUF_TYPE_VIDEO_OVERLAY: >> return ops->vidioc_g_fmt_vid_overlay(file, fh, arg); >> case V4L2_BUF_TYPE_VBI_CAPTURE: >> @@ -1618,15 +1819,22 @@ static int v4l_g_fmt(const struct v4l2_ioctl_ops *ops, >> case V4L2_BUF_TYPE_SLICED_VBI_CAPTURE: >> return ops->vidioc_g_fmt_sliced_vbi_cap(file, fh, arg); >> case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> - if (unlikely(!ops->vidioc_g_fmt_vid_out)) >> - break; >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - ret = ops->vidioc_g_fmt_vid_out(file, fh, arg); >> - /* just in case the driver zeroed it again */ >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - return ret; >> + if (ops->vidioc_g_fmt_vid_out) { >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + ret = ops->vidioc_g_fmt_vid_out(file, fh, arg); >> + /* just in case the driver zeroed it again */ >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + return ret; >> + } else if (ops->vidioc_g_ext_pix_fmt_vid_out) { >> + return v4l_g_fmt_ext_pix(ops, file, fh, p); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> - return ops->vidioc_g_fmt_vid_out_mplane(file, fh, arg); >> + if (ops->vidioc_g_fmt_vid_out_mplane) >> + return ops->vidioc_g_fmt_vid_out_mplane(file, fh, arg); >> + else if (ops->vidioc_g_ext_pix_fmt_vid_out) >> + return v4l_g_fmt_ext_pix(ops, file, fh, p); >> + break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY: >> return ops->vidioc_g_fmt_vid_out_overlay(file, fh, arg); >> case V4L2_BUF_TYPE_VBI_OUTPUT: >> @@ -1645,6 +1853,76 @@ static int v4l_g_fmt(const struct v4l2_ioctl_ops *ops, >> return -EINVAL; >> } >> >> +static int v4l_g_ext_pix_fmt(const struct v4l2_ioctl_ops *ops, >> + struct file *file, void *fh, void *arg) >> +{ >> + struct v4l2_ext_pix_format *ef = arg; >> + struct v4l2_format f = { >> + .type = ef->type, >> + }; >> + int ret; >> + >> + ret = check_fmt(file, ef->type); >> + if (ret) >> + return ret; >> + >> + memset(ef, 0, sizeof(*ef)); >> + ef->type = f.type; >> + >> + switch (f.type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + if (ops->vidioc_g_ext_pix_fmt_vid_cap) >> + return ops->vidioc_g_ext_pix_fmt_vid_cap(file, fh, ef); >> + break; >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + if (ops->vidioc_g_ext_pix_fmt_vid_out) >> + return ops->vidioc_g_ext_pix_fmt_vid_out(file, fh, ef); >> + break; >> + default: >> + return -EINVAL; >> + } >> + >> + ret = v4l_g_fmt(ops, file, fh, &f); >> + if (ret) >> + return ret; >> + >> + return v4l2_format_to_ext_pix_format(&f, ef, true); >> +} >> + >> +static int v4l_s_fmt_ext_pix(const struct v4l2_ioctl_ops *ops, >> + struct file *file, void *fh, >> + struct v4l2_format *f) >> +{ >> + struct v4l2_ext_pix_format ef; >> + int ret; >> + >> + ret = v4l2_format_to_ext_pix_format(f, &ef, false); >> + if (ret) >> + return ret; >> + >> + switch (f->type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> + ret = ops->vidioc_s_ext_pix_fmt_vid_cap(file, fh, &ef); >> + break; >> + >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> + ret = ops->vidioc_s_ext_pix_fmt_vid_out(file, fh, &ef); >> + break; >> + >> + default: >> + return -EINVAL; >> + } >> + >> + if (ret) >> + return ret; >> + >> + return v4l2_ext_pix_format_to_format(&ef, f, >> + V4L2_TYPE_IS_MULTIPLANAR(f->type), >> + true); >> +} >> + >> static int v4l_s_fmt(const struct v4l2_ioctl_ops *ops, >> struct file *file, void *fh, void *arg) >> { >> @@ -1663,23 +1941,31 @@ static int v4l_s_fmt(const struct v4l2_ioctl_ops *ops, >> >> switch (p->type) { >> case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> - if (unlikely(!ops->vidioc_s_fmt_vid_cap)) >> + if (ops->vidioc_s_fmt_vid_cap) { >> + CLEAR_AFTER_FIELD(p, fmt.pix); >> + ret = ops->vidioc_s_fmt_vid_cap(file, fh, arg); >> + /* just in case the driver zeroed it again */ >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + } else if (ops->vidioc_s_ext_pix_fmt_vid_cap) { >> + ret = v4l_s_fmt_ext_pix(ops, file, fh, arg); >> + } else { >> break; >> - CLEAR_AFTER_FIELD(p, fmt.pix); >> - ret = ops->vidioc_s_fmt_vid_cap(file, fh, arg); >> - /* just in case the driver zeroed it again */ >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + } >> + >> if (vfd->vfl_type == VFL_TYPE_TOUCH) >> v4l_pix_format_touch(&p->fmt.pix); >> return ret; >> case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> - if (unlikely(!ops->vidioc_s_fmt_vid_cap_mplane)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> - for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> - CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> - bytesperline); >> - return ops->vidioc_s_fmt_vid_cap_mplane(file, fh, arg); >> + if (ops->vidioc_s_fmt_vid_cap_mplane) { >> + CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> + for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> + CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> + bytesperline); >> + return ops->vidioc_s_fmt_vid_cap_mplane(file, fh, arg); >> + } else if (ops->vidioc_s_ext_pix_fmt_vid_cap) { >> + return v4l_s_fmt_ext_pix(ops, file, fh, arg); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OVERLAY: >> if (unlikely(!ops->vidioc_s_fmt_vid_overlay)) >> break; >> @@ -1696,21 +1982,27 @@ static int v4l_s_fmt(const struct v4l2_ioctl_ops *ops, >> CLEAR_AFTER_FIELD(p, fmt.sliced.io_size); >> return ops->vidioc_s_fmt_sliced_vbi_cap(file, fh, arg); >> case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> - if (unlikely(!ops->vidioc_s_fmt_vid_out)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix); >> - ret = ops->vidioc_s_fmt_vid_out(file, fh, arg); >> - /* just in case the driver zeroed it again */ >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - return ret; >> + if (ops->vidioc_s_fmt_vid_out) { >> + CLEAR_AFTER_FIELD(p, fmt.pix); >> + ret = ops->vidioc_s_fmt_vid_out(file, fh, arg); >> + /* just in case the driver zeroed it again */ >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + return ret; >> + } else if (ops->vidioc_s_ext_pix_fmt_vid_out) { >> + return v4l_s_fmt_ext_pix(ops, file, fh, arg); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> - if (unlikely(!ops->vidioc_s_fmt_vid_out_mplane)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> - for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> - CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> - bytesperline); >> - return ops->vidioc_s_fmt_vid_out_mplane(file, fh, arg); >> + if (ops->vidioc_s_fmt_vid_out_mplane) { >> + CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> + for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> + CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> + bytesperline); >> + return ops->vidioc_s_fmt_vid_out_mplane(file, fh, arg); >> + } else if (ops->vidioc_s_ext_pix_fmt_vid_out) { >> + return v4l_s_fmt_ext_pix(ops, file, fh, arg); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY: >> if (unlikely(!ops->vidioc_s_fmt_vid_out_overlay)) >> break; >> @@ -1750,6 +2042,82 @@ static int v4l_s_fmt(const struct v4l2_ioctl_ops *ops, >> return -EINVAL; >> } >> >> +static int v4l_s_ext_pix_fmt(const struct v4l2_ioctl_ops *ops, >> + struct file *file, void *fh, void *arg) >> +{ >> + struct video_device *vfd = video_devdata(file); >> + struct v4l2_ext_pix_format *ef = arg; >> + struct v4l2_format f; >> + int ret; >> + >> + ret = check_fmt(file, ef->type); >> + if (ret) >> + return ret; >> + >> + switch (ef->type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + if (ops->vidioc_s_ext_pix_fmt_vid_cap) >> + return ops->vidioc_s_ext_pix_fmt_vid_cap(file, fh, ef); >> + break; >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + if (ops->vidioc_s_ext_pix_fmt_vid_out) >> + return ops->vidioc_s_ext_pix_fmt_vid_out(file, fh, ef); >> + break; >> + default: >> + return -EINVAL; >> + } >> + >> + ret = v4l2_ext_pix_format_to_format(ef, &f, >> + vfd->device_caps & >> + (V4L2_CAP_VIDEO_CAPTURE_MPLANE | >> + V4L2_CAP_VIDEO_OUTPUT_MPLANE | >> + V4L2_CAP_VIDEO_M2M_MPLANE), >> + false); >> + if (ret) >> + return ret; >> + >> + ret = v4l_s_fmt(ops, file, fh, &f); >> + if (ret) >> + return ret; >> + >> + return v4l2_format_to_ext_pix_format(&f, ef, true); >> +} >> + >> +static int v4l_try_fmt_ext_pix(const struct v4l2_ioctl_ops *ops, >> + struct file *file, void *fh, >> + struct v4l2_format *f) >> +{ >> + struct v4l2_ext_pix_format ef; >> + int ret; >> + >> + ret = v4l2_format_to_ext_pix_format(f, &ef, false); >> + if (ret) >> + return ret; >> + >> + switch (f->type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> + ret = ops->vidioc_try_ext_pix_fmt_vid_cap(file, fh, &ef); >> + break; >> + >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> + ret = ops->vidioc_try_ext_pix_fmt_vid_out(file, fh, &ef); >> + break; >> + >> + default: >> + return -EINVAL; >> + } >> + >> + if (ret) >> + return ret; >> + >> + return v4l2_ext_pix_format_to_format(&ef, f, >> + V4L2_TYPE_IS_MULTIPLANAR(f->type), >> + true); >> +} >> + >> + >> static int v4l_try_fmt(const struct v4l2_ioctl_ops *ops, >> struct file *file, void *fh, void *arg) >> { >> @@ -1765,23 +2133,32 @@ static int v4l_try_fmt(const struct v4l2_ioctl_ops *ops, >> >> switch (p->type) { >> case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> - if (unlikely(!ops->vidioc_try_fmt_vid_cap)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix); >> - ret = ops->vidioc_try_fmt_vid_cap(file, fh, arg); >> - /* just in case the driver zeroed it again */ >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - if (vfd->vfl_type == VFL_TYPE_TOUCH) >> - v4l_pix_format_touch(&p->fmt.pix); >> - return ret; >> + if (ops->vidioc_try_fmt_vid_cap) { >> + CLEAR_AFTER_FIELD(p, fmt.pix); >> + ret = ops->vidioc_try_fmt_vid_cap(file, fh, arg); >> + /* just in case the driver zeroed it again */ >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + if (vfd->vfl_type == VFL_TYPE_TOUCH) >> + v4l_pix_format_touch(&p->fmt.pix); >> + return ret; >> + } else if (ops->vidioc_try_ext_pix_fmt_vid_cap) { >> + ret = v4l_try_fmt_ext_pix(ops, file, fh, p); >> + if (vfd->vfl_type == VFL_TYPE_TOUCH) >> + v4l_pix_format_touch(&p->fmt.pix); >> + return ret; >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> - if (unlikely(!ops->vidioc_try_fmt_vid_cap_mplane)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> - for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> - CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> - bytesperline); >> - return ops->vidioc_try_fmt_vid_cap_mplane(file, fh, arg); >> + if (ops->vidioc_try_fmt_vid_cap_mplane) { >> + CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> + for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> + CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> + bytesperline); >> + return ops->vidioc_try_fmt_vid_cap_mplane(file, fh, arg); >> + } else if (ops->vidioc_try_ext_pix_fmt_vid_cap) { >> + return v4l_try_fmt_ext_pix(ops, file, fh, p); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OVERLAY: >> if (unlikely(!ops->vidioc_try_fmt_vid_overlay)) >> break; >> @@ -1798,21 +2175,27 @@ static int v4l_try_fmt(const struct v4l2_ioctl_ops *ops, >> CLEAR_AFTER_FIELD(p, fmt.sliced.io_size); >> return ops->vidioc_try_fmt_sliced_vbi_cap(file, fh, arg); >> case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> - if (unlikely(!ops->vidioc_try_fmt_vid_out)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix); >> - ret = ops->vidioc_try_fmt_vid_out(file, fh, arg); >> - /* just in case the driver zeroed it again */ >> - p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> - return ret; >> + if (ops->vidioc_try_fmt_vid_out) { >> + CLEAR_AFTER_FIELD(p, fmt.pix); >> + ret = ops->vidioc_try_fmt_vid_out(file, fh, arg); >> + /* just in case the driver zeroed it again */ >> + p->fmt.pix.priv = V4L2_PIX_FMT_PRIV_MAGIC; >> + return ret; >> + } else if (ops->vidioc_try_ext_pix_fmt_vid_cap) { >> + return v4l_try_fmt_ext_pix(ops, file, fh, p); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> - if (unlikely(!ops->vidioc_try_fmt_vid_out_mplane)) >> - break; >> - CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> - for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> - CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> - bytesperline); >> - return ops->vidioc_try_fmt_vid_out_mplane(file, fh, arg); >> + if (ops->vidioc_try_fmt_vid_out_mplane) { >> + CLEAR_AFTER_FIELD(p, fmt.pix_mp.xfer_func); >> + for (i = 0; i < p->fmt.pix_mp.num_planes; i++) >> + CLEAR_AFTER_FIELD(&p->fmt.pix_mp.plane_fmt[i], >> + bytesperline); >> + return ops->vidioc_try_fmt_vid_out_mplane(file, fh, arg); >> + } else if (ops->vidioc_try_ext_pix_fmt_vid_cap) { >> + return v4l_try_fmt_ext_pix(ops, file, fh, p); >> + } >> + break; >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY: >> if (unlikely(!ops->vidioc_try_fmt_vid_out_overlay)) >> break; >> @@ -1852,6 +2235,49 @@ static int v4l_try_fmt(const struct v4l2_ioctl_ops *ops, >> return -EINVAL; >> } >> >> +static int v4l_try_ext_pix_fmt(const struct v4l2_ioctl_ops *ops, >> + struct file *file, void *fh, void *arg) >> +{ >> + struct video_device *vfd = video_devdata(file); >> + struct v4l2_ext_pix_format *ef = arg; >> + struct v4l2_format f; >> + int ret; >> + >> + ret = check_fmt(file, ef->type); >> + if (ret) >> + return ret; >> + >> + switch (ef->type) { >> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> + if (ops->vidioc_try_ext_pix_fmt_vid_cap) >> + return ops->vidioc_try_ext_pix_fmt_vid_cap(file, fh, >> + ef); >> + break; >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> + if (ops->vidioc_try_ext_pix_fmt_vid_out) >> + return ops->vidioc_try_ext_pix_fmt_vid_out(file, fh, >> + ef); >> + break; >> + default: >> + return -EINVAL; >> + } >> + >> + ret = v4l2_ext_pix_format_to_format(ef, &f, >> + vfd->device_caps & >> + (V4L2_CAP_VIDEO_CAPTURE_MPLANE | >> + V4L2_CAP_VIDEO_OUTPUT_MPLANE | >> + V4L2_CAP_VIDEO_M2M_MPLANE), >> + false); >> + if (ret) >> + return ret; >> + >> + ret = v4l_try_fmt(ops, file, fh, &f); >> + if (ret) >> + return ret; >> + >> + return v4l2_format_to_ext_pix_format(&f, ef, true); >> +} >> + >> static int v4l_streamon(const struct v4l2_ioctl_ops *ops, >> struct file *file, void *fh, void *arg) >> { >> @@ -2771,7 +3197,9 @@ static const struct v4l2_ioctl_info v4l2_ioctls[] = { >> IOCTL_INFO(VIDIOC_QUERYCAP, v4l_querycap, v4l_print_querycap, 0), >> IOCTL_INFO(VIDIOC_ENUM_FMT, v4l_enum_fmt, v4l_print_fmtdesc, 0), >> IOCTL_INFO(VIDIOC_G_FMT, v4l_g_fmt, v4l_print_format, 0), >> + IOCTL_INFO(VIDIOC_G_EXT_PIX_FMT, v4l_g_ext_pix_fmt, v4l_print_ext_pix_format, 0), >> IOCTL_INFO(VIDIOC_S_FMT, v4l_s_fmt, v4l_print_format, INFO_FL_PRIO), >> + IOCTL_INFO(VIDIOC_S_EXT_PIX_FMT, v4l_s_ext_pix_fmt, v4l_print_ext_pix_format, INFO_FL_PRIO), >> IOCTL_INFO(VIDIOC_REQBUFS, v4l_reqbufs, v4l_print_requestbuffers, INFO_FL_PRIO | INFO_FL_QUEUE), >> IOCTL_INFO(VIDIOC_QUERYBUF, v4l_querybuf, v4l_print_buffer, INFO_FL_QUEUE | INFO_FL_CLEAR(v4l2_buffer, length)), >> IOCTL_INFO(VIDIOC_G_FBUF, v4l_stub_g_fbuf, v4l_print_framebuffer, 0), >> @@ -2818,6 +3246,7 @@ static const struct v4l2_ioctl_info v4l2_ioctls[] = { >> IOCTL_INFO(VIDIOC_S_JPEGCOMP, v4l_stub_s_jpegcomp, v4l_print_jpegcompression, INFO_FL_PRIO), >> IOCTL_INFO(VIDIOC_QUERYSTD, v4l_querystd, v4l_print_std, 0), >> IOCTL_INFO(VIDIOC_TRY_FMT, v4l_try_fmt, v4l_print_format, 0), >> + IOCTL_INFO(VIDIOC_TRY_EXT_PIX_FMT, v4l_try_ext_pix_fmt, v4l_print_ext_pix_format, 0), >> IOCTL_INFO(VIDIOC_ENUMAUDIO, v4l_stub_enumaudio, v4l_print_audio, INFO_FL_CLEAR(v4l2_audio, index)), >> IOCTL_INFO(VIDIOC_ENUMAUDOUT, v4l_stub_enumaudout, v4l_print_audioout, INFO_FL_CLEAR(v4l2_audioout, index)), >> IOCTL_INFO(VIDIOC_G_PRIORITY, v4l_g_priority, v4l_print_u32, 0), >> diff --git a/include/media/v4l2-ioctl.h b/include/media/v4l2-ioctl.h >> index 86878fba332b0..8bbcb74d8ee31 100644 >> --- a/include/media/v4l2-ioctl.h >> +++ b/include/media/v4l2-ioctl.h >> @@ -48,11 +48,17 @@ struct v4l2_fh; >> * @vidioc_g_fmt_vid_cap: pointer to the function that implements >> * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video capture >> * in single plane mode >> + * @vidioc_g_ext_pix_fmt_vid_cap: pointer to the function that implements >> + * :ref:`VIDIOC_G_EXT_PIX_FMT <vidioc_g_ext_pix_fmt>` ioctl logic for video >> + * capture >> * @vidioc_g_fmt_vid_overlay: pointer to the function that implements >> * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video overlay >> * @vidioc_g_fmt_vid_out: pointer to the function that implements >> * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video out >> * in single plane mode >> + * @vidioc_g_ext_pix_fmt_vid_out: pointer to the function that implements >> + * :ref:`VIDIOC_G_EXT_PIX_FMT <vidioc_g_ext_pix_fmt>` ioctl logic for video >> + * out >> * @vidioc_g_fmt_vid_out_overlay: pointer to the function that implements >> * :ref:`VIDIOC_G_FMT <vidioc_g_fmt>` ioctl logic for video overlay output >> * @vidioc_g_fmt_vbi_cap: pointer to the function that implements >> @@ -82,11 +88,16 @@ struct v4l2_fh; >> * @vidioc_s_fmt_vid_cap: pointer to the function that implements >> * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video capture >> * in single plane mode >> + * @vidioc_s_ext_pix_fmt_vid_cap: pointer to the function that implements >> + * :ref:`VIDIOC_S_EXT_PIX_FMT <vidioc_g_ext_pix_fmt>` ioctl logic for video >> + * capture >> * @vidioc_s_fmt_vid_overlay: pointer to the function that implements >> * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video overlay >> * @vidioc_s_fmt_vid_out: pointer to the function that implements >> * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video out >> * in single plane mode >> + * @vidioc_s_ext_pix_fmt_vid_out: pointer to the function that implements >> + * :ref:`VIDIOC_S_EXT_PIX_FMT <vidioc_g_fmt>` ioctl logic for video out >> * @vidioc_s_fmt_vid_out_overlay: pointer to the function that implements >> * :ref:`VIDIOC_S_FMT <vidioc_g_fmt>` ioctl logic for video overlay output >> * @vidioc_s_fmt_vbi_cap: pointer to the function that implements >> @@ -116,11 +127,16 @@ struct v4l2_fh; >> * @vidioc_try_fmt_vid_cap: pointer to the function that implements >> * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video capture >> * in single plane mode >> + * @vidioc_try_ext_pix_fmt_vid_cap: pointer to the function that implements >> + * :ref:`VIDIOC_TRY_EXT_PIX_FMT <vidioc_g_ext_pix_fmt>` ioctl logic for >> + video capture >> * @vidioc_try_fmt_vid_overlay: pointer to the function that implements >> * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video overlay >> * @vidioc_try_fmt_vid_out: pointer to the function that implements >> * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video out >> * in single plane mode >> + * @vidioc_try_ext_pix_fmt_vid_out: pointer to the function that implements >> + * :ref:`VIDIOC_TRY_EXT_PIX_FMT <vidioc_g_fmt>` ioctl logic for video out >> * @vidioc_try_fmt_vid_out_overlay: pointer to the function that implements >> * :ref:`VIDIOC_TRY_FMT <vidioc_g_fmt>` ioctl logic for video overlay >> * output >> @@ -319,10 +335,14 @@ struct v4l2_ioctl_ops { >> /* VIDIOC_G_FMT handlers */ >> int (*vidioc_g_fmt_vid_cap)(struct file *file, void *fh, >> struct v4l2_format *f); >> + int (*vidioc_g_ext_pix_fmt_vid_cap)(struct file *file, void *fh, >> + struct v4l2_ext_pix_format *f); >> int (*vidioc_g_fmt_vid_overlay)(struct file *file, void *fh, >> struct v4l2_format *f); >> int (*vidioc_g_fmt_vid_out)(struct file *file, void *fh, >> struct v4l2_format *f); >> + int (*vidioc_g_ext_pix_fmt_vid_out)(struct file *file, void *fh, >> + struct v4l2_ext_pix_format *f); >> int (*vidioc_g_fmt_vid_out_overlay)(struct file *file, void *fh, >> struct v4l2_format *f); >> int (*vidioc_g_fmt_vbi_cap)(struct file *file, void *fh, >> @@ -349,10 +369,14 @@ struct v4l2_ioctl_ops { >> /* VIDIOC_S_FMT handlers */ >> int (*vidioc_s_fmt_vid_cap)(struct file *file, void *fh, >> struct v4l2_format *f); >> + int (*vidioc_s_ext_pix_fmt_vid_cap)(struct file *file, void *fh, >> + struct v4l2_ext_pix_format *f); >> int (*vidioc_s_fmt_vid_overlay)(struct file *file, void *fh, >> struct v4l2_format *f); >> int (*vidioc_s_fmt_vid_out)(struct file *file, void *fh, >> struct v4l2_format *f); >> + int (*vidioc_s_ext_pix_fmt_vid_out)(struct file *file, void *fh, >> + struct v4l2_ext_pix_format *f); >> int (*vidioc_s_fmt_vid_out_overlay)(struct file *file, void *fh, >> struct v4l2_format *f); >> int (*vidioc_s_fmt_vbi_cap)(struct file *file, void *fh, >> @@ -379,10 +403,14 @@ struct v4l2_ioctl_ops { >> /* VIDIOC_TRY_FMT handlers */ >> int (*vidioc_try_fmt_vid_cap)(struct file *file, void *fh, >> struct v4l2_format *f); >> + int (*vidioc_try_ext_pix_fmt_vid_cap)(struct file *file, void *fh, >> + struct v4l2_ext_pix_format *f); >> int (*vidioc_try_fmt_vid_overlay)(struct file *file, void *fh, >> struct v4l2_format *f); >> int (*vidioc_try_fmt_vid_out)(struct file *file, void *fh, >> struct v4l2_format *f); >> + int (*vidioc_try_ext_pix_fmt_vid_out)(struct file *file, void *fh, >> + struct v4l2_ext_pix_format *f); >> int (*vidioc_try_fmt_vid_out_overlay)(struct file *file, void *fh, >> struct v4l2_format *f); >> int (*vidioc_try_fmt_vbi_cap)(struct file *file, void *fh, >> @@ -724,6 +752,12 @@ long int video_usercopy(struct file *file, unsigned int cmd, >> long int video_ioctl2(struct file *file, >> unsigned int cmd, unsigned long int arg); >> >> +int v4l2_format_to_ext_pix_format(const struct v4l2_format *f, >> + struct v4l2_ext_pix_format *e, bool strict); >> +int v4l2_ext_pix_format_to_format(const struct v4l2_ext_pix_format *e, >> + struct v4l2_format *f, >> + bool mplane_cap, bool strict); >> + >> /* >> * The user space interpretation of the 'v4l2_event' differs >> * based on the 'time_t' definition on 32-bit architectures, so >> diff --git a/include/uapi/linux/videodev2.h b/include/uapi/linux/videodev2.h >> index c7b70ff53bc1d..7123c6a4d9569 100644 >> --- a/include/uapi/linux/videodev2.h >> +++ b/include/uapi/linux/videodev2.h >> @@ -2254,6 +2254,58 @@ struct v4l2_pix_format_mplane { >> __u8 reserved[7]; >> } __attribute__ ((packed)); >> >> +/** >> + * struct v4l2_plane_ext_pix_format - additional, per-plane format definition >> + * @sizeimage: maximum size in bytes required for data, for which >> + * this plane will be used. >> + * Should be set to zero for unused planes. >> + * @bytesperline: distance in bytes between the leftmost pixels in two >> + * adjacent lines >> + * @reserved: extra space reserved for future fields, must be set to 0 >> + */ >> +struct v4l2_plane_ext_pix_format { >> + __u32 sizeimage; >> + __u32 bytesperline; >> + __u32 reserved; > > Do we want to make this field a __u64 so the size of the struct is a > multiple of 64 bits? For next version, I'm reusing struct v4l2_plane_pix_format as suggested by Tomasz, so this adjustment won't be required. Thanks, Helen > > > >> +}; >> + >> +/** >> + * struct v4l2_ext_pix_format - extended single/multiplanar format definition >> + * @type: type of the data stream; V4L2_BUF_TYPE_VIDEO_CAPTURE or >> + * V4L2_BUF_TYPE_VIDEO_OUTPUT >> + * @width: image width in pixels >> + * @height: image height in pixels >> + * @field: enum v4l2_field; field order (for interlaced video) >> + * @pixelformat: little endian four character code (fourcc) >> + * @modifier: modifier applied to the format (used for tiled formats >> + * and other kind of HW-specific formats, like compressed >> + * formats) >> + * @colorspace: enum v4l2_colorspace; supplemental to pixelformat >> + * @plane_fmt: per-plane information >> + * @ycbcr_enc: enum v4l2_ycbcr_encoding, Y'CbCr encoding >> + * @hsv_enc: enum v4l2_hsv_encoding, HSV encoding >> + * @quantization: enum v4l2_quantization, colorspace quantization >> + * @xfer_func: enum v4l2_xfer_func, colorspace transfer function >> + * @reserved: extra space reserved for future fields, must be set to 0 >> + */ >> +struct v4l2_ext_pix_format { >> + __u32 type; >> + __u32 width; >> + __u32 height; >> + __u32 field; >> + __u64 modifier; >> + __u32 pixelformat; >> + __u32 colorspace; >> + struct v4l2_plane_ext_pix_format plane_fmt[VIDEO_MAX_PLANES]; >> + union { >> + __u32 ycbcr_enc; >> + __u32 hsv_enc; >> + }; >> + __u32 quantization; >> + __u32 xfer_func; >> + __u32 reserved[9]; >> +}; >> + >> /** >> * struct v4l2_sdr_format - SDR format definition >> * @pixelformat: little endian four character code (fourcc) >> @@ -2571,6 +2623,10 @@ struct v4l2_create_buffers { >> >> #define VIDIOC_QUERY_EXT_CTRL _IOWR('V', 103, struct v4l2_query_ext_ctrl) >> >> +#define VIDIOC_G_EXT_PIX_FMT _IOWR('V', 104, struct v4l2_ext_pix_format) >> +#define VIDIOC_S_EXT_PIX_FMT _IOWR('V', 105, struct v4l2_ext_pix_format) >> +#define VIDIOC_TRY_EXT_PIX_FMT _IOWR('V', 106, struct v4l2_ext_pix_format) >> + >> /* Reminder: when adding new ioctls please add support for them to >> drivers/media/v4l2-core/v4l2-compat-ioctl32.c as well! */ >> >> -- >> 2.28.0.rc2 >>
Hi Helen, On Tue, Aug 04, 2020 at 04:29:39PM -0300, Helen Koike wrote: > Add documentation and update references in current documentation for the > Extended API. > Thank you for the patch. Please see my comments inline. > Signed-off-by: Helen Koike <helen.koike@collabora.com> > --- > Changes in v5: > - new patch > > .../userspace-api/media/v4l/buffer.rst | 5 + > .../userspace-api/media/v4l/common.rst | 1 + > .../userspace-api/media/v4l/dev-capture.rst | 5 + > .../userspace-api/media/v4l/dev-output.rst | 5 + > .../userspace-api/media/v4l/ext-api.rst | 107 +++++++++ > .../userspace-api/media/v4l/format.rst | 16 +- > .../userspace-api/media/v4l/user-func.rst | 5 + > .../media/v4l/vidioc-ext-create-bufs.rst | 95 ++++++++ > .../media/v4l/vidioc-ext-prepare-buf.rst | 62 ++++++ > .../media/v4l/vidioc-ext-qbuf.rst | 204 ++++++++++++++++++ > .../media/v4l/vidioc-ext-querybuf.rst | 79 +++++++ > .../media/v4l/vidioc-g-ext-pix-fmt.rst | 117 ++++++++++ > 12 files changed, 697 insertions(+), 4 deletions(-) > create mode 100644 Documentation/userspace-api/media/v4l/ext-api.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst > > diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst > index 57e752aaf414a..c832bedd64e4c 100644 > --- a/Documentation/userspace-api/media/v4l/buffer.rst > +++ b/Documentation/userspace-api/media/v4l/buffer.rst > @@ -27,6 +27,11 @@ 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. > > +.. note:: > + > + The :ref:`ext_api` version can also be used, and it is > + preferable when applicable. Would rephrasing this as below making a bit more definitive? For modern applications, these operations are replaced by their :ref:`ext_api` counterparts, which should be used instead. > + > 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 > diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst > index 7d81c58a13cd7..3430e0bdad667 100644 > --- a/Documentation/userspace-api/media/v4l/common.rst > +++ b/Documentation/userspace-api/media/v4l/common.rst > @@ -59,6 +59,7 @@ applicable to all devices. > ext-ctrls-detect > fourcc > format > + ext-api > planar-apis > selection-api > crop > diff --git a/Documentation/userspace-api/media/v4l/dev-capture.rst b/Documentation/userspace-api/media/v4l/dev-capture.rst > index 44d3094093ab6..5077639787d92 100644 > --- a/Documentation/userspace-api/media/v4l/dev-capture.rst > +++ b/Documentation/userspace-api/media/v4l/dev-capture.rst > @@ -102,6 +102,11 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC > requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. > :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. > > +.. note:: > + > + The :ref:`ext_api` version can also be used, and it is > + preferable when applicable. > + > > Reading Images > ============== > diff --git a/Documentation/userspace-api/media/v4l/dev-output.rst b/Documentation/userspace-api/media/v4l/dev-output.rst > index e4f2a1d8b0fc7..f8f40c708e49f 100644 > --- a/Documentation/userspace-api/media/v4l/dev-output.rst > +++ b/Documentation/userspace-api/media/v4l/dev-output.rst > @@ -99,6 +99,11 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC > requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. > :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. > > +.. note:: > + > + The :ref:`ext_api` version can also be used, and it is > + preferable when applicable. > + > > Writing Images > ============== > diff --git a/Documentation/userspace-api/media/v4l/ext-api.rst b/Documentation/userspace-api/media/v4l/ext-api.rst > new file mode 100644 > index 0000000000000..da2a82960d22f > --- /dev/null > +++ b/Documentation/userspace-api/media/v4l/ext-api.rst > @@ -0,0 +1,107 @@ > +.. Permission is granted to copy, distribute and/or modify this > +.. document under the terms of the GNU Free Documentation License, > +.. Version 1.1 or any later version published by the Free Software > +.. Foundation, with no Invariant Sections, no Front-Cover Texts > +.. and no Back-Cover Texts. A copy of the license is included at > +.. Documentation/userspace-api/media/fdl-appendix.rst. > +.. > +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > + > +.. _ext_api: > + > +************* > +Extendend API > +************* > + > +Introduction > +============ > + > +The Extended Format API was conceived to extend V4L2 capabilities and > +to simplify certain mechanisms. > +It unifies single- vs multi- planar handling, > +brings the concept of pixelformat + modifiers, allows planes to be placed > +in any offset inside a buffer and let userspace to change colorspace > +attributes if supported by the driver. How about simplifying this paragraph a bit: The Extended Format API unifies single- and multi- planar format handling and provides a base for further functional extensions, such as format modifiers, arbitrary plane offsets, colorspace configuration. > + > +Data format negotiation and buffer handling works very similar to the classical > +version, thus in this document we'll just mention the main differences. nit: "we will" or maybe even just "we mention only the main differences". > + > +Data Format Negotiation > +======================= > + > +The API replaces the classical ioctls: > + > +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, > +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` > +(with :c:type:`v4l2_format` as the main parameter). > + > +By the extended versions: > + > +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>`, > +:ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>`, > +:ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` > +(with :c:type:`v4l2_ext_pix_format` as the main parameter). > + > +For CAPTURE and OUTPUT queues only. > + > +The ``type`` field of struct :c:type:`v4l2_ext_pix_format` only accepts > +``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, and it > +supports multiplanar format through a combination of ``pixelfomat`` and > +``modifier`` fields. > + > +Only the single-planar variants of the pixel formats are valid in the > +``pixelformat`` field. Some formats have only multi-planar variants, like NV12MT. What should we do about them? Since we have to keep those defines to support the legacy API anyway, maybe we can just accept both variants and treat them equally? > +To support multi-planar, a modifier should be set in the ``modifier`` field to > +provide more information regarding the memory layout of pixels and number of > +planes. > + > +The ``plane_fmt`` field is an array which holds information by plane using > +the :c:type:`v4l2_plane_ext_pix_format`. When this struct is filled, its > +``sizeimage`` field should be non-zero for all valid planes for a given > +``pixelformat`` + ``modifier`` combination, and zeroed for the invalid ones. > + > +Colospace attributes are not read-only as in the classical version, i.e, they > +can be set by application and drivers will adjust accordingly depending on what > +is supported by the underlying hardware. > + > +Buffers > +======= > + > +The API replaces the classical ioctls: > + > +:ref:`VIDIOC_CREATE_BUFS <VIDIOC_CREATE_BUFS>` > +(with :c:type:`v4l2_create_buffers` as the main parameter), > +:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, > +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_PREPARE_BUF <VIDIOC_PREPARE_BUF>` > +(with :c:type:`v4l2_buffer` as the main parameter) > + > +By the extended versions: > + > +:ref:`VIDIOC_EXT_CREATE_BUFS <VIDIOC_EXT_CREATE_BUFS>` > +(with :c:type:`v4l2_ext_create_buffers` as the main parameter), > +:ref:`VIDIOC_EXT_QUERYBUF <VIDIOC_EXT_QUERYBUF>`, > +:ref:`VIDIOC_EXT_QBUF <VIDIOC_EXT_QBUF>`, > +:ref:`VIDIOC_EXT_DQBUF <VIDIOC_EXT_QBUF>`, > +:ref:`VIDIOC_EXT_PREPARE_BUF <VIDIOC_EXT_PREPARE_BUF>` > +(with :c:type:`v4l2_ext_buffer` as the main parameter) > + > +The basic difference between :c:type:`v4l2_create_buffers` and > +:c:type:`v4l2_ext_create_buffers` is that the later have a > +:c:type:`v4l2_ext_pix_format` as the type of the ``format`` field. > + > +Comparing :c:type:`v4l2_ext_buffer` with :c:type:`v4l2_buffer`, in the > +extended version there is a unification of the single-/multi- planar handling > +through the ``planes`` field of type :c:type:`v4l2_ext_plane`. > + > +The :c:type:`v4l2_ext_plane also allows planes to be placed in a given offset > +inside a buffer. > +Planes can be placed in different locations inside the same buffer, or in > +different buffers. > + > + > +.. kernel-doc:: include/uapi/linux/videodev2.h > + :functions: v4l2_ext_plane > + > + > +.. kernel-doc:: include/uapi/linux/videodev2.h > + :functions: v4l2_ext_buffer > diff --git a/Documentation/userspace-api/media/v4l/format.rst b/Documentation/userspace-api/media/v4l/format.rst > index e47fc0505727c..b96d26f26793c 100644 > --- a/Documentation/userspace-api/media/v4l/format.rst > +++ b/Documentation/userspace-api/media/v4l/format.rst > @@ -28,13 +28,19 @@ format and the driver selects and reports the best the hardware can do > to satisfy the request. Of course applications can also just query the > current selection. > > -A single mechanism exists to negotiate all data formats using the > -aggregate struct :c:type:`v4l2_format` and the > +There are two mechanism to negociate data formats: negotiate > + > +The first one is using the aggregate struct :c:type:`v4l2_format` and the > :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and > :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the > :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine > what the hardware *could* do, without actually selecting a new data > -format. The data formats supported by the V4L2 API are covered in the > +format. > + > +The second is through the :ref:`ext_api`, please refer to its documentation > +for more information. > + Should we reverse the order to prefer the new API? > +The data formats supported by the V4L2 API are covered in the > respective device section in :ref:`devices`. For a closer look at > image formats see :ref:`pixfmt`. > > @@ -71,7 +77,9 @@ earlier versions of V4L2. Switching the logical stream or returning into > *may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. > > All drivers exchanging data with applications must support the > -:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the > +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl > +or the Extended respective versions (TODO: link). TODO? :) > +Implementation of the > :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. > > > diff --git a/Documentation/userspace-api/media/v4l/user-func.rst b/Documentation/userspace-api/media/v4l/user-func.rst > index bf77c842718e5..67b254812791c 100644 > --- a/Documentation/userspace-api/media/v4l/user-func.rst > +++ b/Documentation/userspace-api/media/v4l/user-func.rst > @@ -20,6 +20,7 @@ Function Reference > func-close > func-ioctl > vidioc-create-bufs > + vidioc-ext-create-bufs > vidioc-cropcap > vidioc-dbg-g-chip-info > vidioc-dbg-g-register > @@ -48,6 +49,7 @@ Function Reference > vidioc-g-ext-ctrls > vidioc-g-fbuf > vidioc-g-fmt > + vidioc-g-ext-pix-fmt > vidioc-g-frequency > vidioc-g-input > vidioc-g-jpegcomp > @@ -62,8 +64,11 @@ Function Reference > vidioc-log-status > vidioc-overlay > vidioc-prepare-buf > + vidioc-ext-prepare-buf > vidioc-qbuf > + vidioc-ext-qbuf > vidioc-querybuf > + vidioc-ext-querybuf > vidioc-querycap > vidioc-queryctrl > vidioc-query-dv-timings > diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst > new file mode 100644 > index 0000000000000..67f2c541e4d79 > --- /dev/null > +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst > @@ -0,0 +1,95 @@ > +.. Permission is granted to copy, distribute and/or modify this > +.. document under the terms of the GNU Free Documentation License, > +.. Version 1.1 or any later version published by the Free Software > +.. Foundation, with no Invariant Sections, no Front-Cover Texts > +.. and no Back-Cover Texts. A copy of the license is included at > +.. Documentation/userspace-api/media/fdl-appendix.rst. > +.. > +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > + TODO? :) > +.. _VIDIOC_EXT_CREATE_BUFS: > + > +**************************** > +ioctl VIDIOC_EXT_CREATE_BUFS > +**************************** > + > +Name > +==== > + > +VIDIOC_EXT_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O > + > + > +Synopsis > +======== > + > +.. c:function:: int ioctl( int fd, VIDIOC_EXT_CREATE_BUFS, struct v4l2_ext_create_buffers *argp ) > + :name: VIDIOC_EXT_CREATE_BUFS > + > + > +Arguments > +========= > + > +``fd`` > + File descriptor returned by :ref:`open() <func-open>`. > + > +``argp`` > + Pointer to struct :c:type:`v4l2_ext_create_buffers`. > + > + > +Description > +=========== > + > +This ioctl is used to create buffers for :ref:`memory mapped <mmap>` > +or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. > +This ioctl can be called multiple times to > +create buffers of different sizes. > + > +To allocate the device buffers applications must initialize the relevant > +fields of the struct :c:type:`v4l2_ext_create_buffers` structure. The > +``count`` field must be set to the number of requested buffers, the > +``memory`` field specifies the requested I/O method and the ``reserved`` > +array must be zeroed. > + > +The ``format`` field specifies the image format that the buffers must be > +able to handle. The application has to fill in this struct > +:c:type:`v4l2_format`. Usually this will be done using the > +:ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` or > +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctls to ensure that the > +requested format is supported by the driver. > +The driver may return an error if the size(s) are not supported by the > +hardware (usually because they are too small). > + > +The driver can create a memory buffer per plane, or a single memory buffer > +containing all the planes, with a minimum size according to the size > +defined by the ``format.plane_fmt[i].sizeimage`` field. > +Usually if the ``format.plane_fmt[i].sizeimage`` > +field is less than the minimum required for the given format, then an > +error will be returned since drivers will typically not allow this. If > +it is larger, then the value will be used as-is. In other words, the > +driver may reject the requested size, but if it is accepted the driver > +will use it unchanged. > + > +When the ioctl is called with a pointer to this structure the driver > +will attempt to allocate up to the requested number of buffers and store > +the actual number allocated and the starting index in the ``count`` and > +the ``index`` fields respectively. On return ``count`` can be smaller > +than the number requested. The 'capabilities' and 'flags' fields seem to go undocumented. > + > + > +.. kernel-doc:: include/uapi/linux/videodev2.h > + :functions: v4l2_ext_create_buffers > + > + > +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 <gen-errors>` chapter. > + > +ENOMEM > + No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O. > + > +EINVAL > + The buffer type (``format.type`` field), requested I/O method > + (``memory``) or format (``format`` field) is not valid. > diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst > new file mode 100644 > index 0000000000000..88e4b57121254 > --- /dev/null > +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst > @@ -0,0 +1,62 @@ > +.. Permission is granted to copy, distribute and/or modify this > +.. document under the terms of the GNU Free Documentation License, > +.. Version 1.1 or any later version published by the Free Software > +.. Foundation, with no Invariant Sections, no Front-Cover Texts > +.. and no Back-Cover Texts. A copy of the license is included at > +.. Documentation/userspace-api/media/fdl-appendix.rst. > +.. > +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > + > +.. _VIDIOC_EXT_PREPARE_BUF: > + > +**************************** > +ioctl VIDIOC_EXT_PREPARE_BUF > +**************************** > + > +Name > +==== > + > +VIDIOC_EXT_PREPARE_BUF - Prepare a buffer for I/O > + > + > +Synopsis > +======== > + > +.. c:function:: int ioctl( int fd, VIDIOC_EXT_PREPARE_BUF, struct v4l2_ext_buffer *argp ) > + :name: VIDIOC_EXT_PREPARE_BUF > + > + > +Arguments > +========= > + > +``fd`` > + File descriptor returned by :ref:`open() <func-open>`. > + > +``argp`` > + Pointer to struct :c:type:`v4l2_ext_buffer`. > + > + > +Description > +=========== > + > +Applications can optionally call the :ref:`VIDIOC_EXT_PREPARE_BUF` ioctl to > +pass ownership of the buffer to the driver before actually enqueuing it, > +using the :ref:`VIDIOC_EXT_QBUF <VIDIOC_EXT_QBUF>` ioctl, and to prepare it for future I/O. Such > +preparations may include cache invalidation or cleaning. Performing them > +in advance saves time during the actual I/O. > + > + > +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 <gen-errors>` chapter. > + > +EBUSY > + File I/O is in progress. > + > +EINVAL > + The buffer ``type`` is not supported, or the ``index`` is out of > + bounds, or no buffers have been allocated yet, or the ``userptr`` or > + ``length`` are invalid. > diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst > new file mode 100644 > index 0000000000000..083e106cf6bad > --- /dev/null > +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst > @@ -0,0 +1,204 @@ > +.. Permission is granted to copy, distribute and/or modify this > +.. document under the terms of the GNU Free Documentation License, > +.. Version 1.1 or any later version published by the Free Software > +.. Foundation, with no Invariant Sections, no Front-Cover Texts > +.. and no Back-Cover Texts. A copy of the license is included at > +.. Documentation/userspace-api/media/fdl-appendix.rst. > +.. > +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > + > +.. _VIDIOC_EXT_QBUF: > + > +*************************************** > +ioctl VIDIOC_EXT_QBUF, VIDIOC_EXT_DQBUF > +*************************************** > + > +Name > +==== > + > +VIDIOC_EXT_QBUF - VIDIOC_EXT_DQBUF - Exchange a buffer with the driver > + > + > +Synopsis > +======== > + > +.. c:function:: int ioctl( int fd, VIDIOC_EXT_QBUF, struct v4l2_ext_buffer *argp ) > + :name: VIDIOC_EXT_QBUF > + > +.. c:function:: int ioctl( int fd, VIDIOC_EXT_DQBUF, struct v4l2_ext_buffer *argp ) > + :name: VIDIOC_EXT_DQBUF > + > + > +Arguments > +========= > + > +``fd`` > + File descriptor returned by :ref:`open() <func-open>`. > + > +``argp`` > + Pointer to struct :c:type:`v4l2_ext_buffer`. > + > + > +Description > +=========== > + > +Applications call the ``VIDIOC_EXT_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 ``type`` field of a struct > +:c:type:`v4l2_ext_buffer` to the same buffer type as was > +previously used with struct :c:type:`v4l2_ext_pix_format` ``type``. > +Applications must also set the ``index`` field. Valid index numbers > +range from zero to the number of buffers allocated with > +:ref:`VIDIOC_EXT_CREATE_BUFS` (struct > +:c:type:`v4l2_ext_create_buffers` ``count``) minus > +one. The contents of the struct :c:type:`v4l2_ext_buffer` returned I think this might not be entirely accurate. One can call VIDIOC_EXT_CREATE_BUFS multiple times. Moreover, I don't think we've prohibited VIDIOC_REQBUFS for the ext API, or have we? > +by a :ref:`VIDIOC_EXT_QUERYBUF` ioctl will do as well. > +When the buffer is intended for output (``type`` is > +``V4L2_BUF_TYPE_VIDEO_OUTPUT``) applications must also initialize the > +``timestamp`` fields and the ``planes[i].plane_length`` for each valid plane, > +and invalid ones must be set as zero. > +see :ref:`buffer` for details. Applications must also set ``flags`` to 0. The > +``reserved`` field must be set to 0. > + > +To enqueue a :ref:`memory mapped <mmap>` buffer applications set the > +``planes[i].memory`` field to ``V4L2_MEMORY_MMAP`` in all the valid planes, > +and invalid ones must be set as zero. > +When ``VIDIOC_EXT_QBUF`` is called > +with a pointer to this structure the driver sets the > +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears > +the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an > +``EINVAL`` error code. > + > +To enqueue a :ref:`user pointer <userp>` buffer applications set the > +``planes[i].memory`` field to ``V4L2_MEMORY_USERPTR`` in all the valid planes, > +and invalid ones must be set as zero, the ``planes[i].m.userptr`` field to the > +address of the buffer,``planes[i].buffer_length`` to the size of the memory > +buffer, ``planes[i].plane_length`` to the size that should be used by the plane, > +and ``planes[i].offset`` of the plane in the memory buffer. Does offset make sense here if an arbitrary pointer can be given for the start of the plane? > + > +When ``VIDIOC_EXT_QBUF`` is called with a pointer to this structure > +the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the > +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the > +``flags`` field, or it returns an error code. This ioctl locks the This seems to be a copy of the text few lines above. > +memory pages of the buffer in physical memory, they cannot be swapped > +out to disk. Buffers remain locked until dequeued, until the > +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or > +:ref:`VIDIOC_EXT_CREATE_BUFS` ioctl is called, or until the > +device is closed. Why would CREATE_BUFS affect existing buffers? > + > +To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the > +``planes[i].memory`` field to ``V4L2_MEMORY_DMABUF`` in all the valid planes, > +and invalid ones must be set as zero, the ``planes[i].m.fd`` field to a > +file descriptor associated with a DMABUF buffer.,``planes[i].buffer_length`` to > +the size of the memory buffer, ``planes[i].plane_length`` to the size that What is the buffer_length field needed for? DMA-bufs by definition are kernel objects and the kernel should already know their sizes. > +should be used by the plane, and ``planes[i].offset`` of the plane in the memory buffer. > +When ``VIDIOC_EXT_QBUF`` is called with a pointer to this structure the driver > +sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the > +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the > +``flags`` field, or it returns an error code. This ioctl locks the Ditto. > +buffer. Locking a buffer means passing it to a driver for a hardware > +access (usually DMA). If an application accesses (reads/writes) a locked > +buffer then the result is undefined. Buffers remain locked until > +dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or > +:ref:`VIDIOC_EXT_CREATE_BUFS` ioctl is called, or until the > +device is closed. Ditto. > + > +The ``request_fd`` field can be used with the ``VIDIOC_EXT_QBUF`` ioctl to specify > +the file descriptor of a :ref:`request <media-request-api>`, if requests are > +in use. Setting it means that the buffer will not be passed to the driver > +until the request itself is queued. Also, the driver will apply any > +settings associated with the request for this buffer. This field will > +be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set. > +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. > + > +.. caution:: > + It is not allowed to mix queuing requests with queuing buffers directly. > + ``EBUSY`` will be returned if the first buffer was queued directly and > + then the application tries to queue a request, or vice versa. After > + closing the file descriptor, calling > + :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_EXT_CREATE_BUFS` > + the check for this will be reset. > + > + For :ref:`memory-to-memory devices <mem2mem>` you can specify the > + ``request_fd`` only for output buffers, not for capture buffers. Attempting > + to specify this for a capture buffer will result in an ``EBADR`` error. > + > +Applications call the ``VIDIOC_EXT_DQBUF`` ioctl to dequeue a filled > +(capturing) or displayed (output) buffer from the driver's outgoing "displayed" is quite inaccurate given that the majority of use cases for OUTPUT in V4L2 now are m2m devices. Maybe "consumed"? > +queue. They just set the ``type``, ``planes[i].memory`` and ``reserved`` fields of Why does the application have to set the memory field? It should be already known by the kernel which owns the buffer at the given time. > +a struct :c:type:`v4l2_ext_buffer` as above, when > +``VIDIOC_EXT_DQBUF`` is called with a pointer to this structure the driver > +fills the remaining fields or returns an error code. The driver may also > +set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a > +non-critical (recoverable) streaming error. In such case the application > +may continue as normal, but should be aware that data in the dequeued > +buffer might be corrupted. When using the multi-planar API, the planes > +array must be passed in as well. > + > +If the application sets the ``memory`` field to ``V4L2_MEMORY_DMABUF`` to > +dequeue a :ref:`DMABUF <dmabuf>` buffer, the driver fills the ``m.fd`` field > +with a file descriptor numerically the same as the one given to ``VIDIOC_EXT_QBUF`` > +when the buffer was enqueued. No new file descriptor is created at dequeue time > +and the value is only for the application convenience. Honestly, I don't like this aspect of the current API. It kind of implies that the value returned is valid, but the file descriptor might have been already closed. Could we just remove this and explicitly state that for DMA-buf, it is the user space responsibility to track the mapping between V4L2 indexes and its own buffer objects? > + > +By default ``VIDIOC_EXT_DQBUF`` blocks when no buffer is in the outgoing > +queue. When the ``O_NONBLOCK`` flag was given to the > +:ref:`open() <func-open>` function, ``VIDIOC_EXT_DQBUF`` returns > +immediately with an ``EAGAIN`` error code when no buffer is available. > + > + > +.. kernel-doc:: include/uapi/linux/videodev2.h > + :functions: v4l2_ext_buffers > + > + > +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 <gen-errors>` chapter. > + > +EAGAIN > + Non-blocking I/O has been selected using ``O_NONBLOCK`` and no > + buffer was in the outgoing queue. > + > +EINVAL > + The buffer ``type`` is not supported, or the ``index`` is out of > + bounds, or no buffers have been allocated yet, or the ``userptr`` or > + ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was There is no 'length' now. > + set but the the given ``request_fd`` was invalid, or ``m.fd`` was > + an invalid DMABUF file descriptor. > + > +EIO > + ``VIDIOC_EXT_DQBUF`` failed due to an internal error. Can also indicate > + temporary problems like signal loss. > + > + .. note:: > + > + The driver might dequeue an (empty) buffer despite returning > + an error, or even stop capturing. Reusing such buffer may be unsafe > + though and its details (e.g. ``index``) may not be returned either. > + It is recommended that drivers indicate recoverable errors by setting > + the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the > + application should be able to safely reuse the buffer and continue > + streaming. What is this for? It sounds like some legacy behavior, which maybe we could drop with this new API? > + > +EPIPE > + ``VIDIOC_EXT_DQBUF`` returns this on an empty capture queue for mem2mem > + codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already > + dequeued and no new buffers are expected to become available. > + > +EBADR > + The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not > + support requests for the given buffer type, or > + the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was not set but the device requires > + that the buffer is part of a request. > + > +EBUSY > + The first buffer was queued via a request, but the application now tries > + to queue it directly, or vice versa (it is not permitted to mix the two > + APIs). > diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst > new file mode 100644 > index 0000000000000..f2a12017253f6 > --- /dev/null > +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst > @@ -0,0 +1,79 @@ > +.. Permission is granted to copy, distribute and/or modify this > +.. document under the terms of the GNU Free Documentation License, > +.. Version 1.1 or any later version published by the Free Software > +.. Foundation, with no Invariant Sections, no Front-Cover Texts > +.. and no Back-Cover Texts. A copy of the license is included at > +.. Documentation/userspace-api/media/fdl-appendix.rst. > +.. > +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > + > +.. _VIDIOC_EXT_QUERYBUF: > + > +************************* > +ioctl VIDIOC_EXT_QUERYBUF > +************************* > + > +Name > +==== > + > +VIDIOC_EXT_QUERYBUF - Query the status of a buffer > + > + > +Synopsis > +======== > + > +.. c:function:: int ioctl( int fd, VIDIOC_EXT_QUERYBUF, struct v4l2_ext_buffer *argp ) > + :name: VIDIOC_EXT_QUERYBUF > + > + > +Arguments > +========= > + > +``fd`` > + File descriptor returned by :ref:`open() <func-open>`. > + > +``argp`` > + Pointer to struct :c:type:`v4l2_ext_buffer`. > + > + > +Description > +=========== > + > +This ioctl is part of the :ref:`streaming <mmap>` 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:`VIDIOC_EXT_CREATE_BUFS` ioctl. > + > +Applications set the ``type`` field of a struct > +:c:type:`v4l2_ext_buffer` to the same buffer type as was > +previously used with struct :c:type:`v4l2_ext_pix_format` ``type``, > +and the ``index`` field. Valid index numbers range from zero to the > +number of buffers allocated with > +:ref:`VIDIOC_EXT_CREATE_BUFS` (struct > +:c:type:`v4l2_ext_create_buffers` ``count``) minus > +one. The ``reserved`` field must be set to 0. > + > +In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``, > +``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and > +``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``planes.memory`` fields will be > +set to the current I/O method for each plane. > + > +For every valid plane, an entry in ``planes`` will be filled, and zeroed for > +invalid ones. ``planes[i].buffer_length`` is the size of the memory buffer > +which contains the plane, ``planes[i].plane_length`` is the length of the plane, What is the length of the plane here? It seems like depending on the context, the field can mean size of the payload (for filled buffer) or total space for the payload (for empty buffer), which is a bit confusing. > +and ``planes[i].offset` is where the plane is placed in the memory buffer. > + > +The size of the ``planes`` array can be calculated by the number of sequential > +planes with ``planes[i].buffer_length`` that differs from zero up to the max > +size of the array. Not sure if it's just me, but "size of array" sounds to me like the total memory size of the array, i.e. the max number of elements, which is fixed for this struct. How about "The entries of the planes array are valid up to the last entry with non-zero buffer_length or the last entry of the array, whichever is first." ? > + > + > +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 <gen-errors>` chapter. > + > +EINVAL > + The buffer ``type`` is not supported, or the ``index`` is out of > + bounds. > diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst > new file mode 100644 > index 0000000000000..008e6c98a88a5 > --- /dev/null > +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst > @@ -0,0 +1,117 @@ > +.. Permission is granted to copy, distribute and/or modify this > +.. document under the terms of the GNU Free Documentation License, > +.. Version 1.1 or any later version published by the Free Software > +.. Foundation, with no Invariant Sections, no Front-Cover Texts > +.. and no Back-Cover Texts. A copy of the license is included at > +.. Documentation/userspace-api/media/fdl-appendix.rst. > +.. > +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > + > +.. _VIDIOC_G_EXT_PIX_FMT: > + > +************************************************************************ > +ioctl VIDIOC_G_EXT_PIX_FMT, VIDIOC_S_EXT_PIX_FMT, VIDIOC_TRY_EXT_PIX_FMT > +************************************************************************ > + > +Name > +==== > + > +VIDIOC_G_EXT_PIX_FMT - VIDIOC_S_EXT_PIX_FMT - VIDIOC_TRY_EXT_PIX_FMT - Get or set the data format, try a format > + > + > +Synopsis > +======== > + > +.. c:function:: int ioctl( int fd, VIDIOC_G_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) > + :name: VIDIOC_G_EXT_PIX_FMT > + > +.. c:function:: int ioctl( int fd, VIDIOC_S_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) > + :name: VIDIOC_S_EXT_PIX_FMT > + > +.. c:function:: int ioctl( int fd, VIDIOC_TRY_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) > + :name: VIDIOC_TRY_EXT_PIX_FMT > + > +Arguments > +========= > + > +``fd`` > + File descriptor returned by :ref:`open() <func-open>`. > + > +``argp`` > + Pointer to struct :c:type:`v4l2_ext_pix_format`. > + > + > +Description > +=========== > + > +These ioctls are used to negotiate the format of data (typically image > +format) exchanged between driver and application. > + > +To query the current parameters applications set the ``type`` field of a > +struct :c:type:`v4l2_ext_pix_format` to ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or > +``V4L2_BUF_TYPE_VIDEO_OUTPUT``, all the other types are invalid in this API, > +and multiplanar is supported through modifiers. > + > +When the application calls the > +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl with a pointer to this > +structure the driver fills the other members. > +When the requested buffer type is not supported drivers return > +an ``EINVAL`` error code. > + > +To change the current format parameters applications initialize all > +the fields in the struct. > +For details see the documentation of the various devices types in > +:ref:`devices`. Good practice is to query the current parameters > +first, and to modify only those parameters not suitable for the > +application. When the application calls the :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl with > +a pointer to a struct :c:type:`v4l2_ext_pix_format` structure the driver > +checks and adjusts the parameters against hardware abilities. Drivers > +should not return an error code unless the ``type`` field is invalid, > +this is a mechanism to fathom device capabilities and to approach > +parameters acceptable for both the application and driver. On success > +the driver may program the hardware, allocate resources and generally > +prepare for data exchange. Finally the :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl returns > +the current format parameters as :ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` does. Very simple, > +inflexible devices may even ignore all input and always return the > +default parameters. However all V4L2 devices exchanging data with the > +application must implement the :ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` and :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` > +ioctl. When the requested buffer type is not supported drivers return an > +EINVAL error code on a :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` attempt. When I/O is already in > +progress or the resource is not available for other reasons drivers > +return the ``EBUSY`` error code. > + > +The :ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` with one > +exception: it does not change driver state. It can also be called at any > +time, never returning ``EBUSY``. This function is provided to negotiate > +parameters, to learn about hardware limitations, without disabling I/O > +or possibly time consuming hardware preparations. Although strongly > +recommended drivers are not required to implement this ioctl. > + Could we make this mandatory to avoid ambiguities in the API? In general, most drivers implemented it anyway, without much added complexity, because one can then simplify S_FMT to TRY_FMT + state update. Best regards, Tomasz
On 20/11/2020 12:06, Tomasz Figa wrote:z > Hi Helen, > > On Tue, Aug 04, 2020 at 04:29:39PM -0300, Helen Koike wrote: >> Add documentation and update references in current documentation for the >> Extended API. >> > > Thank you for the patch. Please see my comments inline. > >> Signed-off-by: Helen Koike <helen.koike@collabora.com> >> --- >> Changes in v5: >> - new patch >> >> .../userspace-api/media/v4l/buffer.rst | 5 + >> .../userspace-api/media/v4l/common.rst | 1 + >> .../userspace-api/media/v4l/dev-capture.rst | 5 + >> .../userspace-api/media/v4l/dev-output.rst | 5 + >> .../userspace-api/media/v4l/ext-api.rst | 107 +++++++++ >> .../userspace-api/media/v4l/format.rst | 16 +- >> .../userspace-api/media/v4l/user-func.rst | 5 + >> .../media/v4l/vidioc-ext-create-bufs.rst | 95 ++++++++ >> .../media/v4l/vidioc-ext-prepare-buf.rst | 62 ++++++ >> .../media/v4l/vidioc-ext-qbuf.rst | 204 ++++++++++++++++++ >> .../media/v4l/vidioc-ext-querybuf.rst | 79 +++++++ >> .../media/v4l/vidioc-g-ext-pix-fmt.rst | 117 ++++++++++ >> 12 files changed, 697 insertions(+), 4 deletions(-) >> create mode 100644 Documentation/userspace-api/media/v4l/ext-api.rst >> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst >> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst >> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst >> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst >> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst >> >> diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst >> index 57e752aaf414a..c832bedd64e4c 100644 >> --- a/Documentation/userspace-api/media/v4l/buffer.rst >> +++ b/Documentation/userspace-api/media/v4l/buffer.rst >> @@ -27,6 +27,11 @@ 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. >> >> +.. note:: >> + >> + The :ref:`ext_api` version can also be used, and it is >> + preferable when applicable. > > Would rephrasing this as below making a bit more definitive? > > For modern applications, these operations are replaced by their > :ref:`ext_api` counterparts, which should be used instead. You can't say that, since especially in the beginning userspace will be running on older kernels that do not support this. This will work: "should be used instead, if supported by the driver." > >> + >> 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 >> diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst >> index 7d81c58a13cd7..3430e0bdad667 100644 >> --- a/Documentation/userspace-api/media/v4l/common.rst >> +++ b/Documentation/userspace-api/media/v4l/common.rst >> @@ -59,6 +59,7 @@ applicable to all devices. >> ext-ctrls-detect >> fourcc >> format >> + ext-api >> planar-apis >> selection-api >> crop >> diff --git a/Documentation/userspace-api/media/v4l/dev-capture.rst b/Documentation/userspace-api/media/v4l/dev-capture.rst >> index 44d3094093ab6..5077639787d92 100644 >> --- a/Documentation/userspace-api/media/v4l/dev-capture.rst >> +++ b/Documentation/userspace-api/media/v4l/dev-capture.rst >> @@ -102,6 +102,11 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC >> requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. >> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. >> >> +.. note:: >> + >> + The :ref:`ext_api` version can also be used, and it is >> + preferable when applicable. >> + >> >> Reading Images >> ============== >> diff --git a/Documentation/userspace-api/media/v4l/dev-output.rst b/Documentation/userspace-api/media/v4l/dev-output.rst >> index e4f2a1d8b0fc7..f8f40c708e49f 100644 >> --- a/Documentation/userspace-api/media/v4l/dev-output.rst >> +++ b/Documentation/userspace-api/media/v4l/dev-output.rst >> @@ -99,6 +99,11 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC >> requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. >> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. >> >> +.. note:: >> + >> + The :ref:`ext_api` version can also be used, and it is >> + preferable when applicable. >> + >> >> Writing Images >> ============== >> diff --git a/Documentation/userspace-api/media/v4l/ext-api.rst b/Documentation/userspace-api/media/v4l/ext-api.rst >> new file mode 100644 >> index 0000000000000..da2a82960d22f >> --- /dev/null >> +++ b/Documentation/userspace-api/media/v4l/ext-api.rst >> @@ -0,0 +1,107 @@ >> +.. Permission is granted to copy, distribute and/or modify this >> +.. document under the terms of the GNU Free Documentation License, >> +.. Version 1.1 or any later version published by the Free Software >> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >> +.. and no Back-Cover Texts. A copy of the license is included at >> +.. Documentation/userspace-api/media/fdl-appendix.rst. >> +.. >> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >> + >> +.. _ext_api: >> + >> +************* >> +Extendend API >> +************* >> + >> +Introduction >> +============ >> + >> +The Extended Format API was conceived to extend V4L2 capabilities and >> +to simplify certain mechanisms. >> +It unifies single- vs multi- planar handling, >> +brings the concept of pixelformat + modifiers, allows planes to be placed >> +in any offset inside a buffer and let userspace to change colorspace >> +attributes if supported by the driver. > > How about simplifying this paragraph a bit: > > The Extended Format API unifies single- and multi- planar format handling > and provides a base for further functional extensions, such as format > modifiers, arbitrary plane offsets, colorspace configuration. Actually, I prefer Helen's version. > >> + >> +Data format negotiation and buffer handling works very similar to the classical >> +version, thus in this document we'll just mention the main differences. > > nit: "we will" or maybe even just "we mention only the main differences". > >> + >> +Data Format Negotiation >> +======================= >> + >> +The API replaces the classical ioctls: >> + >> +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, >> +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` >> +(with :c:type:`v4l2_format` as the main parameter). >> + >> +By the extended versions: >> + >> +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>`, >> +:ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>`, >> +:ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` >> +(with :c:type:`v4l2_ext_pix_format` as the main parameter). >> + >> +For CAPTURE and OUTPUT queues only. >> + >> +The ``type`` field of struct :c:type:`v4l2_ext_pix_format` only accepts >> +``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, and it >> +supports multiplanar format through a combination of ``pixelfomat`` and >> +``modifier`` fields. >> + >> +Only the single-planar variants of the pixel formats are valid in the >> +``pixelformat`` field. > > Some formats have only multi-planar variants, like NV12MT. What should we > do about them? Since we have to keep those defines to support the legacy > API anyway, maybe we can just accept both variants and treat them equally? Helen mentioned that as well in a reply to patch 1/7. I'll have a think about that myself and reply to that post because this is a good question. > >> +To support multi-planar, a modifier should be set in the ``modifier`` field to >> +provide more information regarding the memory layout of pixels and number of >> +planes. >> + >> +The ``plane_fmt`` field is an array which holds information by plane using >> +the :c:type:`v4l2_plane_ext_pix_format`. When this struct is filled, its >> +``sizeimage`` field should be non-zero for all valid planes for a given >> +``pixelformat`` + ``modifier`` combination, and zeroed for the invalid ones. >> + >> +Colospace attributes are not read-only as in the classical version, i.e, they >> +can be set by application and drivers will adjust accordingly depending on what >> +is supported by the underlying hardware. >> + >> +Buffers >> +======= >> + >> +The API replaces the classical ioctls: >> + >> +:ref:`VIDIOC_CREATE_BUFS <VIDIOC_CREATE_BUFS>` >> +(with :c:type:`v4l2_create_buffers` as the main parameter), >> +:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, >> +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_PREPARE_BUF <VIDIOC_PREPARE_BUF>` >> +(with :c:type:`v4l2_buffer` as the main parameter) >> + >> +By the extended versions: >> + >> +:ref:`VIDIOC_EXT_CREATE_BUFS <VIDIOC_EXT_CREATE_BUFS>` >> +(with :c:type:`v4l2_ext_create_buffers` as the main parameter), >> +:ref:`VIDIOC_EXT_QUERYBUF <VIDIOC_EXT_QUERYBUF>`, >> +:ref:`VIDIOC_EXT_QBUF <VIDIOC_EXT_QBUF>`, >> +:ref:`VIDIOC_EXT_DQBUF <VIDIOC_EXT_QBUF>`, >> +:ref:`VIDIOC_EXT_PREPARE_BUF <VIDIOC_EXT_PREPARE_BUF>` >> +(with :c:type:`v4l2_ext_buffer` as the main parameter) >> + >> +The basic difference between :c:type:`v4l2_create_buffers` and >> +:c:type:`v4l2_ext_create_buffers` is that the later have a >> +:c:type:`v4l2_ext_pix_format` as the type of the ``format`` field. >> + >> +Comparing :c:type:`v4l2_ext_buffer` with :c:type:`v4l2_buffer`, in the >> +extended version there is a unification of the single-/multi- planar handling >> +through the ``planes`` field of type :c:type:`v4l2_ext_plane`. >> + >> +The :c:type:`v4l2_ext_plane also allows planes to be placed in a given offset >> +inside a buffer. >> +Planes can be placed in different locations inside the same buffer, or in >> +different buffers. >> + >> + >> +.. kernel-doc:: include/uapi/linux/videodev2.h >> + :functions: v4l2_ext_plane >> + >> + >> +.. kernel-doc:: include/uapi/linux/videodev2.h >> + :functions: v4l2_ext_buffer >> diff --git a/Documentation/userspace-api/media/v4l/format.rst b/Documentation/userspace-api/media/v4l/format.rst >> index e47fc0505727c..b96d26f26793c 100644 >> --- a/Documentation/userspace-api/media/v4l/format.rst >> +++ b/Documentation/userspace-api/media/v4l/format.rst >> @@ -28,13 +28,19 @@ format and the driver selects and reports the best the hardware can do >> to satisfy the request. Of course applications can also just query the >> current selection. >> >> -A single mechanism exists to negotiate all data formats using the >> -aggregate struct :c:type:`v4l2_format` and the >> +There are two mechanism to negociate data formats: > > negotiate > >> + >> +The first one is using the aggregate struct :c:type:`v4l2_format` and the >> :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and >> :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the >> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine >> what the hardware *could* do, without actually selecting a new data >> -format. The data formats supported by the V4L2 API are covered in the >> +format. >> + >> +The second is through the :ref:`ext_api`, please refer to its documentation >> +for more information. >> + > > Should we reverse the order to prefer the new API? > >> +The data formats supported by the V4L2 API are covered in the >> respective device section in :ref:`devices`. For a closer look at >> image formats see :ref:`pixfmt`. >> >> @@ -71,7 +77,9 @@ earlier versions of V4L2. Switching the logical stream or returning into >> *may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. >> >> All drivers exchanging data with applications must support the >> -:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the >> +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl >> +or the Extended respective versions (TODO: link). > > TODO? :) > >> +Implementation of the >> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. >> >> >> diff --git a/Documentation/userspace-api/media/v4l/user-func.rst b/Documentation/userspace-api/media/v4l/user-func.rst >> index bf77c842718e5..67b254812791c 100644 >> --- a/Documentation/userspace-api/media/v4l/user-func.rst >> +++ b/Documentation/userspace-api/media/v4l/user-func.rst >> @@ -20,6 +20,7 @@ Function Reference >> func-close >> func-ioctl >> vidioc-create-bufs >> + vidioc-ext-create-bufs >> vidioc-cropcap >> vidioc-dbg-g-chip-info >> vidioc-dbg-g-register >> @@ -48,6 +49,7 @@ Function Reference >> vidioc-g-ext-ctrls >> vidioc-g-fbuf >> vidioc-g-fmt >> + vidioc-g-ext-pix-fmt >> vidioc-g-frequency >> vidioc-g-input >> vidioc-g-jpegcomp >> @@ -62,8 +64,11 @@ Function Reference >> vidioc-log-status >> vidioc-overlay >> vidioc-prepare-buf >> + vidioc-ext-prepare-buf >> vidioc-qbuf >> + vidioc-ext-qbuf >> vidioc-querybuf >> + vidioc-ext-querybuf >> vidioc-querycap >> vidioc-queryctrl >> vidioc-query-dv-timings >> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst >> new file mode 100644 >> index 0000000000000..67f2c541e4d79 >> --- /dev/null >> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst >> @@ -0,0 +1,95 @@ >> +.. Permission is granted to copy, distribute and/or modify this >> +.. document under the terms of the GNU Free Documentation License, >> +.. Version 1.1 or any later version published by the Free Software >> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >> +.. and no Back-Cover Texts. A copy of the license is included at >> +.. Documentation/userspace-api/media/fdl-appendix.rst. >> +.. >> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >> + > > TODO? :) > >> +.. _VIDIOC_EXT_CREATE_BUFS: >> + >> +**************************** >> +ioctl VIDIOC_EXT_CREATE_BUFS >> +**************************** >> + >> +Name >> +==== >> + >> +VIDIOC_EXT_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O >> + >> + >> +Synopsis >> +======== >> + >> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_CREATE_BUFS, struct v4l2_ext_create_buffers *argp ) >> + :name: VIDIOC_EXT_CREATE_BUFS >> + >> + >> +Arguments >> +========= >> + >> +``fd`` >> + File descriptor returned by :ref:`open() <func-open>`. >> + >> +``argp`` >> + Pointer to struct :c:type:`v4l2_ext_create_buffers`. >> + >> + >> +Description >> +=========== >> + >> +This ioctl is used to create buffers for :ref:`memory mapped <mmap>` >> +or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. >> +This ioctl can be called multiple times to >> +create buffers of different sizes. >> + >> +To allocate the device buffers applications must initialize the relevant >> +fields of the struct :c:type:`v4l2_ext_create_buffers` structure. The >> +``count`` field must be set to the number of requested buffers, the >> +``memory`` field specifies the requested I/O method and the ``reserved`` >> +array must be zeroed. >> + >> +The ``format`` field specifies the image format that the buffers must be >> +able to handle. The application has to fill in this struct >> +:c:type:`v4l2_format`. Usually this will be done using the >> +:ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` or >> +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctls to ensure that the >> +requested format is supported by the driver. >> +The driver may return an error if the size(s) are not supported by the >> +hardware (usually because they are too small). >> + >> +The driver can create a memory buffer per plane, or a single memory buffer >> +containing all the planes, with a minimum size according to the size >> +defined by the ``format.plane_fmt[i].sizeimage`` field. >> +Usually if the ``format.plane_fmt[i].sizeimage`` >> +field is less than the minimum required for the given format, then an >> +error will be returned since drivers will typically not allow this. If >> +it is larger, then the value will be used as-is. In other words, the >> +driver may reject the requested size, but if it is accepted the driver >> +will use it unchanged. >> + >> +When the ioctl is called with a pointer to this structure the driver >> +will attempt to allocate up to the requested number of buffers and store >> +the actual number allocated and the starting index in the ``count`` and >> +the ``index`` fields respectively. On return ``count`` can be smaller >> +than the number requested. > > The 'capabilities' and 'flags' fields seem to go undocumented. > >> + >> + >> +.. kernel-doc:: include/uapi/linux/videodev2.h >> + :functions: v4l2_ext_create_buffers >> + >> + >> +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 <gen-errors>` chapter. >> + >> +ENOMEM >> + No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O. >> + >> +EINVAL >> + The buffer type (``format.type`` field), requested I/O method >> + (``memory``) or format (``format`` field) is not valid. >> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst >> new file mode 100644 >> index 0000000000000..88e4b57121254 >> --- /dev/null >> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst >> @@ -0,0 +1,62 @@ >> +.. Permission is granted to copy, distribute and/or modify this >> +.. document under the terms of the GNU Free Documentation License, >> +.. Version 1.1 or any later version published by the Free Software >> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >> +.. and no Back-Cover Texts. A copy of the license is included at >> +.. Documentation/userspace-api/media/fdl-appendix.rst. >> +.. >> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >> + >> +.. _VIDIOC_EXT_PREPARE_BUF: >> + >> +**************************** >> +ioctl VIDIOC_EXT_PREPARE_BUF >> +**************************** >> + >> +Name >> +==== >> + >> +VIDIOC_EXT_PREPARE_BUF - Prepare a buffer for I/O >> + >> + >> +Synopsis >> +======== >> + >> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_PREPARE_BUF, struct v4l2_ext_buffer *argp ) >> + :name: VIDIOC_EXT_PREPARE_BUF >> + >> + >> +Arguments >> +========= >> + >> +``fd`` >> + File descriptor returned by :ref:`open() <func-open>`. >> + >> +``argp`` >> + Pointer to struct :c:type:`v4l2_ext_buffer`. >> + >> + >> +Description >> +=========== >> + >> +Applications can optionally call the :ref:`VIDIOC_EXT_PREPARE_BUF` ioctl to >> +pass ownership of the buffer to the driver before actually enqueuing it, >> +using the :ref:`VIDIOC_EXT_QBUF <VIDIOC_EXT_QBUF>` ioctl, and to prepare it for future I/O. Such >> +preparations may include cache invalidation or cleaning. Performing them >> +in advance saves time during the actual I/O. >> + >> + >> +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 <gen-errors>` chapter. >> + >> +EBUSY >> + File I/O is in progress. >> + >> +EINVAL >> + The buffer ``type`` is not supported, or the ``index`` is out of >> + bounds, or no buffers have been allocated yet, or the ``userptr`` or >> + ``length`` are invalid. >> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst >> new file mode 100644 >> index 0000000000000..083e106cf6bad >> --- /dev/null >> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst >> @@ -0,0 +1,204 @@ >> +.. Permission is granted to copy, distribute and/or modify this >> +.. document under the terms of the GNU Free Documentation License, >> +.. Version 1.1 or any later version published by the Free Software >> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >> +.. and no Back-Cover Texts. A copy of the license is included at >> +.. Documentation/userspace-api/media/fdl-appendix.rst. >> +.. >> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >> + >> +.. _VIDIOC_EXT_QBUF: >> + >> +*************************************** >> +ioctl VIDIOC_EXT_QBUF, VIDIOC_EXT_DQBUF >> +*************************************** >> + >> +Name >> +==== >> + >> +VIDIOC_EXT_QBUF - VIDIOC_EXT_DQBUF - Exchange a buffer with the driver >> + >> + >> +Synopsis >> +======== >> + >> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_QBUF, struct v4l2_ext_buffer *argp ) >> + :name: VIDIOC_EXT_QBUF >> + >> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_DQBUF, struct v4l2_ext_buffer *argp ) >> + :name: VIDIOC_EXT_DQBUF >> + >> + >> +Arguments >> +========= >> + >> +``fd`` >> + File descriptor returned by :ref:`open() <func-open>`. >> + >> +``argp`` >> + Pointer to struct :c:type:`v4l2_ext_buffer`. >> + >> + >> +Description >> +=========== >> + >> +Applications call the ``VIDIOC_EXT_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 ``type`` field of a struct >> +:c:type:`v4l2_ext_buffer` to the same buffer type as was >> +previously used with struct :c:type:`v4l2_ext_pix_format` ``type``. >> +Applications must also set the ``index`` field. Valid index numbers >> +range from zero to the number of buffers allocated with >> +:ref:`VIDIOC_EXT_CREATE_BUFS` (struct >> +:c:type:`v4l2_ext_create_buffers` ``count``) minus >> +one. The contents of the struct :c:type:`v4l2_ext_buffer` returned > > I think this might not be entirely accurate. One can call > VIDIOC_EXT_CREATE_BUFS multiple times. Moreover, I don't think we've > prohibited VIDIOC_REQBUFS for the ext API, or have we? > >> +by a :ref:`VIDIOC_EXT_QUERYBUF` ioctl will do as well. >> +When the buffer is intended for output (``type`` is >> +``V4L2_BUF_TYPE_VIDEO_OUTPUT``) applications must also initialize the >> +``timestamp`` fields and the ``planes[i].plane_length`` for each valid plane, >> +and invalid ones must be set as zero. >> +see :ref:`buffer` for details. Applications must also set ``flags`` to 0. The >> +``reserved`` field must be set to 0. >> + >> +To enqueue a :ref:`memory mapped <mmap>` buffer applications set the >> +``planes[i].memory`` field to ``V4L2_MEMORY_MMAP`` in all the valid planes, >> +and invalid ones must be set as zero. >> +When ``VIDIOC_EXT_QBUF`` is called >> +with a pointer to this structure the driver sets the >> +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears >> +the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an >> +``EINVAL`` error code. >> + >> +To enqueue a :ref:`user pointer <userp>` buffer applications set the >> +``planes[i].memory`` field to ``V4L2_MEMORY_USERPTR`` in all the valid planes, >> +and invalid ones must be set as zero, the ``planes[i].m.userptr`` field to the >> +address of the buffer,``planes[i].buffer_length`` to the size of the memory >> +buffer, ``planes[i].plane_length`` to the size that should be used by the plane, >> +and ``planes[i].offset`` of the plane in the memory buffer. > > Does offset make sense here if an arbitrary pointer can be given for the > start of the plane? > >> + >> +When ``VIDIOC_EXT_QBUF`` is called with a pointer to this structure >> +the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the >> +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the >> +``flags`` field, or it returns an error code. This ioctl locks the > > This seems to be a copy of the text few lines above. > >> +memory pages of the buffer in physical memory, they cannot be swapped >> +out to disk. Buffers remain locked until dequeued, until the >> +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or >> +:ref:`VIDIOC_EXT_CREATE_BUFS` ioctl is called, or until the >> +device is closed. > > Why would CREATE_BUFS affect existing buffers? > >> + >> +To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the >> +``planes[i].memory`` field to ``V4L2_MEMORY_DMABUF`` in all the valid planes, >> +and invalid ones must be set as zero, the ``planes[i].m.fd`` field to a >> +file descriptor associated with a DMABUF buffer.,``planes[i].buffer_length`` to >> +the size of the memory buffer, ``planes[i].plane_length`` to the size that > > What is the buffer_length field needed for? DMA-bufs by definition are > kernel objects and the kernel should already know their sizes. See this discussion: https://patchwork.linuxtv.org/project/linux-media/patch/gh5kef5bkeel3o6b2dkgc2dfagu9klj4c0@4ax.com/ > >> +should be used by the plane, and ``planes[i].offset`` of the plane in the memory buffer. >> +When ``VIDIOC_EXT_QBUF`` is called with a pointer to this structure the driver >> +sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the >> +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the >> +``flags`` field, or it returns an error code. This ioctl locks the > > Ditto. > >> +buffer. Locking a buffer means passing it to a driver for a hardware >> +access (usually DMA). If an application accesses (reads/writes) a locked >> +buffer then the result is undefined. Buffers remain locked until >> +dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or >> +:ref:`VIDIOC_EXT_CREATE_BUFS` ioctl is called, or until the >> +device is closed. > > Ditto. > >> + >> +The ``request_fd`` field can be used with the ``VIDIOC_EXT_QBUF`` ioctl to specify >> +the file descriptor of a :ref:`request <media-request-api>`, if requests are >> +in use. Setting it means that the buffer will not be passed to the driver >> +until the request itself is queued. Also, the driver will apply any >> +settings associated with the request for this buffer. This field will >> +be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set. >> +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. >> + >> +.. caution:: >> + It is not allowed to mix queuing requests with queuing buffers directly. >> + ``EBUSY`` will be returned if the first buffer was queued directly and >> + then the application tries to queue a request, or vice versa. After >> + closing the file descriptor, calling >> + :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_EXT_CREATE_BUFS` >> + the check for this will be reset. >> + >> + For :ref:`memory-to-memory devices <mem2mem>` you can specify the >> + ``request_fd`` only for output buffers, not for capture buffers. Attempting >> + to specify this for a capture buffer will result in an ``EBADR`` error. >> + >> +Applications call the ``VIDIOC_EXT_DQBUF`` ioctl to dequeue a filled >> +(capturing) or displayed (output) buffer from the driver's outgoing > > "displayed" is quite inaccurate given that the majority of use cases for > OUTPUT in V4L2 now are m2m devices. Maybe "consumed"? > >> +queue. They just set the ``type``, ``planes[i].memory`` and ``reserved`` fields of > > Why does the application have to set the memory field? It should be already > known by the kernel which owns the buffer at the given time. > >> +a struct :c:type:`v4l2_ext_buffer` as above, when >> +``VIDIOC_EXT_DQBUF`` is called with a pointer to this structure the driver >> +fills the remaining fields or returns an error code. The driver may also >> +set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a >> +non-critical (recoverable) streaming error. In such case the application >> +may continue as normal, but should be aware that data in the dequeued >> +buffer might be corrupted. When using the multi-planar API, the planes >> +array must be passed in as well. >> + >> +If the application sets the ``memory`` field to ``V4L2_MEMORY_DMABUF`` to >> +dequeue a :ref:`DMABUF <dmabuf>` buffer, the driver fills the ``m.fd`` field >> +with a file descriptor numerically the same as the one given to ``VIDIOC_EXT_QBUF`` >> +when the buffer was enqueued. No new file descriptor is created at dequeue time >> +and the value is only for the application convenience. > > Honestly, I don't like this aspect of the current API. It kind of implies > that the value returned is valid, but the file descriptor might have been > already closed. Could we just remove this and explicitly state that for > DMA-buf, it is the user space responsibility to track the mapping between > V4L2 indexes and its own buffer objects? > >> + >> +By default ``VIDIOC_EXT_DQBUF`` blocks when no buffer is in the outgoing >> +queue. When the ``O_NONBLOCK`` flag was given to the >> +:ref:`open() <func-open>` function, ``VIDIOC_EXT_DQBUF`` returns >> +immediately with an ``EAGAIN`` error code when no buffer is available. >> + >> + >> +.. kernel-doc:: include/uapi/linux/videodev2.h >> + :functions: v4l2_ext_buffers >> + >> + >> +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 <gen-errors>` chapter. >> + >> +EAGAIN >> + Non-blocking I/O has been selected using ``O_NONBLOCK`` and no >> + buffer was in the outgoing queue. >> + >> +EINVAL >> + The buffer ``type`` is not supported, or the ``index`` is out of >> + bounds, or no buffers have been allocated yet, or the ``userptr`` or >> + ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was > > There is no 'length' now. > >> + set but the the given ``request_fd`` was invalid, or ``m.fd`` was >> + an invalid DMABUF file descriptor. >> + >> +EIO >> + ``VIDIOC_EXT_DQBUF`` failed due to an internal error. Can also indicate >> + temporary problems like signal loss. Drop the last sentence, -EIO should never be used for temporary problems like that. EIO really means that the DMA engine crashed and userspace will have to call STREAMOFF and try to restart the DMA with STREAMON. >> + >> + .. note:: >> + >> + The driver might dequeue an (empty) buffer despite returning >> + an error, or even stop capturing. Reusing such buffer may be unsafe >> + though and its details (e.g. ``index``) may not be returned either. The first part of this note is rather vague. I'm not sure what it meant with this. >> + It is recommended that drivers indicate recoverable errors by setting >> + the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the >> + application should be able to safely reuse the buffer and continue >> + streaming. > > What is this for? It sounds like some legacy behavior, which maybe we could > drop with this new API? No, V4L2_BUF_FLAG_ERROR is really needed. Some hardware can really have intermittent failures causing video frames to be corrupt. And yes, that's typically due to hardware bugs. It usually either happens when you start streaming or just intermittent, but it is not severe enough to stop streaming completely (that's the -EIO error due to a call to vb2_queue_error). It's also used when you stop streaming and pending buffers are returned to userspace. They are marked as ERROR since they don't contain any video, or only partial video (if the DMA was stopped midway a frame). > >> + >> +EPIPE >> + ``VIDIOC_EXT_DQBUF`` returns this on an empty capture queue for mem2mem >> + codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already >> + dequeued and no new buffers are expected to become available. >> + >> +EBADR >> + The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not >> + support requests for the given buffer type, or >> + the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was not set but the device requires >> + that the buffer is part of a request. >> + >> +EBUSY >> + The first buffer was queued via a request, but the application now tries >> + to queue it directly, or vice versa (it is not permitted to mix the two >> + APIs). >> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst >> new file mode 100644 >> index 0000000000000..f2a12017253f6 >> --- /dev/null >> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst >> @@ -0,0 +1,79 @@ >> +.. Permission is granted to copy, distribute and/or modify this >> +.. document under the terms of the GNU Free Documentation License, >> +.. Version 1.1 or any later version published by the Free Software >> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >> +.. and no Back-Cover Texts. A copy of the license is included at >> +.. Documentation/userspace-api/media/fdl-appendix.rst. >> +.. >> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >> + >> +.. _VIDIOC_EXT_QUERYBUF: >> + >> +************************* >> +ioctl VIDIOC_EXT_QUERYBUF >> +************************* >> + >> +Name >> +==== >> + >> +VIDIOC_EXT_QUERYBUF - Query the status of a buffer >> + >> + >> +Synopsis >> +======== >> + >> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_QUERYBUF, struct v4l2_ext_buffer *argp ) >> + :name: VIDIOC_EXT_QUERYBUF >> + >> + >> +Arguments >> +========= >> + >> +``fd`` >> + File descriptor returned by :ref:`open() <func-open>`. >> + >> +``argp`` >> + Pointer to struct :c:type:`v4l2_ext_buffer`. >> + >> + >> +Description >> +=========== >> + >> +This ioctl is part of the :ref:`streaming <mmap>` 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:`VIDIOC_EXT_CREATE_BUFS` ioctl. >> + >> +Applications set the ``type`` field of a struct >> +:c:type:`v4l2_ext_buffer` to the same buffer type as was >> +previously used with struct :c:type:`v4l2_ext_pix_format` ``type``, >> +and the ``index`` field. Valid index numbers range from zero to the >> +number of buffers allocated with >> +:ref:`VIDIOC_EXT_CREATE_BUFS` (struct >> +:c:type:`v4l2_ext_create_buffers` ``count``) minus >> +one. The ``reserved`` field must be set to 0. >> + >> +In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``, >> +``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and >> +``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``planes.memory`` fields will be >> +set to the current I/O method for each plane. >> + >> +For every valid plane, an entry in ``planes`` will be filled, and zeroed for >> +invalid ones. ``planes[i].buffer_length`` is the size of the memory buffer >> +which contains the plane, ``planes[i].plane_length`` is the length of the plane, > > What is the length of the plane here? It seems like depending on the > context, the field can mean size of the payload (for filled buffer) or > total space for the payload (for empty buffer), which is a bit confusing. > >> +and ``planes[i].offset` is where the plane is placed in the memory buffer. >> + >> +The size of the ``planes`` array can be calculated by the number of sequential >> +planes with ``planes[i].buffer_length`` that differs from zero up to the max >> +size of the array. > > Not sure if it's just me, but "size of array" sounds to me like the > total memory size of the array, i.e. the max number of elements, which > is fixed for this struct. How about > > "The entries of the planes array are valid up to the last entry with > non-zero buffer_length or the last entry of the array, whichever is > first." > > ? > >> + >> + >> +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 <gen-errors>` chapter. >> + >> +EINVAL >> + The buffer ``type`` is not supported, or the ``index`` is out of >> + bounds. >> diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst >> new file mode 100644 >> index 0000000000000..008e6c98a88a5 >> --- /dev/null >> +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst >> @@ -0,0 +1,117 @@ >> +.. Permission is granted to copy, distribute and/or modify this >> +.. document under the terms of the GNU Free Documentation License, >> +.. Version 1.1 or any later version published by the Free Software >> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >> +.. and no Back-Cover Texts. A copy of the license is included at >> +.. Documentation/userspace-api/media/fdl-appendix.rst. >> +.. >> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >> + >> +.. _VIDIOC_G_EXT_PIX_FMT: >> + >> +************************************************************************ >> +ioctl VIDIOC_G_EXT_PIX_FMT, VIDIOC_S_EXT_PIX_FMT, VIDIOC_TRY_EXT_PIX_FMT >> +************************************************************************ >> + >> +Name >> +==== >> + >> +VIDIOC_G_EXT_PIX_FMT - VIDIOC_S_EXT_PIX_FMT - VIDIOC_TRY_EXT_PIX_FMT - Get or set the data format, try a format >> + >> + >> +Synopsis >> +======== >> + >> +.. c:function:: int ioctl( int fd, VIDIOC_G_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) >> + :name: VIDIOC_G_EXT_PIX_FMT >> + >> +.. c:function:: int ioctl( int fd, VIDIOC_S_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) >> + :name: VIDIOC_S_EXT_PIX_FMT >> + >> +.. c:function:: int ioctl( int fd, VIDIOC_TRY_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) >> + :name: VIDIOC_TRY_EXT_PIX_FMT >> + >> +Arguments >> +========= >> + >> +``fd`` >> + File descriptor returned by :ref:`open() <func-open>`. >> + >> +``argp`` >> + Pointer to struct :c:type:`v4l2_ext_pix_format`. >> + >> + >> +Description >> +=========== >> + >> +These ioctls are used to negotiate the format of data (typically image >> +format) exchanged between driver and application. >> + >> +To query the current parameters applications set the ``type`` field of a >> +struct :c:type:`v4l2_ext_pix_format` to ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or >> +``V4L2_BUF_TYPE_VIDEO_OUTPUT``, all the other types are invalid in this API, >> +and multiplanar is supported through modifiers. >> + >> +When the application calls the >> +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl with a pointer to this >> +structure the driver fills the other members. >> +When the requested buffer type is not supported drivers return >> +an ``EINVAL`` error code. >> + >> +To change the current format parameters applications initialize all >> +the fields in the struct. >> +For details see the documentation of the various devices types in >> +:ref:`devices`. Good practice is to query the current parameters >> +first, and to modify only those parameters not suitable for the >> +application. When the application calls the :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl with >> +a pointer to a struct :c:type:`v4l2_ext_pix_format` structure the driver >> +checks and adjusts the parameters against hardware abilities. Drivers >> +should not return an error code unless the ``type`` field is invalid, >> +this is a mechanism to fathom device capabilities and to approach >> +parameters acceptable for both the application and driver. On success >> +the driver may program the hardware, allocate resources and generally >> +prepare for data exchange. Finally the :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl returns >> +the current format parameters as :ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` does. Very simple, >> +inflexible devices may even ignore all input and always return the >> +default parameters. However all V4L2 devices exchanging data with the >> +application must implement the :ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` and :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` >> +ioctl. When the requested buffer type is not supported drivers return an >> +EINVAL error code on a :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` attempt. When I/O is already in >> +progress or the resource is not available for other reasons drivers >> +return the ``EBUSY`` error code. >> + >> +The :ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` with one >> +exception: it does not change driver state. It can also be called at any >> +time, never returning ``EBUSY``. This function is provided to negotiate >> +parameters, to learn about hardware limitations, without disabling I/O >> +or possibly time consuming hardware preparations. Although strongly >> +recommended drivers are not required to implement this ioctl. >> + > > Could we make this mandatory to avoid ambiguities in the API? In Yes, please! > general, most drivers implemented it anyway, without much added > complexity, because one can then simplify S_FMT to TRY_FMT + state > update. Ideally we would also fix the ambiguous situation regarding TRY/S_FMT and unsupported pixelformats: some drivers will replace unsupported pixelformats with a valid pixelformat, others will return an error. v4l2-compliance warns about drivers that return an error and point to this very old thread: http://www.mail-archive.com/linux-media@vger.kernel.org/msg56550.html However, I'm not really sure if we can resolve this ambiguity. I believe that it is only older webcam drivers that return an error. Regards, Hans
On Fri, Nov 20, 2020 at 9:24 PM Hans Verkuil <hverkuil@xs4all.nl> wrote: > > On 20/11/2020 12:06, Tomasz Figa wrote:z > > Hi Helen, > > > > On Tue, Aug 04, 2020 at 04:29:39PM -0300, Helen Koike wrote: > >> Add documentation and update references in current documentation for the > >> Extended API. > >> > > > > Thank you for the patch. Please see my comments inline. > > > >> Signed-off-by: Helen Koike <helen.koike@collabora.com> > >> --- > >> Changes in v5: > >> - new patch > >> > >> .../userspace-api/media/v4l/buffer.rst | 5 + > >> .../userspace-api/media/v4l/common.rst | 1 + > >> .../userspace-api/media/v4l/dev-capture.rst | 5 + > >> .../userspace-api/media/v4l/dev-output.rst | 5 + > >> .../userspace-api/media/v4l/ext-api.rst | 107 +++++++++ > >> .../userspace-api/media/v4l/format.rst | 16 +- > >> .../userspace-api/media/v4l/user-func.rst | 5 + > >> .../media/v4l/vidioc-ext-create-bufs.rst | 95 ++++++++ > >> .../media/v4l/vidioc-ext-prepare-buf.rst | 62 ++++++ > >> .../media/v4l/vidioc-ext-qbuf.rst | 204 ++++++++++++++++++ > >> .../media/v4l/vidioc-ext-querybuf.rst | 79 +++++++ > >> .../media/v4l/vidioc-g-ext-pix-fmt.rst | 117 ++++++++++ > >> 12 files changed, 697 insertions(+), 4 deletions(-) > >> create mode 100644 Documentation/userspace-api/media/v4l/ext-api.rst > >> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst > >> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst > >> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst > >> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst > >> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst > >> > >> diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst > >> index 57e752aaf414a..c832bedd64e4c 100644 > >> --- a/Documentation/userspace-api/media/v4l/buffer.rst > >> +++ b/Documentation/userspace-api/media/v4l/buffer.rst > >> @@ -27,6 +27,11 @@ 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. > >> > >> +.. note:: > >> + > >> + The :ref:`ext_api` version can also be used, and it is > >> + preferable when applicable. > > > > Would rephrasing this as below making a bit more definitive? > > > > For modern applications, these operations are replaced by their > > :ref:`ext_api` counterparts, which should be used instead. > > You can't say that, since especially in the beginning userspace will be running > on older kernels that do not support this. > > This will work: "should be used instead, if supported by the driver." > With the wrappers that the patches provide, all drivers would support the new API, so this boils down to the kernel version only, not specific drivers. Agreed, though, that application developers must be made aware that the new API is only available in new kernels and old API must be used for compatibility with old kernels. > > > >> + > >> 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 > >> diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst > >> index 7d81c58a13cd7..3430e0bdad667 100644 > >> --- a/Documentation/userspace-api/media/v4l/common.rst > >> +++ b/Documentation/userspace-api/media/v4l/common.rst > >> @@ -59,6 +59,7 @@ applicable to all devices. > >> ext-ctrls-detect > >> fourcc > >> format > >> + ext-api > >> planar-apis > >> selection-api > >> crop > >> diff --git a/Documentation/userspace-api/media/v4l/dev-capture.rst b/Documentation/userspace-api/media/v4l/dev-capture.rst > >> index 44d3094093ab6..5077639787d92 100644 > >> --- a/Documentation/userspace-api/media/v4l/dev-capture.rst > >> +++ b/Documentation/userspace-api/media/v4l/dev-capture.rst > >> @@ -102,6 +102,11 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC > >> requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. > >> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. > >> > >> +.. note:: > >> + > >> + The :ref:`ext_api` version can also be used, and it is > >> + preferable when applicable. > >> + > >> > >> Reading Images > >> ============== > >> diff --git a/Documentation/userspace-api/media/v4l/dev-output.rst b/Documentation/userspace-api/media/v4l/dev-output.rst > >> index e4f2a1d8b0fc7..f8f40c708e49f 100644 > >> --- a/Documentation/userspace-api/media/v4l/dev-output.rst > >> +++ b/Documentation/userspace-api/media/v4l/dev-output.rst > >> @@ -99,6 +99,11 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC > >> requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. > >> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. > >> > >> +.. note:: > >> + > >> + The :ref:`ext_api` version can also be used, and it is > >> + preferable when applicable. > >> + > >> > >> Writing Images > >> ============== > >> diff --git a/Documentation/userspace-api/media/v4l/ext-api.rst b/Documentation/userspace-api/media/v4l/ext-api.rst > >> new file mode 100644 > >> index 0000000000000..da2a82960d22f > >> --- /dev/null > >> +++ b/Documentation/userspace-api/media/v4l/ext-api.rst > >> @@ -0,0 +1,107 @@ > >> +.. Permission is granted to copy, distribute and/or modify this > >> +.. document under the terms of the GNU Free Documentation License, > >> +.. Version 1.1 or any later version published by the Free Software > >> +.. Foundation, with no Invariant Sections, no Front-Cover Texts > >> +.. and no Back-Cover Texts. A copy of the license is included at > >> +.. Documentation/userspace-api/media/fdl-appendix.rst. > >> +.. > >> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > >> + > >> +.. _ext_api: > >> + > >> +************* > >> +Extendend API > >> +************* > >> + > >> +Introduction > >> +============ > >> + > >> +The Extended Format API was conceived to extend V4L2 capabilities and > >> +to simplify certain mechanisms. > >> +It unifies single- vs multi- planar handling, > >> +brings the concept of pixelformat + modifiers, allows planes to be placed > >> +in any offset inside a buffer and let userspace to change colorspace > >> +attributes if supported by the driver. > > > > How about simplifying this paragraph a bit: > > > > The Extended Format API unifies single- and multi- planar format handling > > and provides a base for further functional extensions, such as format > > modifiers, arbitrary plane offsets, colorspace configuration. > > Actually, I prefer Helen's version. > To me it's a lot of text to read to get the same information, but I won't insist. > > > >> + > >> +Data format negotiation and buffer handling works very similar to the classical > >> +version, thus in this document we'll just mention the main differences. > > > > nit: "we will" or maybe even just "we mention only the main differences". > > > >> + > >> +Data Format Negotiation > >> +======================= > >> + > >> +The API replaces the classical ioctls: > >> + > >> +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, > >> +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` > >> +(with :c:type:`v4l2_format` as the main parameter). > >> + > >> +By the extended versions: > >> + > >> +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>`, > >> +:ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>`, > >> +:ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` > >> +(with :c:type:`v4l2_ext_pix_format` as the main parameter). > >> + > >> +For CAPTURE and OUTPUT queues only. > >> + > >> +The ``type`` field of struct :c:type:`v4l2_ext_pix_format` only accepts > >> +``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, and it > >> +supports multiplanar format through a combination of ``pixelfomat`` and > >> +``modifier`` fields. > >> + > >> +Only the single-planar variants of the pixel formats are valid in the > >> +``pixelformat`` field. > > > > Some formats have only multi-planar variants, like NV12MT. What should we > > do about them? Since we have to keep those defines to support the legacy > > API anyway, maybe we can just accept both variants and treat them equally? > > Helen mentioned that as well in a reply to patch 1/7. I'll have a think about > that myself and reply to that post because this is a good question. > I'm thinking about it as well. :) > > > >> +To support multi-planar, a modifier should be set in the ``modifier`` field to > >> +provide more information regarding the memory layout of pixels and number of > >> +planes. > >> + > >> +The ``plane_fmt`` field is an array which holds information by plane using > >> +the :c:type:`v4l2_plane_ext_pix_format`. When this struct is filled, its > >> +``sizeimage`` field should be non-zero for all valid planes for a given > >> +``pixelformat`` + ``modifier`` combination, and zeroed for the invalid ones. > >> + > >> +Colospace attributes are not read-only as in the classical version, i.e, they > >> +can be set by application and drivers will adjust accordingly depending on what > >> +is supported by the underlying hardware. > >> + > >> +Buffers > >> +======= > >> + > >> +The API replaces the classical ioctls: > >> + > >> +:ref:`VIDIOC_CREATE_BUFS <VIDIOC_CREATE_BUFS>` > >> +(with :c:type:`v4l2_create_buffers` as the main parameter), > >> +:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, > >> +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_PREPARE_BUF <VIDIOC_PREPARE_BUF>` > >> +(with :c:type:`v4l2_buffer` as the main parameter) > >> + > >> +By the extended versions: > >> + > >> +:ref:`VIDIOC_EXT_CREATE_BUFS <VIDIOC_EXT_CREATE_BUFS>` > >> +(with :c:type:`v4l2_ext_create_buffers` as the main parameter), > >> +:ref:`VIDIOC_EXT_QUERYBUF <VIDIOC_EXT_QUERYBUF>`, > >> +:ref:`VIDIOC_EXT_QBUF <VIDIOC_EXT_QBUF>`, > >> +:ref:`VIDIOC_EXT_DQBUF <VIDIOC_EXT_QBUF>`, > >> +:ref:`VIDIOC_EXT_PREPARE_BUF <VIDIOC_EXT_PREPARE_BUF>` > >> +(with :c:type:`v4l2_ext_buffer` as the main parameter) > >> + > >> +The basic difference between :c:type:`v4l2_create_buffers` and > >> +:c:type:`v4l2_ext_create_buffers` is that the later have a > >> +:c:type:`v4l2_ext_pix_format` as the type of the ``format`` field. > >> + > >> +Comparing :c:type:`v4l2_ext_buffer` with :c:type:`v4l2_buffer`, in the > >> +extended version there is a unification of the single-/multi- planar handling > >> +through the ``planes`` field of type :c:type:`v4l2_ext_plane`. > >> + > >> +The :c:type:`v4l2_ext_plane also allows planes to be placed in a given offset > >> +inside a buffer. > >> +Planes can be placed in different locations inside the same buffer, or in > >> +different buffers. > >> + > >> + > >> +.. kernel-doc:: include/uapi/linux/videodev2.h > >> + :functions: v4l2_ext_plane > >> + > >> + > >> +.. kernel-doc:: include/uapi/linux/videodev2.h > >> + :functions: v4l2_ext_buffer > >> diff --git a/Documentation/userspace-api/media/v4l/format.rst b/Documentation/userspace-api/media/v4l/format.rst > >> index e47fc0505727c..b96d26f26793c 100644 > >> --- a/Documentation/userspace-api/media/v4l/format.rst > >> +++ b/Documentation/userspace-api/media/v4l/format.rst > >> @@ -28,13 +28,19 @@ format and the driver selects and reports the best the hardware can do > >> to satisfy the request. Of course applications can also just query the > >> current selection. > >> > >> -A single mechanism exists to negotiate all data formats using the > >> -aggregate struct :c:type:`v4l2_format` and the > >> +There are two mechanism to negociate data formats: > > > > negotiate > > > >> + > >> +The first one is using the aggregate struct :c:type:`v4l2_format` and the > >> :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and > >> :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the > >> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine > >> what the hardware *could* do, without actually selecting a new data > >> -format. The data formats supported by the V4L2 API are covered in the > >> +format. > >> + > >> +The second is through the :ref:`ext_api`, please refer to its documentation > >> +for more information. > >> + > > > > Should we reverse the order to prefer the new API? > > > >> +The data formats supported by the V4L2 API are covered in the > >> respective device section in :ref:`devices`. For a closer look at > >> image formats see :ref:`pixfmt`. > >> > >> @@ -71,7 +77,9 @@ earlier versions of V4L2. Switching the logical stream or returning into > >> *may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. > >> > >> All drivers exchanging data with applications must support the > >> -:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the > >> +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl > >> +or the Extended respective versions (TODO: link). > > > > TODO? :) > > > >> +Implementation of the > >> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. > >> > >> > >> diff --git a/Documentation/userspace-api/media/v4l/user-func.rst b/Documentation/userspace-api/media/v4l/user-func.rst > >> index bf77c842718e5..67b254812791c 100644 > >> --- a/Documentation/userspace-api/media/v4l/user-func.rst > >> +++ b/Documentation/userspace-api/media/v4l/user-func.rst > >> @@ -20,6 +20,7 @@ Function Reference > >> func-close > >> func-ioctl > >> vidioc-create-bufs > >> + vidioc-ext-create-bufs > >> vidioc-cropcap > >> vidioc-dbg-g-chip-info > >> vidioc-dbg-g-register > >> @@ -48,6 +49,7 @@ Function Reference > >> vidioc-g-ext-ctrls > >> vidioc-g-fbuf > >> vidioc-g-fmt > >> + vidioc-g-ext-pix-fmt > >> vidioc-g-frequency > >> vidioc-g-input > >> vidioc-g-jpegcomp > >> @@ -62,8 +64,11 @@ Function Reference > >> vidioc-log-status > >> vidioc-overlay > >> vidioc-prepare-buf > >> + vidioc-ext-prepare-buf > >> vidioc-qbuf > >> + vidioc-ext-qbuf > >> vidioc-querybuf > >> + vidioc-ext-querybuf > >> vidioc-querycap > >> vidioc-queryctrl > >> vidioc-query-dv-timings > >> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst > >> new file mode 100644 > >> index 0000000000000..67f2c541e4d79 > >> --- /dev/null > >> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst > >> @@ -0,0 +1,95 @@ > >> +.. Permission is granted to copy, distribute and/or modify this > >> +.. document under the terms of the GNU Free Documentation License, > >> +.. Version 1.1 or any later version published by the Free Software > >> +.. Foundation, with no Invariant Sections, no Front-Cover Texts > >> +.. and no Back-Cover Texts. A copy of the license is included at > >> +.. Documentation/userspace-api/media/fdl-appendix.rst. > >> +.. > >> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > >> + > > > > TODO? :) > > > >> +.. _VIDIOC_EXT_CREATE_BUFS: > >> + > >> +**************************** > >> +ioctl VIDIOC_EXT_CREATE_BUFS > >> +**************************** > >> + > >> +Name > >> +==== > >> + > >> +VIDIOC_EXT_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O > >> + > >> + > >> +Synopsis > >> +======== > >> + > >> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_CREATE_BUFS, struct v4l2_ext_create_buffers *argp ) > >> + :name: VIDIOC_EXT_CREATE_BUFS > >> + > >> + > >> +Arguments > >> +========= > >> + > >> +``fd`` > >> + File descriptor returned by :ref:`open() <func-open>`. > >> + > >> +``argp`` > >> + Pointer to struct :c:type:`v4l2_ext_create_buffers`. > >> + > >> + > >> +Description > >> +=========== > >> + > >> +This ioctl is used to create buffers for :ref:`memory mapped <mmap>` > >> +or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. > >> +This ioctl can be called multiple times to > >> +create buffers of different sizes. > >> + > >> +To allocate the device buffers applications must initialize the relevant > >> +fields of the struct :c:type:`v4l2_ext_create_buffers` structure. The > >> +``count`` field must be set to the number of requested buffers, the > >> +``memory`` field specifies the requested I/O method and the ``reserved`` > >> +array must be zeroed. > >> + > >> +The ``format`` field specifies the image format that the buffers must be > >> +able to handle. The application has to fill in this struct > >> +:c:type:`v4l2_format`. Usually this will be done using the > >> +:ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` or > >> +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctls to ensure that the > >> +requested format is supported by the driver. > >> +The driver may return an error if the size(s) are not supported by the > >> +hardware (usually because they are too small). > >> + > >> +The driver can create a memory buffer per plane, or a single memory buffer > >> +containing all the planes, with a minimum size according to the size > >> +defined by the ``format.plane_fmt[i].sizeimage`` field. > >> +Usually if the ``format.plane_fmt[i].sizeimage`` > >> +field is less than the minimum required for the given format, then an > >> +error will be returned since drivers will typically not allow this. If > >> +it is larger, then the value will be used as-is. In other words, the > >> +driver may reject the requested size, but if it is accepted the driver > >> +will use it unchanged. > >> + > >> +When the ioctl is called with a pointer to this structure the driver > >> +will attempt to allocate up to the requested number of buffers and store > >> +the actual number allocated and the starting index in the ``count`` and > >> +the ``index`` fields respectively. On return ``count`` can be smaller > >> +than the number requested. > > > > The 'capabilities' and 'flags' fields seem to go undocumented. > > > >> + > >> + > >> +.. kernel-doc:: include/uapi/linux/videodev2.h > >> + :functions: v4l2_ext_create_buffers > >> + > >> + > >> +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 <gen-errors>` chapter. > >> + > >> +ENOMEM > >> + No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O. > >> + > >> +EINVAL > >> + The buffer type (``format.type`` field), requested I/O method > >> + (``memory``) or format (``format`` field) is not valid. > >> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst > >> new file mode 100644 > >> index 0000000000000..88e4b57121254 > >> --- /dev/null > >> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst > >> @@ -0,0 +1,62 @@ > >> +.. Permission is granted to copy, distribute and/or modify this > >> +.. document under the terms of the GNU Free Documentation License, > >> +.. Version 1.1 or any later version published by the Free Software > >> +.. Foundation, with no Invariant Sections, no Front-Cover Texts > >> +.. and no Back-Cover Texts. A copy of the license is included at > >> +.. Documentation/userspace-api/media/fdl-appendix.rst. > >> +.. > >> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > >> + > >> +.. _VIDIOC_EXT_PREPARE_BUF: > >> + > >> +**************************** > >> +ioctl VIDIOC_EXT_PREPARE_BUF > >> +**************************** > >> + > >> +Name > >> +==== > >> + > >> +VIDIOC_EXT_PREPARE_BUF - Prepare a buffer for I/O > >> + > >> + > >> +Synopsis > >> +======== > >> + > >> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_PREPARE_BUF, struct v4l2_ext_buffer *argp ) > >> + :name: VIDIOC_EXT_PREPARE_BUF > >> + > >> + > >> +Arguments > >> +========= > >> + > >> +``fd`` > >> + File descriptor returned by :ref:`open() <func-open>`. > >> + > >> +``argp`` > >> + Pointer to struct :c:type:`v4l2_ext_buffer`. > >> + > >> + > >> +Description > >> +=========== > >> + > >> +Applications can optionally call the :ref:`VIDIOC_EXT_PREPARE_BUF` ioctl to > >> +pass ownership of the buffer to the driver before actually enqueuing it, > >> +using the :ref:`VIDIOC_EXT_QBUF <VIDIOC_EXT_QBUF>` ioctl, and to prepare it for future I/O. Such > >> +preparations may include cache invalidation or cleaning. Performing them > >> +in advance saves time during the actual I/O. > >> + > >> + > >> +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 <gen-errors>` chapter. > >> + > >> +EBUSY > >> + File I/O is in progress. > >> + > >> +EINVAL > >> + The buffer ``type`` is not supported, or the ``index`` is out of > >> + bounds, or no buffers have been allocated yet, or the ``userptr`` or > >> + ``length`` are invalid. > >> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst > >> new file mode 100644 > >> index 0000000000000..083e106cf6bad > >> --- /dev/null > >> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst > >> @@ -0,0 +1,204 @@ > >> +.. Permission is granted to copy, distribute and/or modify this > >> +.. document under the terms of the GNU Free Documentation License, > >> +.. Version 1.1 or any later version published by the Free Software > >> +.. Foundation, with no Invariant Sections, no Front-Cover Texts > >> +.. and no Back-Cover Texts. A copy of the license is included at > >> +.. Documentation/userspace-api/media/fdl-appendix.rst. > >> +.. > >> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > >> + > >> +.. _VIDIOC_EXT_QBUF: > >> + > >> +*************************************** > >> +ioctl VIDIOC_EXT_QBUF, VIDIOC_EXT_DQBUF > >> +*************************************** > >> + > >> +Name > >> +==== > >> + > >> +VIDIOC_EXT_QBUF - VIDIOC_EXT_DQBUF - Exchange a buffer with the driver > >> + > >> + > >> +Synopsis > >> +======== > >> + > >> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_QBUF, struct v4l2_ext_buffer *argp ) > >> + :name: VIDIOC_EXT_QBUF > >> + > >> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_DQBUF, struct v4l2_ext_buffer *argp ) > >> + :name: VIDIOC_EXT_DQBUF > >> + > >> + > >> +Arguments > >> +========= > >> + > >> +``fd`` > >> + File descriptor returned by :ref:`open() <func-open>`. > >> + > >> +``argp`` > >> + Pointer to struct :c:type:`v4l2_ext_buffer`. > >> + > >> + > >> +Description > >> +=========== > >> + > >> +Applications call the ``VIDIOC_EXT_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 ``type`` field of a struct > >> +:c:type:`v4l2_ext_buffer` to the same buffer type as was > >> +previously used with struct :c:type:`v4l2_ext_pix_format` ``type``. > >> +Applications must also set the ``index`` field. Valid index numbers > >> +range from zero to the number of buffers allocated with > >> +:ref:`VIDIOC_EXT_CREATE_BUFS` (struct > >> +:c:type:`v4l2_ext_create_buffers` ``count``) minus > >> +one. The contents of the struct :c:type:`v4l2_ext_buffer` returned > > > > I think this might not be entirely accurate. One can call > > VIDIOC_EXT_CREATE_BUFS multiple times. Moreover, I don't think we've > > prohibited VIDIOC_REQBUFS for the ext API, or have we? > > > >> +by a :ref:`VIDIOC_EXT_QUERYBUF` ioctl will do as well. > >> +When the buffer is intended for output (``type`` is > >> +``V4L2_BUF_TYPE_VIDEO_OUTPUT``) applications must also initialize the > >> +``timestamp`` fields and the ``planes[i].plane_length`` for each valid plane, > >> +and invalid ones must be set as zero. > >> +see :ref:`buffer` for details. Applications must also set ``flags`` to 0. The > >> +``reserved`` field must be set to 0. > >> + > >> +To enqueue a :ref:`memory mapped <mmap>` buffer applications set the > >> +``planes[i].memory`` field to ``V4L2_MEMORY_MMAP`` in all the valid planes, > >> +and invalid ones must be set as zero. > >> +When ``VIDIOC_EXT_QBUF`` is called > >> +with a pointer to this structure the driver sets the > >> +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears > >> +the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an > >> +``EINVAL`` error code. > >> + > >> +To enqueue a :ref:`user pointer <userp>` buffer applications set the > >> +``planes[i].memory`` field to ``V4L2_MEMORY_USERPTR`` in all the valid planes, > >> +and invalid ones must be set as zero, the ``planes[i].m.userptr`` field to the > >> +address of the buffer,``planes[i].buffer_length`` to the size of the memory > >> +buffer, ``planes[i].plane_length`` to the size that should be used by the plane, > >> +and ``planes[i].offset`` of the plane in the memory buffer. > > > > Does offset make sense here if an arbitrary pointer can be given for the > > start of the plane? > > > >> + > >> +When ``VIDIOC_EXT_QBUF`` is called with a pointer to this structure > >> +the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the > >> +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the > >> +``flags`` field, or it returns an error code. This ioctl locks the > > > > This seems to be a copy of the text few lines above. > > > >> +memory pages of the buffer in physical memory, they cannot be swapped > >> +out to disk. Buffers remain locked until dequeued, until the > >> +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or > >> +:ref:`VIDIOC_EXT_CREATE_BUFS` ioctl is called, or until the > >> +device is closed. > > > > Why would CREATE_BUFS affect existing buffers? > > > >> + > >> +To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the > >> +``planes[i].memory`` field to ``V4L2_MEMORY_DMABUF`` in all the valid planes, > >> +and invalid ones must be set as zero, the ``planes[i].m.fd`` field to a > >> +file descriptor associated with a DMABUF buffer.,``planes[i].buffer_length`` to > >> +the size of the memory buffer, ``planes[i].plane_length`` to the size that > > > > What is the buffer_length field needed for? DMA-bufs by definition are > > kernel objects and the kernel should already know their sizes. > > See this discussion: > > https://patchwork.linuxtv.org/project/linux-media/patch/gh5kef5bkeel3o6b2dkgc2dfagu9klj4c0@4ax.com/ > I briefly read through it and I don't see what the conclusion was. Generally I'd still prefer if the need to manually specify the buffer size was eliminated, because that imposes unnecessary burden on the userspace for the majority of cases. It could still remain valid for userspace that wants to restrict the buffer size as it was mentioned in that thread, though. > > > >> +should be used by the plane, and ``planes[i].offset`` of the plane in the memory buffer. > >> +When ``VIDIOC_EXT_QBUF`` is called with a pointer to this structure the driver > >> +sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the > >> +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the > >> +``flags`` field, or it returns an error code. This ioctl locks the > > > > Ditto. > > > >> +buffer. Locking a buffer means passing it to a driver for a hardware > >> +access (usually DMA). If an application accesses (reads/writes) a locked > >> +buffer then the result is undefined. Buffers remain locked until > >> +dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or > >> +:ref:`VIDIOC_EXT_CREATE_BUFS` ioctl is called, or until the > >> +device is closed. > > > > Ditto. > > > >> + > >> +The ``request_fd`` field can be used with the ``VIDIOC_EXT_QBUF`` ioctl to specify > >> +the file descriptor of a :ref:`request <media-request-api>`, if requests are > >> +in use. Setting it means that the buffer will not be passed to the driver > >> +until the request itself is queued. Also, the driver will apply any > >> +settings associated with the request for this buffer. This field will > >> +be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set. > >> +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. > >> + > >> +.. caution:: > >> + It is not allowed to mix queuing requests with queuing buffers directly. > >> + ``EBUSY`` will be returned if the first buffer was queued directly and > >> + then the application tries to queue a request, or vice versa. After > >> + closing the file descriptor, calling > >> + :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_EXT_CREATE_BUFS` > >> + the check for this will be reset. > >> + > >> + For :ref:`memory-to-memory devices <mem2mem>` you can specify the > >> + ``request_fd`` only for output buffers, not for capture buffers. Attempting > >> + to specify this for a capture buffer will result in an ``EBADR`` error. > >> + > >> +Applications call the ``VIDIOC_EXT_DQBUF`` ioctl to dequeue a filled > >> +(capturing) or displayed (output) buffer from the driver's outgoing > > > > "displayed" is quite inaccurate given that the majority of use cases for > > OUTPUT in V4L2 now are m2m devices. Maybe "consumed"? > > > >> +queue. They just set the ``type``, ``planes[i].memory`` and ``reserved`` fields of > > > > Why does the application have to set the memory field? It should be already > > known by the kernel which owns the buffer at the given time. > > > >> +a struct :c:type:`v4l2_ext_buffer` as above, when > >> +``VIDIOC_EXT_DQBUF`` is called with a pointer to this structure the driver > >> +fills the remaining fields or returns an error code. The driver may also > >> +set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a > >> +non-critical (recoverable) streaming error. In such case the application > >> +may continue as normal, but should be aware that data in the dequeued > >> +buffer might be corrupted. When using the multi-planar API, the planes > >> +array must be passed in as well. > >> + > >> +If the application sets the ``memory`` field to ``V4L2_MEMORY_DMABUF`` to > >> +dequeue a :ref:`DMABUF <dmabuf>` buffer, the driver fills the ``m.fd`` field > >> +with a file descriptor numerically the same as the one given to ``VIDIOC_EXT_QBUF`` > >> +when the buffer was enqueued. No new file descriptor is created at dequeue time > >> +and the value is only for the application convenience. > > > > Honestly, I don't like this aspect of the current API. It kind of implies > > that the value returned is valid, but the file descriptor might have been > > already closed. Could we just remove this and explicitly state that for > > DMA-buf, it is the user space responsibility to track the mapping between > > V4L2 indexes and its own buffer objects? > > > >> + > >> +By default ``VIDIOC_EXT_DQBUF`` blocks when no buffer is in the outgoing > >> +queue. When the ``O_NONBLOCK`` flag was given to the > >> +:ref:`open() <func-open>` function, ``VIDIOC_EXT_DQBUF`` returns > >> +immediately with an ``EAGAIN`` error code when no buffer is available. > >> + > >> + > >> +.. kernel-doc:: include/uapi/linux/videodev2.h > >> + :functions: v4l2_ext_buffers > >> + > >> + > >> +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 <gen-errors>` chapter. > >> + > >> +EAGAIN > >> + Non-blocking I/O has been selected using ``O_NONBLOCK`` and no > >> + buffer was in the outgoing queue. > >> + > >> +EINVAL > >> + The buffer ``type`` is not supported, or the ``index`` is out of > >> + bounds, or no buffers have been allocated yet, or the ``userptr`` or > >> + ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was > > > > There is no 'length' now. > > > >> + set but the the given ``request_fd`` was invalid, or ``m.fd`` was > >> + an invalid DMABUF file descriptor. > >> + > >> +EIO > >> + ``VIDIOC_EXT_DQBUF`` failed due to an internal error. Can also indicate > >> + temporary problems like signal loss. > > Drop the last sentence, -EIO should never be used for temporary problems like > that. EIO really means that the DMA engine crashed and userspace will have to call > STREAMOFF and try to restart the DMA with STREAMON. > I suspect the users of the new API wouldn't actually have to deal with a signal loss, but if not, what should be the behavior then? > >> + > >> + .. note:: > >> + > >> + The driver might dequeue an (empty) buffer despite returning > >> + an error, or even stop capturing. Reusing such buffer may be unsafe > >> + though and its details (e.g. ``index``) may not be returned either. > > The first part of this note is rather vague. I'm not sure what it meant with this. > > >> + It is recommended that drivers indicate recoverable errors by setting > >> + the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the > >> + application should be able to safely reuse the buffer and continue > >> + streaming. > > > > What is this for? It sounds like some legacy behavior, which maybe we could > > drop with this new API? > > No, V4L2_BUF_FLAG_ERROR is really needed. Some hardware can really have > intermittent failures causing video frames to be corrupt. And yes, that's > typically due to hardware bugs. It usually either happens when you start > streaming or just intermittent, but it is not severe enough to stop streaming > completely (that's the -EIO error due to a call to vb2_queue_error). > > It's also used when you stop streaming and pending buffers are returned to > userspace. They are marked as ERROR since they don't contain any video, or > only partial video (if the DMA was stopped midway a frame). > Sorry, I meant to insert that comment below the first half. The second half is fine. > > > >> + > >> +EPIPE > >> + ``VIDIOC_EXT_DQBUF`` returns this on an empty capture queue for mem2mem > >> + codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already > >> + dequeued and no new buffers are expected to become available. > >> + > >> +EBADR > >> + The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not > >> + support requests for the given buffer type, or > >> + the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was not set but the device requires > >> + that the buffer is part of a request. > >> + > >> +EBUSY > >> + The first buffer was queued via a request, but the application now tries > >> + to queue it directly, or vice versa (it is not permitted to mix the two > >> + APIs). > >> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst > >> new file mode 100644 > >> index 0000000000000..f2a12017253f6 > >> --- /dev/null > >> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst > >> @@ -0,0 +1,79 @@ > >> +.. Permission is granted to copy, distribute and/or modify this > >> +.. document under the terms of the GNU Free Documentation License, > >> +.. Version 1.1 or any later version published by the Free Software > >> +.. Foundation, with no Invariant Sections, no Front-Cover Texts > >> +.. and no Back-Cover Texts. A copy of the license is included at > >> +.. Documentation/userspace-api/media/fdl-appendix.rst. > >> +.. > >> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > >> + > >> +.. _VIDIOC_EXT_QUERYBUF: > >> + > >> +************************* > >> +ioctl VIDIOC_EXT_QUERYBUF > >> +************************* > >> + > >> +Name > >> +==== > >> + > >> +VIDIOC_EXT_QUERYBUF - Query the status of a buffer > >> + > >> + > >> +Synopsis > >> +======== > >> + > >> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_QUERYBUF, struct v4l2_ext_buffer *argp ) > >> + :name: VIDIOC_EXT_QUERYBUF > >> + > >> + > >> +Arguments > >> +========= > >> + > >> +``fd`` > >> + File descriptor returned by :ref:`open() <func-open>`. > >> + > >> +``argp`` > >> + Pointer to struct :c:type:`v4l2_ext_buffer`. > >> + > >> + > >> +Description > >> +=========== > >> + > >> +This ioctl is part of the :ref:`streaming <mmap>` 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:`VIDIOC_EXT_CREATE_BUFS` ioctl. > >> + > >> +Applications set the ``type`` field of a struct > >> +:c:type:`v4l2_ext_buffer` to the same buffer type as was > >> +previously used with struct :c:type:`v4l2_ext_pix_format` ``type``, > >> +and the ``index`` field. Valid index numbers range from zero to the > >> +number of buffers allocated with > >> +:ref:`VIDIOC_EXT_CREATE_BUFS` (struct > >> +:c:type:`v4l2_ext_create_buffers` ``count``) minus > >> +one. The ``reserved`` field must be set to 0. > >> + > >> +In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``, > >> +``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and > >> +``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``planes.memory`` fields will be > >> +set to the current I/O method for each plane. > >> + > >> +For every valid plane, an entry in ``planes`` will be filled, and zeroed for > >> +invalid ones. ``planes[i].buffer_length`` is the size of the memory buffer > >> +which contains the plane, ``planes[i].plane_length`` is the length of the plane, > > > > What is the length of the plane here? It seems like depending on the > > context, the field can mean size of the payload (for filled buffer) or > > total space for the payload (for empty buffer), which is a bit confusing. > > > >> +and ``planes[i].offset` is where the plane is placed in the memory buffer. > >> + > >> +The size of the ``planes`` array can be calculated by the number of sequential > >> +planes with ``planes[i].buffer_length`` that differs from zero up to the max > >> +size of the array. > > > > Not sure if it's just me, but "size of array" sounds to me like the > > total memory size of the array, i.e. the max number of elements, which > > is fixed for this struct. How about > > > > "The entries of the planes array are valid up to the last entry with > > non-zero buffer_length or the last entry of the array, whichever is > > first." > > > > ? > > > >> + > >> + > >> +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 <gen-errors>` chapter. > >> + > >> +EINVAL > >> + The buffer ``type`` is not supported, or the ``index`` is out of > >> + bounds. > >> diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst > >> new file mode 100644 > >> index 0000000000000..008e6c98a88a5 > >> --- /dev/null > >> +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst > >> @@ -0,0 +1,117 @@ > >> +.. Permission is granted to copy, distribute and/or modify this > >> +.. document under the terms of the GNU Free Documentation License, > >> +.. Version 1.1 or any later version published by the Free Software > >> +.. Foundation, with no Invariant Sections, no Front-Cover Texts > >> +.. and no Back-Cover Texts. A copy of the license is included at > >> +.. Documentation/userspace-api/media/fdl-appendix.rst. > >> +.. > >> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections > >> + > >> +.. _VIDIOC_G_EXT_PIX_FMT: > >> + > >> +************************************************************************ > >> +ioctl VIDIOC_G_EXT_PIX_FMT, VIDIOC_S_EXT_PIX_FMT, VIDIOC_TRY_EXT_PIX_FMT > >> +************************************************************************ > >> + > >> +Name > >> +==== > >> + > >> +VIDIOC_G_EXT_PIX_FMT - VIDIOC_S_EXT_PIX_FMT - VIDIOC_TRY_EXT_PIX_FMT - Get or set the data format, try a format > >> + > >> + > >> +Synopsis > >> +======== > >> + > >> +.. c:function:: int ioctl( int fd, VIDIOC_G_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) > >> + :name: VIDIOC_G_EXT_PIX_FMT > >> + > >> +.. c:function:: int ioctl( int fd, VIDIOC_S_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) > >> + :name: VIDIOC_S_EXT_PIX_FMT > >> + > >> +.. c:function:: int ioctl( int fd, VIDIOC_TRY_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) > >> + :name: VIDIOC_TRY_EXT_PIX_FMT > >> + > >> +Arguments > >> +========= > >> + > >> +``fd`` > >> + File descriptor returned by :ref:`open() <func-open>`. > >> + > >> +``argp`` > >> + Pointer to struct :c:type:`v4l2_ext_pix_format`. > >> + > >> + > >> +Description > >> +=========== > >> + > >> +These ioctls are used to negotiate the format of data (typically image > >> +format) exchanged between driver and application. > >> + > >> +To query the current parameters applications set the ``type`` field of a > >> +struct :c:type:`v4l2_ext_pix_format` to ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or > >> +``V4L2_BUF_TYPE_VIDEO_OUTPUT``, all the other types are invalid in this API, > >> +and multiplanar is supported through modifiers. > >> + > >> +When the application calls the > >> +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl with a pointer to this > >> +structure the driver fills the other members. > >> +When the requested buffer type is not supported drivers return > >> +an ``EINVAL`` error code. > >> + > >> +To change the current format parameters applications initialize all > >> +the fields in the struct. > >> +For details see the documentation of the various devices types in > >> +:ref:`devices`. Good practice is to query the current parameters > >> +first, and to modify only those parameters not suitable for the > >> +application. When the application calls the :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl with > >> +a pointer to a struct :c:type:`v4l2_ext_pix_format` structure the driver > >> +checks and adjusts the parameters against hardware abilities. Drivers > >> +should not return an error code unless the ``type`` field is invalid, > >> +this is a mechanism to fathom device capabilities and to approach > >> +parameters acceptable for both the application and driver. On success > >> +the driver may program the hardware, allocate resources and generally > >> +prepare for data exchange. Finally the :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl returns > >> +the current format parameters as :ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` does. Very simple, > >> +inflexible devices may even ignore all input and always return the > >> +default parameters. However all V4L2 devices exchanging data with the > >> +application must implement the :ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` and :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` > >> +ioctl. When the requested buffer type is not supported drivers return an > >> +EINVAL error code on a :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` attempt. When I/O is already in > >> +progress or the resource is not available for other reasons drivers > >> +return the ``EBUSY`` error code. > >> + > >> +The :ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` with one > >> +exception: it does not change driver state. It can also be called at any > >> +time, never returning ``EBUSY``. This function is provided to negotiate > >> +parameters, to learn about hardware limitations, without disabling I/O > >> +or possibly time consuming hardware preparations. Although strongly > >> +recommended drivers are not required to implement this ioctl. > >> + > > > > Could we make this mandatory to avoid ambiguities in the API? In > > Yes, please! > > > general, most drivers implemented it anyway, without much added > > complexity, because one can then simplify S_FMT to TRY_FMT + state > > update. > > Ideally we would also fix the ambiguous situation regarding TRY/S_FMT > and unsupported pixelformats: some drivers will replace unsupported > pixelformats with a valid pixelformat, others will return an error. > > v4l2-compliance warns about drivers that return an error and point to > this very old thread: > > http://www.mail-archive.com/linux-media@vger.kernel.org/msg56550.html > > However, I'm not really sure if we can resolve this ambiguity. I believe > that it is only older webcam drivers that return an error. I guess we can at least enforce a specific behavior in the new API, before we get compatibility obligations. :) Best regards, Tomasz
On 20/11/2020 13:40, Tomasz Figa wrote: > On Fri, Nov 20, 2020 at 9:24 PM Hans Verkuil <hverkuil@xs4all.nl> wrote: >> >> On 20/11/2020 12:06, Tomasz Figa wrote:z >>> Hi Helen, >>> >>> On Tue, Aug 04, 2020 at 04:29:39PM -0300, Helen Koike wrote: >>>> Add documentation and update references in current documentation for the >>>> Extended API. >>>> >>> >>> Thank you for the patch. Please see my comments inline. >>> >>>> Signed-off-by: Helen Koike <helen.koike@collabora.com> >>>> --- >>>> Changes in v5: >>>> - new patch >>>> >>>> .../userspace-api/media/v4l/buffer.rst | 5 + >>>> .../userspace-api/media/v4l/common.rst | 1 + >>>> .../userspace-api/media/v4l/dev-capture.rst | 5 + >>>> .../userspace-api/media/v4l/dev-output.rst | 5 + >>>> .../userspace-api/media/v4l/ext-api.rst | 107 +++++++++ >>>> .../userspace-api/media/v4l/format.rst | 16 +- >>>> .../userspace-api/media/v4l/user-func.rst | 5 + >>>> .../media/v4l/vidioc-ext-create-bufs.rst | 95 ++++++++ >>>> .../media/v4l/vidioc-ext-prepare-buf.rst | 62 ++++++ >>>> .../media/v4l/vidioc-ext-qbuf.rst | 204 ++++++++++++++++++ >>>> .../media/v4l/vidioc-ext-querybuf.rst | 79 +++++++ >>>> .../media/v4l/vidioc-g-ext-pix-fmt.rst | 117 ++++++++++ >>>> 12 files changed, 697 insertions(+), 4 deletions(-) >>>> create mode 100644 Documentation/userspace-api/media/v4l/ext-api.rst >>>> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst >>>> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst >>>> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst >>>> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst >>>> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst >>>> >>>> diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst >>>> index 57e752aaf414a..c832bedd64e4c 100644 >>>> --- a/Documentation/userspace-api/media/v4l/buffer.rst >>>> +++ b/Documentation/userspace-api/media/v4l/buffer.rst >>>> @@ -27,6 +27,11 @@ 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. >>>> >>>> +.. note:: >>>> + >>>> + The :ref:`ext_api` version can also be used, and it is >>>> + preferable when applicable. >>> >>> Would rephrasing this as below making a bit more definitive? >>> >>> For modern applications, these operations are replaced by their >>> :ref:`ext_api` counterparts, which should be used instead. >> >> You can't say that, since especially in the beginning userspace will be running >> on older kernels that do not support this. >> >> This will work: "should be used instead, if supported by the driver." >> > > With the wrappers that the patches provide, all drivers would support > the new API, so this boils down to the kernel version only, not > specific drivers. > > Agreed, though, that application developers must be made aware that > the new API is only available in new kernels and old API must be used > for compatibility with old kernels. Is the conversion layer fully independent of vb2? We still have older drivers that do not use vb2, and I'm not sure if the extended buffer operations work with those drivers as well. (Sorry, it's been a while since I last looked at this series, so I can't remember). > >>> >>>> + >>>> 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 >>>> diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst >>>> index 7d81c58a13cd7..3430e0bdad667 100644 >>>> --- a/Documentation/userspace-api/media/v4l/common.rst >>>> +++ b/Documentation/userspace-api/media/v4l/common.rst >>>> @@ -59,6 +59,7 @@ applicable to all devices. >>>> ext-ctrls-detect >>>> fourcc >>>> format >>>> + ext-api >>>> planar-apis >>>> selection-api >>>> crop >>>> diff --git a/Documentation/userspace-api/media/v4l/dev-capture.rst b/Documentation/userspace-api/media/v4l/dev-capture.rst >>>> index 44d3094093ab6..5077639787d92 100644 >>>> --- a/Documentation/userspace-api/media/v4l/dev-capture.rst >>>> +++ b/Documentation/userspace-api/media/v4l/dev-capture.rst >>>> @@ -102,6 +102,11 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC >>>> requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. >>>> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. >>>> >>>> +.. note:: >>>> + >>>> + The :ref:`ext_api` version can also be used, and it is >>>> + preferable when applicable. >>>> + >>>> >>>> Reading Images >>>> ============== >>>> diff --git a/Documentation/userspace-api/media/v4l/dev-output.rst b/Documentation/userspace-api/media/v4l/dev-output.rst >>>> index e4f2a1d8b0fc7..f8f40c708e49f 100644 >>>> --- a/Documentation/userspace-api/media/v4l/dev-output.rst >>>> +++ b/Documentation/userspace-api/media/v4l/dev-output.rst >>>> @@ -99,6 +99,11 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC >>>> requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. >>>> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. >>>> >>>> +.. note:: >>>> + >>>> + The :ref:`ext_api` version can also be used, and it is >>>> + preferable when applicable. >>>> + >>>> >>>> Writing Images >>>> ============== >>>> diff --git a/Documentation/userspace-api/media/v4l/ext-api.rst b/Documentation/userspace-api/media/v4l/ext-api.rst >>>> new file mode 100644 >>>> index 0000000000000..da2a82960d22f >>>> --- /dev/null >>>> +++ b/Documentation/userspace-api/media/v4l/ext-api.rst >>>> @@ -0,0 +1,107 @@ >>>> +.. Permission is granted to copy, distribute and/or modify this >>>> +.. document under the terms of the GNU Free Documentation License, >>>> +.. Version 1.1 or any later version published by the Free Software >>>> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >>>> +.. and no Back-Cover Texts. A copy of the license is included at >>>> +.. Documentation/userspace-api/media/fdl-appendix.rst. >>>> +.. >>>> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >>>> + >>>> +.. _ext_api: >>>> + >>>> +************* >>>> +Extendend API >>>> +************* >>>> + >>>> +Introduction >>>> +============ >>>> + >>>> +The Extended Format API was conceived to extend V4L2 capabilities and >>>> +to simplify certain mechanisms. >>>> +It unifies single- vs multi- planar handling, >>>> +brings the concept of pixelformat + modifiers, allows planes to be placed >>>> +in any offset inside a buffer and let userspace to change colorspace >>>> +attributes if supported by the driver. >>> >>> How about simplifying this paragraph a bit: >>> >>> The Extended Format API unifies single- and multi- planar format handling >>> and provides a base for further functional extensions, such as format >>> modifiers, arbitrary plane offsets, colorspace configuration. >> >> Actually, I prefer Helen's version. >> > > To me it's a lot of text to read to get the same information, but I > won't insist. > >>> >>>> + >>>> +Data format negotiation and buffer handling works very similar to the classical >>>> +version, thus in this document we'll just mention the main differences. >>> >>> nit: "we will" or maybe even just "we mention only the main differences". >>> >>>> + >>>> +Data Format Negotiation >>>> +======================= >>>> + >>>> +The API replaces the classical ioctls: >>>> + >>>> +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, >>>> +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` >>>> +(with :c:type:`v4l2_format` as the main parameter). >>>> + >>>> +By the extended versions: >>>> + >>>> +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>`, >>>> +:ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>`, >>>> +:ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` >>>> +(with :c:type:`v4l2_ext_pix_format` as the main parameter). >>>> + >>>> +For CAPTURE and OUTPUT queues only. >>>> + >>>> +The ``type`` field of struct :c:type:`v4l2_ext_pix_format` only accepts >>>> +``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, and it >>>> +supports multiplanar format through a combination of ``pixelfomat`` and >>>> +``modifier`` fields. >>>> + >>>> +Only the single-planar variants of the pixel formats are valid in the >>>> +``pixelformat`` field. >>> >>> Some formats have only multi-planar variants, like NV12MT. What should we >>> do about them? Since we have to keep those defines to support the legacy >>> API anyway, maybe we can just accept both variants and treat them equally? >> >> Helen mentioned that as well in a reply to patch 1/7. I'll have a think about >> that myself and reply to that post because this is a good question. >> > > I'm thinking about it as well. :) > >>> >>>> +To support multi-planar, a modifier should be set in the ``modifier`` field to >>>> +provide more information regarding the memory layout of pixels and number of >>>> +planes. >>>> + >>>> +The ``plane_fmt`` field is an array which holds information by plane using >>>> +the :c:type:`v4l2_plane_ext_pix_format`. When this struct is filled, its >>>> +``sizeimage`` field should be non-zero for all valid planes for a given >>>> +``pixelformat`` + ``modifier`` combination, and zeroed for the invalid ones. >>>> + >>>> +Colospace attributes are not read-only as in the classical version, i.e, they >>>> +can be set by application and drivers will adjust accordingly depending on what >>>> +is supported by the underlying hardware. >>>> + >>>> +Buffers >>>> +======= >>>> + >>>> +The API replaces the classical ioctls: >>>> + >>>> +:ref:`VIDIOC_CREATE_BUFS <VIDIOC_CREATE_BUFS>` >>>> +(with :c:type:`v4l2_create_buffers` as the main parameter), >>>> +:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, >>>> +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_PREPARE_BUF <VIDIOC_PREPARE_BUF>` >>>> +(with :c:type:`v4l2_buffer` as the main parameter) >>>> + >>>> +By the extended versions: >>>> + >>>> +:ref:`VIDIOC_EXT_CREATE_BUFS <VIDIOC_EXT_CREATE_BUFS>` >>>> +(with :c:type:`v4l2_ext_create_buffers` as the main parameter), >>>> +:ref:`VIDIOC_EXT_QUERYBUF <VIDIOC_EXT_QUERYBUF>`, >>>> +:ref:`VIDIOC_EXT_QBUF <VIDIOC_EXT_QBUF>`, >>>> +:ref:`VIDIOC_EXT_DQBUF <VIDIOC_EXT_QBUF>`, >>>> +:ref:`VIDIOC_EXT_PREPARE_BUF <VIDIOC_EXT_PREPARE_BUF>` >>>> +(with :c:type:`v4l2_ext_buffer` as the main parameter) >>>> + >>>> +The basic difference between :c:type:`v4l2_create_buffers` and >>>> +:c:type:`v4l2_ext_create_buffers` is that the later have a >>>> +:c:type:`v4l2_ext_pix_format` as the type of the ``format`` field. >>>> + >>>> +Comparing :c:type:`v4l2_ext_buffer` with :c:type:`v4l2_buffer`, in the >>>> +extended version there is a unification of the single-/multi- planar handling >>>> +through the ``planes`` field of type :c:type:`v4l2_ext_plane`. >>>> + >>>> +The :c:type:`v4l2_ext_plane also allows planes to be placed in a given offset >>>> +inside a buffer. >>>> +Planes can be placed in different locations inside the same buffer, or in >>>> +different buffers. >>>> + >>>> + >>>> +.. kernel-doc:: include/uapi/linux/videodev2.h >>>> + :functions: v4l2_ext_plane >>>> + >>>> + >>>> +.. kernel-doc:: include/uapi/linux/videodev2.h >>>> + :functions: v4l2_ext_buffer >>>> diff --git a/Documentation/userspace-api/media/v4l/format.rst b/Documentation/userspace-api/media/v4l/format.rst >>>> index e47fc0505727c..b96d26f26793c 100644 >>>> --- a/Documentation/userspace-api/media/v4l/format.rst >>>> +++ b/Documentation/userspace-api/media/v4l/format.rst >>>> @@ -28,13 +28,19 @@ format and the driver selects and reports the best the hardware can do >>>> to satisfy the request. Of course applications can also just query the >>>> current selection. >>>> >>>> -A single mechanism exists to negotiate all data formats using the >>>> -aggregate struct :c:type:`v4l2_format` and the >>>> +There are two mechanism to negociate data formats: >>> >>> negotiate >>> >>>> + >>>> +The first one is using the aggregate struct :c:type:`v4l2_format` and the >>>> :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and >>>> :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the >>>> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine >>>> what the hardware *could* do, without actually selecting a new data >>>> -format. The data formats supported by the V4L2 API are covered in the >>>> +format. >>>> + >>>> +The second is through the :ref:`ext_api`, please refer to its documentation >>>> +for more information. >>>> + >>> >>> Should we reverse the order to prefer the new API? >>> >>>> +The data formats supported by the V4L2 API are covered in the >>>> respective device section in :ref:`devices`. For a closer look at >>>> image formats see :ref:`pixfmt`. >>>> >>>> @@ -71,7 +77,9 @@ earlier versions of V4L2. Switching the logical stream or returning into >>>> *may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. >>>> >>>> All drivers exchanging data with applications must support the >>>> -:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the >>>> +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl >>>> +or the Extended respective versions (TODO: link). >>> >>> TODO? :) >>> >>>> +Implementation of the >>>> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. >>>> >>>> >>>> diff --git a/Documentation/userspace-api/media/v4l/user-func.rst b/Documentation/userspace-api/media/v4l/user-func.rst >>>> index bf77c842718e5..67b254812791c 100644 >>>> --- a/Documentation/userspace-api/media/v4l/user-func.rst >>>> +++ b/Documentation/userspace-api/media/v4l/user-func.rst >>>> @@ -20,6 +20,7 @@ Function Reference >>>> func-close >>>> func-ioctl >>>> vidioc-create-bufs >>>> + vidioc-ext-create-bufs >>>> vidioc-cropcap >>>> vidioc-dbg-g-chip-info >>>> vidioc-dbg-g-register >>>> @@ -48,6 +49,7 @@ Function Reference >>>> vidioc-g-ext-ctrls >>>> vidioc-g-fbuf >>>> vidioc-g-fmt >>>> + vidioc-g-ext-pix-fmt >>>> vidioc-g-frequency >>>> vidioc-g-input >>>> vidioc-g-jpegcomp >>>> @@ -62,8 +64,11 @@ Function Reference >>>> vidioc-log-status >>>> vidioc-overlay >>>> vidioc-prepare-buf >>>> + vidioc-ext-prepare-buf >>>> vidioc-qbuf >>>> + vidioc-ext-qbuf >>>> vidioc-querybuf >>>> + vidioc-ext-querybuf >>>> vidioc-querycap >>>> vidioc-queryctrl >>>> vidioc-query-dv-timings >>>> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst >>>> new file mode 100644 >>>> index 0000000000000..67f2c541e4d79 >>>> --- /dev/null >>>> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst >>>> @@ -0,0 +1,95 @@ >>>> +.. Permission is granted to copy, distribute and/or modify this >>>> +.. document under the terms of the GNU Free Documentation License, >>>> +.. Version 1.1 or any later version published by the Free Software >>>> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >>>> +.. and no Back-Cover Texts. A copy of the license is included at >>>> +.. Documentation/userspace-api/media/fdl-appendix.rst. >>>> +.. >>>> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >>>> + >>> >>> TODO? :) >>> >>>> +.. _VIDIOC_EXT_CREATE_BUFS: >>>> + >>>> +**************************** >>>> +ioctl VIDIOC_EXT_CREATE_BUFS >>>> +**************************** >>>> + >>>> +Name >>>> +==== >>>> + >>>> +VIDIOC_EXT_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O >>>> + >>>> + >>>> +Synopsis >>>> +======== >>>> + >>>> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_CREATE_BUFS, struct v4l2_ext_create_buffers *argp ) >>>> + :name: VIDIOC_EXT_CREATE_BUFS >>>> + >>>> + >>>> +Arguments >>>> +========= >>>> + >>>> +``fd`` >>>> + File descriptor returned by :ref:`open() <func-open>`. >>>> + >>>> +``argp`` >>>> + Pointer to struct :c:type:`v4l2_ext_create_buffers`. >>>> + >>>> + >>>> +Description >>>> +=========== >>>> + >>>> +This ioctl is used to create buffers for :ref:`memory mapped <mmap>` >>>> +or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. >>>> +This ioctl can be called multiple times to >>>> +create buffers of different sizes. >>>> + >>>> +To allocate the device buffers applications must initialize the relevant >>>> +fields of the struct :c:type:`v4l2_ext_create_buffers` structure. The >>>> +``count`` field must be set to the number of requested buffers, the >>>> +``memory`` field specifies the requested I/O method and the ``reserved`` >>>> +array must be zeroed. >>>> + >>>> +The ``format`` field specifies the image format that the buffers must be >>>> +able to handle. The application has to fill in this struct >>>> +:c:type:`v4l2_format`. Usually this will be done using the >>>> +:ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` or >>>> +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctls to ensure that the >>>> +requested format is supported by the driver. >>>> +The driver may return an error if the size(s) are not supported by the >>>> +hardware (usually because they are too small). >>>> + >>>> +The driver can create a memory buffer per plane, or a single memory buffer >>>> +containing all the planes, with a minimum size according to the size >>>> +defined by the ``format.plane_fmt[i].sizeimage`` field. >>>> +Usually if the ``format.plane_fmt[i].sizeimage`` >>>> +field is less than the minimum required for the given format, then an >>>> +error will be returned since drivers will typically not allow this. If >>>> +it is larger, then the value will be used as-is. In other words, the >>>> +driver may reject the requested size, but if it is accepted the driver >>>> +will use it unchanged. >>>> + >>>> +When the ioctl is called with a pointer to this structure the driver >>>> +will attempt to allocate up to the requested number of buffers and store >>>> +the actual number allocated and the starting index in the ``count`` and >>>> +the ``index`` fields respectively. On return ``count`` can be smaller >>>> +than the number requested. >>> >>> The 'capabilities' and 'flags' fields seem to go undocumented. >>> >>>> + >>>> + >>>> +.. kernel-doc:: include/uapi/linux/videodev2.h >>>> + :functions: v4l2_ext_create_buffers >>>> + >>>> + >>>> +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 <gen-errors>` chapter. >>>> + >>>> +ENOMEM >>>> + No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O. >>>> + >>>> +EINVAL >>>> + The buffer type (``format.type`` field), requested I/O method >>>> + (``memory``) or format (``format`` field) is not valid. >>>> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst >>>> new file mode 100644 >>>> index 0000000000000..88e4b57121254 >>>> --- /dev/null >>>> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst >>>> @@ -0,0 +1,62 @@ >>>> +.. Permission is granted to copy, distribute and/or modify this >>>> +.. document under the terms of the GNU Free Documentation License, >>>> +.. Version 1.1 or any later version published by the Free Software >>>> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >>>> +.. and no Back-Cover Texts. A copy of the license is included at >>>> +.. Documentation/userspace-api/media/fdl-appendix.rst. >>>> +.. >>>> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >>>> + >>>> +.. _VIDIOC_EXT_PREPARE_BUF: >>>> + >>>> +**************************** >>>> +ioctl VIDIOC_EXT_PREPARE_BUF >>>> +**************************** >>>> + >>>> +Name >>>> +==== >>>> + >>>> +VIDIOC_EXT_PREPARE_BUF - Prepare a buffer for I/O >>>> + >>>> + >>>> +Synopsis >>>> +======== >>>> + >>>> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_PREPARE_BUF, struct v4l2_ext_buffer *argp ) >>>> + :name: VIDIOC_EXT_PREPARE_BUF >>>> + >>>> + >>>> +Arguments >>>> +========= >>>> + >>>> +``fd`` >>>> + File descriptor returned by :ref:`open() <func-open>`. >>>> + >>>> +``argp`` >>>> + Pointer to struct :c:type:`v4l2_ext_buffer`. >>>> + >>>> + >>>> +Description >>>> +=========== >>>> + >>>> +Applications can optionally call the :ref:`VIDIOC_EXT_PREPARE_BUF` ioctl to >>>> +pass ownership of the buffer to the driver before actually enqueuing it, >>>> +using the :ref:`VIDIOC_EXT_QBUF <VIDIOC_EXT_QBUF>` ioctl, and to prepare it for future I/O. Such >>>> +preparations may include cache invalidation or cleaning. Performing them >>>> +in advance saves time during the actual I/O. >>>> + >>>> + >>>> +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 <gen-errors>` chapter. >>>> + >>>> +EBUSY >>>> + File I/O is in progress. >>>> + >>>> +EINVAL >>>> + The buffer ``type`` is not supported, or the ``index`` is out of >>>> + bounds, or no buffers have been allocated yet, or the ``userptr`` or >>>> + ``length`` are invalid. >>>> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst >>>> new file mode 100644 >>>> index 0000000000000..083e106cf6bad >>>> --- /dev/null >>>> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst >>>> @@ -0,0 +1,204 @@ >>>> +.. Permission is granted to copy, distribute and/or modify this >>>> +.. document under the terms of the GNU Free Documentation License, >>>> +.. Version 1.1 or any later version published by the Free Software >>>> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >>>> +.. and no Back-Cover Texts. A copy of the license is included at >>>> +.. Documentation/userspace-api/media/fdl-appendix.rst. >>>> +.. >>>> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >>>> + >>>> +.. _VIDIOC_EXT_QBUF: >>>> + >>>> +*************************************** >>>> +ioctl VIDIOC_EXT_QBUF, VIDIOC_EXT_DQBUF >>>> +*************************************** >>>> + >>>> +Name >>>> +==== >>>> + >>>> +VIDIOC_EXT_QBUF - VIDIOC_EXT_DQBUF - Exchange a buffer with the driver >>>> + >>>> + >>>> +Synopsis >>>> +======== >>>> + >>>> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_QBUF, struct v4l2_ext_buffer *argp ) >>>> + :name: VIDIOC_EXT_QBUF >>>> + >>>> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_DQBUF, struct v4l2_ext_buffer *argp ) >>>> + :name: VIDIOC_EXT_DQBUF >>>> + >>>> + >>>> +Arguments >>>> +========= >>>> + >>>> +``fd`` >>>> + File descriptor returned by :ref:`open() <func-open>`. >>>> + >>>> +``argp`` >>>> + Pointer to struct :c:type:`v4l2_ext_buffer`. >>>> + >>>> + >>>> +Description >>>> +=========== >>>> + >>>> +Applications call the ``VIDIOC_EXT_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 ``type`` field of a struct >>>> +:c:type:`v4l2_ext_buffer` to the same buffer type as was >>>> +previously used with struct :c:type:`v4l2_ext_pix_format` ``type``. >>>> +Applications must also set the ``index`` field. Valid index numbers >>>> +range from zero to the number of buffers allocated with >>>> +:ref:`VIDIOC_EXT_CREATE_BUFS` (struct >>>> +:c:type:`v4l2_ext_create_buffers` ``count``) minus >>>> +one. The contents of the struct :c:type:`v4l2_ext_buffer` returned >>> >>> I think this might not be entirely accurate. One can call >>> VIDIOC_EXT_CREATE_BUFS multiple times. Moreover, I don't think we've >>> prohibited VIDIOC_REQBUFS for the ext API, or have we? >>> >>>> +by a :ref:`VIDIOC_EXT_QUERYBUF` ioctl will do as well. >>>> +When the buffer is intended for output (``type`` is >>>> +``V4L2_BUF_TYPE_VIDEO_OUTPUT``) applications must also initialize the >>>> +``timestamp`` fields and the ``planes[i].plane_length`` for each valid plane, >>>> +and invalid ones must be set as zero. >>>> +see :ref:`buffer` for details. Applications must also set ``flags`` to 0. The >>>> +``reserved`` field must be set to 0. >>>> + >>>> +To enqueue a :ref:`memory mapped <mmap>` buffer applications set the >>>> +``planes[i].memory`` field to ``V4L2_MEMORY_MMAP`` in all the valid planes, >>>> +and invalid ones must be set as zero. >>>> +When ``VIDIOC_EXT_QBUF`` is called >>>> +with a pointer to this structure the driver sets the >>>> +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears >>>> +the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an >>>> +``EINVAL`` error code. >>>> + >>>> +To enqueue a :ref:`user pointer <userp>` buffer applications set the >>>> +``planes[i].memory`` field to ``V4L2_MEMORY_USERPTR`` in all the valid planes, >>>> +and invalid ones must be set as zero, the ``planes[i].m.userptr`` field to the >>>> +address of the buffer,``planes[i].buffer_length`` to the size of the memory >>>> +buffer, ``planes[i].plane_length`` to the size that should be used by the plane, >>>> +and ``planes[i].offset`` of the plane in the memory buffer. >>> >>> Does offset make sense here if an arbitrary pointer can be given for the >>> start of the plane? >>> >>>> + >>>> +When ``VIDIOC_EXT_QBUF`` is called with a pointer to this structure >>>> +the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the >>>> +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the >>>> +``flags`` field, or it returns an error code. This ioctl locks the >>> >>> This seems to be a copy of the text few lines above. >>> >>>> +memory pages of the buffer in physical memory, they cannot be swapped >>>> +out to disk. Buffers remain locked until dequeued, until the >>>> +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or >>>> +:ref:`VIDIOC_EXT_CREATE_BUFS` ioctl is called, or until the >>>> +device is closed. >>> >>> Why would CREATE_BUFS affect existing buffers? >>> >>>> + >>>> +To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the >>>> +``planes[i].memory`` field to ``V4L2_MEMORY_DMABUF`` in all the valid planes, >>>> +and invalid ones must be set as zero, the ``planes[i].m.fd`` field to a >>>> +file descriptor associated with a DMABUF buffer.,``planes[i].buffer_length`` to >>>> +the size of the memory buffer, ``planes[i].plane_length`` to the size that >>> >>> What is the buffer_length field needed for? DMA-bufs by definition are >>> kernel objects and the kernel should already know their sizes. >> >> See this discussion: >> >> https://patchwork.linuxtv.org/project/linux-media/patch/gh5kef5bkeel3o6b2dkgc2dfagu9klj4c0@4ax.com/ >> > > I briefly read through it and I don't see what the conclusion was. > Generally I'd still prefer if the need to manually specify the buffer > size was eliminated, because that imposes unnecessary burden on the > userspace for the majority of cases. It could still remain valid for > userspace that wants to restrict the buffer size as it was mentioned > in that thread, though. That's really the open issue: if userspace sets length to 0, then it should always be replaced by the dmabuf size, that's a no-brainer. But if it is non-zero, what do you do then? Your input would be appreciated. > >>> >>>> +should be used by the plane, and ``planes[i].offset`` of the plane in the memory buffer. >>>> +When ``VIDIOC_EXT_QBUF`` is called with a pointer to this structure the driver >>>> +sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the >>>> +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the >>>> +``flags`` field, or it returns an error code. This ioctl locks the >>> >>> Ditto. >>> >>>> +buffer. Locking a buffer means passing it to a driver for a hardware >>>> +access (usually DMA). If an application accesses (reads/writes) a locked >>>> +buffer then the result is undefined. Buffers remain locked until >>>> +dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or >>>> +:ref:`VIDIOC_EXT_CREATE_BUFS` ioctl is called, or until the >>>> +device is closed. >>> >>> Ditto. >>> >>>> + >>>> +The ``request_fd`` field can be used with the ``VIDIOC_EXT_QBUF`` ioctl to specify >>>> +the file descriptor of a :ref:`request <media-request-api>`, if requests are >>>> +in use. Setting it means that the buffer will not be passed to the driver >>>> +until the request itself is queued. Also, the driver will apply any >>>> +settings associated with the request for this buffer. This field will >>>> +be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set. >>>> +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. >>>> + >>>> +.. caution:: >>>> + It is not allowed to mix queuing requests with queuing buffers directly. >>>> + ``EBUSY`` will be returned if the first buffer was queued directly and >>>> + then the application tries to queue a request, or vice versa. After >>>> + closing the file descriptor, calling >>>> + :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_EXT_CREATE_BUFS` >>>> + the check for this will be reset. >>>> + >>>> + For :ref:`memory-to-memory devices <mem2mem>` you can specify the >>>> + ``request_fd`` only for output buffers, not for capture buffers. Attempting >>>> + to specify this for a capture buffer will result in an ``EBADR`` error. >>>> + >>>> +Applications call the ``VIDIOC_EXT_DQBUF`` ioctl to dequeue a filled >>>> +(capturing) or displayed (output) buffer from the driver's outgoing >>> >>> "displayed" is quite inaccurate given that the majority of use cases for >>> OUTPUT in V4L2 now are m2m devices. Maybe "consumed"? >>> >>>> +queue. They just set the ``type``, ``planes[i].memory`` and ``reserved`` fields of >>> >>> Why does the application have to set the memory field? It should be already >>> known by the kernel which owns the buffer at the given time. >>> >>>> +a struct :c:type:`v4l2_ext_buffer` as above, when >>>> +``VIDIOC_EXT_DQBUF`` is called with a pointer to this structure the driver >>>> +fills the remaining fields or returns an error code. The driver may also >>>> +set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a >>>> +non-critical (recoverable) streaming error. In such case the application >>>> +may continue as normal, but should be aware that data in the dequeued >>>> +buffer might be corrupted. When using the multi-planar API, the planes >>>> +array must be passed in as well. >>>> + >>>> +If the application sets the ``memory`` field to ``V4L2_MEMORY_DMABUF`` to >>>> +dequeue a :ref:`DMABUF <dmabuf>` buffer, the driver fills the ``m.fd`` field >>>> +with a file descriptor numerically the same as the one given to ``VIDIOC_EXT_QBUF`` >>>> +when the buffer was enqueued. No new file descriptor is created at dequeue time >>>> +and the value is only for the application convenience. >>> >>> Honestly, I don't like this aspect of the current API. It kind of implies >>> that the value returned is valid, but the file descriptor might have been >>> already closed. Could we just remove this and explicitly state that for >>> DMA-buf, it is the user space responsibility to track the mapping between >>> V4L2 indexes and its own buffer objects? >>> >>>> + >>>> +By default ``VIDIOC_EXT_DQBUF`` blocks when no buffer is in the outgoing >>>> +queue. When the ``O_NONBLOCK`` flag was given to the >>>> +:ref:`open() <func-open>` function, ``VIDIOC_EXT_DQBUF`` returns >>>> +immediately with an ``EAGAIN`` error code when no buffer is available. >>>> + >>>> + >>>> +.. kernel-doc:: include/uapi/linux/videodev2.h >>>> + :functions: v4l2_ext_buffers >>>> + >>>> + >>>> +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 <gen-errors>` chapter. >>>> + >>>> +EAGAIN >>>> + Non-blocking I/O has been selected using ``O_NONBLOCK`` and no >>>> + buffer was in the outgoing queue. >>>> + >>>> +EINVAL >>>> + The buffer ``type`` is not supported, or the ``index`` is out of >>>> + bounds, or no buffers have been allocated yet, or the ``userptr`` or >>>> + ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was >>> >>> There is no 'length' now. >>> >>>> + set but the the given ``request_fd`` was invalid, or ``m.fd`` was >>>> + an invalid DMABUF file descriptor. >>>> + >>>> +EIO >>>> + ``VIDIOC_EXT_DQBUF`` failed due to an internal error. Can also indicate >>>> + temporary problems like signal loss. >> >> Drop the last sentence, -EIO should never be used for temporary problems like >> that. EIO really means that the DMA engine crashed and userspace will have to call >> STREAMOFF and try to restart the DMA with STREAMON. >> > > I suspect the users of the new API wouldn't actually have to deal with > a signal loss, but if not, what should be the behavior then? The typical behavior is to send out the SOURCE_CHANGE event and stall streaming, waiting for a valid signal. That said, this is something I will dig into a bit deeper for the tegra HDMI support patch series next week, since this might be hard to do for that hardware. But regardless of what is chosen for signal loss, EIO is wrong. Return values as are documented for VIDIOC_QUERY_DV_TIMINGS would be much more appropriate for this. > >>>> + >>>> + .. note:: >>>> + >>>> + The driver might dequeue an (empty) buffer despite returning >>>> + an error, or even stop capturing. Reusing such buffer may be unsafe >>>> + though and its details (e.g. ``index``) may not be returned either. >> >> The first part of this note is rather vague. I'm not sure what it meant with this. >> >>>> + It is recommended that drivers indicate recoverable errors by setting >>>> + the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the >>>> + application should be able to safely reuse the buffer and continue >>>> + streaming. >>> >>> What is this for? It sounds like some legacy behavior, which maybe we could >>> drop with this new API? >> >> No, V4L2_BUF_FLAG_ERROR is really needed. Some hardware can really have >> intermittent failures causing video frames to be corrupt. And yes, that's >> typically due to hardware bugs. It usually either happens when you start >> streaming or just intermittent, but it is not severe enough to stop streaming >> completely (that's the -EIO error due to a call to vb2_queue_error). >> >> It's also used when you stop streaming and pending buffers are returned to >> userspace. They are marked as ERROR since they don't contain any video, or >> only partial video (if the DMA was stopped midway a frame). >> > > Sorry, I meant to insert that comment below the first half. The second > half is fine. Ah, that makes much more sense :-) > >>> >>>> + >>>> +EPIPE >>>> + ``VIDIOC_EXT_DQBUF`` returns this on an empty capture queue for mem2mem >>>> + codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already >>>> + dequeued and no new buffers are expected to become available. >>>> + >>>> +EBADR >>>> + The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not >>>> + support requests for the given buffer type, or >>>> + the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was not set but the device requires >>>> + that the buffer is part of a request. >>>> + >>>> +EBUSY >>>> + The first buffer was queued via a request, but the application now tries >>>> + to queue it directly, or vice versa (it is not permitted to mix the two >>>> + APIs). >>>> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst >>>> new file mode 100644 >>>> index 0000000000000..f2a12017253f6 >>>> --- /dev/null >>>> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst >>>> @@ -0,0 +1,79 @@ >>>> +.. Permission is granted to copy, distribute and/or modify this >>>> +.. document under the terms of the GNU Free Documentation License, >>>> +.. Version 1.1 or any later version published by the Free Software >>>> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >>>> +.. and no Back-Cover Texts. A copy of the license is included at >>>> +.. Documentation/userspace-api/media/fdl-appendix.rst. >>>> +.. >>>> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >>>> + >>>> +.. _VIDIOC_EXT_QUERYBUF: >>>> + >>>> +************************* >>>> +ioctl VIDIOC_EXT_QUERYBUF >>>> +************************* >>>> + >>>> +Name >>>> +==== >>>> + >>>> +VIDIOC_EXT_QUERYBUF - Query the status of a buffer >>>> + >>>> + >>>> +Synopsis >>>> +======== >>>> + >>>> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_QUERYBUF, struct v4l2_ext_buffer *argp ) >>>> + :name: VIDIOC_EXT_QUERYBUF >>>> + >>>> + >>>> +Arguments >>>> +========= >>>> + >>>> +``fd`` >>>> + File descriptor returned by :ref:`open() <func-open>`. >>>> + >>>> +``argp`` >>>> + Pointer to struct :c:type:`v4l2_ext_buffer`. >>>> + >>>> + >>>> +Description >>>> +=========== >>>> + >>>> +This ioctl is part of the :ref:`streaming <mmap>` 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:`VIDIOC_EXT_CREATE_BUFS` ioctl. >>>> + >>>> +Applications set the ``type`` field of a struct >>>> +:c:type:`v4l2_ext_buffer` to the same buffer type as was >>>> +previously used with struct :c:type:`v4l2_ext_pix_format` ``type``, >>>> +and the ``index`` field. Valid index numbers range from zero to the >>>> +number of buffers allocated with >>>> +:ref:`VIDIOC_EXT_CREATE_BUFS` (struct >>>> +:c:type:`v4l2_ext_create_buffers` ``count``) minus >>>> +one. The ``reserved`` field must be set to 0. >>>> + >>>> +In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``, >>>> +``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and >>>> +``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``planes.memory`` fields will be >>>> +set to the current I/O method for each plane. >>>> + >>>> +For every valid plane, an entry in ``planes`` will be filled, and zeroed for >>>> +invalid ones. ``planes[i].buffer_length`` is the size of the memory buffer >>>> +which contains the plane, ``planes[i].plane_length`` is the length of the plane, >>> >>> What is the length of the plane here? It seems like depending on the >>> context, the field can mean size of the payload (for filled buffer) or >>> total space for the payload (for empty buffer), which is a bit confusing. >>> >>>> +and ``planes[i].offset` is where the plane is placed in the memory buffer. >>>> + >>>> +The size of the ``planes`` array can be calculated by the number of sequential >>>> +planes with ``planes[i].buffer_length`` that differs from zero up to the max >>>> +size of the array. >>> >>> Not sure if it's just me, but "size of array" sounds to me like the >>> total memory size of the array, i.e. the max number of elements, which >>> is fixed for this struct. How about >>> >>> "The entries of the planes array are valid up to the last entry with >>> non-zero buffer_length or the last entry of the array, whichever is >>> first." >>> >>> ? >>> >>>> + >>>> + >>>> +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 <gen-errors>` chapter. >>>> + >>>> +EINVAL >>>> + The buffer ``type`` is not supported, or the ``index`` is out of >>>> + bounds. >>>> diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst >>>> new file mode 100644 >>>> index 0000000000000..008e6c98a88a5 >>>> --- /dev/null >>>> +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst >>>> @@ -0,0 +1,117 @@ >>>> +.. Permission is granted to copy, distribute and/or modify this >>>> +.. document under the terms of the GNU Free Documentation License, >>>> +.. Version 1.1 or any later version published by the Free Software >>>> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >>>> +.. and no Back-Cover Texts. A copy of the license is included at >>>> +.. Documentation/userspace-api/media/fdl-appendix.rst. >>>> +.. >>>> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >>>> + >>>> +.. _VIDIOC_G_EXT_PIX_FMT: >>>> + >>>> +************************************************************************ >>>> +ioctl VIDIOC_G_EXT_PIX_FMT, VIDIOC_S_EXT_PIX_FMT, VIDIOC_TRY_EXT_PIX_FMT >>>> +************************************************************************ >>>> + >>>> +Name >>>> +==== >>>> + >>>> +VIDIOC_G_EXT_PIX_FMT - VIDIOC_S_EXT_PIX_FMT - VIDIOC_TRY_EXT_PIX_FMT - Get or set the data format, try a format >>>> + >>>> + >>>> +Synopsis >>>> +======== >>>> + >>>> +.. c:function:: int ioctl( int fd, VIDIOC_G_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) >>>> + :name: VIDIOC_G_EXT_PIX_FMT >>>> + >>>> +.. c:function:: int ioctl( int fd, VIDIOC_S_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) >>>> + :name: VIDIOC_S_EXT_PIX_FMT >>>> + >>>> +.. c:function:: int ioctl( int fd, VIDIOC_TRY_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) >>>> + :name: VIDIOC_TRY_EXT_PIX_FMT >>>> + >>>> +Arguments >>>> +========= >>>> + >>>> +``fd`` >>>> + File descriptor returned by :ref:`open() <func-open>`. >>>> + >>>> +``argp`` >>>> + Pointer to struct :c:type:`v4l2_ext_pix_format`. >>>> + >>>> + >>>> +Description >>>> +=========== >>>> + >>>> +These ioctls are used to negotiate the format of data (typically image >>>> +format) exchanged between driver and application. >>>> + >>>> +To query the current parameters applications set the ``type`` field of a >>>> +struct :c:type:`v4l2_ext_pix_format` to ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or >>>> +``V4L2_BUF_TYPE_VIDEO_OUTPUT``, all the other types are invalid in this API, >>>> +and multiplanar is supported through modifiers. >>>> + >>>> +When the application calls the >>>> +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl with a pointer to this >>>> +structure the driver fills the other members. >>>> +When the requested buffer type is not supported drivers return >>>> +an ``EINVAL`` error code. >>>> + >>>> +To change the current format parameters applications initialize all >>>> +the fields in the struct. >>>> +For details see the documentation of the various devices types in >>>> +:ref:`devices`. Good practice is to query the current parameters >>>> +first, and to modify only those parameters not suitable for the >>>> +application. When the application calls the :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl with >>>> +a pointer to a struct :c:type:`v4l2_ext_pix_format` structure the driver >>>> +checks and adjusts the parameters against hardware abilities. Drivers >>>> +should not return an error code unless the ``type`` field is invalid, >>>> +this is a mechanism to fathom device capabilities and to approach >>>> +parameters acceptable for both the application and driver. On success >>>> +the driver may program the hardware, allocate resources and generally >>>> +prepare for data exchange. Finally the :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl returns >>>> +the current format parameters as :ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` does. Very simple, >>>> +inflexible devices may even ignore all input and always return the >>>> +default parameters. However all V4L2 devices exchanging data with the >>>> +application must implement the :ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` and :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` >>>> +ioctl. When the requested buffer type is not supported drivers return an >>>> +EINVAL error code on a :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` attempt. When I/O is already in >>>> +progress or the resource is not available for other reasons drivers >>>> +return the ``EBUSY`` error code. >>>> + >>>> +The :ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` with one >>>> +exception: it does not change driver state. It can also be called at any >>>> +time, never returning ``EBUSY``. This function is provided to negotiate >>>> +parameters, to learn about hardware limitations, without disabling I/O >>>> +or possibly time consuming hardware preparations. Although strongly >>>> +recommended drivers are not required to implement this ioctl. >>>> + >>> >>> Could we make this mandatory to avoid ambiguities in the API? In >> >> Yes, please! >> >>> general, most drivers implemented it anyway, without much added >>> complexity, because one can then simplify S_FMT to TRY_FMT + state >>> update. >> >> Ideally we would also fix the ambiguous situation regarding TRY/S_FMT >> and unsupported pixelformats: some drivers will replace unsupported >> pixelformats with a valid pixelformat, others will return an error. >> >> v4l2-compliance warns about drivers that return an error and point to >> this very old thread: >> >> http://www.mail-archive.com/linux-media@vger.kernel.org/msg56550.html >> >> However, I'm not really sure if we can resolve this ambiguity. I believe >> that it is only older webcam drivers that return an error. > > I guess we can at least enforce a specific behavior in the new API, > before we get compatibility obligations. :) > > Best regards, > Tomasz > Regards, Hans
Hello, On 8/4/20 4:29 PM, Helen Koike wrote: > Hello, > > This is v5 of the Extended API for formats and buffers, which introduces > the following new ioctls: > > int ioctl(int fd, VIDIOC_G_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp) > int ioctl(int fd, VIDIOC_S_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp) > int ioctl(int fd, VIDIOC_TRY_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp) > > int ioctl(int fd, VIDIOC_EXT_CREATE_BUFS, struct v4l2_ext_create_buffers *argp) > int ioctl(int fd, VIDIOC_EXT_QUERYBUF, struct v4l2_ext_buffer *argp) > int ioctl(int fd, VIDIOC_EXT_QBUF, struct v4l2_ext_buffer *argp) > int ioctl(int fd, VIDIOC_EXT_DQBUF, struct v4l2_ext_buffer *argp) > int ioctl(int fd, VIDIOC_EXT_PREPARE_BUF, struct v4l2_ext_buffer *argp) > > Please check v4 cover letter specific topic past discussions > https://patchwork.linuxtv.org/project/linux-media/cover/20200717115435.2632623-1-helen.koike@collabora.com/ > > Documentation > ============= > I added a first version of the documentation. > I would appreciate some tips in how to organize this better, since there are > several parts of the docs which reference the "old" API, and for now > I just added a note pointing to the Extended API. > > Instead of duplicating documentation from the code to the Docs (as used by > most part of v4l2 documentation), I just added a reference to let Sphinx get > the structs documentation from the code, so we can avoid duplicating. > > For reviewing convenience, I uploaded the generated html docs at > https://people.collabora.com/~koike/ext-doc-v5/userspace-api/media/v4l/ext-api.html > > There is room for improvements, it would be great to get your suggestions. > > uAPI > ==== > This version have some minor changes in the uAPI structs, highlight to the > mem_offset that was returned to struct v4l2_ext_plane, memory field that now > is per plane, and some adjustments in field sizes and re-ordering to make > structs the same for 32 and 64 bits (which I verified with pahole tool). > > I also updated v4l2-compliance: > https://gitlab.collabora.com/koike/v4l-utils/-/tree/ext-api/wip > > We need to decide the size of the reserved fields left, how much reserved > fields do you think we should leave for each struct? > > What is next > ============ > I would like to improve implementation (for the kernel and v4l2-compliane) and > drop the RFC tag for next version, so please review the uAPI. > > > List of changes in v5: > ====================== > * first version of Documentation > * migrate memory from v4l2_ext_buffer to v4l2_ext_plane > * return mem_offset to struct v4l2_ext_plane > * change sizes and reorder fields to avoid holes in the struct and make it > the same for 32 and 64 bits > * removed __attribute__ ((packed)) from uapi structs > * set request_fd to signed > * add documentation > * updated some commit messages > > Hans Verkuil (1): > media: v4l2: Add extended buffer operations > > Helen Koike (6): > media: v4l2: Extend pixel formats to unify single/multi-planar > handling (and more) > media: videobuf2: Expose helpers to implement the _ext_fmt and > _ext_buf hooks > media: mediabus: Add helpers to convert a ext_pix format to/from a > mbus_fmt > media: vivid: Convert the capture and output drivers to > EXT_FMT/EXT_BUF > media: vimc: Implement the ext_fmt and ext_buf hooks > media: docs: add documentation for the Extended API > > .../userspace-api/media/v4l/buffer.rst | 5 + > .../userspace-api/media/v4l/common.rst | 1 + > .../userspace-api/media/v4l/dev-capture.rst | 5 + > .../userspace-api/media/v4l/dev-output.rst | 5 + > .../userspace-api/media/v4l/ext-api.rst | 107 ++ > .../userspace-api/media/v4l/format.rst | 16 +- > .../userspace-api/media/v4l/user-func.rst | 5 + > .../media/v4l/vidioc-ext-create-bufs.rst | 95 ++ > .../media/v4l/vidioc-ext-prepare-buf.rst | 62 ++ > .../media/v4l/vidioc-ext-qbuf.rst | 204 ++++ > .../media/v4l/vidioc-ext-querybuf.rst | 79 ++ > .../media/v4l/vidioc-g-ext-pix-fmt.rst | 117 +++ > .../media/common/videobuf2/videobuf2-core.c | 2 + > .../media/common/videobuf2/videobuf2-v4l2.c | 560 ++++++----- > .../media/test-drivers/vimc/vimc-capture.c | 61 +- > drivers/media/test-drivers/vimc/vimc-common.c | 6 +- > drivers/media/test-drivers/vimc/vimc-common.h | 2 +- > drivers/media/test-drivers/vivid/vivid-core.c | 70 +- > .../test-drivers/vivid/vivid-touch-cap.c | 26 +- > .../test-drivers/vivid/vivid-touch-cap.h | 3 +- > .../media/test-drivers/vivid/vivid-vid-cap.c | 169 +--- > .../media/test-drivers/vivid/vivid-vid-cap.h | 15 +- > .../media/test-drivers/vivid/vivid-vid-out.c | 193 ++-- > .../media/test-drivers/vivid/vivid-vid-out.h | 15 +- > drivers/media/v4l2-core/v4l2-dev.c | 50 +- > drivers/media/v4l2-core/v4l2-ioctl.c | 938 ++++++++++++++++-- > include/media/v4l2-ioctl.h | 60 ++ > include/media/v4l2-mediabus.h | 42 + > include/media/videobuf2-core.h | 6 +- > include/media/videobuf2-v4l2.h | 21 +- > include/uapi/linux/videodev2.h | 146 +++ > 31 files changed, 2363 insertions(+), 723 deletions(-) > create mode 100644 Documentation/userspace-api/media/v4l/ext-api.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst > I'm fixing the format and buffer conversions to separate planes per color component as pointed by Tomasz. It turns out this it a bit more complicated and will require changes in vb2 driver ops interface. I want to share my approach in case you see that I'm missing something while I'm implementing it, or if I'm making wrong assumptions. So I wrote different scenarios below. Please check, specially the NOTEs in the scenarios. Thanks! ---------------------------------------- Considerations: * Multiplanar API vs Singleplanar API. * M-variant vs non-M-variant, * data_offset is only available in Multiplanar API, not in single planar. * Single buffer: contiguous planes or not. * Memory buffers vs color components (planes) * Planes with offsets or not. NOTE: I'm assuming that multiplanar and singleplanar capabilities are mutually exclusive, i.e. if a driver reports V4L2_CAP_VIDEO_CAPTURE_MPLANE then it won't report V4L2_CAP_VIDEO_CAPTURE, which means that only multiplanar API is valid, and if V4L2_CAP_VIDEO_CAPTURE is reported, then _MPLANE isn't and only singleplanar API is valid and supported by the driver. NOTE: I'm assuming both non-M-variants and M-variants are acceptable and equivalent for the Ext API. If we have two pixelformats that are equivalent, then we chose one to be the normalized format. NOTE: Just for the sake of the examples below, I'm assuming that all M-variants have non-M-variants (which I'm considering that will be the normalized form), but I'm not doing this assumption in the code and it doesn't seem to be a problem. =========================================== A: Scenarios where: userspace -> implements clasic API driver -> implements ext API ------------------------------------------- QUESTION: if we want a ext_reqbuf, then queue_setup() (or a ext_queue_setup) should return a buffer per plane? Or a buffer for all planes? Which method should be favored? Also, see NOTE A-1.3. Another option is: ext_reqbufs won't be supported, and leave to userspace to decide this in ext_create_bufs. For the examples below, I'm assuming reqbuf isn't supported Case A-1: Single planar API - I'm assuming that M-variants pixelformats are invalid - I'm assuming the driver report in its capabilities only V4L2_CAP_VIDEO_CAPTURE/OUTPUT/M2M, and not the MPLANE equivalent. FORMATS: 1. framework receives v4l2_format 2. framework converts to v4l2_ext_pix_format, separating color components per plane, in the best effort way (without returning errors). 3. v4l2_ext_pix_format gets processed 4. framework converts back to v4l2_format and sent to userspace. CREATE BUFFER: 1. vb2 receives v4l2_buffer from userspace 2. vb2 converts to v4l2_ext_buffer, dividing the buffer per color component. Planes will be part of the same buffer, just in a different offset. NOTE A-1.1: vb2 needs to know the pixelformat and image size to calculate the number of color components and plane's offset for the conversion, my current solution is to add another callback in vb2_ops to get the format. See NOTE A-2.3. 3. memory sizes is validated by queue_setup() 4. vb2 converts it back to v4l2_buffer and sends to userspace REQ BUFFER: 1. vb2 calls queue_setup to ask the driver about the number of memory buffers in a frame buffer 2. queue_setup() returns with a single memory buffer with contiguous planes. NOTE A-1.2: If the driver decides to add offset between planes, we won't be able to convert back to v4l2_buffer and we fail. Even if we repurpose data_offset, there is no data_offset for single plane API NOTE A-1.3: I need to send a hint to queue_setup() to tell the driver if we need a single mem-buffer for all planes or a different mem-buffer per plane. Or maybe implement a ext_queue_setup(). 3. v4l2_ext_buffer is created 3. v4l2_ext_buffer is converted to v4l2_buffer and returned to userspace. QUEUE BUFFER: 1. vb2 receives v4l2_buffer from userspace (only index and type that matters) 2. vb2 converts to v4l2_ext_buffer 3. vb2_buffer is validated by .buf_prepare() and gets processed. 4. v4l2_ext_buffer is converted to v4l2_buffer and sent to userspace. Case A-2: Multiplanar API with non-M-variant pixelformat - I'm assuming the driver only reports V4L2_CAP_VIDEO_*_MPLANE FORMATS: Same as Case A-1, just changing fields from v4l2_format to use mplane API. CREATE BUFFER: If data-offset is zero, same as Case A-1. NOTE A-2.1: If data_offset isn't zero, then I return an error, since we don't support it. Unless if we re-pourpose the data_offset field as previously proposed. But this looks non consistent with single planar, see NOTE A-1.2. REQ BUFFER: 1. vb2 calls queue_setup to ask the driver about the number of memory buffers in a frame buffer 2. If queue_setup() return a single mem-buffer then it is the same as Case A-1. NOTE A-2.2: If driver returns multiple buffers, then we can't convert back to clasic non-M-variant and we fail. My proposed solution is adding a hint to queue_setup(), see NOTE A-1.3. This hint would depend if the API was multiplanar or not, and if it was M-variant or not. QUEUE BUFFER: 1. vb2 receives v4l2_buffer from userspace (index, type and planes array are filled) 2. vb2 converts v4l2_buffer to v4l2_ext_buffer according to the pixelformat. NOTE: A-2.3: to convert this properly, I thought we could use buf_prepare() to get the updated information of the pixelformat ans sizeimage, but .buf_prepare() is called after this conversion, so we need to call v4l2_g_ext_pix_format() from vb2 somehow, my current solution is to add another callback in vb2_ops. 2. vb2 gets vb2_buffer from index and fills vb2_v4l2_buffer.planes from the converted v4l2_ext_buffer. 3. vb2_buffer is validated by .buf_prepare() and gets processed. 4. v4l2_buffer is converted back to v4l2_ext_buffer and sent to userspace. Case A-3: Multiplanar API with M-variant pixelformat - I'm assuming the driver only reports V4L2_CAP_VIDEO_*_MPLANE FORMATS: 1. framework receives v4l2_format 2. framework converts to v4l2_ext_pix_format, which is easier, we just need to normalize the pixelformat. 3. v4l2_ext_pix_format gets processed 4. framework converts back to v4l2_format keeping the original and sends pixelformat to userspace. NOTE A-3.1: I need to save the original pixelformat, so I can know that I need to convert back to M-variant. CREATE BUFFERS: 1. vb2 receives v4l2_buffer from userspace 2. vb2 converts to v4l2_ext_buffer, which is easier, besides complication from NOTE A-1.1. 3. vb2 validates the sizes with queue_setup() 4. vb2 converts it back to v4l2_buffer and sends to userspace REQ BUFFER: 1. vb2 calls queue_setup to ask the driver about the number of memory buffers in a frame buffer 2. If queue_setup() returns a mem buffer per component then we can continue. NOTE A-3.2: If driver doesn't return a different mem_buffer per color component, then we can't convert back to clasic M-variant and we fail, another reason to a hint in queue_setup(). See NOTE A-1.3 and A-2-2. QUEUE BUFFER: same as Case A-2. =========================================== B: Scenarios where: userspace -> implements ext API driver -> implements classic API ------------------------------------------- - I'm assuming that userspace won't differentiate V4L2_CAP_VIDEO_* from V4L2_CAP_VIDEO_*_MPLANE - I'm not handling the case where we could have the two first planes in a memory buffer and a third plane in another memory buffer Case B-1: Single memory buffer with contiguous planes / driver single planar API FORMATS: 1. framework receives v4l2_ext_pix_format 2. framework converts to v4l2_format non non-M-variant pixelformat (we know we need to convert o non-M-variants because of the driver's capabilities) 3. v4l2_format gets processed 4. framework converts back to v4l2_ext_pix_format and sends to userspace. CREATE BUFFERS: 1. vb2 receives v4l2_ext_buffer from userspace with single mem buffer and contiguous planes. 2. vb2 converts to v4l2_buffer with a single plane 3. v4l2_buffer is validated by queue_setup() 4. vb2 converts back to v4l2_ext_format and sends to userspace. Case B-2: Single memory buffer with contiguous planes / driver multi planar API FORMATS: 1. framework receives v4l2_ext_pix_format 2. framework converts to v4l2_format non non-M-variant pixelformat QUESTION: should we convert to M-variant instead? 3. v4l2_format gets processed QUESTION: if it fails, should we convert to M-variant and re-try? 4. framework converts back to v4l2_ext_pix_format and sent to userspace. Case B-3: Single memory buffer with non contiguous planes FORMATS: same as B-1 or B-2 (if mplane API or not) CREATE BUFFERS: 1. vb2 receives v4l2_ext_buffer from userspace with single mem buffer and non contiguous planes. 2. we fail, since we can't convert to v4l2_buffer Case B-3: Multi memory buffers / driver is single planar API FORMATS: Same as Case B-2 CREATE BUFFERS: 1. vb2 receives v4l2_ext_buffer from userspace requesting a memory buffer per plane. 2. we fail, since driver doesn't support it Case B-4: Multi memory buffers / driver is multi planar API FORMATS: Same as Case B-2 CREATE BUFFERS: 1. vb2 receives v4l2_ext_buffer from userspace requesting a memory buffer per plane. 2. vb2 convert v4l2_ext_buffer to v4l2_buffer using multiplanar API 3. v4l2_buffer is validated by queue_setup() 4. vb2 converts back to v4l2_ext_format and sends to userspace. Regards, Helen
Hi Helen, On Tue, Aug 04, 2020 at 04:29:35PM -0300, Helen Koike wrote: > The VB2 layer is used by a lot of drivers. Patch it to support the > _EXT_PIX_FMT and _EXT_BUF ioctls in order to ease conversion of existing > drivers to these new APIs. > > Note that internally, the VB2 core is now only using ext structs and old > APIs are supported through conversion wrappers. We decided to only support V4L2_BUF_TYPE_VIDEO* for the ext structs. Still, existing drivers may use vb2 with the other, legacy, buf types. How would they be handled with this change? > > Signed-off-by: Boris Brezillon <boris.brezillon@collabora.com> > Signed-off-by: Helen Koike <helen.koike@collabora.com> > --- > Changes in v5: > - Update with new format and buffer structs > - Updated commit message with the uAPI prefix > > Changes in v4: > - Update with new format and buffer structs > - Fix some bugs caught by v4l2-compliance > - Rebased on top of media/master (post 5.8-rc1) > > Changes in v3: > - Rebased on top of media/master (post 5.4-rc1) > > Changes in v2: > - New patch > --- > .../media/common/videobuf2/videobuf2-core.c | 2 + > .../media/common/videobuf2/videobuf2-v4l2.c | 560 ++++++++++-------- > include/media/videobuf2-core.h | 6 +- > include/media/videobuf2-v4l2.h | 21 +- > 4 files changed, 345 insertions(+), 244 deletions(-) > > diff --git a/drivers/media/common/videobuf2/videobuf2-core.c b/drivers/media/common/videobuf2/videobuf2-core.c > index f544d3393e9d6..d719b1e9c148b 100644 > --- a/drivers/media/common/videobuf2/videobuf2-core.c > +++ b/drivers/media/common/videobuf2/videobuf2-core.c > @@ -1270,6 +1270,7 @@ static int __prepare_dmabuf(struct vb2_buffer *vb) > vb->planes[plane].length = 0; > vb->planes[plane].m.fd = 0; > vb->planes[plane].data_offset = 0; > + vb->planes[plane].dbuf_offset = 0; > > /* Acquire each plane's memory */ > mem_priv = call_ptr_memop(vb, attach_dmabuf, > @@ -1313,6 +1314,7 @@ static int __prepare_dmabuf(struct vb2_buffer *vb) > vb->planes[plane].length = planes[plane].length; > vb->planes[plane].m.fd = planes[plane].m.fd; > vb->planes[plane].data_offset = planes[plane].data_offset; > + vb->planes[plane].dbuf_offset = planes[plane].dbuf_offset; > } > > if (reacquired) { > diff --git a/drivers/media/common/videobuf2/videobuf2-v4l2.c b/drivers/media/common/videobuf2/videobuf2-v4l2.c > index 30caad27281e1..911681d24b3ae 100644 > --- a/drivers/media/common/videobuf2/videobuf2-v4l2.c > +++ b/drivers/media/common/videobuf2/videobuf2-v4l2.c > @@ -29,6 +29,7 @@ > #include <media/v4l2-fh.h> > #include <media/v4l2-event.h> > #include <media/v4l2-common.h> > +#include <media/v4l2-ioctl.h> > > #include <media/videobuf2-v4l2.h> > > @@ -56,72 +57,39 @@ module_param(debug, int, 0644); > V4L2_BUF_FLAG_TIMECODE | \ > V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF) > > -/* > - * __verify_planes_array() - verify that the planes array passed in struct > - * v4l2_buffer from userspace can be safely used > - */ > -static int __verify_planes_array(struct vb2_buffer *vb, const struct v4l2_buffer *b) > -{ > - if (!V4L2_TYPE_IS_MULTIPLANAR(b->type)) > - return 0; > - > - /* Is memory for copying plane information present? */ > - if (b->m.planes == NULL) { > - dprintk(vb->vb2_queue, 1, > - "multi-planar buffer passed but planes array not provided\n"); > - return -EINVAL; > - } > - > - if (b->length < vb->num_planes || b->length > VB2_MAX_PLANES) { > - dprintk(vb->vb2_queue, 1, > - "incorrect planes array length, expected %d, got %d\n", > - vb->num_planes, b->length); > - return -EINVAL; > - } > - > - return 0; > -} > - > static int __verify_planes_array_core(struct vb2_buffer *vb, const void *pb) > { > - return __verify_planes_array(vb, pb); > + return 0; > } > > /* > * __verify_length() - Verify that the bytesused value for each plane fits in > * the plane length and that the data offset doesn't exceed the bytesused value. > */ > -static int __verify_length(struct vb2_buffer *vb, const struct v4l2_buffer *b) > +static int __verify_length(struct vb2_buffer *vb, > + const struct v4l2_ext_buffer *b) > { > unsigned int length; > unsigned int bytesused; > - unsigned int plane; > + unsigned int i; > > if (V4L2_TYPE_IS_CAPTURE(b->type)) > return 0; > > - if (V4L2_TYPE_IS_MULTIPLANAR(b->type)) { > - for (plane = 0; plane < vb->num_planes; ++plane) { > - length = (b->memory == VB2_MEMORY_USERPTR || > - b->memory == VB2_MEMORY_DMABUF) > - ? b->m.planes[plane].length > - : vb->planes[plane].length; > - bytesused = b->m.planes[plane].bytesused > - ? b->m.planes[plane].bytesused : length; > - > - if (b->m.planes[plane].bytesused > length) > - return -EINVAL; > - > - if (b->m.planes[plane].data_offset > 0 && > - b->m.planes[plane].data_offset >= bytesused) > - return -EINVAL; > - } > - } else { > - length = (b->memory == VB2_MEMORY_USERPTR || > - b->memory == VB2_MEMORY_DMABUF) > - ? b->length : vb->planes[0].length; > + for (i = 0; i < vb->num_planes; ++i) { > + const struct v4l2_ext_plane *plane = &b->planes[i]; > > - if (b->bytesused > length) > + length = (plane->memory == VB2_MEMORY_USERPTR || > + plane->memory == VB2_MEMORY_DMABUF) ? > + plane->buffer_length : > + vb->planes[i].length; > + bytesused = plane->plane_length ? > + plane->plane_length : length; > + > + if (bytesused > length) > + return -EINVAL; > + > + if (plane->offset + bytesused > length) > return -EINVAL; > } > > @@ -140,21 +108,12 @@ static void __init_vb2_v4l2_buffer(struct vb2_buffer *vb) > > static void __copy_timestamp(struct vb2_buffer *vb, const void *pb) > { > - const struct v4l2_buffer *b = pb; > - struct vb2_v4l2_buffer *vbuf = to_vb2_v4l2_buffer(vb); > + const struct v4l2_ext_buffer *b = pb; > struct vb2_queue *q = vb->vb2_queue; > > - if (q->is_output) { > - /* > - * For output buffers copy the timestamp if needed, > - * and the timecode field and flag if needed. > - */ > - if (q->copy_timestamp) > - vb->timestamp = v4l2_buffer_get_timestamp(b); > - vbuf->flags |= b->flags & V4L2_BUF_FLAG_TIMECODE; > - if (b->flags & V4L2_BUF_FLAG_TIMECODE) > - vbuf->timecode = b->timecode; Is it okay to remove the timecode copying functionality? > - } > + /* For output buffers copy the timestamp if needed. */ > + if (q->is_output && q->copy_timestamp) > + vb->timestamp = b->timestamp; > }; > > static void vb2_warn_zero_bytesused(struct vb2_buffer *vb) > @@ -173,7 +132,8 @@ static void vb2_warn_zero_bytesused(struct vb2_buffer *vb) > pr_warn("use the actual size instead.\n"); > } > > -static int vb2_fill_vb2_v4l2_buffer(struct vb2_buffer *vb, struct v4l2_buffer *b) > +static int vb2_fill_vb2_v4l2_buffer(struct vb2_buffer *vb, > + struct v4l2_ext_buffer *b) > { > struct vb2_queue *q = vb->vb2_queue; > struct vb2_v4l2_buffer *vbuf = to_vb2_v4l2_buffer(vb); > @@ -203,110 +163,67 @@ static int vb2_fill_vb2_v4l2_buffer(struct vb2_buffer *vb, struct v4l2_buffer *b > vbuf->request_fd = -1; > vbuf->is_held = false; > > - if (V4L2_TYPE_IS_MULTIPLANAR(b->type)) { > - switch (b->memory) { > - case VB2_MEMORY_USERPTR: > - for (plane = 0; plane < vb->num_planes; ++plane) { > - planes[plane].m.userptr = > - b->m.planes[plane].m.userptr; > - planes[plane].length = > - b->m.planes[plane].length; > - } > - break; > - case VB2_MEMORY_DMABUF: > - for (plane = 0; plane < vb->num_planes; ++plane) { > - planes[plane].m.fd = > - b->m.planes[plane].m.fd; > - planes[plane].length = > - b->m.planes[plane].length; > - } > - break; > - default: > - for (plane = 0; plane < vb->num_planes; ++plane) { > - planes[plane].m.offset = > - vb->planes[plane].m.offset; > - planes[plane].length = > - vb->planes[plane].length; > - } > - break; > + for (plane = 0; plane < vb->num_planes; ++plane) { > + if (b->planes[0].memory != b->planes[plane].memory) { > + dprintk(q, 1, "planes should have the same memory type\n"); > + return -EINVAL; > } > + } > > - /* Fill in driver-provided information for OUTPUT types */ > - if (V4L2_TYPE_IS_OUTPUT(b->type)) { > - /* > - * Will have to go up to b->length when API starts > - * accepting variable number of planes. > - * > - * If bytesused == 0 for the output buffer, then fall > - * back to the full buffer size. In that case > - * userspace clearly never bothered to set it and > - * it's a safe assumption that they really meant to > - * use the full plane sizes. > - * > - * Some drivers, e.g. old codec drivers, use bytesused == 0 > - * as a way to indicate that streaming is finished. > - * In that case, the driver should use the > - * allow_zero_bytesused flag to keep old userspace > - * applications working. > - */ > - for (plane = 0; plane < vb->num_planes; ++plane) { > - struct vb2_plane *pdst = &planes[plane]; > - struct v4l2_plane *psrc = &b->m.planes[plane]; > - > - if (psrc->bytesused == 0) > - vb2_warn_zero_bytesused(vb); > - > - if (vb->vb2_queue->allow_zero_bytesused) > - pdst->bytesused = psrc->bytesused; > - else > - pdst->bytesused = psrc->bytesused ? > - psrc->bytesused : pdst->length; > - pdst->data_offset = psrc->data_offset; > - } > + switch (b->planes[0].memory) { > + case VB2_MEMORY_USERPTR: > + for (plane = 0; plane < vb->num_planes; ++plane) { > + planes[plane].m.userptr = b->planes[plane].m.userptr; > + planes[plane].length = b->planes[plane].buffer_length; > } > - } else { > + break; > + case VB2_MEMORY_DMABUF: > + for (plane = 0; plane < vb->num_planes; ++plane) { > + planes[plane].m.fd = b->planes[plane].m.dmabuf_fd; > + planes[plane].dbuf_offset = b->planes[plane].offset; > + planes[plane].length = b->planes[plane].buffer_length; > + } > + break; > + default: > + for (plane = 0; plane < vb->num_planes; ++plane) { > + planes[plane].m.offset = vb->planes[plane].m.offset; > + planes[plane].length = vb->planes[plane].length; > + } > + break; > + } > + > + /* Fill in driver-provided information for OUTPUT types */ > + if (V4L2_TYPE_IS_OUTPUT(b->type)) { > /* > - * Single-planar buffers do not use planes array, > - * so fill in relevant v4l2_buffer struct fields instead. > - * In videobuf we use our internal V4l2_planes struct for > - * single-planar buffers as well, for simplicity. > + * Will have to go up to b->length when API starts > + * accepting variable number of planes. > * > - * If bytesused == 0 for the output buffer, then fall back > - * to the full buffer size as that's a sensible default. > + * If bytesused == 0 for the output buffer, then fall Should this be updated with the new field name? > + * back to the full buffer size. In that case > + * userspace clearly never bothered to set it and > + * it's a safe assumption that they really meant to > + * use the full plane sizes. > * > - * Some drivers, e.g. old codec drivers, use bytesused == 0 as > - * a way to indicate that streaming is finished. In that case, > - * the driver should use the allow_zero_bytesused flag to keep > - * old userspace applications working. > + * Some drivers, e.g. old codec drivers, use bytesused == 0 > + * as a way to indicate that streaming is finished. > + * In that case, the driver should use the > + * allow_zero_bytesused flag to keep old userspace > + * applications working. Do we retain this behavior in the new API? If no, I guess we need to check if this was old or new API and react appropriately. > */ > - switch (b->memory) { > - case VB2_MEMORY_USERPTR: > - planes[0].m.userptr = b->m.userptr; > - planes[0].length = b->length; > - break; > - case VB2_MEMORY_DMABUF: > - planes[0].m.fd = b->m.fd; > - planes[0].length = b->length; > - break; > - default: > - planes[0].m.offset = vb->planes[0].m.offset; > - planes[0].length = vb->planes[0].length; > - break; > - } > + for (plane = 0; plane < vb->num_planes; ++plane) { > + struct vb2_plane *pdst = &planes[plane]; > + struct v4l2_ext_plane *psrc = &b->planes[plane]; > > - planes[0].data_offset = 0; > - if (V4L2_TYPE_IS_OUTPUT(b->type)) { > - if (b->bytesused == 0) > + if (psrc->plane_length == 0) > vb2_warn_zero_bytesused(vb); > > if (vb->vb2_queue->allow_zero_bytesused) > - planes[0].bytesused = b->bytesused; > + pdst->bytesused = psrc->plane_length; > else > - planes[0].bytesused = b->bytesused ? > - b->bytesused : planes[0].length; > - } else > - planes[0].bytesused = 0; > - > + pdst->bytesused = psrc->plane_length ? > + psrc->plane_length : > + pdst->length; > + } > } > > /* Zero flags that we handle */ > @@ -343,7 +260,7 @@ static int vb2_fill_vb2_v4l2_buffer(struct vb2_buffer *vb, struct v4l2_buffer *b > > static void set_buffer_cache_hints(struct vb2_queue *q, > struct vb2_buffer *vb, > - struct v4l2_buffer *b) > + struct v4l2_ext_buffer *b) > { > /* > * DMA exporter should take care of cache syncs, so we can avoid > @@ -388,17 +305,44 @@ static void set_buffer_cache_hints(struct vb2_queue *q, > vb->need_cache_sync_on_prepare = 0; > } > > +static enum v4l2_buf_type vb2_ext_qtype(struct vb2_queue *q) > +{ > + if (!q->is_multiplanar) > + return q->type; Do we need this explicit check? Wouldn't the code below would return the right thing anyway? > + > + if (q->type == V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE) > + return V4L2_BUF_TYPE_VIDEO_CAPTURE; > + else if (q->type == V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE) > + return V4L2_BUF_TYPE_VIDEO_OUTPUT; > + > + return q->type; > +} > + > +static enum v4l2_buf_type vb2_ext_type(unsigned int type, bool is_multiplanar) > +{ > + if (!is_multiplanar) > + return type; Ditto. > + > + if (type == V4L2_BUF_TYPE_VIDEO_CAPTURE) > + return V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; > + else if (type == V4L2_BUF_TYPE_VIDEO_OUTPUT) > + return V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE; > + > + return type; > +} > + > static int vb2_queue_or_prepare_buf(struct vb2_queue *q, struct media_device *mdev, > - struct v4l2_buffer *b, bool is_prepare, > + struct v4l2_ext_buffer *b, bool is_prepare, > struct media_request **p_req) > { > const char *opname = is_prepare ? "prepare_buf" : "qbuf"; > struct media_request *req; > struct vb2_v4l2_buffer *vbuf; > struct vb2_buffer *vb; > + unsigned int i; > int ret; > > - if (b->type != q->type) { > + if (b->type != vb2_ext_qtype(q)) { > dprintk(q, 1, "%s: invalid buffer type\n", opname); > return -EINVAL; > } > @@ -414,16 +358,14 @@ static int vb2_queue_or_prepare_buf(struct vb2_queue *q, struct media_device *md > return -EINVAL; > } > > - if (b->memory != q->memory) { > + for (i = 0; i < VIDEO_MAX_PLANES && b->planes[i].buffer_length; i++) > + if (b->planes[i].memory != q->memory) { > dprintk(q, 1, "%s: invalid memory type\n", opname); > return -EINVAL; > } > > vb = q->bufs[b->index]; > vbuf = to_vb2_v4l2_buffer(vb); > - ret = __verify_planes_array(vb, b); > - if (ret) > - return ret; > > if (!is_prepare && (b->flags & V4L2_BUF_FLAG_REQUEST_FD) && > vb->state != VB2_BUF_STATE_DEQUEUED) { > @@ -487,11 +429,6 @@ static int vb2_queue_or_prepare_buf(struct vb2_queue *q, struct media_device *md > !q->ops->buf_out_validate)) > return -EINVAL; > > - if (b->request_fd < 0) { > - dprintk(q, 1, "%s: request_fd < 0\n", opname); > - return -EINVAL; > - } > - I guess this code was useless already, because the call below would validate the FD, but should it be perhaps removed in a separate patch? > req = media_request_get_by_fd(mdev, b->request_fd); > if (IS_ERR(req)) { > dprintk(q, 1, "%s: invalid request_fd\n", opname); > @@ -516,64 +453,46 @@ static int vb2_queue_or_prepare_buf(struct vb2_queue *q, struct media_device *md > } > > /* > - * __fill_v4l2_buffer() - fill in a struct v4l2_buffer with information to be > - * returned to userspace > + * __fill_v4l2_buffer() - fill in a struct v4l2_ext_buffer with information to > + * be returned to userspace > */ > static void __fill_v4l2_buffer(struct vb2_buffer *vb, void *pb) > { > - struct v4l2_buffer *b = pb; > + struct v4l2_ext_buffer *b = pb; > struct vb2_v4l2_buffer *vbuf = to_vb2_v4l2_buffer(vb); > struct vb2_queue *q = vb->vb2_queue; > unsigned int plane; > > /* Copy back data such as timestamp, flags, etc. */ > b->index = vb->index; > - b->type = vb->type; > - b->memory = vb->memory; > - b->bytesused = 0; > + b->type = vb2_ext_qtype(q); > > b->flags = vbuf->flags; > b->field = vbuf->field; > - v4l2_buffer_set_timestamp(b, vb->timestamp); > - b->timecode = vbuf->timecode; > + b->timestamp = vb->timestamp; > b->sequence = vbuf->sequence; > - b->reserved2 = 0; > b->request_fd = 0; > + memset(b->reserved, 0, sizeof(b->reserved)); > > - if (q->is_multiplanar) { > - /* > - * Fill in plane-related data if userspace provided an array > - * for it. The caller has already verified memory and size. > - */ > - b->length = vb->num_planes; > - for (plane = 0; plane < vb->num_planes; ++plane) { > - struct v4l2_plane *pdst = &b->m.planes[plane]; > - struct vb2_plane *psrc = &vb->planes[plane]; > - > - pdst->bytesused = psrc->bytesused; > - pdst->length = psrc->length; > - if (q->memory == VB2_MEMORY_MMAP) > - pdst->m.mem_offset = psrc->m.offset; > - else if (q->memory == VB2_MEMORY_USERPTR) > - pdst->m.userptr = psrc->m.userptr; > - else if (q->memory == VB2_MEMORY_DMABUF) > - pdst->m.fd = psrc->m.fd; > - pdst->data_offset = psrc->data_offset; > - memset(pdst->reserved, 0, sizeof(pdst->reserved)); > - } > - } else { > - /* > - * We use length and offset in v4l2_planes array even for > - * single-planar buffers, but userspace does not. > - */ > - b->length = vb->planes[0].length; > - b->bytesused = vb->planes[0].bytesused; > + /* > + * Fill in plane-related data if userspace provided an array > + * for it. The caller has already verified memory and size. > + */ > + for (plane = 0; plane < vb->num_planes; ++plane) { > + struct v4l2_ext_plane *pdst = &b->planes[plane]; > + struct vb2_plane *psrc = &vb->planes[plane]; > + > + pdst->memory = vb->memory; > + pdst->plane_length = psrc->bytesused; > + pdst->buffer_length = psrc->length; > + pdst->offset = psrc->dbuf_offset; > if (q->memory == VB2_MEMORY_MMAP) > - b->m.offset = vb->planes[0].m.offset; > + pdst->m.mem_offset = psrc->m.offset; > else if (q->memory == VB2_MEMORY_USERPTR) > - b->m.userptr = vb->planes[0].m.userptr; > + pdst->m.userptr = psrc->m.userptr; > else if (q->memory == VB2_MEMORY_DMABUF) > - b->m.fd = vb->planes[0].m.fd; > + pdst->m.dmabuf_fd = psrc->m.fd; > + memset(pdst->reserved, 0, sizeof(pdst->reserved)); > } > > /* > @@ -668,6 +587,35 @@ int vb2_find_timestamp(const struct vb2_queue *q, u64 timestamp, > } > EXPORT_SYMBOL_GPL(vb2_find_timestamp); > > +#define vb2_buf_to_ext_buf_op(_name, ...) \ > +({ \ > + int ret; \ > + \ > + ret = v4l2_buffer_to_ext_buffer(b, &eb); \ > + if (!ret) \ > + ret = _name(__VA_ARGS__); \ > + if (!ret) \ > + ret = v4l2_ext_buffer_to_buffer(&eb, b, \ > + q->is_multiplanar); \ I'm not very happy with this macro implicitly relying on existence of some specific variables with predefined names in the scope of the caller. That said, I don't have a good idea on how this could be fixed, other than just repeating this code manually in each function. If we don't find anything better, I think at least a comment here explaining the assumptions would make it a bit better. > + ret; \ > +}) > + > +int vb2_ext_querybuf(struct vb2_queue *q, struct v4l2_ext_buffer *b) > +{ > + if (b->type != vb2_ext_qtype(q)) { > + dprintk(q, 1, "wrong buffer type\n"); > + return -EINVAL; > + } > + > + if (b->index >= q->num_buffers) { > + dprintk(q, 1, "buffer index out of range\n"); > + return -EINVAL; > + } > + vb2_core_querybuf(q, b->index, b); > + return 0; > +} > +EXPORT_SYMBOL(vb2_ext_querybuf); > + > /* > * vb2_querybuf() - query video buffer information > * @q: videobuf queue > @@ -683,23 +631,9 @@ EXPORT_SYMBOL_GPL(vb2_find_timestamp); > */ > int vb2_querybuf(struct vb2_queue *q, struct v4l2_buffer *b) > { > - struct vb2_buffer *vb; > - int ret; > - > - if (b->type != q->type) { > - dprintk(q, 1, "wrong buffer type\n"); > - return -EINVAL; > - } > + struct v4l2_ext_buffer eb; > > - if (b->index >= q->num_buffers) { > - dprintk(q, 1, "buffer index out of range\n"); > - return -EINVAL; > - } > - vb = q->bufs[b->index]; > - ret = __verify_planes_array(vb, b); > - if (!ret) > - vb2_core_querybuf(q, b->index, b); > - return ret; > + return vb2_buf_to_ext_buf_op(vb2_ext_querybuf, q, &eb); > } > EXPORT_SYMBOL(vb2_querybuf); > > @@ -741,8 +675,8 @@ int vb2_reqbufs(struct vb2_queue *q, struct v4l2_requestbuffers *req) > } > EXPORT_SYMBOL_GPL(vb2_reqbufs); > > -int vb2_prepare_buf(struct vb2_queue *q, struct media_device *mdev, > - struct v4l2_buffer *b) > +int vb2_ext_prepare_buf(struct vb2_queue *q, struct media_device *mdev, > + struct v4l2_ext_buffer *b) > { > int ret; > > @@ -758,16 +692,59 @@ int vb2_prepare_buf(struct vb2_queue *q, struct media_device *mdev, > > return ret ? ret : vb2_core_prepare_buf(q, b->index, b); > } > +EXPORT_SYMBOL_GPL(vb2_ext_prepare_buf); > + > +int vb2_prepare_buf(struct vb2_queue *q, struct media_device *mdev, > + struct v4l2_buffer *b) > +{ > + struct v4l2_ext_buffer eb; > + > + return vb2_buf_to_ext_buf_op(vb2_ext_prepare_buf, q, mdev, &eb); > +} > EXPORT_SYMBOL_GPL(vb2_prepare_buf); > > +int vb2_ext_create_bufs(struct vb2_queue *q, > + struct v4l2_ext_create_buffers *create) > +{ > + unsigned int requested_sizes[VIDEO_MAX_PLANES]; > + struct v4l2_ext_pix_format *f = &create->format; > + int ret = vb2_verify_memory_type(q, create->memory, > + vb2_ext_type(f->type, q->is_multiplanar)); > + unsigned i; > + > + if (create->format.type != V4L2_BUF_TYPE_VIDEO_CAPTURE && > + create->format.type != V4L2_BUF_TYPE_VIDEO_OUTPUT) > + return -EINVAL; > + > + fill_buf_caps(q, &create->capabilities); > + clear_consistency_attr(q, create->memory, &create->flags); > + create->index = q->num_buffers; > + if (create->count == 0) > + return ret != -EBUSY ? ret : 0; > + > + if (!f->plane_fmt[0].sizeimage) > + return -EINVAL; > + for (i = 0; i < VIDEO_MAX_PLANES && > + f->plane_fmt[i].sizeimage; i++) > + requested_sizes[i] = f->plane_fmt[i].sizeimage; > + > + return ret ? ret : vb2_core_create_bufs(q, create->memory, > + create->flags, > + &create->count, > + i, > + requested_sizes); > +} > +EXPORT_SYMBOL_GPL(vb2_ext_create_bufs); > + > int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create) > { > + struct v4l2_format *f = &create->format; > unsigned requested_planes = 1; > unsigned requested_sizes[VIDEO_MAX_PLANES]; > - struct v4l2_format *f = &create->format; > int ret = vb2_verify_memory_type(q, create->memory, f->type); > unsigned i; > > + > fill_buf_caps(q, &create->capabilities); > clear_consistency_attr(q, create->memory, &create->flags); > create->index = q->num_buffers; > @@ -777,18 +754,29 @@ int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create) > switch (f->type) { > case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: > case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: > - requested_planes = f->fmt.pix_mp.num_planes; > - if (requested_planes == 0 || > - requested_planes > VIDEO_MAX_PLANES) > - return -EINVAL; > - for (i = 0; i < requested_planes; i++) > - requested_sizes[i] = > - f->fmt.pix_mp.plane_fmt[i].sizeimage; > - break; > case V4L2_BUF_TYPE_VIDEO_CAPTURE: > - case V4L2_BUF_TYPE_VIDEO_OUTPUT: > - requested_sizes[0] = f->fmt.pix.sizeimage; > - break; > + case V4L2_BUF_TYPE_VIDEO_OUTPUT: { > + struct v4l2_ext_create_buffers ecreate = { > + .count = create->count, > + .memory = create->memory, > + .flags = create->flags, > + }; > + > + ret = v4l2_format_to_ext_pix_format(&create->format, > + &ecreate.format, true); > + if (ret) > + return ret; > + > + ret = vb2_ext_create_bufs(q, &ecreate); > + if (ret) > + return ret; > + > + create->index = ecreate.index; > + create->count = ecreate.count; > + create->flags = ecreate.flags; > + create->capabilities = ecreate.capabilities; > + return 0; > + } > case V4L2_BUF_TYPE_VBI_CAPTURE: > case V4L2_BUF_TYPE_VBI_OUTPUT: > requested_sizes[0] = f->fmt.vbi.samples_per_line * > @@ -820,8 +808,8 @@ int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create) > } > EXPORT_SYMBOL_GPL(vb2_create_bufs); > > -int vb2_qbuf(struct vb2_queue *q, struct media_device *mdev, > - struct v4l2_buffer *b) > +int vb2_ext_qbuf(struct vb2_queue *q, struct media_device *mdev, > + struct v4l2_ext_buffer *b) > { > struct media_request *req = NULL; > int ret; > @@ -839,9 +827,19 @@ int vb2_qbuf(struct vb2_queue *q, struct media_device *mdev, > media_request_put(req); > return ret; > } > +EXPORT_SYMBOL_GPL(vb2_ext_qbuf); > + > +int vb2_qbuf(struct vb2_queue *q, struct media_device *mdev, > + struct v4l2_buffer *b) > +{ > + struct v4l2_ext_buffer eb; > + > + return vb2_buf_to_ext_buf_op(vb2_ext_qbuf, q, mdev, &eb); > +} > EXPORT_SYMBOL_GPL(vb2_qbuf); > > -int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking) > +int vb2_ext_dqbuf(struct vb2_queue *q, struct v4l2_ext_buffer *b, > + bool nonblocking) > { > int ret; > > @@ -850,7 +848,7 @@ int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking) > return -EBUSY; > } > > - if (b->type != q->type) { > + if (b->type != vb2_ext_qtype(q)) { > dprintk(q, 1, "invalid buffer type\n"); > return -EINVAL; > } > @@ -870,6 +868,14 @@ int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking) > > return ret; > } > +EXPORT_SYMBOL_GPL(vb2_ext_dqbuf); > + > +int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking) > +{ > + struct v4l2_ext_buffer eb; > + > + return vb2_buf_to_ext_buf_op(vb2_ext_dqbuf, q, &eb, nonblocking); > +} > EXPORT_SYMBOL_GPL(vb2_dqbuf); > > int vb2_streamon(struct vb2_queue *q, enum v4l2_buf_type type) > @@ -1040,6 +1046,33 @@ int vb2_ioctl_create_bufs(struct file *file, void *priv, > } > EXPORT_SYMBOL_GPL(vb2_ioctl_create_bufs); > > +int vb2_ioctl_ext_create_bufs(struct file *file, void *priv, > + struct v4l2_ext_create_buffers *p) > +{ > + struct video_device *vdev = video_devdata(file); > + int res = vb2_verify_memory_type(vdev->queue, p->memory, > + vb2_ext_type(p->format.type, vdev->queue->is_multiplanar)); > + > + p->index = vdev->queue->num_buffers; > + fill_buf_caps(vdev->queue, &p->capabilities); > + /* > + * If count == 0, then just check if memory and type are valid. > + * Any -EBUSY result from vb2_verify_memory_type can be mapped to 0. > + */ > + if (p->count == 0) > + return res != -EBUSY ? res : 0; > + if (res) > + return res; > + if (vb2_queue_is_busy(vdev, file)) > + return -EBUSY; > + > + res = vb2_ext_create_bufs(vdev->queue, p); > + if (res == 0) > + vdev->queue->owner = file->private_data; > + return res; > +} > +EXPORT_SYMBOL_GPL(vb2_ioctl_ext_create_bufs); > + > int vb2_ioctl_prepare_buf(struct file *file, void *priv, > struct v4l2_buffer *p) > { > @@ -1051,6 +1084,17 @@ int vb2_ioctl_prepare_buf(struct file *file, void *priv, > } > EXPORT_SYMBOL_GPL(vb2_ioctl_prepare_buf); > > +int vb2_ioctl_ext_prepare_buf(struct file *file, void *priv, > + struct v4l2_ext_buffer *p) > +{ > + struct video_device *vdev = video_devdata(file); > + > + if (vb2_queue_is_busy(vdev, file)) > + return -EBUSY; > + return vb2_ext_prepare_buf(vdev->queue, vdev->v4l2_dev->mdev, p); > +} > +EXPORT_SYMBOL_GPL(vb2_ioctl_ext_prepare_buf); > + > int vb2_ioctl_querybuf(struct file *file, void *priv, struct v4l2_buffer *p) > { > struct video_device *vdev = video_devdata(file); > @@ -1060,6 +1104,16 @@ int vb2_ioctl_querybuf(struct file *file, void *priv, struct v4l2_buffer *p) > } > EXPORT_SYMBOL_GPL(vb2_ioctl_querybuf); > > +int vb2_ioctl_ext_querybuf(struct file *file, void *priv, > + struct v4l2_ext_buffer *p) > +{ > + struct video_device *vdev = video_devdata(file); > + > + /* No need to call vb2_queue_is_busy(), anyone can query buffers. */ > + return vb2_ext_querybuf(vdev->queue, p); > +} > +EXPORT_SYMBOL_GPL(vb2_ioctl_ext_querybuf); > + > int vb2_ioctl_qbuf(struct file *file, void *priv, struct v4l2_buffer *p) > { > struct video_device *vdev = video_devdata(file); > @@ -1070,6 +1124,17 @@ int vb2_ioctl_qbuf(struct file *file, void *priv, struct v4l2_buffer *p) > } > EXPORT_SYMBOL_GPL(vb2_ioctl_qbuf); > > +int vb2_ioctl_ext_qbuf(struct file *file, void *priv, > + struct v4l2_ext_buffer *p) > +{ > + struct video_device *vdev = video_devdata(file); > + > + if (vb2_queue_is_busy(vdev, file)) > + return -EBUSY; > + return vb2_ext_qbuf(vdev->queue, vdev->v4l2_dev->mdev, p); > +} > +EXPORT_SYMBOL_GPL(vb2_ioctl_ext_qbuf); > + > int vb2_ioctl_dqbuf(struct file *file, void *priv, struct v4l2_buffer *p) > { > struct video_device *vdev = video_devdata(file); > @@ -1080,6 +1145,17 @@ int vb2_ioctl_dqbuf(struct file *file, void *priv, struct v4l2_buffer *p) > } > EXPORT_SYMBOL_GPL(vb2_ioctl_dqbuf); > > +int vb2_ioctl_ext_dqbuf(struct file *file, void *priv, > + struct v4l2_ext_buffer *p) > +{ > + struct video_device *vdev = video_devdata(file); > + > + if (vb2_queue_is_busy(vdev, file)) > + return -EBUSY; > + return vb2_ext_dqbuf(vdev->queue, p, file->f_flags & O_NONBLOCK); > +} > +EXPORT_SYMBOL_GPL(vb2_ioctl_ext_dqbuf); > + > int vb2_ioctl_streamon(struct file *file, void *priv, enum v4l2_buf_type i) > { > struct video_device *vdev = video_devdata(file); > diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h > index 52ef92049073e..f334767785bd9 100644 > --- a/include/media/videobuf2-core.h > +++ b/include/media/videobuf2-core.h > @@ -152,6 +152,8 @@ struct vb2_mem_ops { > * @mem_priv: private data with this plane. > * @dbuf: dma_buf - shared buffer object. > * @dbuf_mapped: flag to show whether dbuf is mapped or not > + * @dbuf_offset: offset where the plane starts. Usually 0, unless the buffer > + * is shared by all planes of a multi-planar format. The comment kind of implies that non-zero is a special case, but I wouldn't want driver authors to come to incorrect conclusions based on that. Do we actually need the last sentence at all? > * @bytesused: number of bytes occupied by data in the plane (payload). > * @length: size of this plane (NOT the payload) in bytes. > * @min_length: minimum required size of this plane (NOT the payload) in bytes. > @@ -175,6 +177,7 @@ struct vb2_plane { > void *mem_priv; > struct dma_buf *dbuf; > unsigned int dbuf_mapped; > + unsigned int dbuf_offset; > unsigned int bytesused; > unsigned int length; > unsigned int min_length; > @@ -446,7 +449,8 @@ struct vb2_ops { > * struct vb2_buffer. > * For V4L2 this is a &struct vb2_v4l2_buffer. > * @fill_user_buffer: given a &vb2_buffer fill in the userspace structure. > - * For V4L2 this is a &struct v4l2_buffer. > + * For V4L2 this is a &struct v4l2_buffer or > + * &struct v4l2_ext_buffer. Isn't it always v4l2_ext_buffer with current code? Best regards, Tomasz
On Thu, Nov 19, 2020 at 10:43 PM Helen Koike <helen.koike@collabora.com> wrote: > > > > On 11/19/20 7:08 AM, Helen Koike wrote: > > Hi Tomasz, > > > > On 11/19/20 2:45 AM, Tomasz Figa wrote: > >> On Sat, Nov 14, 2020 at 11:21:26AM -0300, Helen Koike wrote: > >>> Hi Tomasz, > >>> > >>> On 10/2/20 4:49 PM, Tomasz Figa wrote: > >>>> Hi Helen, > >>>> > >>>> On Tue, Aug 04, 2020 at 04:29:33PM -0300, Helen Koike wrote: > >> [snip] > >>>>> +static void v4l_print_ext_pix_format(const void *arg, bool write_only) > >>>>> +{ > >>>>> + const struct v4l2_ext_pix_format *pix = arg; > >>>>> + unsigned int i; > >>>>> + > >>>>> + pr_cont("type=%s, width=%u, height=%u, format=%c%c%c%c, modifier %llx, field=%s, colorspace=%d, ycbcr_enc=%u, quantization=%u, xfer_func=%u\n", > >>>>> + prt_names(pix->type, v4l2_type_names), > >>>>> + pix->width, pix->height, > >>>>> + (pix->pixelformat & 0xff), > >>>>> + (pix->pixelformat >> 8) & 0xff, > >>>>> + (pix->pixelformat >> 16) & 0xff, > >>>>> + (pix->pixelformat >> 24) & 0xff, > >>>>> + pix->modifier, prt_names(pix->field, v4l2_field_names), > >>>>> + pix->colorspace, pix->ycbcr_enc, > >>>>> + pix->quantization, pix->xfer_func); > >>>>> + for (i = 0; i < VIDEO_MAX_PLANES && pix->plane_fmt[i].sizeimage; i++) > >>>> > >>>> This is going to print 8 lines every time. Maybe we could skip 0-sized > >>>> planes or something? > >>> > >>> I'm already checking pix->plane_fmt[i].sizeimage in the loop, it shouldn't > >>> print 8 lines every time. > >>> > >> > >> Oops, how could I not notice it. Sorry for the noise. > >> > >> [snip] > >>>>> +int v4l2_ext_pix_format_to_format(const struct v4l2_ext_pix_format *e, > >>>>> + struct v4l2_format *f, bool mplane_cap, > >>>>> + bool strict) > >>>>> +{ > >>>>> + const struct v4l2_plane_ext_pix_format *pe; > >>>>> + struct v4l2_plane_pix_format *p; > >>>>> + unsigned int i; > >>>>> + > >>>>> + memset(f, 0, sizeof(*f)); > >>>>> + > >>>>> + /* > >>>>> + * Make sure no modifier is required before doing the > >>>>> + * conversion. > >>>>> + */ > >>>>> + if (e->modifier && strict && > >>>> > >>>> Do we need the explicit check for e->modifier != 0 if we have to check for > >>>> the 2 specific values below anyway? > >>> > >>> We don't, since DRM_FORMAT_MOD_LINEAR is zero. > >>> > >>> But I wanted to make it explicit we don't support modifiers in this conversion. > >>> But I can remove this check, no problem. > >>> > >> > >> Yes, please. I think the double checking is confusing for the reader. > > > > ok. > > > >> > >>>> > >>>>> + e->modifier != DRM_FORMAT_MOD_LINEAR && > >>>>> + e->modifier != DRM_FORMAT_MOD_INVALID) > >>>>> + return -EINVAL; > >>>>> + > >>>>> + if (!e->plane_fmt[0].sizeimage && strict) > >>>>> + return -EINVAL; > >>>> > >>>> Why is this incorrect? > >>> > >>> !sizeimage for the first plane means that there are no planes in ef. > >>> strict is true if the result for the conversion should be returned to userspace > >>> and it is not some internal handling. > >>> > >>> So if there are no planes, we would return an incomplete v4l2_format struct > >>> to userspace. > >>> > >>> But this is not very clear, I'll improve this for the next version. > >>> > >> > >> So I can see 2 cases here: > >> > >> 1) Userspace gives ext struct and driver accepts legacy. > >> > >> In this case, the kernel needs to adjust the structure to be correct. > >> -EINVAL is only valid if > >> > >> "The struct v4l2_format type field is invalid or the requested buffer type not supported." > >> > >> as per the current uAPI documentation. > >> > >> 2) Driver gives ext struct and userspace accepts legacy. > >> > >> If at this point we get a struct with no planes, that sounds like a > >> driver bug, so rather than signaling -EINVAL to the userspace, we should > >> probably WARN()? > >> > >> Or am I getting something wrong? :) > > > > Make sense, I'll restructure this for the next version. > > > >> > >> [snip] > >>>>> +{ > >>>>> + const struct v4l2_plane_pix_format *p; > >>>>> + struct v4l2_plane_ext_pix_format *pe; > >>>>> + unsigned int i; > >>>>> + > >>>>> + memset(e, 0, sizeof(*e)); > >>>>> + > >>>>> + switch (f->type) { > >>>>> + case V4L2_BUF_TYPE_VIDEO_CAPTURE: > >>>>> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: > >>>>> + e->width = f->fmt.pix.width; > >>>>> + e->height = f->fmt.pix.height; > >>>>> + e->pixelformat = f->fmt.pix.pixelformat; > >>>>> + e->field = f->fmt.pix.field; > >>>>> + e->colorspace = f->fmt.pix.colorspace; > >>>>> + if (f->fmt.pix.flags) > >>>>> + pr_warn("Ignoring pixelformat flags 0x%x\n", > >>>>> + f->fmt.pix.flags); > >>>> > >>>> Would it make sense to print something like video node name and/or function > >>>> name to explain where this warning comes from? > >>> > >>> I would need to update the function to receive this information, I can try but > >>> I'm not sure if it is worthy. > >>> > >> > >> I don't have a strong opinion on this, so maybe let's see if others have > >> any comments. > >> > >>>> > >>>>> + e->ycbcr_enc = f->fmt.pix.ycbcr_enc; > >>>>> + e->quantization = f->fmt.pix.quantization; > >>>> > >>>> Missing xfer_func? > >>> > >>> Yes, thanks for catching this. > >>> > >>>> > >>>>> + e->plane_fmt[0].bytesperline = f->fmt.pix.bytesperline; > >>>>> + e->plane_fmt[0].sizeimage = f->fmt.pix.sizeimage; > >>>> > >>>> This doesn't look right. In the ext API we expected the planes to describe > >>>> color planes, which means that bytesperline needs to be computed for planes > >>>>> = 1 and sizeimage replaced with per-plane sizes, according to the > >>>>> pixelformat. > >>> > >>> Ack. > >>> > >>> Just to be clear, even if we are using a planar format that isn't a V4L2_PIX_FMT_*M > >>> variant, we should describe every plane separatly. > >>> > >>> For instance, if V4L2_PIX_FMT_YVU420 is being used, then f->fmt.pix.bytesperline > >>> will have data, and we need to calculate bytesperline for all 3 planes, so we'll fill > >>> out: > >>> > >>> f->plane_fmt[0].bytesperline = f->fmt.pix.bytesperline; > >>> f->plane_fmt[1].bytesperline = f->fmt.pix.bytesperline / hdiv; > >>> f->plane_fmt[2].bytesperline = f->fmt.pix.bytesperline / hdiv; > >>> > >>> I'll update this for the next version. > >>> > >> > >> Yes. This basically gives us a unified representation across all > >> pixelformats and allows userspace to handle them in a uniform way, as > >> opposed to current uAPI. > > > > Right, I already updated this in my wip branch for next version. > > > >> > >> [snip] > >>>>> + if (f->type == V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE) > >>>>> + e->type = V4L2_BUF_TYPE_VIDEO_CAPTURE; > >>>>> + else > >>>>> + e->type = V4L2_BUF_TYPE_VIDEO_OUTPUT; > >>>>> + > >>>>> + for (i = 0; i < VIDEO_MAX_PLANES; i++) { > >>>>> + pe = &e->plane_fmt[i]; > >>>>> + p = &f->fmt.pix_mp.plane_fmt[i]; > >>>>> + pe->bytesperline = p->bytesperline; > >>>>> + pe->sizeimage = p->sizeimage; > >>>>> + } > >>>> > >>>> Same here. A blind copy is not enough. For non-M formats, the plane > >>>> parameters need to be filled according to the pixelformat. > >>> > >>> > >>> Right, following the idea above, we need a different handling if we > >>> aren't using a M-variant of the pixelformat, and we also need to > >>> convert the pixelformat from the M-variant to non-M-variant. > >>> > >>> I'll also need to save that the original format was a > >>> M-variant or not, so I can convert it back as expected. > >> > >> I'm still reading the rest of the series, so it might be answered > >> already, but did we decide to do anything about the pixelformat codes > >> themselves? If both M and non-M variants would be allowed with the new > >> API, then I guess there isn't anything to save, because the original > >> format would be preserved? > > > > I was working with the idea that M-variants wouldn't be allowed. > > But then, we have cases where non-M-variant don't exist, such as: > > > > V4L2_PIX_FMT_YVU422M > > V4L2_PIX_FMT_YVU444M > > > > (at least, I couldn't find non-M-variant equivalent for those) > > > > But actually, I don't think we formally decided this (and it seems > > easier to implement if both are allowed). > > > > Should we allow both variants in the Ext API ? > > I see 3 options: > > 1) Ext API doesn't accept M-variants and return -EINVAL. > > But this doesn't seem to be the v4l2 way, where we avoid returning > errors and try to adjust to what we think it is better. > > At the same time, this could allow us, in a very remote hypothetical > future situation, to remove the M-variants from the kernel when/if > the old API gets obsolete. > > Future ENUM_EXT_FMT won't enumerate M-variants in this option. > > 2) Ext API accept M-variants without normalization. > > The driver can receive both variants, and need to handle both as > equivalents, i.e. if (V4L2_PIX_FMT_YUV420M || V4L2_PIX_FMT_YUV420) > > Both can be returned to userspace. > > Future ENUM_EXT_FMT can enumerate M-variants in this option. > > 3) Ext API accept M-variants with normalization. > > If userspace uses V4L2_PIX_FMT_YUV420M, the framework converts > to V4L2_PIX_FMT_YUV420 before passing it to the driver. > > Only V4L2_PIX_FMT_YUV420 is sent back to userspace (even if userspace > used the M variant, the kernel normalizes it, which is a similar behavior > when userspace try to use a non-supported resolution and the kernel > adjusts it). > > (we could also leave this pixelformat normalization to the driver, > but I don't see a reason to that) > > Future ENUM_EXT_FMT won't enumerate M-variants in this option. > > > > I'm leaning towards option 3, please let me know your thoughts. Same here. I think it would make it easier to support both APIs at the same time and also allows having M-only formats as is. The drawback of option 3 is that it would basically carve the non-M and M fourcc duality in stone and we couldn't clean them up even if we eventually deprecate the old API after many years. On the other hand, in practice we might not be able to deprecate the old API anyway, like what happened with the current single-planar API, so maybe that's fine? I'd like others' opinions on this. Best regards, Tomasz
Hi Tomasz, Thank you for your comments, On 12/14/20 5:52 AM, Tomasz Figa wrote: > Hi Helen, > > On Tue, Aug 04, 2020 at 04:29:35PM -0300, Helen Koike wrote: >> The VB2 layer is used by a lot of drivers. Patch it to support the >> _EXT_PIX_FMT and _EXT_BUF ioctls in order to ease conversion of existing >> drivers to these new APIs. >> >> Note that internally, the VB2 core is now only using ext structs and old >> APIs are supported through conversion wrappers. > > We decided to only support V4L2_BUF_TYPE_VIDEO* for the ext structs. Still, > existing drivers may use vb2 with the other, legacy, buf types. How would > they be handled with this change? I completly refactored this patch in my wip branch, I'll submit for comments soon after finishing addressing the other comments. The way I'm approaching this is to support both structures v4l2_buffer and v4l2_ext_buffer, but only in the vb2 entry points, since all the information we need is in vb2_buffer struct. To implement this I had to use new hooks in the framework. I think it is easier if you take a look in next version when I submited it. > >> >> Signed-off-by: Boris Brezillon <boris.brezillon@collabora.com> >> Signed-off-by: Helen Koike <helen.koike@collabora.com> >> --- >> Changes in v5: >> - Update with new format and buffer structs >> - Updated commit message with the uAPI prefix >> >> Changes in v4: >> - Update with new format and buffer structs >> - Fix some bugs caught by v4l2-compliance >> - Rebased on top of media/master (post 5.8-rc1) >> >> Changes in v3: >> - Rebased on top of media/master (post 5.4-rc1) >> >> Changes in v2: >> - New patch >> --- >> .../media/common/videobuf2/videobuf2-core.c | 2 + >> .../media/common/videobuf2/videobuf2-v4l2.c | 560 ++++++++++-------- >> include/media/videobuf2-core.h | 6 +- >> include/media/videobuf2-v4l2.h | 21 +- >> 4 files changed, 345 insertions(+), 244 deletions(-) >> >> diff --git a/drivers/media/common/videobuf2/videobuf2-core.c b/drivers/media/common/videobuf2/videobuf2-core.c >> index f544d3393e9d6..d719b1e9c148b 100644 >> --- a/drivers/media/common/videobuf2/videobuf2-core.c >> +++ b/drivers/media/common/videobuf2/videobuf2-core.c >> @@ -1270,6 +1270,7 @@ static int __prepare_dmabuf(struct vb2_buffer *vb) >> vb->planes[plane].length = 0; >> vb->planes[plane].m.fd = 0; >> vb->planes[plane].data_offset = 0; >> + vb->planes[plane].dbuf_offset = 0; >> >> /* Acquire each plane's memory */ >> mem_priv = call_ptr_memop(vb, attach_dmabuf, >> @@ -1313,6 +1314,7 @@ static int __prepare_dmabuf(struct vb2_buffer *vb) >> vb->planes[plane].length = planes[plane].length; >> vb->planes[plane].m.fd = planes[plane].m.fd; >> vb->planes[plane].data_offset = planes[plane].data_offset; >> + vb->planes[plane].dbuf_offset = planes[plane].dbuf_offset; >> } >> >> if (reacquired) { >> diff --git a/drivers/media/common/videobuf2/videobuf2-v4l2.c b/drivers/media/common/videobuf2/videobuf2-v4l2.c >> index 30caad27281e1..911681d24b3ae 100644 >> --- a/drivers/media/common/videobuf2/videobuf2-v4l2.c >> +++ b/drivers/media/common/videobuf2/videobuf2-v4l2.c >> @@ -29,6 +29,7 @@ >> #include <media/v4l2-fh.h> >> #include <media/v4l2-event.h> >> #include <media/v4l2-common.h> >> +#include <media/v4l2-ioctl.h> >> >> #include <media/videobuf2-v4l2.h> >> >> @@ -56,72 +57,39 @@ module_param(debug, int, 0644); >> V4L2_BUF_FLAG_TIMECODE | \ >> V4L2_BUF_FLAG_M2M_HOLD_CAPTURE_BUF) >> >> -/* >> - * __verify_planes_array() - verify that the planes array passed in struct >> - * v4l2_buffer from userspace can be safely used >> - */ >> -static int __verify_planes_array(struct vb2_buffer *vb, const struct v4l2_buffer *b) >> -{ >> - if (!V4L2_TYPE_IS_MULTIPLANAR(b->type)) >> - return 0; >> - >> - /* Is memory for copying plane information present? */ >> - if (b->m.planes == NULL) { >> - dprintk(vb->vb2_queue, 1, >> - "multi-planar buffer passed but planes array not provided\n"); >> - return -EINVAL; >> - } >> - >> - if (b->length < vb->num_planes || b->length > VB2_MAX_PLANES) { >> - dprintk(vb->vb2_queue, 1, >> - "incorrect planes array length, expected %d, got %d\n", >> - vb->num_planes, b->length); >> - return -EINVAL; >> - } >> - >> - return 0; >> -} >> - >> static int __verify_planes_array_core(struct vb2_buffer *vb, const void *pb) >> { >> - return __verify_planes_array(vb, pb); >> + return 0; >> } >> >> /* >> * __verify_length() - Verify that the bytesused value for each plane fits in >> * the plane length and that the data offset doesn't exceed the bytesused value. >> */ >> -static int __verify_length(struct vb2_buffer *vb, const struct v4l2_buffer *b) >> +static int __verify_length(struct vb2_buffer *vb, >> + const struct v4l2_ext_buffer *b) >> { >> unsigned int length; >> unsigned int bytesused; >> - unsigned int plane; >> + unsigned int i; >> >> if (V4L2_TYPE_IS_CAPTURE(b->type)) >> return 0; >> >> - if (V4L2_TYPE_IS_MULTIPLANAR(b->type)) { >> - for (plane = 0; plane < vb->num_planes; ++plane) { >> - length = (b->memory == VB2_MEMORY_USERPTR || >> - b->memory == VB2_MEMORY_DMABUF) >> - ? b->m.planes[plane].length >> - : vb->planes[plane].length; >> - bytesused = b->m.planes[plane].bytesused >> - ? b->m.planes[plane].bytesused : length; >> - >> - if (b->m.planes[plane].bytesused > length) >> - return -EINVAL; >> - >> - if (b->m.planes[plane].data_offset > 0 && >> - b->m.planes[plane].data_offset >= bytesused) >> - return -EINVAL; >> - } >> - } else { >> - length = (b->memory == VB2_MEMORY_USERPTR || >> - b->memory == VB2_MEMORY_DMABUF) >> - ? b->length : vb->planes[0].length; >> + for (i = 0; i < vb->num_planes; ++i) { >> + const struct v4l2_ext_plane *plane = &b->planes[i]; >> >> - if (b->bytesused > length) >> + length = (plane->memory == VB2_MEMORY_USERPTR || >> + plane->memory == VB2_MEMORY_DMABUF) ? >> + plane->buffer_length : >> + vb->planes[i].length; >> + bytesused = plane->plane_length ? >> + plane->plane_length : length; >> + >> + if (bytesused > length) >> + return -EINVAL; >> + >> + if (plane->offset + bytesused > length) >> return -EINVAL; >> } >> >> @@ -140,21 +108,12 @@ static void __init_vb2_v4l2_buffer(struct vb2_buffer *vb) >> >> static void __copy_timestamp(struct vb2_buffer *vb, const void *pb) >> { >> - const struct v4l2_buffer *b = pb; >> - struct vb2_v4l2_buffer *vbuf = to_vb2_v4l2_buffer(vb); >> + const struct v4l2_ext_buffer *b = pb; >> struct vb2_queue *q = vb->vb2_queue; >> >> - if (q->is_output) { >> - /* >> - * For output buffers copy the timestamp if needed, >> - * and the timecode field and flag if needed. >> - */ >> - if (q->copy_timestamp) >> - vb->timestamp = v4l2_buffer_get_timestamp(b); >> - vbuf->flags |= b->flags & V4L2_BUF_FLAG_TIMECODE; >> - if (b->flags & V4L2_BUF_FLAG_TIMECODE) >> - vbuf->timecode = b->timecode; > > Is it okay to remove the timecode copying functionality? > >> - } >> + /* For output buffers copy the timestamp if needed. */ >> + if (q->is_output && q->copy_timestamp) >> + vb->timestamp = b->timestamp; >> }; >> >> static void vb2_warn_zero_bytesused(struct vb2_buffer *vb) >> @@ -173,7 +132,8 @@ static void vb2_warn_zero_bytesused(struct vb2_buffer *vb) >> pr_warn("use the actual size instead.\n"); >> } >> >> -static int vb2_fill_vb2_v4l2_buffer(struct vb2_buffer *vb, struct v4l2_buffer *b) >> +static int vb2_fill_vb2_v4l2_buffer(struct vb2_buffer *vb, >> + struct v4l2_ext_buffer *b) >> { >> struct vb2_queue *q = vb->vb2_queue; >> struct vb2_v4l2_buffer *vbuf = to_vb2_v4l2_buffer(vb); >> @@ -203,110 +163,67 @@ static int vb2_fill_vb2_v4l2_buffer(struct vb2_buffer *vb, struct v4l2_buffer *b >> vbuf->request_fd = -1; >> vbuf->is_held = false; >> >> - if (V4L2_TYPE_IS_MULTIPLANAR(b->type)) { >> - switch (b->memory) { >> - case VB2_MEMORY_USERPTR: >> - for (plane = 0; plane < vb->num_planes; ++plane) { >> - planes[plane].m.userptr = >> - b->m.planes[plane].m.userptr; >> - planes[plane].length = >> - b->m.planes[plane].length; >> - } >> - break; >> - case VB2_MEMORY_DMABUF: >> - for (plane = 0; plane < vb->num_planes; ++plane) { >> - planes[plane].m.fd = >> - b->m.planes[plane].m.fd; >> - planes[plane].length = >> - b->m.planes[plane].length; >> - } >> - break; >> - default: >> - for (plane = 0; plane < vb->num_planes; ++plane) { >> - planes[plane].m.offset = >> - vb->planes[plane].m.offset; >> - planes[plane].length = >> - vb->planes[plane].length; >> - } >> - break; >> + for (plane = 0; plane < vb->num_planes; ++plane) { >> + if (b->planes[0].memory != b->planes[plane].memory) { >> + dprintk(q, 1, "planes should have the same memory type\n"); >> + return -EINVAL; >> } >> + } >> >> - /* Fill in driver-provided information for OUTPUT types */ >> - if (V4L2_TYPE_IS_OUTPUT(b->type)) { >> - /* >> - * Will have to go up to b->length when API starts >> - * accepting variable number of planes. >> - * >> - * If bytesused == 0 for the output buffer, then fall >> - * back to the full buffer size. In that case >> - * userspace clearly never bothered to set it and >> - * it's a safe assumption that they really meant to >> - * use the full plane sizes. >> - * >> - * Some drivers, e.g. old codec drivers, use bytesused == 0 >> - * as a way to indicate that streaming is finished. >> - * In that case, the driver should use the >> - * allow_zero_bytesused flag to keep old userspace >> - * applications working. >> - */ >> - for (plane = 0; plane < vb->num_planes; ++plane) { >> - struct vb2_plane *pdst = &planes[plane]; >> - struct v4l2_plane *psrc = &b->m.planes[plane]; >> - >> - if (psrc->bytesused == 0) >> - vb2_warn_zero_bytesused(vb); >> - >> - if (vb->vb2_queue->allow_zero_bytesused) >> - pdst->bytesused = psrc->bytesused; >> - else >> - pdst->bytesused = psrc->bytesused ? >> - psrc->bytesused : pdst->length; >> - pdst->data_offset = psrc->data_offset; >> - } >> + switch (b->planes[0].memory) { >> + case VB2_MEMORY_USERPTR: >> + for (plane = 0; plane < vb->num_planes; ++plane) { >> + planes[plane].m.userptr = b->planes[plane].m.userptr; >> + planes[plane].length = b->planes[plane].buffer_length; >> } >> - } else { >> + break; >> + case VB2_MEMORY_DMABUF: >> + for (plane = 0; plane < vb->num_planes; ++plane) { >> + planes[plane].m.fd = b->planes[plane].m.dmabuf_fd; >> + planes[plane].dbuf_offset = b->planes[plane].offset; >> + planes[plane].length = b->planes[plane].buffer_length; >> + } >> + break; >> + default: >> + for (plane = 0; plane < vb->num_planes; ++plane) { >> + planes[plane].m.offset = vb->planes[plane].m.offset; >> + planes[plane].length = vb->planes[plane].length; >> + } >> + break; >> + } >> + >> + /* Fill in driver-provided information for OUTPUT types */ >> + if (V4L2_TYPE_IS_OUTPUT(b->type)) { >> /* >> - * Single-planar buffers do not use planes array, >> - * so fill in relevant v4l2_buffer struct fields instead. >> - * In videobuf we use our internal V4l2_planes struct for >> - * single-planar buffers as well, for simplicity. >> + * Will have to go up to b->length when API starts >> + * accepting variable number of planes. >> * >> - * If bytesused == 0 for the output buffer, then fall back >> - * to the full buffer size as that's a sensible default. >> + * If bytesused == 0 for the output buffer, then fall > > Should this be updated with the new field name? For next version I implemented a vb2_fill_vb2_v4l2_buffer_ext() and I didn't touch this code. > >> + * back to the full buffer size. In that case >> + * userspace clearly never bothered to set it and >> + * it's a safe assumption that they really meant to >> + * use the full plane sizes. >> * >> - * Some drivers, e.g. old codec drivers, use bytesused == 0 as >> - * a way to indicate that streaming is finished. In that case, >> - * the driver should use the allow_zero_bytesused flag to keep >> - * old userspace applications working. >> + * Some drivers, e.g. old codec drivers, use bytesused == 0 >> + * as a way to indicate that streaming is finished. >> + * In that case, the driver should use the >> + * allow_zero_bytesused flag to keep old userspace >> + * applications working. > > Do we retain this behavior in the new API? If no, I guess we need to check > if this was old or new API and react appropriately. For next version I implemented a vb2_fill_vb2_v4l2_buffer_ext() and I didn't touch this code. > >> */ >> - switch (b->memory) { >> - case VB2_MEMORY_USERPTR: >> - planes[0].m.userptr = b->m.userptr; >> - planes[0].length = b->length; >> - break; >> - case VB2_MEMORY_DMABUF: >> - planes[0].m.fd = b->m.fd; >> - planes[0].length = b->length; >> - break; >> - default: >> - planes[0].m.offset = vb->planes[0].m.offset; >> - planes[0].length = vb->planes[0].length; >> - break; >> - } >> + for (plane = 0; plane < vb->num_planes; ++plane) { >> + struct vb2_plane *pdst = &planes[plane]; >> + struct v4l2_ext_plane *psrc = &b->planes[plane]; >> >> - planes[0].data_offset = 0; >> - if (V4L2_TYPE_IS_OUTPUT(b->type)) { >> - if (b->bytesused == 0) >> + if (psrc->plane_length == 0) >> vb2_warn_zero_bytesused(vb); >> >> if (vb->vb2_queue->allow_zero_bytesused) >> - planes[0].bytesused = b->bytesused; >> + pdst->bytesused = psrc->plane_length; >> else >> - planes[0].bytesused = b->bytesused ? >> - b->bytesused : planes[0].length; >> - } else >> - planes[0].bytesused = 0; >> - >> + pdst->bytesused = psrc->plane_length ? >> + psrc->plane_length : >> + pdst->length; >> + } >> } >> >> /* Zero flags that we handle */ >> @@ -343,7 +260,7 @@ static int vb2_fill_vb2_v4l2_buffer(struct vb2_buffer *vb, struct v4l2_buffer *b >> >> static void set_buffer_cache_hints(struct vb2_queue *q, >> struct vb2_buffer *vb, >> - struct v4l2_buffer *b) >> + struct v4l2_ext_buffer *b) >> { >> /* >> * DMA exporter should take care of cache syncs, so we can avoid >> @@ -388,17 +305,44 @@ static void set_buffer_cache_hints(struct vb2_queue *q, >> vb->need_cache_sync_on_prepare = 0; >> } >> >> +static enum v4l2_buf_type vb2_ext_qtype(struct vb2_queue *q) >> +{ >> + if (!q->is_multiplanar) >> + return q->type; > > Do we need this explicit check? Wouldn't the code below would return > the right thing anyway? Ack, I had already updated this in my wip branch. > >> + >> + if (q->type == V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE) >> + return V4L2_BUF_TYPE_VIDEO_CAPTURE; >> + else if (q->type == V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE) >> + return V4L2_BUF_TYPE_VIDEO_OUTPUT; >> + >> + return q->type; >> +} >> + >> +static enum v4l2_buf_type vb2_ext_type(unsigned int type, bool is_multiplanar) >> +{ >> + if (!is_multiplanar) >> + return type; > > Ditto. Not here, since ext type always use non MPLANE regardless if the driver supports multiplanar or not, so we need to know to which type to convert back. > >> + >> + if (type == V4L2_BUF_TYPE_VIDEO_CAPTURE) >> + return V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; >> + else if (type == V4L2_BUF_TYPE_VIDEO_OUTPUT) >> + return V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE; >> + >> + return type; >> +} >> + >> static int vb2_queue_or_prepare_buf(struct vb2_queue *q, struct media_device *mdev, >> - struct v4l2_buffer *b, bool is_prepare, >> + struct v4l2_ext_buffer *b, bool is_prepare, >> struct media_request **p_req) >> { >> const char *opname = is_prepare ? "prepare_buf" : "qbuf"; >> struct media_request *req; >> struct vb2_v4l2_buffer *vbuf; >> struct vb2_buffer *vb; >> + unsigned int i; >> int ret; >> >> - if (b->type != q->type) { >> + if (b->type != vb2_ext_qtype(q)) { >> dprintk(q, 1, "%s: invalid buffer type\n", opname); >> return -EINVAL; >> } >> @@ -414,16 +358,14 @@ static int vb2_queue_or_prepare_buf(struct vb2_queue *q, struct media_device *md >> return -EINVAL; >> } >> >> - if (b->memory != q->memory) { >> + for (i = 0; i < VIDEO_MAX_PLANES && b->planes[i].buffer_length; i++) >> + if (b->planes[i].memory != q->memory) { >> dprintk(q, 1, "%s: invalid memory type\n", opname); >> return -EINVAL; >> } >> >> vb = q->bufs[b->index]; >> vbuf = to_vb2_v4l2_buffer(vb); >> - ret = __verify_planes_array(vb, b); >> - if (ret) >> - return ret; >> >> if (!is_prepare && (b->flags & V4L2_BUF_FLAG_REQUEST_FD) && >> vb->state != VB2_BUF_STATE_DEQUEUED) { >> @@ -487,11 +429,6 @@ static int vb2_queue_or_prepare_buf(struct vb2_queue *q, struct media_device *md >> !q->ops->buf_out_validate)) >> return -EINVAL; >> >> - if (b->request_fd < 0) { >> - dprintk(q, 1, "%s: request_fd < 0\n", opname); >> - return -EINVAL; >> - } >> - > > I guess this code was useless already, because the call below would > validate the FD, but should it be perhaps removed in a separate patch? Ack, I'll submit a separate patch. > >> req = media_request_get_by_fd(mdev, b->request_fd); >> if (IS_ERR(req)) { >> dprintk(q, 1, "%s: invalid request_fd\n", opname); >> @@ -516,64 +453,46 @@ static int vb2_queue_or_prepare_buf(struct vb2_queue *q, struct media_device *md >> } >> >> /* >> - * __fill_v4l2_buffer() - fill in a struct v4l2_buffer with information to be >> - * returned to userspace >> + * __fill_v4l2_buffer() - fill in a struct v4l2_ext_buffer with information to >> + * be returned to userspace >> */ >> static void __fill_v4l2_buffer(struct vb2_buffer *vb, void *pb) >> { >> - struct v4l2_buffer *b = pb; >> + struct v4l2_ext_buffer *b = pb; >> struct vb2_v4l2_buffer *vbuf = to_vb2_v4l2_buffer(vb); >> struct vb2_queue *q = vb->vb2_queue; >> unsigned int plane; >> >> /* Copy back data such as timestamp, flags, etc. */ >> b->index = vb->index; >> - b->type = vb->type; >> - b->memory = vb->memory; >> - b->bytesused = 0; >> + b->type = vb2_ext_qtype(q); >> >> b->flags = vbuf->flags; >> b->field = vbuf->field; >> - v4l2_buffer_set_timestamp(b, vb->timestamp); >> - b->timecode = vbuf->timecode; >> + b->timestamp = vb->timestamp; >> b->sequence = vbuf->sequence; >> - b->reserved2 = 0; >> b->request_fd = 0; >> + memset(b->reserved, 0, sizeof(b->reserved)); >> >> - if (q->is_multiplanar) { >> - /* >> - * Fill in plane-related data if userspace provided an array >> - * for it. The caller has already verified memory and size. >> - */ >> - b->length = vb->num_planes; >> - for (plane = 0; plane < vb->num_planes; ++plane) { >> - struct v4l2_plane *pdst = &b->m.planes[plane]; >> - struct vb2_plane *psrc = &vb->planes[plane]; >> - >> - pdst->bytesused = psrc->bytesused; >> - pdst->length = psrc->length; >> - if (q->memory == VB2_MEMORY_MMAP) >> - pdst->m.mem_offset = psrc->m.offset; >> - else if (q->memory == VB2_MEMORY_USERPTR) >> - pdst->m.userptr = psrc->m.userptr; >> - else if (q->memory == VB2_MEMORY_DMABUF) >> - pdst->m.fd = psrc->m.fd; >> - pdst->data_offset = psrc->data_offset; >> - memset(pdst->reserved, 0, sizeof(pdst->reserved)); >> - } >> - } else { >> - /* >> - * We use length and offset in v4l2_planes array even for >> - * single-planar buffers, but userspace does not. >> - */ >> - b->length = vb->planes[0].length; >> - b->bytesused = vb->planes[0].bytesused; >> + /* >> + * Fill in plane-related data if userspace provided an array >> + * for it. The caller has already verified memory and size. >> + */ >> + for (plane = 0; plane < vb->num_planes; ++plane) { >> + struct v4l2_ext_plane *pdst = &b->planes[plane]; >> + struct vb2_plane *psrc = &vb->planes[plane]; >> + >> + pdst->memory = vb->memory; >> + pdst->plane_length = psrc->bytesused; >> + pdst->buffer_length = psrc->length; >> + pdst->offset = psrc->dbuf_offset; >> if (q->memory == VB2_MEMORY_MMAP) >> - b->m.offset = vb->planes[0].m.offset; >> + pdst->m.mem_offset = psrc->m.offset; >> else if (q->memory == VB2_MEMORY_USERPTR) >> - b->m.userptr = vb->planes[0].m.userptr; >> + pdst->m.userptr = psrc->m.userptr; >> else if (q->memory == VB2_MEMORY_DMABUF) >> - b->m.fd = vb->planes[0].m.fd; >> + pdst->m.dmabuf_fd = psrc->m.fd; >> + memset(pdst->reserved, 0, sizeof(pdst->reserved)); >> } >> >> /* >> @@ -668,6 +587,35 @@ int vb2_find_timestamp(const struct vb2_queue *q, u64 timestamp, >> } >> EXPORT_SYMBOL_GPL(vb2_find_timestamp); >> >> +#define vb2_buf_to_ext_buf_op(_name, ...) \ >> +({ \ >> + int ret; \ >> + \ >> + ret = v4l2_buffer_to_ext_buffer(b, &eb); \ >> + if (!ret) \ >> + ret = _name(__VA_ARGS__); \ >> + if (!ret) \ >> + ret = v4l2_ext_buffer_to_buffer(&eb, b, \ >> + q->is_multiplanar); \ > > I'm not very happy with this macro implicitly relying on existence of some > specific variables with predefined names in the scope of the caller. > > That said, I don't have a good idea on how this could be fixed, other than > just repeating this code manually in each function. > > If we don't find anything better, I think at least a comment here > explaining the assumptions would make it a bit better. I completly removed this macro for the newer version. > >> + ret; \ >> +}) >> + >> +int vb2_ext_querybuf(struct vb2_queue *q, struct v4l2_ext_buffer *b) >> +{ >> + if (b->type != vb2_ext_qtype(q)) { >> + dprintk(q, 1, "wrong buffer type\n"); >> + return -EINVAL; >> + } >> + >> + if (b->index >= q->num_buffers) { >> + dprintk(q, 1, "buffer index out of range\n"); >> + return -EINVAL; >> + } >> + vb2_core_querybuf(q, b->index, b); >> + return 0; >> +} >> +EXPORT_SYMBOL(vb2_ext_querybuf); >> + >> /* >> * vb2_querybuf() - query video buffer information >> * @q: videobuf queue >> @@ -683,23 +631,9 @@ EXPORT_SYMBOL_GPL(vb2_find_timestamp); >> */ >> int vb2_querybuf(struct vb2_queue *q, struct v4l2_buffer *b) >> { >> - struct vb2_buffer *vb; >> - int ret; >> - >> - if (b->type != q->type) { >> - dprintk(q, 1, "wrong buffer type\n"); >> - return -EINVAL; >> - } >> + struct v4l2_ext_buffer eb; >> >> - if (b->index >= q->num_buffers) { >> - dprintk(q, 1, "buffer index out of range\n"); >> - return -EINVAL; >> - } >> - vb = q->bufs[b->index]; >> - ret = __verify_planes_array(vb, b); >> - if (!ret) >> - vb2_core_querybuf(q, b->index, b); >> - return ret; >> + return vb2_buf_to_ext_buf_op(vb2_ext_querybuf, q, &eb); >> } >> EXPORT_SYMBOL(vb2_querybuf); >> >> @@ -741,8 +675,8 @@ int vb2_reqbufs(struct vb2_queue *q, struct v4l2_requestbuffers *req) >> } >> EXPORT_SYMBOL_GPL(vb2_reqbufs); >> >> -int vb2_prepare_buf(struct vb2_queue *q, struct media_device *mdev, >> - struct v4l2_buffer *b) >> +int vb2_ext_prepare_buf(struct vb2_queue *q, struct media_device *mdev, >> + struct v4l2_ext_buffer *b) >> { >> int ret; >> >> @@ -758,16 +692,59 @@ int vb2_prepare_buf(struct vb2_queue *q, struct media_device *mdev, >> >> return ret ? ret : vb2_core_prepare_buf(q, b->index, b); >> } >> +EXPORT_SYMBOL_GPL(vb2_ext_prepare_buf); >> + >> +int vb2_prepare_buf(struct vb2_queue *q, struct media_device *mdev, >> + struct v4l2_buffer *b) >> +{ >> + struct v4l2_ext_buffer eb; >> + >> + return vb2_buf_to_ext_buf_op(vb2_ext_prepare_buf, q, mdev, &eb); >> +} >> EXPORT_SYMBOL_GPL(vb2_prepare_buf); >> >> +int vb2_ext_create_bufs(struct vb2_queue *q, >> + struct v4l2_ext_create_buffers *create) >> +{ >> + unsigned int requested_sizes[VIDEO_MAX_PLANES]; >> + struct v4l2_ext_pix_format *f = &create->format; >> + int ret = vb2_verify_memory_type(q, create->memory, >> + vb2_ext_type(f->type, q->is_multiplanar)); >> + unsigned i; >> + >> + if (create->format.type != V4L2_BUF_TYPE_VIDEO_CAPTURE && >> + create->format.type != V4L2_BUF_TYPE_VIDEO_OUTPUT) >> + return -EINVAL; >> + >> + fill_buf_caps(q, &create->capabilities); >> + clear_consistency_attr(q, create->memory, &create->flags); >> + create->index = q->num_buffers; >> + if (create->count == 0) >> + return ret != -EBUSY ? ret : 0; >> + >> + if (!f->plane_fmt[0].sizeimage) >> + return -EINVAL; >> + for (i = 0; i < VIDEO_MAX_PLANES && >> + f->plane_fmt[i].sizeimage; i++) >> + requested_sizes[i] = f->plane_fmt[i].sizeimage; >> + >> + return ret ? ret : vb2_core_create_bufs(q, create->memory, >> + create->flags, >> + &create->count, >> + i, >> + requested_sizes); >> +} >> +EXPORT_SYMBOL_GPL(vb2_ext_create_bufs); >> + >> int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create) >> { >> + struct v4l2_format *f = &create->format; >> unsigned requested_planes = 1; >> unsigned requested_sizes[VIDEO_MAX_PLANES]; >> - struct v4l2_format *f = &create->format; >> int ret = vb2_verify_memory_type(q, create->memory, f->type); >> unsigned i; >> >> + >> fill_buf_caps(q, &create->capabilities); >> clear_consistency_attr(q, create->memory, &create->flags); >> create->index = q->num_buffers; >> @@ -777,18 +754,29 @@ int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create) >> switch (f->type) { >> case V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE: >> case V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE: >> - requested_planes = f->fmt.pix_mp.num_planes; >> - if (requested_planes == 0 || >> - requested_planes > VIDEO_MAX_PLANES) >> - return -EINVAL; >> - for (i = 0; i < requested_planes; i++) >> - requested_sizes[i] = >> - f->fmt.pix_mp.plane_fmt[i].sizeimage; >> - break; >> case V4L2_BUF_TYPE_VIDEO_CAPTURE: >> - case V4L2_BUF_TYPE_VIDEO_OUTPUT: >> - requested_sizes[0] = f->fmt.pix.sizeimage; >> - break; >> + case V4L2_BUF_TYPE_VIDEO_OUTPUT: { >> + struct v4l2_ext_create_buffers ecreate = { >> + .count = create->count, >> + .memory = create->memory, >> + .flags = create->flags, >> + }; >> + >> + ret = v4l2_format_to_ext_pix_format(&create->format, >> + &ecreate.format, true); >> + if (ret) >> + return ret; >> + >> + ret = vb2_ext_create_bufs(q, &ecreate); >> + if (ret) >> + return ret; >> + >> + create->index = ecreate.index; >> + create->count = ecreate.count; >> + create->flags = ecreate.flags; >> + create->capabilities = ecreate.capabilities; >> + return 0; >> + } >> case V4L2_BUF_TYPE_VBI_CAPTURE: >> case V4L2_BUF_TYPE_VBI_OUTPUT: >> requested_sizes[0] = f->fmt.vbi.samples_per_line * >> @@ -820,8 +808,8 @@ int vb2_create_bufs(struct vb2_queue *q, struct v4l2_create_buffers *create) >> } >> EXPORT_SYMBOL_GPL(vb2_create_bufs); >> >> -int vb2_qbuf(struct vb2_queue *q, struct media_device *mdev, >> - struct v4l2_buffer *b) >> +int vb2_ext_qbuf(struct vb2_queue *q, struct media_device *mdev, >> + struct v4l2_ext_buffer *b) >> { >> struct media_request *req = NULL; >> int ret; >> @@ -839,9 +827,19 @@ int vb2_qbuf(struct vb2_queue *q, struct media_device *mdev, >> media_request_put(req); >> return ret; >> } >> +EXPORT_SYMBOL_GPL(vb2_ext_qbuf); >> + >> +int vb2_qbuf(struct vb2_queue *q, struct media_device *mdev, >> + struct v4l2_buffer *b) >> +{ >> + struct v4l2_ext_buffer eb; >> + >> + return vb2_buf_to_ext_buf_op(vb2_ext_qbuf, q, mdev, &eb); >> +} >> EXPORT_SYMBOL_GPL(vb2_qbuf); >> >> -int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking) >> +int vb2_ext_dqbuf(struct vb2_queue *q, struct v4l2_ext_buffer *b, >> + bool nonblocking) >> { >> int ret; >> >> @@ -850,7 +848,7 @@ int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking) >> return -EBUSY; >> } >> >> - if (b->type != q->type) { >> + if (b->type != vb2_ext_qtype(q)) { >> dprintk(q, 1, "invalid buffer type\n"); >> return -EINVAL; >> } >> @@ -870,6 +868,14 @@ int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking) >> >> return ret; >> } >> +EXPORT_SYMBOL_GPL(vb2_ext_dqbuf); >> + >> +int vb2_dqbuf(struct vb2_queue *q, struct v4l2_buffer *b, bool nonblocking) >> +{ >> + struct v4l2_ext_buffer eb; >> + >> + return vb2_buf_to_ext_buf_op(vb2_ext_dqbuf, q, &eb, nonblocking); >> +} >> EXPORT_SYMBOL_GPL(vb2_dqbuf); >> >> int vb2_streamon(struct vb2_queue *q, enum v4l2_buf_type type) >> @@ -1040,6 +1046,33 @@ int vb2_ioctl_create_bufs(struct file *file, void *priv, >> } >> EXPORT_SYMBOL_GPL(vb2_ioctl_create_bufs); >> >> +int vb2_ioctl_ext_create_bufs(struct file *file, void *priv, >> + struct v4l2_ext_create_buffers *p) >> +{ >> + struct video_device *vdev = video_devdata(file); >> + int res = vb2_verify_memory_type(vdev->queue, p->memory, >> + vb2_ext_type(p->format.type, vdev->queue->is_multiplanar)); >> + >> + p->index = vdev->queue->num_buffers; >> + fill_buf_caps(vdev->queue, &p->capabilities); >> + /* >> + * If count == 0, then just check if memory and type are valid. >> + * Any -EBUSY result from vb2_verify_memory_type can be mapped to 0. >> + */ >> + if (p->count == 0) >> + return res != -EBUSY ? res : 0; >> + if (res) >> + return res; >> + if (vb2_queue_is_busy(vdev, file)) >> + return -EBUSY; >> + >> + res = vb2_ext_create_bufs(vdev->queue, p); >> + if (res == 0) >> + vdev->queue->owner = file->private_data; >> + return res; >> +} >> +EXPORT_SYMBOL_GPL(vb2_ioctl_ext_create_bufs); >> + >> int vb2_ioctl_prepare_buf(struct file *file, void *priv, >> struct v4l2_buffer *p) >> { >> @@ -1051,6 +1084,17 @@ int vb2_ioctl_prepare_buf(struct file *file, void *priv, >> } >> EXPORT_SYMBOL_GPL(vb2_ioctl_prepare_buf); >> >> +int vb2_ioctl_ext_prepare_buf(struct file *file, void *priv, >> + struct v4l2_ext_buffer *p) >> +{ >> + struct video_device *vdev = video_devdata(file); >> + >> + if (vb2_queue_is_busy(vdev, file)) >> + return -EBUSY; >> + return vb2_ext_prepare_buf(vdev->queue, vdev->v4l2_dev->mdev, p); >> +} >> +EXPORT_SYMBOL_GPL(vb2_ioctl_ext_prepare_buf); >> + >> int vb2_ioctl_querybuf(struct file *file, void *priv, struct v4l2_buffer *p) >> { >> struct video_device *vdev = video_devdata(file); >> @@ -1060,6 +1104,16 @@ int vb2_ioctl_querybuf(struct file *file, void *priv, struct v4l2_buffer *p) >> } >> EXPORT_SYMBOL_GPL(vb2_ioctl_querybuf); >> >> +int vb2_ioctl_ext_querybuf(struct file *file, void *priv, >> + struct v4l2_ext_buffer *p) >> +{ >> + struct video_device *vdev = video_devdata(file); >> + >> + /* No need to call vb2_queue_is_busy(), anyone can query buffers. */ >> + return vb2_ext_querybuf(vdev->queue, p); >> +} >> +EXPORT_SYMBOL_GPL(vb2_ioctl_ext_querybuf); >> + >> int vb2_ioctl_qbuf(struct file *file, void *priv, struct v4l2_buffer *p) >> { >> struct video_device *vdev = video_devdata(file); >> @@ -1070,6 +1124,17 @@ int vb2_ioctl_qbuf(struct file *file, void *priv, struct v4l2_buffer *p) >> } >> EXPORT_SYMBOL_GPL(vb2_ioctl_qbuf); >> >> +int vb2_ioctl_ext_qbuf(struct file *file, void *priv, >> + struct v4l2_ext_buffer *p) >> +{ >> + struct video_device *vdev = video_devdata(file); >> + >> + if (vb2_queue_is_busy(vdev, file)) >> + return -EBUSY; >> + return vb2_ext_qbuf(vdev->queue, vdev->v4l2_dev->mdev, p); >> +} >> +EXPORT_SYMBOL_GPL(vb2_ioctl_ext_qbuf); >> + >> int vb2_ioctl_dqbuf(struct file *file, void *priv, struct v4l2_buffer *p) >> { >> struct video_device *vdev = video_devdata(file); >> @@ -1080,6 +1145,17 @@ int vb2_ioctl_dqbuf(struct file *file, void *priv, struct v4l2_buffer *p) >> } >> EXPORT_SYMBOL_GPL(vb2_ioctl_dqbuf); >> >> +int vb2_ioctl_ext_dqbuf(struct file *file, void *priv, >> + struct v4l2_ext_buffer *p) >> +{ >> + struct video_device *vdev = video_devdata(file); >> + >> + if (vb2_queue_is_busy(vdev, file)) >> + return -EBUSY; >> + return vb2_ext_dqbuf(vdev->queue, p, file->f_flags & O_NONBLOCK); >> +} >> +EXPORT_SYMBOL_GPL(vb2_ioctl_ext_dqbuf); >> + >> int vb2_ioctl_streamon(struct file *file, void *priv, enum v4l2_buf_type i) >> { >> struct video_device *vdev = video_devdata(file); >> diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h >> index 52ef92049073e..f334767785bd9 100644 >> --- a/include/media/videobuf2-core.h >> +++ b/include/media/videobuf2-core.h >> @@ -152,6 +152,8 @@ struct vb2_mem_ops { >> * @mem_priv: private data with this plane. >> * @dbuf: dma_buf - shared buffer object. >> * @dbuf_mapped: flag to show whether dbuf is mapped or not >> + * @dbuf_offset: offset where the plane starts. Usually 0, unless the buffer >> + * is shared by all planes of a multi-planar format. > > The comment kind of implies that non-zero is a special case, but I wouldn't > want driver authors to come to incorrect conclusions based on that. Do we > actually need the last sentence at all? I removed this field in next version to let drivers decide where to place the planes in the memory buffers. > >> * @bytesused: number of bytes occupied by data in the plane (payload). >> * @length: size of this plane (NOT the payload) in bytes. >> * @min_length: minimum required size of this plane (NOT the payload) in bytes. >> @@ -175,6 +177,7 @@ struct vb2_plane { >> void *mem_priv; >> struct dma_buf *dbuf; >> unsigned int dbuf_mapped; >> + unsigned int dbuf_offset; >> unsigned int bytesused; >> unsigned int length; >> unsigned int min_length; >> @@ -446,7 +449,8 @@ struct vb2_ops { >> * struct vb2_buffer. >> * For V4L2 this is a &struct vb2_v4l2_buffer. >> * @fill_user_buffer: given a &vb2_buffer fill in the userspace structure. >> - * For V4L2 this is a &struct v4l2_buffer. >> + * For V4L2 this is a &struct v4l2_buffer or >> + * &struct v4l2_ext_buffer. > > Isn't it always v4l2_ext_buffer with current code? I added a fill_user_ext_buffer for next version, since we need to keep both v4l2_buffer and v4l2_ext_buffer to userspace. > > Best regards, > Tomasz > Thanks for your comments, Helen
On 11/20/20 10:20 AM, Hans Verkuil wrote: > On 20/11/2020 13:40, Tomasz Figa wrote: >> On Fri, Nov 20, 2020 at 9:24 PM Hans Verkuil <hverkuil@xs4all.nl> wrote: >>> >>> On 20/11/2020 12:06, Tomasz Figa wrote:z >>>> Hi Helen, >>>> >>>> On Tue, Aug 04, 2020 at 04:29:39PM -0300, Helen Koike wrote: >>>>> Add documentation and update references in current documentation for the >>>>> Extended API. >>>>> >>>> >>>> Thank you for the patch. Please see my comments inline. >>>> >>>>> Signed-off-by: Helen Koike <helen.koike@collabora.com> >>>>> --- >>>>> Changes in v5: >>>>> - new patch >>>>> >>>>> .../userspace-api/media/v4l/buffer.rst | 5 + >>>>> .../userspace-api/media/v4l/common.rst | 1 + >>>>> .../userspace-api/media/v4l/dev-capture.rst | 5 + >>>>> .../userspace-api/media/v4l/dev-output.rst | 5 + >>>>> .../userspace-api/media/v4l/ext-api.rst | 107 +++++++++ >>>>> .../userspace-api/media/v4l/format.rst | 16 +- >>>>> .../userspace-api/media/v4l/user-func.rst | 5 + >>>>> .../media/v4l/vidioc-ext-create-bufs.rst | 95 ++++++++ >>>>> .../media/v4l/vidioc-ext-prepare-buf.rst | 62 ++++++ >>>>> .../media/v4l/vidioc-ext-qbuf.rst | 204 ++++++++++++++++++ >>>>> .../media/v4l/vidioc-ext-querybuf.rst | 79 +++++++ >>>>> .../media/v4l/vidioc-g-ext-pix-fmt.rst | 117 ++++++++++ >>>>> 12 files changed, 697 insertions(+), 4 deletions(-) >>>>> create mode 100644 Documentation/userspace-api/media/v4l/ext-api.rst >>>>> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst >>>>> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst >>>>> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst >>>>> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst >>>>> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst >>>>> >>>>> diff --git a/Documentation/userspace-api/media/v4l/buffer.rst b/Documentation/userspace-api/media/v4l/buffer.rst >>>>> index 57e752aaf414a..c832bedd64e4c 100644 >>>>> --- a/Documentation/userspace-api/media/v4l/buffer.rst >>>>> +++ b/Documentation/userspace-api/media/v4l/buffer.rst >>>>> @@ -27,6 +27,11 @@ 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. >>>>> >>>>> +.. note:: >>>>> + >>>>> + The :ref:`ext_api` version can also be used, and it is >>>>> + preferable when applicable. >>>> >>>> Would rephrasing this as below making a bit more definitive? >>>> >>>> For modern applications, these operations are replaced by their >>>> :ref:`ext_api` counterparts, which should be used instead. >>> >>> You can't say that, since especially in the beginning userspace will be running >>> on older kernels that do not support this. >>> >>> This will work: "should be used instead, if supported by the driver." >>> >> >> With the wrappers that the patches provide, all drivers would support >> the new API, so this boils down to the kernel version only, not >> specific drivers. >> >> Agreed, though, that application developers must be made aware that >> the new API is only available in new kernels and old API must be used >> for compatibility with old kernels. > > Is the conversion layer fully independent of vb2? We still have older > drivers that do not use vb2, and I'm not sure if the extended buffer > operations work with those drivers as well. (Sorry, it's been a while > since I last looked at this series, so I can't remember). The conversion layer should be independent of vb2 (please check v6, I think it is cleaner). > >> >>>> >>>>> + >>>>> 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 >>>>> diff --git a/Documentation/userspace-api/media/v4l/common.rst b/Documentation/userspace-api/media/v4l/common.rst >>>>> index 7d81c58a13cd7..3430e0bdad667 100644 >>>>> --- a/Documentation/userspace-api/media/v4l/common.rst >>>>> +++ b/Documentation/userspace-api/media/v4l/common.rst >>>>> @@ -59,6 +59,7 @@ applicable to all devices. >>>>> ext-ctrls-detect >>>>> fourcc >>>>> format >>>>> + ext-api >>>>> planar-apis >>>>> selection-api >>>>> crop >>>>> diff --git a/Documentation/userspace-api/media/v4l/dev-capture.rst b/Documentation/userspace-api/media/v4l/dev-capture.rst >>>>> index 44d3094093ab6..5077639787d92 100644 >>>>> --- a/Documentation/userspace-api/media/v4l/dev-capture.rst >>>>> +++ b/Documentation/userspace-api/media/v4l/dev-capture.rst >>>>> @@ -102,6 +102,11 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC >>>>> requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. >>>>> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. >>>>> >>>>> +.. note:: >>>>> + >>>>> + The :ref:`ext_api` version can also be used, and it is >>>>> + preferable when applicable. >>>>> + >>>>> >>>>> Reading Images >>>>> ============== >>>>> diff --git a/Documentation/userspace-api/media/v4l/dev-output.rst b/Documentation/userspace-api/media/v4l/dev-output.rst >>>>> index e4f2a1d8b0fc7..f8f40c708e49f 100644 >>>>> --- a/Documentation/userspace-api/media/v4l/dev-output.rst >>>>> +++ b/Documentation/userspace-api/media/v4l/dev-output.rst >>>>> @@ -99,6 +99,11 @@ and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl, even if :ref:`VIDIOC_S_FMT <VIDIOC >>>>> requests and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does. >>>>> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is optional. >>>>> >>>>> +.. note:: >>>>> + >>>>> + The :ref:`ext_api` version can also be used, and it is >>>>> + preferable when applicable. >>>>> + >>>>> >>>>> Writing Images >>>>> ============== >>>>> diff --git a/Documentation/userspace-api/media/v4l/ext-api.rst b/Documentation/userspace-api/media/v4l/ext-api.rst >>>>> new file mode 100644 >>>>> index 0000000000000..da2a82960d22f >>>>> --- /dev/null >>>>> +++ b/Documentation/userspace-api/media/v4l/ext-api.rst >>>>> @@ -0,0 +1,107 @@ >>>>> +.. Permission is granted to copy, distribute and/or modify this >>>>> +.. document under the terms of the GNU Free Documentation License, >>>>> +.. Version 1.1 or any later version published by the Free Software >>>>> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >>>>> +.. and no Back-Cover Texts. A copy of the license is included at >>>>> +.. Documentation/userspace-api/media/fdl-appendix.rst. >>>>> +.. >>>>> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >>>>> + >>>>> +.. _ext_api: >>>>> + >>>>> +************* >>>>> +Extendend API >>>>> +************* >>>>> + >>>>> +Introduction >>>>> +============ >>>>> + >>>>> +The Extended Format API was conceived to extend V4L2 capabilities and >>>>> +to simplify certain mechanisms. >>>>> +It unifies single- vs multi- planar handling, >>>>> +brings the concept of pixelformat + modifiers, allows planes to be placed >>>>> +in any offset inside a buffer and let userspace to change colorspace >>>>> +attributes if supported by the driver. >>>> >>>> How about simplifying this paragraph a bit: >>>> >>>> The Extended Format API unifies single- and multi- planar format handling >>>> and provides a base for further functional extensions, such as format >>>> modifiers, arbitrary plane offsets, colorspace configuration. >>> >>> Actually, I prefer Helen's version. >>> >> >> To me it's a lot of text to read to get the same information, but I >> won't insist. >> >>>> >>>>> + >>>>> +Data format negotiation and buffer handling works very similar to the classical >>>>> +version, thus in this document we'll just mention the main differences. >>>> >>>> nit: "we will" or maybe even just "we mention only the main differences". Applied for v6. >>>> >>>>> + >>>>> +Data Format Negotiation >>>>> +======================= >>>>> + >>>>> +The API replaces the classical ioctls: >>>>> + >>>>> +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>`, :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`, >>>>> +:ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` >>>>> +(with :c:type:`v4l2_format` as the main parameter). >>>>> + >>>>> +By the extended versions: >>>>> + >>>>> +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>`, >>>>> +:ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>`, >>>>> +:ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` >>>>> +(with :c:type:`v4l2_ext_pix_format` as the main parameter). >>>>> + >>>>> +For CAPTURE and OUTPUT queues only. >>>>> + >>>>> +The ``type`` field of struct :c:type:`v4l2_ext_pix_format` only accepts >>>>> +``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or ``V4L2_BUF_TYPE_VIDEO_OUTPUT``, and it >>>>> +supports multiplanar format through a combination of ``pixelfomat`` and >>>>> +``modifier`` fields. >>>>> + >>>>> +Only the single-planar variants of the pixel formats are valid in the >>>>> +``pixelformat`` field. >>>> >>>> Some formats have only multi-planar variants, like NV12MT. What should we >>>> do about them? Since we have to keep those defines to support the legacy >>>> API anyway, maybe we can just accept both variants and treat them equally? >>> >>> Helen mentioned that as well in a reply to patch 1/7. I'll have a think about >>> that myself and reply to that post because this is a good question. >>> >> >> I'm thinking about it as well. :) >> >>>> >>>>> +To support multi-planar, a modifier should be set in the ``modifier`` field to >>>>> +provide more information regarding the memory layout of pixels and number of >>>>> +planes. >>>>> + >>>>> +The ``plane_fmt`` field is an array which holds information by plane using >>>>> +the :c:type:`v4l2_plane_ext_pix_format`. When this struct is filled, its >>>>> +``sizeimage`` field should be non-zero for all valid planes for a given >>>>> +``pixelformat`` + ``modifier`` combination, and zeroed for the invalid ones. >>>>> + >>>>> +Colospace attributes are not read-only as in the classical version, i.e, they >>>>> +can be set by application and drivers will adjust accordingly depending on what >>>>> +is supported by the underlying hardware. >>>>> + >>>>> +Buffers >>>>> +======= >>>>> + >>>>> +The API replaces the classical ioctls: >>>>> + >>>>> +:ref:`VIDIOC_CREATE_BUFS <VIDIOC_CREATE_BUFS>` >>>>> +(with :c:type:`v4l2_create_buffers` as the main parameter), >>>>> +:ref:`VIDIOC_QUERYBUF <VIDIOC_QUERYBUF>`, :ref:`VIDIOC_QBUF <VIDIOC_QBUF>`, >>>>> +:ref:`VIDIOC_DQBUF <VIDIOC_QBUF>`, :ref:`VIDIOC_PREPARE_BUF <VIDIOC_PREPARE_BUF>` >>>>> +(with :c:type:`v4l2_buffer` as the main parameter) >>>>> + >>>>> +By the extended versions: >>>>> + >>>>> +:ref:`VIDIOC_EXT_CREATE_BUFS <VIDIOC_EXT_CREATE_BUFS>` >>>>> +(with :c:type:`v4l2_ext_create_buffers` as the main parameter), >>>>> +:ref:`VIDIOC_EXT_QUERYBUF <VIDIOC_EXT_QUERYBUF>`, >>>>> +:ref:`VIDIOC_EXT_QBUF <VIDIOC_EXT_QBUF>`, >>>>> +:ref:`VIDIOC_EXT_DQBUF <VIDIOC_EXT_QBUF>`, >>>>> +:ref:`VIDIOC_EXT_PREPARE_BUF <VIDIOC_EXT_PREPARE_BUF>` >>>>> +(with :c:type:`v4l2_ext_buffer` as the main parameter) >>>>> + >>>>> +The basic difference between :c:type:`v4l2_create_buffers` and >>>>> +:c:type:`v4l2_ext_create_buffers` is that the later have a >>>>> +:c:type:`v4l2_ext_pix_format` as the type of the ``format`` field. >>>>> + >>>>> +Comparing :c:type:`v4l2_ext_buffer` with :c:type:`v4l2_buffer`, in the >>>>> +extended version there is a unification of the single-/multi- planar handling >>>>> +through the ``planes`` field of type :c:type:`v4l2_ext_plane`. >>>>> + >>>>> +The :c:type:`v4l2_ext_plane also allows planes to be placed in a given offset >>>>> +inside a buffer. >>>>> +Planes can be placed in different locations inside the same buffer, or in >>>>> +different buffers. >>>>> + >>>>> + >>>>> +.. kernel-doc:: include/uapi/linux/videodev2.h >>>>> + :functions: v4l2_ext_plane >>>>> + >>>>> + >>>>> +.. kernel-doc:: include/uapi/linux/videodev2.h >>>>> + :functions: v4l2_ext_buffer >>>>> diff --git a/Documentation/userspace-api/media/v4l/format.rst b/Documentation/userspace-api/media/v4l/format.rst >>>>> index e47fc0505727c..b96d26f26793c 100644 >>>>> --- a/Documentation/userspace-api/media/v4l/format.rst >>>>> +++ b/Documentation/userspace-api/media/v4l/format.rst >>>>> @@ -28,13 +28,19 @@ format and the driver selects and reports the best the hardware can do >>>>> to satisfy the request. Of course applications can also just query the >>>>> current selection. >>>>> >>>>> -A single mechanism exists to negotiate all data formats using the >>>>> -aggregate struct :c:type:`v4l2_format` and the >>>>> +There are two mechanism to negociate data formats: >>>> >>>> negotiate Ack, updated for v6. >>>> >>>>> + >>>>> +The first one is using the aggregate struct :c:type:`v4l2_format` and the >>>>> :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and >>>>> :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctls. Additionally the >>>>> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` ioctl can be used to examine >>>>> what the hardware *could* do, without actually selecting a new data >>>>> -format. The data formats supported by the V4L2 API are covered in the >>>>> +format. >>>>> + >>>>> +The second is through the :ref:`ext_api`, please refer to its documentation >>>>> +for more information. >>>>> + >>>> >>>> Should we reverse the order to prefer the new API? Ack, updated for v6. >>>> >>>>> +The data formats supported by the V4L2 API are covered in the >>>>> respective device section in :ref:`devices`. For a closer look at >>>>> image formats see :ref:`pixfmt`. >>>>> >>>>> @@ -71,7 +77,9 @@ earlier versions of V4L2. Switching the logical stream or returning into >>>>> *may* support a switch using :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>`. >>>>> >>>>> All drivers exchanging data with applications must support the >>>>> -:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl. Implementation of the >>>>> +:ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` and :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` ioctl >>>>> +or the Extended respective versions (TODO: link). >>>> >>>> TODO? :) Thanks! >>>> >>>>> +Implementation of the >>>>> :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` is highly recommended but optional. >>>>> >>>>> >>>>> diff --git a/Documentation/userspace-api/media/v4l/user-func.rst b/Documentation/userspace-api/media/v4l/user-func.rst >>>>> index bf77c842718e5..67b254812791c 100644 >>>>> --- a/Documentation/userspace-api/media/v4l/user-func.rst >>>>> +++ b/Documentation/userspace-api/media/v4l/user-func.rst >>>>> @@ -20,6 +20,7 @@ Function Reference >>>>> func-close >>>>> func-ioctl >>>>> vidioc-create-bufs >>>>> + vidioc-ext-create-bufs >>>>> vidioc-cropcap >>>>> vidioc-dbg-g-chip-info >>>>> vidioc-dbg-g-register >>>>> @@ -48,6 +49,7 @@ Function Reference >>>>> vidioc-g-ext-ctrls >>>>> vidioc-g-fbuf >>>>> vidioc-g-fmt >>>>> + vidioc-g-ext-pix-fmt >>>>> vidioc-g-frequency >>>>> vidioc-g-input >>>>> vidioc-g-jpegcomp >>>>> @@ -62,8 +64,11 @@ Function Reference >>>>> vidioc-log-status >>>>> vidioc-overlay >>>>> vidioc-prepare-buf >>>>> + vidioc-ext-prepare-buf >>>>> vidioc-qbuf >>>>> + vidioc-ext-qbuf >>>>> vidioc-querybuf >>>>> + vidioc-ext-querybuf >>>>> vidioc-querycap >>>>> vidioc-queryctrl >>>>> vidioc-query-dv-timings >>>>> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst >>>>> new file mode 100644 >>>>> index 0000000000000..67f2c541e4d79 >>>>> --- /dev/null >>>>> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst >>>>> @@ -0,0 +1,95 @@ >>>>> +.. Permission is granted to copy, distribute and/or modify this >>>>> +.. document under the terms of the GNU Free Documentation License, >>>>> +.. Version 1.1 or any later version published by the Free Software >>>>> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >>>>> +.. and no Back-Cover Texts. A copy of the license is included at >>>>> +.. Documentation/userspace-api/media/fdl-appendix.rst. >>>>> +.. >>>>> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >>>>> + >>>> >>>> TODO? :) Thanks! >>>> >>>>> +.. _VIDIOC_EXT_CREATE_BUFS: >>>>> + >>>>> +**************************** >>>>> +ioctl VIDIOC_EXT_CREATE_BUFS >>>>> +**************************** >>>>> + >>>>> +Name >>>>> +==== >>>>> + >>>>> +VIDIOC_EXT_CREATE_BUFS - Create buffers for Memory Mapped or User Pointer or DMA Buffer I/O >>>>> + >>>>> + >>>>> +Synopsis >>>>> +======== >>>>> + >>>>> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_CREATE_BUFS, struct v4l2_ext_create_buffers *argp ) >>>>> + :name: VIDIOC_EXT_CREATE_BUFS >>>>> + >>>>> + >>>>> +Arguments >>>>> +========= >>>>> + >>>>> +``fd`` >>>>> + File descriptor returned by :ref:`open() <func-open>`. >>>>> + >>>>> +``argp`` >>>>> + Pointer to struct :c:type:`v4l2_ext_create_buffers`. >>>>> + >>>>> + >>>>> +Description >>>>> +=========== >>>>> + >>>>> +This ioctl is used to create buffers for :ref:`memory mapped <mmap>` >>>>> +or :ref:`user pointer <userp>` or :ref:`DMA buffer <dmabuf>` I/O. >>>>> +This ioctl can be called multiple times to >>>>> +create buffers of different sizes. >>>>> + >>>>> +To allocate the device buffers applications must initialize the relevant >>>>> +fields of the struct :c:type:`v4l2_ext_create_buffers` structure. The >>>>> +``count`` field must be set to the number of requested buffers, the >>>>> +``memory`` field specifies the requested I/O method and the ``reserved`` >>>>> +array must be zeroed. >>>>> + >>>>> +The ``format`` field specifies the image format that the buffers must be >>>>> +able to handle. The application has to fill in this struct >>>>> +:c:type:`v4l2_format`. Usually this will be done using the >>>>> +:ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` or >>>>> +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctls to ensure that the >>>>> +requested format is supported by the driver. >>>>> +The driver may return an error if the size(s) are not supported by the >>>>> +hardware (usually because they are too small). >>>>> + >>>>> +The driver can create a memory buffer per plane, or a single memory buffer >>>>> +containing all the planes, with a minimum size according to the size >>>>> +defined by the ``format.plane_fmt[i].sizeimage`` field. >>>>> +Usually if the ``format.plane_fmt[i].sizeimage`` >>>>> +field is less than the minimum required for the given format, then an >>>>> +error will be returned since drivers will typically not allow this. If >>>>> +it is larger, then the value will be used as-is. In other words, the >>>>> +driver may reject the requested size, but if it is accepted the driver >>>>> +will use it unchanged. >>>>> + >>>>> +When the ioctl is called with a pointer to this structure the driver >>>>> +will attempt to allocate up to the requested number of buffers and store >>>>> +the actual number allocated and the starting index in the ``count`` and >>>>> +the ``index`` fields respectively. On return ``count`` can be smaller >>>>> +than the number requested. >>>> >>>> The 'capabilities' and 'flags' fields seem to go undocumented. I removed create_bufs for v6 for now, since it is only useful for MMAP, and if we are going torwards a DMA-fd centric API, then this is low priority and we can define it later. Please check v6 and let me know what you think. >>>> >>>>> + >>>>> + >>>>> +.. kernel-doc:: include/uapi/linux/videodev2.h >>>>> + :functions: v4l2_ext_create_buffers >>>>> + >>>>> + >>>>> +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 <gen-errors>` chapter. >>>>> + >>>>> +ENOMEM >>>>> + No memory to allocate buffers for :ref:`memory mapped <mmap>` I/O. >>>>> + >>>>> +EINVAL >>>>> + The buffer type (``format.type`` field), requested I/O method >>>>> + (``memory``) or format (``format`` field) is not valid. >>>>> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst >>>>> new file mode 100644 >>>>> index 0000000000000..88e4b57121254 >>>>> --- /dev/null >>>>> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst >>>>> @@ -0,0 +1,62 @@ >>>>> +.. Permission is granted to copy, distribute and/or modify this >>>>> +.. document under the terms of the GNU Free Documentation License, >>>>> +.. Version 1.1 or any later version published by the Free Software >>>>> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >>>>> +.. and no Back-Cover Texts. A copy of the license is included at >>>>> +.. Documentation/userspace-api/media/fdl-appendix.rst. >>>>> +.. >>>>> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >>>>> + >>>>> +.. _VIDIOC_EXT_PREPARE_BUF: >>>>> + >>>>> +**************************** >>>>> +ioctl VIDIOC_EXT_PREPARE_BUF >>>>> +**************************** >>>>> + >>>>> +Name >>>>> +==== >>>>> + >>>>> +VIDIOC_EXT_PREPARE_BUF - Prepare a buffer for I/O >>>>> + >>>>> + >>>>> +Synopsis >>>>> +======== >>>>> + >>>>> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_PREPARE_BUF, struct v4l2_ext_buffer *argp ) >>>>> + :name: VIDIOC_EXT_PREPARE_BUF >>>>> + >>>>> + >>>>> +Arguments >>>>> +========= >>>>> + >>>>> +``fd`` >>>>> + File descriptor returned by :ref:`open() <func-open>`. >>>>> + >>>>> +``argp`` >>>>> + Pointer to struct :c:type:`v4l2_ext_buffer`. >>>>> + >>>>> + >>>>> +Description >>>>> +=========== >>>>> + >>>>> +Applications can optionally call the :ref:`VIDIOC_EXT_PREPARE_BUF` ioctl to >>>>> +pass ownership of the buffer to the driver before actually enqueuing it, >>>>> +using the :ref:`VIDIOC_EXT_QBUF <VIDIOC_EXT_QBUF>` ioctl, and to prepare it for future I/O. Such >>>>> +preparations may include cache invalidation or cleaning. Performing them >>>>> +in advance saves time during the actual I/O. >>>>> + >>>>> + >>>>> +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 <gen-errors>` chapter. >>>>> + >>>>> +EBUSY >>>>> + File I/O is in progress. >>>>> + >>>>> +EINVAL >>>>> + The buffer ``type`` is not supported, or the ``index`` is out of >>>>> + bounds, or no buffers have been allocated yet, or the ``userptr`` or >>>>> + ``length`` are invalid. >>>>> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst >>>>> new file mode 100644 >>>>> index 0000000000000..083e106cf6bad >>>>> --- /dev/null >>>>> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst >>>>> @@ -0,0 +1,204 @@ >>>>> +.. Permission is granted to copy, distribute and/or modify this >>>>> +.. document under the terms of the GNU Free Documentation License, >>>>> +.. Version 1.1 or any later version published by the Free Software >>>>> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >>>>> +.. and no Back-Cover Texts. A copy of the license is included at >>>>> +.. Documentation/userspace-api/media/fdl-appendix.rst. >>>>> +.. >>>>> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >>>>> + >>>>> +.. _VIDIOC_EXT_QBUF: >>>>> + >>>>> +*************************************** >>>>> +ioctl VIDIOC_EXT_QBUF, VIDIOC_EXT_DQBUF >>>>> +*************************************** >>>>> + >>>>> +Name >>>>> +==== >>>>> + >>>>> +VIDIOC_EXT_QBUF - VIDIOC_EXT_DQBUF - Exchange a buffer with the driver >>>>> + >>>>> + >>>>> +Synopsis >>>>> +======== >>>>> + >>>>> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_QBUF, struct v4l2_ext_buffer *argp ) >>>>> + :name: VIDIOC_EXT_QBUF >>>>> + >>>>> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_DQBUF, struct v4l2_ext_buffer *argp ) >>>>> + :name: VIDIOC_EXT_DQBUF >>>>> + >>>>> + >>>>> +Arguments >>>>> +========= >>>>> + >>>>> +``fd`` >>>>> + File descriptor returned by :ref:`open() <func-open>`. >>>>> + >>>>> +``argp`` >>>>> + Pointer to struct :c:type:`v4l2_ext_buffer`. >>>>> + >>>>> + >>>>> +Description >>>>> +=========== >>>>> + >>>>> +Applications call the ``VIDIOC_EXT_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 ``type`` field of a struct >>>>> +:c:type:`v4l2_ext_buffer` to the same buffer type as was >>>>> +previously used with struct :c:type:`v4l2_ext_pix_format` ``type``. >>>>> +Applications must also set the ``index`` field. Valid index numbers >>>>> +range from zero to the number of buffers allocated with >>>>> +:ref:`VIDIOC_EXT_CREATE_BUFS` (struct >>>>> +:c:type:`v4l2_ext_create_buffers` ``count``) minus >>>>> +one. The contents of the struct :c:type:`v4l2_ext_buffer` returned >>>> >>>> I think this might not be entirely accurate. One can call >>>> VIDIOC_EXT_CREATE_BUFS multiple times. Moreover, I don't think we've >>>> prohibited VIDIOC_REQBUFS for the ext API, or have we? As per above, I removed VIDIOC_EXT_CREATE_BUFS for v6. >>>> >>>>> +by a :ref:`VIDIOC_EXT_QUERYBUF` ioctl will do as well. >>>>> +When the buffer is intended for output (``type`` is >>>>> +``V4L2_BUF_TYPE_VIDEO_OUTPUT``) applications must also initialize the >>>>> +``timestamp`` fields and the ``planes[i].plane_length`` for each valid plane, >>>>> +and invalid ones must be set as zero. >>>>> +see :ref:`buffer` for details. Applications must also set ``flags`` to 0. The >>>>> +``reserved`` field must be set to 0. >>>>> + >>>>> +To enqueue a :ref:`memory mapped <mmap>` buffer applications set the >>>>> +``planes[i].memory`` field to ``V4L2_MEMORY_MMAP`` in all the valid planes, >>>>> +and invalid ones must be set as zero. >>>>> +When ``VIDIOC_EXT_QBUF`` is called >>>>> +with a pointer to this structure the driver sets the >>>>> +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_QUEUED`` flags and clears >>>>> +the ``V4L2_BUF_FLAG_DONE`` flag in the ``flags`` field, or it returns an >>>>> +``EINVAL`` error code. >>>>> + >>>>> +To enqueue a :ref:`user pointer <userp>` buffer applications set the >>>>> +``planes[i].memory`` field to ``V4L2_MEMORY_USERPTR`` in all the valid planes, >>>>> +and invalid ones must be set as zero, the ``planes[i].m.userptr`` field to the >>>>> +address of the buffer,``planes[i].buffer_length`` to the size of the memory >>>>> +buffer, ``planes[i].plane_length`` to the size that should be used by the plane, >>>>> +and ``planes[i].offset`` of the plane in the memory buffer. >>>> >>>> Does offset make sense here if an arbitrary pointer can be given for the >>>> start of the plane? You are right, it doesn't, but offset can be set to non-zero in dqueue time, in case drivers want to skip a header in the buffer. Make sense? >>>> >>>>> + >>>>> +When ``VIDIOC_EXT_QBUF`` is called with a pointer to this structure >>>>> +the driver sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the >>>>> +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the >>>>> +``flags`` field, or it returns an error code. This ioctl locks the >>>> >>>> This seems to be a copy of the text few lines above. It is not quite the same, the flags that are set or cleared are slighly different. The one a few lines above has V4L2_BUF_FLAG_MAPPED set, and here it is cleared. Maybe we can show a table instead, showing which ones are set and which are cleared, to make it easier to read. >>>> >>>>> +memory pages of the buffer in physical memory, they cannot be swapped >>>>> +out to disk. Buffers remain locked until dequeued, until the >>>>> +:ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or >>>>> +:ref:`VIDIOC_EXT_CREATE_BUFS` ioctl is called, or until the >>>>> +device is closed. >>>> >>>> Why would CREATE_BUFS affect existing buffers? This was a mistake, fixed in v6. >>>> >>>>> + >>>>> +To enqueue a :ref:`DMABUF <dmabuf>` buffer applications set the >>>>> +``planes[i].memory`` field to ``V4L2_MEMORY_DMABUF`` in all the valid planes, >>>>> +and invalid ones must be set as zero, the ``planes[i].m.fd`` field to a >>>>> +file descriptor associated with a DMABUF buffer.,``planes[i].buffer_length`` to >>>>> +the size of the memory buffer, ``planes[i].plane_length`` to the size that >>>> >>>> What is the buffer_length field needed for? DMA-bufs by definition are >>>> kernel objects and the kernel should already know their sizes. >>> >>> See this discussion: >>> >>> https://patchwork.linuxtv.org/project/linux-media/patch/gh5kef5bkeel3o6b2dkgc2dfagu9klj4c0@4ax.com/ >>> >> >> I briefly read through it and I don't see what the conclusion was. >> Generally I'd still prefer if the need to manually specify the buffer >> size was eliminated, because that imposes unnecessary burden on the >> userspace for the majority of cases. It could still remain valid for >> userspace that wants to restrict the buffer size as it was mentioned >> in that thread, though. > > That's really the open issue: if userspace sets length to 0, then it should > always be replaced by the dmabuf size, that's a no-brainer. But if it is non-zero, > what do you do then? Your input would be appreciated. I removed the length field for v6, please check. > >> >>>> >>>>> +should be used by the plane, and ``planes[i].offset`` of the plane in the memory buffer. >>>>> +When ``VIDIOC_EXT_QBUF`` is called with a pointer to this structure the driver >>>>> +sets the ``V4L2_BUF_FLAG_QUEUED`` flag and clears the >>>>> +``V4L2_BUF_FLAG_MAPPED`` and ``V4L2_BUF_FLAG_DONE`` flags in the >>>>> +``flags`` field, or it returns an error code. This ioctl locks the >>>> >>>> Ditto. Ditto. >>>> >>>>> +buffer. Locking a buffer means passing it to a driver for a hardware >>>>> +access (usually DMA). If an application accesses (reads/writes) a locked >>>>> +buffer then the result is undefined. Buffers remain locked until >>>>> +dequeued, until the :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or >>>>> +:ref:`VIDIOC_EXT_CREATE_BUFS` ioctl is called, or until the >>>>> +device is closed. >>>> >>>> Ditto. Ditto. >>>> >>>>> + >>>>> +The ``request_fd`` field can be used with the ``VIDIOC_EXT_QBUF`` ioctl to specify >>>>> +the file descriptor of a :ref:`request <media-request-api>`, if requests are >>>>> +in use. Setting it means that the buffer will not be passed to the driver >>>>> +until the request itself is queued. Also, the driver will apply any >>>>> +settings associated with the request for this buffer. This field will >>>>> +be ignored unless the ``V4L2_BUF_FLAG_REQUEST_FD`` flag is set. >>>>> +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. >>>>> + >>>>> +.. caution:: >>>>> + It is not allowed to mix queuing requests with queuing buffers directly. >>>>> + ``EBUSY`` will be returned if the first buffer was queued directly and >>>>> + then the application tries to queue a request, or vice versa. After >>>>> + closing the file descriptor, calling >>>>> + :ref:`VIDIOC_STREAMOFF <VIDIOC_STREAMON>` or calling :ref:`VIDIOC_EXT_CREATE_BUFS` >>>>> + the check for this will be reset. >>>>> + >>>>> + For :ref:`memory-to-memory devices <mem2mem>` you can specify the >>>>> + ``request_fd`` only for output buffers, not for capture buffers. Attempting >>>>> + to specify this for a capture buffer will result in an ``EBADR`` error. >>>>> + >>>>> +Applications call the ``VIDIOC_EXT_DQBUF`` ioctl to dequeue a filled >>>>> +(capturing) or displayed (output) buffer from the driver's outgoing >>>> >>>> "displayed" is quite inaccurate given that the majority of use cases for >>>> OUTPUT in V4L2 now are m2m devices. Maybe "consumed"? Right, I copy&pasted from vidioc-qbuf.rst, so I guess we should update there too. >>>> >>>>> +queue. They just set the ``type``, ``planes[i].memory`` and ``reserved`` fields of >>>> >>>> Why does the application have to set the memory field? It should be already >>>> known by the kernel which owns the buffer at the given time. Ack, does this apply to EXT_QBUF too? Since userspace needs to switch the memory type in advance with reqbufs, then the kernel already knows the memory type at queue time too. >>>> >>>>> +a struct :c:type:`v4l2_ext_buffer` as above, when >>>>> +``VIDIOC_EXT_DQBUF`` is called with a pointer to this structure the driver >>>>> +fills the remaining fields or returns an error code. The driver may also >>>>> +set ``V4L2_BUF_FLAG_ERROR`` in the ``flags`` field. It indicates a >>>>> +non-critical (recoverable) streaming error. In such case the application >>>>> +may continue as normal, but should be aware that data in the dequeued >>>>> +buffer might be corrupted. When using the multi-planar API, the planes >>>>> +array must be passed in as well. >>>>> + >>>>> +If the application sets the ``memory`` field to ``V4L2_MEMORY_DMABUF`` to >>>>> +dequeue a :ref:`DMABUF <dmabuf>` buffer, the driver fills the ``m.fd`` field >>>>> +with a file descriptor numerically the same as the one given to ``VIDIOC_EXT_QBUF`` >>>>> +when the buffer was enqueued. No new file descriptor is created at dequeue time >>>>> +and the value is only for the application convenience. >>>> >>>> Honestly, I don't like this aspect of the current API. It kind of implies >>>> that the value returned is valid, but the file descriptor might have been >>>> already closed. Could we just remove this and explicitly state that for >>>> DMA-buf, it is the user space responsibility to track the mapping between >>>> V4L2 indexes and its own buffer objects? I can set to zero, and I would do this for all memory types, not only dma, just for consistency. But wouldn't it be usefull if applications want to re-queue the buffer without the need to re-assign the pointers? >>>> >>>>> + >>>>> +By default ``VIDIOC_EXT_DQBUF`` blocks when no buffer is in the outgoing >>>>> +queue. When the ``O_NONBLOCK`` flag was given to the >>>>> +:ref:`open() <func-open>` function, ``VIDIOC_EXT_DQBUF`` returns >>>>> +immediately with an ``EAGAIN`` error code when no buffer is available. >>>>> + >>>>> + >>>>> +.. kernel-doc:: include/uapi/linux/videodev2.h >>>>> + :functions: v4l2_ext_buffers >>>>> + >>>>> + >>>>> +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 <gen-errors>` chapter. >>>>> + >>>>> +EAGAIN >>>>> + Non-blocking I/O has been selected using ``O_NONBLOCK`` and no >>>>> + buffer was in the outgoing queue. >>>>> + >>>>> +EINVAL >>>>> + The buffer ``type`` is not supported, or the ``index`` is out of >>>>> + bounds, or no buffers have been allocated yet, or the ``userptr`` or >>>>> + ``length`` are invalid, or the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was >>>> >>>> There is no 'length' now. Ack, removed. >>>> >>>>> + set but the the given ``request_fd`` was invalid, or ``m.fd`` was >>>>> + an invalid DMABUF file descriptor. >>>>> + >>>>> +EIO >>>>> + ``VIDIOC_EXT_DQBUF`` failed due to an internal error. Can also indicate >>>>> + temporary problems like signal loss. >>> >>> Drop the last sentence, -EIO should never be used for temporary problems like >>> that. EIO really means that the DMA engine crashed and userspace will have to call >>> STREAMOFF and try to restart the DMA with STREAMON. >>> >> >> I suspect the users of the new API wouldn't actually have to deal with >> a signal loss, but if not, what should be the behavior then? > > The typical behavior is to send out the SOURCE_CHANGE event and stall streaming, > waiting for a valid signal. > > That said, this is something I will dig into a bit deeper for the tegra HDMI > support patch series next week, since this might be hard to do for that hardware. > > But regardless of what is chosen for signal loss, EIO is wrong. Return values > as are documented for VIDIOC_QUERY_DV_TIMINGS would be much more appropriate for this. I'm dropping the last sentense for v6. > >> >>>>> + >>>>> + .. note:: >>>>> + >>>>> + The driver might dequeue an (empty) buffer despite returning >>>>> + an error, or even stop capturing. Reusing such buffer may be unsafe >>>>> + though and its details (e.g. ``index``) may not be returned either. >>> >>> The first part of this note is rather vague. I'm not sure what it meant with this. >>> >>>>> + It is recommended that drivers indicate recoverable errors by setting >>>>> + the ``V4L2_BUF_FLAG_ERROR`` and returning 0 instead. In that case the >>>>> + application should be able to safely reuse the buffer and continue >>>>> + streaming. >>>> >>>> What is this for? It sounds like some legacy behavior, which maybe we could >>>> drop with this new API? >>> >>> No, V4L2_BUF_FLAG_ERROR is really needed. Some hardware can really have >>> intermittent failures causing video frames to be corrupt. And yes, that's >>> typically due to hardware bugs. It usually either happens when you start >>> streaming or just intermittent, but it is not severe enough to stop streaming >>> completely (that's the -EIO error due to a call to vb2_queue_error). >>> >>> It's also used when you stop streaming and pending buffers are returned to >>> userspace. They are marked as ERROR since they don't contain any video, or >>> only partial video (if the DMA was stopped midway a frame). >>> >> >> Sorry, I meant to insert that comment below the first half. The second >> half is fine. > > Ah, that makes much more sense :-) I'm removing the first half for v6 then. > >> >>>> >>>>> + >>>>> +EPIPE >>>>> + ``VIDIOC_EXT_DQBUF`` returns this on an empty capture queue for mem2mem >>>>> + codecs if a buffer with the ``V4L2_BUF_FLAG_LAST`` was already >>>>> + dequeued and no new buffers are expected to become available. >>>>> + >>>>> +EBADR >>>>> + The ``V4L2_BUF_FLAG_REQUEST_FD`` flag was set but the device does not >>>>> + support requests for the given buffer type, or >>>>> + the ``V4L2_BUF_FLAG_REQUEST_FD`` flag was not set but the device requires >>>>> + that the buffer is part of a request. >>>>> + >>>>> +EBUSY >>>>> + The first buffer was queued via a request, but the application now tries >>>>> + to queue it directly, or vice versa (it is not permitted to mix the two >>>>> + APIs). >>>>> diff --git a/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst b/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst >>>>> new file mode 100644 >>>>> index 0000000000000..f2a12017253f6 >>>>> --- /dev/null >>>>> +++ b/Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst >>>>> @@ -0,0 +1,79 @@ >>>>> +.. Permission is granted to copy, distribute and/or modify this >>>>> +.. document under the terms of the GNU Free Documentation License, >>>>> +.. Version 1.1 or any later version published by the Free Software >>>>> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >>>>> +.. and no Back-Cover Texts. A copy of the license is included at >>>>> +.. Documentation/userspace-api/media/fdl-appendix.rst. >>>>> +.. >>>>> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >>>>> + >>>>> +.. _VIDIOC_EXT_QUERYBUF: >>>>> + >>>>> +************************* >>>>> +ioctl VIDIOC_EXT_QUERYBUF >>>>> +************************* >>>>> + >>>>> +Name >>>>> +==== >>>>> + >>>>> +VIDIOC_EXT_QUERYBUF - Query the status of a buffer >>>>> + >>>>> + >>>>> +Synopsis >>>>> +======== >>>>> + >>>>> +.. c:function:: int ioctl( int fd, VIDIOC_EXT_QUERYBUF, struct v4l2_ext_buffer *argp ) >>>>> + :name: VIDIOC_EXT_QUERYBUF >>>>> + >>>>> + >>>>> +Arguments >>>>> +========= >>>>> + >>>>> +``fd`` >>>>> + File descriptor returned by :ref:`open() <func-open>`. >>>>> + >>>>> +``argp`` >>>>> + Pointer to struct :c:type:`v4l2_ext_buffer`. >>>>> + >>>>> + >>>>> +Description >>>>> +=========== >>>>> + >>>>> +This ioctl is part of the :ref:`streaming <mmap>` 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:`VIDIOC_EXT_CREATE_BUFS` ioctl. >>>>> + >>>>> +Applications set the ``type`` field of a struct >>>>> +:c:type:`v4l2_ext_buffer` to the same buffer type as was >>>>> +previously used with struct :c:type:`v4l2_ext_pix_format` ``type``, >>>>> +and the ``index`` field. Valid index numbers range from zero to the >>>>> +number of buffers allocated with >>>>> +:ref:`VIDIOC_EXT_CREATE_BUFS` (struct >>>>> +:c:type:`v4l2_ext_create_buffers` ``count``) minus >>>>> +one. The ``reserved`` field must be set to 0. >>>>> + >>>>> +In the ``flags`` field the ``V4L2_BUF_FLAG_MAPPED``, >>>>> +``V4L2_BUF_FLAG_PREPARED``, ``V4L2_BUF_FLAG_QUEUED`` and >>>>> +``V4L2_BUF_FLAG_DONE`` flags will be valid. The ``planes.memory`` fields will be >>>>> +set to the current I/O method for each plane. >>>>> + >>>>> +For every valid plane, an entry in ``planes`` will be filled, and zeroed for >>>>> +invalid ones. ``planes[i].buffer_length`` is the size of the memory buffer >>>>> +which contains the plane, ``planes[i].plane_length`` is the length of the plane, >>>> >>>> What is the length of the plane here? It seems like depending on the >>>> context, the field can mean size of the payload (for filled buffer) or >>>> total space for the payload (for empty buffer), which is a bit confusing. I removed ext_querybuf for v6. >>>> >>>>> +and ``planes[i].offset` is where the plane is placed in the memory buffer. >>>>> + >>>>> +The size of the ``planes`` array can be calculated by the number of sequential >>>>> +planes with ``planes[i].buffer_length`` that differs from zero up to the max >>>>> +size of the array. >>>> >>>> Not sure if it's just me, but "size of array" sounds to me like the >>>> total memory size of the array, i.e. the max number of elements, which >>>> is fixed for this struct. How about >>>> >>>> "The entries of the planes array are valid up to the last entry with >>>> non-zero buffer_length or the last entry of the array, whichever is >>>> first." >>>> >>>> ? Sounds better indeed, but I removed ext_querybuf for v6. >>>> >>>>> + >>>>> + >>>>> +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 <gen-errors>` chapter. >>>>> + >>>>> +EINVAL >>>>> + The buffer ``type`` is not supported, or the ``index`` is out of >>>>> + bounds. >>>>> diff --git a/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst b/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst >>>>> new file mode 100644 >>>>> index 0000000000000..008e6c98a88a5 >>>>> --- /dev/null >>>>> +++ b/Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst >>>>> @@ -0,0 +1,117 @@ >>>>> +.. Permission is granted to copy, distribute and/or modify this >>>>> +.. document under the terms of the GNU Free Documentation License, >>>>> +.. Version 1.1 or any later version published by the Free Software >>>>> +.. Foundation, with no Invariant Sections, no Front-Cover Texts >>>>> +.. and no Back-Cover Texts. A copy of the license is included at >>>>> +.. Documentation/userspace-api/media/fdl-appendix.rst. >>>>> +.. >>>>> +.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections >>>>> + >>>>> +.. _VIDIOC_G_EXT_PIX_FMT: >>>>> + >>>>> +************************************************************************ >>>>> +ioctl VIDIOC_G_EXT_PIX_FMT, VIDIOC_S_EXT_PIX_FMT, VIDIOC_TRY_EXT_PIX_FMT >>>>> +************************************************************************ >>>>> + >>>>> +Name >>>>> +==== >>>>> + >>>>> +VIDIOC_G_EXT_PIX_FMT - VIDIOC_S_EXT_PIX_FMT - VIDIOC_TRY_EXT_PIX_FMT - Get or set the data format, try a format >>>>> + >>>>> + >>>>> +Synopsis >>>>> +======== >>>>> + >>>>> +.. c:function:: int ioctl( int fd, VIDIOC_G_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) >>>>> + :name: VIDIOC_G_EXT_PIX_FMT >>>>> + >>>>> +.. c:function:: int ioctl( int fd, VIDIOC_S_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) >>>>> + :name: VIDIOC_S_EXT_PIX_FMT >>>>> + >>>>> +.. c:function:: int ioctl( int fd, VIDIOC_TRY_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp ) >>>>> + :name: VIDIOC_TRY_EXT_PIX_FMT >>>>> + >>>>> +Arguments >>>>> +========= >>>>> + >>>>> +``fd`` >>>>> + File descriptor returned by :ref:`open() <func-open>`. >>>>> + >>>>> +``argp`` >>>>> + Pointer to struct :c:type:`v4l2_ext_pix_format`. >>>>> + >>>>> + >>>>> +Description >>>>> +=========== >>>>> + >>>>> +These ioctls are used to negotiate the format of data (typically image >>>>> +format) exchanged between driver and application. >>>>> + >>>>> +To query the current parameters applications set the ``type`` field of a >>>>> +struct :c:type:`v4l2_ext_pix_format` to ``V4L2_BUF_TYPE_VIDEO_CAPTURE`` or >>>>> +``V4L2_BUF_TYPE_VIDEO_OUTPUT``, all the other types are invalid in this API, >>>>> +and multiplanar is supported through modifiers. >>>>> + >>>>> +When the application calls the >>>>> +:ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl with a pointer to this >>>>> +structure the driver fills the other members. >>>>> +When the requested buffer type is not supported drivers return >>>>> +an ``EINVAL`` error code. >>>>> + >>>>> +To change the current format parameters applications initialize all >>>>> +the fields in the struct. >>>>> +For details see the documentation of the various devices types in >>>>> +:ref:`devices`. Good practice is to query the current parameters >>>>> +first, and to modify only those parameters not suitable for the >>>>> +application. When the application calls the :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl with >>>>> +a pointer to a struct :c:type:`v4l2_ext_pix_format` structure the driver >>>>> +checks and adjusts the parameters against hardware abilities. Drivers >>>>> +should not return an error code unless the ``type`` field is invalid, >>>>> +this is a mechanism to fathom device capabilities and to approach >>>>> +parameters acceptable for both the application and driver. On success >>>>> +the driver may program the hardware, allocate resources and generally >>>>> +prepare for data exchange. Finally the :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl returns >>>>> +the current format parameters as :ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` does. Very simple, >>>>> +inflexible devices may even ignore all input and always return the >>>>> +default parameters. However all V4L2 devices exchanging data with the >>>>> +application must implement the :ref:`VIDIOC_G_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` and :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` >>>>> +ioctl. When the requested buffer type is not supported drivers return an >>>>> +EINVAL error code on a :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` attempt. When I/O is already in >>>>> +progress or the resource is not available for other reasons drivers >>>>> +return the ``EBUSY`` error code. >>>>> + >>>>> +The :ref:`VIDIOC_TRY_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` ioctl is equivalent to :ref:`VIDIOC_S_EXT_PIX_FMT <VIDIOC_G_EXT_PIX_FMT>` with one >>>>> +exception: it does not change driver state. It can also be called at any >>>>> +time, never returning ``EBUSY``. This function is provided to negotiate >>>>> +parameters, to learn about hardware limitations, without disabling I/O >>>>> +or possibly time consuming hardware preparations. Although strongly >>>>> +recommended drivers are not required to implement this ioctl. >>>>> + >>>> >>>> Could we make this mandatory to avoid ambiguities in the API? In >>> >>> Yes, please! I updated the text for v6. The only problem is if userspace uses EXT_TRY_FMT to a legacy driver through a conversion layer, and the driver doesn't implement TRY_FMT, do we need a dummy hook for those cases? Thanks Helen >>> >>>> general, most drivers implemented it anyway, without much added >>>> complexity, because one can then simplify S_FMT to TRY_FMT + state >>>> update. >>> >>> Ideally we would also fix the ambiguous situation regarding TRY/S_FMT >>> and unsupported pixelformats: some drivers will replace unsupported >>> pixelformats with a valid pixelformat, others will return an error. >>> >>> v4l2-compliance warns about drivers that return an error and point to >>> this very old thread: >>> >>> http://www.mail-archive.com/linux-media@vger.kernel.org/msg56550.html >>> >>> However, I'm not really sure if we can resolve this ambiguity. I believe >>> that it is only older webcam drivers that return an error. >> >> I guess we can at least enforce a specific behavior in the new API, >> before we get compatibility obligations. :) >> >> Best regards, >> Tomasz >> > > Regards, > > Hans >
Hello, This is v5 of the Extended API for formats and buffers, which introduces the following new ioctls: int ioctl(int fd, VIDIOC_G_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp) int ioctl(int fd, VIDIOC_S_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp) int ioctl(int fd, VIDIOC_TRY_EXT_PIX_FMT, struct v4l2_ext_pix_format *argp) int ioctl(int fd, VIDIOC_EXT_CREATE_BUFS, struct v4l2_ext_create_buffers *argp) int ioctl(int fd, VIDIOC_EXT_QUERYBUF, struct v4l2_ext_buffer *argp) int ioctl(int fd, VIDIOC_EXT_QBUF, struct v4l2_ext_buffer *argp) int ioctl(int fd, VIDIOC_EXT_DQBUF, struct v4l2_ext_buffer *argp) int ioctl(int fd, VIDIOC_EXT_PREPARE_BUF, struct v4l2_ext_buffer *argp) Please check v4 cover letter specific topic past discussions https://patchwork.linuxtv.org/project/linux-media/cover/20200717115435.2632623-1-helen.koike@collabora.com/ Documentation ============= I added a first version of the documentation. I would appreciate some tips in how to organize this better, since there are several parts of the docs which reference the "old" API, and for now I just added a note pointing to the Extended API. Instead of duplicating documentation from the code to the Docs (as used by most part of v4l2 documentation), I just added a reference to let Sphinx get the structs documentation from the code, so we can avoid duplicating. For reviewing convenience, I uploaded the generated html docs at https://people.collabora.com/~koike/ext-doc-v5/userspace-api/media/v4l/ext-api.html There is room for improvements, it would be great to get your suggestions. uAPI ==== This version have some minor changes in the uAPI structs, highlight to the mem_offset that was returned to struct v4l2_ext_plane, memory field that now is per plane, and some adjustments in field sizes and re-ordering to make structs the same for 32 and 64 bits (which I verified with pahole tool). I also updated v4l2-compliance: https://gitlab.collabora.com/koike/v4l-utils/-/tree/ext-api/wip We need to decide the size of the reserved fields left, how much reserved fields do you think we should leave for each struct? What is next ============ I would like to improve implementation (for the kernel and v4l2-compliane) and drop the RFC tag for next version, so please review the uAPI. List of changes in v5: ====================== * first version of Documentation * migrate memory from v4l2_ext_buffer to v4l2_ext_plane * return mem_offset to struct v4l2_ext_plane * change sizes and reorder fields to avoid holes in the struct and make it the same for 32 and 64 bits * removed __attribute__ ((packed)) from uapi structs * set request_fd to signed * add documentation * updated some commit messages Hans Verkuil (1): media: v4l2: Add extended buffer operations Helen Koike (6): media: v4l2: Extend pixel formats to unify single/multi-planar handling (and more) media: videobuf2: Expose helpers to implement the _ext_fmt and _ext_buf hooks media: mediabus: Add helpers to convert a ext_pix format to/from a mbus_fmt media: vivid: Convert the capture and output drivers to EXT_FMT/EXT_BUF media: vimc: Implement the ext_fmt and ext_buf hooks media: docs: add documentation for the Extended API .../userspace-api/media/v4l/buffer.rst | 5 + .../userspace-api/media/v4l/common.rst | 1 + .../userspace-api/media/v4l/dev-capture.rst | 5 + .../userspace-api/media/v4l/dev-output.rst | 5 + .../userspace-api/media/v4l/ext-api.rst | 107 ++ .../userspace-api/media/v4l/format.rst | 16 +- .../userspace-api/media/v4l/user-func.rst | 5 + .../media/v4l/vidioc-ext-create-bufs.rst | 95 ++ .../media/v4l/vidioc-ext-prepare-buf.rst | 62 ++ .../media/v4l/vidioc-ext-qbuf.rst | 204 ++++ .../media/v4l/vidioc-ext-querybuf.rst | 79 ++ .../media/v4l/vidioc-g-ext-pix-fmt.rst | 117 +++ .../media/common/videobuf2/videobuf2-core.c | 2 + .../media/common/videobuf2/videobuf2-v4l2.c | 560 ++++++----- .../media/test-drivers/vimc/vimc-capture.c | 61 +- drivers/media/test-drivers/vimc/vimc-common.c | 6 +- drivers/media/test-drivers/vimc/vimc-common.h | 2 +- drivers/media/test-drivers/vivid/vivid-core.c | 70 +- .../test-drivers/vivid/vivid-touch-cap.c | 26 +- .../test-drivers/vivid/vivid-touch-cap.h | 3 +- .../media/test-drivers/vivid/vivid-vid-cap.c | 169 +--- .../media/test-drivers/vivid/vivid-vid-cap.h | 15 +- .../media/test-drivers/vivid/vivid-vid-out.c | 193 ++-- .../media/test-drivers/vivid/vivid-vid-out.h | 15 +- drivers/media/v4l2-core/v4l2-dev.c | 50 +- drivers/media/v4l2-core/v4l2-ioctl.c | 938 ++++++++++++++++-- include/media/v4l2-ioctl.h | 60 ++ include/media/v4l2-mediabus.h | 42 + include/media/videobuf2-core.h | 6 +- include/media/videobuf2-v4l2.h | 21 +- include/uapi/linux/videodev2.h | 146 +++ 31 files changed, 2363 insertions(+), 723 deletions(-) create mode 100644 Documentation/userspace-api/media/v4l/ext-api.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-create-bufs.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-prepare-buf.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-qbuf.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-ext-querybuf.rst create mode 100644 Documentation/userspace-api/media/v4l/vidioc-g-ext-pix-fmt.rst