Skip to content

Feature/remove toc not included warnings #721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
sipke wants to merge 8 commits into
base: master
Choose a base branch
from
Draft

Feature/remove toc not included warnings #721

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
264bbd7
docs: adjust readme files to have a title
Mar 9, 2026
94473e5
docs: shorten title for integration with open-amp readthedocs
Mar 9, 2026
bab97f7
docs: reduce toc depth for integration with open-amp readthedocs
Mar 9, 2026
13ff2bc
docs: fix table formatting in zephyr docs
Mar 9, 2026
76e067f
docs: fix duplicate auto labels in zephyr docs
Mar 9, 2026
dcc0c50
docs: add empty line after bullet list to remove warning
Mar 9, 2026
731d6e8
docs: add delimiter to remove start-string without end-string warning
Mar 9, 2026
3285e5f
specification: fix duplicate auto labels when autolabel enabled in sp…
Mar 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 23 additions & 21 deletions README-architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
# Lopper processing flow:
# Lopper Architecture

## Lopper processing flow:

Lopper is data driven and only performs operations or invokes assist routines as
specified by its inputs (command line or operation files). This means that
Expand Down Expand Up @@ -85,7 +87,7 @@ The flow of lopper processing is broken into the following broad categories:
files. An exit and trap handler are part of lopper and will clean up in the
case or normal or abnormal exit.

# Lopper Classes / Routines:
## Lopper Classes / Routines:

Lopper contains the following classes for use when manipulating a system device
tree:
Expand Down Expand Up @@ -134,7 +136,7 @@ the latest detailed information on lopper, execute the following:
% pydoc3 lopper/dt.py
% pydoc3 lopper/schema.py

# Lopper Inputs / Outputs:
## Lopper Inputs / Outputs:

Although most inputs and outputs from Lopper are dts files (or dtb in rare cases),
YAML/JSON is also supported. While not everything can (or should) be expressed in
Expand All @@ -149,7 +151,7 @@ To aid decoding and interpretation of properties carried in a LopperTree, if a
node has been created from yaml, the LopperNode field '_source' is set to "yaml"
or "json" (otherwise it is "dts").

# Lopper Tree and complex (non-dts) types:
## Lopper Tree and complex (non-dts) types:

Depending on the input format, complex data types or associated data are
carried in the Lopper tree.
Expand Down Expand Up @@ -196,7 +198,7 @@ assists in the pipeline

Would all match and be queued for execution in the pipeline

# Lopper operations
## Lopper operations

Lopper operations (in "lop files") are a series of base/core operations that
are largely self contained and that are be applied to the input device
Expand Down Expand Up @@ -263,7 +265,7 @@ details.

NOTE/TODO: bindings will be written for the lopper operations.

# module load: load a lopper assist module
## module load: load a lopper assist module

lop_0 {
compatible = "system-device-tree-v1,lop,load";
Expand All @@ -284,7 +286,7 @@ NOTE/TODO: bindings will be written for the lopper operations.
id = "xlnx,output,cdo";
};

# assist: call an assist function that is compatible with the id
## assist: call an assist function that is compatible with the id

lop_0 {
compatible = "system-device-tree-v1,lop,assist-v1";
Expand All @@ -299,7 +301,7 @@ NOTE/TODO: bindings will be written for the lopper operations.
// output = "<output directory>";
};

# modify: a general purpose node and property modify/delete/add/move operation
## modify: a general purpose node and property modify/delete/add/move operation

# format is: "path":"property":"replacement"
# - modify to "nothing", is a remove operation
Expand Down Expand Up @@ -366,7 +368,7 @@ NOTE/TODO: bindings will be written for the lopper operations.
};
};

# node add: copies the compiled node to the target device tree
## node add: copies the compiled node to the target device tree

# Additional operations or assists can modify this node just as if it was
# compiled into the original device tree. In this example the __...__ values
Expand Down Expand Up @@ -413,7 +415,7 @@ NOTE/TODO: bindings will be written for the lopper operations.
};


# output: write selected nodes to an output file
## output: write selected nodes to an output file

