Re: [PATCHv17 01/34] Documentation: v4l: document request API
Hi! > Document the request API for V4L2 devices, and amend the documentation > of system calls influenced by it. > > Signed-off-by: Alexandre Courbot > Signed-off-by: Hans Verkuil Cc documentation people? > +Synopsis > + > + > +.. c:function:: int ioctl( int request_fd, MEDIA_REQUEST_IOC_QUEUE ) > +:name: MEDIA_REQUEST_IOC_QUEUE > + > + > +Arguments > += > + > +``request_fd`` > +File descriptor returned by :ref:`MEDIA_IOC_REQUEST_ALLOC`. > + > + > +Description > +=== > + > +If the media device supports :ref:`requests `, then > +this request ioctl can be used to queue a previously allocated request. > + > +If the request was successfully queued, then the file descriptor can be > +:ref:`polled ` to wait for the request to complete. > + > +If the request was already queued before, then ``EBUSY`` is returned. I'd expect -1 to be returned and errno set to EBUSY? > + > + > +On success 0 is returned, on error -1 and the ``errno`` variable is set > +appropriately. The generic error codes are described at the > +:ref:`Generic Error Codes ` chapter. > + > +EBUSY > +The request was already queued. > +EPERM > +The application queued the first buffer directly, but later attempted > +to use a request. It is not permitted to mix the two APIs. > +ENOENT > +The request did not contain any buffers. All requests are required > +to have at least one buffer. This can also be returned if required > +controls are missing. > +ENOMEM > +Out of memory when allocating internal data structures for this > +request. > +EINVAL > +The request has invalid data. > +EIO > +The hardware is in a bad state. To recover, the application needs to > +stop streaming to reset the hardware state and then try to restart > +streaming. Pavel
Re: [PATCHv17 01/34] Documentation: v4l: document request API
Em Tue, 14 Aug 2018 11:51:30 +0200 Hans Verkuil escreveu: > On 14/08/18 10:48, Mauro Carvalho Chehab wrote: > > Em Tue, 14 Aug 2018 09:57:27 +0200 > > Hans Verkuil 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 ` 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 ` 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 > ` 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 ` > >> > >> 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. Ok, let's be consistent with what's already there. Thanks, Mauro
Re: [PATCHv17 01/34] Documentation: v4l: document request API
On 14/08/18 10:48, Mauro Carvalho Chehab wrote: > Em Tue, 14 Aug 2018 09:57:27 +0200 > Hans Verkuil 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 ` 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 ` 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 ` 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 ` >> >> 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 >
Re: [PATCHv17 01/34] Documentation: v4l: document request API
Em Tue, 14 Aug 2018 09:57:27 +0200 Hans Verkuil 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 ` 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 ` 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 > >> ` 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 ` > > 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. > > Regards, > > Hans Thanks, Mauro
Re: [PATCHv17 01/34] Documentation: v4l: document request API
Em Fri, 10 Aug 2018 09:20:48 +0200
Hans Verkuil escreveu:
> On 08/09/2018 07:43 PM, Mauro Carvalho Chehab wrote:
> > Em Sat, 4 Aug 2018 14:44:53 +0200
> > Hans Verkuil escreveu:
> >
> >> From: Alexandre Courbot
> >>
> >> Document the request API for V4L2 devices, and amend the documentation
> >> of system calls influenced by it.
> >
> > It follows some comments. Most are nitpicks. There are just two ones
> > that aren't:
> > - a problem at the tables changes on Documentation/
> > - a question with regards to MEDIA_IOC_REQUEST_ALLOC ioctl.
>
> I'll fix all the smaller comments and in this reply only address these
> two topics.
>
> >
> > I'll keep reviewing this patch series.
> >
> > PS.: I lost entirely my first review to this doc... I hope I didn't
> > forget anything when re-typing my comments.
> >
> >>
> >> Signed-off-by: Alexandre Courbot
> >> Signed-off-by: Hans Verkuil
> >> ---
> >> .../media/uapi/mediactl/media-controller.rst | 1 +
> >> .../media/uapi/mediactl/media-funcs.rst | 6 +
> >> .../uapi/mediactl/media-ioc-request-alloc.rst | 78 ++
> >> .../uapi/mediactl/media-request-ioc-queue.rst | 82 ++
> >> .../mediactl/media-request-ioc-reinit.rst | 51
> >> .../media/uapi/mediactl/request-api.rst | 247 ++
> >> .../uapi/mediactl/request-func-close.rst | 49
> >> .../uapi/mediactl/request-func-ioctl.rst | 68 +
> >> .../media/uapi/mediactl/request-func-poll.rst | 77 ++
> >> Documentation/media/uapi/v4l/buffer.rst | 21 +-
> >> .../media/uapi/v4l/vidioc-g-ext-ctrls.rst | 94 ---
> >> Documentation/media/uapi/v4l/vidioc-qbuf.rst | 32 ++-
> >> .../media/videodev2.h.rst.exceptions | 1 +
> >> 13 files changed, 771 insertions(+), 36 deletions(-)
> >> create mode 100644
> >> Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
> >> create mode 100644
> >> Documentation/media/uapi/mediactl/media-request-ioc-queue.rst
> >> create mode 100644
> >> Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst
> >> create mode 100644 Documentation/media/uapi/mediactl/request-api.rst
> >> create mode 100644
> >> Documentation/media/uapi/mediactl/request-func-close.rst
> >> create mode 100644
> >> Documentation/media/uapi/mediactl/request-func-ioctl.rst
> >> create mode 100644 Documentation/media/uapi/mediactl/request-func-poll.rst
> >>
>
>
>
> >> +.. c:type:: media_request_alloc
> >> +
> >> +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
> >> +
> >> +.. flat-table:: struct media_request_alloc
> >> +:header-rows: 0
> >> +:stub-columns: 0
> >> +:widths: 1 1 2
> >> +
> >> +* - __s32
> >> + - ``fd``
> >> + - The file descriptor of the request.
> >
> > It should be mentioned that the struct should be zeroed before calling
> > the Kernel, but I is overkill to have a struct to pass just one value.
> >
> > I mean, if this has just one value inside the struct, it is a way better
> > to declare it as:
> >
> > .. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, s32 )
> >
> > Even if we later need more stuff, the size of a new MEDIA_IOC_REQUEST_ALLOC
> > will be bigger, and then (and only then) we can add extra stuff.
> >
> > Or are you foreseen any new fields there in short term?
>
> The first version just had a s32 argument, not a struct. The main reason for
> going back to a struct was indeed to make it easier to add new fields in the
> future. I don't foresee any, but then, you never do.
>
> I don't have a particularly strong opinion on this one way or another, but
> if we change it back to a s32 argument, then I want the opinion of others as
> well.
I'll comment it on patch 02/34.
>
>
>
> >> @@ -110,15 +130,13 @@ still cause this situation.
> >> .. flat-table:: struct v4l2_ext_control
> >> :header-rows: 0
> >> :stub-columns: 0
> >> -:widths: 1 1 1 2
> >> +:widths: 1 1 3
> >
> > This is wrong: you can't change widths without changing the preceeding
> > .. tabularcolumns tag.
> >
> > You probably didn't test PDF generation for this table.
> >
> > Also, the change is this table doesn't belong to this patch. It is
> > a (doubtful) optimization at the table, not related to requests API.
> >
> >>
> >> * - __u32
> >>- ``id``
> >> - -
> >>- Identifies the control, set by the application.
> >> * - __u32
> >>- ``size``
> >> - -
> >>- The total size in bytes of the payload of this control. This is
> >>normally 0, but for pointer controls this should be set to the
> >>size of the memory containing the payload, or that will receive
> >> @@ -135,51 +153,43 @@ still cause this situation.
> >> *length* of the string may well be much smaller.
> >> * - __u32
> >>- ``reserved2``\ [1]
> >> - -
> >>- Reserved for future extensions. Drivers and applications must set
> >>the
Re: [PATCHv17 01/34] Documentation: v4l: document request API
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 ` 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 ` 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 >> ` 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 ` 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. Regards, Hans
Re: [PATCHv17 01/34] Documentation: v4l: document request API
On 08/09/2018 07:43 PM, Mauro Carvalho Chehab wrote:
> Em Sat, 4 Aug 2018 14:44:53 +0200
> Hans Verkuil escreveu:
>
>> From: Alexandre Courbot
>>
>> Document the request API for V4L2 devices, and amend the documentation
>> of system calls influenced by it.
>
> It follows some comments. Most are nitpicks. There are just two ones
> that aren't:
> - a problem at the tables changes on Documentation/
> - a question with regards to MEDIA_IOC_REQUEST_ALLOC ioctl.
I'll fix all the smaller comments and in this reply only address these
two topics.
>
> I'll keep reviewing this patch series.
>
> PS.: I lost entirely my first review to this doc... I hope I didn't
> forget anything when re-typing my comments.
>
>>
>> Signed-off-by: Alexandre Courbot
>> Signed-off-by: Hans Verkuil
>> ---
>> .../media/uapi/mediactl/media-controller.rst | 1 +
>> .../media/uapi/mediactl/media-funcs.rst | 6 +
>> .../uapi/mediactl/media-ioc-request-alloc.rst | 78 ++
>> .../uapi/mediactl/media-request-ioc-queue.rst | 82 ++
>> .../mediactl/media-request-ioc-reinit.rst | 51
>> .../media/uapi/mediactl/request-api.rst | 247 ++
>> .../uapi/mediactl/request-func-close.rst | 49
>> .../uapi/mediactl/request-func-ioctl.rst | 68 +
>> .../media/uapi/mediactl/request-func-poll.rst | 77 ++
>> Documentation/media/uapi/v4l/buffer.rst | 21 +-
>> .../media/uapi/v4l/vidioc-g-ext-ctrls.rst | 94 ---
>> Documentation/media/uapi/v4l/vidioc-qbuf.rst | 32 ++-
>> .../media/videodev2.h.rst.exceptions | 1 +
>> 13 files changed, 771 insertions(+), 36 deletions(-)
>> create mode 100644
>> Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
>> create mode 100644
>> Documentation/media/uapi/mediactl/media-request-ioc-queue.rst
>> create mode 100644
>> Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst
>> create mode 100644 Documentation/media/uapi/mediactl/request-api.rst
>> create mode 100644 Documentation/media/uapi/mediactl/request-func-close.rst
>> create mode 100644 Documentation/media/uapi/mediactl/request-func-ioctl.rst
>> create mode 100644 Documentation/media/uapi/mediactl/request-func-poll.rst
>>
>> +.. c:type:: media_request_alloc
>> +
>> +.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
>> +
>> +.. flat-table:: struct media_request_alloc
>> +:header-rows: 0
>> +:stub-columns: 0
>> +:widths: 1 1 2
>> +
>> +* - __s32
>> + - ``fd``
>> + - The file descriptor of the request.
>
> It should be mentioned that the struct should be zeroed before calling
> the Kernel, but I is overkill to have a struct to pass just one value.
>
> I mean, if this has just one value inside the struct, it is a way better
> to declare it as:
>
> .. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, s32 )
>
> Even if we later need more stuff, the size of a new MEDIA_IOC_REQUEST_ALLOC
> will be bigger, and then (and only then) we can add extra stuff.
>
> Or are you foreseen any new fields there in short term?
The first version just had a s32 argument, not a struct. The main reason for
going back to a struct was indeed to make it easier to add new fields in the
future. I don't foresee any, but then, you never do.
I don't have a particularly strong opinion on this one way or another, but
if we change it back to a s32 argument, then I want the opinion of others as
well.
>> @@ -110,15 +130,13 @@ still cause this situation.
>> .. flat-table:: struct v4l2_ext_control
>> :header-rows: 0
>> :stub-columns: 0
>> -:widths: 1 1 1 2
>> +:widths: 1 1 3
>
> This is wrong: you can't change widths without changing the preceeding
> .. tabularcolumns tag.
>
> You probably didn't test PDF generation for this table.
>
> Also, the change is this table doesn't belong to this patch. It is
> a (doubtful) optimization at the table, not related to requests API.
>
>>
>> * - __u32
>>- ``id``
>> - -
>>- Identifies the control, set by the application.
>> * - __u32
>>- ``size``
>> - -
>>- The total size in bytes of the payload of this control. This is
>> normally 0, but for pointer controls this should be set to the
>> size of the memory containing the payload, or that will receive
>> @@ -135,51 +153,43 @@ still cause this situation.
>> *length* of the string may well be much smaller.
>> * - __u32
>>- ``reserved2``\ [1]
>> - -
>>- Reserved for future extensions. Drivers and applications must set
>> the array to zero.
>> -* - union
>> +* - union {
>
> Adding { and } at the end sounds ok...
>
>>- (anonymous)
>> -* -
>> - - __s32
>> +* - __s32
>>- ``value``
>>- New value or current value. Valid if this control is not of type
>> ``V4L2_CTRL_TYPE_INTEGER64`` and ``V4L2_CTRL_FLAG_HAS_PAYLOAD`` is
>> not
Re: [PATCHv17 01/34] Documentation: v4l: document request API
Em Sat, 4 Aug 2018 14:44:53 +0200 Hans Verkuil escreveu: > From: Alexandre Courbot > > Document the request API for V4L2 devices, and amend the documentation > of system calls influenced by it. It follows some comments. Most are nitpicks. There are just two ones that aren't: - a problem at the tables changes on Documentation/ - a question with regards to MEDIA_IOC_REQUEST_ALLOC ioctl. I'll keep reviewing this patch series. PS.: I lost entirely my first review to this doc... I hope I didn't forget anything when re-typing my comments. > > Signed-off-by: Alexandre Courbot > Signed-off-by: Hans Verkuil > --- > .../media/uapi/mediactl/media-controller.rst | 1 + > .../media/uapi/mediactl/media-funcs.rst | 6 + > .../uapi/mediactl/media-ioc-request-alloc.rst | 78 ++ > .../uapi/mediactl/media-request-ioc-queue.rst | 82 ++ > .../mediactl/media-request-ioc-reinit.rst | 51 > .../media/uapi/mediactl/request-api.rst | 247 ++ > .../uapi/mediactl/request-func-close.rst | 49 > .../uapi/mediactl/request-func-ioctl.rst | 68 + > .../media/uapi/mediactl/request-func-poll.rst | 77 ++ > Documentation/media/uapi/v4l/buffer.rst | 21 +- > .../media/uapi/v4l/vidioc-g-ext-ctrls.rst | 94 --- > Documentation/media/uapi/v4l/vidioc-qbuf.rst | 32 ++- > .../media/videodev2.h.rst.exceptions | 1 + > 13 files changed, 771 insertions(+), 36 deletions(-) > create mode 100644 > Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst > create mode 100644 > Documentation/media/uapi/mediactl/media-request-ioc-queue.rst > create mode 100644 > Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst > create mode 100644 Documentation/media/uapi/mediactl/request-api.rst > create mode 100644 Documentation/media/uapi/mediactl/request-func-close.rst > create mode 100644 Documentation/media/uapi/mediactl/request-func-ioctl.rst > create mode 100644 Documentation/media/uapi/mediactl/request-func-poll.rst > > diff --git a/Documentation/media/uapi/mediactl/media-controller.rst > b/Documentation/media/uapi/mediactl/media-controller.rst > index 0eea4f9a07d5..66aff38cd499 100644 > --- a/Documentation/media/uapi/mediactl/media-controller.rst > +++ b/Documentation/media/uapi/mediactl/media-controller.rst > @@ -21,6 +21,7 @@ Part IV - Media Controller API > media-controller-intro > media-controller-model > media-types > +request-api > media-funcs > media-header > > diff --git a/Documentation/media/uapi/mediactl/media-funcs.rst > b/Documentation/media/uapi/mediactl/media-funcs.rst > index 076856501cdb..260f9dcadcde 100644 > --- a/Documentation/media/uapi/mediactl/media-funcs.rst > +++ b/Documentation/media/uapi/mediactl/media-funcs.rst > @@ -16,3 +16,9 @@ Function Reference > media-ioc-enum-entities > media-ioc-enum-links > media-ioc-setup-link > +media-ioc-request-alloc > +request-func-close > +request-func-ioctl > +request-func-poll > +media-request-ioc-queue > +media-request-ioc-reinit > diff --git a/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst > b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst > new file mode 100644 > index ..11dcc14ca0bd > --- /dev/null > +++ b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst > @@ -0,0 +1,78 @@ > +.. SPDX-License-Identifier: GPL-2.0 Better to use SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-or-later WITH no-invariant-sections E. g. dual-licensing it with FDL and add a LICENSES/exceptions for no-invariant-sections. > + > +.. _media_ioc_request_alloc: > + > +* > +ioctl MEDIA_IOC_REQUEST_ALLOC > +* > + > +Name > + > + > +MEDIA_IOC_REQUEST_ALLOC - Allocate a request > + > + > +Synopsis > + > + > +.. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, struct > media_request_alloc *argp ) > +:name: MEDIA_IOC_REQUEST_ALLOC > + > + > +Arguments > += > + > +``fd`` > +File descriptor returned by :ref:`open() `. > + > +``argp`` > +Pointer to struct :c:type:`media_request_alloc`. > + > + > +Description > +=== > + > +If the media device supports :ref:`requests `, then > +this ioctl can be used to allocate a request. If it is not supported, then > +``errno`` is set to ``ENOTTY``. A request is accessed through a file > descriptor > +that is returned in struct :c:type:`media_request_alloc`. > + > +If the request was successfully allocated, then the request file descriptor > +can be passed to the :ref:`VIDIOC_QBUF `, > +:ref:`VIDIOC_G_EXT_CTRLS `, > +:ref:`VIDIOC_S_EXT_CTRLS ` and > +:ref:`VIDIOC_TRY_EXT_CTRLS ` ioctls. > + > +In addition, the request can be queued by calling > +:ref:`MEDIA_REQUEST_IOC_QUEUE` and re-initialized by calling > +:ref:`MEDIA_REQUEST_IOC_REINIT`. > + > +Finally, the file descriptor can be :ref:`polled ` to wait >
[PATCHv17 01/34] Documentation: v4l: document request API
From: Alexandre Courbot
Document the request API for V4L2 devices, and amend the documentation
of system calls influenced by it.
Signed-off-by: Alexandre Courbot
Signed-off-by: Hans Verkuil
---
.../media/uapi/mediactl/media-controller.rst | 1 +
.../media/uapi/mediactl/media-funcs.rst | 6 +
.../uapi/mediactl/media-ioc-request-alloc.rst | 78 ++
.../uapi/mediactl/media-request-ioc-queue.rst | 82 ++
.../mediactl/media-request-ioc-reinit.rst | 51
.../media/uapi/mediactl/request-api.rst | 247 ++
.../uapi/mediactl/request-func-close.rst | 49
.../uapi/mediactl/request-func-ioctl.rst | 68 +
.../media/uapi/mediactl/request-func-poll.rst | 77 ++
Documentation/media/uapi/v4l/buffer.rst | 21 +-
.../media/uapi/v4l/vidioc-g-ext-ctrls.rst | 94 ---
Documentation/media/uapi/v4l/vidioc-qbuf.rst | 32 ++-
.../media/videodev2.h.rst.exceptions | 1 +
13 files changed, 771 insertions(+), 36 deletions(-)
create mode 100644
Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
create mode 100644
Documentation/media/uapi/mediactl/media-request-ioc-queue.rst
create mode 100644
Documentation/media/uapi/mediactl/media-request-ioc-reinit.rst
create mode 100644 Documentation/media/uapi/mediactl/request-api.rst
create mode 100644 Documentation/media/uapi/mediactl/request-func-close.rst
create mode 100644 Documentation/media/uapi/mediactl/request-func-ioctl.rst
create mode 100644 Documentation/media/uapi/mediactl/request-func-poll.rst
diff --git a/Documentation/media/uapi/mediactl/media-controller.rst
b/Documentation/media/uapi/mediactl/media-controller.rst
index 0eea4f9a07d5..66aff38cd499 100644
--- a/Documentation/media/uapi/mediactl/media-controller.rst
+++ b/Documentation/media/uapi/mediactl/media-controller.rst
@@ -21,6 +21,7 @@ Part IV - Media Controller API
media-controller-intro
media-controller-model
media-types
+request-api
media-funcs
media-header
diff --git a/Documentation/media/uapi/mediactl/media-funcs.rst
b/Documentation/media/uapi/mediactl/media-funcs.rst
index 076856501cdb..260f9dcadcde 100644
--- a/Documentation/media/uapi/mediactl/media-funcs.rst
+++ b/Documentation/media/uapi/mediactl/media-funcs.rst
@@ -16,3 +16,9 @@ Function Reference
media-ioc-enum-entities
media-ioc-enum-links
media-ioc-setup-link
+media-ioc-request-alloc
+request-func-close
+request-func-ioctl
+request-func-poll
+media-request-ioc-queue
+media-request-ioc-reinit
diff --git a/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
new file mode 100644
index ..11dcc14ca0bd
--- /dev/null
+++ b/Documentation/media/uapi/mediactl/media-ioc-request-alloc.rst
@@ -0,0 +1,78 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _media_ioc_request_alloc:
+
+*
+ioctl MEDIA_IOC_REQUEST_ALLOC
+*
+
+Name
+
+
+MEDIA_IOC_REQUEST_ALLOC - Allocate a request
+
+
+Synopsis
+
+
+.. c:function:: int ioctl( int fd, MEDIA_IOC_REQUEST_ALLOC, struct
media_request_alloc *argp )
+:name: MEDIA_IOC_REQUEST_ALLOC
+
+
+Arguments
+=
+
+``fd``
+File descriptor returned by :ref:`open() `.
+
+``argp``
+Pointer to struct :c:type:`media_request_alloc`.
+
+
+Description
+===
+
+If the media device supports :ref:`requests `, then
+this ioctl can be used to allocate a request. If it is not supported, then
+``errno`` is set to ``ENOTTY``. A request is accessed through a file descriptor
+that is returned in struct :c:type:`media_request_alloc`.
+
+If the request was successfully allocated, then the request file descriptor
+can be passed to the :ref:`VIDIOC_QBUF `,
+:ref:`VIDIOC_G_EXT_CTRLS `,
+:ref:`VIDIOC_S_EXT_CTRLS ` and
+:ref:`VIDIOC_TRY_EXT_CTRLS ` ioctls.
+
+In addition, the request can be queued by calling
+:ref:`MEDIA_REQUEST_IOC_QUEUE` and re-initialized by calling
+:ref:`MEDIA_REQUEST_IOC_REINIT`.
+
+Finally, the file descriptor can be :ref:`polled ` to wait
+for the request to complete.
+
+The request will remain allocated until all the file descriptors associated
+with it are closed by :ref:`close() ` and the driver no
+longer uses the request internally.
+
+.. c:type:: media_request_alloc
+
+.. tabularcolumns:: |p{4.4cm}|p{4.4cm}|p{8.7cm}|
+
+.. flat-table:: struct media_request_alloc
+:header-rows: 0
+:stub-columns: 0
+:widths: 1 1 2
+
+* - __s32
+ - ``fd``
+ - The file descriptor of the request.
+
+Return Value
+
+
+On success 0 is returned, on error -1 and the ``errno`` variable is set
+appropriately. The generic error codes are described at the
+:ref:`Generic Error Codes ` chapter.
+
+ENOTTY
+The driver has no support for requests.
diff --git a/Documentation/media/uapi/mediactl/media-request-ioc-queue.rst
