1
0
mirror of https://github.com/RPCS3/llvm-mirror.git synced 2024-11-24 03:33:20 +01:00
llvm-mirror/docs
John McCall 3f8b48091d Extend coroutines to support a "returned continuation" lowering.
A quick contrast of this ABI with the currently-implemented ABI:

- Allocation is implicitly managed by the lowering passes, which is fine
  for frontends that are fine with assuming that allocation cannot fail.
  This assumption is necessary to implement dynamic allocas anyway.

- The lowering attempts to fit the coroutine frame into an opaque,
  statically-sized buffer before falling back on allocation; the same
  buffer must be provided to every resume point.  A buffer must be at
  least pointer-sized.

- The resume and destroy functions have been combined; the continuation
  function takes a parameter indicating whether it has succeeded.

- Conversely, every suspend point begins its own continuation function.

- The continuation function pointer is directly returned to the caller
  instead of being stored in the frame.  The continuation can therefore
  directly destroy the frame when exiting the coroutine instead of having
  to leave it in a defunct state.

- Other values can be returned directly to the caller instead of going
  through a promise allocation.  The frontend provides a "prototype"
  function declaration from which the type, calling convention, and
  attributes of the continuation functions are taken.

- On the caller side, the frontend can generate natural IR that directly
  uses the continuation functions as long as it prevents IPO with the
  coroutine until lowering has happened.  In combination with the point
  above, the frontend is almost totally in charge of the ABI of the
  coroutine.

- Unique-yield coroutines are given some special treatment.

