[{"id":4485,"web_url":"https://patchwork.libcamera.org/comment/4485/","msgid":"<20200421215541.GE5381@paasikivi.fi.intel.com>","date":"2020-04-21T21:55:41","subject":"Re: [libcamera-devel] [PATCH v4 5/5] v4l: document\n\tVIDIOC_SUBDEV_QUERYCAP","submitter":{"id":37,"url":"https://patchwork.libcamera.org/api/people/37/","name":"Sakari Ailus","email":"sakari.ailus@linux.intel.com"},"content":"Hi Jacopo,\n\nOn Sat, Apr 18, 2020 at 12:32:16PM +0200, Jacopo Mondi wrote:\n> From: Hans Verkuil \n> \n> Add documentation for the new VIDIOC_SUBDEV_QUERYCAP ioctl.\n> \n> Signed-off-by: Hans Verkuil \n> Signed-off-by: Jacopo Mondi \n> ---\n> .../userspace-api/media/v4l/user-func.rst | 1 +\n> .../media/v4l/vidioc-subdev-querycap.rst | 114 ++++++++++++++++++\n> 2 files changed, 115 insertions(+)\n> create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst\n> \n> diff --git a/Documentation/userspace-api/media/v4l/user-func.rst b/Documentation/userspace-api/media/v4l/user-func.rst\n> index f235f88efe89..559cce421d41 100644\n> --- a/Documentation/userspace-api/media/v4l/user-func.rst\n> +++ b/Documentation/userspace-api/media/v4l/user-func.rst\n> @@ -78,6 +78,7 @@ Function Reference\n> vidioc-subdev-g-fmt\n> vidioc-subdev-g-frame-interval\n> vidioc-subdev-g-selection\n> + vidioc-subdev-querycap.rst\n\n.rst looks like extra.\n\n> vidioc-subscribe-event\n> func-mmap\n> func-munmap\n> diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst\n> new file mode 100644\n> index 000000000000..d9b2e19e1339\n> --- /dev/null\n> +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst\n> @@ -0,0 +1,114 @@\n> +.. Permission is granted to copy, distribute and/or modify this\n> +.. document under the terms of the GNU Free Documentation License,\n> +.. Version 1.1 or any later version published by the Free Software\n> +.. Foundation, with no Invariant Sections, no Front-Cover Texts\n> +.. and no Back-Cover Texts. A copy of the license is included at\n> +.. Documentation/userspace-api/media/fdl-appendix.rst.\n> +..\n> +\n> +.. _VIDIOC_SUBDEV_QUERYCAP:\n> +\n> +****************************\n> +ioctl VIDIOC_SUBDEV_QUERYCAP\n> +****************************\n> +\n> +Name\n> +====\n> +\n> +VIDIOC_SUBDEV_QUERYCAP - Query sub-device capabilities\n> +\n> +\n> +Synopsis\n> +========\n> +\n> +.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERYCAP, struct v4l2_subdev_capability *argp )\n> + :name: VIDIOC_SUBDEV_QUERYCAP\n> +\n> +\n> +Arguments\n> +=========\n> +\n> +``fd``\n> + File descriptor returned by :ref:`open() `.\n> +\n> +``argp``\n> + Pointer to struct :c:type:`v4l2_subdev_capability`.\n> +\n> +\n> +Description\n> +===========\n> +\n> +All V4L2 sub-devices support the\n> +``VIDIOC_SUBDEV_QUERYCAP`` ioctl. It is used to identify\n\nYou could rewrap the paragraph.\n\n> +kernel devices compatible with this specification and to obtain\n> +information about driver and hardware capabilities. The ioctl takes a\n> +pointer to a struct :c:type:`v4l2_subdev_capability` which is filled by the\n> +driver. When the driver is not compatible with this specification the ioctl\n> +returns ``ENOTTY`` error code.\n> +\n> +.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}|\n> +\n> +.. c:type:: v4l2_subdev_capability\n> +\n> +.. flat-table:: struct v4l2_subdev_capability\n> + :header-rows: 0\n> + :stub-columns: 0\n> + :widths: 3 4 20\n> +\n> + * - __u32\n> + - ``version``\n> + - Version number of the driver.\n> +\n> + The version reported is provided by the V4L2 subsystem following the\n> + kernel numbering scheme. However, it may not always return the same\n> + version as the kernel if, for example, a stable or\n> + distribution-modified kernel uses the V4L2 stack from a newer kernel.\n> +\n> +\tThe version number is formatted using the ``KERNEL_VERSION()``\n> +\tmacro:\n> + * - :cspan:`2`\n> +\n> +\t``#define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))``\n> +\n> +\t``__u32 version = KERNEL_VERSION(0, 8, 1);``\n> +\n> +\t``printf (\"Version: %u.%u.%u\\\\n\",``\n> +\n> +\t``(version >> 16) & 0xFF, (version >> 8) & 0xFF, version & 0xFF);``\n> + * - __u32\n> + - ``subdev_caps``\n> + - Sub-device capabilities of the opened device, see\n> +\t:ref:`subdevice-capabilities`.\n> +\n> +.. tabularcolumns:: |p{6cm}|p{2.2cm}|p{8.8cm}|\n> +\n> +.. _subdevice-capabilities:\n> +\n> +.. cssclass:: longtable\n> +\n> +.. flat-table:: Sub-Device Capabilities Flags\n> + :header-rows: 0\n> + :stub-columns: 0\n> + :widths: 3 1 4\n> +\n> + * - V4L2_SUBDEV_CAP_RO_SUBDEV\n> + - 0x00000001\n> + - The sub-device device node is registered in read-only mode.\n> + Access to the sub-device ioctls that modify the device state is\n> + restricted. Refer to each individual subdevice ioctl documentation\n> + for a description of which restrictions apply to a read-only sub-device.\n\nTabs would be nice. Same below (and above, too).\n\nAcked-by: Sakari Ailus \n\n> +\n> + * - V4L2_SUBDEV_CAP_RW_SUBDEV\n> + - 0x00000002\n> + - The sub-device device node is registered in read/write mode, all the\n> + subdevice ioctls are accessible from userspace.\n> +\n> +Return Value\n> +============\n> +\n> +On success 0 is returned, on error -1 and the ``errno`` variable is set\n> +appropriately. The generic error codes are described at the\n> +:ref:`Generic Error Codes ` chapter.\n> +\n> +ENOTTY\n> + The device node is not a V4L2 sub-device.","headers":{"Return-Path":"","Received":["from mga07.intel.com (mga07.intel.com [134.134.136.100])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 87ED560406\n\tfor ;\n\tTue, 21 Apr 2020 23:56:17 +0200 (CEST)","from orsmga008.jf.intel.com ([10.7.209.65])\n\tby orsmga105.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; \n\t21 Apr 2020 14:56:16 -0700","from paasikivi.fi.intel.com ([10.237.72.42])\n\tby orsmga008-auth.jf.intel.com with\n\tESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 21 Apr 2020 14:56:13 -0700","by paasikivi.fi.intel.com (Postfix, from userid 1000)\n\tid 601F1204D0; Wed, 22 Apr 2020 00:55:41 +0300 (EEST)"],"IronPort-SDR":["GqMwVQvGnrbmLelQHyFToELXkkrE1+++64wO6CTejzgWmkqWCo7wHvy0pq0QWq8/nqMGdvRo64\n\tjBw7+RAlbsRA==","asPLudFKSlXnorjCTZInW86jjPKWHQcTyHhrS9b4cz4j63JH7aDqJ0IPolToNWcVeBITiIcRcl\n\t4WZxlJyeILSg=="],"X-Amp-Result":"SKIPPED(no attachment in message)","X-Amp-File-Uploaded":"False","X-IronPort-AV":"E=Sophos;i=\"5.72,411,1580803200\"; d=\"scan'208\";a=\"291733440\"","Date":"Wed, 22 Apr 2020 00:55:41 +0300","From":"Sakari Ailus ","To":"Jacopo Mondi ","Cc":"linux-media@vger.kernel.org, libcamera-devel@lists.libcamera.org,\n\tmchehab@kernel.org, hverkuil-cisco@xs4all.nl,\n\tandrey.konovalov@linaro.org, laurent.pinchart@ideasonboard.com,\n\tHans Verkuil ","Message-ID":"<20200421215541.GE5381@paasikivi.fi.intel.com>","References":"<20200418103216.140572-1-jacopo@jmondi.org>\n\t<20200418103216.140572-6-jacopo@jmondi.org>","MIME-Version":"1.0","Content-Type":"text/plain; charset=us-ascii","Content-Disposition":"inline","In-Reply-To":"<20200418103216.140572-6-jacopo@jmondi.org>","User-Agent":"Mutt/1.10.1 (2018-07-13)","Subject":"Re: [libcamera-devel] [PATCH v4 5/5] v4l: document\n\tVIDIOC_SUBDEV_QUERYCAP","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","X-List-Received-Date":"Tue, 21 Apr 2020 21:56:18 -0000"}},{"id":4620,"web_url":"https://patchwork.libcamera.org/comment/4620/","msgid":"<20200428145230.kqvbbzzc6qgplx4t@uno.localdomain>","date":"2020-04-28T14:52:30","subject":"Re: [libcamera-devel] [PATCH v4 5/5] v4l: document\n\tVIDIOC_SUBDEV_QUERYCAP","submitter":{"id":3,"url":"https://patchwork.libcamera.org/api/people/3/","name":"Jacopo Mondi","email":"jacopo@jmondi.org"},"content":"Hi Sakari,\n\nOn Wed, Apr 22, 2020 at 12:55:41AM +0300, Sakari Ailus wrote:\n> Hi Jacopo,\n>\n> On Sat, Apr 18, 2020 at 12:32:16PM +0200, Jacopo Mondi wrote:\n> > From: Hans Verkuil \n> >\n> > Add documentation for the new VIDIOC_SUBDEV_QUERYCAP ioctl.\n> >\n> > Signed-off-by: Hans Verkuil \n> > Signed-off-by: Jacopo Mondi \n> > ---\n> > .../userspace-api/media/v4l/user-func.rst | 1 +\n> > .../media/v4l/vidioc-subdev-querycap.rst | 114 ++++++++++++++++++\n> > 2 files changed, 115 insertions(+)\n> > create mode 100644 Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst\n> >\n> > diff --git a/Documentation/userspace-api/media/v4l/user-func.rst b/Documentation/userspace-api/media/v4l/user-func.rst\n> > index f235f88efe89..559cce421d41 100644\n> > --- a/Documentation/userspace-api/media/v4l/user-func.rst\n> > +++ b/Documentation/userspace-api/media/v4l/user-func.rst\n> > @@ -78,6 +78,7 @@ Function Reference\n> > vidioc-subdev-g-fmt\n> > vidioc-subdev-g-frame-interval\n> > vidioc-subdev-g-selection\n> > + vidioc-subdev-querycap.rst\n>\n> .rst looks like extra.\n>\n> > vidioc-subscribe-event\n> > func-mmap\n> > func-munmap\n> > diff --git a/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst\n> > new file mode 100644\n> > index 000000000000..d9b2e19e1339\n> > --- /dev/null\n> > +++ b/Documentation/userspace-api/media/v4l/vidioc-subdev-querycap.rst\n> > @@ -0,0 +1,114 @@\n> > +.. Permission is granted to copy, distribute and/or modify this\n> > +.. document under the terms of the GNU Free Documentation License,\n> > +.. Version 1.1 or any later version published by the Free Software\n> > +.. Foundation, with no Invariant Sections, no Front-Cover Texts\n> > +.. and no Back-Cover Texts. A copy of the license is included at\n> > +.. Documentation/userspace-api/media/fdl-appendix.rst.\n> > +..\n> > +\n> > +.. _VIDIOC_SUBDEV_QUERYCAP:\n> > +\n> > +****************************\n> > +ioctl VIDIOC_SUBDEV_QUERYCAP\n> > +****************************\n> > +\n> > +Name\n> > +====\n> > +\n> > +VIDIOC_SUBDEV_QUERYCAP - Query sub-device capabilities\n> > +\n> > +\n> > +Synopsis\n> > +========\n> > +\n> > +.. c:function:: int ioctl( int fd, VIDIOC_SUBDEV_QUERYCAP, struct v4l2_subdev_capability *argp )\n> > + :name: VIDIOC_SUBDEV_QUERYCAP\n> > +\n> > +\n> > +Arguments\n> > +=========\n> > +\n> > +``fd``\n> > + File descriptor returned by :ref:`open() `.\n> > +\n> > +``argp``\n> > + Pointer to struct :c:type:`v4l2_subdev_capability`.\n> > +\n> > +\n> > +Description\n> > +===========\n> > +\n> > +All V4L2 sub-devices support the\n> > +``VIDIOC_SUBDEV_QUERYCAP`` ioctl. It is used to identify\n>\n> You could rewrap the paragraph.\n>\n> > +kernel devices compatible with this specification and to obtain\n> > +information about driver and hardware capabilities. The ioctl takes a\n> > +pointer to a struct :c:type:`v4l2_subdev_capability` which is filled by the\n> > +driver. When the driver is not compatible with this specification the ioctl\n> > +returns ``ENOTTY`` error code.\n> > +\n> > +.. tabularcolumns:: |p{1.5cm}|p{2.5cm}|p{13cm}|\n> > +\n> > +.. c:type:: v4l2_subdev_capability\n> > +\n> > +.. flat-table:: struct v4l2_subdev_capability\n> > + :header-rows: 0\n> > + :stub-columns: 0\n> > + :widths: 3 4 20\n> > +\n> > + * - __u32\n> > + - ``version``\n> > + - Version number of the driver.\n> > +\n> > + The version reported is provided by the V4L2 subsystem following the\n> > + kernel numbering scheme. However, it may not always return the same\n> > + version as the kernel if, for example, a stable or\n> > + distribution-modified kernel uses the V4L2 stack from a newer kernel.\n> > +\n> > +\tThe version number is formatted using the ``KERNEL_VERSION()``\n> > +\tmacro:\n> > + * - :cspan:`2`\n> > +\n> > +\t``#define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))``\n> > +\n> > +\t``__u32 version = KERNEL_VERSION(0, 8, 1);``\n> > +\n> > +\t``printf (\"Version: %u.%u.%u\\\\n\",``\n> > +\n> > +\t``(version >> 16) & 0xFF, (version >> 8) & 0xFF, version & 0xFF);``\n> > + * - __u32\n> > + - ``subdev_caps``\n> > + - Sub-device capabilities of the opened device, see\n> > +\t:ref:`subdevice-capabilities`.\n> > +\n> > +.. tabularcolumns:: |p{6cm}|p{2.2cm}|p{8.8cm}|\n> > +\n> > +.. _subdevice-capabilities:\n> > +\n> > +.. cssclass:: longtable\n> > +\n> > +.. flat-table:: Sub-Device Capabilities Flags\n> > + :header-rows: 0\n> > + :stub-columns: 0\n> > + :widths: 3 1 4\n> > +\n> > + * - V4L2_SUBDEV_CAP_RO_SUBDEV\n> > + - 0x00000001\n> > + - The sub-device device node is registered in read-only mode.\n> > + Access to the sub-device ioctls that modify the device state is\n> > + restricted. Refer to each individual subdevice ioctl documentation\n> > + for a description of which restrictions apply to a read-only sub-device.\n>\n> Tabs would be nice. Same below (and above, too).\n\nI'm not sure what is the rule here, but mixing tabs and spaces doesn't\nseem nice to me :)\n\n>\n> Acked-by: Sakari Ailus \n>\n\nThanks\n j\n\n> > +\n> > + * - V4L2_SUBDEV_CAP_RW_SUBDEV\n> > + - 0x00000002\n> > + - The sub-device device node is registered in read/write mode, all the\n> > + subdevice ioctls are accessible from userspace.\n> > +\n> > +Return Value\n> > +============\n> > +\n> > +On success 0 is returned, on error -1 and the ``errno`` variable is set\n> > +appropriately. The generic error codes are described at the\n> > +:ref:`Generic Error Codes ` chapter.\n> > +\n> > +ENOTTY\n> > + The device node is not a V4L2 sub-device.\n>\n> --\n> Kind regards,\n>\n> Sakari Ailus","headers":{"Return-Path":"","Received":["from relay8-d.mail.gandi.net (relay8-d.mail.gandi.net\n\t[217.70.183.201])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id C86B860AF5\n\tfor ;\n\tTue, 28 Apr 2020 16:49:22 +0200 (CEST)","from uno.localdomain (a-ur1-85.tin.it [212.216.150.148])\n\t(Authenticated sender: jacopo@jmondi.org)\n\tby relay8-d.mail.gandi.net (Postfix) with ESMTPSA id 8DD5D1BF20D;\n\tTue, 28 Apr 2020 14:49:19 +0000 (UTC)"],"X-Originating-IP":"212.216.150.148","Date":"Tue, 28 Apr 2020 16:52:30 +0200","From":"Jacopo Mondi ","To":"Sakari Ailus ","Cc":"linux-media@vger.kernel.org, libcamera-devel@lists.libcamera.org,\n\tmchehab@kernel.org, hverkuil-cisco@xs4all.nl,\n\tandrey.konovalov@linaro.org, laurent.pinchart@ideasonboard.com,\n\tHans Verkuil ","Message-ID":"<20200428145230.kqvbbzzc6qgplx4t@uno.localdomain>","References":"<20200418103216.140572-1-jacopo@jmondi.org>\n\t<20200418103216.140572-6-jacopo@jmondi.org>\n\t<20200421215541.GE5381@paasikivi.fi.intel.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20200421215541.GE5381@paasikivi.fi.intel.com>","Subject":"Re: [libcamera-devel] [PATCH v4 5/5] v4l: document\n\tVIDIOC_SUBDEV_QUERYCAP","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","X-List-Received-Date":"Tue, 28 Apr 2020 14:49:23 -0000"}}]