Device tree plumbers 2018 etherpad

Top Device Tree page

Device Tree Microconference Notes
Welcome to Linux Plumbers Conference 2018

The structure will be short introductions to an issue or topic followed by a discussion with the audience. A limit of 3 slides per presentation is enforced to ensure focus and allocate enough time for discussions..

IF SOMEONE PRESENTS MORE THAN 3 SLIDES, PLEASE HECKLE AND THROW THINGS AT THEM!

Please use this Etherpad to take notes. Microconf leaders will be giving a TWO MINUTE summary of their microconference during the Thursday afternoon closing session.

Add your name to the list of editors

Please add your name in the right column of this web page so we can identify who wrote what (you can make up an anonymous name if you want) 1. cliick on the "show users on this pad" icon (rightmost icon on toolbar) 1. type your name into the "unnamed" box

You can use the icons on thetop bar for headers ("Style" dropdown) and font enhancements

Please remember there is no video this year, so your notes are the only record of your microconference.

There is video of the audience, but not video of the slides.

Slides will be posted at 
 * https://elinux.org/Device_tree_future#Linux_Plumbers_2018
 * https://elinux.org/Device_Tree_presentations_papers_articles

The slides should also be available by downloading on the conference schedule (they may not all be there yet)

Miniconf leaders: Please remember to take note of the approximate number of attendees in your session(s).

Please help us take notes at: https://etherpad.openstack.org/p/Device_Tree

9:00 Welcome & Introduction
Slides and notes will be made available from plumbers and the elinux site (see link above)
 * Maintainers present: Frank, Rob, Grant

9:10 Q&A Session 1 + General Discussion
Overview? Rob: Devicetree.org update
 * small trickle of patches going in.   Connector binding (GPIO) is recent focus,
 * spec release planned for end of year, moving into annual cadence.
 * looking for help with reviewing bindings, converting bindings to schema, etc.

9:25 json-schema for DT bindings and validation
Overview of past attempts with links (see slides) Currently around 3000 binding documents... Lots of YAML downside: Custom language, syntax,various attempts at constraints json-schema approach has some strong tooling advantages
 * problem areas - lack of toolchian support/checking, freeform text,  too much manual review

Define a DT schema language

Sean reconfirms that everyone understands what Rob is talking about

Its going to be messy to transition, but better to try to be as close as possible, and then we can fix later.

Does DT schema actually solve the underlying problem of people not understanding hardware? - no, doesn't help in this aspect at all.

DTS is interesting language, converting it into a type language will improve things. DTS has typing, DTB does not.

Using json-schema leverage exisiting tooling, create specification

Kernel should be able to tell if devicetree conforms to schema (Frank) Don't allow the DTB to built if fails (Mark) How can we have runtime validation? - device and overlay source - number of permutations - do runtime validation in kernel? lots of complexity - when overlays, required.

FPGA manager (Moritz) looking at properties of overlays? reject if it doesn't pass?

Challenge is there are 1000's of warnings, mostly it's defining more rules around bindings.

Using Draft 6 for schema vocabulary.

Done in YAML since (perceived) better human readabiliity Subject to change, don't use it as fixed format Tools implemented in python3

Rob's directory has meta schema to validate schema. Installable with pip. Integrating into kernel build to validate docs, core schema and valid bindings. Tool to extract binding doc, and build schema doc. Required a lot of time to get the build time to be reasonable.

Have we considered taking an alternate validation path so it's not in the kernel build?
 * see diagram on DT Schema Build flow from slides.

Concern: Feature of JSON schema, is it case sensitive, and if it doesn't understand a keyword, it ignores it.

Note: dts '<>' are maintained, but we may need to do some cleanup here, to be stricter.

Found interrupt cells is a case where we'd like to have type information from DTS (Grant) Grouping is there, via angle brackets,  so we'll use it. Once the schema is there, we can go back to add typing back in. It will require type information to get this information back in. Interrupt cells being nested in arrays is an example of area to be improved.

Validators can do lookups, but we're not using it yet.

Is there a linter to help with the gotchas (indentation sensitive, etc.) (Kate) Rob has written a format tool (name?) to help with this.

For reg and regnames - how can we express they have to be the same size? Some work in upstream to address, but not there today.

What's the relation between JSON and YAML? (Sean) YAML is a superset of JSON. JSON schema is no relationship to JSON. JSON can always be read by Y:AML parser. YAML gives us comments, that helps us maintain files,  and addition of type tags. JSON was designed as interchange format, YAML was designed as human writable.

