| |
| <!DOCTYPE html> |
| |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" /> |
| |
| <title>Custom Sections — WebAssembly 2.0 (Draft 2024-04-28)</title> |
| <link rel="stylesheet" type="text/css" href="../_static/pygments.css" /> |
| <link rel="stylesheet" type="text/css" href="../_static/alabaster.css" /> |
| <script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script> |
| <script src="../_static/jquery.js"></script> |
| <script src="../_static/underscore.js"></script> |
| <script src="../_static/_sphinx_javascript_frameworks_compat.js"></script> |
| <script src="../_static/doctools.js"></script> |
| <script>window.MathJax = {"tex": {"maxBuffer": 30720}}</script> |
| <script defer="defer" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script> |
| <link rel="index" title="Index" href="../genindex.html" /> |
| <link rel="search" title="Search" href="../search.html" /> |
| <link rel="next" title="Soundness" href="properties.html" /> |
| <link rel="prev" title="Validation Algorithm" href="algorithm.html" /> |
| |
| <link rel="stylesheet" href="../_static/custom.css" type="text/css" /> |
| |
| |
| |
| |
| |
| </head><body> |
| <div class="document"> |
| |
| <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> |
| <div class="sphinxsidebarwrapper"> |
| <p class="logo"><a href="../index.html"> |
| <img class="logo" src="../_static/webassembly.png" alt="Logo"/> |
| </a></p><h3>Navigation</h3> |
| <ul class="current"> |
| <li class="toctree-l1"><a class="reference internal" href="../intro/index.html">Introduction</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../syntax/index.html">Structure</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../valid/index.html">Validation</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../exec/index.html">Execution</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../binary/index.html">Binary Format</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../text/index.html">Text Format</a></li> |
| <li class="toctree-l1 current"><a class="reference internal" href="index.html">Appendix</a><ul class="current"> |
| <li class="toctree-l2"><a class="reference internal" href="embedding.html">Embedding</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="implementation.html">Implementation Limitations</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="algorithm.html">Validation Algorithm</a></li> |
| <li class="toctree-l2 current"><a class="current reference internal" href="#">Custom Sections</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="properties.html">Soundness</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="changes.html">Change History</a></li> |
| </ul> |
| </li> |
| </ul> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="index-types.html">Index of Types</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="index-instructions.html">Index of Instructions</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="index-rules.html">Index of Semantic Rules</a></li> |
| </ul> |
| |
| |
| <hr /> |
| <ul> |
| |
| <li class="toctree-l1"><a href="../genindex.html">Index</a></li> |
| |
| <li class="toctree-l1"><a href="../_download/WebAssembly.pdf">Download as PDF</a></li> |
| |
| </ul> |
| |
| <div id="searchbox" style="display: none" role="search"> |
| <h3 id="searchlabel">Quick search</h3> |
| <div class="searchformwrapper"> |
| <form class="search" action="../search.html" method="get"> |
| <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/> |
| <input type="submit" value="Go" /> |
| </form> |
| </div> |
| </div> |
| <script>document.getElementById('searchbox').style.display = "block"</script> |
| </div> |
| </div> |
| <div class="documentwrapper"> |
| <div class="bodywrapper"> |
| |
| |
| <div class="body" role="main"> |
| |
| <section id="custom-sections"> |
| <span id="index-0"></span><h1>Custom Sections<a class="headerlink" href="#custom-sections" title="Permalink to this heading">¶</a></h1> |
| <p>This appendix defines dedicated <a class="reference internal" href="../binary/modules.html#binary-customsec"><span class="std std-ref">custom sections</span></a> for WebAssembly’s <a class="reference internal" href="../binary/index.html#binary"><span class="std std-ref">binary format</span></a>. |
| Such sections do not contribute to, or otherwise affect, the WebAssembly semantics, and like any custom section they may be ignored by an implementation. |
| However, they provide useful meta data that implementations can make use of to improve user experience or take compilation hints.</p> |
| <p>Currently, only one dedicated custom section is defined, the <a class="reference internal" href="#binary-namesec"><span class="std std-ref">name section</span></a>.</p> |
| <section id="name-section"> |
| <span id="binary-namesec"></span><span id="index-1"></span><h2>Name Section<a class="headerlink" href="#name-section" title="Permalink to this heading">¶</a></h2> |
| <p>The <em>name section</em> is a <a class="reference internal" href="../binary/modules.html#binary-customsec"><span class="std std-ref">custom section</span></a> whose name string is itself <span class="math notranslate nohighlight">\(\def\mathdef118#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef118{name}\)</span>. |
| The name section should appear only once in a module, and only after the <a class="reference internal" href="../binary/modules.html#binary-datasec"><span class="std std-ref">data section</span></a>.</p> |
| <p>The purpose of this section is to attach printable names to definitions in a module, which e.g. can be used by a debugger or when parts of the module are to be rendered in <a class="reference internal" href="../text/index.html#text"><span class="std std-ref">text form</span></a>.</p> |
| <div class="admonition note"> |
| <p class="admonition-title">Note</p> |
| <p>All <a class="reference internal" href="../binary/values.html#binary-name"><span class="std std-ref">names</span></a> are represented in <a class="reference external" href="https://www.unicode.org/versions/latest/">Unicode</a> encoded in UTF-8. |
| Names need not be unique.</p> |
| </div> |
| <section id="subsections"> |
| <span id="binary-namesubsection"></span><h3>Subsections<a class="headerlink" href="#subsections" title="Permalink to this heading">¶</a></h3> |
| <p>The <a class="reference internal" href="../binary/modules.html#binary-customsec"><span class="std std-ref">data</span></a> of a name section consists of a sequence of <em>subsections</em>. |
| Each subsection consists of a</p> |
| <ul class="simple"> |
| <li><p>a one-byte subsection <em>id</em>,</p></li> |
| <li><p>the <span class="math notranslate nohighlight">\(\href{../syntax/values.html#syntax-int}{\mathit{u32}}\)</span> <em>size</em> of the contents, in bytes,</p></li> |
| <li><p>the actual <em>contents</em>, whose structure is dependent on the subsection id.</p></li> |
| </ul> |
| <div class="math notranslate nohighlight"> |
| \[\begin{split}\begin{array}{llcll} |
| \def\mathdef79#1{{}}\mathdef79{name section} & \href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesec}} &::=& |
| \href{../binary/modules.html#binary-section}{\mathtt{section}}_0(\href{../appendix/custom.html#binary-namesubsection}{\mathtt{namedata}}) \\ |
| \def\mathdef79#1{{}}\mathdef79{name data} & \href{../appendix/custom.html#binary-namesubsection}{\mathtt{namedata}} &::=& |
| n{:}\href{../binary/values.html#binary-name}{\mathtt{name}} & (\mathrel{\mbox{if}} n = \def\mathdef119#1{\mbox{‘}\mathtt{#1}\mbox{’}}\mathdef119{name}) \\ &&& |
| \href{../appendix/custom.html#binary-modulenamesec}{\mathtt{modulenamesubsec}}^? \\ &&& |
| \href{../appendix/custom.html#binary-funcnamesec}{\mathtt{funcnamesubsec}}^? \\ &&& |
| \href{../appendix/custom.html#binary-localnamesec}{\mathtt{localnamesubsec}}^? \\ |
| \def\mathdef79#1{{}}\mathdef79{name subsection} & \href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesubsection}}_N(\mathtt{B}) &::=& |
| N{:}\href{../binary/values.html#binary-byte}{\mathtt{byte}}~~\mathit{size}{:}\href{../binary/values.html#binary-int}{\def\mathdef84#1{{\mathtt{u}#1}}\mathdef84{\mathtt{32}}}~~\mathtt{B} |
| & (\mathrel{\mbox{if}} \mathit{size} = ||\mathtt{B}||) \\ |
| \end{array}\end{split}\]</div> |
| <p>The following subsection ids are used:</p> |
| <table class="docutils align-default"> |
| <thead> |
| <tr class="row-odd"><th class="head"><p>Id</p></th> |
| <th class="head"><p>Subsection</p></th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr class="row-even"><td><p>0</p></td> |
| <td><p><a class="reference internal" href="#binary-modulenamesec"><span class="std std-ref">module name</span></a></p></td> |
| </tr> |
| <tr class="row-odd"><td><p>1</p></td> |
| <td><p><a class="reference internal" href="#binary-funcnamesec"><span class="std std-ref">function names</span></a></p></td> |
| </tr> |
| <tr class="row-even"><td><p>2</p></td> |
| <td><p><a class="reference internal" href="#binary-localnamesec"><span class="std std-ref">local names</span></a></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <p>Each subsection may occur at most once, and in order of increasing id.</p> |
| </section> |
| <section id="name-maps"> |
| <span id="binary-namemap"></span><span id="binary-indirectnamemap"></span><span id="index-2"></span><h3>Name Maps<a class="headerlink" href="#name-maps" title="Permalink to this heading">¶</a></h3> |
| <p>A <em>name map</em> assigns <a class="reference internal" href="../syntax/values.html#syntax-name"><span class="std std-ref">names</span></a> to <a class="reference internal" href="../syntax/modules.html#syntax-index"><span class="std std-ref">indices</span></a> in a given <a class="reference internal" href="../syntax/modules.html#syntax-index"><span class="std std-ref">index space</span></a>. |
| It consists of a <a class="reference internal" href="../binary/conventions.html#binary-vec"><span class="std std-ref">vector</span></a> of index/name pairs in order of increasing index value. |
| Each index must be unique, but the assigned names need not be.</p> |
| <div class="math notranslate nohighlight"> |
| \[\begin{split}\begin{array}{llclll} |
| \def\mathdef79#1{{}}\mathdef79{name map} & \href{../appendix/custom.html#binary-namemap}{\mathtt{namemap}} &::=& |
| \href{../binary/conventions.html#binary-vec}{\mathtt{vec}}(\href{../appendix/custom.html#binary-namemap}{\mathtt{nameassoc}}) \\ |
| \def\mathdef79#1{{}}\mathdef79{name association} & \href{../appendix/custom.html#binary-namemap}{\mathtt{nameassoc}} &::=& |
| \href{../binary/modules.html#binary-index}{\mathtt{idx}}~\href{../binary/values.html#binary-name}{\mathtt{name}} \\ |
| \end{array}\end{split}\]</div> |
| <p>An <em>indirect name map</em> assigns <a class="reference internal" href="../syntax/values.html#syntax-name"><span class="std std-ref">names</span></a> to a two-dimensional <a class="reference internal" href="../syntax/modules.html#syntax-index"><span class="std std-ref">index space</span></a>, where secondary indices are <em>grouped</em> by primary indices. |
| It consists of a vector of primary index/name map pairs in order of increasing index value, where each name map in turn maps secondary indices to names. |
| Each primary index must be unique, and likewise each secondary index per individual name map.</p> |
| <div class="math notranslate nohighlight"> |
| \[\begin{split}\begin{array}{llclll} |
| \def\mathdef79#1{{}}\mathdef79{indirect name map} & \href{../appendix/custom.html#binary-indirectnamemap}{\mathtt{indirectnamemap}} &::=& |
| \href{../binary/conventions.html#binary-vec}{\mathtt{vec}}(\href{../appendix/custom.html#binary-indirectnamemap}{\mathtt{indirectnameassoc}}) \\ |
| \def\mathdef79#1{{}}\mathdef79{indirect name association} & \href{../appendix/custom.html#binary-indirectnamemap}{\mathtt{indirectnameassoc}} &::=& |
| \href{../binary/modules.html#binary-index}{\mathtt{idx}}~\href{../appendix/custom.html#binary-namemap}{\mathtt{namemap}} \\ |
| \end{array}\end{split}\]</div> |
| </section> |
| <section id="module-names"> |
| <span id="binary-modulenamesec"></span><span id="index-3"></span><h3>Module Names<a class="headerlink" href="#module-names" title="Permalink to this heading">¶</a></h3> |
| <p>The <em>module name subsection</em> has the id 0. |
| It simply consists of a single <a class="reference internal" href="../binary/values.html#binary-name"><span class="std std-ref">name</span></a> that is assigned to the module itself.</p> |
| <div class="math notranslate nohighlight"> |
| \[\begin{split}\begin{array}{llclll} |
| \def\mathdef79#1{{}}\mathdef79{module name subsection} & \href{../appendix/custom.html#binary-modulenamesec}{\mathtt{modulenamesubsec}} &::=& |
| \href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesubsection}}_0(\href{../binary/values.html#binary-name}{\mathtt{name}}) \\ |
| \end{array}\end{split}\]</div> |
| </section> |
| <section id="function-names"> |
| <span id="binary-funcnamesec"></span><span id="index-4"></span><h3>Function Names<a class="headerlink" href="#function-names" title="Permalink to this heading">¶</a></h3> |
| <p>The <em>function name subsection</em> has the id 1. |
| It consists of a <a class="reference internal" href="#binary-namemap"><span class="std std-ref">name map</span></a> assigning function names to <a class="reference internal" href="../syntax/modules.html#syntax-funcidx"><span class="std std-ref">function indices</span></a>.</p> |
| <div class="math notranslate nohighlight"> |
| \[\begin{split}\begin{array}{llclll} |
| \def\mathdef79#1{{}}\mathdef79{function name subsection} & \href{../appendix/custom.html#binary-funcnamesec}{\mathtt{funcnamesubsec}} &::=& |
| \href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesubsection}}_1(\href{../appendix/custom.html#binary-namemap}{\mathtt{namemap}}) \\ |
| \end{array}\end{split}\]</div> |
| </section> |
| <section id="local-names"> |
| <span id="binary-localnamesec"></span><span id="index-5"></span><h3>Local Names<a class="headerlink" href="#local-names" title="Permalink to this heading">¶</a></h3> |
| <p>The <em>local name subsection</em> has the id 2. |
| It consists of an <a class="reference internal" href="#binary-indirectnamemap"><span class="std std-ref">indirect name map</span></a> assigning local names to <a class="reference internal" href="../syntax/modules.html#syntax-localidx"><span class="std std-ref">local indices</span></a> grouped by <a class="reference internal" href="../syntax/modules.html#syntax-funcidx"><span class="std std-ref">function indices</span></a>.</p> |
| <div class="math notranslate nohighlight"> |
| \[\begin{split}\begin{array}{llclll} |
| \def\mathdef79#1{{}}\mathdef79{local name subsection} & \href{../appendix/custom.html#binary-localnamesec}{\mathtt{localnamesubsec}} &::=& |
| \href{../appendix/custom.html#binary-namesubsection}{\mathtt{namesubsection}}_2(\href{../appendix/custom.html#binary-indirectnamemap}{\mathtt{indirectnamemap}}) \\ |
| \end{array}\end{split}\]</div> |
| </section> |
| </section> |
| </section> |
| |
| |
| </div> |
| |
| </div> |
| </div> |
| <div class="clearer"></div> |
| </div> |
| <div class="footer"> |
| ©2022, WebAssembly Community Group. |
| |
| </div> |
| |
| |
| |
| |
| </body> |
| </html> |
