From patchwork Mon Feb 22 15:51:37 2010 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sakari Ailus X-Patchwork-Id: 81165 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 o1MFq4Rd022564 for ; Mon, 22 Feb 2010 15:52:04 GMT Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754120Ab0BVPvz (ORCPT ); Mon, 22 Feb 2010 10:51:55 -0500 Received: from smtp.nokia.com ([192.100.122.230]:38954 "EHLO mgw-mx03.nokia.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753807Ab0BVPvy (ORCPT ); Mon, 22 Feb 2010 10:51:54 -0500 Received: from esebh106.NOE.Nokia.com (esebh106.ntc.nokia.com [172.21.138.213]) by mgw-mx03.nokia.com (Switch-3.3.3/Switch-3.3.3) with ESMTP id o1MFpeXZ011679; Mon, 22 Feb 2010 17:51:51 +0200 Received: from esebh102.NOE.Nokia.com ([172.21.138.183]) by esebh106.NOE.Nokia.com with Microsoft SMTPSVC(6.0.3790.3959); Mon, 22 Feb 2010 17:51:41 +0200 Received: from mgw-sa01.ext.nokia.com ([147.243.1.47]) by esebh102.NOE.Nokia.com over TLS secured channel with Microsoft SMTPSVC(6.0.3790.3959); Mon, 22 Feb 2010 17:51:41 +0200 Received: from maxwell.research.nokia.com (maxwell.research.nokia.com [172.21.50.162]) by mgw-sa01.ext.nokia.com (Switch-3.3.3/Switch-3.3.3) with ESMTP id o1MFpdNf007177 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 22 Feb 2010 17:51:39 +0200 Received: from kaali.localdomain (kaali.localdomain [192.168.239.7]) by maxwell.research.nokia.com (Postfix) with ESMTPS id AB3737010E; Mon, 22 Feb 2010 17:51:37 +0200 (EET) Received: from sailus by kaali.localdomain with local (Exim 4.69) (envelope-from ) id 1NjaZN-0006iJ-KQ; Mon, 22 Feb 2010 17:51:37 +0200 From: Sakari Ailus To: linux-media@vger.kernel.org Cc: laurent.pinchart@nokia.com, hverkuil@xs4all.nl, david.cohen@nokia.com Subject: [PATCH 6/6] V4L: Events: Add documentation Date: Mon, 22 Feb 2010 17:51:37 +0200 Message-Id: <1266853897-25749-6-git-send-email-sakari.ailus@maxwell.research.nokia.com> X-Mailer: git-send-email 1.5.6.5 In-Reply-To: <1266853897-25749-5-git-send-email-sakari.ailus@maxwell.research.nokia.com> References: <4B82A7FB.50505@maxwell.research.nokia.com> <1266853897-25749-1-git-send-email-sakari.ailus@maxwell.research.nokia.com> <1266853897-25749-2-git-send-email-sakari.ailus@maxwell.research.nokia.com> <1266853897-25749-3-git-send-email-sakari.ailus@maxwell.research.nokia.com> <1266853897-25749-4-git-send-email-sakari.ailus@maxwell.research.nokia.com> <1266853897-25749-5-git-send-email-sakari.ailus@maxwell.research.nokia.com> X-OriginalArrivalTime: 22 Feb 2010 15:51:41.0136 (UTC) FILETIME=[ECD6E500:01CAB3D6] X-Nokia-AV: Clean 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]); Mon, 22 Feb 2010 15:52:04 +0000 (UTC) diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl index c725cb8..770be3c 100644 --- a/Documentation/DocBook/media-entities.tmpl +++ b/Documentation/DocBook/media-entities.tmpl @@ -17,6 +17,7 @@ VIDIOC_DBG_G_REGISTER"> VIDIOC_DBG_S_REGISTER"> VIDIOC_DQBUF"> +VIDIOC_DQEVENT"> VIDIOC_ENCODER_CMD"> VIDIOC_ENUMAUDIO"> VIDIOC_ENUMAUDOUT"> @@ -60,6 +61,7 @@ VIDIOC_REQBUFS"> VIDIOC_STREAMOFF"> VIDIOC_STREAMON"> +VIDIOC_SUBSCRIBE_EVENT"> VIDIOC_S_AUDIO"> VIDIOC_S_AUDOUT"> VIDIOC_S_CROP"> @@ -141,6 +143,8 @@ v4l2_enc_idx"> v4l2_enc_idx_entry"> v4l2_encoder_cmd"> +v4l2_event"> +v4l2_event_subscription"> v4l2_ext_control"> v4l2_ext_controls"> v4l2_fmtdesc"> @@ -200,6 +204,7 @@ + @@ -292,6 +297,8 @@ + + @@ -381,3 +388,5 @@ + + diff --git a/Documentation/DocBook/v4l/dev-event.xml b/Documentation/DocBook/v4l/dev-event.xml new file mode 100644 index 0000000..70a9895 --- /dev/null +++ b/Documentation/DocBook/v4l/dev-event.xml @@ -0,0 +1,34 @@ + Event Interface + + The V4L2 event interface provides means for user to get + immediately notified on certain conditions taking place on a device. + This might include start of frame or loss of signal events, for + example. + + + To receive events, the events the user is interested first + must be subscribed using the &VIDIOC-SUBSCRIBE-EVENT; ioctl. Once an + event is subscribed, the events of subscribed types are dequeueable + using the &VIDIOC-DQEVENT; ioctl. Events may be unsubscribed using + VIDIOC_UNSUBSCRIBE_EVENT ioctl. The special event type + V4L2_EVENT_ALL may be used to subscribe or unsubscribe all the + events the driver supports. + + The event subscriptions and event queues are specific to file + handles. Subscribing an event on one file handle does not affect + other file handles. + + + The information on dequeueable events are obtained by using + select or poll system calls on video devices. The V4L2 events use + POLLPRI events on poll system call and exceptions on select system + call. + + + diff --git a/Documentation/DocBook/v4l/v4l2.xml b/Documentation/DocBook/v4l/v4l2.xml index 060105a..9737243 100644 --- a/Documentation/DocBook/v4l/v4l2.xml +++ b/Documentation/DocBook/v4l/v4l2.xml @@ -401,6 +401,7 @@ and discussions on the V4L mailing list.
&sub-dev-teletext;
&sub-dev-radio;
&sub-dev-rds;
+
&sub-dev-event;
@@ -426,6 +427,7 @@ and discussions on the V4L mailing list. &sub-cropcap; &sub-dbg-g-chip-ident; &sub-dbg-g-register; + &sub-dqevent; &sub-encoder-cmd; &sub-enumaudio; &sub-enumaudioout; @@ -467,6 +469,7 @@ and discussions on the V4L mailing list. &sub-reqbufs; &sub-s-hw-freq-seek; &sub-streamon; + &sub-subscribe-event; &sub-mmap; &sub-munmap; diff --git a/Documentation/DocBook/v4l/vidioc-dqevent.xml b/Documentation/DocBook/v4l/vidioc-dqevent.xml new file mode 100644 index 0000000..eb45c16 --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-dqevent.xml @@ -0,0 +1,124 @@ + + + ioctl VIDIOC_DQEVENT + &manvol; + + + + VIDIOC_DQEVENT + Dequeue event + + + + + + int ioctl + int fd + int request + struct v4l2_event +*argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_DQEVENT + + + + argp + + + + + + + + + Description + + Dequeue an event from a video device. No input is required + for this ioctl. All the fields of the &v4l2-event; structure are + filled by the driver. The file handle will also receive exceptions + which the application may get by e.g. using the select system + call. + + + struct <structname>v4l2_event</structname> + + &cs-str; + + + __u32 + type + + Type of the event. + + + union + u + + + + + + __u8 + data[64] + Event data. Defined by the event type. The union + should be used to define easily accessible type for + events. + + + __u32 + pending + + Number of pending events excluding this one. + + + __u32 + sequence + + Event sequence number. The sequence number is + incremented for every subscribed event that takes place. + If sequence numbers are not contiguous it means that + events have been lost. + + + + struct timeval + timestamp + + Event timestamp. + + + __u32 + reserved[9] + + Reserved for future extensions. Drivers must set + the array to zero. + + + +
+ + + + diff --git a/Documentation/DocBook/v4l/vidioc-subscribe-event.xml b/Documentation/DocBook/v4l/vidioc-subscribe-event.xml new file mode 100644 index 0000000..4ee70bf --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-subscribe-event.xml @@ -0,0 +1,103 @@ + + + ioctl VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT + &manvol; + + + + VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT + Subscribe or unsubscribe event + + + + + + int ioctl + int fd + int request + struct v4l2_event_subscription +*argp + + + + + + Arguments + + + + fd + + &fd; + + + + request + + VIDIOC_SUBSCRIBE_EVENT, VIDIOC_UNSUBSCRIBE_EVENT + + + + argp + + + + + + + + + Description + + Subscribe or unsubscribe V4L2 event. Subscribed events are + dequeued by using the &VIDIOC-DQEVENT; ioctl. + + + struct <structname>v4l2_event_subscription</structname> + + &cs-str; + + + __u32 + type + Type of the event. + + + __u32 + reserved[7] + Reserved for future extensions. Drivers must set + the array to zero. + + + +
+ + + Event Types + + &cs-def; + + + V4L2_EVENT_ALL + 0 + All events. V4L2_EVENT_ALL is valid only for + VIDIOC_UNSUBSCRIBE_EVENT for unsubscribing all events at once. + + + + V4L2_EVENT_PRIVATE_START + 0x08000000 + + + +
+ + + + diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index bfaf0c5..221fd5c 100644 --- a/Documentation/video4linux/v4l2-framework.txt +++ b/Documentation/video4linux/v4l2-framework.txt @@ -732,3 +732,61 @@ Useful functions: The users of v4l2_fh know whether a driver uses v4l2_fh as its file->private_data pointer by testing the V4L2_FL_USES_V4L2_FH bit in video_device->flags. + +V4L2 events +----------- + +The V4L2 events provide a generic way to pass events to user space. +The driver must use v4l2_fh to be able to support V4L2 events. + +Useful functions: + +- v4l2_event_alloc() + + To use events, the driver must allocate events for the file handle. By + calling the function more than once, the driver may assure that at least n + events in total has been allocated. The function may not be called in + atomic context. + +- v4l2_event_queue() + + Queue events to video device. The driver's only responsibility is to fill + in the type and the data fields. The other fields will be filled in by + V4L2. + +- v4l2_event_subscribe() + + The video_device->ioctl_ops->vidioc_subscribe_event must check the driver + is able to produce events with specified event id. Then it calls + v4l2_event_subscribe() to subscribe the event. + +- v4l2_event_unsubscribe() + + vidioc_unsubscribe_event in struct v4l2_ioctl_ops. A driver may use + v4l2_event_unsubscribe() directly unless it wants to be involved in + unsubscription process. + + The special type V4L2_EVENT_ALL may be used to unsubscribe all events. The + drivers may want to handle this in a special way. + +- v4l2_event_pending() + + Returns the number of pending events. Useful when implementing poll. + +Drivers do not initialise events directly. The events are initialised +through v4l2_fh_init() if video_device->ioctl_ops->vidioc_subscribe_event is +non-NULL. This *MUST* be performed in the driver's +v4l2_file_operations->open() handler. + +Events are delivered to user space through the poll system call. The driver +can use v4l2_fh->events->wait wait_queue_head_t as the argument for +poll_wait(). + +There are standard and private events. New standard events must use the +smallest available event type. The drivers must allocate their events +starting from base (V4L2_EVENT_PRIVATE_START + n * 1024) while individual +events start from base + 1. + +An example on how the V4L2 events may be used can be found in the OMAP +3 ISP driver available at as of +writing this.