John Newlin | b744f44 | 2016-06-21 10:48:09 -0700 | [diff] [blame] | 1 | What: /dev/fw[0-9]+ |
| 2 | Date: May 2007 |
| 3 | KernelVersion: 2.6.22 |
| 4 | Contact: linux1394-devel@lists.sourceforge.net |
| 5 | Description: |
| 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 | |
| 101 | Users: libraw1394 |
| 102 | libdc1394 |
| 103 | tools like jujuutils, fwhack, ... |