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 */