aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/ABI
diff options
context:
space:
mode:
authorStefan Richter <stefanr@s5r6.in-berlin.de>2011-07-14 15:08:39 -0400
committerStefan Richter <stefanr@s5r6.in-berlin.de>2011-07-16 01:24:32 -0400
commitf6a7cd0212c359f7b55414aeee364ee7cac363cc (patch)
treef7d75b8040c69f21b8b1ffcbbde762c5636cac37 /Documentation/ABI
parent93b37905f70083d6143f5f4dba0a45cc64379a62 (diff)
firewire: cdev: ABI documentation enhancements
Add overview documentation in Documentation/ABI/stable/firewire-cdev. Improve the inline reference documentation in firewire-cdev.h: - Add /* available since kernel... */ comments to event numbers consistent with the comments on ioctl numbers. - Shorten some documentation on an event and an ioctl that are less interesting to current programming because there are newer preferable variants. - Spell Configuration ROM (name of an IEEE 1212 register) in upper case. - Move the dummy FW_CDEV_VERSION out of the reader's field of vision. We should remove it from the header next year or so. Signed-off-by: Stefan Richter <stefanr@s5r6.in-berlin.de>
Diffstat (limited to 'Documentation/ABI')
-rw-r--r--Documentation/ABI/stable/firewire-cdev103
1 files changed, 103 insertions, 0 deletions
diff --git a/Documentation/ABI/stable/firewire-cdev b/Documentation/ABI/stable/firewire-cdev
new file mode 100644
index 000000000000..16d030827368
--- /dev/null
+++ b/Documentation/ABI/stable/firewire-cdev
@@ -0,0 +1,103 @@
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, ...