/** @file * IPRT - Flattened Devicetree parser and generator API. */ /* * Copyright (C) 2023-2024 Oracle and/or its affiliates. * * This file is part of VirtualBox base platform packages, as * available from https://www.virtualbox.org. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation, in version 3 of the * License. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, see . * * The contents of this file may alternatively be used under the terms * of the Common Development and Distribution License Version 1.0 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included * in the VirtualBox distribution, in which case the provisions of the * CDDL are applicable instead of those of the GPL. * * You may elect to license modified versions of this file under the * terms and conditions of either the GPL or the CDDL or both. * * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0 */ #ifndef IPRT_INCLUDED_fdt_h #define IPRT_INCLUDED_fdt_h #ifndef RT_WITHOUT_PRAGMA_ONCE # pragma once #endif #include #include #include RT_C_DECLS_BEGIN /** @defgroup grp_rt_fdt RTFdt - Flattened Devicetree parser and generator API. * @ingroup grp_rt * @{ */ /** * Flattened device tree type. */ typedef enum RTFDTTYPE { /** The invalid output type. */ RTFDTTYPE_INVALID = 0, /** Output is an UTF-8 DTS. */ RTFDTTYPE_DTS, /** Output is the flattened devicetree binary format. */ RTFDTTYPE_DTB, /** Usual 32-bit hack. */ RTFDTTYPE_32BIT_HACK = 0x7fffffff } RTFDTTYPE; #ifdef IN_RING3 /** * Creates a new empty flattened devicetree returning the handle. * * @returns IPRT status code. * @param phFdt Where to store the handle to the flattened devicetree on success. */ RTDECL(int) RTFdtCreateEmpty(PRTFDT phFdt); /** * Creates a flattened device tree from the given VFS file. * * @returns IPRT status code. * @param phFdt Where to store the handle to the flattened devicetree on success. * @param hVfsIos The VFS I/O stream handle to read the devicetree from. * @param enmInType The input type of the flattened devicetree. * @param pErrInfo Where to return additional error information. */ RTDECL(int) RTFdtCreateFromVfsIoStrm(PRTFDT phFdt, RTVFSIOSTREAM hVfsIos, RTFDTTYPE enmInType, PRTERRINFO pErrInfo); /** * Creates a flattened device tree from the given filename. * * @returns IPRT status code. * @param phFdt Where to store the handle to the flattened devicetree on success. * @param pszFilename The filename to read the devicetree from. * @param enmInType The input type of the flattened devicetree. * @param pErrInfo Where to return additional error information. */ RTDECL(int) RTFdtCreateFromFile(PRTFDT phFdt, const char *pszFilename, RTFDTTYPE enmInType, PRTERRINFO pErrInfo); /** * Destroys the given flattened devicetree. * * @param hFdt The flattened devicetree handle to destroy. */ RTDECL(void) RTFdtDestroy(RTFDT hFdt); /** * Finalizes the given FDT for writing out. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. */ RTDECL(int) RTFdtFinalize(RTFDT hFdt); /** * Allocates a new phandle serving as a unique identifer within the given FDT. * * @returns The phandle value * @retval UINT32_MAX in case the given FDT handle is invalid or the FDT is out of free phandle values. * @param hFdt The flattened devicetree handle to destroy. */ RTDECL(uint32_t) RTFdtPHandleAllocate(RTFDT hFdt); /** * Dumps the given flattened devicetree to the given VFS file. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. * @param enmOutType The output type. * @param fFlags Flags controlling the output, MBZ. * @param hVfsIos The VFS I/O stream handle to dump the DTS to. * @param pErrInfo Where to return additional error information. */ RTDECL(int) RTFdtDumpToVfsIoStrm(RTFDT hFdt, RTFDTTYPE enmOutType, uint32_t fFlags, RTVFSIOSTREAM hVfsIos, PRTERRINFO pErrInfo); /** * Dumps the given flattened devicetree to the given file. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. * @param enmOutType The output type. * @param fFlags Flags controlling the output, MBZ. * @param pszFilename The filename to dump to. * @param pErrInfo Where to return additional error information. */ RTDECL(int) RTFdtDumpToFile(RTFDT hFdt, RTFDTTYPE enmOutType, uint32_t fFlags, const char *pszFilename, PRTERRINFO pErrInfo); /** * Adds a new memory reservation to the given FDT instance. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. * @param PhysAddrStart The physical start address of the reservation. * @param cbArea Size of the area in bytes. */ RTDECL(int) RTFdtAddMemoryReservation(RTFDT hFdt, uint64_t PhysAddrStart, uint64_t cbArea); /** * Sets the physical boot CPU id for the given FDT instance. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. * @param idPhysBootCpu The physical boot CPU ID. */ RTDECL(int) RTFdtSetPhysBootCpuId(RTFDT hFdt, uint32_t idPhysBootCpu); /** * Adds a new node with the given name under the currently active one. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. * @param pszName The name of the node. */ RTDECL(int) RTFdtNodeAdd(RTFDT hFdt, const char *pszName); /** * Adds a new node with the given name under the currently active one. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. * @param pszNameFmt The name of the node as a format string. * @param ... The format arguments. */ RTDECL(int) RTFdtNodeAddF(RTFDT hFdt, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(2, 3); /** * Adds a new node with the given name under the currently active one. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. * @param pszNameFmt The name of the node as a format string. * @param va The format arguments. */ RTDECL(int) RTFdtNodeAddV(RTFDT hFdt, const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(2, 0); /** * Finalizes the current active node and returns the state to the parent node. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. */ RTDECL(int) RTFdtNodeFinalize(RTFDT hFdt); /** * Adds a single empty property with the given name to the current node acting as a boolean. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. * @param pszProperty The property name. */ RTDECL(int) RTFdtNodePropertyAddEmpty(RTFDT hFdt, const char *pszProperty); /** * Adds a single u32 property with the given name to the current node. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. * @param pszProperty The property name. * @param u32 The u32 value to set the property to. */ RTDECL(int) RTFdtNodePropertyAddU32(RTFDT hFdt, const char *pszProperty, uint32_t u32); /** * Adds a single u64 property as two 32-bit cells with the given name to the current node. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. * @param pszProperty The property name. * @param u64 The u64 value to set the property to. */ RTDECL(int) RTFdtNodePropertyAddU64(RTFDT hFdt, const char *pszProperty, uint64_t u64); /** * Adds a string property with the given name to the current node. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. * @param pszProperty The property name. * @param pszVal The string value to set the property to. */ RTDECL(int) RTFdtNodePropertyAddString(RTFDT hFdt, const char *pszProperty, const char *pszVal); /** * Adds a property with a variable number of u32 items. * * @returns IPRT staus code. * @param hFdt The flattened devicetree handle. * @param pszProperty The property name. * @param cCells The number of cells. * @param ... The cell u32 data items. */ RTDECL(int) RTFdtNodePropertyAddCellsU32(RTFDT hFdt, const char *pszProperty, uint32_t cCells, ...); /** * Adds a property with a variable number of u32 items. * * @returns IPRT staus code. * @param hFdt The flattened devicetree handle. * @param pszProperty The property name. * @param cCells The number of cells. * @param va The cell u32 data items. */ RTDECL(int) RTFdtNodePropertyAddCellsU32V(RTFDT hFdt, const char *pszProperty, uint32_t cCells, va_list va); /** * Adds a property with a variable number of u32 items passed as an array. * * @returns IPRT staus code. * @param hFdt The flattened devicetree handle. * @param pszProperty The property name. * @param cCells The number of cells. * @param pau32Cells Pointer to the array of u32 cell data items. */ RTDECL(int) RTFdtNodePropertyAddCellsU32AsArray(RTFDT hFdt, const char *pszProperty, uint32_t cCells, uint32_t *pau32Cells); /** * Adds a property with a variable number of u64 items (each as two 32-bit cells). * * @returns IPRT staus code. * @param hFdt The flattened devicetree handle. * @param pszProperty The property name. * @param cCells The number of cells. * @param ... The cell u64 data items. */ RTDECL(int) RTFdtNodePropertyAddCellsU64(RTFDT hFdt, const char *pszProperty, uint32_t cCells, ...); /** * Adds a property with a variable number of u64 items (each as two 32-bit cells). * * @returns IPRT staus code. * @param hFdt The flattened devicetree handle. * @param pszProperty The property name. * @param cCells The number of cells. * @param va The cell u64 data items. */ RTDECL(int) RTFdtNodePropertyAddCellsU64V(RTFDT hFdt, const char *pszProperty, uint32_t cCells, va_list va); /** * Adds the given string list property to the given FDT. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. * @param pszProperty The property name. * @param cStrings How many strings are following. * @param ... The strings. */ RTDECL(int) RTFdtNodePropertyAddStringList(RTFDT hFdt, const char *pszProperty, uint32_t cStrings, ...); /** * Adds the given string list property to the given FDT. * * @returns IPRT status code. * @param hFdt The flattened devicetree handle. * @param pszProperty The property name. * @param cStrings How many strings are following. * @param va The strings. */ RTDECL(int) RTFdtNodePropertyAddStringListV(RTFDT hFdt, const char *pszProperty, uint32_t cStrings, va_list va); #endif /* IN_RING3 */ /** @} */ RT_C_DECLS_END #endif /* !IPRT_INCLUDED_fdt_h */