View source for Device tree plumbers 2016 etherpad

[[Category:Device_tree]]

[[Device_Tree | Top Device Tree page]]

== Local cache of Linux Plumbers 2016 Device Tree Track etherpad notes ==

Device Tree Microconference Notes

Welcome to Linux Plumbers Conference 2016

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.

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

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

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

About 60 people attended this session.

SCHEDULE

=== etherpad location ===

hello everyone  etherpad URL: https://etherpad.openstack.org/p/LPC2016_Device_Tree


=== Welcome by Frank ===

=== Device Tree Schema Discussion - by Grant Likely ===

New Specification for Device Tree
* Linaro started beginning of 2016
* old EPAPR spec has been opened and reformatted (sphynx)
* Then things stalled...
* Uneasy about converting bindings from human form to another human form
* We would like mechanical validation.

Matt Porter did some stuff with YAML a year ago.
* Didn't want to only do text-based work.

Now have a proposal for schema validation.
* Want to talk about schema and tools
* Matt Porter proposed a YAML syntax - that's where Grant started.
* What is the grammar to use to validate the content of the bindings
* How do we write a tool to validate device tree files

Still needs to be human readable, suitable for doc generation

Conceptual model:
* Every single node of the tree has been validated
* How to map schema files to nodes?  How to inherit?  How to determine which schemas are applicable?
* idea: load or index all schemas available, and then walk the tree
**    find every schema that matches each node compatible values can be used for matching any node/property not validates is flagged as error or warning

Schema example: see slides
* key properties: pattern and schema
* pattern = criteria for applying schema
* schema = validation for attributes

pattern notes:
* match property contains a list of things that have to match (at least one)
* match needs to be expressive, but most of the time, this will be compatible strings
** Question: how to enforce required children?
** Answer: can put in schema for parent, or..

envision tool loading everything and then matching nodes to schema items

schema notes:
* list of properties that can exist
* for each one:

** name, whether required, pattern of data in the property, human readable description

* can have core schema definitions with general requirements
* allow special casing

* can inherit schema attributes to avoid repetition

Grammar:
* BNF, JSON, something else
* Settled on BNF (kind-of)
* what kinds of things need to be validated:
** bytes, cells, uints, ints, strings, phandle
* first thing is to specify the property name itself
* 2 dots for parent, 3 dots for ancestor path

* more grammar elements:
** string-list

* use #<name>-cells ancestor reference to specify size of cells for this schema definition

* more difficult for interrupts, because you have to find which ancestor is the one providing the size info

Implementation:
* use of pyparsing - grant like this a lot
* can very quickly play around with syntax

Rob Herring started something similar last year based on Matt's work.
* Rob looked at how to convert the current documentation.
* He used the DTS files and instrumented DTC to dump our each nodes properties
* Had mass conversion of the documentation tree
* Question: was code released
** Answer:
** commented on Matt's YAML syntax, got no feedback, moved on...
** Also, code is here: https://git.kernel.org/cgit/linux/kernel/git/robh/linux.git/log/?h=dt-yaml-v2

Grant: would like some YAML syntax modifications based on work done so far

Generating the syntax is easy.

Rob recommends worrying about the schema syntax intricacies later.  Grand schemes don't work.

Just get started with something.

Need to stop reviewing differences in how people write binding documentation.  Would be nice to get to that point.

Question: if you write a syntax that doesn't work, we would have to re-write it later
* Answer: could start with a few simple requirements, and add specializations later.
* Answer2: once the bindings are parseable we can convert to another format later.

Anything we do now  to make bindings parseable would be good progress.

This will change the way we submit bindings.
* Need to avoid confusion about submission requirements.
* Need to communicate clearly, when bindings need to be submitted under the new regime.
* There will be lots of work to do once we start applying the validation to existing bindings
* Can ask maintainers to help convert existing bindings.

We won't get suffering to zero - still need to validate that the driver is dooing the right thing.

Frank working on a tool to show which properties are being accessed.  Tool shows
what properties are being accessed at runtime.  Was presented at ELCE. see: http://events.linuxfoundation.org/sites/events/files/slides/dt_debugging_part_3_0.pdf

Comment on rationale: board files used compiler to check validity of structures, types, etc.  This
makes up for that loss of functionality in the conversion to DT.
This also helps developers know exactly what they should put into the bindings.

Want to reduce information in documentation files

devicetree-spec is the mail list to use to discuss this.   Location of room on Thursday to further discussion will be posted to this mail list.

Optional properties started to get complicated.
* Grant has thought about this.
* Need a way to determine when a property is optional or not.
* Can possibly use groupings

