VirtualBox

source: vbox/trunk/include/iprt/fdt.h@ 104212

Last change on this file since 104212 was 101470, checked in by vboxsync, 14 months ago

Runtime/RTFdt: Add convenience method to add a property consisting of an arbitrary number of u32 cells which are given as an array, bugref:10528

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 11.4 KB
Line 
1/** @file
2 * IPRT - Flattened Devicetree parser and generator API.
3 */
4
5/*
6 * Copyright (C) 2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_fdt_h
37#define IPRT_INCLUDED_fdt_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/cdefs.h>
43#include <iprt/types.h>
44#include <iprt/vfs.h>
45
46
47RT_C_DECLS_BEGIN
48
49/** @defgroup grp_rt_fdt RTFdt - Flattened Devicetree parser and generator API.
50 * @ingroup grp_rt
51 * @{
52 */
53
54/**
55 * Flattened device tree type.
56 */
57typedef enum RTFDTTYPE
58{
59 /** The invalid output type. */
60 RTFDTTYPE_INVALID = 0,
61 /** Output is an UTF-8 DTS. */
62 RTFDTTYPE_DTS,
63 /** Output is the flattened devicetree binary format. */
64 RTFDTTYPE_DTB,
65 /** Usual 32-bit hack. */
66 RTFDTTYPE_32BIT_HACK = 0x7fffffff
67} RTFDTTYPE;
68
69
70#ifdef IN_RING3
71
72/**
73 * Creates a new empty flattened devicetree returning the handle.
74 *
75 * @returns IPRT status code.
76 * @param phFdt Where to store the handle to the flattened devicetree on success.
77 */
78RTDECL(int) RTFdtCreateEmpty(PRTFDT phFdt);
79
80
81/**
82 * Creates a flattened device tree from the given VFS file.
83 *
84 * @returns IPRT status code.
85 * @param phFdt Where to store the handle to the flattened devicetree on success.
86 * @param hVfsIos The VFS I/O stream handle to read the devicetree from.
87 * @param enmInType The input type of the flattened devicetree.
88 * @param pErrInfo Where to return additional error information.
89 */
90RTDECL(int) RTFdtCreateFromVfsIoStrm(PRTFDT phFdt, RTVFSIOSTREAM hVfsIos, RTFDTTYPE enmInType, PRTERRINFO pErrInfo);
91
92
93/**
94 * Creates a flattened device tree from the given filename.
95 *
96 * @returns IPRT status code.
97 * @param phFdt Where to store the handle to the flattened devicetree on success.
98 * @param pszFilename The filename to read the devicetree from.
99 * @param enmInType The input type of the flattened devicetree.
100 * @param pErrInfo Where to return additional error information.
101 */
102RTDECL(int) RTFdtCreateFromFile(PRTFDT phFdt, const char *pszFilename, RTFDTTYPE enmInType, PRTERRINFO pErrInfo);
103
104
105/**
106 * Destroys the given flattened devicetree.
107 *
108 * @param hFdt The flattened devicetree handle to destroy.
109 */
110RTDECL(void) RTFdtDestroy(RTFDT hFdt);
111
112
113/**
114 * Finalizes the given FDT for writing out.
115 *
116 * @returns IPRT status code.
117 * @param hFdt The flattened devicetree handle.
118 */
119RTDECL(int) RTFdtFinalize(RTFDT hFdt);
120
121
122/**
123 * Allocates a new phandle serving as a unique identifer within the given FDT.
124 *
125 * @returns The phandle value
126 * @retval UINT32_MAX in case the given FDT handle is invalid or the FDT is out of free phandle values.
127 * @param hFdt The flattened devicetree handle to destroy.
128 */
129RTDECL(uint32_t) RTFdtPHandleAllocate(RTFDT hFdt);
130
131
132/**
133 * Dumps the given flattened devicetree to the given VFS file.
134 *
135 * @returns IPRT status code.
136 * @param hFdt The flattened devicetree handle.
137 * @param enmOutType The output type.
138 * @param fFlags Flags controlling the output, MBZ.
139 * @param hVfsIos The VFS I/O stream handle to dump the DTS to.
140 * @param pErrInfo Where to return additional error information.
141 */
142RTDECL(int) RTFdtDumpToVfsIoStrm(RTFDT hFdt, RTFDTTYPE enmOutType, uint32_t fFlags, RTVFSIOSTREAM hVfsIos, PRTERRINFO pErrInfo);
143
144
145/**
146 * Dumps the given flattened devicetree to the given file.
147 *
148 * @returns IPRT status code.
149 * @param hFdt The flattened devicetree handle.
150 * @param enmOutType The output type.
151 * @param fFlags Flags controlling the output, MBZ.
152 * @param pszFilename The filename to dump to.
153 * @param pErrInfo Where to return additional error information.
154 */
155RTDECL(int) RTFdtDumpToFile(RTFDT hFdt, RTFDTTYPE enmOutType, uint32_t fFlags, const char *pszFilename, PRTERRINFO pErrInfo);
156
157
158/**
159 * Adds a new memory reservation to the given FDT instance.
160 *
161 * @returns IPRT status code.
162 * @param hFdt The flattened devicetree handle.
163 * @param PhysAddrStart The physical start address of the reservation.
164 * @param cbArea Size of the area in bytes.
165 */
166RTDECL(int) RTFdtAddMemoryReservation(RTFDT hFdt, uint64_t PhysAddrStart, uint64_t cbArea);
167
168
169/**
170 * Sets the physical boot CPU id for the given FDT instance.
171 *
172 * @returns IPRT status code.
173 * @param hFdt The flattened devicetree handle.
174 * @param idPhysBootCpu The physical boot CPU ID.
175 */
176RTDECL(int) RTFdtSetPhysBootCpuId(RTFDT hFdt, uint32_t idPhysBootCpu);
177
178
179/**
180 * Adds a new ode with the given name under the currently active one.
181 *
182 * @returns IPRT status code.
183 * @param hFdt The flattened devicetree handle.
184 * @param pszName The name of the node.
185 */
186RTDECL(int) RTFdtNodeAdd(RTFDT hFdt, const char *pszName);
187
188
189/**
190 * Adds a new ode with the given name under the currently active one.
191 *
192 * @returns IPRT status code.
193 * @param hFdt The flattened devicetree handle.
194 * @param pszNameFmt The name of the node as a format string.
195 * @param ... The format arguments.
196 */
197RTDECL(int) RTFdtNodeAddF(RTFDT hFdt, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(2, 3);
198
199
200/**
201 * Adds a new ode with the given name under the currently active one.
202 *
203 * @returns IPRT status code.
204 * @param hFdt The flattened devicetree handle.
205 * @param pszNameFmt The name of the node as a format string.
206 * @param va The format arguments.
207 */
208RTDECL(int) RTFdtNodeAddV(RTFDT hFdt, const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(2, 0);
209
210
211/**
212 * Finalizes the current active node and returns the state to the parent node.
213 *
214 * @returns IPRT status code.
215 * @param hFdt The flattened devicetree handle.
216 */
217RTDECL(int) RTFdtNodeFinalize(RTFDT hFdt);
218
219
220/**
221 * Adds a single empty property with the given name to the current node acting as a boolean.
222 *
223 * @returns IPRT status code.
224 * @param hFdt The flattened devicetree handle.
225 * @param pszProperty The property name.
226 */
227RTDECL(int) RTFdtNodePropertyAddEmpty(RTFDT hFdt, const char *pszProperty);
228
229
230/**
231 * Adds a single u32 property with the given name to the current node.
232 *
233 * @returns IPRT status code.
234 * @param hFdt The flattened devicetree handle.
235 * @param pszProperty The property name.
236 * @param u32 The u32 value to set the property to.
237 */
238RTDECL(int) RTFdtNodePropertyAddU32(RTFDT hFdt, const char *pszProperty, uint32_t u32);
239
240
241/**
242 * Adds a single u64 property as two 32-bit cells with the given name to the current node.
243 *
244 * @returns IPRT status code.
245 * @param hFdt The flattened devicetree handle.
246 * @param pszProperty The property name.
247 * @param u64 The u64 value to set the property to.
248 */
249RTDECL(int) RTFdtNodePropertyAddU64(RTFDT hFdt, const char *pszProperty, uint64_t u64);
250
251
252/**
253 * Adds a string property with the given name to the current node.
254 *
255 * @returns IPRT status code.
256 * @param hFdt The flattened devicetree handle.
257 * @param pszProperty The property name.
258 * @param pszVal The string value to set the property to.
259 */
260RTDECL(int) RTFdtNodePropertyAddString(RTFDT hFdt, const char *pszProperty, const char *pszVal);
261
262
263/**
264 * Adds a property with a variable number of u32 items.
265 *
266 * @returns IPRT staus code.
267 * @param hFdt The flattened devicetree handle.
268 * @param pszProperty The property name.
269 * @param cCells The number of cells.
270 * @param ... The cell u32 data items.
271 */
272RTDECL(int) RTFdtNodePropertyAddCellsU32(RTFDT hFdt, const char *pszProperty, uint32_t cCells, ...);
273
274
275/**
276 * Adds a property with a variable number of u32 items.
277 *
278 * @returns IPRT staus code.
279 * @param hFdt The flattened devicetree handle.
280 * @param pszProperty The property name.
281 * @param cCells The number of cells.
282 * @param va The cell u32 data items.
283 */
284RTDECL(int) RTFdtNodePropertyAddCellsU32V(RTFDT hFdt, const char *pszProperty, uint32_t cCells, va_list va);
285
286
287/**
288 * Adds a property with a variable number of u32 items passed as an array.
289 *
290 * @returns IPRT staus code.
291 * @param hFdt The flattened devicetree handle.
292 * @param pszProperty The property name.
293 * @param cCells The number of cells.
294 * @param pau32Cells Pointer to the array of u32 cell data items.
295 */
296RTDECL(int) RTFdtNodePropertyAddCellsU32AsArray(RTFDT hFdt, const char *pszProperty, uint32_t cCells, uint32_t *pau32Cells);
297
298
299/**
300 * Adds a property with a variable number of u64 items (each as two 32-bit cells).
301 *
302 * @returns IPRT staus code.
303 * @param hFdt The flattened devicetree handle.
304 * @param pszProperty The property name.
305 * @param cCells The number of cells.
306 * @param ... The cell u64 data items.
307 */
308RTDECL(int) RTFdtNodePropertyAddCellsU64(RTFDT hFdt, const char *pszProperty, uint32_t cCells, ...);
309
310
311/**
312 * Adds a property with a variable number of u64 items (each as two 32-bit cells).
313 *
314 * @returns IPRT staus code.
315 * @param hFdt The flattened devicetree handle.
316 * @param pszProperty The property name.
317 * @param cCells The number of cells.
318 * @param va The cell u64 data items.
319 */
320RTDECL(int) RTFdtNodePropertyAddCellsU64V(RTFDT hFdt, const char *pszProperty, uint32_t cCells, va_list va);
321
322
323/**
324 * Adds the given string list property to the given FDT.
325 *
326 * @returns IPRT status code.
327 * @param hFdt The flattened devicetree handle.
328 * @param pszProperty The property name.
329 * @param cStrings How many strings are following.
330 * @param ... The strings.
331 */
332RTDECL(int) RTFdtNodePropertyAddStringList(RTFDT hFdt, const char *pszProperty, uint32_t cStrings, ...);
333
334
335/**
336 * Adds the given string list property to the given FDT.
337 *
338 * @returns IPRT status code.
339 * @param hFdt The flattened devicetree handle.
340 * @param pszProperty The property name.
341 * @param cStrings How many strings are following.
342 * @param va The strings.
343 */
344RTDECL(int) RTFdtNodePropertyAddStringListV(RTFDT hFdt, const char *pszProperty, uint32_t cStrings, va_list va);
345
346#endif /* IN_RING3 */
347
348/** @} */
349
350RT_C_DECLS_END
351
352#endif /* !IPRT_INCLUDED_fdt_h */
353
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette