1 files changed, 53 insertions, 18 deletions
diff --git a/llvm/docs/CommandGuide/FileCheck.rst b/llvm/docs/CommandGuide/FileCheck.rst
index 0072c9c..49db571 100644
--- a/llvm/docs/CommandGuide/FileCheck.rst
+++ b/llvm/docs/CommandGuide/FileCheck.rst
@@ -112,10 +112,11 @@ and from the command line.
   Sets a filecheck pattern variable ``VAR`` with value ``VALUE`` that can be
   used in ``CHECK:`` lines.
 
-.. option:: -D#<NUMVAR>=<NUMERIC EXPRESSION>
+.. option:: -D#<FMT>,<NUMVAR>=<NUMERIC EXPRESSION>
 
-  Sets a filecheck numeric variable ``NUMVAR`` to the result of evaluating
-  ``<NUMERIC EXPRESSION>`` that can be used in ``CHECK:`` lines. See section
+  Sets a filecheck numeric variable ``NUMVAR`` of matching format ``FMT`` to
+  the result of evaluating ``<NUMERIC EXPRESSION>`` that can be used in
+  ``CHECK:`` lines.  See section
   ``FileCheck Numeric Variables and Expressions`` for details on supported
   numeric expressions.
 
@@ -588,27 +589,44 @@ numeric expression constraint based on those variables via a numeric
 substitution. This allows ``CHECK:`` directives to verify a numeric relation
 between two numbers, such as the need for consecutive registers to be used.
 
-The syntax to define a numeric variable is ``[[#<NUMVAR>:]]`` where
-``<NUMVAR>`` is the name of the numeric variable to define to the matching
-value.
+The syntax to define a numeric variable is ``[[#%<fmtspec>,<NUMVAR>:]]`` where:
+
+* ``%<fmtspec>`` is an optional scanf-style matching format specifier to
+  indicate what number format to match (e.g. hex number).  Currently accepted
+  format specifiers are ``%u``, ``%x`` and ``%X``.  If absent, the format
+  specifier defaults to ``%u``.
+
+* ``<NUMVAR>`` is the name of the numeric variable to define to the matching
+  value.
 
 For example:
 
 .. code-block:: llvm
 
-    ; CHECK: mov r[[#REG:]], 42
+    ; CHECK: mov r[[#REG:]], 0x[[#%X,IMM:]]
+
+would match ``mov r5, 0xF0F0`` and set ``REG`` to the value ``5`` and ``IMM``
+to the value ``0xF0F0``.
 
-would match ``mov r5, 42`` and set ``REG`` to the value ``5``.
+The syntax of a numeric substitution is ``[[#%<fmtspec>,<expr>]]`` where:
 
-The syntax of a numeric substitution is ``[[#<expr>]]`` where ``<expr>`` is an
-expression. An expression is recursively defined as:
+* ``%<fmtspec>`` is the same matching format specifier as for defining numeric
+  variables but acting as a printf-style format to indicate how a numeric
+  expression value should be matched against.  If absent, the format specifier
+  is inferred from the matching format of the numeric variable(s) used by the
+  expression constraint if any, and defaults to ``%u`` if no numeric variable
+  is used.  In case of conflict between matching formats of several numeric
+  variables the format specifier is mandatory.
 
-* a numeric operand, or
-* an expression followed by an operator and a numeric operand.
+* ``<expr>`` is an expression. An expression is in turn recursively defined
+  as:
 
-A numeric operand is a previously defined numeric variable, or an integer
-literal. The supported operators are ``+`` and ``-``. Spaces are accepted
-before, after and between any of these elements.
+  * a numeric operand, or
+  * an expression followed by an operator and a numeric operand.
+
+  A numeric operand is a previously defined numeric variable, or an integer
+  literal. The supported operators are ``+`` and ``-``. Spaces are accepted
+  before, after and between any of these elements.
 
 For example:
 
@@ -616,6 +634,7 @@ For example:
 
     ; CHECK: load r[[#REG:]], [r0]
     ; CHECK: load r[[#REG+1]], [r1]
+    ; CHECK: Loading from 0x[[#%x,ADDR:] to 0x[[#ADDR + 7]]
 
 The above example would match the text:
 
@@ -623,6 +642,7 @@ The above example would match the text:
 
     load r5, [r0]
     load r6, [r1]
+    Loading from 0xa0463440 to 0xa0463447
 
 but would not match the text:
 
@@ -630,8 +650,10 @@ but would not match the text:
 
     load r5, [r0]
     load r7, [r1]
+    Loading from 0xa0463440 to 0xa0463443
 
-due to ``7`` being unequal to ``5 + 1``.
+Due to ``7`` being unequal to ``5 + 1`` and ``a0463443`` being unequal to
+``a0463440 + 7``.
 
 The syntax also supports an empty expression, equivalent to writing {{[0-9]+}},
 for cases where the input must contain a numeric value but the value itself
@@ -646,8 +668,21 @@ to check that a value is synthesized rather than moved around.
 A numeric variable can also be defined to the result of a numeric expression,
 in which case the numeric expression is checked and if verified the variable is
 assigned to the value. The unified syntax for both defining numeric variables
-and checking a numeric expression is thus ``[[#<NUMVAR>: <expr>]]`` with each
-element as described previously.
+and checking a numeric expression is thus ``[[#%<fmtspec>,<NUMVAR>: <expr>]]``
+with each element as described previously. One can use this syntax to make a
+testcase more self-describing by using variables instead of values:
+
+.. code-block:: gas
+
+    ; CHECK: mov r[[#REG_OFFSET:]], 0x[[#%X,FIELD_OFFSET:12]]
+    ; CHECK-NEXT: load r[[#]], [r[[#REG_BASE:]], r[[#REG_OFFSET]]]
+
+which would match:
+
+.. code-block:: gas
+
+    mov r4, 0xC
+    load r6, [r5, r4]
 
 The ``--enable-var-scope`` option has the same effect on numeric variables as
 on string variables.