Specification rendering tools

.gitignore

@@ -3,6 +3,11 @@
 
 # IDE settings
 /.vscode
+# Local OS files
+.DS_Store
+# Python cache
+__pycache__/
+*.py[cod]
 # Generated documentation
 _build
 build

Makefile

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates
+# SPDX-License-Identifier: Apache-2.0
+
+PSA_API_TOOL ?= tools
+
+# The location of psa-api-tool must be specified
+ifeq ($(wildcard $(PSA_API_TOOL)/make),)
+ $(error The 'PSA_API_TOOL' variable is not set, or does not point to a suitable installation of psa-api-tool)
+endif
+
+include $(PSA_API_TOOL)/make

README.md

@@ -11,6 +11,7 @@ This GitHub repository contains:
 *  Specification source files
 *  Reference copies of the PSA Certified API header files
 *  Examples of usage and implementation of the PSA Certified APIs
+*  Build tooling for rendering the specifications
 *  Discussions of updates to the specifications
 *  Proposed changes to the specifications
 
@@ -77,6 +78,32 @@ Crypto Driver Interface | [1.0 Alpha-1][crypto-driver-specs] | [doc/crypto-drive
 
 Reference header files for each minor version of each API are provided in the [headers/](headers) folder.
 
+## Building the specifications
+
+This repository includes the documentation build tooling in [tools/](tools). The top-level `Makefile` uses that local tool copy by default, so a normal build does not require a separate checkout of the build tools.
+
+The core HTML build path requires Python, Sphinx, and `make`. PDF output also requires a LaTeX toolchain with `pdflatex`. Regenerating figures can require additional tools, depending on the figure source format, including Graphviz, `wavedrompy`, PlantUML, Java, and `rsvg-convert`.
+
+Build one specification from the repository root with:
+
+```sh
+make doc/crypto/html
+make doc/crypto/pdf
+make doc/crypto/headers
+make doc/crypto/api-diff
+```
+
+Replace `doc/crypto` with another specification directory, such as `doc/attestation`, `doc/storage`, `doc/fwu`, `doc/status-code`, or `doc/crypto-driver`.
+
+Build one output format for every specification with:
+
+```sh
+make html
+make pdf
+```
+
+Generated output is written under [build/](build). The build guide in [tools/docs/using-psa-api-tool.md](tools/docs/using-psa-api-tool.md) describes the available targets, dependencies, and validation flow. The editing reference in [tools/docs/psa-api-tool-notes.md](tools/docs/psa-api-tool-notes.md) describes the custom directives, roles, and source conventions used by the specifications.
+
 ## Test Suite
 
 Test suites are available to validate compliance of API implementations against the specifications for Crypto, Attestation, and Secure Storage APIs, from:

design/rfc-01-fwu-suit/fetch-sequence.puml

@@ -5,7 +5,7 @@
 
 ' SUIT update using the FWU API
 
-!include atg-spec.pumh
+!include psa-spec.pumh
 
 box Network
 participant "Update server" as server

design/rfc-01-fwu-suit/installer-sequence.puml

@@ -3,7 +3,7 @@
 
 @startuml
 
-!include atg-spec.pumh
+!include psa-spec.pumh
 
 ' Complex SUIT installation using the FWU API
 

design/rfc-01-fwu-suit/no-reboot-sequence.puml

@@ -3,7 +3,7 @@
 
 @startuml
 
-!include atg-spec.pumh
+!include psa-spec.pumh
 
 ' Complex SUIT installation using the FWU API, no boot
 

design/rfc-01-fwu-suit/suit-install.puml

@@ -3,7 +3,7 @@
 
 @startuml
 
-!include atg-spec.pumh
+!include psa-spec.pumh
 
 ' title SUIT update : advanced installers
 

design/rfc-01-fwu-suit/suit-update.puml

@@ -3,7 +3,7 @@
 
 @startuml
 
-!include atg-spec.pumh
+!include psa-spec.pumh
 
 ' title SUIT update : high-level flow
 

doc/attestation/conf.py

@@ -68,14 +68,12 @@
     'page_break': 'chapter'
     }
 
-# absolute or relative path to the psa_spec material from this file
-# atg_sphinx_spec_dir = '../atg-sphinx-spec'
-
-# Set up and run the atg-sphinx-spec configuration
+# Set up and run the psa-api-tool configuration
 
 import os
 
-atg_sphinx_spec_dir = os.environ.get('ATG_SPHINX_SPEC') or atg_sphinx_spec_dir
-exec(compile(open(os.path.join(atg_sphinx_spec_dir,'atg-sphinx-conf.py'),
+psa_api_tool_path = os.path.normpath(os.path.join(os.path.dirname(__file__), '..', '..', 'tools'))
+psa_api_tool_path = os.environ.get('PSA_API_TOOL') or psa_api_tool_path
+exec(compile(open(os.path.join(psa_api_tool_path,'psa-api-conf.py'),
                   encoding='utf-8').read(),
-             'atg-sphinx-conf.py', 'exec'))
+             'psa-api-conf.py', 'exec'))

doc/attestation/pyproject.toml

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright 2026 Arm Limited and/or its affiliates
+# SPDX-License-Identifier: Apache-2.0
+
+[tool.esbonio]

doc/crypto-driver/conf.py

@@ -84,14 +84,12 @@
     #'page_break': 'chapter'
     }
 
