From dd96608369be9d3cfc604eaa3a53a2d38f1cb415 Mon Sep 17 00:00:00 2001 From: Sakari Ailus Date: Sat, 27 Mar 2010 10:58:24 -0300 Subject: V4L/DVB: V4L: Events: Add documentation Add documentation on how to use V4L2 events, both for V4L2 drivers and for V4L2 applications. Signed-off-by: Sakari Ailus Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/media-entities.tmpl | 9 ++ Documentation/DocBook/v4l/dev-event.xml | 31 ++++++ Documentation/DocBook/v4l/v4l2.xml | 3 + Documentation/DocBook/v4l/vidioc-dqevent.xml | 124 +++++++++++++++++++++ .../DocBook/v4l/vidioc-subscribe-event.xml | 104 +++++++++++++++++ 5 files changed, 271 insertions(+) create mode 100644 Documentation/DocBook/v4l/dev-event.xml create mode 100644 Documentation/DocBook/v4l/vidioc-dqevent.xml create mode 100644 Documentation/DocBook/v4l/vidioc-subscribe-event.xml (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/media-entities.tmpl b/Documentation/DocBook/media-entities.tmpl index c725cb852c5..770be3c3ba7 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 00000000000..be5a98fb4fa --- /dev/null +++ b/Documentation/DocBook/v4l/dev-event.xml @@ -0,0 +1,31 @@ + 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 in 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 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 is 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 060105af49e..9737243377a 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 00000000000..eb45c1695d8 --- /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 00000000000..71ab88cb76b --- /dev/null +++ b/Documentation/DocBook/v4l/vidioc-subscribe-event.xml @@ -0,0 +1,104 @@ + + + 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 and applications + 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 + Base event number for driver-private events. + + + +
+ + + + -- cgit v1.2.3-18-g5258