devicetree.h

Go to the documentation of this file.

/*
 * This file is part of the Ultibo project, https://ultibo.org/
 *
 * The MIT License (MIT)
 *
 * Copyright (c) 2026 Garry Wood <garry@softoz.com.au>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
#ifndef _ULTIBO_DEVICETREE_H
#define _ULTIBO_DEVICETREE_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "ultibo/globaltypes.h"
#include "ultibo/globalconst.h"
#include "ultibo/platform.h"

#define DTB_MAGIC   0xD00DFEED

#define DTB_VERSION_17  17
#define DTB_VERSION_16  16
 
#define DTB_VERSION_CURRENT DTB_VERSION_17
#define DTB_VERSION_COMPATIBLE  DTB_VERSION_16

#define DTB_BEGIN_NODE  0x00000001 
#define DTB_END_NODE    0x00000002 
#define DTB_PROP    0x00000003 
#define DTB_NOP 0x00000004 
#define DTB_END 0x00000009 

#define DTB_NODE_OFFSET 4 
#define DTB_PROPERTY_OFFSET 12 

#define DTB_STRUCTURE_ALIGNMENT 4
#define DTB_RESERVATION_ALIGNMENT   8

#define DTB_NODE_ROOT   "/"
#define DTB_NODE_CPUS   "cpus"
#define DTB_NODE_MEMORY "memory"
#define DTB_NODE_CHOSEN "chosen"
#define DTB_NODE_ALIASES    "aliases"
#define DTB_NODE_SYMBOLS    "__symbols__"
#define DTB_NODE_OVERRIDES  "__overrides__"

#define DTB_PATH_SEPARATOR  "/"

#define DTB_TYPE_UNKNOWN    0
#define DTB_TYPE_EMPTY  1 
#define DTB_TYPE_U32    2 
#define DTB_TYPE_U64    3 
#define DTB_TYPE_STRING 4 
#define DTB_TYPE_ENCODED_ARRAY  5 
#define DTB_TYPE_PHANDLE    6 
#define DTB_TYPE_STRINGLIST 7 

#define DTB_PROPERTY_COMPATIBLE "compatible" 
#define DTB_PROPERTY_MODEL  "model" 
#define DTB_PROPERTY_PHANDLE    "phandle" 
#define DTB_PROPERTY_STATUS "status" 
#define DTB_PROPERTY_ADDRESS_CELLS  "#address-cells" 
#define DTB_PROPERTY_SIZE_CELLS "#size-cells" 
#define DTB_PROPERTY_REG    "reg" 
#define DTB_PROPERTY_VIRTUAL_REG    "virtual-reg" 
#define DTB_PROPERTY_RANGES "ranges" 
#define DTB_PROPERTY_DMA_RANGES "dma-ranges" 
#define DTB_PROPERTY_NAME   "name" 
#define DTB_PROPERTY_DEVICE_TYPE    "device_type" 

#define DTB_PROPERTY_INTERRUPTS "interrupts" 
#define DTB_PROPERTY_INTERRUPT_PARENT   "interrupt-parent" 
#define DTB_PROPERTY_INTERRUPTS_EXTENDED    "interrupts-extended" 

#define DTB_PROPERTY_INTERRUPT_CELLS    "#interrupt-cells" 
#define DTB_PROPERTY_INTERRUPT_CONTROLLER   "interrupt-controller" 

#define DTB_PROPERTY_INTERRUPT_MAP  "interrupt-map" 
#define DTB_PROPERTY_INTERRUPT_MAP_MASK "interrupt-map-mask" 

#define DTB_PROPERTY_INITIAL_MAPPED_AREA    "initial-mapped-area" 

#define DTB_PROPERTY_BOOTARGS   "bootargs" 
#define DTB_PROPERTY_STDOUT_PATH    "stdout-path" 
#define DTB_PROPERTY_STDIN_PATH "stdin-path" 
#define DTB_PROPERTY_INITRD_START   "initrd-start" 
#define DTB_PROPERTY_INITRD_END "initrd-end" 

#define DTB_PROPERTY_CLOCK_FREQUENCY    "clock-frequency" 
#define DTB_PROPERTY_TIMEBASE_FREQUENCY "timebase-frequency" 
#define DTB_PROPERTY_ENABLE_METHOD  "enable-method" 
#define DTB_PROPERTY_CPU_RELEASE_ADDR   "cpu-release-addr" 
 
#define DTB_PROPERTY_POWER_ISA_VERSION  "power-isa-version" 
#define DTB_PROPERTY_CACHE_OP_BLOCK_SIZE    "cache-op-block-size" 
#define DTB_PROPERTY_RESERVATION_GRANULE_SIZE   "reservation-granule-size" 
#define DTB_PROPERTY_MMU_TYPE   "mmu-type" 
 
#define DTB_PROPERTY_TLB_SPLIT  "tlb-split" 
#define DTB_PROPERTY_TLB_SIZE   "tlb-size" 
#define DTB_PROPERTY_TLB_SETS   "tlb-sets" 
#define DTB_PROPERTY_D_TLB_SIZE "d-tlb-size" 
#define DTB_PROPERTY_D_TLB_SETS "d-tlb-sets" 
#define DTB_PROPERTY_I_TLB_SIZE "i-tlb-size" 
#define DTB_PROPERTY_I_TLB_SETS "i-tlb-sets" 
 
#define DTB_PROPERTY_CACHE_UNIFIED  "cache-unified" 
#define DTB_PROPERTY_CACHE_SIZE "cache-size" 
#define DTB_PROPERTY_CACHE_SETS "cache-sets" 
#define DTB_PROPERTY_CACHE_BLOCK_SIZE   "cache-block-size" 
#define DTB_PROPERTY_CACHE_LINE_SIZE    "cache-line-size" 
#define DTB_PROPERTY_I_CACHE_SIZE   "i-cache-size" 
#define DTB_PROPERTY_I_CACHE_SETS   "i-cache-sets" 
#define DTB_PROPERTY_I_CACHE_BLOCK_SIZE "i-cache-block-size" 
#define DTB_PROPERTY_I_CACHE_LINE_SIZE  "i-cache-line-size" 
#define DTB_PROPERTY_D_CACHE_SIZE   "d-cache-size" 
#define DTB_PROPERTY_D_CACHE_SETS   "d-cache-sets" 
#define DTB_PROPERTY_D_CACHE_BLOCK_SIZE "d-cache-block-size" 
#define DTB_PROPERTY_D_CACHE_LINE_SIZE  "d-cache-line-size" 
#define DTB_PROPERTY_NEXT_LEVEL_CACHE   "next-level-cache" 
 
#define DTB_PROPERTY_CACHE_LEVEL    "cache-level" 

#define DTB_PROPERTY_SERIAL_NUMBER  "serial-number" 
#define DTB_PROPERTY_ALLOC_RANGES   "alloc-ranges" 
#define DTB_PROPERTY_RESETS "resets" 
#define DTB_PROPERTY_CLOCK_CELLS    "#clock-cells" 
#define DTB_PROPERTY_LINUX_INITRD_START "linux,initrd-start" 
#define DTB_PROPERTY_LINUX_INITRD_END   "linux,initrd-end" 

#define DTB_MAX_PROPERTY_TYPE   60

typedef struct _DTB_HEADER DTB_HEADER;
struct _DTB_HEADER
{
    uint32_t magic; 
    uint32_t totalsize; 
    uint32_t structureoffset; 
    uint32_t stringsoffset; 
    uint32_t reservationoffset; 
    uint32_t version; 
    uint32_t compatibleversion; 
    uint32_t bootcpuid; 
    uint32_t stringssize; 
    uint32_t structuresize; 
} PACKED;

typedef struct _DTB_RESERVATION DTB_RESERVATION;
struct _DTB_RESERVATION
{
    uint64_t address; 
    uint64_t size; 
} PACKED;

typedef struct _DTB_NODE DTB_NODE;
struct _DTB_NODE
{
    uint32_t token; 
    char name[1]; 
} PACKED;

typedef struct _DTB_PROPERTY DTB_PROPERTY;
struct _DTB_PROPERTY
{
    uint32_t token; 
    uint32_t valuelength; 
    uint32_t nameoffset; 
    uint8_t value[1]; 
} PACKED;
 

typedef struct _DTB_PROPERTY_CHAR DTB_PROPERTY_CHAR;
struct _DTB_PROPERTY_CHAR
{
    uint32_t token; 
    uint32_t valuelength; 
    uint32_t nameoffset; 
    char value[1]; 
} PACKED;
 

typedef struct _DTB_PROPERTY_LONGWORD DTB_PROPERTY_LONGWORD;
struct _DTB_PROPERTY_LONGWORD
{
    uint32_t token; 
    uint32_t valuelength; 
    uint32_t nameoffset; 
    uint32_t value[1]; 
} PACKED;
 

typedef struct _DTB_PROPERTY_QUADWORD DTB_PROPERTY_QUADWORD;
struct _DTB_PROPERTY_QUADWORD
{
    uint32_t token; 
    uint32_t valuelength; 
    uint32_t nameoffset; 
    uint64_t value[1]; 
} PACKED;

typedef void STDCALL (*dtb_log_output_cb)(const char *text, void *data);
typedef char * STDCALL (*dtb_decode_value_cb)(HANDLE node, HANDLE handle, void *value, uint32_t size, void *data);


BOOL STDCALL device_tree_validate(size_t address, uint32_t *size);

HANDLE STDCALL device_tree_next_node(HANDLE parent, HANDLE previous);

HANDLE STDCALL device_tree_next_property(HANDLE node, HANDLE previous);

HANDLE STDCALL device_tree_get_node(const char *path, HANDLE parent);

HANDLE STDCALL device_tree_get_property(HANDLE node, const char *name);

uint32_t STDCALL device_tree_get_node_name(HANDLE handle, char *name, uint32_t len);

uint32_t STDCALL device_tree_split_node_name(HANDLE handle, char *nodename, uint32_t namelen, char *unitaddress, uint32_t addresslen);

HANDLE STDCALL device_tree_get_node_parent(HANDLE handle);

BOOL STDCALL device_tree_get_node_reg_cells(HANDLE handle, uint32_t *address, uint32_t *size);

BOOL STDCALL device_tree_get_node_range_cells(HANDLE handle, uint32_t *parentaddress, uint32_t *nodeaddress, uint32_t *nodesize);

uint32_t STDCALL device_tree_get_property_name(HANDLE handle, char *name, uint32_t len);

uint32_t STDCALL device_tree_split_property_name(HANDLE handle, char *uniqueprefix, uint32_t prefixlen, char *propertyname, uint32_t namelen);

void * STDCALL device_tree_get_property_value(HANDLE handle);

uint32_t STDCALL device_tree_get_property_length(HANDLE handle);

uint32_t STDCALL device_tree_get_property_string(HANDLE handle, char *string, uint32_t len);

uint32_t STDCALL device_tree_get_property_longword(HANDLE handle);

uint64_t STDCALL device_tree_get_property_quadword(HANDLE handle);


char * STDCALL device_tree_get_boot_args(void);

BOOL STDCALL device_tree_get_ramdisk(size_t *address, uint64_t *size);

#if defined (__i386__) || defined (__arm__)
BOOL STDCALL device_tree_get_memory(uint32_t index, uint32_t *range, size_t *address, uint64_t *size);
#else
BOOL STDCALL device_tree_get_memory(uint32_t index, size_t *address, uint64_t *size);
#endif

BOOL STDCALL device_tree_get_reservation(uint32_t index, size_t *address, uint64_t *size);

uint32_t STDCALL device_tree_log_tree(void);

uint32_t STDCALL device_tree_log_tree_ex(HANDLE node, dtb_log_output_cb output, dtb_decode_value_cb decode, void *data);
 
#ifdef __cplusplus
}
#endif
 
#endif // _ULTIBO_DEVICETREE_H