gas/doc/c-wasm32.texi

   1 @c Copyright (C) 2017-2022 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.