build(cmake): add platform metadata support

This commit introduces the schema for a new "platform metadata file"
(`platform.json`). This file is expected to exist for each platform
within its source directory, and contains structured information
relevant to the platform.

For now, the platform metadata file only contains the name of the
platform's build system target. For example, the platform *MyPlatform*
might use:

```json
{
  "target": "my-platform"
}
```

This target name follows the following regular expression:

```
^(?![0-9])([a-z0-9]+-?)+(?<!-)$
```

Or, in English, it must begin with any ASCII alphabetical lower-case
character, optionally followed by any number of ASCII alphabetical
lower-case characters or numbers (which may be separated by a hyphen),
and may not end with a hyphen.

Change-Id: I5b4ee7cc1f6ad9b64e4e6948216d3736635640bf
Signed-off-by: Chris Kay <chris.kay@arm.com>

4 files changed, 89 insertions, 0 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index b41f9e9f0..b6dcead4e 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -71,6 +71,21 @@ arm_assert(
             "${TFA_PLATFORM_SOURCE_DIR}")
 
 #
+# Because the platform's source directory might have come from outside, CMake
+# may be unable to derive the platform's binary directory automatically. As an
+# alternative, we'll use the platform's target name as its binary directory.
+#
+
+tfa_platform_target(target
+    PLATFORM "${TFA_PLATFORM}")
+
+arm_config_option(
+    NAME TFA_PLATFORM_BINARY_DIR HIDDEN
+    HELP "Platform binary directory."
+    DEFAULT "${CMAKE_CURRENT_BINARY_DIR}/${target}"
+    TYPE PATH)
+
+#
 # We're done with very early setup, so we can now create the project. This will
 # do some of the automatic compiler detection, which we need for setting up
 # further configuration options.
diff --git a/cmake/Modules/TFAMetadata.cmake b/cmake/Modules/TFAMetadata.cmake
index 9019eaa5f..fccb67d97 100644
--- a/cmake/Modules/TFAMetadata.cmake
+++ b/cmake/Modules/TFAMetadata.cmake
@@ -25,6 +25,14 @@ Return the list of supported platforms in ``<out-var>``.
     tfa_platform_path(<out-var> PLATFORM <platform>)
 
 Return the path to the platform ``<platform>`` in ``<out-var>``.
+
+.. command:: tfa_platform_target
+
+.. code-block:: cmake
+
+    tfa_platform_target(<out-var> PLATFORM <platform>)
+
+Return the CMake target name for the platform ``<platform>`` in ``<out-var>``.
 #]=======================================================================]
 
 include_guard()
@@ -140,3 +148,44 @@ tfa_json_getter(tfa_platforms
 tfa_json_getter(tfa_platform_path
     JSON "${global-metadata}" PARENT tfa_metadata_platforms_platform
     DECODE STRING)
+
+#
+# Internal platform metadata API.
+#
+
+macro(tfa_platform_metadata_preprocess)
+    #
+    # Because we are using `tfa_platform_path` as our parent, `ARG_JSON` already
+    # contains the decoded platform path.
+    #
+
+    arm_assert(
+        CONDITION EXISTS "${ARG_JSON}/platform.json"
+        MESSAGE "The platform metadata file for the ${ARG_PLATFORM} platform "
+                "could not be found:\n"
+
+                "${ARG_JSON}/platform.json")
+
+    #
+    # Replace `ARG_JSON` with the contents of the platform metadata file.
+    #
+
+    file(READ "${ARG_JSON}/platform.json" ARG_JSON)
+    arm_expand(OUTPUT ARG_JSON STRING "${ARG_JSON}")
+endmacro()
+
+tfa_json_getter(tfa_platform_metadata
+    JSON "${global-metadata}" PARENT tfa_platform_path
+    PREPROCESS tfa_platform_metadata_preprocess)
+
+tfa_json_getter(tfa_platform_metadata_target
+    JSON "${global-metadata}" PARENT tfa_platform_metadata
+    PATH "target")
+
+#
+# External platform metadata API.
+#
+
+tfa_json_getter(tfa_platform_target
+    JSON "${global-metadata}" PARENT tfa_platform_metadata_target
+    DECODE STRING)
diff --git a/docs/cmake/manual/variable/common/TFA_PLATFORM_BINARY_DIR.rst b/docs/cmake/manual/variable/common/TFA_PLATFORM_BINARY_DIR.rst
new file mode 100644
index 000000000..96a3bad20
--- /dev/null
+++ b/docs/cmake/manual/variable/common/TFA_PLATFORM_BINARY_DIR.rst
@@ -0,0 +1,13 @@
+TFA_PLATFORM_BINARY_DIR
+=======================
+
+.. default-domain:: cmake
+
+.. variable:: TFA_PLATFORM_BINARY_DIR
+
+Path to the platform binary directory. This is automatically derived from the
+platform name, and should not be set manually.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
diff --git a/schemas/platform.schema.json b/schemas/platform.schema.json
new file mode 100644
index 000000000..550450f7c
--- /dev/null
+++ b/schemas/platform.schema.json
@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "type": "object",
+  "required": ["target"],
+  "additionalProperties": false,
+  "properties": {
+    "target": {
+      "type": "string",
+      "pattern": "^(?![0-9])([a-z0-9]+-?)+(?<!-)$"
+    }
+  }
+}