RE: [PATCH v2 2/3] powerpc: document the Open PIC device tree binding

quoted

+  - no-reset
+      Usage: optional
+      Value type: <empty>
+      Definition: The presence of this property indicates that the
+ PIC
+          should not be reset during runtime initialization.  The
+ presence of
+          this property also mandates that any initialization related
+ to
+          interrupt sources shall be limited to sources explicitly
+ referenced
+          in the device tree.

Please follow the lead set by the other binding documentation which is more
concise and tends to be of the form:

    Required properties:
        - reg : <description>
        - interrupt-controller : <description>

    Optional Properties:
        - no-reset : blah

I'm considering formalizing the binding format so that fully specified and
cross-referenced documentation can be generated from the bindings
directory.

Regarding the format-- The definition should also to specify the value
type.  I don't see this being consistently done in existing bindings.  
They are not completely unclear, but using consistent terms might help.

The ePAPR uses this convention:

    <empty>      # no value, a Boolean
     <u32>       # A 32-bit integer in big-endian format
     <u64>       # A 64-bit integer in big-endian format
   <string>      # null terminated
 <prop-encoded-array>    # format specific to the property
   <phandle>    # A <u32> value, referecnes another node
  <stringlist>    # A list of <string> values concatenated together.

The identifier prop-encoded-array came from precedence in other
of binding and ieee1275.   prop-encoded-arrays should be
be specifically defined in terms of # of cells and the 
meaning of each cell.

If you use the above types identifiers, there is no ambiguity.

Also, there are properties that don't necessarily fall in 'required'
and 'optional', but may be required depending on the context.  Thus
the 'Usage' identifier which Meador derived from my mpic binding
posted.   Usage could be:
               Required
               Optional
               See Definition

Stuart