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
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: <u32>
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. Highest vlue allowed for this field is 0xFFFF.
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: <u32>
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 via FFA_MSG_SEND_DIRECT_REQ ABI if set
111      - Bit[1]: partition can send direct requests via FFA_MSG_SEND_DIRECT_REQ ABI if set
112      - Bit[2]: partition can send and receive indirect messages
113      - Bit[9]: partition can receive direct requests via FFA_MSG_SEND_DIRECT_REQ2 ABI if set
114      - Bit[10]: partition can send direct requests via FFA_MSG_SEND_DIRECT_REQ2 ABI if set
115
116- managed-exit
117   - value type: <empty>
118   - Specifies if managed exit is supported.
119   - This field is deprecated in favor of ns-interrupts-action field in the FF-A
120     v1.1 EAC0 spec.
121
122- managed-exit-virq
123   - value type: <empty>
124   - Indicates if the partition needs managed exit, if supported, to be signaled
125     through vIRQ signal.
126
127- ns-interrupts-action [mandatory]
128   - value type: <u32>
129   - Specifies the action that the SPMC must take in response to a Non-secure
130     physical interrupt.
131
132      - 0x0: Non-secure interrupt is queued
133      - 0x1: Non-secure interrupt is signaled after a managed exit
134      - 0x2: Non-secure interrupt is signaled
135
136   - This field supersedes the managed-exit field in the FF-A v1.0 spec.
137
138- other-s-interrupts-action
139   - value type: <u32>
140   - Specifies the action that the SPMC must take in response to a Other-Secure
141     physical interrupt.
142
143      - 0x0: Other-Secure interrupt is queued
144      - 0x1: Other-Secure interrupt is signaled
145
146- has-primary-scheduler
147   - value type: <empty>
148   - Presence of this field indicates that the partition implements the primary
149     scheduler. If so, run-time EL must be EL1.
150
151- time-slice-mem
152   - value type: <empty>
153   - Presence of this field indicates that the partition doesn't expect the
154     partition manager to time slice long running memory management functions.
155
156- gp-register-num
157   - value type: <u32>
158   - The field specifies the general purpose register number but not its width.
159     The width is derived from the partition's execution state, as specified in
160     the partition properties. For example, if the number value is 1 then the
161     general-purpose register used will be x1 in AArch64 state and w1 in AArch32
162     state.
163     Presence of this field indicates that the partition expects the address of
164     the FF-A boot information blob to be passed in the specified general purpose
165     register.
166
167- power-management-messages
168   - value type: <u32>
169   - Specifies which power management messages a partition subscribes to.
170     A set bit means the partition should be informed of the power event, clear
171     bit - should not be informed of event:
172
173      - Bit[0]: CPU_OFF
174      - Bit[1]: CPU_SUSPEND
175      - Bit[2]: CPU_SUSPEND_RESUME
176
177- vm-availability-messages
178   - value type: <u32>
179   - Specifies which VM availability messages a partition subscribes to. A set
180     bit means the partition should be informed of the event, clear bit - should
181     not be informed of event:
182
183      - Bit[0]: VM created
184      - Bit[1]: VM destroyed
185
186.. _memory_region_node:
187
188Memory Regions
189--------------
190
191- compatible [mandatory]
192   - value type: <string>
193   - Must be the string "arm,ffa-manifest-memory-regions".
194
195- description
196   - value type: <string>
197   - Name of the memory region e.g. for debugging purposes.
198
199- pages-count [mandatory]
200   - value type: <u32>
201   - Count of pages of memory region as a multiple of the translation granule
202     size
203
204- attributes [mandatory]
205   - value type: <u32>
206   - Mapping modes: ORed to get required permission
207
208      - 0x1: Read
209      - 0x2: Write
210      - 0x4: Execute
211      - 0x8: Security state
212
213- base-address
214   - value type: <u64>
215   - Base address of the region. The address must be aligned to the translation
216     granule size.
217     The address given may be a Physical Address (PA), Virtual Address (VA), or
218     Intermediate Physical Address (IPA). Refer to the FF-A specification for
219     more information on the restrictions around the address type.
220     If the base address is omitted then the partition manager must map a memory
221     region of the specified size into the partition's translation regime and
222     then communicate the region properties (including the base address chosen
223     by the partition manager) to the partition.
224
225- load-address-relative-offset
226   - value type: <u64>
227   - Offset relative to the load address of the partition.
228     When this is provided in the partition manifest, it should be added to the
229     load address to get the base address of the region. The secure partition
230     manifest can have either "base-address" or "load-address-relative-offset".
231     It cannot have both.
232
233- stream-ids
234   - value type: <prop-encoded-array>
235   - List of IDs belonging to a DMA capable peripheral device that has access to
236     the memory region represented by current node.
237   - Each ID must have been declared in exactly one device region node.
238
239- smmu-id
240   - value type: <u32>
241   - Identifies the SMMU IP that enforces the access control for the DMA device
242     that owns the above stream-ids.
243
244- stream-ids-access-permissions
245   - value type: <prop-encoded-array>
246   - List of attributes representing the instruction and data access permissions
247     used by the DMA device streams to access the memory region represented by
248     current node.
249
250.. _device_region_node:
251
252Device Regions
253--------------
254
255- compatible [mandatory]
256   - value type: <string>
257   - Must be the string "arm,ffa-manifest-device-regions".
258
259- description
260   - value type: <string>
261   - Name of the device region e.g. for debugging purposes.
262
263- pages-count [mandatory]
264   - value type: <u32>
265   - Count of pages of memory region as a multiple of the translation granule
266     size
267
268- attributes [mandatory]
269   - value type: <u32>
270   - Mapping modes: ORed to get required permission
271
272     - 0x1: Read
273     - 0x2: Write
274     - 0x4: Execute
275     - 0x8: Security state
276
277- base-address [mandatory]
278   - value type: <u64>
279   - Base address of the region. The address must be aligned to the translation
280     granule size.
281     The address given may be a Physical Address (PA), Virtual Address (VA), or
282     Intermediate Physical Address (IPA). Refer to the FF-A specification for
283     more information on the restrictions around the address type.
284
285- smmu-id
286   - value type: <u32>
287   - On systems with multiple System Memory Management Units (SMMUs) this
288     identifier is used to inform the partition manager which SMMU the device is
289     upstream of. If the field is omitted then it is assumed that the device is
290     not upstream of any SMMU.
291
292- stream-ids
293   - value type: <prop-encoded-array>
294   - List of IDs where an ID is a unique <u32> value amongst all devices assigned
295     to the partition.
296
297- interrupts
298   - value type: <prop-encoded-array>
299   - A list of (id, attributes) pair describing the device interrupts, where:
300
301      - id: The <u32> interrupt IDs.
302      - attributes: A <u32> value, containing attributes for each interrupt ID:
303
304        +----------------------+----------+
305        |Field                 | Bit(s)   |
306        +----------------------+----------+
307        | Priority	       | 7:0      |
308        +----------------------+----------+
309        | Security state       | 8        |
310        +----------------------+----------+
311        | Config(Edge/Level)   | 9        |
312        +----------------------+----------+
313        | Type(SPI/PPI/SGI)    | 11:10    |
314        +----------------------+----------+
315
316        Security state:
317          - Secure:       1
318          - Non-secure:   0
319
320        Configuration:
321          - Edge triggered:       0
322          - Level triggered:      1
323
324        Type:
325          - SPI:  0b10
326          - PPI:  0b01
327          - SGI:  0b00
328
329- interrupts-target
330   - value type: <prop-encoded-array>
331   - A list of (id, mpdir upper bits, mpidr lower bits) tuples describing which
332     mpidr the interrupt is routed to, where:
333
334      - id: The <u32> interrupt ID. Must be one of those specified in the
335            "interrupts" field.
336      - mpidr upper bits: The <u32> describing the upper bits of the 64 bits
337                          mpidr
338      - mpidr lower bits: The <u32> describing the lower bits of the 64 bits
339                          mpidr
340
341- exclusive-access
342   - value type: <empty>
343   - Presence of this field implies that this endpoint must be granted exclusive
344     access and ownership of this device's MMIO region.
345
346--------------
347
348*Copyright (c) 2019-2024, Arm Limited and Contributors. All rights reserved.*
349