Firewire (IEEE 1394) 驱动程序接口指南¶

简介和概述¶

Linux FireWire 子系统在 Linux 系统中添加了一些接口，用于: 使用/维护+IEEE 1394 总线上的任何资源。

这些接口的主要目的是通过 ISO/IEC 13213 (IEEE 1212) 程序访问 IEEE 1394 总线上每个节点上的地址空间，并通过 IEEE 1394 程序控制总线上的等时资源。

根据接口的使用者，添加了两种类型的接口。一组用户空间接口可通过 firewire 字符设备获得。一组内核接口可通过 firewire-core 模块中导出的符号获得。

Firewire 字符设备数据结构¶

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;
                libhinawa;
                tools like linux-firewire-utils, fwhack, ...

struct fw_cdev_event_common¶: 所有 fw_cdev_event_* 类型的公共部分

定义:

struct fw_cdev_event_common {
    __u64 closure;
    __u32 type;
};

成员

closure: 供用户空间任意使用
type: 区分 fw_cdev_event_* 类型

描述

此结构可用于访问所有 fw_cdev_event_* 类型的通用成员，而无需考虑特定类型。

请求中在 closure 字段中传递的数据将在相应的事件中返回。它足够大，可以在所有平台上保存一个指针。用于设置 closure 的 ioctl 取决于事件的 type。

struct fw_cdev_event_bus_reset¶: 总线复位发生时发送

定义:

struct fw_cdev_event_bus_reset {
    __u64 closure;
    __u32 type;
    __u32 node_id;
    __u32 local_node_id;
    __u32 bm_node_id;
    __u32 irm_node_id;
    __u32 root_node_id;
    __u32 generation;
};

成员

closure: 参见 fw_cdev_event_common；由 FW_CDEV_IOC_GET_INFO ioctl 设置
type: 参见 fw_cdev_event_common；始终为 FW_CDEV_EVENT_BUS_RESET
node_id: 此节点的新节点 ID
local_node_id: 本地节点的节点 ID，即控制器的节点 ID
bm_node_id: 总线管理器的节点 ID
irm_node_id: ISO 资源管理器的节点 ID
root_node_id: 根节点的节点 ID
generation: 新的总线代数

描述

当设备所属的总线经历总线复位时，将发送此事件。它提供有关新总线配置的信息，例如此设备的新节点 ID、新根 ID 等。

如果在总线复位后 bm_node_id 立即为 0xffff，则可以在总线管理器选择完成后通过 FW_CDEV_IOC_GET_INFO ioctl 重新读取。ABI 版本 < 4 的内核不设置 bm_node_id。

struct fw_cdev_event_response¶: 接收到响应数据包时发送

定义:

struct fw_cdev_event_response {
    __u64 closure;
    __u32 type;
    __u32 rcode;
    __u32 length;
    __u32 data[];
};

成员

closure: 参见 fw_cdev_event_common；由 FW_CDEV_IOC_SEND_REQUEST 或 FW_CDEV_IOC_SEND_BROADCAST_REQUEST 或 FW_CDEV_IOC_SEND_STREAM_PACKET ioctl 设置
type: 参见 fw_cdev_event_common；始终为 FW_CDEV_EVENT_RESPONSE
rcode: 远程节点返回的响应代码
length: 数据长度，即响应的有效负载大小（以字节为单位）
data: 有效负载数据（如果有）

描述

如果内核或客户端实现 ABI 版本 <= 5，则发送此事件以代替 fw_cdev_event_response。与 fw_cdev_event_response2 相比，它缺少时间戳字段。

struct fw_cdev_event_response2¶: 接收到响应数据包时发送

定义:

struct fw_cdev_event_response2 {
    __u64 closure;
    __u32 type;
    __u32 rcode;
    __u32 length;
    __u32 request_tstamp;
    __u32 response_tstamp;
    __u32 padding;
    __u32 data[];
};

成员

closure: 参见 fw_cdev_event_common；由 FW_CDEV_IOC_SEND_REQUEST 或 FW_CDEV_IOC_SEND_BROADCAST_REQUEST 或 FW_CDEV_IOC_SEND_STREAM_PACKET ioctl 设置
type: 参见 fw_cdev_event_common；始终为 FW_CDEV_EVENT_RESPONSE
rcode: 远程节点返回的响应代码
length: 数据长度，即响应的有效负载大小（以字节为单位）
request_tstamp: 发送请求的等时周期的时间戳。
response_tstamp: 发送响应的等时周期的时间戳。
padding: 填充，以保持结构的大小为各种体系结构中 8 的倍数，因为对于 i386 体系结构中的 System V ABI 的 8 字节对象类型使用 4 字节对齐。
data: 有效负载数据（如果有）

描述

当堆栈接收到对 FW_CDEV_IOC_SEND_REQUEST ioctl 发送的传出请求的响应时，将发送此事件。携带数据的响应（读取和锁定响应）的有效负载数据紧随其后，可以通过 data 字段访问。

事务结束后也会生成该事件，该事务不涉及响应数据包。这包括统一写入事务、广播写入事务和异步流数据包的传输。rcode 指示此类传输的成功或失败。

request_tstamp 的值表示发起事务的请求发送到的等时周期。response_tstamp 的值表示完成事务的响应到达的等时周期。每个值都是一个无符号的 16 位整数，包含周期计时器寄存器格式的 second 字段的低 3 位和 cycle 字段的所有 13 位。

struct fw_cdev_event_request¶: fw_cdev_event_request2 的旧版本

定义:

struct fw_cdev_event_request {
    __u64 closure;
    __u32 type;
    __u32 tcode;
    __u64 offset;
    __u32 handle;
    __u32 length;
    __u32 data[];
};

成员

closure: 参见 fw_cdev_event_common；由 FW_CDEV_IOC_ALLOCATE ioctl 设置
type: 参见 fw_cdev_event_common；始终为 FW_CDEV_EVENT_REQUEST
tcode: 传入请求的事务代码
offset: 进入每个节点的 48 位地址空间的偏移量
handle: 对内核端挂起请求的引用
length: 数据长度，即请求的有效负载大小（以字节为单位）
data: 传入数据（如果有）

描述

如果内核或客户端实现 ABI 版本 <= 3，则发送此事件以代替 fw_cdev_event_request2。fw_cdev_event_request 缺少基本信息；请改用 fw_cdev_event_request2。

struct fw_cdev_event_request2¶: 在传入对地址区域的请求时发送

定义:

struct fw_cdev_event_request2 {
    __u64 closure;
    __u32 type;
    __u32 tcode;
    __u64 offset;
    __u32 source_node_id;
    __u32 destination_node_id;
    __u32 card;
    __u32 generation;
    __u32 handle;
    __u32 length;
    __u32 data[];
};

成员

