Add the rt linux 4.1.3-rt3 as base

[kvmfornfv.git] / kernel / Documentation / ABI / stable / firewire-cdev

diff --git a/kernel/Documentation/ABI/stable/firewire-cdev b/kernel/Documentation/ABI/stable/firewire-cdev
new file mode 100644 (file)
index 0000000..16d0308
--- /dev/null
+++ b/kernel/Documentation/ABI/stable/firewire-cdev
@@ -0,0 +1,103 @@
+What:          /dev/fw[0-9]+
+Date:          May 2007
+KernelVersion: 2.6.22
+Contact:       linux1394-devel@lists.sourceforge.net
+Description:
+               The character device files /dev/fw* are the interface between
+               firewire-core and IEEE 1394 device drivers implemented in
+               userspace.  The ioctl(2)- and read(2)-based ABI is defined and
+               documented in <linux/firewire-cdev.h>.
+
+               This ABI offers most of the features which firewire-core also
+               exposes to kernelspace IEEE 1394 drivers.
+
+               Each /dev/fw* is associated with one IEEE 1394 node, which can
+               be remote or local nodes.  Operations on a /dev/fw* file have
+               different scope:
+                 - The 1394 node which is associated with the file:
+                         - Asynchronous request transmission
+                         - Get the Configuration ROM
+                         - Query node ID
+                         - Query maximum speed of the path between this node
+                           and local node
+                 - The 1394 bus (i.e. "card") to which the node is attached to:
+                         - Isochronous stream transmission and reception
+                         - Asynchronous stream transmission and reception
+                         - Asynchronous broadcast request transmission
+                         - PHY packet transmission and reception
+                         - Allocate, reallocate, deallocate isochronous
+                           resources (channels, bandwidth) at the bus's IRM
+                         - Query node IDs of local node, root node, IRM, bus
+                           manager
+                         - Query cycle time
+                         - Bus reset initiation, bus reset event reception
+                 - All 1394 buses:
+                         - Allocation of IEEE 1212 address ranges on the local
+                           link layers, reception of inbound requests to such
+                           an address range, asynchronous response transmission
+                           to inbound requests
+                         - Addition of descriptors or directories to the local
+                           nodes' Configuration ROM
+
+               Due to the different scope of operations and in order to let
+               userland implement different access permission models, some
+               operations are restricted to /dev/fw* files that are associated
+               with a local node:
+                         - Addition of descriptors or directories to the local
+                           nodes' Configuration ROM
+                         - PHY packet transmission and reception
+
+               A /dev/fw* file remains associated with one particular node
+               during its entire life time.  Bus topology changes, and hence
+               node ID changes, are tracked by firewire-core.  ABI users do not
+               need to be aware of topology.
+
+               The following file operations are supported:
+
+               open(2)
+               Currently the only useful flags are O_RDWR.
+
+               ioctl(2)
+               Initiate various actions.  Some take immediate effect, others
+               are performed asynchronously while or after the ioctl returns.
+               See the inline documentation in <linux/firewire-cdev.h> for
+               descriptions of all ioctls.
+
+               poll(2), select(2), epoll_wait(2) etc.
+               Watch for events to become available to be read.
+
+               read(2)
+               Receive various events.  There are solicited events like
+               outbound asynchronous transaction completion or isochronous
+               buffer completion, and unsolicited events such as bus resets,
+               request reception, or PHY packet reception.  Always use a read
+               buffer which is large enough to receive the largest event that
+               could ever arrive.  See <linux/firewire-cdev.h> for descriptions
+               of all event types and for which ioctls affect reception of
+               events.
+
+               mmap(2)
+               Allocate a DMA buffer for isochronous reception or transmission
+               and map it into the process address space.  The arguments should
+               be used as follows:  addr = NULL, length = the desired buffer
+               size, i.e. number of packets times size of largest packet,
+               prot = at least PROT_READ for reception and at least PROT_WRITE
+               for transmission, flags = MAP_SHARED, fd = the handle to the
+               /dev/fw*, offset = 0.
+
+               Isochronous reception works in packet-per-buffer fashion except
+               for multichannel reception which works in buffer-fill mode.
+
+               munmap(2)
+               Unmap the isochronous I/O buffer from the process address space.
+
+               close(2)
+               Besides stopping and freeing I/O contexts that were associated
+               with the file descriptor, back out any changes to the local
+               nodes' Configuration ROM.  Deallocate isochronous channels and
+               bandwidth at the IRM that were marked for kernel-assisted
+               re- and deallocation.
+
+Users:         libraw1394
+               libdc1394
+               tools like jujuutils, fwhack, ...