Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/ieee1394/linux1394-2.6

* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/ieee1394/linux1394-2.6:
  firewire: document the sysfs ABIs
  firewire: cdev: ABI documentation enhancements
  firewire: cdev: prevent race between first get_info ioctl and bus reset event queuing
  firewire: cdev: return -ENOTTY for unimplemented ioctls, not -EINVAL
  firewire: ohci: skip soft reset retries after card ejection
  firewire: ohci: fix PHY reg access after card ejection
  firewire: ohci: add a comment on PHY reg access serialization
  firewire: ohci: reduce potential context_stop latency
  firewire: ohci: remove superfluous posted write flushes
  firewire: net: replacing deprecated __attribute__((packed)) with __packed

6 files changed, 303 insertions, 67 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 @@
+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, ...
diff --git a/Documentation/ABI/stable/sysfs-bus-firewire b/Documentation/ABI/stable/sysfs-bus-firewire
new file mode 100644
index 000000000000..3d484e5dc846
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-bus-firewire
@@ -0,0 +1,122 @@
+What:           /sys/bus/firewire/devices/fw[0-9]+/
+Date:           May 2007
+KernelVersion:  2.6.22
+Contact:        linux1394-devel@lists.sourceforge.net
+Description:
+                IEEE 1394 node device attributes.
+                Read-only.  Mutable during the node device's lifetime.
+                See IEEE 1212 for semantic definitions.
+
+                config_rom
+                        Contents of the Configuration ROM register.
+                        Binary attribute; an array of host-endian u32.
+
+                guid
+                        The node's EUI-64 in the bus information block of
+                        Configuration ROM.
+                        Hexadecimal string representation of an u64.
+
+
+What:           /sys/bus/firewire/devices/fw[0-9]+/units
+Date:           June 2009
+KernelVersion:  2.6.31
+Contact:        linux1394-devel@lists.sourceforge.net
+Description:
+                IEEE 1394 node device attribute.
+                Read-only.  Mutable during the node device's lifetime.
+                See IEEE 1212 for semantic definitions.
+
+                units
+                        Summary of all units present in an IEEE 1394 node.
+                        Contains space-separated tuples of specifier_id and
+                        version of each unit present in the node.  Specifier_id
+                        and version are hexadecimal string representations of
+                        u24 of the respective unit directory entries.
+                        Specifier_id and version within each tuple are separated
+                        by a colon.
+
+Users:          udev rules to set ownership and access permissions or ACLs of
+                /dev/fw[0-9]+ character device files
+
+
+What:           /sys/bus/firewire/devices/fw[0-9]+[.][0-9]+/
+Date:           May 2007
+KernelVersion:  2.6.22
+Contact:        linux1394-devel@lists.sourceforge.net
+Description:
+                IEEE 1394 unit device attributes.
+                Read-only.  Immutable during the unit device's lifetime.
+                See IEEE 1212 for semantic definitions.
+
+                modalias
+                        Same as MODALIAS in the uevent at device creation.
+
+                rom_index
+                        Offset of the unit directory within the parent device's
+                        (node device's) Configuration ROM, in quadlets.
+                        Decimal string representation.
+
+
+What:           /sys/bus/firewire/devices/*/
+Date:           May 2007
+KernelVersion:  2.6.22
+Contact:        linux1394-devel@lists.sourceforge.net
+Description:
+                Attributes common to IEEE 1394 node devices and unit devices.
+                Read-only.  Mutable during the node device's lifetime.
+                Immutable during the unit device's lifetime.
+                See IEEE 1212 for semantic definitions.
+
+                These attributes are only created if the root directory of an
+                IEEE 1394 node or the unit directory of an IEEE 1394 unit
+                actually contains according entries.
+
+                hardware_version
+                        Hexadecimal string representation of an u24.
+
+                hardware_version_name
+                        Contents of a respective textual descriptor leaf.
+
+                model
+                        Hexadecimal string representation of an u24.
+
+                model_name
+                        Contents of a respective textual descriptor leaf.
+
+                specifier_id
+                        Hexadecimal string representation of an u24.
+                        Mandatory in unit directories according to IEEE 1212.
+
+                vendor
+                        Hexadecimal string representation of an u24.
+                        Mandatory in the root directory according to IEEE 1212.
+
+                vendor_name
+                        Contents of a respective textual descriptor leaf.
+
+                version
+                        Hexadecimal string representation of an u24.
+                        Mandatory in unit directories according to IEEE 1212.
+
+
+What:           /sys/bus/firewire/drivers/sbp2/fw*/host*/target*/*:*:*:*/ieee1394_id
+                formerly
+                /sys/bus/ieee1394/drivers/sbp2/fw*/host*/target*/*:*:*:*/ieee1394_id
+Date:           Feb 2004
+KernelVersion:  2.6.4
+Contact:        linux1394-devel@lists.sourceforge.net
+Description:
+                SCSI target port identifier and logical unit identifier of a
+                logical unit of an SBP-2 target.  The identifiers are specified
+                in SAM-2...SAM-4 annex A.  They are persistent and world-wide
+                unique properties the SBP-2 attached target.
+
+                Read-only attribute, immutable during the target's lifetime.
+                Format, as exposed by firewire-sbp2 since 2.6.22, May 2007:
+                Colon-separated hexadecimal string representations of
+                        u64 EUI-64 : u24 directory_ID : u16 LUN
+                without 0x prefixes, without whitespace.  The former sbp2 driver
+                (removed in 2.6.37 after being superseded by firewire-sbp2) used
+                a somewhat shorter format which was not as close to SAM.
+
+Users:          udev rules to create /dev/disk/by-id/ symlinks
diff --git a/drivers/firewire/core-cdev.c b/drivers/firewire/core-cdev.c
index b1c11775839c..e6ad3bb6c1a6 100644
--- a/drivers/firewire/core-cdev.c
+++ b/drivers/firewire/core-cdev.c
@@ -253,14 +253,11 @@ static int fw_device_op_open(struct inode *inode, struct file *file)
         init_waitqueue_head(&client->wait);
         init_waitqueue_head(&client->tx_flush_wait);
         INIT_LIST_HEAD(&client->phy_receiver_link);
+        INIT_LIST_HEAD(&client->link);
         kref_init(&client->kref);
 
         file->private_data = client;
 
-        mutex_lock(&device->client_list_mutex);
-        list_add_tail(&client->link, &device->client_list);
-        mutex_unlock(&device->client_list_mutex);
-
         return nonseekable_open(inode, file);
 }
 
