version update
[goodguy/cinelerra.git] / cinelerra-5.1 / cinelerra / dv1394.h
1
2 /*
3  * CINELERRA
4  * Copyright (C) 2008 Adam Williams <broadcast at earthling dot net>
5  * Copyright (C) 2003-2016 Cinelerra CV contributors
6  *
7  * This program is free software; you can redistribute it and/or modify
8  * it under the terms of the GNU General Public License as published by
9  * the Free Software Foundation; either version 2 of the License, or
10  * (at your option) any later version.
11  *
12  * This program is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program; if not, write to the Free Software
19  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
20  *
21  */
22
23 /*
24  * dv1394.h - DV input/output over IEEE 1394 on OHCI chips
25  *   Copyright (C)2001 Daniel Maas <dmaas@dcine.com>
26  *     receive, proc_fs by Dan Dennedy <dan@dennedy.org>
27  *
28  * based on:
29  *   video1394.h - driver for OHCI 1394 boards
30  *   Copyright (C)1999,2000 Sebastien Rougeaux <sebastien.rougeaux@anu.edu.au>
31  *                          Peter Schlaile <udbz@rz.uni-karlsruhe.de>
32  *
33  * This program is free software; you can redistribute it and/or modify
34  * it under the terms of the GNU General Public License as published by
35  * the Free Software Foundation; either version 2 of the License, or
36  * (at your option) any later version.
37  *
38  * This program is distributed in the hope that it will be useful,
39  * but WITHOUT ANY WARRANTY; without even the implied warranty of
40  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
41  * GNU General Public License for more details.
42  *
43  * You should have received a copy of the GNU General Public License
44  * along with this program; if not, write to the Free Software Foundation,
45  * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
46  */
47
48 #ifndef _DV_1394_H
49 #define _DV_1394_H
50
51 /* This is the public user-space interface. Try not to break it. */
52
53 #define DV1394_API_VERSION 0x20011127
54
55 /* ********************
56    **                **
57    **   DV1394 API   **
58    **                **
59    ********************
60
61    There are two methods of operating the DV1394 DV output device.
62
63    1)
64
65    The simplest is an interface based on write(): simply write
66    full DV frames of data to the device, and they will be transmitted
67    as quickly as possible. The FD may be set for non-blocking I/O,
68    in which case you can use select() or poll() to wait for output
69    buffer space.
70
71    To set the DV output parameters (e.g. whether you want NTSC or PAL
72    video), use the DV1394_INIT ioctl, passing in the parameters you
73    want in a struct dv1394_init.
74
75    Example 1:
76          To play a raw .DV file:   cat foo.DV > /dev/dv1394
77          (cat will use write() internally)
78
79    Example 2:
80            static struct dv1394_init init = {
81               0x63,        (broadcast channel)
82               4,           (four-frame ringbuffer)
83               DV1394_NTSC, (send NTSC video)
84               0, 0         (default empty packet rate)
85            }
86
87            ioctl(fd, DV1394_INIT, &init);
88
89            while(1) {
90                   read( <a raw DV file>, buf, DV1394_NTSC_FRAME_SIZE );
91                   write( <the dv1394 FD>, buf, DV1394_NTSC_FRAME_SIZE );
92            }
93
94    2)
95
96    For more control over buffering, and to avoid unnecessary copies
97    of the DV data, you can use the more sophisticated the mmap() interface.
98    First, call the DV1394_INIT ioctl to specify your parameters,
99    including the number of frames in the ringbuffer. Then, calling mmap()
100    on the dv1394 device will give you direct access to the ringbuffer
101    from which the DV card reads your frame data.
102
103    The ringbuffer is simply one large, contiguous region of memory
104    containing two or more frames of packed DV data. Each frame of DV data
105    is 120000 bytes (NTSC) or 144000 bytes (PAL).
106
107    Fill one or more frames in the ringbuffer, then use the DV1394_SUBMIT_FRAMES
108    ioctl to begin I/O. You can use either the DV1394_WAIT_FRAMES ioctl
109    or select()/poll() to wait until the frames are transmitted. Next, you'll
110    need to call the DV1394_GET_STATUS ioctl to determine which ringbuffer
111    frames are clear (ready to be filled with new DV data). Finally, use
112    DV1394_SUBMIT_FRAMES again to send the new data to the DV output.
113
114
115    Example: here is what a four-frame ringbuffer might look like
116             during DV transmission:
117
118
119          frame 0   frame 1   frame 2   frame 3
120
121         *--------------------------------------*
122         | CLEAR   | DV data | DV data | CLEAR  |
123         *--------------------------------------*
124                    <ACTIVE>
125
126         transmission goes in this direction --->>>
127
128
129    The DV hardware is currently transmitting the data in frame 1.
130    Once frame 1 is finished, it will automatically transmit frame 2.
131    (if frame 2 finishes before frame 3 is submitted, the device
132    will continue to transmit frame 2, and will increase the dropped_frames
133    counter each time it repeats the transmission).
134
135
136    If you called DV1394_GET_STATUS at this instant, you would
137    receive the following values:
138
139           n_frames          = 4
140           active_frame      = 1
141           first_clear_frame = 3
142           n_clear_frames    = 2
143
144    At this point, you should write new DV data into frame 3 and optionally
145    frame 0. Then call DV1394_SUBMIT_FRAMES to inform the device that
146    it may transmit the new frames.
147
148    ERROR HANDLING
149
150    An error (buffer underflow/overflow or a break in the DV stream due
151    to a 1394 bus reset) can be detected by checking the dropped_frames
152    field of struct dv1394_status (obtained through the
153    DV1394_GET_STATUS ioctl).
154
155    The best way to recover from such an error is to re-initialize
156    dv1394, either by using the DV1394_INIT ioctl call, or closing the
157    file descriptor and opening it again. (note that you must unmap all
158    ringbuffer mappings when closing the file descriptor, or else
159    dv1394 will still be considered 'in use').
160
161    MAIN LOOP
162
163    For maximum efficiency and robustness against bus errors, you are
164    advised to model the main loop of your application after the
165    following pseudo-code example:
166
167    (checks of system call return values omitted for brevity; always
168    check return values in your code!)
169
170    while ( frames left ) {
171
172     struct pollfd *pfd = ...;
173
174     pfd->fd = dv1394_fd;
175     pfd->revents = 0;
176     pfd->events = POLLOUT | POLLIN; (OUT for transmit, IN for receive)
177
178     (add other sources of I/O here)
179
180     poll(pfd, 1, -1); (or select(); add a timeout if you want)
181
182     if (pfd->revents) {
183          struct dv1394_status status;
184
185          ioctl(dv1394_fd, DV1394_GET_STATUS, &status);
186
187          if (status.dropped_frames > 0) {
188               reset_dv1394();
189          } else {
190               for (int i = 0; i < status.n_clear_frames; i++) {
191                   copy_DV_frame();
192               }
193          }
194     }
195    }
196
197    where copy_DV_frame() reads or writes on the dv1394 file descriptor
198    (read/write mode) or copies data to/from the mmap ringbuffer and
199    then calls ioctl(DV1394_SUBMIT_FRAMES) to notify dv1394 that new
200    frames are availble (mmap mode).
201
202    reset_dv1394() is called in the event of a buffer
203    underflow/overflow or a halt in the DV stream (e.g. due to a 1394
204    bus reset). To guarantee recovery from the error, this function
205    should close the dv1394 file descriptor (and munmap() all
206    ringbuffer mappings, if you are using them), then re-open the
207    dv1394 device (and re-map the ringbuffer).
208
209 */
210
211
212 /* maximum number of frames in the ringbuffer */
213 #define DV1394_MAX_FRAMES 32
214
215 /* number of *full* isochronous packets per DV frame */
216 #define DV1394_NTSC_PACKETS_PER_FRAME 250
217 #define DV1394_PAL_PACKETS_PER_FRAME  300
218
219 /* size of one frame's worth of DV data, in bytes */
220 #define DV1394_NTSC_FRAME_SIZE (480 * DV1394_NTSC_PACKETS_PER_FRAME)
221 #define DV1394_PAL_FRAME_SIZE  (480 * DV1394_PAL_PACKETS_PER_FRAME)
222
223
224 /* ioctl() commands */
225 #include "ieee1394-ioctl.h"
226
227
228 enum pal_or_ntsc {
229         DV1394_NTSC = 0,
230         DV1394_PAL
231 };
232
233
234
235
236 /* this is the argument to DV1394_INIT */
237 struct dv1394_init {
238         /* DV1394_API_VERSION */
239         unsigned int api_version;
240
241         /* isochronous transmission channel to use */
242         unsigned int channel;
243
244         /* number of frames in the ringbuffer. Must be at least 2
245            and at most DV1394_MAX_FRAMES. */
246         unsigned int n_frames;
247
248         /* send/receive PAL or NTSC video format */
249         enum pal_or_ntsc format;
250
251         /* the following are used only for transmission */
252
253         /* set these to zero unless you want a
254            non-default empty packet rate (see below) */
255         unsigned long cip_n;
256         unsigned long cip_d;
257
258         /* set this to zero unless you want a
259            non-default SYT cycle offset (default = 3 cycles) */
260         unsigned int syt_offset;
261 };
262
263 /* NOTE: you may only allocate the DV frame ringbuffer once each time
264    you open the dv1394 device. DV1394_INIT will fail if you call it a
265    second time with different 'n_frames' or 'format' arguments (which
266    would imply a different size for the ringbuffer). If you need a
267    different buffer size, simply close and re-open the device, then
268    initialize it with your new settings. */
269
270 /* Q: What are cip_n and cip_d? */
271
272 /*
273   A: DV video streams do not utilize 100% of the potential bandwidth offered
274   by IEEE 1394 (FireWire). To achieve the correct rate of data transmission,
275   DV devices must periodically insert empty packets into the 1394 data stream.
276   Typically there is one empty packet per 14-16 data-carrying packets.
277
278   Some DV devices will accept a wide range of empty packet rates, while others
279   require a precise rate. If the dv1394 driver produces empty packets at
280   a rate that your device does not accept, you may see ugly patterns on the
281   DV output, or even no output at all.
282
283   The default empty packet insertion rate seems to work for many people; if
284   your DV output is stable, you can simply ignore this discussion. However,
285   we have exposed the empty packet rate as a parameter to support devices that
286   do not work with the default rate.
287
288   The decision to insert an empty packet is made with a numerator/denominator
289   algorithm. Empty packets are produced at an average rate of CIP_N / CIP_D.
290   You can alter the empty packet rate by passing non-zero values for cip_n
291   and cip_d to the INIT ioctl.
292
293  */
294
295
296
297 struct dv1394_status {
298         /* this embedded init struct returns the current dv1394
299            parameters in use */
300         struct dv1394_init init;
301
302         /* the ringbuffer frame that is currently being
303            displayed. (-1 if the device is not transmitting anything) */
304         int active_frame;
305
306         /* index of the first buffer (ahead of active_frame) that
307            is ready to be filled with data */
308         unsigned int first_clear_frame;
309
310         /* how many buffers, including first_clear_buffer, are
311            ready to be filled with data */
312         unsigned int n_clear_frames;
313
314         /* how many times the DV stream has underflowed, overflowed,
315            or otherwise encountered an error, since the previous call
316            to DV1394_GET_STATUS */
317         unsigned int dropped_frames;
318
319         /* N.B. The dropped_frames counter is only a lower bound on the actual
320            number of dropped frames, with the special case that if dropped_frames
321            is zero, then it is guaranteed that NO frames have been dropped
322            since the last call to DV1394_GET_STATUS.
323         */
324 };
325
326
327 #endif /* _DV_1394_H */