[Letux-kernel] dt-bindings: converting .txt to .yaml

[H. Nikolaus Schaller]

> Am 22.10.2019 um 21:14 schrieb H. Nikolaus Schaller <hns at goldelico.com>:
> 
> After searching a full day I think I have found it deeply buried...
> 
> https://lwn.net/Articles/771621/
> says in "Current status and further plans":
> 
> 	"An additional tool, doc2yaml, exists in Herring's tree, but has not been submitted;
> 	 the script can be used for a preliminary conversion of a device-tree binding file in the current text format to the YAML one."
> 
> That is what I have been searching for.
> 
> THE TOOL IS HERE:
> 
> 	https://git.kernel.org/pub/scm/linux/kernel/git/robh/linux.git/log/?h=yaml-bindings
> 
> Should be prominently documented somewhere!
> 
> Well, while I agree on all goals of the approach:
>  https://elinux.org/images/6/6b/LPC2018_json-schema_for_Devicetree.pdf
> 
> 	• Define a DT schema language
> 		• ○  Human friendly
> 		• ○  Machine readable
> 		• ○  Include binding documentation
> 	• ●  Better tooling
> 		• ○  Validate DTS files at build time
> 		• ○  Validate DT Schema files are in the correct format
> 		• ○  Useful error and warning messages
> 	• ●  Leverage existing technology
> 		○ Use existing schema validation framework ■ Extended to handle quirks of DT
> 		• ○  Don’t write a lot of code!
> 		• ○  Don’t define an entirely new language!
> 	● Generate Specification Documentation from Schema files
> 
> the first bullet point "Human friendly" is something to doubt.
> Doubtlessly, "YAML" is well "Human readable" - but is it also "Human writable"?
> And, it only needs to be machine readable...
> 
> As a kernel bindings developer I only have to care about writing the yaml schemes.
> 
> Unfortunately, the set of tools to *write* dt-bindings.yaml seems to be almost non-existant.
> 
> Ok, let's stop complaining and better give the doc2yaml tool a try to show what it does.

Well, some prerequisites:
1. needs python 3.7
2. I had to modify the hard-coded /usr/bin link because my python is installed elsewhere
3. needs pip3 to install ruaml.yaml package
4. then it works :)

It does well:
* create template
* translate title, document name, description
* prepare for "properties"
* add a "history" section which contains the original .txt

But it is a good and helpful start.

The next step is to use https://github.com/robherring/dt-schema/blob/master/example-schema.yaml
to go through the properties and example in "history" and manually translate things.

Unfortunately I can't run

make dt_binding_check dtbs_check

The second complains about dt-mk-schema command not found and the second
requires a libyaml development package.

So I have to dig even deeper...

BR,
Nikolaus