usr.bin/dtc/fdt.hh

   1 /*-
   2  * Copyright (c) 2013 David Chisnall
   3  * All rights reserved.
   4  *
   5  * This software was developed by SRI International and the University of
   6  * Cambridge Computer Laboratory under DARPA/AFRL contract (FA8750-10-C-0237)
   7  * ("CTSRD"), as part of the DARPA CRASH research programme.
   8  *
   9  * Redistribution and use in source and binary forms, with or without
  10  * modification, are permitted provided that the following conditions
  11  * are met:
  12  * 1. Redistributions of source code must retain the above copyright
  13  *    notice, this list of conditions and the following disclaimer.
  14  * 2. Redistributions in binary form must reproduce the above copyright
  15  *    notice, this list of conditions and the following disclaimer in the
  16  *    documentation and/or other materials provided with the distribution.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  19  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  22  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28  * SUCH DAMAGE.
  29  *
  30  * $FreeBSD$
  31  */
  32
  33 #ifndef _FDT_HH_
  34 #define _FDT_HH_
  35 #include <unordered_map>
  36 #include <unordered_set>
  37 #include <memory>
  38 #include <string>
  39 #include <functional>
  40
  41 #include "util.hh"
  42 #include "input_buffer.hh"
  43
  44 namespace dtc
  45 {
  46
  47 namespace dtb
  48 {
  49 struct output_writer;
  50 class string_table;
  51 }
  52
  53 namespace fdt
  54 {
  55 class property;
  56 class node;
  57 /**
  58  * Type for (owned) pointers to properties.
  59  */
  60 typedef std::shared_ptr<property> property_ptr;
  61 /**
  62  * Owning pointer to a node.
  63  */
  64 typedef std::unique_ptr<node> node_ptr;
  65 /**
  66  * Map from macros to property pointers.
  67  */
  68 typedef std::unordered_map<std::string, property_ptr> define_map;
  69 /**
  70  * Set of strings used for label names.
  71  */
  72 typedef std::unordered_set<std::string> string_set;
  73 /**
  74  * Properties may contain a number of different value, each with a different
  75  * label.  This class encapsulates a single value.
  76  */
  77 struct property_value
  78 {
  79         /**
  80          * The label for this data.  This is usually empty.
  81          */
  82         std::string label;
  83         /**
  84          * If this value is a string, or something resolved from a string (a
  85          * reference) then this contains the source string.
  86          */
  87         std::string string_data;
  88         /**
  89          * The data that should be written to the final output.
  90          */
  91         byte_buffer byte_data;
  92         /**
  93          * Enumeration describing the possible types of a value.  Note that
  94          * property-coded arrays will appear simply as binary (or possibly
  95          * string, if they happen to be nul-terminated and printable), and must
  96          * be checked separately.
  97          */
  98         enum value_type
  99         {
 100                 /**
 101                  * This is a list of strings.  When read from source, string
 102                  * lists become one property value for each string, however
 103                  * when read from binary we have a single property value
 104                  * incorporating the entire text, with nul bytes separating the
 105                  * strings.
 106                  */
 107                 STRING_LIST,
 108                 /**
 109                  * This property contains a single string.
 110                  */
 111                 STRING,
 112                 /**
 113                  * This is a binary value.  Check the size of byte_data to
 114                  * determine how many bytes this contains.
 115                  */
 116                 BINARY,
 117                 /** This contains a short-form address that should be replaced
 118                  * by a fully-qualified version.  This will only appear when
 119                  * the input is a device tree source.  When parsed from a
 120                  * device tree blob, the cross reference will have already been
 121                  * resolved and the property value will be a string containing
 122                  * the full path of the target node.  */
 123                 CROSS_REFERENCE,
 124                 /**
 125                  * This is a phandle reference.  When parsed from source, the
 126                  * string_data will contain the node label for the target and,
 127                  * after cross references have been resolved, the binary data
 128                  * will contain a 32-bit integer that should match the phandle
 129                  * property of the target node.
 130                  */
 131                 PHANDLE,
 132                 /**
 133                  * An empty property value.  This will never appear on a real
 134                  * property value, it is used by checkers to indicate that no
 135                  * property values should exist for a property.
 136                  */
 137                 EMPTY,
 138                 /**
 139                  * The type of this property has not yet been determined.
 140                  */
 141                 UNKNOWN
 142         };
 143         /**
 144          * The type of this property.
 145          */
 146         value_type type;
 147         /**
 148          * Returns true if this value is a cross reference, false otherwise.
 149          */
 150         inline bool is_cross_reference()
 151         {
 152                 return is_type(CROSS_REFERENCE);
 153         }
 154         /**
 155          * Returns true if this value is a phandle reference, false otherwise.
 156          */
 157         inline bool is_phandle()
 158         {
 159                 return is_type(PHANDLE);
 160         }
 161         /**
 162          * Returns true if this value is a string, false otherwise.
 163          */
 164         inline bool is_string()
 165         {
 166                 return is_type(STRING);
 167         }
 168         /**
 169          * Returns true if this value is a string list (a nul-separated
 170          * sequence of strings), false otherwise.
 171          */
 172         inline bool is_string_list()
 173         {
 174                 return is_type(STRING_LIST);
 175         }
 176         /**
 177          * Returns true if this value is binary, false otherwise.
 178          */
 179         inline bool is_binary()
 180         {
 181                 return is_type(BINARY);
 182         }
 183         /**
 184          * Returns this property value as a 32-bit integer.  Returns 0 if this
 185          * property value is not 32 bits long.  The bytes in the property value
 186          * are assumed to be in big-endian format, but the return value is in
 187          * the host native endian.
 188          */
 189         uint32_t get_as_uint32();
 190         /**
 191          * Default constructor, specifying the label of the value.
 192          */
 193         property_value(std::string l=std::string()) : label(l), type(UNKNOWN) {}
 194         /**
 195          * Writes the data for this value into an output buffer.
 196          */
 197         void push_to_buffer(byte_buffer &buffer);
 198
 199         /**
 200          * Writes the property value to the standard output.  This uses the
 201          * following heuristics for deciding how to print the output:
 202          *
 203          * - If the value is nul-terminated and only contains printable
 204          *   characters, it is written as a string.
 205          * - If it is a multiple of 4 bytes long, then it is printed as cells.
 206          * - Otherwise, it is printed as a byte buffer.
 207          */
 208         void write_dts(FILE *file);
 209         /**
 210          * Tries to merge adjacent property values, returns true if it succeeds and
 211          * false otherwise.
 212          */
 213         bool try_to_merge(property_value &other);
 214         /**
 215          * Returns the size (in bytes) of this property value.
 216          */
 217         size_t size();
 218         private:
 219         /**
 220          * Returns whether the value is of the specified type.  If the type of
 221          * the value has not yet been determined, then this calculates it.
 222          */
 223         inline bool is_type(value_type v)
 224         {
 225                 if (type == UNKNOWN)
 226                 {
 227                         resolve_type();
 228                 }
 229                 return type == v;
 230         }
 231         /**
 232          * Determines the type of the value based on its contents.
 233          */
 234         void resolve_type();
 235         /**
 236          * Writes the property value to the specified file as a quoted string.
 237          * This is used when generating DTS.
 238          */
 239         void write_as_string(FILE *file);
 240         /**
 241          * Writes the property value to the specified file as a sequence of
 242          * 32-bit big-endian cells.  This is used when generating DTS.
 243          */
 244         void write_as_cells(FILE *file);
 245         /**
 246          * Writes the property value to the specified file as a sequence of
 247          * bytes.  This is used when generating DTS.
 248          */
 249         void write_as_bytes(FILE *file);
 250 };
 251
 252 /**
 253  * A value encapsulating a single property.  This contains a key, optionally a
 254  * label, and optionally one or more values.
 255  */
 256 class property
 257 {
 258         /**
 259          * The name of this property.
 260          */
 261         std::string key;
 262         /**
 263          * Zero or more labels.
 264          */
 265         string_set labels;
 266         /**
 267          * The values in this property.
 268          */
 269         std::vector<property_value> values;
 270         /**
 271          * Value indicating that this is a valid property.  If a parse error
 272          * occurs, then this value is false.
 273          */
 274         bool valid;
 275         /**
 276          * Parses a string property value, i.e. a value enclosed in double quotes.
 277          */
 278         void parse_string(text_input_buffer &input);
 279         /**
 280          * Parses one or more 32-bit values enclosed in angle brackets.
 281          */
 282         void parse_cells(text_input_buffer &input, int cell_size);
 283         /**
 284          * Parses an array of bytes, contained within square brackets.
 285          */
 286         void parse_bytes(text_input_buffer &input);
 287         /**
 288          * Parses a reference.  This is a node label preceded by an ampersand
 289          * symbol, which should expand to the full path to that node.
 290          *
 291          * Note: The specification says that the target of such a reference is
 292          * a node name, however dtc assumes that it is a label, and so we
 293          * follow their interpretation for compatibility.
 294          */
 295         void parse_reference(text_input_buffer &input);
 296         /**
 297          * Parse a predefined macro definition for a property.
 298          */
 299         void parse_define(text_input_buffer &input, define_map *defines);
 300         /**
 301          * Constructs a new property from two input buffers, pointing to the
 302          * struct and strings tables in the device tree blob, respectively.
 303          * The structs input buffer is assumed to have just consumed the
 304          * FDT_PROP token.
 305          */
 306         property(input_buffer &structs, input_buffer &strings);
 307         /**
 308          * Parses a new property from the input buffer.
 309          */
 310         property(text_input_buffer &input,
 311                  std::string &&k,
 312                  string_set &&l,
 313                  bool terminated,
 314                  define_map *defines);
 315         public:
 316         /**
 317          * Creates an empty property.
 318          */
 319         property(std::string &&k, string_set &&l=string_set())
 320                 : key(k), labels(l), valid(true) {}
 321         /**
 322          * Copy constructor.
 323          */
 324         property(property &p) : key(p.key), labels(p.labels), values(p.values),
 325                 valid(p.valid) {}
 326         /**
 327          * Factory method for constructing a new property.  Attempts to parse a
 328          * property from the input, and returns it on success.  On any parse
 329          * error, this will return 0.
 330          */
 331         static property_ptr parse_dtb(input_buffer &structs,
 332                                       input_buffer &strings);
 333         /**
 334          * Factory method for constructing a new property.  Attempts to parse a
 335          * property from the input, and returns it on success.  On any parse
 336          * error, this will return 0.
 337          */
 338         static property_ptr parse(text_input_buffer &input,
 339                                   std::string &&key,
 340                                   string_set &&labels=string_set(),
 341                                   bool semicolonTerminated=true,
 342                                   define_map *defines=0);
 343         /**
 344          * Iterator type used for accessing the values of a property.
 345          */
 346         typedef std::vector<property_value>::iterator value_iterator;
 347         /**
 348          * Returns an iterator referring to the first value in this property.
 349          */
 350         inline value_iterator begin()
 351         {
 352                 return values.begin();
 353         }
 354         /**
 355          * Returns an iterator referring to the last value in this property.
 356          */
 357         inline value_iterator end()
 358         {
 359                 return values.end();
 360         }
 361         /**
 362          * Adds a new value to an existing property.
 363          */
 364         inline void add_value(property_value v)
 365         {
 366                 values.push_back(v);
 367         }
 368         /**
 369          * Returns the key for this property.
 370          */
 371         inline std::string get_key()
 372         {
 373                 return key;
 374         }
 375         /**
 376          * Writes the property to the specified writer.  The property name is a
 377          * reference into the strings table.
 378          */
 379         void write(dtb::output_writer &writer, dtb::string_table &strings);
 380         /**
 381          * Writes in DTS format to the specified file, at the given indent
 382          * level.  This will begin the line with the number of tabs specified
 383          * as the indent level and then write the property in the most
 384          * applicable way that it can determine.
 385          */
 386         void write_dts(FILE *file, int indent);
 387         /**
 388          * Returns the byte offset of the specified property value.
 389          */
 390         size_t offset_of_value(property_value &val);
 391 };
 392
 393 /**
 394  * Class encapsulating a device tree node.  Nodes may contain properties and
 395  * other nodes.
 396  */
 397 class node
 398 {
 399         public:
 400         /**
 401          * The labels for this node, if any.  Node labels are used as the
 402          * targets for cross references.
 403          */
 404         std::unordered_set<std::string> labels;
 405         /**
 406          * The name of the node.
 407          */
 408         std::string name;
 409         /**
 410          * The unit address of the node, which is optionally written after the
 411          * name followed by an at symbol.
 412          */
 413         std::string unit_address;
 414         /**
 415          * The type for the property vector.
 416          */
 417         typedef std::vector<property_ptr> property_vector;
 418         /**
 419          * Iterator type for child nodes.
 420          */
 421         typedef std::vector<node_ptr>::iterator child_iterator;
 422         private:
 423         /**
 424          * Adaptor to use children in range-based for loops.
 425          */
 426         struct child_range
 427         {
 428                 child_range(node &nd) : n(nd) {}
 429                 child_iterator begin() { return n.child_begin(); }
 430                 child_iterator end() { return n.child_end(); }
 431                 private:
 432                 node &n;
 433         };
 434         /**
 435          * Adaptor to use properties in range-based for loops.
 436          */
 437         struct property_range
 438         {
 439                 property_range(node &nd) : n(nd) {}
 440                 property_vector::iterator begin() { return n.property_begin(); }
 441                 property_vector::iterator end() { return n.property_end(); }
 442                 private:
 443                 node &n;
 444         };
 445         /**
 446          * The properties contained within this node.
 447          */
 448         property_vector props;
 449         /**
 450          * The children of this node.
 451          */
 452         std::vector<node_ptr> children;
 453         /**
 454          * Children that should be deleted from this node when merging.
 455          */
 456         std::unordered_set<std::string> deleted_children;
 457         /**
 458          * Properties that should be deleted from this node when merging.
 459          */
 460         std::unordered_set<std::string> deleted_props;
 461         /**
 462          * A flag indicating whether this node is valid.  This is set to false
 463          * if an error occurs during parsing.
 464          */
 465         bool valid;
 466         /**
 467          * Parses a name inside a node, writing the string passed as the last
 468          * argument as an error if it fails.
 469          */
 470         std::string parse_name(text_input_buffer &input,
 471                                bool &is_property,
 472                                const char *error);
 473         /**
 474          * Constructs a new node from two input buffers, pointing to the struct
 475          * and strings tables in the device tree blob, respectively.
 476          */
 477         node(input_buffer &structs, input_buffer &strings);
 478         /**
 479          * Parses a new node from the specified input buffer.  This is called
 480          * when the input cursor is on the open brace for the start of the
 481          * node.  The name, and optionally label and unit address, should have
 482          * already been parsed.
 483          */
 484         node(text_input_buffer &input,
 485              std::string &&n,
 486              std::unordered_set<std::string> &&l,
 487              std::string &&a,
 488              define_map*);
 489         /**
 490          * Creates a special node with the specified name and properties.
 491          */
 492         node(const std::string &n, const std::vector<property_ptr> &p);
 493         /**
 494          * Comparison function for properties, used when sorting the properties
 495          * vector.  Orders the properties based on their names.
 496          */
 497         static inline bool cmp_properties(property_ptr &p1, property_ptr &p2);
 498                 /*
 499         {
 500                 return p1->get_key() < p2->get_key();
 501         }
 502         */
 503         /**
 504          * Comparison function for nodes, used when sorting the children
 505          * vector.  Orders the nodes based on their names or, if the names are
 506          * the same, by the unit addresses.
 507          */
 508         static inline bool cmp_children(node_ptr &c1, node_ptr &c2);
 509         public:
 510         /**
 511          * Sorts the node's properties and children into alphabetical order and
 512          * recursively sorts the children.
 513          */
 514         void sort();
 515         /**
 516          * Returns an iterator for the first child of this node.
 517          */
 518         inline child_iterator child_begin()
 519         {
 520                 return children.begin();
 521         }
 522         /**
 523          * Returns an iterator after the last child of this node.
 524          */
 525         inline child_iterator child_end()
 526         {
 527                 return children.end();
 528         }
 529         /**
 530          * Returns a range suitable for use in a range-based for loop describing
 531          * the children of this node.
 532          */
 533         inline child_range child_nodes()
 534         {
 535                 return child_range(*this);
 536         }
 537         /**
 538          * Accessor for the deleted children.
 539          */
 540         inline const std::unordered_set<std::string> &deleted_child_nodes()
 541         {
 542                 return deleted_children;
 543         }
 544         /**
 545          * Accessor for the deleted properties
 546          */
 547         inline const std::unordered_set<std::string> &deleted_properties()
 548         {
 549                 return deleted_props;
 550         }
 551         /**
 552          * Returns a range suitable for use in a range-based for loop describing
 553          * the properties of this node.
 554          */
 555         inline property_range properties()
 556         {
 557                 return property_range(*this);
 558         }
 559         /**
 560          * Returns an iterator after the last property of this node.
 561          */
 562         inline property_vector::iterator property_begin()
 563         {
 564                 return props.begin();
 565         }
 566         /**
 567          * Returns an iterator for the first property of this node.
 568          */
 569         inline property_vector::iterator property_end()
 570         {
 571                 return props.end();
 572         }
 573         /**
 574          * Factory method for constructing a new node.  Attempts to parse a
 575          * node in DTS format from the input, and returns it on success.  On
 576          * any parse error, this will return 0.  This should be called with the
 577          * cursor on the open brace of the property, after the name and so on
 578          * have been parsed.
 579          */
 580         static node_ptr parse(text_input_buffer &input,
 581                               std::string &&name,
 582                               std::unordered_set<std::string> &&label=std::unordered_set<std::string>(),
 583                               std::string &&address=std::string(),
 584                               define_map *defines=0);
 585         /**
 586          * Factory method for constructing a new node.  Attempts to parse a
 587          * node in DTB format from the input, and returns it on success.  On
 588          * any parse error, this will return 0.  This should be called with the
 589          * cursor on the open brace of the property, after the name and so on
 590          * have been parsed.
 591          */
 592         static node_ptr parse_dtb(input_buffer &structs, input_buffer &strings);
 593         /**
 594          * Construct a new special node from a name and set of properties.
 595          */
 596         static node_ptr create_special_node(const std::string &name,
 597                         const std::vector<property_ptr> &props);
 598         /**
 599          * Returns a property corresponding to the specified key, or 0 if this
 600          * node does not contain a property of that name.
 601          */
 602         property_ptr get_property(const std::string &key);
 603         /**
 604          * Adds a new property to this node.
 605          */
 606         inline void add_property(property_ptr &p)
 607         {
 608                 props.push_back(p);
 609         }
 610         /**
 611          * Adds a new child to this node.
 612          */
 613         inline void add_child(node_ptr &&n)
 614         {
 615                 children.push_back(std::move(n));
 616         }
 617         /**
 618          * Merges a node into this one.  Any properties present in both are
 619          * overridden, any properties present in only one are preserved.
 620          */
 621         void merge_node(node_ptr other);
 622         /**
 623          * Write this node to the specified output.  Although nodes do not
 624          * refer to a string table directly, their properties do.  The string
 625          * table passed as the second argument is used for the names of
 626          * properties within this node and its children.
 627          */
 628         void write(dtb::output_writer &writer, dtb::string_table &strings);
 629         /**
 630          * Writes the current node as DTS to the specified file.  The second
 631          * parameter is the indent level.  This function will start every line
 632          * with this number of tabs.
 633          */
 634         void write_dts(FILE *file, int indent);
 635         /**
 636          * Recursively visit this node and then its children.
 637          */
 638         void visit(std::function<void(node&)>);
 639 };
 640
 641 /**
 642  * Class encapsulating the entire parsed FDT.  This is the top-level class,
 643  * which parses the entire DTS representation and write out the finished
 644  * version.
 645  */
 646 class device_tree
 647 {
 648         public:
 649         /**
 650          * Type used for node paths.  A node path is sequence of names and unit
 651          * addresses.
 652          */
 653         class node_path : public std::vector<std::pair<std::string,std::string>>
 654         {
 655                 public:
 656                 /**
 657                  * Converts this to a string representation.
 658                  */
 659                 std::string to_string() const;
 660         };
 661         /**
 662          * Name that we should use for phandle nodes.
 663          */
 664         enum phandle_format
 665         {
 666                 /** linux,phandle */
 667                 LINUX,
 668                 /** phandle */
 669                 EPAPR,
 670                 /** Create both nodes. */
 671                 BOTH
 672         };
 673         private:
 674         /**
 675          * The format that we should use for writing phandles.
 676          */
 677         phandle_format phandle_node_name;
 678         /**
 679          * Flag indicating that this tree is valid.  This will be set to false
 680          * on parse errors.
 681          */
 682         bool valid;
 683         /**
 684          * Type used for memory reservations.  A reservation is two 64-bit
 685          * values indicating a base address and length in memory that the
 686          * kernel should not use.  The high 32 bits are ignored on 32-bit
 687          * platforms.
 688          */
 689         typedef std::pair<uint64_t, uint64_t> reservation;
 690         /**
 691          * The memory reserves table.
 692          */
 693         std::vector<reservation> reservations;
 694         /**
 695          * Root node.  All other nodes are children of this node.
 696          */
 697         node_ptr root;
 698         /**
 699          * Mapping from names to nodes.  Only unambiguous names are recorded,
 700          * duplicate names are stored as (node*)-1.
 701          */
 702         std::unordered_map<std::string, node*> node_names;
 703         /**
 704          * A map from labels to node paths.  When resolving cross references,
 705          * we look up referenced nodes in this and replace the cross reference
 706          * with the full path to its target.
 707          */
 708         std::unordered_map<std::string, node_path> node_paths;
 709         /**
 710          * A collection of property values that are references to other nodes.
 711          * These should be expanded to the full path of their targets.
 712          */
 713         std::vector<property_value*> cross_references;
 714         /**
 715          * The location of something requiring a fixup entry.
 716          */
 717         struct fixup
 718         {
 719                 /**
 720                  * The path to the node.
 721                  */
 722                 node_path path;
 723                 /**
 724                  * The property containing the reference.
 725                  */
 726                 property_ptr prop;
 727                 /**
 728                  * The property value that contains the reference.
 729                  */
 730                 property_value &val;
 731         };
 732         /**
 733          * A collection of property values that refer to phandles.  These will
 734          * be replaced by the value of the phandle property in their
 735          * destination.
 736          */
 737         std::vector<fixup> fixups;
 738         /**
 739          * The locations of all of the values that are supposed to become phandle
 740          * references, but refer to things outside of this file.
 741          */
 742         std::vector<std::reference_wrapper<fixup>> unresolved_fixups;
 743         /**
 744          * The names of nodes that target phandles.
 745          */
 746         std::unordered_set<std::string> phandle_targets;
 747         /**
 748          * A collection of input buffers that we are using.  These input
 749          * buffers are the ones that own their memory, and so we must preserve
 750          * them for the lifetime of the device tree.
 751          */
 752         std::vector<std::unique_ptr<input_buffer>> buffers;
 753         /**
 754          * A map of used phandle values to nodes.  All phandles must be unique,
 755          * so we keep a set of ones that the user explicitly provides in the
 756          * input to ensure that we don't reuse them.
 757          *
 758          * This is a map, rather than a set, because we also want to be able to
 759          * find phandles that were provided by the user explicitly when we are
 760          * doing checking.
 761          */
 762         std::unordered_map<uint32_t, node*> used_phandles;
 763         /**
 764          * Paths to search for include files.  This contains a set of
 765          * nul-terminated strings, which are not owned by this class and so
 766          * must be freed separately.
 767          */
 768         std::vector<std::string> include_paths;
 769         /**
 770          * Dictionary of predefined macros provided on the command line.
 771          */
 772         define_map               defines;
 773         /**
 774          * The default boot CPU, specified in the device tree header.
 775          */
 776         uint32_t boot_cpu;
 777         /**
 778          * The number of empty reserve map entries to generate in the blob.
 779          */
 780         uint32_t spare_reserve_map_entries;
 781         /**
 782          * The minimum size in bytes of the blob.
 783          */
 784         uint32_t minimum_blob_size;
 785         /**
 786          * The number of bytes of padding to add to the end of the blob.
 787          */
 788         uint32_t blob_padding;
 789         /**
 790          * Is this tree a plugin?
 791          */
 792         bool is_plugin;
 793         /**
 794          * Visit all of the nodes recursively, and if they have labels then add
 795          * them to the node_paths and node_names vectors so that they can be
 796          * used in resolving cross references.  Also collects phandle
 797          * properties that have been explicitly added.
 798          */
 799         void collect_names_recursive(node_ptr &n, node_path &path);
 800         /**
 801          * Assign phandle properties to all nodes that have been referenced and
 802          * require one.  This method will recursively visit the tree starting at
 803          * the node that it is passed.
 804          */
 805         void assign_phandles(node_ptr &n, uint32_t &next);
 806         /**
 807          * Calls the recursive version of this method on every root node.
 808          */
 809         void collect_names();
 810         /**
 811          * Resolves all cross references.  Any properties that refer to another
 812          * node must have their values replaced by either the node path or
 813          * phandle value.
 814          */
 815         void resolve_cross_references();
 816         /**
 817          * Parses a dts file in the given buffer and adds the roots to the parsed
 818          * set.  The `read_header` argument indicates whether the header has
 819          * already been read.  Some dts files place the header in an include,
 820          * rather than in the top-level file.
 821          */
 822         void parse_file(text_input_buffer &input,
 823                         std::vector<node_ptr> &roots,
 824                         bool &read_header);
 825         /**
 826          * Template function that writes a dtb blob using the specified writer.
 827          * The writer defines the output format (assembly, blob).
 828          */
 829         template<class writer>
 830         void write(int fd);
 831         public:
 832         /**
 833          * Should we write the __symbols__ node (to allow overlays to be linked
 834          * against this blob)?
 835          */
 836         bool write_symbols = false;
 837         /**
 838          * Returns the node referenced by the property.  If this is a tree that
 839          * is in source form, then we have a string that we can use to index
 840          * the cross_references array and so we can just look that up.
 841          */
 842         node *referenced_node(property_value &v);
 843         /**
 844          * Writes this FDT as a DTB to the specified output.
 845          */
 846         void write_binary(int fd);
 847         /**
 848          * Writes this FDT as an assembly representation of the DTB to the
 849          * specified output.  The result can then be assembled and linked into
 850          * a program.
 851          */
 852         void write_asm(int fd);
 853         /**
 854          * Writes the tree in DTS (source) format.
 855          */
 856         void write_dts(int fd);
 857         /**
 858          * Default constructor.  Creates a valid, but empty FDT.
 859          */
 860         device_tree() : phandle_node_name(EPAPR), valid(true),
 861                 boot_cpu(0), spare_reserve_map_entries(0),
 862                 minimum_blob_size(0), blob_padding(0) {}
 863         /**
 864          * Constructs a device tree from the specified file name, referring to
 865          * a file that contains a device tree blob.
 866          */
 867         void parse_dtb(const std::string &fn, FILE *depfile);
 868         /**
 869          * Constructs a device tree from the specified file name, referring to
 870          * a file that contains device tree source.
 871          */
 872         void parse_dts(const std::string &fn, FILE *depfile);
 873         /**
 874          * Returns whether this tree is valid.
 875          */
 876         inline bool is_valid()
 877         {
 878                 return valid;
 879         }
 880         /**
 881          * Sets the format for writing phandle properties.
 882          */
 883         inline void set_phandle_format(phandle_format f)
 884         {
 885                 phandle_node_name = f;
 886         }
 887         /**
 888          * Returns a pointer to the root node of this tree.  No ownership
 889          * transfer.
 890          */
 891         inline const node_ptr &get_root() const
 892         {
 893                 return root;
 894         }
 895         /**
 896          * Sets the physical boot CPU.
 897          */
 898         void set_boot_cpu(uint32_t cpu)
 899         {
 900                 boot_cpu = cpu;
 901         }
 902         /**
 903          * Sorts the tree.  Useful for debugging device trees.
 904          */
 905         void sort()
 906         {
 907                 root->sort();
 908         }
 909         /**
 910          * Adds a path to search for include files.  The argument must be a
 911          * nul-terminated string representing the path.  The device tree keeps
 912          * a pointer to this string, but does not own it: the caller is
 913          * responsible for freeing it if required.
 914          */
 915         void add_include_path(const char *path)
 916         {
 917                 std::string p(path);
 918                 include_paths.push_back(std::move(p));
 919         }
 920         /**
 921          * Sets the number of empty reserve map entries to add.
 922          */
 923         void set_empty_reserve_map_entries(uint32_t e)
 924         {
 925                 spare_reserve_map_entries = e;
 926         }
 927         /**
 928          * Sets the minimum size, in bytes, of the blob.
 929          */
 930         void set_blob_minimum_size(uint32_t s)
 931         {
 932                 minimum_blob_size = s;
 933         }
 934         /**
 935          * Sets the amount of padding to add to the blob.
 936          */
 937         void set_blob_padding(uint32_t p)
 938         {
 939                 blob_padding = p;
 940         }
 941         /**
 942          * Parses a predefined macro value.
 943          */
 944         bool parse_define(const char *def);
 945 };
 946
 947 } // namespace fdt
 948
 949 } // namespace dtc
 950
 951 #endif // !_FDT_HH_