analyzer: more state machine documentation

gcc/analyzer/ChangeLog:
	* sm-fd.dot: Fix typo in comment.
	* sm-file.dot: New file.
	* varargs.cc: Fix typo in comment.
	* varargs.dot: New file.

Signed-off-by: David Malcolm <dmalcolm@redhat.com>

4 files changed, 125 insertions, 2 deletions

diff --git a/gcc/analyzer/sm-fd.dot b/gcc/analyzer/sm-fd.dot
index 175daae..5c9984a 100644
--- a/gcc/analyzer/sm-fd.dot
+++ b/gcc/analyzer/sm-fd.dot
@@ -18,7 +18,7 @@ You should have received a copy of the GNU General Public License
 along with GCC; see the file COPYING3.  If not see
 <http://www.gnu.org/licenses/>.  */
 
-/* Keep this in-sync with sm-dot.cc  */
+/* Keep this in-sync with sm-fd.cc  */
 
 digraph "fd" {
 
diff --git a/gcc/analyzer/sm-file.dot b/gcc/analyzer/sm-file.dot
new file mode 100644
index 0000000..ac0f361
--- /dev/null
+++ b/gcc/analyzer/sm-file.dot
@@ -0,0 +1,67 @@
+/* An overview of the state machine from sm-file.cc.
+   Copyright (C) 2022 Free Software Foundation, Inc.
+   Contributed by David Malcolm <dmalcolm@redhat.com>.
+
+This file is part of GCC.
+
+GCC is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3, or (at your option)
+any later version.
+
+GCC is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GCC; see the file COPYING3.  If not see
+<http://www.gnu.org/licenses/>.  */
+
+/* Keep this in-sync with sm-file.cc  */
+
+digraph "file" {
+
+  /* STATES. */
+
+  /* Start state.  */
+  start;
+
+  /* State for a FILE * returned from fopen that hasn't been checked for
+     NULL.
+     It could be an open stream, or could be NULL.  */
+  unchecked;
+
+  /* State for a FILE * that's known to be NULL.  */
+  null;
+
+  /* State for a FILE * that's known to be a non-NULL open stream.  */
+  nonnull;
+
+  /* State for a FILE * that's had fclose called on it.  */
+  closed;
+
+  /* Stop state, for a FILE * we don't want to track any more.  */
+  stop;
+
+  /* TRANSITIONS. */
+
+  /* On "fopen".  */
+  start -> unchecked [label="on 'X = fopen(...);'"];
+
+  /* On "fclose".  */
+  start -> closed [label="on 'close(X);'"];
+  /* TODO: is it safe to call fclose (NULL) ? */
+  unchecked -> closed [label="on 'close(X);'"];
+  null -> closed [label="on 'close(X);'"];
+  nonnull -> closed [label="on 'close(X);'"];
+  closed -> stop [label="on 'close(X);':\nWarn('double fclose')"];
+
+  /* on_condition.  */
+  unchecked -> nonnull [label="on 'X != 0'"];
+  unchecked -> null [label="on 'X == 0'"];
+
+  /* Leaks.  */
+  unchecked -> stop [label="on leak:\nWarn('leak')"];
+  nonnull -> stop [label="on leak:\nWarn('leak')"];
+}
diff --git a/gcc/analyzer/varargs.cc b/gcc/analyzer/varargs.cc
index f7d4838..6fc20f0 100644
--- a/gcc/analyzer/varargs.cc
+++ b/gcc/analyzer/varargs.cc
@@ -216,7 +216,7 @@ public:
   }
   std::unique_ptr<pending_diagnostic> on_leak (tree var) const final override;
 
-  /* State for a va_list that the result of a va_start or va_copy.  */
+  /* State for a va_list that is the result of a va_start or va_copy.  */
   state_t m_started;
 
   /* State for a va_list that has had va_end called on it.  */
diff --git a/gcc/analyzer/varargs.dot b/gcc/analyzer/varargs.dot
new file mode 100644
index 0000000..b456c96
--- /dev/null
+++ b/gcc/analyzer/varargs.dot
@@ -0,0 +1,56 @@
+/* An overview of the state machine from varargs.cc
+   Copyright (C) 2022 Free Software Foundation, Inc.
+   Contributed by David Malcolm <dmalcolm@redhat.com>.
+
+This file is part of GCC.
+
+GCC is free software; you can redistribute it and/or modify it
+under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 3, or (at your option)
+any later version.
+
+GCC is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GCC; see the file COPYING3.  If not see
+<http://www.gnu.org/licenses/>.  */
+
+/* Keep this in-sync with varargs.cc  */
+
+digraph "va_list" {
+
+  /* STATES. */
+
+  /* Start state.  */
+  start;
+
+  /* State for a va_list that is the result of a va_start or va_copy.  */
+  started;
+
+  /* State for a va_list that has had va_end called on it.  */
+  ended;
+
+  /* TRANSITIONS. */
+
+  /* on_va_start: */
+  start -> started [label="on 'va_start(X, ...)'"];
+
+  /* on_va_copy: */
+  start -> started [label="on 'va_copy(X, ...)'"];
+  // in check_for_ended_va_list:
+  ended -> ended [label="on 'va_copy(X, ...)':\nWarn('use after va_end')"];
+
+  /* on_va_arg: */
+  started -> started [label="on 'va_arg(X, ...)'"];
+  started -> started [label="on 'va_copy(..., X)'"];
+  // in check_for_ended_va_list:
+  ended -> ended [label="on 'va_arg(X, ...)':\nWarn('use after va_end')"];
+
+  /* on_va_end: */
+  started -> ended [label="on 'va_end(X)'"];
+  // in check_for_ended_va_list:
+  ended -> ended [label="on 'va_end(X)':\nWarn('use after va_end')"];
+}