Driver dispatch Codegen 1.1

ChangeLog

@@ -122,6 +122,11 @@ Features
      and hmac_demo.c, which use PSA and the md/cipher interfaces side
      by side in order to illustrate how the operation is performed in PSA.
      Addresses #5208.
+   * Brought in PSA code gen driver list JSON,
+     auto generated templating support for key management, 
+     transparent and opaque keys ( import/export/copy ), iincluded some 
+     general JSON validation, and more specifically for the given entry points.
+     Addresses ver 1.1 of #5137
 
 Security
    * Zeroize dynamically-allocated buffers used by the PSA Crypto key storage

docs/proposed/psa-driver-developer-guide.md

@@ -36,6 +36,12 @@ A driver therefore consists of:
 
 Mbed TLS calls driver entry points [as specified in the PSA Cryptography Driver Interface specification](psa-driver-interface.html#driver-entry-points) except as otherwise indicated in this section.
 
+## Mbed TLS extensions
+
+The driver description can include Mbed TLS extensions (marked by the namespace "mbedtls"). Mbed TLS extensions are meant to extend/help integrating the driver into the library's infrastructure.
+* `"mbedtls/h_condition"` (optional, string) can include complex preprocessor definitions to conditionally include header files for a given driver. 
+* `"mbedtls/c_condition"` (optional, string) can include complex preprocessor definitions to conditionally enable dispatch capabilities for a driver.
+
 ## Building and testing your driver
 
 <!-- TODO -->

docs/proposed/psa-driver-wrappers-codegen-migration-guide.md

@@ -13,20 +13,28 @@ During the process of implementation there might be minor variations wrt version
 
 ## Prerequisites
 
-Python3 and Jinja2 rev 2.10.1
+Python3, Jinja2 rev 2.10.1 and jsonschema rev 3.2.0
 
 ## Feature Version
 
-1.0
+1.1
 
 ### What's critical for a migrating user
 
 The Driver Wrapper auto generation project is designed to use a python templating library ( Jinja2 ) to render templates based on drivers that are defined using a Driver description JSON file(s).
 
-While that is the larger goal, for version 1.0 here's what's changed
+While that is the larger goal, for version 1.1 here's what's changed
 
 #### What's changed
 
 (1) psa_crypto_driver_wrappers.c will from this point on be auto generated.
-(2) The auto generation is based on the template file at scripts/data_files/driver_templates/psa_crypto_driver_wrappers.c.jinja.
-(3) So while all driver wrapper templating support is yet to come in, the library user will need to patch into the template file as needed, this could be read as replacing the template file with the current psa_crypto_driver_wrappers.c file maintained by the library user.
+(2) The auto generation is based on the template file at **scripts/data_files/driver_templates/psa_crypto_driver_wrappers.c.jinja**.
+(3) The driver JSONS to be used for generating the psa_crypto_driver_wrappers.c file can be found at **scripts/data_files/driver_jsons/** as their default location, this path includes the schemas against which the driver schemas will be validated (driver_opaque_schema.json, driver_transparent_schema.json) and a driverlist.json which specifies the drivers to be considered and the order in which they want to be called into. The default location for driverlist.json and driver JSONS can be overloaded by passing an argument --json-dir while running the script generate_driver_wrappers.py.
+(4) While the complete driver wrapper templating support is yet to come in, if the library user sees a need to patch psa_crypto_driver_wrappers.c file, the user will need to patch into the template file as needed (psa_crypto_driver_wrappers.c.jinja).
+
+#### How to set your driver up
+
+Please refer to psa-driver-interface.md for information on how a driver schema can be written.
+One can also refer to the example test drivers/ JSON schemas under **scripts/data_files/driver_jsons/**.
+
+The JSON file 'driverlist.json' is meant to be edited by the user to reflect the drivers one wants to use on a device. The order in which the drivers are passed is also essential if/when there are multiple transparent drivers on a given system to retain the same order in the templating.

scripts/data_files/driver_jsons/driver_opaque_schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "_comment": {
+      "type": "string"
+    },
+    "prefix": {
+      "type": "string",
+      "pattern": "^[A-Z_a-z][0-9A-Z_a-z]*$"
+    },
+    "type": {
+      "type": "string",
+      "const": ["opaque"]
+    },
+    "location": {
+      "type": ["integer","string"],
+      "pattern": "^(0x|0X)?[a-fA-F0-9]+$"
+    },
+    "mbedtls/h_condition": {
+      "type": "string"
+    },
+    "headers": {
+      "type": "array",
+      "items": {
+          "type": "string"
+        },
+        "default": []
+    },
+    "capabilities": {
+      "type": "array",
+      "items": [
+        {
+          "type": "object",
+          "properties": {
+            "_comment": {
+              "type": "string"
+            },
+            "mbedtls/c_condition": {
+              "type": "string"
+            },
+            "entry_points": {
+              "type": "array",
+              "items": {
+                  "type": "string"
+                }
+            },
+            "names": {
+              "type": "object",
+              "patternProperties": {
+                "^[A-Z_a-z][0-9A-Z_a-z]*$": {
+                  "type": "string",
+                  "pattern": "^[A-Z_a-z][0-9A-Z_a-z]*$"
+                }
+              }
+            }
+          },
+          "required": [
+            "entry_points"
+          ]
+        }
+      ]
+    }
+  },
+  "required": [
+    "prefix",
+    "type",
+    "location",
+    "capabilities"
+  ]
+}

scripts/data_files/driver_jsons/driver_transparent_schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "type": "object",
+  "properties": {
+    "_comment": {
+      "type": "string"
+    },
+    "prefix": {
+      "type": "string",
+      "pattern": "^[A-Z_a-z][0-9A-Z_a-z]*$"
+    },
+    "type": {
+      "type": "string",
+      "const": ["transparent"]
+    },
+    "mbedtls/h_condition": {
+      "type": "string"
+    },
+    "headers": {
+      "type": "array",
+      "items": {
+          "type": "string"
+        },
+        "default": []
+    },
+    "capabilities": {
+      "type": "array",
+      "items": [
+        {
+          "type": "object",
+          "properties": {
+            "_comment": {
+              "type": "string"
+            },
+            "mbedtls/c_condition": {
+              "type": "string"
+            },
+            "entry_points": {
+              "type": "array",
+              "items": {
+                  "type": "string"
+                }
+            },
+            "names": {
+              "type": "object",
+              "patternProperties": {
+                "^[A-Z_a-z][0-9A-Z_a-z]*$": {
+                  "type": "string",
+                  "pattern": "^[A-Z_a-z][0-9A-Z_a-z]*$"
+                }
+              }
+            },
+            "fallback": {
+              "type": "boolean",
+              "default": "false"
+            }
+          },
+          "required": [
+            "entry_points"
+          ]
+        }
+      ]
+    }
+  },
+  "required": [
+    "prefix",
+    "type",
+    "capabilities"
+  ]
+}

scripts/data_files/driver_jsons/driverlist.json

@@ -0,0 +1 @@
+["mbedtls_test_opaque_driver.json","mbedtls_test_transparent_driver.json"]

scripts/data_files/driver_jsons/mbedtls_test_opaque_driver.json

@@ -0,0 +1,20 @@
+{
+    "prefix":       "mbedtls_test",
+    "type":         "opaque",
+    "location":     "0x7fffff",
+    "mbedtls/h_condition":   "defined(PSA_CRYPTO_DRIVER_TEST)",
+    "headers":      ["test/drivers/test_driver.h"],
+    "capabilities": [
+        {
+            "_comment":     "The Mbed TLS opaque driver supports import key/export key/export_public key",
+            "mbedtls/c_condition":    "defined(PSA_CRYPTO_DRIVER_TEST)",
+            "entry_points": ["import_key", "export_key", "export_public_key"]
+        },
+        {
+            "_comment":     "The Mbed TLS opaque driver supports copy key/ get builtin key",
+            "mbedtls/c_condition":    "defined(PSA_CRYPTO_DRIVER_TEST)",
+            "entry_points": ["copy_key", "get_builtin_key"],
+            "names":         {"copy_key":"mbedtls_test_opaque_copy_key", "get_builtin_key":"mbedtls_test_opaque_get_builtin_key"}
+        }
+     ]
+}

scripts/data_files/driver_jsons/mbedtls_test_transparent_driver.json

@@ -0,0 +1,22 @@
+{
+    "prefix":       "mbedtls_test",
+    "type":         "transparent",
+    "mbedtls/h_condition":   "defined(PSA_CRYPTO_DRIVER_TEST)",
+    "headers":      ["test/drivers/test_driver.h"],
+    "capabilities": [
+        {
+            "_comment":     "The Mbed TLS transparent driver supports import key/export key",
+            "mbedtls/c_condition":    "defined(PSA_CRYPTO_DRIVER_TEST)",
+            "entry_points": ["import_key", "export_key"],
+            "fallback":     true
+        },
+        {
+            "_comment":     "The Mbed TLS transparent driver supports export_public key",
+            "mbedtls/c_condition":    "defined(PSA_CRYPTO_DRIVER_TEST)",
+            "entry_points": ["export_public_key"],
+            "fallback":     true,
+            "names":         {"export_public_key":"mbedtls_test_transparent_export_public_key"}
+        }
+
+    ]
+}

scripts/data_files/driver_templates/OS-template-opaque.jinja

@@ -0,0 +1,17 @@
+{# One Shot function's dispatch code for opaque drivers.
+Expected inputs:
+* drivers: the list of driver descriptions.
+* entry_point: the name of the entry point that this function dispatches to.
+* entry_point_param(driver): the parameters to pass to the entry point.
+* nest_indent: number of extra spaces to indent the code to.
+-#}
+{% for driver in drivers if driver.type == "opaque" -%}
+{% for capability in driver.capabilities if entry_point in capability.entry_points -%}
+#if ({% if capability['mbedtls/c_condition'] is defined -%}{{ capability['mbedtls/c_condition'] }} {% else -%} {{ 1 }} {% endif %})
+{%- filter indent(width = nest_indent) %}
+case {{ driver.location }}:
+    return( {{ entry_point_name(capability, entry_point, driver) }}({{entry_point_param(driver) | indent(20)}}));
+{% endfilter -%}
+#endif
+{% endfor %}
+{% endfor %}

scripts/data_files/driver_templates/OS-template-transparent.jinja

@@ -0,0 +1,19 @@
+{# One Shot function's dispatch code for transparent drivers.
+Expected inputs:
+* drivers: the list of driver descriptions.
+* entry_point: the name of the entry point that this function dispatches to.
+* entry_point_param(driver): the parameters to pass to the entry point.
+* nest_indent: number of extra spaces to indent the code to.
+-#}
+{% for driver in drivers if driver.type == "transparent" -%}
+{% for capability in driver.capabilities if entry_point in capability.entry_points -%}
+#if ({% if capability['mbedtls/c_condition'] is defined -%}{{ capability['mbedtls/c_condition'] }} {% else -%} {{ 1 }} {% endif %})
+{%- filter indent(width = nest_indent) %}
+status = {{ entry_point_name(capability, entry_point, driver) }}({{entry_point_param(driver) | indent(20)}});
+
+if( status != PSA_ERROR_NOT_SUPPORTED )
+    return( status );
+{% endfilter -%}
+#endif
+{% endfor %}
+{% endfor %}