feat(arm): update documentation for cot-dt2c

Add documentation for the cot-dt2c feature

Change-Id: I27383882b639e39217d09ca76e316098cc4753d0
Signed-off-by: Xialin Liu <Xialin.Liu@ARM.com>

docs/components/cot-binding.rst

@@ -138,7 +138,7 @@ Example:
          trusted-key-cert: trusted-key-cert {
             root-certificate;
             image-id = <TRUSTED_KEY_CERT_ID>;
-            antirollback-counter = <&trusted_nv_counter>;
+            antirollback-counter = <&trusted_nv_ctr>;
 
             trusted-world-pk: trusted-world-pk {
                oid = TRUSTED_WORLD_PK_OID;
@@ -152,7 +152,7 @@ Example:
             image-id = <SCP_FW_KEY_CERT_ID>;
             parent = <&trusted-key-cert>;
             signing-key = <&trusted_world_pk>;
-            antirollback-counter = <&trusted_nv_counter>;
+            antirollback-counter = <&trusted_nv_ctr>;
 
             scp_fw_content_pk: scp_fw_content_pk {
                oid = SCP_FW_CONTENT_CERT_PK_OID;
@@ -312,13 +312,13 @@ Below is non-volatile counters example for ARM platform
         #address-cells = <1>;
         #size-cells = <0>;
 
-        trusted-nv-counter: trusted_nv_counter {
+        trusted_nv_ctr: trusted_nv_ctr {
            id  = <TRUSTED_NV_CTR_ID>;
            reg = <TFW_NVCTR_BASE>;
            oid = TRUSTED_FW_NVCOUNTER_OID;
         };
 
-        non_trusted_nv_counter: non_trusted_nv_counter {
+        non_trusted_nv_ctr: non_trusted_nv_ctr {
            id  = <NON_TRUSTED_NV_CTR_ID>;
            reg = <NTFW_CTR_BASE>;
            oid = NON_TRUSTED_FW_NVCOUNTER_OID;

docs/license.rst

@@ -93,9 +93,27 @@ license text is included in those source files.
 
    -  ``include/lib/dice/dice.h``
 
+-  Some source files originating from the `pydevicetree`_ project.
+   These files are licensed under the Apache License, Version 2.0, which is a
+   permissive license compatible with BSD-3-Clause. Any contributions to this
+   code must also be made under the terms of `Apache License 2.0`_.
+   These files are:
+
+   -  ``tools/cot_dt2c/cot_dt2c/pydevicetree/ast/__init__.py``
+   -  ``tools/cot_dt2c/cot_dt2c/pydevicetree/ast/directive.py``
+   -  ``tools/cot_dt2c/cot_dt2c/pydevicetree/ast/helpers.py``
+   -  ``tools/cot_dt2c/cot_dt2c/pydevicetree/ast/node.py``
+   -  ``tools/cot_dt2c/cot_dt2c/pydevicetree/ast/property.py``
+   -  ``tools/cot_dt2c/cot_dt2c/pydevicetree/ast/reference.py``
+   -  ``tools/cot_dt2c/cot_dt2c/pydevicetree/source/__init__.py``
+   -  ``tools/cot_dt2c/cot_dt2c/pydevicetree/source/grammar.py``
+   -  ``tools/cot_dt2c/cot_dt2c/pydevicetree/source/parser.py``
+   -  ``tools/cot_dt2c/cot_dt2c/pydevicetree/__init__.py``
+
+
 .. _FreeBSD: http://www.freebsd.org
 .. _Linux MIT license: https://raw.githubusercontent.com/torvalds/linux/master/LICENSES/preferred/MIT
 .. _SCC: http://www.simple-cc.org/
 .. _Open Profile for DICE: https://pigweed.googlesource.com/open-dice/
 .. _Apache License 2.0: https://www.apache.org/licenses/LICENSE-2.0.txt
-
+.. _pydevicetree: https://pypi.org/project/pydevicetree/

docs/tools/cot-dt2c.rst

@@ -0,0 +1,149 @@
+TF-A CoT dt2c Tool
+==================
+
+This tool is used to automatically generate the corresponding c file for a
+CoT DT file. Since currently TF-A support two type of CoT file: static c file
+and CoT DT binding. This is error prone and hard to maintain, therefore this
+tool can generate the c file for the platform that does not support CoT DT
+binding, given the CoT DT file so the c file can be deprecated.
+
+Prerequisites
+~~~~~~~~~~~~~
+
+#. Python (3.8 or later)
+#. `Poetry`_ Python package manager
+
+
+Getting Started
+~~~~~~~~~~~~~~~
+
+#. Install the tool
+
+    .. code::
+
+        make install
+
+
+#. Verify that the tool runs correctly
+
+    .. code::
+
+        make test
+
+
+#. Usage of the tool
+
+    .. code::
+
+        cot-dt2c
+
+    This command will output the following as usage for this command
+
+    .. code-block:: text
+
+        Usage: cot-dt2c [OPTIONS] COMMAND [ARGS]...
+
+        Options:
+        --version  Show the version and exit.
+        --help     Show this message and exit.
+
+        Commands:
+        convert-to-c
+        validate-cot
+        visualize-cot
+        validate-dt
+
+#. Uninstall the tool
+    .. code::
+
+        make uninstall
+
+    This command will uninstall the tool
+
+
+#. Uninstall the tool and clean all the build file
+    .. code::
+
+        make clean
+
+    This command will clean all the build file and implicitly uninstall the tool
+
+
+#. Call the make file from TF-A root directory
+    .. code::
+
+        make -C tools/cot-dt2c install
+        make -C tools/cot-dt2c uninstall
+        make -C tools/cot-dt2c clean
+
+Convert CoT descriptors to C file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To convert the CoT descriptors
+
+This command is for the platform that does not use CoT DT parser,
+which can generate the C file given the CoT descriptors. Before
+the conversion to C file, the tool will do an implicit checks on
+the validity of the CoT DT file.
+
+.. code::
+
+    cot-dt2c convert-to-c [INPUT DTB PATH] [OUTPUT C PATH]
+    cot-dt2c convert-to-c fdts/tbbr_cot_descriptors.dtsi test.c
+
+
+Validate CoT descriptors
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To validate the certificate
+
+The tests folder in the tool folder provides some bad-example of the
+DT file, and the tool will print out "not a valid CoT DT file" on console.
+
+The command will check the format of the CoT file
+
+#. The open bracket
+#. The open ifdef macro
+#. The missing mandatory attribute
+#. Malformed DT file (cert missing parent, missing root certs. etc.)
+
+Currently the validation is specifically for checking the CoT DT file
+
+.. code::
+
+    cot-dt2c validate-cot [INPUT DTB PATH]
+    cot-dt2c validate-cot fdts/tbbr_cot_descriptors.dtsi
+
+
+Visualize CoT descriptors
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This command create a HTML to visualize the relationship between
+the certificates and the image of a CoT DT file.
+
+.. code::
+
+    cot-dt2c visualize-cot [INPUT DTB PATH]
+    cot-dt2c visualize-cot fdts/tbbr_cot_descriptors.dtsi
+
+
+Validate Other DT files
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The command will transform the dtsi/dts file into a more standard
+dtsi/dts file inside /tmp folder that can be used as input to dt-schema
+for further validation. Currently the tool will perform some basic validation
+for the file (syntax) and dt-schema can be used for advance checks. dt-schema
+is not installed along with the tool.
+
+.. code::
+
+    cot-dt2c validate-dt [INPUT DTS PATH or INPUT DTS folder]
+    cot-dt2c validate-dt fdts/
+    cot-dt2c validate-dt fdts/fvp-bsae-gicv3.dtsi
+
+--------------
+
+*Copyright (c) 2024, Arm Limited. All rights reserved.*
+
+.. _Poetry: https://python-poetry.org/docs/

docs/tools/index.rst

@@ -7,6 +7,7 @@ Tools
 
    memory-layout-tool
    transfer-list-compiler
+   cot-dt2c
 
 --------------