Does anyone read device.txt etc?
Hi All,
I'm just wondering if some corners of our documentation are useful or not.
So straw poll. Has anyone ever read the stuff in
device.txt?
trigger.txt?
ring.txt?
I'm tempted to drop all 3 of these as pointless maintenance overhead...
Obviously those I've cc'd are actually active developers and probably don't look at any docs at all that often, so other lurkers / new developers please do respond to this email!
A well commented dummy driver would be better for explaining these things.
Thanks,
Jonathan
Hi Jonathan,
Quoted 1 line
I'm just wondering if some corners of our documentation are useful or not=
.
Quoted 6 lines
So straw poll. =A0Has anyone ever read the stuff in
device.txt?
trigger.txt?
ring.txt?
Yes. When I was first looking at changing my HMC6343 driver over to the IIO subsystem I read everything in drivers/staging/iio/Documentation. It wasn't all that helpful--partly because I'm new to kernel development, and partly because it wasn't specific enough. (This was a few months ago.)
Quoted 2 lines
I'm tempted to drop all 3 of these as pointless maintenance overhead...
I can certainly understand this!
Quoted 2 lines
A well commented dummy driver would be better for explaining these things.
Agreed, especially with these three docs. The information presented is fairly fundamental to writing a good IIO driver, but would be much more useful inline with the reference implementation of each part.
I also agree with Michael that the documentation should be a good jumping-off point. In particular, I was looking to answer two questions:
1) Why would I use this subsystem? (general feature descriptions, example applications, comparison to other subsystems)
2) How is this subsystem organized/used? (constants, masking, relationship with other subsystems like i2c)
Part of the difficulty I had was in attempting to grok a staging feature as=
if
it were mature and static (ring.txt in particular confused me), so this is,=
of
course, just my 2c.
Thanks for all the work you're putting in to IIO! I hope this helps.
Cheers,
Jon
Quoted 6 lines · Jonathan Kunkee
Hi Jonathan,
Quoted 4 lines
I'm just wondering if some corners of our documentation are useful or not.
So straw poll. Has anyone ever read the stuff in
Quoted 8 lines
Quoted 3 lines
device.txt?
trigger.txt?
ring.txt?Yes. When I was first looking at changing my HMC6343 driver over to the IIO subsystem I read everything in
drivers/staging/iio/Documentation. It wasn't all that helpful--partly because I'm new to kernel development, and partly because it wasn't specific enough. (This was a few months ago.)
Hehe, I think that counts as a negative on current docs but a positive that we should have something that actually does the job better!
Quoted 4 lines
Quoted 3 lines
I'm tempted to drop all 3 of these as pointless maintenance overhead...
Quoted 8 lines
I can certainly understand this!
Quoted 2 lines
A well commented dummy driver would be better for explaining these things.
Agreed, especially with these three docs. The information presented is fairly fundamental to writing a good IIO driver, but would be much more useful inline with the reference implementation of each part.
Guess we need a 'stub' driver or perhaps two of them, one a basic sysfs only version (so really short) and the other with all the bells and whistles.
Manuel, you proposed something that would be a bit like the all bells and whistles a while ago. Is there any code to see yet? Seems a shame to duplicate effort if you have had a chance to work on this!
Quoted 5 lines
I also agree with Michael that the documentation should be a good jumping-off point. In particular, I was looking to answer two questions:
1) Why would I use this subsystem? (general feature descriptions, example applications, comparison to other subsystems)
Ah, would you be willing to look at the intro email I wrote to the proposal to start moving out of staging? It is meant to be covering exactly those sort of issues, but I may well have missed stuff given I'm reasonably familiar with all the relevant subsystems! It was in the thread
[RFC PATCH 0/4] IIO: Out of staging step 1. The core.
or I can repost if that helps.
Would love to get some feedback on that from everyone.
Quoted 2 lines
2) How is this subsystem organized/used? (constants, masking, relationship with other subsystems like i2c)
The relationship with bus subsystems is something that wouldn't have occurred to me for starters! Thanks.
Quoted 6 lines
Part of the difficulty I had was in attempting to grok a staging feature as if it were mature and static (ring.txt in particular confused me), so this is, of course, just my 2c.
Thanks for all the work you're putting in to IIO! I hope this helps.
I certainly does. Thanks for taking the time!
Jonathan
Hi all,
Am Freitag, 16. September 2011, 10:35:46 schrieb Jonathan Cameron:
Quoted 12 lines · Jonathan Kunkee
Quoted 11 lines
Hi Jonathan,
Quoted 8 lines
I'm just wondering if some corners of our documentation are useful or not.
So straw poll. Has anyone ever read the stuff in
device.txt?
trigger.txt?
ring.txt?
Quoted 5 lines
Quoted 5 lines
Yes. When I was first looking at changing my HMC6343 driver over to the IIO subsystem I read everything in
drivers/staging/iio/Documentation. It wasn't all that helpful--partly because I'm new to kernel development, and partly because it wasn't specific enough. (This was a few months ago.)
I take these docs as a reference to see "how it was thought to be", when drivers implementations disagree on some point. But sure a reference driver would be even better.
Quoted 15 lines
Hehe, I think that counts as a negative on current docs but a positive that we should have something that actually does the job better!
Quoted 11 lines
Quoted 2 lines
I'm tempted to drop all 3 of these as pointless maintenance overhead...
I can certainly understand this!
Quoted 2 lines
A well commented dummy driver would be better for explaining these things.
Agreed, especially with these three docs. The information presented is fairly fundamental to writing a good IIO driver, but would be much more useful inline with the reference implementation of each part.
Quoted 7 lines
Guess we need a 'stub' driver or perhaps two of them, one a basic sysfs only version (so really short) and the other with all the bells and whistles.
Manuel, you proposed something that would be a bit like the all bells and whistles a while ago. Is there any code to see yet? Seems a shame to duplicate effort if you have had a chance to work on this!
Actually Michael and I agreed that he will start with such an implementation. If there's nothing to go with yet, I can do that too, of course.
Quoted 33 lines
Quoted 6 lines
I also agree with Michael that the documentation should be a good jumping-off point. In particular, I was looking to answer two questions:
1) Why would I use this subsystem? (general feature descriptions,example applications, comparison to other subsystems)
Ah, would you be willing to look at the intro email I wrote to the proposal to start moving out of staging? It is meant to be covering exactly those sort of issues, but I may well have missed stuff given I'm reasonably familiar with all the relevant subsystems! It was in the thread [RFC PATCH 0/4] IIO: Out of staging step 1. The core.
or I can repost if that helps.Would love to get some feedback on that from everyone.
Quoted 4 lines
2) How is this subsystem organized/used? (constants, masking, relationship
with other subsystems like i2c)
The relationship with bus subsystems is something that wouldn't have occurred to me for starters! Thanks.
Quoted 5 lines
Part of the difficulty I had was in attempting to grok a staging feature as if it were mature and static (ring.txt in particular confused me), so this is, of course, just my 2c.
Thanks for all the work you're putting in to IIO! I hope this helps.
I certainly does. Thanks for taking the time!
Jonathan
Signature · 2 lines
Regards, Manuel Stahl
Quoted 21 lines · Manuel Stahl
Hi all,
Am Freitag, 16. September 2011, 10:35:46 schrieb Jonathan Cameron:
Quoted 12 lines · Jonathan Kunkee
Quoted 11 lines
Hi Jonathan,
Quoted 8 lines
I'm just wondering if some corners of our documentation are useful or not.
So straw poll. Has anyone ever read the stuff in
device.txt?
trigger.txt?
ring.txt?Quoted 5 lines
Quoted 5 lines
Yes. When I was first looking at changing my HMC6343 driver over to the IIO subsystem I read everything in
drivers/staging/iio/Documentation. It wasn't all that helpful--partly because I'm new to kernel development, and partly because it wasn't specific enough. (This was a few months ago.)
Quoted 3 lines
I take these docs as a reference to see "how it was thought to be", when drivers implementations disagree on some point. But sure a reference driver would be even better.
Hmm. how it was thought to be some time ago unfortunately. These fuzzy docs are a real pain to keep in sync. A demo driver would be much easier as it would break with everything else when we change the internal ABIs.
Quoted 20 lines
Quoted 20 lines
Hehe, I think that counts as a negative on current docs but a positive that we should have something that actually does the job better!
Quoted 11 lines
Quoted 2 lines
I'm tempted to drop all 3 of these as pointless maintenance overhead...
I can certainly understand this!
Quoted 2 lines
A well commented dummy driver would be better for explaining these things.
Agreed, especially with these three docs. The information presented is fairly fundamental to writing a good IIO driver, but would be much more useful inline with the reference implementation of each part.
Guess we need a 'stub' driver or perhaps two of them, one a basic sysfs only version (so really short) and the other with all the bells and whistles.
Quoted 6 lines
Quoted 3 lines
Manuel, you proposed something that would be a bit like the all bells and whistles a while ago. Is there any code to see yet? Seems a shame to duplicate effort if you have had a chance to work on this!
Actually Michael and I agreed that he will start with such an implementation. If there's nothing to go with yet, I can do that too, of course.
I'll bash out a very basic and massively overly commented one to act as a discussion point then we can firm it up into something useful both as documentation and for your userspace testing (if sensible).
Quoted 36 lines
Quoted 34 lines
Quoted 7 lines
I also agree with Michael that the documentation should be a good jumping-off point. In particular, I was looking to answer two questions:
1) Why would I use this subsystem? (general feature descriptions,example applications, comparison to other subsystems)
Ah, would you be willing to look at the intro email I wrote to the proposal to start moving out of staging? It is meant to be covering exactly those sort of issues, but I may well have missed stuff given I'm reasonably familiar with all the relevant subsystems! It was in the thread [RFC PATCH 0/4] IIO: Out of staging step 1. The core.
or I can repost if that helps.Would love to get some feedback on that from everyone.
Quoted 4 lines
2) How is this subsystem organized/used? (constants, masking, relationship
with other subsystems like i2c)
The relationship with bus subsystems is something that wouldn't have occurred to me for starters! Thanks.
Quoted 5 lines
Part of the difficulty I had was in attempting to grok a staging feature as if it were mature and static (ring.txt in particular confused me), so this is, of course, just my 2c.
Thanks for all the work you're putting in to IIO! I hope this helps.
I certainly does. Thanks for taking the time!
Jonathan