firewire-cdev

  1What:		/dev/fw[0-9]+
  2Date:		May 2007
  3KernelVersion:	2.6.22
  4Contact:	linux1394-devel@lists.sourceforge.net
  5Description:
  6		The character device files /dev/fw* are the interface between
  7		firewire-core and IEEE 1394 device drivers implemented in
  8		userspace.  The ioctl(2)- and read(2)-based ABI is defined and
  9		documented in <linux/firewire-cdev.h>.
 10
 11		This ABI offers most of the features which firewire-core also
 12		exposes to kernelspace IEEE 1394 drivers.
 13
 14		Each /dev/fw* is associated with one IEEE 1394 node, which can
 15		be remote or local nodes.  Operations on a /dev/fw* file have
 16		different scope:
 17
 18		  - The 1394 node which is associated with the file:
 19
 20			  - Asynchronous request transmission
 21			  - Get the Configuration ROM
 22			  - Query node ID
 23			  - Query maximum speed of the path between this node
 24			    and local node
 25
 26		  - The 1394 bus (i.e. "card") to which the node is attached to:
 27
 28			  - Isochronous stream transmission and reception
 29			  - Asynchronous stream transmission and reception
 30			  - Asynchronous broadcast request transmission
 31			  - PHY packet transmission and reception
 32			  - Allocate, reallocate, deallocate isochronous
 33			    resources (channels, bandwidth) at the bus's IRM
 34			  - Query node IDs of local node, root node, IRM, bus
 35			    manager
 36			  - Query cycle time
 37			  - Bus reset initiation, bus reset event reception
 38
 39		  - All 1394 buses:
 40
 41			  - Allocation of IEEE 1212 address ranges on the local
 42			    link layers, reception of inbound requests to such
 43			    an address range, asynchronous response transmission
 44			    to inbound requests
 45			  - Addition of descriptors or directories to the local
 46			    nodes' Configuration ROM
 47
 48		Due to the different scope of operations and in order to let
 49		userland implement different access permission models, some
 50		operations are restricted to /dev/fw* files that are associated
 51		with a local node:
 52
 53			  - Addition of descriptors or directories to the local
 54			    nodes' Configuration ROM
 55			  - PHY packet transmission and reception
 56
 57		A /dev/fw* file remains associated with one particular node
 58		during its entire life time.  Bus topology changes, and hence
 59		node ID changes, are tracked by firewire-core.  ABI users do not
 60		need to be aware of topology.
 61
 62		The following file operations are supported:
 63
 64		open(2)
 65		    Currently the only useful flags are O_RDWR.
 66
 67		ioctl(2)
 68		    Initiate various actions.  Some take immediate effect, others
 69		    are performed asynchronously while or after the ioctl returns.
 70		    See the inline documentation in <linux/firewire-cdev.h> for
 71		    descriptions of all ioctls.
 72
 73		poll(2), select(2), epoll_wait(2) etc.
 74		    Watch for events to become available to be read.
 75
 76		read(2)
 77		    Receive various events.  There are solicited events like
 78		    outbound asynchronous transaction completion or isochronous
 79		    buffer completion, and unsolicited events such as bus resets,
 80		    request reception, or PHY packet reception.  Always use a read
 81		    buffer which is large enough to receive the largest event that
 82		    could ever arrive.  See <linux/firewire-cdev.h> for descriptions
 83		    of all event types and for which ioctls affect reception of
 84		    events.
 85
 86		mmap(2)
 87		    Allocate a DMA buffer for isochronous reception or transmission
 88		    and map it into the process address space.  The arguments should
 89		    be used as follows:  addr = NULL, length = the desired buffer
 90		    size, i.e. number of packets times size of largest packet,
 91		    prot = at least PROT_READ for reception and at least PROT_WRITE
 92		    for transmission, flags = MAP_SHARED, fd = the handle to the
 93		    /dev/fw*, offset = 0.
 94
 95		Isochronous reception works in packet-per-buffer fashion except
 96		for multichannel reception which works in buffer-fill mode.
 97
 98		munmap(2)
 99		    Unmap the isochronous I/O buffer from the process address space.
100
101		close(2)
102		    Besides stopping and freeing I/O contexts that were associated
103		    with the file descriptor, back out any changes to the local
104		    nodes' Configuration ROM.  Deallocate isochronous channels and
105		    bandwidth at the IRM that were marked for kernel-assisted
106		    re- and deallocation.
107
108Users:		libraw1394;
109		libdc1394;
110		libhinawa;
111		tools like linux-firewire-utils, fwhack, ...