On Thu, Aug 16, 2012 at 11:10:30AM -1000, Mitch Bradley wrote:

On 8/16/2012 8:38 AM, Stephen Warren wrote:

quoted

Device tree bindings shouldn't reference Linux documentation; the
bindings are supposed to be OS-agnostic.

While it is true that bindings should try to be OS-agnostic, there is
the practical matter of where to put documentation so that it is widely
accessible.  The Linux source tree is one of the most accessible things
there is, considering how widely it is replicated.

As the original instigator of the policy that the device tree should
describe the hardware "OS-neutrally", I personally don't have a problem
with bindings referring to Linux documentation.  I wouldn't like
references to proprietary and inaccessible documentation.

OS agnosticness isn't the only issue here - the other problem with using
Linux documentation is that except for things that are specifically
userspace interfaces and the DT bindings nothing is intended to be
stable so bindings defined in terms of Linux documentation may randomly
change.  We're not doing an awesome job of that with DT right now but we
should try and so we ought to avoid including non-ABI things in ABIs
like this.