llvm-svn: 368788
2019-08-14 03:53:17 +00:00
..
_ocamldoc
_static
_templates
_themes/llvm-theme
AMDGPU [AMDGPU][MC][GFX9][GFX10] Added support of GET_DOORBELL message 2019-07-15 15:12:16 +00:00
CommandGuide [Docs][llvm-strip] Fix an indentation issue. 2019-08-09 19:41:13 +00:00
Frontend
HistoricalNotes
PDB PDB docs: Delete trailing whitespace, wrap to 80 cols 2019-06-22 11:23:01 +00:00
Proposals docs/GithubMove.rst: Add link to GitHub migration status page 2019-07-12 02:31:50 +00:00
TableGen [docs] Fix TableGen/LangRef typos 2019-06-13 18:42:30 +00:00
tutorial Rename F_{None,Text,Append} to OF_{None,Text,Append}. NFC 2019-08-05 05:43:48 +00:00
AddingConstrainedIntrinsics.rst [FPEnv] A missing crucial step was undocumented. 2019-06-25 16:09:39 +00:00
AdvancedBuilds.rst Use backquotes to avoid a sphinx unexpected error: 2018-12-16 14:19:39 +00:00
AliasAnalysis.rst [doc] Removed obsolete -count-aa from AliasAnalysis documentation 2018-04-23 13:45:28 +00:00
AMDGPUInstructionNotation.rst [AMDGPU][MC][DOC] Updated AMD GPU assembler description. 2018-12-28 11:48:23 +00:00
AMDGPUInstructionSyntax.rst [AMDGPU][MC][DOC] Updated AMD GPU assembler syntax description. 2019-07-08 16:50:11 +00:00
AMDGPUModifierSyntax.rst [AMDGPU][MC][DOC] Updated AMD GPU assembler syntax description. 2019-07-08 16:50:11 +00:00
AMDGPUOperandSyntax.rst [AMDGPU][MC][DOC] Updated AMD GPU assembler syntax description. 2019-07-08 16:50:11 +00:00
AMDGPUUsage.rst [AMDGPU] gfx908 target 2019-07-09 18:10:06 +00:00
ARM-BE-bitcastfail.png
ARM-BE-bitcastsuccess.png
ARM-BE-ld1.png
ARM-BE-ldr.png
Atomics.rst [docs] Clarify where the indirect UB due to write-write races comes from 2019-07-23 21:51:26 +00:00
Benchmarking.rst
BigEndianNEON.rst
BitCodeFormat.rst ARM MTE stack sanitizer. 2019-07-15 20:02:23 +00:00
BlockFrequencyTerminology.rst
BranchWeightMetadata.rst [TI removal] Remove discussion of TerminatorInst from the LLVM 2018-10-18 07:40:24 +00:00
BugLifeCycle.rst Introduce bug life cycle documentation. 2018-11-07 08:49:36 +00:00
Bugpoint.rst Rename DEBUG macro to LLVM_DEBUG. 2018-05-14 12:53:11 +00:00
BugpointRedesign.md [Bugpoint redesign] Fix nonlocal URI link in doc 2019-08-09 21:48:47 +00:00
BuildingADistribution.rst [docs] Add new document on building distributions 2019-05-21 16:29:31 +00:00
CFIVerify.rst [cfi-verify] Abort on unsupported targets 2018-07-16 15:26:44 +00:00
CMake.rst Fix spacing of LLVM_USE_PERF in CMake.rst that caused it to be tabbed in funny 2019-08-01 17:30:25 +00:00
CMakeLists.txt [dsymutil][doc] Improve wording in manpage and rename file. 2017-11-02 18:44:54 +00:00
CMakePrimer.rst
CodeGenerator.rst CodeGen: Allow virtual registers in bundles 2019-08-01 18:41:28 +00:00
CodeOfConduct.rst
CodingStandards.rst Update the coding standards with the new file header. 2019-01-19 11:53:58 +00:00
CommandLine.rst [NFC] fix trivial typos in documents 2019-06-25 07:24:27 +00:00
CompileCudaWithLLVM.rst Adjust documentation for git migration. 2019-01-29 16:37:27 +00:00
CompilerWriterInfo.rst [Docs] Modernize references to macOS 2019-05-30 16:46:22 +00:00
conf.py Bump the trunk version to 10.0.0svn 2019-07-18 11:51:05 +00:00
Contributing.rst [Docs] Add LLVM for Grad Students to Contributing page. 2018-03-02 14:35:02 +00:00
Coroutines.rst Extend coroutines to support a "returned continuation" lowering. 2019-08-14 03:53:17 +00:00
CoverageMappingFormat.rst [Coverage] Use gap regions to select better line exec counts 2017-09-18 23:37:28 +00:00
DebuggingJITedCode.rst [Docs] Modernize references to macOS 2019-05-30 16:46:22 +00:00
DeveloperPolicy.rst DeveloperPolicy: fix a typo 2019-07-15 08:09:21 +00:00
Docker.rst [build] Rename clang-headers to clang-resource-headers 2019-03-04 21:19:53 +00:00
doxygen-mainpage.dox
doxygen.cfg.in [NFC] Remove LLVM_ALIGNAS 2019-07-31 03:22:08 +00:00
ExceptionHandling.rst [NFC] fix trivial typos in documents and comments 2018-04-12 05:53:20 +00:00
ExtendedIntegerResults.txt
ExtendingLLVM.rst Note ImmArg in documentation for adding intrinsics 2019-03-14 13:46:17 +00:00
Extensions.rst Add IR support, ELF section and user documentation for partitioning feature. 2019-05-29 03:29:01 +00:00
FAQ.rst Remove some autoconf references from docs and comments 2019-07-03 09:57:59 +00:00
FaultMaps.rst
FuzzingLLVM.rst [docs] Try to clarify the FuzzingLLVM docs 2018-08-16 21:55:09 +00:00
GarbageCollection.rst [GC docs] Update the gcroot documentation to reflect recent simplifcations to GCStrategy configurability 2018-11-12 20:30:50 +00:00
gcc-loops.png
GetElementPtr.rst [DOC] Fix load instructions' syntax, function definition. 2019-06-12 11:24:22 +00:00
GettingStarted.rst [docs] Add cmake to Software requirements 2019-07-31 08:48:36 +00:00
GettingStartedVS.rst Retire VS2015 Support 2019-07-09 10:10:48 +00:00
GlobalISel.rst [globalisel][legalizer] Attempt to write down the minimal legalization rules 2019-08-08 17:54:23 +00:00
GoldPlugin.rst [docs][gold] Fix a typo 2018-08-21 21:00:54 +00:00
HowToAddABuilder.rst
HowToBuildOnARM.rst
HowToBuildWithPGO.rst HowToBuildWithPGO.rst: Fix a few details in the manual steps 2018-12-05 08:35:30 +00:00
HowToCrossCompileBuiltinsOnArm.rst [docs] Improve HowToCrossCompilerBuiltinsOnArm 2018-12-18 12:40:19 +00:00
HowToCrossCompileLLVM.rst
HowToReleaseLLVM.rst Remove some autoconf references from docs and comments 2019-07-03 09:57:59 +00:00
HowToSetUpLLVMStyleRTTI.rst
HowToSubmitABug.rst [docs] Prevent O0 optnone for opt input 2019-01-29 22:17:51 +00:00
HowToUseAttributes.rst
HowToUseInstrMappings.rst
InAlloca.rst
index.rst [ORC] Start adding ORCv1 to ORCv2 transition tips to the ORCv2 doc. 2019-07-15 15:36:37 +00:00
LangRef.rst Add llvm.licm.disable metadata 2019-08-08 13:46:17 +00:00
Lexicon.rst Update the coding standards and developer policy documentation surrounding whitespace. 2018-08-10 17:26:07 +00:00
LibFuzzer.rst [libFuzzer] document -len_control 2019-03-18 22:20:47 +00:00
LinkTimeOptimization.rst
linpack-pc.png
llvm-objdump.1 Update the file headers across all of the LLVM projects in the monorepo 2019-01-19 08:50:56 +00:00
LLVMBuild.rst
LLVMBuild.txt Update the file headers across all of the LLVM projects in the monorepo 2019-01-19 08:50:56 +00:00
LoopTerminology.rst Attempt to unbreak sphinx build bot by inserting a link. 2019-07-31 22:14:26 +00:00
make.bat
Makefile.sphinx
MarkdownQuickstartTemplate.md [docs] Reinstate r337730 - Add support for Markdown documentation in 2018-08-06 00:38:31 +00:00
MarkedUpDisassembly.rst
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 [NFC] fix trivial typos in comments and documents 2018-01-26 08:15:29 +00:00
MergeFunctions.rst Updating MergeFunctions.rst 2018-08-18 20:17:19 +00:00
MIRLangRef.rst [MachineFunction] Base support for call site info tracking 2019-06-27 07:48:06 +00:00
NVPTXUsage.rst [CodeGen] Unify MBB reference format in both MIR and debug output 2017-12-04 17:18:51 +00:00
OptBisect.rst [Docs] Remove hard tab character from code block in optbisect documentation 2018-07-27 06:54:13 +00:00
ORCv2.rst [ORC] Change the locking scheme for ThreadSafeModule. 2019-08-02 15:21:37 +00:00
Packaging.rst
Passes.rst [Unroll/UnrollAndJam/Vectorizer/Distribute] Add followup loop attributes. 2018-12-12 17:32:52 +00:00
Phabricator.rst Update GettingStarted guide to recommend that people use the new 2019-01-14 22:27:32 +00:00
ProgrammersManual.rst Fix typo in programmer's manual cantFile -> cantFail 2019-07-18 05:24:22 +00:00
Projects.rst
re_format.7
README.txt [NFC] Test commit, whitespace change 2019-06-06 22:07:14 +00:00
ReleaseNotes.rst Revert r367941 "Add a note to the release not about a potentially breaking optimization" 2019-08-06 08:32:33 +00:00
ReleaseProcess.rst [docs] Make ReleaseProcess.rst 80 column. NFCI 2018-01-18 14:57:55 +00:00
Remarks.rst Reland: [Remarks] Add an LLVM-bitstream-based remark serializer 2019-07-31 00:13:51 +00:00
ReportingGuide.rst
ScudoHardenedAllocator.rst [docs] Scudo: document error messages & their potential cause 2019-01-22 16:43:45 +00:00
SegmentedStacks.rst
SourceLevelDebugging.rst [DebugInfo][Docs] Document that prologue/epilogue variable location changes are ignored 2019-06-18 08:52:38 +00:00
speculative_load_hardening_microbenchmarks.png [x86/SLH] Add the design document for Speculative Load Hardening, 2018-07-18 14:05:14 +00:00
SpeculativeLoadHardening.md [docs] Fix a couple spelling errors. 2019-01-28 23:03:41 +00:00
SphinxQuickstartTemplate.rst
StackMaps.rst [docs] Clarify ELF section naming for StackMaps and fix a typo 2018-11-08 17:20:35 +00:00
StackSafetyAnalysis.rst Remove trailing empty line 2018-11-26 23:17:52 +00:00
Statepoints.rst [docs][statepoints] Reformulate open issues list 2018-11-09 17:09:16 +00:00
SupportLibrary.rst [Docs] [Support] Correct a missed reference and use up to date .inc examples. 2018-09-21 01:53:51 +00:00
SystemLibrary.rst [Docs] [Support] System Library to Support Library transition along with minor corrections to reflect it. 2018-09-18 18:05:38 +00:00
TableGenFundamentals.rst
TestingGuide.rst [Docs] Modernize references to macOS 2019-05-30 16:46:22 +00:00
TestSuiteGuide.md Adjust documentation for git migration. 2019-01-29 16:37:27 +00:00
TestSuiteMakefileGuide.rst Adjust documentation for git migration. 2019-01-29 16:37:27 +00:00
TransformMetadata.rst [Unroll/UnrollAndJam/Vectorizer/Distribute] Add followup loop attributes. 2018-12-12 17:32:52 +00:00
TypeMetadata.rst Update GettingStarted guide to recommend that people use the new 2019-01-14 22:27:32 +00:00
Vectorizers.rst Update GettingStarted guide to recommend that people use the new 2019-01-14 22:27:32 +00:00
WritingAnLLVMBackend.rst [Docs] Fix typo in scheduler model documentation. enumemation->enumeration 2017-12-10 09:14:35 +00:00
WritingAnLLVMPass.rst Attempt to unbreak sphinx build bot by inserting a link. 2019-07-31 22:14:26 +00:00
XRay.rst [Docs] Update of Xray page 2018-07-26 04:44:31 +00:00
XRayExample.rst [XRay][docs] Fix option name 2019-03-12 13:44:42 +00:00
XRayFDRFormat.rst Tidy some language in the xray documentation. 2018-05-27 09:19:03 +00:00
yaml2obj.rst
YamlIO.rst [Docs] Fix LLVM_YAML_IS_DOCUMENT_LIST_VECTOR 2018-07-23 14:17:43 +00: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 <http://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` <-> `http://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.
`http://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