[RFC] New driver information

[RFC] New driver information

[Heikki Orsila]

I just read

	http://kerneltrap.org/node/7729

and it occured to me that it would be informative to have a new device 
driver macro. The motivation for the new macro would be 4 issues:

	* Is it possible to get specifications for the device?
	* If yes, under what terms? (nda, public)
	* Where to get public specs?
	* How many closed and open drivers in the Linux source tree?

I suggest to add following macro:

MODULE_SPECIFICATION(terms, source);

where "terms" is one of

 * MODULE_SPEC_ANY_PARTY_NDA
	- specification available to any party for an NDA
 * MODULE_SPEC_ANY_PARTY
	- specification available in public, or at least available 
	  without NDA to any party
 * MODULE_SPEC_RESTRICTED
	- none of the above

and "source":

 * contact address for nda specs
 * any public source for a public specification (http://, email address, 
   ...)
 * empty string otherwise

I realise this macro somewhat circumvents the purpose of Documentation/ 
directory but the idea is to have a direct 1:1 mapping between drivers 
and specification sources so that it would be easy to collect statistics 
of "open" hardware by using grep et al.

What do you think? Useless annotations or useful information?

-- 
Heikki Orsila			Barbie's law:
heikki.orsila@iki.fi		"Math is hard, let's go shopping!"
http://www.iki.fi/shd

Re: [RFC] New driver information

[Thiago Galesi]

SInce this information does not, in any way, affect the functioning of
the driver... It is not "executable code", I don't see the point of
it.

For "module_licence" we have the restriction of some functions being
used only for GPL code, but for this?!? I really don't see it...

Just think: what would this macro do, "executable-code wise"?


On 2/16/07, Heikki Orsila <shdl@zakalwe.fi> wrote:
> I just read
>
>         http://kerneltrap.org/node/7729
>
> and it occured to me that it would be informative to have a new device
> driver macro. The motivation for the new macro would be 4 issues:
>
>         * Is it possible to get specifications for the device?
>         * If yes, under what terms? (nda, public)
>         * Where to get public specs?
>         * How many closed and open drivers in the Linux source tree?
>
> I suggest to add following macro:
>
> MODULE_SPECIFICATION(terms, source);
>
> where "terms" is one of
>
>  * MODULE_SPEC_ANY_PARTY_NDA
>         - specification available to any party for an NDA
>  * MODULE_SPEC_ANY_PARTY
>         - specification available in public, or at least available
>           without NDA to any party
>  * MODULE_SPEC_RESTRICTED
>         - none of the above
>
> and "source":
>
>  * contact address for nda specs
>  * any public source for a public specification (http://, email address,
>    ...)
>  * empty string otherwise
>
> I realise this macro somewhat circumvents the purpose of Documentation/
> directory but the idea is to have a direct 1:1 mapping between drivers
> and specification sources so that it would be easy to collect statistics
> of "open" hardware by using grep et al.
>
> What do you think? Useless annotations or useful information?
>
> --
> Heikki Orsila                   Barbie's law:
> heikki.orsila@iki.fi            "Math is hard, let's go shopping!"
> http://www.iki.fi/shd
> -
> To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
> Please read the FAQ at  http://www.tux.org/lkml/
>


-- 
-
Thiago Galesi

Re: [RFC] New driver information

[Maxim]

