Interrupt tree example (current Fig 2.3) does not show in PDF

[wmamills]

The current Fig 2.3: Interrupt tree example is just blank in the PDF.
I am not sure how to fix it.

[robherring]

Note that it was fine in v0.3, but broken in main/v0.4-rc1.

[robherring]

I'd guess it is related to this (the only warning in the pdf build):

WARNING: dot code 'digraph tree {\nrankdir = LR\nranksep = "1.5"\nsize = "6,8"\nedge [ dir="none" ]\nnode [ shape="Mrecord" width="2.5" ]\n\nsubgraph cluster_devices {\n label = "Devicetree"\n graph [ style = dotted ]\n "soc" [ ]\n "device1" [ label = "device1 | interrupt-parent=\<&open-pic\>" ]\n "device2" [ label = "device2 | interrupt-parent=\<&gpioctrl\>" ]\n "pci-host" [ label = "pci-host | interrupt-parent=\<&open-pic\>" ]\n "slot0" [ label = "slot0 | interrupt-parent=\<&pci-host\>" ]\n "slot1" [ label = "slot1 | interrupt-parent=\<&pci-host\>" ]\n "simple-bus" [ label = "simple-bus" ]\n "gpioctrl" [ label = "gpioctrl | interrupt-parent=\<&open-pic\>" ]\n "device3" [ label = "device3 | interrupt-parent=\<&gpioctrl\>" ]\n\n edge [dir=back color=blue]\n "soc":e -> "device1":w\n "soc":e -> "device2":w\n "soc":e -> "open-pic":w\n "soc":e -> "pci-host":w\n "soc":e -> "simple-bus":w\n "pci-host":e -> "slot0":w\n "pci-host":e -> "slot1":w\n "simple-bus":e -> "gpioctrl":w\n "simple-bus":e -> "device3":w\n}\n\nsubgraph cluster_interrupts {\n label = "Interrupt tree"\n graph [ style = dotted ]\n\n "i-open-pic" [ label = "open-pic | Root of Interrupt tree" ]\n "i-pci-host" [ label = "pci-host | Nexus Node" ]\n "i-gpioctrl" [ label = "gpioctrl | Nexus Node" ]\n "i-device1" [ label = "device1" ]\n "i-device2" [ label = "device2" ]\n "i-device3" [ label = "device3" ]\n "i-slot0" [ label = "slot0" ]\n "i-slot1" [ label = "slot1" ]\n\n edge [dir=back color=green]\n "i-open-pic":e -> "i-device1":w\n "i-open-pic":e -> "i-pci-host":w\n "i-open-pic":e -> "i-gpioctrl":w\n "i-pci-host":e -> "i-slot0":w\n "i-pci-host":e -> "i-slot1":w\n "i-gpioctrl":e -> "i-device2":w\n "i-gpioctrl":e -> "i-device3":w\n}\n\nsubgraph {\n edge [color=red, style=dotted, constraint=false]\n "open-pic" -> "i-open-pic"\n "gpioctrl":w -> "i-gpioctrl"\n "pci-host" -> "i-pci-host"\n "slot0":e -> "i-slot0":e\n "slot1":e -> "i-slot1":e\n "device1" -> "i-device1"\n "device2":e -> "i-device2":w\n "device3":e -> "i-device3":e\n}\n}\n': dot exited with error:
[stderr]
b'Warning: flat edge between adjacent nodes one of which has a record shape - replace records with HTML-like labels\n Edge i-device1 -> device1\nError: lost device1 i-device1 edge\n'

[wmamills]

It looks like that diagram did not change between v0.3 and main tip so I assume the difference must be in the tools.
You have not rebuilt v0.3 pdf with the new flow right?

[wmamills]

The edge in question device1 to i-device1 is missing in v0.3 pdf also. I think the tooling is now deleting the whole image on any error.

I have stared at this for awhile. I don't understand how pci-host to i-pci-host works and device1 to i-device-1 does not.

[robherring]

Maybe @glikely has some ideas as he got all the image stuff working.

[wmamills]

OK here is what I have found.
I am not a dot/graphviz user and I hate to be the new user that blames the compiler but ...

I am convinced this is a bug in dot/graphviz.
Others have the same problem: mdaines/viz-js#134
It is reported to have started with 2.40 (and I currently have 2.42.2-3ubuntu2 on Ubuntu 20.04)

Changing the shape of the nodes DOES fix the problem but the diagram then looks horrible.
The problem occurs when record or mrecord shapes are right on top of each other with no node in between.
I tried to rearrange the order of the nodes in the diagram but dot is putting them in an order it likes from the connections.
(Perhaps a more experienced dot user could help rearrange the nodes)

The error message says to use HTML labels but then the doc page says:
http://www.graphviz.org/doc/info/shapes.html#html
"""
Adding HTML labels to record-based shapes (record and Mrecord) is discouraged and may lead to unexpected behavior because of their conflicting label schemas and overlapping functionality.
"""
My suggestions are workarounds but they are:

1. comment out the device1 to i-device1 edge until dot can be fixed (it was not coming through before, so this gets us back to the v0.3 diagram.
   -or-
2. Delete the whole red dotted line section. I don't think they are really needed and adds a good bit of clutter to the diagram.

[wmamills]

I sent workaround 1 in a PR just in case.
Ignore it if your not ready to accept defeat as I am.

[daviewales]

The current version of the website appears to still be on 0.3, which doesn't show the image:
You can still view it in the 0.2 version:
https://devicetree-specification.readthedocs.io/en/v0.2/devicetree-basics.html#example-interrupt-tree

But it doesn't appear for 0.3:
https://devicetree-specification.readthedocs.io/en/v0.3/devicetree-basics.html#example-interrupt-tree

Nor for latest:
https://devicetree-specification.readthedocs.io/en/latest/chapter2-devicetree-basics.html#example-interrupt-tree