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