From d037f7a3c599c04e1909107f019c43b30b162644 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kamil=20=C5=9Aliwak?= <kamil.sliwak@codepoets.it>
Date: Mon, 4 May 2020 15:45:08 +0200
Subject: [PATCH 1/2] docs: Info about --yul-optimizations and optimizer steps
 in Yul section

---
 docs/yul.rst | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/docs/yul.rst b/docs/yul.rst
index 6e8654ff5..b99dd18c1 100644
--- a/docs/yul.rst
+++ b/docs/yul.rst
@@ -1034,3 +1034,56 @@ If you want to use Solidity in stand-alone Yul mode, you activate the optimizer
     solc --strict-assembly --optimize
 
 In Solidity mode, the Yul optimizer is activated together with the regular optimizer.
+
+Optimization step sequence
+--------------------------
+
+By default the Yul optimizer applies its predefined sequence of optimization steps to the generated assembly.
+You can override this sequence and supply your own using the `--yul-optimizations` option when compiling
+in Solidity mode:
+
+.. code-block:: sh
+
+    solc --optimize --ir-optimized --yul-optimizations 'dhfoD[xarrscLMcCTU]uljmul'
+
+By enclosing part of the sequence in square brackets (`[]`) you tell the optimizer to repeatedly
+apply that part until it no longer improves the size of the resulting assembly.
+You can use brackets multiple times in a single sequence but they cannot be nested.
+
+The following optimization steps are available:
+
+============ ===============================
+Abbreviation Full name
+============ ===============================
+f            `BlockFlattener`
+l            `CircularReferencesPruner`
+c            `CommonSubexpressionEliminator`
+C            `ConditionalSimplifier`
+U            `ConditionalUnsimplifier`
+n            `ControlFlowSimplifier`
+D            `DeadCodeEliminator`
+v            `EquivalentFunctionCombiner`
+e            `ExpressionInliner`
+j            `ExpressionJoiner`
+s            `ExpressionSimplifier`
+x            `ExpressionSplitter`
+I            `ForLoopConditionIntoBody`
+O            `ForLoopConditionOutOfBody`
+o            `ForLoopInitRewriter`
+i            `FullInliner`
+g            `FunctionGrouper`
+h            `FunctionHoister`
+T            `LiteralRematerialiser`
+L            `LoadResolver`
+M            `LoopInvariantCodeMotion`
+r            `RedundantAssignEliminator`
+m            `Rematerialiser`
+V            `SSAReverser`
+a            `SSATransform`
+t            `StructuralSimplifier`
+u            `UnusedPruner`
+d            `VarDeclInitializer`
+============ ===============================
+
+Some steps depend on properties ensured by `BlockFlattener`, `FunctionGrouper`, `ForLoopInitRewriter`.
+For this reason the Yul optimizer always applies them before applying any steps supplied by the user.

From 457cc754d02d54bf4c4a576d5e32b6a79b633047 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kamil=20=C5=9Aliwak?= <kamil.sliwak@codepoets.it>
Date: Mon, 4 May 2020 15:45:44 +0200
Subject: [PATCH 2/2] docs: Info about optimizerSteps field in Standard JSON
 input and metadata listings

---
 docs/metadata.rst           | 8 ++++++--
 docs/using-the-compiler.rst | 5 ++++-
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/docs/metadata.rst b/docs/metadata.rst
index 0c8ae47f1..96a02c43a 100644
--- a/docs/metadata.rst
+++ b/docs/metadata.rst
@@ -82,8 +82,12 @@ explanatory purposes.
             deduplicate: false,
             cse: false,
             constantOptimizer: false,
-            yul: false,
-            yulDetails: {}
+            yul: true,
+            // Optional: Only present if "yul" is "true"
+            yulDetails: {
+              stackAllocation: false,
+              optimizerSteps: "dhfoDgvulfnTUtnIf..."
+            }
           }
         },
         metadata: {
diff --git a/docs/using-the-compiler.rst b/docs/using-the-compiler.rst
index ea573ed70..84b4ef9d7 100644
--- a/docs/using-the-compiler.rst
+++ b/docs/using-the-compiler.rst
@@ -231,7 +231,10 @@ Input Description
             "yulDetails": {
               // Improve allocation of stack slots for variables, can free up stack slots early.
               // Activated by default if the Yul optimizer is activated.
-              "stackAllocation": true
+              "stackAllocation": true,
+              // Select optimization steps to be applied.
+              // Optional, the optimizer will use the default sequence if omitted.
+              "optimizerSteps": "dhfoDgvulfnTUtnIf..."
             }
           }
         },