From: Jon Loeliger <hidden> Date: 2007-06-02 16:04:58
So, like, the other day Segher Boessenkool mumbled:
That, and I often get tired of seeing the same mistakes
over and over again. When I see a proposed tree that's
just too awful I don't really know where to start.
That is a good point.
I think there are several factors at work here. First and
foremost, I am not an expert in this area; it is new to me.
I am not afraid to say that I really need the guidance of
an expert here. Second, perhaps there is lingering legacy
crap in some of the early DTS files that should be systematically
cleaned up. Many of them were written during a time when we
were really first learning about the whole Device Tree. While
they may have been there on some, say, Apple boards, it's all
new for the FSL embedded parts. Cloned mistakes then likely
contributed to the problems and should be fixed. Finally,
perhaps our documentation on how some of the important fields
should work or be derived is lacking and could be improved.
Suggestions or patches down this line would likely be welcomed.
I also find the DTS source format a bit hard to read,
but maybe that's just me.
I, at least, am open to suggestions that might improve it.
Thanks,
jdl
That, and I often get tired of seeing the same mistakes
over and over again. When I see a proposed tree that's
just too awful I don't really know where to start.
That is a good point.
I think there are several factors at work here. First and
foremost, I am not an expert in this area; it is new to me.
I am not afraid to say that I really need the guidance of
an expert here.
Feel free to ask for advice on IRC, on the list, or
elsewhere _before_ sending a patch.
Second, perhaps there is lingering legacy
crap in some of the early DTS files that should be systematically
cleaned up.
Yes there is. Maybe one day I'll get to it, I'm hoping
someone else will fix this though ;-)
Many of them were written during a time when we
were really first learning about the whole Device Tree. While
they may have been there on some, say, Apple boards, it's all
new for the FSL embedded parts.
Many apple trees (pun intended) aren't all that great
either.
Cloned mistakes then likely
contributed to the problems and should be fixed. Finally,
perhaps our documentation on how some of the important fields
should work or be derived is lacking and could be improved.
The official (and unofficial) Open Firmware docs are quite
good. Perhaps we need a big huge fat sign in the DTS docs
pointing to them.
Suggestions or patches down this line would likely be welcomed.
quoted
I also find the DTS source format a bit hard to read,
but maybe that's just me.
I, at least, am open to suggestions that might improve it.
My biggest problem when reviewing patches (or whole trees)
in mail is the indenting. Part of that I could fix myself
by setting my mail reader to eight spaces indent. The bigger
problem is that trees are just not very readable in flat
text format (you really need to see the parent node together
with every of its child nodes). There's no real way to fix
this I'm afraid. In "real" OF, most properties are filled
in programmatibly, and you typically have one node per source
file. This won't help for DTS files. Maybe putting more
(good!) comments in DTS files would help though?
Segher
From: Benjamin Herrenschmidt <benh@kernel.crashing.org> Date: 2007-06-02 23:17:17
On Sat, 2007-06-02 at 22:00 +0200, Segher Boessenkool wrote:
Feel free to ask for advice on IRC, on the list, or
elsewhere _before_ sending a patch.
Bah, sending a patch is good too, don't be too hard there. I for one
prefer the approach of sending a patch first.
quoted
Second, perhaps there is lingering legacy
crap in some of the early DTS files that should be systematically
cleaned up.
Yes there is. Maybe one day I'll get to it, I'm hoping
someone else will fix this though ;-)
We probably need to improve the documentation in fact. Maybe with a step
by step HOWTO create your device-tree with examples for typical things
like PCI etc.. and the rational of why for each of these, we chose to do
XXX instead of YYY...
The official (and unofficial) Open Firmware docs are quite
good. Perhaps we need a big huge fat sign in the DTS docs
pointing to them.
They aren't -that- good when you come out of the blue and don't know
where to start. I think a tutorial based on building a tree for an
example board step by step would be best.
Ben.
Feel free to ask for advice on IRC, on the list, or
elsewhere _before_ sending a patch.
Bah, sending a patch is good too, don't be too hard there. I for one
prefer the approach of sending a patch first.
I'm saying that if you're unsure about stuff, you can ask
about it -- sending a preliminary patch with the question
is one way, sure.
quoted
quoted
Second, perhaps there is lingering legacy
crap in some of the early DTS files that should be systematically
cleaned up.
Yes there is. Maybe one day I'll get to it, I'm hoping
someone else will fix this though ;-)
We probably need to improve the documentation in fact. Maybe with a
step
by step HOWTO create your device-tree with examples for typical things
like PCI etc.. and the rational of why for each of these, we chose to
do
XXX instead of YYY...
A howto-like doc would help yes. Rationale might help people
better understand how things work, too, sure.
quoted
The official (and unofficial) Open Firmware docs are quite
good. Perhaps we need a big huge fat sign in the DTS docs
pointing to them.
They aren't -that- good when you come out of the blue and don't know
where to start.
Well most people don't even know those docs _exist_ it
seems.
I think a tutorial based on building a tree for an
example board step by step would be best.
From: Olof Johansson <hidden> Date: 2007-06-04 00:10:38
On Sun, Jun 03, 2007 at 09:16:42AM +1000, Benjamin Herrenschmidt wrote:
On Sat, 2007-06-02 at 22:00 +0200, Segher Boessenkool wrote:
quoted
The official (and unofficial) Open Firmware docs are quite
good. Perhaps we need a big huge fat sign in the DTS docs
pointing to them.
They aren't -that- good when you come out of the blue and don't know
where to start. I think a tutorial based on building a tree for an
example board step by step would be best.
There seems to be two things that causes problems:
1) People basing their new tree on an old example that's broken, and
getting crap for that because it's not correct
2) Trying to add new devices that aren't in any trees already, and
the near infinite discussions that then start.
(1) Could clearly be solved to a fair extent by having a "blessed
golden tree" that people can clone their own board files from, instead
of grabbing a random one and hoping that it's not too broken.
(2) I don't have a good solution for. Better documentation pointers would
definitely be a help, but it's not the whole solution. I'd expect it to
get better and better over time as there'll be less and less unmapped
terrain, and better and better examples to use.
-Olof
They aren't -that- good when you come out of the blue and don't know
where to start. I think a tutorial based on building a tree for an
example board step by step would be best.
There seems to be two things that causes problems:
0) The lack of good, clear, exhaustive, and recipe-style
documentation.
1) People basing their new tree on an old example that's broken, and
getting crap for that because it's not correct
Yeah.
2) Trying to add new devices that aren't in any trees already, and
the near infinite discussions that then start.
This is a *good* thing (as long as it's productive) --
it simply is a lot of work to define a good device binding
for non-trivial devices.
(2) I don't have a good solution for. Better documentation pointers
would
definitely be a help, but it's not the whole solution. I'd expect it to
get better and better over time as there'll be less and less unmapped
terrain, and better and better examples to use.