closure: 参见 fw_cdev_event_common；由 FW_CDEV_IOC_ALLOCATE ioctl 设置
type: 参见 fw_cdev_event_common；始终为 FW_CDEV_EVENT_REQUEST2
tcode: 传入请求的事务代码
offset: 进入每个节点的 48 位地址空间的偏移量
source_node_id: 发送方节点 ID
destination_node_id: 目标节点 ID
card: 请求来自的卡的索引
generation: 请求有效的总线代数
handle: 对内核端挂起请求的引用
length: 数据长度，即请求的有效负载大小（以字节为单位）
data: 传入数据（如果有）

描述

如果内核或客户端实现 ABI 版本 <= 5，则发送此事件以代替 fw_cdev_event_request3。与 fw_cdev_event_request3 相比，它缺少时间戳字段。

struct fw_cdev_event_request3¶: 在传入对地址区域的请求时发送

定义:

struct fw_cdev_event_request3 {
    __u64 closure;
    __u32 type;
    __u32 tcode;
    __u64 offset;
    __u32 source_node_id;
    __u32 destination_node_id;
    __u32 card;
    __u32 generation;
    __u32 handle;
    __u32 length;
    __u32 tstamp;
    __u32 padding;
    __u32 data[];
};

成员

closure: 参见 fw_cdev_event_common；由 FW_CDEV_IOC_ALLOCATE ioctl 设置
type: 参见 fw_cdev_event_common；始终为 FW_CDEV_EVENT_REQUEST2
tcode: 传入请求的事务代码
offset: 进入每个节点的 48 位地址空间的偏移量
source_node_id: 发送方节点 ID
destination_node_id: 目标节点 ID
card: 请求来自的卡的索引
generation: 请求有效的总线代数
handle: 对内核端挂起请求的引用
length: 数据长度，即请求的有效负载大小（以字节为单位）
tstamp: 请求到达的等时周期的时间戳。
padding: 填充，以保持结构的大小为各种体系结构中 8 的倍数，因为对于 i386 体系结构中的 System V ABI 的 8 字节对象类型使用 4 字节对齐。
data: 传入数据（如果有）

描述

当堆栈接收到对使用 FW_CDEV_IOC_ALLOCATE ioctl 注册的地址区域的传入请求时，将发送此事件。保证请求完全包含在指定的区域中。用户空间负责使用相同的 handle 通过 FW_CDEV_IOC_SEND_RESPONSE ioctl 发送响应。

携带数据的请求（写入和锁定请求）的有效负载数据紧随其后，可以通过 data 字段访问。

与 fw_cdev_event_request 不同，锁定请求的 tcode 是 firewire-core 特定的 TCODE_LOCK_MASK_SWAP...``TCODE_LOCK_VENDOR_DEPENDENT`` 之一，即对扩展事务代码进行编码。

card 可能与 fw_cdev_get_info.card 不同，因为请求是从 Linux 主机的所有卡接收的。source_node_id、destination_node_id 和 generation 与该卡有关。因此，目标节点 ID 和总线代数可能与上次 fw_cdev_event_bus_reset 的相应字段不同。

由于非本地总线 ID 部分或广播写入请求，destination_node_id 也可能与当前节点 ID 不同。请注意，即使在广播写入请求的情况下，客户端也必须调用 FW_CDEV_IOC_SEND_RESPONSE ioctl；然后，内核将释放内核端挂起的请求，但实际上不会发送响应数据包。

如果写入请求是针对 FCP_REQUEST 或 FCP_RESPONSE 的，则内核会在收到请求后立即发送写入响应；在这种情况下，客户端仍然必须调用 FW_CDEV_IOC_SEND_RESPONSE ioctl 以释放内核端挂起的请求，即使不会发送另一个响应。

如果客户端随后需要发起对 fw_cdev_event_request3 的发送方节点的请求，则它需要使用与卡索引、节点 ID 和出站请求的代数匹配的设备文件。

tstamp 是请求到达的等时周期。它是 16 位整数值，高 3 位表示周期时间寄存器格式的 second 字段的低 3 位，其余 13 位表示 cycle 字段。

struct fw_cdev_event_iso_interrupt¶: 等时数据包完成时发送

定义:

struct fw_cdev_event_iso_interrupt {
    __u64 closure;
    __u32 type;
    __u32 cycle;
    __u32 header_length;
    __u32 header[];
};

成员

closure: 参见 fw_cdev_event_common；由 FW_CDEV_CREATE_ISO_CONTEXT ioctl 设置
type: 参见 fw_cdev_event_common；始终为 FW_CDEV_EVENT_ISO_INTERRUPT
cycle: 上次完成的数据包的周期计数器
header_length: 以下标头的总长度（以字节为单位）
header: 剥离的标头（如果有）

描述

当控制器使用设置了 FW_CDEV_ISO_INTERRUPT 位的 fw_cdev_iso_packet 时，或者使用 FW_CDEV_IOC_FLUSH_ISO 显式请求时，或者当在没有设置中断位的情况下完成了太多数据包，以至于内核的 header 的内部缓冲区即将溢出时，会发送此事件。（在最后一种情况下，ABI 版本 < 5 会删除标头数据，直到下一个中断数据包。）

等时传输事件（上下文类型 FW_CDEV_ISO_CONTEXT_TRANSMIT）

在 ABI 的版本 3 和某些版本 2 的实现中，header_length 是 4 的倍数，并且 header 包含直到中断数据包的所有数据包的时间戳。时间戳的格式如下面针对等时接收所述。在 ABI 的版本 1 中，header_length 为 0。

等时接收事件（上下文类型 FW_CDEV_ISO_CONTEXT_RECEIVE）

在 header 字段中返回直到并包括中断数据包的所有数据包中剥离的标头。每个数据包的标头数据量由在 iso 上下文创建时通过 fw_cdev_create_iso_context.header_size 指定。

因此，_interrupt.header_length / _context.header_size 是在此中断事件中接收的数据包数。客户端现在可以根据此数据包数和客户端在 fw_cdev_queue_iso 中指定的缓冲区大小来迭代 mmap() 的 DMA 缓冲区。

自此 ABI 的版本 2 起，_interrupt.header 中每个数据包的部分由 1394 等时数据包标头组成，如果 fw_cdev_create_iso_context.header_size > 4，则后跟一个时间戳四字组，如果 fw_cdev_create_iso_context.header_size > 8，则后跟来自数据包有效负载的四字组。

1394 iso 数据包标头的格式：16 位 data_length、2 位 tag、6 位 channel、4 位 tcode、4 位 sy，以大端字节顺序排列。data_length 是数据包的实际接收大小，不包括四个 1394 iso 数据包标头字节。

时间戳的格式：16 位 invalid、3 位 cycleSeconds、13 位 cycleCount，以大端字节顺序排列。

