new sysfs layout and ethernet device names

new sysfs layout and ethernet device names

[Bill Nottingham]

I was fiddling with the 'new' (no CONFIG_SYSFS_DEPRECATED) layout
and ethernet device names, and noticed that the new layout effectively
restricts the availability of certain device names.

By making a directory for the ethernet device name in the parent
device, you no longer can use any name that is used in sysfs for
the parent device type - for PCI devices this would be 'resource0',
'power', 'enable', etc. For USB, it would be a different set
of names that are no longer available.

If you *do* try to use one of these names, the rename will succeed...
partway. The link in /sys/class/net is renamed, the directory is
not (as it obviously can't rename on top of whatever is already there.)
Various networking tools then break in assorted ways due to the
naming disconnect.

Going back to the deprecated layout makes these names available again -
it's possible (although not necessarily likely) that the new layout
will break someone's device configuration if they upgrade kernels,
even if the rest of their tools are updated for the new layout.

Bill

Re: new sysfs layout and ethernet device names

[Kay Sievers]

On 3/20/07, Bill Nottingham <notting@redhat.com> wrote:
> I was fiddling with the 'new' (no CONFIG_SYSFS_DEPRECATED) layout
> and ethernet device names, and noticed that the new layout effectively
> restricts the availability of certain device names.
>
> By making a directory for the ethernet device name in the parent
> device, you no longer can use any name that is used in sysfs for
> the parent device type - for PCI devices this would be 'resource0',
> 'power', 'enable', etc. For USB, it would be a different set
> of names that are no longer available.

Yeah, we heard, people want to name their network interfaces "irq". :)

> If you *do* try to use one of these names, the rename will succeed...
> partway. The link in /sys/class/net is renamed, the directory is
> not (as it obviously can't rename on top of whatever is already there.)
> Various networking tools then break in assorted ways due to the
> naming disconnect.
>
> Going back to the deprecated layout makes these names available again -
> it's possible (although not necessarily likely) that the new layout
> will break someone's device configuration if they upgrade kernels,
> even if the rest of their tools are updated for the new layout.

There will be a directory at the bus-device with the name of the
class, that glues together the bus-devices and the class-devices in
the unified tree:
  http://git.kernel.org/?p=linux/kernel/git/gregkh/patches.git;a=blob;f=driver/driver-core-fix-namespace-issue-with-devices-assigned-to-classes.patch;hb=HEAD

So the network-interface(s) will be in their own directory "net",
below the bus-device, and don't conflict with the existing attributes.

Thanks,
Kay

Re: new sysfs layout and ethernet device names

[Bill Nottingham]

Kay Sievers (kay.sievers@vrfy.org) said: 
> >If you *do* try to use one of these names, the rename will succeed...
> >partway. The link in /sys/class/net is renamed, the directory is
> >not (as it obviously can't rename on top of whatever is already there.)
> >Various networking tools then break in assorted ways due to the
> >naming disconnect.
> >
> >Going back to the deprecated layout makes these names available again -
> >it's possible (although not necessarily likely) that the new layout
> >will break someone's device configuration if they upgrade kernels,
> >even if the rest of their tools are updated for the new layout.
> 
> There will be a directory at the bus-device with the name of the
> class, that glues together the bus-devices and the class-devices in
> the unified tree:
>  http://git.kernel.org/?p=linux/kernel/git/gregkh/patches.git;a=blob;f=driver/driver-core-fix-namespace-issue-with-devices-assigned-to-classes.patch;hb=HEAD
> 
> So the network-interface(s) will be in their own directory "net",
> below the bus-device, and don't conflict with the existing attributes.

So, the layout will change again?

Bill

Re: new sysfs layout and ethernet device names

[Greg KH]

On Tue, Mar 27, 2007 at 11:17:43PM -0400, Bill Nottingham wrote:
> Kay Sievers (kay.sievers@vrfy.org) said: 
> > >If you *do* try to use one of these names, the rename will succeed...
> > >partway. The link in /sys/class/net is renamed, the directory is
> > >not (as it obviously can't rename on top of whatever is already there.)
> > >Various networking tools then break in assorted ways due to the
> > >naming disconnect.
> > >
> > >Going back to the deprecated layout makes these names available again -
> > >it's possible (although not necessarily likely) that the new layout
> > >will break someone's device configuration if they upgrade kernels,
> > >even if the rest of their tools are updated for the new layout.
> > 
> > There will be a directory at the bus-device with the name of the
> > class, that glues together the bus-devices and the class-devices in
> > the unified tree:
> >  http://git.kernel.org/?p=linux/kernel/git/gregkh/patches.git;a=blob;f=driver/driver-core-fix-namespace-issue-with-devices-assigned-to-classes.patch;hb=HEAD
> > 
> > So the network-interface(s) will be in their own directory "net",
> > below the bus-device, and don't conflict with the existing attributes.
> 
> So, the layout will change again?

If you follow the rules in Documentation/ABI/testing/sysfs-class your
program will not have any problems.

And yes, it will change by adding another subdirectory in the device
tree, but just follow the link from the /sys/class/ directorys and you
will be fine.

thanks,

greg k-h

Re: new sysfs layout and ethernet device names

[Bill Nottingham]

Greg KH (greg@kroah.com) said: 
> If you follow the rules in Documentation/ABI/testing/sysfs-class your
> program will not have any problems.

Oh, of *course*. We add interfaces and then claim years later,
after code has been written, "Oh, you shouldn't be using that!" in
documentation. Meanwhile, such code using the old interface will still
a) continue to compile b) continue to run without any sort of warnings.

If interfaces have to change, so be it. But changing the rules for
using them years after it's implemented and then claiming "you didn't
read the instructions" is pretty lame.

Bill

Re: new sysfs layout and ethernet device names

[Greg KH]

On Wed, Mar 28, 2007 at 08:41:38PM -0400, Bill Nottingham wrote:
> Greg KH (greg@kroah.com) said: 
> > If you follow the rules in Documentation/ABI/testing/sysfs-class your
> > program will not have any problems.
> 
> Oh, of *course*. We add interfaces and then claim years later,
> after code has been written, "Oh, you shouldn't be using that!" in
> documentation. Meanwhile, such code using the old interface will still
> a) continue to compile b) continue to run without any sort of warnings.
> 
> If interfaces have to change, so be it. But changing the rules for
> using them years after it's implemented and then claiming "you didn't
> read the instructions" is pretty lame.

