From 5bc06e8250d10cc15c19bc74c70f201b8fd11a2b Mon Sep 17 00:00:00 2001 From: Ulf Magnusson Date: Mon, 16 Sep 2019 19:04:41 +0200 Subject: [PATCH] doc: release notes: Mention devicetree script changes for 2.0 and 2.1 Added in 2.0, along with some binding format simplifications in 2.1. Bunch of other stuff that could be mentioned, but keep it relatively short. Signed-off-by: Ulf Magnusson --- doc/guides/dts/index.rst | 65 ++++++++++++++++++++++++++++++ doc/releases/release-notes-2.0.rst | 21 ++++++++++ doc/releases/release-notes-2.1.rst | 5 +++ 3 files changed, 91 insertions(+) diff --git a/doc/guides/dts/index.rst b/doc/guides/dts/index.rst index 7e03e7bb83a..174ec299959 100644 --- a/doc/guides/dts/index.rst +++ b/doc/guides/dts/index.rst @@ -449,6 +449,71 @@ Below is a template that shows the format of binding files, stored in .. literalinclude:: ../../../dts/binding-template.yaml :language: yaml +.. _legacy_binding_syntax: + +Legacy binding syntax +===================== + +Various parts of the binding syntax were simplified and generalized for the +Zephyr 2.1 release. + +The binding below shows various legacy syntax. + +.. code-block:: yaml + + title: ... + description: ... + + inherits: + !include foo.yaml + + parent: + bus: spi + + properties: + compatible: + constraint: "company,device" + type: string-array + + frequency: + type: int + category: optional + + sub-node: + properties: + child-prop: + type: int + category: required + +This should now be written like this: + +.. code-block:: yaml + + title: ... + description: ... + + compatible: "company,device" + + include: foo.yaml + + parent-bus: spi + + properties: + frequency: + type: int + required: false + + child-node: + title: ... + description: ... + + properties: + child-prop: + type: int + required: true + +The legacy syntax is still supported for backwards compatibility, but generates +deprecation warnings. Support will be dropped in the Zephyr 2.3 release. Include files generation ************************ diff --git a/doc/releases/release-notes-2.0.rst b/doc/releases/release-notes-2.0.rst index e9c33597881..5e977096f97 100644 --- a/doc/releases/release-notes-2.0.rst +++ b/doc/releases/release-notes-2.0.rst @@ -448,6 +448,27 @@ Bluetooth Build and Infrastructure ************************ +* The devicetree Python scripts have been rewritten to be more robust and + easier to understand and change. The new scripts are these three files: + + - :zephyr_file:`scripts/dts/dtlib.py` -- a low-level :file:`.dts` parsing + library + + - :zephyr_file:`scripts/dts/edtlib.py` -- a higher-level library that adds + information from bindings + + - :zephyr_file:`scripts/dts/gen_defines.py` -- generates a C header from the + devicetree files for the board + + The new scripts verify ``category: optional/required`` and ``type:`` settings + given in bindings for nodes, and add some new types, like ``phandle-array``. + Error messages and other output is now more helpful. + + See the updated documentation in :zephyr_file:`dts/binding-template.yaml`. + + The old scripts are kept around to generate a few deprecated ``#define``\ s. + They will be removed in the Zephyr 2.2 release. + * Changed ARM Embedded toolchain to default to nano variant of newlib diff --git a/doc/releases/release-notes-2.1.rst b/doc/releases/release-notes-2.1.rst index 6c0f5c887b2..13d5b6b5a3f 100644 --- a/doc/releases/release-notes-2.1.rst +++ b/doc/releases/release-notes-2.1.rst @@ -50,6 +50,11 @@ Build and Infrastructure Use new functions that utilize eDTS info such as dt_node_reg_addr. See :zephyr_file:`scripts/kconfig/kconfigfunctions.py` for details. +* Various parts of the binding format have been simplified. The format is + better documented now too. + + See :ref:`legacy_binding_syntax` for more information. + Libraries / Subsystems ***********************