[PATCH] nvme: add ctrl state machine pdf creator

[PATCH] nvme: add ctrl state machine pdf creator

[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.

Signed-off-by: Chaitanya Kulkarni <kch@nvidia.com>
---
 .../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

diff --git a/Documentation/nvme/host-ctrl-state-machine/Makefile b/Documentation/nvme/host-ctrl-state-machine/Makefile
new file mode 100644
index 000000000000..916ce24b1b2f
--- /dev/null
+++ b/Documentation/nvme/host-ctrl-state-machine/Makefile
@@ -0,0 +1,4 @@
+all:
+	dot -Tps ctrl-state-machine.dot -o ctrl-state-machine.pdf
+clean:
+	rm -fr ctrl-state-machine.pdf
diff --git a/Documentation/nvme/host-ctrl-state-machine/ctrl-state-machine.dot b/Documentation/nvme/host-ctrl-state-machine/ctrl-state-machine.dot
new file mode 100644
index 000000000000..9c277112c5df
--- /dev/null
+++ b/Documentation/nvme/host-ctrl-state-machine/ctrl-state-machine.dot
@@ -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]
+}
-- 
2.29.0

Re: [PATCH] nvme: add ctrl state machine pdf creator

[Christoph Hellwig]

On Wed, Jul 27, 2022 at 02:54:24PM -0700, Chaitanya Kulkarni wrote:
> 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();
	..

Re: [PATCH] nvme: add ctrl state machine pdf creator

[Chaitanya Kulkarni]

On 7/28/22 11:40, Christoph Hellwig wrote:
> On Wed, Jul 27, 2022 at 02:54:24PM -0700, Chaitanya Kulkarni wrote:
>> 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?
> 

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.

> 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