26 ways to set a device driver variable from userland

26 ways to set a device driver variable from userland

[Rick Niles]

There are so many ways to set a configuration value in a device driver. I'm wondering
which are "recommended" methods. I'm looking for some sort of guidance when writing a
new driver.  I kinda assume this is a FAQ, but I didn't see it anyway, maybe it should
be added to the FAQ.

OK there might not be 26 ways, but there's a few major ones. I'm thinking in term of
char devices so some of these might not apply to block and network drivers.

(1) ioctl, probably the oldest.
(2) use read/write to a special configuration-only /dev file (e.g. /dev/dvb)
(3) /proc filesystem
(4) sysfs
(5) module load-time command line options.

I understand that flexibility is a good thing, but some guidance would be helpful.

I sorta got the idea that /proc is "out" this year and sysfs is the "in" thing, but
what about the others?  Would you say that (2) should be be discouraged?  Did anyone
tell the DVB people that? Or maybe more is better, that is, a good driver should
allow for ALL of the above! (OK, yeah that was flame bait.)  Should EVERY variable
that can be modified by say sysfs also be settable by insmod command line?

Any guidance would be greatly appreciated,
Rick Niles.

Re: 26 ways to set a device driver variable from userland

[Kyle Moffett]

On Oct 19, 2005, at 13:00:45, Rick Niles wrote:
> There are so many ways to set a configuration value in a device  
> driver. I'm wondering which are "recommended" methods. I'm looking  
> for some sort of guidance when writing a new driver.  I kinda  
> assume this is a FAQ, but I didn't see it anyway, maybe it should  
> be added to the FAQ.
>
> OK there might not be 26 ways, but there's a few major ones. I'm  
> thinking in term of char devices so some of these might not apply  
> to block and network drivers.

I'm going to kind of try to summarize a lot of the comments I see on  
this list in general here; I may get some of the fine points wrong,  
but you should be able to get the gist of things.

> (1) ioctl, probably the oldest.

New ioctls are frowed upon, mainly because they tend to involve  
fragile binary structures that aren't very 64-bit compatible.  It's  
possible to avoid those issues, but sufficiently difficult that I  
would recommend against ioctls.

> (2) use read/write to a special configuration-only /dev file (e.g. / 
> dev/dvb)

This is similar to the above with ioctls, except using read() and  
write() instead of ioctl() on the device.  I don't recommend it for  
similar reasons.

> (3) /proc filesystem

/proc is for processes, not hardware.  There is some stuff in there  
that shouldn't be (/proc/bus/usb), but it's slowly being moved out,  
so don't introduce new stuff.

> (4) sysfs

This is ideal for almost all device driver purposes.  It's really  
easy, integrates well into the device model, trivial to configure  
from hotplug scripts which already have sysfs path info associated  
with them, etc.  The idea behind sysfs is to have small single values  
broken up into human-readable and human-useable pseudo-files.  Some  
random PCI device would have various little configuration values and  
strings, dma mode configuration, useful human-readable numbers and  
text pulled from the PCI ROM, a binary dump of PCI config space and/ 
or firmware for debugging, etc.

> (5) module load-time command line options.

These are nice and relatively easy to use, but cannot be changed at  
runtime on their own (If they have a corresponding sysfs file, then  
they can, however).  Sometimes that's appropriate, but usually you  
want a more flexible solution.

> Should EVERY variable that can be modified by say sysfs also be  
> settable by insmod command line?

I wouldn't recommend it.  Frequently such sysfs files are device- 
specific.

Cheers,
Kyle Moffett

--
Simple things should be simple and complex things should be possible
   -- Alan Kay

Re: 26 ways to set a device driver variable from userland

[Christopher Friesen]

Kyle Moffett wrote:

>> (4) sysfs

> This is ideal for almost all device driver purposes.

The one thing that I have yet to see a good solution for is 
transaction-based operations, where userspace passes in something (could 
be a command, a new value, a query, etc.) and expects some data in return.

