GeezerVisonThe World Wide Web, restored to 800 pixels of glory. |
| Home|About|Gaming cabinet|Archives|How it works|Starter sites |
GeezerVison is showing www.kernel.org — Firewire (IEEE 1394) driver Interface Guide — The Linux Kernel documentation Firewire (IEEE 1394) driver Interface Guide¶Introduction and Overview¶
The main purpose of these interfaces is to access address space on each node on IEEE 1394 bus by ISO/IEC 13213 (IEEE 1212) procedure, and to control isochronous resources on the bus by IEEE 1394 procedure. Two types of interfaces are added, according to consumers of the interface. A set of userspace interfaces is available via firewire character devices. A set of kernel interfaces is available via exported symbols in firewire-core module. Firewire char device data structures¶What: /dev/fw[0-9]+ Date: May 2007 KernelVersion: 2.6.22 Contact: [email protected] Description: The character device files /dev/fw* are the interface between firewire-core and IEEE 1394 device drivers implemented in userspace. The ioctl(2)- and read(2)-based ABI is defined and documented in <linux/firewire-cdev.h>. This ABI offers most of the features which firewire-core also exposes to kernelspace IEEE 1394 drivers. Each /dev/fw* is associated with one IEEE 1394 node, which can be remote or local nodes. Operations on a /dev/fw* file have different scope: - The 1394 node which is associated with the file: - Asynchronous request transmission - Get the Configuration ROM - Query node ID - Query maximum speed of the path between this node and local node - The 1394 bus (i.e. "card") to which the node is attached to: - Isochronous stream transmission and reception - Asynchronous stream transmission and reception - Asynchronous broadcast request transmission - PHY packet transmission and reception - Allocate, reallocate, deallocate isochronous resources (channels, bandwidth) at the bus's IRM - Query node IDs of local node, root node, IRM, bus manager - Query cycle time - Bus reset initiation, bus reset event reception - All 1394 buses: - Allocation of IEEE 1212 address ranges on the local link layers, reception of inbound requests to such an address range, asynchronous response transmission to inbound requests - Addition of descriptors or directories to the local nodes' Configuration ROM Due to the different scope of operations and in order to let userland implement different access permission models, some operations are restricted to /dev/fw* files that are associated with a local node: - Addition of descriptors or directories to the local nodes' Configuration ROM - PHY packet transmission and reception A /dev/fw* file remains associated with one particular node during its entire life time. Bus topology changes, and hence node ID changes, are tracked by firewire-core. ABI users do not need to be aware of topology. The following file operations are supported: open(2) Currently the only useful flags are O_RDWR. ioctl(2) Initiate various actions. Some take immediate effect, others are performed asynchronously while or after the ioctl returns. See the inline documentation in <linux/firewire-cdev.h> for descriptions of all ioctls. poll(2), select(2), epoll_wait(2) etc. Watch for events to become available to be read. read(2) Receive various events. There are solicited events like outbound asynchronous transaction completion or isochronous buffer completion, and unsolicited events such as bus resets, request reception, or PHY packet reception. Always use a read buffer which is large enough to receive the largest event that could ever arrive. See <linux/firewire-cdev.h> for descriptions of all event types and for which ioctls affect reception of events. mmap(2) Allocate a DMA buffer for isochronous reception or transmission and map it into the process address space. The arguments should be used as follows: addr = NULL, length = the desired buffer size, i.e. number of packets times size of largest packet, prot = at least PROT_READ for reception and at least PROT_WRITE for transmission, flags = MAP_SHARED, fd = the handle to the /dev/fw*, offset = 0. Isochronous reception works in packet-per-buffer fashion except for multichannel reception which works in buffer-fill mode. munmap(2) Unmap the isochronous I/O buffer from the process address space. close(2) Besides stopping and freeing I/O contexts that were associated with the file descriptor, back out any changes to the local nodes' Configuration ROM. Deallocate isochronous channels and bandwidth at the IRM that were marked for kernel-assisted re- and deallocation. Users: libraw1394; libdc1394; libhinawa; tools like linux-firewire-utils, fwhack, ...
Definition struct fw_cdev_event_common {
__u64 closure;
__u32 type;
};
Members
Description This struct may be used to access generic members of all fw_cdev_event_* types regardless of the specific type. Data passed in the closure field for a request will be returned in the corresponding event. It is big enough to hold a pointer on all platforms. The ioctl used to set closure depends on the type of event.
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
Description This event is sent when the bus the device belongs to goes through a bus reset. It provides information about the new bus configuration, such as new node ID for this device, new root ID, and others. If bm_node_id is 0xffff right after bus reset it can be reread by an
Definition struct fw_cdev_event_response {
__u64 closure;
__u32 type;
__u32 rcode;
__u32 length;
__u32 data[0];
};
Members
Description This event is sent when the stack receives a response to an outgoing request
sent by The event is also generated after conclusions of transactions that do not involve response packets. This includes unified write transactions, broadcast write transactions, and transmission of asynchronous stream packets. rcode indicates success or failure of such transmissions.
Definition struct fw_cdev_event_request {
__u64 closure;
__u32 type;
__u32 tcode;
__u64 offset;
__u32 handle;
__u32 length;
__u32 data[0];
};
Members
Description This event is sent instead of
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[0];
};
Members
Description This event is sent when the stack receives an incoming request to an address
region registered using the The payload data for requests carrying data (write and lock requests) follows immediately and can be accessed through the data field. Unlike card may differ from destination_node_id may also differ from the current node ID because of a
non-local bus ID part or in case of a broadcast write request. Note, a
client must call an In case of a write request to FCP_REQUEST or FCP_RESPONSE, the kernel already
sent a write response immediately after the request was received; in this
case the client must still call an If the client subsequently needs to initiate requests to the sender node of
an
Definition struct fw_cdev_event_iso_interrupt {
__u64 closure;
__u32 type;
__u32 cycle;
__u32 header_length;
__u32 header[0];
};
Members
Description This event is sent when the controller has completed an Isochronous transmit events (context type In version 3 and some implementations of version 2 of the ABI, Isochronous receive events (context type The headers stripped of all packets up until and including the interrupt
packet are returned in the header field. The amount of header data per
packet is as specified at iso context creation by
Hence, _interrupt.header_length / _context.header_size is the number of
packets received in this interrupt event. The client can now iterate
through the mmap()’ed DMA buffer according to this number of packets and
to the buffer sizes as the client specified in Since version 2 of this ABI, the portion for each packet in _interrupt.header
consists of the 1394 isochronous packet header, followed by a timestamp
quadlet if Format of 1394 iso packet header: 16 bits data_length, 2 bits tag, 6 bits channel, 4 bits tcode, 4 bits sy, in big endian byte order. data_length is the actual received size of the packet without the four 1394 iso packet header bytes. Format of timestamp: 16 bits invalid, 3 bits cycleSeconds, 13 bits cycleCount, in big endian byte order. In version 1 of the ABI, no timestamp quadlet was inserted; instead, payload data 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.
Definition struct fw_cdev_event_iso_interrupt_mc {
__u64 closure;
__u32 type;
__u32 completed;
};
Members
Description This event is sent in multichannel contexts (context type
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 the completed offset. A packet near the end of a buffer chunk will typically spill over into the next queued buffer chunk. It is the responsibility of the client to check for this condition, assemble a broken-up packet from its parts, and not to re-queue any buffer chunks in which as yet unread packet parts reside.
Definition struct fw_cdev_event_iso_resource {
__u64 closure;
__u32 type;
__u32 handle;
__s32 channel;
__s32 bandwidth;
};
Members
Description An An 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.
Definition struct fw_cdev_event_phy_packet {
__u64 closure;
__u32 type;
__u32 rcode;
__u32 length;
__u32 data[0];
};
Members
Description If type is If type is
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;
};
Members
Description Convenience union for userspace use. Events could be read(2) into an
appropriately aligned char buffer and then cast to this union for further
processing. Note that for a request, response or iso_interrupt event,
the data[] or header[] may make the size of the full event larger than
sizeof(
Definition struct fw_cdev_get_info {
__u32 version;
__u32 rom_length;
__u64 rom;
__u64 bus_reset;
__u64 bus_reset_closure;
__u32 card;
};
Members
Description The As a side effect, reception of
Definition struct fw_cdev_send_request {
__u32 tcode;
__u32 length;
__u64 offset;
__u64 closure;
__u64 data;
__u32 generation;
};
Members
Description Send a request to the device. This ioctl implements all outgoing requests.
Both quadlet and block request specify the payload as a pointer to the data
in the data field. Once the transaction completes, the kernel writes an
Definition struct fw_cdev_send_response {
__u32 rcode;
__u32 length;
__u64 data;
__u32 handle;
};
Members
Description Send a response to an incoming request. By setting up an address range using
the
Definition struct fw_cdev_allocate {
__u64 offset;
__u64 closure;
__u32 length;
__u32 handle;
__u64 region_end;
};
Members
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 an
offset within that address range. Every time when the kernel receives a
request within the range, an The closure field is passed back to userspace in these request events. The handle field is an out parameter, returning a handle to the allocated range to be used for later deallocation of the range. The address range is allocated on all local nodes. The address allocation
is exclusive except for the FCP command and response registers. If an
exclusive address region is already in use, the ioctl fails with errno set
to If kernel and client implement ABI version >= 4, the kernel looks up a free spot of size length inside [offset..**region_end**) and, if found, writes the start address of the new CSR back in offset. I.e. offset is an in and out parameter. If this automatic placement of a CSR in a bigger address range is not desired, the client simply needs to set region_end = offset + length. If the kernel or the client implements ABI version <= 3, region_end is ignored and effectively assumed to be offset + 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.
Definition struct fw_cdev_deallocate {
__u32 handle;
};
Members
Definition struct fw_cdev_initiate_bus_reset {
__u32 type;
};
Members
Description Initiate a bus reset for the bus this device is on. The bus reset can be either the original (long) bus reset or the arbitrated (short) bus reset introduced in 1394a-2000. The ioctl returns immediately. A subsequent
Definition struct fw_cdev_add_descriptor {
__u32 immediate;
__u32 key;
__u64 data;
__u32 length;
__u32 handle;
};
Members
Description Add a descriptor block and optionally a preceding immediate key to the local node’s Configuration ROM. The key field specifies the upper 8 bits of the descriptor root directory pointer and the data and length fields specify the contents. The key should be of the form 0xXX000000. The offset part of the root directory entry will be filled in by the kernel. If not 0, the immediate field specifies an immediate key which will be inserted before the root directory pointer. immediate, key, and data array elements are CPU-endian quadlets. If successful, the kernel adds the descriptor and writes back a handle to the kernel-side object to be used for later removal of the descriptor block and immediate key. The kernel will also generate a bus reset to signal the change of the Configuration ROM to other nodes. This ioctl affects the Configuration ROMs of all local nodes. The ioctl only succeeds on device files which represent a local node.
Definition struct fw_cdev_remove_descriptor {
__u32 handle;
};
Members
Description Remove a descriptor block and accompanying immediate key from the local nodes’ Configuration ROMs. The kernel will also generate a bus reset to signal the change of the Configuration ROM to other nodes.
Definition struct fw_cdev_create_iso_context {
__u32 type;
__u32 header_size;
__u32 channel;
__u32 speed;
__u64 closure;
__u32 handle;
};
Members
Description Prior to sending or receiving isochronous I/O, a context must be created. The context records information about the transmit or receive configuration and typically maps to an underlying hardware resource. A context is set up for either sending or receiving. It is bound to a specific isochronous channel. In case of multichannel reception, header_size and channel are ignored
and the channels are selected by For speed is ignored in receive context types. If a context was successfully created, the kernel writes back a handle to the context, 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 can create on a card at a time is a hardware limit, typically 4 or 8 contexts per direction, and of them at most one multichannel receive context.
Definition struct fw_cdev_set_iso_channels {
__u64 channels;
__u32 handle;
};
Members
Description channels is the bitwise or of 1ULL << n for each channel n to listen to. The ioctl fails with errno
Definition struct fw_cdev_iso_packet {
__u32 control;
__u32 header[0];
};
Members
Description
Context type control.HEADER_LENGTH must be a multiple of 4. It specifies the numbers of bytes in header that will be prepended to the packet’s payload. These bytes are copied into the kernel and will not be accessed after the ioctl has returned. The control.SY and TAG fields are copied to the iso packet header. These fields are specified by IEEE 1394a and IEC 61883-1. The control.SKIP flag specifies that no packet is to be sent in a frame. When using this, all other fields except control.INTERRUPT must be zero. When a packet with the control.INTERRUPT flag set has been completed, an
Context type 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, multiple packets are queued for this entry. The control.SY and TAG fields are ignored. If the control.SYNC flag is set, the context drops all packets until a
packet with a sy field is received which matches control.PAYLOAD_LENGTH defines how many payload bytes can be received for
one packet (in addition to payload quadlets that have been defined as headers
and are stripped and returned in the When a packet with the control.INTERRUPT flag set has been completed, an
Context type Here, control.PAYLOAD_LENGTH is the size of the buffer chunk and specifies room for 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 described for single-channel reception. When a buffer chunk with the control.INTERRUPT flag set has been filled
entirely, an
Definition struct fw_cdev_queue_iso {
__u64 packets;
__u64 data;
__u32 size;
__u32 handle;
};
Members
Description Queue a number of isochronous packets for reception or transmission.
This ioctl takes a pointer to an array of The kernel may or may not queue all packets, but will write back updated values of the packets, data and size fields, so the ioctl can be resubmitted easily. In case of a multichannel receive context, data must be quadlet-aligned relative to the buffer start.
Definition struct fw_cdev_start_iso {
__s32 cycle;
__u32 sync;
__u32 tags;
__u32 handle;
};
Members
Definition struct fw_cdev_stop_iso {
__u32 handle;
};
Members
Definition struct fw_cdev_flush_iso {
__u32 handle;
};
Members
Description For For Any
Definition struct fw_cdev_get_cycle_timer {
__u64 local_time;
__u32 cycle_timer;
};
Members
Description Same as In version 1 and 2 of the ABI, this ioctl returned unreliable (non- monotonic) cycle_timer values on certain controllers.
Definition struct fw_cdev_get_cycle_timer2 {
__s64 tv_sec;
__s32 tv_nsec;
__s32 clk_id;
__u32 cycle_timer;
};
Members
Description The clk_id lets you choose a clock like with POSIX’ clock_gettime function.
Supported clk_id values are POSIX’ cycle_timer consists of 7 bits cycleSeconds, 13 bits cycleCount, and 12 bits cycleOffset, in host byte order. Cf. the Cycle Time register per IEEE 1394 or Isochronous Cycle Timer register per OHCI-1394.
Definition struct fw_cdev_allocate_iso_resource {
__u64 closure;
__u64 channels;
__u32 bandwidth;
__u32 handle;
};
Members
Description The The The The To summarize, channels is a host-endian bitfield with the least significant bit representing 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 send one quadlet of data (payload or header data) at speed S1600.
Definition struct fw_cdev_send_stream_packet {
__u32 length;
__u32 tag;
__u32 channel;
__u32 sy;
__u64 closure;
__u64 data;
__u32 generation;
__u32 speed;
};
Members
Description The
Definition struct fw_cdev_send_phy_packet {
__u64 closure;
__u32 data[2];
__u32 generation;
};
Members
Description The The payload data[] shall be specified in host byte order. Usually, data[1] needs to be the bitwise inverse of data[0]. VersaPHY packets are an exception to this rule. The ioctl is only permitted on device files which represent a local node.
Definition struct fw_cdev_receive_phy_packets {
__u64 closure;
};
Members
Description This ioctl activates issuing of 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 2007 KernelVersion: 2.6.22 Contact: [email protected] Description: IEEE 1394 node device attributes. Read-only. Mutable during the node device's lifetime. See IEEE 1212 for semantic definitions. config_rom Contents of the Configuration ROM register. Binary attribute; an array of host-endian u32. guid The node's EUI-64 in the bus information block of Configuration ROM. Hexadecimal string representation of an u64. What: /sys/bus/firewire/devices/fw[0-9]+/units Date: June 2009 KernelVersion: 2.6.31 Contact: [email protected] Description: IEEE 1394 node device attribute. Read-only. Mutable during the node device's lifetime. See IEEE 1212 for semantic definitions. units Summary of all units present in an IEEE 1394 node. Contains space-separated tuples of specifier_id and version of each unit present in the node. Specifier_id and version are hexadecimal string representations of u24 of the respective unit directory entries. Specifier_id and version within each tuple are separated by a colon. Users: udev rules to set ownership and access permissions or ACLs of /dev/fw[0-9]+ character device files What: /sys/bus/firewire/devices/fw[0-9]+/is_local Date: July 2012 KernelVersion: 3.6 Contact: [email protected] Description: IEEE 1394 node device attribute. Read-only and immutable. Values: 1: The sysfs entry represents a local node (a controller card). 0: The sysfs entry represents a remote node. What: /sys/bus/firewire/devices/fw[0-9]+[.][0-9]+/ Date: May 2007 KernelVersion: 2.6.22 Contact: [email protected] Description: IEEE 1394 unit device attributes. Read-only. Immutable during the unit device's lifetime. See IEEE 1212 for semantic definitions. modalias Same as MODALIAS in the uevent at device creation. rom_index Offset of the unit directory within the parent device's (node device's) Configuration ROM, in quadlets. Decimal string representation. What: /sys/bus/firewire/devices/*/ Date: May 2007 KernelVersion: 2.6.22 Contact: [email protected] Description: Attributes common to IEEE 1394 node devices and unit devices. Read-only. Mutable during the node device's lifetime. Immutable during the unit device's lifetime. See IEEE 1212 for semantic definitions. These attributes are only created if the root directory of an IEEE 1394 node or the unit directory of an IEEE 1394 unit actually contains according entries. hardware_version Hexadecimal string representation of an u24. hardware_version_name Contents of a respective textual descriptor leaf. model Hexadecimal string representation of an u24. model_name Contents of a respective textual descriptor leaf. specifier_id Hexadecimal string representation of an u24. Mandatory in unit directories according to IEEE 1212. vendor Hexadecimal string representation of an u24. Mandatory in the root directory according to IEEE 1212. vendor_name Contents of a respective textual descriptor leaf. version Hexadecimal string representation of an u24. Mandatory in unit directories according to IEEE 1212. What: /sys/bus/firewire/drivers/sbp2/fw*/host*/target*/*:*:*:*/ieee1394_id formerly /sys/bus/ieee1394/drivers/sbp2/fw*/host*/target*/*:*:*:*/ieee1394_id Date: Feb 2004 KernelVersion: 2.6.4 Contact: [email protected] Description: SCSI target port identifier and logical unit identifier of a logical unit of an SBP-2 target. The identifiers are specified in SAM-2...SAM-4 annex A. They are persistent and world-wide unique properties the SBP-2 attached target. Read-only attribute, immutable during the target's lifetime. Format, as exposed by firewire-sbp2 since 2.6.22, May 2007: Colon-separated hexadecimal string representations of u64 EUI-64 : u24 directory_ID : u16 LUN without 0x prefixes, without whitespace. The former sbp2 driver (removed in 2.6.37 after being superseded by firewire-sbp2) used a somewhat shorter format which was not as close to SAM. Users: udev rules to create /dev/disk/by-id/ symlinks
Parameters
Description The string is taken from a minimal ASCII text descriptor leaf after the immediate entry with key. The string is zero-terminated. An overlong string is silently truncated such that it and the zero byte fit into size. Returns strlen(buf) or a negative error code. Firewire core transaction interfaces¶
Parameters
Description Submit a request packet into the asynchronous request transmission queue.
Can be called from atomic context. If you prefer a blocking API, use
In case of lock requests, specify one of the firewire-core specific Make sure that the value in destination_id is not older than the one in generation. Otherwise the request is in danger to be sent to a wrong node. In case of asynchronous stream packets i.e. The payload buffer at data is going to be DMA-mapped except in case of length <= 8 or of local (loopback) requests. Hence make sure that the buffer complies with the restrictions of the streaming DMA mapping API. payload must not be freed before the callback is called. In case of request types without payload, data is NULL and length is 0. After the transaction is completed successfully or unsuccessfully, the
callback will be called. Among its parameters is the response code which
is either one of the rcodes per IEEE 1394 or, in case of internal errors,
the firewire-core specific Note some timing corner cases:
Parameters
Description Returns the RCODE. See
Parameters
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 callback is invoked. The parameters passed to the callback give the details of the particular request. 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 by
Address allocations are exclusive, except for the FCP registers.
Parameters
Description To be called in process context. When
Parameters
Parameters
Firewire Isochronous I/O interfaces¶
Parameters
Description In parameters: card, generation, channels_mask, bandwidth, allocate Out 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 for channel 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 with channel = -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 independently of each other’s success. |
| You are visitor 01402503 — GeezerVison does not store the pages you look up. Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required. |