在 ABI 的版本 1 中，未插入时间戳四字组；相反，如果 header_size > 4，则有效负载数据紧随 1394 iso 标头之后。自 ABI 版本 2 以来，ABI 的版本 1 的行为不再可用。

struct fw_cdev_event_iso_interrupt_mc¶: 完成了一个 iso 缓冲区块

定义:

struct fw_cdev_event_iso_interrupt_mc {
    __u64 closure;
    __u32 type;
    __u32 completed;
};

成员

closure: 参见 fw_cdev_event_common；由 FW_CDEV_CREATE_ISO_CONTEXT ioctl 设置
type: FW_CDEV_EVENT_ISO_INTERRUPT_MULTICHANNEL
completed: 进入接收缓冲区的偏移量；此偏移量之前的数据有效

描述

在多通道上下文（上下文类型 FW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL）中，对于已完全填充且设置了 FW_CDEV_ISO_INTERRUPT 位的 fw_cdev_iso_packet 缓冲区块，或在使用 FW_CDEV_IOC_FLUSH_ISO 显式请求时，将发送此事件。

缓冲区会持续填充以下数据，每个数据包

1394 iso 数据包标头（如 fw_cdev_event_iso_interrupt 中所述），但采用小端字节顺序，
数据包有效负载（采用大端字节顺序，如 1394 iso 数据包标头的 data_length 字段中所指定的字节数），
根据需要使用 0...3 个填充字节来对齐以下尾部四字组，
尾部四字组，包含接收时间戳（如 fw_cdev_event_iso_interrupt 中所述），但采用小端字节顺序。

因此，每个数据包的大小为 data_length（向上舍入为 4 的倍数）+ 8。处理数据时，在将越过 completed 偏移量的数据包之前停止。

缓冲区块末尾附近的数据包通常会溢出到下一个排队的缓冲区块中。客户端有责任检查此情况，从其各个部分组装一个被破坏的数据包，并且不要重新排队任何其中仍存在未读取的数据包部分的缓冲区块。

struct fw_cdev_event_iso_resource¶: 已分配或释放 ISO 资源

定义:

struct fw_cdev_event_iso_resource {
    __u64 closure;
    __u32 type;
    __u32 handle;
    __s32 channel;
    __s32 bandwidth;
};

成员

closure: 参见 fw_cdev_event_common；由``FW_CDEV_IOC_(DE)ALLOCATE_ISO_RESOURCE(_ONCE)`` ioctl 设置
type: FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED 或 FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED
handle: 可以取消分配已分配资源的引用
channel: （已）分配的等时通道（如果有）
bandwidth: （反）分配的带宽分配单元（如果有）

描述

在 IRM 处分配同步资源后，将发送 FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED 事件。客户端必须检查 channel 和 bandwidth 以确定分配是否实际成功。

在 IRM 处取消分配同步资源后，将发送 FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED 事件。当总线复位后自动重新分配失败时，也会发送此事件。

如果未（反）分配任何通道或重新分配失败，则 channel < 0。如果未（反）分配任何带宽或重新分配失败，则 bandwidth 为 0。

struct fw_cdev_event_phy_packet¶: 已发送或接收到 PHY 数据包

定义:

struct fw_cdev_event_phy_packet {
    __u64 closure;
    __u32 type;
    __u32 rcode;
    __u32 length;
    __u32 data[];
};

成员

closure: 参见 fw_cdev_event_common；由 FW_CDEV_IOC_SEND_PHY_PACKET 或 FW_CDEV_IOC_RECEIVE_PHY_PACKETS ioctl 设置
type: FW_CDEV_EVENT_PHY_PACKET_SENT 或 %..._RECEIVED
rcode: RCODE_...，指示传输成功或失败
length: 数据长度（以字节为单位）
data: FW_CDEV_IOC_RECEIVE_PHY_PACKETS 的传入数据。对于 FW_CDEV_IOC_SEND_PHY_PACKET，该字段在请求中具有相同的数据，因此长度为 8 个字节。

描述

如果内核或客户端实现 ABI 版本 <= 5，则发送此事件而不是 fw_cdev_event_phy_packet2。与 fw_cdev_event_phy_packet2 相比，它缺少时间戳字段。

struct fw_cdev_event_phy_packet2¶: 已发送或接收到带有时间戳的 PHY 数据包。

定义:

struct fw_cdev_event_phy_packet2 {
    __u64 closure;
    __u32 type;
    __u32 rcode;
    __u32 length;
    __u32 tstamp;
    __u32 data[];
};

成员

closure

参见 fw_cdev_event_common；由 FW_CDEV_IOC_SEND_PHY_PACKET 或 FW_CDEV_IOC_RECEIVE_PHY_PACKETS ioctl 设置

type

FW_CDEV_EVENT_PHY_PACKET_SENT2 或 FW_CDEV_EVENT_PHY_PACKET_RECEIVED2

rcode

RCODE_...，指示传输成功或失败

length

数据长度（以字节为单位）

tstamp

对于 FW_CDEV_EVENT_PHY_PACKET_RECEIVED2，是数据包到达的同步周期的时间戳。对于 FW_CDEV_EVENT_PHY_PACKET_SENT2 和非 ping 数据包，是发送数据包的同步周期的时间戳。对于 ping 数据包，是由 1394 OHCI 控制器测量的往返时间刻度计数。

对于 FW_CDEV_EVENT_PHY_PACKET_SENT2，是发送响应的同步周期的时间戳；对于 FW_CDEV_EVENT_PHY_PACKET_RECEIVED2，是请求到达的同步周期的时间戳。

data

传入数据

描述

如果 type 为 FW_CDEV_EVENT_PHY_PACKET_SENT2，则 length 为 8，并且 data 由两个要发送的 PHY 数据包四字组（主机字节顺序）组成。

如果 type 为 FW_CDEV_EVENT_PHY_PACKET_RECEIVED2，则 length 为 8，并且 data 由两个 PHY 数据包四字组（主机字节顺序）组成。

对于 FW_CDEV_EVENT_PHY_PACKET_RECEIVED2，tstamp 是数据包到达的同步周期。它是 16 位整数值，高 3 位表示 second 字段的低 3 位，其余 13 位表示 CYCLE_TIME 寄存器格式的 cycle 字段。

对于 FW_CDEV_EVENT_PHY_PACKET_SENT2，tstamp 的含义因是否发送 ping 数据包而异。如果不是 ping 数据包，则 tstamp 是发送数据包的同步周期，并使用与 FW_CDEV_EVENT_PHY_PACKET_SENT2 相同格式。如果是 ping 数据包，则 tstamp 用于由 1394 OHCI 控制器以 42.195 MHz 分辨率测量的往返时间。

