View source for Dv1394 - Linux-2.4

__TOC__


== Description ==

dv1394 implements IEC 61883-2 DV (Digital Video) reception and transmission.  dv1394 is frame-oriented and completely encapsulates the handling of DV over 1394.  Prior to dv1394, [[video1394]] has been used in conjunction with user space application code from Kino, libdv/dvconnect, and Cinelerra.  It proved to be too difficult to get reliable results across a range of devices using that approach, and thus dv1394 was implemented.

With dv1394 one can read and write dv1394 devices exactly as if they are raw DV files.  However, for more robust operation and status feedback, it supports IOCTL, polling, and mmap-ed buffers.  Finally, dv1394 support simultaneous operations limited by the number of DMA contexts on your host adapter.

There are no future plans for dv1394.  Future DV I/O capabilities will be implemented in a new raw1394-based API (rawiso) and [[Libraries#libiec61883|libiec61883]] (under development).


== Parameters ==

None


== Dependencies ==

* ieee1394
* ohci1394


== /dev ==

dv1394 has parallel dev and proc filesystem architectures.  The information provided here is based upon the default devfs naming scheme.  If you do not use devfs, then you can use your own names, but you must then map your names to the corresponding /proc files for non-programmatic (non-IOCTL) control.

dv1394 is a character device whose major number is 171.

{| border="1" cellpadding="5"
 !align="left"|Name
 !align="left"|Minor
 !align="left"|Description
 |-
 |/dev/ieee1394/dv/host0/NTSC/in
 |32
 |for NTSC on the first adapter (port)
 |-
 |/dev/ieee1394/dv/host0/NTSC/out
 |33
 |for NTSC on the first adapter (port)
 |-
 |/dev/ieee1394/dv/host0/PAL/in
 |34
 |for PAL on the first adapter (port)
 |-
 |/dev/ieee1394/dv/host0/PAL/out
 |35
 |for PAL on the first adapter (port)
 |-
 |...
 |...
 |...
 |-
 |/dev/ieee1394/dv/host3/NTSC/in
 |44
 |for NTSC on the fourth adapter (port)
 |-
 |/dev/ieee1394/dv/host3/NTSC/out
 |45
 |for NTSC on the fourth adapter (port)
 |-
 |/dev/ieee1394/dv/host3/PAL/in
 |46
 |for PAL on the fourth adapter (port)
 |-
 |/dev/ieee1394/dv/host3/PAL/out
 |47
 |for PAL on the fourth adapter (port)
 |}

Up to four host adapters are supported.  At this time the difference between in and out is not important; they simply provide 2 interfaces per signal type for simultaneous operations.  However, this limitation could change especially if dv1394 is adapted to the new rawiso API (no plans at this time).

In the absence of devfs, you can make your own device by, for example,
<pre>mknod -m 666 /dev/dv1394/0 c 171 32 for NTSC</pre>
or
<pre>mknod -m 666 /dev/dv1394/0 c 171 34 for PAL</pre>


== /proc ==

{| border="1" cellpadding="5"
 !align="left"|Name
 !align="left"|Description
 |-
 |/proc/bus/ieee1394/dv/host0/NTSC/in
 |for NTSC on the first adapter (port)
 |-
 |/proc/bus/ieee1394/dv/host0/NTSC/out
 |for NTSC on the first adapter (port)
 |-
 |/proc/bus/ieee1394/dv/host0/PAL/in
 |for PAL on the first adapter (port)
 |-
 |/proc/bus/ieee1394/dv/host0/PAL/out
 |for PAL on the first adapter (port)
 |-
 |...
 |...
 |-
 |/proc/bus/ieee1394/dv/host3/NTSC/in
 |for NTSC on the fourth adapter (port)
 |-
 |/proc/bus/ieee1394/dv/host3/NTSC/out
 |for NTSC on the fourth adapter (port)
 |-
 |/proc/bus/ieee1394/dv/host3/PAL/in
 |for PAL on the fourth adapter (port)
 |-
 |/proc/bus/ieee1394/dv/host3/PAL/out
 |for PAL on the fourth adapter (port)
 |}

Each proc file contains the following key/value pairs:
* format=(NTSC|PAL)
* channel=-1
* cip_n=0
* cip_d=0
* syt_offset=0

One can change a particular value by writing a new key and value pair to the file:
<pre>echo format=PAL >/proc/bus/ieee1394/dv/host0/NTSC/in</pre>

cip_n, cip_d, and syt_offset control the DV transmission timing.  The values of 0 use the hardcoded defaults, which should work for most users.  cip_n is the numerator and cip_d the denominator of an empty packet ratio algorithm used to slow the data rate.  syt_offset is the offset in cycle count applied to a timestamp placed into the header of 1394 packets.  A receiving device uses it to compensate for jitter.  The default value of 3 should work, but you may try 1,2, or 4.  Unlike Kino, this is measured in whole cycle counts, whereas Kino and video1394 uses cycle offset as the unit value, so do not try to use your known good Kino value here.  The spec calls for somewhere between 2 and 3 cycle counts.


== Known Problems ==

Kernel 2.4.19 released with a working dv1394 good for transmission and reception.  However, it is somewhat broken on non-devfs systems.  In that case, you should only use a single device file on minor 32 and configure it for your needs through IOCTL or /proc.  Also, the driver in kernel 2.4.19 required an interrupt for each packet received, which results in an inefficient high interrupt rate that proves problematic on some systems.

Kernel 2.4.20 released with dv1394 broken for reception.  ohci1394 had gone through some changes to interrupt handling to alleviate the need for high interrupt rates and allow handlers to be scheduled for background processing.  dv1394 reception was not adapted in time.

Since the above releases, all issues have been addressed.  The Subversion trunk and the linux-2.4 branch contain known good drivers.  The fixes will also appear in the kernel 2.4.21 release.

Attempting to receive PAL DV when dv1394 is configured for NTSC can result in a kernel oops.

The code in Subversion linux-2.4 branch requires kernel 2.4.19 or newer.


== Applications ==

Kino 0.6.2 can use dv1394 as new method for capture or IEEE 1394 export.

A forthcoming version of dvgrab uses dv1394 as an alternative method for capture.

dv1394d is a video server (TCP daemon) that supports multiple, simultaneous transmissions over the same bus using private isochronous channels.

ddr1394 is an IEC-61883 digital disk recorder with AV/C control.  There is some overlap between this and the dv1394d project and they may converge sometime soon.


[[Category:Kernel drivers]]
[[Category:Linux-2.4]]