llvm/docs/CommandGuide/llvm-mc.rst

   1 llvm-mc - LLVM Machine Code Playground
   2 ======================================
   3
   4 .. program:: llvm-mc
   5
   6 SYNOPSIS
   7 --------
   8
   9 :program:`llvm-mc` [*options*] [*filename*]
  10
  11 DESCRIPTION
  12 -----------
  13
  14 The :program:`llvm-mc` command takes assembly code for a specified architecture
  15 as input and generates an object file or executable.
  16
  17 :program:`llvm-mc` provides a set of tools for working with machine code,
  18 such as encoding instructions and displaying internal representations,
  19 disassembling strings to bytes, etc.
  20
  21 The choice of architecture for the output assembly code is automatically
  22 determined from the input file, unless the :option:`--arch` option is used to
  23 override the default.
  24
  25 OPTIONS
  26 -------
  27
  28 If the :option:`-o` option is omitted, then :program:`llvm-mc` will send its
  29 output to standard output if the input is from standard input.  If the
  30 :option:`-o` option specifies "``-``", then the output will also be sent to
  31 standard output.
  32
  33 If no :option:`-o` option is specified and an input file other than "``-``" is
  34 specified, then :program:`llvm-mc` creates the output filename by taking the
  35 input filename, removing any existing ``.s`` extension, and adding a ``.o``
  36 suffix.
  37
  38 Other :program:`llvm-mc` options are described below.
  39
  40 End-user Options
  41 ~~~~~~~~~~~~~~~~
  42
  43 .. option:: --help
  44
  45  Display available options (--help-hidden for more).
  46
  47 .. option:: -o <filename>
  48
  49  Use ``<filename>`` as the output filename. See the summary above for more
  50  details.
  51
  52 .. option:: --arch=<string>
  53
  54  Target arch to assemble for, see -version for available targets.
  55
  56 .. option:: --as-lex
  57
  58  Apply the assemblers "lexer" to break the input into tokens and print each of
  59  them out. This is intended to help develop and test an assembler
  60  implementation.
  61
  62 .. option:: --assemble
  63
  64  Assemble assembly file (default), and print the result to assembly. This is
  65  useful to design and test instruction parsers, and can be a useful tool when
  66  combined with other llvm-mc flags. For example, this option may be useful to
  67  transcode assembly from different dialects, e.g. on Intel where you can use
  68  -output-asm-variant=1 to translate from AT&T to Intel assembly syntax. It can
  69  also be combined with --show-encoding to understand how instructions are
  70  encoded.
  71
  72 .. option:: --disassemble
  73
  74  Parse a series of hex bytes, and print the result out as assembly syntax.
  75
  76 .. option:: --mdis
  77
  78  Marked up disassembly of string of hex bytes.
  79
  80 .. option:: --cdis
  81
  82  Colored disassembly of string of hex bytes.
  83
  84 .. option:: --filetype=[asm,null,obj]
  85
  86  Sets the output filetype. Setting this flag to `asm` will make the tool output
  87  text assembly. Setting this flag to `obj` will make the tool output an object
  88  file. Setting it to `null` causes no output to be created and can be used for
  89  timing purposes. The default value is `asm`.
  90
  91 .. option:: -g
  92
  93  Generate DWARF debugging info for assembly source files.
  94
  95 .. option:: --large-code-model
  96
  97  Create CFI directives that assume the code might be more than 2 GB.
  98
  99 .. option:: --main-file-name=<string>
 100
 101  Specify the name we should consider the input file.
 102
 103
 104 .. option:: --masm-hexfloats
 105
 106  Enable MASM-style hex float initializers (3F800000r).
 107
 108
 109 .. option:: -mattr=a1,+a2,-a3,...
 110  Target specific attributes (-mattr=help for details).
 111
 112 .. option:: --mcpu=<cpu-name>
 113
 114  Target a specific cpu type (-mcpu=help for details).
 115
 116 .. option::   --triple=<string>
 117
 118  Target triple to assemble for, see -version for available targets.
 119
 120 .. option::  --split-dwarf-file=<filename>
 121
 122  DWO output filename.
 123
 124 .. option:: --show-inst-operands
 125
 126  Show instructions operands as parsed.
 127
 128 .. option:: --show-inst
 129
 130  Show internal instruction representation.
 131
 132 .. option::  --show-encoding
 133
 134  Show instruction encodings.
 135
 136 .. option:: --save-temp-labels
 137
 138  Don't discard temporary labels.
 139
 140 .. option::   --relax-relocations
 141
 142  Emit R_X86_64_GOTPCRELX instead of R_X86_64_GOTPCREL.
 143
 144 .. option:: --print-imm-hex
 145
 146  Prefer hex format for immediate values.
 147
 148 .. option::  --preserve-comments
 149
 150  Preserve Comments in outputted assembly.
 151
 152 .. option:: --output-asm-variant=<uint>
 153
 154  Syntax variant to use for output printing. For example, on x86 targets
 155  --output-asm-variant=0 prints in AT&T syntax, and --output-asm-variant=1
 156  prints in Intel/MASM syntax.
 157
 158 .. option:: --compress-debug-sections=[none|zlib|zstd]
 159
 160  Choose DWARF debug sections compression.
 161
 162
 163 EXIT STATUS
 164 -----------
 165
 166 If :program:`llvm-mc` succeeds, it will exit with 0.  Otherwise, if an error
 167 occurs, it will exit with a non-zero value.
 168