Update service deployment documentation
Updates the old portability model page to better describe how
service provider deployments for different environments and
platforms are organised. Introduces a more flexible directory
structure that improves reuse and extensibility for service
provider deployments.
Signed-off-by: Julian Hall <julian.hall@arm.com>
Change-Id: I5635c38210cbb55d993150e8efe9e84b95acdf49
diff --git a/docs/deployments/index.rst b/docs/deployments/index.rst
index 40a6949..bc98e61 100644
--- a/docs/deployments/index.rst
+++ b/docs/deployments/index.rst
@@ -17,10 +17,10 @@
libraries
tools-demo-apps
-Related deployments:
+Related documentsments:
- :ref:`Project Structure`
- - :ref:`Portability Model`
+ - :ref:`Service Deployment Model`
- :ref:`Build Instructions`
- :ref:`Running Tests`
diff --git a/docs/developer/arch-overview.rst b/docs/developer/arch-overview.rst
index d2f8c4d..c1f985a 100644
--- a/docs/developer/arch-overview.rst
+++ b/docs/developer/arch-overview.rst
@@ -9,7 +9,7 @@
featured trusted OSs, such as OP-TEE, to bare metal secure partitions.
For a more in-depth description of how the ports and adapters pattern is applied, see:
-:ref:`Portability Model`
+:ref:`Service Deployment Model`
Service Model
-------------
@@ -74,6 +74,6 @@
--------------
-*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/image/TSportabilityModel.svg b/docs/developer/image/TSportabilityModel.svg
index e0635c5..d8fcbb6 100644
--- a/docs/developer/image/TSportabilityModel.svg
+++ b/docs/developer/image/TSportabilityModel.svg
@@ -1,3 +1,4 @@
<?xml version="1.0" encoding="UTF-8"?>
+<!-- Do not edit this file with editors other than diagrams.net -->
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
-<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="471px" height="371px" viewBox="-0.5 -0.5 471 371" content="<mxfile host="confluence.arm.com" modified="2021-01-21T15:49:55.792Z" agent="Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:84.0) Gecko/20100101 Firefox/84.0" etag="T4OmEHaxOAbJXEuewn-x" version="12.7.1.1" type="atlas"><mxAtlasLibraries/><diagram id="Fh55IqWZiI4TxFe46PeK" name="Page-1">7Zpbc5s4FIB/jWe2D+4YZMf2Y25tZrbddSftNN2XjAwyaAuICvlCf/1KRsIg4ZikxgRv8xLpoAv6zjnSOTI9cB1u3lMY+x+Ji4KePXA3PXDTs21rZA35PyFJpQRYk0ziUexK2U5wj38iKRxI6RK7KCk1ZIQEDMdloUOiCDmsJIOUknW52YIE5Vlj6MkZBzvBvQMDZDT7il3mZ9LJqND6DmHPVzNbA/kkhKqxFCQ+dMm6IAK3PXBNCWFZKdxco0DQU1yyfu/2PM1fjKKI1elAfvzzJ/2azsm3VTL8Mr999B/Tvp2NsoLBUi74M10mDLlceI/oCjuIl2aUrLgaaM++CPhcV3NR8kTpDxjHAXYgwyR6I9fJUgWPLzkWRR9toEci3j5GFIeI8aFy6UyJOJGrtY8Zuo+hI7qtuU1xmc/CgNcsXnQx5UrGYqibhCwF4SuTg0SzQpShTUEkubxHhM9HU95EPgVSRdJIh7K63incmkiZX1B2bqRQGpmXj7zTAy9IVTxDLSNDLe2wXeAguCYBEUNGJELHwd0flnn3wcgADuwK4GDcFPALA/httMKURKFYps6er5OV4SWMku9IQ1VBDwbYE4AdPqxQ1JWgxv0nuJQPQuy6YppKbVGyjFwk1jE4jiby3Upqwh6bpj+ssvym9DA29ABdGAtUug7KLA7YdjN2nGNINZoFeqNT0pt0ml7FtntSetNO05u0TE+dhd3A1wevzHUtq9P42vZdywxku4SvdecFBr5ZANmC0NDgdzbBj32hhaF2y8GPSpafCvv5MDz13ceoecu1NNOdmqF7leWCxpjVSJVQ5F6KqwBhegFMEuyUUaENZg+F8jdhY29HsnazkSa3raSqEvG3fyhWCr1EdddtW1P99uqAp1zUQTWsg0HqIVbjJEauutrYo9MDOlMyivhWgFflC5EqRcoZZgSLnGmvyQwHmjFkS5fdijcY+kiT8kBgpA2UoTEG2hpWvu5fsDUzSzze6dKzwWL7d6TNTY9vTD+tyrAbu9GwzNykM+yGbbMzM5POsJu0zE5N1g12rw2emZR0B17bXqtYdRJe28eFbSYkBrwDuGASZz8ILfBGIG6SH88/NYBVV9qnjIvtOrnEWcTFylQOx8VyxN9x8ZHjYrtODvaSvPXYu5wGPN++DjhpYwm/XSOhaNRJrVM56bSmjypTOjsfHWo+ahjVHh/luodpoVksGiT73xhY2kE0HTz5Xnp77SsCXsje4Lgbhvkzn2H31CfhfJm0umH0tVPdrgiLTnuq18gE1YcBThrgyN3esx4gOM+i0A/zXACd7942Nv17yfgoqHnUQEM9td/WC0FVoHV01qBG/H4eEdS47uY8PdPNue0ACtTIds7DrS3Qvl//bzKjSU2/Vub3269f7tfj9Mt0Pftr/u8D++xfkk8f7+5oxdeVL7a0wTMs7eUWowKzV2sJ+oVTbUvQf3GfNhN+6xZnfJR7oL0Wrj83/ObV3QfFWfPdd9ng9j8=</diagram></mxfile>"><defs/><g><path d="M 197.5 90 L 302.5 90 L 355 180 L 302.5 270 L 197.5 270 L 145 180 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" transform="rotate(90,250,180)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 178px; height: 1px; padding-top: 180px; margin-left: 161px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Trusted Service Provider<br />(application)</div></div></div></foreignObject><text x="250" y="184" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Trusted Service Provider...</text></switch></g><path d="M 157.5 25 L 342.5 25 L 435 185 L 342.5 345 L 157.5 345 L 65 185 Z" fill="none" stroke="#000000" stroke-miterlimit="10" transform="rotate(90,250,185)" pointer-events="all"/><rect x="230" y="305" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 315px; margin-left: 231px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Environment</div></div></div></foreignObject><text x="250" y="319" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Enviro...</text></switch></g><rect x="350" y="135" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 145px; margin-left: 351px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="375" y="149" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="350" y="175" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 185px; margin-left: 351px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="375" y="189" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="350" y="215" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 225px; margin-left: 351px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="375" y="229" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="100" y="135" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 145px; margin-left: 101px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="125" y="149" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="100" y="175" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 185px; margin-left: 101px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="125" y="189" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="100" y="215" width="50" height="20" fill="none" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 225px; margin-left: 101px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">adapter</div></div></div></foreignObject><text x="125" y="229" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="390" y="15" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 25px; margin-left: 391px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Platform</div></div></div></foreignObject><text x="410" y="29" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">Platfo...</text></switch></g><ellipse cx="25" cy="145" rx="25" ry="15" fill="transparent" stroke="#000000" pointer-events="all"/><path d="M 50 145 L 93.63 145" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 98.88 145 L 91.88 148.5 L 93.63 145 L 91.88 141.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="150" y="140" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="150" y="180" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="150" y="220" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="330" y="220" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="330" y="180" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="330" y="140" width="20" height="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="10" y="170" width="30" height="30" fill="#ffffff" stroke="#000000" pointer-events="all"/><path d="M 40 185 L 93.63 185" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 98.88 185 L 91.88 188.5 L 93.63 185 L 91.88 181.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><ellipse cx="375" cy="255" rx="15" ry="10" fill="#ffffff" stroke="#000000" pointer-events="all"/><path d="M 400 225 L 430 225 Q 440 225 440 235 L 440 245 Q 440 255 430 255 L 396.37 255" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 391.12 255 L 398.12 251.5 L 396.37 255 L 398.12 258.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 125 240 L 140 255 L 125 270 L 110 255 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 134.5 C 450 125.17 470 125.17 470 134.5 L 470 155.5 C 470 164.83 450 164.83 450 155.5 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 134.5 C 450 141.5 470 141.5 470 134.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 400 145 L 443.63 145" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 448.88 145 L 441.88 148.5 L 443.63 145 L 441.88 141.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 174.5 C 450 165.17 470 165.17 470 174.5 L 470 195.5 C 470 204.83 450 204.83 450 195.5 Z" fill="#ffffff" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 174.5 C 450 181.5 470 181.5 470 174.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 400 185 L 443.63 185" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 448.88 185 L 441.88 188.5 L 443.63 185 L 441.88 181.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 110 255 L 60 255 Q 50 255 50 245 L 50 235 Q 50 225 60 225 L 93.63 225" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 98.88 225 L 91.88 228.5 L 93.63 225 L 91.88 221.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://desk.draw.io/support/solutions/articles/16000042487" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Viewer does not support full SVG 1.1</text></a></switch></svg>
\ No newline at end of file
+<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="471px" height="371px" viewBox="-0.5 -0.5 471 371" content="<mxfile host="confluence.arm.com" modified="2022-09-02T12:38:49.699Z" agent="5.0 (X11)" etag="gZJ4USVuZGaly2bdFk2b" version="20.1.4" type="atlas"><mxAtlasLibraries/><diagram id="Fh55IqWZiI4TxFe46PeK" name="Page-1">7Zpbk5s2FIB/jWfaB2cMwmv7cW/Ndtq07mwy2fQlI4MMagBRIV/Ir69kJAwSjtmNMYubfVnpoAv6zjnSOTIDcBtt31KYBO+Ih8KBPfK2A3A3sG1rDAD/JySZlNjAySU+xZ6U7QWP+CuSwpGUrrCH0kpDRkjIcFIVuiSOkcsqMkgp2VSbLUlYnTWBvpxxtBc8ujBERrOP2GNBLp2OS60fEPYDNbM1kk8iqBpLQRpAj2xKInA/ALeUEJaXou0tCgU9xSXv98uBp8WLURSzJh3Iv3//Rj9mC/JpnTofFvefg8/Z0M5HWcNwJRf8nq5ShjwufER0jV3ES3NK1lwNdGBfhXyum4Uo+aL0E0ySELuQYRL/LNfJMgWPLzkRxQBtoU9i3j5BFEeI8aEK6VyJOJGbTYAZekygK7ptuE1xWcCikNcsXvQw5UrGYqi7lKwE4RuTg0SzRpShbUkkubxFhM9HM95EPgVSRdJIHVnd7BVuTaUsKCm7MFIojcwvRt7rgRekKp6hlrGhlm7YLnEY3pKQiCFjEqPT4B46Vd5DMDaAA7sGOJi0BfzKAP5rvKQwZXTlshVFBn6+VFblx9uSL0ijVQMQhtgXjF0OUOjqRoDjLhReywcR9jwxTa3CKFnFHhJLGZ1GGcWGJZVhT0zrd+qMvy1VTAxVQA8mApWugyqLI+bdjikXGDKNZone+Jz0pr2mV7PznpXerNf0ph3TU8dhP/ANwStzXcvqNb6ufdcyY9k+4evceYGBbx5CtiQ04uPdx2tMSRyJBV9sKGRfaXGp3XEoZDmGTgz6fBieCx9i1L4dW5ohz8xYvs6OQWvMGuROKPauxd2AML0Qpil2q6jQFrOnUvmTsLE3Y1m720qT21UyVYn52z+VK6Veorrvtqupfgd1wHMw6qIG1sEg9RFrcC4jT911HNDpEZ0pGUV8Y8Dr6g1JnSLlDHOCxbZx0GSckWYM+dJlt/KVhj7StDoQGGsD5WiMgXaGVaz7O2zNTBtPd9YMbLDc/Z1oc9OjHdNP61Lu1q44LDNT6Q07p2t2Zp7SG3bTjtmpyfrB7rXBM1OU/sDr2msVq17C6/q4sM30xIB3BBdMk/wXoiXeCsRt8uPZqAaw7o77nHGx3SSXuIi4WJnK8bhYjvgjLj5xXGw3ycFekreeepfTgBfb1xEnbS3htxskFK06qXUuJ5019FFlShfno47mo4ZRHfBRrnuYlZolokF6+I2BpR1Es9E330tvr31WwAv5G5x2wzB/9DPsngYkWqzSTjeMoXaq2zVh0XlP9QaZoPpSwM1CHHu7e9YjBBd5FPr7ohBA94u/i03/XDE+CmofNdBQz+w3zUJQFWidnDVoEL9fRgQ1abo5zy50c+46gAINsp3LcGsLdO/X/5vMaNrQr5X5/fDrl/v1JPsw28z/WPzzxN4H1+Svdw8PtOZzyxdb2ugZlvZyi1GB2au1BP3CqbEl6L+/z9oJv3WLM77SPdJeC9efG37z6v4L47z5/kNtcP8f</diagram></mxfile>"><defs/><g><path d="M 197.5 90 L 302.5 90 L 355 180 L 302.5 270 L 197.5 270 L 145 180 Z" fill="rgb(255, 255, 255)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" transform="rotate(90,250,180)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 178px; height: 1px; padding-top: 180px; margin-left: 161px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Trusted Service Provider<br />(application)</div></div></div></foreignObject><text x="250" y="184" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Trusted Service Provider...</text></switch></g><path d="M 157.5 25 L 342.5 25 L 435 185 L 342.5 345 L 157.5 345 L 65 185 Z" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" transform="rotate(90,250,185)" pointer-events="all"/><rect x="230" y="305" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 315px; margin-left: 231px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Infrastructure</div></div></div></foreignObject><text x="250" y="319" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Infras...</text></switch></g><rect x="350" y="135" width="50" height="20" fill="none" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 145px; margin-left: 351px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">adapter</div></div></div></foreignObject><text x="375" y="149" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="350" y="175" width="50" height="20" fill="none" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 185px; margin-left: 351px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">adapter</div></div></div></foreignObject><text x="375" y="189" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="350" y="215" width="50" height="20" fill="none" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 225px; margin-left: 351px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">adapter</div></div></div></foreignObject><text x="375" y="229" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="100" y="135" width="50" height="20" fill="none" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 145px; margin-left: 101px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">adapter</div></div></div></foreignObject><text x="125" y="149" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="100" y="175" width="50" height="20" fill="none" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 185px; margin-left: 101px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">adapter</div></div></div></foreignObject><text x="125" y="189" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="100" y="215" width="50" height="20" fill="none" stroke="rgb(0, 0, 0)" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 48px; height: 1px; padding-top: 225px; margin-left: 101px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">adapter</div></div></div></foreignObject><text x="125" y="229" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">adapter</text></switch></g><rect x="390" y="15" width="40" height="20" fill="none" stroke="none" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 38px; height: 1px; padding-top: 25px; margin-left: 391px;"><div style="box-sizing: border-box; font-size: 0px; text-align: center;" data-drawio-colors="color: rgb(0, 0, 0); "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: rgb(0, 0, 0); line-height: 1.2; pointer-events: all; white-space: normal; overflow-wrap: normal;">Platform/Environment</div></div></div></foreignObject><text x="410" y="29" fill="rgb(0, 0, 0)" font-family="Helvetica" font-size="12px" text-anchor="middle">Platfo...</text></switch></g><ellipse cx="25" cy="145" rx="25" ry="15" fill="transparent" stroke="rgb(0, 0, 0)" pointer-events="all"/><path d="M 50 145 L 93.63 145" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 98.88 145 L 91.88 148.5 L 93.63 145 L 91.88 141.5 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><rect x="150" y="140" width="20" height="10" fill="#ffffff" stroke="rgb(0, 0, 0)" pointer-events="all"/><rect x="150" y="180" width="20" height="10" fill="#ffffff" stroke="rgb(0, 0, 0)" pointer-events="all"/><rect x="150" y="220" width="20" height="10" fill="#ffffff" stroke="rgb(0, 0, 0)" pointer-events="all"/><rect x="330" y="220" width="20" height="10" fill="#ffffff" stroke="rgb(0, 0, 0)" pointer-events="all"/><rect x="330" y="180" width="20" height="10" fill="#ffffff" stroke="rgb(0, 0, 0)" pointer-events="all"/><rect x="330" y="140" width="20" height="10" fill="#ffffff" stroke="rgb(0, 0, 0)" pointer-events="all"/><rect x="10" y="170" width="30" height="30" fill="#ffffff" stroke="rgb(0, 0, 0)" pointer-events="all"/><path d="M 40 185 L 93.63 185" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 98.88 185 L 91.88 188.5 L 93.63 185 L 91.88 181.5 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><ellipse cx="375" cy="255" rx="15" ry="10" fill="#ffffff" stroke="rgb(0, 0, 0)" pointer-events="all"/><path d="M 400 225 L 430 225 Q 440 225 440 235 L 440 245 Q 440 255 430 255 L 396.37 255" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 391.12 255 L 398.12 251.5 L 396.37 255 L 398.12 258.5 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 125 240 L 140 255 L 125 270 L 110 255 Z" fill="#ffffff" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 134.5 C 450 125.17 470 125.17 470 134.5 L 470 155.5 C 470 164.83 450 164.83 450 155.5 Z" fill="#ffffff" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 134.5 C 450 141.5 470 141.5 470 134.5" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 400 145 L 443.63 145" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 448.88 145 L 441.88 148.5 L 443.63 145 L 441.88 141.5 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 174.5 C 450 165.17 470 165.17 470 174.5 L 470 195.5 C 470 204.83 450 204.83 450 195.5 Z" fill="#ffffff" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 450 174.5 C 450 181.5 470 181.5 470 174.5" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 400 185 L 443.63 185" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 448.88 185 L 441.88 188.5 L 443.63 185 L 441.88 181.5 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/><path d="M 110 255 L 60 255 Q 50 255 50 245 L 50 235 Q 50 225 60 225 L 93.63 225" fill="none" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 98.88 225 L 91.88 228.5 L 93.63 225 L 91.88 221.5 Z" fill="rgb(0, 0, 0)" stroke="rgb(0, 0, 0)" stroke-miterlimit="10" pointer-events="all"/></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://www.diagrams.net/doc/faq/svg-export-text-problems" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Text is not SVG - cannot display</text></a></switch></svg>
\ No newline at end of file
diff --git a/docs/developer/index.rst b/docs/developer/index.rst
index 1fdccae..4ea55f5 100644
--- a/docs/developer/index.rst
+++ b/docs/developer/index.rst
@@ -7,7 +7,7 @@
arch-overview
project-structure
- portability-model
+ service-deployment-model
service-access-protocols
service-locator
software-requirements
diff --git a/docs/developer/portability-model.rst b/docs/developer/portability-model.rst
deleted file mode 100644
index 8305cb2..0000000
--- a/docs/developer/portability-model.rst
+++ /dev/null
@@ -1,211 +0,0 @@
-Portability Model
-=================
-
-Within the Trusted Services project, an environment represents the execution environment for an application such
-as a trusted service provider. Some example environments are:
-
- - *opteesp* - Secure partition managed by OP-TEE.
- - *opteeta* - TA running under OP-TEE with access to the Global Platform internal API.
- - *hfsp* - Secure partition managed by Hafnium.
-
-An underlying TEE or SPM that manages a secure processing environment will have its own model for porting to different hardware.
-For example, OP-TEE has its own driver model that allows for alternative hardware drivers. In some cases, a secure processing
-environment will not provide native support for all hardware that an application depends on. To address this, the TS
-portability model allows:
-
- - Application interfaces to be adapted to services natively provided by a secure processing environment if they are available.
- - Adapting to platform provided drivers when no native environment support is available.
-
-Ports and Adapters Architecture
--------------------------------
-
-An application is decoupled from any particular environment via a set of interfaces that reflect the needs of the application.
-This model conforms to the *ports and adapters* architectural pattern that aims to avoid tight coupling between application
-components and any particular environment. This pattern, also known as the *hexagonal architecture*, is often illustrated as
-a hexagonal cell with the application on the inside and the platform on the outside.
-
-The following diagram illustrates how ports and adapters is applied in the trusted services project to provide a model for
-application portability.
-
-.. image:: image/TSportabilityModel.svg
-
-The portability model has the following characteristics:
-
- - The application is decoupled from the environment by a set of virtual interfaces (ports) that reflect the needs of the
- application.
- - Those interfaces are realized by a set of adapters that either use native environment services or platform provided
- services.
- - For a given environment, the set of adapters that realize interfaces used by an application will always be the same,
- independent of the platform.
- - A platform presents interfaces that conform to conventional driver and middleware abstractions such as block drivers and
- filesystems.
- - The set of platform interfaces that an application depends on is defined by the set of adapters used for a deployment of an
- application in a particular environment. This can form the basis for a platform configuration.
-
-The need to use platform provided components will depend on the native features provided by an environment. For example, the
-*opteeta* environment represents the TA environment provided by OP-TEE. In its role as a trusted OS, OP-TEE provides access to
-an implementation of the Global Platform Internal Core API that provides services such as secure storage. Usage of any back-end
-hardware is handled by OP-TEE and its own OS components so no additional provision is needed. Bare metal environments such as
-secure partitions offer few native facilities so it may be necessary to map application interfaces to platform provided drivers.
-Mapping application interfaces to platform drivers is a way of extending the native services provided by an environment.
-
-The portability model allows for an arbitrary partitioning of hardware-backed services between native environment services and
-platform drivers.
-
-Portability Model Example
--------------------------
-
-To illustrate usage of the portability model, consider deployments of the following two trusted services:
-
- - fTPM based on the Microsoft TPM2.0 reference implementation.
- - trustedfirmware.org Crypto service based on the Mbed TLS library.
-
-The Microsoft TPM2.0 reference and Mbed TLS both define their own platform interfaces to allow for platform specific
-implementations of features such as roll-back protected storage and entropy. Although some interfaces are similar between the
-two implementations, they are not the same. These interfaces are classed as ports within the ports and adapters architecture.
-To simplify the example, just the entropy platform dependency is considered. Both fTPM and Crypto service providers need access
-to a cryptographic grade RNG to support key generation. How the RNG is realized will depend on:
-
- - What facilities the environment natively provides.
- - What other trusted services are available on the device.
- - Whether the environment allows for platform specific access to hardware.
- - Availability of a spare hardware TRNG instance.
-
-Adapters will be responsible for adapting both fTPM and Crypto views of an entropy source to a suitable realization.
-Some example adapters:
-
-fTPM adapters that realize MS entropy interface (port)
-''''''''''''''''''''''''''''''''''''''''''''''''''''''
- - *Adapts to crypto service* - Uses crypto service generate_random operation
- - *Adapts to TEE API* - Uses native TEE OS
- - *Adapts to TRNG* - Uses platform TRNG hardware
-
-Crypto adapters that realize Mbed TLS entropy source interface (port)
-'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
- - *Adapts to fTPM* - Uses TPM2 getrandom command
- - *TEE API* - Uses native TEE OS
- - *TRNG* - Uses platform TRNG hardware
-
-The above examples reveal that for a given environment, a port may be realized by more than one type of adapter. For example, an
-fTPM deployed within a secure partition could source entropy from either TRNG hardware or from the Crypto service. This
-ambiguity may be resolved by various strategies such as:
-
- 1. Allow a service profile to be applied at build time that defines a core set of mandatory trusted services. A build-time
- selection of alternative adapters is made, based on available core services.
- 2. A built image for a trusted service deployment to a particular environment includes the superset of adapters that could be
- used. A runtime configuration is applied, that specifies which adapters to use.
-
-Providing Platform Firmware
----------------------------
-
-A goal of the TS project is to reduce barriers to deploying trusted services on different hardware platforms. To this end,
-build-time and run-time coupling between TS project and platform components should be minimized. Platform providers should be
-free to make any of the following choices:
-
- - Reuse existing drivers and driver frameworks (e.g. from tf-a, an RTOS, CMSIS).
- - Provide platform components as part of a BSP.
- - Maintain platform components in separate repos.
- - Operate independent test, bug reporting and release processes for platform components.
- - Control the logical organization and naming of different platforms within the TS project.
- - Maintain whatever platform configuration files that are needed within the provider's sub-tree within the TS project.
-
-The platform top-level directory within the TS project provides a structure that allows platform specific components to be
-contributed by different providers. Different providers are represented beneath the platform/providers directory. The virtual
-platform interfaces used by some adapters are defined under platform/interface. The directory structure beneath a platform
-provider's parent is organized to reflect the provider's own naming scheme for different hardware. Supported platforms are each
-represented by a leaf sub-directory within the provider's subtree.
-
-For Arm provided platforms, the structure will look something like this::
-
- platform
- |-- interface
- |-- providers
- |--arm
- |-- corstone700
- |-- fvp
- |-- fvp_base_aemva
- |-- fvp_base_revc-2xaemv8a
- |-- platform.cmake
-
-Under each platform leaf directory is a file called *platform.cmake*. This file implements the common configuration and build
-interface that will be used during the deployment build process. How this interface is realized is entirely down to the
-platform provider. An implementation will do things like setting configuration variables for SoC, board and driver selection.
-Any additional files needed to support platform configuration and build may be included within the platform provider's sub-tree.
-
-For product developers who want to define and maintain their own private platforms, it should be possible to override the
-default platform/providers directory path to allow an alternative sub-tree to be used. A product developer is free to organize
-a private sub-tree in any way that suites their needs.
-
-Although the TS project structure doesn't mandate it, platform specific firmware is likely to live outside of the TS project.
-The ability to reuse existing drivers and driver frameworks is important for promoting adoption across hardware from different
-vendors. Board and silicon vendors may reuse existing CI and project infrastructure for platform components that they maintain.
-
-Some special platforms are provided by the TS project itself. These are represented beneath the *ts* provider.
-Current TS platforms are:
-
-.. list-table::
- :header-rows: 1
- :widths: 10, 90
-
- * - TS Platform
- - Purpose
- * - ts/vanilla
- - | A platform that never provides any drivers. The ts/vanilla platform should be used when an environment provides its own
- | device framework and no additional drivers need to be provided by the platform. An attempt to build a deployment with
- | platform dependencies on the vanilla platform will result in a build-time error. The vanilla platform is selected by
- | default at build-time if no explicit platform has been specified.
- * - ts/mock
- - | A platform that provides a complete set of drivers that may be selected when building any deployment. The platform uses
- | mock drivers that don't offer functionality suitable for production builds. The mock platform is useful for CI build
- | testing of deployments with platform dependencies. You should always expect a deployment with platform dependencies to
- | build when TS_PLATFORM=ts/mock.
-
-Determining a Platform Configuration for a Deployment
------------------------------------------------------
-
-The TS project supports building and installing an application image into different environments that could be hosted on
-different hardware platforms. A platform is characterized by SoC and board-level hardware and possibly by OS type components
-such as device drivers and middleware. To deploy an application that depends on platform drivers, you need to tie-down:
-
- - *Application name* - such as the name of the service e.g. crypto, secure-storage, attestation, tpm.
- - *Environment* - the environment in which the application will run e.g. bare metal secure partition, Global Platform TEE,
- Trusty TEE, microcontroller RTOS.
- - *Platform* - the hardware platform that hosts the environment.
-
-The following example illustrates how these parameters are specified via the deployment build command line::
-
- cd trusted-services/deployments/crypto/opteesp
- cmake -S . -B build -DTS_PLATFORM=arm/fvp/fvp_base_revc-2xaemv8a
-
-The combination of <application name> + <environment> allows a set of build-time platform dependencies to be generated, based on
-the set of adapter components used for the deployment. This information is passed via the platform build interface to the
-platform.cmake file for the specified platform via a CMake target property called TS_PLATFORM_DRIVER_DEPENDENCIES. The
-translation of the platform dependency information to a suitable build configuration is handled by the platform.cmake file for
-the selected platform. This separation gives a platform provider the freedom to use their own configuration conventions when
-reusing existing drivers.
-
-To allow for out-of-tree platform definitions, the root path for platform definitions may be modified by providing an
-alternative value for TS_PLATFORM_ROOT. Both TS_PLATFORM and TS_PLATFORM_ROOT may be set via the CMake command line or using
-environment variables.
-
-Adapters
---------
-
-As described above, the role of an adapter conforms to the Ports and Adapters pattern. With reference to the hexagonal cell
-representation, an adapter implements an application defined inside interface and adapts it to either an environment interface
-or an outside platform interface. Within the TS project, adapters are treated like any other software component and may be
-reused whenever appropriate. However, because an adapter implements an application defined interface, adapter implementations
-will tend to be tied to a particular application or component. The complexity of adapter implementations can vary a lot and
-will depend on how closely an inside interface matches either an outside interface or an environment interface.
-
-The collection of adapters used for a deployment is defined by the environment specific build file for a deployment. Deployment
-of the same service into a different environment may result in a different set of adapters being used. As each adapter is
-treated as a separate component, a separate component.cmake file exists for each adapter. When an adapter depends on one or
-more platform interfaces, the dependency must be declared in the adapter's component.cmake file. This information forms the
-basis for the platform build configuration.
-
---------------
-
-*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
-
-SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/project-structure.rst b/docs/developer/project-structure.rst
index b69af98..3f0e717 100644
--- a/docs/developer/project-structure.rst
+++ b/docs/developer/project-structure.rst
@@ -93,7 +93,7 @@
For some deployments, an environment may not provide access to all hardware backed services needed by an
application. Files under the platforms directory are concerned with configuring and building platform specific
code that extends the capabilities of an environment. Details of how this works are described in the:
-:ref:`Portability Model`
+:ref:`Service Deployment Model`
components
''''''''''
@@ -206,6 +206,6 @@
--------------
-*Copyright (c) 2020-2021, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/service-deployment-model.rst b/docs/developer/service-deployment-model.rst
new file mode 100644
index 0000000..9f79999
--- /dev/null
+++ b/docs/developer/service-deployment-model.rst
@@ -0,0 +1,292 @@
+Service Deployment Model
+========================
+A goal of the Trusted Services project is to provide a toolbox of reusable service components
+that can be deployed across a wide range of platforms. The project structure promotes reuse by
+grouping related source files into subdirectories that represent reusable components. Components
+may be configured and combined in different ways to meet the needs of platform integrators who
+aim to create firmware with the right features and tradeoffs for their products.
+
+Within the TS project structure, build files that combine and configure components to create
+deployable firmware images reside under the deployments top-level directory. Beneath the
+deployments parent are sub-directories concerned with building and deploying different
+applications. Applications can generally be classified as one of the following:
+
+ - Service providers
+ - Test suites
+ - Libraries
+ - Development support applications
+
+This page is mainly concerned with describing the conventions used to enable service providers
+to be deployed in different environments, on different platforms and with different capabilities.
+The conventions aim to minimize build definition duplication between alternative deployments
+while offering sufficient flexibility to customize capabilities and support different platforms.
+The service deployment model borrows from a pattern used for deploying cloud services where There
+is a similar requirement for deployment flexibility.
+
+Ports and Adapters Architecture
+-------------------------------
+An application is decoupled from any particular environment via a set of interfaces that reflect
+the needs of the application. This model conforms to the ports and adapters architectural
+pattern that aims to avoid tight coupling between application components and any particular
+environment. This pattern, also known as the hexagonal architecture, is often illustrated as a
+hexagonal cell with the application on the inside and the platform on the outside.
+
+The following diagram illustrates how ports and adapters is applied in the trusted services
+project to provide a model for service provider deployment.
+
+.. image:: image/TSportabilityModel.svg
+
+This deployment model has the following characteristics:
+
+ - The application is decoupled from the environment by a set of virtual interfaces (ports)
+ that reflect the needs of the application.
+ - Ports are realized by a set of adapters. An adapter may:
+
+ * Use a service/device provided by the platform or environment.
+ * Communicate with another service provider.
+ * Provide a self-contained implementation.
+ - The set of adapters that the application depends on represents the infrastructure that is
+ needed to support the application.
+ - Different infrastructure realizations may be needed for different deployments of the same
+ service provider.
+
+Service Deployment Structure
+----------------------------
+By convention, the directory structure for service provider deployments reflects the layers in
+the ports and adapters architecture. The following dependency diagram illustrates the set of
+relationships that exist for a fully defined deployment:
+
+.. uml:: uml/ServiceDeploymentDependencies.puml
+
+To avoid undesirable build definition duplication when adding new deployments of an application,
+the directory structure used to organize files related to different deployments should reflect
+the above model. The following table lists reusable build components that may be used across
+different deployment definitions:
+
+.. list-table::
+ :widths: 10 20 20
+ :header-rows: 1
+
+ * - Build Component
+ - Defines
+ - Reuse Scope
+ * - Application
+ - | Set of components that form the core application to be deployed.
+ - | All deployments of the application.
+ * - Infra
+ - | The set of adapters that realize the ports that the application depends on.
+ | An infrastructure definition may depend on:
+
+ * Environment specific components.
+ * Drivers that conform to a driver model.
+ * Platform specific drivers.
+ - | Any deployment that uses the same infrastructure to support the application.
+ | This will depend on how specific the infrastructure is. An infrastructure
+ | definition may allow for some level of configurability to enable deployment
+ | to impose a particular build configuration. Where an infrastructure includes
+ | adapters that use a well supported driver model (such as UEFI), the scope
+ | for reuse is large.
+ * - Env
+ - | The set of environment specific components that are common across all
+ | deployments of an application for a particular environment.
+ - | All deployments of the application into a specific environment. There is
+ | scope to improve reuse of environment specific components across multiple
+ | deployments.
+ * - Config
+ - | Build configuration variables together with a particular application, infra
+ | and env.
+ - | Depends on how specific the config is.
+
+Deployment Directory Structure
+------------------------------
+Using the block-storage deployment as an example, the deployment directory structure reflects
+the service deployment model as follows::
+
+ deployments
+ |- block-storage
+ |- block-storage.cmake - Common application build definition
+ |- env - Environment specific build definitions
+ |- infra - Alternative infrastructures
+ |- config - Configurations for block-storage deployments
+
+Configuration Definitions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+To build a particular configuration of the block-storage service provider (in this case, one
+that uses flash storage on the N1SDP platform), use::
+
+ cd deployments/block-storage/config/n1sdp-flash
+ cmake -B build
+ cd build
+ make
+
+The CMakeLists.txt file for the n1sdp-flash deployment of the block-storage service provider
+includes:
+
+ - Set TS_PLATFORM to n1sdp platform name
+ - Set any build configuration parameter overrides
+ - Include ``${DEPLOYMENT_ROOT}/env/opteesp.cmake``
+ - Include ``${DEPLOYMENT_ROOT}/infra/edk2-flash.cmake``
+ - Include ``${DEPLOYMENT_ROOT}/block-storage.cmake``
+
+Each alternative deployment of the block-storage service provider is represented by a
+subdirectory under ``${DEPLOYMENT_ROOT}/config``. The number of directories under config is
+likely to grow to accommodate platform variability and different tradeoffs for how the infrastructure
+for an application will be realized.
+
+To support test and to provide a starting point for new config definitions, a default config should
+exist for each supported environment.
+
+Infrastructure Definitions
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+An infrastructure defines a set of adapter components that realize the ports that the application
+depends on. For block-storage deployments, some possible infrastructures are:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10, 40
+
+ * - Infra Name
+ - Description
+ * - ref-ram
+ - Provides volatile storage using the reference partition configuration. Intended for test.
+ * - edk2-flash
+ - Provides persistent storage using a flash driver that conforms to the EDK2 driver model.
+ * - tfa-flash
+ - Provides persistent storage using a flash driver that conforms to the TF-A driver model.
+ * - rpmb
+ - Provides persistent storage using an RPMB partition, accessed via a Nwd agent.
+
+Platform Support
+----------------
+The Trusted Services project is not intended to be a home for platform specific code such as
+device drivers. Ideally, device drivers and other platform specific code should be reused
+from external upstream repos such as edk2-platforms. The ports and adapters pattern allows
+alternative driver models to be accommodated so different upstream projects with different
+driver models may be used without the need to modify driver code. Where driver reuse from
+an external project is not possible, the platform directory structure can accommodate driver
+components that reside within the TS project.
+
+The ability to accommodate third-party device drivers that conform to different driver models
+is important for enabling TS components to be used across different segments. The EDK2
+project for example can provide a rich source of drivers that conform to the UEFI model.
+UEFI is not however adopted in all product segments.
+
+All files related to supporting different platforms reside beneath the platform top-level
+directory.
+
+Platform Providers
+^^^^^^^^^^^^^^^^^^
+Within the TS project, a platform provider is responsible for adding and maintaining the
+glue that enables platform specific code to be used from a particular source. The platform
+code will either be:
+
+ - Fetched from an upstream repo (preferred)
+ - Added to the TS project.
+
+Each platform provider is represented by a subdirectory beneath ``platform/providers``. For
+Arm provided platforms, the structure will look something like this::
+
+ platform
+ |-- providers
+ |--arm
+ |-- corstone1000
+ |-- fvp
+ |-- fvp_base_aemva
+ |-- fvp_base_revc-2xaemv8a
+ |-- platform.cmake
+
+Under each platform leaf directory is a file called ``platform.cmake``. This file implements
+the common configuration and build interface that will be used during the deployment build
+process. How this interface is realized is entirely down to the platform provider. An
+implementation will do things like setting configuration variables for SoC, board and driver
+selection. Any additional files needed to support platform configuration and build may be
+included within the platform provider's sub-tree.
+
+For product developers who want to define and maintain their own private platforms, it should
+be possible to override the default ``platform/providers`` directory path to allow an
+alternative sub-tree to be used. A product developer is free to organize a private sub-tree
+in any way that suites their needs.
+
+Although the TS project structure doesn't mandate it, platform specific firmware is likely
+to live outside of the TS project. The ability to reuse existing drivers and driver frameworks
+is important for promoting adoption across hardware from different vendors. Board and silicon
+vendors may reuse existing CI and project infrastructure for platform components that they
+maintain.
+
+Platform support that depends on EDK2 platform components is represented by the edk2 platform
+provider. Files related to the EDK2 platform provider are organized as follows::
+
+ platform
+ |- providers
+ |- edk2
+ |- edk2-platforms.cmake - Fetches the upstream edk2-platforms repo
+ |- platform - Directory for platform definitions, organized by contributor
+ |- arm
+ |- n1sdp
+ |- platform.cmake
+
+Some special platforms are provided by the TS project itself. These are represented beneath
+the ts provider. Current TS platforms are:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10, 90
+
+ * - TS Platform
+ - Purpose
+ * - ``ts/vanilla``
+ - | A platform that never provides any drivers. The ``ts/vanilla`` platform should be used when an environment provides its own
+ | device framework and no additional drivers need to be provided by the platform. An attempt to build a deployment with
+ | platform dependencies on the vanilla platform will result in a build-time error. The vanilla platform is selected by
+ | default at build-time if no explicit platform has been specified.
+ * - ``ts/mock``
+ - | A platform that provides a complete set of drivers that may be selected when building any deployment. The platform uses
+ | mock drivers that don't offer functionality suitable for production builds. The mock platform is useful for CI build
+ | testing of deployments with platform dependencies. You should always expect a deployment with platform dependencies to
+ | build when ``TS_PLATFORM=ts/mock``.
+
+Diver Models
+^^^^^^^^^^^^
+Alternative driver models are represented by subdirectories beneath ``platform/driver_model``.
+Driver code imported from an external project, such as edk2-platforms, will also depend on
+interface and other header files related to the driver model. For drivers reused from
+edk2-platforms, the driver interface header files will define interface structures defined
+by the UEFI specification. The following example illustrates two driver models, one for
+UEFI drivers from the EDK2 project and another for bare-metal drivers that conform to TS
+defined interfaces::
+
+ platform
+ |- driver_model
+ |- edk2
+ |- baremetal
+
+Header files under the driver_model/edk2 directory will either explicitly provide definitions for
+the EDK2 driver model or include definitions from an external component. To maintain compatibility
+with driver code imported from edk2-platforms, sub-directories beneath platform/driver_model/edk2
+should conform to the EDK2 directory structure and naming conventions. The following illustrates
+how UEFI driver model files are organized::
+
+ platform
+ |- driver_model
+ |- edk2
+ |- interface
+ |- Protocol
+ | |- BlockIo.h
+ | |- DiskIo.h
+ | |- FirmwareVolumeBlock.h
+ |
+ |- Library
+ | |- IoLib.h
+ | |- DebugLib.h
+
+Drivers
+^^^^^^^
+The platforms/drivers directory provides a home for CMake files that enable driver code to be built
+as part of the the deployment build process. Source files will either have been fetched from an
+upstream repo or will live under the ``platform/drivers`` parent.
+
+--------------
+
+*Copyright (c) 2021-2022, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/uml/ServiceDeploymentDependencies.puml b/docs/developer/uml/ServiceDeploymentDependencies.puml
new file mode 100644
index 0000000..515a7c5
--- /dev/null
+++ b/docs/developer/uml/ServiceDeploymentDependencies.puml
@@ -0,0 +1,25 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+package Deployment
+package Application
+package Infrastructure
+package Environment
+package Platform
+package BuildConfig
+package Adapter
+
+Deployment -down.> Application
+Deployment -down.> Infrastructure
+Deployment -down.> Environment
+Deployment -down.> "0..1" Platform
+Deployment -down.> "0..1" BuildConfig
+Infrastructure -down.> "0..*" Adapter
+
+@enduml
\ No newline at end of file
