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