| Tom Rini | 53633a8 | 2024-02-29 12:33:36 -0500 | [diff] [blame] | 1 | * ARM Secure world bindings |
| 2 | |
| 3 | ARM CPUs with TrustZone support have two distinct address spaces, |
| 4 | "Normal" and "Secure". Most devicetree consumers (including the Linux |
| 5 | kernel) are not TrustZone aware and run entirely in either the Normal |
| 6 | world or the Secure world. However some devicetree consumers are |
| 7 | TrustZone aware and need to be able to determine whether devices are |
| 8 | visible only in the Secure address space, only in the Normal address |
| 9 | space, or visible in both. (One example of that situation would be a |
| 10 | virtual machine which boots Secure firmware and wants to tell the |
| 11 | firmware about the layout of the machine via devicetree.) |
| 12 | |
| 13 | The general principle of the naming scheme for Secure world bindings |
| 14 | is that any property that needs a different value in the Secure world |
| 15 | can be supported by prefixing the property name with "secure-". So for |
| 16 | instance "secure-foo" would override "foo". For property names with |
| 17 | a vendor prefix, the Secure variant of "vendor,foo" would be |
| 18 | "vendor,secure-foo". If there is no "secure-" property then the Secure |
| 19 | world value is the same as specified for the Normal world by the |
| 20 | non-prefixed property. However, only the properties listed below may |
| 21 | validly have "secure-" versions; this list will be enlarged on a |
| 22 | case-by-case basis. |
| 23 | |
| 24 | Defining the bindings in this way means that a device tree which has |
| 25 | been annotated to indicate the presence of Secure-only devices can |
| 26 | still be processed unmodified by existing Non-secure software (and in |
| 27 | particular by the kernel). |
| 28 | |
| 29 | Note that it is still valid for bindings intended for purely Secure |
| 30 | world consumers (like kernels that run entirely in Secure) to simply |
| 31 | describe the view of Secure world using the standard bindings. These |
| 32 | secure- bindings only need to be used where both the Secure and Normal |
| 33 | world views need to be described in a single device tree. |
| 34 | |
| 35 | Valid Secure world properties |
| 36 | ----------------------------- |
| 37 | |
| 38 | - secure-status : specifies whether the device is present and usable |
| 39 | in the secure world. The combination of this with "status" allows |
| 40 | the various possible combinations of device visibility to be |
| 41 | specified. If "secure-status" is not specified it defaults to the |
| 42 | same value as "status"; if "status" is not specified either then |
| 43 | both default to "okay". This means the following combinations are |
| 44 | possible: |
| 45 | |
| 46 | /* Neither specified: default to visible in both S and NS */ |
| 47 | secure-status = "okay"; /* visible in both */ |
| 48 | status = "okay"; /* visible in both */ |
| 49 | status = "okay"; secure-status = "okay"; /* visible in both */ |
| 50 | secure-status = "disabled"; /* NS-only */ |
| 51 | status = "okay"; secure-status = "disabled"; /* NS-only */ |
| 52 | status = "disabled"; secure-status = "okay"; /* S-only */ |
| 53 | status = "disabled"; /* disabled in both */ |
| 54 | status = "disabled"; secure-status = "disabled"; /* disabled in both */ |
| 55 | |
| 56 | The secure-chosen node |
| 57 | ---------------------- |
| 58 | |
| 59 | Similar to the /chosen node which serves as a place for passing data |
| 60 | between firmware and the operating system, the /secure-chosen node may |
| 61 | be used to pass data to the Secure OS. Only the properties defined |
| 62 | below may appear in the /secure-chosen node. |
| 63 | |
| 64 | - stdout-path : specifies the device to be used by the Secure OS for |
| 65 | its console output. The syntax is the same as for /chosen/stdout-path. |
| 66 | If the /secure-chosen node exists but the stdout-path property is not |
| 67 | present, the Secure OS should not perform any console output. If |
| 68 | /secure-chosen does not exist, the Secure OS should use the value of |
| 69 | /chosen/stdout-path instead (that is, use the same device as the |
| 70 | Normal world OS). |