From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from galahad.ideasonboard.com ([185.26.127.97]:40878 "EHLO galahad.ideasonboard.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752258AbbEDHob (ORCPT ); Mon, 4 May 2015 03:44:31 -0400 From: Laurent Pinchart To: Hans Verkuil Cc: linux-media@vger.kernel.org, Hans Verkuil Subject: Re: [RFC PATCH 2/3] DocBook/media: document VIDIOC_SUBDEV_QUERYCAP Date: Mon, 04 May 2015 01:29:20 +0300 Message-ID: <2025720.hkQNlttbI3@avalon> In-Reply-To: <1430480030-29136-3-git-send-email-hverkuil@xs4all.nl> References: <1430480030-29136-1-git-send-email-hverkuil@xs4all.nl> <1430480030-29136-3-git-send-email-hverkuil@xs4all.nl> MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" Sender: linux-media-owner@vger.kernel.org List-ID: Hi Hans, Thank you for the patch. On Friday 01 May 2015 13:33:49 Hans Verkuil wrote: > From: Hans Verkuil > > Add documentation for the new VIDIOC_SUBDEV_QUERYCAP ioctl. > > Signed-off-by: Hans Verkuil > --- > Documentation/DocBook/media/v4l/v4l2.xml | 1 + > .../DocBook/media/v4l/vidioc-querycap.xml | 2 +- > .../DocBook/media/v4l/vidioc-subdev-querycap.xml | 140 ++++++++++++++++++ > 3 files changed, 142 insertions(+), 1 deletion(-) > create mode 100644 > Documentation/DocBook/media/v4l/vidioc-subdev-querycap.xml > > diff --git a/Documentation/DocBook/media/v4l/v4l2.xml > b/Documentation/DocBook/media/v4l/v4l2.xml index e98caa1..23607bc 100644 > --- a/Documentation/DocBook/media/v4l/v4l2.xml > +++ b/Documentation/DocBook/media/v4l/v4l2.xml > @@ -669,6 +669,7 @@ and discussions on the V4L mailing list. > &sub-subdev-g-fmt; > &sub-subdev-g-frame-interval; > &sub-subdev-g-selection; > + &sub-subdev-querycap; > &sub-subscribe-event; > > &sub-mmap; > diff --git a/Documentation/DocBook/media/v4l/vidioc-querycap.xml > b/Documentation/DocBook/media/v4l/vidioc-querycap.xml index > 20fda75..c1ed844 100644 > --- a/Documentation/DocBook/media/v4l/vidioc-querycap.xml > +++ b/Documentation/DocBook/media/v4l/vidioc-querycap.xml > @@ -54,7 +54,7 @@ kernel devices compatible with this specification and to > obtain information about driver and hardware capabilities. The ioctl takes > a pointer to a &v4l2-capability; which is filled by the driver. When the > driver is not compatible with this specification the ioctl returns an > -&EINVAL;. > +&ENOTTY;. I'd split this change to a separate patch as it's unrelated to VIDIOC_SUBDEV_QUERYCAP. We can't really guarantee that non-V4L2 drivers will return -ENOTTY, they might be buggy and return a different error code. That's slightly nitpicking though. > > struct <structname>v4l2_capability</structname> > diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-querycap.xml > b/Documentation/DocBook/media/v4l/vidioc-subdev-querycap.xml new file mode > 100644 > index 0000000..a1cbb36 > --- /dev/null > +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-querycap.xml > @@ -0,0 +1,140 @@ > + > + > + ioctl VIDIOC_SUBDEV_QUERYCAP > + &manvol; > + > + > + > + VIDIOC_SUBDEV_QUERYCAP > + Query sub-device capabilities > + > + > + > + > + > + int ioctl > + int fd > + int request > + struct v4l2_subdev_capability > *argp > + > + > + > + > + > + Arguments > + > + > + > + fd > + > + &fd; > + > + > + > + request > + > + VIDIOC_SUBDEV_QUERYCAP > + > + > + > + argp > + > + > + > + > + > + > + > + > + Description > + > + All V4L2 sub-devices support the > +VIDIOC_SUBDEV_QUERYCAP ioctl. It is used to identify > +kernel devices compatible with this specification and to obtain > +information about driver and hardware capabilities. The ioctl takes a > +pointer to a &v4l2-subdev-capability; which is filled by the driver. When > the > +driver is not compatible with this specification the ioctl returns an > +&ENOTTY;. > + > +
> + struct <structname>v4l2_subdev_capability</structname> > + > + &cs-str; > + > + > + __u32 > + version > + Version number of the driver. > +The version reported is provided by the > +V4L2 subsystem following the kernel numbering scheme. However, it > +may not always return the same version as the kernel if, for example, > +a stable or distribution-modified kernel uses the V4L2 stack from a > +newer kernel. > +The version number is formatted using the > +KERNEL_VERSION() macro: > + > + > + > + > +#define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c)) > + > +__u32 version = KERNEL_VERSION(0, 8, 1); > + > +printf ("Version: %u.%u.%u\n", > + (version >> 16) & 0xFF, > + (version >> 8) & 0xFF, > + version & 0xFF); > + > + > + > + __u32 > + device_caps > + Sub-device capabilities of the opened device, see + linkend="subdevice-capabilities" />. > + > + > + > + __u32 > + pads > + The number of pads of this sub-device. May be 0 if there are no > + pads. Should we mention explicitly that the pads field is only valid if V4L2_SUBDEV_CAP_ENTITY is set ? > + > + > + > + __u32 > + entity_id > + The media controller entity ID of the sub-device. This is only > valid if > + the V4L2_SUBDEV_CAP_ENTITY capability is set. > + > + > + > + __u32 > + reserved[48] > + Reserved for future extensions. Drivers must set > +this array to zero. > + > + > + > +
> + > + > + Sub-Device Capabilities Flags > + > + &cs-def; > + > + > + V4L2_SUBDEV_CAP_ENTITY > + 0x00000001 > + The sub-device is a media controller entity and > + the entity_id field of > &v4l2-subdev-capability; > + is valid. > + > + > + > +
> + > + > + > + &return-value; > + > + -- Regards, Laurent Pinchart