1FF-A manifest binding to device tree
2========================================
3
4This document defines the nodes and properties used to define a partition,
5according to the FF-A specification.
6
7Version 1.0
8-----------
9
10Partition Properties
11^^^^^^^^^^^^^^^^^^^^
12
13- compatible [mandatory]
14   - value type: <string>
15   - Must be the string "arm,ffa-manifest-X.Y" which specifies the major and
16     minor versions of the device tree binding for the FFA manifest represented
17     by this node. The minor number is incremented if the binding changes in a
18     backwards compatible manner.
19
20      - X is an integer representing the major version number of this document.
21      - Y is an integer representing the minor version number of this document.
22
23- ffa-version [mandatory]
24   - value type: <u32>
25   - Must be two 16 bits values (X, Y), concatenated as 31:16 -> X,
26     15:0 -> Y, where:
27
28      - X is the major version of FF-A expected by the partition at the FFA
29        instance it will execute.
30      - Y is the minor version of FF-A expected by the partition at the FFA
31        instance it will execute.
32
33- uuid [mandatory]
34   - value type: <prop-encoded-array>
35   - An array consisting of 4 <u32> values, identifying the UUID of the service
36     implemented by this partition. The UUID format is described in RFC 4122.
37
38- id
39   - value type: <u32>
40   - Pre-allocated partition ID.
41
42- auxiliary-id
43   - value type: <u32>
44   - Pre-allocated ID that could be used in memory management transactions.
45
46- description
47   - value type: <string>
48   - Name of the partition e.g. for debugging purposes.
49
50- execution-ctx-count [mandatory]
51   - value type: <u32>
52   - Number of vCPUs that a VM or SP wants to instantiate.
53
54      - In the absence of virtualization, this is the number of execution
55        contexts that a partition implements.
56      - If value of this field = 1 and number of PEs > 1 then the partition is
57        treated as UP & migrate capable.
58      - If the value of this field > 1 then the partition is treated as a MP
59        capable partition irrespective of the number of PEs.
60
61- exception-level [mandatory]
62   - value type: <u32>
63   - The target exception level for the partition:
64
65      - 0x0: EL1
66      - 0x1: S_EL0
67      - 0x2: S_EL1
68
69- execution-state [mandatory]
70   - value type: <u32>
71   - The target execution state of the partition:
72
73      - 0: AArch64
74      - 1: AArch32
75
76- load-address
77   - value type: <u64>
78   - Physical base address of the partition in memory. Absence of this field
79     indicates that the partition is position independent and can be loaded at
80     any address chosen at boot time.
81
82- entrypoint-offset
83   - value type: <u64>
84   - Offset from the base of the partition's binary image to the entry point of
85     the partition. Absence of this field indicates that the entry point is at
86     offset 0x0 from the base of the partition's binary.
87
88- xlat-granule [mandatory]
89   - value type: <u32>
90   - Translation granule used with the partition:
91
92      - 0x0: 4k
93      - 0x1: 16k
94      - 0x2: 64k
95
96- boot-order
97   - value type: <u32>
98   - A unique number amongst all partitions that specifies if this partition
99     must be booted before others. The partition with the smaller number will be
100     booted first.
101
102- rx-tx-buffer
103   - value type: "memory-regions" node
104   - Specific "memory-regions" nodes that describe the RX/TX buffers expected
105     by the partition.
106     The "compatible" must be the string "arm,ffa-manifest-rx_tx-buffer".
107
108- messaging-method [mandatory]
109   - value type: <u8>
110   - Specifies which messaging methods are supported by the partition, set bit
111     means the feature is supported, clear bit - not supported:
112
113      - Bit[0]: partition can receive direct requests if set
114      - Bit[1]: partition can send direct requests if set
115      - Bit[2]: partition can send and receive indirect messages
116
117- managed-exit
118   - value type: <empty>
119   - Specifies if managed exit is supported.
120
121- has-primary-scheduler
122   - value type: <empty>
123   - Presence of this field indicates that the partition implements the primary
124     scheduler. If so, run-time EL must be EL1.
125
126- run-time-model
127   - value type: <u32>
128   - Run time model that the SPM must enforce for this SP:
129
130      - 0x0: Run to completion
131      - 0x1: Preemptible
132
133- time-slice-mem
134   - value type: <empty>
135   - Presence of this field indicates that the partition doesn't expect the
136     partition manager to time slice long running memory management functions.
137
138- gp-register-num
139   - value type: <u32>
140   - Presence of this field indicates that the partition expects the
141     ffa_init_info structure to be passed in via the specified general purpose
142     register.
143     The field specifies the general purpose register number but not its width.
144     The width is derived from the partition's execution state, as specified in
145     the partition properties. For example, if the number value is 1 then the
146     general-purpose register used will be x1 in AArch64 state and w1 in AArch32
147     state.
148
149- stream-endpoint-ids
150   - value type: <prop-encoded-array>
151   - List of <u32> tuples, identifying the IDs this partition is acting as
152     proxy for.
153
154Memory Regions
155--------------
156
157- compatible [mandatory]
158   - value type: <string>
159   - Must be the string "arm,ffa-manifest-memory-regions".
160
161- description
162   - value type: <string>
163   - Name of the memory region e.g. for debugging purposes.
164
165- pages-count [mandatory]
166   - value type: <u32>
167   - Count of pages of memory region as a multiple of the translation granule
168     size
169
170- attributes [mandatory]
171   - value type: <u32>
172   - Mapping modes: ORed to get required permission
173
174      - 0x1: Read
175      - 0x2: Write
176      - 0x4: Execute
177
178- base-address
179   - value type: <u64>
180   - Base address of the region. The address must be aligned to the translation
181     granule size.
182     The address given may be a Physical Address (PA), Virtual Address (VA), or
183     Intermediate Physical Address (IPA). Refer to the FFA specification for
184     more information on the restrictions around the address type.
185     If the base address is omitted then the partition manager must map a memory
186     region of the specified size into the partition's translation regime and
187     then communicate the region properties (including the base address chosen
188     by the partition manager) to the partition.
189
190Device Regions
191--------------
192
193- compatible [mandatory]
194   - value type: <string>
195   - Must be the string "arm,ffa-manifest-device-regions".
196
197- description
198   - value type: <string>
199   - Name of the device region e.g. for debugging purposes.
200
201- reg [mandatory]
202   - value type: <prop-encoded-array>
203   - A (address, num-pages) pair describing the device, where:
204
205      - address: The physical base address <u64> value of the device MMIO
206        region.
207      - num-pages: The <u32> number of pages of the region. The total size of
208        the region is this value multiplied by the translation granule size.
209
210- attributes [mandatory]
211   - value type: <u32>
212   - Mapping modes: ORed to get required permission
213
214     - 0x1: Read
215     - 0x2: Write
216     - 0x4: Execute
217
218- smmu-id
219   - value type: <u32>
220   - On systems with multiple System Memory Management Units (SMMUs) this
221     identifier is used to inform the partition manager which SMMU the device is
222     upstream of. If the field is omitted then it is assumed that the device is
223     not upstream of any SMMU.
224
225- stream-ids
226   - value type: <prop-encoded-array>
227   - A list of (id, mem-manage) pair, where:
228
229      - id: A unique <u32> value amongst all devices assigned to the partition.
230
231- interrupts [mandatory]
232   - value type: <prop-encoded-array>
233   - A list of (id, attributes) pair describing the device interrupts, where:
234
235      - id: The <u32> interrupt IDs.
236      - attributes: A <u32> value,
237        containing the attributes for each interrupt ID:
238
239         - Interrupt type: SPI, PPI, SGI
240         - Interrupt configuration: Edge triggered, Level triggered
241         - Interrupt security state: Secure, Non-secure
242         - Interrupt priority value
243         - Target execution context/vCPU for each SPI
244
245- exclusive-access
246   - value type: <empty>
247   - Presence of this field implies that this endpoint must be granted exclusive
248     access and ownership of this device's MMIO region.
249
250--------------
251
252*Copyright (c) 2019-2021, Arm Limited and Contributors. All rights reserved.*
253