Can start with small schemas and grow in complexity over time.
* Can put the human-readable requirements for properties and values into description nodes (mechanically parsed, but not validated)
* As we add syntax, it should not break existing schema files.

Validator will help convert from a system of human validation of dts by intepreting the binding doc,
to one where the computer can help us validate DTS and detect bugs when they are malformed.

=== Device Tree: Hardware Description vs. Configuration vs. Policy by Frank Rowand ===

Talk is about issue of what is actually in the device tree definitions?
* is a way of describing hardware that is not discoverable
* ePAPR is vague on details also

Boils down to things like: vendor id, where in the memory address space, etc.
like a PCI header, but more complex

We say it's a description of hardware, but more
example of more: chosen node = parameters from firmware (this is not hardware)

Should DT contain things other than hardware description?
* If so, what should be there?  How to explain this to others?  How to agree on what is acceptable?
* If something doesn't belong in device tree, where should it go?

Not always clear what category an item fits in.

types of information:
* hardware description (ex address, range of baud rates, interrupt line, set of pins and how they're wired)
* configuration (ex. specific baud rate to set, which mux to use for a pinmux group)
* policy/tuning (ex. clock frequency for best performance)

communication channels = a mechanism to transfer opaque data
state = property that reports current state (ex. status)
* can have an overlay that changes status from disabled to enabled
* state normally lives in drivers

other configuration examples: stdoutpath = configuration or state?

example of what the hardware is doing right now (=state)

another example of state: configuration of endpoints chosen by uboot, but represents state

A certain amount of state can't be ignored by the kernel.  ex. Current speed of UART.

Maybe say "dts describes the platform", not "dts describes the hardware"

Some of what's in DTS is based on taste.

Grant is comfortable with definitions being a little loose, as long as we can push back.

Guidance is valuable as opposed to hard-and-fast rules.

Trying to put something like a small amount of config for a device into dts
is OK - more sane to just use DTS than force this into the firmware system.

concern amount implementing firmware in DT due to license issue (often firmware
has proprietary license)

default position is DTS doesn't support firmware - need a good argument to support it.

FPGAs are weird (and how) - hardware defined by software.

providing information about state is consistent with notion of telling kernel something
it can't determine.  Maybe use the chosen node - kernel command line to convey info
like this.  Having the bootloader convey what state it left the hardware in is a good thing.

Wanted to use device tree for heterogeneous nodes, and have done so.
* google ieee p2415

Zephyr is looking at device tree.  Device tree isn't just for Linux - other systems use it.

Why not describe the clock tree in DT - response was "that's too much information".

Question: How do you decide how much to put in DT vs driver?
* Answer: It's a judgement call on device-by-device basis.  Take into account what we've learned from previous bindings.  Use the smallest binding you can.
* Generally want to match the node size to the size of IP block.

In qualcomm case, it's convenient to override values in text rather than C source, for small changes to clock definitions.

descriptive information:
* proscriptive info - DT tells the driver what to do to work around an issue
* descriptive - sd-broken-highspeed - can take something that doesn't fit the DT mental model, and change it to something that does fit.

Avoid things that are are linux-specific (put partition type, not name of Linux probe routine)

examples of configuration:
* ex. regulator-always-on - tells the driver how to behave ??
** can represent physical constraint on the system.  Could do a special property, but it's more complicated.

message-to-bootloader:  DT describes the firmware API (reboot-mode)

dynamic-clock-gating/standby-mode example - really difficult case
* We should let developers know not to copy this example.

Description can help frame the mental model and help a binding get accepted.

radio-band definitions:
* how big of a firmware image is acceptable to put into device tree?

How to tell developers what's acceptable?
* Are we describing the hardware or the state of the machine (platform)?
* Will specification cover this?
* Grant: spec will describe syntax, encoding, common cases.
* other things: tension between architectures
* Grant's view: spec should cover the things that we have consensus on.
* Don't want to put bindings for individual hardware.  It's transient.
* It is important to put the conventions we are using.  We describe the platform.
* We have 'chosen' and 'operation points', and these are OK.
* Mark: We describe the platform as visible to the OS.

Describing the state of the firmware via DT is OK.

We have UEFI, UBOOT and LK firmware.  UEFO has strict API for communicating with kernel.

Question: Can we put code in DT?
* Answer: No - we have made a conscious decision to avoid putting an interpreter into DT
* (But there are exceptions. ex: coresight?)
* We're not trying to duplicate ACPI.  ACPI's model is that the firmware remains active.

How about probe ordering?  There is some implicit ordering, but desire is to avoid explicit ordering.
* There are examples of nodes with ordering info in DT already.

If you have data that the kernel does not have a good way to get, that's OK to put into DT.
* Operating points are OK - but should still be structured well.

When to put a configuration item in device tree?  There are alternatives: kernel command line, sysfs
configfs, kernel config.
* Need to look at who wants to change it? how to change it?
* Is one of these other methods easier to change than the DT for a board?

How to determine what operating points to convey to the kernel, and what properties to use to communicate them?
* e.g. when the same chip is used in different products.
* ACPI had to do this with frequency scaling.  Need to do on case-by-case basis.
* If kernel can boot, then the DT is adequate. It may be OK to leave this to a user-space governor.
* If firmware is deciding the operating point, then it's OK to convey it via DT.

Question: What is an appropriate use of an alias?
* Answer: we try to avoid them.  They function like labels.  You shouldn't use aliases to define a fixed number (only) for a device.
* Some examples: serial port numbers for ttyS[123] is good.  Kernel doesn't know how SOC ports are numbered.
* kernel probe order is not guaranteed.  Alias is the only mechanism available to guarantee the name of a device (when ordering is required).

A lot of DT questions are about tradeoff between cheaper to implement in DT vs building a framework to hold some new data.
* There's a difference between cheaper for a single developer vs. cheaper for the maintainer.

Question: Are dynamic device tree's a good match for the use case of FPGAs connected to SoCs (via PCI)?
* Answer: Sounds reasonable.
* This is similar to i2c controller on PCI - you can detect the PCI controller but not the i2c devices connected to it.
* A lot of the IP blocks you might put in an FPGA already have device drivers in the kernel, so device tree is convenient.

Question: what about device tree on x86
* Answer: there's already support for DT on x86.  But, we should not mix DT and ACPI.

A controversial topic is ACPI overlays (putting DT in ACPI or ACPI in DT).
* Don't want to have drivers that get part of their info from ACPI and part from DT.  That's nuts.
* Use case is datacenter stuff.

Is x86 fully supported?  Are overlays supported?
* Answer: don't know extent of support.  Overlays are not supported.

Question: Can you have ACPI and DT at the same time on x86?
* Answer: No.  Some ARM64 systems have support for both ACPI and DT, but the system selects one to use at runtime.  They are not used at the same time.
* You can run the DT unit tests on x86.

---------------------------
Just after this session there are some examples being presented.

=== Overlays - discussion ===

Some key participants are not here: Pantelis is not here.  David Gibson is not here. David Gibson is not here.

QuestIon: When is the loader interface going to go in?
* Answer: PPC has dynamic device tree.  Pantelis worked on overlays.
* Basic overlay support is in the kernel (not 100%, but basic mechanisms work).

How do we load an overlay into the kernel?
* Antoniou (sp?) from Free Electrons gave a talk at ELCE on the topic.
* Pantelis has submitted patches, but don't know the status.
* Want to get the plugin connector paradigm finished first.

Grant was opposed to a generic loader for security reasons.
* Want the plug concept really well defined to contain changes allowed to DT.
* Alan has a patch for overlay notifications (as a set)

Overlays can be applied at boot time, but also a bootloader could apply overlays.  Or you could process an overlay before you process the main tree.  We have to deal with dynamic additions no matter what.

Can update the DTB format to allow tagged sections with the same format as overlays.
* Would allow us to start signing sections.

2 overlay manager proposals made recently.  One from google.
* Puts overlay into base DT.
* Can select overlays to use on command line.
* other manager was about reading EEPROM from daughter cards and deciding what overlays to apply.
* From a data structure point of view - no technical reason for different encodings for all use cases

We're getting into hotplug.
* The code is there for hot unplug for DT.
* We don't free the overlay memory when it is removed.
* Model is that DT changes are applied, then notifications to the driver model are done.
* You can only remove overlays in order.
** There's a single stack of overlays.
** FPGAs have regions that are not dependent.
** First implementation of overlays was conservative.
** Dependency tracking for more complicated removal can be done if needed.

Overlays have non-trivial security issues.  Need to audit driver usage of device tree.

=== wrapup ===

Next steps for this week:   Grant propses meeting in hallway at back, then use one of BOF rooms.
* 9:30 am on Friday - device tree grammar BOF
* 2:00 pm on Friday - device tree specification BOF (devicetree.org)

Frank is using elinux.org for docs.  Contributors welcome as to what is reasonable.   Tribal history.
(ex dash vs. underscore)

Alan will organize a Discussion on plugins for FPGAs.
* Frank, Rob, Mark,  ? ....
* don't want to overlap with FPGA talk, but it might come up there.