From patchwork Wed Mar 31 09:32:27 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pawel Osciak X-Patchwork-Id: 89912 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by demeter.kernel.org (8.14.3/8.14.3) with ESMTP id o2V9WpcG007487 for ; Wed, 31 Mar 2010 09:34:31 GMT Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S933073Ab0CaJcv (ORCPT ); Wed, 31 Mar 2010 05:32:51 -0400 Received: from mailout2.w1.samsung.com ([210.118.77.12]:30210 "EHLO mailout2.w1.samsung.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S933071Ab0CaJcs (ORCPT ); Wed, 31 Mar 2010 05:32:48 -0400 Received: from eu_spt2 (mailout2.w1.samsung.com [210.118.77.12]) by mailout2.w1.samsung.com (iPlanet Messaging Server 5.2 Patch 2 (built Jul 14 2004)) with ESMTP id <0L0500DZR3UJE4@mailout2.w1.samsung.com> for linux-media@vger.kernel.org; Wed, 31 Mar 2010 10:32:43 +0100 (BST) Received: from linux.samsung.com ([106.116.38.10]) by spt2.w1.samsung.com (iPlanet Messaging Server 5.2 Patch 2 (built Jul 14 2004)) with ESMTPA id <0L0500K0V3UJ13@spt2.w1.samsung.com> for linux-media@vger.kernel.org; Wed, 31 Mar 2010 10:32:43 +0100 (BST) Received: from localhost.localdomain (unknown [106.116.37.23]) by linux.samsung.com (Postfix) with ESMTP id 73D7427004E; Wed, 31 Mar 2010 11:32:42 +0200 (CEST) Date: Wed, 31 Mar 2010 11:32:27 +0200 From: Pawel Osciak Subject: [PATCH v2 3/3] v4l: Add documentation for the new error flag In-reply-to: <1270027947-28327-1-git-send-email-p.osciak@samsung.com> To: linux-media@vger.kernel.org Cc: p.osciak@samsung.com, m.szyprowski@samsung.com, kyungmin.park@samsung.com Message-id: <1270027947-28327-4-git-send-email-p.osciak@samsung.com> MIME-version: 1.0 X-Mailer: git-send-email 1.7.0 Content-type: TEXT/PLAIN Content-transfer-encoding: 7BIT References: <1270027947-28327-1-git-send-email-p.osciak@samsung.com> Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org X-Greylist: IP, sender and recipient auto-whitelisted, not delayed by milter-greylist-4.2.3 (demeter.kernel.org [140.211.167.41]); Wed, 31 Mar 2010 09:34:31 +0000 (UTC) diff --git a/Documentation/DocBook/v4l/io.xml b/Documentation/DocBook/v4l/io.xml index e870330..1bc2057 100644 --- a/Documentation/DocBook/v4l/io.xml +++ b/Documentation/DocBook/v4l/io.xml @@ -702,6 +702,16 @@ They can be both cleared however, then the buffer is in "dequeued" state, in the application domain to say so. + V4L2_BUF_FLAG_ERROR + 0x0040 + When this flag is set, the buffer has been dequeued + sucessfully, although the data might have been corrupted. + This is recoverable, streaming may continue as normal and + the buffer may be reused normally. + Drivers set this flag when the VIDIOC_DQBUF + ioctl is called. + + V4L2_BUF_FLAG_KEYFRAME 0x0008 Drivers set or clear this flag when calling the diff --git a/Documentation/DocBook/v4l/vidioc-qbuf.xml b/Documentation/DocBook/v4l/vidioc-qbuf.xml index b843bd7..ab691eb 100644 --- a/Documentation/DocBook/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/v4l/vidioc-qbuf.xml @@ -111,7 +111,11 @@ from the driver's outgoing queue. They just set the and reserved fields of a &v4l2-buffer; as above, when VIDIOC_DQBUF is called with a pointer to this structure the driver fills the -remaining fields or returns an error code. +remaining fields or returns an error code. The driver may also set +V4L2_BUF_FLAG_ERROR in the flags +field. It indicates a non-critical (recoverable) streaming error. In such case +the application may continue as normal, but should be aware that data in the +dequeued buffer might be corrupted. By default VIDIOC_DQBUF blocks when no buffer is in the outgoing queue. When the @@ -158,7 +162,13 @@ enqueue a user pointer buffer. VIDIOC_DQBUF failed due to an internal error. Can also indicate temporary problems like signal loss. Note the driver might dequeue an (empty) buffer despite -returning an error, or even stop capturing. +returning an error, or even stop capturing. Reusing such buffer may be unsafe +though and its details (e.g. index) may not be +returned either. It is recommended that drivers indicate recoverable errors +by setting the V4L2_BUF_FLAG_ERROR and returning 0 instead. +In that case the application should be able to safely reuse the buffer and +continue streaming. +