# multiple of these can be in a single lop file. They pull fields from the
# modified system device tree and write them to output files.
Expand Down Expand Up @@ -451,7 +453,7 @@ NOTE/TODO: bindings will be written for the lopper operations.
nodes = "axi.*:testprop:testvalue";
};

# conditional: do a conditional test on nodes of the tree, and execute an operation
## conditional: do a conditional test on nodes of the tree, and execute an operation

# does a set of conditional tests against a nodes in the system device tree that
# match the structure of the conditional tree found at the base defined by "cond_root".
Expand Down Expand Up @@ -684,7 +686,7 @@ NOTE/TODO: bindings will be written for the lopper operations.
};


# print: output strings during processing
## print: output strings during processing

# print provides basic string output and is primarily provided for debug purposes
# (complex output can be generated from code lops).
Expand All @@ -704,7 +706,7 @@ NOTE/TODO: bindings will be written for the lopper operations.
};


# exec: execute another lop
## exec: execute another lop

# Commonly used in combination with a conditional lop to avoid code duplication
# and execute another lopper operation. i.e. renaming a node, deleting a property
Expand Down Expand Up @@ -738,7 +740,7 @@ NOTE/TODO: bindings will be written for the lopper operations.
exec = <&track_feature>;
};

# select: select nodes to be used in other lopper operations
## select: select nodes to be used in other lopper operations

# select is provided to build up complex conditionals or series of nodes,
# It is similar to the conditional lop (and could replace it in the
Expand Down Expand Up @@ -827,7 +829,7 @@ NOTE/TODO: bindings will be written for the lopper operations.
";
};

# tree: create a subtree from specified nodes
## tree: create a subtree from specified nodes

# To allow for nodes to not only be collected for output, but also for
# modification, we have the "tree" lop.
Expand Down Expand Up @@ -866,7 +868,7 @@ NOTE/TODO: bindings will be written for the lopper operations.
nodes = "reserved-memory", "zynqmp-rpu", "zynqmp_ipi1";
};

# xlate: translate a node / properties
## xlate: translate a node / properties

# It is becoming more common that non dts compatible trees / properties
# are carried along side of device tree ones (i.e. yaml), and those
Expand Down Expand Up @@ -913,7 +915,7 @@ NOTE/TODO: bindings will be written for the lopper operations.
# in the node).


# meta-v1, phandle-desc-v1
## meta-v1, phandle-desc-v1

# lopper performs phandle validation and phandle replacement during dts /
# dtb output handling. To do these lookups, it must understand the names and
Expand Down Expand Up @@ -954,7 +956,7 @@ NOTE/TODO: bindings will be written for the lopper operations.
mynewproperty = "phandle field field";
};

# conditional execution or inhibiting of a lop execution
## conditional execution or inhibiting of a lop execution

There are two properties that can be used to control the execution of a
lop.
Expand Down Expand Up @@ -1104,7 +1106,7 @@ LopperProp routines can be used to modify the tree.
If the module has invalid code, or otherwise generates and exception, Lopper
catches it and reports the error to the user.

# Command line assists:
## Command line assists:

Commonly we want to run an assist against the loaded system device tree and exit.

Expand Down Expand Up @@ -1136,7 +1138,7 @@ tree. It can then process the arguments as it sees fit:
/bus@f1000000/dma@ffae0000: compatible = "xlnx,zynqmp-dma-1.0";
/bus@f1000000/dma@ffa90000: compatible = "xlnx,zynqmp-dma-1.0";

# output assists:
## output assists:

Output assists are similar to standard (node) assists, except they are called
when an output file extension is not recognized. Each loaded assist is queried
Expand All @@ -1157,7 +1159,7 @@ above) to the passed output filename.

The output filename is passed via the options dictionary, in the key 'outfile'

# execution samples:
## execution samples:

# testing with openamp domains
#
Expand Down
8 changes: 4 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Overview:
# Lopper Overview

Fundamentally, lopper takes an input device tree (normally a system device tree),
applies operations to that tree, and outputs one or more modified/processed trees.

See the README-architecture.txt for details on how lopper works. This README file
has practical information, known limitations and TODO items.

# config/setup:
## config/setup:

Lopper is in a single repository, and is available via git or pypi:

