1About Linux "VBI proxy"
2-----------------------
3
4    With "video4linux" drivers only one application at a time can
5capture VBI data.  The 2nd generation "v4l2" API allows multiple clients
6to open a device, but still only one client may read from the device.  If
7for example the Nxtvepg daemon runs in the background users will not be
8able to start a Teletext application.  The VBI proxy was developed as a
9solution to this problem.
10
11    VBI can transport many independent data streams: VPS, WSS, Closed
12Caption and Teletext, within them PDC, XDS and custom data streams
13providing such services as Teletext, subtitles, caption, NexTView and
14other Electronic Programme Guides, channel identification, video
15recording triggers, information about the current program, wide screen
16signalling and more.  We want to share one VBI stream between for
17example an application opening the device to update the system clock,
18Teletext viewers, TV viewers displaying channel names, caption or
19subtitles, recording applications, a PVR watching channels for
20recording triggers, and an EPG daemon updating its database.
21
22    The proxy must assign higher priority to recording and lower
23priority to background applications.  It must coordinate channel changes
24between background "data harvesting" applications.  Such apps would
25register a channel request with the proxy together with a priority and
26expected time of use and the proxy will then grant those requests
27according to priority and previous grants in a round-robin way.
28
29    How does it work?  The VBI proxy is implemented as a daemon "zvbid",
30which usually will be started during system boot.  The daemon remains
31dormant until the first proxy client connects through a socket, then
32opens the VBI device and starts capturing and decoding the services
33requested by the client, e.g. Teletext.  It will not pass raw but
34sliced VBI data, reducing the required bandwidth and saving repeated
35decoding of data needed by multiple clients.
36
37    One drawback of this solution is that clients must be adapted, i.e.
38instead of opening the VBI device as usual, clients have to connect to
39the daemon (but if the daemon is not running they should fall back to
40using the device directly).  For most applications already using libzvbi
41the change is minimal:  A single function call is enough to create a
42proxy client and connect to the server, another to start capturing.  The
43API to capture and decode services is identical for v4l2, v4l, bktr,
44dvb and proxy devices.  Legacy applications can often be ported simply
45by replacing open and read system calls with their libzvbi equivalents.
46
47    As a work-around for applications which cannot be adapted, a wrapper
48"zvbi-chains" is available which intercepts access to the VBI device and
49redirects it to the proxy.  In this case however only raw VBI data can be
50forwarded, resulting in a significantly higher CPU load.
51
52    Hopefully the solution is elegant enough to convince the authors to
53invest the necessary effort to switch to libzvbi (or at least implement
54the proxy protocol) in subsequent releases of their software.
55
56
57Current status
58--------------
59
60    The proxy may still need improvement, see below for a detailed list
61of open points, but at least the basic service works well, and the API
62will remain backwards compatible.  If you want to try it out, libzvbi
63is available from http://zapping.sourceforge.net/.  Some applications
64using the proxy:
65
66- The libzvbi test directory contains a small program "proxy-test" which
67  can read and dump Teletext and VPS data from the proxy.  Try -help for
68  a list of options.
69
70- The Nxtevpg EPG viewer (http://nxtvepg.sourceforge.net/) uses the proxy
71  when compiled with -DUSE_LIBZVBI in the Makefile.
72
73- The Zapping 0.8 TV viewer and Teletext browser
74  (http://zapping.sourceforge.net) has basic proxy support and will use
75  the proxy automatically when installed and running.
76
77- The AleVT 1.6.1 Teletext browser and Xawdecode TV viewer
78  (http://xawdecode.sourceforge.net/download/) use the proxy with the
79  following patches:
80  http://nxtvepg.sourceforge.net/tmp/alevt-1.6.1-libzvbi.diff
81  http://nxtvepg.sourceforge.net/tmp/alevtd-3.91-vbiproxy.diff
82
83  AleVT is also known to work unmodified with zvbi-chains.
84
85With proxy you can run these applications (or multiple instances of
86them, perhaps only pure VBI apps - YMMV) in parallel.
87
88
89TODO list
90---------
91
92    This is an unordered list of open points (unimplemented or yet
93undecided) regarding the proxy.  Any comments or help appreciated.
94
95- Optimize raw buffer forward, possibly based on shared memory to avoid
96  copying -> requires user-space DMA in io-v4l2k (i.e. streaming into
97  buffers allocated by the user)
98
99- Device permissions are implemented by copying group id and access
100  mask of the device.  This is not portable however according to man
101  socket(7).  Possibly a sub-directory should be used and permissions
102  set on the directory.  Disadvantage: other people cannot clean up
103  (same for socket file if sticky bit is set).  Or an X11 way a key
104  file could be used.
105
106- Save errno upon device errors deep down, e.g. in proxy-msg.c into io
107  struct to make sure it's not overwritten higher up in the return path
108
109- Log daemon's errors and warnings in syslog (esp. protocol violations
110  in clients, such as not returning token on request)
111
112- Channel change handling and scheduling not fully implemented yet;
113  needs more testing
114
115- Option: allow user to override or fine-tune channel priority requests
116  (on side of daemon, based on client-names)
117
118- Inform clients about video norm changes: e.g. sampling rate may change
119  (only relevant for raw data though), frame rate changes -> must be
120  considered when evaluating time stamps to detect dropped frames;
121  number of VBI lines may change, client may want to change service IDs.
122  Probably only for clients which explicitly enable this; others could
123  simply be starved.
124
125- io-bktr.c not supported at all yet for new features.  Note bktr is
126  weird(tm), for example one cannot capture VBI without video.  The
127  proxy is not officially supported on FreeBSD.
128
129- Possibly add a generic capture client config function to:
130  + set video device path (v4l1 for channel changes & norm query)
131  + sequence counter instead of time stamp in vbi_capture_buffer (v4l1 bttv)
132    Alternatively libzvbi 0.3 may provide sampling time and stream time,
133    the latter derived from sequence counters for analog devices.
134  + query time between frames; query timestamp from driver or after read()
135  + dynamically change buffer count (v4l2 only)
136  + optionally use read even if streaming is available
137
138- Possible v4l2 API extensions:
139  + channel change event notification
140  + CGUNIT to check if two nodes refer to the same piece of hardware
141  + EIO from DQBUF: timeout, buffer must be requeued
142