1af0dd31fSDavid Chisnall$FreeBSD$ 2af0dd31fSDavid Chisnall 3af0dd31fSDavid ChisnallNotes for people hacking on dtc 4af0dd31fSDavid Chisnall=============================== 5af0dd31fSDavid Chisnall 6af0dd31fSDavid ChisnallThis file contains some notes for people wishing to hack on dtc. 7af0dd31fSDavid Chisnall 8af0dd31fSDavid ChisnallUpstreaming 9af0dd31fSDavid Chisnall----------- 10af0dd31fSDavid Chisnall 11af0dd31fSDavid ChisnallThis code is developed in the FreeBSD svn repository: 12af0dd31fSDavid Chisnall 13af0dd31fSDavid Chisnallhttps://svn.freebsd.org/base/head/usr.bin/dtc 14af0dd31fSDavid Chisnall 15af0dd31fSDavid ChisnallIf you got the source from anywhere else and wish to make changes, please 16af0dd31fSDavid Chisnallensure that you are working against the latest version, or you may end up 17af0dd31fSDavid Chisnallfixing bugs that are already fixed upstream. Although the license makes no 18af0dd31fSDavid Chisnallrequirement that you share any improvements that you make, patches are very 19af0dd31fSDavid Chisnallwelcome. 20af0dd31fSDavid Chisnall 21af0dd31fSDavid ChisnallC++11 22af0dd31fSDavid Chisnall----- 23af0dd31fSDavid Chisnall 24*70d7ec67SDavid ChisnallThis project uses C++11, as the goal for FreeBSD 11 is to require C/C++11 as a 25*70d7ec67SDavid Chisnallminimum, either from clang or an external toolchain. In particular, it uses 26*70d7ec67SDavid Chisnall`std::unique_ptr` extensively for memory management within the tree. Unique 27*70d7ec67SDavid Chisnallpointers are also used in several other places to track ownership. 28af0dd31fSDavid Chisnall 29*70d7ec67SDavid ChisnallMost iterator loops use the new loop syntax and the `auto` type for type 30*70d7ec67SDavid Chisnalldeduction. Range-based `for` loops generally improve the readability of the 31*70d7ec67SDavid Chisnallcode, though `auto` should only be used in places where the type can be deduced 32*70d7ec67SDavid Chisnallas easily by the reader as by the compiler. 33af0dd31fSDavid Chisnall 34*70d7ec67SDavid ChisnallThe code also makes use of `static_assert()` to track compile-time invariants. 35af0dd31fSDavid Chisnall 36af0dd31fSDavid ChisnallAdding New Checks 37af0dd31fSDavid Chisnall----------------- 38af0dd31fSDavid Chisnall 39af0dd31fSDavid ChisnallCurrently, the biggest weakness of this version of the tool is that it lacks 40af0dd31fSDavid Chisnallmost of the semantic checkers that can be implemented by simply reading the 41af0dd31fSDavid ChisnallePAPR spec. The `checker` class provides a simple superclass for implementing 42af0dd31fSDavid Chisnallthese quite easily. There are also helper methods on `device_tree` for finding 43af0dd31fSDavid Chisnallspecific nodes, for checks that require some understanding of the structure of 44af0dd31fSDavid Chisnallthe tree. 45af0dd31fSDavid Chisnall 46af0dd31fSDavid ChisnallWe should probably add a parent pointer to the `node` class for easily walking 47af0dd31fSDavid Chisnallup the tree. 48af0dd31fSDavid Chisnall 49af0dd31fSDavid ChisnallAdding Direct C Output 50af0dd31fSDavid Chisnall---------------------- 51af0dd31fSDavid Chisnall 52af0dd31fSDavid ChisnallThe FreeBSD build system currently uses dtc to generate a blob and then 53af0dd31fSDavid Chisnallconverts this to C source code. A new `output_writer` subclass could easily 54af0dd31fSDavid Chisnallgenerate the C directly. 55af0dd31fSDavid Chisnall 56af0dd31fSDavid ChisnallParser Improvements 57af0dd31fSDavid Chisnall------------------- 58af0dd31fSDavid Chisnall 59af0dd31fSDavid ChisnallThere are a few FIXME lines in the parser for some corner cases that are not 60af0dd31fSDavid Chisnallcurrently used by FreeBSD. These are mainly related to labels in the middle of 61af0dd31fSDavid Chisnallvalues. These can be fixed by creating a new `property_value` with the 62af0dd31fSDavid Chisnallspecified label, starting at the location of the label. Don't forget to remove 63af0dd31fSDavid Chisnallthe associated comments from the BUGS section of the man page if you fix this. 64