1
0
mirror of https://github.com/RPCS3/llvm-mirror.git synced 2024-11-22 10:42:39 +01:00
llvm-mirror/docs
Hans Wennborg c2ea8c4219 Revert "[ObjC][ARC] Use operand bundle 'clang.arc.attachedcall' instead of explicitly emitting retainRV or claimRV calls in the IR"
This caused miscompiles of Chromium tests for iOS due clobbering of live
registers. See discussion on the code review for details.

> Background:
>
> This fixes a longstanding problem where llvm breaks ARC's autorelease
> optimization (see the link below) by separating calls from the marker
> instructions or retainRV/claimRV calls. The backend changes are in
> https://reviews.llvm.org/D92569.
>
> https://clang.llvm.org/docs/AutomaticReferenceCounting.html#arc-runtime-objc-autoreleasereturnvalue
>
> What this patch does to fix the problem:
>
> - The front-end adds operand bundle "clang.arc.attachedcall" to calls,
>   which indicates the call is implicitly followed by a marker
>   instruction and an implicit retainRV/claimRV call that consumes the
>   call result. In addition, it emits a call to
>   @llvm.objc.clang.arc.noop.use, which consumes the call result, to
>   prevent the middle-end passes from changing the return type of the
>   called function. This is currently done only when the target is arm64
>   and the optimization level is higher than -O0.
>
> - ARC optimizer temporarily emits retainRV/claimRV calls after the calls
>   with the operand bundle in the IR and removes the inserted calls after
>   processing the function.
>
> - ARC contract pass emits retainRV/claimRV calls after the call with the
>   operand bundle. It doesn't remove the operand bundle on the call since
>   the backend needs it to emit the marker instruction. The retainRV and
>   claimRV calls are emitted late in the pipeline to prevent optimization
>   passes from transforming the IR in a way that makes it harder for the
>   ARC middle-end passes to figure out the def-use relationship between
>   the call and the retainRV/claimRV calls (which is the cause of
>   PR31925).
>
> - The function inliner removes an autoreleaseRV call in the callee if
>   nothing in the callee prevents it from being paired up with the
>   retainRV/claimRV call in the caller. It then inserts a release call if
>   claimRV is attached to the call since autoreleaseRV+claimRV is
>   equivalent to a release. If it cannot find an autoreleaseRV call, it
>   tries to transfer the operand bundle to a function call in the callee.
>   This is important since the ARC optimizer can remove the autoreleaseRV
>   returning the callee result, which makes it impossible to pair it up
>   with the retainRV/claimRV call in the caller. If that fails, it simply
>   emits a retain call in the IR if retainRV is attached to the call and
>   does nothing if claimRV is attached to it.
>
> - SCCP refrains from replacing the return value of a call with a
>   constant value if the call has the operand bundle. This ensures the
>   call always has at least one user (the call to
>   @llvm.objc.clang.arc.noop.use).
>
> - This patch also fixes a bug in replaceUsesOfNonProtoConstant where
>   multiple operand bundles of the same kind were being added to a call.
>
> Future work:
>
> - Use the operand bundle on x86-64.
>
> - Fix the auto upgrader to convert call+retainRV/claimRV pairs into
>   calls with the operand bundles.
>
> rdar://71443534
>
> Differential Revision: https://reviews.llvm.org/D92808