union fw_cdev_event¶: fw_cdev_event_* 类型的便捷联合

定义:

union fw_cdev_event {
    struct fw_cdev_event_common             common;
    struct fw_cdev_event_bus_reset          bus_reset;
    struct fw_cdev_event_response           response;
    struct fw_cdev_event_request            request;
    struct fw_cdev_event_request2           request2;
    struct fw_cdev_event_iso_interrupt      iso_interrupt;
    struct fw_cdev_event_iso_interrupt_mc   iso_interrupt_mc;
    struct fw_cdev_event_iso_resource       iso_resource;
    struct fw_cdev_event_phy_packet         phy_packet;
    struct fw_cdev_event_request3           request3;
    struct fw_cdev_event_response2          response2;
    struct fw_cdev_event_phy_packet2        phy_packet2;
};

成员

common: 对所有类型有效
bus_reset: 如果 common.type == FW_CDEV_EVENT_BUS_RESET，则有效
response: 如果 common.type == FW_CDEV_EVENT_RESPONSE，则有效
request: 如果 common.type == FW_CDEV_EVENT_REQUEST，则有效
request2: 如果 common.type == FW_CDEV_EVENT_REQUEST2，则有效
iso_interrupt: 如果 common.type == FW_CDEV_EVENT_ISO_INTERRUPT，则有效
iso_interrupt_mc: 如果 common.type == FW_CDEV_EVENT_ISO_INTERRUPT_MULTICHANNEL，则有效
iso_resource: 如果 common.type == FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED 或 FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED，则有效
phy_packet: 如果 common.type == FW_CDEV_EVENT_PHY_PACKET_SENT 或 FW_CDEV_EVENT_PHY_PACKET_RECEIVED，则有效
request3: 如果 common.type == FW_CDEV_EVENT_REQUEST3，则有效
response2: 如果 common.type == FW_CDEV_EVENT_RESPONSE2，则有效
phy_packet2: 如果 common.type == FW_CDEV_EVENT_PHY_PACKET_SENT2 或 FW_CDEV_EVENT_PHY_PACKET_RECEIVED2，则有效

描述

方便用户空间使用的联合。可以将事件读入 (2) 适当对齐的字符缓冲区，然后强制转换为此联合以进行进一步处理。请注意，对于请求、响应或 iso_interrupt 事件，data[] 或 header[] 可能会使完整事件的大小大于 sizeof(union fw_cdev_event)。另请注意，如果您尝试将事件读入 (2) 不够大的缓冲区，则不适合的数据将被丢弃，以便下一次读入 (2) 返回新事件。

struct fw_cdev_get_info¶: 通用信息 ioctl

定义:

struct fw_cdev_get_info {
    __u32 version;
    __u32 rom_length;
    __u64 rom;
    __u64 bus_reset;
    __u64 bus_reset_closure;
    __u32 card;
};

成员

version: version 字段只是一个运行序列号。既是输入参数（客户端实现的 ABI 版本），又是输出参数（内核实现的 ABI 版本）。客户端应填写客户端实现的 ABI version。这对于向前兼容性是必需的。
rom_length: 如果 rom 非零，则会将最多 rom_length 字节的配置 ROM 复制到该用户空间地址。无论哪种情况，都会使用配置 ROM 的实际长度更新 rom_length。
rom: 如果非零，则为要由设备配置 ROM 副本填充的缓冲区的地址
bus_reset: 如果非零，则为要由带有总线当前状态的 struct fw_cdev_event_bus_reset 填充的缓冲区的地址。这不会导致发生总线复位。
bus_reset_closure: 此总线复位事件及后续总线复位事件中 closure 的值
card: 此设备所属的卡的索引

描述

FW_CDEV_IOC_GET_INFO ioctl 通常是客户端在打开 /dev/fw* 文件后立即执行的第一个 ioctl。

作为副作用，接收要读入 (2) 的 FW_CDEV_EVENT_BUS_RESET 事件由此 ioctl 启动。

struct fw_cdev_send_request¶: 发送异步请求数据包

定义:

struct fw_cdev_send_request {
    __u32 tcode;
    __u32 length;
    __u64 offset;
    __u64 closure;
    __u64 data;
    __u32 generation;
};

成员

tcode: 请求的事务代码
length: 传出负载的长度（以字节为单位）
offset: 目标节点中的 48 位偏移量
closure: 在响应事件中传递回用户空间
data: 指向负载的用户空间指针
generation: 数据包有效的总线世代

描述

向设备发送请求。此 ioctl 实现所有传出请求。四字组和块请求都将负载指定为指向 data 字段中数据的指针。事务完成后，内核会写回 fw_cdev_event_response 事件或 fw_cdev_event_response 事件。closure 字段在响应事件中传递回用户空间。

struct fw_cdev_send_response¶: 发送异步响应数据包

定义:

struct fw_cdev_send_response {
    __u32 rcode;
    __u32 length;
    __u64 data;
    __u32 handle;
};

成员

rcode: 由用户空间处理程序确定的响应代码
length: 传出负载的长度（以字节为单位）
data: 指向负载的用户空间指针
handle: 来自 fw_cdev_event_request 的句柄

描述

发送对传入请求的响应。通过使用 FW_CDEV_IOC_ALLOCATE ioctl 设置地址范围，用户空间可以侦听传入请求。传入请求将生成 FW_CDEV_EVENT_REQUEST，并且用户空间必须使用此 ioctl 发送回复。该事件具有指向内核端挂起事务的句柄，该句柄应与此 ioctl 一起使用。

struct fw_cdev_allocate¶: 在地址范围中分配 CSR

定义:

struct fw_cdev_allocate {
    __u64 offset;
    __u64 closure;
    __u32 length;
    __u32 handle;
    __u64 region_end;
};

成员

offset: 地址范围的起始偏移量
closure: 在请求事件中传递回用户空间
length: CSR 的长度（以字节为单位）
handle: 分配的句柄，由内核写入
region_end: 地址范围之上的第一个地址（在 ABI v4、2.6.36 中添加）

描述

在本地节点（控制器）上的 48 位地址空间中分配地址范围。这允许用户空间侦听偏移量在该地址范围内的请求。每次当内核接收到该范围内的请求时，将发出 fw_cdev_event_request2 事件。（如果内核或客户端实现 ABI 版本 <= 3，则将改为生成 fw_cdev_event_request。）

closure 字段在这些请求事件中传递回用户空间。handle 字段是一个输出参数，返回一个分配范围的句柄，用于以后取消分配该范围。

地址范围是在所有本地节点上分配的。地址分配是独占的，FCP 命令和响应寄存器除外。如果独占地址区域已在使用中，则 ioctl 将失败，并将 errno 设置为 EBUSY。

