0001 What: /dev/fw[0-9]+
0002 Date: May 2007
0003 KernelVersion: 2.6.22
0004 Contact: linux1394-devel@lists.sourceforge.net
0005 Description:
0006 The character device files /dev/fw* are the interface between
0007 firewire-core and IEEE 1394 device drivers implemented in
0008 userspace. The ioctl(2)- and read(2)-based ABI is defined and
0009 documented in <linux/firewire-cdev.h>.
0010
0011 This ABI offers most of the features which firewire-core also
0012 exposes to kernelspace IEEE 1394 drivers.
0013
0014 Each /dev/fw* is associated with one IEEE 1394 node, which can
0015 be remote or local nodes. Operations on a /dev/fw* file have
0016 different scope:
0017
0018 - The 1394 node which is associated with the file:
0019
0020 - Asynchronous request transmission
0021 - Get the Configuration ROM
0022 - Query node ID
0023 - Query maximum speed of the path between this node
0024 and local node
0025
0026 - The 1394 bus (i.e. "card") to which the node is attached to:
0027
0028 - Isochronous stream transmission and reception
0029 - Asynchronous stream transmission and reception
0030 - Asynchronous broadcast request transmission
0031 - PHY packet transmission and reception
0032 - Allocate, reallocate, deallocate isochronous
0033 resources (channels, bandwidth) at the bus's IRM
0034 - Query node IDs of local node, root node, IRM, bus
0035 manager
0036 - Query cycle time
0037 - Bus reset initiation, bus reset event reception
0038
0039 - All 1394 buses:
0040
0041 - Allocation of IEEE 1212 address ranges on the local
0042 link layers, reception of inbound requests to such
0043 an address range, asynchronous response transmission
0044 to inbound requests
0045 - Addition of descriptors or directories to the local
0046 nodes' Configuration ROM
0047
0048 Due to the different scope of operations and in order to let
0049 userland implement different access permission models, some
0050 operations are restricted to /dev/fw* files that are associated
0051 with a local node:
0052
0053 - Addition of descriptors or directories to the local
0054 nodes' Configuration ROM
0055 - PHY packet transmission and reception
0056
0057 A /dev/fw* file remains associated with one particular node
0058 during its entire life time. Bus topology changes, and hence
0059 node ID changes, are tracked by firewire-core. ABI users do not
0060 need to be aware of topology.
0061
0062 The following file operations are supported:
0063
0064 open(2)
0065 Currently the only useful flags are O_RDWR.
0066
0067 ioctl(2)
0068 Initiate various actions. Some take immediate effect, others
0069 are performed asynchronously while or after the ioctl returns.
0070 See the inline documentation in <linux/firewire-cdev.h> for
0071 descriptions of all ioctls.
0072
0073 poll(2), select(2), epoll_wait(2) etc.
0074 Watch for events to become available to be read.
0075
0076 read(2)
0077 Receive various events. There are solicited events like
0078 outbound asynchronous transaction completion or isochronous
0079 buffer completion, and unsolicited events such as bus resets,
0080 request reception, or PHY packet reception. Always use a read
0081 buffer which is large enough to receive the largest event that
0082 could ever arrive. See <linux/firewire-cdev.h> for descriptions
0083 of all event types and for which ioctls affect reception of
0084 events.
0085
0086 mmap(2)
0087 Allocate a DMA buffer for isochronous reception or transmission
0088 and map it into the process address space. The arguments should
0089 be used as follows: addr = NULL, length = the desired buffer
0090 size, i.e. number of packets times size of largest packet,
0091 prot = at least PROT_READ for reception and at least PROT_WRITE
0092 for transmission, flags = MAP_SHARED, fd = the handle to the
0093 /dev/fw*, offset = 0.
0094
0095 Isochronous reception works in packet-per-buffer fashion except
0096 for multichannel reception which works in buffer-fill mode.
0097
0098 munmap(2)
0099 Unmap the isochronous I/O buffer from the process address space.
0100
0101 close(2)
0102 Besides stopping and freeing I/O contexts that were associated
0103 with the file descriptor, back out any changes to the local
0104 nodes' Configuration ROM. Deallocate isochronous channels and
0105 bandwidth at the IRM that were marked for kernel-assisted
0106 re- and deallocation.
0107
0108 Users: libraw1394;
0109 libdc1394;
0110 libhinawa;
0111 tools like linux-firewire-utils, fwhack, ...
