[U-Boot] [PATCH 4/4 v3] s5pc1xx: add support SMDKC100 board

[Peter Tyser]

> >>>
> >> Please include a brief readme doc/README.s5pc1xx similar to README.omap
> > 
> > Hi Tom,
> > Others may disagree, but I'm personally opposed to creating
> 
> Slugfest over documentation!

Nothing gets me more worked up than a documentation discussion:)

> I can see you point.  If you have the board you likely have the user manual.
> In no way do I want a user manual.
> 
> Mostly what I am looking for brief product description and a list of the
> configs.  Maybe some hints if the setup is tricky.  README.omap3 contains
> writeups on 6 boards, each get about 10 lines.

The README.omap3 looks decent, but even that I would personally have a
few issues with the following:
1. The list of omap3 boards is going to get out of date quickly when
people don't update README.omap3.  Eg devkit8000 already isn't in the
list:)

2. I still think the details of how to configure U-Boot for a board, use
the ecc commands, and gpio interfaces would still be better placed in a
User's Manual.  New users will use the User's Manual and experienced
users will know how to dig through the code - eg I'm not sure who will
reference README.omap3:).  Those command names and config names will
probably change at some point in the future, and there's a decent chance
README.omap3 won't be similarly updated.

> The vendor readme is also good if you want to convey board family u-boot
> interfaces to other developers.  See my writeup of omap gpio in omap3.

I see your point.  If it were me, I'd throw that documentation in the
omap3 gpio driver itself.  Its much more likely to be kept in sync when
code changes, and if someone is writing low-level U-Boot code, I'd hope
they'd be smart enough to track down the gpio driver they need to use.

> > board/vendor-specific doc/README.<board> files in most cases.  My logic
> > is that the people that are compiling and using U-Boot on my company's
> > boards will have bought the boards from us, and we should be the ones
> > providing them documentation.  eg I would guess the vast majority of
> > board vendors don't say "for board information consult
> > doc/README.<board> in the U-Boot source code", they provide a PDF, text
> > document, datasheet, etc about the board and how it can be used.  Thus
> > the doc/README.<board> doesn't really provide any useful info.
> 
> This is doc/README.<soc>

OK, I missed that point.  SOC documentation does seem more fitting.  I
personally think low-level details shouldn't be in the SOC doc however.
For example, take a look at README.blackfin.  There's nothing I could
ever change about U-Boot which would require this file to be updated,
which is perfect!

<snip>

> > I only care because I hate having to pick through 10 board-specific
> > README files every time I make a change the renames a command, adds a
> > new command, changes a CONFIG_XYZ name, etc:)
> > 
> 
> This should be the task of the board/soc maintainer.

I think this is debatable.  I'd guess most board maintainers don't
follow the list closely or care enough to monitor every change and
determine if they need to update their board's README file.  So if the
person making a large change doesn't update relevant READMEs, no one
will.  Eg, no one added devkit8000 to README.omap3.

> > I think README files are good in general, but board-specific details
> > should be documented elsewhere such as a product manual. 
> > 
> > Anyway, that's my $.02.
> 
> Taking it outside over documentation,

Best,
Peter