如果内核和客户端实现 ABI 版本 >= 4，则内核会在 [offset..**region_end**) 中查找大小为 length 的空闲位置，如果找到，则将新 CSR 的起始地址写回到 offset 中。即，offset 是输入和输出参数。如果不需要在这种更大的地址范围中自动放置 CSR，则客户端只需设置 region_end = offset + length 即可。

如果内核或客户端实现 ABI 版本 <= 3，则 region_end 将被忽略，并有效地假定为 offset + length。

region_end 仅存在于内核标头 >= 2.6.36 中。如有必要，例如可以通过 #ifdef FW_CDEV_EVENT_REQUEST2 进行测试。

struct fw_cdev_deallocate¶: 释放 CSR 地址范围或同步资源

定义:

struct fw_cdev_deallocate {
    __u32 handle;
};

成员

handle: 地址范围或 iso 资源的句柄，由内核在分配范围或资源时返回

struct fw_cdev_initiate_bus_reset¶: 启动总线复位

定义:

struct fw_cdev_initiate_bus_reset {
    __u32 type;
};

成员

type: FW_CDEV_SHORT_RESET 或 FW_CDEV_LONG_RESET

描述

为此设备所在的总线启动总线复位。总线复位可以是原始（长）总线复位，也可以是 1394a-2000 中引入的仲裁（短）总线复位。

ioctl 立即返回。随后的 fw_cdev_event_bus_reset 指示何时实际发生复位。由于 ABI v4，这可能比 ioctl 晚得多，因为内核会按照 IEEE 1394 总线管理规范确保后续总线复位之间存在缓冲期。

struct fw_cdev_add_descriptor¶: 将内容添加到本地节点的配置 ROM

定义:

struct fw_cdev_add_descriptor {
    __u32 immediate;
    __u32 key;
    __u64 data;
    __u32 length;
    __u32 handle;
};

成员

immediate: 如果非零，则为在指针之前插入的 immediate 键
key: 根目录指针的高 8 位
data: 指向描述符块内容的用户空间指针
length: 描述符块数据的长度（以四字组为单位）
handle: 描述符的句柄，由内核写入

描述

将描述符块和可选的前导 immediate 键添加到本地节点的配置 ROM。

key 字段指定描述符根目录指针的高 8 位，data 和 length 字段指定内容。key 的形式应为 0xXX000000。根目录条目的偏移量部分将由内核填写。

如果非 0，则 immediate 字段指定将在根目录指针之前插入的 immediate 键。

immediate、key 和 data 数组元素是 CPU 端序四字组。

如果成功，内核将添加描述符并写回指向内核端对象的 handle，该对象用于以后删除描述符块和 immediate 键。内核还将生成总线复位以向其他节点发出配置 ROM 更改的信号。

此 ioctl 会影响所有本地节点的配置 ROM。该 ioctl 仅在表示本地节点的设备文件上成功。

struct fw_cdev_remove_descriptor¶: 从配置 ROM 中删除内容

定义:

struct fw_cdev_remove_descriptor {
    __u32 handle;
};

成员

handle: 描述符的句柄，由内核在添加描述符时返回

描述

从本地节点的配置 ROM 中删除描述符块和随附的 immediate 键。内核还将生成总线复位以向其他节点发出配置 ROM 更改的信号。

struct fw_cdev_create_iso_context¶: 为同步 I/O 创建上下文

定义:

struct fw_cdev_create_iso_context {
    __u32 type;
    __u32 header_size;
    __u32 channel;
    __u32 speed;
    __u64 closure;
    __u32 handle;
};

成员

type: FW_CDEV_ISO_CONTEXT_TRANSMIT 或 FW_CDEV_ISO_CONTEXT_RECEIVE 或 FW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL
header_size: 在单通道接收中要剥离的标头大小
channel: 在单通道接收或传输中要绑定的通道
speed: 传输速度
closure: 在 fw_cdev_event_iso_interrupt 或 fw_cdev_event_iso_interrupt_multichannel 中返回
handle: 上下文的句柄，由内核写回

描述

在发送或接收同步 I/O 之前，必须创建一个上下文。上下文记录有关传输或接收配置的信息，通常映射到基础硬件资源。为发送或接收设置上下文。它绑定到特定的同步 channel。

在多通道接收的情况下，header_size 和 channel 将被忽略，通道由 FW_CDEV_IOC_SET_ISO_CHANNELS 选择。

对于 FW_CDEV_ISO_CONTEXT_RECEIVE 上下文，header_size 必须至少为 4，并且必须是 4 的倍数。在其他上下文类型中，它将被忽略。

speed 在接收上下文类型中被忽略。

如果成功创建上下文，则内核会写回上下文的句柄，该句柄必须传入以用于对该上下文的后续操作。

限制：每个 fd 最多可以创建一个 iso 上下文。所有用户空间和内核空间驱动程序一次可以在卡上创建的上下文总数是硬件限制，通常每个方向 4 或 8 个上下文，并且其中最多一个多通道接收上下文。

struct fw_cdev_set_iso_channels¶: 在多通道接收中选择通道

定义:

struct fw_cdev_set_iso_channels {
    __u64 channels;
    __u32 handle;
};

成员

channels: 要侦听的通道的位掩码
handle: 多通道接收上下文的句柄

描述

channels 是每个要侦听的通道 n 的 1ULL << n 的按位或运算结果。

如果 channels 中某个通道上已存在另一个接收上下文，则 ioctl 将失败，并将 errno EBUSY。在这种情况下，所有未占用通道的位掩码将在 channels 中返回。

struct fw_cdev_iso_packet¶: 同步数据包

定义:

struct fw_cdev_iso_packet {
    __u32 control;
    __u32 header[];
};

成员

control: 包含标头长度（最高 8 位）、sy 字段（4 位）、tag 字段（2 位）、同步标志或跳过标志（1 位）、中断标志（1 位）和负载长度（最低 16 位）
header: 传输上下文中的标头和负载。

描述

struct fw_cdev_iso_packet 用于描述同步数据包队列。使用 FW_CDEV_ISO_* 宏填充 control。在接收上下文的情况下，header 数组为空。

上下文类型 FW_CDEV_ISO_CONTEXT_TRANSMIT

control.HEADER_LENGTH 必须是 4 的倍数。它指定 header 中将添加到数据包负载之前的字节数。这些字节被复制到内核中，并且在 ioctl 返回后将无法访问。

control.SY 和 TAG 字段被复制到 iso 数据包标头。这些字段由 IEEE 1394a 和 IEC 61883-1 指定。

control.SKIP 标志指定在帧中不发送任何数据包。使用此标志时，除 control.INTERRUPT 之外的所有其他字段都必须为零。

当设置了 control.INTERRUPT 标志的数据包完成后，将发送 fw_cdev_event_iso_interrupt 事件。

