Home | History | Annotate | Line # | Download | only in doc 
      1 @c Copyright (C) 2017-2026 Free Software Foundation, Inc.
      2 @c This is part of the GAS manual.
      3 @c For copying conditions, see the file as.texinfo.
      4 @c man end
      5 
      6 @ifset GENERIC
      7 @page
      8 @node WebAssembly-Dependent
      9 @chapter WebAssembly Dependent Features
     10 @end ifset
     11 
     12 @ifclear GENERIC
     13 @node Machine Dependencies
     14 @chapter WebAssembly Dependent Features
     15 @end ifclear
     16 
     17 @cindex WebAssembly support
     18 @menu
     19 * WebAssembly-Notes::                Notes
     20 * WebAssembly-Syntax::               Syntax
     21 * WebAssembly-Floating-Point::       Floating Point
     22 * WebAssembly-Opcodes::              Opcodes
     23 * WebAssembly-module-layout::        Module Layout
     24 @end menu
     25 
     26 @node WebAssembly-Notes
     27 @section Notes
     28 @cindex WebAssembly notes
     29 @cindex notes for WebAssembly
     30 
     31 While WebAssembly provides its own module format for executables, this
     32 documentation describes how to use @code{@value{AS}} to produce
     33 intermediate ELF object format files.
     34 
     35 @node WebAssembly-Syntax
     36 @section Syntax
     37 @cindex WebAssembly Syntax
     38 The assembler syntax directly encodes sequences of opcodes as defined
     39 in the WebAssembly binary encoding specification at
     40 https://github.com/webassembly/spec/BinaryEncoding.md.  Structured
     41 sexp-style expressions are not supported as input.
     42 
     43 @menu
     44 * WebAssembly-Chars::                Special Characters
     45 * WebAssembly-Relocs::               Relocations
     46 * WebAssembly-Signatures::           Signatures
     47 @end menu
     48 
     49 @node WebAssembly-Chars
     50 @subsection Special Characters
     51 
     52 @cindex line comment character, WebAssembly
     53 @cindex WebAssembly line comment character
     54 @samp{#} and @samp{;} are the line comment characters.  Note that if
     55 @samp{#} is the first character on a line then it can also be a
     56 logical line number directive (@pxref{Comments}) or a preprocessor
     57 control command (@pxref{Preprocessing}).
     58 
     59 @node WebAssembly-Relocs
     60 @subsection Relocations
     61 @cindex WebAssembly relocations
     62 @cindex relocations, WebAssembly
     63 
     64 Special relocations are available by using the @samp{@@@var{plt}},
     65 @samp{@@@var{got}}, or @samp{@@@var{got}} suffixes after a constant
     66 expression, which correspond to the R_ASMJS_LEB128_PLT,
     67 R_ASMJS_LEB128_GOT, and R_ASMJS_LEB128_GOT_CODE relocations,
     68 respectively.
     69 
     70 The @samp{@@@var{plt}} suffix is followed by a symbol name in braces;
     71 the symbol value is used to determine the function signature for which
     72 a PLT stub is generated. Currently, the symbol @emph{name} is parsed
     73 from its last @samp{F} character to determine the argument count of
     74 the function, which is also necessary for generating a PLT stub.
     75 
     76 @node WebAssembly-Signatures
     77 @subsection Signatures
     78 @cindex WebAssembly signatures
     79 @cindex signatures, WebAssembly
     80 
     81 Function signatures are specified with the @code{signature}
     82 pseudo-opcode, followed by a simple function signature imitating a
     83 C++-mangled function type: @code{F} followed by an optional @code{v},
     84 then a sequence of @code{i}, @code{l}, @code{f}, and @code{d}
     85 characters to mark i32, i64, f32, and f64 parameters, respectively;
     86 followed by a final @code{E} to mark the end of the function
     87 signature.
     88 
     89 @node WebAssembly-Floating-Point
     90 @section Floating Point
     91 @cindex floating point, WebAssembly (@sc{ieee})
     92 @cindex WebAssembly floating point (@sc{ieee})
     93 WebAssembly uses little-endian @sc{ieee} floating-point numbers.
     94 
     95 @node WebAssembly-Opcodes
     96 @section Regular Opcodes
     97 @cindex opcodes, WebAssembly
     98 @cindex WebAssembly opcodes
     99 Ordinary instructions are encoded with the WebAssembly mnemonics as
    100 listed at:
    101 @url{https://github.com/WebAssembly/design/blob/master/BinaryEncoding.md}.
    102 
    103 Opcodes are written directly in the order in which they are encoded,
    104 without going through an intermediate sexp-style expression as in the
    105 @code{was} format.
    106 
    107 For ``typed'' opcodes (block, if, etc.), the type of the block is
    108 specified in square brackets following the opcode: @code{if[i]},
    109 @code{if[]}.
    110 
    111 @node WebAssembly-module-layout
    112 @section WebAssembly Module Layout
    113 @cindex module layout, WebAssembly
    114 @cindex WebAssembly module layout
    115 @code{@value{AS}} will only produce ELF output, not a valid
    116 WebAssembly module. It is possible to make @code{@value{AS}} produce
    117 output in a single ELF section which becomes a valid WebAssembly
    118 module, but a linker script to do so may be preferable, as it doesn't
    119 require running the entire module through the assembler at once.
    120