[DTSpec PATCH v2] Add items to Devicetree Source Format chapter

[DTSpec PATCH v2] Add items to Devicetree Source Format chapter

[Frank Rowand]

From: Frank Rowand <frank.rowand-mEdOJwZ7QcZBDgjK7y7TUQ@public.gmane.org>

Add items to Devicetree Source Format chapter

- Add naming convention for DTS files and DTS include files
- Add /include/ compiler directive
- Add ";" to end of node definition
- Add /delete-node/ and /delete-property/
- Add arithmetic, bitwise, logical, and ternary expressions

Note that cpp directives are not included in this patch, and
are not yet specified in this appendix.

Signed-off-by: Frank Rowand <frank.rowand-mEdOJwZ7QcZBDgjK7y7TUQ@public.gmane.org>
---

changes in v2
  - arithmetic operators "and", "or" were incorrectly listed as as bitwise
  - thus bitwise operators "and", "or" were incorrectly shown
  - "exclusive or" operator added
  - logical and arithmetic "not" operators added
  - ternary operator added
  - moved shift operators from arithmetic to bitwise


 source/source-language.rst |   70 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 69 insertions(+), 1 deletion(-)

Index: b/source/source-language.rst
===================================================================
--- a/source/source-language.rst
+++ b/source/source-language.rst
@@ -9,6 +9,19 @@ devicetree in the form expected by the k
 not a formal syntax definition of DTS, but describes the basic
 constructs used to represent devicetrees.
 
+The name of DTS files should end with ".dts".
+
+Compiler directives
+-------------------
+
+Other source files can be included from a DTS file.  The name of include
+files should end with ".dtsi".  Included files can in turn include
+additional files.
+
+::
+
+    /include/ "FILE"
+
 Node and property definitions
 -----------------------------
 
@@ -21,11 +34,18 @@ preceded by a label.
     [label:] node-name[@unit-address] {
         [properties definitions]
         [child nodes]
-    }
+    };
 
 Nodes may contain property definitions and/or child node definitions. If
 both are present, properties shall come before child nodes.
 
+Previously defined nodes may be deleted.
+
+::
+
+    /delete-node/ node-name;
+    /delete-node/ &label;
+
 Property definitions are name value pairs in the form:
 
 ::
@@ -39,6 +59,12 @@ form:
 
         [label:] property-name;
 
+Previously defined properties may be deleted.
+
+::
+
+    /delete-property/ property-name;
+
 Property values may be defined as an array of 32-bit integer cells, as
 null-terminated strings, as bytestrings or a combination of these.
 
@@ -48,6 +74,48 @@ null-terminated strings, as bytestrings
 ::
 
         interrupts = <17 0xc>;
+-  values may be represented as arithmetic, bitwise, or logical expressions
+   within parenthesis.
+
+::
+
+    Arithmetic operators
+
+    +   add
+    -   subtract
+    *   multiply
+    /   divide
+
+::
+
+    Bitwise operators
+
+    &    and
+    |    or
+    ^    exclusive or
+    ~    not
+    <<  left shift
+    >>  right shift
+
+::
+
+    Logical operators
+
+    <    less than
+    >    greater than
+    <=   less than or equal
+    >=   greater than or equal
+    ==   equal
+    !=   not equal
+    &&   and
+    ||   or
+    !    not
+
+::
+
+    Ternary operators
+
+    ?:   (condition ? value_if_true : value_if_false)
 
 -  A 64-bit value is represented with two 32-bit cells. Example:
 

Re: [DTSpec PATCH v2] Add items to Devicetree Source Format chapter

[David Gibson]

