Firewire (IEEE 1394) driver Interface Guide

Introduction and Overview

The Linux FireWire subsystem adds some interfaces into the Linux system to
use/maintain+any resource on IEEE 1394 bus.

The main purpose of these interfaces is to access address space on each node on IEEE 1394 bus by ISO/IEC 13213 (IEEE 1212) procedure, and to control isochronous resources on the bus by IEEE 1394 procedure.

Two types of interfaces are added, according to consumers of the interface. A set of userspace interfaces is available via firewire character devices. A set of kernel interfaces is available via exported symbols in firewire-core module.

Firewire char device data structures

What:           /dev/fw[0-9]+
Date:           May 2007
KernelVersion:  2.6.22
Contact:        linux1394-devel@lists.sourceforge.net
Description:
                The character device files /dev/fw* are the interface between
                firewire-core and IEEE 1394 device drivers implemented in
                userspace.  The ioctl(2)- and read(2)-based ABI is defined and
                documented in <linux/firewire-cdev.h>.

                This ABI offers most of the features which firewire-core also
                exposes to kernelspace IEEE 1394 drivers.

                Each /dev/fw* is associated with one IEEE 1394 node, which can
                be remote or local nodes.  Operations on a /dev/fw* file have
                different scope:
                  - The 1394 node which is associated with the file:
                          - Asynchronous request transmission
                          - Get the Configuration ROM
                          - Query node ID
                          - Query maximum speed of the path between this node
                            and local node
                  - The 1394 bus (i.e. "card") to which the node is attached to:
                          - Isochronous stream transmission and reception
                          - Asynchronous stream transmission and reception
                          - Asynchronous broadcast request transmission
                          - PHY packet transmission and reception
                          - Allocate, reallocate, deallocate isochronous
                            resources (channels, bandwidth) at the bus's IRM
                          - Query node IDs of local node, root node, IRM, bus
                            manager
                          - Query cycle time
                          - Bus reset initiation, bus reset event reception
                  - All 1394 buses:
                          - Allocation of IEEE 1212 address ranges on the local
                            link layers, reception of inbound requests to such
                            an address range, asynchronous response transmission
                            to inbound requests
                          - Addition of descriptors or directories to the local
                            nodes' Configuration ROM

                Due to the different scope of operations and in order to let
                userland implement different access permission models, some
                operations are restricted to /dev/fw* files that are associated
                with a local node:
                          - Addition of descriptors or directories to the local
                            nodes' Configuration ROM
                          - PHY packet transmission and reception

                A /dev/fw* file remains associated with one particular node
                during its entire life time.  Bus topology changes, and hence
                node ID changes, are tracked by firewire-core.  ABI users do not
                need to be aware of topology.

                The following file operations are supported:

                open(2)
                Currently the only useful flags are O_RDWR.

                ioctl(2)
                Initiate various actions.  Some take immediate effect, others
                are performed asynchronously while or after the ioctl returns.
                See the inline documentation in <linux/firewire-cdev.h> for
                descriptions of all ioctls.

                poll(2), select(2), epoll_wait(2) etc.
                Watch for events to become available to be read.

                read(2)
                Receive various events.  There are solicited events like
                outbound asynchronous transaction completion or isochronous
                buffer completion, and unsolicited events such as bus resets,
                request reception, or PHY packet reception.  Always use a read
                buffer which is large enough to receive the largest event that
                could ever arrive.  See <linux/firewire-cdev.h> for descriptions
                of all event types and for which ioctls affect reception of
                events.

                mmap(2)
                Allocate a DMA buffer for isochronous reception or transmission
                and map it into the process address space.  The arguments should
                be used as follows:  addr = NULL, length = the desired buffer
                size, i.e. number of packets times size of largest packet,
                prot = at least PROT_READ for reception and at least PROT_WRITE
                for transmission, flags = MAP_SHARED, fd = the handle to the
                /dev/fw*, offset = 0.

                Isochronous reception works in packet-per-buffer fashion except
                for multichannel reception which works in buffer-fill mode.

                munmap(2)
                Unmap the isochronous I/O buffer from the process address space.

                close(2)
                Besides stopping and freeing I/O contexts that were associated
                with the file descriptor, back out any changes to the local
                nodes' Configuration ROM.  Deallocate isochronous channels and
                bandwidth at the IRM that were marked for kernel-assisted
                re- and deallocation.

Users:          libraw1394
                libdc1394
                libhinawa
                tools like linux-firewire-utils, fwhack, ...

Error

kernel-doc missing

Firewire device probing and sysfs interfaces

