diff options
author | Stefan Richter <stefanr@s5r6.in-berlin.de> | 2010-07-17 21:36:02 +0200 |
---|---|---|
committer | Stefan Richter <stefanr@s5r6.in-berlin.de> | 2010-07-23 13:36:27 +0200 |
commit | d505e6e87127d4dbdaa5d91561eed810c180ca23 (patch) | |
tree | 590f16144d1d125f745610baae4503e2e0ae8901 | |
parent | 18d0cdfd1a4cc9028c0ef80f94538b31541f8fe5 (diff) | |
download | op-kernel-dev-d505e6e87127d4dbdaa5d91561eed810c180ca23.zip op-kernel-dev-d505e6e87127d4dbdaa5d91561eed810c180ca23.tar.gz |
firewire: cdev: some clarifications to the API documentation
Response events:
- are generated on more occasions than their documentation claimed.
CSR allocation:
- An already occupied CSR can be determined from errno==EBUSY.
Bus resets:
- Note that FW_CDEV_IOC_INITIATE_BUS_RESET is nonblocking and that the
client is not required to observe a grace period since kernels
2.6.36+ will enforce it now (commit 02d37bed).
- The possible values of fw_cdev_initiate_bus_reset.type are listed in
the kerneldoc comment already.
- Clarify that an application that uses FW_CDEV_IOC_ADD_DESCRIPTOR and
FW_CDEV_IOC_REMOVE_DESCRIPTOR does not have to issue a bus reset.
Isochronous I/O contexts:
- At most one can be created per open file descriptor.
Signed-off-by: Stefan Richter <stefanr@s5r6.in-berlin.de>
-rw-r--r-- | include/linux/firewire-cdev.h | 33 |
1 files changed, 25 insertions, 8 deletions
diff --git a/include/linux/firewire-cdev.h b/include/linux/firewire-cdev.h index d31022b..fde9568 100644 --- a/include/linux/firewire-cdev.h +++ b/include/linux/firewire-cdev.h @@ -84,8 +84,9 @@ struct fw_cdev_event_bus_reset { /** * struct fw_cdev_event_response - Sent when a response packet was received - * @closure: See &fw_cdev_event_common; - * set by %FW_CDEV_IOC_SEND_REQUEST ioctl + * @closure: See &fw_cdev_event_common; set by %FW_CDEV_IOC_SEND_REQUEST + * or %FW_CDEV_IOC_SEND_BROADCAST_REQUEST + * or %FW_CDEV_IOC_SEND_STREAM_PACKET ioctl * @type: See &fw_cdev_event_common; always %FW_CDEV_EVENT_RESPONSE * @rcode: Response code returned by the remote node * @length: Data length, i.e. the response's payload size in bytes @@ -95,6 +96,11 @@ struct fw_cdev_event_bus_reset { * sent by %FW_CDEV_IOC_SEND_REQUEST ioctl. The payload data for responses * carrying data (read and lock responses) follows immediately and can be * accessed through the @data field. + * + * The event is also generated after conclusions of transactions that do not + * involve response packets. This includes unified write transactions, + * broadcast write transactions, and transmission of asynchronous stream + * packets. @rcode indicates success or failure of such transmissions. */ struct fw_cdev_event_response { __u64 closure; @@ -447,7 +453,9 @@ struct fw_cdev_send_response { * range to be used for later deallocation of the range. * * The address range is allocated on all local nodes. The address allocation - * is exclusive except for the FCP command and response registers. + * is exclusive except for the FCP command and response registers. If an + * exclusive address region is already in use, the ioctl fails with errno set + * to %EBUSY. */ struct fw_cdev_allocate { __u64 offset; @@ -475,9 +483,14 @@ struct fw_cdev_deallocate { * Initiate a bus reset for the bus this device is on. The bus reset can be * either the original (long) bus reset or the arbitrated (short) bus reset * introduced in 1394a-2000. + * + * The ioctl returns immediately. A subsequent &fw_cdev_event_bus_reset + * indicates when the reset actually happened. Since ABI v4, this may be + * considerably later than the ioctl because the kernel ensures a grace period + * between subsequent bus resets as per IEEE 1394 bus management specification. */ struct fw_cdev_initiate_bus_reset { - __u32 type; /* FW_CDEV_SHORT_RESET or FW_CDEV_LONG_RESET */ + __u32 type; }; /** @@ -501,9 +514,10 @@ struct fw_cdev_initiate_bus_reset { * * @immediate, @key, and @data array elements are CPU-endian quadlets. * - * 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. + * 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. * * This ioctl affects the configuration ROMs of all local nodes. * The ioctl only succeeds on device files which represent a local node. @@ -522,7 +536,8 @@ struct fw_cdev_add_descriptor { * descriptor was added * * Remove a descriptor block and accompanying immediate key from the local - * nodes' configuration ROMs. + * 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; @@ -554,6 +569,8 @@ struct fw_cdev_remove_descriptor { * * Note that the effect of a @header_size > 4 depends on * &fw_cdev_get_info.version, as documented at &fw_cdev_event_iso_interrupt. + * + * No more than one iso context can be created per fd. */ struct fw_cdev_create_iso_context { __u32 type; |