Embedding Versioning into the bindings? (Sean) Schema key says metaschema validating against. We'll use a new meta-schema to validate against. Will get back after converted 100's of bindings.

Cross property dependencies can be handled by if/then/else which is new in draft 7 (but we're using draft 6).

Discussion on compatibles,  could cause significant problems and enumeration growth,  and is painful enough that we might want to define our own keyword (ordering, wildcards, ...)

json-schema patch series: https://lkml.org/lkml/2018/10/5/883  targetting v.4.21.

Help wanted with conversion, what's the strategy to get rid of the warnings?

Can we get some orientation information available for maintainers and formulate a transition plan for all the files? (Kate) (reach out to existing creators, etc.)

Rob's working on GPIO, but nothing structured beyond there for the transition

Can we include licensing changes as part of transition plan? (Kate)   If no response,  remove/drop dts. Dual licensing will be really important here (Olof)

Which way leaning? (Sean) Rob, GPL-2.0,  but copyright is Linaro/ARM so relicensing should be straightforward.

10:15 DT memory size (kernel, bootloader, FDT)
Patches from Rob decreased memory use, Nicolas Pitre reported success
 * Ignore disabled nodes now possible if there's not reference
 * Remove full path from np->full_name

Increases: What is the cause of the bloat at end of the graph? Unmaintained DTS? (Kate) No analysis has been done, but there is a listing of size by DTS are there.
 * making nodes kobjects (making this optional helped, though)
 * phandle cache
 * overlay metadata (symbols)
 * currently not in the right place
 * overhead for problematic DTs are prohibitive to always enable symbols with dtc -@

There are other opportunities for reducing the szie of the DTB files (Grant)... and now for Simon. ;-)

went thourgh slide poposals  net:  about 40% size savings with the proposal are possible.

Doc here https://docs.google.com/document/d/1-4Mj3slh7SpX9Q28F3VRYmWKVk0gW2ZxO8O6cjQDK8Y/edit#heading=h.5irk4csrpu0y

We want it to be decompressible from the outset (Mark)

Overview of measures proposed in the slides (generally quite significant savings can be achieved)

How would mapping work if we don't have compatible strings?
 * First come first served (Sean) ?
 * What about out of tree users? (Frank)

Conversion table might be an option?

Are there other ideas?

Multiple projects using it now beyond Linux ( Zephyr, U-Boot, Tianocore, BSDs) Challenge is how can we get all the stakeholders in the same room? Probably ELCE/OpenIoT Europe is probably best point.

Where else has this proposal been discussed? Simon is showing this here for the first time. Sean indicates it will be useful to start the socialization on the mail lists, etc.

Behan - which direction is DMA being used is worth considering? Separate property.

Simon - indicates there are some ways to get things down that Zephyr should consider https://www.elinux.org/File:Device_tree_in_U-Boot_SPL.pdf https://docs.google.com/presentation/d/1OR4u1bDnT_WQHikypRcmIX_hKrIvNCrUdtQbSX_M4xo/edit#slide=id.g27382790ad_0_0

11:10 New FDT Format & Overlays
Slides are at https://elinux.org/Device_Tree_presesntations_papers_articles

Need to have version and compatibilty of Header form at compatibility. Preference to go with big hard break. Lots of project involved.

Pointers to subblock within FDT. Strings blocks are byte aligned, and can be pointed to within.

Frank overviews parsing implications, and if we're going to break compatibility, we should do it. In particular, tags are going to drive incompatibility. Space savings are potentially large.

Can we make the change in such a way that we can avoid breaking them in future? (Rob) Addign complexity into what a tag can be might be able to achieve's Rob's goal. Maybe base on Simon's proposal

Need to figure out what is wrong libfdt API first, so we can do inplace parsing of the tree, and we have a transition path, then we can experiment about what is the best way to do this? (Grant) - phandle is going to be painful, and is the benefit worth it. Wrip on the bandage? Then experiment with format. Figure out what is really needed, rather than bandaid fixes approach makes sense. (Simon) fdt_get_property returns a struct, and if we preserve with new properties behind,  decode the new structure,  see any problems with approach? (Sean) Simon agrees could be possible Grant indicates we have scope problem, how do we allocate the space. Behan indicats there are not many places to do it in and out of tree. May be a big problem.

Simon, already code in there, if an old version, returns null. fdt_get_property_by_offset: /* Prior to version 16, properties may need realignment * and this API does not work. fdt_getprop_* will, however. */

