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