2 * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
4 * Copyright (c) 2013 David Chisnall
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.
11 * Redistribution and use in source and binary forms, with or without
12 * modification, are permitted provided that the following conditions
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.
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
35 #ifndef _INPUT_BUFFER_HH_
36 #define _INPUT_BUFFER_HH_
41 #include <unordered_set>
48 typedef std::unique_ptr<expression> expression_ptr;
52 * Class encapsulating the input file. Can be used as a const char*, but has
53 * range checking. Attempting to access anything out of range will return a 0
54 * byte. The input buffer can be cheaply copied, without copying the
55 * underlying memory, however it is the user's responsibility to ensure that
56 * such copies do not persist beyond the lifetime of the underlying memory.
58 * This also contains methods for reporting errors and for consuming the token
63 friend class text_input_buffer;
66 * The buffer. This class doesn't own the buffer, but the
67 * mmap_input_buffer subclass does.
71 * The size of the buffer.
76 * The current place in the buffer where we are reading. This class
77 * keeps a separate size, pointer, and cursor so that we can move
78 * forwards and backwards and still have checks that we haven't fallen
83 * Private constructor. This is used to create input buffers that
84 * refer to the same memory, but have different cursors.
86 input_buffer(const char* b, int s, int c) : buffer(b), size(s),
90 * Returns the file name associated with this buffer.
92 virtual const std::string &filename() const
97 static std::unique_ptr<input_buffer> buffer_for_file(const std::string &path,
100 * Skips all characters in the input until the specified character is
105 * Parses up to a specified character and returns the intervening
106 * characters as a string.
108 std::string parse_to(char);
110 * Return whether all input has been consumed.
112 bool finished() { return cursor >= size; }
114 * Virtual destructor. Does nothing, but exists so that subclasses
115 * that own the memory can run cleanup code for deallocating it.
117 virtual ~input_buffer() {};
119 * Constructs an empty buffer.
121 input_buffer() : buffer(0), size(0), cursor(0) {}
123 * Constructs a new buffer with a specified memory region and size.
125 input_buffer(const char* b, int s) : buffer(b), size(s), cursor(0){}
127 * Returns a new input buffer referring into this input, clamped to the
128 * specified size. If the requested buffer would fall outside the
129 * range of this one, then it returns an empty buffer.
131 * The returned buffer shares the same underlying storage as the
132 * original. This is intended to be used for splitting up the various
133 * sections of a device tree blob. Requesting a size of 0 will give a
134 * buffer that extends to the end of the available memory.
136 input_buffer buffer_from_offset(int offset, int s=0);
138 * Dereferencing operator, allows the buffer to be treated as a char*
139 * and dereferenced to give a character. This returns a null byte if
140 * the cursor is out of range.
142 inline char operator*()
144 if (cursor >= size) { return '\0'; }
145 if (cursor < 0) { return '\0'; }
146 return buffer[cursor];
149 * Array subscripting operator, returns a character at the specified
150 * index offset from the current cursor. The offset may be negative,
151 * to reread characters that have already been read. If the current
152 * cursor plus offset is outside of the range, this returns a nul
155 inline char operator[](int offset)
157 if (cursor + offset >= size) { return '\0'; }
158 if (cursor + offset < 0) { return '\0'; }
159 return buffer[cursor + offset];
162 * Increments the cursor, iterating forward in the buffer.
164 inline input_buffer &operator++()
175 return buffer + size;
178 * Consumes a character. Moves the cursor one character forward if the
179 * next character matches the argument, returning true. If the current
180 * character does not match the argument, returns false.
182 inline bool consume(char c)
192 * Consumes a string. If the (null-terminated) string passed as the
193 * argument appears in the input, advances the cursor to the end and
194 * returns true. Returns false if the string does not appear at the
195 * current point in the input.
197 bool consume(const char *str);
199 * Reads an integer in base 8, 10, or 16. Returns true and advances
200 * the cursor to the end of the integer if the cursor points to an
201 * integer, returns false and does not move the cursor otherwise.
203 * The parsed value is returned via the argument.
205 bool consume_integer(unsigned long long &outInt);
207 * Reads an arithmetic expression (containing any of the normal C
208 * operators), evaluates it, and returns the result.
210 bool consume_integer_expression(unsigned long long &outInt);
212 * Consumes two hex digits and return the resulting byte via the first
213 * argument. If the next two characters are hex digits, returns true
214 * and advances the cursor. If not, then returns false and leaves the
217 bool consume_hex_byte(uint8_t &outByte);
219 * Template function that consumes a binary value in big-endian format
220 * from the input stream. Returns true and advances the cursor if
221 * there is a value of the correct size. This function assumes that
222 * all values must be natively aligned, and so advances the cursor to
223 * the correct alignment before reading.
226 bool consume_binary(T &out)
229 int type_size = sizeof(T);
230 if (cursor % type_size != 0)
232 align = type_size - (cursor % type_size);
234 if (size < cursor + align + type_size)
239 assert(cursor % type_size == 0);
241 for (int i=0 ; i<type_size ; ++i)
248 out |= (((T)buffer[cursor++]) & 0xff);
254 * Dumps the current cursor value and the unconsumed values in the
255 * input buffer to the standard error. This method is intended solely
262 * Explicit specialisation for reading a single byte.
265 inline bool input_buffer::consume_binary(uint8_t &out)
267 if (size < cursor + 1)
271 out = buffer[cursor++];
276 * An input buffer subclass used for parsing DTS files. This manages a stack
277 * of input buffers to handle /input/ operations.
279 class text_input_buffer
281 std::unordered_set<std::string> defines;
283 * The cursor is the input into the input stream where we are currently reading.
287 * The current stack of includes. The current input is always from the top
290 std::stack<std::shared_ptr<input_buffer>> input_stack;
294 const std::vector<std::string> include_paths;
296 * Reads forward past any spaces. The DTS format is not whitespace
297 * sensitive and so we want to scan past whitespace when reading it.
301 * Returns the character immediately after the current one.
303 * This method does not look between files.
307 * If a /include/ token is encountered, then look up the corresponding
308 * input file, push it onto the input stack, and continue.
310 void handle_include();
312 * The base directory for this file.
314 const std::string dir;
316 * The file where dependencies should be output.
321 * Construct a new text input buffer with the specified buffer as the start
322 * of parsing and the specified set of input paths for handling new
325 text_input_buffer(std::unique_ptr<input_buffer> &&b,
326 std::unordered_set<std::string> &&d,
327 std::vector<std::string> &&i,
328 const std::string directory,
330 : defines(d), include_paths(i), dir(directory), depfile(deps)
332 input_stack.push(std::move(b));
335 * Skips all characters in the input until the specified character is
340 * Parse an expression. If `stopAtParen` is set, then only parse a number
341 * or a parenthetical expression, otherwise assume that either is the
342 * left-hand side of a binary expression and try to parse the right-hand
345 expression_ptr parse_expression(bool stopAtParen=false);
347 * Parse a binary expression, having already parsed the right-hand side.
349 expression_ptr parse_binary_expression(expression_ptr lhs);
351 * Return whether all input has been consumed.
355 return input_stack.empty() ||
356 ((input_stack.size() == 1) && input_stack.top()->finished());
359 * Dereferencing operator. Returns the current character in the top input buffer.
361 inline char operator*()
363 if (input_stack.empty())
367 return *(*input_stack.top());
370 * Increments the cursor, iterating forward in the buffer.
372 inline text_input_buffer &operator++()
374 if (input_stack.empty())
379 auto &top = *input_stack.top();
388 * Consumes a character. Moves the cursor one character forward if the
389 * next character matches the argument, returning true. If the current
390 * character does not match the argument, returns false.
392 inline bool consume(char c)
402 * Consumes a string. If the (null-terminated) string passed as the
403 * argument appears in the input, advances the cursor to the end and
404 * returns true. Returns false if the string does not appear at the
405 * current point in the input.
407 * This method does not scan between files.
409 bool consume(const char *str)
411 if (input_stack.empty())
415 return input_stack.top()->consume(str);
418 * Reads an integer in base 8, 10, or 16. Returns true and advances
419 * the cursor to the end of the integer if the cursor points to an
420 * integer, returns false and does not move the cursor otherwise.
422 * The parsed value is returned via the argument.
424 * This method does not scan between files.
426 bool consume_integer(unsigned long long &outInt)
428 if (input_stack.empty())
432 return input_stack.top()->consume_integer(outInt);
435 * Reads an arithmetic expression (containing any of the normal C
436 * operators), evaluates it, and returns the result.
438 bool consume_integer_expression(unsigned long long &outInt);
440 * Consumes two hex digits and return the resulting byte via the first
441 * argument. If the next two characters are hex digits, returns true
442 * and advances the cursor. If not, then returns false and leaves the
445 * This method does not scan between files.
447 bool consume_hex_byte(uint8_t &outByte)
449 if (input_stack.empty())
453 return input_stack.top()->consume_hex_byte(outByte);
456 * Returns the longest string in the input buffer starting at the
457 * current cursor and composed entirely of characters that are valid in
460 std::string parse_node_name();
462 * Returns the longest string in the input buffer starting at the
463 * current cursor and composed entirely of characters that are valid in
466 std::string parse_property_name();
468 * Parses either a node or a property name. If is_property is true on
469 * entry, then only property names are parsed. If it is false, then it
470 * will be set, on return, to indicate whether the parsed name is only
471 * valid as a property.
473 std::string parse_node_or_property_name(bool &is_property);
475 * Parses up to a specified character and returns the intervening
476 * characters as a string.
478 std::string parse_to(char);
480 * Advances the cursor to the start of the next token, skipping
481 * comments and whitespace. If the cursor already points to the start
482 * of a token, then this function does nothing.
484 text_input_buffer &next_token();
486 * Location in the source file. This should never be interpreted by
487 * anything other than error reporting functions of this class. It will
488 * eventually become something more complex than an `int`.
490 class source_location
492 friend class text_input_buffer;
494 * The text buffer object that included `b`.
496 text_input_buffer &buffer;
498 * The underlying buffer that contains this location.
500 std::shared_ptr<input_buffer> b;
502 * The offset within the current buffer of the source location.
505 source_location(text_input_buffer &buf)
507 b(buf.input_stack.empty() ? nullptr : buf.input_stack.top()),
508 cursor(b ? b->cursor : 0) {}
511 * Report an error at this location.
513 void report_error(const char *msg)
517 buffer.parse_error(msg, *b, cursor);
521 buffer.parse_error(msg);
526 * Returns the current source location.
528 source_location location()
533 * Prints a message indicating the location of a parse error.
535 void parse_error(const char *msg);
537 * Reads the contents of a binary file into `b`. The file name is assumed
538 * to be relative to one of the include paths.
540 * Returns true if the file exists and can be read, false otherwise.
542 bool read_binary_file(const std::string &filename, byte_buffer &b);
545 * Prints a message indicating the location of a parse error, given a
546 * specified location. This is used when input has already moved beyond
547 * the location that caused the failure.
549 void parse_error(const char *msg, input_buffer &b, int loc);
554 #endif // !_INPUT_BUFFER_HH_