libfdt.h

/* SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) */
#ifndef LIBFDT_H
#define LIBFDT_H
/*
 * libfdt - Flat Device Tree manipulation
 * Copyright (C) 2006 David Gibson, IBM Corporation.
 */

#include <libfdt_env.h>
#include <fdt.h>

#define FDT_FIRST_SUPPORTED_VERSION 0x02
#define FDT_LAST_SUPPORTED_VERSION  0x11

/* Error codes: informative error codes */
#define FDT_ERR_NOTFOUND    1
    /* FDT_ERR_NOTFOUND: The requested node or property does not exist */
#define FDT_ERR_EXISTS      2
    /* FDT_ERR_EXISTS: Attempted to create a node or property which
     * already exists */
#define FDT_ERR_NOSPACE     3
    /* FDT_ERR_NOSPACE: Operation needed to expand the device
     * tree, but its buffer did not have sufficient space to
     * contain the expanded tree. Use fdt_open_into() to move the
     * device tree to a buffer with more space. */

/* Error codes: codes for bad parameters */
#define FDT_ERR_BADOFFSET   4
    /* FDT_ERR_BADOFFSET: Function was passed a structure block
     * offset which is out-of-bounds, or which points to an
     * unsuitable part of the structure for the operation. */
#define FDT_ERR_BADPATH     5
    /* FDT_ERR_BADPATH: Function was passed a badly formatted path
     * (e.g. missing a leading / for a function which requires an
     * absolute path) */
#define FDT_ERR_BADPHANDLE  6
    /* FDT_ERR_BADPHANDLE: Function was passed an invalid phandle.
     * This can be caused either by an invalid phandle property
     * length, or the phandle value was either 0 or -1, which are
     * not permitted. */
#define FDT_ERR_BADSTATE    7
    /* FDT_ERR_BADSTATE: Function was passed an incomplete device
     * tree created by the sequential-write functions, which is
     * not sufficiently complete for the requested operation. */

/* Error codes: codes for bad device tree blobs */
#define FDT_ERR_TRUNCATED   8
    /* FDT_ERR_TRUNCATED: FDT or a sub-block is improperly
     * terminated (overflows, goes outside allowed bounds, or
     * isn't properly terminated).  */
#define FDT_ERR_BADMAGIC    9
    /* FDT_ERR_BADMAGIC: Given "device tree" appears not to be a
     * device tree at all - it is missing the flattened device
     * tree magic number. */
#define FDT_ERR_BADVERSION  10
    /* FDT_ERR_BADVERSION: Given device tree has a version which
     * can't be handled by the requested operation.  For
     * read-write functions, this may mean that fdt_open_into() is
     * required to convert the tree to the expected version. */
#define FDT_ERR_BADSTRUCTURE    11
    /* FDT_ERR_BADSTRUCTURE: Given device tree has a corrupt
     * structure block or other serious error (e.g. misnested
     * nodes, or subnodes preceding properties). */
#define FDT_ERR_BADLAYOUT   12
    /* FDT_ERR_BADLAYOUT: For read-write functions, the given
     * device tree has it's sub-blocks in an order that the
     * function can't handle (memory reserve map, then structure,
     * then strings).  Use fdt_open_into() to reorganize the tree
     * into a form suitable for the read-write operations. */

/* "Can't happen" error indicating a bug in libfdt */
#define FDT_ERR_INTERNAL    13
    /* FDT_ERR_INTERNAL: libfdt has failed an internal assertion.
     * Should never be returned, if it is, it indicates a bug in
     * libfdt itself. */

/* Errors in device tree content */
#define FDT_ERR_BADNCELLS   14
    /* FDT_ERR_BADNCELLS: Device tree has a #address-cells, #size-cells
     * or similar property with a bad format or value */

#define FDT_ERR_BADVALUE    15
    /* FDT_ERR_BADVALUE: Device tree has a property with an unexpected
     * value. For example: a property expected to contain a string list
     * is not NUL-terminated within the length of its value. */

#define FDT_ERR_BADOVERLAY  16
    /* FDT_ERR_BADOVERLAY: The device tree overlay, while
     * correctly structured, cannot be applied due to some
     * unexpected or missing value, property or node. */