-# absolute or relative path to the psa_spec material from this file
-# atg_sphinx_spec_dir = '../atg-sphinx-spec'
-
-# Set up and run the atg-sphinx-spec configuration
+# Set up and run the psa-api-tool configuration
 
 import os
 
-atg_sphinx_spec_dir = os.environ.get('ATG_SPHINX_SPEC') or atg_sphinx_spec_dir
-exec(compile(open(os.path.join(atg_sphinx_spec_dir,'atg-sphinx-conf.py'),
+psa_api_tool_path = os.path.normpath(os.path.join(os.path.dirname(__file__), '..', '..', 'tools'))
+psa_api_tool_path = os.environ.get('PSA_API_TOOL') or psa_api_tool_path
+exec(compile(open(os.path.join(psa_api_tool_path,'psa-api-conf.py'),
                   encoding='utf-8').read(),
-             'atg-sphinx-conf.py', 'exec'))
+             'psa-api-conf.py', 'exec'))

doc/crypto-driver/pyproject.toml

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright 2026 Arm Limited and/or its affiliates
+# SPDX-License-Identifier: Apache-2.0
+
+[tool.esbonio]

doc/crypto/conf.py

@@ -99,14 +99,12 @@
     'prolog_files': ['/substitutions'],
     }
 
-# absolute or relative path to the psa_spec material from this file
-# atg_sphinx_spec_dir = '../atg-sphinx-spec'
-
-# Set up and run the atg-sphinx-spec configuration
+# Set up and run the psa-api-tool configuration
 
 import os
 
