Merge pull request #8829 from ethereum/docs-for-yul-optimizations-option

Minimal docs for --yul-optimizations option

docs/metadata.rst

@@ -82,8 +82,12 @@ explanatory purposes.
             deduplicate: false,
             cse: false,
             constantOptimizer: false,
-            yul: false,
+            yul: true,
-            yulDetails: {}
+            // Optional: Only present if "yul" is "true"
+            yulDetails: {
+              stackAllocation: false,
+              optimizerSteps: "dhfoDgvulfnTUtnIf..."
+            }
           }
         },
         metadata: {

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..."
             }
           }
         },

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.