From mboxrd@z Thu Jan 1 00:00:00 1970 Return-path: Received: from lb2-smtp-cloud2.xs4all.net ([194.109.24.25]:49776 "EHLO lb2-smtp-cloud2.xs4all.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750798AbbEDH6k (ORCPT ); Mon, 4 May 2015 03:58:40 -0400 Message-ID: <554726A6.804@xs4all.nl> Date: Mon, 04 May 2015 09:58:30 +0200 From: Hans Verkuil MIME-Version: 1.0 To: Laurent Pinchart CC: linux-media@vger.kernel.org, Hans Verkuil Subject: Re: [RFC PATCH 2/3] DocBook/media: document VIDIOC_SUBDEV_QUERYCAP References: <1430480030-29136-1-git-send-email-hverkuil@xs4all.nl> <1430480030-29136-3-git-send-email-hverkuil@xs4all.nl> <2025720.hkQNlttbI3@avalon> In-Reply-To: <2025720.hkQNlttbI3@avalon> Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 7bit Sender: linux-media-owner@vger.kernel.org List-ID: On 05/04/2015 12:29 AM, Laurent Pinchart wrote: > 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. You are right. I just happened to come across this while adding the subdev-querycap text. > 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. Well, ENOTTY is much more likely than EINVAL :-) But I can replace it with: "...returns an error, most likely &ENOTTY;." and use the same phrase for subdev-querycap. > >> >> 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 ? Yes, we can do that. I checked that all subdev drivers that create a v4l-subdev node are also a media entity. I wasn't sure about that before. Regards, Hans > >> + >> + >> + >> + __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; >> + >> + >