-atg_sphinx_spec_dir = os.environ.get('ATG_SPHINX_SPEC') or atg_sphinx_spec_dir
-exec(compile(open(os.path.join(atg_sphinx_spec_dir,'atg-sphinx-conf.py'),
+psa_api_tool_path = os.path.normpath(os.path.join(os.path.dirname(__file__), '..', '..', 'tools'))
+psa_api_tool_path = os.environ.get('PSA_API_TOOL') or psa_api_tool_path
+exec(compile(open(os.path.join(psa_api_tool_path,'psa-api-conf.py'),
                   encoding='utf-8').read(),
-             'atg-sphinx-conf.py', 'exec'))
+             'psa-api-conf.py', 'exec'))

doc/crypto/figure/multi_part_operation.puml

@@ -2,7 +2,7 @@
 ' SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 @startuml
-!include atg-spec.pumh
+!include psa-spec.pumh
 
 skinparam LegendFontSize 12
 

doc/crypto/figure/pake/j-pake.puml

@@ -3,7 +3,7 @@
 
 @startuml
 
-    !include atg-spec.pumh
+    !include psa-spec.pumh
 
     participant User
     participant Peer

doc/crypto/figure/pake/spake2plus-reg.puml

@@ -3,7 +3,7 @@
 
 @startuml
 
-    !include atg-spec.pumh
+    !include psa-spec.pumh
 
     participant "Prover  //(Client role)//" as Prover
     participant "Verifier  //(Server role)//" as Verifier

doc/crypto/figure/pake/spake2plus.puml

@@ -3,7 +3,7 @@
 
 @startuml
 
-    !include atg-spec.pumh
+    !include psa-spec.pumh
 
     participant "Prover //(Client role)//" as Prover
     participant "Verifier //(Server role)//" as Verifier

doc/crypto/figure/pake/wpa3-sae-pt.puml

@@ -3,7 +3,7 @@
 
 @startuml
 
-    !include atg-spec.pumh
+    !include psa-spec.pumh
 
     participant "station (STA)" as Participant
 

doc/crypto/figure/pake/wpa3-sae.puml

@@ -3,7 +3,7 @@
 
 @startuml
 
-    !include atg-spec.pumh
+    !include psa-spec.pumh
 
     participant "STA-A" as STAA
     participant "STA-B" as STAB

doc/crypto/figure/sra/dfd_caller_isolation.puml

@@ -2,8 +2,8 @@
 ' SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 @startuml
-!include atg-spec.pumh
-!include atg-dataflow.pumh
+!include psa-spec.pumh
+!include psa-dataflow.pumh
 
 dfd_agent "External system" as ext
 dfd_agent "External system" as ext2

doc/crypto/figure/sra/dfd_crypto_isolation.puml

@@ -2,8 +2,8 @@
 ' SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 @startuml
-!include atg-spec.pumh
-!include atg-dataflow.pumh
+!include psa-spec.pumh
+!include psa-dataflow.pumh
 
 dfd_agent "External system" as ext
 dfd_tb("System boundary") {

doc/crypto/figure/sra/dfd_no_isolation.puml

@@ -2,8 +2,8 @@
 ' SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 @startuml
-!include atg-spec.pumh
-!include atg-dataflow.pumh
+!include psa-spec.pumh
+!include psa-dataflow.pumh
 
 dfd_agent "External system" as ext
 dfd_tb("System boundary") {

doc/crypto/figure/sra/system-entities.puml

@@ -2,7 +2,7 @@
 ' SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 @startuml
-!include atg-spec.pumh
+!include psa-spec.pumh
 
 skinparam defaultTextAlignment center
 

doc/crypto/pyproject.toml

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright 2026 Arm Limited and/or its affiliates
+# SPDX-License-Identifier: Apache-2.0
+
+[tool.esbonio]

doc/fwu/conf.py

@@ -73,14 +73,12 @@
     'page_break': 'chapter',
     }
 
-# absolute or relative path to the psa_spec material from this file
-atg_sphinx_spec_dir = '../atg-sphinx-spec'
-
-# Set up and run the atg-sphinx-spec configuration
+# Set up and run the psa-api-tool configuration
 
 import os
 
-atg_sphinx_spec_dir = os.environ.get('ATG_SPHINX_SPEC') or atg_sphinx_spec_dir
-exec(compile(open(os.path.join(atg_sphinx_spec_dir,'atg-sphinx-conf.py'),
+psa_api_tool_path = os.path.normpath(os.path.join(os.path.dirname(__file__), '..', '..', 'tools'))
+psa_api_tool_path = os.environ.get('PSA_API_TOOL') or psa_api_tool_path
+exec(compile(open(os.path.join(psa_api_tool_path,'psa-api-conf.py'),
                   encoding='utf-8').read(),
-             'atg-sphinx-conf.py', 'exec'))
+             'psa-api-conf.py', 'exec'))

doc/fwu/figure/arch/components.puml

@@ -3,31 +3,31 @@
 
 @startuml
 
-!include atg-spec.pumh
-!include atg-dataflow.pumh
+!include psa-spec.pumh
+!include psa-dataflow.pumh
 
 skinparam RectangleborderThickness 0
 skinparam RectanglefontColor white
-skinparam DatabaseBorderColor #ArmMidGray
-skinparam InterfaceBorderColor #ArmMidGray
+skinparam DatabaseBorderColor #PSAMidGray
+skinparam InterfaceBorderColor #PSAMidGray
 
-rectangle "Firmware creator" as creator #ArmDarkBlue
+rectangle "Firmware creator" as creator #PSADarkBlue
 cloud Internet {
-    rectangle "Update server" as server #ArmMidGray
+    rectangle "Update server" as server #PSAMidGray
 }
-interface "MQTT\n CoAP\nHTTPS\n    ..." as tls #ArmLightGray
+interface "MQTT\n CoAP\nHTTPS\n    ..." as tls #PSALightGray
 
 dfd_tb("Device ") {
-    rectangle "Update client" as client #ArmMidGray
-    interface "  **Firmware**\n**Update API**" as api  #ArmGreen
-    rectangle "Update service" as service #ArmMidBlue
-    database "Firmware store" as store #ArmLightGray
-    rectangle "Bootloader" as bootloader #ArmMidBlue
+    rectangle "Update client" as client #PSAMidGray
+    interface "  **Firmware**\n**Update API**" as api  #PSAGreen
+    rectangle "Update service" as service #PSAMidBlue
+    database "Firmware store" as store #PSALightGray
+    rectangle "Bootloader" as bootloader #PSAMidBlue
     label "<size:30>   <&key>\nTrust anchor" as anchor
 }
 
-database "External storage" as drive #ArmLightGray
-interface "USB" as usb #ArmLightGray
+database "External storage" as drive #PSALightGray
+interface "USB" as usb #PSALightGray
 
 creator -> server
 server <- tls

doc/fwu/figure/arch/trusted-client.puml

@@ -3,23 +3,23 @@
 
 @startuml
 
-!include atg-spec.pumh
-!include atg-dataflow.pumh
+!include psa-spec.pumh
+!include psa-dataflow.pumh
 
 skinparam RectangleborderThickness 0
 skinparam RectanglefontColor white
 skinparam FilefontColor white
-skinparam DatabaseBorderColor #ArmMidGray
-skinparam InterfaceBorderColor #ArmMidGray
+skinparam DatabaseBorderColor #PSAMidGray
+skinparam InterfaceBorderColor #PSAMidGray
 
-file "Firmware package" <<data>> as firmware #ArmDarkBlue
+file "Firmware package" <<data>> as firmware #PSADarkBlue
 
 dfd_tb($label = "Device") {
-    rectangle "Update client" <<app>> as client #ArmMidGray
-    interface "  **Firmware**\n**Update API**" as api  #ArmGreen
-    rectangle "Update service" <<library>> as service #ArmMidBlue
-    database "Firmware store" as store #ArmLightGray
-    rectangle "Bootloader" as bootloader #ArmMidBlue
+    rectangle "Update client" <<app>> as client #PSAMidGray
+    interface "  **Firmware**\n**Update API**" as api  #PSAGreen
+    rectangle "Update service" <<library>> as service #PSAMidBlue
+    database "Firmware store" as store #PSALightGray
+    rectangle "Bootloader" as bootloader #PSAMidBlue
     label "<size:30>   <&key>\nTrust anchor" as anchor
 }