上下文类型 FW_CDEV_ISO_CONTEXT_RECEIVE

control.HEADER_LENGTH 必须是上下文的 header_size 的倍数。如果 HEADER_LENGTH 大于上下文的 header_size，则为此条目排队多个数据包。

control.SY 和 TAG 字段将被忽略。

如果设置了 control.SYNC 标志，则上下文会丢弃所有数据包，直到接收到 sy 字段与 fw_cdev_start_iso.sync 匹配的数据包。

control.PAYLOAD_LENGTH 定义了每个数据包可以接收多少个有效载荷字节（除了已定义为头部并被剥离并在 fw_cdev_event_iso_interrupt 结构中返回的有效载荷四字节）。如果接收到更多字节，则额外的字节将被丢弃。如果接收到的字节更少，则有效载荷缓冲区中剩余的字节将不会被写入，即使是下一个数据包也不会。也就是说，在连续帧中接收到的数据包不一定在内存中是连续的。如果一个条目已排队多个数据包，则 PAYLOAD_LENGTH 将在它们之间平均分配。

当设置了 control.INTERRUPT 标志的数据包完成后，将发送一个 fw_cdev_event_iso_interrupt 事件。当条目的最后一个数据包完成后，该条目排队的多个接收数据包即完成。

上下文类型 FW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL

在这里，fw_cdev_iso_packet 更适合命名为 _iso_buffer_chunk，因为它指定了 mmap() 缓冲区的一个块，而要放入缓冲区块中的数据包的数量和对齐方式事先未知。

control.PAYLOAD_LENGTH 是缓冲区块的大小，并指定一个或多个数据包的头部、有效载荷、填充和尾部字节的空间。它必须是 4 的倍数。

control.HEADER_LENGTH、TAG 和 SY 被忽略。SYNC 的处理方式与单通道接收所述相同。

当设置了 control.INTERRUPT 标志的缓冲区块被完全填满时，将发送一个 fw_cdev_event_iso_interrupt_mc 事件。

struct fw_cdev_queue_iso¶: 为 I/O 排队同步数据包

定义:

struct fw_cdev_queue_iso {
    __u64 packets;
    __u64 data;
    __u32 size;
    __u32 handle;
};

成员

数据包: 指向 fw_cdev_iso_packet 数组的用户空间指针
data: 指向 mmap() 的有效载荷缓冲区的指针
大小: packets 数组的大小，以字节为单位
handle: 同步上下文句柄

描述

排队多个同步数据包用于接收或传输。此 ioctl 接受指向 fw_cdev_iso_packet 结构数组的指针，这些结构描述了如何从 mmap() 的连续有效载荷缓冲区区域传输或接收到该区域。作为传输数据包描述符的一部分，可以提供一系列头部，这些头部将在 DMA 期间添加到有效载荷之前。

内核可能会或可能不会排队所有数据包，但会将更新后的 packets、data 和 size 字段的值写回，因此可以轻松地重新提交 ioctl。

在多通道接收上下文的情况下，data 必须相对于缓冲区起始位置四字节对齐。

struct fw_cdev_start_iso¶: 启动同步传输或接收

定义:

struct fw_cdev_start_iso {
    __s32 cycle;
    __u32 sync;
    __u32 tags;
    __u32 handle;
};

成员

cycle: 启动 I/O 的周期。如果 cycle 大于或等于 0，则 I/O 将在该周期启动。
sync: 确定要等待的、设置了 FW_CDEV_ISO_SYNC 位的数据包的值
tags: 标签过滤器位掩码。仅对同步接收有效。确定将接受的数据包的标签值。使用 FW_CDEV_ISO_CONTEXT_MATCH_* 宏来设置 tags。
handle: 要在其中传输或接收的同步上下文句柄

struct fw_cdev_stop_iso¶: 停止同步传输或接收

定义:

struct fw_cdev_stop_iso {
    __u32 handle;
};

成员

handle: 要停止的同步上下文的句柄

struct fw_cdev_flush_iso¶: 刷新已完成的 iso 数据包

定义:

struct fw_cdev_flush_iso {
    __u32 handle;
};

成员

handle: 要刷新的同步上下文的句柄

描述

对于 FW_CDEV_ISO_CONTEXT_TRANSMIT 或 FW_CDEV_ISO_CONTEXT_RECEIVE 上下文，报告任何已完成的数据包。

对于 FW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL 上下文，如果接收缓冲区中的当前偏移量已更改，则报告该偏移量；这通常位于某些缓冲区块的中间。

由此 ioctl 生成的任何 FW_CDEV_EVENT_ISO_INTERRUPT 或 FW_CDEV_EVENT_ISO_INTERRUPT_MULTICHANNEL 事件都是同步发送的，即在返回此 ioctl 时，可以从文件描述符中读取。

struct fw_cdev_get_cycle_timer¶: 读取循环定时器寄存器

定义:

struct fw_cdev_get_cycle_timer {
    __u64 local_time;
    __u32 cycle_timer;
};

成员

local_time: 系统时间，自 Epoch 以来的微秒数
cycle_timer: 循环时间寄存器内容

描述

与 FW_CDEV_IOC_GET_CYCLE_TIMER2 相同，但固定为使用 CLOCK_REALTIME 且仅具有微秒分辨率。

在 ABI 的第 1 版和第 2 版中，此 ioctl 在某些控制器上返回不可靠（非单调）的 cycle_timer 值。

struct fw_cdev_get_cycle_timer2¶: 读取循环定时器寄存器

定义:

struct fw_cdev_get_cycle_timer2 {
    __s64 tv_sec;
    __s32 tv_nsec;
    __s32 clk_id;
    __u32 cycle_timer;
};

成员

tv_sec: 系统时间，以秒为单位
tv_nsec: 系统时间，子秒部分以纳秒为单位
clk_id: 输入参数，从中获取系统时钟的时钟
cycle_timer: 循环时间寄存器内容

描述

FW_CDEV_IOC_GET_CYCLE_TIMER2 ioctl 读取同步循环定时器和系统时钟。这允许将同步数据包的接收时间与系统时间相关联。

clk_id 允许您像使用 POSIX 的 clock_gettime 函数一样选择时钟。支持的 clk_id 值是 POSIX 的 CLOCK_REALTIME 和 CLOCK_MONOTONIC 以及 Linux 的 CLOCK_MONOTONIC_RAW。

cycle_timer 由 7 位 cycleSeconds、13 位 cycleCount 和 12 位 cycleOffset 组成，采用主机字节顺序。参见 IEEE 1394 的 Cycle Time 寄存器或 OHCI-1394 的 Isochronous Cycle Timer 寄存器。

struct fw_cdev_allocate_iso_resource¶: （取消）分配通道或带宽

定义:

