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