This reverts commit ed4718eccb12bd42214ca4fb17d196d49561c0c7.
2021-03-03 15:51:40 +01:00
..
_ocamldoc
_static
_templates [www] More HTTPS and outdated link fixes. 2019-11-08 14:41:27 -08:00
_themes/llvm-theme [Docs] Updates sidebar links and sets max-width property for div.body 2019-10-15 21:27:20 +00:00
AMDGPU [AMDGPU][MC][NFC][DOC] Updated AMD GPU assembler syntax description. 2020-08-21 14:25:14 +03:00
CommandGuide [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
DependenceGraphs [llvm] NFC: fix trivial typos in documents 2020-01-22 11:32:51 +08:00
Frontend [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
GlobalISel [docs] Fix the GlobalISel/GenericOpcode.rst 2021-02-19 10:31:31 +01:00
HistoricalNotes Doc: Links should use https 2020-03-22 22:49:33 +01:00
PDB Fix a few spellos in docs. 2019-09-13 14:58:24 +00:00
Proposals [VPlan] Add VPDef class. 2020-11-17 16:18:11 +00:00
TableGen [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
tutorial [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
AddingConstrainedIntrinsics.rst [FEnv] Fix AddingConstrainedIntrinsics.rst after llvmorg-10-init-10282-g0c50c0b0552 2019-11-19 23:09:13 -08:00
AdvancedBuilds.rst Update documentation and implementation of stage3 build 2020-10-08 07:55:37 +02:00
AliasAnalysis.rst [docs] Fix typos 2020-08-09 19:31:49 -07:00
AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
AMDGPUInstructionNotation.rst [AMDGPU][MC][NFC][DOC] Updated AMD GPU assembler syntax description. 2020-08-21 14:25:14 +03:00
AMDGPUInstructionSyntax.rst [AMDGPU][MC][NFC][DOC] Updated AMD GPU assembler syntax description. 2020-08-21 14:25:14 +03:00
AMDGPUModifierSyntax.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
AMDGPUOperandSyntax.rst [AMDGPU][MC][NFC][DOC] Updated AMD GPU assembler syntax description. 2020-08-21 14:25:14 +03:00
AMDGPUUsage.rst [NFC][AMDGPU] Document the AMDGPU target feature defaults 2021-02-27 18:28:15 +00:00
ARM-BE-bitcastfail.png
ARM-BE-bitcastsuccess.png
ARM-BE-ld1.png
ARM-BE-ldr.png
Atomics.rst [AArch64] Out-of-line atomics (-moutline-atomics) implementation. 2020-11-20 13:30:12 +00:00
Benchmarking.rst
BigEndianNEON.rst [llvm] NFC: fix trivial typos in documents 2020-01-22 11:32:51 +08:00
BitCodeFormat.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
BlockFrequencyTerminology.rst [llvm] NFC: fix trivial typos in documents 2020-01-22 11:32:51 +08:00
BranchWeightMetadata.rst Add support of __builtin_expect_with_probability 2020-06-22 10:21:28 -07:00
BugLifeCycle.rst [docs] Fix typos 2020-08-09 19:31:49 -07:00
Bugpoint.rst [llvm] NFC: fix trivial typos in documents 2020-01-22 11:32:51 +08:00
BugpointRedesign.md [Bugpoint redesign] Fix nonlocal URI link in doc 2019-08-09 21:48:47 +00:00
BuildingADistribution.rst Remove AllTargetsAsmPrinters 2020-01-17 19:04:06 -05:00
CFIVerify.rst
CMake.rst [cmake] Add LLVM_UBSAN_FLAGS, to allow overriding UBSan flags 2020-10-26 15:48:19 -07:00
CMakeLists.txt [dsymutil][doc] Improve wording in manpage and rename file. 2017-11-02 18:44:54 +00:00
CMakePrimer.rst [CMake] Bump CMake minimum version to 3.13.4 2020-07-22 14:25:07 -04:00
CodeGenerator.rst [Doc] Fix example in codegen doc. 2021-01-18 08:24:10 -05:00
CodeOfConduct.rst
CodeReview.rst Make the post-commit review expectations more explicit with respect to revert 2020-10-28 23:29:29 +00:00
CodingStandards.rst Update references to 'master' branch. 2020-12-21 19:10:34 +00:00
CommandLine.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
CompileCudaWithLLVM.rst doc: use the right url to bugzilla 2020-03-22 22:49:40 +01:00
CompilerWriterInfo.rst [XCore][docs] Fix XCore compiler writer documentation links. 2020-12-08 12:21:09 +00:00
conf.py Bump forgotten version nbr in llvm/docs/conf.py 2020-08-05 17:11:59 +02:00
Contributing.rst [docs] Fix overly specific link to uploading patches on Phabricator 2021-01-20 11:14:18 -05:00
Coroutines.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
CoverageMappingFormat.rst [Coverage] Store compilation dir separately in coverage mapping 2021-02-18 14:34:39 -08:00
DebuggingJITedCode.rst [docs] Update DebuggingJITedCode page after fix in LLDB 2021-01-14 15:43:11 +01:00
DeveloperPolicy.rst [DeveloperPolicy] Specify LLVM's license more clearly. 2021-02-12 09:16:43 +00:00
Docker.rst update of the llvm doc: we moved to git 2020-03-22 22:36:21 +01:00
doxygen-mainpage.dox
doxygen.cfg.in [docs] update mathjax path in doxygen 2020-02-07 16:26:35 +00:00
epilogue-vectorization-cfg.png [LV] Epilogue Vectorization with Optimal Control Flow (Recommit) 2020-12-02 10:09:56 -05:00
ExceptionHandling.rst [docs] Fix typos 2020-08-09 19:31:49 -07:00
ExtendedIntegerResults.txt
ExtendingLLVM.rst [docs] Update ExtendingLLVM.rst 2020-09-21 16:49:48 -07:00
Extensions.rst Introduce and use a new section type for the bb_addr_map section. 2020-10-08 11:13:19 -07:00
FAQ.rst Update references to 'master' branch. 2020-12-21 19:10:34 +00:00
FaultMaps.rst
FuzzingLLVM.rst [llvm] NFC: fix trivial typos in documents 2020-01-22 11:32:51 +08:00
GarbageCollection.rst [AsmPrinter] De-capitalize all AsmPrinter::Emit* but EmitInstruction 2020-02-13 17:06:24 -08:00
gcc-loops.png
GetElementPtr.rst [DOC] Fix load instructions' syntax, function definition. 2019-06-12 11:24:22 +00:00
GettingInvolved.rst llvmbuildectomy - replace llvm-build by plain cmake 2020-11-13 10:35:24 +01:00
GettingStarted.rst [Docs] Mention clone depth feature of git in LLVM getting started 2021-02-24 10:56:10 +05:30
GettingStartedTutorials.rst [Docs] Adds Documentation links to sidebar 2019-10-09 20:26:13 +00:00
GettingStartedVS.rst Remove Python2 fallback and only advertise Python3 in the doc 2020-12-17 15:40:16 +01:00
GitBisecting.rst Update references to 'master' branch. 2020-12-21 19:10:34 +00:00
GoldPlugin.rst
GwpAsan.rst [llvm] NFC: fix trivial typos in documents 2020-01-22 11:32:51 +08:00
HowToAddABuilder.rst Update filename to workers.py file in documentation 2021-01-22 00:20:26 -08:00
HowToBuildOnARM.rst Remove Python2 fallback and only advertise Python3 in the doc 2020-12-17 15:40:16 +01:00
HowToBuildWithPGO.rst docs: Add pointer to cmake caches for PGO 2020-12-07 15:55:26 -05:00
HowToCrossCompileBuiltinsOnArm.rst [arm builtin crosscompile docs] add COMPILER_RT_BUILD_MEMPROF=OFF 2021-02-25 10:44:52 -05:00
HowToCrossCompileLLVM.rst Doc: Links should use https 2020-03-22 22:49:33 +01:00
HowToReleaseLLVM.rst HowToReleaseLLVM: Update document to match the current release process 2020-12-21 15:16:11 -08:00
HowToSetUpLLVMStyleRTTI.rst [docs] Fix typos 2020-08-09 19:31:49 -07:00
HowToSubmitABug.rst [Docs] Update HowToSubmitABug 2021-02-02 21:19:20 -08:00
HowToUpdateDebugInfo.rst Reland "[Debugify] Make the debugify aware of the original (-g) Debug Info" 2021-02-18 23:29:22 -08:00
HowToUseAttributes.rst Remove references to the 4.0 release as a major breaking (NFC) 2020-06-25 23:49:07 +00:00
HowToUseInstrMappings.rst [llvm] NFC: Fix trivial typo in rst and td files 2020-04-23 14:26:32 +09:00
InAlloca.rst [docs] Fixing Sphinx warnings to unclog the buildbot 2016-07-20 12:16:38 +00:00
index.rst [docs] LLVM Security Group and Process 2020-07-10 15:24:02 -07:00
JITLink.rst [docs][JITLink] Fix a typo (NFC) 2021-03-02 15:07:36 +01:00
LangRef.rst Revert "[ObjC][ARC] Use operand bundle 'clang.arc.attachedcall' instead of explicitly emitting retainRV or claimRV calls in the IR" 2021-03-03 15:51:40 +01:00
Lexicon.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
LibFuzzer.rst Update references to 'master' branch. 2020-12-21 19:10:34 +00:00
LinkTimeOptimization.rst [LTO][Legacy] Add new API to query Mach-O CPU (sub)type 2020-02-28 12:56:05 -08:00
linpack-pc.png
llvm-objdump.1 [llvm-objdump] Implement --prefix option 2020-10-16 17:50:42 +01:00
loop-guard.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-irreducible.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-merge.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-nested.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-nonmaximal.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-separate.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-single.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-terminology-guarded-loop.png [LoopTerminology] Rotated Loops images 2020-03-17 01:02:19 +02:00
loop-terminology-initial-loop.png [LoopTerminology] Rotated Loops images 2020-03-17 01:02:19 +02:00
loop-terminology-rotated-loop.png [LoopTerminology] Rotated Loops images 2020-03-17 01:02:19 +02:00
loop-terminology.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
LoopTerminology.rst [LCSSA] Doc for special treatment of PHIs 2020-10-29 22:50:07 +02:00
make.bat
Makefile.sphinx Bring back Makefile.sphinx 2016-03-23 00:30:57 +00:00
MarkdownQuickstartTemplate.md Doc: Links should use https 2020-03-22 22:49:33 +01:00
MarkedUpDisassembly.rst [llvm] NFC: fix trivial typos in documents 2020-01-22 11:32:51 +08:00
MCJIT-creation.png
MCJIT-dyld-load.png
MCJIT-engine-builder.png
MCJIT-load-object.png
MCJIT-load.png
MCJIT-resolve-relocations.png
MCJITDesignAndImplementation.rst
MeetupGuidelines.rst Add guidelines/recommendations for organizers of LLVM Socials 2019-05-14 07:20:58 +00:00
MemorySSA.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
MemTagSanitizer.rst Fix MemTagSanitizer docs to point at Armv8.5-A MTE 2020-03-05 17:23:58 +00:00
MergeFunctions.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
MIRLangRef.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
NewPassManager.rst [docs] Add documentation on using the new pass manager 2021-02-26 15:28:19 -08:00
NVPTXUsage.rst
OptBisect.rst [LegacyPassManager] Delete BasicBlockPass/Manager. 2019-10-30 11:40:16 -07:00
ORCv2.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
Packaging.rst update of the llvm doc: we moved to git 2020-03-22 22:36:21 +01:00
Passes.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
Phabricator.rst [Doc] Update branch name in Phabricator documentation 2020-12-10 22:25:04 +03:00
ProgrammersManual.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
Projects.rst
re_format.7 Revert r103213. It broke several sections of live website. 2010-05-07 00:28:04 +00:00
README.txt Doc: Links should use https 2020-03-22 22:49:33 +01:00
Reference.rst [docs][JITLink] Add a JITLink design and API document. 2021-02-24 21:04:35 +11:00
ReleaseNotes.rst [llvm-objcopy] Delete --build-id-link-{dir,input,output} 2021-02-15 11:17:32 -08:00
ReleaseProcess.rst Doc: Links should use https 2020-03-22 22:49:33 +01:00
Remarks.rst [Remarks] Extend the RemarkStreamer to support other emitters 2020-02-04 17:16:02 -08:00
ReportingGuide.rst [llvm] NFC: fix trivial typos in documents 2020-01-22 11:32:51 +08:00
ScudoHardenedAllocator.rst [docs] Scudo: document error messages & their potential cause 2019-01-22 16:43:45 +00:00
Security.rst Adding new Azul representative to security group 2020-10-19 22:41:19 -07:00
SegmentedStacks.rst
SourceLevelDebugging.rst [DebugInfo][flang]Added support for representing Fortran assumed length strings 2020-08-22 10:13:40 +05:30
speculative_load_hardening_microbenchmarks.png
SpeculativeLoadHardening.md Fix a few spellos in docs. 2019-09-13 14:58:24 +00:00
SphinxQuickstartTemplate.rst Doc: Links should use https 2020-03-22 22:49:33 +01:00
StackMaps.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
StackSafetyAnalysis.rst Remove trailing empty line 2018-11-26 23:17:52 +00:00
Statepoints.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
SupportLibrary.rst
SupportPolicy.rst [docs] Adding a Support Policy 2020-11-07 21:06:05 +00:00
SystemLibrary.rst
TableGenFundamentals.rst
TestingGuide.rst [test] Use host platform specific error message substitution in lit tests - continued 2021-02-03 09:53:22 -05:00
TestSuiteGuide.md [docs] Fix typos 2020-08-09 19:31:49 -07:00
TestSuiteMakefileGuide.rst Adjust documentation for git migration. 2019-01-29 16:37:27 +00:00
TransformMetadata.rst Insert missing bracket in docs. 2020-09-08 15:20:39 -07:00
TypeMetadata.rst Update references to 'master' branch. 2020-12-21 19:10:34 +00:00
UserGuides.rst [docs] Add documentation on using the new pass manager 2021-02-26 15:28:19 -08:00
Vectorizers.rst [Branch-Rename] Fix some links 2021-02-01 16:43:21 +05:30
WritingAnLLVMBackend.rst Update spelling of {analyze,insert,remove}Branch in strings and comments 2020-01-21 10:15:38 -06:00
WritingAnLLVMNewPMPass.rst [docs] Add documentation on using the new pass manager 2021-02-26 15:28:19 -08:00
WritingAnLLVMPass.rst [docs] Add documentation on using the new pass manager 2021-02-26 15:28:19 -08:00
XRay.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
XRayExample.rst [XRay][docs] Fix option name 2019-03-12 13:44:42 +00:00
XRayFDRFormat.rst [llvm] NFC: fix trivial typos in documents 2020-01-22 11:32:51 +08:00
yaml2obj.rst
YamlIO.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00

LLVM Documentation
==================

LLVM's documentation is written in reStructuredText, a lightweight
plaintext markup language (file extension `.rst`). While the
reStructuredText documentation should be quite readable in source form, it
is mostly meant to be processed by the Sphinx documentation generation
system to create HTML pages which are hosted on <https://llvm.org/docs/> and
updated after every commit. Manpage output is also supported, see below.

If you instead would like to generate and view the HTML locally, install
Sphinx <http://sphinx-doc.org/> and then do:

    cd <build-dir>
    cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true <src-dir>
    make -j3 docs-llvm-html
    $BROWSER <build-dir>/docs//html/index.html

The mapping between reStructuredText files and generated documentation is
`docs/Foo.rst` <-> `<build-dir>/docs//html/Foo.html` <-> `https://llvm.org/docs/Foo.html`.

If you are interested in writing new documentation, you will want to read
`SphinxQuickstartTemplate.rst` which will get you writing documentation
very fast and includes examples of the most important reStructuredText
markup syntax.

Manpage Output
===============

Building the manpages is similar to building the HTML documentation. The
primary difference is to use the `man` makefile target, instead of the
default (which is `html`). Sphinx then produces the man pages in the
directory `<build-dir>/docs/man/`.

    cd <build-dir>
    cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true <src-dir>
    make -j3 docs-llvm-man
    man -l >build-dir>/docs/man/FileCheck.1

The correspondence between .rst files and man pages is
`docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs//man/Foo.1`.
These .rst files are also included during HTML generation so they are also
viewable online (as noted above) at e.g.
`https://llvm.org/docs/CommandGuide/Foo.html`.

Checking links
==============

The reachability of external links in the documentation can be checked by
running:

    cd docs/
    make -f Makefile.sphinx linkcheck

Doxygen page Output
==============

Install doxygen <http://www.stack.nl/~dimitri/doxygen/download.html> and dot2tex <https://dot2tex.readthedocs.io/en/latest>.

    cd <build-dir>
    cmake -DLLVM_ENABLE_DOXYGEN=On <llvm-top-src-dir>
    make doxygen-llvm # for LLVM docs
    make doxygen-clang # for clang docs

It will generate html in

    <build-dir>/docs/doxygen/html # for LLVM docs
    <build-dir>/tools/clang/docs/doxygen/html # for clang docs