#define FDT_ERR_NOPHANDLES  17
    /* FDT_ERR_NOPHANDLES: The device tree doesn't have any
     * phandle available anymore without causing an overflow */

#define FDT_ERR_BADFLAGS    18
    /* FDT_ERR_BADFLAGS: The function was passed a flags field that
     * contains invalid flags or an invalid combination of flags. */

#define FDT_ERR_MAX     18

/* constants */
#define FDT_MAX_PHANDLE 0xfffffffe
    /* Valid values for phandles range from 1 to 2^32-2. */

/**********************************************************************/
/* Low-level functions (you probably don't need these)                */
/**********************************************************************/

#ifndef SWIG /* This function is not useful in Python */
const void *fdt_offset_ptr(const void *fdt, int offset, unsigned int checklen);
#endif
static inline void *fdt_offset_ptr_w(void *fdt, int offset, int checklen)
{
    return (void *)(uintptr_t)fdt_offset_ptr(fdt, offset, checklen);
}

uint32_t fdt_next_tag(const void *fdt, int offset, int *nextoffset);

/*
 * Alignment helpers:
 *     These helpers access words from a device tree blob.  They're
 *     built to work even with unaligned pointers on platforms (ike
 *     ARM) that don't like unaligned loads and stores
 */

static inline uint32_t fdt32_ld(const fdt32_t *p)
{
    const uint8_t *bp = (const uint8_t *)p;

    return ((uint32_t)bp[0] << 24)
        | ((uint32_t)bp[1] << 16)
        | ((uint32_t)bp[2] << 8)
        | bp[3];
}

static inline void fdt32_st(void *property, uint32_t value)
{
    uint8_t *bp = (uint8_t *)property;

    bp[0] = value >> 24;
    bp[1] = (value >> 16) & 0xff;
    bp[2] = (value >> 8) & 0xff;
    bp[3] = value & 0xff;
}

static inline uint64_t fdt64_ld(const fdt64_t *p)
{
    const uint8_t *bp = (const uint8_t *)p;

    return ((uint64_t)bp[0] << 56)
        | ((uint64_t)bp[1] << 48)
        | ((uint64_t)bp[2] << 40)
        | ((uint64_t)bp[3] << 32)
        | ((uint64_t)bp[4] << 24)
        | ((uint64_t)bp[5] << 16)
        | ((uint64_t)bp[6] << 8)
        | bp[7];
}

static inline void fdt64_st(void *property, uint64_t value)
{
    uint8_t *bp = (uint8_t *)property;

    bp[0] = value >> 56;
    bp[1] = (value >> 48) & 0xff;
    bp[2] = (value >> 40) & 0xff;
    bp[3] = (value >> 32) & 0xff;
    bp[4] = (value >> 24) & 0xff;
    bp[5] = (value >> 16) & 0xff;
    bp[6] = (value >> 8) & 0xff;
    bp[7] = value & 0xff;
}

/**********************************************************************/
/* Traversal functions                                                */
/**********************************************************************/

int fdt_next_node(const void *fdt, int offset, int *depth);

int fdt_first_subnode(const void *fdt, int offset);

int fdt_next_subnode(const void *fdt, int offset);

#define fdt_for_each_subnode(node, fdt, parent)     \
    for (node = fdt_first_subnode(fdt, parent); \
         node >= 0;                 \
         node = fdt_next_subnode(fdt, node))

/**********************************************************************/
/* General functions                                                  */
/**********************************************************************/
#define fdt_get_header(fdt, field) \
    (fdt32_ld(&((const struct fdt_header *)(fdt))->field))
#define fdt_magic(fdt)          (fdt_get_header(fdt, magic))
#define fdt_totalsize(fdt)      (fdt_get_header(fdt, totalsize))
#define fdt_off_dt_struct(fdt)      (fdt_get_header(fdt, off_dt_struct))
#define fdt_off_dt_strings(fdt)     (fdt_get_header(fdt, off_dt_strings))
#define fdt_off_mem_rsvmap(fdt)     (fdt_get_header(fdt, off_mem_rsvmap))
#define fdt_version(fdt)        (fdt_get_header(fdt, version))
#define fdt_last_comp_version(fdt)  (fdt_get_header(fdt, last_comp_version))
#define fdt_boot_cpuid_phys(fdt)    (fdt_get_header(fdt, boot_cpuid_phys))
#define fdt_size_dt_strings(fdt)    (fdt_get_header(fdt, size_dt_strings))
#define fdt_size_dt_struct(fdt)     (fdt_get_header(fdt, size_dt_struct))

