From patchwork Fri Jan 25 18:03:29 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sakari Ailus X-Patchwork-Id: 2046651 Return-Path: X-Original-To: patchwork-linux-media@patchwork.kernel.org Delivered-To: patchwork-process-083081@patchwork2.kernel.org Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by patchwork2.kernel.org (Postfix) with ESMTP id 7A355DF23E for ; Fri, 25 Jan 2013 18:03:45 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932439Ab3AYSDg (ORCPT ); Fri, 25 Jan 2013 13:03:36 -0500 Received: from nblzone-211-213.nblnetworks.fi ([83.145.211.213]:56981 "EHLO hillosipuli.retiisi.org.uk" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S932435Ab3AYSDf (ORCPT ); Fri, 25 Jan 2013 13:03:35 -0500 Received: from salottisipuli.retiisi.org.uk (salottisipuli.retiisi.org.uk [IPv6:2001:1bc8:102:6d9a::83:2]) by hillosipuli.retiisi.org.uk (Postfix) with ESMTP id 908A6602A2; Fri, 25 Jan 2013 20:03:30 +0200 (EET) Received: by salottisipuli.retiisi.org.uk (Postfix, from userid 1000) id 1CBCE20B4A; Fri, 25 Jan 2013 20:03:29 +0200 (EET) From: Sakari Ailus To: linux-media@vger.kernel.org Cc: k.debski@samsung.com, laurent.pinchart@ideasonboard.com, hverkuil@xs4all.nl Subject: [PATCH 1/1] v4l: Document timestamp behaviour to correspond to reality Date: Fri, 25 Jan 2013 20:03:29 +0200 Message-Id: <1359137009-23921-1-git-send-email-sakari.ailus@iki.fi> X-Mailer: git-send-email 1.7.2.5 Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org Document that monotonic timestamps are taken after the corresponding frame has been received, not when the reception has begun. This corresponds to the reality of current drivers: the timestamp is naturally taken when the hardware triggers an interrupt to tell the driver to handle the received frame. Signed-off-by: Sakari Ailus --- Documentation/DocBook/media/v4l/io.xml | 27 ++++++++++++++------------- 1 files changed, 14 insertions(+), 13 deletions(-) diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 2c4646d..3b8bf61 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -654,19 +654,20 @@ plane, are stored in struct v4l2_plane instead. In that case, struct v4l2_buffer contains an array of plane structures. - Nominally timestamps refer to the first data byte transmitted. -In practice however the wide range of hardware covered by the V4L2 API -limits timestamp accuracy. Often an interrupt routine will -sample the system clock shortly after the field or frame was stored -completely in memory. So applications must expect a constant -difference up to one field or frame period plus a small (few scan -lines) random error. The delay and error can be much -larger due to compression or transmission over an external bus when -the frames are not properly stamped by the sender. This is frequently -the case with USB cameras. Here timestamps refer to the instant the -field or frame was received by the driver, not the capture time. These -devices identify by not enumerating any video standards, see . + On timestamp types that are sampled from the system clock +(V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC) it is guaranteed that the timestamp is +taken after the complete frame has been received. For other kinds of +timestamps this may vary depending on the driver. In practice however the +wide range of hardware covered by the V4L2 API limits timestamp accuracy. +Often an interrupt routine will sample the system clock shortly after the +field or frame was stored completely in memory. So applications must expect +a constant difference up to one field or frame period plus a small (few scan +lines) random error. The delay and error can be much larger due to +compression or transmission over an external bus when the frames are not +properly stamped by the sender. This is frequently the case with USB +cameras. Here timestamps refer to the instant the field or frame was +received by the driver, not the capture time. These devices identify by not +enumerating any video standards, see . Similar limitations apply to output timestamps. Typically the video hardware locks to a clock controlling the video timing, the