From patchwork Tue Jun 28 11:26:05 2011 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Hans Verkuil X-Patchwork-Id: 924302 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by demeter2.kernel.org (8.14.4/8.14.4) with ESMTP id p5SBSeft003532 for ; Tue, 28 Jun 2011 11:29:23 GMT Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1756686Ab1F1L16 (ORCPT ); Tue, 28 Jun 2011 07:27:58 -0400 Received: from smtp-vbr10.xs4all.nl ([194.109.24.30]:3056 "EHLO smtp-vbr10.xs4all.nl" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1757322Ab1F1L0V (ORCPT ); Tue, 28 Jun 2011 07:26:21 -0400 Received: from tschai (64-103-25-233.cisco.com [64.103.25.233]) (authenticated bits=0) by smtp-vbr10.xs4all.nl (8.13.8/8.13.8) with ESMTP id p5SBQ9kB032542 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Tue, 28 Jun 2011 13:26:18 +0200 (CEST) (envelope-from hverkuil@xs4all.nl) From: Hans Verkuil To: linux-media@vger.kernel.org Cc: Hans Verkuil Subject: [RFCv2 PATCH 13/13] v4l2-event.h: add overview documentation to the header. Date: Tue, 28 Jun 2011 13:26:05 +0200 Message-Id: <671351808887ca28ad4b844b343fefc5fa360641.1309260043.git.hans.verkuil@cisco.com> X-Mailer: git-send-email 1.7.1 In-Reply-To: <1309260365-4831-1-git-send-email-hverkuil@xs4all.nl> References: <1309260365-4831-1-git-send-email-hverkuil@xs4all.nl> In-Reply-To: <3d92b242dcf5e7766d128d6c1f05c0bd837a2633.1309260043.git.hans.verkuil@cisco.com> References: <3d92b242dcf5e7766d128d6c1f05c0bd837a2633.1309260043.git.hans.verkuil@cisco.com> X-Virus-Scanned: by XS4ALL Virus Scanner 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.6 (demeter2.kernel.org [140.211.167.43]); Tue, 28 Jun 2011 11:29:24 +0000 (UTC) From: Hans Verkuil It's getting confusing who is linking to what, so add an overview at the start of the header. Signed-off-by: Hans Verkuil --- include/media/v4l2-event.h | 34 ++++++++++++++++++++++++++++++++++ 1 files changed, 34 insertions(+), 0 deletions(-) diff --git a/include/media/v4l2-event.h b/include/media/v4l2-event.h index 7abeb39..5f14e88 100644 --- a/include/media/v4l2-event.h +++ b/include/media/v4l2-event.h @@ -29,6 +29,40 @@ #include #include +/* + * Overview: + * + * Events are subscribed per-filehandle. An event specification consists of a + * type and is optionally associated with an object identified through the + * 'id' field. So an event is uniquely identified by the (type, id) tuple. + * + * The v4l2-fh struct has a list of subscribed events. The v4l2_subscribed_event + * struct is added to that list, one for every subscribed event. + * + * Each v4l2_subscribed_event struct ends with an array of v4l2_kevent structs. + * This array (ringbuffer, really) is used to store any events raised by the + * driver. The v4l2_kevent struct links into the 'available' list of the + * v4l2_fh struct so VIDIOC_DQEVENT will know which event to dequeue first. + * + * Finally, if the event subscription is associated with a particular object + * such as a V4L2 control, then that object needs to know about that as well + * so that an event can be raised by that object. So the 'node' field can + * be used to link the v4l2_subscribed_event struct into a list of that + * object. + * + * So to summarize: + * + * struct v4l2_fh has two lists: one of the subscribed events, and one of the + * pending events. + * + * struct v4l2_subscribed_event has a ringbuffer of raised (pending) events of + * that particular type. + * + * If struct v4l2_subscribed_event is associated with a specific object, then + * that object will have an internal list of struct v4l2_subscribed_event so + * it knows who subscribed an event to that object. + */ + struct v4l2_fh; struct v4l2_subscribed_event; struct video_device;