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 核心

目錄

本頁