Documentation/ABI/stable/firewire-cdev

   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
  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
 108 Users:          libraw1394;
 109                 libdc1394;
 110                 libhinawa;
 111                 tools like linux-firewire-utils, fwhack, ...