xiaomi-sm8450/android_kernel_xiaomi_sm8450
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

firewire: cdev: ABI documentation enhancements

Browse Source 
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>
This commit is contained in:
Stefan Richter
2011-07-14 21:08:39 +02:00
parent 93b37905f7
commit f6a7cd0212
2 changed files with 137 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
include/linux/firewire-cdev.h
View File

@@ -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,30 +442,29 @@ 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.
*/
@@ -615,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
@@ -630,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 {
@@ -644,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;
@@ -866,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.
@@ -889,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;
@@ -1014,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 */