That documentation has been in the kernel tree for almost a full year:
	commit c18f6365fdbaf30611a8822afcd7097865dcaa32
	Author: Greg Kroah-Hartman <gregkh@suse.de>
	Date:   Thu Apr 27 14:10:12 2006 -0700

	    [PATCH] Add kernel<->userspace ABI stability documentation

And Kay and I have been saying to not to rely on directories for over
two years now...

Anyway, yes, older code should still "just work" if you enable the
CONFIG_SYSFS_DEPRECATED config option in the kernel, that is what it is
there for.

If you have any problems with that option enabled, please let me know
and I will be glad to fix it up.

thanks,

greg k-h

Re: new sysfs layout and ethernet device names

[Bill Nottingham]

Greg KH (greg@kroah.com) said: 
> > If interfaces have to change, so be it. But changing the rules for
> > using them years after it's implemented and then claiming "you didn't
> > read the instructions" is pretty lame.
> 
> That documentation has been in the kernel tree for almost a full year:

It has a date on it. I'm not blind. That doesn't change the fact that
that documentation:

> 	Date:   Thu Apr 27 14:10:12 2006 -0700

postdates the interface it's describing by at *least* two years. Which
was the point of my mail that you conveniently ignored - retroactively
deciding which parts of the interface you export to userspace shouldn't be
used falls way short of best practices.

> Anyway, yes, older code should still "just work" if you enable the
> CONFIG_SYSFS_DEPRECATED config option in the kernel, that is what it is
> there for.

It appears to... the point was that (as far as the code is concerned)
it's a silent break. Of course, code that expects the 'current' layout
will then break when this new change is made, unless you add
CONFIG_SYSFS_SLIGHTLY_LESS_DEPRECATED?

Bill

Re: new sysfs layout and ethernet device names

[Greg KH]

On Thu, Mar 29, 2007 at 11:29:05PM -0400, Bill Nottingham wrote:
> Greg KH (greg@kroah.com) said: 
> > > If interfaces have to change, so be it. But changing the rules for
> > > using them years after it's implemented and then claiming "you didn't
> > > read the instructions" is pretty lame.
> > 
> > That documentation has been in the kernel tree for almost a full year:
> 
> It has a date on it. I'm not blind. That doesn't change the fact that
> that documentation:
> 
> > 	Date:   Thu Apr 27 14:10:12 2006 -0700
> 
> postdates the interface it's describing by at *least* two years. Which
> was the point of my mail that you conveniently ignored - retroactively
> deciding which parts of the interface you export to userspace shouldn't be
> used falls way short of best practices.

I am not disagreeing with that, that is why the config option is
present.

> > Anyway, yes, older code should still "just work" if you enable the
> > CONFIG_SYSFS_DEPRECATED config option in the kernel, that is what it is
> > there for.
> 
> It appears to... the point was that (as far as the code is concerned)
> it's a silent break. Of course, code that expects the 'current' layout
> will then break when this new change is made, unless you add
> CONFIG_SYSFS_SLIGHTLY_LESS_DEPRECATED?

Well, the idea is that over time, older things will move under this
config option.  If you disable it, you will have a "cleaner" sysfs tree,
but if you enable it, it should all just look the same.

Now some people have proposed versioning the sysfs interface (1, 2, 3,
etc.) and have a config option for that.  I don't know if that's really
necessary just yet, but am considering it for future changes.

thanks,

greg k-h