yading@10: /*
yading@10:  * DV input/output over IEEE 1394 on OHCI chips
yading@10:  *   Copyright (C)2001 Daniel Maas <dmaas@dcine.com>
yading@10:  *     receive, proc_fs by Dan Dennedy <dan@dennedy.org>
yading@10:  *
yading@10:  * based on:
yading@10:  *   video1394.h - driver for OHCI 1394 boards
yading@10:  *   Copyright (C)1999,2000 Sebastien Rougeaux <sebastien.rougeaux@anu.edu.au>
yading@10:  *                          Peter Schlaile <udbz@rz.uni-karlsruhe.de>
yading@10:  *
yading@10:  * This file is part of FFmpeg.
yading@10:  *
yading@10:  * FFmpeg is free software; you can redistribute it and/or
yading@10:  * modify it under the terms of the GNU Lesser General Public
yading@10:  * License as published by the Free Software Foundation; either
yading@10:  * version 2.1 of the License, or (at your option) any later version.
yading@10:  *
yading@10:  * FFmpeg is distributed in the hope that it will be useful,
yading@10:  * but WITHOUT ANY WARRANTY; without even the implied warranty of
yading@10:  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
yading@10:  * Lesser General Public License for more details.
yading@10:  *
yading@10:  * You should have received a copy of the GNU Lesser General Public
yading@10:  * License along with FFmpeg; if not, write to the Free Software
yading@10:  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
yading@10:  */
yading@10: 
yading@10: #ifndef AVDEVICE_DV1394_H
yading@10: #define AVDEVICE_DV1394_H
yading@10: 
yading@10: #define DV1394_DEFAULT_CHANNEL 63
yading@10: #define DV1394_DEFAULT_CARD    0
yading@10: #define DV1394_RING_FRAMES     20
yading@10: 
yading@10: #define DV1394_WIDTH  720
yading@10: #define DV1394_NTSC_HEIGHT 480
yading@10: #define DV1394_PAL_HEIGHT 576
yading@10: 
yading@10: /* This is the public user-space interface. Try not to break it. */
yading@10: 
yading@10: #define DV1394_API_VERSION 0x20011127
yading@10: 
yading@10: /* ********************
yading@10:    **                **
yading@10:    **   DV1394 API   **
yading@10:    **                **
yading@10:    ********************
yading@10: 
yading@10:    There are two methods of operating the DV1394 DV output device.
yading@10: 
yading@10:    1)
yading@10: 
yading@10:    The simplest is an interface based on write(): simply write
yading@10:    full DV frames of data to the device, and they will be transmitted
yading@10:    as quickly as possible. The FD may be set for non-blocking I/O,
yading@10:    in which case you can use select() or poll() to wait for output
yading@10:    buffer space.
yading@10: 
yading@10:    To set the DV output parameters (e.g. whether you want NTSC or PAL
yading@10:    video), use the DV1394_INIT ioctl, passing in the parameters you
yading@10:    want in a struct dv1394_init.
yading@10: 
yading@10:    Example 1:
yading@10:          To play a raw .DV file:   cat foo.DV > /dev/dv1394
yading@10:          (cat will use write() internally)
yading@10: 
yading@10:    Example 2:
yading@10:            static struct dv1394_init init = {
yading@10:               0x63,        (broadcast channel)
yading@10:               4,           (four-frame ringbuffer)
yading@10:               DV1394_NTSC, (send NTSC video)
yading@10:               0, 0         (default empty packet rate)
yading@10:            }
yading@10: 
yading@10:            ioctl(fd, DV1394_INIT, &init);
yading@10: 
yading@10:            while(1) {
yading@10:                   read( <a raw DV file>, buf, DV1394_NTSC_FRAME_SIZE );
yading@10:                   write( <the dv1394 FD>, buf, DV1394_NTSC_FRAME_SIZE );
yading@10:            }
yading@10: 
yading@10:    2)
yading@10: 
yading@10:    For more control over buffering, and to avoid unnecessary copies
yading@10:    of the DV data, you can use the more sophisticated the mmap() interface.
yading@10:    First, call the DV1394_INIT ioctl to specify your parameters,
yading@10:    including the number of frames in the ringbuffer. Then, calling mmap()
yading@10:    on the dv1394 device will give you direct access to the ringbuffer
yading@10:    from which the DV card reads your frame data.
yading@10: 
yading@10:    The ringbuffer is simply one large, contiguous region of memory
yading@10:    containing two or more frames of packed DV data. Each frame of DV data
yading@10:    is 120000 bytes (NTSC) or 144000 bytes (PAL).
yading@10: 
yading@10:    Fill one or more frames in the ringbuffer, then use the DV1394_SUBMIT_FRAMES
yading@10:    ioctl to begin I/O. You can use either the DV1394_WAIT_FRAMES ioctl
yading@10:    or select()/poll() to wait until the frames are transmitted. Next, you'll
yading@10:    need to call the DV1394_GET_STATUS ioctl to determine which ringbuffer
yading@10:    frames are clear (ready to be filled with new DV data). Finally, use
yading@10:    DV1394_SUBMIT_FRAMES again to send the new data to the DV output.
yading@10: 
yading@10: 
yading@10:    Example: here is what a four-frame ringbuffer might look like
yading@10:             during DV transmission:
yading@10: 
yading@10: 
yading@10:          frame 0   frame 1   frame 2   frame 3
yading@10: 
yading@10:         *--------------------------------------*
yading@10:         | CLEAR   | DV data | DV data | CLEAR  |
yading@10:         *--------------------------------------*
yading@10:                    <ACTIVE>
yading@10: 
yading@10:         transmission goes in this direction --->>>
yading@10: 
yading@10: 
yading@10:    The DV hardware is currently transmitting the data in frame 1.
yading@10:    Once frame 1 is finished, it will automatically transmit frame 2.
yading@10:    (if frame 2 finishes before frame 3 is submitted, the device
yading@10:    will continue to transmit frame 2, and will increase the dropped_frames
yading@10:    counter each time it repeats the transmission).
yading@10: 
yading@10: 
yading@10:    If you called DV1394_GET_STATUS at this instant, you would
yading@10:    receive the following values:
yading@10: 
yading@10:                   n_frames          = 4
yading@10:                   active_frame      = 1
yading@10:                   first_clear_frame = 3
yading@10:                   n_clear_frames    = 2
yading@10: 
yading@10:    At this point, you should write new DV data into frame 3 and optionally
yading@10:    frame 0. Then call DV1394_SUBMIT_FRAMES to inform the device that
yading@10:    it may transmit the new frames.
yading@10: 
yading@10:    ERROR HANDLING
yading@10: 
yading@10:    An error (buffer underflow/overflow or a break in the DV stream due
yading@10:    to a 1394 bus reset) can be detected by checking the dropped_frames
yading@10:    field of struct dv1394_status (obtained through the
yading@10:    DV1394_GET_STATUS ioctl).
yading@10: 
yading@10:    The best way to recover from such an error is to re-initialize
yading@10:    dv1394, either by using the DV1394_INIT ioctl call, or closing the
yading@10:    file descriptor and opening it again. (note that you must unmap all
yading@10:    ringbuffer mappings when closing the file descriptor, or else
yading@10:    dv1394 will still be considered 'in use').
yading@10: 
yading@10:    MAIN LOOP
yading@10: 
yading@10:    For maximum efficiency and robustness against bus errors, you are
yading@10:    advised to model the main loop of your application after the
yading@10:    following pseudo-code example:
yading@10: 
yading@10:    (checks of system call return values omitted for brevity; always
yading@10:    check return values in your code!)
yading@10: 
yading@10:    while( frames left ) {
yading@10: 
yading@10:     struct pollfd *pfd = ...;
yading@10: 
yading@10:     pfd->fd = dv1394_fd;
yading@10:     pfd->revents = 0;
yading@10:     pfd->events = POLLOUT | POLLIN; (OUT for transmit, IN for receive)
yading@10: 
yading@10:     (add other sources of I/O here)
yading@10: 
yading@10:     poll(pfd, 1, -1); (or select(); add a timeout if you want)
yading@10: 
yading@10:     if(pfd->revents) {
yading@10:          struct dv1394_status status;
yading@10: 
yading@10:          ioctl(dv1394_fd, DV1394_GET_STATUS, &status);
yading@10: 
yading@10:          if(status.dropped_frames > 0) {
yading@10:               reset_dv1394();
yading@10:          } else {
yading@10:               int i;
yading@10:               for (i = 0; i < status.n_clear_frames; i++) {
yading@10:                   copy_DV_frame();
yading@10:               }
yading@10:          }
yading@10:     }
yading@10:    }
yading@10: 
yading@10:    where copy_DV_frame() reads or writes on the dv1394 file descriptor
yading@10:    (read/write mode) or copies data to/from the mmap ringbuffer and
yading@10:    then calls ioctl(DV1394_SUBMIT_FRAMES) to notify dv1394 that new
yading@10:    frames are available (mmap mode).
yading@10: 
yading@10:    reset_dv1394() is called in the event of a buffer
yading@10:    underflow/overflow or a halt in the DV stream (e.g. due to a 1394
yading@10:    bus reset). To guarantee recovery from the error, this function
yading@10:    should close the dv1394 file descriptor (and munmap() all
yading@10:    ringbuffer mappings, if you are using them), then re-open the
yading@10:    dv1394 device (and re-map the ringbuffer).
yading@10: 
yading@10: */
yading@10: 
yading@10: 
yading@10: /* maximum number of frames in the ringbuffer */
yading@10: #define DV1394_MAX_FRAMES 32
yading@10: 
yading@10: /* number of *full* isochronous packets per DV frame */
yading@10: #define DV1394_NTSC_PACKETS_PER_FRAME 250
yading@10: #define DV1394_PAL_PACKETS_PER_FRAME  300
yading@10: 
yading@10: /* size of one frame's worth of DV data, in bytes */
yading@10: #define DV1394_NTSC_FRAME_SIZE (480 * DV1394_NTSC_PACKETS_PER_FRAME)
yading@10: #define DV1394_PAL_FRAME_SIZE  (480 * DV1394_PAL_PACKETS_PER_FRAME)
yading@10: 
yading@10: 
yading@10: /* ioctl() commands */
yading@10: 
yading@10: enum {
yading@10:         /* I don't like using 0 as a valid ioctl() */
yading@10:         DV1394_INVALID = 0,
yading@10: 
yading@10: 
yading@10:         /* get the driver ready to transmit video.
yading@10:            pass a struct dv1394_init* as the parameter (see below),
yading@10:            or NULL to get default parameters */
yading@10:         DV1394_INIT,
yading@10: 
yading@10: 
yading@10:         /* stop transmitting video and free the ringbuffer */
yading@10:         DV1394_SHUTDOWN,
yading@10: 
yading@10: 
yading@10:         /* submit N new frames to be transmitted, where
yading@10:            the index of the first new frame is first_clear_buffer,
yading@10:            and the index of the last new frame is
yading@10:            (first_clear_buffer + N) % n_frames */
yading@10:         DV1394_SUBMIT_FRAMES,
yading@10: 
yading@10: 
yading@10:         /* block until N buffers are clear (pass N as the parameter)
yading@10:            Because we re-transmit the last frame on underrun, there
yading@10:            will at most be n_frames - 1 clear frames at any time */
yading@10:         DV1394_WAIT_FRAMES,
yading@10: 
yading@10:         /* capture new frames that have been received, where
yading@10:            the index of the first new frame is first_clear_buffer,
yading@10:            and the index of the last new frame is
yading@10:            (first_clear_buffer + N) % n_frames */
yading@10:         DV1394_RECEIVE_FRAMES,
yading@10: 
yading@10: 
yading@10:         DV1394_START_RECEIVE,
yading@10: 
yading@10: 
yading@10:         /* pass a struct dv1394_status* as the parameter (see below) */
yading@10:         DV1394_GET_STATUS,
yading@10: };
yading@10: 
yading@10: 
yading@10: 
yading@10: enum pal_or_ntsc {
yading@10:         DV1394_NTSC = 0,
yading@10:         DV1394_PAL
yading@10: };
yading@10: 
yading@10: 
yading@10: 
yading@10: 
yading@10: /* this is the argument to DV1394_INIT */
yading@10: struct dv1394_init {
yading@10:         /* DV1394_API_VERSION */
yading@10:         unsigned int api_version;
yading@10: 
yading@10:         /* isochronous transmission channel to use */
yading@10:         unsigned int channel;
yading@10: 
yading@10:         /* number of frames in the ringbuffer. Must be at least 2
yading@10:            and at most DV1394_MAX_FRAMES. */
yading@10:         unsigned int n_frames;
yading@10: 
yading@10:         /* send/receive PAL or NTSC video format */
yading@10:         enum pal_or_ntsc format;
yading@10: 
yading@10:         /* the following are used only for transmission */
yading@10: 
yading@10:         /* set these to zero unless you want a
yading@10:            non-default empty packet rate (see below) */
yading@10:         unsigned long cip_n;
yading@10:         unsigned long cip_d;
yading@10: 
yading@10:         /* set this to zero unless you want a
yading@10:            non-default SYT cycle offset (default = 3 cycles) */
yading@10:         unsigned int syt_offset;
yading@10: };
yading@10: 
yading@10: /* NOTE: you may only allocate the DV frame ringbuffer once each time
yading@10:    you open the dv1394 device. DV1394_INIT will fail if you call it a
yading@10:    second time with different 'n_frames' or 'format' arguments (which
yading@10:    would imply a different size for the ringbuffer). If you need a
yading@10:    different buffer size, simply close and re-open the device, then
yading@10:    initialize it with your new settings. */
yading@10: 
yading@10: /* Q: What are cip_n and cip_d? */
yading@10: 
yading@10: /*
yading@10:   A: DV video streams do not utilize 100% of the potential bandwidth offered
yading@10:   by IEEE 1394 (FireWire). To achieve the correct rate of data transmission,
yading@10:   DV devices must periodically insert empty packets into the 1394 data stream.
yading@10:   Typically there is one empty packet per 14-16 data-carrying packets.
yading@10: 
yading@10:   Some DV devices will accept a wide range of empty packet rates, while others
yading@10:   require a precise rate. If the dv1394 driver produces empty packets at
yading@10:   a rate that your device does not accept, you may see ugly patterns on the
yading@10:   DV output, or even no output at all.
yading@10: 
yading@10:   The default empty packet insertion rate seems to work for many people; if
yading@10:   your DV output is stable, you can simply ignore this discussion. However,
yading@10:   we have exposed the empty packet rate as a parameter to support devices that
yading@10:   do not work with the default rate.
yading@10: 
yading@10:   The decision to insert an empty packet is made with a numerator/denominator
yading@10:   algorithm. Empty packets are produced at an average rate of CIP_N / CIP_D.
yading@10:   You can alter the empty packet rate by passing non-zero values for cip_n
yading@10:   and cip_d to the INIT ioctl.
yading@10: 
yading@10:  */
yading@10: 
yading@10: 
yading@10: 
yading@10: struct dv1394_status {
yading@10:         /* this embedded init struct returns the current dv1394
yading@10:            parameters in use */
yading@10:         struct dv1394_init init;
yading@10: 
yading@10:         /* the ringbuffer frame that is currently being
yading@10:            displayed. (-1 if the device is not transmitting anything) */
yading@10:         int active_frame;
yading@10: 
yading@10:         /* index of the first buffer (ahead of active_frame) that
yading@10:            is ready to be filled with data */
yading@10:         unsigned int first_clear_frame;
yading@10: 
yading@10:         /* how many buffers, including first_clear_buffer, are
yading@10:            ready to be filled with data */
yading@10:         unsigned int n_clear_frames;
yading@10: 
yading@10:         /* how many times the DV stream has underflowed, overflowed,
yading@10:            or otherwise encountered an error, since the previous call
yading@10:            to DV1394_GET_STATUS */
yading@10:         unsigned int dropped_frames;
yading@10: 
yading@10:         /* N.B. The dropped_frames counter is only a lower bound on the actual
yading@10:            number of dropped frames, with the special case that if dropped_frames
yading@10:            is zero, then it is guaranteed that NO frames have been dropped
yading@10:            since the last call to DV1394_GET_STATUS.
yading@10:         */
yading@10: };
yading@10: 
yading@10: 
yading@10: #endif /* AVDEVICE_DV1394_H */