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:        [email protected]
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: 由于 i386 架构的 System V ABI 中 8 字节的对象类型使用 4 字节对齐，因此填充以保持结构的大小为各种架构中 8 的倍数。
data: 有效负载数据（如果有）

描述

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

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

request_tstamp 的值表示发送请求以启动事务的同步循环。response_tstamp 的值表示响应到达以完成事务的同步循环。每个值都是一个 16 位无符号整数，其中包含 CYCLE_TIMER 寄存器格式的第二个字段的三个低位和循环字段的所有 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: 由于 i386 架构的 System V ABI 中 8 字节的对象类型使用 4 字节对齐，因此填充以保持结构的大小为各种架构中 8 的倍数。
data: 传入数据（如果有）

描述

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

携带数据的请求（写入和锁定请求）的有效负载数据会紧随其后，并且可以通过 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 的相应字段不同。

destination_node_id 可能也会与当前节点 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 位表示 CYCLE_TIME 寄存器格式中第二个字段的低 3 位，其余 13 位表示周期字段。

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
周期: 最后一个完成的数据包的周期计数器
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 字段中返回。每个数据包的标头数据量由 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 等时数据包标头的格式：16 位 data_length、2 位 tag、6 位 channel、4 位 tcode、4 位 sy，采用大端字节序。data_length 是数据包的实际接收大小，不包括 1394 等时数据包标头的四个字节。

时间戳的格式：16 位无效位、3 位 cycleSeconds、13 位 cycleCount，采用大端字节序。

在 ABI 的版本 1 中，未插入时间戳四字；相反，如果 header_size > 4，则有效负载数据直接跟在 1394 是标头之后。自 ABI 版本 2 起，不再提供此 ABI 的版本 1 的行为。

struct fw_cdev_event_iso_interrupt_mc¶: 等时缓冲区块已完成

定义:

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
已完成: 接收缓冲区中的偏移量；此偏移量之前的数据有效

描述

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

缓冲区会按每个数据包连续填充以下数据

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

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

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

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

定义:

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 位表示第二个字段的低 3 位，其余 13 位表示 CYCLE_TIME 寄存器格式的周期字段。

对于 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 则有效

描述

供用户空间使用的方便联合体。可以将事件 read(2) 到适当对齐的字符缓冲区中，然后转换为此联合体以进行进一步处理。请注意，对于请求、响应或 iso_interrupt 事件，data[] 或 header[] 可能会使完整事件的大小大于 sizeof(union fw_cdev_event)。另请注意，如果您尝试将事件 read(2) 到一个不够大的缓冲区中，则不适合的数据将被丢弃，以便下一次 read(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: 版本字段只是一个运行序列号。既是输入参数（客户端实现的 ABI 版本）又是输出参数（内核实现的 ABI 版本）。客户端应填写客户端实现的 ABI version。这对于向前兼容性是必要的。
rom_length: 如果 rom 非零，则最多 rom_length 个字节的配置 ROM 将被复制到该用户空间地址。在任何一种情况下，rom_length 都会更新为配置 ROM 的实际长度。
rom: 如果非零，则指向要填充设备配置 ROM 副本的缓冲区的地址
bus_reset: 如果非零，则指向一个缓冲区的地址，该缓冲区将填充一个包含总线当前状态的 struct fw_cdev_event_bus_reset。这不会导致总线重置发生。
bus_reset_closure: 此事件和后续总线重置事件中 closure 的值
card: 此设备所属的卡的索引

描述

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

作为副作用，开始接收要 read(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: 如果非零，则是在指针之前插入的立即键
key: 根目录指针的高 8 位
data: 指向描述符块内容的用户空间指针
length: 描述符块数据的长度（以四字节组为单位）
handle: 描述符的句柄，由内核写入

描述

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

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

如果非 0，则 immediate 字段指定一个立即键，该键将插入到根目录指针之前。

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

如果成功，内核会添加描述符，并写回一个指向内核端对象的 handle，以便后续删除描述符块和立即键。内核还会生成总线复位信号，以通知其他节点配置 ROM 的更改。

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

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

定义:

struct fw_cdev_remove_descriptor {
    __u32 handle;
};

成员

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

描述

从本地节点的配置 ROM 中删除描述符块和随附的立即键。内核还会生成总线复位信号，以通知其他节点配置 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 位）、标签字段（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;
};

成员

packets: 指向 fw_cdev_iso_packet 数组的用户空间指针
data: 指向 mmap() 映射的有效负载缓冲区的指针
size: 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;
};

成员

周期: 启动 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 的周期时间寄存器或 OHCI-1394 的等时周期定时器寄存器。

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 激活发布 FW_CDEV_EVENT_PHY_PACKET_RECEIVED 或 FW_CDEV_EVENT_PHY_PACKET_RECEIVED2，因为来自与设备位于同一总线上的任何节点的传入 PHY 数据包。

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

Firewire 设备探测和 sysfs 接口¶

What:           /sys/bus/firewire/devices/fw[0-9]+/
Date:           May 2007
KernelVersion:  2.6.22
Contact:        [email protected]
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:        [email protected]
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:        [email protected]
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:        [email protected]
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:        [email protected]
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:        [email protected]
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。

除非 length <= 8 或本地（环回）请求，否则 data 处的有效负载缓冲区将被 DMA 映射。因此，请确保缓冲区符合流式 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() 可能比请求数据包实际到达网络上的时间早得多完成。另一方面，事务完成，因此 callback 的执行甚至可能在 fw_send_request() 返回之前发生。

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。）分配或释放指定数量的带宽分配单元。

如果没有分配或释放通道，则返回通道 < 0。如果没有分配或释放带宽，则返回带宽 = 0。

如果代数过时，则释放操作会成功，但分配操作会失败，并返回 channel = -EAGAIN。

如果通道分配失败，则也不会分配带宽。如果带宽分配失败，则也不会分配通道。但是，通道和带宽的释放会尝试独立于彼此的成功。

Linux 内核

目录

本页