From acf92046a0a666051f9c6b4a53d874c618203173 Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sat, 20 Sep 2014 16:16:36 -0300 Subject: [media] DocBook media: fix the poll() 'no QBUF' documentation Clarify what poll() returns if STREAMON was called but not QBUF. Make explicit the different behavior for this scenario for capture and output devices. Signed-off-by: Hans Verkuil Acked-by: Laurent Pinchart Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/func-poll.xml | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) (limited to 'Documentation/DocBook/media/v4l/func-poll.xml') diff --git a/Documentation/DocBook/media/v4l/func-poll.xml b/Documentation/DocBook/media/v4l/func-poll.xml index 85cad8bff5ba..bd07104a35e9 100644 --- a/Documentation/DocBook/media/v4l/func-poll.xml +++ b/Documentation/DocBook/media/v4l/func-poll.xml @@ -44,10 +44,18 @@ Capture devices set the POLLIN and flags. When the function timed out it returns a value of zero, on failure it returns -1 and the errno variable is set appropriately. When the -application did not call &VIDIOC-QBUF; or &VIDIOC-STREAMON; yet the +application did not call &VIDIOC-STREAMON; the poll() function succeeds, but sets the POLLERR flag in the -revents field. +revents field. When the +application has called &VIDIOC-STREAMON; for a capture device but hasn't +yet called &VIDIOC-QBUF;, the poll() function +succeeds and sets the POLLERR flag in the +revents field. For output devices this +same situation will cause poll() to succeed +as well, but it sets the POLLOUT and +POLLWRNORM flags in the revents +field. When use of the read() function has been negotiated and the driver does not capture yet, the -- cgit v1.2.3 From 91235537bc4b53f0b6f953acf963bcbb6215c49c Mon Sep 17 00:00:00 2001 From: Hans Verkuil Date: Sat, 20 Sep 2014 16:16:37 -0300 Subject: [media] DocBook media: improve the poll() documentation The poll documentation was incomplete: document how events (POLLPRI) are handled and fix the documentation of what poll does for display devices and streaming I/O. Signed-off-by: Hans Verkuil Acked-by: Laurent Pinchart Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media/v4l/func-poll.xml | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) (limited to 'Documentation/DocBook/media/v4l/func-poll.xml') diff --git a/Documentation/DocBook/media/v4l/func-poll.xml b/Documentation/DocBook/media/v4l/func-poll.xml index bd07104a35e9..4c73f115219b 100644 --- a/Documentation/DocBook/media/v4l/func-poll.xml +++ b/Documentation/DocBook/media/v4l/func-poll.xml @@ -29,9 +29,12 @@ can suspend execution until the driver has captured data or is ready to accept data for output. When streaming I/O has been negotiated this function waits -until a buffer has been filled or displayed and can be dequeued with -the &VIDIOC-DQBUF; ioctl. When buffers are already in the outgoing -queue of the driver the function returns immediately. +until a buffer has been filled by the capture device and can be dequeued +with the &VIDIOC-DQBUF; ioctl. For output devices this function waits +until the device is ready to accept a new buffer to be queued up with +the &VIDIOC-QBUF; ioctl for display. When buffers are already in the outgoing +queue of the driver (capture) or the incoming queue isn't full (display) +the function returns immediately. On success poll() returns the number of file descriptors that have been selected (that is, file descriptors @@ -57,6 +60,10 @@ as well, but it sets the POLLOUT and POLLWRNORM flags in the revents field. + If an event occurred (see &VIDIOC-DQEVENT;) then +POLLPRI will be set in the revents +field and poll() will return. + When use of the read() function has been negotiated and the driver does not capture yet, the poll function starts capturing. When that fails @@ -66,10 +73,18 @@ continuously (as opposed to, for example, still images) the function may return immediately. When use of the write() function has -been negotiated the poll function just waits +been negotiated and the driver does not stream yet, the +poll function starts streaming. When that fails +it returns a POLLERR as above. Otherwise it waits until the driver is ready for a non-blocking write() call. + If the caller is only interested in events (just +POLLPRI is set in the events +field), then poll() will not +start streaming if the driver does not stream yet. This makes it +possible to just poll for events and not for buffers. + All drivers implementing the read() or write() function or streaming I/O must also support the poll() function. -- cgit v1.2.3