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