UIO patches for 2.6.22

Here are the UIO (Userspace I/O driver framework) patches for 2.6.22

They have been revamped from the last time you have seen them, and they include a real driver, the Hilscher CIF DeviceNet and Profibus card controller, which is being used in production systems with this driver framework right now. The kernel driver they replaced was a total mess, with over 60+ ioctls to try to control the different aspects of the device. See the last patch in this series for more details on this driver.

These patches include full documentation, are self-contained from the rest of the kernel, and have been in the -mm tree for the past few months with no complaints.

Please pull from:

	master.kernel.org:/pub/scm/linux/kernel/git/gregkh/uio-2.6.git/

Patches will be sent as a follow-on to this message to lkml for people to see.

thanks,

greg k-h

 Documentation/DocBook/kernel-api.tmpl |    4 +
 Documentation/DocBook/uio-howto.tmpl  |  611 ++++++++++++++++++++++++++++
 drivers/Kconfig                       |    1 +
 drivers/Makefile                      |    1 +
 drivers/uio/Kconfig                   |   29 ++
 drivers/uio/Makefile                  |    2 +
 drivers/uio/uio.c                     |  701 +++++++++++++++++++++++++++++++++
 drivers/uio/uio_cif.c                 |  156 ++++++++
 include/linux/uio_driver.h            |   91 +++++
 9 files changed, 1596 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/DocBook/uio-howto.tmpl
 create mode 100644 drivers/uio/Kconfig
 create mode 100644 drivers/uio/Makefile
 create mode 100644 drivers/uio/uio.c
 create mode 100644 drivers/uio/uio_cif.c
 create mode 100644 include/linux/uio_driver.h

---------------

Hans J. Koch (2):
UIO: Add the User IO core code
UIO: Documentation

Hans-Jürgen Koch (1):
UIO: Hilscher CIF card driver

From: Hans J. Koch <[email protected]>

This interface allows the ability to write the majority of a driver in userspace with only a very small shell of a driver in the kernel itself. It uses a char device and sysfs to interact with a userspace process to process interrupts and control memory accesses.

See the docbook documentation for more details on how to use this interface.

From: Hans J. Koch <[email protected]>

---
 drivers/Kconfig            |    1 +
 drivers/Makefile           |    1 +
 drivers/uio/Kconfig        |   16 +
 drivers/uio/Makefile       |    1 +
 drivers/uio/uio.c          |  701 ++++++++++++++++++++++++++++++++++++++++++++
 include/linux/uio_driver.h |   91 ++++++
 6 files changed, 811 insertions(+), 0 deletions(-)
 create mode 100644 drivers/uio/Kconfig
 create mode 100644 drivers/uio/Makefile
 create mode 100644 drivers/uio/uio.c
 create mode 100644 include/linux/uio_driver.h

index 7916f4b..ae01d86 100644
@@ -84,4 +84,5 @@ source "drivers/auxdisplay/Kconfig"
 
 source "drivers/kvm/Kconfig"
 
+source "drivers/uio/Kconfig"
 endmenu

index 6d9d7fa..c34c8ef 100644
@@ -40,6 +40,7 @@ obj-$(CONFIG_ATA)		+= ata/
 obj-$(CONFIG_FUSION)		+= message/
 obj-$(CONFIG_FIREWIRE)		+= firewire/
 obj-$(CONFIG_IEEE1394)		+= ieee1394/
+obj-$(CONFIG_UIO)		+= uio/
 obj-y				+= cdrom/
 obj-y				+= auxdisplay/
 obj-$(CONFIG_MTD)		+= mtd/

new file mode 100644
index 0000000..6b1a62d
@@ -0,0 +1,16 @@
+menu "Userspace I/O"
+	depends on !S390
+
+config UIO
+	tristate "Userspace I/O drivers"
+	default n
+	help
+	  Enable this to allow the userspace driver core code to be
+	  built.  This code allows userspace programs easy access to
+	  kernel interrupts and memory locations, allowing some drivers
+	  to be written in userspace.  Note that a small kernel driver
+	  is also required for interrupt handling to work properly.
+
+	  If you don't know what to do here, say N.
+
+endmenu

new file mode 100644
index 0000000..9b7c830
@@ -0,0 +1 @@
+obj-$(CONFIG_UIO) += uio.o

1.5.2.2

From: Hans J. Koch <[email protected]>

Documentation for the UIO interface

From: Hans J. Koch <[email protected]>

---
 Documentation/DocBook/kernel-api.tmpl |    4 +
 Documentation/DocBook/uio-howto.tmpl  |  611 +++++++++++++++++++++++++++++++++
 2 files changed, 615 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/DocBook/uio-howto.tmpl

index fd2ef4d..a0af560 100644
@@ -408,6 +408,10 @@ X!Edrivers/pnp/system.c
 !Edrivers/pnp/manager.c
 !Edrivers/pnp/support.c
      </sect1>
+     <sect1><title>Userspace IO devices</title>
+!Edrivers/uio/uio.c
+!Iinclude/linux/uio_driver.h
+     </sect1>
   </chapter>
 
   <chapter id="blkdev">

1.5.2.2

