usr.bin/dtc/dtb.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 _DTB_HH_
  34 #define _DTB_HH_
  35 #include <map>
  36 #include "string.hh"
  37
  38 #include <assert.h>
  39
  40 namespace dtc
  41 {
  42 /**
  43  * The dtb namespace contains code related to the generation of device tree
  44  * blobs, the binary representation of flattened device trees.  The abstract
  45  * tree representation calls into this code to generate the output.
  46  */
  47 namespace dtb
  48 {
  49 /** The token types in the DTB, as defined by §7.4.1 of the ePAPR
  50  * specification.  All of these values are written in big-endian format in the
  51  * output.
  52  */
  53 enum token_type
  54 {
  55         /**
  56          * Marker indicating the start of a node in the tree.  This is followed
  57          * by the nul-terminated name.  If a unit address is specified, then
  58          * the name also contains the address, with an @ symbol between the end
  59          * of the name and the start of the address.
  60          *
  61          * The name is then padded such that the next token begins on a 4-byte
  62          * boundary.  The node may contain properties, other nodes, both, or be
  63          * empty.
  64          */
  65         FDT_BEGIN_NODE = 0x00000001,
  66         /**
  67          * Marker indicating the end of a node.
  68          */
  69         FDT_END_NODE   = 0x00000002,
  70         /**
  71          * The start of a property.  This is followed by two 32-bit big-endian
  72          * values.  The first indicates the length of the property value, the
  73          * second its index in the strings table.  It is then followed by the
  74          * property value, if the value is of non-zero length.
  75          */
  76         FDT_PROP       = 0x00000003,
  77         /**
  78          * Ignored token.  May be used for padding inside DTB nodes.
  79          */
  80         FDT_NOP        = 0x00000004,
  81         /**
  82          * Marker indicating the end of the tree.
  83          */
  84         FDT_END        = 0x00000009
  85 };
  86
  87 /**
  88  * Returns the token as a string.  This is used for debugging and for printing
  89  * human-friendly error messages about malformed DTB input.
  90  */
  91 inline const char *token_type_name(token_type t)
  92 {
  93         switch(t)
  94         {
  95                 case FDT_BEGIN_NODE:
  96                         return "FDT_BEGIN_NODE";
  97                 case FDT_END_NODE:
  98                         return "FDT_END_NODE";
  99                 case FDT_PROP:
 100                         return "FDT_PROP";
 101                 case FDT_NOP:
 102                         return "FDT_NOP";
 103                 case FDT_END:
 104                         return "FDT_END";
 105         }
 106         assert(0);
 107 }
 108
 109 /**
 110  * Abstract class for writing a section of the output.  We create one
 111  * of these for each section that needs to be written.  It is intended to build
 112  * a temporary buffer of the output in memory and then write it to a file
 113  * stream.  The size can be returned after all of the data has been written
 114  * into the internal buffer, so the sizes of the three tables can be calculated
 115  * before storing them in the buffer.
 116  */
 117 struct output_writer
 118 {
 119         /**
 120          * Writes a label into the output stream.  This is only applicable for
 121          * assembly output, where the labels become symbols that can be
 122          * resolved at link time.
 123          */
 124         virtual void write_label(string name)   = 0;
 125         /**
 126          * Writes a comment into the output stream.  Useful only when debugging
 127          * the output.
 128          */
 129         virtual void write_comment(string name) = 0;
 130         /**
 131          * Writes a string.  A nul terminator is implicitly added.
 132          */
 133         virtual void write_string(string name)  = 0;
 134         /**
 135          * Writes a single 8-bit value.
 136          */
 137         virtual void write_data(uint8_t)        = 0;
 138         /**
 139          * Writes a single 32-bit value.  The value is written in big-endian
 140          * format, but should be passed in the host's native endian.
 141          */
 142         virtual void write_data(uint32_t)       = 0;
 143         /**
 144          * Writes a single 64-bit value.  The value is written in big-endian
 145          * format, but should be passed in the host's native endian.
 146          */
 147         virtual void write_data(uint64_t)       = 0;
 148         /**
 149          * Writes the collected output to the specified file descriptor.
 150          */
 151         virtual void write_to_file(int fd)      = 0;
 152         /**
 153          * Returns the number of bytes.
 154          */
 155         virtual uint32_t size()                 = 0;
 156         /**
 157          * Helper for writing tokens to the output stream.  This writes a
 158          * comment above the token describing its value, for easier debugging
 159          * of the output.
 160          */
 161         inline void write_token(token_type t)
 162         {
 163                 write_comment(token_type_name(t));
 164                 write_data((uint32_t)t);
 165         }
 166         /**
 167          * Helper function that writes a byte buffer to the output, one byte at
 168          * a time.
 169          */
 170         void write_data(byte_buffer b);
 171 };
 172
 173 /**
 174  * Binary file writer.  This class is responsible for writing the DTB output
 175  * directly in blob format.
 176  */
 177 class binary_writer : public output_writer
 178 {
 179         /**
 180          * The internal buffer used to store the blob while it is being
 181          * constructed.
 182          */
 183         byte_buffer buffer;
 184         public:
 185         /**
 186          *  The binary format does not support labels, so this method
 187          * does nothing.
 188          */
 189         virtual void write_label(string name) {}
 190         /**
 191          * Comments are ignored by the binary writer.
 192          */
 193         virtual void write_comment(string name) {}
 194         virtual void write_string(string name);
 195         virtual void write_data(uint8_t v);
 196         virtual void write_data(uint32_t v);
 197         virtual void write_data(uint64_t v);
 198         virtual void write_to_file(int fd);
 199         virtual uint32_t size();
 200 };
 201 /**
 202  * Assembly writer.  This class is responsible for writing the output in an
 203  * assembly format that is suitable for linking into a kernel, loader, and so
 204  * on.
 205  */
 206 class asm_writer : public output_writer
 207 {
 208         /**
 209          * The internal buffer for temporary values.  Note that this actually
 210          * contains ASCII text, but it is a byte buffer so that we can just
 211          * copy strings across as-is.
 212          */
 213         byte_buffer buffer;
 214         /**
 215          * The number of bytes written to the current line.  This is used to
 216          * allow line wrapping, where we aim to write four .byte directives to
 217          * make the alignment clearer.
 218          */
 219         int byte_count;
 220         /**
 221          * The current number of bytes written.  This is the number in binary
 222          * format, not the number of bytes in the buffer.
 223          */
 224         uint32_t bytes_written;
 225
 226         /**
 227          * Writes a C string directly to the ouput as-is.  This is mainly used
 228          * for writing directives.
 229          */
 230         void write_string(const char *c);
 231         /**
 232          * Writes the string, starting on a new line.
 233          */
 234         void write_line(const char *c);
 235         /**
 236          * Writes a byte in binary format.  This will emit a single .byte
 237          * directive, with up to four per line.
 238          */
 239         void write_byte(uint8_t b);
 240         public:
 241         asm_writer() : byte_count(0), bytes_written(0) {}
 242         virtual void write_label(string name);
 243         virtual void write_comment(string name);
 244         virtual void write_string(string name);
 245         virtual void write_data(uint8_t v);
 246         virtual void write_data(uint32_t v);
 247         virtual void write_data(uint64_t v);
 248         virtual void write_to_file(int fd);
 249         virtual uint32_t size();
 250 };
 251
 252 /**
 253  * Class encapsulating the device tree blob header.  This class stores all of
 254  * the values found in the header and is responsible for writing them to the
 255  * output.
 256  */
 257 struct header
 258 {
 259         /**
 260          * Magic value, used to validate that this really is a device tree
 261          * blob.  Should always be set to 0xd00dfeed.
 262          */
 263         uint32_t magic;
 264         /**
 265          * The total size of the blob, including header, reservations, strings
 266          * table, and padding.
 267          */
 268         uint32_t totalsize;
 269         /**
 270          * The offset from the start of the blob of the struct table (i.e. the
 271          * part of the blob containing the entire device tree).
 272          */
 273         uint32_t off_dt_struct;
 274         /**
 275          * The offset from the start of the blob of the strings table.
 276          */
 277         uint32_t off_dt_strings;
 278         /**
 279          * The offset of the reservation map from the start of the blob.
 280          */
 281         uint32_t off_mem_rsvmap;
 282         /**
 283          * The version of the blob.  This should always be 17.
 284          */
 285         uint32_t version;
 286         /**
 287          * The earliest version of the DTB specification with which this blob
 288          * is backwards compatible.  This should always be 16.
 289          */
 290         uint32_t last_comp_version;
 291         /**
 292          * The ID of the CPU where this boots.
 293          */
 294         uint32_t boot_cpuid_phys;
 295         /**
 296          * The size of the strings table.
 297          */
 298         uint32_t size_dt_strings;
 299         /**
 300          * The size of the struct table.
 301          */
 302         uint32_t size_dt_struct;
 303         /**
 304          * Writes the entire header to the specified output buffer.
 305          */
 306         void write(output_writer &out);
 307         /**
 308          * Reads the header from bits binary representation in a blob.
 309          */
 310         bool read_dtb(input_buffer &input);
 311         /**
 312          * Default constructor.  Initialises the values that have sensible
 313          * defaults, leaves the others blank.
 314          */
 315         header() : magic(0xd00dfeed), version(17), last_comp_version(16),
 316                 boot_cpuid_phys(0) {}
 317 };
 318
 319 /**
 320  * Class encapsulating the string table.  FDT strings are stored in a string
 321  * section.  This maintains a map from strings to their offsets in the strings
 322  * section.
 323  *
 324  * Note: We don't currently do suffix matching, which may save a small amount
 325  * of space.
 326  */
 327 class string_table {
 328         /**
 329          * Map from strings to their offset.
 330          */
 331         std::map<string, uint32_t> string_offsets;
 332         /**
 333          * The strings, in the order in which they should be written to the
 334          * output.  The order must be stable - adding another string must not
 335          * change the offset of any that we have already referenced - and so we
 336          * simply write the strings in the order that they are passed.
 337          */
 338         std::vector<string> strings;
 339         /**
 340          * The current size of the strings section.
 341          */
 342         uint32_t size;
 343         public:
 344         /**
 345          * Default constructor, creates an empty strings table.
 346          */
 347         string_table() : size(0) {}
 348         /**
 349          * Adds a string to the table, returning the offset from the start
 350          * where it will be written.  If the string is already present, this
 351          * will return its existing offset, otherwise it will return a new
 352          * offset.
 353          */
 354         uint32_t add_string(string str);
 355         /**
 356          * Writes the strings table to the specified output.
 357          */
 358         void write(dtb::output_writer &writer);
 359 };
 360
 361 } // namespace dtb
 362
 363 } // namespace dtc
 364
 365 #endif // !_DTB_HH_