On 14/08/18 10:48, Mauro Carvalho Chehab wrote:
> Em Tue, 14 Aug 2018 09:57:27 +0200
> Hans Verkuil <hverk...@xs4all.nl> escreveu:
>
>> On 09/08/18 19:43, Mauro Carvalho Chehab wrote:
>>>> diff --git a/Documentation/media/uapi/v4l/vidioc-qbuf.rst
>>>> b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
>>>> index 9e448a4aa3aa..0e415f2551b2 100644
>>>> --- a/Documentation/media/uapi/v4l/vidioc-qbuf.rst
>>>> +++ b/Documentation/media/uapi/v4l/vidioc-qbuf.rst
>>>> @@ -65,7 +65,7 @@ To enqueue a :ref:`memory mapped <mmap>` buffer
>>>> applications set the
>>>> 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.
>>>> +``EINVAL`` error code.
>>>
>>> Side note: we should likely do a similar replacement on all other places
>>> inside the media uAPI docs.
>>>
>>>>
>>>> To enqueue a :ref:`user pointer <userp>` buffer applications set the
>>>> ``memory`` field to ``V4L2_MEMORY_USERPTR``, the ``m.userptr`` field to
>>>> @@ -98,6 +98,25 @@ dequeued, until the :ref:`VIDIOC_STREAMOFF
>>>> <VIDIOC_STREAMON>` or
>>>> :ref:`VIDIOC_REQBUFS` ioctl is called, or until the
>>>> device is closed.
>>>>
>>>> +The ``request_fd`` field can be used with the ``VIDIOC_QBUF`` ioctl to
>>>> specify
>>>
>>> Please prefer using :ref: for QBUF too, e. g.:
>>> :ref:`ioctl VIDIOC_QBUF <VIDIOC_QBUF>`
>>
>> Does this make sense when you are in the QBUF documentation itself? Using
>> :ref: will
>> just link back to the same page.
>>
>> We need some guidelines here. I personally don't think this makes sense.
>
> I'm almost sure we're doing the same on every other place within media docs.
Not in vidioc-qbuf.rst: there you never use :ref: to refer to a QBUF/DQBUF.
I want to keep this as-is. If we really want to change this, then it should
be done for all vidioc-*.rst files.
A quick grep shows that this is very common:
git grep '``VIDIOC_' Documentation/media/uapi/v4l/vidioc-*
I honestly think it is silly and even confusing to use a :ref: to the page
you are already on.
I keep this as-is since this is consistent with the usage elsewhere in
vidioc-qbuuf.rst.
If we want to change this, then that's something we should do separately from
this
patch.
Regards,
Hans
>
>>
>> Regards,
>>
>> Hans
>
>
>
> Thanks,
> Mauro
>
