diff --git a/docs/components/cot-binding.rst b/docs/components/cot-binding.rst index 702bb56a0..1d31e3dd9 100644 --- a/docs/components/cot-binding.rst +++ b/docs/components/cot-binding.rst @@ -138,7 +138,7 @@ Example: trusted-key-cert: trusted-key-cert { root-certificate; image-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 = ; 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 = ; reg = ; oid = TRUSTED_FW_NVCOUNTER_OID; }; - non_trusted_nv_counter: non_trusted_nv_counter { + non_trusted_nv_ctr: non_trusted_nv_ctr { id = ; reg = ; oid = NON_TRUSTED_FW_NVCOUNTER_OID; diff --git a/docs/license.rst b/docs/license.rst index 89961059b..9e0298b7f 100644 --- a/docs/license.rst +++ b/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/ diff --git a/docs/tools/cot-dt2c.rst b/docs/tools/cot-dt2c.rst new file mode 100644 index 000000000..7b7e56fde --- /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 91651bf1e..c0e214a97 100644 --- a/docs/tools/index.rst +++ b/docs/tools/index.rst @@ -7,6 +7,7 @@ Tools memory-layout-tool transfer-list-compiler + cot-dt2c --------------