#define fdt_set_hdr_(name) \
    static inline void fdt_set_##name(void *fdt, uint32_t val) \
    { \
        struct fdt_header *fdth = (struct fdt_header *)fdt; \
        fdth->name = cpu_to_fdt32(val); \
    }
fdt_set_hdr_(magic);
fdt_set_hdr_(totalsize);
fdt_set_hdr_(off_dt_struct);
fdt_set_hdr_(off_dt_strings);
fdt_set_hdr_(off_mem_rsvmap);
fdt_set_hdr_(version);
fdt_set_hdr_(last_comp_version);
fdt_set_hdr_(boot_cpuid_phys);
fdt_set_hdr_(size_dt_strings);
fdt_set_hdr_(size_dt_struct);
#undef fdt_set_hdr_

size_t fdt_header_size(const void *fdt);

size_t fdt_header_size_(uint32_t version);

int fdt_check_header(const void *fdt);

int fdt_move(const void *fdt, void *buf, int bufsize);

/**********************************************************************/
/* Read-only functions                                                */
/**********************************************************************/

int fdt_check_full(const void *fdt, size_t bufsize);

const char *fdt_get_string(const void *fdt, int stroffset, int *lenp);

const char *fdt_string(const void *fdt, int stroffset);

int fdt_find_max_phandle(const void *fdt, uint32_t *phandle);

static inline uint32_t fdt_get_max_phandle(const void *fdt)
{
    uint32_t phandle;
    int err;

    err = fdt_find_max_phandle(fdt, &phandle);
    if (err < 0)
        return (uint32_t)-1;

    return phandle;
}

int fdt_generate_phandle(const void *fdt, uint32_t *phandle);

int fdt_num_mem_rsv(const void *fdt);

int fdt_get_mem_rsv(const void *fdt, int n, uint64_t *address, uint64_t *size);

#ifndef SWIG /* Not available in Python */
int fdt_subnode_offset_namelen(const void *fdt, int parentoffset,
                   const char *name, int namelen);
#endif

int fdt_subnode_offset(const void *fdt, int parentoffset, const char *name);

#ifndef SWIG /* Not available in Python */
int fdt_path_offset_namelen(const void *fdt, const char *path, int namelen);
#endif

int fdt_path_offset(const void *fdt, const char *path);

const char *fdt_get_name(const void *fdt, int nodeoffset, int *lenp);

int fdt_first_property_offset(const void *fdt, int nodeoffset);

int fdt_next_property_offset(const void *fdt, int offset);

#define fdt_for_each_property_offset(property, fdt, node)   \
    for (property = fdt_first_property_offset(fdt, node);   \
         property >= 0;                 \
         property = fdt_next_property_offset(fdt, property))

const struct fdt_property *fdt_get_property_by_offset(const void *fdt,
                              int offset,
                              int *lenp);

#ifndef SWIG /* Not available in Python */
const struct fdt_property *fdt_get_property_namelen(const void *fdt,
                            int nodeoffset,
                            const char *name,
                            int namelen, int *lenp);
#endif

const struct fdt_property *fdt_get_property(const void *fdt, int nodeoffset,
                        const char *name, int *lenp);
static inline struct fdt_property *fdt_get_property_w(void *fdt, int nodeoffset,
                              const char *name,
                              int *lenp)
{
    return (struct fdt_property *)(uintptr_t)
        fdt_get_property(fdt, nodeoffset, name, lenp);
}

#ifndef SWIG /* This function is not useful in Python */
const void *fdt_getprop_by_offset(const void *fdt, int offset,
                  const char **namep, int *lenp);
#endif

#ifndef SWIG /* Not available in Python */
const void *fdt_getprop_namelen(const void *fdt, int nodeoffset,
                const char *name, int namelen, int *lenp);
static inline void *fdt_getprop_namelen_w(void *fdt, int nodeoffset,
                      const char *name, int namelen,
                      int *lenp)
{
    return (void *)(uintptr_t)fdt_getprop_namelen(fdt, nodeoffset, name,
                              namelen, lenp);
}
#endif