The ioctl() method is ideal for this, passing down a binary struct with 
a command/query member, and the driver fills in the rest of the struct 
based on the commnd.

How do you do this cleanly via sysfs?  It seems like you either double 
the number of syscalls (write to one file, read from another) or else 
you need to have sysfs files for every possible query/command, so that 
the input becomes implicitly encoded in the file that you are reading. 
This could end up creating a large number of files depending on the 
range of inputs.

Are there any other standard ways to do this?

Chris

Re: 26 ways to set a device driver variable from userland

[Matt Helsley]

On Wed, 2005-10-19 at 12:35 -0600, Christopher Friesen wrote:
> Kyle Moffett wrote:
> 
> >> (4) sysfs
> 
> > This is ideal for almost all device driver purposes.
> 
> The one thing that I have yet to see a good solution for is 
> transaction-based operations, where userspace passes in something (could 
> be a command, a new value, a query, etc.) and expects some data in return.
> 
> The ioctl() method is ideal for this, passing down a binary struct with 
> a command/query member, and the driver fills in the rest of the struct 
> based on the commnd.
> 
> How do you do this cleanly via sysfs?  It seems like you either double 
> the number of syscalls (write to one file, read from another) or else 
> you need to have sysfs files for every possible query/command, so that 
> the input becomes implicitly encoded in the file that you are reading. 
> This could end up creating a large number of files depending on the 
> range of inputs.
> 
> Are there any other standard ways to do this?
> 
> Chris

	Perhaps a connector would be appropriate here. Userspace could send a
netlink message to the connector with the query/command and the
connector could respond by sending appropriate results back to
userspace.

Cheers,
	-Matt Helsley

Re: 26 ways to set a device driver variable from userland

[Neil Brown]

On Wednesday October 19, cfriesen@nortel.com wrote:
> Kyle Moffett wrote:
> 
> >> (4) sysfs
> 
> > This is ideal for almost all device driver purposes.
> 
> The one thing that I have yet to see a good solution for is 
> transaction-based operations, where userspace passes in something (could 
> be a command, a new value, a query, etc.) and expects some data in return.
> 

knfsd does this sort of stuff with it's own tiny filesystem.

If you look in fs/libfs.c you will see a section headed
  Transaction based IO
which is exactly for this sort of thing.