On Friday 16 February 2007 16:08:53 Thiago Galesi wrote:
> SInce this information does not, in any way, affect the functioning of
> the driver... It is not "executable code", I don't see the point of
> it.
> 
> For "module_licence" we have the restriction of some functions being
> used only for GPL code, but for this?!? I really don't see it...
> 
> Just think: what would this macro do, "executable-code wise"?
> 
> 
> On 2/16/07, Heikki Orsila <shdl@zakalwe.fi> wrote:
> > I just read
> >
> >         http://kerneltrap.org/node/7729
> >
> > and it occured to me that it would be informative to have a new device
> > driver macro. The motivation for the new macro would be 4 issues:
> >
> >         * Is it possible to get specifications for the device?
> >         * If yes, under what terms? (nda, public)
> >         * Where to get public specs?
> >         * How many closed and open drivers in the Linux source tree?
> >
> > I suggest to add following macro:
> >
> > MODULE_SPECIFICATION(terms, source);
> >
> > where "terms" is one of
> >
> >  * MODULE_SPEC_ANY_PARTY_NDA
> >         - specification available to any party for an NDA
> >  * MODULE_SPEC_ANY_PARTY
> >         - specification available in public, or at least available
> >           without NDA to any party
> >  * MODULE_SPEC_RESTRICTED
> >         - none of the above
> >
> > and "source":
> >
> >  * contact address for nda specs
> >  * any public source for a public specification (http://, email address,
> >    ...)
> >  * empty string otherwise
> >
> > I realise this macro somewhat circumvents the purpose of Documentation/
> > directory but the idea is to have a direct 1:1 mapping between drivers
> > and specification sources so that it would be easy to collect statistics
> > of "open" hardware by using grep et al.
> >
> > What do you think? Useless annotations or useful information?
> >
> > --
> > Heikki Orsila                   Barbie's law:
> > heikki.orsila@iki.fi            "Math is hard, let's go shopping!"
> > http://www.iki.fi/shd
> > -
> > To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
> > the body of a message to majordomo@vger.kernel.org
> > More majordomo info at  http://vger.kernel.org/majordomo-info.html
> > Please read the FAQ at  http://www.tux.org/lkml/
> >
> 
> 

I think both sides are right.

I think that documentation about drivers and their specs is a good thing ( i personally spent lot if time to locate it and find that it is unavailable in some cases)
But I agree that it has no place in executable code , instead I think such list can be in /Documentation or even in MAINTAINERS

	Regards, 
		Maxim Levitsky 

Re: [RFC] New driver information

[Adrian Bunk]

On Fri, Feb 16, 2007 at 03:58:51PM +0200, Heikki Orsila wrote:
> I just read
> 
> 	http://kerneltrap.org/node/7729
> 
> and it occured to me that it would be informative to have a new device 
> driver macro. The motivation for the new macro would be 4 issues:
> 
> 	* Is it possible to get specifications for the device?
> 	* If yes, under what terms? (nda, public)
> 	* Where to get public specs?
> 	* How many closed and open drivers in the Linux source tree?
> 
> I suggest to add following macro:
> 
> MODULE_SPECIFICATION(terms, source);
> 
> where "terms" is one of
> 
>  * MODULE_SPEC_ANY_PARTY_NDA
> 	- specification available to any party for an NDA
>  * MODULE_SPEC_ANY_PARTY
> 	- specification available in public, or at least available 
> 	  without NDA to any party
>  * MODULE_SPEC_RESTRICTED
> 	- none of the above
> 
> and "source":
> 
>  * contact address for nda specs
>  * any public source for a public specification (http://, email address, 
>    ...)
>  * empty string otherwise
> 
> I realise this macro somewhat circumvents the purpose of Documentation/ 
> directory but the idea is to have a direct 1:1 mapping between drivers 
> and specification sources so that it would be easy to collect statistics 
> of "open" hardware by using grep et al.
> 
> What do you think? Useless annotations or useful information?

Useless, since noone will maintain this information (e.g. an
"email address" might no longer be valid several years from now, or a 
company might change the policies for releaseing information).

And also useless since there doesn't seem to be a serious use case.

> Heikki Orsila

cu
Adrian

-- 

       "Is there not promise of rain?" Ling Tan asked suddenly out
        of the darkness. There had been need of rain for many days.
       "Only a promise," Lao Er said.
                                       Pearl S. Buck - Dragon Seed

Re: [RFC] New driver information

[Daniel Barkalow]

On Fri, 16 Feb 2007, Heikki Orsila wrote:

> I just read
> 
> 	http://kerneltrap.org/node/7729
> 
> and it occured to me that it would be informative to have a new device 
> driver macro. The motivation for the new macro would be 4 issues:
> 
> 	* Is it possible to get specifications for the device?
> 	* If yes, under what terms? (nda, public)
> 	* Where to get public specs?
> 	* How many closed and open drivers in the Linux source tree?

This doesn't make any sense as a driver macro, because it's per device, 
not per driver. E.g., the sdhci driver drives a number of devices, 
including both well-documented devices and devices whose only 
documentation is that the PCI ID matches (and they work with only a few 
quirks).

On the other hand, a kconfig-readable table of PCI, USB, etc IDs with this 
information isn't a bad idea, especially if the drivers actually depend on 
it (so that it has to be kept up to date, at least as far as the 
device/driver mapping).