From: Hans-Jürgen Koch <[email protected]>

this is a patch that adds support for Hilscher CIF DeviceNet and Profibus cards. I tested it on a Kontron CPX board, and Thomas reviewed it.

You can find the user space part here:

http://www.osadl.org/projects/downloads/UIO/user/cif-0.1.0.tar.gz

Notes: cif_api.c is the main file you want to look at. It contains the functions to open, close, mmap and so on. cif_dps.c adds functions specific to Profibus cards, and cif_dn.c contains functions for DeviceNet cards. cif.c is a universal playground, it's just a small test program. The user space part of this UIO driver is still work in progress, and not everything is tested yet. At the moment, the thread in cif_api.c contains some code that artificially makes the card generate interrupts, this was added for testing and will be removed later. But the driver already contains all the functions needed for useful operation, so it gives a good idea of how such a thing looks like.

For comparison, here's what you get from the manufacturer (www.hilscher.com) when you ask for a Linux 2.6 driver:

http://www.tglx.de/private/hjk/cif-orig-2.6.tar.bz2

WARNING: Don't look at the code for too long, you might become sick :-)

---
 drivers/uio/Kconfig   |   13 ++++
 drivers/uio/Makefile  |    3 +-
 drivers/uio/uio_cif.c |  156 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 171 insertions(+), 1 deletions(-)
 create mode 100644 drivers/uio/uio_cif.c

index 6b1a62d..b778ed7 100644
@@ -13,4 +13,17 @@ config UIO
 
 	  If you don't know what to do here, say N.
 
+config UIO_CIF
+	tristate "generic Hilscher CIF Card driver"
+	depends on UIO && PCI
+	default n
+	help
+	  Driver for Hilscher CIF DeviceNet and Profibus cards.  This
+	  driver requires a userspace component that handles all of the
+	  heavy lifting and can be found at:
+	  	http://www.osadl.org/projects/downloads/UIO/user/cif-*
+
+	  To compile this driver as a module, choose M here: the module
+	  will be called uio_cif.
+
 endmenu

index 9b7c830..7fecfb4 100644
@@ -1 +1,2 @@
-obj-$(CONFIG_UIO) += uio.o
+obj-$(CONFIG_UIO)	+= uio.o
+obj-$(CONFIG_UIO_CIF)	+= uio_cif.o

1.5.2.2

Taking precautions for people? I get a 404...

Jan

Am Donnerstag 19 Juli 2007 18:33 schrieb Jan Engelhardt:

Now it's there.

Thanks,
Hans

aaaa, my eyes... ("Microsoft" is a good summary of the codingstyle...) :)

Jan

Am Donnerstag 19 Juli 2007 22:02 schrieb Jan Engelhardt:

It's not just coding style, it's also concept. This was written with the only goal to get a card working at one particular time. What happens in future is not important. Would you like to port this driver to 2.6.22? Would you like to post it on lkml, signed-off by you?

The concept is bad because the authors of that driver never tried to find out how a driver should look like and what has to be done to get it into mainline. Allright, with such a big driver for a relatively unknown card(?) it's not easy to include that in mainline. That's why we now have UIO... It greatly simplifies tasks like that.

I really hope that UIO will soon be used for industrial cards like this one, and that we can fill drivers/uio/ with lots of small kernel modules. And yes, these programmers in industry who wrote drivers like the above, they will still be doing what they want and what they're able to. But, hopefully, they'll now do it in userspace.

Thanks,
Hans

...

...

Jesper Juhl <[email protected]>
Don't top-post  http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please      http://www.expita.com/nomime.html

On the other hand, given that we've always said that closed-source stuff in userspace is OK, the only way to not let *that* horse out of the barn is to not merge UIO at all.

If you have UIO in the kernel talking to stuff in userspace, you're going to have to deal with closed-source stuff at the userspace end of the pipe.

Unless somebody can come up with some great feat of sophistry to avoid that?

Exactely.

Naturally.
I just wanted to get people to think about whether or not this is something that we are willing to accept for device drivers - I guess it is since UIO is already merged - I just think it's a potential step back in terms of encouraging open source drivers for Linux, that's all.

I think the only way to avoid it is to not provide something like UIO.

Jesper Juhl <[email protected]>
Don't top-post  http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please      http://www.expita.com/nomime.html

Problem is, things like UIO provide a real solution for a wide range of different types of devices. Like the one provided in the kernel right now, and a bunch of others that I am currently discussing with different manufacturers (think high-speed DSPs that just want to give userspace direct access to the card and have the kernel get the hell out of the way so data can be read and processed as fast as possible.)

And also realize that some types of systems have been doing this very same kind of kernel/userspace interface for many years, namely X :)

As for the legalities of using closed source userspace code with the UIO interface, consult a lawyer if you have questions, and be sure to bring up Alan's comments about derivative works :)

thanks,

greg k-h

Please understand that I'm not saying UIO isn't potentially useful, nor am I saying that it won't potentially give us support for a bunch of new hardware. All I'm trying to say is that, to me at least, it is trying to buy us those new drivers in a way that encourages creating those drivers as closed source software- *that* is all I'm having issues with - that is what I think is a step backwards - something that may give us a short-term gain but will make us lose out long-term.