const void *fdt_getprop(const void *fdt, int nodeoffset,
            const char *name, int *lenp);
static inline void *fdt_getprop_w(void *fdt, int nodeoffset,
                  const char *name, int *lenp)
{
    return (void *)(uintptr_t)fdt_getprop(fdt, nodeoffset, name, lenp);
}

uint32_t fdt_get_phandle(const void *fdt, int nodeoffset);

#ifndef SWIG /* Not available in Python */
const char *fdt_get_alias_namelen(const void *fdt,
                  const char *name, int namelen);
#endif

const char *fdt_get_alias(const void *fdt, const char *name);

int fdt_get_path(const void *fdt, int nodeoffset, char *buf, int buflen);

int fdt_supernode_atdepth_offset(const void *fdt, int nodeoffset,
                 int supernodedepth, int *nodedepth);

int fdt_node_depth(const void *fdt, int nodeoffset);

int fdt_parent_offset(const void *fdt, int nodeoffset);

int fdt_node_offset_by_prop_value(const void *fdt, int startoffset,
                  const char *propname,
                  const void *propval, int proplen);

int fdt_node_offset_by_phandle(const void *fdt, uint32_t phandle);

int fdt_node_check_compatible(const void *fdt, int nodeoffset,
                  const char *compatible);

int fdt_node_offset_by_compatible(const void *fdt, int startoffset,
                  const char *compatible);

int fdt_stringlist_contains(const char *strlist, int listlen, const char *str);

int fdt_stringlist_count(const void *fdt, int nodeoffset, const char *property);

int fdt_stringlist_search(const void *fdt, int nodeoffset, const char *property,
              const char *string);

const char *fdt_stringlist_get(const void *fdt, int nodeoffset,
                   const char *property, int index,
                   int *lenp);

/**********************************************************************/
/* Read-only functions (addressing related)                           */
/**********************************************************************/

#define FDT_MAX_NCELLS      4

int fdt_address_cells(const void *fdt, int nodeoffset);

int fdt_size_cells(const void *fdt, int nodeoffset);


/**********************************************************************/
/* Write-in-place functions                                           */
/**********************************************************************/

#ifndef SWIG /* Not available in Python */
int fdt_setprop_inplace_namelen_partial(void *fdt, int nodeoffset,
                    const char *name, int namelen,
                    uint32_t idx, const void *val,
                    int len);
#endif

#ifndef SWIG /* Not available in Python */
int fdt_setprop_inplace(void *fdt, int nodeoffset, const char *name,
            const void *val, int len);
#endif

static inline int fdt_setprop_inplace_u32(void *fdt, int nodeoffset,
                      const char *name, uint32_t val)
{
    fdt32_t tmp = cpu_to_fdt32(val);
    return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));
}

static inline int fdt_setprop_inplace_u64(void *fdt, int nodeoffset,
                      const char *name, uint64_t val)
{
    fdt64_t tmp = cpu_to_fdt64(val);
    return fdt_setprop_inplace(fdt, nodeoffset, name, &tmp, sizeof(tmp));
}

static inline int fdt_setprop_inplace_cell(void *fdt, int nodeoffset,
                       const char *name, uint32_t val)
{
    return fdt_setprop_inplace_u32(fdt, nodeoffset, name, val);
}

int fdt_nop_property(void *fdt, int nodeoffset, const char *name);

int fdt_nop_node(void *fdt, int nodeoffset);

/**********************************************************************/
/* Sequential write functions                                         */
/**********************************************************************/

/* fdt_create_with_flags flags */
#define FDT_CREATE_FLAG_NO_NAME_DEDUP 0x1
    /* FDT_CREATE_FLAG_NO_NAME_DEDUP: Do not try to de-duplicate property
     * names in the fdt. This can result in faster creation times, but
     * a larger fdt. */

#define FDT_CREATE_FLAGS_ALL    (FDT_CREATE_FLAG_NO_NAME_DEDUP)

int fdt_create_with_flags(void *buf, int bufsize, uint32_t flags);

int fdt_create(void *buf, int bufsize);

