migration.rst - pub/scm/docs/docsko/ieee1394 - Git at Google

 ===============================
 Migration from old driver stack
 ===============================

 2023/02/17 Takashi Sakamoto

 .. contents:: Contents
    :depth: 2
    :local:
    :backlinks: top

 Compatibility and stability
 ===========================

 In Q4/2010, the new FireWire kernel driver stack (alias Juju) became feature-complete and ready to
 replace the older ieee1394 stack. Here is a brief comparison to the older stack:

 * Storage devices: The new stack works better.
 * Video devices: The new stack generally works better or as well as the old one.
 * Audio devices: Caveats apply.
 * Controllers: All more or less widespread controllers are known to work. There are known issues
   with some rare controllers or rarely used software, see below.

 Audio devices require kernel 2.6.32 or later, ``libraw1394`` 2.0.5 or later, and ``libffado`` 2.0.1
 or later. Recommended for audio devices are kernel 2.6.36 or later, ``libraw1394`` 2.0.7 or later,
 and ``libffado`` 2.1.0 or later.

 Some old camcorders require kernel 3.1 or later and ``libraw1394`` 2.0.8 or later.

 IP over 1394 users should use kernel 2.6.38 or later.

 New stack not yet working as the old stack does
 -----------------------------------------------

 * Controllers

   * ALi M525x

     * Some cards with these controllers don't work yet. These controllers are comparably rare
       though. They were available as mid-range priced PCI cards (possibly also CardBus cards)
       and can be swapped for any cheap FireWire PCI card or CardBus card as a stop-gap
       solution.

   * Apple UniNorth rev.1

     * There seem to be problems with this controller, found in PowerBook G3 Pismo and G4 Titanium.
       These controllers are very rare nowadays. It is possible to use a cheap CardBus FireWire
       controller in all affected machines instead.

   * NVIDIA NForce2

     * May or may not work with the old drivers, do not yet work with the new drivers. These
       controllers are very rare. It is possible to use a cheap FireWire PCI controller in all
       affected machines instead. Note that there were reports that NForce2 did not work for some
       with the old drivers either, so this may not actually be a regression.

   * Pinnacle MovieBoard

     * ``firewire-ohci`` `hangs <http://thread.gmane.org/gmane.linux.kernel.firewire.devel/14972>`_
       in an interrupt loop at shutdown or 1panics
       `<http://thread.gmane.org/gmane.linux.kernel.firewire.devel/14982>`_ already at startup.
       These problems did apparently not happen with the older ``ohci1394`` driver, but the extent
       to which these card worked (or didn't) with ``ohci1394`` is not clear.

   * TI PCILynx TSB12LV21

     * No support for PCILynx or PCILynx2 controllers. Unlike TI OHCI-Lynx, PCILynx do not implement
       the OHCI-1394 standard and are nowadays very rare, hence it is unlikely that support for them
       will ever be written for the new driver stack. Note that their support in the old stack is
       extremely limited as well (no isochronous I/O which means no video, no audio, not even IP
       over 1394; slow and possibly very unstable SBP-2 support i.e. storage support). For all
       practical purposes, PCILynx controllers are not actually supported in the old stack either,
       and there was never any PCILynx owner who cared. (Instead, they use this hardware as a bus
       analyzer with the stand-alone driver nosy rather than as a controller with the old ieee1394
       pcilynx driver.)

 Historical note: VIA VT6306 did not work properly for DV capture with gstreamer's ``dv1394src``
 plugin or with the ``DV4Linux`` tool
 (`report <http://thread.gmane.org/gmane.linux.kernel.firewire.user/4101>`_). This should be fixed
 since kernel 3.10. VT6306 are shown by lspci as rev 46; higher chip revisions denote VT6307 or
 VT6308 which were apparently not affected by this problem.

 Installation of old drivers as fallback if the new ones are insufficient
 ------------------------------------------------------------------------

 As a migration aid, it is possible until kernel 2.6.36 inclusive to build and install the new _and_
 the old drivers together. However, care needs to be taken to keep in control which drivers are
 loaded. I.e. create proper blacklist entries in ``/etc/modprobe.conf`` as explained below to avoid
 auto-loading of the wrong drivers. ``Libraw1394`` v2 falls back to access the old drivers if the
 new ones are not loaded/ not bound to hardware, transparently to ``libraw1394`` based libraries and
 applications.

 If you are having trouble with the new drivers, do not hesitate to get in touch via the
 Mailinglists.

 Why the migration?
 ==================

 The code base of the new stack is smaller, cleaner, and closer follows modern Linux kernel
 programming paradigms. There are already some features in the new stack which the old one lacks,
 notably bus manager capability and so-called gap count optimization. The latter provides a
 noticeable speedup of SBP-2 and other asynchronous protocols. Instead of 3 or 5 userspace
 interfaces in the old stack, there is a single universal interface in the new stack. Furthermore,
 there are some fundamental bugs and security considerations with the old stack which to a large
 part motivated the rewrite of the driver stack.

 Module auto-loading
 ===================

 How to get auto-loading
 -----------------------

 The drivers ``firewire-ohci`` and ``firewire-sbp2`` contain the module aliases
 ``pci:v*d*sv*sd*bc0Csc00i10*`` and ``ieee1394:ven*mo*sp0000609Ever00010483*`` which should suffice
 with hotplug scripts and recent coldplug scripts to automatically load these two drivers when
 respective hardware is detected. The dependence of both drivers on ``firewire-core`` is of course
 recognized by modprobe.

 If the kernel was configured without ``ohci1394`` and ``sbp2`` as modules, then ``firewire-core`` and
 ``firewire-sbp2`` also contain the module aliases ``ohci1394`` and ``sbp2`` respectively. That is,
 ``modprobe ohci1394``" will load ``firewire-ohci`` (and ``firewire-core``) instead of ``ohci1394``
 if ``ohci1394`` was excluded from the kernel build.

 How to suppress auto-loading
 ----------------------------

 To avoid confusion, it is recommended that either the old or the new driver stack is built, but not
 both together. It is nevertheless possible to build and install both stacks together. If you chose
 to do so, you may want to add lines like

 ::

     # blacklist ``firewire-ohci``
     # blacklist ``firewire-sbp2``
     # blacklist firewire-net

     blacklist ``ohci1394``
     blacklist sbp2
     blacklist eth1394
     blacklist dv1394
     blacklist raw1394
     blacklist video1394

 to ``/etc/modprobe.d/file_of_your_choice`` or ``/etc/modprobe.conf`` to suppress auto-loading of
 one of the stacks.

 Extremely old modutils which do not support the blacklist keyword can be instructed by
 configuration entries like ``install _module_ /bin/true`` to suppress loading of a particular
 _module_.

 Module blacklisting alone is of course insufficient if the drivers are statically linked into the
 kernel. But less obvious, it is also insufficient if the set of drivers that you don't want are
 already loaded by an initrd (initial RAM disk) during system boot. For example, the stock initrd of
 Ubuntu 10.4 binds ``ohci1394`` to FireWire controllers. A remedy is to
 `rebuild the initrd <https://bugs.launchpad.net/ubuntu/+source/kino/+bug/6290/comments/78>`_
 with a reduced
 `selection of modules <http://marc.info/?l=linux1394-user&m=130289059932203>`_.

 Character device files, block device files
 ==========================================

 Basic operation
 ---------------

 Out of the box, udevd and udev scripts automatically create and remove

 * ``/dev/fw*`` devices exposed by ``firewire-core`` (for use by libraries like ``libraw1394`` and
   ``libdc1394``, provided the libraries are updated)
 * ``/dev/{sd,sg,sr,st}*`` devices exposed by SCSI command set drivers (sd_mod, sg, sr_mod, st) with
   ``firewire-sbp2`` underneath.

 Permissions and ownership for /dev/fw*
 ---------------------------------------

 Without any configuration file, the device files will be only accessible to root. This is fine and
 intended for SCSI block device files. But it is usually desirable to access the ``/dev/fw*``
 character device files as non-root user. The example udev rules shown below allow any user in group
 ``video`` to access ``/dev/fw*`` with programs such as ``dvgrab``, ``kino``, or ``coriander``.

 By evaluating information in ``firewire-core``'s sysfs files, it is possible to automatically adapt
 file permissions and ownership of ``/def/fw*`` files according to device types

 * Files pertaining to local nodes (the controllers) and SBP-2 nodes (storage devices, scanners
   etc.) should get restrictive file permissions and ownership. Actually, the default should be
   restrictive on most systems.

 * Files pertaining to audio and video devices (AV/C or IIDC compliant nodes) can get liberal
   permissions so that they are accessible to application programs without root privilege.

 * Old ``libraw1394`` versions and some special-purpose ``libraw1394`` clients (e.g. ``gscanbus``)
   currently require also access to the local node. Its permissions need to be liberal in those
   cases too.  To the author's knowledge, this does not have any actual security impact on systems
   on which user access to AV/C and IIDC devices is already allowed, but distributors typically
   won't want to open this up per default.

 The following rules implement this device type dependent control over permissions, using the
 example ``video`` group. These rules work with Linux kernel 2.6.31 and later. These rules have been
 merged into ``/lib/udev/rules.d/50-udev-default.rules`` of udev v144.

 ``/etc/udev/rules.d/example-firewire.rules`` ::

   # IIDC devices: industrial cameras and some webcams
   SUBSYSTEM=="firewire", ATTR{units}=="*0x00a02d:0x00010*", GROUP="video"

   # AV/C devices: camcorders, set-top boxes, TV sets, various audio devices, and more
   SUBSYSTEM=="firewire", ATTR{units}=="*0x00a02d:0x010001*", GROUP="video"

 In udev v161, two more match patterns were added: ``*0x00b09d:0x00010*`` for IIDC cameras from
 Point Grey and ``*0x00a02d:0x014001*`` for AV/C devices with vendor-unique command set.

 Unfortunately, FireWire audio devices often adhere to vendor-specific protocols. Furthermore, an
 ``audio`` group assignment may be preferred over ``video``. Therefore, a special ruleset for the
 FFADO FireWire audio library is provided by recent versions of ``libffado``
 (`60-ffado.rules <http://subversion.ffado.org/browser/trunk/libffado/libffado/60-ffado.rules>`_).

 If your application needs access to all nodes, simply use:

 ::

   SUBSYSTEM=="firewire", GROUP="video"

 There are also schemes which are based on access control lists instead of UNIX file permissions.
 For example, the Fedora Linux distribution currently contains a mechanism to add read and write
 permission for the locally logged in user to the ACLs of ``fw*`` files of some FireWire device
 types.  To this end, recent udev releases have firewire subsystem rules in the file
 ``70-acl.rules`` file.

 Symlinks to SCSI block device files
 ===================================

 Reasonably recent udev scripts create symbolic links in ``/dev/disk/by-id/*``, pointing to the
 block devices of FireWire harddisks. These links are convenient for example to use them in static
 fstab entries: Their names are always the same because they are based on persistent and unique
 device identifiers, while the actual device files have arbitrary names that change all the time
 when disks are plugged in and out.

 The names of the by-id links look per default a little bit different with ``firewire-sbp2`` compared
 to sbp2. To make them look exactly the same, add the following to
 ``/etc/modprobe.d/file_of_your_choice or /etc/modprobe.conf``:

 ::

   options ``sbp2`` long_ieee1394_id=y

 This option has been added to ``sbp2`` in Linux 2.6.22.

 You only need this if you plan to switch between ``sbp2`` and ``firewire-sbp2`` and if you are using the
 ``/dev/disk/by-id`` symlinks.

 Hald support
 ============

 Nothing special is needed; hotplug and hot-removal of ``firewire-sbp2`` driven disks is exposed on
 desktops just fine.

 Initrd
 ======

 Scripts which generate initrd (an initial RAM disk used during boot) may need to be updated to deal
 with the new kernel module names ``firewire-core``, ``firewire-ohci``, ``firewire-sbp2``. Scripts within initrd
 may already work with the new drivers.

 Libraries
 =========

 libraw1394
 ----------

 _At the time of this writing (July 2012), ``libraw1394`` v2.1.0 is the current release and also the
 recommended stable release for use with the new firewire drivers._

 Compatibility with the new drivers is available since ``libraw1394`` v2.0.0, released in July 2008.
 This version is able to transparently switch between old and new stack, depending on which drivers
 you have loaded. Bug fixes related to usage with the new kernel drivers followed in further v2.0.x
 sub-releases.

 Either get the latest ``libraw1394`` 2.x release, or build ``libraw1394`` from a fresh git checkout:

 ::

     $ git clone git://git.kernel.org/pub/scm/libs/ieee1394/``libraw1394``.git
     $ cd ``libraw1394``/
     $ autoreconf -fi
     $ ./configure
     $ make
     $ sudo make install

 The Juju backend of ``libraw1394`` requires the inotify kernel interface. If you have got a very old
 libc which does not contain support for inotify, you can have a look at the following patches for
 ``libraw1394``: `patch 1 <http://marc.info/?l=linux1394-devel&m=120058086516766>`_,
 `patch 2 <http://marc.info/?l=linux1394-devel&m=120058086516770>`_. They don't apply to recent
 versions of ``libraw1394`` anymore though.

 Libraw1394's Juju backend furthermore expects that the kernel was configured and built with the
 following options:

 ::

     CONFIG_INOTIFY_USER=y
     CONFIG_EPOLL=y

 The inotify option is located in the "File systems" section of the Kconfig dialogs.
 ``CONFIG_EPOLL`` is already enabled in usual kernel configurations and not even visible in the
 Kconfig dialogs. But if the kernel was configured for embedded systems it may be necessary to
 switch ``CONFIG_EPOLL`` on explicitly; it is then found in the ``General setup`` section of the
 kernel configuration.

 libdc1394
 ---------

 .. note: At the time of this writing (May 2012), ``libdc1394`` v2.2.0 is the current release and
    also the recommended stable release for use with the new firewire drivers.

 There is compatibility with ``libdc1394`` v2, released in January 2008. Some deployed ``libdc1394``
 applications still use the older ``libdc1394`` v1 though which has no support for the Juju drivers.
 Since v2.1.0, ``libdc1394`` transparently supports the old and the new drivers, though with
 different extent of functionality. Since ``libdc1394`` v2.1.2 from June 2009 and kernel 2.6.30,
 ``libdc1394`` 's Juju backend fully supports multiple cameras on the same bus, precise packet
 timestamps/ framerate measurement, and isochronous resource clean-up even at unclean program
 termination — i.e. offers same or better functionality with the new drivers compared to the old
 ones.

 You can check ``libdc1394`` v2 out from the project's repository and build it with support for both
 the new and the old driver stack by the following steps:

 ::

     $ git clone git://libdc1394.git.sourceforge.net/gitroot/libdc1394/libdc1394
     $ cd libdc1394/libdc1394/
     $ autoreconf -fi
     $ ./configure
     $ make
     $ sudo make install

 (In ``libdc1394`` until v2.0.3 inclusive, a configure switch called "--with-juju-dir" was necessary
 to support the new driver ABI, e.g. ``./configure --with-juju-dir=/usr/src/linux/include``. But this
 also disabled support for the old ieee1394 stack.)

 ``Libdc1394`` is able to work with the new drivers even if you have only a ``libraw1394`` v1
 installed alongside ``libdc1394``. This is because ``libdc1394`` requires ``libraw1394`` only in
 order to use the old drivers while it accesses the new drivers without assistance of
 ``libraw1394``.

 No special kernel headers package is required to build ``libdc1394``.

 FFmpeg: libavformat
 -------------------

 Alas the ``dv1394`` module of `FFmpeg <http://ffmpeg.mplayerhq.hu/>`_ s libavformat has not been
 ported to ``firewire-core`` yet. This particularly affects players like MPlayer and Xine. However,
 you can use the capture utility ``dvgrab`` to provide input to players:

 ::

     $ dvgrab - | xine stdin:/

 pwlib: AV/C and IIDC plugins
 ----------------------------

 The `AV/C video input module <http://opalvoip.svn.sourceforge.net/viewvc/opalvoip/ptlib/trunk/plugins/vidinput_avc/vidinput_avc.cxx>`_
 of ``pwlib`` a.k.a. ``ptlib``, used in `Opal <http://www.opalvoip.org/>`_,
 `Ekiga <http://www.ekiga.org/>`_ etc. uses the old ``raw1394_start_iso_rcv`` API which is no longer
 implemented in the kernel since Release Notes/2.6.2x.

 The `IIDC video input module <http://opalvoip.svn.sourceforge.net/viewvc/opalvoip/ptlib/trunk/plugins/vidinput_dc/video4dc1394.cxx>`_
 (a.k.a. DC module) of ``pwlib``/``ptlib`` uses ``libdc1394`` v1 to which the new drivers are not
 compatible.

 Best would be if we had a V4L2 interface to FireWire cameras; then these applications would work
 out of the box without special 1394 backends and libraries.
	===============================
	Migration from old driver stack
	===============================

	2023/02/17 Takashi Sakamoto

	.. contents:: Contents
	:depth: 2
	:local:
	:backlinks: top

	Compatibility and stability
	===========================

	In Q4/2010, the new FireWire kernel driver stack (alias Juju) became feature-complete and ready to
	replace the older ieee1394 stack. Here is a brief comparison to the older stack:

	* Storage devices: The new stack works better.
	* Video devices: The new stack generally works better or as well as the old one.
	* Audio devices: Caveats apply.
	* Controllers: All more or less widespread controllers are known to work. There are known issues
	with some rare controllers or rarely used software, see below.

	Audio devices require kernel 2.6.32 or later, ``libraw1394`` 2.0.5 or later, and ``libffado`` 2.0.1
	or later. Recommended for audio devices are kernel 2.6.36 or later, ``libraw1394`` 2.0.7 or later,
	and ``libffado`` 2.1.0 or later.

	Some old camcorders require kernel 3.1 or later and ``libraw1394`` 2.0.8 or later.

	IP over 1394 users should use kernel 2.6.38 or later.

	New stack not yet working as the old stack does
	-----------------------------------------------

	* Controllers

	* ALi M525x

	* Some cards with these controllers don't work yet. These controllers are comparably rare
	though. They were available as mid-range priced PCI cards (possibly also CardBus cards)
	and can be swapped for any cheap FireWire PCI card or CardBus card as a stop-gap
	solution.

	* Apple UniNorth rev.1

	* There seem to be problems with this controller, found in PowerBook G3 Pismo and G4 Titanium.
	These controllers are very rare nowadays. It is possible to use a cheap CardBus FireWire
	controller in all affected machines instead.

	* NVIDIA NForce2

	* May or may not work with the old drivers, do not yet work with the new drivers. These
	controllers are very rare. It is possible to use a cheap FireWire PCI controller in all
	affected machines instead. Note that there were reports that NForce2 did not work for some
	with the old drivers either, so this may not actually be a regression.

	* Pinnacle MovieBoard

	* ``firewire-ohci`` `hangs <http://thread.gmane.org/gmane.linux.kernel.firewire.devel/14972>`_
	in an interrupt loop at shutdown or 1panics
	`<http://thread.gmane.org/gmane.linux.kernel.firewire.devel/14982>`_ already at startup.
	These problems did apparently not happen with the older ``ohci1394`` driver, but the extent
	to which these card worked (or didn't) with ``ohci1394`` is not clear.

	* TI PCILynx TSB12LV21

	* No support for PCILynx or PCILynx2 controllers. Unlike TI OHCI-Lynx, PCILynx do not implement
	the OHCI-1394 standard and are nowadays very rare, hence it is unlikely that support for them
	will ever be written for the new driver stack. Note that their support in the old stack is
	extremely limited as well (no isochronous I/O which means no video, no audio, not even IP
	over 1394; slow and possibly very unstable SBP-2 support i.e. storage support). For all
	practical purposes, PCILynx controllers are not actually supported in the old stack either,
	and there was never any PCILynx owner who cared. (Instead, they use this hardware as a bus
	analyzer with the stand-alone driver nosy rather than as a controller with the old ieee1394
	pcilynx driver.)

	Historical note: VIA VT6306 did not work properly for DV capture with gstreamer's ``dv1394src``
	plugin or with the ``DV4Linux`` tool
	(`report <http://thread.gmane.org/gmane.linux.kernel.firewire.user/4101>`_). This should be fixed
	since kernel 3.10. VT6306 are shown by lspci as rev 46; higher chip revisions denote VT6307 or
	VT6308 which were apparently not affected by this problem.

	Installation of old drivers as fallback if the new ones are insufficient
	------------------------------------------------------------------------

	As a migration aid, it is possible until kernel 2.6.36 inclusive to build and install the new _and_
	the old drivers together. However, care needs to be taken to keep in control which drivers are
	loaded. I.e. create proper blacklist entries in ``/etc/modprobe.conf`` as explained below to avoid
	auto-loading of the wrong drivers. ``Libraw1394`` v2 falls back to access the old drivers if the
	new ones are not loaded/ not bound to hardware, transparently to ``libraw1394`` based libraries and
	applications.

	If you are having trouble with the new drivers, do not hesitate to get in touch via the
	Mailinglists.

	Why the migration?
	==================

	The code base of the new stack is smaller, cleaner, and closer follows modern Linux kernel
	programming paradigms. There are already some features in the new stack which the old one lacks,
	notably bus manager capability and so-called gap count optimization. The latter provides a
	noticeable speedup of SBP-2 and other asynchronous protocols. Instead of 3 or 5 userspace
	interfaces in the old stack, there is a single universal interface in the new stack. Furthermore,
	there are some fundamental bugs and security considerations with the old stack which to a large
	part motivated the rewrite of the driver stack.

	Module auto-loading
	===================

	How to get auto-loading
	-----------------------

	The drivers ``firewire-ohci`` and ``firewire-sbp2`` contain the module aliases
	``pci:vdsvsdbc0Csc00i10`` and ``ieee1394:venmosp0000609Ever00010483`` which should suffice
	with hotplug scripts and recent coldplug scripts to automatically load these two drivers when
	respective hardware is detected. The dependence of both drivers on ``firewire-core`` is of course
	recognized by modprobe.

	If the kernel was configured without ``ohci1394`` and ``sbp2`` as modules, then ``firewire-core`` and
	``firewire-sbp2`` also contain the module aliases ``ohci1394`` and ``sbp2`` respectively. That is,
	``modprobe ohci1394``" will load ``firewire-ohci`` (and ``firewire-core``) instead of ``ohci1394``
	if ``ohci1394`` was excluded from the kernel build.

	How to suppress auto-loading
	----------------------------

	To avoid confusion, it is recommended that either the old or the new driver stack is built, but not
	both together. It is nevertheless possible to build and install both stacks together. If you chose
	to do so, you may want to add lines like

	::

	# blacklist ``firewire-ohci``
	# blacklist ``firewire-sbp2``
	# blacklist firewire-net

	blacklist ``ohci1394``
	blacklist sbp2
	blacklist eth1394
	blacklist dv1394
	blacklist raw1394
	blacklist video1394

	to ``/etc/modprobe.d/file_of_your_choice`` or ``/etc/modprobe.conf`` to suppress auto-loading of
	one of the stacks.

	Extremely old modutils which do not support the blacklist keyword can be instructed by
	configuration entries like ``install _module_ /bin/true`` to suppress loading of a particular
	_module_.

	Module blacklisting alone is of course insufficient if the drivers are statically linked into the
	kernel. But less obvious, it is also insufficient if the set of drivers that you don't want are
	already loaded by an initrd (initial RAM disk) during system boot. For example, the stock initrd of
	Ubuntu 10.4 binds ``ohci1394`` to FireWire controllers. A remedy is to
	`rebuild the initrd <https://bugs.launchpad.net/ubuntu/+source/kino/+bug/6290/comments/78>`_
	with a reduced
	`selection of modules <http://marc.info/?l=linux1394-user&m=130289059932203>`_.

	Character device files, block device files
	==========================================

	Basic operation
	---------------

	Out of the box, udevd and udev scripts automatically create and remove

	* ``/dev/fw*`` devices exposed by ``firewire-core`` (for use by libraries like ``libraw1394`` and
	``libdc1394``, provided the libraries are updated)
	* ``/dev/{sd,sg,sr,st}*`` devices exposed by SCSI command set drivers (sd_mod, sg, sr_mod, st) with
	``firewire-sbp2`` underneath.

	Permissions and ownership for /dev/fw*
	---------------------------------------

	Without any configuration file, the device files will be only accessible to root. This is fine and
	intended for SCSI block device files. But it is usually desirable to access the ``/dev/fw*``
	character device files as non-root user. The example udev rules shown below allow any user in group
	``video`` to access ``/dev/fw*`` with programs such as ``dvgrab``, ``kino``, or ``coriander``.

	By evaluating information in ``firewire-core``'s sysfs files, it is possible to automatically adapt
	file permissions and ownership of ``/def/fw*`` files according to device types

	* Files pertaining to local nodes (the controllers) and SBP-2 nodes (storage devices, scanners
	etc.) should get restrictive file permissions and ownership. Actually, the default should be
	restrictive on most systems.

	* Files pertaining to audio and video devices (AV/C or IIDC compliant nodes) can get liberal
	permissions so that they are accessible to application programs without root privilege.

	* Old ``libraw1394`` versions and some special-purpose ``libraw1394`` clients (e.g. ``gscanbus``)
	currently require also access to the local node. Its permissions need to be liberal in those
	cases too. To the author's knowledge, this does not have any actual security impact on systems
	on which user access to AV/C and IIDC devices is already allowed, but distributors typically
	won't want to open this up per default.

	The following rules implement this device type dependent control over permissions, using the
	example ``video`` group. These rules work with Linux kernel 2.6.31 and later. These rules have been
	merged into ``/lib/udev/rules.d/50-udev-default.rules`` of udev v144.

	``/etc/udev/rules.d/example-firewire.rules`` ::

	# IIDC devices: industrial cameras and some webcams
	SUBSYSTEM=="firewire", ATTR{units}=="0x00a02d:0x00010", GROUP="video"

	# AV/C devices: camcorders, set-top boxes, TV sets, various audio devices, and more
	SUBSYSTEM=="firewire", ATTR{units}=="0x00a02d:0x010001", GROUP="video"

	In udev v161, two more match patterns were added: ``0x00b09d:0x00010`` for IIDC cameras from
	Point Grey and ``0x00a02d:0x014001`` for AV/C devices with vendor-unique command set.

	Unfortunately, FireWire audio devices often adhere to vendor-specific protocols. Furthermore, an
	``audio`` group assignment may be preferred over ``video``. Therefore, a special ruleset for the
	FFADO FireWire audio library is provided by recent versions of ``libffado``
	(`60-ffado.rules <http://subversion.ffado.org/browser/trunk/libffado/libffado/60-ffado.rules>`_).

	If your application needs access to all nodes, simply use:

	::

	SUBSYSTEM=="firewire", GROUP="video"

	There are also schemes which are based on access control lists instead of UNIX file permissions.
	For example, the Fedora Linux distribution currently contains a mechanism to add read and write
	permission for the locally logged in user to the ACLs of ``fw*`` files of some FireWire device
	types. To this end, recent udev releases have firewire subsystem rules in the file
	``70-acl.rules`` file.

	Symlinks to SCSI block device files
	===================================

	Reasonably recent udev scripts create symbolic links in ``/dev/disk/by-id/*``, pointing to the
	block devices of FireWire harddisks. These links are convenient for example to use them in static
	fstab entries: Their names are always the same because they are based on persistent and unique
	device identifiers, while the actual device files have arbitrary names that change all the time
	when disks are plugged in and out.

	The names of the by-id links look per default a little bit different with ``firewire-sbp2`` compared
	to sbp2. To make them look exactly the same, add the following to
	``/etc/modprobe.d/file_of_your_choice or /etc/modprobe.conf``:

	::

	options ``sbp2`` long_ieee1394_id=y

	This option has been added to ``sbp2`` in Linux 2.6.22.

	You only need this if you plan to switch between ``sbp2`` and ``firewire-sbp2`` and if you are using the
	``/dev/disk/by-id`` symlinks.

	Hald support
	============

	Nothing special is needed; hotplug and hot-removal of ``firewire-sbp2`` driven disks is exposed on
	desktops just fine.

	Initrd
	======

	Scripts which generate initrd (an initial RAM disk used during boot) may need to be updated to deal
	with the new kernel module names ``firewire-core``, ``firewire-ohci``, ``firewire-sbp2``. Scripts within initrd
	may already work with the new drivers.

	Libraries
	=========

	libraw1394
	----------

	_At the time of this writing (July 2012), ``libraw1394`` v2.1.0 is the current release and also the
	recommended stable release for use with the new firewire drivers._

	Compatibility with the new drivers is available since ``libraw1394`` v2.0.0, released in July 2008.
	This version is able to transparently switch between old and new stack, depending on which drivers
	you have loaded. Bug fixes related to usage with the new kernel drivers followed in further v2.0.x
	sub-releases.

	Either get the latest ``libraw1394`` 2.x release, or build ``libraw1394`` from a fresh git checkout:

	::

	$ git clone git://git.kernel.org/pub/scm/libs/ieee1394/``libraw1394``.git
	$ cd ``libraw1394``/
	$ autoreconf -fi
	$ ./configure
	$ make
	$ sudo make install

	The Juju backend of ``libraw1394`` requires the inotify kernel interface. If you have got a very old
	libc which does not contain support for inotify, you can have a look at the following patches for
	``libraw1394``: `patch 1 <http://marc.info/?l=linux1394-devel&m=120058086516766>`_,
	`patch 2 <http://marc.info/?l=linux1394-devel&m=120058086516770>`_. They don't apply to recent
	versions of ``libraw1394`` anymore though.

	Libraw1394's Juju backend furthermore expects that the kernel was configured and built with the
	following options:

	::

	CONFIG_INOTIFY_USER=y
	CONFIG_EPOLL=y

	The inotify option is located in the "File systems" section of the Kconfig dialogs.
	``CONFIG_EPOLL`` is already enabled in usual kernel configurations and not even visible in the
	Kconfig dialogs. But if the kernel was configured for embedded systems it may be necessary to
	switch ``CONFIG_EPOLL`` on explicitly; it is then found in the ``General setup`` section of the
	kernel configuration.

	libdc1394
	---------

	.. note: At the time of this writing (May 2012), ``libdc1394`` v2.2.0 is the current release and
	also the recommended stable release for use with the new firewire drivers.

	There is compatibility with ``libdc1394`` v2, released in January 2008. Some deployed ``libdc1394``
	applications still use the older ``libdc1394`` v1 though which has no support for the Juju drivers.
	Since v2.1.0, ``libdc1394`` transparently supports the old and the new drivers, though with
	different extent of functionality. Since ``libdc1394`` v2.1.2 from June 2009 and kernel 2.6.30,
	``libdc1394`` 's Juju backend fully supports multiple cameras on the same bus, precise packet
	timestamps/ framerate measurement, and isochronous resource clean-up even at unclean program
	termination — i.e. offers same or better functionality with the new drivers compared to the old
	ones.

	You can check ``libdc1394`` v2 out from the project's repository and build it with support for both
	the new and the old driver stack by the following steps:

	::

	$ git clone git://libdc1394.git.sourceforge.net/gitroot/libdc1394/libdc1394
	$ cd libdc1394/libdc1394/
	$ autoreconf -fi
	$ ./configure
	$ make
	$ sudo make install

	(In ``libdc1394`` until v2.0.3 inclusive, a configure switch called "--with-juju-dir" was necessary
	to support the new driver ABI, e.g. ``./configure --with-juju-dir=/usr/src/linux/include``. But this
	also disabled support for the old ieee1394 stack.)

	``Libdc1394`` is able to work with the new drivers even if you have only a ``libraw1394`` v1
	installed alongside ``libdc1394``. This is because ``libdc1394`` requires ``libraw1394`` only in
	order to use the old drivers while it accesses the new drivers without assistance of
	``libraw1394``.

	No special kernel headers package is required to build ``libdc1394``.

	FFmpeg: libavformat
	-------------------

	Alas the ``dv1394`` module of `FFmpeg <http://ffmpeg.mplayerhq.hu/>`_ s libavformat has not been
	ported to ``firewire-core`` yet. This particularly affects players like MPlayer and Xine. However,
	you can use the capture utility ``dvgrab`` to provide input to players:

	::

	$ dvgrab - \| xine stdin:/

	pwlib: AV/C and IIDC plugins
	----------------------------

	The `AV/C video input module <http://opalvoip.svn.sourceforge.net/viewvc/opalvoip/ptlib/trunk/plugins/vidinput_avc/vidinput_avc.cxx>`_
	of ``pwlib`` a.k.a. ``ptlib``, used in `Opal <http://www.opalvoip.org/>`_,
	`Ekiga <http://www.ekiga.org/>`_ etc. uses the old ``raw1394_start_iso_rcv`` API which is no longer
	implemented in the kernel since Release Notes/2.6.2x.

	The `IIDC video input module <http://opalvoip.svn.sourceforge.net/viewvc/opalvoip/ptlib/trunk/plugins/vidinput_dc/video4dc1394.cxx>`_
	(a.k.a. DC module) of ``pwlib``/``ptlib`` uses ``libdc1394`` v1 to which the new drivers are not
	compatible.

	Best would be if we had a V4L2 interface to FireWire cameras; then these applications would work
	out of the box without special 1394 backends and libraries.