Skip to contentSkip to conversation

nvme: add ctrl state machine pdf creator

PATCH In review Chaitanya Kulkarni 3 participants 3 messages Jul 27, 2022 – Jul 28, 2022

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 nvme: add ctrl state machine pdf creator

It is not always easy to read the NVMe Host controller state machine quickly written in C when debugging the code for various transports.

This adds a simple dot based state machine for the host controller that creates pdf. The resulting pdf is easier to understand and process.

---
 .../nvme/host-ctrl-state-machine/Makefile     |  4 +++
 .../ctrl-state-machine.dot                    | 27 +++++++++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 Documentation/nvme/host-ctrl-state-machine/Makefile
 create mode 100644 Documentation/nvme/host-ctrl-state-machine/ctrl-state-machine.dot
Documentation/nvme/host-ctrl-state-machine/Makefile new file +4 -0
new file mode 100644
index 000000000000..916ce24b1b2f
@@ -0,0 +1,4 @@
+all:
+	dot -Tps ctrl-state-machine.dot -o ctrl-state-machine.pdf
+clean:
+	rm -fr ctrl-state-machine.pdf
Documentation/nvme/host-ctrl-state-machine/ctrl-state-machine.dot new file +27 -0
new file mode 100644
index 000000000000..9c277112c5df
@@ -0,0 +1,27 @@
+/*
+ * NVMe Host Controller State transition diagram
+ * dot -Tps nvme-ctrl-state-machine.dot -o nvme-ctrl-state-machine.pdf
+ */
+digraph NVMe_Controller_State_Machine {
+NEW -> LIVE
+NEW -> CONNECTING
+NEW -> RESETTING
+CONNECTING -> LIVE
+CONNECTING -> DELETING
+LIVE -> RESETTING
+LIVE -> DELETING
+RESETTING -> CONNECTING
+RESETTING -> DELETING
+RESETTING -> LIVE
+DEAD -> DELETING_NOIO
+DELETING -> DELETING_NOIO
+DELETING -> DEAD
+
+NEW [shape=polygon,sides=5,peripheries=3,color=lightblue,style=filled]
+LIVE [color=green,style=filled]
+CONNECTING [color=yellow,style=filled]
+RESETTING [color=lightyellow,style=filled]
+DELETING [color=pink,style=filled]
+DEAD [color=red,style=filled]
+DELETING_NOIO [shape=polygon,sides=5,peripheries=3,color=maroon,style=filled]
+}
Signature · 1 line
2.29.0
#1 lore raw
Quoted 5 lines · Chaitanya Kulkarni

It is not always easy to read the NVMe Host controller state machine quickly written in C when debugging the code for various transports.

This adds a simple dot based state machine for the host controller that creates pdf. The resulting pdf is easier to understand and process.

So, the graph looks pretty, but I'm a little worried that having a separate copy of the transitions somewhere out in Documentation/ just means it will become out of date very quickly. Can we instead come up with macros that allow to both generate the code and the visualization?

e.g.

	switch (new_state) {
	FROM_STATE(NVME_CTRL_LIVE);
		TO_STATE(NVME_CTRL_NEW);
		TO_STATE(NVME_CTRL_RESETTING);
		TO_STATE(NVME_CTRL_CONNECTING);
		END_STATE();
	..
#2 lore raw
Quoted 4 lines · Christoph Hellwig
Quoted 3 lines · Chaitanya Kulkarni

It is not always easy to read the NVMe Host controller state machine quickly written in C when debugging the code for various transports.

Quoted 9 lines
Quoted 2 lines

This adds a simple dot based state machine for the host controller that creates pdf. The resulting pdf is easier to understand and process.

So, the graph looks pretty, but I'm a little worried that having a separate copy of the transitions somewhere out in Documentation/ just means it will become out of date very quickly. Can we instead come up with macros that allow to both generate the code and the visualization?

I'll make sure to update the graph when reviewing the new branch.

I did thought of adding the documentation in in the drivers/nvme/host/ctrl-state-machine, but found it odd to have it in the nvme/host.

Quoted 10 lines

e.g.

	switch (new_state) {
	FROM_STATE(NVME_CTRL_LIVE);
		TO_STATE(NVME_CTRL_NEW);
		TO_STATE(NVME_CTRL_RESETTING);
		TO_STATE(NVME_CTRL_CONNECTING);
		END_STATE();
	..

I fail to understand the part that links the C code from host/core.c to the pdf in the graph, can you please explain more on this ?

I was trying to avoid new code changes and add more macros for the documentation purpose, let me see if I can do come up with something with minimal complexity.

-ck