[-- Attachment #1: Type: text/plain, Size: 4237 bytes --]

On Tue, Jun 07, 2016 at 01:49:59PM -0700, Frank Rowand wrote:
> From: Frank Rowand <frank.rowand-mEdOJwZ7QcZBDgjK7y7TUQ@public.gmane.org>
> 
> Add items to Devicetree Source Format chapter
> 
> - Add naming convention for DTS files and DTS include files
> - Add /include/ compiler directive
> - Add ";" to end of node definition
> - Add /delete-node/ and /delete-property/
> - Add arithmetic, bitwise, logical, and ternary expressions
> 
> Note that cpp directives are not included in this patch, and
> are not yet specified in this appendix.
> 
> Signed-off-by: Frank Rowand <frank.rowand-mEdOJwZ7QcZBDgjK7y7TUQ@public.gmane.org>
> ---
> 
> changes in v2
>   - arithmetic operators "and", "or" were incorrectly listed as as bitwise
>   - thus bitwise operators "and", "or" were incorrectly shown
>   - "exclusive or" operator added
>   - logical and arithmetic "not" operators added
>   - ternary operator added
>   - moved shift operators from arithmetic to bitwise
> 
> 
>  source/source-language.rst |   70 ++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 69 insertions(+), 1 deletion(-)
> 
> Index: b/source/source-language.rst
> ===================================================================
> --- a/source/source-language.rst
> +++ b/source/source-language.rst
> @@ -9,6 +9,19 @@ devicetree in the form expected by the k
>  not a formal syntax definition of DTS, but describes the basic
>  constructs used to represent devicetrees.
>  
> +The name of DTS files should end with ".dts".
> +
> +Compiler directives
> +-------------------
> +
> +Other source files can be included from a DTS file.  The name of include
> +files should end with ".dtsi".  Included files can in turn include
> +additional files.
> +
> +::
> +
> +    /include/ "FILE"
> +
>  Node and property definitions
>  -----------------------------
>  
> @@ -21,11 +34,18 @@ preceded by a label.
>      [label:] node-name[@unit-address] {
>          [properties definitions]
>          [child nodes]
> -    }
> +    };
>  
>  Nodes may contain property definitions and/or child node definitions. If
>  both are present, properties shall come before child nodes.
>  
> +Previously defined nodes may be deleted.
> +
> +::
> +
> +    /delete-node/ node-name;
> +    /delete-node/ &label;
> +
>  Property definitions are name value pairs in the form:
>  
>  ::
> @@ -39,6 +59,12 @@ form:
>  
>          [label:] property-name;
>  
> +Previously defined properties may be deleted.
> +
> +::
> +
> +    /delete-property/ property-name;
> +
>  Property values may be defined as an array of 32-bit integer cells, as
>  null-terminated strings, as bytestrings or a combination of these.
>  
> @@ -48,6 +74,48 @@ null-terminated strings, as bytestrings
>  ::
>  
>          interrupts = <17 0xc>;
> +-  values may be represented as arithmetic, bitwise, or logical expressions
> +   within parenthesis.
> +
> +::
> +
> +    Arithmetic operators
> +
> +    +   add
> +    -   subtract
> +    *   multiply
> +    /   divide
> +
> +::
> +
> +    Bitwise operators
> +
> +    &    and
> +    |    or
> +    ^    exclusive or
> +    ~    not
> +    <<  left shift
> +    >>  right shift
> +
> +::
> +
> +    Logical operators
> +
> +    <    less than
> +    >    greater than
> +    <=   less than or equal
> +    >=   greater than or equal
> +    ==   equal
> +    !=   not equal
> +    &&   and
> +    ||   or
> +    !    not

Fwiw, I think &&, || and ! usually get classified as "logical
operators" but <, > etc. get classified as "relational operators"
rather than putting them in the same category.

Hrm.. given that you're listing them all here, I wonder if it would
make sense to do so in precedence order (should be the same as for C).

> +::
> +
> +    Ternary operators
> +
> +    ?:   (condition ? value_if_true : value_if_false)
>  
>  -  A 64-bit value is represented with two 32-bit cells. Example:
>  
> 

-- 
David Gibson			| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you.  NOT _the_ _other_
				| _way_ _around_!
http://www.ozlabs.org/~dgibson

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [DTSpec PATCH v2] Add items to Devicetree Source Format chapter

[Frank Rowand]

On 06/07/16 16:50, David Gibson wrote:
> On Tue, Jun 07, 2016 at 01:49:59PM -0700, Frank Rowand wrote:
>> From: Frank Rowand <frank.rowand-mEdOJwZ7QcZBDgjK7y7TUQ@public.gmane.org>
>>
>> Add items to Devicetree Source Format chapter
>>
>> - Add naming convention for DTS files and DTS include files
>> - Add /include/ compiler directive
>> - Add ";" to end of node definition
>> - Add /delete-node/ and /delete-property/
>> - Add arithmetic, bitwise, logical, and ternary expressions
>>
>> Note that cpp directives are not included in this patch, and
>> are not yet specified in this appendix.
>>
>> Signed-off-by: Frank Rowand <frank.rowand-mEdOJwZ7QcZBDgjK7y7TUQ@public.gmane.org>
>> ---
>>
>> changes in v2
>>   - arithmetic operators "and", "or" were incorrectly listed as as bitwise
>>   - thus bitwise operators "and", "or" were incorrectly shown
>>   - "exclusive or" operator added
>>   - logical and arithmetic "not" operators added
>>   - ternary operator added
>>   - moved shift operators from arithmetic to bitwise
>>
>>
>>  source/source-language.rst |   70 ++++++++++++++++++++++++++++++++++++++++++++-
>>  1 file changed, 69 insertions(+), 1 deletion(-)
>>
>> Index: b/source/source-language.rst
>> ===================================================================
>> --- a/source/source-language.rst
>> +++ b/source/source-language.rst
>> @@ -9,6 +9,19 @@ devicetree in the form expected by the k

< snip >

>> +    Logical operators
>> +
>> +    <    less than
>> +    >    greater than
>> +    <=   less than or equal
>> +    >=   greater than or equal
>> +    ==   equal
>> +    !=   not equal
>> +    &&   and
>> +    ||   or
>> +    !    not
> 
> Fwiw, I think &&, || and ! usually get classified as "logical
> operators" but <, > etc. get classified as "relational operators"
> rather than putting them in the same category.

Good point.  I'll send v3 with that change.


> Hrm.. given that you're listing them all here, I wonder if it would
> make sense to do so in precedence order (should be the same as for C).

That seems like a good idea, so I tried it.  The result is a lot less
readable to me.

< snip >