xref: /freebsd/usr.bin/dtc/dtb.hh (revision 4d293dd8dcde59fc9842a0ce1125fef8fcf83a8c)
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 output 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_
366