From 550e79de20091cb5ed7faade2962c06799915f2c Mon Sep 17 00:00:00 2001
From: Andreas Rossberg <rossberg@chromium.org>
Date: Thu, 25 Aug 2022 20:53:40 +0200
Subject: [PATCH] [spec] Add note to instruction index (#1528)

---
 document/core/appendix/gen-index-instructions.py | 9 +++++++++
 document/core/appendix/index-instructions.rst    | 5 +++++
 2 files changed, 14 insertions(+)

diff --git a/document/core/appendix/gen-index-instructions.py b/document/core/appendix/gen-index-instructions.py
index 2b61b55089..65a9717155 100755
--- a/document/core/appendix/gen-index-instructions.py
+++ b/document/core/appendix/gen-index-instructions.py
@@ -21,6 +21,14 @@
 ---------------------
 """
 
+FOOTER = """\
+
+.. note::
+   Multi-byte opcodes are given with the shortest possible encoding in the table.
+   However, what is following the first byte is actually a :ref:`u32 <binary-uint>` with variable-length encoding
+   and consequently has multiple possible representations.\
+"""
+
 COLUMNS = [
     'Instruction',
     'Binary Opcode',
@@ -591,3 +599,4 @@ def Row(columns):
           print(Row(instr), file=f)
 
         print(DIVIDER, file=f)
+        print(FOOTER, file=f)
diff --git a/document/core/appendix/index-instructions.rst b/document/core/appendix/index-instructions.rst
index 0636a4266d..84055a9fa2 100644
--- a/document/core/appendix/index-instructions.rst
+++ b/document/core/appendix/index-instructions.rst
@@ -516,3 +516,8 @@ Instruction                                        Binary Opcode
 :math:`\F64X2.\VCONVERT\K{\_low\_i32x4\_s}`        :math:`\hex{FD}~~\hex{FE}~~\hex{01}`  :math:`[\V128] \to [\V128]`                    :ref:`validation <valid-vcvtop>`               :ref:`execution <exec-vcvtop>`, :ref:`operator <op-convert_s>`    
 :math:`\F64X2.\VCONVERT\K{\_low\_i32x4\_u}`        :math:`\hex{FD}~~\hex{FF}~~\hex{01}`  :math:`[\V128] \to [\V128]`                    :ref:`validation <valid-vcvtop>`               :ref:`execution <exec-vcvtop>`, :ref:`operator <op-convert_u>`    
 =================================================  ====================================  =============================================  =============================================  ==================================================================
+
+.. note::
+   Multi-byte opcodes are given with the shortest possible encoding in the table.
+   However, what is following the first byte is actually a :ref:`u32 <binary-uint>` with variable-length encoding
+   and consequently has multiple possible representations.