@@ -451,15 +448,20 @@ static int ioctl_get_info(struct client *client, union ioctl_arg *arg)
         if (ret != 0)
                 return -EFAULT;
 
+        mutex_lock(&client->device->client_list_mutex);
+
         client->bus_reset_closure = a->bus_reset_closure;
         if (a->bus_reset != 0) {
                 fill_bus_reset_event(&bus_reset, client);
-                if (copy_to_user(u64_to_uptr(a->bus_reset),
-                                 &bus_reset, sizeof(bus_reset)))
-                        return -EFAULT;
+                ret = copy_to_user(u64_to_uptr(a->bus_reset),
+                                   &bus_reset, sizeof(bus_reset));
         }
+        if (ret == 0 && list_empty(&client->link))
+                list_add_tail(&client->link, &client->device->client_list);
 
-        return 0;
+        mutex_unlock(&client->device->client_list_mutex);
+
+        return ret ? -EFAULT : 0;
 }
 
 static int add_client_resource(struct client *client,
@@ -1583,7 +1585,7 @@ static int dispatch_ioctl(struct client *client,
         if (_IOC_TYPE(cmd) != '#' ||
             _IOC_NR(cmd) >= ARRAY_SIZE(ioctl_handlers) ||
             _IOC_SIZE(cmd) > sizeof(buffer))
-                return -EINVAL;
+                return -ENOTTY;
 
         if (_IOC_DIR(cmd) == _IOC_READ)
                 memset(&buffer, 0, _IOC_SIZE(cmd));
diff --git a/drivers/firewire/net.c b/drivers/firewire/net.c
index eced1c25bf58..03a7a85d0424 100644
--- a/drivers/firewire/net.c
+++ b/drivers/firewire/net.c
@@ -7,6 +7,7 @@
  */
 
 #include <linux/bug.h>
+#include <linux/compiler.h>
 #include <linux/delay.h>
 #include <linux/device.h>
 #include <linux/ethtool.h>
@@ -73,7 +74,7 @@ struct rfc2734_arp {
         __be32 fifo_lo;         /* lo 32bits of sender's FIFO addr      */
         __be32 sip;             /* Sender's IP Address                  */
         __be32 tip;             /* IP Address of requested hw addr      */
-} __attribute__((packed));
+} __packed;
 
 /* This header format is specific to this driver implementation. */
 #define FWNET_ALEN      8
@@ -81,7 +82,7 @@ struct rfc2734_arp {
 struct fwnet_header {
         u8 h_dest[FWNET_ALEN];  /* destination address */
         __be16 h_proto;         /* packet type ID field */
-} __attribute__((packed));
+} __packed;
 
 /* IPv4 and IPv6 encapsulation header */
 struct rfc2734_header {
diff --git a/drivers/firewire/ohci.c b/drivers/firewire/ohci.c
index ebb897329c1e..bcf792fac442 100644
--- a/drivers/firewire/ohci.c
+++ b/drivers/firewire/ohci.c
@@ -253,7 +253,6 @@ static inline struct fw_ohci *fw_ohci(struct fw_card *card)
 #define OHCI1394_MAX_PHYS_RESP_RETRIES  0x8
 
 #define OHCI1394_REGISTER_SIZE          0x800
-#define OHCI_LOOP_COUNT                 500
 #define OHCI1394_PCI_HCI_Control        0x40
 #define SELF_ID_BUF_SIZE                0x800
 #define OHCI_TCODE_PHY_PACKET           0x0e
@@ -514,6 +513,12 @@ static inline void flush_writes(const struct fw_ohci *ohci)
         reg_read(ohci, OHCI1394_Version);
 }
 
+/*
+ * Beware!  read_phy_reg(), write_phy_reg(), update_phy_reg(), and
+ * read_paged_phy_reg() require the caller to hold ohci->phy_reg_mutex.
+ * In other words, only use ohci_read_phy_reg() and ohci_update_phy_reg()
+ * directly.  Exceptions are intrinsically serialized contexts like pci_probe.
+ */
 static int read_phy_reg(struct fw_ohci *ohci, int addr)
 {
         u32 val;
@@ -522,6 +527,9 @@ static int read_phy_reg(struct fw_ohci *ohci, int addr)
         reg_write(ohci, OHCI1394_PhyControl, OHCI1394_PhyControl_Read(addr));
         for (i = 0; i < 3 + 100; i++) {
                 val = reg_read(ohci, OHCI1394_PhyControl);
+                if (!~val)
+                        return -ENODEV; /* Card was ejected. */
+
                 if (val & OHCI1394_PhyControl_ReadDone)
                         return OHCI1394_PhyControl_ReadData(val);
 
@@ -545,6 +553,9 @@ static int write_phy_reg(const struct fw_ohci *ohci, int addr, u32 val)
                   OHCI1394_PhyControl_Write(addr, val));
         for (i = 0; i < 3 + 100; i++) {
                 val = reg_read(ohci, OHCI1394_PhyControl);
+                if (!~val)
+                        return -ENODEV; /* Card was ejected. */
+
                 if (!(val & OHCI1394_PhyControl_WritePending))
                         return 0;
 
@@ -630,7 +641,6 @@ static void ar_context_link_page(struct ar_context *ctx, unsigned int index)
         ctx->last_buffer_index = index;
 
         reg_write(ctx->ohci, CONTROL_SET(ctx->regs), CONTEXT_WAKE);
-        flush_writes(ctx->ohci);
 }
 
 static void ar_context_release(struct ar_context *ctx)
@@ -1002,7 +1012,6 @@ static void ar_context_run(struct ar_context *ctx)
 
         reg_write(ctx->ohci, COMMAND_PTR(ctx->regs), ctx->descriptors_bus | 1);
         reg_write(ctx->ohci, CONTROL_SET(ctx->regs), CONTEXT_RUN);
-        flush_writes(ctx->ohci);
 }
 
 static struct descriptor *find_branch_descriptor(struct descriptor *d, int z)
@@ -1202,14 +1211,14 @@ static void context_stop(struct context *ctx)
 
         reg_write(ctx->ohci, CONTROL_CLEAR(ctx->regs), CONTEXT_RUN);
         ctx->running = false;
-        flush_writes(ctx->ohci);
 
-        for (i = 0; i < 10; i++) {
+        for (i = 0; i < 1000; i++) {
                 reg = reg_read(ctx->ohci, CONTROL_SET(ctx->regs));
                 if ((reg & CONTEXT_ACTIVE) == 0)
                         return;
 
-                mdelay(1);
+                if (i)
+                        udelay(10);
         }
         fw_error("Error: DMA context still active (0x%08x)\n", reg);
 }
@@ -1346,12 +1355,10 @@ static int at_context_queue_packet(struct context *ctx,
 
         context_append(ctx, d, z, 4 - z);
 
-        if (ctx->running) {
+        if (ctx->running)
                 reg_write(ohci, CONTROL_SET(ctx->regs), CONTEXT_WAKE);
-                flush_writes(ohci);
-        } else {
+        else
                 context_run(ctx, 0);
-        }
 
         return 0;
 }
@@ -1960,14 +1967,18 @@ static irqreturn_t irq_handler(int irq, void *data)
 
 static int software_reset(struct fw_ohci *ohci)
 {
+        u32 val;
         int i;
 
         reg_write(ohci, OHCI1394_HCControlSet, OHCI1394_HCControl_softReset);
+        for (i = 0; i < 500; i++) {
+                val = reg_read(ohci, OHCI1394_HCControlSet);
+                if (!~val)
+                        return -ENODEV; /* Card was ejected. */
 
-        for (i = 0; i < OHCI_LOOP_COUNT; i++) {
-                if ((reg_read(ohci, OHCI1394_HCControlSet) &
-                     OHCI1394_HCControl_softReset) == 0)
+                if (!(val & OHCI1394_HCControl_softReset))
                         return 0;
+
                 msleep(1);
         }
 
@@ -2197,7 +2208,9 @@ static int ohci_enable(struct fw_card *card,
                   OHCI1394_LinkControl_rcvPhyPkt);
 
         ar_context_run(&ohci->ar_request_ctx);
-        ar_context_run(&ohci->ar_response_ctx); /* also flushes writes */
+        ar_context_run(&ohci->ar_response_ctx);
+
+        flush_writes(ohci);
 
         /* We are ready to go, reset bus to finish initialization. */
         fw_schedule_bus_reset(&ohci->card, false, true);
@@ -3129,7 +3142,6 @@ static void ohci_flush_queue_iso(struct fw_iso_context *base)
                         &container_of(base, struct iso_context, base)->context;
 
         reg_write(ctx->ohci, CONTROL_SET(ctx->regs), CONTEXT_WAKE);
-        flush_writes(ctx->ohci);
 }
 
 static const struct fw_card_driver ohci_driver = {
diff --git a/include/linux/firewire-cdev.h b/include/linux/firewire-cdev.h
index 4ff09889c5c0..357dbfc2829e 100644
--- a/include/linux/firewire-cdev.h
+++ b/include/linux/firewire-cdev.h
@@ -30,10 +30,13 @@
 #include <linux/types.h>
 #include <linux/firewire-constants.h>
 
+/* available since kernel version 2.6.22 */
 #define FW_CDEV_EVENT_BUS_RESET                         0x00
 #define FW_CDEV_EVENT_RESPONSE                          0x01
 #define FW_CDEV_EVENT_REQUEST                           0x02
 #define FW_CDEV_EVENT_ISO_INTERRUPT                     0x03
+
+/* available since kernel version 2.6.30 */
 #define FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED            0x04
 #define FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED          0x05
 
@@ -120,24 +123,11 @@ struct fw_cdev_event_response {
 
 /**
  * struct fw_cdev_event_request - Old version of &fw_cdev_event_request2
- * @closure:    See &fw_cdev_event_common; set by %FW_CDEV_IOC_ALLOCATE ioctl
  * @type:       See &fw_cdev_event_common; always %FW_CDEV_EVENT_REQUEST
- * @tcode:      See &fw_cdev_event_request2
- * @offset:     See &fw_cdev_event_request2
- * @handle:     See &fw_cdev_event_request2
- * @length:     See &fw_cdev_event_request2
- * @data:       See &fw_cdev_event_request2
  *
  * This event is sent instead of &fw_cdev_event_request2 if the kernel or
- * the client implements ABI version <= 3.
- *
- * Unlike &fw_cdev_event_request2, the sender identity cannot be established,
- * broadcast write requests cannot be distinguished from unicast writes, and
- * @tcode of lock requests is %TCODE_LOCK_REQUEST.
- *
- * Requests to the FCP_REQUEST or FCP_RESPONSE register are responded to as
- * with &fw_cdev_event_request2, except in kernel 2.6.32 and older which send
- * the response packet of the client's %FW_CDEV_IOC_SEND_RESPONSE ioctl.
+ * the client implements ABI version <= 3.  &fw_cdev_event_request lacks
+ * essential information; use &fw_cdev_event_request2 instead.
  */
 struct fw_cdev_event_request {
         __u64 closure;
@@ -452,29 +442,31 @@ union fw_cdev_event {
  *                 %FW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL, and
  *                 %FW_CDEV_IOC_SET_ISO_CHANNELS
  */
-#define FW_CDEV_VERSION 3 /* Meaningless; don't use this macro. */
 
 /**
  * struct fw_cdev_get_info - General purpose information ioctl
  * @version:    The version field is just a running serial number.  Both an
  *              input parameter (ABI version implemented by the client) and
  *              output parameter (ABI version implemented by the kernel).
- *              A client must not fill in an %FW_CDEV_VERSION defined from an
- *              included kernel header file but the actual version for which
- *              the client was implemented.  This is necessary for forward
- *              compatibility.  We never break backwards compatibility, but
- *              may add more structs, events, and ioctls in later revisions.
- * @rom_length: If @rom is non-zero, at most rom_length bytes of configuration
+ *              A client shall fill in the ABI @version for which the client
+ *              was implemented.  This is necessary for forward compatibility.
+ * @rom_length: If @rom is non-zero, up to @rom_length bytes of Configuration
  *              ROM will be copied into that user space address.  In either
  *              case, @rom_length is updated with the actual length of the
- *              configuration ROM.
+ *              Configuration ROM.
  * @rom:        If non-zero, address of a buffer to be filled by a copy of the
- *              device's configuration ROM
+ *              device's Configuration ROM
  * @bus_reset:  If non-zero, address of a buffer to be filled by a
  *              &struct fw_cdev_event_bus_reset with the current state
  *              of the bus.  This does not cause a bus reset to happen.
  * @bus_reset_closure: Value of &closure in this and subsequent bus reset events
  * @card:       The index of the card this device belongs to
+ *
+ * The %FW_CDEV_IOC_GET_INFO ioctl is usually the very first one which a client
+ * performs right after it opened a /dev/fw* file.
+ *
+ * As a side effect, reception of %FW_CDEV_EVENT_BUS_RESET events to be read(2)
+ * is started by this ioctl.
  */
 struct fw_cdev_get_info {
         __u32 version;
@@ -612,7 +604,7 @@ struct fw_cdev_initiate_bus_reset {
  * @handle:     Handle to the descriptor, written by the kernel
  *
  * Add a descriptor block and optionally a preceding immediate key to the local
- * node's configuration ROM.
+ * node's Configuration ROM.
  *
  * The @key field specifies the upper 8 bits of the descriptor root directory
  * pointer and the @data and @length fields specify the contents. The @key
@@ -627,9 +619,9 @@ struct fw_cdev_initiate_bus_reset {
  * If successful, the kernel adds the descriptor and writes back a @handle to
  * the kernel-side object to be used for later removal of the descriptor block
  * and immediate key.  The kernel will also generate a bus reset to signal the
- * change of the configuration ROM to other nodes.
+ * change of the Configuration ROM to other nodes.
  *
- * This ioctl affects the configuration ROMs of all local nodes.
+ * This ioctl affects the Configuration ROMs of all local nodes.
  * The ioctl only succeeds on device files which represent a local node.
  */
 struct fw_cdev_add_descriptor {
@@ -641,13 +633,13 @@ struct fw_cdev_add_descriptor {
 };
 
 /**
- * struct fw_cdev_remove_descriptor - Remove contents from the configuration ROM
+ * struct fw_cdev_remove_descriptor - Remove contents from the Configuration ROM
  * @handle:     Handle to the descriptor, as returned by the kernel when the
  *              descriptor was added
  *
  * Remove a descriptor block and accompanying immediate key from the local
- * nodes' configuration ROMs.  The kernel will also generate a bus reset to
- * signal the change of the configuration ROM to other nodes.
+ * nodes' Configuration ROMs.  The kernel will also generate a bus reset to
+ * signal the change of the Configuration ROM to other nodes.
  */
 struct fw_cdev_remove_descriptor {
         __u32 handle;
@@ -863,13 +855,8 @@ struct fw_cdev_stop_iso {
  * @local_time:   system time, in microseconds since the Epoch
  * @cycle_timer:  Cycle Time register contents
  *
- * The %FW_CDEV_IOC_GET_CYCLE_TIMER ioctl reads the isochronous cycle timer
- * and also the system clock (%CLOCK_REALTIME).  This allows to express the
- * receive time of an isochronous packet as a system time.
- *
- * @cycle_timer consists of 7 bits cycleSeconds, 13 bits cycleCount, and
- * 12 bits cycleOffset, in host byte order.  Cf. the Cycle Time register
- * per IEEE 1394 or Isochronous Cycle Timer register per OHCI-1394.
+ * Same as %FW_CDEV_IOC_GET_CYCLE_TIMER2, but fixed to use %CLOCK_REALTIME
+ * and only with microseconds resolution.
  *
  * In version 1 and 2 of the ABI, this ioctl returned unreliable (non-
  * monotonic) @cycle_timer values on certain controllers.
@@ -886,10 +873,17 @@ struct fw_cdev_get_cycle_timer {
  * @clk_id:       input parameter, clock from which to get the system time
  * @cycle_timer:  Cycle Time register contents
  *
- * The %FW_CDEV_IOC_GET_CYCLE_TIMER2 works like
- * %FW_CDEV_IOC_GET_CYCLE_TIMER but lets you choose a clock like with POSIX'
- * clock_gettime function.  Supported @clk_id values are POSIX' %CLOCK_REALTIME
- * and %CLOCK_MONOTONIC and Linux' %CLOCK_MONOTONIC_RAW.
+ * The %FW_CDEV_IOC_GET_CYCLE_TIMER2 ioctl reads the isochronous cycle timer
+ * and also the system clock.  This allows to correlate reception time of
+ * isochronous packets with system time.
+ *
+ * @clk_id lets you choose a clock like with POSIX' clock_gettime function.
+ * Supported @clk_id values are POSIX' %CLOCK_REALTIME and %CLOCK_MONOTONIC
+ * and Linux' %CLOCK_MONOTONIC_RAW.
+ *
+ * @cycle_timer consists of 7 bits cycleSeconds, 13 bits cycleCount, and
+ * 12 bits cycleOffset, in host byte order.  Cf. the Cycle Time register
+ * per IEEE 1394 or Isochronous Cycle Timer register per OHCI-1394.
  */
 struct fw_cdev_get_cycle_timer2 {
         __s64 tv_sec;
@@ -1011,4 +1005,6 @@ struct fw_cdev_receive_phy_packets {
         __u64 closure;
 };
 
+#define FW_CDEV_VERSION 3 /* Meaningless legacy macro; don't use it. */
+
 #endif /* _LINUX_FIREWIRE_CDEV_H */