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: <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.
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
118- has-primary-scheduler
119   - value type: <empty>
120   - Presence of this field indicates that the partition implements the primary
121     scheduler. If so, run-time EL must be EL1.
122
123- run-time-model
124   - value type: <u32>
125   - Run time model that the SPM must enforce for this SP:
126
127      - 0x0: Run to completion
128      - 0x1: Preemptible
129
130- time-slice-mem
131   - value type: <empty>
132   - Presence of this field indicates that the partition doesn't expect the
133     partition manager to time slice long running memory management functions.
134
135- gp-register-num
136   - value type: <u32>
137   - The field specifies the general purpose register number but not its width.
138     The width is derived from the partition's execution state, as specified in
139     the partition properties. For example, if the number value is 1 then the
140     general-purpose register used will be x1 in AArch64 state and w1 in AArch32
141     state.
142     Presence of this field indicates that the partition expects the address of
143     the FF-A boot information blob to be passed in the specified general purpose
144     register.
145
146- stream-endpoint-ids
147   - value type: <prop-encoded-array>
148   - List of <u32> tuples, identifying the IDs this partition is acting as
149     proxy for.
150
151- power-management-messages
152   - value type: <u32>
153   - Specifies which power management messages a partition subscribes to.
154     A set bit means the partition should be informed of the power event, clear
155     bit - should not be informed of event:
156
157      - Bit[0]: CPU_OFF
158      - Bit[1]: CPU_SUSPEND
159      - Bit[2]: CPU_SUSPEND_RESUME
160
161Memory Regions
162--------------
163
164- compatible [mandatory]
165   - value type: <string>
166   - Must be the string "arm,ffa-manifest-memory-regions".
167
168- description
169   - value type: <string>
170   - Name of the memory region e.g. for debugging purposes.
171
172- pages-count [mandatory]
173   - value type: <u32>
174   - Count of pages of memory region as a multiple of the translation granule
175     size
176
177- attributes [mandatory]
178   - value type: <u32>
179   - Mapping modes: ORed to get required permission
180
181      - 0x1: Read
182      - 0x2: Write
183      - 0x4: Execute
184      - 0x8: Security state
185
186- base-address
187   - value type: <u64>
188   - Base address of the region. The address must be aligned to the translation
189     granule size.
190     The address given may be a Physical Address (PA), Virtual Address (VA), or
191     Intermediate Physical Address (IPA). Refer to the FF-A specification for
192     more information on the restrictions around the address type.
193     If the base address is omitted then the partition manager must map a memory
194     region of the specified size into the partition's translation regime and
195     then communicate the region properties (including the base address chosen
196     by the partition manager) to the partition.
197
198Device Regions
199--------------
200
201- compatible [mandatory]
202   - value type: <string>
203   - Must be the string "arm,ffa-manifest-device-regions".
204
205- description
206   - value type: <string>
207   - Name of the device region e.g. for debugging purposes.
208
209- pages-count [mandatory]
210   - value type: <u32>
211   - Count of pages of memory region as a multiple of the translation granule
212     size
213
214- attributes [mandatory]
215   - value type: <u32>
216   - Mapping modes: ORed to get required permission
217
218     - 0x1: Read
219     - 0x2: Write
220     - 0x4: Execute
221     - 0x8: Security state
222
223- base-address [mandatory]
224   - value type: <u64>
225   - Base address of the region. The address must be aligned to the translation
226     granule size.
227     The address given may be a Physical Address (PA), Virtual Address (VA), or
228     Intermediate Physical Address (IPA). Refer to the FF-A specification for
229     more information on the restrictions around the address type.
230
231- smmu-id
232   - value type: <u32>
233   - On systems with multiple System Memory Management Units (SMMUs) this
234     identifier is used to inform the partition manager which SMMU the device is
235     upstream of. If the field is omitted then it is assumed that the device is
236     not upstream of any SMMU.
237
238- stream-ids
239   - value type: <prop-encoded-array>
240   - A list of (id, mem-manage) pair, where:
241
242      - id: A unique <u32> value amongst all devices assigned to the partition.
243
244- interrupts [mandatory]
245   - value type: <prop-encoded-array>
246   - A list of (id, attributes) pair describing the device interrupts, where:
247
248      - id: The <u32> interrupt IDs.
249      - attributes: A <u32> value, containing attributes for each interrupt ID:
250
251        +----------------------+----------+
252        |Field                 | Bit(s)   |
253        +----------------------+----------+
254        | Priority	       | 7:0      |
255        +----------------------+----------+
256        | Security state       | 8        |
257        +----------------------+----------+
258        | Config(Edge/Level)   | 9        |
259        +----------------------+----------+
260        | Type(SPI/PPI/SGI)    | 11:10    |
261        +----------------------+----------+
262
263        Security state:
264          - Secure:       1
265          - Non-secure:   0
266
267        Configuration:
268          - Edge triggered:       0
269          - Level triggered:      1
270
271        Type:
272          - SPI:  0b10
273          - PPI:  0b01
274          - SGI:  0b00
275
276- exclusive-access
277   - value type: <empty>
278   - Presence of this field implies that this endpoint must be granted exclusive
279     access and ownership of this device's MMIO region.
280
281--------------
282
283*Copyright (c) 2019-2022, Arm Limited and Contributors. All rights reserved.*
284