That something has been going on for years doesn't in itself make it a good argument for that model. ;-)

I'm not arguing against closed source applications in userspace. That is of course OK. What I'm arguing about is a kernel interface that encourages closed source (userspace) *drivers*.

Jesper Juhl <[email protected]>
Don't top-post  http://www.catb.org/~esr/jargon/html/T/top-post.html
Plain text mails only, please      http://www.expita.com/nomime.html

It really makes no difference whether it is merged or not. The test is "derivative work" and not 'linking'.

A user space driver that is unusuable without a specific GPL kernel chunk is quite likely to be a derived work of the GPL kernel module so the documentation is giving poor advice however

Alan

Am Donnerstag 09 August 2007 01:40 schrieb Alan Cox:

I disagree. UIO is a documented kernel<->userspace interface, like sysfs or proc. Using your argument, we would also have to say that a userspace software that is unusable without sysfs is a derived work of the kernel. But IANAL, tell me if I missed an important point.

I guess you mean this sentence:

"if you need to keep some parts of your driver closed source, you can do so without violating the GPL license on the kernel."

What would you write instead?

Thanks,
Hans

O> I disagree. UIO is a documented kernel<->userspace interface, like sysfs

It depends how closely the bits are tied. As far as I can ascertain there is no simple yes/no answer and whether you can do so depends a great deal upon how tightly bound the two are (consider the difference between the intel ipw daemon which is integrated very tightly into the old ipw3945 driver and a script monitoring CPU temperature via a sysfs file)

I would simply remove the statement. Leave it to the lawyers.

Alan

Am Donnerstag 09 August 2007 00:12 schrieb [email protected]:

That's no UIO invention. Userspace software that uses kernel interfaces like syscall, device files, sysfs, and so on, is by definition _not_ a derived work of the kernel and can be distributed under any license.

If you ask a manufacturer of an industrial IO card for a Linux driver today, you either get nothing at all, or you get an unmaintainable and buggy piece of crap for an ancient kernel. The alternative is a binary kernel module that really violates the GPL.

With UIO, you have a kernel module that is so small, that even somebody who hasn't got the hardware can easily review it and tell if the code is OK or not. It is easy to maintain and doesn't reveal any secrets about the hardware. The kernel remains clean, which further improves maintenance and debugging. People frequently use /dev/mem to access hardware from userspace, that's nothing new. UIO really improves this, making it safer and more user friendly. And it prevents people from inventing dirty tricks to do some sort of interrupt handling in user space (which is simply not possible).

Furthermore, drivers for this kind of hardware are written by programmers in industry, who often don't have kernel experience, reviews, time for tests, and so on. I really prefer it if they do their stuff in userspace. And they prefer it, too, because they can use all the nice tools and libraries they're used to.

There might be a small possibility that a manufacturer now writes a closed source UIO driver, and would have written an open source kernel driver if UIO didn't exist. But, honestly, I doubt that we'll find many such cases.

Thanks,
Hans

This I believe incorrect. Please cite caselaw if you know better.

False

Because you have no idea if the interface is correct or the userspace is doing stuff like triggering DMA to arbitary addresses via the interface or mmap functions. If it does so then even if its root only you've blown your security model.

Am Donnerstag 09 August 2007 16:12 schrieb Alan Cox:

What about the statement at the top of COPYING in the top level kernel source directory?

I know, you've got examples in mind where a kernel module and a userspace program are dependent on each other and none of them can be used without the other. Of course, we've got such a case for a UIO kernel module and userspace driver. But if the degree of dependency between kernel and userspace can constitute a different legal situation, then we have a _very_ large legal grayzone.

OK, I agree. But in comparison to using /dev/mem for these tasks, I still consider UIO an improvement.

Thanks,
Hans

Am Mittwoch 08 August 2007 23:36 schrieb Jesper Juhl:

Yes. Please remember that UIO is for industrial I/O cards, not mainstream PC hardware. You'll never see an UIO driver for an USB Scanner or a TV card. Just try to write one. You will see that an UIO kernel driver for a device that has to interact with lots of kernel subsystems will become almost as big as a normal kernel driver. Not much left for user space.

Typical industrial IO cards are simple PCI cards with loads of functions that don't fit in any kernel subsystem. A pure kernel driver is usually _big_ and ugly and introduces 50 new ioctls and will never make it into mainline.

If a company wants to do that, they'll do it, with or without UIO.

No. Please note that there _are_ reasons to keep code closed. I agree with you when it comes to mass market hardware like graphics cards. But in embedded systems with custom hardware for military or other critical applications, you can't force a manufacturer to show you his concepts. Usually, he's not allowed to.

UIO offers a legal way for these people to implement their driver. Without it, they'll violate the GPL or don't use Linux at all.

No. UIO doesn't change anything. You were always free to choose your license for userspace stuff.

What we want to achieve is that IO cards, for which you get a driver with 5000 lines of unreadable code for 2.6.12 from the manufacturer at the moment, can get a sensible driver with mainline support. That's all. We will see if that encourages manufacturers to make drivers closed source.

Thanks,
Hans