if (fdt_version(fdt) < 0x10) return NULL;

See overlay slides from Frank. (link??)

Who is the decision maker? David Gibson will be deciding.

Applying overlays from a run kernel userspace? Frank has observations on what we need to resolve to phase this in. Things like memory leak issues, locking,  user after free. FPGA are using overlays.

Frank doesn't want to accept the overlay use case until we have a firm foundation. Want to get rid of as many problems as we can, so we can walk into it over time.

11:40 FPGA + DT
Mortiz Problem most DT code predates DT overlays,   4.19 FPGA manager does not have a workable userspace interface for DT based systems. See Documentation/devicetree/bindings/fpga/fpga-region.txt for more info on the original plan as well as slides for good history.

What if we lockdown where we apply overlays? Whitelist approach was proposed, using DT connectors.

Frank indicates it been discussed, but no solid conclusion.

Assuming we fix up the implementation, can we salvage Alan's RFC and make this work?

Grant wonders if we should be treating these as security bugs? Rob wonders if FPGA manager should have its own link? Frank asks how load it from userspace? Possibly cat together and make a header? Its not clear what can overlay, and what can't.

Frank, some properties if only add new nodes if not modifying existing nodes. Challenge is goes against some semantics already in use. Rob, what do we do if an overlay tries to change a memory size? Other agrees its an issue.

Frank, overlay code should be doing this sort of checking,  shouldn't be done outside.

Behan concerned we're baking policy into the kernel with the comments. (FPGAs can change hardware, etc. memory, etc.). Frank, we will allow subsets of functionalities.

Mark wants to make sure the use case of the fact that we can have same connectors that work with multple boards. (96 boards, beagle boards, etc) that should be considered (PINMUXing is not standard, but outcomes are standard).

Frank connector description is tied to SoC not the board? Does this help...

12:10 Summary, Action Items, and closing
Request is for all folks here to read the notes, and update the etherpad/edit/add things in,  fix anything that is wrong, etc.

How can we document this / teach this and bring people forward?
 * who's going to write some of the docs.

Action items
 * 1) Create a transition plan for moving DT binding documents between features /licensing. - how to make it real?
 * 2) Need a howto document for people creating schemas (typically based on existing DT binding documents.
 * 3) Who will create the schemas?
 * 4) Bindings are currently GPL.  There is an interest in dual licensing them.
 * 5) Connectors - needs someone to drive?
 * 6) This has withered on the vine.  Additional discussion is required to determine if this is a viable approach.
 * 7) Mark Brown mentioned that Linus Walleij has done some work on a plugin module for a board file
 * 8) Frank will review and respond
 * 9) How can we whitelist drivers - Alan & Moritz will handle and get a proposal.
 * 10) Alan/Moritz will revive this patchset and resubmit with existing concerns, if any, addressed
 * 11) Simon will publish proposal around size improvements.
 * 12) Sean observed that there are multiple proposals around sizing, and it would be good to get mature and capture.
 * 13) This should provide good suggestions and data to the FDT format update
 * 14) Frank will restart the discussion around the flattened device tree format update
 * 15) solicit  the necessary changes from as many stakeholders as possible in the first pass
 * 16) engage other communities (dtc tools, libfdt, bootloaders, Zephy, BSD, etc.)
 * 17) Simon would like to discuss ordering....  libfdt first?   then more freedom to change.
 * 18) Frank indicates we need to change the use of kernel struct property in live tree API (unflattend)
 * 19) Possibly allocate memory and return the allocated memory.
 * 20) The caller is then responsible for freeing the memory.
 * 21) This is to prevent use after free issues and is unrelated to FDT format changes
 * 22) This is a a long standing issue that Frank would like to address
 * 23) Libfdt API Changes for Bootloader (U-Boot initially)
 * 24) If existing accessors of the FDT property entries are provided a pointer to the entry then they need to be modified for the new format
 * 25) An alternative is to create a new API that copies the property value into newly allocated memory and returns a pointer to the new memory
 * 26) Possible issue with drivers having to free memory allocated in libfdt
 * 27) Need to audit any locations in the kernel that directly access the unflattened tree
 * 28) they will have the same issues as listed for bootloader accesses of FDT property entry pointers
 * 29) Rob indicates the kernel uses strings and boundaries.
 * 30) Possibly survey this first, and then see how widespread it actually is.
 * 31) Folding in the tags is important.

12:30 Lunch
https://etherpad.openstack.org/p/Device_Tree   <--- this document