From bf337b15c28ae25904a73e7e2e0de2f9c4f0e9f8 Mon Sep 17 00:00:00 2001 From: August Lilleaas Date: Sun, 29 May 2011 19:07:19 +0200 Subject: firewire: net: replacing deprecated __attribute__((packed)) with __packed Fixing a deprecation, replacing __attribute__((packed)) with __packed. It was deprecated for portability, specifically to avoid GCC specific code. See commit 82ddcb040570411fc2d421d96b3e69711c670328. Signed-off-by: August Lilleaas Signed-off-by: Stefan Richter (added include compiler.h) --- drivers/firewire/net.c | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/drivers/firewire/net.c b/drivers/firewire/net.c index b9762d07198..512492a122d 100644 --- a/drivers/firewire/net.c +++ b/drivers/firewire/net.c @@ -7,6 +7,7 @@ */ #include +#include #include #include #include @@ -73,7 +74,7 @@ struct rfc2734_arp { __be32 fifo_lo; /* lo 32bits of sender's FIFO addr */ __be32 sip; /* Sender's IP Address */ __be32 tip; /* IP Address of requested hw addr */ -} __attribute__((packed)); +} __packed; /* This header format is specific to this driver implementation. */ #define FWNET_ALEN 8 @@ -81,7 +82,7 @@ struct rfc2734_arp { struct fwnet_header { u8 h_dest[FWNET_ALEN]; /* destination address */ __be16 h_proto; /* packet type ID field */ -} __attribute__((packed)); +} __packed; /* IPv4 and IPv6 encapsulation header */ struct rfc2734_header { -- cgit v1.2.3 From dd6254e5c0efe01ad255188898cb3dadf98cb56d Mon Sep 17 00:00:00 2001 From: Clemens Ladisch Date: Mon, 16 May 2011 08:10:10 +0200 Subject: firewire: ohci: remove superfluous posted write flushes The call to flush_writes() in context_stop() is superfluous because another register read is done immediately afterwards. The call to flush_writes() in ar_context_run() does not need to be done individually for each AR context, so move it to ohci_enable(). This also makes ohci_enable() clearer because it no longer depends on a side effect of ar_context_run() to flush its own register writes. Finally, the setting of a context's wake bit does not need to be flushed because neither the driver logic nor the API require the CPU to wait for this action. This removes the last MMIO reads from the packet queueing code paths. Signed-off-by: Clemens Ladisch Signed-off-by: Stefan Richter --- drivers/firewire/ohci.c | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/drivers/firewire/ohci.c b/drivers/firewire/ohci.c index 438e6c83117..e291edaa5ee 100644 --- a/drivers/firewire/ohci.c +++ b/drivers/firewire/ohci.c @@ -629,7 +629,6 @@ static void ar_context_link_page(struct ar_context *ctx, unsigned int index) ctx->last_buffer_index = index; reg_write(ctx->ohci, CONTROL_SET(ctx->regs), CONTEXT_WAKE); - flush_writes(ctx->ohci); } static void ar_context_release(struct ar_context *ctx) @@ -1001,7 +1000,6 @@ static void ar_context_run(struct ar_context *ctx) reg_write(ctx->ohci, COMMAND_PTR(ctx->regs), ctx->descriptors_bus | 1); reg_write(ctx->ohci, CONTROL_SET(ctx->regs), CONTEXT_RUN); - flush_writes(ctx->ohci); } static struct descriptor *find_branch_descriptor(struct descriptor *d, int z) @@ -1201,7 +1199,6 @@ static void context_stop(struct context *ctx) reg_write(ctx->ohci, CONTROL_CLEAR(ctx->regs), CONTEXT_RUN); ctx->running = false; - flush_writes(ctx->ohci); for (i = 0; i < 10; i++) { reg = reg_read(ctx->ohci, CONTROL_SET(ctx->regs)); @@ -1345,12 +1342,10 @@ static int at_context_queue_packet(struct context *ctx, context_append(ctx, d, z, 4 - z); - if (ctx->running) { + if (ctx->running) reg_write(ohci, CONTROL_SET(ctx->regs), CONTEXT_WAKE); - flush_writes(ohci); - } else { + else context_run(ctx, 0); - } return 0; } @@ -2196,7 +2191,9 @@ static int ohci_enable(struct fw_card *card, OHCI1394_LinkControl_rcvPhyPkt); ar_context_run(&ohci->ar_request_ctx); - ar_context_run(&ohci->ar_response_ctx); /* also flushes writes */ + ar_context_run(&ohci->ar_response_ctx); + + flush_writes(ohci); /* We are ready to go, reset bus to finish initialization. */ fw_schedule_bus_reset(&ohci->card, false, true); @@ -3128,7 +3125,6 @@ static void ohci_flush_queue_iso(struct fw_iso_context *base) &container_of(base, struct iso_context, base)->context; reg_write(ctx->ohci, CONTROL_SET(ctx->regs), CONTEXT_WAKE); - flush_writes(ctx->ohci); } static const struct fw_card_driver ohci_driver = { -- cgit v1.2.3 From 9ef28ccd59a23d219c4660f55a11ac06ca91f632 Mon Sep 17 00:00:00 2001 From: Stefan Richter Date: Sun, 12 Jun 2011 14:30:57 +0200 Subject: firewire: ohci: reduce potential context_stop latency Stopping an isochronous reception DMA context takes two loop iterations in context_stop on several controllers (JMicron, NEC, VIA). But there is no extra delay necessary between these two reg_read trials; the MMIO reads themselves are slow enough. Hence bring back the behavior from before commit dd6254e5c0efe01ad255188898cb3dadf98cb56d "firewire: ohci: remove superfluous posted write flushes" on these controllers by means of an "if (i)" condition. Isochronous context stop is performed in preemptible contexts (and only rarely), hence this change is of little impact. (Besides, Agere and TI controllers always, or almost always, have the context stopped already at the first ContextControl read.) More important is asynchronous transmit context stop, which is performed while local interrupts are disabled (on the two AT DMAs in bus_reset_tasklet, i.e. after a self-ID-complete event). In my experience with several controllers, tested with a usermode AT-request transmitter as well as with FTP transmission over firewire-net, the AT contexts were luckily already stopped at the first ContextControl read, i.e. never required another MMIO read let alone mdelay. A possible explanation for this is that the controllers which I tested perhaps stop AT DMA before they perform the self-ID reception DMA. But we cannot be sure about that and should keep the interrupts-disabled busy loop as short as possible. Hence, query the ContextControl register in 1000 udelay(10) intervals instead of 10 udelay(1000) intervals. I understand from an estimation by Clemens Ladisch that stopping a busy DMA context should take microseconds or at worst tens of microseconds, not milliseconds. Signed-off-by: Stefan Richter --- drivers/firewire/ohci.c | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/drivers/firewire/ohci.c b/drivers/firewire/ohci.c index e291edaa5ee..3b6f3429fb4 100644 --- a/drivers/firewire/ohci.c +++ b/drivers/firewire/ohci.c @@ -1200,12 +1200,13 @@ static void context_stop(struct context *ctx) reg_write(ctx->ohci, CONTROL_CLEAR(ctx->regs), CONTEXT_RUN); ctx->running = false; - for (i = 0; i < 10; i++) { + for (i = 0; i < 1000; i++) { reg = reg_read(ctx->ohci, CONTROL_SET(ctx->regs)); if ((reg & CONTEXT_ACTIVE) == 0) return; - mdelay(1); + if (i) + udelay(10); } fw_error("Error: DMA context still active (0x%08x)\n", reg); } -- cgit v1.2.3 From b14c369d87d7fbf120ad21919d34a8f1290290f1 Mon Sep 17 00:00:00 2001 From: Stefan Richter Date: Tue, 21 Jun 2011 15:24:26 +0200 Subject: firewire: ohci: add a comment on PHY reg access serialization Signed-off-by: Stefan Richter --- drivers/firewire/ohci.c | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/drivers/firewire/ohci.c b/drivers/firewire/ohci.c index 3b6f3429fb4..a818dc83469 100644 --- a/drivers/firewire/ohci.c +++ b/drivers/firewire/ohci.c @@ -513,6 +513,12 @@ static inline void flush_writes(const struct fw_ohci *ohci) reg_read(ohci, OHCI1394_Version); } +/* + * Beware! read_phy_reg(), write_phy_reg(), update_phy_reg(), and + * read_paged_phy_reg() require the caller to hold ohci->phy_reg_mutex. + * In other words, only use ohci_read_phy_reg() and ohci_update_phy_reg() + * directly. Exceptions are intrinsically serialized contexts like pci_probe. + */ static int read_phy_reg(struct fw_ohci *ohci, int addr) { u32 val; -- cgit v1.2.3 From 215fa444c2a6d571f1f915cf3dc7a8b01cc51a0a Mon Sep 17 00:00:00 2001 From: Stefan Richter Date: Wed, 22 Jun 2011 21:05:08 +0200 Subject: firewire: ohci: fix PHY reg access after card ejection Detect and handle ejection of FireWire CardBus cards in PHY register accesses: - The last attempt of firewire-core to reset the bus during shutdown caused a spurious "firewire_ohci: failed to write phy reg" error message in the log. Skip this message as well as the prior retry loop that needlessly took 100 milliseconds. - In the unlikely case that a PHY register was read right after card ejection, a bogus value was obtained and possibly acted upon. Instead, fail the read attempt. Signed-off-by: Stefan Richter --- drivers/firewire/ohci.c | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/drivers/firewire/ohci.c b/drivers/firewire/ohci.c index a818dc83469..44859887627 100644 --- a/drivers/firewire/ohci.c +++ b/drivers/firewire/ohci.c @@ -527,6 +527,9 @@ static int read_phy_reg(struct fw_ohci *ohci, int addr) reg_write(ohci, OHCI1394_PhyControl, OHCI1394_PhyControl_Read(addr)); for (i = 0; i < 3 + 100; i++) { val = reg_read(ohci, OHCI1394_PhyControl); + if (!~val) + return -ENODEV; /* Card was ejected. */ + if (val & OHCI1394_PhyControl_ReadDone) return OHCI1394_PhyControl_ReadData(val); @@ -550,6 +553,9 @@ static int write_phy_reg(const struct fw_ohci *ohci, int addr, u32 val) OHCI1394_PhyControl_Write(addr, val)); for (i = 0; i < 3 + 100; i++) { val = reg_read(ohci, OHCI1394_PhyControl); + if (!~val) + return -ENODEV; /* Card was ejected. */ + if (!(val & OHCI1394_PhyControl_WritePending)) return 0; -- cgit v1.2.3 From 9f426173e54a4f0882f9516c226f3165a3bd5474 Mon Sep 17 00:00:00 2001 From: Stefan Richter Date: Sun, 3 Jul 2011 17:39:26 +0200 Subject: firewire: ohci: skip soft reset retries after card ejection The software reset in firewire-ohci's pci_remove does not have a great prospect of success if the card was already physically removed at this point. So let's skip the 500 ms that were spent in retries here. Also, replace a defined constant by its open-coded value. This is not a constant from a specification but an arbitrarily chosen retry limit. It was only used in this single place. Signed-off-by: Stefan Richter --- drivers/firewire/ohci.c | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/drivers/firewire/ohci.c b/drivers/firewire/ohci.c index 44859887627..4f6d72f87f6 100644 --- a/drivers/firewire/ohci.c +++ b/drivers/firewire/ohci.c @@ -253,7 +253,6 @@ static inline struct fw_ohci *fw_ohci(struct fw_card *card) #define OHCI1394_MAX_PHYS_RESP_RETRIES 0x8 #define OHCI1394_REGISTER_SIZE 0x800 -#define OHCI_LOOP_COUNT 500 #define OHCI1394_PCI_HCI_Control 0x40 #define SELF_ID_BUF_SIZE 0x800 #define OHCI_TCODE_PHY_PACKET 0x0e @@ -1967,14 +1966,18 @@ static irqreturn_t irq_handler(int irq, void *data) static int software_reset(struct fw_ohci *ohci) { + u32 val; int i; reg_write(ohci, OHCI1394_HCControlSet, OHCI1394_HCControl_softReset); + for (i = 0; i < 500; i++) { + val = reg_read(ohci, OHCI1394_HCControlSet); + if (!~val) + return -ENODEV; /* Card was ejected. */ - for (i = 0; i < OHCI_LOOP_COUNT; i++) { - if ((reg_read(ohci, OHCI1394_HCControlSet) & - OHCI1394_HCControl_softReset) == 0) + if (!(val & OHCI1394_HCControl_softReset)) return 0; + msleep(1); } -- cgit v1.2.3 From d873d794235efa590ab3c94d5ee22bb1fab19ac4 Mon Sep 17 00:00:00 2001 From: Stefan Richter Date: Sat, 9 Jul 2011 16:42:26 +0200 Subject: firewire: cdev: return -ENOTTY for unimplemented ioctls, not -EINVAL On Jun 27 Linus Torvalds wrote: > The correct error code for "I don't understand this ioctl" is ENOTTY. > The naming may be odd, but you should think of that error value as a > "unrecognized ioctl number, you're feeding me random numbers that I > don't understand and I assume for historical reasons that you tried to > do some tty operation on me". [...] > The EINVAL thing goes way back, and is a disaster. It predates Linux > itself, as far as I can tell. You'll find lots of man-pages that have > this line in it: > > EINVAL Request or argp is not valid. > > and it shows up in POSIX etc. And sadly, it generally shows up > _before_ the line that says > > ENOTTY The specified request does not apply to the kind of object > that the descriptor d references. > > so a lot of people get to the EINVAL, and never even notice the ENOTTY. [...] > At least glibc (and hopefully other C libraries) use a _string_ that > makes much more sense: strerror(ENOTTY) is "Inappropriate ioctl for > device" So let's correct this in the ABI while it is still young, relative to distributor adoption. Side note: We return -ENOTTY not only on _IOC_TYPE or _IOC_NR mismatch, but also on _IOC_SIZE mismatch. An ioctl with an unsupported size of argument structure can be seen as an unsupported version of that ioctl. Signed-off-by: Stefan Richter Cc: --- drivers/firewire/core-cdev.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/drivers/firewire/core-cdev.c b/drivers/firewire/core-cdev.c index b1c11775839..9b5915ebeb3 100644 --- a/drivers/firewire/core-cdev.c +++ b/drivers/firewire/core-cdev.c @@ -1583,7 +1583,7 @@ static int dispatch_ioctl(struct client *client, if (_IOC_TYPE(cmd) != '#' || _IOC_NR(cmd) >= ARRAY_SIZE(ioctl_handlers) || _IOC_SIZE(cmd) > sizeof(buffer)) - return -EINVAL; + return -ENOTTY; if (_IOC_DIR(cmd) == _IOC_READ) memset(&buffer, 0, _IOC_SIZE(cmd)); -- cgit v1.2.3 From 93b37905f70083d6143f5f4dba0a45cc64379a62 Mon Sep 17 00:00:00 2001 From: Stefan Richter Date: Sat, 9 Jul 2011 16:43:22 +0200 Subject: firewire: cdev: prevent race between first get_info ioctl and bus reset event queuing Between open(2) of a /dev/fw* and the first FW_CDEV_IOC_GET_INFO ioctl(2) on it, the kernel already queues FW_CDEV_EVENT_BUS_RESET events to be read(2) by the client. The get_info ioctl is practically always issued right away after open, hence this condition only occurs if the client opens during a bus reset, especially during a rapid series of bus resets. The problem with this condition is twofold: - These bus reset events carry the (as yet undocumented) @closure value of 0. But it is not the kernel's place to choose closures; they are privat to the client. E.g., this 0 value forced from the kernel makes it unsafe for clients to dereference it as a pointer to a closure object without NULL pointer check. - It is impossible for clients to determine the relative order of bus reset events from get_info ioctl(2) versus those from read(2), except in one way: By comparison of closure values. Again, such a procedure imposes complexity on clients and reduces freedom in use of the bus reset closure. So, change the ABI to suppress queuing of bus reset events before the first FW_CDEV_IOC_GET_INFO ioctl was issued by the client. Note, this ABI change cannot be version-controlled. The kernel cannot distinguish old from new clients before the first FW_CDEV_IOC_GET_INFO ioctl. We will try to back-merge this change into currently maintained stable/ longterm series, and we only document the new behaviour. The old behavior is now considered a kernel bug, which it basically is. Signed-off-by: Stefan Richter Cc: --- drivers/firewire/core-cdev.c | 18 ++++++++++-------- include/linux/firewire-cdev.h | 3 +++ 2 files changed, 13 insertions(+), 8 deletions(-) diff --git a/drivers/firewire/core-cdev.c b/drivers/firewire/core-cdev.c index 9b5915ebeb3..e6ad3bb6c1a 100644 --- a/drivers/firewire/core-cdev.c +++ b/drivers/firewire/core-cdev.c @@ -253,14 +253,11 @@ static int fw_device_op_open(struct inode *inode, struct file *file) init_waitqueue_head(&client->wait); init_waitqueue_head(&client->tx_flush_wait); INIT_LIST_HEAD(&client->phy_receiver_link); + INIT_LIST_HEAD(&client->link); kref_init(&client->kref); file->private_data = client; - mutex_lock(&device->client_list_mutex); - list_add_tail(&client->link, &device->client_list); - mutex_unlock(&device->client_list_mutex); - return nonseekable_open(inode, file); } @@ -451,15 +448,20 @@ static int ioctl_get_info(struct client *client, union ioctl_arg *arg) if (ret != 0) return -EFAULT; + mutex_lock(&client->device->client_list_mutex); + client->bus_reset_closure = a->bus_reset_closure; if (a->bus_reset != 0) { fill_bus_reset_event(&bus_reset, client); - if (copy_to_user(u64_to_uptr(a->bus_reset), - &bus_reset, sizeof(bus_reset))) - return -EFAULT; + ret = copy_to_user(u64_to_uptr(a->bus_reset), + &bus_reset, sizeof(bus_reset)); } + if (ret == 0 && list_empty(&client->link)) + list_add_tail(&client->link, &client->device->client_list); - return 0; + mutex_unlock(&client->device->client_list_mutex); + + return ret ? -EFAULT : 0; } static int add_client_resource(struct client *client, diff --git a/include/linux/firewire-cdev.h b/include/linux/firewire-cdev.h index 4ff09889c5c..55814aa33be 100644 --- a/include/linux/firewire-cdev.h +++ b/include/linux/firewire-cdev.h @@ -475,6 +475,9 @@ union fw_cdev_event { * of the bus. This does not cause a bus reset to happen. * @bus_reset_closure: Value of &closure in this and subsequent bus reset events * @card: The index of the card this device belongs to + * + * As a side effect, reception of %FW_CDEV_EVENT_BUS_RESET events to be read(2) + * is started by this ioctl. */ struct fw_cdev_get_info { __u32 version; -- cgit v1.2.3 From f6a7cd0212c359f7b55414aeee364ee7cac363cc Mon Sep 17 00:00:00 2001 From: Stefan Richter Date: Thu, 14 Jul 2011 21:08:39 +0200 Subject: firewire: cdev: ABI documentation enhancements Add overview documentation in Documentation/ABI/stable/firewire-cdev. Improve the inline reference documentation in firewire-cdev.h: - Add /* available since kernel... */ comments to event numbers consistent with the comments on ioctl numbers. - Shorten some documentation on an event and an ioctl that are less interesting to current programming because there are newer preferable variants. - Spell Configuration ROM (name of an IEEE 1212 register) in upper case. - Move the dummy FW_CDEV_VERSION out of the reader's field of vision. We should remove it from the header next year or so. Signed-off-by: Stefan Richter --- Documentation/ABI/stable/firewire-cdev | 103 +++++++++++++++++++++++++++++++++ include/linux/firewire-cdev.h | 75 +++++++++++------------- 2 files changed, 137 insertions(+), 41 deletions(-) create mode 100644 Documentation/ABI/stable/firewire-cdev diff --git a/Documentation/ABI/stable/firewire-cdev b/Documentation/ABI/stable/firewire-cdev new file mode 100644 index 00000000000..16d03082736 --- /dev/null +++ b/Documentation/ABI/stable/firewire-cdev @@ -0,0 +1,103 @@ +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 . + + 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 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 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 + tools like jujuutils, fwhack, ... diff --git a/include/linux/firewire-cdev.h b/include/linux/firewire-cdev.h index 55814aa33be..357dbfc2829 100644 --- a/include/linux/firewire-cdev.h +++ b/include/linux/firewire-cdev.h @@ -30,10 +30,13 @@ #include #include +/* available since kernel version 2.6.22 */ #define FW_CDEV_EVENT_BUS_RESET 0x00 #define FW_CDEV_EVENT_RESPONSE 0x01 #define FW_CDEV_EVENT_REQUEST 0x02 #define FW_CDEV_EVENT_ISO_INTERRUPT 0x03 + +/* available since kernel version 2.6.30 */ #define FW_CDEV_EVENT_ISO_RESOURCE_ALLOCATED 0x04 #define FW_CDEV_EVENT_ISO_RESOURCE_DEALLOCATED 0x05 @@ -120,24 +123,11 @@ struct fw_cdev_event_response { /** * struct fw_cdev_event_request - Old version of &fw_cdev_event_request2 - * @closure: See &fw_cdev_event_common; set by %FW_CDEV_IOC_ALLOCATE ioctl * @type: See &fw_cdev_event_common; always %FW_CDEV_EVENT_REQUEST - * @tcode: See &fw_cdev_event_request2 - * @offset: See &fw_cdev_event_request2 - * @handle: See &fw_cdev_event_request2 - * @length: See &fw_cdev_event_request2 - * @data: See &fw_cdev_event_request2 * * This event is sent instead of &fw_cdev_event_request2 if the kernel or - * the client implements ABI version <= 3. - * - * Unlike &fw_cdev_event_request2, the sender identity cannot be established, - * broadcast write requests cannot be distinguished from unicast writes, and - * @tcode of lock requests is %TCODE_LOCK_REQUEST. - * - * Requests to the FCP_REQUEST or FCP_RESPONSE register are responded to as - * with &fw_cdev_event_request2, except in kernel 2.6.32 and older which send - * the response packet of the client's %FW_CDEV_IOC_SEND_RESPONSE ioctl. + * the client implements ABI version <= 3. &fw_cdev_event_request lacks + * essential information; use &fw_cdev_event_request2 instead. */ struct fw_cdev_event_request { __u64 closure; @@ -452,30 +442,29 @@ union fw_cdev_event { * %FW_CDEV_ISO_CONTEXT_RECEIVE_MULTICHANNEL, and * %FW_CDEV_IOC_SET_ISO_CHANNELS */ -#define FW_CDEV_VERSION 3 /* Meaningless; don't use this macro. */ /** * struct fw_cdev_get_info - General purpose information ioctl * @version: The version field is just a running serial number. Both an * input parameter (ABI version implemented by the client) and * output parameter (ABI version implemented by the kernel). - * A client must not fill in an %FW_CDEV_VERSION defined from an - * included kernel header file but the actual version for which - * the client was implemented. This is necessary for forward - * compatibility. We never break backwards compatibility, but - * may add more structs, events, and ioctls in later revisions. - * @rom_length: If @rom is non-zero, at most rom_length bytes of configuration + * A client shall fill in the ABI @version for which the client + * was implemented. This is necessary for forward compatibility. + * @rom_length: If @rom is non-zero, up to @rom_length bytes of Configuration * ROM will be copied into that user space address. In either * case, @rom_length is updated with the actual length of the - * configuration ROM. + * Configuration ROM. * @rom: If non-zero, address of a buffer to be filled by a copy of the - * device's configuration ROM + * device's Configuration ROM * @bus_reset: If non-zero, address of a buffer to be filled by a * &struct fw_cdev_event_bus_reset with the current state * of the bus. This does not cause a bus reset to happen. * @bus_reset_closure: Value of &closure in this and subsequent bus reset events * @card: The index of the card this device belongs to * + * The %FW_CDEV_IOC_GET_INFO ioctl is usually the very first one which a client + * performs right after it opened a /dev/fw* file. + * * As a side effect, reception of %FW_CDEV_EVENT_BUS_RESET events to be read(2) * is started by this ioctl. */ @@ -615,7 +604,7 @@ struct fw_cdev_initiate_bus_reset { * @handle: Handle to the descriptor, written by the kernel * * Add a descriptor block and optionally a preceding immediate key to the local - * node's configuration ROM. + * 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 @@ -630,9 +619,9 @@ struct fw_cdev_initiate_bus_reset { * 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. + * change of the Configuration ROM to other nodes. * - * This ioctl affects the configuration ROMs of all local nodes. + * This ioctl affects the Configuration ROMs of all local nodes. * The ioctl only succeeds on device files which represent a local node. */ struct fw_cdev_add_descriptor { @@ -644,13 +633,13 @@ struct fw_cdev_add_descriptor { }; /** - * struct fw_cdev_remove_descriptor - Remove contents from the configuration ROM + * struct fw_cdev_remove_descriptor - Remove contents from the Configuration ROM * @handle: Handle to the descriptor, as returned by the kernel when the * descriptor was added * * 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. + * nodes' Configuration ROMs. The kernel will also generate a bus reset to + * signal the change of the Configuration ROM to other nodes. */ struct fw_cdev_remove_descriptor { __u32 handle; @@ -866,13 +855,8 @@ struct fw_cdev_stop_iso { * @local_time: system time, in microseconds since the Epoch * @cycle_timer: Cycle Time register contents * - * The %FW_CDEV_IOC_GET_CYCLE_TIMER ioctl reads the isochronous cycle timer - * and also the system clock (%CLOCK_REALTIME). This allows to express the - * receive time of an isochronous packet as a system time. - * - * @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. + * Same as %FW_CDEV_IOC_GET_CYCLE_TIMER2, but fixed to use %CLOCK_REALTIME + * and only with microseconds resolution. * * In version 1 and 2 of the ABI, this ioctl returned unreliable (non- * monotonic) @cycle_timer values on certain controllers. @@ -889,10 +873,17 @@ struct fw_cdev_get_cycle_timer { * @clk_id: input parameter, clock from which to get the system time * @cycle_timer: Cycle Time register contents * - * The %FW_CDEV_IOC_GET_CYCLE_TIMER2 works like - * %FW_CDEV_IOC_GET_CYCLE_TIMER but lets you choose a clock like with POSIX' - * clock_gettime function. Supported @clk_id values are POSIX' %CLOCK_REALTIME - * and %CLOCK_MONOTONIC and Linux' %CLOCK_MONOTONIC_RAW. + * The %FW_CDEV_IOC_GET_CYCLE_TIMER2 ioctl reads the isochronous cycle timer + * and also the system clock. This allows to correlate reception time of + * isochronous packets with system time. + * + * @clk_id lets you choose a clock like with POSIX' clock_gettime function. + * Supported @clk_id values are POSIX' %CLOCK_REALTIME and %CLOCK_MONOTONIC + * and Linux' %CLOCK_MONOTONIC_RAW. + * + * @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. */ struct fw_cdev_get_cycle_timer2 { __s64 tv_sec; @@ -1014,4 +1005,6 @@ struct fw_cdev_receive_phy_packets { __u64 closure; }; +#define FW_CDEV_VERSION 3 /* Meaningless legacy macro; don't use it. */ + #endif /* _LINUX_FIREWIRE_CDEV_H */ -- cgit v1.2.3 From 9a00c24ae7cb08dcd46edf1327a47871e8466444 Mon Sep 17 00:00:00 2001 From: Stefan Richter Date: Sat, 9 Jul 2011 16:48:29 +0200 Subject: firewire: document the sysfs ABIs of firewire-core and firewire-sbp2. Signed-off-by: Stefan Richter --- Documentation/ABI/stable/sysfs-bus-firewire | 122 ++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 Documentation/ABI/stable/sysfs-bus-firewire diff --git a/Documentation/ABI/stable/sysfs-bus-firewire b/Documentation/ABI/stable/sysfs-bus-firewire new file mode 100644 index 00000000000..3d484e5dc84 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-bus-firewire @@ -0,0 +1,122 @@ +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]+[.][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 -- cgit v1.2.3