Adding upstream version 2.8.0+dfsg.upstream/2.8.0+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 296 insertions, 0 deletions

diff --git a/docs/components/ffa-manifest-binding.rst b/docs/components/ffa-manifest-binding.rst
new file mode 100644
index 0000000..7483c90
--- /dev/null
+++ b/docs/components/ffa-manifest-binding.rst
@@ -0,0 +1,296 @@
+FF-A manifest binding to device tree
+========================================
+
+This document defines the nodes and properties used to define a partition,
+according to the FF-A specification.
+
+Partition Properties
+--------------------
+
+- compatible [mandatory]
+   - value type: <string>
+   - Must be the string "arm,ffa-manifest-X.Y" which specifies the major and
+     minor versions of the device tree binding for the FFA manifest represented
+     by this node. The minor number is incremented if the binding changes in a
+     backwards compatible manner.
+
+      - X is an integer representing the major version number of this document.
+      - Y is an integer representing the minor version number of this document.
+
+- ffa-version [mandatory]
+   - value type: <u32>
+   - Must be two 16 bits values (X, Y), concatenated as 31:16 -> X,
+     15:0 -> Y, where:
+
+      - X is the major version of FF-A expected by the partition at the FFA
+        instance it will execute.
+      - Y is the minor version of FF-A expected by the partition at the FFA
+        instance it will execute.
+
+- uuid [mandatory]
+   - value type: <prop-encoded-array>
+   - An array consisting of 4 <u32> values, identifying the UUID of the service
+     implemented by this partition. The UUID format is described in RFC 4122.
+
+- id
+   - value type: <u32>
+   - Pre-allocated partition ID.
+
+- auxiliary-id
+   - value type: <u32>
+   - Pre-allocated ID that could be used in memory management transactions.
+
+- description
+   - value type: <string>
+   - Name of the partition e.g. for debugging purposes.
+
+- execution-ctx-count [mandatory]
+   - value type: <u32>
+   - Number of vCPUs that a VM or SP wants to instantiate.
+
+      - In the absence of virtualization, this is the number of execution
+        contexts that a partition implements.
+      - If value of this field = 1 and number of PEs > 1 then the partition is
+        treated as UP & migrate capable.
+      - If the value of this field > 1 then the partition is treated as a MP
+        capable partition irrespective of the number of PEs.
+
+- exception-level [mandatory]
+   - value type: <u32>
+   - The target exception level for the partition:
+
+      - 0x0: EL1
+      - 0x1: S_EL0
+      - 0x2: S_EL1
+
+- execution-state [mandatory]
+   - value type: <u32>
+   - The target execution state of the partition:
+
+      - 0: AArch64
+      - 1: AArch32
+
+- load-address
+   - value type: <u64>
+   - Physical base address of the partition in memory. Absence of this field
+     indicates that the partition is position independent and can be loaded at
+     any address chosen at boot time.
+
+- entrypoint-offset
+   - value type: <u64>
+   - Offset from the base of the partition's binary image to the entry point of
+     the partition. Absence of this field indicates that the entry point is at
+     offset 0x0 from the base of the partition's binary.
+
+- xlat-granule [mandatory]
+   - value type: <u32>
+   - Translation granule used with the partition:
+
+      - 0x0: 4k
+      - 0x1: 16k
+      - 0x2: 64k
+
+- boot-order
+   - value type: <u32>
+   - A unique number amongst all partitions that specifies if this partition
+     must be booted before others. The partition with the smaller number will be
+     booted first.
+
+- rx-tx-buffer
+   - value type: "memory-regions" node
+   - Specific "memory-regions" nodes that describe the RX/TX buffers expected
+     by the partition.
+     The "compatible" must be the string "arm,ffa-manifest-rx_tx-buffer".
+
+- messaging-method [mandatory]
+   - value type: <u8>
+   - Specifies which messaging methods are supported by the partition, set bit
+     means the feature is supported, clear bit - not supported:
+
+      - Bit[0]: partition can receive direct requests if set
+      - Bit[1]: partition can send direct requests if set
+      - Bit[2]: partition can send and receive indirect messages
+
+- managed-exit
+   - value type: <empty>
+   - Specifies if managed exit is supported.
+   - This field is deprecated in favor of ns-interrupts-action field in the FF-A
+     v1.1 EAC0 spec.
+
+- ns-interrupts-action [mandatory]
+   - value type: <u32>
+   - Specifies the action that the SPMC must take in response to a Non-secure
+     physical interrupt.
+
+      - 0x0: Non-secure interrupt is queued
+      - 0x1: Non-secure interrupt is signaled after a managed exit
+      - 0x2: Non-secure interrupt is signaled
+
+   - This field supersedes the managed-exit field in the FF-A v1.0 spec.
+
+- has-primary-scheduler
+   - value type: <empty>
+   - Presence of this field indicates that the partition implements the primary
+     scheduler. If so, run-time EL must be EL1.
+
+- run-time-model
+   - value type: <u32>
+   - Run time model that the SPM must enforce for this SP:
+
+      - 0x0: Run to completion
+      - 0x1: Preemptible
+
+- time-slice-mem
+   - value type: <empty>
+   - Presence of this field indicates that the partition doesn't expect the
+     partition manager to time slice long running memory management functions.
+
+- gp-register-num
+   - value type: <u32>
+   - The field specifies the general purpose register number but not its width.
+     The width is derived from the partition's execution state, as specified in
+     the partition properties. For example, if the number value is 1 then the
+     general-purpose register used will be x1 in AArch64 state and w1 in AArch32
+     state.
+     Presence of this field indicates that the partition expects the address of
+     the FF-A boot information blob to be passed in the specified general purpose
+     register.
+
+- stream-endpoint-ids
+   - value type: <prop-encoded-array>
+   - List of <u32> tuples, identifying the IDs this partition is acting as
+     proxy for.
+
+- power-management-messages
+   - value type: <u32>
+   - Specifies which power management messages a partition subscribes to.
+     A set bit means the partition should be informed of the power event, clear
+     bit - should not be informed of event:
+
+      - Bit[0]: CPU_OFF
+      - Bit[1]: CPU_SUSPEND
+      - Bit[2]: CPU_SUSPEND_RESUME
+
+Memory Regions
+--------------
+
+- compatible [mandatory]
+   - value type: <string>
+   - Must be the string "arm,ffa-manifest-memory-regions".
+
+- description
+   - value type: <string>
+   - Name of the memory region e.g. for debugging purposes.
+
+- pages-count [mandatory]
+   - value type: <u32>
+   - Count of pages of memory region as a multiple of the translation granule
+     size
+
+- attributes [mandatory]
+   - value type: <u32>
+   - Mapping modes: ORed to get required permission
+
+      - 0x1: Read
+      - 0x2: Write
+      - 0x4: Execute
+      - 0x8: Security state
+
+- base-address
+   - value type: <u64>
+   - Base address of the region. The address must be aligned to the translation
+     granule size.
+     The address given may be a Physical Address (PA), Virtual Address (VA), or
+     Intermediate Physical Address (IPA). Refer to the FF-A specification for
+     more information on the restrictions around the address type.
+     If the base address is omitted then the partition manager must map a memory
+     region of the specified size into the partition's translation regime and
+     then communicate the region properties (including the base address chosen
+     by the partition manager) to the partition.
+
+Device Regions
+--------------
+
+- compatible [mandatory]
+   - value type: <string>
+   - Must be the string "arm,ffa-manifest-device-regions".
+
+- description
+   - value type: <string>
+   - Name of the device region e.g. for debugging purposes.
+
+- pages-count [mandatory]
+   - value type: <u32>
+   - Count of pages of memory region as a multiple of the translation granule
+     size
+
+- attributes [mandatory]
+   - value type: <u32>
+   - Mapping modes: ORed to get required permission
+
+     - 0x1: Read
+     - 0x2: Write
+     - 0x4: Execute
+     - 0x8: Security state
+
+- base-address [mandatory]
+   - value type: <u64>
+   - Base address of the region. The address must be aligned to the translation
+     granule size.
+     The address given may be a Physical Address (PA), Virtual Address (VA), or
+     Intermediate Physical Address (IPA). Refer to the FF-A specification for
+     more information on the restrictions around the address type.
+
+- smmu-id
+   - value type: <u32>
+   - On systems with multiple System Memory Management Units (SMMUs) this
+     identifier is used to inform the partition manager which SMMU the device is
+     upstream of. If the field is omitted then it is assumed that the device is
+     not upstream of any SMMU.
+
+- stream-ids
+   - value type: <prop-encoded-array>
+   - A list of (id, mem-manage) pair, where:
+
+      - id: A unique <u32> value amongst all devices assigned to the partition.
+
+- interrupts [mandatory]
+   - value type: <prop-encoded-array>
+   - A list of (id, attributes) pair describing the device interrupts, where:
+
+      - id: The <u32> interrupt IDs.
+      - attributes: A <u32> value, containing attributes for each interrupt ID:
+
+        +----------------------+----------+
+        |Field                 | Bit(s)   |
+        +----------------------+----------+
+        | Priority	       | 7:0      |
+        +----------------------+----------+
+        | Security state       | 8        |
+        +----------------------+----------+
+        | Config(Edge/Level)   | 9        |
+        +----------------------+----------+
+        | Type(SPI/PPI/SGI)    | 11:10    |
+        +----------------------+----------+
+
+        Security state:
+          - Secure:       1
+          - Non-secure:   0
+
+        Configuration:
+          - Edge triggered:       0
+          - Level triggered:      1
+
+        Type:
+          - SPI:  0b10
+          - PPI:  0b01
+          - SGI:  0b00
+
+- exclusive-access
+   - value type: <empty>
+   - Presence of this field implies that this endpoint must be granted exclusive
+     access and ownership of this device's MMIO region.
+
+--------------
+
+*Copyright (c) 2019-2022, Arm Limited and Contributors. All rights reserved.*