RFC Request API, version 2
--------------------------
This document proposes the public API for handling requests.
There has been some confusion about how to do this, so this summarizes the
current approach based on conversations with the various stakeholders today
(Sakari, Alexandre Courbot, Thomasz Figa and myself).
1) Additions to the media API
Allocate an empty request object:
#define MEDIA_IOC_REQUEST_ALLOC _IOW('|', 0x05, __s32 *)
This will return a file descriptor representing the request or an error
if it can't allocate the request.
If the pointer argument is NULL, then this will just return 0 (if this ioctl
is implemented) or -ENOTTY otherwise. This can be used to test whether this
ioctl is supported or not without actually having to allocate a request.
2) Operations on the request fd
You can queue or reinit a request by calling these ioctls on the request fd:
#define MEDIA_REQUEST_IOC_QUEUE _IO('|', 128)
#define MEDIA_REQUEST_IOC_REINIT _IO('|', 129)
With REINIT you reset the state of the request as if you had just allocated
it.
You can poll the request fd to wait for it to complete.
To free a request you close the request fd. Note that it may still be in
use internally, so the internal datastructures have to be refcounted.
For this initial implementation only buffers and controls are contained
in a request. This is needed to implement stateless codecs. Supporting
complex camera pipelines will require more work.
Requests only contain the changes to the state at request queue time
relative to the previously queued request(s) or the current hardware state
if no other requests were queued.
Once a request is completed it will retain the state at completion
time.
3) To associate a v4l2 buffer with a request the 'reserved' field in struct
v4l2_buffer is used to store the request fd. Buffers won't be 'prepared'
until the request is queued since the request may contain information that
is needed to prepare the buffer.
To indicate that request_fd should be used this flag should be set by
userspace at QBUF time:
#define V4L2_BUF_FLAG_REQUEST 0x00800000
This flag will also be returned by the driver to indicate that the buffer
is associated with a request.
TBD: what should vb2 return as request_fd value if this flag is set?
This should act the same as the fence patch series and this is still
being tweaked so let's wait for that to be merged first, then we can
finalize this.
4) To associate v4l2 controls with a request we take the first of the
'reserved[2]' array elements in struct v4l2_ext_controls and use it to store
the request fd.
We also add a new WHICH value:
#define V4L2_CTRL_WHICH_REQUEST 0x0f010000
This tells the control framework to get/set controls from the given
request fd.
When querying a control value from a request it will return the newest
value in the list of pending requests, or the current hardware value if
is not set in any of the pending requests.
When a request is completed the controls will no longer change. A copy
will be made of volatile controls at the time of completion (actually
it will be up to the driver to decide when to do that).
Volatile controls and requests:
- If you set a volatile control in a request, then that will be ignored,
unless the V4L2_CTRL_FLAG_EXECUTE_ON_WRITE flag is set as well.
- If you get a volatile control from a request then:
1) If the request is completed it will return the value of the volatile
control at completion time.
2) Otherwise: if the V4L2_CTRL_FLAG_EXECUTE_ON_WRITE is set and it was
set in a request, then that value is returned.
3) Otherwise: return the current value from the hardware (i.e. normal
behavior).
Read-only controls and requests:
- If you get a read-only control from a request then:
1) If the request is completed it will return the value of the read-only
control at completion time.
2) Otherwise it will get the current value from the driver (i.e. normal
behavior).
Open issue: should we receive control events if a control in a request is
added/changed? Currently there are no plans to support control events for
requests. I don't see a clear use-case and neither do I see an easy way
of implementing this (which fd would receive those events?).
Notes:
- Earlier versions of this API had a TRY command as well to validate the
request. I'm not sure that is useful so I dropped it, but it can easily
be added if there is a good use-case for it. Traditionally within V4L the
TRY ioctl will also update wrong values to something that works, but that
is not the intention here as far as I understand it. So the validation
step can also be done when the request is queued and, if it fails, it will
just return an error.
- If due to performance reasons we will have to allocate/queue/reinit multiple
requests with a single ioctl, then we will have to add new ioctls to the
media device. At this moment in time it is not clear that this is really
needed and it certainly isn't needed for the stateless codec support that
we are looking at now.
- The behavior of VIDIOC_G_EXT_CTRLS with which == V4L2_CTRL_WHICH_CUR_VAL
and VIDIOC_G_CTRL remains the same (i.e. it returns the current driver/HW
values). However, when combined with requests the documentation should make
clear that this returns a snapshot only and is racy w.r.t. applying values
from a request.
- There is a discussion whether there should be a VIDIOC_REQUEST_ALLOC ioctl
for V4L2 in addition to the media ioctl. The reason is that stateless codecs
do not need the media controller except for allocating requests. So a V4L2
ioctl would avoid applications from having to deal with a media device.
This would also add additional hassle w.r.t. SELinux as I understand it.
Support for this can be added for now as a final patch in the Request API
patch series and we'll postpone the decision on this.
