doc: Add documentation about devicetree usage

At present some of the ideas and techniques behind devicetree in U-Boot
are assumed, implied or unsaid. Add some documentation to cover how
devicetree is build, how it can be modified and the rules about using
the various CONFIG_OF_... options.

Commit-notes:
This patch attracted quite a bit of discussion here:

https://patchwork.ozlabs.org/project/uboot/patch/20210909201033.755713-4-sjg@chromium.org/

I have not included the text suggested by François. While I agree that
it would be useful to have an introduction in this space, I do not agree
that we should have two devicetrees or that U-Boot should not have its own
things in the devicetree, so it is not clear to me what we should actually
write.

The 'Devicetree Control in U-Boot' docs were recently merged and these
provide some base info, for now.
END

Series-to: u-boot
Series-version: 4
Series-links: 261659
Series-cc: Mark Kettenis <mark.kettenis@xs4all.nl>
Series-cc: trini, heinrich
Series-cc: Sean Anderson <seanga2@gmail.com>
Series-cc: Ilias Apalodimas <ilias.apalodimas@linaro.org>
Series-changes: 2
- Fix typos per Sean (thank you!) and a few others
- Add a 'Use of U-Boot /config node' section
- Drop mention of dm-verity since that actually uses the kernel cmdline
- Explain that OF_BOARD will still work after these changes (in
  'Once this bug is fixed...' paragraph)
- Expand a bit on the reason why the 'Current situation' is bad
- Clarify in a second place that Linux and U-Boot use the same devicetree
  in 'To be clear, while U-Boot...'
- Expand on why we should have rules for other projects in
  'Devicetree in another project'
- Add a comment as to why devicetree in U-Boot is not 'bad design'
- Reword 'in-tree U-Boot devicetree' to 'devicetree source in U-Boot'
- Rewrite 'Devicetree generated on-the-fly in another project' to cover
  points raised on v1
- Add 'Why does U-Boot have its nodes and properties?'
- Add 'Why not have two devicetrees?'

Series-changes: 3
- Clarify the 'bug' refered to at the top
- Reword 'This means that there' paragraph to explain U-Boot-specific things
- Move to doc/develop/devicetree now that OF_CONTROL is in the docs

Cover-letter:
doc: Clarify how U-Boot makes use of devicetree
This series includes a documentation update to clarify how U-Boot makes
use of devicetree and its requirements when working with other firmware
projects.

Once agreed it should provide more clarity in this area, which seems to
have devolved into a confusing mire recently.

My goal here is to sort out this area one and for all, clearly documenting
the use cases and implications of them. I hope that the end result of this
(substantial) effort will be a shared understanding of how to move
forward in U-Boot and hopefully some ideas for firmware in general.

It also cleans up the config binding since this has got a bit out-of-date.
END

Signed-off-by: Simon Glass <sjg@chromium.org>
Reviewed-by: Marcel Ziswiler <marcel.ziswiler@toradex.com>
40 jobs for dt-working in 2 minutes and 16 seconds (queued for 4 seconds)
latest
Status Name Job ID Coverage
  Testsuites
passed Build envtools #324261

00:00:12

passed Build tools-only #324260

00:00:12

passed Check for configs without MAINTAINERS entry #324259

00:00:10

passed cppcheck #324255

00:00:19

passed grep TODO/FIXME/HACK #324256

00:00:13

passed htmldocs #324257

00:00:57

passed Run binman, buildman, dtoc, Kconfig and patman testsuites #324262

00:01:22

canceled Run tests for Nokia RX-51 (aka N900) #324263

00:01:22

passed sloccount #324258

00:00:39

 
  Test.Py
canceled evb-ast2500 test.py #324268

canceled integratorcp_cm926ejs test.py #324270

canceled qemu_arm64 test.py #324272

canceled qemu_arm test.py #324271

canceled qemu_malta64el test.py #324276

canceled qemu_malta64 test.py #324275

canceled qemu_maltael test.py #324274

canceled qemu_malta test.py #324273

canceled qemu-ppce500 test.py #324277

canceled qemu-riscv32_spl test.py #324280

canceled qemu-riscv32 test.py #324278

canceled qemu-riscv64_spl test.py #324281

canceled qemu-riscv64 test.py #324279

canceled qemu-x86_64 test.py #324283

canceled qemu-x86 test.py #324282

canceled r2dplus_i82557c test.py #324284

canceled r2dplus_pcnet test.py #324285

canceled r2dplus_rtl8139 test.py #324286

canceled r2dplus_tulip test.py #324287

canceled sandbox_flattree test.py #324269

canceled sandbox_noinst_test.py #324267

canceled sandbox_spl test.py #324266

canceled sandbox test.py #324264

canceled sandbox with clang test.py #324265

canceled xilinx_versal_virt test.py #324289

canceled xilinx_zynq_virt test.py #324288

canceled xtfpga test.py #324290

 
  World Build
canceled build all 32bit ARM platforms #324291

canceled build all 64bit ARM platforms #324292

canceled build all other platforms #324294

canceled build all PowerPC platforms #324293