int fdt_resize(void *fdt, void *buf, int bufsize);
int fdt_add_reservemap_entry(void *fdt, uint64_t addr, uint64_t size);
int fdt_finish_reservemap(void *fdt);
int fdt_begin_node(void *fdt, const char *name);
int fdt_property(void *fdt, const char *name, const void *val, int len);
static inline int fdt_property_u32(void *fdt, const char *name, uint32_t val)
{
    fdt32_t tmp = cpu_to_fdt32(val);
    return fdt_property(fdt, name, &tmp, sizeof(tmp));
}
static inline int fdt_property_u64(void *fdt, const char *name, uint64_t val)
{
    fdt64_t tmp = cpu_to_fdt64(val);
    return fdt_property(fdt, name, &tmp, sizeof(tmp));
}

#ifndef SWIG /* Not available in Python */
static inline int fdt_property_cell(void *fdt, const char *name, uint32_t val)
{
    return fdt_property_u32(fdt, name, val);
}
#endif

int fdt_property_placeholder(void *fdt, const char *name, int len, void **valp);

#define fdt_property_string(fdt, name, str) \
    fdt_property(fdt, name, str, strlen(str)+1)
int fdt_end_node(void *fdt);
int fdt_finish(void *fdt);

/**********************************************************************/
/* Read-write functions                                               */
/**********************************************************************/

int fdt_create_empty_tree(void *buf, int bufsize);
int fdt_open_into(const void *fdt, void *buf, int bufsize);
int fdt_pack(void *fdt);

int fdt_add_mem_rsv(void *fdt, uint64_t address, uint64_t size);

int fdt_del_mem_rsv(void *fdt, int n);

int fdt_set_name(void *fdt, int nodeoffset, const char *name);

int fdt_setprop(void *fdt, int nodeoffset, const char *name,
        const void *val, int len);

int fdt_setprop_placeholder(void *fdt, int nodeoffset, const char *name,
                int len, void **prop_data);

static inline int fdt_setprop_u32(void *fdt, int nodeoffset, const char *name,
                  uint32_t val)
{
    fdt32_t tmp = cpu_to_fdt32(val);
    return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
}

static inline int fdt_setprop_u64(void *fdt, int nodeoffset, const char *name,
                  uint64_t val)
{
    fdt64_t tmp = cpu_to_fdt64(val);
    return fdt_setprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
}

static inline int fdt_setprop_cell(void *fdt, int nodeoffset, const char *name,
                   uint32_t val)
{
    return fdt_setprop_u32(fdt, nodeoffset, name, val);
}

#define fdt_setprop_string(fdt, nodeoffset, name, str) \
    fdt_setprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)


#define fdt_setprop_empty(fdt, nodeoffset, name) \
    fdt_setprop((fdt), (nodeoffset), (name), NULL, 0)

int fdt_appendprop(void *fdt, int nodeoffset, const char *name,
           const void *val, int len);

static inline int fdt_appendprop_u32(void *fdt, int nodeoffset,
                     const char *name, uint32_t val)
{
    fdt32_t tmp = cpu_to_fdt32(val);
    return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
}

static inline int fdt_appendprop_u64(void *fdt, int nodeoffset,
                     const char *name, uint64_t val)
{
    fdt64_t tmp = cpu_to_fdt64(val);
    return fdt_appendprop(fdt, nodeoffset, name, &tmp, sizeof(tmp));
}

static inline int fdt_appendprop_cell(void *fdt, int nodeoffset,
                      const char *name, uint32_t val)
{
    return fdt_appendprop_u32(fdt, nodeoffset, name, val);
}

#define fdt_appendprop_string(fdt, nodeoffset, name, str) \
    fdt_appendprop((fdt), (nodeoffset), (name), (str), strlen(str)+1)

int fdt_appendprop_addrrange(void *fdt, int parent, int nodeoffset,
                 const char *name, uint64_t addr, uint64_t size);

int fdt_delprop(void *fdt, int nodeoffset, const char *name);

#ifndef SWIG /* Not available in Python */
int fdt_add_subnode_namelen(void *fdt, int parentoffset,
                const char *name, int namelen);
#endif

int fdt_add_subnode(void *fdt, int parentoffset, const char *name);

int fdt_del_node(void *fdt, int nodeoffset);

int fdt_overlay_apply(void *fdt, void *fdto);

/**********************************************************************/
/* Debugging / informational functions                                */
/**********************************************************************/

const char *fdt_strerror(int errval);

#endif /* LIBFDT_H */