Currently I think you need to create your own tiny filesystem (which
isn't much effort if you use the stuff in libfs).

I think I'd like this sort of file to be a standard option for sysfs
attributes, but I haven't looked seriously into the possibility yet.

NeilBrown

Re: 26 ways to set a device driver variable from userland

[Greg KH]

On Wed, Oct 19, 2005 at 12:35:27PM -0600, Christopher Friesen wrote:
> Kyle Moffett wrote:
> 
> >>(4) sysfs
> 
> >This is ideal for almost all device driver purposes.
> 
> The one thing that I have yet to see a good solution for is 
> transaction-based operations, where userspace passes in something (could 
> be a command, a new value, a query, etc.) and expects some data in return.
> 
> The ioctl() method is ideal for this, passing down a binary struct with 
> a command/query member, and the driver fills in the rest of the struct 
> based on the commnd.
> 
> How do you do this cleanly via sysfs?  It seems like you either double 
> the number of syscalls (write to one file, read from another) or else 
> you need to have sysfs files for every possible query/command, so that 
> the input becomes implicitly encoded in the file that you are reading. 
> This could end up creating a large number of files depending on the 
> range of inputs.
> 
> Are there any other standard ways to do this?

Take a look at configfs, as part of the ocfs2 patches in the -mm tree.
It is set up to help solve this using a filesystem much like sysfs.

thanks,

greg k-h

Re: 26 ways to set a device driver variable from userland

[Kyle Moffett]

I'm CCing this to the LKML, because it's useful to the list in  
general and you're much more likely to get useful replies as well.

On Oct 19, 2005, at 14:07:44, Rick Niles wrote:
> I really appreciate the prompt and complete feedback.  While you're  
> at it perhaps you can answer another one for me.

Please don't top-post :-D.  Thanks!
http://www.zipworld.com.au/~akpm/linux/patches/stuff/top-posting.txt
http://catb.org/~esr/jargon/html/T/top-post.html

> I'm doing a low-level GPS receiver driver. This is NOT a serial  
> port kinda thing.  I have to close tracking loops and that sort of  
> thing at faster that 1ms.  I was planning on outputing the actual  
> tracking data (not the parameters I asked about earlier) through a  
> read of a device file.   However, your point about binary  
> structures applied to this as well.  Would you say I should not use  
> a device file at all?  Should the device file output ASCII instead  
> of binary (this brings up an eff. argument)
>
> Also, each GPS satellite transmits a standard binary data message  
> that I definitely should not mess with in the kernel (IMHO).   
> However, the GPS range is computed using the settings of the  
> oscillator and some counters off the correlator chip.  I planned on  
> making each channel a separate
> device file. Would it be OK to mix this GPS data message with the  
> corellator tracking information, or should I make two files?  Or  
> perhaps, depending on your answer to above you might say the  
> tracking info should be in sysfs.

Umm, hmm.  This really depends on a bunch of stuff I don't really  
understand all that well, but I'll try :-D.  The simplest way to do  
it would be to just stick each distinct value in a sysfs file and let  
your GPS software read each one and do what it wants from them.  That  
would make it really easy to shell-script with GPS coordinates too :- 
D.  Others on the list may have more informative/useful responses  
here, sorry!

Cheers,
Kyle Moffett

--
There are two ways of constructing a software design. One way is to  
make it so simple that there are obviously no deficiencies. And the  
other way is to make it so complicated that there are no obvious  
deficiencies.  The first method is far more difficult.
   -- C.A.R. Hoare

Re: 26 ways to set a device driver variable from userland

[linux-os (Dick Johnson)]

On Wed, 19 Oct 2005, Rick Niles wrote:

> There are so many ways to set a configuration value in a device driver. I'm wondering
> which are "recommended" methods. I'm looking for some sort of guidance when writing a
> new driver.  I kinda assume this is a FAQ, but I didn't see it anyway, maybe it should
> be added to the FAQ.
>
> OK there might not be 26 ways, but there's a few major ones. I'm thinking in term of
> char devices so some of these might not apply to block and network drivers.
>
> (1) ioctl, probably the oldest.
> (2) use read/write to a special configuration-only /dev file (e.g. /dev/dvb)
> (3) /proc filesystem
> (4) sysfs
> (5) module load-time command line options.
>
> I understand that flexibility is a good thing, but some guidance would be helpful.
>
> I sorta got the idea that /proc is "out" this year and sysfs is the "in" thing, but
> what about the others?  Would you say that (2) should be be discouraged?  Did anyone
> tell the DVB people that? Or maybe more is better, that is, a good driver should
> allow for ALL of the above! (OK, yeah that was flame bait.)  Should EVERY variable
> that can be modified by say sysfs also be settable by insmod command line?
>
> Any guidance would be greatly appreciated,
> Rick Niles.
>

There is no question that ioctl() will always exist. You will never
have a problem compiling your module when Linux-99.99 rolls out
in the year 2054. That said, you want to start your ioctl control
values above anything the kernel uses and return -ENOTTY for anything
out of range. This will allow somebody to do `od /dev/YourDevice` without
breaking your device!


Cheers,
Dick Johnson
Penguin : Linux version 2.6.13.4 on an i686 machine (5589.55 BogoMips).
Warning : 98.36% of all statistics are fiction.
.

****************************************************************
The information transmitted in this message is confidential and may be privileged.  Any review, retransmission, dissemination, or other use of this information by persons or entities other than the intended recipient is prohibited.  If you are not the intended recipient, please notify Analogic Corporation immediately - by replying to this message or by sending an email to DeliveryErrors@analogic.com - and destroy all copies of this information, including any attachments, without reading or disclosing them.

Thank you.