From: Hans Verkuil Date: Thu, 29 Oct 2015 04:07:30 +0000 (-0200) Subject: [media] DocBook media: update VIDIOC_CREATE_BUFS documentation X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=02a34b6ace4cce92d5cf4d76e54afe0c71e4f706;p=GitHub%2Fmoto-9609%2Fandroid_kernel_motorola_exynos9610.git [media] DocBook media: update VIDIOC_CREATE_BUFS documentation During the Seoul media workshop we decided to relax the VIDIOC_CREATE_BUFS specification so it would no longer require drivers to validate the format field since almost no driver did that anyway. Instead drivers use the buffer size(s) based on the format type and the corresponding format fields and will ignore any other fields. If the size cannot be used an error is returned, otherwise the size is used as-is. Signed-off-by: Hans Verkuil Signed-off-by: Mauro Carvalho Chehab --- diff --git a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml index 8ffe74f84af1..d81fa0d4016b 100644 --- a/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-create-bufs.xml @@ -58,7 +58,7 @@ This ioctl is used to create buffers for memory mapped or user pointer or DMA buffer I/O. It can be used as an alternative or in -addition to the VIDIOC_REQBUFS ioctl, when a tighter +addition to the &VIDIOC-REQBUFS; ioctl, when a tighter control over buffers is required. This ioctl can be called multiple times to create buffers of different sizes. @@ -71,30 +71,28 @@ zeroed. The format field specifies the image format that the buffers must be able to handle. The application has to fill in this -&v4l2-format;. Usually this will be done using the -VIDIOC_TRY_FMT or VIDIOC_G_FMT ioctl() -to ensure that the requested format is supported by the driver. Unsupported -formats will result in an error. +&v4l2-format;. Usually this will be done using the &VIDIOC-TRY-FMT; or &VIDIOC-G-FMT; ioctls +to ensure that the requested format is supported by the driver. +Based on the format's type field the requested buffer +size (for single-planar) or plane sizes (for multi-planar formats) will be +used for the allocated buffers. The driver may return an error if the size(s) +are not supported by the hardware (usually because they are too small). The buffers created by this ioctl will have as minimum size the size -defined by the format.pix.sizeimage field. If the +defined by the format.pix.sizeimage field (or the +corresponding fields for other format types). Usually if the format.pix.sizeimage field is less than the minimum -required for the given format, then sizeimage will be -increased by the driver to that minimum to allocate the buffers. If it is -larger, then the value will be used as-is. The same applies to the -sizeimage field of the -v4l2_plane_pix_format structure in the case of -multiplanar formats. +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 driver may also increase buffer sizes if required, -however, it will not update sizeimage field values. -The user has to use VIDIOC_QUERYBUF to retrieve that -information. +the number requested. struct <structname>v4l2_create_buffers</structname>