struct fw_cdev_allocate_iso_resource {
    __u64 closure;
    __u64 channels;
    __u32 bandwidth;
    __u32 handle;
};

成员

closure: 在相应的 iso 资源事件中传递回用户空间
channels: 要（取消）分配的同步通道
bandwidth: 要（取消）分配的同步带宽单位
handle: 分配的句柄，由内核写入（仅在 FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE ioctl 的情况下有效）

描述

FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE ioctl 启动在同步资源管理器 (IRM) 处分配同步通道和/或同步带宽。仅分配 channels 中指定的一个通道。与 IRM 通信后，将发送一个 FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED，在事件数据中指示成功或失败。内核将在总线重置后自动重新分配资源。如果重新分配失败，将发送一个 FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED 事件。关闭文件描述符时，内核也会自动取消分配资源。

FW_CDEV_IOC_DEALLOCATE_ISO_RESOURCE ioctl 可用于启动取消分配上述分配的资源。一个 FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED 事件结束此操作。

FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE ioctl 是一种变体，它不进行自动重新分配或取消分配。一个 FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED 事件结束此操作，并在其数据中指示成功或失败。

FW_CDEV_IOC_DEALLOCATE_ISO_RESOURCE_ONCE ioctl 的工作方式类似于 FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE，只不过是释放资源而不是分配资源。一个 FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED 事件结束此操作。

总而言之，FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE 为 fd 或 handle 的生命周期分配 iso 资源。相反，FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE 为总线一代的持续时间分配 iso 资源。

channels 是一个主机字节序位域，其中最低有效位表示通道 0，最高有效位表示通道 63：对于每个通道 c，1ULL << c 是 (取消) 分配的候选通道。

bandwidth 以带宽分配单位表示，即以速度 S1600 发送一个四字节数据（有效载荷或头部数据）的时间。

struct fw_cdev_send_stream_packet¶: 发送异步流数据包

定义:

struct fw_cdev_send_stream_packet {
    __u32 length;
    __u32 tag;
    __u32 channel;
    __u32 sy;
    __u64 closure;
    __u64 data;
    __u32 generation;
    __u32 speed;
};

成员

length: 传出负载的长度（以字节为单位）
tag: 数据格式标签
channel: 要传输到的同步通道
sy: 同步代码
closure: 在响应事件中传递回用户空间
data: 指向负载的用户空间指针
generation: 数据包有效的总线世代
speed: 传输速度

描述

FW_CDEV_IOC_SEND_STREAM_PACKET ioctl 将异步流数据包发送到每个正在侦听指定通道的设备。内核写入 fw_cdev_event_response 事件或 fw_cdev_event_response2 事件，指示传输成功或失败。

struct fw_cdev_send_phy_packet¶: 发送 PHY 数据包

定义:

struct fw_cdev_send_phy_packet {
    __u64 closure;
    __u32 data[2];
    __u32 generation;
};

成员

closure: 在 PHY 数据包发送事件中传递回用户空间
data: PHY 数据包的第一个和第二个四字节
generation: 数据包有效的总线世代

描述

FW_CDEV_IOC_SEND_PHY_PACKET ioctl 将 PHY 数据包发送到与此设备位于同一卡上的所有节点。传输后，将生成 FW_CDEV_EVENT_PHY_PACKET_SENT 事件或 FW_CDEV_EVENT_PHY_PACKET_SENT 事件。

有效载荷 data[] 应以主机字节顺序指定。通常，data[1] 需要是 data[0] 的按位逆。VersaPHY 数据包是此规则的例外。

ioctl 仅允许在表示本地节点的设备文件上使用。

struct fw_cdev_receive_phy_packets¶: 启动 PHY 数据包的接收

定义:

struct fw_cdev_receive_phy_packets {
    __u64 closure;
};

成员

closure: 在 phy 数据包事件中传递回用户空间

描述

此 ioctl 激活由于来自与设备位于同一总线上的任何节点的传入 PHY 数据包而发出 FW_CDEV_EVENT_PHY_PACKET_RECEIVED 或 FW_CDEV_EVENT_PHY_PACKET_RECEIVED2。

ioctl 仅允许在表示本地节点的设备文件上使用。

Firewire 设备探测和 sysfs 接口¶

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]+/is_local
Date:           July 2012
KernelVersion:  3.6
Contact:        linux1394-devel@lists.sourceforge.net
Description:
                IEEE 1394 node device attribute.
                Read-only and immutable.
Values:         1: The sysfs entry represents a local node (a controller card).

                0: The sysfs entry represents a remote node.


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

int fw_csr_string(const u32 *directory, int key, char *buf, size_t size)¶: 从配置 ROM 读取字符串

参数

const u32 *directory: 例如，根目录或单元目录
int key: 前一个目录条目的键
char *buf: 字符串的放置位置
size_t size: buf 的大小，以字节为单位

描述

该字符串取自紧接在具有 key 的条目之后的最小 ASCII 文本描述符叶。该字符串以零结尾。将默默地截断过长的字符串，以使其及其零字节适合 size。

返回 strlen(buf) 或负错误代码。

Firewire 核心事务接口¶

void __fw_send_request(struct fw_card *card, struct fw_transaction *t, int tcode, int destination_id, int generation, int speed, unsigned long long offset, void *payload, size_t length, union fw_transaction_callback callback, bool with_tstamp, void *callback_data)¶: 提交一个请求数据包以进行传输，从而生成具有或不具有时间戳的响应子操作的回调。

参数

struct fw_card *card: 用于发送请求的接口
struct fw_transaction *t: 请求所属的事务实例
int tcode: 事务代码
int destination_id: 目标节点 ID，由 bus_ID 和 phy_ID 组成
int generation: 请求和响应有效的总线代
int speed: 传输速度
unsigned long long offset: 48 位宽的偏移量，指向目标地址空间
void *payload: 请求子操作的数据有效载荷
size_t length: 有效载荷的长度，以字节为单位
union fw_transaction_callback callback: 两个函数的联合，用于确定是否接收响应子操作的时间戳。
bool with_tstamp: 是否接收响应子操作的时间戳。
void *callback_data: 要传递给事务完成回调的数据

描述

将请求数据包提交到异步请求传输队列中。可以从原子上下文中调用。如果您更喜欢阻塞 API，请在使用 fw_run_transaction() 的上下文中调用，该上下文可以休眠。

对于锁定请求，请在 tcode 中指定 firewire-core 特定的 TCODE_ 常量之一，而不是 TCODE_LOCK_REQUEST。

确保 destination_id 中的值不早于 generation 中的值。否则，请求可能会发送到错误的节点。

对于异步流数据包，即 TCODE_STREAM_DATA，调用方需要使用 fw_stream_packet_destination_id() 合成 destination_id。然后，它将包含标签、通道和 sy 数据，而不是节点 ID。

