mirror of
https://github.com/edk2-porting/linux-next.git
synced 2024-12-27 06:34:11 +08:00
f6a7cd0212
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>
104 lines
4.0 KiB
Plaintext
104 lines
4.0 KiB
Plaintext
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, ...
|