Firewire (IEEE 1394) driver Interface Guide¶
Introduction and Overview¶
- The Linux FireWire subsystem adds some interfaces into the Linux system to
use/maintain+any resource on IEEE 1394 bus.
The main purpose of these interfaces is to access address space on each nodeon IEEE 1394 bus by ISO/IEC 13213 (IEEE 1212) procedure, and to controlisochronous resources on the bus by IEEE 1394 procedure.
Two types of interfaces are added, according to consumers of the interface. Aset of userspace interfaces is available viafirewire character devices. A setof kernel interfaces is available via exported symbols infirewire-core module.
Firewire char device data structures¶
What: /dev/fw[0-9]+Date: May 2007KernelVersion: 2.6.22Contact: linux1394-devel@lists.sourceforge.netDescription: 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, ...
- structfw_cdev_event_common¶
Common part of all fw_cdev_event_* types
Definition:
struct fw_cdev_event_common { __u64 closure; __u32 type;};Members
closureFor arbitrary use by userspace
typeDiscriminates the fw_cdev_event_* types
Description
Thisstructmay be used to access generic members of all fw_cdev_event_*types regardless of the specific type.
Data passed in theclosure field for a request will be returned in thecorresponding event. It is big enough to hold a pointer on all platforms.The ioctl used to setclosure depends on thetype of event.
- structfw_cdev_event_bus_reset¶
Sent when a bus reset occurred
Definition:
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;};Members
closureSee
fw_cdev_event_common; set byFW_CDEV_IOC_GET_INFOioctltypeSee
fw_cdev_event_common; alwaysFW_CDEV_EVENT_BUS_RESETnode_idNew node ID of this node
local_node_idNode ID of the local node, i.e. of the controller
bm_node_idNode ID of the bus manager
irm_node_idNode ID of the iso resource manager
root_node_idNode ID of the root node
generationNew bus generation
Description
This event is sent when the bus the device belongs to goes through a busreset. It provides information about the new bus configuration, such asnew node ID for this device, new root ID, and others.
Ifbm_node_id is 0xffff right after bus reset it can be reread by anFW_CDEV_IOC_GET_INFO ioctl after bus manager selection was finished.Kernels with ABI version < 4 do not setbm_node_id.
- structfw_cdev_event_response¶
Sent when a response packet was received
Definition:
struct fw_cdev_event_response { __u64 closure; __u32 type; __u32 rcode; __u32 length; __u32 data[];};Members
closureSee
fw_cdev_event_common; set byFW_CDEV_IOC_SEND_REQUESTorFW_CDEV_IOC_SEND_BROADCAST_REQUESTorFW_CDEV_IOC_SEND_STREAM_PACKETioctltypeSee
fw_cdev_event_common; alwaysFW_CDEV_EVENT_RESPONSErcodeResponse code returned by the remote node
lengthData length, i.e. the response’s payload size in bytes
dataPayload data, if any
Description
This event is sent instead offw_cdev_event_response if the kernel or the client implementsABI version <= 5. It has the lack of time stamp field comparing tofw_cdev_event_response2.
- structfw_cdev_event_response2¶
Sent when a response packet was received
Definition:
struct fw_cdev_event_response2 { __u64 closure; __u32 type; __u32 rcode; __u32 length; __u32 request_tstamp; __u32 response_tstamp; __u32 padding; __u32 data[];};Members
closureSee
fw_cdev_event_common; set byFW_CDEV_IOC_SEND_REQUESTorFW_CDEV_IOC_SEND_BROADCAST_REQUESTorFW_CDEV_IOC_SEND_STREAM_PACKETioctltypeSee
fw_cdev_event_common; alwaysFW_CDEV_EVENT_RESPONSErcodeResponse code returned by the remote node
lengthData length, i.e. the response’s payload size in bytes
request_tstampThe time stamp of isochronous cycle at which the request was sent.
response_tstampThe time stamp of isochronous cycle at which the response was sent.
paddingPadding to keep the size of structure as multiples of 8 in various architecturessince 4 byte alignment is used for 8 byte of object type in System V ABI for i386architecture.
dataPayload data, if any
Description
This event is sent when the stack receives a response to an outgoing requestsent byFW_CDEV_IOC_SEND_REQUEST ioctl. The payload data for responsescarrying data (read and lock responses) follows immediately and can beaccessed through thedata field.
The event is also generated after conclusions of transactions that do notinvolve response packets. This includes unified write transactions,broadcast write transactions, and transmission of asynchronous streampackets.rcode indicates success or failure of such transmissions.
The value ofrequest_tstamp expresses the isochronous cycle at which the request was sent toinitiate the transaction. The value ofresponse_tstamp expresses the isochronous cycle at whichthe response arrived to complete the transaction. Each value is unsigned 16 bit integercontaining three low order bits of second field and all 13 bits of cycle field in format ofCYCLE_TIMER register.
- structfw_cdev_event_request¶
Old version of
fw_cdev_event_request2
Definition:
struct fw_cdev_event_request { __u64 closure; __u32 type; __u32 tcode; __u64 offset; __u32 handle; __u32 length; __u32 data[];};Members
closureSee
fw_cdev_event_common; set byFW_CDEV_IOC_ALLOCATEioctltypeSee
fw_cdev_event_common; alwaysFW_CDEV_EVENT_REQUESTtcodeTransaction code of the incoming request
offsetThe offset into the 48-bit per-node address space
handleReference to the kernel-side pending request
lengthData length, i.e. the request’s payload size in bytes
dataIncoming data, if any
Description
This event is sent instead offw_cdev_event_request2 if the kernel orthe client implements ABI version <= 3.fw_cdev_event_request lacksessential information; usefw_cdev_event_request2 instead.
- structfw_cdev_event_request2¶
Sent on incoming request to an address region
Definition:
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[];};Members
closureSee
fw_cdev_event_common; set byFW_CDEV_IOC_ALLOCATEioctltypeSee
fw_cdev_event_common; alwaysFW_CDEV_EVENT_REQUEST2tcodeTransaction code of the incoming request
offsetThe offset into the 48-bit per-node address space
source_node_idSender node ID
destination_node_idDestination node ID
cardThe index of the card from which the request came
generationBus generation in which the request is valid
handleReference to the kernel-side pending request
lengthData length, i.e. the request’s payload size in bytes
dataIncoming data, if any
Description
This event is sent instead offw_cdev_event_request3 if the kernel or the client implementsABI version <= 5. It has the lack of time stamp field comparing tofw_cdev_event_request3.
- structfw_cdev_event_request3¶
Sent on incoming request to an address region
Definition:
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[];};Members
closureSee
fw_cdev_event_common; set byFW_CDEV_IOC_ALLOCATEioctltypeSee
fw_cdev_event_common; alwaysFW_CDEV_EVENT_REQUEST2tcodeTransaction code of the incoming request
offsetThe offset into the 48-bit per-node address space
source_node_idSender node ID
destination_node_idDestination node ID
cardThe index of the card from which the request came
generationBus generation in which the request is valid
handleReference to the kernel-side pending request
lengthData length, i.e. the request’s payload size in bytes
tstampThe time stamp of isochronous cycle at which the request arrived.
paddingPadding to keep the size of structure as multiples of 8 in various architecturessince 4 byte alignment is used for 8 byte of object type in System V ABI for i386architecture.
dataIncoming data, if any
Description
This event is sent when the stack receives an incoming request to an addressregion registered using theFW_CDEV_IOC_ALLOCATE ioctl. The request isguaranteed to be completely contained in the specified region. Userspace isresponsible for sending the response byFW_CDEV_IOC_SEND_RESPONSE ioctl,using the samehandle.
The payload data for requests carrying data (write and lock requests)follows immediately and can be accessed through thedata field.
Unlikefw_cdev_event_request,tcode of lock requests is one of thefirewire-core specificTCODE_LOCK_MASK_SWAP...``TCODE_LOCK_VENDOR_DEPENDENT``,i.e. encodes the extended transaction code.
card may differ fromfw_cdev_get_info.card because requests are receivedfrom all cards of the Linux host.source_node_id,destination_node_id, andgeneration pertain to that card. Destination node ID and bus generation maytherefore differ from the corresponding fields of the lastfw_cdev_event_bus_reset.
destination_node_id may also differ from the current node ID because of anon-local bus ID part or in case of a broadcast write request. Note, aclient must call anFW_CDEV_IOC_SEND_RESPONSE ioctl even in case of abroadcast write request; the kernel will then release the kernel-side pendingrequest but will not actually send a response packet.
In case of a write request to FCP_REQUEST or FCP_RESPONSE, the kernel alreadysent a write response immediately after the request was received; in thiscase the client must still call anFW_CDEV_IOC_SEND_RESPONSE ioctl torelease the kernel-side pending request, though another response won’t besent.
If the client subsequently needs to initiate requests to the sender node ofanfw_cdev_event_request3, it needs to use a device file with matchingcard index, node ID, and generation for outbound requests.
tstamp is isochronous cycle at which the request arrived. It is 16 bit integer value and thehigher 3 bits expresses three low order bits of second field in the format of CYCLE_TIMEregister and the rest 13 bits expresses cycle field.
- structfw_cdev_event_iso_interrupt¶
Sent when an iso packet was completed
Definition:
struct fw_cdev_event_iso_interrupt { __u64 closure; __u32 type; __u32 cycle; __u32 header_length; __u32 header[];};Members
closureSee
fw_cdev_event_common;set byFW_CDEV_CREATE_ISO_CONTEXTioctltypeSee
fw_cdev_event_common; alwaysFW_CDEV_EVENT_ISO_INTERRUPTcycleCycle counter of the last completed packet
header_lengthTotal length of following headers, in bytes
headerStripped headers, if any
Description
This event is sent when the controller has completed anfw_cdev_iso_packetwith theFW_CDEV_ISO_INTERRUPT bit set, when explicitly requested withFW_CDEV_IOC_FLUSH_ISO, or when there have been so many completed packetswithout the interrupt bit set that the kernel’s internal buffer forheaderis about to overflow. (In the last case, ABI versions < 5 drop header dataup to the next interrupt packet.)
Isochronous transmit events (context typeFW_CDEV_ISO_CONTEXT_TRANSMIT):
In version 3 and some implementations of version 2 of the ABI,header_lengthis a multiple of 4 andheader contains timestamps of all packets up untilthe interrupt packet. The format of the timestamps is as described below forisochronous reception. In version 1 of the ABI,header_length was 0.
Isochronous receive events (context typeFW_CDEV_ISO_CONTEXT_RECEIVE):
The headers stripped of all packets up until and including the interruptpacket are returned in theheader field. The amount of header data perpacket is as specified at iso context creation byfw_cdev_create_iso_context.header_size.
Hence, _interrupt.header_length / _context.header_size is the number ofpackets received in this interrupt event. The client can now iteratethrough the mmap()’ed DMA buffer according to this number of packets andto the buffer sizes as the client specified infw_cdev_queue_iso.
Since version 2 of this ABI, the portion for each packet in _interrupt.headerconsists of the 1394 isochronous packet header, followed by a timestampquadlet iffw_cdev_create_iso_context.header_size > 4, followed by quadletsfrom the packet payload iffw_cdev_create_iso_context.header_size > 8.
Format of 1394 iso packet header: 16 bits data_length, 2 bits tag, 6 bitschannel, 4 bits tcode, 4 bits sy, in big endian byte order.data_length is the actual received size of the packet without the four1394 iso packet header bytes.
Format of timestamp: 16 bits invalid, 3 bits cycleSeconds, 13 bitscycleCount, in big endian byte order.
In version 1 of the ABI, no timestamp quadlet was inserted; instead, payloaddata followed directly after the 1394 is header if header_size > 4.Behaviour of ver. 1 of this ABI is no longer available since ABI ver. 2.
- structfw_cdev_event_iso_interrupt_mc¶
An iso buffer chunk was completed
Definition:
struct fw_cdev_event_iso_interrupt_mc { __u64 closure; __u32 type; __u32 completed;};Members
closureSee
fw_cdev_event_common;set byFW_CDEV_CREATE_ISO_CONTEXTioctltypeFW_CDEV_EVENT_ISO_INTERRUPT_MULTICHANNELcompletedOffset into the receive buffer; data before this offset is valid
Description
This event is sent in multichannel contexts (context typeFW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL) forfw_cdev_iso_packet bufferchunks that have been completely filled and that have theFW_CDEV_ISO_INTERRUPT bit set, or when explicitly requested withFW_CDEV_IOC_FLUSH_ISO.
- The buffer is continuously filled with the following data, per packet:
the 1394 iso packet header as described at
fw_cdev_event_iso_interrupt,but in little endian byte order,packet payload (as many bytes as specified in the data_length field ofthe 1394 iso packet header) in big endian byte order,
0...3 padding bytes as needed to align the following trailer quadlet,
trailer quadlet, containing the reception timestamp as described at
fw_cdev_event_iso_interrupt, but in little endian byte order.
Hence the per-packet size is data_length (rounded up to a multiple of 4) + 8.When processing the data, stop before a packet that would cross thecompleted offset.
A packet near the end of a buffer chunk will typically spill over into thenext queued buffer chunk. It is the responsibility of the client to checkfor this condition, assemble a broken-up packet from its parts, and not tore-queue any buffer chunks in which as yet unread packet parts reside.
- structfw_cdev_event_iso_resource¶
Iso resources were allocated or freed
Definition:
struct fw_cdev_event_iso_resource { __u64 closure; __u32 type; __u32 handle; __s32 channel; __s32 bandwidth;};Members
closureSee
fw_cdev_event_common;set by``FW_CDEV_IOC_(DE)ALLOCATE_ISO_RESOURCE(_ONCE)`` ioctltypeFW_CDEV_EVENT_ISO_RESOURCE_ALLOCATEDorFW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATEDhandleReference by which an allocated resource can be deallocated
channelIsochronous channel which was (de)allocated, if any
bandwidthBandwidth allocation units which were (de)allocated, if any
Description
AnFW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED event is sent after an isochronousresource was allocated at the IRM. The client has to checkchannel andbandwidth for whether the allocation actually succeeded.
AnFW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED event is sent after an isochronousresource was deallocated at the IRM. It is also sent when automaticreallocation after a bus reset failed.
channel is <0 if no channel was (de)allocated or if reallocation failed.bandwidth is 0 if no bandwidth was (de)allocated or if reallocation failed.
- structfw_cdev_event_phy_packet¶
A PHY packet was transmitted or received
Definition:
struct fw_cdev_event_phy_packet { __u64 closure; __u32 type; __u32 rcode; __u32 length; __u32 data[];};Members
closureSee
fw_cdev_event_common; set byFW_CDEV_IOC_SEND_PHY_PACKETorFW_CDEV_IOC_RECEIVE_PHY_PACKETSioctltypeFW_CDEV_EVENT_PHY_PACKET_SENTor %..._RECEIVEDrcodeRCODE_..., indicates success or failure of transmissionlengthData length in bytes
dataIncoming data for
FW_CDEV_IOC_RECEIVE_PHY_PACKETS. ForFW_CDEV_IOC_SEND_PHY_PACKETthe field has the same data in the request, thus the length of 8 bytes.
Description
This event is sent instead offw_cdev_event_phy_packet2 if the kernel orthe client implements ABI version <= 5. It has the lack of time stamp field comparing tofw_cdev_event_phy_packet2.
- structfw_cdev_event_phy_packet2¶
A PHY packet was transmitted or received with time stamp.
Definition:
struct fw_cdev_event_phy_packet2 { __u64 closure; __u32 type; __u32 rcode; __u32 length; __u32 tstamp; __u32 data[];};Members
closureSee
fw_cdev_event_common; set byFW_CDEV_IOC_SEND_PHY_PACKETorFW_CDEV_IOC_RECEIVE_PHY_PACKETSioctltypeFW_CDEV_EVENT_PHY_PACKET_SENT2orFW_CDEV_EVENT_PHY_PACKET_RECEIVED2rcodeRCODE_..., indicates success or failure of transmissionlengthData length in bytes
tstampFor
FW_CDEV_EVENT_PHY_PACKET_RECEIVED2, the time stamp of isochronous cycle atwhich the packet arrived. ForFW_CDEV_EVENT_PHY_PACKET_SENT2and non-ping packet,the time stamp of isochronous cycle at which the packet was sent. For ping packet,the tick count for round-trip time measured by 1394 OHCI controller.dataIncoming data
Description
The time stamp of isochronous cycle at which either the response was sent for
FW_CDEV_EVENT_PHY_PACKET_SENT2or the request arrived forFW_CDEV_EVENT_PHY_PACKET_RECEIVED2.
Iftype isFW_CDEV_EVENT_PHY_PACKET_SENT2,length is 8 anddata consists of the two PHYpacket quadlets to be sent, in host byte order,
Iftype isFW_CDEV_EVENT_PHY_PACKET_RECEIVED2,length is 8 anddata consists of the two PHYpacket quadlets, in host byte order.
ForFW_CDEV_EVENT_PHY_PACKET_RECEIVED2, thetstamp is the isochronous cycle at which thepacket arrived. It is 16 bit integer value and the higher 3 bits expresses three low order bitsof second field and the rest 13 bits expresses cycle field in the format of CYCLE_TIME register.
ForFW_CDEV_EVENT_PHY_PACKET_SENT2, thetstamp has different meanings whether to sent thepacket for ping or not. If it’s not for ping, thetstamp is the isochronous cycle at which thepacket was sent, and use the same format as the case ofFW_CDEV_EVENT_PHY_PACKET_SENT2. If it’sfor ping, thetstamp is for round-trip time measured by 1394 OHCI controller with 42.195 MHzresolution.
- unionfw_cdev_event¶
Convenience
unionoffw_cdev_event_* types
Definition:
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;};Members
commonValid for all types
bus_resetValid ifcommon.type ==
FW_CDEV_EVENT_BUS_RESETresponseValid ifcommon.type ==
FW_CDEV_EVENT_RESPONSErequestValid ifcommon.type ==
FW_CDEV_EVENT_REQUESTrequest2Valid ifcommon.type ==
FW_CDEV_EVENT_REQUEST2iso_interruptValid ifcommon.type ==
FW_CDEV_EVENT_ISO_INTERRUPTiso_interrupt_mcValid ifcommon.type ==
FW_CDEV_EVENT_ISO_INTERRUPT_MULTICHANNELiso_resourceValid ifcommon.type ==
FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATEDorFW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATEDphy_packetValid ifcommon.type ==
FW_CDEV_EVENT_PHY_PACKET_SENTorFW_CDEV_EVENT_PHY_PACKET_RECEIVEDrequest3Valid ifcommon.type ==
FW_CDEV_EVENT_REQUEST3response2Valid ifcommon.type ==
FW_CDEV_EVENT_RESPONSE2phy_packet2Valid ifcommon.type ==
FW_CDEV_EVENT_PHY_PACKET_SENT2orFW_CDEV_EVENT_PHY_PACKET_RECEIVED2
Description
Convenience union for userspace use. Events could be read(2) into anappropriately aligned char buffer and then cast to this union for furtherprocessing. Note that for a request, response or iso_interrupt event,the data[] or header[] may make the size of the full event larger thansizeof(unionfw_cdev_event). Also note that if you attempt to read(2)an event into a buffer that is not large enough for it, the data that doesnot fit will be discarded so that the next read(2) will return a new event.
- structfw_cdev_get_info¶
General purpose information ioctl
Definition:
struct fw_cdev_get_info { __u32 version; __u32 rom_length; __u64 rom; __u64 bus_reset; __u64 bus_reset_closure; __u32 card;};Members
versionThe version field is just a running serial number. Both aninput parameter (ABI version implemented by the client) andoutput parameter (ABI version implemented by the kernel).A client shall fill in the ABIversion for which the clientwas implemented. This is necessary for forward compatibility.
rom_lengthIfrom is non-zero, up torom_length bytes of ConfigurationROM will be copied into that user space address. In eithercase,rom_length is updated with the actual length of theConfiguration ROM.
romIf non-zero, address of a buffer to be filled by a copy of thedevice’s Configuration ROM
bus_resetIf non-zero, address of a buffer to be filled by a
structfw_cdev_event_bus_resetwith the current stateof the bus. This does not cause a bus reset to happen.bus_reset_closureValue of
closurein this and subsequent bus reset eventscardThe index of the card this device belongs to
Description
TheFW_CDEV_IOC_GET_INFO ioctl is usually the very first one which a clientperforms right after it opened a /dev/fw* file.
As a side effect, reception ofFW_CDEV_EVENT_BUS_RESET events to be read(2)is started by this ioctl.
- structfw_cdev_send_request¶
Send an asynchronous request packet
Definition:
struct fw_cdev_send_request { __u32 tcode; __u32 length; __u64 offset; __u64 closure; __u64 data; __u32 generation;};Members
tcodeTransaction code of the request
lengthLength of outgoing payload, in bytes
offset48-bit offset at destination node
closurePassed back to userspace in the response event
dataUserspace pointer to payload
generationThe bus generation where packet is valid
Description
Send a request to the device. This ioctl implements all outgoing requests. Both quadlet andblock request specify the payload as a pointer to the data in thedata field. Once thetransaction completes, the kernel writes eitherfw_cdev_event_response event orfw_cdev_event_response event back. Theclosure field is passed back to user space in theresponse event.
- structfw_cdev_send_response¶
Send an asynchronous response packet
Definition:
struct fw_cdev_send_response { __u32 rcode; __u32 length; __u64 data; __u32 handle;};Members
rcodeResponse code as determined by the userspace handler
lengthLength of outgoing payload, in bytes
dataUserspace pointer to payload
handleThe handle from the
fw_cdev_event_request
Description
Send a response to an incoming request. By setting up an address range usingtheFW_CDEV_IOC_ALLOCATE ioctl, userspace can listen for incoming requests. Anincoming request will generate anFW_CDEV_EVENT_REQUEST, and userspace mustsend a reply using this ioctl. The event has a handle to the kernel-sidepending transaction, which should be used with this ioctl.
- structfw_cdev_allocate¶
Allocate a CSR in an address range
Definition:
struct fw_cdev_allocate { __u64 offset; __u64 closure; __u32 length; __u32 handle; __u64 region_end;};Members
offsetStart offset of the address range
closureTo be passed back to userspace in request events
lengthLength of the CSR, in bytes
handleHandle to the allocation, written by the kernel
region_endFirst address above the address range (added in ABI v4, 2.6.36)
Description
Allocate an address range in the 48-bit address space on the local node(the controller). This allows userspace to listen for requests with anoffset within that address range. Every time when the kernel receives arequest within the range, anfw_cdev_event_request2 event will be emitted.(If the kernel or the client implements ABI version <= 3, anfw_cdev_event_request will be generated instead.)
Theclosure field is passed back to userspace in these request events.Thehandle field is an out parameter, returning a handle to the allocatedrange to be used for later deallocation of the range.
The address range is allocated on all local nodes. The address allocationis exclusive except for the FCP command and response registers. If anexclusive address region is already in use, the ioctl fails with errno settoEBUSY.
If kernel and client implement ABI version >= 4, the kernel looks up a freespot of sizelength inside [offset..**region_end**) and, if found, writesthe start address of the new CSR back inoffset. I.e.offset is anin and out parameter. If this automatic placement of a CSR in a biggeraddress range is not desired, the client simply needs to setregion_end=offset +length.
If the kernel or the client implements ABI version <= 3,region_end isignored and effectively assumed to beoffset +length.
region_end is only present in a kernel header >= 2.6.36. If necessary,this can for example be tested by #ifdef FW_CDEV_EVENT_REQUEST2.
- structfw_cdev_deallocate¶
Free a CSR address range or isochronous resource
Definition:
struct fw_cdev_deallocate { __u32 handle;};Members
handleHandle to the address range or iso resource, as returned by thekernel when the range or resource was allocated
- structfw_cdev_initiate_bus_reset¶
Initiate a bus reset
Definition:
struct fw_cdev_initiate_bus_reset { __u32 type;};Members
typeFW_CDEV_SHORT_RESETorFW_CDEV_LONG_RESET
Description
Initiate a bus reset for the bus this device is on. The bus reset can beeither the original (long) bus reset or the arbitrated (short) bus resetintroduced in 1394a-2000.
The ioctl returns immediately. A subsequentfw_cdev_event_bus_resetindicates when the reset actually happened. Since ABI v4, this may beconsiderably later than the ioctl because the kernel ensures a grace periodbetween subsequent bus resets as per IEEE 1394 bus management specification.
- structfw_cdev_add_descriptor¶
Add contents to the local node’s config ROM
Definition:
struct fw_cdev_add_descriptor { __u32 immediate; __u32 key; __u64 data; __u32 length; __u32 handle;};Members
immediateIf non-zero, immediate key to insert before pointer
keyUpper 8 bits of root directory pointer
dataUserspace pointer to contents of descriptor block
lengthLength of descriptor block data, in quadlets
handleHandle to the descriptor, written by the kernel
Description
Add a descriptor block and optionally a preceding immediate key to the localnode’s Configuration ROM.
Thekey field specifies the upper 8 bits of the descriptor root directorypointer and thedata andlength fields specify the contents. Thekeyshould be of the form 0xXX000000. The offset part of the root directory entrywill be filled in by the kernel.
If not 0, theimmediate field specifies an immediate key which will beinserted before the root directory pointer.
immediate,key, anddata array elements are CPU-endian quadlets.
If successful, the kernel adds the descriptor and writes back ahandle tothe kernel-side object to be used for later removal of the descriptor blockand immediate key. The kernel will also generate a bus reset to signal thechange of the Configuration ROM to other nodes.
This ioctl affects the Configuration ROMs of all local nodes.The ioctl only succeeds on device files which represent a local node.
- structfw_cdev_remove_descriptor¶
Remove contents from the Configuration ROM
Definition:
struct fw_cdev_remove_descriptor { __u32 handle;};Members
handleHandle to the descriptor, as returned by the kernel when thedescriptor was added
Description
Remove a descriptor block and accompanying immediate key from the localnodes’ Configuration ROMs. The kernel will also generate a bus reset tosignal the change of the Configuration ROM to other nodes.
- structfw_cdev_create_iso_context¶
Create a context for isochronous I/O
Definition:
struct fw_cdev_create_iso_context { __u32 type; __u32 header_size; __u32 channel; __u32 speed; __u64 closure; __u32 handle;};Members
typeFW_CDEV_ISO_CONTEXT_TRANSMITorFW_CDEV_ISO_CONTEXT_RECEIVEorFW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNELheader_sizeHeader size to strip in single-channel reception
channelChannel to bind to in single-channel reception or transmission
speedTransmission speed
closureTo be returned in
fw_cdev_event_iso_interruptorfw_cdev_event_iso_interrupt_multichannelhandleHandle to context, written back by kernel
Description
Prior to sending or receiving isochronous I/O, a context must be created.The context records information about the transmit or receive configurationand typically maps to an underlying hardware resource. A context is set upfor either sending or receiving. It is bound to a specific isochronouschannel.
In case of multichannel reception,header_size andchannel are ignoredand the channels are selected byFW_CDEV_IOC_SET_ISO_CHANNELS.
ForFW_CDEV_ISO_CONTEXT_RECEIVE contexts,header_size must be at least 4and must be a multiple of 4. It is ignored in other context types.
speed is ignored in receive context types.
If a context was successfully created, the kernel writes back a handle to thecontext, which must be passed in for subsequent operations on that context.
Limitations:No more than one iso context can be created per fd.The total number of contexts that all userspace and kernelspace drivers cancreate on a card at a time is a hardware limit, typically 4 or 8 contexts perdirection, and of them at most one multichannel receive context.
- structfw_cdev_set_iso_channels¶
Select channels in multichannel reception
Definition:
struct fw_cdev_set_iso_channels { __u64 channels; __u32 handle;};Members
channelsBitmask of channels to listen to
handleHandle of the mutichannel receive context
Description
channels is the bitwise or of 1ULL << n for each channel n to listen to.
The ioctl fails with errnoEBUSY if there is already another receive contexton a channel inchannels. In that case, the bitmask of all unoccupiedchannels is returned inchannels.
- structfw_cdev_iso_packet¶
Isochronous packet
Definition:
struct fw_cdev_iso_packet { __u32 control; __u32 header[];};Members
controlContains the header length (8 uppermost bits),the sy field (4 bits), the tag field (2 bits), a sync flagor a skip flag (1 bit), an interrupt flag (1 bit), and thepayload length (16 lowermost bits)
headerHeader and payload in case of a transmit context.
Description
structfw_cdev_iso_packet is used to describe isochronous packet queues.Use the FW_CDEV_ISO_* macros to fill incontrol.Theheader array is empty in case of receive contexts.
Context typeFW_CDEV_ISO_CONTEXT_TRANSMIT:
control.HEADER_LENGTH must be a multiple of 4. It specifies the numbers ofbytes inheader that will be prepended to the packet’s payload. These bytesare copied into the kernel and will not be accessed after the ioctl hasreturned.
Thecontrol.SY and TAG fields are copied to the iso packet header. Thesefields are specified by IEEE 1394a and IEC 61883-1.
Thecontrol.SKIP flag specifies that no packet is to be sent in a frame.When using this, all other fields exceptcontrol.INTERRUPT must be zero.
When a packet with thecontrol.INTERRUPT flag set has been completed, anfw_cdev_event_iso_interrupt event will be sent.
Context typeFW_CDEV_ISO_CONTEXT_RECEIVE:
control.HEADER_LENGTH must be a multiple of the context’s header_size.If the HEADER_LENGTH is larger than the context’s header_size, multiplepackets are queued for this entry.
Thecontrol.SY and TAG fields are ignored.
If thecontrol.SYNC flag is set, the context drops all packets until apacket with a sy field is received which matchesfw_cdev_start_iso.sync.
control.PAYLOAD_LENGTH defines how many payload bytes can be received forone packet (in addition to payload quadlets that have been defined as headersand are stripped and returned in thefw_cdev_event_iso_interrupt structure).If more bytes are received, the additional bytes are dropped. If less bytesare received, the remaining bytes in this part of the payload buffer will notbe written to, not even by the next packet. I.e., packets received inconsecutive frames will not necessarily be consecutive in memory. If anentry has queued multiple packets, the PAYLOAD_LENGTH is divided equallyamong them.
When a packet with thecontrol.INTERRUPT flag set has been completed, anfw_cdev_event_iso_interrupt event will be sent. An entry that has queuedmultiple receive packets is completed when its last packet is completed.
Context typeFW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL:
Here,fw_cdev_iso_packet would be more aptly named _iso_buffer_chunk sinceit specifies a chunk of the mmap()’ed buffer, while the number and alignmentof packets to be placed into the buffer chunk is not known beforehand.
control.PAYLOAD_LENGTH is the size of the buffer chunk and specifies roomfor header, payload, padding, and trailer bytes of one or more packets.It must be a multiple of 4.
control.HEADER_LENGTH, TAG and SY are ignored. SYNC is treated as describedfor single-channel reception.
When a buffer chunk with thecontrol.INTERRUPT flag set has been filledentirely, anfw_cdev_event_iso_interrupt_mc event will be sent.
- structfw_cdev_queue_iso¶
Queue isochronous packets for I/O
Definition:
struct fw_cdev_queue_iso { __u64 packets; __u64 data; __u32 size; __u32 handle;};Members
packetsUserspace pointer to an array of
fw_cdev_iso_packetdataPointer into mmap()’ed payload buffer
sizeSize of thepackets array, in bytes
handleIsochronous context handle
Description
Queue a number of isochronous packets for reception or transmission.This ioctl takes a pointer to an array offw_cdev_iso_packet structs,which describe how to transmit from or receive into a contiguous regionof a mmap()’ed payload buffer. As part of transmit packet descriptors,a series of headers can be supplied, which will be prepended to thepayload during DMA.
The kernel may or may not queue all packets, but will write back updatedvalues of thepackets,data andsize fields, so the ioctl can beresubmitted easily.
In case of a multichannel receive context,data must be quadlet-alignedrelative to the buffer start.
- structfw_cdev_start_iso¶
Start an isochronous transmission or reception
Definition:
struct fw_cdev_start_iso { __s32 cycle; __u32 sync; __u32 tags; __u32 handle;};Members
cycleCycle in which to start I/O. Ifcycle is greater than orequal to 0, the I/O will start on that cycle.
syncDetermines the value to wait for receive packets that havethe
FW_CDEV_ISO_SYNCbit settagsTag filter bit mask. Only valid for isochronous reception.Determines the tag values for which packets will be accepted.Use FW_CDEV_ISO_CONTEXT_MATCH_* macros to settags.
handleIsochronous context handle within which to transmit or receive
- structfw_cdev_stop_iso¶
Stop an isochronous transmission or reception
Definition:
struct fw_cdev_stop_iso { __u32 handle;};Members
handleHandle of isochronous context to stop
- structfw_cdev_flush_iso¶
flush completed iso packets
Definition:
struct fw_cdev_flush_iso { __u32 handle;};Members
handlehandle of isochronous context to flush
Description
ForFW_CDEV_ISO_CONTEXT_TRANSMIT orFW_CDEV_ISO_CONTEXT_RECEIVE contexts,report any completed packets.
ForFW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL contexts, report the currentoffset in the receive buffer, if it has changed; this is typically in themiddle of some buffer chunk.
AnyFW_CDEV_EVENT_ISO_INTERRUPT orFW_CDEV_EVENT_ISO_INTERRUPT_MULTICHANNELevents generated by this ioctl are sent synchronously, i.e., are availablefor reading from the file descriptor when this ioctl returns.
- structfw_cdev_get_cycle_timer¶
read cycle timer register
Definition:
struct fw_cdev_get_cycle_timer { __u64 local_time; __u32 cycle_timer;};Members
local_timesystem time, in microseconds since the Epoch
cycle_timerCycle Time register contents
Description
Same asFW_CDEV_IOC_GET_CYCLE_TIMER2, but fixed to useCLOCK_REALTIMEand only with microseconds resolution.
In version 1 and 2 of the ABI, this ioctl returned unreliable (non-monotonic)cycle_timer values on certain controllers.
- structfw_cdev_get_cycle_timer2¶
read cycle timer register
Definition:
struct fw_cdev_get_cycle_timer2 { __s64 tv_sec; __s32 tv_nsec; __s32 clk_id; __u32 cycle_timer;};Members
tv_secsystem time, seconds
tv_nsecsystem time, sub-seconds part in nanoseconds
clk_idinput parameter, clock from which to get the system time
cycle_timerCycle Time register contents
Description
TheFW_CDEV_IOC_GET_CYCLE_TIMER2 ioctl reads the isochronous cycle timerand also the system clock. This allows to correlate reception time ofisochronous packets with system time.
clk_id lets you choose a clock like with POSIX’ clock_gettime function.Supportedclk_id values are POSIX’CLOCK_REALTIME andCLOCK_MONOTONICand Linux’CLOCK_MONOTONIC_RAW.
cycle_timer consists of 7 bits cycleSeconds, 13 bits cycleCount, and12 bits cycleOffset, in host byte order. Cf. the Cycle Time registerper IEEE 1394 or Isochronous Cycle Timer register per OHCI-1394.
- structfw_cdev_allocate_iso_resource¶
(De)allocate a channel or bandwidth
Definition:
struct fw_cdev_allocate_iso_resource { __u64 closure; __u64 channels; __u32 bandwidth; __u32 handle;};Members
closurePassed back to userspace in corresponding iso resource events
channelsIsochronous channels of which one is to be (de)allocated
bandwidthIsochronous bandwidth units to be (de)allocated
handleHandle to the allocation, written by the kernel (only valid incase of
FW_CDEV_IOC_ALLOCATE_ISO_RESOURCEioctls)
Description
TheFW_CDEV_IOC_ALLOCATE_ISO_RESOURCE ioctl initiates allocation of anisochronous channel and/or of isochronous bandwidth at the isochronousresource manager (IRM). Only one of the channels specified inchannels isallocated. AnFW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED is sent aftercommunication with the IRM, indicating success or failure in the event data.The kernel will automatically reallocate the resources after bus resets.Should a reallocation fail, anFW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED eventwill be sent. The kernel will also automatically deallocate the resourceswhen the file descriptor is closed.
TheFW_CDEV_IOC_DEALLOCATE_ISO_RESOURCE ioctl can be used to initiatedeallocation of resources which were allocated as described above.AnFW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED event concludes this operation.
TheFW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE ioctl is a variant of allocationwithout automatic re- or deallocation.AnFW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED event concludes this operation,indicating success or failure in its data.
TheFW_CDEV_IOC_DEALLOCATE_ISO_RESOURCE_ONCE ioctl works likeFW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE except that resources are freedinstead of allocated.AnFW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED event concludes this operation.
To summarize,FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE allocates iso resourcesfor the lifetime of the fd orhandle.In contrast,FW_CDEV_IOC_ALLOCATE_ISO_RESOURCE_ONCE allocates iso resourcesfor the duration of a bus generation.
channels is a host-endian bitfield with the least significant bitrepresenting channel 0 and the most significant bit representing channel 63:1ULL << c for each channel c that is a candidate for (de)allocation.
bandwidth is expressed in bandwidth allocation units, i.e. the time to sendone quadlet of data (payload or header data) at speed S1600.
- structfw_cdev_send_stream_packet¶
send an asynchronous stream packet
Definition:
struct fw_cdev_send_stream_packet { __u32 length; __u32 tag; __u32 channel; __u32 sy; __u64 closure; __u64 data; __u32 generation; __u32 speed;};Members
lengthLength of outgoing payload, in bytes
tagData format tag
channelIsochronous channel to transmit to
sySynchronization code
closurePassed back to userspace in the response event
dataUserspace pointer to payload
generationThe bus generation where packet is valid
speedSpeed to transmit at
Description
TheFW_CDEV_IOC_SEND_STREAM_PACKET ioctl sends an asynchronous stream packet to every devicewhich is listening to the specified channel. The kernel writes eitherfw_cdev_event_responseevent orfw_cdev_event_response2 event which indicates success or failure of the transmission.
- structfw_cdev_send_phy_packet¶
send a PHY packet
Definition:
struct fw_cdev_send_phy_packet { __u64 closure; __u32 data[2]; __u32 generation;};Members
closurePassed back to userspace in the PHY-packet-sent event
dataFirst and second quadlet of the PHY packet
generationThe bus generation where packet is valid
Description
TheFW_CDEV_IOC_SEND_PHY_PACKET ioctl sends a PHY packet to all nodes on the same card as thisdevice. After transmission, eitherFW_CDEV_EVENT_PHY_PACKET_SENT event orFW_CDEV_EVENT_PHY_PACKET_SENT event is generated.
The payloaddata[] shall be specified in host byte order. Usually,data[1] needs to be the bitwise inverse ofdata[0]. VersaPHY packetsare an exception to this rule.
The ioctl is only permitted on device files which represent a local node.
- structfw_cdev_receive_phy_packets¶
start reception of PHY packets
Definition:
struct fw_cdev_receive_phy_packets { __u64 closure;};Members
closurePassed back to userspace in phy packet events
Description
This ioctl activates issuing of eitherFW_CDEV_EVENT_PHY_PACKET_RECEIVED orFW_CDEV_EVENT_PHY_PACKET_RECEIVED2 due to incoming PHY packets from any node on the same busas the device.
The ioctl is only permitted on device files which represent a local node.
Firewire device probing and sysfs interfaces¶
What: /sys/bus/firewire/devices/fw[0-9]+/Date: May 2007KernelVersion: 2.6.22Contact: linux1394-devel@lists.sourceforge.netDescription: 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]+/unitsDate: June 2009KernelVersion: 2.6.31Contact: linux1394-devel@lists.sourceforge.netDescription: 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 filesWhat: /sys/bus/firewire/devices/fw[0-9]+/is_localDate: July 2012KernelVersion: 3.6Contact: linux1394-devel@lists.sourceforge.netDescription: 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 2007KernelVersion: 2.6.22Contact: linux1394-devel@lists.sourceforge.netDescription: 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 2007KernelVersion: 2.6.22Contact: linux1394-devel@lists.sourceforge.netDescription: 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_idDate: Feb 2004KernelVersion: 2.6.4Contact: linux1394-devel@lists.sourceforge.netDescription: 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
- intfw_csr_string(constu32*directory,intkey,char*buf,size_tsize)¶
reads a string from the configuration ROM
Parameters
constu32*directorye.g. root directory or unit directory
intkeythe key of the preceding directory entry
char*bufwhere to put the string
size_tsizesize ofbuf, in bytes
Description
The string is taken from a minimal ASCII text descriptor leaf just after the entry with thekey. The string is zero-terminated. An overlong string is silently truncated such that itand the zero byte fit intosize.
Returns strlen(buf) or a negative error code.
Firewire core transaction interfaces¶
- void__fw_send_request(structfw_card*card,structfw_transaction*t,inttcode,intdestination_id,intgeneration,intspeed,unsignedlonglongoffset,void*payload,size_tlength,unionfw_transaction_callbackcallback,boolwith_tstamp,void*callback_data)¶
submit a request packet for transmission to generate callback for response subaction with or without time stamp.
Parameters
structfw_card*cardinterface to send the request at
structfw_transaction*ttransaction instance to which the request belongs
inttcodetransaction code
intdestination_iddestination node ID, consisting of bus_ID and phy_ID
intgenerationbus generation in which request and response are valid
intspeedtransmission speed
unsignedlonglongoffset48bit wide offset into destination’s address space
void*payloaddata payload for the request subaction
size_tlengthlength of the payload, in bytes
unionfw_transaction_callbackcallbackunionoftwo functions whether to receive time stamp or not for responsesubaction.boolwith_tstampWhether to receive time stamp or not for response subaction.
void*callback_datadata to be passed to the transaction completion callback
Description
Submit a request packet into the asynchronous request transmission queue.Can be called from atomic context. If you prefer a blocking API, usefw_run_transaction() in a context that can sleep.
In case of lock requests, specify one of the firewire-core specificTCODE_constants instead ofTCODE_LOCK_REQUEST intcode.
Make sure that the value indestination_id is not older than the one ingeneration. Otherwise the request is in danger to be sent to a wrong node.
In case of asynchronous stream packets i.e.TCODE_STREAM_DATA, the callerneeds to synthesizedestination_id withfw_stream_packet_destination_id().It will contain tag, channel, and sy data instead of a node ID then.
The payload buffer atdata is going to be DMA-mapped except in case oflength <= 8 or of local (loopback) requests. Hence make sure that thebuffer complies with the restrictions of the streaming DMA mapping API.payload must not be freed before thecallback is called.
In case of request types without payload,data is NULL andlength is 0.
After the transaction is completed successfully or unsuccessfully, thecallback will be called. Among its parameters is the response code whichis either one of the rcodes per IEEE 1394 or, in case of internal errors,the firewire-core specificRCODE_SEND_ERROR. The other firewire-corespecific rcodes (RCODE_CANCELLED,RCODE_BUSY,RCODE_GENERATION,RCODE_NO_ACK) denote transaction timeout, busy responder, stale requestgeneration, or missing ACK respectively.
Note some timing corner cases:fw_send_request() may complete much earlierthan when the request packet actually hits the wire. On the other hand,transaction completion and hence execution ofcallback may happen evenbeforefw_send_request() returns.
- intfw_run_transaction(structfw_card*card,inttcode,intdestination_id,intgeneration,intspeed,unsignedlonglongoffset,void*payload,size_tlength)¶
send request and sleep until transaction is completed
Parameters
structfw_card*cardcard interface for this request
inttcodetransaction code
intdestination_iddestination node ID, consisting of bus_ID and phy_ID
intgenerationbus generation in which request and response are valid
intspeedtransmission speed
unsignedlonglongoffset48bit wide offset into destination’s address space
void*payloaddata payload for the request subaction
size_tlengthlength of the payload, in bytes
Description
Returns the RCODE. Seefw_send_request() for parameter documentation.Unlikefw_send_request(),data points to the payload of the request or/andto the payload of the response. DMA mapping restrictions apply to outboundrequest payloads of >= 8 bytes but not to inbound response payloads.
- intfw_core_add_address_handler(structfw_address_handler*handler,conststructfw_address_region*region)¶
register for incoming requests
Parameters
structfw_address_handler*handlercallback
conststructfw_address_region*regionregion in the IEEE 1212 node space address range
Description
region->start, ->end, and handler->length have to be quadlet-aligned.
When a request is received that falls within the specified address range, the specified callbackis invoked. The parameters passed to the callback give the details of the particular request.The callback is invoked in the workqueue context in most cases. However, if the request isinitiated by the local node, the callback is invoked in the initiator’s context.
To be called in process context.Return value: 0 on success, non-zero otherwise.
The start offset of the handler’s address region is determined byfw_core_add_address_handler() and is returned in handler->offset.
Address allocations are exclusive, except for the FCP registers.
- voidfw_core_remove_address_handler(structfw_address_handler*handler)¶
unregister an address handler
Parameters
structfw_address_handler*handlercallback
Description
To be called in process context.
Whenfw_core_remove_address_handler() returns,handler->callback() isguaranteed to not run on any CPU anymore.
- voidfw_send_response(structfw_card*card,structfw_request*request,intrcode)¶
send response packet for asynchronous transaction.
Parameters
structfw_card*cardinterface to send the response at.
structfw_request*requestfirewire request data for the transaction.
intrcoderesponse code to send.
Description
Submit a response packet into the asynchronous response transmission queue. Therequestis going to be released when the transmission successfully finishes later.
- intfw_get_request_speed(structfw_request*request)¶
returns speed at which therequest was received
Parameters
structfw_request*requestfirewire request data
- u32fw_request_get_timestamp(conststructfw_request*request)¶
Get timestamp of the request.
Parameters
conststructfw_request*requestThe opaque pointer to request structure.
Description
Get timestamp when 1394 OHCI controller receives the asynchronous request subaction. Thetimestamp consists of the low order 3 bits of second field and the full 13 bits of countfield of isochronous cycle time register.
Return
timestamp of the request.
- constchar*fw_rcode_string(intrcode)¶
convert a firewire result code to an error description
Parameters
intrcodethe result code
Firewire Isochronous I/O interfaces¶
- voidfw_iso_context_schedule_flush_completions(structfw_iso_context*ctx)¶
schedule work item to process isochronous context.
Parameters
structfw_iso_context*ctxthe isochronous context
Description
Schedule a work item on workqueue to process the isochronous context. The registered callbackfunction is called by the worker when a queued packet buffer with the interrupt flag iscompleted, either after transmission in the IT context or after being filled in the IR context.The callback function is also called when the header buffer in the context becomes full, If itis required to process the context in the current context,fw_iso_context_flush_completions() isavailable instead.
Context
Any context.
- intfw_iso_context_flush_completions(structfw_iso_context*ctx)¶
process isochronous context in current process context.
Parameters
structfw_iso_context*ctxthe isochronous context
Description
Process the isochronous context in the current process context. The registered callback functionis called when a queued packet buffer with the interrupt flag is completed, either aftertransmission in the IT context or after being filled in the IR context. Additionally, thecallback function is also called for the packet buffer completed at last. Furthermore, thecallback function is called as well when the header buffer in the context becomes full. If it isrequired to process the context asynchronously,fw_iso_context_schedule_flush_completions() isavailable instead.
Context
Process context. May sleep due todisable_work_sync().
- voidfw_iso_resource_manage(structfw_card*card,intgeneration,u64channels_mask,int*channel,int*bandwidth,boolallocate)¶
Allocate or deallocate a channel and/or bandwidth
Parameters
structfw_card*cardcard interface for this action
intgenerationbus generation
u64channels_maskbitmask for channel allocation
int*channelpointer for returning channel allocation result
int*bandwidthpointer for returning bandwidth allocation result
boolallocatewhether to allocate (true) or deallocate (false)
Description
In parameters: card, generation, channels_mask, bandwidth, allocateOut parameters: channel, bandwidth
This function blocks (sleeps) during communication with the IRM.
Allocates or deallocates at most one channel out of channels_mask.channels_mask is a bitfield with MSB for channel 63 and LSB for channel 0.(Note, the IRM’s CHANNELS_AVAILABLE is a big-endian bitfield with MSB forchannel 0 and LSB for channel 63.)Allocates or deallocates as many bandwidth allocation units as specified.
Returns channel < 0 if no channel was allocated or deallocated.Returns bandwidth = 0 if no bandwidth was allocated or deallocated.
If generation is stale, deallocations succeed but allocations fail withchannel = -EAGAIN.
If channel allocation fails, no bandwidth will be allocated either.If bandwidth allocation fails, no channel will be allocated either.But deallocations of channel and bandwidth are tried independentlyof each other’s success.