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