What:           /sys/bus/firewire/devices/fw[0-9]+/
Date:           May 2007
KernelVersion:  2.6.22
Contact:        linux1394-devel@lists.sourceforge.net
Description:
                IEEE 1394 node device attributes.
                Read-only.  Mutable during the node device's lifetime.
                See IEEE 1212 for semantic definitions.

                config_rom
                        Contents of the Configuration ROM register.
                        Binary attribute; an array of host-endian u32.

                guid
                        The node's EUI-64 in the bus information block of
                        Configuration ROM.
                        Hexadecimal string representation of an u64.


What:           /sys/bus/firewire/devices/fw[0-9]+/units
Date:           June 2009
KernelVersion:  2.6.31
Contact:        linux1394-devel@lists.sourceforge.net
Description:
                IEEE 1394 node device attribute.
                Read-only.  Mutable during the node device's lifetime.
                See IEEE 1212 for semantic definitions.

                units
                        Summary of all units present in an IEEE 1394 node.
                        Contains space-separated tuples of specifier_id and
                        version of each unit present in the node.  Specifier_id
                        and version are hexadecimal string representations of
                        u24 of the respective unit directory entries.
                        Specifier_id and version within each tuple are separated
                        by a colon.

Users:          udev rules to set ownership and access permissions or ACLs of
                /dev/fw[0-9]+ character device files


What:           /sys/bus/firewire/devices/fw[0-9]+/is_local
Date:           July 2012
KernelVersion:  3.6
Contact:        linux1394-devel@lists.sourceforge.net
Description:
                IEEE 1394 node device attribute.
                Read-only and immutable.
Values:         1: The sysfs entry represents a local node (a controller card).
                0: The sysfs entry represents a remote node.


What:           /sys/bus/firewire/devices/fw[0-9]+[.][0-9]+/
Date:           May 2007
KernelVersion:  2.6.22
Contact:        linux1394-devel@lists.sourceforge.net
Description:
                IEEE 1394 unit device attributes.
                Read-only.  Immutable during the unit device's lifetime.
                See IEEE 1212 for semantic definitions.

                modalias
                        Same as MODALIAS in the uevent at device creation.

                rom_index
                        Offset of the unit directory within the parent device's
                        (node device's) Configuration ROM, in quadlets.
                        Decimal string representation.


What:           /sys/bus/firewire/devices/*/
Date:           May 2007
KernelVersion:  2.6.22
Contact:        linux1394-devel@lists.sourceforge.net
Description:
                Attributes common to IEEE 1394 node devices and unit devices.
                Read-only.  Mutable during the node device's lifetime.
                Immutable during the unit device's lifetime.
                See IEEE 1212 for semantic definitions.

                These attributes are only created if the root directory of an
                IEEE 1394 node or the unit directory of an IEEE 1394 unit
                actually contains according entries.

                hardware_version
                        Hexadecimal string representation of an u24.

                hardware_version_name
                        Contents of a respective textual descriptor leaf.

                model
                        Hexadecimal string representation of an u24.

                model_name
                        Contents of a respective textual descriptor leaf.

                specifier_id
                        Hexadecimal string representation of an u24.
                        Mandatory in unit directories according to IEEE 1212.

                vendor
                        Hexadecimal string representation of an u24.
                        Mandatory in the root directory according to IEEE 1212.

                vendor_name
                        Contents of a respective textual descriptor leaf.

                version
                        Hexadecimal string representation of an u24.
                        Mandatory in unit directories according to IEEE 1212.


What:           /sys/bus/firewire/drivers/sbp2/fw*/host*/target*/*:*:*:*/ieee1394_id
                formerly
                /sys/bus/ieee1394/drivers/sbp2/fw*/host*/target*/*:*:*:*/ieee1394_id
Date:           Feb 2004
KernelVersion:  2.6.4
Contact:        linux1394-devel@lists.sourceforge.net
Description:
                SCSI target port identifier and logical unit identifier of a
                logical unit of an SBP-2 target.  The identifiers are specified
                in SAM-2...SAM-4 annex A.  They are persistent and world-wide
                unique properties the SBP-2 attached target.

                Read-only attribute, immutable during the target's lifetime.
                Format, as exposed by firewire-sbp2 since 2.6.22, May 2007:
                Colon-separated hexadecimal string representations of
                        u64 EUI-64 : u24 directory_ID : u16 LUN
                without 0x prefixes, without whitespace.  The former sbp2 driver
                (removed in 2.6.37 after being superseded by firewire-sbp2) used
                a somewhat shorter format which was not as close to SAM.

Users:          udev rules to create /dev/disk/by-id/ symlinks

Error

kernel-doc missing

Firewire core transaction interfaces

Error

kernel-doc missing

Firewire Isochronous I/O interfaces

Error

kernel-doc missing