VirtualBox

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

Last change on this file since 100339 was 100037, checked in by vboxsync, 19 months ago

Runtime/RTFdt: Add methods to add stringlist properties, bugref:10401

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 9.7 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 string property 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 pszVal The string value to set the property to.
248 */
249RTDECL(int) RTFdtNodePropertyAddString(RTFDT hFdt, const char *pszProperty, const char *pszVal);
250
251
252/**
253 * Adds a property with a variable number of u32 items.
254 *
255 * @returns IPRT staus code.
256 * @param hFdt The flattened devicetree handle.
257 * @param pszProperty The property name.
258 * @param cCells The number of cells.
259 * @param ... The cell u32 data items.
260 */
261RTDECL(int) RTFdtNodePropertyAddCellsU32(RTFDT hFdt, const char *pszProperty, uint32_t cCells, ...);
262
263
264/**
265 * Adds a property with a variable number of u32 items.
266 *
267 * @returns IPRT staus code.
268 * @param hFdt The flattened devicetree handle.
269 * @param pszProperty The property name.
270 * @param cCells The number of cells.
271 * @param va The cell u32 data items.
272 */
273RTDECL(int) RTFdtNodePropertyAddCellsU32V(RTFDT hFdt, const char *pszProperty, uint32_t cCells, va_list va);
274
275
276/**
277 * Adds the given string list property to the given FDT.
278 *
279 * @returns IPRT status code.
280 * @param hFdt The flattened devicetree handle.
281 * @param pszProperty The property name.
282 * @param cStrings How many strings are following.
283 * @param ... The strings.
284 */
285RTDECL(int) RTFdtNodePropertyAddStringList(RTFDT hFdt, const char *pszProperty, uint32_t cStrings, ...);
286
287
288/**
289 * Adds the given string list property to the given FDT.
290 *
291 * @returns IPRT status code.
292 * @param hFdt The flattened devicetree handle.
293 * @param pszProperty The property name.
294 * @param cStrings How many strings are following.
295 * @param va The strings.
296 */
297RTDECL(int) RTFdtNodePropertyAddStringListV(RTFDT hFdt, const char *pszProperty, uint32_t cStrings, va_list va);
298
299#endif /* IN_RING3 */
300
301/** @} */
302
303RT_C_DECLS_END
304
305#endif /* !IPRT_INCLUDED_fdt_h */
306
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