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