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>
diff --git a/docs/components/cot-binding.rst b/docs/components/cot-binding.rst
index 702bb56..1d31e3d 100644
--- a/docs/components/cot-binding.rst
+++ b/docs/components/cot-binding.rst
@@ -138,7 +138,7 @@
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 @@
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 @@
#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;
diff --git a/docs/license.rst b/docs/license.rst
index 8996105..9e0298b 100644
--- a/docs/license.rst
+++ b/docs/license.rst
@@ -93,9 +93,27 @@
- ``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/
diff --git a/docs/tools/cot-dt2c.rst b/docs/tools/cot-dt2c.rst
new file mode 100644
index 0000000..7b7e56f
--- /dev/null
+++ b/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/
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
index 91651bf..c0e214a 100644
--- a/docs/tools/index.rst
+++ b/docs/tools/index.rst
@@ -7,6 +7,7 @@
memory-layout-tool
transfer-list-compiler
+ cot-dt2c
--------------