File 2122-compiler-Document-BEAM-SSA-invariants.patch of Package erlang

From 5bf9a59015a1253b202093074e14e2519b5c249d Mon Sep 17 00:00:00 2001
From: Frej Drejhammar <frej.drejhammar@gmail.com>
Date: Tue, 23 Mar 2021 15:38:38 +0100
Subject: [PATCH 2/2] compiler: Document BEAM SSA invariants

The BEAM SSA representation is well described type-wise, but some
aspects such as inter-instruction requirements and strategies for
creating unique names are not. This patch adds a document to the
internal documentation of the compiler describing the structure and
format of BEAM SSA in the hope that it helps first-time compiler
developers.
---
 lib/compiler/doc/src/Makefile         |  6 ++++
 lib/compiler/doc/src/internal.xml     |  1 +
 lib/compiler/internal_doc/beam_ssa.md | 43 +++++++++++++++++++++++++++
 3 files changed, 50 insertions(+)
 create mode 100644 lib/compiler/internal_doc/beam_ssa.md

diff --git a/lib/compiler/doc/src/Makefile b/lib/compiler/doc/src/Makefile
index e1c445662c..39c00935cb 100644
--- a/lib/compiler/doc/src/Makefile
+++ b/lib/compiler/doc/src/Makefile
@@ -36,6 +36,9 @@ EDOC_REF3_FILES =  cerl.xml cerl_trees.xml cerl_clauses.xml
 
 XML_PART_FILES = internal.xml
 XML_NOTES_FILES = notes.xml
+XML_INTERNAL_FILES = beam_ssa.xml
+
+XML_GEN_FILES = $(XML_INTERNAL_FILES:%=$(XMLDIR)/%)
 
 BOOK_FILES = book.xml
 
@@ -43,4 +46,7 @@ XML_FILES = \
 	$(BOOK_FILES) $(XML_NOTES_FILES) \
 	$(XML_PART_FILES) $(XML_REF3_FILES) $(XML_APPLICATION_FILES)
 
+$(XMLDIR)/%.xml: ../../internal_doc/%.md $(ERL_TOP)/make/emd2exml
+	$(ERL_TOP)/make/emd2exml $< $@
+
 include $(ERL_TOP)/make/doc.mk
diff --git a/lib/compiler/doc/src/internal.xml b/lib/compiler/doc/src/internal.xml
index f24b363c1c..4167f43e95 100644
--- a/lib/compiler/doc/src/internal.xml
+++ b/lib/compiler/doc/src/internal.xml
@@ -34,5 +34,6 @@
   <xi:include href="cerl.xml"/>
   <xi:include href="cerl_trees.xml"/>
   <xi:include href="cerl_clauses.xml"/>
+  <xi:include href="beam_ssa.xml"/>
 </internal>
 
diff --git a/lib/compiler/internal_doc/beam_ssa.md b/lib/compiler/internal_doc/beam_ssa.md
new file mode 100644
index 0000000000..29ad019194
--- /dev/null
+++ b/lib/compiler/internal_doc/beam_ssa.md
@@ -0,0 +1,43 @@
+Invariants on the Structure and Format of BEAM SSA
+==================================================
+
+Function Calls
+--------------
+
+All function calls not in a tail call position must be followed by a
+succeeded:body-instruction unless one of the following exceptions
+apply:
+
+* The function call can statically be proven to always fail.
+
+* The function call is to the `erlang`-module and can statically be
+  proven to always succeed or fail.
+
+Variable Naming
+---------------
+
+A variable name in BEAM SSA is either an atom, a non-negative integer
+or a tuple: `atom() | non_neg_integer() | {atom() | non_neg_integer(),
+non_neg_integer()}`. In order to generate fresh unused variable names,
+all compiler transforms maintain a counter, the `cnt`-field in the
+`opt_st`-record, which is incremented each time a new variable or
+label is created. In the following description the value of the
+`cnt`-field is called `Cnt`.
+
+Due to peculiarities in the BEAM SSA code generator, a compiler
+transformation unfortunately cannot just use the `cnt`-value directly
+as a fresh name. There are three basic strategies for creating fresh
+variable names which can by used by a compiler pass:
+
+1) A name can be derived from an existing name of the form `V ::
+  atom() | non_neg_integer()` by selecting an atom, which is unique to
+  the compiler pass, to form a new name `{A, V}`. The same `A` cannot
+  be used by strategy 3) below.
+
+2) A name can be derived from an existing name of the form `V ::
+  non_neg_integer()` by combining it with the `cnt`-field into `{V,
+  Cnt}`.
+
+3) A fresh name can be created by selecting an atom `A`, which is
+  unique to the compiler pass, to form the new name `{A, Cnt}`. The
+  same `A` cannot be used by strategy 1) above.
-- 
2.26.2