45 Commits

Author SHA1 Message Date
Stephen Tozer
400d4fd7b6
[RemoveDIs] Update all docs to use debug records (#91768)
As we approach the state where support for debug intrinsics is dropping and
we print and use debug records by default, the documentation should be updated
to refer to debug records as the primary debug info representation, with
debug intrinsics being relegated to an optional alternative.

This patch performs a few updates:
- Replace references to intrinsics with references to records across all
the documentation.
- Replace intrinsics with records in code examples.
- Move debug records prior to debug intrinsics in the
SourceLevelDebugging document, and change text to refer to them as the
primary representation.
- Add release notes describing the change.
2024-06-11 14:16:32 +01:00
Florian Mayer
80f8ae3f84
[NFC] add explanation to register flags doc (#91803) 2024-05-14 11:34:27 -07:00
XChy
08011cf845
[Docs][NFC] Use opaque ptr in the example (#91502) 2024-05-09 01:15:49 +08:00
Ramkumar Ramachandra
dabf8490a9
MIRLangRef: fix llc invocation lines to write output (#74104)
The first couple of llc invocations mentioned in the document are wrong,
and users will get confused about no output being written. Fix them.
2023-12-08 09:54:33 +00:00
Stephen Tozer
c383f4d655 [DebugInfo] Allow non-stack_value variadic expressions and use in DBG_INSTR_REF
Prior to this patch, variadic DIExpressions (i.e. ones that contain
DW_OP_LLVM_arg) could only be created by salvaging debug values to create
stack value expressions, resulting in a DBG_VALUE_LIST being created. As of
the previous patch in this patch stack, DBG_INSTR_REF's syntax has been
changed to match DBG_VALUE_LIST in preparation for supporting variadic
expressions. This patch adds some minor changes needed to allow variadic
expressions that aren't stack values to exist, and allows variadic expressions
that are trivially reduceable to non-variadic expressions to be handled
similarly to non-variadic expressions.

Reviewed by: jmorse

Differential Revision: https://reviews.llvm.org/D133926
2023-01-06 19:31:10 +00:00
Stephen Tozer
85bff00c73 Fix: Title underline too short in D129372
This patch fixes an error in commit e10e9363 in which the
added documentation contained an incorrectly-styled underline
for the title "Debug Instruction Reference Operands".
2023-01-06 18:22:02 +00:00
Stephen Tozer
e10e936315 [DebugInfo][NFC] Add new MachineOperand type and change DBG_INSTR_REF syntax
This patch makes two notable changes to the MIR debug info representation,
which result in different MIR output but identical final DWARF output (NFC
w.r.t. the full compilation). The two changes are:

  * The introduction of a new MachineOperand type, MO_DbgInstrRef, which
    consists of two unsigned numbers that are used to index an instruction
    and an output operand within that instruction, having a meaning
    identical to first two operands of the current DBG_INSTR_REF
    instruction. This operand is only used in DBG_INSTR_REF (see below).
  * A change in syntax for the DBG_INSTR_REF instruction, shuffling the
    operands to make it resemble DBG_VALUE_LIST instead of DBG_VALUE,
    and replacing the first two operands with a single MO_DbgInstrRef-type
    operand.

This patch is the first of a set that will allow DBG_INSTR_REF
instructions to refer to multiple machine locations in the same manner
as DBG_VALUE_LIST.

Reviewed By: jmorse

Differential Revision: https://reviews.llvm.org/D129372
2023-01-06 18:03:48 +00:00
J. Ryan Stinnett
7a1d5ef703 [DebugInfo][NFC] Add instr-ref documentation, migration guide
This used to be D102158, but all the code it describes got re-written, so I
figured I'd take another shot at documenting the new instruction referencing
variable locations, this time from a higher level. Happily there's no longer any
need to describe LiveDebugValues in any detail seeing how it's all SSA-based
now.

Probably the most important part is the explanation of what targets need to do
to support instruction referencing. The list is small, mostly because there's
nothing especially complicated that targets need to do: just instrument their
target-specific optimisations and implement the stack spill/restore recognition
target hooks.

This is a small amount of text (which is a virtue), I'm extremely happy to
expand on anything.

Differential Revision: https://reviews.llvm.org/D113586

Co-authored-by: Jeremy Morse <jeremy.morse@sony.com>
2022-05-20 14:13:46 +01:00
Jay Foad
548b01c7a6 [MIRParser] Add support for IsInlineAsmBrIndirectTarget
Print this basic block flag as inlineasm-br-indirect-target and parse
it. This allows you to write MIR test cases for INLINEASM_BR. The test
case I added is one that I wanted to precommit anyway for D110834.

Differential Revision: https://reviews.llvm.org/D111291
2021-10-07 19:08:01 +01:00
Kazu Hirata
e8fa9014cc [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
Sjoerd Meijer
cc4dcd48b8 [MIRLangRef] Document MachineOperand comments
Late follow-up of D74306 to document MachineOperand comments in
MIRLangRef.

Differential Revision: https://reviews.llvm.org/D96518
2021-02-12 10:15:47 +00:00
Jeremy Morse
cda32aba4f [DebugInfo][Docs] Document MIR language debug-info constructs
This patch documents the MIR syntax for a number of things relevant to
debugging information:
 * Trailing 'debug-location' metadata that becomes a DebugLoc,
 * Variable location metadata for stack slots,
 * Syntax for DBG_VALUE metainstructions,
 * Syntax for DBG_INSTR_REF, including trailing instruction numbers
   attached to MIR instructions.

Differential Revision: https://reviews.llvm.org/D89337
2020-12-08 11:01:55 +00:00
Daniel Sanders
ad0dfb0a25 [globalisel][docs] Rework GMIR documentation and add an early GenericOpcode reference
Summary:
Rework the GMIR documentation to focus more on the end user than the
implementation and tie it in to the MIR document. There was also some
out-of-date information which has been removed.

The quality of the GenericOpcode reference is highly variable and drops
sharply as I worked through them all but we've got to start somewhere :-).
It would be great if others could expand on this too as there is an awful
lot to get through.

Also fix a typo in the definition of G_FLOG. Previously, the comments said
we had two base-2's (G_FLOG and G_FLOG2).

Reviewers: aemerson, volkan, rovka, arsenm

Reviewed By: rovka

Subscribers: wdng, arphaman, jfb, Petar.Avramovic, llvm-commits

Tags: #llvm

Differential Revision: https://reviews.llvm.org/D69545
2019-11-05 15:16:43 -08:00
Guillaume Chatelet
aff45e4b23 [LLVM][Alignment] Make functions using log of alignment explicit
Summary:
This patch renames functions that takes or returns alignment as log2, this patch will help with the transition to llvm::Align.
The renaming makes it explicit that we deal with log(alignment) instead of a power of two alignment.
A few renames uncovered dubious assignments:

 - `MirParser`/`MirPrinter` was expecting powers of two but `MachineFunction` and `MachineBasicBlock` were using deal with log2(align). This patch fixes it and updates the documentation.
 - `MachineBlockPlacement` exposes two flags (`align-all-blocks` and `align-all-nofallthru-blocks`) supposedly interpreted as power of two alignments, internally these values are interpreted as log2(align). This patch updates the documentation,
 - `MachineFunctionexposes` exposes `align-all-functions` also interpreted as power of two alignment, internally this value is interpreted as log2(align). This patch updates the documentation,

Reviewers: lattner, thegameg, courbet

Subscribers: dschuff, arsenm, jyknight, dylanmckay, sdardis, nemanjai, jvesely, nhaehnle, javed.absar, hiraditya, kbarton, fedor.sergeev, asb, rbar, johnrusso, simoncook, apazos, sabuasal, niosHD, jrtc27, MaskRay, zzheng, edward-jones, atanasyan, rogfer01, MartinMosbeck, brucehoult, the_o, dexonsmith, PkmX, jocewei, jsji, Jim, s.egerton, llvm-commits, courbet

Tags: #llvm

Differential Revision: https://reviews.llvm.org/D65945

llvm-svn: 371045
2019-09-05 10:00:22 +00:00
Djordje Todorovic
a7cde103c1 [MachineFunction] Base support for call site info tracking
Add an attribute into the MachineFunction that tracks call site info.

([8/13] Introduce the debug entry values.)

Co-authored-by: Ananth Sowda <asowda@cisco.com>
Co-authored-by: Nikola Prica <nikola.prica@rt-rk.com>
Co-authored-by: Ivan Baev <ibaev@cisco.com>

Differential Revision: https://reviews.llvm.org/D61061

llvm-svn: 364506
2019-06-27 07:48:06 +00:00
Matt Arsenault
43153024ab MIR: Add method to stop after specific runs of passes
Currently if you use -{start,stop}-{before,after}, it picks
the first instance with the matching pass name. If you run
the same pass multiple times, there's no way to distinguish them.

Allow specifying a run index wih ,N to specify which you mean.

llvm-svn: 348285
2018-12-04 17:45:12 +00:00
Chandler Carruth
75ca6be1c1 [x86/MIR] Implement support for pre- and post-instruction symbols, as
well as MIR parsing support for `MCSymbol` `MachineOperand`s.

The only real way to test pre- and post-instruction symbol support is to
use them in operands, so I ended up implementing that within the patch
as well. I can split out the operand support if folks really want but it
doesn't really seem worth it.

The functional implementation of pre- and post-instruction symbols is
now *completely trivial*. Two tiny bits of code in the (misnamed)
AsmPrinter. It should be completely target independent as well. We emit
these exactly the same way as we emit basic block labels. Most of the
code here is to give full dumping, MIR printing, and MIR parsing support
so that we can write useful tests.

The MIR parsing of MC symbol operands still isn't 100%, as it forces the
symbols to be non-temporary and non-local symbols with names. However,
those names often can encode most (if not all) of the special semantics
desired, and unnamed symbols seem especially annoying to serialize and
de-serialize. While this isn't perfect or full support, it seems plenty
to write tests that exercise usage of these kinds of operands.

The MIR support for pre-and post-instruction symbols was quite
straightforward. I chose to print them out in an as-if-operand syntax
similar to debug locations as this seemed the cleanest way and let me
use nice introducer tokens rather than inventing more magic punctuation
like we use for memoperands.

However, supporting MIR-based parsing of these symbols caused me to
change the design of the symbol support to allow setting arbitrary
symbols. Without this, I don't see any reasonable way to test things
with MIR.

Differential Revision: https://reviews.llvm.org/D50833

llvm-svn: 339962
2018-08-16 23:11:05 +00:00
Hiroshi Inoue
c36a1f1cb7 [NFC] fix trivial typos in documents
llvm-svn: 334799
2018-06-15 05:10:09 +00:00
Puyan Lotfi
5bd46b0008 Updating MIR Language Reference to include new syntax for symbols and physregs.
External symbols now get the sigil '&' while physical registers get the sigil
'$' for their prefix.

llvm-svn: 327276
2018-03-12 14:51:19 +00:00
Francis Visoiu Mistrih
5836790955 [MIR] Update MIRLangRef with documentation on bundled instructions
Differential Revision: https://reviews.llvm.org/D41872

llvm-svn: 322198
2018-01-10 17:53:16 +00:00
Francis Visoiu Mistrih
dbf2c48fc7 [MIR] Add support for the frame-destroy MachineInstr flag
We are printing / parsing the `frame-setup` MachineInstr flag but not
the `frame-destroy` one.

Differential Revision: https://reviews.llvm.org/D41509

llvm-svn: 322071
2018-01-09 11:33:22 +00:00
Francis Visoiu Mistrih
cb2683d46a [CodeGen] Move printing MO_IntrinsicID operands to MachineOperand::print
Work towards the unification of MIR and debug output by refactoring the
interfaces.

llvm-svn: 321112
2017-12-19 21:47:10 +00:00
Francis Visoiu Mistrih
bbd610ae92 [CodeGen] Move printing MO_IntrinsicID operands to MachineOperand::print
Work towards the unification of MIR and debug output by refactoring the
interfaces.

Also add support for printing with a null TargetIntrinsicInfo and no
MachineFunction.

llvm-svn: 321111
2017-12-19 21:47:05 +00:00
Francis Visoiu Mistrih
874ae6faa5 [CodeGen] Move printing MO_CFIIndex operands to MachineOperand::print
Work towards the unification of MIR and debug output by refactoring the
interfaces.

Before this patch we printed "<call frame instruction>" in the debug
output.

llvm-svn: 321084
2017-12-19 16:51:52 +00:00
Francis Visoiu Mistrih
3c99371c6e [CodeGen] Print MCSymbol operands as <mcsymbol sym> in both MIR and debug output
Work towards the unification of MIR and debug output by printing
`<mcsymbol sym>` instead of `<MCSym=sym>`.

Only debug syntax is affected.

llvm-svn: 320685
2017-12-14 10:03:23 +00:00
Francis Visoiu Mistrih
e76c5fcd70 [CodeGen] Print external symbols as $symbol in both MIR and debug output
Work towards the unification of MIR and debug output by printing
`$symbol` instead of `<es:symbol>`.

Only debug syntax is affected.

llvm-svn: 320681
2017-12-14 10:02:58 +00:00
Francis Visoiu Mistrih
b41dbbe325 [CodeGen] Print jump-table index operands as %jump-table.0 in both MIR and debug output
Work towards the unification of MIR and debug output by printing `%jump-table.0` instead of `<jt#0>`.

Only debug syntax is affected.

llvm-svn: 320566
2017-12-13 10:30:59 +00:00
Francis Visoiu Mistrih
b3a0d51374 [CodeGen] Print target index operands as target-index(target-specific) + 8 in both MIR and debug output
Work towards the unification of MIR and debug output by printing `target-index(target-specific) + 8` instead of `<ti#0+8>` and `target-index(target-specific) + 8` instead of `<ti#0-8>`.

Only debug syntax is affected.

llvm-svn: 320565
2017-12-13 10:30:51 +00:00
Francis Visoiu Mistrih
26ae8a6582 [CodeGen] Print constant pool index operands as %const.0 + 8 in both MIR and debug output
Work towards the unification of MIR and debug output by printing
`%const.0 + 8` instead of `<cp#0+8>` and `%const.0 - 8` instead of
`<cp#0-8>`.

Only debug syntax is affected.

Differential Revision: https://reviews.llvm.org/D41116

llvm-svn: 320564
2017-12-13 10:30:45 +00:00
Geoff Berry
60c431022e [MachineOperand][MIR] Add isRenamable to MachineOperand.
Summary:
Add isRenamable() predicate to MachineOperand.  This predicate can be
used by machine passes after register allocation to determine whether it
is safe to rename a given register operand.  Register operands that
aren't marked as renamable may be required to be assigned their current
register to satisfy constraints that are not captured by the machine
IR (e.g. ABI or ISA constraints).

Reviewers: qcolombet, MatzeB, hfinkel

Subscribers: nemanjai, mcrosier, javed.absar, llvm-commits

Differential Revision: https://reviews.llvm.org/D39400

llvm-svn: 320503
2017-12-12 17:53:59 +00:00
Francis Visoiu Mistrih
440f69c95a [CodeGen] Move printing MO_Immediate operands to MachineOperand::print
Work towards the unification of MIR and debug output by refactoring the
interfaces.

Add support for operand subreg index as an immediate to debug printing
and use ::print in the MIRPrinter.

Differential Review: https://reviews.llvm.org/D40965

llvm-svn: 320209
2017-12-08 22:53:21 +00:00
Francis Visoiu Mistrih
6c4ca713f1 [CodeGen] Move printing MO_CImmediate operands to MachineOperand::print
Work towards the unification of MIR and debug output by refactoring the
interfaces.

llvm-svn: 320140
2017-12-08 11:40:06 +00:00
Francis Visoiu Mistrih
25528d6de7 [CodeGen] Unify MBB reference format in both MIR and debug output
As part of the unification of the debug format and the MIR format, print
MBB references as '%bb.5'.

The MIR printer prints the IR name of a MBB only for block definitions.

* find . \( -name "*.mir" -o -name "*.cpp" -o -name "*.h" -o -name "*.ll" \) -type f -print0 | xargs -0 sed -i '' -E 's/BB#" << ([a-zA-Z0-9_]+)->getNumber\(\)/" << printMBBReference(*\1)/g'
* find . \( -name "*.mir" -o -name "*.cpp" -o -name "*.h" -o -name "*.ll" \) -type f -print0 | xargs -0 sed -i '' -E 's/BB#" << ([a-zA-Z0-9_]+)\.getNumber\(\)/" << printMBBReference(\1)/g'
* find . \( -name "*.txt" -o -name "*.s" -o -name "*.mir" -o -name "*.cpp" -o -name "*.h" -o -name "*.ll" \) -type f -print0 | xargs -0 sed -i '' -E 's/BB#([0-9]+)/%bb.\1/g'
* grep -nr 'BB#' and fix

Differential Revision: https://reviews.llvm.org/D40422

llvm-svn: 319665
2017-12-04 17:18:51 +00:00
Matthias Braun
8940114f61 MIParser/MIRPrinter: Compute block successors if not explicitely specified
- MIParser: If the successor list is not specified successors will be
  added based on basic block operands in the block and possible
  fallthrough.

- MIRPrinter: Adds a new `simplify-mir` option, with that option set:
  Skip printing of block successor lists in cases where the
  parser is guaranteed to reconstruct it. This means we still print the
  list if some successor cannot be determined (happens for example for
  jump tables), if the successor order changes or branch probabilities
  being unequal.

Differential Revision: https://reviews.llvm.org/D31262

llvm-svn: 302289
2017-05-05 21:09:30 +00:00
Matthias Braun
836c383b30 MIRLangRef: Add a section on simplifying .mir tests
Differential Revision: http://reviews.llvm.org/D32058

llvm-svn: 300282
2017-04-13 23:45:14 +00:00
Matthias Braun
e6185b70e9 MIRLangRef: Simplify/update documentation
- Refer to options by `-option` instead of `option`
- Use `-mtriple=` instead of `-march` in the example (-march will still
  target the default operating system which is usually not what you want
  in a test)
- Rephrase sentence because output does not go to stdout by default (you
  need -o - for that as should be expected).

llvm-svn: 300268
2017-04-13 22:14:45 +00:00
Renato Golin
124f2593fc [docs] Fixing Sphinx warnings to unclog the buildbot
Lots of blocks had "llvm" or "nasm" syntax types but either weren't following
the syntax, or the syntax has changed (and sphinx hasn't keep up) or the type
doesn't even exist (nasm?).

Other documents had :options: what were invalid. I only removed those that had
warnings, and left the ones that didn't, in order to follow the principle of
least surprise.

This is like this for ages, but the buildbot is now failing on errors. It may
take a while to upgrade the buildbot's sphinx, if that's even possible, but
that shouldn't stop us from getting docs updates (which seem down for quite
a while).

Also, we're not losing any syntax highlight, since when it doesn't parse, it
doesn't colour. Ie. those blocks are not being highlighted anyway.

I'm trying to get all docs in one go, so that it's easy to revert later if we
do fix, or at least easy to know what's to fix.

llvm-svn: 276109
2016-07-20 12:16:38 +00:00
Alex Lorenz
37e026260b MIRLangRef: Add documentation for the subregister indices.
llvm-svn: 247005
2015-09-08 11:39:47 +00:00
Alex Lorenz
d4990ebd02 MIRLangRef: Add documentation for the global value machine operands.
llvm-svn: 247004
2015-09-08 11:38:16 +00:00
Alex Lorenz
ea788c4bf8 MIRLangRef: Add 'MIR Testing Guide' section.
llvm-svn: 245757
2015-08-21 22:58:33 +00:00
Alex Lorenz
b981d37272 MIRLangRef: Describe the syntax for the immediate operands, register values,
register operands and register flags.

llvm-svn: 245738
2015-08-21 21:17:01 +00:00
Alex Lorenz
8eadc3f38b MIRLangRef: Describe the syntax for machine instruction names and flags.
llvm-svn: 245710
2015-08-21 17:26:38 +00:00
Alex Lorenz
3a4a60cba5 MIRLangRef: Describe the syntax that is used to represent machine basic blocks.
llvm-svn: 245138
2015-08-15 01:06:06 +00:00
Alex Lorenz
9846167816 Update MIRLangRef for MIR syntax change from r244982.
llvm-svn: 244996
2015-08-14 00:36:10 +00:00
Alex Lorenz
3d311776fb Add initial documentation for the MIR serialization format.
Differential Revision: http://reviews.llvm.org/D11736

llvm-svn: 244292
2015-08-06 22:55:19 +00:00