Expand Down Expand Up @@ -90,7 +90,7 @@ Now, everytime you'd like to use lopper, just activate and deactivate within any

% export PYTHONPATH=<path to pylibfdt>:$PYTHONPATH

# submitting patches / reporting issues
## submitting patches / reporting issues

Pull requests or patches are acceptable for sending changes/fixes/features to Lopper,
chose whichever matches your preferred workflow.
Expand All @@ -111,7 +111,7 @@ For discussion:

- Use the mailing list or the github wiki/discussions/issue tracker

# Lopper overview:
## Lopper overview:

```
lopper.py --help
Expand Down
7 changes: 3 additions & 4 deletions docs/amd/linux/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,11 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.

Welcome to Linux Device Tree Generation for AMD SOCs using Lopper and SDT's documentation!
===========================================================================================
Linux Device Tree Generation for AMD SOCs using Lopper and SDT's
================================================================
Copy link
Collaborator

@zeddii zeddii Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer to leave this as-is, there's different consumers of this, and I'm not fond of tweaking it to suit one over the others.

Copy link
Author

@sipke sipke Mar 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok. fair.


.. toctree::
:maxdepth: 3
:hidden:
:maxdepth: 2

chapter1-introduction.rst
chapter2-linux_device_tree_generation.rst
Expand Down
22 changes: 12 additions & 10 deletions docs/amd/zephyr/source/cortex-a78/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ This step transforms the domain-specific device-tree from Step 1 into a Zephyr-c
- ``{workspace}``: Output directory for generated files
- ``system-domain.dts``: Domain-specific device-tree file generated in Step 1
- ``{proc}``: Processor name (refer to the processor name in the ``pl.dtsi`` file - this varies based on the processor configuration in the Vivado design)

**Optional**: - ``{zephyr_board_dts}``: Zephyr board-specific device-tree configuration. When provided, it will be compared against the domain-specific device-tree and removes unneeded nodes as per design configuration or mapping requirements

**Output**: ``system-zephyr.dts`` - Zephyr-specific device-tree file
Expand All @@ -71,13 +72,13 @@ This step transforms the domain-specific device-tree from Step 1 into a Zephyr-c
Platform-Specific Processor Names
---------------------------------

+----------------+--------------------+
| Platform | Processor Name |
+================+====================+
| Versal Gen 2 | ``cortexa78_0`` |
+----------------+--------------------+
+----------------+---------------------+
| Platform | Processor Name |
+================+=====================+
| Versal Gen 2 | ``cortexa78_0`` |
+----------------+---------------------+
| Versal Net | ``psx_cortexa78_0`` |
+----------------+--------------------+
+----------------+---------------------+

Prerequisites
-------------
Expand All @@ -100,8 +101,8 @@ Example Workflow
For Versal Gen 2 Platform:
~~~~~~~~~~~~~~~~~~~~~~~~~~

Basic Workflow (without board-specific device-tree):
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Gen 2 Basic Workflow (without board-specific device-tree):
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Copy link
Collaborator

@zeddii zeddii Mar 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know very little about sphinx (outside of occasioning editing file and generating with it).

What is the significance of "Gen 2" in the updated lines ?

Copy link
Author

@sipke sipke Mar 17, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can enable autosectionlabel generation when using sphinx/doxygen. i.e. for every heading in an rst or md file a label is created based on the heading. https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html
Where the autosectionlabel can be used in external other rst files to reference/link these headings directly, without having to add manual labels.
Unfortunately sphinx does not prefix subheadings with the previous heading level so any subheading which is the same in multiple higher level headings is a duplicate label.
What you had is cleaner (more readable), so maybe not a good idea to change, but anyone using autosectionlabel will receive a warning currently if enabled.
The Gen 2 was just propogated from the top level heading "For Versal Gen 2 Platform:"


::

Expand All @@ -111,8 +112,9 @@ Basic Workflow (without board-specific device-tree):
# Step 2: Generate Zephyr-specific device-tree
lopper -f --enhanced -O ./output ./output/system-domain.dts ./output/system-zephyr.dts -- gen_domain_dts cortexa78_0 zephyr_dt

Advanced Workflow (with board-specific device-tree optimization):
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Gen 2 Advanced Workflow (with board-specific device-tree optimization):
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

Expand Down
21 changes: 11 additions & 10 deletions docs/amd/zephyr/source/cortex-r52/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ This step transforms the domain-specific device-tree from Step 1 into a Zephyr-c
- ``{workspace}``: Output directory for generated files
- ``system-domain.dts``: Domain-specific device-tree file generated in Step 1
- ``{proc}``: Processor name (refer to the processor name in the ``pl.dtsi`` file - this varies based on the processor configuration in the Vivado design)

**Optional**: - ``{zephyr_board_dts}``: Zephyr board-specific device-tree configuration. When provided, it will be compared against the domain-specific device-tree and removes unneeded nodes as per design configuration or mapping requirements

**Output**: ``system-zephyr.dts`` - Zephyr-specific device-tree file
Expand All @@ -71,13 +72,13 @@ This step transforms the domain-specific device-tree from Step 1 into a Zephyr-c
Platform-Specific Processor Names
---------------------------------

+----------------+--------------------+
| Platform | Processor Name |
+================+====================+
| Versal Gen 2 | ``cortexr52_0`` |
+----------------+--------------------+
+----------------+---------------------+
| Platform | Processor Name |
+================+=====================+
| Versal Gen 2 | ``cortexr52_0`` |
+----------------+---------------------+
| Versal Net | ``psx_cortexr52_0`` |
+----------------+--------------------+
+----------------+---------------------+

Prerequisites
-------------
Expand All @@ -100,8 +101,8 @@ Example Workflow
For Versal Gen 2 Platform:
~~~~~~~~~~~~~~~~~~~~~~~~~~

Basic Workflow (without board-specific device-tree):
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Gen 2 Basic Workflow (without board-specific device-tree):
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

Expand All @@ -111,8 +112,8 @@ Basic Workflow (without board-specific device-tree):
# Step 2: Generate Zephyr-specific device-tree
lopper -f --enhanced -O ./output ./output/system-domain.dts ./output/system-zephyr.dts -- gen_domain_dts cortexr52_0 zephyr_dt

Advanced Workflow (with board-specific device-tree optimization):
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Gen 2 Advanced Workflow (with board-specific device-tree optimization):
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

Expand Down
1 change: 1 addition & 0 deletions docs/amd/zephyr/source/microblaze-riscv/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ This step transforms the domain-specific device-tree from Step 1 into a Zephyr-c
- ``lop-microblaze-riscv.dts``: Hardware configuration file containing tuning flags in YAML format
- ``system-domain.dts``: Domain-specific device-tree file generated in Step 1
- ``{proc}``: Processor name (same as Step 1)

**Optional**: - ``{zephyr_board_dts}``: Zephyr board-specific device-tree configuration. When provided, it will be compared against the domain-specific device-tree and removes unneeded nodes as per design configuration or mapping requirements

**Output**: ``system-zephyr.dts`` - Zephyr-specific device-tree file
Expand Down
8 changes: 4 additions & 4 deletions specification/source/chapter4-bus-firewalls.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,8 @@ the Bus Master ID of the device:
bus-master-id = <&lpd_xppu 0x212>;
};

Full Example
~~~~~~~~~~~~
Full Example Hardware Description
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: dts

Expand Down Expand Up @@ -184,8 +184,8 @@ listed in the firewallconf property:
In this example, we want to block all bus-master-ids except for the ones
of domain-0 and domain-1.

Full Example
~~~~~~~~~~~~
Full Example Firewall Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Two domains are block access from everybody else to their resources with
the exception of two devices, ethernet and serial0, which are shared
Expand Down
2 changes: 1 addition & 1 deletion specification/source/chapter6-simplified-yaml.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -282,7 +282,7 @@ These special key values are an extension to YAML merge keys: <<+ and <<*
to specify multiple aliases, if a single alias is specified
(in a list or not) then this is equivalent to <<

<<*: Future: Indicates that node expansion/inheritance should be
<<\*: Future: Indicates that node expansion/inheritance should be
performed. This allows the multiple inheritance of YAML
nodes (in the current implementation it is functionally
equivalent to <<+)
Expand Down