data 处的有效载荷缓冲区将被 DMA 映射，除非 length <= 8 或本地（环回）请求。因此，请确保缓冲区符合流 DMA 映射 API 的限制。在调用 callback 之前，不得释放 payload。

对于没有有效载荷的请求类型，data 为 NULL，length 为 0。

成功或不成功地完成事务后，将调用 callback。其参数包括响应代码，响应代码是每个 IEEE 1394 的 rcode 之一，或者在发生内部错误的情况下，是 firewire-core 特定的 RCODE_SEND_ERROR。其他 firewire-core 特定的 rcode（RCODE_CANCELLED、RCODE_BUSY、RCODE_GENERATION、RCODE_NO_ACK）分别表示事务超时、繁忙的响应方、过时的请求生成或缺少 ACK。

请注意一些时序边界情况：fw_send_request() 可能会比请求数据包实际到达网络的时间早得多完成。另一方面，即使在 fw_send_request() 返回之前，也可能发生事务完成以及 callback 的执行。

int fw_run_transaction(struct fw_card *card, int tcode, int destination_id, int generation, int speed, unsigned long long offset, void *payload, size_t length)¶: 发送请求并休眠直到事务完成

参数

struct fw_card *card: 此请求的卡接口
int tcode: 事务代码
int destination_id: 目标节点 ID，由 bus_ID 和 phy_ID 组成
int generation: 请求和响应有效的总线代
int speed: 传输速度
unsigned long long offset: 48 位宽的偏移量，指向目标地址空间
void *payload: 请求子操作的数据有效载荷
size_t length: 有效载荷的长度，以字节为单位

描述

返回 RCODE。有关参数文档，请参见 fw_send_request()。与 fw_send_request() 不同，data 指向请求的有效载荷和/或响应的有效载荷。DMA 映射限制适用于 >= 8 字节的出站请求有效载荷，但不适用于入站响应有效载荷。

int fw_core_add_address_handler(struct fw_address_handler *handler, const struct fw_address_region *region)¶: 注册以接收传入的请求

参数

struct fw_address_handler *handler: 回调
const struct fw_address_region *region: IEEE 1212 节点空间地址范围内的区域

描述

region->start, ->end 和 handler->length 必须是四字节对齐的。

当接收到指定地址范围内的请求时，将调用指定的回调函数。传递给回调的参数提供特定请求的详细信息。

在进程上下文中调用。返回值：成功时为 0，否则为非零值。

处理程序的地址区域的起始偏移量由 fw_core_add_address_handler() 确定，并在 handler->offset 中返回。

地址分配是排他的，FCP 寄存器除外。

void fw_core_remove_address_handler(struct fw_address_handler *handler)¶: 注销地址处理程序

参数

struct fw_address_handler *handler: 回调

描述

在进程上下文中调用。

当 fw_core_remove_address_handler() 返回时，保证 handler->callback() 不再在任何 CPU 上运行。

void fw_send_response(struct fw_card *card, struct fw_request *request, int rcode)¶

为异步事务发送响应数据包。

参数

struct fw_card *card: 用于发送响应的接口。
struct fw_request *request: 事务的 FireWire 请求数据。
int rcode: 要发送的响应代码。

描述

将响应数据包提交到异步响应传输队列。当传输成功完成后，将会释放 request。

int fw_get_request_speed(struct fw_request *request)¶: 返回接收到 request 的速度

参数

struct fw_request *request: FireWire 请求数据

u32 fw_request_get_timestamp(const struct fw_request *request)¶: 获取请求的时间戳。

参数

const struct fw_request *request: 指向请求结构的不透明指针。

描述

获取 1394 OHCI 控制器接收到异步请求子操作的时间戳。时间戳由秒字段的低 3 位和同步周期时间寄存器的计数字段的全部 13 位组成。

返回

请求的时间戳。

const char *fw_rcode_string(int rcode)¶: 将 FireWire 结果代码转换为错误描述

参数

int rcode: 结果代码

FireWire 等时 I/O 接口¶

void fw_iso_context_schedule_flush_completions(struct fw_iso_context *ctx)¶: 调度工作项以处理等时上下文。

参数

struct fw_iso_context *ctx: 等时上下文

描述

在工作队列上调度一个工作项以处理等时上下文。当带有中断标志的排队数据包缓冲区完成时，工作程序会调用注册的回调函数，无论是在 IT 上下文中传输之后，还是在 IR 上下文中填充之后。当上下文中的标头缓冲区已满时，也会调用回调函数。如果需要在当前上下文中处理上下文，则可以使用 fw_iso_context_flush_completions()。

上下文

任何上下文。

int fw_iso_context_flush_completions(struct fw_iso_context *ctx)¶: 在当前进程上下文中处理等时上下文。

参数

struct fw_iso_context *ctx: 等时上下文

描述

在当前进程上下文中处理等时上下文。当带有中断标志的排队数据包缓冲区完成时，将调用注册的回调函数，无论是在 IT 上下文中传输之后，还是在 IR 上下文中填充之后。此外，也会为最后完成的数据包缓冲区调用回调函数。此外，当上下文中的标头缓冲区已满时，也会调用回调函数。如果需要异步处理上下文，则可以使用 fw_iso_context_schedule_flush_completions()。

上下文

进程上下文。可能由于 disable_work_sync() 而睡眠。

void fw_iso_resource_manage(struct fw_card *card, int generation, u64 channels_mask, int *channel, int *bandwidth, bool allocate)¶: 分配或取消分配通道和/或带宽

参数

struct fw_card *card: 此操作的卡接口
int generation: 总线代
u64 channels_mask: 通道分配的位掩码
int *channel: 用于返回通道分配结果的指针
int *bandwidth: 用于返回带宽分配结果的指针
bool allocate: 是否分配 (true) 或取消分配 (false)

描述

输入参数：card、generation、channels_mask、bandwidth、allocate 输出参数：channel、bandwidth

此函数在与 IRM 通信期间阻塞（睡眠）。

最多分配或取消分配 channels_mask 中的一个通道。 channels_mask 是一个位域，MSB 代表通道 63，LSB 代表通道 0。（注意，IRM 的 CHANNELS_AVAILABLE 是一个大端字节序位域，MSB 代表通道 0，LSB 代表通道 63。）分配或取消分配指定数量的带宽分配单元。

如果没有分配或取消分配通道，则返回 channel < 0。如果没有分配或取消分配带宽，则返回 bandwidth = 0。

如果 generation 过时，则取消分配成功，但分配失败，channel = -EAGAIN。

如果通道分配失败，也不会分配带宽。如果带宽分配失败，也不会分配通道。但是通道和带宽的取消分配会彼此独立尝试。

Linux 内核

目录

本页