From e105b8bfc769b0545b6f0f395179d1e43cbee822 Mon Sep 17 00:00:00 2001 From: Dan Williams Date: Mon, 21 Apr 2008 10:51:07 -0700 Subject: sysfs: add /sys/dev/{char,block} to lookup sysfs path by major:minor Why?: There are occasions where userspace would like to access sysfs attributes for a device but it may not know how sysfs has named the device or the path. For example what is the sysfs path for /dev/disk/by-id/ata-ST3160827AS_5MT004CK? With this change a call to stat(2) returns the major:minor then userspace can see that /sys/dev/block/8:32 links to /sys/block/sdc. What are the alternatives?: 1/ Add an ioctl to return the path: Doable, but sysfs is meant to reduce the need to proliferate ioctl interfaces into the kernel, so this seems counter productive. 2/ Use udev to create these symlinks: Also doable, but it adds a udev dependency to utilities that might be running in a limited environment like an initramfs. 3/ Do a full-tree search of sysfs. [kay.sievers@vrfy.org: fix duplicate registrations] [kay.sievers@vrfy.org: cleanup suggestions] Cc: Neil Brown Cc: Tejun Heo Acked-by: Kay Sievers Reviewed-by: SL Baur Acked-by: Kay Sievers Acked-by: Mark Lord Acked-by: H. Peter Anvin Signed-off-by: Dan Williams Signed-off-by: Greg Kroah-Hartman --- Documentation/ABI/testing/sysfs-dev | 20 ++++++++++++++++++++ Documentation/filesystems/sysfs.txt | 6 ++++++ 2 files changed, 26 insertions(+) create mode 100644 Documentation/ABI/testing/sysfs-dev (limited to 'Documentation') diff --git a/Documentation/ABI/testing/sysfs-dev b/Documentation/ABI/testing/sysfs-dev new file mode 100644 index 00000000000..a9f2b8b0530 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-dev @@ -0,0 +1,20 @@ +What: /sys/dev +Date: April 2008 +KernelVersion: 2.6.26 +Contact: Dan Williams +Description: The /sys/dev tree provides a method to look up the sysfs + path for a device using the information returned from + stat(2). There are two directories, 'block' and 'char', + beneath /sys/dev containing symbolic links with names of + the form ":". These links point to the + corresponding sysfs path for the given device. + + Example: + $ readlink /sys/dev/block/8:32 + ../../block/sdc + + Entries in /sys/dev/char and /sys/dev/block will be + dynamically created and destroyed as devices enter and + leave the system. + +Users: mdadm diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt index 7f27b8f840d..9e9c348275a 100644 --- a/Documentation/filesystems/sysfs.txt +++ b/Documentation/filesystems/sysfs.txt @@ -248,6 +248,7 @@ The top level sysfs directory looks like: block/ bus/ class/ +dev/ devices/ firmware/ net/ @@ -274,6 +275,11 @@ fs/ contains a directory for some filesystems. Currently each filesystem wanting to export attributes must create its own hierarchy below fs/ (see ./fuse.txt for an example). +dev/ contains two directories char/ and block/. Inside these two +directories there are symlinks named :. These symlinks +point to the sysfs directory for the given device. /sys/dev provides a +quick way to lookup the sysfs interface for a device from the result of +a stat(2) operation. More information can driver-model specific features can be found in Documentation/driver-model/. -- cgit v1.2.3 From 328a14e70e7f46997cb50d4258dd93d5377f98c6 Mon Sep 17 00:00:00 2001 From: "Hans J. Koch" Date: Fri, 23 May 2008 13:50:14 +0200 Subject: UIO: Add write function to allow irq masking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sometimes it is necessary to enable/disable the interrupt of a UIO device from the userspace part of the driver. With this patch, the UIO kernel driver can implement an "irqcontrol()" function that does this. Userspace can write an s32 value to /dev/uioX (usually 0 or 1 to turn the irq off or on). The UIO core will then call the driver's irqcontrol function. Signed-off-by: Hans J. Koch Acked-by: Uwe Kleine-König Acked-by: Magnus Damm Signed-off-by: Greg Kroah-Hartman --- Documentation/DocBook/uio-howto.tmpl | 40 +++++++++++++++++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index fdd7f4f887b..c4d18731396 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -29,6 +29,12 @@ + + 0.5 + 2008-05-22 + hjk + Added description of write() function. + 0.4 2007-11-26 @@ -64,7 +70,7 @@ Copyright and License - Copyright (c) 2006 by Hans-Jürgen Koch. + Copyright (c) 2006-2008 by Hans-Jürgen Koch. This documentation is Free Software licensed under the terms of the GPL version 2. @@ -189,6 +195,30 @@ interested in translating it, please email me represents the total interrupt count. You can use this number to figure out if you missed some interrupts. + + For some hardware that has more than one interrupt source internally, + but not separate IRQ mask and status registers, there might be + situations where userspace cannot determine what the interrupt source + was if the kernel handler disables them by writing to the chip's IRQ + register. In such a case, the kernel has to disable the IRQ completely + to leave the chip's register untouched. Now the userspace part can + determine the cause of the interrupt, but it cannot re-enable + interrupts. Another cornercase is chips where re-enabling interrupts + is a read-modify-write operation to a combined IRQ status/acknowledge + register. This would be racy if a new interrupt occurred + simultaneously. + + + To address these problems, UIO also implements a write() function. It + is normally not used and can be ignored for hardware that has only a + single interrupt source or has separate IRQ mask and status registers. + If you need it, however, a write to /dev/uioX + will call the irqcontrol() function implemented + by the driver. You have to write a 32-bit value that is usually either + 0 or 1 to disable or enable interrupts. If a driver does not implement + irqcontrol(), write() will + return with -ENOSYS. + To handle interrupts properly, your custom kernel module can @@ -362,6 +392,14 @@ device is actually used. open(), you will probably also want a custom release() function. + + +int (*irqcontrol)(struct uio_info *info, s32 irq_on) +: Optional. If you need to be able to enable or disable +interrupts from userspace by writing to /dev/uioX, +you can implement this function. The parameter irq_on +will be 0 to disable interrupts and 1 to enable them. + -- cgit v1.2.3 From 17149d9fff18c4811349140934dc541f70c617df Mon Sep 17 00:00:00 2001 From: Mike Frysinger Date: Tue, 24 Jun 2008 14:24:57 -0700 Subject: uio-howto.tmpl: use standard copyright/legal markings The Userspace I/O HOWTO document uses straight tags and plain text to describe copyright/legal information. It should instead use the and tags like all other documents in the kernel. Signed-off-by: Mike Frysinger Acked-by: Hans J. Koch Cc: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Greg Kroah-Hartman --- Documentation/DocBook/uio-howto.tmpl | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index c4d18731396..d799a2621e2 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -21,6 +21,18 @@ + + 2006-2008 + Hans-Jürgen Koch. + + + + +This documentation is Free Software licensed under the terms of the +GPL version 2. + + + 2006-12-11 @@ -66,17 +78,6 @@ About this document - - -Copyright and License - - Copyright (c) 2006-2008 by Hans-Jürgen Koch. - -This documentation is Free Software licensed under the terms of the -GPL version 2. - - - Translations -- cgit v1.2.3 From 4f7e53096c93f0bdf2205134dfc541d0c3cc6e41 Mon Sep 17 00:00:00 2001 From: Mike Frysinger Date: Tue, 24 Jun 2008 14:25:00 -0700 Subject: uio-howto.tmpl: use unique output names The Userspace I/O HOWTO template sets two different sections with the same html output name (about.html). This clearly won't work, so change the first one to a unique "aboutthis.html" to prevent clobbering. Signed-off-by: Mike Frysinger Acked-by: Hans J. Koch Cc: Randy Dunlap Signed-off-by: Andrew Morton Signed-off-by: Greg Kroah-Hartman --- Documentation/DocBook/uio-howto.tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index d799a2621e2..df87d1b9360 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -75,7 +75,7 @@ GPL version 2. - + About this document -- cgit v1.2.3 From 43166141f73f969794bd7c850c89913631df99e4 Mon Sep 17 00:00:00 2001 From: Tsugikazu Shibata Date: Fri, 20 Jun 2008 10:59:52 +0900 Subject: HOWTO: change email addresses of James in HOWTO Signed-off-by: Tsugikazu Shibata Signed-off-by: Greg Kroah-Hartman --- Documentation/HOWTO | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/HOWTO b/Documentation/HOWTO index 619e8caf30d..c2371c5a98f 100644 --- a/Documentation/HOWTO +++ b/Documentation/HOWTO @@ -358,7 +358,7 @@ Here is a list of some of the different kernel trees available: - pcmcia, Dominik Brodowski git.kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git - - SCSI, James Bottomley + - SCSI, James Bottomley git.kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git - x86, Ingo Molnar -- cgit v1.2.3 From 83c79b55f0d929a0dcf2b0d347cd1875afc06f21 Mon Sep 17 00:00:00 2001 From: Nathan Lynch Date: Wed, 2 Jul 2008 10:21:30 -0700 Subject: sysfs-rules.txt: reword API stability statement The first paragraph of this document implies that user space developers shouldn't use sysfs at all, but then it goes on to describe rules that developers should follow when accessing sysfs. Not only is this somewhat self-contradictory, it has been shown to discourage developers from using established sysfs interfaces. A note of caution is more appropriate than a blanket "sysfs will never be stable" assertion. Signed-off-by: Nathan Lynch Cc: Stephen Rothwell Signed-off-by: Andrew Morton Signed-off-by: Greg Kroah-Hartman --- Documentation/sysfs-rules.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'Documentation') diff --git a/Documentation/sysfs-rules.txt b/Documentation/sysfs-rules.txt index 80ef562160b..6049a2a84dd 100644 --- a/Documentation/sysfs-rules.txt +++ b/Documentation/sysfs-rules.txt @@ -3,9 +3,8 @@ Rules on how to access information in the Linux kernel sysfs The kernel-exported sysfs exports internal kernel implementation details and depends on internal kernel structures and layout. It is agreed upon by the kernel developers that the Linux kernel does not provide a stable -internal API. As sysfs is a direct export of kernel internal -structures, the sysfs interface cannot provide a stable interface either; -it may always change along with internal kernel changes. +internal API. Therefore, there are aspects of the sysfs interface that +may not be stable across kernel releases. To minimize the risk of breaking users of sysfs, which are in most cases low-level userspace applications, with a new kernel release, the users -- cgit v1.2.3